How dylanhogg/llmgraph works
Project Type and Purpose
• llmgraph is a Python-based CLI tool and library that automates creation of knowledge graphs from Wikipedia seed pages by invoking large language models (LLMs).
• It ingests a seed entity type and Wikipedia URL, recursively queries an LLM (via LiteLLM/OpenAI), fetches Wikipedia metadata, deduplicates nodes, builds a graph in memory (NetworkX), and exports to GraphML, GEXF, and interactive HTML (pyvis).
High-Level Architecture Components
A. CLI Layer
• llmgraph/console.py – parses user flags and options (Click)
• Entrypoint “llmgraph” command
• Reads prompts.yaml and .env for configuration
B. Core Library
• llmgraph/library/engine.py – orchestrator: loop over levels, merge nodes, track tokens
• llmgraph/library/llm.py – adapter to LiteLLM/OpenAI, handles prompt templating, requests, and responses
• llmgraph/library/wikipedia.py – fetches and parses Wikipedia pages (requests/BeautifulSoup)
• llmgraph/library/classes.py – in-memory graph models (Node, Edge, Graph container)
• llmgraph/library/utils.py – helpers (formatting, JSON extraction, file I/O)
• llmgraph/library/prompts.py – loads and renders prompt templates from prompts.yaml
• llmgraph/library/env.py – environment variables and API key management
• llmgraph/library/log.py – structured logging of steps and token usage
• llmgraph/library/consts.py – shared constants (cache paths, default levels, formats)
C. Cache Layer
• .joblib_cache/ – caches LLM and Wikipedia API calls to avoid duplication
• llmgraph/library/env.py and engine.py integrate cache lookups
D. Graph Builder & Exporters
• Graph assembly in memory (NetworkX)
• Exporters:
– GraphML/GEXF via networkx.write_*
– HTML via pyvis (llmgraph/library/utils.py)
E. External Services
• LiteLLM/OpenAI endpoints – LLM model inference
• Wikipedia API or page HTML – seed and supplemental metadata
F. Packaging, Testing & CI
• pyproject.toml/requirements.txt – dependency declaration (Click, LiteLLM, networkx, pyvis)
• tests/ – unit tests for console, JSON extraction, networkx integration, prompts, Wikipedia fetches
• .github/workflows/python-poetry-app.yml – CI for linting, tests, packaging
• pre-commit hooks (.pre-commit-config.yaml)
Relationships and Data Flow
1. User invokes llmgraph <entity_type> <wikipedia_url> [--flags]
2. console.py parses input → instantiates Engine
3. Engine at level N:
a. Calls prompts.py to render LLM prompt template with entity_root, top_n, etc.
b. llm.py checks cache → if miss, calls LLM API → stores in cache
c. wikipedia.py checks cache → if miss, fetches Wikipedia content → stores in cache
d. classes.py/engine.py create Node and Edge objects, merge duplicates
4. Repeat for deeper levels until --levels reached
5. Engine hands final NetworkX graph to utils.py exporters
6. utils.py writes GraphML/GEXF to disk, spins up pyvis for HTML output
7. console.py prints summary (total tokens, output locations)
Architectural Patterns & Principles
• Separation of Concerns: CLI, orchestration, LLM abstraction, Wikipedia abstraction, graph model, export
• Caching Decorator/Repository pattern for LLM and Wikipedia calls
• Template Method pattern for prompts rendering
• Dependency Injection of LLM provider via llm-base-url and llm-model flags
• Modular exporters allow additional formats in future
Detail
• Caching layer’s role in performance and resumability.
• Modularity that allows swapping out LLM providers.
• Flow of “total tokens” metric from LLM Adapter back to Engine and CLI output.