robert-mcdermott/ai-knowledge-graph: Turn Text into Interactive Knowledge Graphs

robert-mcdermott/ai-knowledge-graph: Turn Text into Interactive Knowledge Graphs

Unstructured text holds relationships that traditional search and summarization miss. Developers building RAG pipelines, research tools, or semantic analysis systems need ways to surface entities and their connections without hand-crafting ontologies or writing brittle regex parsers. robert-mcdermott/ai-knowledge-graph addresses this by using LLMs to extract Subject-Predicate-Object triplets from raw documents and rendering them as explorable, interactive graphs. With 2,547 GitHub stars, 354 forks, and active development through late 2025, this Python^{↗ Bright Coding Blog}-based tool has gained traction among developers who want knowledge graph construction without enterprise infrastructure.

This article walks through what robert-mcdermott/ai-knowledge-graph does, how it works, and where it fits in your stack.

What is robert-mcdermott/ai-knowledge-graph?

robert-mcdermott/ai-knowledge-graph is an open-source Python system that transforms unstructured text documents into interactive knowledge graph visualizations. Maintained by Robert McDermott, the project sits at the intersection of natural language processing, graph theory, and LLM orchestration. It is licensed under Apache 2.0 and requires Python 3.11+.

The tool's core pipeline: chunk text, prompt an LLM to extract SPO triplets, standardize entity references, infer additional relationships, and output an HTML visualization. Notably, it is model-agnostic through OpenAI-compatible endpoints—Ollama, LM Studio, vLLM, LiteLLM (which bridges AWS^{↗ Bright Coding Blog} Bedrock, Azure OpenAI, Anthropic, and others)—so you are not locked to a single provider or pricing tier.

The project's relevance stems from a practical gap. Many knowledge graph tools assume structured input (CSV, RDF, existing ontologies) or require heavy manual curation. This tool starts from raw text, making it accessible for ad-hoc analysis, prototype RAG enrichment, or exploratory research. The interactive output—built with PyVis—runs in any browser without additional dependencies, lowering the barrier for sharing or embedding results.

Key Features

Text Chunking with Overlap Control

Large documents exceed typical LLM context windows. The system automatically splits input into configurable chunks with overlapping regions to preserve cross-boundary context. Chunk size and overlap are tunable via config.toml (default: 200 words per chunk, 20-word overlap).

LLM-Powered Knowledge Extraction

Each chunk is processed to extract Subject-Predicate-Object triplets. The implementation in process_with_llm handles entity and relationship identification without predefined schemas. This flexibility means the tool adapts to domain-specific vocabulary without reconfiguration.

Entity Standardization

A common failure mode in multi-chunk extraction: "AI," "artificial intelligence," and "AI system" get treated as distinct nodes. The optional standardization pass (configurable, with LLM-assisted resolution) collapses synonymous references. The README documents a real case: 201 entities standardized to 160, improving graph coherence.

Relationship Inference

Beyond explicit extraction, the tool applies transitive rules, lexical similarity matching, and optional LLM-based inference to connect disconnected graph communities. This reduces fragmentation—critical for discoverability in large documents. The example run shows 216 original triples expanding to 564 after inference, with 355 inferred edges flagged separately from 209 original edges.

Interactive Visualization

Output is a self-contained HTML file with: color-coded communities (Louvain method), node sizing by centrality metrics (degree, betweenness, eigenvector), solid lines for original relationships and dashed for inferred, plus zoom/pan/hover controls and light/dark themes.

Provider Flexibility

Any OpenAI-compatible endpoint works. Local development with Ollama, prototyping with LM Studio, or production via LiteLLM's provider aggregation—all supported through base_url and api_key configuration.

Use Cases

Academic Literature Review

Researchers processing survey papers or thesis chapters can extract conceptual relationships without manual annotation. The chunking handles book-length inputs; standardization resolves author variations in terminology. The resulting graph reveals thematic clusters and cross-topic connections invisible in linear reading.

RAG Pipeline Debugging

Developers building retrieval-augmented generation systems can visualize what relationships their chunking strategy actually preserves. If critical entity links span chunk boundaries, the overlap setting or inference pass may surface gaps in retrieval coverage. The JSON export (-kg.json alongside HTML) enables programmatic downstream analysis.

Domain Ontology Bootstrapping

Starting knowledge graph construction in a new domain typically requires expensive expert curation. This tool generates a first-pass structure from existing text corpora—technical documentation, regulatory filings, internal wikis—which human curators then refine. The inference layer suggests relationships experts might overlook.

Historical or Narrative Analysis

The included Industrial Revolution demo illustrates temporal/causal relationship extraction from historical texts. Similar applications apply to legal case analysis, intelligence report processing, or narrative structure visualization in media studies.

Local-First AI Workflows

Teams with data residency requirements can run the full pipeline against local Ollama instances, never transmitting source documents to third-party APIs. The --debug flag exposes raw LLM responses for audit and reproducibility.

Installation & Setup

The project supports both pip and uv workflows. Clone and install:

# Clone repository
git clone https://github.com/robert-mcdermott/ai-knowledge-graph.git
cd ai-knowledge-graph

# Option A: pip install
pip install -r requirements.txt

# Option B: uv sync (if using uv)
uv sync

Install as an editable module for CLI access:

pip install --upgrade -e .

Configure your LLM endpoint in config.toml:

[llm]
model = "gemma3"  # or your preferred model
api_key = "sk-1234"
base_url = "http://localhost:11434/v1/chat/completions"  # Ollama example
max_tokens = 8192
temperature = 0.2

[chunking]
chunk_size = 200
overlap = 20

[standardization]
enabled = true
use_llm_for_entities = true

[inference]
enabled = true
use_llm_for_inference = true
apply_transitive = true

Key configuration notes: base_url accepts any OpenAI-compatible endpoint. For local development, Ollama's default is shown. For cloud providers via LiteLLM, adjust base_url and api_key accordingly. The temperature = 0.2 prioritizes consistent extraction over creative variation—appropriate for structured output tasks.

Real Code Examples

Basic Pipeline Execution

Run the full extraction-to-visualization pipeline:

python generate-graph.py --input your_text_file.txt --output knowledge_graph.html

Or with uv:

uv run generate-graph.py --input your_text_file.txt --output knowledge_graph.html

After editable install, use the module CLI:

generate-graph --input your_text_file.txt --output knowledge_graph.html

The --input flag specifies the source text; --output controls the HTML destination. Without --output, the tool defaults to knowledge_graph.html in the working directory.

Processing a Real Document with Full Output

The README documents this example with the Industrial Revolution text:

generate-graph --input data/industrial-revolution.txt --output industrial-revolution-kg.html

Console output shows the three-phase pipeline in action:

Using input text from file: data/industrial-revolution.txt
==================================================
PHASE 1: INITIAL TRIPLE EXTRACTION
==================================================
Processing text in 13 chunks (size: 100 words, overlap: 20 words)
Processing chunk 1/13 (100 words)
...
Extracted a total of 216 triples from all chunks

==================================================
PHASE 2: ENTITY STANDARDIZATION
==================================================
Starting with 216 triples and 201 unique entities
Standardized 201 entities into 181 standard forms
After standardization: 216 triples and 160 unique entities

==================================================
PHASE 3: RELATIONSHIP INFERENCE
==================================================
Added 370 inferred relationships
Final knowledge graph: 564 triples

This demonstrates the tool's transparency: per-phase statistics, entity counts, and final graph composition are all reported. The Added -22 inferred relationships line (likely a display quirk in deduplication) suggests reviewing output when tuning inference settings.

Test Mode for Validation

Verify installation without configuring an LLM:

generate-graph --test

This generates a sample visualization with built-in test data, confirming the visualization pipeline works independently of LLM connectivity.

Debug Mode for Prompt Engineering

Inspect raw LLM responses when refining extraction quality:

generate-graph --input your_text_file.txt --debug

The --debug flag outputs raw LLM responses and extracted JSON, essential for diagnosing parsing failures or tuning prompts in prompts.py.

Advanced Usage & Best Practices

Tune Chunk Size to Your LLM's Context Window

The default 200-word chunks suit 8K-32K context models. With larger context windows (128K+), increasing chunk_size reduces API calls and may improve cross-sentence relationship capture. Conversely, smaller chunks for weaker models reduce truncation risk. Monitor the "words" report in phase 1 output to verify actual chunk sizes.

Disable Inference for Factual Rigor

The inference layer adds plausible but unverified relationships. For applications requiring strict source grounding—legal analysis, medical literature—run with --no-inference to preserve only explicit extractions. The visualization still shows community structure via original edges alone.

Standardization Trade-offs

LLM-assisted standardization improves coherence but increases token usage and latency. For cost-sensitive batch processing, try use_llm_for_entities = false first; basic text normalization may suffice for well-edited inputs. Review the "entity groups" count in output to assess standardization impact.

Export JSON for Downstream Processing

The tool automatically saves .json alongside .html. Parse this for: Neo4j import, network analysis with NetworkX, or vector database metadata enrichment. The JSON schema mirrors the internal graph representation.

Community Detection Interpretation

Louvain-detected communities (9 in the Industrial Revolution example) indicate dense connection clusters, not necessarily semantic topics. Cross-reference with node labels before treating communities as categorical labels.

Comparison with Alternatives

robert-mcdermott/ai-knowledge-graph occupies a middle ground: lower setup than SpaCy pipelines, more endpoint flexibility than LangChain defaults, and lighter weight than enterprise platforms. The trade-off is less production hardening—no built-in retry logic, rate limiting, or graph database persistence are documented. For teams already invested in Neo4j or needing async batch processing at scale, LangChain or custom solutions may integrate more cleanly. For exploration, teaching, or local-first workflows, this tool's self-contained output and provider agnosticism are genuine differentiators.

FAQ

What Python version is required?

Python 3.11 or higher.

Can I use Claude, GPT-4, or local models?

Yes—any OpenAI-compatible endpoint works, including Anthropic via LiteLLM, OpenAI directly, or local Ollama/LM Studio instances.

Is there a hosted version or SaaS?

No; the README describes only local/self-hosted operation.

How large a document can it process?

Limited by your LLM's rate limits and your patience; chunking handles arbitrary length, but each chunk requires an API call.

Can I disable the LLM-based standardization and inference?

Yes—both are configurable in config.toml or via --no-standardize and --no-inference flags.

What license applies?

Apache License 2.0, permitting commercial use with attribution.

Does it support non-English text?

The README does not specify; extraction quality depends on your chosen LLM's multilingual capabilities.

Conclusion

robert-mcdermott/ai-knowledge-graph solves a specific, recurring developer problem: transforming unstructured text into explorable relationship graphs without heavy infrastructure investment. Its 2,547-star traction reflects genuine utility for prototyping, research, and local-first AI workflows. The three-phase pipeline—extraction, standardization, inference—provides transparency and control that black-box alternatives lack, while OpenAI-compatible endpoint support future-proofs against provider shifts.

This tool best serves: developers building RAG systems who need visibility into chunk-level relationships; researchers exploring document corpora without annotation budgets; and teams with data residency requirements seeking local LLM execution. It is less suited for production-scale batch processing requiring built-in observability or enterprise governance features.

To evaluate it against your use case, clone the repository and run the --test visualization or process your own text: https://github.com/robert-mcdermott/ai-knowledge-graph. The Industrial Revolution demo offers a concrete sense of output quality before you configure your own LLM endpoint.