vps-brain-client 0.1.0

A Python client for the VPS Brain API.

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

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.

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`
task	`str	None`

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:

git clone 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.