robert-mcdermott/ai-knowledge-graph: LLM-Powered Knowledge Graphs from Text

robert-mcdermott/ai-knowledge-graph: LLM-Powered Knowledge Graphs from Text

Unstructured text holds relationships that traditional search and summarization tools miss. Developers building RAG pipelines, research tools, or semantic applications need ways to surface entities and their connections without hand-crafting ontologies or writing brittle regex extraction rules. The ai knowledge graph generator from robert-mcdermott/ai-knowledge-graph addresses this by using any OpenAI-compatible LLM to extract Subject-Predicate-Object triplets from plain text, then renders them as an interactive, explorable graph. With 2,547 GitHub stars, 354 forks, and an Apache 2.0 license, it is a practical open-source option for teams that want transparency and local control over their knowledge extraction pipeline.

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

robert-mcdermott/ai-knowledge-graph is a Python^{↗ Bright Coding Blog}-based system that transforms unstructured documents into structured knowledge representations. Released under the Apache License 2.0 and actively maintained (last commit December 28, 2025), the project targets developers and researchers who need to extract semantic relationships from text without building custom NLP pipelines.

The tool sits at the intersection of three technical categories: LLM orchestration, information extraction, and graph visualization. Unlike black-box SaaS offerings, it is fully self-hostable. You point it at any OpenAI-compatible endpoint—Ollama for local models, vLLM for high-throughput serving, LiteLLM for unified access to Bedrock, Azure OpenAI, or Anthropic—and it handles chunking, extraction, standardization, inference, and rendering.

The core output is an interactive HTML visualization powered by PyVis, with nodes sized by centrality metrics and color-coded by community detection (Louvain method). The project also exports raw JSON for downstream processing. This dual-output design makes it useful both for human exploration and for feeding structured data into larger applications.

The repository's traction (2,547 stars, 354 forks) suggests it fills a genuine gap: developers want knowledge graph capabilities without the complexity of enterprise graph databases or the lock-in of proprietary AI services.

Key Features

Text Chunking with Overlap Control

Large documents exceed typical LLM context windows. The system automatically splits input into configurable chunks with configurable overlap, ensuring no relationships are lost at segment boundaries. Chunk size and overlap are exposed in config.toml—not hardcoded—so you tune for your model's context length and your text's coherence requirements.

LLM-Agnostic Knowledge Extraction

The extraction phase uses your choice of LLM via any OpenAI-compatible API. The README explicitly lists Ollama, LM Studio, OpenAI, vLLM, and LiteLLM as supported endpoints. This matters for teams with data residency requirements, cost constraints, or existing model infrastructure.

Entity Standardization

A common failure mode in multi-chunk extraction is entity fragmentation: "AI," "artificial intelligence," and "AI system" get treated as distinct nodes. The optional standardization pass resolves these via text normalization and, when enabled, LLM-assisted entity alignment. The README documents a real case: 201 raw entities consolidated to 160 standardized forms.

Relationship Inference

Beyond explicit extraction, the tool infers additional relationships through three mechanisms: transitive rules, lexical similarity, and optional LLM-based inference between disconnected graph communities. This reduces the "island problem" where related concepts appear unconnected because they occurred in distant document chunks.

Interactive Visualization

The HTML output supports zoom, pan, hover details, physics controls, and filtering. Original relationships render as solid lines; inferred relationships as dashed lines. Both light and dark themes are available. Node sizing reflects degree, betweenness, or eigenvector centrality—metrics calculated via NetworkX.

Use Cases

Academic Research & Literature Review

Researchers processing historical texts, policy documents, or scientific literature can use the tool to map conceptual landscapes without manual annotation. The Industrial Revolution demo shows how the system surfaces enabling technologies, social impacts, and key figures from a single narrative text.

RAG Pipeline Enhancement

Retrieval-Augmented Generation systems often struggle with multi-hop reasoning. Feeding extracted triplets into a graph database (Neo4j, Amazon Neptune) gives retrieval layers explicit relationship paths to traverse. The JSON export format supports this integration.

Content Analysis & Competitive Intelligence

Analysts processing earnings calls, regulatory filings, or news archives can quickly identify which entities relate to which capabilities or risks. The community detection feature surfaces thematic clusters that keyword search might miss.

Local-First AI Applications

Teams running Ollama or vLLM on private infrastructure can use this tool without sending documents to third-party APIs. The entire pipeline—from text to visualization—operates within your network boundary.

Educational Tool for NLP Concepts

The explicit three-phase architecture (extraction → standardization → inference) makes the codebase a concrete reference for teaching information extraction pipelines. The Mermaid diagram in the README visualizes program flow for students tracing data transformations.

Installation & Setup

The project requires Python 3.11 or newer. Two dependency management paths are documented.

Standard pip installation:

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

# Install dependencies
pip install -r requirements.txt

UV-based installation (faster, reproducible):

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

# Sync dependencies with uv
uv sync

Install as editable module:

pip install --upgrade -e .

After installation, create config.toml in the project root. The README provides this template:

[llm]
model = "gemma3"  # Google open weight model
api_key = "sk-1234"
base_url = "http://localhost:11434/v1/chat/completions" # Local Ollama instance
max_tokens = 8192
temperature = 0.2

[chunking]
chunk_size = 200  # Number of words per chunk
overlap = 20      # Number of words to overlap between chunks

[standardization]
enabled = true            # Enable entity standardization
use_llm_for_entities = true  # Use LLM for additional entity resolution

[inference]
enabled = true             # Enable relationship inference
use_llm_for_inference = true  # Use LLM for relationship inference
apply_transitive = true    # Apply transitive inference rules

The base_url field accepts any OpenAI-compatible endpoint. For cloud providers via LiteLLM, adjust accordingly. The temperature = 0.2 setting prioritizes deterministic extraction over creative generation—appropriate for structured output tasks.

Real Code Examples

Basic invocation with pip-installed dependencies:

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

This is the simplest entry point. The script reads config.toml from the working directory, processes the input text through all configured phases, and writes both HTML visualization and JSON data export.

UV-based execution (no explicit install step after uv sync):

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

UV handles environment isolation automatically. This pattern suits teams already standardized on UV for Python project management.

Module-installed CLI (after pip install --upgrade -e .):

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

The installed command exposes the same interface as the direct script invocation. This is the cleanest option for system-wide or containerized deployments.

Documented example run with actual output:

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

The README preserves the complete console output from this run, showing 13 chunks processed, 216 initial triples extracted, 201 entities standardized to 160, and 370 inferred relationships added for a final graph of 564 triples across 9 communities. This transparency lets users calibrate expectations for their own documents.

Debug mode for troubleshooting extraction quality:

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

The --debug flag surfaces raw LLM responses and extracted JSON, essential for tuning prompts or diagnosing parsing failures when adapting to new model endpoints.

Advanced Usage & Best Practices

Model Selection Trade-offs

The README uses Gemma 3 via Ollama as its example, but the architecture is model-agnostic. Smaller models (3B-7B parameters) suffice for well-structured domains with predictable entity types. Complex technical or biomedical texts may need larger context windows and stronger reasoning capabilities—adjust max_tokens and select models accordingly.

Chunk Size Calibration

The default 200-word chunks with 20-word overlap is a starting point, not a universal constant. Dense academic prose may need smaller chunks to stay within context limits after prompt templating. Narrative texts with long-range dependencies may benefit from larger chunks and higher overlap to preserve anaphoric references.

Selective Phase Disabling

Both standardization and inference are optional. Disable with --no-standardize or --no-inference when:

• You need raw extraction for downstream manual curation
• LLM API costs are a constraint (inference phases add additional calls)
• You have domain-specific normalization already handled

JSON Export for Pipeline Integration

The tool saves raw graph data alongside HTML visualization. Parse this JSON to load triplets into graph databases, vector stores with metadata, or evaluation frameworks for extraction quality assessment.

Comparison with Alternatives

The primary trade-off is integration depth versus control. robert-mcdermott/ai-knowledge-graph gives you a complete, runnable pipeline with visible intermediate outputs at each phase. Enterprise platforms offer more scalable storage and querying but require separate infrastructure. Framework components demand more assembly but fit existing LangChain applications naturally.

FAQ

What Python version is required? Python 3.11 or newer.

Does it work with Claude, GPT-4, or other commercial APIs? Yes—any OpenAI-compatible endpoint, including via LiteLLM proxy for Anthropic, Azure, or Bedrock.

Can I run entirely offline? Yes, with Ollama or LM Studio serving local models.

What license covers the project? Apache License 2.0.

How large a document can it process? Limited by your LLM's context window and your API rate limits; chunking handles arbitrary document length.

Is the visualization self-contained? Yes—the HTML output includes all JavaScript^{↗ Bright Coding Blog} and CSS; no external dependencies for viewing.

Can I disable the LLM-based standardization and inference? Yes, via config flags or command-line options --no-standardize and --no-inference.

Conclusion

robert-mcdermott/ai-knowledge-graph is a pragmatic tool for developers who need to surface structured relationships from unstructured text without surrendering control to opaque services. Its four-phase architecture—chunked extraction, entity standardization, relationship inference, and interactive visualization—addresses real friction points in knowledge graph construction. The OpenAI-compatible API design and local-first options make it adaptable to diverse operational constraints.

It is best suited for: prototyping knowledge extraction pipelines, augmenting RAG systems with explicit relationship data, building local AI applications under data residency requirements, and teaching information extraction concepts through inspectable, modifiable code.

The project is not a replacement for enterprise graph databases at production scale, but it is an excellent on-ramp. For teams evaluating whether knowledge graphs improve their applications, this tool provides a low-friction path to empirical validation.

Explore the repository, run the Industrial Revolution demo, and adapt the configuration to your documents: https://github.com/robert-mcdermott/ai-knowledge-graph