> ## 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.

# Quickstart

> From zero to your first Stratus response in under 60 seconds

<Info>
  Stratus is in private beta. [Apply for
  access](https://stratus.run/?beta=true).
</Info>

## Prerequisites

* A Stratus X1 API key — get one at [stratus.run/dashboard](https://stratus.run/dashboard)

<Info>
  **No LLM provider key required.** Formation provides a shared OpenRouter pool that activates automatically when no provider key is configured. You can make your first request immediately after signing up. Add your own provider key later to [remove the 25% pool markup](/docs/authentication#key-resolution-priority).
</Info>

## Install

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @formthefog/stratus-sdk-ts
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @formthefog/stratus-sdk-ts
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @formthefog/stratus-sdk-ts
    ```
  </Tab>

  <Tab title="pip">
    ```bash theme={null}
    pip install openai
    ```
  </Tab>
</Tabs>

## Make Your First Call

<Tabs>
  <Tab title="Stratus SDK">
    <Info>
      The native SDK exposes `response.stratus` — action sequences, confidence scores, and world-model metadata not available through third-party SDKs.
    </Info>

    <CodeGroup>
      ```typescript TypeScript theme={null}
      import { StratusClient } from "@formthefog/stratus-sdk-ts";

      const client = new StratusClient({
        apiKey: process.env.STRATUS_API_KEY!,
      });

      const response = await client.chat.completions.create({
        model: "stratus-x1ac-small-gpt-4o",
        messages: [
          {
            role: "system",
            content: "Current state: Google homepage. Search box visible and active.",
          },
          {
            role: "user",
            content: "Search for best laptops 2024",
          },
        ],
      });

      console.log(response.choices[0].message.content);
      console.log("Planned:", response.stratus?.action_sequence);
      console.log("Confidence:", response.stratus?.overall_confidence);
      console.log("Brain signal:", response.stratus?.brain_signal);
      ```

      ```python Python theme={null}
      import os
      from openai import OpenAI

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

      response = client.chat.completions.create(
          model="stratus-x1ac-small-gpt-4o",
          messages=[
              {
                  "role": "system",
                  "content": "Current state: Google homepage. Search box visible and active."
              },
              {
                  "role": "user",
                  "content": "Search for best laptops 2024"
              }
          ]
      )

      print(response.choices[0].message.content)
      print("Planned:", response.stratus.action_sequence)
      print("Confidence:", response.stratus.overall_confidence)
      print("Brain signal:", response.stratus.brain_signal)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="OpenAI SDK">
    <Info>
      Drop-in compatible. Just change the `baseURL` and use your Stratus API key.
    </Info>

    <CodeGroup>
      ```typescript TypeScript theme={null}
      import OpenAI from "openai";

      const client = new OpenAI({
        baseURL: "https://api.stratus.run/v1",
        apiKey: process.env.STRATUS_API_KEY,
      });

      const response = await client.chat.completions.create({
        model: "stratus-x1ac-small-gpt-4o",
        messages: [
          {
            role: "system",
            content: "Current state: Google homepage. Search box visible and active.",
          },
          {
            role: "user",
            content: "Search for best laptops 2024",
          },
        ],
      });

      console.log(response.choices[0].message.content);
      ```

      ```python Python theme={null}
      import os
      from openai import OpenAI

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

      response = client.chat.completions.create(
          model="stratus-x1ac-small-gpt-4o",
          messages=[
              {
                  "role": "system",
                  "content": "Current state: Google homepage. Search box visible and active."
              },
              {
                  "role": "user",
                  "content": "Search for best laptops 2024"
              }
          ]
      )

      print(response.choices[0].message.content)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Anthropic SDK">
    <Info>
      Drop-in compatible. Just change the `baseURL` and use your Stratus API key.
    </Info>

    <CodeGroup>
      ```typescript TypeScript theme={null}
      import Anthropic from "@anthropic-ai/sdk";

      const client = new Anthropic({
        baseURL: "https://api.stratus.run/v1",
        apiKey: process.env.STRATUS_API_KEY,
      });

      const response = await client.messages.create({
        model: "stratus-x1ac-small-claude-sonnet-4-5",
        max_tokens: 1024,
        messages: [
          {
            role: "user",
            content: "Search for best laptops 2024",
          },
        ],
      });

      console.log(response.content[0].text);
      ```

      ```python Python theme={null}
      import os
      import anthropic

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

      response = client.messages.create(
          model="stratus-x1ac-small-claude-sonnet-4-5",
          max_tokens=1024,
          messages=[
              {
                  "role": "user",
                  "content": "Search for best laptops 2024"
              }
          ]
      )

      print(response.content[0].text)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="LangChain">
    <Info>
      Drop-in compatible. Just change the `baseURL` and use your Stratus API key.
    </Info>

    <CodeGroup>
      ```typescript TypeScript theme={null}
      import { ChatOpenAI } from "@langchain/openai";

      const llm = new ChatOpenAI({
        configuration: {
          baseURL: "https://api.stratus.run/v1",
          apiKey: process.env.STRATUS_API_KEY,
        },
        model: "stratus-x1ac-small-gpt-4o",
      });

      const response = await llm.invoke("Search for best laptops 2024");
      ```

      ```python Python theme={null}
      import os
      from langchain_openai import ChatOpenAI

      llm = ChatOpenAI(
          base_url="https://api.stratus.run/v1",
          api_key=os.environ["STRATUS_API_KEY"],
          model="stratus-x1ac-small-gpt-4o"
      )

      response = llm.invoke("Search for best laptops 2024")
      ```
    </CodeGroup>
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    export STRATUS_API_KEY=your_api_key_here

    curl https://api.stratus.run/v1/chat/completions \
      -H "Authorization: Bearer $STRATUS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "stratus-x1ac-small-gpt-4o",
        "messages": [
          {
            "role": "system",
            "content": "Current state: Google homepage. Search box visible and active."
          },
          {
            "role": "user",
            "content": "Search for best laptops 2024"
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

## Understanding the Response

Stratus returns a standard OpenAI-compatible response envelope plus a `stratus` metadata block containing everything the planning layer produced.

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1740000000,
  "model": "stratus-x1ac-small",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I'll search for that. Clicking the search box and typing..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 312,
    "completion_tokens": 84,
    "total_tokens": 396
  },
  "stratus": {
    "stratus_model": "x1ac-small",
    "execution_llm": "gpt-4o",
    "key_source": "formation",
    "formation_markup_applied": 0.25,
    "action_sequence": ["focus", "type", "submit"],
    "steps_to_goal": 3,
    "overall_confidence": 0.94,
    "confidence": 0.94,
    "confidence_labels": ["High", "High", "Medium"],
    "predicted_state_changes": [18.2, 12.7, 9.1],
    "planning_time_ms": 12,
    "execution_time_ms": 740,
    "total_steps_executed": 3,
    "execution_trace": [
      {
        "step": 1,
        "action": "focus",
        "response_summary": "Clicking the search box..."
      },
      {
        "step": 2,
        "action": "type",
        "response_summary": "Typing the query..."
      },
      {
        "step": 3,
        "action": "submit",
        "response_summary": "Pressing Enter to submit..."
      }
    ],
    "brain_signal": {
      "action_type": "submit_form",
      "confidence": 0.9412,
      "plan_ahead": ["wait_for_results", "read_results"],
      "simulation_confirmed": true,
      "goal_proximity": 0.87
    }
  }
}
```

### Top-level fields

<CardGroup cols={2}>
  <Card title="id" icon="fingerprint" color="#94a3b8">
    Unique completion ID for this request.
  </Card>

  <Card title="usage" icon="calculator" color="#94a3b8">
    Token counts aggregated across all agentic loop iterations: `prompt_tokens`,
    `completion_tokens`, and `total_tokens`.
  </Card>
</CardGroup>

### LLM key source

<CardGroup cols={2}>
  <Card title="key_source" icon="key" color="#94a3b8">
    Where Stratus sourced the LLM key for this request: `"user"` (your stored or inline key) or `"formation"` (Formation's OpenRouter pool).
  </Card>

  <Card title="formation_markup_applied" icon="percent" color="#94a3b8">
    The markup applied when Formation's pool was used (`0.25` = 25%). `null` when `key_source` is `"user"` — no markup is applied on BYOK requests.
  </Card>
</CardGroup>

### Core planning fields

<CardGroup cols={2}>
  <Card title="action_sequence" icon="list-check" color="#22d3ee">
    The complete plan Stratus built **before** calling your LLM. Use it for logging, verification, or branching logic.
  </Card>

  <Card title="steps_to_goal" icon="route" color="#22d3ee">
    Number of steps in the plan. Always equal to `action_sequence.length`.
  </Card>

  <Card title="overall_confidence" icon="gauge-high" color="#c084fc">
    Top-1 action softmax probability (0–1). **This is the primary confidence field.** Below `0.7` usually means the state description needs more detail.
  </Card>

  <Card title="confidence" icon="gauge" color="#c084fc">
    Legacy alias for `overall_confidence`. Kept for backward compatibility — prefer `overall_confidence` in new integrations.
  </Card>

  <Card title="confidence_labels" icon="tag" color="#c084fc">
    Per-step confidence rating: `"High"` (embedding magnitude > 15), `"Medium"` (> 10), or `"Low"`. `null` if planning did not complete.
  </Card>

  <Card title="predicted_state_changes" icon="chart-line" color="#c084fc">
    Per-step L2 norm of predicted state embedding deltas. Higher values indicate larger predicted state transitions. `null` if planning did not complete.
  </Card>

  <Card title="stratus_model" icon="microchip" color="#34d399">
    The Stratus world model variant used, e.g. `x1ac-small` or `x1ac-base`.
  </Card>

  <Card title="execution_llm" icon="plug" color="#34d399">
    The underlying LLM that executed the plan, e.g. `gpt-4o` or `claude-sonnet-4-5`.
  </Card>
</CardGroup>

### Timing

<CardGroup cols={2}>
  <Card title="planning_time_ms" icon="bolt" color="#fbbf24">
    World model inference time in ms. Typically **under 15ms** for `small`,
    under 50ms for `base`. `null` if the world model was not loaded.
  </Card>

  <Card title="execution_time_ms" icon="clock" color="#fbbf24">
    Total LLM execution time in ms. Most of total request latency comes from
    here. `null` if not measured.
  </Card>
</CardGroup>

### Agentic loop

These fields are only populated when the agentic loop ran more than one step.

<CardGroup cols={2}>
  <Card title="total_steps_executed" icon="repeat" color="#fb923c">
    Number of LLM calls made in the agentic loop. Greater than `1` for
    multi-step executions.
  </Card>

  <Card title="execution_trace" icon="list-timeline" color="#fb923c">
    Per-step breakdown. Each entry contains `step` (number), `action` (string),
    and `response_summary` — the first 150 characters of the LLM response at
    that step.
  </Card>
</CardGroup>

### Brain signal

Populated only when StratusBrain is active. Contains the world model's forward-looking predictions for the current step.

<CardGroup cols={2}>
  <Card title="action_type" icon="bullseye" color="#a78bfa">
    The high-level action category predicted by StratusBrain, e.g. `submit_form`
    or `navigate`.
  </Card>

  <Card title="confidence" icon="percent" color="#a78bfa">
    Softmax probability for this action, rounded to 4 decimal places.
  </Card>

  <Card title="plan_ahead" icon="forward" color="#a78bfa">
    Predicted next 1–2 actions after the current step (lookahead).
  </Card>

  <Card title="simulation_confirmed" icon="circle-check" color="#a78bfa">
    Whether the world model validated this action via simulation before
    execution.
  </Card>

  <Card title="goal_proximity" icon="crosshairs" color="#a78bfa">
    Cosine similarity of the current state embedding vs. the goal embedding
    (0–1). `null` if goal embedding is unavailable.
  </Card>
</CardGroup>

<Tip>
  **State quality drives confidence.** `"some website"` → 0.61. `"Amazon product
      page, price $49.99, Add to Cart button visible"` → 0.94. The more specific
  your system message, the tighter the plan.
</Tip>

## Go Deeper

Stratus dominates tasks that require **predicting consequences before acting** — especially multi-step, cascade-heavy, or time-sensitive workflows. These tutorials show it in action:

<CardGroup cols={2}>
  <Card title="Web Navigation Agent" icon="globe" color="#22d3ee" href="/docs/tutorials/web-navigation">
    Build an agent that searches, filters, and books — handling every state
    transition through a real checkout flow.
  </Card>

  <Card title="Cascade Prediction" icon="diagram-project" color="#c084fc" href="/docs/tutorials/cascade-prediction">
    Actions that trigger waves of downstream effects. Stratus predicts the chain
    before the first click fires.
  </Card>

  <Card title="Temporal Sequencing" icon="clock" color="#fbbf24" href="/docs/tutorials/temporal-sequencing">
    Order-sensitive workflows where two actions triggered simultaneously cause
    conflicts.
  </Card>

  <Card title="Concurrent Task Agent" icon="layer-group" color="#34d399" href="/docs/tutorials/concurrent-tasks">
    Coordinate multiple parallel task threads with timing constraints and
    interference avoidance.
  </Card>
</CardGroup>