NexusRAG: A Hybrid RAG Stack With LightRAG, ChromaDB and Cross-Encoder Reranking

The gap NexusRAG targets: retrieval that loses document structure

Most retrieval pipelines split text, embed it, retrieve by cosine similarity and hand the chunks to a model. NexusRAG's README frames the problem as structure loss at every stage of that sequence. Headings, page boundaries and formulas disappear during parsing. Images and tables are dropped outright. Fixed-size chunking cuts mid-sentence. Citations are manual or absent, so a reader cannot check where an answer came from. The project's comparison table sets traditional RAG against its own pipeline on nine rows, covering parsing, media handling, chunking, embeddings, retrieval, entity awareness, context assembly, citations and page awareness. The intended audience is a team building an internal knowledge base over PDFs, DOCX and PPTX files where the answer has to point back at a page. A legal, compliance or research workflow fits that description. A chatbot over short support articles does not, because the parsing and knowledge graph stages add cost that plain vector search would avoid.

How the hybrid retrieval pipeline is assembled

Retrieval runs two paths in parallel. The vector path uses BAAI/bge-m3, described as a 1024-dimension multilingual bi-encoder covering more than 100 languages, stored in ChromaDB with cosine similarity and an over-fetch of the top 20 candidates. The knowledge graph path uses LightRAG for entity and relationship extraction plus keyword-to-entity matching. The README explains the dual embedding design as a split of duties: vector search needs speed from a local model, while graph extraction needs semantic richness for entity recognition, so it can use Gemini Embedding at 3072 dimensions, Ollama, or a local sentence-transformers model. After both paths return, all 20 candidates are scored jointly with the query by BAAI/bge-reranker-v2-m3, a cross-encoder that encodes the query and chunk together rather than comparing independent vectors. Filtering keeps the top 8 above a relevance threshold of 0.15, with a fallback to the top 3 if everything falls below it. A media discovery step then finds images and tables on the same pages as surviving chunks. Context assembly is ordered: knowledge graph insights first, then cited chunks, then related images and tables.

Citations, page numbers and the ParsedDocument contract

Every chunk carries its page number, heading path and references to images and tables on the same page, and the README states that page awareness is preserved end to end from chunk to citation to document viewer navigation. Citations use auto-generated four-character IDs. On the parsing side, Docling and Marker are interchangeable behind a shared output contract called ParsedDocument, so deduplication, embedding, graph construction and retrieval behave the same regardless of which parser produced the document. That is the strongest design decision in the repository as described: it means the parser is a configuration choice rather than an architectural commitment. The media handling follows from the same page metadata. Images and tables are not kept in a separate index. A vision model captions an image, the caption is appended to the text chunks on that page in a form like [Image on page 5]: Graph showing 12% revenue growth YoY, and the combined text is embedded. Table summaries work the same way, capped at 500 characters. The consequence is that image and table search depends entirely on caption quality and on the caption landing on the right page chunks.

Getting it running: parser switch, env keys and the two-model decision

The README gives one concrete configuration example. Setting NEXUSRAG_DOCUMENT_PARSER=marker in the .env file switches the parser from Docling, which is the default, to Marker. That single key is the main operational lever shown in the material. The second lever is the knowledge graph embedding provider, which the README describes as configurable across Gemini at 3072 dimensions, Ollama, or local sentence-transformers such as bge-m3 at 1024 dimensions. Generation is likewise Gemini or Ollama, with agentic streaming chat and function calling. The stack is Python 3.10 or later, React 19, FastAPI and Docker, and the README links a Quick Start section, though the truncated text here does not include its commands. Beyond the parser key and the provider choice, the supplied material does not list the remaining environment variables, the Docker Compose service names, or the API routes. Treat those as unverified until you read the repository directly.

The Docling default is the expensive one

The parser comparison table puts the trade-off plainly. Docling handles PDF, DOCX, PPTX and HTML and is described as having basic formula support with known LaTeX issues, at roughly 18 to 20 GB of VRAM when formula enrichment is active. Marker handles a wider format list that adds XLSX and EPUB, produces better LaTeX through Surya, and runs in roughly 2 to 4 GB of VRAM. The default is the heavier option. A team that follows the README without reading the table may provision a GPU that Docling needs and Marker would not, or may hit out-of-memory on a shared card and conclude the project does not work. The second limitation is structural: because image and table search runs through captions embedded in page chunks, a document whose images carry no captions, or whose captions are vague, is effectively invisible to image search even though the file was parsed. The knowledge graph adds its own failure surface. Entity extraction quality depends on the KG embedding provider, and the README offers Gemini, Ollama and sentence-transformers as alternatives without stating how much retrieval quality differs between them.

Where a plain vector store is the better fit

ChromaDB on its own, or any single-model vector pipeline, is the honest alternative for a large share of the cases NexusRAG targets. The difference in approach is not one of tuning but of what runs at query time. A ChromaDB-only pipeline embeds the query once, compares it against stored vectors by cosine similarity and returns the nearest chunks. NexusRAG adds a second embedding model for graph construction, an entity extraction pass at index time, a LightRAG lookup at query time, a cross-encoder that scores query and chunk jointly, and a media discovery step. The cross-encoder in particular is a transformer forward pass over every candidate pair, which is more precise than cosine similarity but cannot be precomputed the way an embedding can. If your corpus is short, flat and text-only, the graph and reranking stages buy little and cost latency on every query. If your documents are long PDFs with tables, figures and a heading hierarchy, the extra stages are the reason to pick this project over a bare vector store.

Licence, maintenance and what the repository does not say

The README carries an MIT badge that links to a LICENSE file, but the repository metadata supplied here lists the licence as unknown and no releases were retrieved. Those two signals conflict, and the badge alone is not a licence grant. Before any commercial use, check that the LICENSE file exists and contains the MIT text. The MIT badge covers the NexusRAG code as published; it says nothing about the models the pipeline pulls in. BAAI/bge-m3 and BAAI/bge-reranker-v2-m3 carry their own terms, as do Docling, Marker, LightRAG, ChromaDB and the Gemini API. Running Docling or Marker locally keeps document content on your hardware; routing KG embedding or generation through Gemini sends text to a third party. That is a data handling decision, not a licensing one, and it belongs in the adoption review. The last push recorded is 2026-04-20, so the project is active, but with no releases there is no versioned upgrade path to follow. Pinning the commit you deploy is the only reproducible option the material supports.

Editorial conclusion

Adopt NexusRAG if you want a working end-to-end reference for hybrid retrieval and you can accept the Docling VRAM footprint or switch to Marker. Do not adopt it if you only need a retrieval library to import, or if you need a named open source licence before shipping. Verify first whether the repository ships a LICENSE file matching the MIT badge, and confirm which of Gemini, Ollama or sentence-transformers you intend to run for KG embeddings, since that choice determines whether the pipeline needs network access.

Official sources

1. Issues
2. LeDat98/NexusRAG on GitHub
3. README