agent-optimus 0.1.1

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