agent-optimus

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-api-token")

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

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

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-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 internal end point 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"])