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

# Use the SDK to read world state

> Experimental world.read vertical slice across API, CLI, SDK, agent metadata, and trace output.

This page documents the first experimental SDK/agent vertical slice:

```text theme={null}
world.read -> GET /api/agent/world?format=json -> sf world --json -> sf.world.get()
```

It is read-only. It does not place trades, create paper orders, mutate portfolio state, create theses, start daemons, or expand MCP.

## Status

`@spfunctions/sdk` is published as a stable package:

```bash theme={null}
npm install @spfunctions/sdk@1.0.1
```

Use the stable package version.

## API

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

The endpoint returns the current salience-ranked SimpleFunctions world state. The current schema is conservative because the endpoint still includes the SPEC-10 snapshot shape plus legacy aliases for older consumers.

Stable fields to expect when present:

* `asOf`
* `servedAt`
* `op`
* `region`
* `regime`
* `salient`
* `childRegions`
* `marketCount`

## CLI

```bash theme={null}
sf world --json
```

The CLI is the first-class surface. It calls the same world endpoint and requests JSON when `--json` is present.

## SDK

```ts theme={null}
import { SimpleFunctions } from "@spfunctions/sdk"

const sf = new SimpleFunctions({
  apiKey: process.env.SF_API_KEY,
  baseUrl: process.env.SF_API_URL,
})

const world = await sf.world.get()

console.log(world.asOf)
console.log(world.salient?.slice(0, 3))
```

`world.read` is read-only (`sideEffect: "none"`) but it is a hosted data call with `costEffect: "api_cost"` and `access.anonymousAllowed: false`. The SDK therefore requires `SF_API_KEY` for `sf.world.get()`. No-key SDK bootstrap is limited to strict manifest inspection such as `sf.manifest.get("world.read")`.

If `apiKey` is present, the SDK sends it as a bearer token. The SDK does not shell out to the CLI, call an LLM, retry hidden mutations, or perform side effects.

## Agent Tool

The agent metadata exposes the canonical tool as `world.read`. Tool hosts that reject dotted identifiers can use the compatibility name `world_read`.

```json theme={null}
{
  "name": "world.read",
  "compatName": "world_read",
  "permissions": ["read.public", "market_data", "read"],
  "sideEffect": "none",
  "costEffect": "api_cost",
  "access": { "anonymousAllowed": false },
  "authRequired": false,
  "schema": "WorldState",
  "sdk": "sf.world.get()",
  "http": "GET /api/agent/world?format=json",
  "cli": "sf world --json"
}
```

## Direct Agent Tool Events

The first accepted event stream supported only `world.read`. The current direct tool once-mode also supports additional read/research tools from the draft contract map.

```bash theme={null}
sf agent --tool world.read --stream-json
sf agent --tool markets.search --stream-json --input '{"query":"Fed CPI","limit":5}'
```

`--ndjson` is an alias for `--stream-json`.

Minimum emitted event types:

* `session.init`
* `tool.catalog.loaded`
* `run.started`
* `tool.call.started`
* `tool.call.completed` or `tool.call.failed`
* `agent.final`
* `run.completed`

## Trace

Use a local trace file when you need an audit receipt:

```bash theme={null}
sf agent --tool world.read --stream-json --record-trace trace.ndjson
sf trace receipt trace.ndjson --json
```

The trace entry stores the tool name, empty input, compact output summary, error if any, and duration. It must not store API keys, bearer tokens, venue credentials, or trading secrets.

## Contract Map

The draft contract map entry lives at:

```text theme={null}
contracts/sf-contract-map.draft.json
```

The draft now includes the read/research SDK and Agent contract slices plus deferred entries for surfaces that do not yet have safe canonical endpoints.