ai-knowledge-graph: turning a text file into an interactive graph with any OpenAI-compatible LLM

What ai-knowledge-graph actually produces

The input is an unstructured document. The output is a set of Subject-Predicate-Object triples, each relationship carrying the sentence it was extracted from, plus an HTML page where you can click a node, filter by entity type, and read the source sentences behind an edge. The README lists person, organization, place, event, technology, product, work, date and concept as the entity types the extraction step returns.

The audience is narrow and identifiable: someone with a corpus of reports, articles or notes who wants to see the structure inside them without standing up a graph database first. The README's own sample set (the Industrial Revolutions, Marie Curie, the Apollo Program, a coffee supply chain, La Alhambra in Spanish) shows the intended scale: a single document or a small directory, not a streaming pipeline. The optional graph-chat command answers questions against the generated graph with citations back to it, which is the closest this gets to retrieval-augmented generation, except the retrieval target is a graph the tool just built rather than a vector index.

The extraction pipeline, chunk by chunk

The README describes the flow in one line: large documents are split on sentence boundaries with overlap and extracted in parallel. The config exposes the knobs for that split. Under [chunking], chunk_size defaults to 500 words and overlap to 50 words, and the README states chunks end on sentence boundaries rather than mid-sentence. Under [llm], concurrency defaults to 4, so four chunks are in flight at once against your endpoint.

After extraction come two cleanup stages. Entity standardization merges case, stop-word and plural variants, with an optional LLM pass for whatever the deterministic rules miss. Then inference runs, and this is the part worth reading closely. The README calls it conservative and traceable: LLM passes bridge isolated parts of the graph and add well-known relationships between central entities, a deterministic taxonomy rule links specific terms to general ones, every inferred edge records which method produced it, and the count of inferred edges is capped relative to the extracted ones. That cap is the design decision that separates this from tools that let a model hallucinate freely into your graph. It also means the graph will look sparse next to what a permissive pipeline would emit.

Everything downstream is networkx plus a Jinja template. The README lists exports to JSON, CSV, GraphML for Gephi, yEd and Cytoscape, and a Cypher script for Neo4j. The visualization is a single self-contained HTML file with search, click-to-highlight, a relationships panel with sources, named communities, entity-type filters, a shortest-path finder and light/dark themes.

Installing it and rendering your first graph

The README requires Python 3.11 or newer. Core dependencies are networkx, jinja2 and requests, installed automatically. The web interface lives behind an extra, so the quick start clones the repository and syncs with it.

git clone https://github.com/robert-mcdermott/ai-knowledge-graph.git
cd ai-knowledge-graph
uv sync --extra web            # or: pip install -e ".[web]"

That creates the generate-graph, graph-chat and graph-serve commands. With uv, prefix commands with uv run; with pip, drop the prefix.

Before touching a model, the README suggests exploring the bundled samples, which needs no LLM at all.

uv run graph-serve --config config.toml --graphs data/samples --open

You should see a library of the five sample graphs from data/samples/. Browsing works without a reachable model; the Ask panel and the New graph form do not. To render one sample to a static page instead:

uv run generate-graph --from-json data/samples/marie-curie.json --output marie-curie.html

For your own text, edit config.toml first. The README gives this shape, with model and base_url as the only required keys:

[llm]
model = "gemma3"
api_key = "env:OPENAI_API_KEY"
base_url = "http://localhost:11434/v1/chat/completions"
max_tokens = 32768
temperature = 0.2

Then run the generator against a file:

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

Three files appear: knowledge_graph.html, knowledge_graph.json with the triples, and knowledge_graph.meta.json with community names. The README warns that reasoning models need a large max_tokens budget, and notes temperature should be omitted for models that only accept the default, naming gpt-5 as an example. Keep personal settings in a file git ignores, such as config-working.toml, and pass it with --config.

Where the LLM dependency bites

This tool is only as good as the endpoint behind it, and the README's feature list reads partly as a list of failure modes its client already absorbs. There is truncation detection for reasoning models, retries with back-off, and an automatic max_completion_tokens fallback. The token_param option defaults to auto and switches to max_completion_tokens for newer OpenAI models. None of that is decoration; it is evidence that models routinely return malformed or cut-off responses to this kind of extraction prompt, and the client is working around it.

json_mode defaults to false, which means the tool does not require the server to support response_format = json_object. That widens endpoint compatibility but puts the parsing burden on the client. If your model drifts into prose mid-response, expect the extraction to degrade rather than fail loudly, because the README does not document a strict validation gate on individual triples.

The on-disk cache at .kg-cache is the other constraint to understand. It makes re-running the same input free, which matters when you are iterating on chunking, but it also means a cached run will not reflect a change you made to the prompt or to entity standardization. The README notes the cache can be disabled with an empty string or --no-cache. If a re-run looks identical after you changed something, that is why.

Finally, the tool is not a knowledge graph database. There is no query language, no persistence layer, no incremental update path described. You regenerate the graph. For a corpus that changes daily, that regeneration cost is the whole story.

How it differs from GraphRAG-style pipelines

The obvious comparison is Microsoft's GraphRAG, which also builds a graph from text with an LLM. The difference is in what each treats as the deliverable. GraphRAG's published approach builds hierarchical community summaries so that a retrieval step can answer global questions across a corpus; the graph is infrastructure for question answering. Here the graph is the artifact. The README's explorer is the primary interface, and graph-chat is described as an optional companion command.

That changes the cost profile too. GraphRAG's summarization passes are expensive per token of input. This tool's inference stage is deliberately capped relative to extracted edges, so the LLM bill stays closer to one extraction pass plus a bounded amount of bridging. If your goal is a browsable map of one document, the lighter pipeline is the right shape. If your goal is answering "what are the main themes across 10,000 documents", you want the summarization layer this project does not have.

A second alternative is simpler: skip the LLM, use spaCy or a rule-based triple extractor, and accept lower recall on implicit relationships. That costs nothing per document and is deterministic. The reason to pay for an LLM here is that the README's extraction handles any language via extraction.language (set it to "Chinese" to get entity names and predicates in Chinese) and picks up relationships a dependency parser will miss. Whether that recall gain is worth a per-chunk API call is a question only your corpus can answer.

Licence, maintenance and the cost of upgrading

The project is Apache-2.0, declared in pyproject.toml as license = { file = "LICENSE" } and in the classifier list. Apache-2.0 includes an explicit patent grant and requires you to preserve notices and state changes; it does not impose copyleft on your own code. Nothing here restricts commercial use. That is a statement about the licence text, not advice about your situation.

The last push to the repository was on 2026-09-12, and v0.8.0 was released the same day, with v0.7.0 earlier that day and 0.6.3 back on 2025-12-28. The repository is not archived. Note that pyproject.toml still declares version = "0.7.0" while the release list shows v0.8.0, so the package metadata and the tag disagree; if you pin by version string rather than by commit, check which one you actually got.

Upgrade cost is low in one direction and awkward in another. The dependency surface is three packages (networkx, jinja2, requests) plus optional extras for PDF, DOCX and web, so there is little to break. But the outputs are files you may have already shared: the HTML is self-contained and the JSON schema is what graph-chat reads. A change to the triple format or the meta.json structure would invalidate saved graphs. The README does not document a schema version field or a migration path, so keep the source text alongside the generated JSON if you plan to regenerate later. Development commands are listed for anyone patching it: uv sync --extra dev --extra web, then uv run pytest -q, which the README says runs 170 tests without needing an LLM.

Editorial conclusion

Adopt it if you have a local Ollama or another OpenAI-compatible endpoint, a folder of .txt, .md, .pdf or .docx documents, and you want a browsable graph rather than a database schema. Skip it if you need Cypher-backed queries at scale, entity resolution against an existing ontology, or a hosted service with an SLA: the README points to a Cypher export for Neo4j rather than a Neo4j backend. Verify first that your model returns clean JSON at your configured max_tokens, because truncation detection and the max_completion_tokens fallback exist precisely because that fails often enough to matter.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. robert-mcdermott/ai-knowledge-graph on GitHub