agent-optimus 0.1.0

Python SDK for the Optimus API — MSC construction, routing, and answers

agent-optimus

Python SDK for the Optimus backend API. Install with pip and call MSC construction, model routing, and full answer generation from Python.

Installation

pip install agent-optimus

Quick start

You can use Optimus with the exact same call pattern as OpenRouter/OpenAI. Only the import and API key differ.

Option 1 — built-in client (recommended, no extra install)

from agent_optimus import OpenAI

client = OpenAI(api_key="your-optimus-api-token")

response = client.chat.completions.create(
    model="qwen/qwen3-32b",
    messages=[
        {"role": "user", "content": "Hello"}
    ],
)

print(response.choices[0].message.content)

base_url defaults to production. Override only for local development:

client = OpenAI(
    api_key="your-optimus-api-token",
    base_url="http://127.0.0.1:8000",
)

Option 2 — official openai package

If you need the real OpenAI SDK types/objects:

pip install agent-optimus[openai]

from openai import OpenAI
from agent_optimus import create_openai_client

client = create_openai_client(api_key="your-optimus-api-token")

response = client.chat.completions.create(
    model="qwen/qwen3-32b",
    messages=[
        {"role": "user", "content": "Hello"}
    ],
)

print(response.choices[0].message.content)

Note: from openai import OpenAI alone cannot talk to Optimus directly, because Optimus uses /finish instead of OpenAI's /v1/chat/completions. create_openai_client() wires that up for you.

Optimus-specific fields (routing_score, cost_usd, metrics) are available on response.optimus (built-in client) or inside the raw response payload (official client).

Native SDK usage

from agent_optimus import AgentOptimus

client = AgentOptimus(api_token="your-api-key")

# 1. Build an MSC from long context
msc = client.construct_msc(
    context="Italy dominates European silk production...",
    user_query="Who leads silk production in Europe?",
)
print(msc["msc_string"], msc["compression_ratio"])

# 2. Route only (no full MSC + answer pipeline)
routed = client.route(
    context="The Eiffel Tower is in Paris.",
    query="Where is the Eiffel Tower?",
)
print(routed["content"], routed["model_provider_detail"])

# 3. Full pipeline answer (MSC + route + generate)
answer = client.answer(
    context="The Eiffel Tower is in Paris.",
    query="Where is the Eiffel Tower?",
)
print(answer["content"], answer["metrics"])

You can also pass api_token per call instead of on the client:

client = AgentOptimus(base_url="http://127.0.0.1:8000")
result = client.route(api_token="your-api-key", context="...", query="...")

Configuration

Setting	Default	Override
Base URL	https://api-optimus-backend-service.up.railway.app	AGENT_OPTIMUS_BASE_URL env var or base_url=
OpenAI client	OpenAI(api_key=...)	api_key=
Native client	AgentOptimus(api_token=...)	api_token= on client or each method
Auth header	x-api-token	fixed

API mapping

SDK method	HTTP	Path
OpenAI.chat.completions.create()	POST	/finish
construct_msc()	POST	/generate-msc
route()	POST	/route
answer()	POST	/finish

Extra keyword arguments on each method are forwarded in the JSON request body.

PyPI auto-publish (GitHub Actions)

Merges to main that touch package files trigger .github/workflows/publish-pypi.yml, which builds and uploads to PyPI.

One-time setup

1. Create a PyPI API token at pypi.org/manage/account/token/ (scope: entire account for the first release).
2. In your GitHub repo go to Settings → Environments → New environment and create pypi.
3. (Optional) Under pypi, enable Required reviewers and add yourself so publishes need approval.
4. In the pypi environment, add secret PYPI_API_TOKEN with your full pypi-... token.

Versioning

Bump version in pyproject.toml before merging a release to main. The workflow uses --skip-existing, so pushes without a version bump are no-ops instead of failures.

Development

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python3 -m build

Publish to PyPI

python3 -m pip install --upgrade twine
python3 -m twine upload dist/*

When prompted for credentials:

• Username: __token__
• Password: your PyPI API token (including the pypi- prefix)