Metadata-Version: 2.4
Name: agent-optimus
Version: 0.1.0
Summary: Python SDK for the Optimus API — MSC construction, routing, and answers
Author-email: Your Name <your.email@example.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Dynamic: license-file

# 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

```bash
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)

```python
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:

```python
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:

```bash
pip install agent-optimus[openai]
```

```python
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

```python
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:

```python
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/](https://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

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

## Publish to PyPI

```bash
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)
