---
name: spawnllm
description: >
  Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools. Use when writing Python code that uses the spawnllm package.
license: MIT
compatibility: Requires Python >=3.13.
---

# spawnllm

Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.

## Installation

```bash
pip install spawnllm
```

## API overview

### Calling

One-shot LLM calls and structured output.

- `call.call`
- `schema_for`: Serialize a Pydantic model's JSON schema, with `additionalProperties` set to false
- `resolve_schema_path`: Resolve a JSON schema into the argument form the backend's CLI expects
- `extract_structured`: Return the validated `structured_output` from a stream-json event list, if present
- `parse_structured_output`: Parse raw CLI stdout into text or a validated model
- `parse_result_envelope`: Parse a `{is_error, result}` JSON envelope into its result text

### Backends

CLI backends, the specialty registry, and Claude status checks.

- `LlmBackend`: Abstract interface for an LLM CLI backend
- `ClaudeCliBackend`: `LlmBackend` for the Anthropic `claude` CLI
- `CodexCliBackend`: `LlmBackend` for the OpenAI `codex` CLI
- `LlmBackends`: Registry mapping each specialty to the `LlmBackend` that serves it
- `check_status`: Check whether the `claude` CLI is installed and authenticated
- `ClaudeStatus`: Represent a union type
- `ClaudeReady`: The `claude` CLI is installed and authenticated
- `ClaudeNotInstalled`: The `claude` CLI is not on PATH
- `ClaudeNotAuthenticated`: The `claude` CLI is installed but not authenticated

### ClaudeCliBackend Methods

Methods for the ClaudeCliBackend class

- `ClaudeCliBackend.cc_sentiment`
- `ClaudeCliBackend.build_command`
- `ClaudeCliBackend.parse_response`
- `ClaudeCliBackend.env`
- `ClaudeCliBackend.build_argv`
- `ClaudeCliBackend.parse_result_envelope`

### Transport

Subprocess plumbing shared by the CLI backends.

- `run_cli`: Run a CLI command to completion and return its stdout
- `arun_cli`: Run a CLI command asynchronously and return its stdout
- `collect_process`: Drain a subprocess's stdout and stderr concurrently and wait for it to exit
- `map_concurrent`: Map an async function over items with bounded concurrency

### Types

Shared type aliases.

- `types.TModel`
- `types.TSpecialty`

### MLX

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

- `mlx.MlxEngine`
- `mlx.AdapterCodec`
- `mlx.AdapterFuser`
- `mlx.MLXPatches`

## Resources

- [Full documentation](https://yasyf.github.io/spawnllm/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/yasyf/spawnllm)