AI‑Powered Knowledge Graph Generator – Technical Briefing
Repository snapshot
Total files: 26 Primary language: Python (14 files) with supporting TOML, HTML, Markdown. Package manager: pip (also uv lock file present). Entry points: generate-graph.py (CLI wrapper) and src/knowledgegraph/main.py (core workflow). Core configuration: config.toml; build metadata in pyproject.toml and requirements.txt.
High‑level architecture
generate-graph.py ──► src/knowledgegraph/main.py │ ├─► src/knowledgegraph/llm.py # LLM API wrapper (OpenAI‑compatible) ├─► src/knowledgegraph/textutils.py # Chunking logic ├─► src/knowledgegraph/entitystandardization.py ├─► src/knowledgegraph/prompts/.py # Prompt templates ├─► src/knowledgegraph/visualization.py └─► src/knowledgegraph/templates/graphtemplate.html Chunking – textutils.py splits the input document per config.toml (chunksize, overlap). Extraction – llm.py sends each chunk to the configured LLM, using prompt files (entityprompts.py, inferenceprompts.py). Standardization – entitystandardization.py optionally normalizes entity strings via a secondary LLM call. Inference – main.py merges SPO triples, runs optional transitive inference (applytransitive). Visualization – visualization.py renders the final graph into knowledgegraph.html using graphtemplate.html.
Installation & execution
Clone & install
git clone https://github.com/robert-mcdermott/ai-knowledge-graph.git cd ai-knowledge-graph pip install -r requirements.txt # or: uv sync (uv.lock present)
Configure LLM access
Edit config.toml → [llm] section (model, apikey, baseurl)
Generate a graph
python generate-graph.py \ --input data/industrial-revolution.txt \ --output industrial-revolution-kg.html
The same command works with the uv runner (uv run generate-graph.py …). The --test flag produces a demo using the bundled data/industrial-revolution.txt.
Key code artifacts
| File | Role |
|---|---|
| generate-graph.py | CLI parser; forwards arguments to src/knowledgegraph/main.py. |
| src/knowledgegraph/config.py | Loads config.toml with tomllib; provides typed config objects. |
| src/knowledgegraph/llm.py | Thin wrapper around httpx for chat completions; respects maxtokens & temperature. |
| src/knowledgegraph/prompts/.py | Centralised prompt strings; easy to swap or extend. |
| src/knowledgegraph/visualization.py | Converts triplet list to JSON and injects into graphtemplate.html. |
| src/knowledgegraph/templates/graphtemplate.html | Stand‑alone HTML+JS (Vis.js) for interactive display. |
Observed gaps & risk assessment
Testing – Medium – No tests/ directory or pytest fixtures; core functions (textutils.chunk, entitystandardization.standardize) are exercised only via manual runs. CI/CD – Medium – No .github/workflows/ or other pipeline definitions; builds are not automatically validated. Dependency lock – Low – requirements.txt is present but no requirements.lock; reproducibility relies on the uv.lock which is not used by default pip. Error handling – Low – LLM calls in llm.py raise generic Exception on non‑200 responses; callers do not retry or fallback, which can cause abrupt termination on transient API errors. Input validation – Low – CLI accepts any --input path; main.py assumes UTF‑8 text and does not guard against binary files. Security – Low – API keys are stored in plain config.toml; no guidance for environment‑variable injection or secret management.
Documentation – README covers purpose, quick‑start, and CLI flags. The docs/index.html mirrors the demo visualization but adds no developer guide. Inline docstrings are sparse; function signatures are self‑explanatory but lack type hints in several modules (visualization.py).
Bottom line
The repository delivers a functional end‑to‑end pipeline for extracting and visualizing SPO triples from arbitrary text, with a clear separation of concerns (chunking, LLM interaction, standardization, inference, rendering). It is suitable for prototypes, research demos, or small‑team projects that can manage the missing test suite and manual CI. Teams requiring production‑grade reliability should add automated tests, a CI workflow, and stronger secret handling before integration.