simonw / llm

Platform metadata describes the repository as a tool to "Access large language models from the command-line", with a homepage at https://llm.datasette.io. The codebase is almost entirely Python: the platform lists Python as the primary language, with about 1.23 million of the counted language bytes. The project is licensed Apache-2.0 and includes a root-level LICENSE file. Platform metadata records 12,489 stargazers (2026-09-12) and a latest release, 0.35, published 2026-09-07. Static analysis covered 116 files.

Running the package as a script starts at llm/__main__.py, which contains this execution guard:

if __name__ == "__main__":
    cli()

A bounded execution path connects that guard to the cli function in llm/cli.py, which the analyzer also flags as a likely executable entrypoint by filename heuristic. From there, static paths show llm/cli.py calling load_plugins in llm/plugins.py. Those plugin-loading paths terminate at unresolved boundaries such as pm.load_setuptools_entrypoints and hasattr, so what plugin discovery actually does is outside the static view. By static call degree, the analyzer labels llm/cli.py an entry/orchestration candidate, with 105 incoming and 245 outgoing calls.

The repository organizes into three top-level subsystems: docs, llm, and tests; the analyzer counts 35 files under docs, 20 under llm, and 44 under tests. Among analyzed modules, llm/__init__.py has the highest incoming call count — 754 incoming against 48 outgoing — which suggests it acts as the package's shared surface. llm/parts.py follows with 470 incoming calls, while llm/models.py (130 incoming) and llm/logs.py (123 incoming) are also core candidates. In total the analyzer recorded 9,698 static relations — 9,116 calls and 582 imports — of which 2,324 resolved to local targets and 7,374 stayed external or unresolved. One test module, tests/test_parts.py, shows 422 outgoing calls and none incoming, which the analyzer reads as an orchestration candidate.

The only dependency records captured come from docs/requirements.txt and describe documentation tooling: sphinx (pinned to 7.2.6), furo, sphinx-autobuild, sphinx-copybutton, sphinx-markdown-builder, myst-parser, and cogapp. Runtime dependencies are absent from these records because the analyzer does not parse pyproject.toml dependency tables. The repository does contain three build/dependency manifest files, so packaging information exists but was only partially read. On the test side, the analyzer counted 44 test files. Among the listed test modules, tests/test_logs_store.py has 58 incoming and 348 outgoing calls, tests/test_openai_messages.py has 27 incoming and 92 outgoing, and tests/test_openai_responses.py has 26 incoming and 93 outgoing. tests/test_logs_store.py defines test classes including TestCanonicalJson, TestMessageHash, TestSchema, TestChainRoundTrip, TestDedup, TestThreads, TestForking, and TestPendingToolCalls, while llm/logs.py defines the LogStore class.

Start with README.md, which the analyzer classed as a project-level important file, then continue in this order:

• pyproject.toml — one of the repository's three manifests — and the LICENSE file at the root.
• The entry chain: llm/__main__.py and llm/cli.py.
• llm/__init__.py, the most referenced module, and llm/plugins.py, whose load_plugins the entry chain reaches.
• llm/models.py and llm/parts.py, heavily referenced service/core modules, then llm/logs.py for the logging side.

This asset rests on static analysis only: reflection, runtime dependency injection, dynamic imports, monkey-patching, generated code, framework runtime wiring, and dynamic dispatch are not resolved. Coverage is partial: 7,374 of the 9,698 static relations remained external or unresolved. Plugin loading is a hard boundary — bounded paths from llm/cli.py into load_plugins end at unresolved calls such as pm.load_setuptools_entrypoints and LLM_LOAD_PLUGINS.split, so dynamically loaded plugin behavior is invisible here. Dependency data is incomplete: only requirements-style manifests were parsed, and pyproject.toml dependency tables were skipped. Install, run, and build flow inference is partial, and installation commands are unverified by this analysis. README-derived text is extracted line by line and may capture code instead of prose, so such text should be read as author-claimed.

• llm/__init__.py concentrates lookup helpers: get_plugins, get_models_with_aliases, get_tools, get_embedding_model, and get_model_aliases.
• llm/parts.py defines the message-part model: Part, TextPart, ReasoningPart, ToolCallPart, ToolResultPart, AttachmentPart, and Message, plus normalize_parts and the system and user helpers.
• llm/models.py defines model-facing types: Usage, Attachment, Tool, ServerSideTool, Toolbox, ToolCall, ToolResult, and ToolOutput.
• llm/logs.py centers on LogStore (lines 143-711) with canonical_json, content_hash, and message_hash helpers.
• llm/default_plugins/openai_models.py holds register_models, register_embedding_models, and register_commands, plus an OpenAIEmbeddingModel class.