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

# World Model

> Use world snapshots, deltas, drill paths, op operations, and inspection dossiers as compact market context for agents.

The world model is the fastest way to give an agent current prediction-market context.

Start with a snapshot, use query for task-specific search, inspect the markets that matter, then poll deltas instead of reloading the whole world.

## Start here

```bash theme={null}
curl "https://simplefunctions.dev/api/agent/world?format=json"
curl "https://simplefunctions.dev/api/agent/world/delta?since=1h&format=json"
curl "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31"
```

CLI equivalents:

```bash theme={null}
sf world --json
sf world --delta --json --since 1h
sf inspect KXRATECUT-26DEC31 --json
```

## What to call

| Need                 | HTTP                                              | CLI                                  |
| -------------------- | ------------------------------------------------- | ------------------------------------ |
| Cold-start context   | `GET /api/agent/world?format=json`                | `sf world --json`                    |
| Topic drill          | `GET /api/agent/world/iran/hormuz?format=json`    | `sf world iran/hormuz --json`        |
| Recent changes       | `GET /api/agent/world/delta?since=1h&format=json` | `sf world --delta --json --since 1h` |
| One market dossier   | `GET /api/agent/inspect/{ticker}`                 | `sf inspect <ticker> --json`         |
| Task-specific search | `GET /api/public/query?q=Fed%20rate%20cut`        | `sf query "Fed rate cut" --json`     |

## Agent loop

```bash theme={null}
sf world --json
sf query "Fed rate cut" --json --limit 3
sf inspect KXRATECUT-26DEC31 --json
sf world --delta --json --since 1h
```

Use the snapshot for the agent's context window. Use query when the user asks about a specific event. Use inspect before acting on one ticker. Use delta for recurring jobs.

## Snapshot

```http theme={null}
GET /api/agent/world?format=json
```

The JSON snapshot includes:

| Field             | Use                                                |
| ----------------- | -------------------------------------------------- |
| `region`          | Current world path, such as root or `iran/hormuz`. |
| `regime`          | Market-wide label and signals.                     |
| `salient[]`       | Ranked items the agent should notice.              |
| `index`           | Back-compatible SimpleFunctions Index fields.      |
| `traditional[]`   | Traditional-market anchors when available.         |
| `movers[]`        | Back-compatible notable movers.                    |
| `opportunities[]` | Back-compatible opportunity-like signals.          |
| `marketCount`     | Count of salient items in the response.            |
| `servedAt`        | Response timestamp.                                |

Example:

```bash theme={null}
curl "https://simplefunctions.dev/api/agent/world?format=json&limit=10"
```

## Drill paths

Path segments narrow the world model.

```bash theme={null}
curl "https://simplefunctions.dev/api/agent/world/iran?format=json"
curl "https://simplefunctions.dev/api/agent/world/iran/hormuz?format=json"
```

CLI:

```bash theme={null}
sf world iran --json
sf world iran/hormuz --json
```

Use drill paths when an agent already knows the topic and needs a smaller context object.

## Operations

`op` changes the view while keeping the response shaped as a world snapshot.

| Operation       | HTTP                                                      | CLI                                          |
| --------------- | --------------------------------------------------------- | -------------------------------------------- |
| Snapshot        | `/api/agent/world?op=snapshot&format=json`                | `sf world --op snapshot --json`              |
| Catalyst window | `/api/agent/world/iran?op=catalyst&window=7d&format=json` | `sf world iran --op catalyst --json`         |
| Dispersion      | `/api/agent/world/iran?op=dispersion&format=json`         | `sf world iran --op dispersion --json`       |
| History         | `/api/agent/world/iran?op=history&dt=24h&format=json`     | `sf world iran --op history --dt 24h --json` |
| Trail           | `/api/agent/world?op=trail&from=KXHORMUZ&format=json`     | `sf world --op trail --from KXHORMUZ --json` |
| Explain item    | `/api/agent/world?op=explain&item=s-7&format=json`        | `sf world --op explain --item s-7 --json`    |

Useful parameters:

| Parameter               | Use                                                                            |
| ----------------------- | ------------------------------------------------------------------------------ |
| `format=json`           | Machine-readable JSON. Defaults to markdown if omitted.                        |
| `since=12h`             | Override baseline where supported. Accepts relative duration or ISO timestamp. |
| `dt=24h` or `window=7d` | Window for history/catalyst views.                                             |
| `depth=0..3`            | Drill expansion depth.                                                         |
| `limit=1..30`           | Number of salient items.                                                       |
| `focus=energy`          | Legacy alias for a first drill path.                                           |

## Delta

```http theme={null}
GET /api/agent/world/delta?since=1h&format=json
```

```json theme={null}
{
  "from": "2026-04-30T08:00:00.000Z",
  "to": "2026-04-30T08:15:00.000Z",
  "changes": [
    "- SimpleFunctions Index: Disagreement 49->52",
    "- NEW opportunity [contagion_gap]: ..."
  ],
  "markdown": "# World Delta — 08:00->08:15 UTC\n- ...",
  "latencyMs": 32
}
```

If `changes` is empty, keep the previous snapshot and continue the loop.

## Inspect

```http theme={null}
GET /api/agent/inspect/{ticker}
```

```bash theme={null}
curl "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31"
```

Inspect returns the detailed object an agent needs before it acts on a market:

| Field                                         | Use                                                                             |
| --------------------------------------------- | ------------------------------------------------------------------------------- |
| `ticker`, `venue`, `title`, `price`, `status` | Market identity and current state.                                              |
| `suggestion`                                  | Action suggestion, confidence, reasoning, positives, warnings, size hint.       |
| `regime`                                      | Market regime score and signals.                                                |
| `indicators`                                  | IY, CRI, EE, LAS, overround, and related computed fields when available.        |
| `edges[]`                                     | Thesis-derived edges linked to the ticker.                                      |
| `contagion[]`                                 | Connected markets to inspect next.                                              |
| `trend7d[]`                                   | Recent price trend when available.                                              |
| `legislation`                                 | Linked government context when available.                                       |
| `nextActions`                                 | URLs for execution intents, monitoring, deeper inspection, or query follow-ups. |

Options:

```bash theme={null}
curl "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31?format=markdown"
curl "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31?contagion=false&trend=false"
curl "https://simplefunctions.dev/api/agent/inspect/KXRATECUT-26DEC31?nextActions=off"
```

## Feed

```http theme={null}
GET /api/agent/world/feed
```

The feed is Atom XML for subscribers that want the latest world snapshots without polling JSON directly.

```bash theme={null}
curl "https://simplefunctions.dev/api/agent/world/feed"
```

Use it for RSS readers, automation tools, crawlers, and agent frameworks that ingest feeds.

## Recommended reading path

<CardGroup cols={2}>
  <Card title="World State API" href="/api-reference/world-state">
    Endpoint parameters and response shapes.
  </Card>

  <Card title="Query API" href="/api-reference/query">
    Natural-language event search.
  </Card>

  <Card title="Market Detail API" href="/api-reference/market-detail">
    Public market detail endpoint.
  </Card>

  <Card title="Agentic CLI" href="/cli/agentic-cli">
    Local command equivalents for agents.
  </Card>
</CardGroup>