Paper deep dive
Quanta: A Self-Contained Python Library for Hybrid Retrieval over Quantised Embeddings, Lexical Indexes, and Knowledge Graphs
Ioannis E. Livieris
Intelligence
Status: succeeded | Model: Gemma-4-26B-A4B | Prompt: intel-v1 | Confidence: 90%
Last extracted: 9/17/2026, 4:44:27 AM
Summary
The paper introduces Quanta, an open-source Python library that unifies dense vector search over 4-bit quantised embeddings, BM25 full-text retrieval, and knowledge graph traversal into a single hybrid retrieval API. It employs weighted reciprocal rank fusion for score combination and treats the knowledge graph as a candidate expander rather than a relevance scorer, using structural adjacency to widen the candidate pool before re-scoring via content-based indexes.
Entities (8)
Relation Signals (7)
Quanta → supports → BM25
confidence 95% · unifies dense vector search... BM25 full-text retrieval
Quanta → uses → Reciprocal Rank Fusion
confidence 95% · signals are combined by weighted reciprocal rank fusion
Quanta → demonstratedon → Clinical Knowledge Graph
confidence 90% · We describe a running deployment—a tool-using language-model agent over a clinical knowledge graph
Quanta → supports → Neo4j
confidence 90% · the Neo4j graph and the Redis cache are networked services... bounded Cypher traversals... against Neo4j
Quanta → uses → TurboQuant
confidence 90% · Quanta delegates vector compression entirely, storing vectors through turbovec, an implementation of TurboQuant
Quanta → supports → DuckDB
confidence 85% · the embedded DuckDBDocStore
Quanta → supports → Tantivy
confidence 85% · the Tantivy full-text index
Cypher Suggestions (0)
No Cypher suggestions yet.
Abstract
Abstract:An advanced retrieval-augmented generation pipeline is typically assembled from three or four independently operated systems: an approximate nearest-neighbour index, a full-text search engine, a graph database, and a relational document store. Each contributes its own deployment surface, configuration model, and failure modes, and the integration logic that binds them is written anew in every project. In this work, we present \textsc{Quanta}, an open-source Python library, which unifies dense vector search over 4-bit quantised embeddings, BM25 full-text retrieval, and knowledge-graph traversal behind a single retrieval API. Quanta makes two design commitments, which distinguish it from existing hybrid retrieval stacks. First, signals are combined by \emph{weighted reciprocal rank fusion} rather than by normalising heterogeneous scores onto a shared range, which we argue is ill-posed because such normalisations are query-dependent. Second, the graph is a \emph{candidate expander and not a relevance scorer}: traversal widens the candidate pool, and the newly admitted documents are re-scored by the dense indexes under an identifier allowlist, so structural adjacency determines what is considered while content evidence determines how it ranks.
Tags
Links
- Source: https://arxiv.org/abs/2609.18248v1
- Canonical: https://arxiv.org/abs/2609.18248v1
PDF not stored locally. Use the link above to view on the source site.
Full Text
22,567 characters extracted from source content.
Expand or collapse full text
Quanta: A Self-Contained Python Library for Hybrid Retrieval over Quantised Embeddings, Lexical Indexes, and Knowledge Graphs Ioannis E. Livieris Affiliation: Novelcore, Athens, GR 10436 Affiliation: Department of Business Administration & Organization Administration University of Peloponnese, Kalamata, GR 24100 livieris@uop.gr Abstract An advanced retrieval-augmented generation pipeline is typically assembled from three or four independently operated systems: an approximate nearest-neighbour index, a full-text search engine, a graph database, and a relational document store. Each contributes its own deployment surface, configuration model, and failure modes, and the integration logic that binds them is written anew in every project. In this work, we present Quanta, an open-source Python library, which unifies dense vector search over 4-bit quantised embeddings, BM25 full-text retrieval, and knowledge-graph traversal behind a single retrieval API. Quanta makes two design commitments, which distinguish it from existing hybrid retrieval stacks. First, signals are combined by weighted reciprocal rank fusion rather than by normalising heterogeneous scores onto a shared range, which we argue is ill-posed because such normalisations are query-dependent. Second, the graph is a candidate expander and not a relevance scorer: traversal widens the candidate pool, and the newly admitted documents are re-scored by the dense indexes under an identifier allowlist, so structural adjacency determines what is considered while content evidence determines how it ranks. Every optional component—graph, lexical index, embedding cache—has a null implementation, so a deployment can begin as pure vector search and acquire further signals through configuration alone. We describe a running deployment—a tool-using language-model agent over a clinical knowledge graph—and report its observed behaviour. This is a system description; a controlled retrieval evaluation is left to future work. A Preprint Keywords Hybrid retrieval ⋅· knowledge graphs ⋅· vector quantisation ⋅· retrieval-augmented generation. 1 Introduction Retrieval-augmented generation (RAG) Gao et al. (2024); Lewis et al. (2020) has made retrieval quality a first-order concern for applications previously served by a single similarity index, and no single signal is sufficient. Dense bi-encoders Karpukhin et al. (2020) generalise across vocabulary mismatch but degrade on rare tokens such as product codes, statute numbers and proper nouns. Lexical scoring with BM25 Robertson and Zaragoza (2009) covers that gap, and hybrid dense–lexical retrieval is now standard practice. Neither signal exploits relationships known to the corpus owner yet absent from the text: that a court decision cites a statute, or that a diagnosis is clinically comorbid with another. Combining all three signals is, in current practice, an integration problem rather than a retrieval problem. A representative stack pairs FAISS Johnson et al. (2019) or a managed vector database Wang and others (2021) with Elasticsearch for BM25, Neo4j Neo4j (2026) for traversal and PostgreSQL for storage; four systems must be provisioned and kept consistent, and the code fanning a query across them is rewritten in each project. Orchestration frameworks LlamaIndex (2026) reduce this boilerplate but do not remove the systems, and treat the graph, where present, as a separate index with its own query path rather than as a participant in one ranking. Quanta delegates vector compression entirely, storing vectors through turbovec, an implementation of TurboQuant Google Research (2025); it claims no contribution to quantisation or approximate indexing Malkov and Yashunin (2020). Its fusion rule is likewise established: reciprocal rank fusion (RRF) Cormack et al. (2009) combines ranked lists without the score normalisation CombSUM-style fusion Fox and Shaw (1994) requires, and Bruch et al. Bruch et al. (2023) show that convex combination surpasses RRF only when tuned per collection, leaving RRF the stronger default in the untuned regime a general-purpose library must assume. The principal departure from prior work concerns the graph: GraphRAG and related systems Edge et al. (2024) extract an entity graph using a language model and apply it to query-focused summarisation, whereas Quanta consumes a graph authored by the corpus owner, inside ordinary top-k retrieval, and restricts its influence to candidate selection. The contributions of this paper are threefold: • a single-process retriever fusing dense, lexical and structural evidence over one document store, with no external retrieval service (Section 2); • a two-pass procedure in which graph traversal enlarges the candidate set and the admitted documents are re-scored by the dense indexes through an allowlist, so that the graph alters what is retrieved without altering the ranking function (Sections 2.2 and 2.3); and • measurements from a clinical knowledge-graph deployment characterising candidate enlargement, fusion behaviour and cost (Section 3). The remainder of this paper is organised as follows. Section 2 describes the system architecture, including the quantised vector indexes, document stores, rank-fusion mechanism and graph-based candidate expansion. Section 3 presents a case study on a clinical knowledge-graph deployment and characterises candidate enlargement, retrieval behaviour and runtime cost. Finally, Section 4 discusses the limitations of the current design and concludes the paper. 2 System Architecture A deployment comprises a set of named vector indexes, a document store and any subset of three optional backends: a graph, a lexical index and an embedding cache. A single MultiRetriever owns them and exposes one asynchronous search() entry point. Fig. 1 shows the runtime decomposition. Quanta performs no embedding of its own, so the embedding provider remains on the consumer side and an optional LlamaIndex adapter may drive the same retriever. Components that must be local—the quantised vector indexes and the Tantivy full-text index—reside in the library process, whereas the document store, the Neo4j graph and the Redis cache are networked services. The edges leaving the retriever are the legs of a query: a dense search per index, a keyword leg, a seed-and-expand exchange with the graph returning candidate identifiers rather than scores, and one hydration of the ranked top-k. Figure 1: Quanta runtime architecture. The graph returns candidate identifiers rather than scores, and the document store is contacted once, to hydrate the ranked top-k. 2.1 Index and Storage Layer QuantaIndex wraps a turbovec identifier-mapped index. Application identifiers are strings whereas the index addresses vectors by 64-bit integers; Quanta maps between them with a fixed-seed xxhash-64 digest and rejects insertions whose digest collides with a different existing identifier. At bit width b, an index of n vectors of dimension d occupies ndb/8ndb/8 bytes: for 10610^6 vectors of dimension 768 at b=4b=4 this is 366 MiB against 2.86 GiB for float32, obtained in-process with no ANN service to operate. Search is exact over the quantised representation, so query time is linear in corpus size. Two document-store backends implement one asynchronous interface: PostgresDocStore, using asyncpg with a GIN index over a JSONB metadata column, and the embedded DuckDBDocStore Raasveldt and Mühleisen (2019). Metadata filtering is commonly implemented as a post-filter, retrieving the top-K vectors and discarding those failing the predicate, which under a selective predicate shrinks the effective K and costs recall invisibly. Quanta resolves the predicate first, obtains the identifiers satisfying it and passes them to the index as an allowlist, so the nearest-neighbour scan ranges only over admissible vectors. The same allowlist enables the re-scoring of Section 2.3; both features rest on one primitive. 2.2 Rank Fusion The legs emit incommensurable quantities. Cosine similarity is bounded and, for a competent encoder over a topical corpus, concentrated near the upper end of its range; BM25 is unbounded and grows with query length and collection statistics; inverse hop distance is a property of the graph and the seed set rather than of the query. Quanta therefore fuses on rank. For legs ℓ∈ℒ with weights wℓw_ , where rℓ(d)r_ (d) is the one-based position of document d in the ranked list of leg ℓ , score(d)=∑ℓ∈ℒwℓkrrf+rℓ(d),score(d)= _ w_ k_rrf+r_ (d), (1) where a document absent from a leg contributes nothing from it and krrfk_rrf (default 60) damps the head of each list. Each dense index carries wdense/|ℐ|w_dense/|I| over the active index set ℐI, the lexical leg wbm25w_bm25 and the graph leg wgraphw_graph. Since (1) is homogeneous in the weights, only their ratios are meaningful and no renormalisation is required. 2.3 Graph Expansion as Candidate Enlargement Retrieval proceeds in two passes (Algorithm 1). The first ranks the corpus by content alone and a preliminary application of (1) selects the top graph_seed_k documents as seeds; a bounded breadth-first traversal then returns every document within graph_hops steps of a seed. The admitted identifiers are not injected with a synthetic score but re-scored: a second search per dense index, constrained through the allowlist to exactly those identifiers, is merged into that index’s ranked list before the final fusion. An expanded document therefore competes on its own similarity to the query, on the same footing as one the first pass returned. Let 1C_1 denote the candidate set of the first pass and 2⊇1C_2 _1 the set after expansion. With wgraph=0w_graph=0 the graph leg vanishes from (1), so a document’s fused score depends only on its ranks in the content legs and traversal effects 1↦2C_1 _2 and nothing further. The graph determines which documents are considered, never how well they rank. Algorithm 1 Two-pass hybrid retrieval 1: Query embedding q, query text t, active indexes ℐI, allowlist A, fetch size K, graph seed size S, graph hops H 2: Ranked top-k documents 3: 4: Pass 1: Content retrieval 5: for all i∈ℐi do 6: Li←rank(search(i,q,K,A))L_i (search(i,q,K,A)) 7: Lbm25←rank(search(BM25,t,K))L_bm25 (search(BM25,t,K)) 8: R1←RRF(Lii∈ℐ,Lbm25)R_1 (\L_i\_i ,L_bm25) 9: Seeds←topS(R1)Seeds _S(R_1) 10: 11: Pass 2: Graph expansion and constrained re-scoring 12: Lgraph←expand(Graph,Seeds,H)L_graph (Graph,Seeds,H) 13: N←keys(Lgraph)∖covered(Lii∈ℐ)N (L_graph) (\L_i\_i ) 14: for all i∈ℐi do 15: Li′←search(i,q,allowed_ids=N)L _i (i,q,allowed\_ids=N) 16: Li←merge(Li,Li′)L_i (L_i,L _i) 17: 18: Final fusion 19: R←RRF(Lii∈ℐ,Lbm25,Lgraph)R (\L_i\_i ,L_bm25,L_graph) 20: return topk(R)top_k(R) Setting wgraph>0w_graph>0 admits the graph as a further leg ranked by hop distance. This is warranted only when expanded documents possess no vector in any index and therefore cannot be re-scored, because (1) compresses each leg severely. With one dense index, wdense=0.7w_dense=0.7, krrf=60k_rrf=60 and the frequently quoted setting wgraph=0.3w_graph=0.3, a document ranked first by content scores 0.7/61=0.01150.7/61=0.0115, whereas one ranked fourth by content but first in the graph leg—an arbitrary one-hop neighbour of a seed—scores 0.7/64+0.3/61=0.01590.7/64+0.3/61=0.0159 and overtakes it. A graph weight within a small factor of the content weight is therefore not a tie-breaker: it promotes every one-hop neighbour above the best content match. Quanta defaults to wgraph=0w_graph=0 and directs tuning towards graph_seed_k and graph_hops, which widen the pool without perturbing the order. 3 Case Study: A Clinical Knowledge Graph The following characterises observed behaviour on a deployment distributed with the library. It is not a retrieval evaluation: no relevance judgements and no baseline ranker are involved. Figure 2: Medical search agent runtime. The dispatcher is the only component that reaches data; the quantised indexes reside inside the application process. 3.1 Corpus and Ontology The corpus is a synthetic hospital record set in Neo4j comprising 100 patients, 30 physicians, 12 diagnoses coded to ICD-10, 12 procedures, 12 medications and 5 hospitals, joined by nine relationship types. The ontology places properties that vary per relationship on the edges rather than the nodes: a HAS_DIAGNOSIS edge carries the severity and chronicity of that diagnosis for that patient, so the same diagnosis is mild for one patient and severe for another. Two edge families encode knowledge no document states: nine COMORBID_WITH edges between diagnoses, graded by evidence level, and ten INTERACTS_WITH edges between medications, graded by severity. Because these edges are authored rather than extracted, the corpus tests graph expansion instead of restating what the embeddings already encode. Five narrative fields are embedded into separate indexes: patient summaries (100 vectors), physician expertise (30), diagnosis and procedure descriptions (12 each) and medical images (198), using a 768-dimensional multilingual sentence encoder for text and a 512-dimensional CLIP encoder for images. All indexes are quantised to four bits, occupying 107.3 KiB against 858 KiB for float32. Every narrative is written in Greek. 3.2 Retrieval Behaviour Three dense legs—diagnoses, procedures and patient summaries—were registered with a Tantivy BM25 leg over the same narratives and a graph leg, using wdense=0.5w_dense=0.5, wbm25=0.3w_bm25=0.3, wgraph=0w_graph=0 and an embedded DuckDB store. The bundled Neo4jGraph assumes a homogeneous (:Document id) model, which this graph is not; the deployment therefore implements the GraphBackend interface directly against the real schema in roughly forty lines, coalescing per-label key properties into the identifier used by the indexes. No projection or migration of the graph was required. Table 1 reports the candidate pool before and after expansion. Dense retrieval over three indexes yields 18 identifiers; a two-hop traversal from three seeds reaches 50 nodes, of which 41–42 are new, and approximately 70% of those receive a similarity from the constrained re-scoring search. The pool grows by a factor of roughly 3.3 with no document receiving a score originating in the graph. Table 1: Candidate Enlargement, k=6k=6, Three Seeds, Two Hops Query Pool BFS New Re-scored Pool′ Insulin resistance, polyuria (el) 18 50 41 28 59 Chronic kidney disease (en) 18 50 42 30 60 Heart failure, dyspnoea (el) 18 50 42 28 60 For the query heart failure and dyspnoea, the content legs place I50 (heart failure) first and E11 (type 2 diabetes) sixth, the latter through the BM25 leg alone: no dense index ranked it within its top-k, so it carried no dense contribution. Expansion from the seed I50 crosses an authored COMORBID_WITH edge and admits E11; re-scoring returns its similarity, yielding rank 6 in the diagnoses leg and a dense term of 0.16¯/66=0.00250.1 6/66=0.0025. Its fused score rises from 0.00460.0046 to 0.00710.0071 and it advances from sixth position to fourth. The graph determined that a diabetes description merited consideration for a heart-failure query; it did not determine where that description ranked. Dense and dense-plus-BM25 searches complete in 7–9 ms on this corpus, and enabling expansion raises query time to 44–115 ms. 3.3 Agent Deployment The same substrate supports a tool-using agent exposing twelve tools: dense retrieval against a QuantaIndex, lexical resolution over Neo4j full-text indexes with edit-distance matching, and bounded Cypher traversals. Fig. 2 shows the runtime. A clinician’s question enters a reasoning loop alternating between an OpenAI-compatible model endpoint and a dispatcher, the only component that reaches data: it issues Cypher and graph tools against Neo4j and semantic or image searches through the indexer, which calls the sentence and CLIP encoders. Conversation history is persisted to Redis when configured. Retrieval is entirely in-process; only the model endpoint, the graph and the cache cross a network boundary. Six unseen clinical questions were answered by an open-weight 27B model on a local endpoint, all without error. Tool execution ranged from 19 to 984 ms against turn latencies of 19–32 s dominated by generation, below five percent of the turn throughout. This is the regime in which an embedded, exactly searched, compressed index is an appropriate trade, and in which the in-process design removes a network round trip from a loop issuing several tool calls. Two further properties are exercised: the allowlist serves cohort-restricted similarity by mechanically the same call that re-scores expanded candidates, and cross-lingual matching survives quantisation, an English referral question matching a Greek nephrology narrative at cosine 0.620. 4 Conclusion In this work, we present Quanta, a minimal-dependency architecture for hybrid retrieval that combines semantic, lexical, and structural signals within a lightweight Python library. Its central design principle is to separate candidate generation from relevance estimation: the knowledge graph is used primarily to expand the candidate set through bounded structural traversal, while semantic and lexical evidence remains responsible for ranking the retrieved documents. This separation allows structural relationships to improve the coverage of retrieval without allowing graph proximity to dominate content-based relevance. A second aspect of the design is the use of quantised vector indexes for memory-efficient dense retrieval. Quanta performs exhaustive search over 4-bit representations, providing exact nearest-neighbour search with respect to the quantised vectors while substantially reducing the memory footprint of the vector store. Combined with identifier-based allowlists, the same retrieval primitive supports both metadata-constrained search and the constrained re-scoring of graph-expanded candidates, without requiring a separate approximate-nearest-neighbour service. The resulting architecture provides a simple integration path from pure dense retrieval to hybrid dense–lexical–graph retrieval. Optional components are exposed through common interfaces and null implementations, allowing deployments to introduce lexical search, graph expansion, caching, or external document storage without changing the retrieval logic itself. Our clinical deployment demonstrates the operational behaviour of this design, including substantial candidate-set enlargement through graph traversal and the relatively small latency contribution of retrieval compared with downstream language-model generation. These observations characterise the architecture rather than establish retrieval superiority; a controlled evaluation against relevance-labelled benchmarks and alternative hybrid rankers remains an important direction for future work. Quanta is MIT-licensed and available at https://github.com/ilivieris/quanta. References [1] S. Bruch, S. Gai, and A. Ingber (2023) An analysis of fusion functions for hybrid retrieval. ACM Transactions on Information Systems 42 (1). Cited by: §1. [2] G. V. Cormack, C. L. A. Clarke, and S. Büttcher (2009) Reciprocal rank fusion outperforms condorcet and individual rank learning methods. In Proceedings of the SIGIR Conference, p. 758–759. Cited by: §1. [3] D. Edge, H. Trinh, N. Cheng, J. Bradley, A. Chao, A. Mody, S. Truitt, and J. Larson (2024) From local to global: a graph rag approach to query-focused summarization. arXiv preprint arXiv:2404.16130. Cited by: §1. [4] E. A. Fox and J. A. Shaw (1994) Combination of multiple searches. In Proceedings of TREC-2, Cited by: §1. [5] Y. Gao, Y. Xiong, X. Gao, K. Jia, J. Pan, Y. Bi, Y. Dai, J. Sun, Q. Guo, M. Wang, and H. Wang (2024) Retrieval-augmented generation for large language models: a survey. arXiv preprint arXiv:2312.10997. Cited by: §1. [6] Google Research (2025) TurboQuant: online vector quantization with near-optimal distortion rate. Note: Implementation: https://pypi.org/project/turbovec/ Cited by: §1. [7] J. Johnson, M. Douze, and H. Jégou (2019) Billion-scale similarity search with gpus. IEEE Transactions on Big Data 7 (3), p. 535–547. Cited by: §1. [8] V. Karpukhin, B. Oğuz, S. Min, P. Lewis, L. Wu, S. Edunov, D. Chen, and W. Yih (2020) Dense passage retrieval for open-domain question answering. In Proceedings of EMNLP, p. 6769–6781. Cited by: §1. [9] P. Lewis, E. Perez, A. Piktus, F. Petroni, V. Karpukhin, N. Goyal, H. Küttler, M. Lewis, W. Yih, T. Rocktäschel, S. Riedel, and D. Kiela (2020) Retrieval-augmented generation for knowledge-intensive nlp tasks. In Proceedings of NeurIPS, Cited by: §1. [10] LlamaIndex (2026) LlamaIndex. Note: https://github.com/run-llama/llama_indexAccessed 2026 Cited by: §1. [11] Yu. A. Malkov and D. A. Yashunin (2020) Efficient and robust approximate nearest neighbor search using hierarchical navigable small world graphs. IEEE Transactions on Pattern Analysis and Machine Intelligence 42 (4), p. 824–836. Cited by: §1. [12] Neo4j (2026) Neo4j graph database. Note: https://neo4j.comAccessed 2026 Cited by: §1. [13] M. Raasveldt and H. Mühleisen (2019) DuckDB: an embeddable analytical database. In Proceedings of the SIGMOD Conference, p. 1981–1984. Cited by: §2.1. [14] S. Robertson and H. Zaragoza (2009) The probabilistic relevance framework: bm25 and beyond. Foundations and Trends in Information Retrieval 3 (4), p. 333–389. Cited by: §1. [15] J. Wang et al. (2021) Milvus: a purpose-built vector data management system. In Proceedings of the SIGMOD Conference, p. 2614–2627. Cited by: §1.