# simonw/llm architecture

> Architecture diagram of the GitHub repository simonw/llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/simonw/llm
- Repository: https://github.com/simonw/llm

## Overview

LLM is a command-line tool and Python library for running prompts and chats against hosted or local language models. The main workflow starts at the CLI, which resolves a model through the plugin-backed registry, sends a structured prompt to a provider adapter, and presents the response; tool execution and response logging are additional stages. Separate capabilities cover embeddings, templates, schemas, and prompt fragments. The graph preserves major modules named in the source index; unsampled feature wiring is shown only where the README documents it.

Main entry points: [`llm/cli.py`](https://github.com/simonw/llm/blob/main/llm/cli.py) (CLI commands), [`llm/models.py`](https://github.com/simonw/llm/blob/main/llm/models.py) (Prompt and chat), [`llm/default_plugins/openai_models.py`](https://github.com/simonw/llm/blob/main/llm/default_plugins/openai_models.py) (OpenAI adapter), [`llm/plugins.py`](https://github.com/simonw/llm/blob/main/llm/plugins.py) (Plugin loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interface"]
  node_cli["CLI commands<br/>[cli.py]"]
end

subgraph group_runtime["Model runtime"]
  node_model_registry["Model registry<br/>[__init__.py]"]
  node_model_runtime["Prompt and chat<br/>[models.py]"]
  node_parts["Messages and parts<br/>[parts.py]"]
  node_openai["OpenAI adapter<br/>[openai_models.py]"]
  node_serialization["Wire serialization<br/>[serialization.py]"]
end

subgraph group_extensions["Plugins and tools"]
  node_plugin_loader["Plugin loader<br/>[plugins.py]"]
  node_hooks["Plugin hooks<br/>[hookspecs.py]"]
  node_tools["Tool execution<br/>[tools.py]"]
  node_default_tools["Built-in tools<br/>[default_tools.py]"]
end

subgraph group_persistence["Persistence"]
  node_log_store["Conversation logs<br/>[logs.py]"]
  node_log_migrations["Log migrations<br/>[migrations.py]"]
  node_embedding_api["Embedding collections<br/>[embeddings.py]"]
  node_embedding_migrations["Embedding migrations"]
  node_sqlite[("SQLite database")]
end

subgraph group_content["Content features"]
  node_templates["Prompt templates<br/>[templates.py]"]
  node_schemas["Schema and fragments<br/>[utils.py]"]
end

node_user(("CLI user"))
node_model_service(("Model provider"))

node_user -->|"runs commands"| node_cli
node_cli -->|"resolves models"| node_model_registry
node_model_registry -->|"loads plugins"| node_plugin_loader
node_plugin_loader -->|"registers hooks"| node_hooks
node_plugin_loader -->|"registers adapter"| node_openai
node_plugin_loader -->|"registers tools"| node_default_tools
node_cli -->|"runs prompts"| node_model_runtime
node_model_runtime -->|"uses messages"| node_parts
node_openai -->|"implements models"| node_model_runtime
node_openai -->|"handles parts"| node_parts
node_model_runtime -->|"uses wire types"| node_serialization
node_model_runtime -->|"executes calls"| node_tools
node_default_tools -->|"uses tool API"| node_tools
node_openai -->|"sends requests"| node_model_service
node_cli -->|"reads and logs"| node_log_store
node_log_store -->|"stores messages"| node_parts
node_log_store -->|"reads and writes"| node_sqlite
node_cli -->|"runs migrations"| node_log_migrations
node_log_migrations -->|"updates schema"| node_sqlite
node_cli -->|"manages embeddings"| node_embedding_api
node_embedding_api -->|"uses migrations"| node_embedding_migrations
node_embedding_api -->|"stores vectors"| node_sqlite
node_cli -->|"uses templates"| node_templates
node_cli -->|"extracts structured data"| node_schemas
node_cli -->|"uses fragments"| node_schemas

click node_cli "https://github.com/simonw/llm/blob/main/llm/cli.py"
click node_model_registry "https://github.com/simonw/llm/blob/main/llm/__init__.py"
click node_model_runtime "https://github.com/simonw/llm/blob/main/llm/models.py"
click node_parts "https://github.com/simonw/llm/blob/main/llm/parts.py"
click node_openai "https://github.com/simonw/llm/blob/main/llm/default_plugins/openai_models.py"
click node_serialization "https://github.com/simonw/llm/blob/main/llm/serialization.py"
click node_plugin_loader "https://github.com/simonw/llm/blob/main/llm/plugins.py"
click node_hooks "https://github.com/simonw/llm/blob/main/llm/hookspecs.py"
click node_tools "https://github.com/simonw/llm/blob/main/llm/tools.py"
click node_default_tools "https://github.com/simonw/llm/blob/main/llm/default_plugins/default_tools.py"
click node_log_store "https://github.com/simonw/llm/blob/main/llm/logs.py"
click node_log_migrations "https://github.com/simonw/llm/blob/main/llm/migrations.py"
click node_embedding_api "https://github.com/simonw/llm/blob/main/llm/embeddings.py"
click node_embedding_migrations "https://github.com/simonw/llm/blob/main/llm/embeddings_migrations.py"
click node_templates "https://github.com/simonw/llm/blob/main/llm/templates.py"
click node_schemas "https://github.com/simonw/llm/blob/main/llm/utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_user toneBlue
class node_model_registry,node_model_runtime,node_parts,node_openai,node_serialization toneAmber
class node_plugin_loader,node_hooks,node_tools,node_default_tools toneMint
class node_log_store,node_log_migrations,node_embedding_api,node_embedding_migrations,node_sqlite toneRose
class node_templates,node_schemas,node_model_service toneIndigo
```

## Components

### User interface

- [CLI commands](https://github.com/simonw/llm/blob/main/llm/cli.py): `llm/cli.py`

### Model runtime

- [Model registry](https://github.com/simonw/llm/blob/main/llm/__init__.py): `llm/__init__.py`
- [Prompt and chat](https://github.com/simonw/llm/blob/main/llm/models.py): `llm/models.py`
- [Messages and parts](https://github.com/simonw/llm/blob/main/llm/parts.py): `llm/parts.py`
- [OpenAI adapter](https://github.com/simonw/llm/blob/main/llm/default_plugins/openai_models.py): `llm/default_plugins/openai_models.py`
- [Wire serialization](https://github.com/simonw/llm/blob/main/llm/serialization.py): `llm/serialization.py`

### Plugins and tools

- [Plugin loader](https://github.com/simonw/llm/blob/main/llm/plugins.py): `llm/plugins.py`
- [Plugin hooks](https://github.com/simonw/llm/blob/main/llm/hookspecs.py): `llm/hookspecs.py`
- [Tool execution](https://github.com/simonw/llm/blob/main/llm/tools.py): `llm/tools.py`
- [Built-in tools](https://github.com/simonw/llm/blob/main/llm/default_plugins/default_tools.py): `llm/default_plugins/default_tools.py`

### Persistence

- [Conversation logs](https://github.com/simonw/llm/blob/main/llm/logs.py): `llm/logs.py`
- [Log migrations](https://github.com/simonw/llm/blob/main/llm/migrations.py): `llm/migrations.py`
- [Embedding collections](https://github.com/simonw/llm/blob/main/llm/embeddings.py): `llm/embeddings.py`
- [Embedding migrations](https://github.com/simonw/llm/blob/main/llm/embeddings_migrations.py): `llm/embeddings_migrations.py`
- **SQLite database**

### Content features

- [Prompt templates](https://github.com/simonw/llm/blob/main/llm/templates.py): `llm/templates.py`
- [Schema and fragments](https://github.com/simonw/llm/blob/main/llm/utils.py): `llm/utils.py`

### Other components

- **CLI user**
- **Model provider**

## Connections

- CLI user → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Model registry: resolves models (evidence: `llm/cli.py`)
- Model registry → Plugin loader: loads plugins (evidence: `llm/__init__.py`)
- Plugin loader → Plugin hooks: registers hooks (evidence: `llm/plugins.py`)
- Plugin loader → OpenAI adapter: registers adapter (evidence: `llm/plugins.py`)
- Plugin loader → Built-in tools: registers tools (evidence: `llm/plugins.py`)
- CLI commands → Prompt and chat: runs prompts (evidence: `llm/cli.py`)
- Prompt and chat → Messages and parts: uses messages (evidence: `llm/models.py`)
- OpenAI adapter → Prompt and chat: implements models (evidence: `llm/default_plugins/openai_models.py`)
- OpenAI adapter → Messages and parts: handles parts (evidence: `llm/default_plugins/openai_models.py`)
- Prompt and chat → Wire serialization: uses wire types (evidence: `llm/models.py`)
- Prompt and chat → Tool execution: executes calls (evidence: `llm/models.py`)
- Built-in tools → Tool execution: uses tool API (evidence: `llm/default_plugins/default_tools.py`)
- OpenAI adapter → Model provider: sends requests (evidence: `README.md`)
- CLI commands → Conversation logs: reads and logs (evidence: `llm/cli.py`)
- Conversation logs → Messages and parts: stores messages (evidence: `llm/logs.py`)
- Conversation logs → SQLite database: reads and writes (evidence: `llm/logs.py`)
- CLI commands → Log migrations: runs migrations (evidence: `llm/cli.py`)
- Log migrations → SQLite database: updates schema (evidence: `llm/migrations.py`)
- CLI commands → Embedding collections: manages embeddings (evidence: `README.md`)
- Embedding collections → Embedding migrations: uses migrations (evidence: `llm/embeddings.py`)
- Embedding collections → SQLite database: stores vectors (evidence: `llm/embeddings.py`)
- CLI commands → Prompt templates: uses templates (evidence: `README.md`)
- CLI commands → Schema and fragments: extracts structured data (evidence: `README.md`)
- CLI commands → Schema and fragments: uses fragments (evidence: `README.md`)
