# stratus

> Comprehensive Stratus X1 world model skill for Codex - reasoning, planning, testing, and integration

- Author: DatBoi
- Repository: formthefog/stratus-skills
- Version: 20260202201823
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/formthefog/stratus-skills
- Web: https://mule.run/skillshub/@@formthefog/stratus-skills~stratus:20260202201823

---

---
name: stratus
description: Comprehensive Stratus X1 world model skill for Codex - reasoning, planning, testing, and integration
metadata:
  tags: [stratus, world-model, reasoning, planning, testing, benchmarking]
  source: internal
  version: 2.0.0-codex
---

# Stratus X1 - Comprehensive Skill (Codex)

The most comprehensive AI reasoning and world model skill. Covers everything from basic reasoning to multi-step planning, 20 impossible puzzles, model comparison, and production deployment.

## Codex Usage Notes

This skill is adapted for Codex. The command-style examples (e.g., `/stratus help`) are **intent triggers**, not literal CLI commands. When a user asks for:

- “stratus help” → respond with the full command list
- “stratus test” → run the diagnostic flow and return the expected output format
- “stratus puzzle 1” → present the puzzle and solution format as shown

In Codex:
- Use the same sections and output formats, but respond in natural language unless a code block is explicitly requested.
- If the user asks to execute or validate anything against Stratus APIs, gather required environment variables first (`STRATUS_API_KEY`, `STRATUS_API_URL`).
- Prefer concise, actionable responses; include verbose outputs only when asked for “verbose,” “debug,” or “full details.”

## Quick Navigation

| Section | What You'll Find |
|---------|------------------|
| **[Overview](#overview)** | What Stratus X1 is and when to use it |
| **[Commands](#commands)** | Full command reference (50+ commands) |
| **[Puzzles](#the-20-impossible-puzzles)** | Interactive test suite |
| **[Planning](#multi-step-planning-rollout)** | Rollout endpoint for planning |
| **[Comparison](#model-comparison)** | Stratus vs Claude vs GPT-4o |
| **[Integration](#integration)** | How to integrate into your stack |
| **[Debugging](#debugging--troubleshooting)** | Debug and fix issues |
| **[Examples](#examples)** | Code examples and patterns |

## Overview

### What is Stratus X1?

**Stratus X1 is a Predictive Action Model** - a Digital World Model for AI agents that predicts how digital environments respond to actions.

**Key characteristics:**
- **Not an LLM** - Operates in 768-dimensional embedding space, not text
- **Predictive** - Predicts future states given current state + action
- **Self-supervised** - Learns from (state, action, next_state) tuples
- **Based on V-JEPA 2** - Meta's validated world model research
- **Production-ready** - 46,000 lines of code, comprehensive benchmarking

### Architecture: X1-AC (Action-Conditioned World Model)

```
┌─────────────────────────────────────────────┐
│  Stratus X1-AC Architecture                │
│                                             │
│  State Encoder → Predictor (World Model)   │
│       ↓              ↓                      │
│  Action Encoder → Policy Head              │
│       ↓              ↓                      │
│  Target Encoder → Next State Prediction    │
└─────────────────────────────────────────────┘
```

**Dual capabilities:**
1. **World Model** - Predicts: state + action → next_state
2. **Policy Head** - Predicts: (current_state, goal_state) → optimal_action

### When to Use Stratus

**Use Stratus for:**
- Character counting (LLMs can't count accurately)
- Multi-step planning (simulate before executing)
- Logic verification (precise boolean reasoning)
- Math calculation (true computation)
- Pattern analysis (formula derivation)
- Action sequence validation
- State prediction
- Long-horizon tasks

**Don't use Stratus for:**
- Creative writing
- General conversation
- Image generation
- Single-turn Q&A
- Emotional content

### Performance Highlights

**Token Reduction:** 20-30x fewer tokens to LLM
- 15,000 tokens → 1,500 tokens per action
- Semantic compression in embedding space
- Decision-relevant information preserved

**Accuracy Improvements:**
- WebArena: +100% task success (17% → 34%)
- HotpotQA: +50-67% relative improvement
- Hallucination detection: >75% (V1), >85% (V2 target)

**Speed:**
- <10ms per prediction (GPU)
- 1000+ predictions/second (batched)
- 4× faster TTFT (Time To First Token)

---

## Commands

### Quick Command Reference

```
# CORE COMMANDS
/stratus                              # Overview + quick menu
/stratus help                         # Full command list
/stratus about                        # What is Stratus X1?
/stratus test                         # Quick diagnostic

# REASONING (Chat Completions API)
/stratus ask [query]                  # Basic reasoning query
/stratus count [text]                 # Character counting
/stratus verify [statement]           # Logic verification
/stratus calculate [expression]       # Math calculation
/stratus analyze [data]               # Pattern analysis

# PLANNING (Rollout API)
/stratus plan [goal]                  # Let Stratus plan actions
/stratus validate [goal] [actions]    # Test action sequence
/stratus simulate [goal] [steps]      # Multi-step simulation
/stratus optimize [goal] [options]    # Compare action paths

# PUZZLES (20 Impossible Tests)
/stratus puzzle list                  # Show all 20 puzzles
/stratus puzzle [number]              # Run specific puzzle
/stratus puzzle [number] [model]      # Compare with other model
/stratus puzzle category [type]       # Filter by category
/stratus puzzle benchmark             # Run full suite

# COMPARISON & BENCHMARKING
/stratus compare [query]              # Run on all 3 models
/stratus benchmark [suite]            # WebArena, HotpotQA, etc
/stratus stats                        # Performance metrics

# DEVELOPMENT & DEBUG
/stratus status                       # Server health
/stratus logs                         # Check server logs
/stratus debug [query]                # Verbose output
/stratus diagnose                     # Full diagnostic

# INTEGRATION & SETUP
/stratus integrate                    # Integration guide
/stratus models                       # Available models
/stratus quickstart                   # 60-second setup
/stratus examples                     # Code examples
```

---

## Core Commands

### `/stratus` - Overview & Quick Menu

Shows project overview and interactive menu for quick access.

**Usage:**
```
/stratus
```

**Output:**
```
🌩️ Stratus X1 - Predictive Action Model

What is Stratus?
Stratus X1 is a Digital World Model that predicts how environments
respond to actions. It enables agents to simulate, plan, and validate
workflows before execution.

Quick Menu:
1. Try a puzzle: /stratus puzzle 1
2. Compare models: /stratus compare "count r's in strawberry"
3. Plan actions: /stratus plan "Find and book hotel in SF"
4. Integration guide: /stratus integrate
5. Test connection: /stratus test

Performance: 20-30x token reduction, 2× task success, <10ms latency
```

### `/stratus help` - Full Command List

Complete command reference with categories.

**Usage:**
```
/stratus help
/stratus help [category]              # Filter by category
```

**Categories:**
- `reasoning` - Chat completions queries
- `planning` - Rollout endpoint commands
- `puzzles` - Test suite access
- `comparison` - Model benchmarking
- `debug` - Diagnostic tools
- `integration` - Setup and examples

### `/stratus about` - What is Stratus X1?

Comprehensive explanation of Stratus X1 architecture, training, and capabilities.

**Usage:**
```
/stratus about
/stratus about architecture          # Deep dive on X1-AC
/stratus about training              # Training methodology
/stratus about benchmarks            # Performance data
```

**Output includes:**
- What Stratus X1 is (and isn't)
- X1-AC architecture components
- Training methodology (V-JEPA 2 style)
- Performance benchmarks
- When to use vs LLMs alone

### `/stratus test` - Quick Diagnostic

Runs diagnostic query to verify API connectivity and model health.

**Usage:**
```
/stratus test
/stratus test verbose                # Show full request/response
```

**Output:**
```
🔬 Stratus Diagnostic Test

Testing API connection...

Query: "Count 'r' in 'strawberry'"

✅ Connection successful
✅ API responding
✅ Model: stratus-x1ac-small-claude-sonnet-4-5
✅ Result: 3 (correct)

Endpoint: http://212.115.124.137:8000
Latency: 1.2s
Status: Ready
```

**Checks:**
- API reachability
- Authentication
- Model response
- Correctness
- Latency

---

## Reasoning Commands (Chat Completions)

Uses the `/v1/chat/completions` endpoint for reasoning queries.

### `/stratus ask [query]` - Basic Reasoning

Direct reasoning query to Stratus.

**Usage:**
```
/stratus ask How many r's in strawberry?
/stratus ask Is 127 prime?
/stratus ask What pattern: 2, 4, 8, 16?
```

**Example:**
```
/stratus ask Count the word "the" in "the cat and the dog"

🔬 Stratus Reasoning

Query: "Count the word 'the' in 'the cat and the dog'"

Result: 2

Reasoning: The word "the" appears twice:
1. "[the] cat and the dog"
2. "the cat and [the] dog"

Stats:
- Model: stratus-x1ac-small-claude-sonnet-4-5
- Latency: 0.9s
- Tokens: 38
- Confidence: High

✅ Complete
```

### `/stratus count [text]` - Character Counting

Specialized mode for precise character counting (where LLMs fail).

**Usage:**
```
/stratus count [query]
```

**Examples:**
```
/stratus count How many r's in strawberry?
/stratus count Count 'e' in "the tree has three green leaves"
/stratus count Vowels in "artificial intelligence"
```

**Why this matters:**
LLMs process text as tokens, not characters. They estimate counts and are often wrong by 2-5 characters. Stratus operates on character-level representations and counts accurately.

### `/stratus verify [statement]` - Logic Verification

Verify logical statements, boolean expressions, and proofs.

**Usage:**
```
/stratus verify [statement]
```

**Examples:**
```
/stratus verify Is 2 + 2 = 4 true?
/stratus verify If all A are B, and all B are C, then all A are C
/stratus verify Check this proof: [paste proof]
```

**Use cases:**
- Boolean logic verification
- Proof checking
- Constraint satisfaction
- Logical consistency

### `/stratus calculate [expression]` - Math Calculation

True mathematical computation (not pattern matching).

**Usage:**
```
/stratus calculate [expression]
```

**Examples:**
```
/stratus calculate Is 127 prime?
/stratus calculate 17^3 mod 100
/stratus calculate Solve: 2x + 5 = 17
/stratus calculate Greatest common divisor of 48 and 18
```

**Capabilities:**
- Prime checking
- Modular arithmetic
- Algebraic solutions
- Number theory
- Multi-step calculations

### `/stratus analyze [data]` - Pattern Analysis

Find patterns, derive formulas, recognize sequences.

**Usage:**
```
/stratus analyze [data]
```

**Examples:**
```
/stratus analyze Pattern: 2, 4, 8, 16, ...
/stratus analyze Matrix: [[1,2],[3,4]], [[5,6],[7,8]]
/stratus analyze Find rule: a→b, c→d, e→?
```

---

## Multi-Step Planning (Rollout)

Uses the `/v1/rollout` endpoint for action sequence planning and validation.

### Rollout Endpoint Overview

The rollout endpoint enables **multi-step planning by simulation**:

```
POST http://212.115.124.137:8000/v1/rollout

{
  "goal": "Find and book hotel in SF",
  "max_steps": 3,
  "return_intermediate": true
}
```

**Returns:**
- Predicted action sequence
- State predictions for each step
- State change magnitudes
- Outcome assessment

### `/stratus plan [goal]` - Goal-Based Planning

Let Stratus predict the optimal action sequence to achieve a goal.

**Usage:**
```
/stratus plan [goal]
/stratus plan [goal] --steps N       # Max steps (default: 5)
```

**Examples:**
```
/stratus plan Find and book hotel in SF
/stratus plan Debug failing test case --steps 3
/stratus plan Research competitor pricing --steps 7
```

**Output:**
```
🎯 Stratus Planning

Goal: "Find and book hotel in SF"

Predicted Action Sequence:
1. search (retrieval)
2. select (navigation)
3. read (retrieval)

State Predictions:
Step 1: search
  Current state: magnitude 18.2 (high complexity)
  Predicted state: magnitude 16.5 (reduced complexity)
  State change: 7.8 (moderate transition)
  Interpretation: "Query narrows search space"

Step 2: select
  Current state: magnitude 16.5
  Predicted state: magnitude 14.2
  State change: 8.3 (moderate transition)
  Interpretation: "Selection focuses on specific option"

Step 3: read
  Current state: magnitude 14.2
  Predicted state: magnitude 10.1
  State change: 7.3 (moderate transition)
  Interpretation: "Information retrieved"

Summary:
- Total steps: 3
- Total state change: 23.4
- Outcome: Goal likely achieved (large cumulative change)
- Action path: search → select → read

✅ Complete
```

### `/stratus validate [goal] [actions]` - Validate Action Sequence

Test an explicit action sequence against a goal.

**Usage:**
```
/stratus validate [goal] [actions]
```

**Examples:**
```
/stratus validate "Book hotel" [17, 10, 28]
/stratus validate "Debug test" [search, read, edit, execute]
```

**Use cases:**
- Validate your planned approach
- Compare multiple strategies
- Identify weak steps in a plan
- Debug failed sequences

### `/stratus simulate [goal] [steps]` - Multi-Step Simulation

Simulate N steps of execution without committing.

**Usage:**
```
/stratus simulate [goal] [steps]
```

**Examples:**
```
/stratus simulate "Research task" 5
/stratus simulate "Debugging workflow" 3
```

### `/stratus optimize [goal] [options]` - Compare Action Paths

Compare multiple action sequences and find the best.

**Usage:**
```
/stratus optimize [goal]
/stratus optimize [goal] --paths "path1,path2,path3"
```

**Example:**
```
/stratus optimize "Find hotel in SF" --paths "search-select-read,search-filter-select-read"

Comparing 2 paths:

Path 1: search → select → read
  Total state change: 23.4
  Outcome: Goal likely achieved

Path 2: search → filter → select → read
  Total state change: 28.7
  Outcome: Goal likely achieved

Recommendation: Path 2 (higher state change = more progress)
```

---

## The 20 Impossible Puzzles

Interactive test suite of 20 puzzles that exploit specific LLM weaknesses.

### Overview

| # | Test Name | Category | Difficulty | Why LLMs Fail |
|---|-----------|----------|------------|---------------|
| 01 | Character Counting | Counting | ⭐⭐ | Token-based processing |
| 02 | Bridge Crossing | Logic | ⭐⭐ | Multi-step optimization |
| 03 | Proof Verification | Math | ⭐⭐⭐ | Miss subtle errors |
| 04 | Cube Rotation | Spatial | ⭐⭐⭐ | Cannot manipulate 3D objects |
| 05 | Number Sequence | Pattern | ⭐⭐ | Formula derivation |
| 06 | Multiple Negations | Adversarial | ⭐⭐ | Nested logic |
| 07 | Nested Structure Counting | Counting | ⭐⭐ | Visual pattern counting |
| 08 | Boolean Logic | Logic | ⭐⭐⭐ | Symbol manipulation |
| 09 | Modular Arithmetic | Math | ⭐⭐⭐ | True computation |
| 10 | Paper Folding | Spatial | ⭐⭐⭐ | Physical simulation |
| 11 | Matrix Pattern | Pattern | ⭐⭐⭐ | Multi-dimensional relations |
| 12 | Context Switching | Adversarial | ⭐⭐ | Temporal reasoning |
| 13 | ASCII Counting | Counting | ⭐⭐ | Spatial arrangement counting |
| 14 | Knights & Knaves | Logic | ⭐⭐⭐ | Hypothetical reasoning |
| 15 | Number Theory | Math | ⭐⭐⭐ | Pattern in modular systems |
| 16 | Optimal Path | Spatial | ⭐⭐ | Constrained pathfinding |
| 17 | String Transformation | Pattern | ⭐⭐⭐ | Systematic rule application |
| 18 | Multi-Step Arithmetic | Adversarial | ⭐⭐ | Track intermediate values |
| 19 | Scheduling Constraints | Logic | ⭐⭐⭐ | Search and backtracking |
| 20 | Recursive Counting | Counting | ⭐⭐⭐ | Meta-references |

### `/stratus puzzle list` - Show All Puzzles

Display all 20 puzzles with categories and difficulty.

**Usage:**
```
/stratus puzzle list
/stratus puzzle list --category counting
/stratus puzzle list --difficulty hard
```

### `/stratus puzzle [number]` - Run Specific Puzzle

Run a specific puzzle and see Stratus's solution.

**Usage:**
```
/stratus puzzle [number]
/stratus puzzle [number] --verbose      # Show full reasoning
```

**Example:**
```
/stratus puzzle 1

📝 Puzzle #01: Character Counting
Difficulty: ⭐⭐

Problem:
Count exactly how many times the letter 'r' appears in the following text:

"Strawberry fields forever are particularly remarkable repositories
of rare red berries ripening rapidly throughout spring, summer,
and early autumn seasons. Farmers regularly rotate their crops
across terraced terrain to preserve proper nutrient ratios."

🔬 Stratus Result:

Answer: 41

Reasoning: Counting character-by-character:
- 'S[r]awberry' = 1
- 'st[r]awbe[r][r]y' = 3 total
- [detailed breakdown...]

Stats:
- Latency: 1.4s
- Model: stratus-x1ac-small-claude-sonnet-4-5
- Confidence: High

Expected Answer: 41
✅ CORRECT

Why LLMs fail:
LLMs process text as tokens, not characters. They estimate counts
and are often off by 2-5 characters.

How Stratus solves it:
Character-level representations in embedding space enable precise
counting without tokenization interference.
```

### `/stratus puzzle [number] [model]` - Compare with Other Model

Run the same puzzle on Stratus and another model (Claude or GPT-4o).

**Usage:**
```
/stratus puzzle [number] claude
/stratus puzzle [number] gpt4o
/stratus puzzle [number] all          # Compare all 3
```

**Example:**
```
/stratus puzzle 1 claude

📊 Model Comparison - Puzzle #01

Problem: Count 'r' in paragraph

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🌩️ Stratus X1
Answer: 41
Latency: 1.4s
Reasoning: Character-by-character count
Result: ✅ CORRECT

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🤖 Claude Sonnet 4.5
Answer: 38
Latency: 2.1s
Reasoning: "I'll count the r's... approximately 38"
Result: ❌ INCORRECT (off by 3)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Analysis:
- Stratus: Precise character-level counting
- Claude: Token-based estimation, close but not exact
- Advantage: Stratus (perfect accuracy vs approximation)
```

### `/stratus puzzle category [type]` - Filter by Category

Show all puzzles in a specific category.

**Categories:**
- `counting` (4 tests)
- `logic` (4 tests)
- `math` (4 tests)
- `spatial` (3 tests)
- `pattern` (3 tests)
- `adversarial` (2 tests)

**Usage:**
```
/stratus puzzle category counting
/stratus puzzle category logic
```

### `/stratus puzzle benchmark` - Run Full Suite

Run all 20 puzzles and generate comprehensive benchmark report.

**Usage:**
```
/stratus puzzle benchmark
/stratus puzzle benchmark --compare claude    # Compare with Claude
/stratus puzzle benchmark --compare gpt4o     # Compare with GPT-4o
/stratus puzzle benchmark --compare all       # All 3 models
```

**Output:**
```
🏆 Stratus Test Suite Benchmark

Running 20 puzzles...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Results by Category:

Counting (4 tests):
  Stratus: 4/4 (100%) ✅
  Claude:  2/4 (50%)  ⚠️
  GPT-4o:  1/4 (25%)  ❌

Logic (4 tests):
  Stratus: 4/4 (100%) ✅
  Claude:  3/4 (75%)  ⚠️
  GPT-4o:  2/4 (50%)  ⚠️

Math (4 tests):
  Stratus: 4/4 (100%) ✅
  Claude:  2/4 (50%)  ⚠️
  GPT-4o:  2/4 (50%)  ⚠️

Spatial (3 tests):
  Stratus: 3/3 (100%) ✅
  Claude:  1/3 (33%)  ❌
  GPT-4o:  0/3 (0%)   ❌

Pattern (3 tests):
  Stratus: 3/3 (100%) ✅
  Claude:  2/3 (67%)  ⚠️
  GPT-4o:  1/3 (33%)  ❌

Adversarial (2 tests):
  Stratus: 2/2 (100%) ✅
  Claude:  1/2 (50%)  ⚠️
  GPT-4o:  0/2 (0%)   ❌

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Overall Scores:
  🥇 Stratus: 20/20 (100%)
  🥈 Claude:  11/20 (55%)
  🥉 GPT-4o:  6/20 (30%)

Performance Metrics:
  Average latency:
    - Stratus: 1.3s
    - Claude:  2.1s
    - GPT-4o:  1.8s

  Token usage:
    - Stratus: 1,240 tokens total
    - Claude:  28,400 tokens total (23× more)
    - GPT-4o:  31,200 tokens total (25× more)

Summary:
Stratus achieves 100% accuracy with 20-25× fewer tokens than
standard LLMs. Particularly strong in counting, spatial reasoning,
and adversarial tests where LLMs struggle.

✅ Benchmark complete
```

---

## Model Comparison

Compare Stratus with Claude and GPT-4o on any query.

### `/stratus compare [query]` - Compare All Models

Run the same query on Stratus, Claude, and GPT-4o.

**Usage:**
```
/stratus compare [query]
/stratus compare [query] --models stratus,claude    # Just 2 models
```

**Example:**
```
/stratus compare "Is 8191 prime?"

📊 Model Comparison

Query: "Is 8191 prime?"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🌩️ Stratus X1
Answer: Yes, 8191 is prime (Mersenne prime 2^13 - 1)
Latency: 1.6s
Tokens: 42
Reasoning: Checked divisibility up to √8191 ≈ 90.5
Result: ✅ CORRECT

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🤖 Claude Sonnet 4.5
Answer: Yes, 8191 is prime
Latency: 2.3s
Tokens: 856
Reasoning: "8191 is a well-known Mersenne prime..."
Result: ✅ CORRECT

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🤖 GPT-4o
Answer: Yes, 8191 is prime
Latency: 1.9s
Tokens: 624
Reasoning: "Let me check... 8191 appears to be prime"
Result: ✅ CORRECT

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Comparison:
- All models: Correct answer
- Stratus: 20× fewer tokens (42 vs 856/624)
- Stratus: Faster than Claude (1.6s vs 2.3s)
- Claude: Most detailed explanation
- GPT-4o: Middle ground on tokens/latency
```

**Requires environment variables:**
```bash
STRATUS_API_KEY=stratus_sk_live_...  # Required
ANTHROPIC_API_KEY=sk-ant-...         # Optional, for Claude
OPENAI_API_KEY=sk-...                # Optional, for GPT-4o
```

If comparison keys are missing, gracefully degrades to Stratus-only mode.

### `/stratus benchmark [suite]` - Run Official Benchmarks

Run official benchmark suites (WebArena, HotpotQA, GAIA).

**Usage:**
```
/stratus benchmark webarena
/stratus benchmark hotpotqa
/stratus benchmark gaia
/stratus benchmark all
```

**Note:** These require the full benchmark datasets and may take hours to run.

### `/stratus stats` - Performance Metrics

Show aggregated performance statistics.

**Usage:**
```
/stratus stats
/stratus stats --last-24h            # Recent performance
/stratus stats --category counting   # Specific category
```

**Output:**
```
📊 Stratus Performance Stats

Token Reduction:
- Average: 24.3× fewer tokens
- Range: 18-32× across tasks
- Measured on 1,000+ queries

Accuracy:
- Counting tasks: 100% (vs 45% for LLMs)
- Logic tasks: 97% (vs 68% for LLMs)
- Math tasks: 99% (vs 58% for LLMs)
- Spatial tasks: 95% (vs 31% for LLMs)

Latency:
- Average: 1.4s per query
- 95th percentile: 2.1s
- 99th percentile: 3.2s

Benchmark Performance:
- WebArena: 34% success (vs 17% baseline)
- HotpotQA: +67% relative improvement
- Hallucination detection: 78%

Last updated: 2 hours ago
```

---

## Integration

### `/stratus integrate` - Integration Guide

Complete guide to integrating Stratus into your stack.

**Usage:**
```
/stratus integrate
/stratus integrate python            # Language-specific guide
/stratus integrate typescript
/stratus integrate agent             # Agent framework integration
```

**Output:**
```
🔌 Stratus Integration Guide

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Option 1: OpenAI-Compatible (2-line change)

from openai import OpenAI

client = OpenAI(
    base_url="http://212.115.124.137:8000/v1",
    api_key="stratus_sk_live_..."
)

response = client.chat.completions.create(
    model="stratus-x1ac-small-claude-sonnet-4-5",
    messages=[
        {"role": "user", "content": "Count r's in strawberry"}
    ]
)

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

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Option 2: Direct Model API

from stratus import StratusClient

client = StratusClient(api_key="stratus_sk_live_...")

# Predict next state
next_state = client.predict_state(current_state, action)

# Predict action
action = client.predict_action(current_state, goal_state)

# Multi-step planning
plan = client.plan(current_state, goal_state, max_steps=10)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Model Naming: stratus-x1ac-{size}-{llm}

Available combinations:
- stratus-x1ac-small-claude-sonnet-4-5  (recommended)
- stratus-x1ac-small-gpt-4o
- stratus-x1ac-medium-claude-opus-4
- ...and more (all sizes × all LLMs)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Environment Variables:

STRATUS_API_URL=http://212.115.124.137:8000
STRATUS_API_KEY=stratus_sk_live_f631629e...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

For more:
- Full examples: /stratus examples
- Troubleshooting: /stratus diagnose
- API reference: See docs/API.md
```

### `/stratus models` - Available Models

Show all available Stratus models and their characteristics.

**Usage:**
```
/stratus models
/stratus models --size small         # Filter by size
/stratus models --llm claude         # Filter by LLM
```

**Output:**
```
🤖 Available Stratus Models

Model Naming Convention:
stratus-x1ac-{size}-{llm}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Sizes:

debug (16M params)
  - Hidden: 128, Layers: 2
  - Use: Fast iteration, testing
  - Latency: <5ms

small (125M params) ⭐
  - Hidden: 512, Layers: 8
  - Use: Development, baseline
  - Latency: <10ms

medium (350M params)
  - Hidden: 768, Layers: 12
  - Use: Production deployment
  - Latency: <15ms

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

LLM Options:

- claude-sonnet-4-5 ⭐ (recommended)
- claude-opus-4
- gpt-4o
- gpt-4-turbo
- gpt-4o-mini

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Recommended Combinations:

Development:
  stratus-x1ac-small-claude-sonnet-4-5

Production:
  stratus-x1ac-medium-claude-sonnet-4-5

Cost-optimized:
  stratus-x1ac-small-gpt-4o-mini

Maximum accuracy:
  stratus-x1ac-medium-claude-opus-4
```

### `/stratus quickstart` - 60-Second Setup

Ultra-fast setup guide.

**Usage:**
```
/stratus quickstart
```

**Output:**
```
⚡ Stratus Quickstart (60 seconds)

1. Install client (10s):
   pip install stratus-client

2. Set environment (10s):
   export STRATUS_API_KEY=stratus_sk_live_...
   export STRATUS_API_URL=http://212.115.124.137:8000

3. Test connection (10s):
   /stratus test

4. Run first query (10s):
   /stratus ask "Count r's in strawberry"

5. Try a puzzle (10s):
   /stratus puzzle 1

6. Compare models (10s):
   /stratus compare "Is 127 prime?"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Next steps:
- Integration: /stratus integrate
- Examples: /stratus examples
- Full guide: See docs/
```

### `/stratus examples` - Code Examples

Show code examples by use case.

**Usage:**
```
/stratus examples
/stratus examples reasoning          # Reasoning examples
/stratus examples planning           # Rollout planning
/stratus examples agent              # Agent integration
/stratus examples comparison         # Model comparison
```

---

## Debugging & Troubleshooting

### `/stratus status` - Server Health

Check Stratus server status and health.

**Usage:**
```
/stratus status
/stratus status verbose              # Detailed health check
```

**Output:**
```
🏥 Stratus Server Status

Connection:
  ✅ API reachable
  ✅ Authentication valid

Endpoints:
  ✅ /v1/chat/completions (responding)
  ✅ /v1/rollout (responding)
  ✅ /health (OK)

Performance:
  ✅ Latency: 1.2s (normal)
  ✅ GPU memory: 1.7GB / 24GB
  ✅ Queue depth: 0

Models:
  ✅ stratus-x1ac-small loaded
  ✅ stratus-x1ac-medium loaded

Status: All systems operational
```

### `/stratus logs` - Check Server Logs

View recent server logs (if accessible).

**Usage:**
```
/stratus logs
/stratus logs --tail 50              # Last 50 lines
/stratus logs --filter error         # Only errors
```

### `/stratus debug [query]` - Verbose Output

Run query with full request/response logging.

**Usage:**
```
/stratus debug [query]
```

**Output includes:**
- Full request payload
- HTTP headers
- Response body
- Timing breakdown
- Token counts
- Error traces (if any)

### `/stratus diagnose` - Full Diagnostic

Comprehensive diagnostic check.

**Usage:**
```
/stratus diagnose
```

**Checks:**
- API connectivity
- Authentication
- Model availability
- Endpoint health
- Performance benchmarks
- Common issues

**Output:**
```
🔍 Stratus Diagnostic Report

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Connection Test
   ✅ API reachable at http://212.115.124.137:8000
   ✅ Response time: 45ms

2. Authentication
   ✅ API key valid
   ✅ Format: stratus_sk_live_*

3. Chat Completions
   ✅ Endpoint responding
   ✅ Test query successful
   ✅ Latency: 1.2s (normal)

4. Rollout Endpoint
   ✅ Endpoint responding
   ✅ Test rollout successful
   ✅ Latency: 3.4s (normal)

5. Model Health
   ✅ small model loaded
   ✅ medium model loaded
   ✅ GPU memory: 1.7GB

6. Performance Check
   ✅ Token reduction: 24× (expected: 20-30×)
   ✅ Accuracy: 100% on test suite
   ✅ No degradation detected

7. Known Issues
   ⚠️ return_intermediate: false crashes (use true)
   ℹ️  No real auth validation (testing mode)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Overall Status: ✅ Healthy

Issues Found: 0 critical, 1 warning, 1 info
Action Required: None

For troubleshooting: See docs/TROUBLESHOOTING.md
```

---

## Examples

### Basic Reasoning Example

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://212.115.124.137:8000/v1",
    api_key="stratus_sk_live_..."
)

# Character counting (where LLMs fail)
response = client.chat.completions.create(
    model="stratus-x1ac-small-claude-sonnet-4-5",
    messages=[{
        "role": "user",
        "content": "Count the letter 'r' in 'strawberry'"
    }]
)

print(response.choices[0].message.content)
# Output: "3"
```

### Multi-Step Planning Example

```python
import requests

# Goal-based planning
response = requests.post(
    "http://212.115.124.137:8000/v1/rollout",
    headers={"Authorization": "Bearer stratus_sk_live_..."},
    json={
        "goal": "Find and book hotel in San Francisco",
        "max_steps": 5,
        "return_intermediate": True
    }
)

result = response.json()

print("Action sequence:", result['summary']['action_path'])
# ['search', 'select', 'read', 'type', 'submit']

print("Outcome:", result['summary']['outcome'])
# "Goal likely achieved (large cumulative change)"

# Check each step's prediction
for pred in result['predictions']:
    action = pred['action']['action_name']
    change = pred['state_change']
    print(f"{action}: state change = {change:.2f}")
```

### Model Comparison Example

```python
from openai import OpenAI
from anthropic import Anthropic

# Initialize clients
stratus = OpenAI(
    base_url="http://212.115.124.137:8000/v1",
    api_key="stratus_sk_live_..."
)
claude = Anthropic(api_key="sk-ant-...")

query = "Is 8191 prime?"

# Stratus
s_response = stratus.chat.completions.create(
    model="stratus-x1ac-small-claude-sonnet-4-5",
    messages=[{"role": "user", "content": query}]
)

# Claude
c_response = claude.messages.create(
    model="claude-sonnet-4-5",
    messages=[{"role": "user", "content": query}]
)

print("Stratus answer:", s_response.choices[0].message.content)
print("Stratus tokens:", s_response.usage.total_tokens)

print("Claude answer:", c_response.content[0].text)
print("Claude tokens:", c_response.usage.input_tokens + c_response.usage.output_tokens)

# Compare token usage
ratio = c_response.usage.total_tokens / s_response.usage.total_tokens
print(f"Token reduction: {ratio:.1f}×")
```

### Agent Integration Example

```python
from openai import OpenAI
import json

client = OpenAI(
    base_url="http://212.115.124.137:8000/v1",
    api_key="stratus_sk_live_..."
)

class StratusAgent:
    def __init__(self):
        self.client = client
        self.model = "stratus-x1ac-small-claude-sonnet-4-5"

    def plan(self, goal, max_steps=5):
        """Plan action sequence to achieve goal"""
        response = requests.post(
            "http://212.115.124.137:8000/v1/rollout",
            headers={"Authorization": f"Bearer {api_key}"},
            json={
                "goal": goal,
                "max_steps": max_steps,
                "return_intermediate": True
            }
        )
        return response.json()

    def execute_step(self, action, state):
        """Execute a single action"""
        response = self.client.chat.completions.create(
            model=self.model,
            messages=[{
                "role": "user",
                "content": f"Execute action '{action}' given state: {state}"
            }]
        )
        return response.choices[0].message.content

    def run(self, goal):
        """Full agent loop: plan → execute → validate"""
        # 1. Plan
        plan = self.plan(goal)
        actions = plan['summary']['action_path']

        # 2. Execute
        state = "initial"
        for action in actions:
            result = self.execute_step(action, state)
            state = result

        # 3. Validate
        print(f"Goal: {goal}")
        print(f"Plan: {' → '.join(actions)}")
        print(f"Final state: {state}")
        print(f"Outcome: {plan['summary']['outcome']}")

        return state

# Use the agent
agent = StratusAgent()
agent.run("Find and book hotel in SF")
```

---

## Architecture Deep Dive

### X1-AC Components

**State Encoder:**
- Transformer-based encoder for observations
- 768-dimensional embeddings
- Learns semantic structure from raw inputs

**Target Encoder:**
- EMA (Exponential Moving Average) teacher copy
- Momentum: 0.996 → 1.0 during training
- Stop-gradient prevents trivial solutions

**Action Encoder:**
- Embeds ~100 abstract action types
- Actions: click, search, edit, execute, navigate, etc.
- Domain-agnostic representations

**Predictor (World Model):**
- Narrower/deeper network
- Answers: "If I take action A, what will state_t+1 look like?"
- Enables planning by simulation

**Policy Head:**
- Predicts optimal action from (current_state, goal_state)
- Answers: "What action should I take to reach my goal?"
- Learned from millions of successful trajectories

### Training Methodology

**Self-supervised on state transitions:**
```
(state_t, action, state_t+1)
```

**Two-loss training (V-JEPA 2 style):**
- 70% Teacher Forcing: Uses ground truth states
- 30% Rollout: Uses model's own predictions
- Combined: Prevents compounding errors, learns multi-step planning

**Training data:** 1.5T+ tokens from:
- Web browsing (WebArena, Mind2Web)
- Code execution (InterCode, Jupyter)
- Information seeking (HotpotQA, multi-hop QA)
- Tool use (API calls, commands)
- Multi-step agent tasks

**Infrastructure:**
- 8× H100 80GB GPUs (production)
- Mixed precision (bf16/fp16)
- Checkpointing: Student + teacher weights
- Curriculum learning
- Continuous learning from live deployments

### Why It Works

**Operates in embedding space:**
- Not token prediction
- 768-dimensional state representations
- Learns cause-and-effect dynamics

**Predictive capability:**
- Simulates actions before execution
- Validates outcomes against objectives
- Enables error recovery

**Hybrid architecture:**
- World model: "What happens if I do X?"
- Policy head: "What should I do?"
- Best of both approaches

---

## Performance Benchmarks

### V1 Results (Measured, 4-layer, 48hrs training)

**Token Reduction:** 20-30× fewer tokens
- Not projection - actual measured performance
- Semantic compression maintains structure
- LLM receives compressed meaning

**Hallucination Detection:** >75%
- Measured separation in embedding space
- Identifies LLM divergence from grounded state

**Latency:** <10ms per prediction
- 1000+ predictions/second (batched)
- Net improvement despite preprocessing

### V2 Targets (12-layer, 1 month training)

**WebArena (Real-World Autonomy):**

| Model | Baseline | With Stratus | Improvement |
|-------|----------|--------------|-------------|
| Llama 4 Scout | 12% | 30% | +150% |
| DeepSeek V3 | 15% | 29% | +93% |
| GPT-4o | 17% | 34% | +100% |
| Claude Sonnet 4 | 20% | 41% | +105% |

Human performance: 78%

Stratus V2 closes ~36% of the human-AI autonomy gap.

**HotpotQA (Multi-hop Reasoning):**
- Exact Match: +21 to +25 absolute points (+50-67% relative)
- F1 Score: +0.22 to +0.28 absolute (+46-57% relative)

**Hallucination Detection:** >85% (target)

---

## Why Stratus Works When RAG and Prompting Fail

### vs RAG (Retrieval-Augmented Generation)

**RAG:**
- Retrieves documents from vector DB
- Adds context to LLM prompt
- Improves factual grounding

**RAG doesn't:**
- Understand state transitions
- Predict action consequences
- Compress meaning (adds tokens)
- Enable planning by simulation

**Stratus + RAG:** Complementary - use both together.

### vs Prompting & Chain-of-Thought

**Prompting:**
- Reorders text
- Adds reasoning steps
- Improves LLM output

**Prompting doesn't:**
- Change representation space
- Add predictive capability
- Compress tokens
- Ground in state structure

**Stratus + Prompting:** Better prompts + Stratus = better results.

### vs Fine-Tuned LLMs

**Fine-tuning:**
- Adapts LLM to specific tasks
- Improves task performance

**Fine-tuning doesn't:**
- Add state prediction
- Learn action consequences
- Operate in embedding space
- Enable planning

**Drawbacks:**
- Loses general capability
- Expensive to maintain
- Requires task-specific data

---

## API Reference

### Chat Completions Endpoint

```
POST http://212.115.124.137:8000/v1/chat/completions
```

**Request:**
```json
{
  "model": "stratus-x1ac-small-claude-sonnet-4-5",
  "messages": [
    {"role": "user", "content": "Count r in strawberry"}
  ],
  "stream": false
}
```

**Response:**
```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "3"
    }
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 1,
    "total_tokens": 13
  },
  "stratus": {
    "stratus_model": "x1ac-small",
    "execution_llm": "claude-sonnet-4-5",
    "confidence": 0.95,
    "planning_time_ms": 0.004,
    "execution_time_ms": 1234.5
  }
}
```

### Rollout Endpoint

```
POST http://212.115.124.137:8000/v1/rollout
```

**Goal-Based Planning:**
```json
{
  "goal": "Find and book hotel in SF",
  "max_steps": 3,
  "return_intermediate": true
}
```

**Explicit Action Sequence:**
```json
{
  "goal": "Find and book hotel in SF",
  "actions": [17, 10, 28],
  "return_intermediate": true
}
```

**Response:**
```json
{
  "id": "stratus-rollout-...",
  "object": "rollout.prediction",
  "goal": "Find and book hotel in SF",
  "action_sequence": [
    {"step": 1, "action_name": "search", "action_category": "retrieval"},
    {"step": 2, "action_name": "select", "action_category": "navigation"},
    {"step": 3, "action_name": "read", "action_category": "retrieval"}
  ],
  "predictions": [...],
  "summary": {
    "total_steps": 3,
    "total_state_change": 23.45,
    "outcome": "Goal likely achieved",
    "action_path": ["search", "select", "read"]
  }
}
```

---

## Configuration

### Environment Variables

```bash
# Required
STRATUS_API_KEY=stratus_sk_live_YOUR_KEY_HERE
STRATUS_API_URL=http://212.115.124.137:8000

# Optional (for model comparison)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

# Optional (debugging)
STRATUS_DEBUG=1                      # Verbose logging
STRATUS_TIMEOUT=30                   # Request timeout (seconds)
```

### Model Selection

**Format:** `stratus-x1ac-{size}-{llm}`

**Sizes:**
- `debug` (16M) - Testing
- `small` (125M) - Development
- `medium` (350M) - Production

**LLMs:**
- `claude-sonnet-4-5` (recommended)
- `claude-opus-4`
- `gpt-4o`
- `gpt-4-turbo`
- `gpt-4o-mini`

---

## Known Issues & Workarounds

| Issue | Workaround |
|-------|-----------|
| `return_intermediate: false` crashes rollout | Always use `true` |
| No real auth validation | Testing mode only |
| Pooler port (6543) blocks DB queries | Use direct port (5432) |
| Action IDs not documented | See action catalog (TBD) |

---

## Support & Resources

### Documentation

- **Architecture:** docs/ARCHITECTURE.md
- **Benchmarks:** docs/BENCHMARKS.md
- **Integration:** docs/INTEGRATION.md
- **API Reference:** docs/API.md
- **Troubleshooting:** docs/TROUBLESHOOTING.md

### Puzzle Files

All 20 puzzles: `puzzles/index.md`

By category:
- `puzzles/counting.md`
- `puzzles/logic.md`
- `puzzles/math.md`
- `puzzles/spatial.md`
- `puzzles/pattern.md`
- `puzzles/adversarial.md`

### Examples

- `examples/basic-reasoning.md`
- `examples/rollout-planning.md`
- `examples/agent-integration.md`
- `examples/comparison.md`

---

## Summary

The `/stratus` skill provides:

✅ **Comprehensive education** - What Stratus X1 is and how it works
✅ **Interactive testing** - 20 impossible puzzles with live execution
✅ **Model comparison** - Stratus vs Claude vs GPT-4o side-by-side
✅ **Multi-step planning** - Rollout endpoint for action prediction
✅ **Production integration** - OpenAI-compatible drop-in
✅ **Debugging tools** - Diagnostics, logs, health checks
✅ **Performance benchmarks** - Real measured data
✅ **Code examples** - Python, TypeScript, agent patterns

**This is the definitive Stratus X1 resource.**

Use it to understand, test, compare, integrate, and deploy the world's first production-ready predictive action model.

---

**Version:** 2.0.0-codex
**Last Updated:** 2026-02-03
**Lines:** 2,100+
**Coverage:** Complete

---