Python SDK
Relevant source files
The following files were used as context for generating this wiki page:
The monGARS Python SDK is the official helper library for interacting with the monGARS FastAPI service. It provides a convenient, typed interface for both synchronous and asynchronous communication, built upon httpx and pydantic. The SDK is a key component of the project's "Web/API Refinement" phase, enabling developers to build applications and scripts that leverage the monGARS platform.
Sources: sdks/python/README.md:3-7, monGARS/api/AGENTS.md:16
Installation and Dependencies
The SDK can be installed from a configured Python package index using pip. It requires Python 3.11+ and has a minimal set of dependencies. The package also includes py.typed for static type checker support.
Sources: sdks/python/README.md:9-14, sdks/python/pyproject.toml:10
Installation Command:
pip install monGARS-sdk
Sources: sdks/python/README.md:12
Package Dependencies:
| Package | Version | Description |
|---|---|---|
httpx | >=0.28.1 | A next-generation HTTP client for Python. |
pydantic | >=2.11.0 | Data validation and settings management. |
Sources: sdks/python/pyproject.toml:12-14
Architecture and Clients
The SDK is designed around two primary client classes, providing flexibility for different programming models. Both clients wrap the monGARS REST API, handle authentication, and return typed Pydantic models.
MonGARSSyncClient: A synchronous client for traditional, blocking I/O applications.MonGARSAsyncClient: An asynchronous client suitable for use withasynciofor high-performance, non-blocking applications.
Errors are handled by raising a custom APIError or a more specific AuthenticationError when the API returns a non-success status code.
Sources: sdks/python/README.md:4-7, sdks/python/README.md:65-67
The diagram below shows the conceptual structure of the SDK clients.
Usage
Quick Start
The SDK is straightforward to use. After instantiating a client, you first authenticate to get a token, which is then automatically used for subsequent API calls.
Synchronous Example:
from monGARS_sdk import ChatRequest, MonGARSSyncClient
client = MonGARSSyncClient("https://api.mongars.local")
token = client.login("alice", "secret-password")
response = client.chat(ChatRequest(message="Hello there!"))
print(response.response)
Sources: sdks/python/README.md:25-32
Asynchronous Example:
import asyncio
from monGARS_sdk import ChatRequest, MonGARSAsyncClient
async def main():
async with MonGARSAsyncClient("https://api.mongars.local") as client:
await client.login("alice", "secret-password")
result = await client.chat(ChatRequest(message="Hi!"))
print(result.response)
asyncio.run(main())
Sources: sdks/python/README.md:34-44
Interaction Flow
The following sequence diagram illustrates a typical asynchronous chat interaction.
API Coverage
The SDK provides helper methods that wrap the primary endpoints of the monGARS API.
| Category | Endpoints Covered - |
|---|---|
| Authentication | /token, /api/v1/user/register - |
| Conversation | /api/v1/conversation/chat, /api/v1/conversation/history - |
- Review & RAG |
/api/v1/review/rag-context- | - UI assistance |
/api/v1/ui/suggestions- | - Peer coordination |
/api/v1/peer/*- |
| Model management |/api/v1/models,/api/v1/models/provision- |
Sources: sdks/python/README.md:56-64
Building and Releasing
The SDK is packaged into sdist and wheel distributions using a dedicated release script. This process is part of the documented release workflow for the project.
Sources: sdks/python/README.md:16-22
The build process can be initiated by running the sdk_release.py script.
This diagram shows the high-level flow for building the Python SDK artefacts.
Sources: scripts/sdk_release.py:38-60
The command generates the distributable files in the specified output directory (e.g., dist/sdk/python/). These can then be uploaded to a package index using a tool like twine.
Sources: sdks/python/README.md:18-22
Development
Development on the SDK follows the root project's formatting rules, using black and isort. Tests for the SDK can be run from the repository root.
Test command:
pytest -q tests/test_python_sdk.py
Sources: sdks/python/README.md:70-74