Hyper-Extract: A CLI That Turns Documents Into Hypergraphs, Not Just Graphs
Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
At a glance
- What is it?
- Hyper-Extract is a Python CLI that uses LLMs to extract structured knowledge from unstructured text, supporting graphs, hypergraphs, and spatio-temporal models. It stands out for its incremental updates and provenance tracking, but its licensing and provider dependencies need scrutiny.
- Who is it for?
- Adopt Hyper-Extract if you need a single command to turn PDFs, papers, or reports into queryable graphs or hypergraphs, especially when your sources change and you want automatic rollback of outdated facts. Skip it if you require a permissive license for commercial redistribution, or if you cannot run an LLM provider that matches its expectations.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What Problem It Solves and Who It Targets
Hyper-Extract addresses the gap between raw documents and machine-readable knowledge. Instead of writing custom extraction scripts, you run a single CLI command that parses a file and outputs a structured knowledge base. The README positions it for researchers turning papers into concept graphs, financial analysts extracting entities from earnings reports, and knowledge base managers who need to keep facts current. The tool's pitch is that hypergraphs capture many-to-many relationships that ordinary graphs miss, which matters for domains like biomedicine or legal reasoning where a single event can connect multiple entities at once. The intended user is an engineer or analyst who already has an LLM API key and wants a reproducible pipeline, not someone who needs a GUI or a fully managed service.
The Extraction Pipeline: From File to Graph to Query
The core workflow is visible in the quick start. You run `he parse` on a document, which sends the content to an LLM along with a template that defines the target structure. The output is stored in a directory that serves as your knowledge base. Then you query with `he search`, which likely embeds your question and retrieves relevant nodes or hyperedges, though the exact retrieval mechanism is not detailed in the supplied material. Visualization with `he show` produces an interactive graph, and `he export obsidian` converts the structure into Markdown notes with wikilinks. The documentation claims support for 11 extraction engines including GraphRAG, LightRAG, and Hyper-RAG, plus over 80 YAML templates across finance, legal, and general domains. This suggests the template determines the schema, and the engine determines how the LLM extracts and indexes. The separation is useful: you can switch from a simple list to a hypergraph without changing your source document.
Getting Started: Commands and Configuration
Installation requires either `uv tool install hyperextract` or `pipx install hyperextract`. The CLI is invoked as `he`. Configuration is provider-based: `he config init -p openai -k YOUR_KEY` sets both LLM and embeddings for OpenAI. For DeepSeek, which is LLM-only, you must run separate commands: `he config llm -p deepseek -k YOUR_KEY` and `he config embedder -p openai -k YOUR_KEY`. Local deployment uses vLLM with two endpoints, one for the LLM model like Qwen3.5-9B and another for an embedding model like bge-m3. The README notes that OpenAI and Bailian provide both in one key, while Anthropic and DeepSeek require pairing with an OpenAI-compatible embedder. The cost estimate for DeepSeek is about $0.001 to $0.005 per page, which is a concrete figure but not benchmarked by this review. For rich document ingestion, you need the extra package: `pip install "hyperextract[ingest]"` to handle PDF, Word, PowerPoint, Excel, HTML, and EPUB.
Incremental Updates and Provenance: The Real Differentiator
Most extraction tools treat a document as a one-shot input. Hyper-Extract instead tracks each source. The `he feed` command accepts an updated version of a file under the same source name, and the README states that old facts roll back automatically. You can tag sources with `he tag`, scope searches with `--tag`, and audit which documents contributed what using `he info --sources`. The `he remove --document` command allows rollback of a specific source. This provenance model is valuable in domains where documents get revised, such as regulatory filings or clinical guidelines. The trade-off is complexity: the index must maintain a mapping from facts to sources, which likely increases storage and update latency compared to a simple rebuild. The README does not explain how conflicts are resolved when two sources state contradictory facts, so you should test that behavior before relying on it for critical data.
Limitations and Failure Modes
The most obvious limitation is the dependency on external LLM providers. If you use OpenAI or DeepSeek, your document content leaves your machine, which may be unacceptable for proprietary or personal data. The local vLLM option exists, but it requires a GPU and setting up two separate services. The README does not specify minimum VRAM or model sizes beyond the example of Qwen3.5-9B, so you cannot predict whether it runs on your hardware. Another limitation is the reliance on templates. With over 80 templates, you might find one for your domain, but if your data does not fit a predefined schema, you must write your own YAML template, and the documentation for that process is not in the supplied material. Also, the extraction quality depends entirely on the LLM's ability to follow the template; there is no mention of validation or error handling when the model returns malformed JSON. The license is listed as NOASSERTION on GitHub, even though the README badge shows Apache 2.0. That mismatch is a red flag: you cannot assume the license until the repository clarifies it.
Comparison with a Simpler Alternative
A direct alternative is to use a generic LLM chain with a library like LangChain or LlamaIndex to extract entities and relationships into a standard graph database such as Neo4j. That approach gives you full control over the schema, the prompts, and the storage layer. Hyper-Extract differs by packaging the entire pipeline into a CLI with predefined templates and a built-in index format. The trade-off is that you lose flexibility: you cannot easily plug in a custom graph database or write your own retrieval logic. Hyper-Extract also adds the hypergraph and spatio-temporal structures, which are not native to most graph databases. If your use case is a simple entity-relationship graph, the alternative may be simpler and more transparent. But if you need hyperedges or temporal reasoning, you would have to build that yourself, and Hyper-Extract offers it out of the box.
Maintenance, Upgrade Cost, and License Concerns
The repository shows active development with releases v0.9.0, v0.8.2, and v0.8.1 in September 2026, and a last push on September 9, 2026. That pace suggests frequent changes, which means upgrading may require adapting to new CLI flags or template formats. The release notes mention "Rich Document Ingestion" and "Scoped Search" as recent features, indicating the tool is still evolving. There is no documented migration guide in the supplied material, so you should budget time to test after each upgrade. The license is a serious concern. The GitHub API reports NOASSERTION, while the README displays an Apache 2.0 badge. This discrepancy means you cannot legally rely on the badge. Before using it in a commercial product, you must contact the maintainer or check the LICENSE file directly. The project is not archived, which is positive, but the license ambiguity is a blocker for many organizations.
Editorial conclusion
Adopt Hyper-Extract if you need a single command to turn PDFs, papers, or reports into queryable graphs or hypergraphs, especially when your sources change and you want automatic rollback of outdated facts. Skip it if you require a permissive license for commercial redistribution, or if you cannot run an LLM provider that matches its expectations. Before committing, verify which extraction engines and templates match your domain, confirm your provider supports both LLM and embedding calls or plan to pair them, and test the vLLM path if you need on-premise data handling. The project is actively developed, with releases in September 2026, so check the changelog for breaking changes before upgrading.
Community notes