TopoRAG checks retrieved context for the gaps nearest-neighbor search can miss

Retrieval relevance is not the same as a complete explanation

Retrieval-augmented generation, or RAG, gives a language model external context before it answers. The usual retrieval step is designed to return chunks that are close to a query in vector space. That is useful, but it does not by itself establish that the selected chunks form a coherent account.

TopoRAG is aimed at that distinction. The project describes a Python workflow for detecting conceptual gaps and blind spots in text, with a particular focus on the context retrieved for a RAG pipeline. Its central premise is that a set of individually relevant passages can still skip a needed step, topic, or connection. When that happens, the model receiving the context has less grounding for its answer.

That makes the library relevant to AI engineers who already retrieve document chunks and want an additional check before inference. It accepts raw text, a URL, or a pre-chunked list of strings. The latter is the most direct fit for a RAG application: pass the retrieved chunks to the analyzer, inspect the reported gaps, then decide whether to retrieve more material, revise chunking, or change how the downstream system handles incomplete evidence.

Treating missing context as a shape problem

TopoRAG uses topological data analysis, abbreviated TDA. In this setting, the project turns text segments into embedding vectors, reduces their dimensions, and looks for persistent homology features. Persistent homology is a TDA technique that examines shapes in data across multiple distance scales. The README specifically identifies H1 holes, which are loop-like gaps in the point cloud formed by the segments.

The documented pipeline starts with paragraph-aware text splitting when the input is raw text. It creates embeddings with OpenAI's text-embedding-3-small model, then applies principal component analysis, or PCA, to reduce the representation to min(10, n-1) dimensions. It sends the reduced vectors to Ripser for persistent-homology analysis.

The library reports holes that meet a persistence threshold. Persistence is the value used here to decide which holes are substantial enough to surface. A lower threshold is more sensitive, and the README suggests trying 0.05 for small sets of fewer than 10 chunks, compared with the API default of 0.15.

If the Ripser path fails, the documented workflow falls back to Local Outlier Factor, or LOF, to identify sparse regions. That fallback is notable because it keeps the analysis moving with a different geometric signal rather than assuming a topological result will always be available.

From geometric signal to a useful review item

A detected hole is not automatically a human-readable diagnosis. TopoRAG uses gpt-4o-mini to name and explain a gap from nearby context, and can suggest material that could fill it. Each returned dictionary includes a topic_label, explanation, suggested_content, persistence, and rank.

The suggested content should be understood as a review aid, not verified source material. The library's own flow asks an LLM to generate that suggestion, so a team should use it to guide retrieval or investigation rather than insert it into a knowledge base without validation. This separation is a practical lesson for RAG systems: detecting that context may be incomplete and asserting the missing fact are different tasks.

The API exposes that choice through generate_suggestions, which defaults to True. Teams that only need a structural signal can disable suggestion generation. They can also cap the number of returned items with max_holes, defaulting to five, which provides a way to keep a review queue focused.

For pre-retrieved context, the primary entry point is TopoAnalyzer.analyze_segments(segments, ...). analyze_text handles splitting a raw string before analysis, while analyze_url is documented to scrape readable text and run the same overall process. All three routes give builders options depending on where the text enters their system.

A stack built around embeddings and geometry

The project targets Python 3.9 and newer and is packaged as toporag version 0.1.0. Its manifest confirms the components behind the documented workflow:

• OpenAI supplies the embedding and LLM integration described in the README.
• NumPy provides numerical-array support.
• scikit-learn supplies machine-learning utilities, including the documented PCA and LOF stages.
• Ripser performs persistent-homology computation.
• HTTPX and Beautiful Soup 4 support the documented URL-analysis path.

This composition also exposes an operational tradeoff. The current documented embedding and suggestion flow relies on an OpenAI API key. The roadmap lists local Hugging Face embedding support as future work, so users who need a no-key embedding option should not assume it is available today.

There is a second, more conceptual tradeoff. A topological hole in an embedding-based representation is a signal worth examining, not a proof that a particular fact is missing. Results can depend on segmentation, embedding behavior, dimensionality reduction, and the chosen threshold. TopoRAG acknowledges part of this tuning surface directly through its threshold and small-document guidance. In practice, it is best positioned as a context-quality diagnostic alongside retrieval evaluation, source checks, and application-specific tests.

Inspect the project

TopoRAG offers a distinct checkpoint for builders who want to ask not only whether their RAG system found related passages, but whether the retrieved passages leave an important conceptual space unaddressed. The repository includes installation guidance, example scripts, API details, and a stated roadmap. Inspect it at github.com/MuLIAICHI/toporag_lib.