Calling

call.call()

Run one LLM call asynchronously and return its text response.

Usage

Source

call.call(
    prompt,
    *,
    backend=None,
    specialty=None,
    model=DEFAULT_MODEL,
    agent=False,
    cwd=None,
    api_auth=False,
    timeout=180
)

Resolves a backend, maps the abstract model tier to the provider’s literal model id, and executes through run (transient retry included). The backend fully resolves the outcome; a provider error raises BackendCallError.

Parameters

prompt: str

The user prompt, delivered to the backend over stdin.

backend: LlmBackend | None = None

The LlmBackend to invoke; when None, auto-selects the first ready backend via the priority chain, optionally scoped by specialty.

specialty: TSpecialty | None = None

Specialty used to scope auto-selection when backend is None; ignored when backend is given.

model: TModel | str = DEFAULT_MODEL


Abstract model tier (small/medium/large), or a concrete provider model id passed through unchanged.

agent: bool = False

Whether the call may use tools / agent capabilities.

cwd: str | None = None

Working directory for the backend process; None inherits the caller’s.

api_auth: bool = False

Whether to inherit provider API-key environment variables.

timeout: int = 180

Seconds to wait before the backend process is killed.

Returns

str

The text response.

Raises

BackendCallError

When the backend returns a provider error.

call.call_sync()

Run one LLM call synchronously and return its text response.

Usage

Source

call.call_sync(
    prompt,
    *,
    backend=None,
    specialty=None,
    model=DEFAULT_MODEL,
    agent=False,
    cwd=None,
    api_auth=False,
    timeout=180
)

The synchronous companion to call: resolves a backend, maps the abstract model tier, executes through run_sync (transient retry included), and returns the text. A provider error raises BackendCallError.

Parameters

prompt: str

The user prompt, delivered to the backend over stdin.

backend: LlmBackend | None = None

The LlmBackend to invoke; when None, auto-selects the first ready backend via the priority chain, optionally scoped by specialty.

specialty: TSpecialty | None = None

Specialty used to scope auto-selection when backend is None; ignored when backend is given.

model: TModel | str = DEFAULT_MODEL


Abstract model tier (small/medium/large), or a concrete provider model id passed through unchanged.

agent: bool = False

Whether the call may use tools / agent capabilities.

cwd: str | None = None

Working directory for the backend process; None inherits the caller’s.

api_auth: bool = False

Whether to inherit provider API-key environment variables.

timeout: int = 180

Seconds to wait before the backend process is killed.

Returns

str

The text response.

Raises

BackendCallError

When the backend returns a provider error.

extract.extract()

Run one LLM call asynchronously and return a validated response_model.

Usage

Source

extract.extract(
    prompt,
    response_model,
    *,
    backend=None,
    specialty=None,
    model="small",
    agent=False,
    cwd=None,
    api_auth=False,
    timeout=180
)

Resolves a backend, maps the abstract model tier, and executes through run. The backend runs, reads, and validates; a provider error raises BackendCallError, and a pydantic.ValidationError from a non-conforming model propagates out of this call.

Parameters

prompt: str

The user prompt, delivered to the backend over stdin.

response_model: type[T]

The Pydantic model the structured output is validated against.

backend: LlmBackend | None = None

The LlmBackend to invoke; when None, auto-selects the first ready backend via the priority chain, optionally scoped by specialty.

specialty: TSpecialty | None = None

Specialty used to scope auto-selection when backend is None; ignored when backend is given.

model: TModel = "small"

Abstract model tier (small/medium/large), or a concrete provider model id passed through unchanged.

agent: bool = False

Whether the call may use tools / agent capabilities.

cwd: str | None = None

Working directory for the backend process; None inherits the caller’s.

api_auth: bool = False

Whether to inherit provider API-key environment variables.

timeout: int = 180

Seconds to wait before the backend process is killed.

Returns

T

The validated response_model instance.

Raises

BackendCallError

When the backend returns a provider error.

pydantic.ValidationError

When the model’s output fails validation.

extract.extract_sync()

Run one LLM call synchronously and return a validated response_model.

Usage

Source

extract.extract_sync(
    prompt,
    response_model,
    *,
    backend=None,
    specialty=None,
    model="small",
    agent=False,
    cwd=None,
    api_auth=False,
    timeout=180
)

The synchronous companion to extract: resolves a backend, maps the model tier, executes through run_sync, and returns the validated model. A provider error raises BackendCallError; a pydantic.ValidationError propagates.

Parameters

prompt: str

The user prompt, delivered to the backend over stdin.

response_model: type[T]

The Pydantic model the structured output is validated against.

backend: LlmBackend | None = None

The LlmBackend to invoke; when None, auto-selects the first ready backend via the priority chain, optionally scoped by specialty.

specialty: TSpecialty | None = None

Specialty used to scope auto-selection when backend is None; ignored when backend is given.

model: TModel = "small"

Abstract model tier (small/medium/large), or a concrete provider model id passed through unchanged.

agent: bool = False

Whether the call may use tools / agent capabilities.

cwd: str | None = None

Working directory for the backend process; None inherits the caller’s.

api_auth: bool = False

Whether to inherit provider API-key environment variables.

timeout: int = 180

Seconds to wait before the backend process is killed.

Returns

T

The validated response_model instance.

Raises

BackendCallError

When the backend returns a provider error.

pydantic.ValidationError

When the model’s output fails validation.

structured.extract_json_block()

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

Usage

Source

structured.extract_json_block(text)

Parameters

text: str

The model output to scan for a JSON object or array.

Returns

str

The extracted JSON value re-serialized as a string.

Raises

ValueError

When the core finds no JSON value in text.

structured.structured_value()

Return the JSON value to validate from a stream-json envelope.

Usage

Source

structured.structured_value(raw)

Parses raw as JSON; when a type=="result" event carries a structured_output field (claude/mlx stream-json), returns that field, otherwise returns the parsed value itself.

Parameters

raw: str

Raw stdout holding a JSON value or a list of stream-json events.

Returns

object

The structured_output payload when present, else the parsed JSON.