## Calling


## call.call()


Run one LLM call asynchronously and return its text response.


Usage

``` python
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](running.md#spawnllm.run.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: `<a href="backends.html#spawnllm.LlmBackend" class="gdls-link gdls-code"><code>LlmBackend</code></a>` | None = None`  
The [LlmBackend](backends.md#spawnllm.LlmBackend) to invoke; when `None`, auto-selects the first ready backend via the priority chain, optionally scoped by `specialty`.

`specialty: `<a href="types.html#spawnllm.types.TSpecialty" class="gdls-link gdls-code"><code>TSpecialty</code></a>` | None = None`  
Specialty used to scope auto-selection when `backend` is `None`; ignored when `backend` is given.

`model: `<a href="types.html#spawnllm.types.TModel" class="gdls-link gdls-code"><code>TModel</code></a>` | 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

``` python
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](calling.md#spawnllm.call.call): resolves a backend, maps the abstract model tier, executes through [run_sync](running.md#spawnllm.run.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: `<a href="backends.html#spawnllm.LlmBackend" class="gdls-link gdls-code"><code>LlmBackend</code></a>` | None = None`  
The [LlmBackend](backends.md#spawnllm.LlmBackend) to invoke; when `None`, auto-selects the first ready backend via the priority chain, optionally scoped by `specialty`.

`specialty: `<a href="types.html#spawnllm.types.TSpecialty" class="gdls-link gdls-code"><code>TSpecialty</code></a>` | None = None`  
Specialty used to scope auto-selection when `backend` is `None`; ignored when `backend` is given.

`model: `<a href="types.html#spawnllm.types.TModel" class="gdls-link gdls-code"><code>TModel</code></a>` | 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

``` python
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](running.md#spawnllm.run.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: `<a href="backends.html#spawnllm.LlmBackend" class="gdls-link gdls-code"><code>LlmBackend</code></a>` | None = None`  
The [LlmBackend](backends.md#spawnllm.LlmBackend) to invoke; when `None`, auto-selects the first ready backend via the priority chain, optionally scoped by `specialty`.

`specialty: `<a href="types.html#spawnllm.types.TSpecialty" class="gdls-link gdls-code"><code>TSpecialty</code></a>` | None = None`  
Specialty used to scope auto-selection when `backend` is `None`; ignored when `backend` is given.

`model: `<a href="types.html#spawnllm.types.TModel" class="gdls-link gdls-code"><code>TModel</code></a>` = ``"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

``` python
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](calling.md#spawnllm.extract.extract): resolves a backend, maps the model tier, executes through [run_sync](running.md#spawnllm.run.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: `<a href="backends.html#spawnllm.LlmBackend" class="gdls-link gdls-code"><code>LlmBackend</code></a>` | None = None`  
The [LlmBackend](backends.md#spawnllm.LlmBackend) to invoke; when `None`, auto-selects the first ready backend via the priority chain, optionally scoped by `specialty`.

`specialty: `<a href="types.html#spawnllm.types.TSpecialty" class="gdls-link gdls-code"><code>TSpecialty</code></a>` | None = None`  
Specialty used to scope auto-selection when `backend` is `None`; ignored when `backend` is given.

`model: `<a href="types.html#spawnllm.types.TModel" class="gdls-link gdls-code"><code>TModel</code></a>` = ``"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

``` python
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

``` python
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.