# API Reference


## Calling


One-shot LLM calls, text and structured.


[call.call()](calling.md#spawnllm.call.call)  
Run one LLM call asynchronously and return its text response.

[call.call_sync()](calling.md#spawnllm.call.call_sync)  
Run one LLM call synchronously and return its text response.

[extract.extract()](calling.md#spawnllm.extract.extract)  
Run one LLM call asynchronously and return a validated `response_model`.

[extract.extract_sync()](calling.md#spawnllm.extract.extract_sync)  
Run one LLM call synchronously and return a validated `response_model`.

[structured.extract_json_block()](calling.md#spawnllm.structured.extract_json_block)  
Extract the first complete JSON value from model text, tolerating \`\`\`json fences or surrounding prose.

[structured.structured_value()](calling.md#spawnllm.structured.structured_value)  
Return the JSON value to validate from a stream-json envelope.


## Running


Spec-driven execution with envelope-aware retry, async and sync.


[run.run()](running.md#spawnllm.run.run)  
Execute a `RunSpec` asynchronously, retrying transient failures with backoff.

[run.run_sync()](running.md#spawnllm.run.run_sync)  
Execute a `RunSpec` synchronously, retrying transient failures with backoff.

[RunSpec](running.md#spawnllm.RunSpec)  
A single configured run, translated per backend at execution time.

[Response](running.md#spawnllm.Response)  
A backend's fully-resolved outcome: the spec, the raw output, and exactly one of result/error.

[Result](running.md#spawnllm.Result)  
A successful run: the extracted final text and the optional validated model.

[Output](running.md#spawnllm.Output)  
The full unparsed transport stream, present on success and failure alike.

[Error](running.md#spawnllm.Error)  
A failed run: a human-readable message plus the underlying exception.

[DiscardedAttempt](running.md#spawnllm.DiscardedAttempt)  
A transient failure the retry loop threw away, summarized for spend accounting.

[AppleConfig](running.md#spawnllm.AppleConfig)  
Apple Foundation Models knobs applied only by the Apple backend.

[ClaudeConfig](running.md#spawnllm.ClaudeConfig)  
Claude CLI flag passthrough applied only by the Claude backend.

[CodexConfig](running.md#spawnllm.CodexConfig)  
Codex CLI knobs applied only by the Codex backend.

[GeminiConfig](running.md#spawnllm.GeminiConfig)  
Gemini CLI knobs applied only by the Gemini and Antigravity backends.


## Backends


CLI backends (Claude, Codex, and the Gemini family), the in-process Claude Agent SDK backend, the Apple Foundation Models backend over its bundled Swift sidecar, the MLX and OpenAI-endpoint backends, the specialty registry, backend selection, and install/auth status checks.


[LlmBackend](backends.md#spawnllm.LlmBackend)  
Abstract execution contract for an LLM backend.

[CliBackend](backends.md#spawnllm.CliBackend)  
Execution contract for the subprocess-backed LLM family.

[ClaudeCliBackend](backends.md#spawnllm.ClaudeCliBackend)  
`CliBackend` for the Anthropic `claude` CLI.

[ClaudeSdkBackend](backends.md#spawnllm.ClaudeSdkBackend)  
Claude backend hosted through the optional `claude-agent-sdk` package.

[CodexCliBackend](backends.md#spawnllm.CodexCliBackend)  
`CliBackend` for the OpenAI `codex` CLI.

[GeminiCliBackend](backends.md#spawnllm.GeminiCliBackend)  
`CliBackend` for Google's `gemini` CLI.

[AntigravityCliBackend](backends.md#spawnllm.AntigravityCliBackend)  
`CliBackend` for the Antigravity `agy` CLI, a Gemini-family successor.

[AppleBackend](backends.md#spawnllm.AppleBackend)  
`CliBackend` for the `spawnllm-apple` on-device Foundation Models sidecar.

[MlxBackend](backends.md#spawnllm.MlxBackend)  
In-process backend that runs a prompt through a local `MlxEngine`.

[OpenAiEndpointBackend](backends.md#spawnllm.OpenAiEndpointBackend)  
`LlmBackend` that POSTs to an OpenAI-compatible `/chat/completions` endpoint.

[LlmBackends](backends.md#spawnllm.LlmBackends)  
Registry mapping each specialty to the `LlmBackend` that serves it.

[select_backend()](backends.md#spawnllm.select_backend)  
Return the first installed, authenticated backend in priority order.

[BackendStatus](backends.md#spawnllm.BackendStatus)  
Result of `LlmBackend.check_status`: `BackendReady`, `BackendNotInstalled`, or `BackendNotAuthenticated`.

[BackendReady](backends.md#spawnllm.BackendReady)  
A backend whose CLI is installed and authenticated.

[BackendNotInstalled](backends.md#spawnllm.BackendNotInstalled)  
A backend whose CLI is not on PATH.

[BackendNotAuthenticated](backends.md#spawnllm.BackendNotAuthenticated)  
A backend whose CLI is installed but not authenticated.

[BackendUnavailable](backends.md#spawnllm.BackendUnavailable)  
Raised when no backend is ready (installed and authenticated).


## Transport


Subprocess plumbing shared by the CLI backends.


[proc.run_cli()](transport.md#spawnllm.proc.run_cli)  
Run a CLI command to completion and return its stdout.

[proc.arun_cli()](transport.md#spawnllm.proc.arun_cli)  
Run a CLI command asynchronously and return its stdout.

[proc.capture_cli()](transport.md#spawnllm.proc.capture_cli)  
Run a CLI command to completion and capture its full outcome.

[proc.acapture_cli()](transport.md#spawnllm.proc.acapture_cli)  
Run a CLI command asynchronously and capture its full outcome.

[proc.collect_process()](transport.md#spawnllm.proc.collect_process)  
Drain a subprocess's stdout and stderr concurrently and wait for it to exit.

[proc.map_concurrent()](transport.md#spawnllm.proc.map_concurrent)  
Map an async function over items with bounded concurrency.

[proc.RunResult](transport.md#spawnllm.proc.RunResult)  
The raw outcome of a CLI invocation.


## Types


Shared type aliases.


[types.TModel](types.md#spawnllm.types.TModel)  
Abstract model tier; each backend maps it to a provider-specific model name.

[types.TSpecialty](types.md#spawnllm.types.TSpecialty)  
Task specialty; `LlmBackends.for_specialty` maps each to its registered backend.


## MLX


Local Apple-Silicon engine, adapter codec, fuser, and runtime patches.


[mlx.MlxEngine](mlx.md#spawnllm.mlx.MlxEngine)  
Runs batched MLX inference on a dedicated worker thread.

[mlx.AdapterCodec](mlx.md#spawnllm.mlx.AdapterCodec)  
Compresses and decompresses a homogeneous-dtype safetensors LoRA adapter.

[mlx.AdapterFuser](mlx.md#spawnllm.mlx.AdapterFuser)  
Fuses a shipped LoRA adapter into a base MLX model.

[mlx.MLXPatches](mlx.md#spawnllm.mlx.MLXPatches)  
Idempotent runtime patches for `mlx_lm`.