SimpleFunctions Developer Manual

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

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:

npm install @spfunctions/sdk@1.0.1

Use the stable package version.

API

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

sf world --json

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

SDK

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.

{
  "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.

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:

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:

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.

Choose a package

SDK quickstarts

Agent contracts

Use the SDK to read world state

Status

API

CLI

SDK

Agent Tool

Direct Agent Tool Events

Trace

Contract Map

​Status

​API

​CLI

​SDK

​Agent Tool

​Direct Agent Tool Events

​Trace

​Contract Map

Status

API

CLI

SDK

Agent Tool

Direct Agent Tool Events

Trace

Contract Map