Metadata-Version: 2.4
Name: vps-brain-client
Version: 0.1.0
Summary: A Python client for the VPS Brain API.
Author-email: Gemini CLI <gemini@google.com>
License: MIT License
        
        Copyright (c) 2025 Gemini CLI
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.14.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# VPS Brain Python Client

A Python client for interacting with the VPS Brain API. This SDK provides a convenient way to integrate with the VPS Brain service, allowing you to offload computationally intensive Large Language Model (LLM) processing.

## Features

*   Asynchronous API calls using `httpx`.
*   Type-safe request and response models using `pydantic`.
*   Clear error handling for API and network issues.
*   Support for `process_text`, `healthz`, and `readyz` endpoints.

## Installation

```bash
pip install vps-brain-client
```

## Usage

The client is asynchronous and should be used with `await` in an `async` function. You will need a `base_url` for the VPS Brain API and an `api_key` for authentication.

```python
import os
import asyncio
from vps_brain_client import VpsBrainClient, ProcessTextRequest, VpsBrainClientError

async def main():
    # Initialize the client
    # Replace with your actual VPS Brain API URL
    client = VpsBrainClient(
        base_url="https://your-vps-brain-api-url.com",
        api_key=os.getenv("VPS_BRAIN_API_KEY") # Ensure VPS_BRAIN_API_KEY is set in your environment
    )

    try:
        # Example: Process text
        request_payload = ProcessTextRequest(
            text="Summarize the following article: The quick brown fox jumps over the lazy dog.",
            task="summarize"
        )
        response = await client.process_text(request_payload)
        print(f"LLM Response: {response.llm_response}")
        print(f"Request ID: {response.meta.request_id}")

        # Example: Check health
        health_status = await client.get_healthz()
        print(f"Health Status: {health_status}")

        # Example: Check readiness
        readiness_status = await client.get_readyz()
        print(f"Readiness Status: {readiness_status}")

    except VpsBrainClientError as e:
        print(f"An API error occurred: {e.status_code} - {e.message}")
        if e.response_data:
            print(f"Response data: {e.response_data}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")
    finally:
        await client.close() # Ensure the client session is closed

if __name__ == "__main__":
    asyncio.run(main())
```

## API Models

### `ProcessTextRequest`

Represents the request payload for the `/process_text` endpoint.

| Field   | Type        | Description                                                              |
| :------ | :---------- | :----------------------------------------------------------------------- |
| `text`  | `str`       | The input text to be processed by the LLM. (Required, min_length=1)      |
| `model` | `str | None` | Optional model override; defaults to configured model when omitted.      |
| `task`  | `str | None` | Optional task profile (e.g., `sentiment`, `summarize`, `intent`).        |

### `ProcessTextResponse`

Represents the response payload from the `/process_text` endpoint.

| Field           | Type             | Description                                                      |
| :-------------- | :--------------- | :--------------------------------------------------------------- |
| `status`        | `str`            | The status of the processing (e.g., `success`).                  |
| `model`         | `str`            | The model that processed the request.                            |
| `task`          | `str`            | The task that was performed.                                     |
| `input_text`    | `str`            | The original input text.                                         |
| `rendered_prompt` | `str`            | The prompt sent to the LLM after any templating.                 |
| `llm_response`  | `str`            | The response generated by the LLM.                               |
| `meta`          | `ResponseMetadata` | Metadata about the request and inference.                        |

### `ResponseMetadata`

Contains metadata about the API request and LLM inference.

| Field                 | Type    | Description                                                      |
| :-------------------- | :------ | :--------------------------------------------------------------- |
| `request_id`          | `str`   | Unique identifier for the request.                               |
| `received_at`         | `str`   | Timestamp when the request was received (ISO 8601 format).       |
| `request_duration_ms` | `float` | Total duration of the request in milliseconds.                   |
| `inference_duration_ms` | `float` | Duration of the LLM inference in milliseconds.                   |
| `prompt_chars`        | `int`   | Number of characters in the rendered prompt.                     |
| `response_chars`      | `int`   | Number of characters in the LLM response.                        |

## Error Handling

The `VpsBrainClient` raises `VpsBrainClientError` for any issues during API communication, including HTTP errors (e.g., 4xx, 5xx) and network problems. The `VpsBrainClientError` object contains `status_code` and `response_data` attributes for detailed error information.

## Development

To set up the development environment:

1.  **Clone the repository:**
    ```bash
git clone <repository-url>
cd vps-brain-client-python
    ```
2.  **Create and activate a virtual environment:**
    ```bash
python3 -m venv .venv
source .venv/bin/activate
    ```
3.  **Install dependencies (including development dependencies):**
    ```bash
pip install -e .[dev]
    ```
4.  **Run tests:**
    ```bash
pytest
    ```
5.  **Run linting and formatting:**
    ```bash
ruff check .
ruff format .
    ```

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.
