> ## Documentation Index
> Fetch the complete documentation index at: https://www.stratus.run/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Use the OpenAI SDK you already have. One line change.

You don't need a new SDK. Add one line to what you already have.

<CodeGroup>
  ```python Standard theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["OPENAI_API_KEY"]
  )
  ```

  ```python With Stratus theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["STRATUS_API_KEY"],
      base_url="https://api.stratus.run/v1"
  )
  ```
</CodeGroup>

That's it. Works with GPT-4o, Claude, Gemini, DeepSeek, Llama, Grok, Mistral, Qwen, and 2,050+ model combinations via OpenRouter.

<Note>
  The `base_url` is required — Stratus does not auto-detect it. Set `STRATUS_API_KEY` to your Stratus key (`stratus_sk_live_...`). No LLM provider key needed to get started — Formation's pool handles requests automatically. See [Authentication](/docs/authentication) for details and BYOK options.
</Note>

## Installation

```bash theme={null}
pip install openai
```

You already have this. Nothing new to install.

***

## Making Calls

### Chat Completions

```python theme={null}
response = client.chat.completions.create(
    model="stratus-x1ac-base-gpt-4o",
    messages=[
        {"role": "system", "content": "Current state: checkout page, 3 items in cart"},
        {"role": "user",   "content": "Proceed to checkout"}
    ]
)

print(response.choices[0].message.content)
# → "Click the Proceed to Checkout button"

# Stratus-specific planning metadata
print(response.stratus.action_sequence)  # ['click', 'wait', 'verify']
print(response.stratus.overall_confidence)       # 0.94
```

### Messages (Anthropic-style)

Works with Anthropic's client too:

```python theme={null}
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["STRATUS_API_KEY"],
    base_url="https://api.stratus.run"
)

message = client.messages.create(
    model="stratus-x1ac-base-claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Plan the next steps."}]
)
```

### Streaming

```python theme={null}
with client.chat.completions.stream(
    model="stratus-x1ac-base-gpt-4o",
    messages=[{"role": "user", "content": "Plan the deployment steps."}]
) as stream:
    for chunk in stream:
        content = chunk.choices[0].delta.content or ""
        print(content, end="")
```

***

## Models

<CardGroup cols={2}>
  <Card title="stratus-x1ac-small-gpt-4o-mini" icon="gauge" color="#34d399">
    Lowest cost. Simple classification, routing, and action selection.
  </Card>

  <Card title="stratus-x1ac-base-gpt-4o" icon="bolt" color="#22d3ee">
    Balanced. Most use cases — web navigation, form completion, task planning.
  </Card>

  <Card title="stratus-x1ac-large-gpt-4o" icon="brain" color="#c084fc">
    Complex reasoning. Multi-step workflows, cascade prediction, concurrent coordination.
  </Card>

  <Card title="stratus-x1ac-base-claude-sonnet-4-5" icon="sparkles" color="#fbbf24">
    Claude backbone. Best for long-context planning and nuanced state reasoning.
  </Card>
</CardGroup>

See [Models](/docs/api-reference/models) for the full list and credit costs per model.

***

## The `stratus` Response Field

Every response includes planning metadata from the X1 world model:

```python theme={null}
response = client.chat.completions.create(...)

response.stratus.action_sequence   # list[str] — predicted action chain
response.stratus.overall_confidence        # float    — 0–1 prediction confidence
response.stratus.planning_time_ms  # int      — world model inference time
```

Use `confidence` as a gate before executing:

```python theme={null}
result = client.chat.completions.create(...)

if result.stratus.overall_confidence < 0.8:
    # Re-describe state with more detail before proceeding
    print("Low confidence — refine state description")
```

***

## Optional: `stratus-sdk-py`

For vector compression and trajectory simulation, install the Stratus Python SDK:

```bash theme={null}
pip install stratus-sdk-py
```

### Rollout (Pre-Execution Simulation)

Simulate a full action plan before anything executes:

```python theme={null}
from stratus_sdk import StratusClient

stratus = StratusClient(api_key=os.environ["STRATUS_API_KEY"])

plan = stratus.rollout(
    goal="Complete the checkout flow",
    initial_state="Cart page, 3 items, coupon field visible",
    max_steps=8
)

if plan.summary.outcome == "success":
    for pred in plan.predictions:
        print(f"Step {pred.step}: {pred.action.action_name}")
```

Or call the endpoint directly — no extra package needed:

```python theme={null}
import requests

plan = requests.post(
    "https://api.stratus.run/v1/rollout",
    headers={
        "Authorization": f"Bearer {os.environ['STRATUS_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "goal": "Complete the checkout flow",
        "initial_state": "Cart page, 3 items, coupon field visible",
        "max_steps": 8
    }
).json()
```

### Vector Compression

Compress embedding vectors 10–20× with 99%+ quality:

```python theme={null}
from stratus_sdk import compress, decompress, compress_batch, analyze_quality

# Single vector: 6144 bytes → ~600 bytes
compressed = compress(embedding)
restored = decompress(compressed)

# Batch
compressed = compress_batch(embeddings)

# Verify quality before deploying
report = analyze_quality(embeddings, decompress_batch(compressed))
print(report.summary)  # "GOOD (97.2%). Cosine: 99.23%, Recall@10: 95.8%"
```

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" color="#22d3ee" href="/docs/authentication">
    Set up your Stratus key. Optionally add provider keys to remove the Formation pool markup.
  </Card>

  <Card title="Tutorials" icon="graduation-cap" color="#c084fc" href="/docs/tutorials/web-navigation">
    Real-world agents — navigation, cascades, concurrency.
  </Card>

  <Card title="API Reference" icon="code" color="#34d399" href="/docs/api-reference/introduction">
    Full endpoint docs, parameters, and error codes.
  </Card>
</CardGroup>