Skip to main content
Stratus is in private beta. Apply for access.

​
Prerequisites

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.

​
Install

npm install @formthefog/stratus-sdk-ts

​
Make Your First Call

The native SDK exposes response.stratus — action sequences, confidence scores, and world-model metadata not available through third-party SDKs.
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);

​
Understanding the Response

Stratus returns a standard OpenAI-compatible response envelope plus a stratus metadata block containing everything the planning layer produced. 
{
  "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

id

Unique completion ID for this request.

usage

Token counts aggregated across all agentic loop iterations: prompt_tokens, completion_tokens, and total_tokens.

​
LLM key source

key_source

Where Stratus sourced the LLM key for this request: "user" (your stored or inline key) or "formation" (Formation’s OpenRouter pool).

formation_markup_applied

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.

​
Core planning fields

action_sequence

The complete plan Stratus built before calling your LLM. Use it for logging, verification, or branching logic.

steps_to_goal

Number of steps in the plan. Always equal to action_sequence.length.

overall_confidence

Top-1 action softmax probability (0–1). This is the primary confidence field. Below 0.7 usually means the state description needs more detail.

confidence

Legacy alias for overall_confidence. Kept for backward compatibility — prefer overall_confidence in new integrations.

confidence_labels

Per-step confidence rating: "High" (embedding magnitude > 15), "Medium" (> 10), or "Low". null if planning did not complete.

predicted_state_changes

Per-step L2 norm of predicted state embedding deltas. Higher values indicate larger predicted state transitions. null if planning did not complete.

stratus_model

The Stratus world model variant used, e.g. x1ac-small or x1ac-base.

execution_llm

The underlying LLM that executed the plan, e.g. gpt-4o or claude-sonnet-4-5.

​
Timing

planning_time_ms

World model inference time in ms. Typically under 15ms for small, under 50ms for base. null if the world model was not loaded.

execution_time_ms

Total LLM execution time in ms. Most of total request latency comes from here. null if not measured.

​
Agentic loop

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

total_steps_executed

Number of LLM calls made in the agentic loop. Greater than 1 for multi-step executions.

execution_trace

Per-step breakdown. Each entry contains step (number), action (string), and response_summary — the first 150 characters of the LLM response at that step.

​
Brain signal

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

action_type

The high-level action category predicted by StratusBrain, e.g. submit_form or navigate.

confidence

Softmax probability for this action, rounded to 4 decimal places.

plan_ahead

Predicted next 1–2 actions after the current step (lookahead).

simulation_confirmed

Whether the world model validated this action via simulation before execution.

goal_proximity

Cosine similarity of the current state embedding vs. the goal embedding (0–1). null if goal embedding is unavailable.
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.

​
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:

Web Navigation Agent

Build an agent that searches, filters, and books — handling every state transition through a real checkout flow.

Cascade Prediction

Actions that trigger waves of downstream effects. Stratus predicts the chain before the first click fires.

Temporal Sequencing

Order-sensitive workflows where two actions triggered simultaneously cause conflicts.

Concurrent Task Agent

Coordinate multiple parallel task threads with timing constraints and interference avoidance.