backends

backends

LLM CLI backends for :func:HookContext.call_llm.

Each backend maps the framework's abstract :data:TModel sizes to provider model names and knows how to build the CLI invocation and parse its response.

LlmBackend

Bases: ABC

Abstract interface for an LLM CLI backend.

Concrete backends map abstract :data:TModel sizes to provider-specific model names and encapsulate how to invoke the provider's CLI and parse the raw response.

Attributes:

Name	Type	Description
models	dict[TModel, str]	Mapping from abstract model size to the provider's model name.

build_command abstractmethod

build_command(
    model: str, schema_path: str | None, agent: bool
) -> list[str]

Build the CLI argv for a single LLM invocation.

Parameters:

Name	Type	Description	Default
model	str	Provider-specific model name.	required
schema_path	str | None	Path to a JSON schema for structured output, or None.	required
agent	bool	Whether the invocation may use tools / agent capabilities.	required

Returns:

Type	Description
list[str]	The argv list to execute.

parse_response abstractmethod

parse_response(
    raw: str, response_model: type[BaseModel] | None
) -> str | BaseModel

Parse raw CLI stdout into text or a validated model.

Parameters:

Name	Type	Description	Default
raw	str	Raw stdout from the backend CLI.	required
response_model	type[BaseModel] | None	Model to validate against, or None for raw text.	required

Returns:

Type	Description
str | BaseModel	raw when response_model is None, else a validated instance.

env abstractmethod

env() -> dict[str, str]

Return extra environment variables to set for the CLI invocation.

CodexBackend

Bases: LlmBackend

:class:LlmBackend for the OpenAI codex CLI.

ClaudeBackend

Bases: LlmBackend

:class:LlmBackend for the Anthropic claude CLI.

extract_structured staticmethod

extract_structured(
    events: list[dict[str, Any]], model: type[BaseModel]
) -> BaseModel | None

Return the validated structured_output from a stream-json event list, if present.

LlmBackends

Registry mapping each :data:TSpecialty to the :class:LlmBackend that serves it.

for_specialty classmethod

for_specialty(specialty: TSpecialty) -> LlmBackend

Return the backend registered for specialty.