Relevant source files

The following files were used as context for generating this wiki page: - [sdks/python/README.md](https://github.com/ales27pm/monGARS/blob/main/sdks/python/README.md) - [sdks/python/pyproject.toml](https://github.com/ales27pm/monGARS/blob/main/sdks/python/pyproject.toml) - [scripts/sdk_release.py](https://github.com/ales27pm/monGARS/blob/main/scripts/sdk_release.py) - [README.md](https://github.com/ales27pm/monGARS/blob/main/README.md) - [monGARS/api/AGENTS.md](https://github.com/ales27pm/monGARS/blob/main/monGARS/api/AGENTS.md)

# Python SDK 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:** ```bash 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 with `asyncio` for 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. ```mermaid classDiagram direction LR class MonGARSSyncClient { +login(username, password) Token +chat(ChatRequest) ChatResponse ... } class MonGARSAsyncClient { +login(username, password) await~Token~ +chat(ChatRequest) await~ChatResponse~ ... } class httpx_Client { <> } class httpx_AsyncClient { <> } class PydanticModels { <> ChatRequest ChatResponse Token } MonGARSSyncClient ..> httpx_Client : uses MonGARSAsyncClient ..> httpx_AsyncClient : uses MonGARSSyncClient ..> PydanticModels : uses MonGARSAsyncClient ..> PydanticModels : uses ``` Sources: [sdks/python/README.md:4-7](), [sdks/python/README.md:25-41]() ## 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:** ```python 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:** ```python 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. ```mermaid sequenceDiagram participant User as "User Application" participant SDK as "MonGARSAsyncClient" participant API as "monGARS FastAPI" User->>SDK: create MonGARSAsyncClient User->>SDK: login("alice", "password") SDK->>API: POST /token (credentials) API-->>SDK: JWT Token SDK-->>User: (stores token internally) User->>SDK: chat(ChatRequest) SDK->>API: POST /api/v1/conversation/chat (with auth header) API-->>SDK: ChatResponse SDK-->>User: result (ChatResponse) ``` Sources: [sdks/python/README.md:34-44](), [sdks/python/README.md:58-64]() ## 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. ```mermaid flowchart TD A[Start] --> B{Run `python -m scripts.sdk_release`}; B --> C[build_python_sdk() is called]; C --> D{Check for 'build' package}; D --> E[Create output directory]; E --> F[Execute `python -m build --wheel --sdist`]; F --> G[sdist and wheel artefacts created]; G --> H[End]; ``` 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:** ```bash pytest -q tests/test_python_sdk.py ``` Sources: [sdks/python/README.md:70-74]()