API Reference

Calling

One-shot LLM calls, text and structured.

call.call()

Run one LLM call asynchronously and return its text response.

call.call_sync()

Run one LLM call synchronously and return its text response.

extract.extract()

Run one LLM call asynchronously and return a validated response_model.

extract.extract_sync()

Run one LLM call synchronously and return a validated response_model.

structured.extract_json_block()

Extract the first complete JSON value from model text, tolerating ```json fences or surrounding prose.

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()

Execute a RunSpec asynchronously, retrying transient failures with backoff.

run.run_sync()

Execute a RunSpec synchronously, retrying transient failures with backoff.

RunSpec

A single configured run, translated per backend at execution time.

Response

A backend’s fully-resolved outcome: the spec, the raw output, and exactly one of result/error.

Result

A successful run: the extracted final text and the optional validated model.

Output

The full unparsed transport stream, present on success and failure alike.

Error

A failed run: a human-readable message plus the underlying exception.

DiscardedAttempt

A transient failure the retry loop threw away, summarized for spend accounting.

AppleConfig

Apple Foundation Models knobs applied only by the Apple backend.

ClaudeConfig

Claude CLI flag passthrough applied only by the Claude backend.

CodexConfig

Codex CLI knobs applied only by the Codex backend.

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

Abstract execution contract for an LLM backend.

CliBackend

Execution contract for the subprocess-backed LLM family.

ClaudeCliBackend

CliBackend for the Anthropic claude CLI.

ClaudeSdkBackend

Claude backend hosted through the optional claude-agent-sdk package.

CodexCliBackend

CliBackend for the OpenAI codex CLI.

GeminiCliBackend

CliBackend for Google’s gemini CLI.

AntigravityCliBackend

CliBackend for the Antigravity agy CLI, a Gemini-family successor.

AppleBackend

CliBackend for the spawnllm-apple on-device Foundation Models sidecar.

MlxBackend

In-process backend that runs a prompt through a local MlxEngine.

OpenAiEndpointBackend

LlmBackend that POSTs to an OpenAI-compatible /chat/completions endpoint.

LlmBackends

Registry mapping each specialty to the LlmBackend that serves it.

select_backend()

Return the first installed, authenticated backend in priority order.

BackendStatus

Result of LlmBackend.check_status: BackendReady, BackendNotInstalled, or BackendNotAuthenticated.

BackendReady

A backend whose CLI is installed and authenticated.

BackendNotInstalled

A backend whose CLI is not on PATH.

BackendNotAuthenticated

A backend whose CLI is installed but not authenticated.

BackendUnavailable

Raised when no backend is ready (installed and authenticated).

Transport

Subprocess plumbing shared by the CLI backends.

proc.run_cli()

Run a CLI command to completion and return its stdout.

proc.arun_cli()

Run a CLI command asynchronously and return its stdout.

proc.capture_cli()

Run a CLI command to completion and capture its full outcome.

proc.acapture_cli()

Run a CLI command asynchronously and capture its full outcome.

proc.collect_process()

Drain a subprocess’s stdout and stderr concurrently and wait for it to exit.

proc.map_concurrent()

Map an async function over items with bounded concurrency.

proc.RunResult

The raw outcome of a CLI invocation.

Types

Shared type aliases.

types.TModel

Abstract model tier; each backend maps it to a provider-specific model name.

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

Runs batched MLX inference on a dedicated worker thread.

mlx.AdapterCodec

Compresses and decompresses a homogeneous-dtype safetensors LoRA adapter.

mlx.AdapterFuser

Fuses a shipped LoRA adapter into a base MLX model.

mlx.MLXPatches

Idempotent runtime patches for mlx_lm.