Octpo Python SDK

octpo is the Python client for Octpo's hosted API at https://platform-octpo.vercel.app/v1. It uses HTTPX and supports synchronous and asynchronous calls.

Installation

python -m pip install octpo

For a local checkout:

cd octpo_python_lib
python -m venv .venv
. .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install -e '.[test]'

Quick start

Set OCTPO_API_KEY to the caller bearer token configured for your Octpo deployment:

export OCTPO_API_KEY="your-token"

import octpo

client = octpo.Client(
    default_headers={"X-Client-Name": "Octpo", "X-Client-Version": "1.0.0"},
)
response = client.responses.create(model="octpo-auto", input="Hello! Introduce yourself briefly.")
print(response.output_text)
client.close()

The equivalent async call is:

import asyncio
import octpo

async def main():
    async with octpo.AsyncClient() as client:
        response = await client.responses.create(model="octpo-auto", input="Hello!")
        print(response.output_text)

asyncio.run(main())

Configuration

Both clients accept api_key, base_url, default_headers, timeout (seconds or httpx.Timeout), max_retries (default 2), and an optional HTTPX client as http_client. If api_key is omitted, the client reads OCTPO_API_KEY. Authorization is always set to the supplied API key; custom headers cannot replace Authorization, Accept, or Content-Type. Requests use Authorization: Bearer ….

Retries are limited to idempotent model discovery (GET /models) for transport failures, timeouts, 429, and selected transient 5xx responses. Retry-After is honored up to 30 seconds. Response creation is never automatically retried because it is a non-idempotent POST.

Supported API

The SDK matches the Vercel gateway implementation:

• POST /responses: text-only input, model, instructions, max_output_tokens, temperature, top_p, and metadata. Returns a typed Response with output_text.
• GET /models: lists public model IDs configured for the deployment. IDs can vary by deployment; source defaults are octpo-auto and octpo-code.
• POST /chat/completions is implemented by the gateway, but is not exposed in this first SDK release; use the Responses API for supported text generation.

The Responses gateway does not support image/audio inputs, tool calling, or streaming. It rejects unsupported request fields instead of silently ignoring them. Streaming is not implemented in this SDK. The gateway has no documented OpenAPI schema or additional endpoints in its route configuration; /health, action, and computer-use routes are not part of this hosted gateway.

Errors

All SDK exceptions derive from OctpoError. HTTP errors derive from APIError and expose status_code, response, and body. Common status codes map to AuthenticationError, InvalidRequestError, RateLimitError, and ServerError. Connection failures raise NetworkError; timeouts raise APITimeoutError; incompatible successful payloads raise ResponseFormatError. API error messages are retained.

Troubleshooting

• 503 API is not configured: the deployment has not configured its caller token.
• 401 invalid/missing API token: verify OCTPO_API_KEY matches the deployment's OCTPO_API_TOKEN. Never include it in source control or logs.
• 400 unsupported fields: this gateway accepts only the fields listed above and text message input. Remove unsupported options.
• 502/504 upstream errors: the hosted gateway could not obtain a valid response from the configured Octpo model server; check the deployment's upstream configuration.

Local checks

python -m pytest
python -m ruff check src tests
python -m mypy src
python -m build

Integration tests run only when OCTPO_API_KEY is explicitly set. They do not print the key.