simonw / llm · Architecture

The analyzer's summary describes a Python project of 116 analyzed files organized around three directory subsystems: docs, llm, and tests. The inventory counts 11 root files, 6 in .github, 35 in docs, 20 in llm, and 44 in tests, with 44 test-like files noted overall.

The llm package holds the paths the role records name as active code: cli.py, plugins.py, models.py, logs.py, migrations.py, utils.py, parts.py, and default_plugins/openai_models.py. At the root, README.md, pyproject.toml, and LICENSE are flagged as project-level important, while llm/__main__.py and llm/cli.py are flagged as likely entrypoints. The only parsed dependency records come from docs/requirements.txt (sphinx and related tooling), so docs carries the documentation build.

Two entrypoints were detected: llm/__main__.py, whose __main__ guard calls cli(), and llm/cli.py, flagged as likely executable by filename heuristic. The bounded path from llm/__main__.py is a single local step to llm/cli.py:cli, terminating as a leaf with no cycle and no truncation.

From llm/cli.py, one path ends immediately at warnings.simplefilter. Eight paths descend into llm/plugins.py [load_plugins] and stop at external or unresolved targets: hasattr, pm.load_setuptools_entrypoints, LLM_LOAD_PLUGINS.split, name.strip, metadata.distribution, entry_point.load, pm.register, and pm._plugin_distinfo.append. The reconstruction reports 13 bounded execution paths, 2 entrypoints, and 2059 resolved call relations; this packet includes ten of those paths. Read statically, llm/cli.py is the first module reached, and load_plugins is where eight of the nine traced paths from llm/cli.py leave the resolved call graph; the ninth ends at warnings.simplefilter without passing load_plugins.

These role labels are inferred by the analyzer from static resolved call degree and entrypoint membership; they describe call-graph position, not design intent. llm/__init__.py is the most connected module — 754 incoming, 48 outgoing — and llm/parts.py follows with 470 incoming, 22 outgoing; both are labeled service/core candidates. llm/cli.py carries the entry/orchestration label (105 in, 245 out), matching its entrypoint status. Among library modules, llm/models.py (130 in / 96 out), llm/logs.py (123 in / 64 out), llm/utils.py (102 in / 12 out), and llm/default_plugins/openai_models.py (89 in / 130 out) are labeled service/core candidates. llm/plugins.py sits at the edge — 41 in, 0 out, labeled leaf/data-boundary — with llm/migrations.py nearby (38 in, 1 out). The labels track call volume: tests/test_parts.py gets the orchestration label with 422 outgoing calls, and tests/test_logs_store.py is labeled service/core.

Plugin loading is the dominant boundary: from load_plugins, the traced paths reach pm.load_setuptools_entrypoints, entry_point.load, pm.register, and metadata.distribution, all external or unresolved; the analyzer's boundary list also names importlib.import_module, though no exec path terminates there. Plain-code stops appear too: llm/cli.py ends at warnings.simplefilter, and load_plugins touches hasattr, LLM_LOAD_PLUGINS.split, and name.strip; the boundary list additionally names sys.stderr.write without an exec record. The scale is large — 7,374 of 9,698 relations are external_or_unresolved against 2,324 local, and the analyzer keeps textual targets instead of inventing local destinations. In practice, anything behind plugin loading — installed entry points, hook registration — lies outside this reconstruction, because all eight traced paths into load_plugins end at an unresolved_boundary; dynamic imports are separately recorded by the analyzer as not resolved.

By static degree, llm/__init__.py is the package's aggregation point (754 incoming calls), and llm/cli.py is a heavy consumer (105 in, 245 out) drawing on that hub. llm/parts.py and llm/models.py carry much of the remaining local call mass, while llm/plugins.py is a leaf — 41 incoming, 0 outgoing. All seven parsed dependency records are labeled scope 'runtime' yet source from docs/requirements.txt (sphinx and documentation tooling), so they describe the docs build toolchain. Because pyproject.toml dependency tables were not parsed, the package's own runtime dependencies are not established by this analysis. Unresolved edges dominate the graph: 7,374 external_or_unresolved versus 2,324 local, and dynamic imports are explicitly not resolved.

This is a static picture: reflection, runtime dependency injection, dynamic imports, monkey-patching, generated code, framework runtime wiring, and dynamic dispatch are not resolved by the analyzer. How plugin loading, model resolution, and logging interact at runtime is not established by this packet. Install/run/build inference is partial and installation commands are not verified, so nothing here is a runnable recipe. Tests appear as 44 test-like files and as call-graph nodes, but the packet cannot show whether they pass or how the code behaves when executed. README-derived claims in this pipeline are line-based extracts that may capture code lines, so they stand as author statements at most.

Start with README.md and pyproject.toml for framing, then follow execution: llm/__main__.py, llm/cli.py:cli, and llm/plugins.py [load_plugins]. The analyzer's teaching record recommends the same shape — manifests and important symbols first, then the bounded path, then unresolved boundaries. For the core, read llm/__init__.py as the hub, then llm/parts.py and llm/models.py. Close with tests/test_parts.py, whose 422 outgoing calls make it the labeled orchestration candidate, before changing any code.