Problem Processing long, unstructured documents to extract structured knowledge is tedious and error‑prone. Manual curation of subject‑predicate‑object (SPO) triples does not scale, and visualizing the resulting graph requires ad‑hoc scripts.

What This Does ai-knowledge-graph turns a plain‑text file into an interactive knowledge graph. It chunks the input (src/knowledge_graph/text_utils.chunk_text), sends each chunk to a configurable LLM, resolves and standardizes entities (src/knowledge_graph/entity_standardization.standardize_entities), infers additional relationships (src/knowledge_graph/entity_standardization.infer_relationships), and finally renders an HTML graph (src/knowledge_graph/visualization.visualize_knowledge_graph). The LLM endpoint is supplied via config.toml; any OpenAI‑compatible service (Ollama, Azure, Anthropic, etc.) works.

How It Is Wired

  1. Entry point – generate-graph.py (root) parses CLI options and loads config.toml.
  2. It imports src/knowledge_graph/main.main and calls it with the input path.
  3. main (line 200) orchestrates the pipeline: - process_text_in_chunks (line 90) reads the file, splits it (chunk_text), and iterates over chunks. - For each chunk process_with_llm (line 19) builds a prompt (src/knowledge_graph/prompts.get_prompt) and calls call_llm in src/knowledge_graph/llm.py. - call_llm performs a single requests.post network request – the only outbound call in the repo. - The JSON response is parsed by extract_json_from_text. - Collected SPO triples feed standardize_entities (entity_standardization) which normalizes text, limits predicate length (limit_predicate_length), and may invoke additional LLM calls (_resolve_entities_with_llm). - infer_relationships expands the graph using community detection (_identify_communities) and several inference helpers (_infer_relationships_with_llm, _apply_transitive_inference, etc.). - The final triple set is handed to visualize_knowledge_graph, which loads src/knowledge_graph/templates/graph_template.html and writes the output HTML (json_to_html.py assists with a minimal conversion).

The most connected module is src/knowledge_graph/main (imports six others, called from two places) and src/knowledge_graph/config is a pure leaf (imports none, imported by three). No circular imports were detected.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/ai-knowledge-graph
cd ai-knowledge-graph

# Install dependencies (Python 3.11+)
pip install -r requirements.txt        # or: uv sync

# Edit the configuration (API key, model, etc.)
#   – file: config.toml
#   – example section shown in README

# Run the generator
python generate-graph.py \
    --input data/industrial-revolution.txt \
    --output industrial-revolution-kg.html

Optional flags (--no-standardize, --no-inference, --debug, --test) are documented in the CLI help (generate-graph --help). The script can also be installed in editable mode (pip install -e .) and invoked as generate-graph.

Real‑World Use A data‑science team can embed this step in an ETL pipeline: after ingesting raw reports, a nightly job runs generate-graph.py to produce a searchable HTML graph that downstream analysts explore in a browser. The LLM endpoint can be switched from a local Ollama model to a managed OpenAI service by editing only config.toml.

Code Health & Issues

  • HIGH – No test suite – 14 source files, zero tests. Fix: add unit tests for each public function and a CI step that runs them.
  • HIGH – No CI workflow – repository lacks .github/workflows or other CI config. Fix: add a GitHub Actions workflow that installs dependencies and runs the test suite on push and pull request.
  • MEDIUM – No Dependabot/Renovate – manifests (pyproject.toml, requirements.txt) exist but no update bot. Fix: commit .github/dependabot.yml covering the Python ecosystem.

Additional measured findings:

  • Broad except: blocks in src/knowledge_graph/llm.py and src/knowledge_graph/visualization.py swallow errors; replace with specific exception handling.
  • Deep nesting (up to 8 levels) in entity_standardization.py and llm.py; refactor with early returns or helper functions.
  • Small duplicated logic across entity_standardization.py and main.py; extract to a shared utility.

The Bottom Line The repository delivers a functional end‑to‑end LLM‑driven knowledge‑graph pipeline with a clear CLI and configurable LLM back‑end. However, the lack of tests, CI, and precise error handling makes it risky for production use without additional engineering effort. It is best suited for prototyping or internal tooling where rapid iteration outweighs the current maintenance gaps.