vector-graph-rag 0.2.2__tar.gz → 0.3.0__tar.gz

{vector_graph_rag-0.2.2 → vector_graph_rag-0.3.0}/.env.example

@@ -99,3 +99,11 @@ MILVUS_URI=./vector_graph_rag.db
 # VGRAG_ENTITY_COLLECTION=vgrag_entities
 # VGRAG_RELATION_COLLECTION=vgrag_relations
 # VGRAG_PASSAGE_COLLECTION=vgrag_passages
+
+# Task-specific models override the shared VGRAG_LLM_MODEL.
+# VGRAG_EXTRACTOR_MODEL=gpt-5-mini
+# VGRAG_RERANKER_MODEL=jev
+# VGRAG_ANSWER_MODEL=gpt-4o-mini
+# TYPESAFE_API_KEY=your-key
+
+# VGRAG_JEV_MAX_CONCURRENCY=3

{vector_graph_rag-0.2.2 → vector_graph_rag-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: vector-graph-rag
-Version: 0.2.2
+Version: 0.3.0
 Summary: A Graph RAG implementation using pure vector search with Milvus
 Project-URL: Homepage, https://github.com/zilliztech/vector-graph-rag
 Project-URL: Documentation, https://zilliztech.github.io/vector-graph-rag/
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
 Requires-Dist: langchain-core>=0.3.0
 Requires-Dist: milvus-lite>=2.4.0
 Requires-Dist: numpy>=1.24.0
@@ -67,11 +68,14 @@ Requires-Dist: lxml-html-clean; extra == 'docling'
 Requires-Dist: trafilatura>=2.0.0; extra == 'docling'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
+Provides-Extra: evaluation
+Requires-Dist: matplotlib>=3.9; extra == 'evaluation'
 Provides-Extra: google
 Requires-Dist: google-genai>=1.0; extra == 'google'
 Provides-Extra: hf
 Requires-Dist: torch>=2.0.0; extra == 'hf'
 Requires-Dist: transformers>=4.30.0; extra == 'hf'
+Provides-Extra: jev
 Provides-Extra: jina
 Requires-Dist: httpx>=0.27; extra == 'jina'
 Provides-Extra: loaders
@@ -121,20 +125,24 @@ Description-Content-Type: text/markdown
   <a href="https://discord.com/invite/FG6hMJStWu"><img src="https://img.shields.io/badge/Discord-chat-7289da?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
 </p>
 
-> 💡 Encode entities and relations as vectors in [Milvus](https://milvus.io/), replace iterative LLM agents with a single reranking pass — achieve state-of-the-art multi-hop retrieval at a fraction of the operational and computational cost.
+> 💡 Encode entities and relations as vectors in [Milvus](https://milvus.io/), retrieve multi-hop evidence with single-pass generative reranking or two-stage Jev scoring, without an iterative search loop.
 
 <p align="center">
   <img src="https://github.com/user-attachments/assets/1185b651-ed72-4408-9dcd-25a74b12835b" alt="Vector Graph RAG Demo" width="800">
 </p>
 
+## What’s New
+
+- **Two-stage Jev retrieval reaches the quality–latency Pareto frontier.** See the [evaluation results](evaluation/jev/README.md).
+
 ## ✨ Features
 
 - **No Graph Database Required** — Pure vector search with Milvus, no Neo4j or other graph databases needed
-- **Single-Pass LLM Reranking** — One LLM call to rerank, no iterative agent loops (unlike IRCoT or multi-step reflection)
+- **Configurable Reranking** — Single-pass generative reranking or two-stage Jev relation and passage scoring
 - **Knowledge-Intensive Friendly** — Optimized for domains with dense factual content: legal, finance, medical, literature, etc.
 - **Zero Configuration** — Uses Milvus Lite by default, works out of the box with a single file
 - **Multi-hop Reasoning** — Subgraph expansion enables complex multi-hop question answering
-- **State-of-the-Art Performance** — 87.8% avg Recall@5 on multi-hop QA benchmarks, outperforming HippoRAG
+- **State-of-the-Art Performance** — Two-stage Jev leads the compared baselines on MuSiQue and 2Wiki and reaches the quality–latency Pareto frontier. See the [latest results](evaluation/jev/README.md) and [historical three-dataset evaluation](docs/evaluation.md#historical-results).
 
 ## 📦 Installation
 
@@ -227,7 +235,7 @@ argument. The method replaces only that source's chunks and graph references.
 Source-level writes are not transactionally atomic, but the same upsert/delete
 operation can be retried after an interruption to converge the source back to a
 consistent state.
-See the [Incremental Updates guide](docs/incremental-updates.md) for parser
+See the [Incremental Updates guide](docs/guides/incremental-updates.md) for parser
 integration, source key design, and retry recommendations.
 
 ```python
@@ -287,7 +295,7 @@ with observability_context(
 
 The built-in spans avoid document text, prompts, query text, generated answers,
 filters, and full URLs by default. See the
-[Observability guide](docs/observability.md) for setup details.
+[Observability guide](docs/guides/observability.md) for setup details.
 
 </details>
 
@@ -339,7 +347,7 @@ VGRAG_MILVUS_URI=http://localhost:19530
 
 </details>
 
-> 📖 Full Python API reference → [Python API docs](https://zilliztech.github.io/vector-graph-rag/python-api/)
+> 📖 Full Python API reference → [Python API docs](https://zilliztech.github.io/vector-graph-rag/reference/python-api/)
 
 ## 🔬 How It Works
 
@@ -363,11 +371,13 @@ Question → Entity Extraction → Vector Search → Subgraph Expansion → LLM
 4. **Single-pass LLM reranking** selects the most relevant passages
 5. Generate answer from selected passages
 
-> 📖 Detailed pipeline walkthrough with diagrams → [How It Works](https://zilliztech.github.io/vector-graph-rag/how-it-works/) · [Design Philosophy](https://zilliztech.github.io/vector-graph-rag/design-philosophy/)
+> 📖 Detailed pipeline walkthrough with diagrams → [How It Works](https://zilliztech.github.io/vector-graph-rag/architecture/how-it-works/) · [Design Philosophy](https://zilliztech.github.io/vector-graph-rag/architecture/design-philosophy/)
 
 ## 📊 Evaluation Results
 
-Evaluated on three multi-hop QA benchmarks (Recall@5):
+### Historical evaluation — before September 2026
+
+Before introducing Jev, we evaluated Vector Graph RAG on three multi-hop QA benchmarks (Recall@5):
 
 <p align="center">
   <img src="https://github.com/user-attachments/assets/221a0c8d-a414-4234-ac8b-ba4223aaa2cc" alt="Recall@5: Naive RAG vs Vector Graph RAG" width="700">
@@ -384,6 +394,16 @@ Evaluated on three multi-hop QA benchmarks (Recall@5):
 
 > 📖 Detailed analysis and reproduction steps → [Evaluation](https://zilliztech.github.io/vector-graph-rag/evaluation/)
 
+### Latest evaluation — October 2026: two-stage Jev
+
+**Two-stage Jev reaches the quality–latency Pareto frontier.**
+
+**86.07% average Recall@5**, the highest among the compared methods, with **3.13 seconds of additional model-call latency**. On MuSiQue and 2Wiki (1,000 questions each), two-stage Jev reaches the Pareto frontier under the reference latency estimates. This two-dataset result is separate from the historical three-dataset average above.
+
+![Quality and additional model latency](docs/assets/evaluation/quality-latency.png)
+
+See [Evaluation Results](evaluation/jev/README.md) for the gains over relation-only Jev and other baselines, timing details and reproduction instructions.
+
 ## 🗄️ Milvus Backend
 
 Just change `milvus_uri` to switch between deployment modes:
@@ -452,13 +472,13 @@ cd frontend && npm install && npm run dev
 
 See API docs at `http://localhost:8000/docs` after starting the server.
 
-> 📖 Full endpoint reference → [REST API docs](https://zilliztech.github.io/vector-graph-rag/rest-api/) · [Frontend guide](https://zilliztech.github.io/vector-graph-rag/frontend/)
+> 📖 Full endpoint reference → [REST API docs](https://zilliztech.github.io/vector-graph-rag/reference/rest-api/) · [Frontend guide](https://zilliztech.github.io/vector-graph-rag/guides/frontend/)
 
 ## 📚 Links
 
 - [Documentation](https://zilliztech.github.io/vector-graph-rag/) — full guides, API reference, and architecture details
-- [How It Works](https://zilliztech.github.io/vector-graph-rag/how-it-works/) — pipeline walkthrough with diagrams
-- [Design Philosophy](https://zilliztech.github.io/vector-graph-rag/design-philosophy/) — why pure vector search, no graph DB
+- [How It Works](https://zilliztech.github.io/vector-graph-rag/architecture/how-it-works/) — pipeline walkthrough with diagrams
+- [Design Philosophy](https://zilliztech.github.io/vector-graph-rag/architecture/design-philosophy/) — why pure vector search, no graph DB
 - [Milvus](https://milvus.io/) — the vector database powering Vector Graph RAG
 - [FAQ](https://zilliztech.github.io/vector-graph-rag/faq/) — common questions and troubleshooting
 

{vector_graph_rag-0.2.2 → vector_graph_rag-0.3.0}/README.md

@@ -17,20 +17,24 @@
   <a href="https://discord.com/invite/FG6hMJStWu"><img src="https://img.shields.io/badge/Discord-chat-7289da?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
 </p>
 
-> 💡 Encode entities and relations as vectors in [Milvus](https://milvus.io/), replace iterative LLM agents with a single reranking pass — achieve state-of-the-art multi-hop retrieval at a fraction of the operational and computational cost.
+> 💡 Encode entities and relations as vectors in [Milvus](https://milvus.io/), retrieve multi-hop evidence with single-pass generative reranking or two-stage Jev scoring, without an iterative search loop.
 
 <p align="center">
   <img src="https://github.com/user-attachments/assets/1185b651-ed72-4408-9dcd-25a74b12835b" alt="Vector Graph RAG Demo" width="800">
 </p>
 
+## What’s New
+
+- **Two-stage Jev retrieval reaches the quality–latency Pareto frontier.** See the [evaluation results](evaluation/jev/README.md).
+
 ## ✨ Features
 
 - **No Graph Database Required** — Pure vector search with Milvus, no Neo4j or other graph databases needed
-- **Single-Pass LLM Reranking** — One LLM call to rerank, no iterative agent loops (unlike IRCoT or multi-step reflection)
+- **Configurable Reranking** — Single-pass generative reranking or two-stage Jev relation and passage scoring
 - **Knowledge-Intensive Friendly** — Optimized for domains with dense factual content: legal, finance, medical, literature, etc.
 - **Zero Configuration** — Uses Milvus Lite by default, works out of the box with a single file
 - **Multi-hop Reasoning** — Subgraph expansion enables complex multi-hop question answering
-- **State-of-the-Art Performance** — 87.8% avg Recall@5 on multi-hop QA benchmarks, outperforming HippoRAG
+- **State-of-the-Art Performance** — Two-stage Jev leads the compared baselines on MuSiQue and 2Wiki and reaches the quality–latency Pareto frontier. See the [latest results](evaluation/jev/README.md) and [historical three-dataset evaluation](docs/evaluation.md#historical-results).
 
 ## 📦 Installation
 
@@ -123,7 +127,7 @@ argument. The method replaces only that source's chunks and graph references.
 Source-level writes are not transactionally atomic, but the same upsert/delete
 operation can be retried after an interruption to converge the source back to a
 consistent state.
-See the [Incremental Updates guide](docs/incremental-updates.md) for parser
+See the [Incremental Updates guide](docs/guides/incremental-updates.md) for parser
 integration, source key design, and retry recommendations.
 
 ```python
@@ -183,7 +187,7 @@ with observability_context(
 
 The built-in spans avoid document text, prompts, query text, generated answers,
 filters, and full URLs by default. See the
-[Observability guide](docs/observability.md) for setup details.
+[Observability guide](docs/guides/observability.md) for setup details.
 
 </details>
 
@@ -235,7 +239,7 @@ VGRAG_MILVUS_URI=http://localhost:19530
 
 </details>
 
-> 📖 Full Python API reference → [Python API docs](https://zilliztech.github.io/vector-graph-rag/python-api/)
+> 📖 Full Python API reference → [Python API docs](https://zilliztech.github.io/vector-graph-rag/reference/python-api/)
 
 ## 🔬 How It Works
 
@@ -259,11 +263,13 @@ Question → Entity Extraction → Vector Search → Subgraph Expansion → LLM
 4. **Single-pass LLM reranking** selects the most relevant passages
 5. Generate answer from selected passages
 
-> 📖 Detailed pipeline walkthrough with diagrams → [How It Works](https://zilliztech.github.io/vector-graph-rag/how-it-works/) · [Design Philosophy](https://zilliztech.github.io/vector-graph-rag/design-philosophy/)
+> 📖 Detailed pipeline walkthrough with diagrams → [How It Works](https://zilliztech.github.io/vector-graph-rag/architecture/how-it-works/) · [Design Philosophy](https://zilliztech.github.io/vector-graph-rag/architecture/design-philosophy/)
 
 ## 📊 Evaluation Results
 
-Evaluated on three multi-hop QA benchmarks (Recall@5):
+### Historical evaluation — before September 2026
+
+Before introducing Jev, we evaluated Vector Graph RAG on three multi-hop QA benchmarks (Recall@5):
 
 <p align="center">
   <img src="https://github.com/user-attachments/assets/221a0c8d-a414-4234-ac8b-ba4223aaa2cc" alt="Recall@5: Naive RAG vs Vector Graph RAG" width="700">
@@ -280,6 +286,16 @@ Evaluated on three multi-hop QA benchmarks (Recall@5):
 
 > 📖 Detailed analysis and reproduction steps → [Evaluation](https://zilliztech.github.io/vector-graph-rag/evaluation/)
 
+### Latest evaluation — October 2026: two-stage Jev
+
+**Two-stage Jev reaches the quality–latency Pareto frontier.**
+
+**86.07% average Recall@5**, the highest among the compared methods, with **3.13 seconds of additional model-call latency**. On MuSiQue and 2Wiki (1,000 questions each), two-stage Jev reaches the Pareto frontier under the reference latency estimates. This two-dataset result is separate from the historical three-dataset average above.
+
+![Quality and additional model latency](docs/assets/evaluation/quality-latency.png)
+
+See [Evaluation Results](evaluation/jev/README.md) for the gains over relation-only Jev and other baselines, timing details and reproduction instructions.
+
 ## 🗄️ Milvus Backend
 
 Just change `milvus_uri` to switch between deployment modes:
@@ -348,13 +364,13 @@ cd frontend && npm install && npm run dev
 
 See API docs at `http://localhost:8000/docs` after starting the server.
 
-> 📖 Full endpoint reference → [REST API docs](https://zilliztech.github.io/vector-graph-rag/rest-api/) · [Frontend guide](https://zilliztech.github.io/vector-graph-rag/frontend/)
+> 📖 Full endpoint reference → [REST API docs](https://zilliztech.github.io/vector-graph-rag/reference/rest-api/) · [Frontend guide](https://zilliztech.github.io/vector-graph-rag/guides/frontend/)
 
 ## 📚 Links
 
 - [Documentation](https://zilliztech.github.io/vector-graph-rag/) — full guides, API reference, and architecture details
-- [How It Works](https://zilliztech.github.io/vector-graph-rag/how-it-works/) — pipeline walkthrough with diagrams
-- [Design Philosophy](https://zilliztech.github.io/vector-graph-rag/design-philosophy/) — why pure vector search, no graph DB
+- [How It Works](https://zilliztech.github.io/vector-graph-rag/architecture/how-it-works/) — pipeline walkthrough with diagrams
+- [Design Philosophy](https://zilliztech.github.io/vector-graph-rag/architecture/design-philosophy/) — why pure vector search, no graph DB
 - [Milvus](https://milvus.io/) — the vector database powering Vector Graph RAG
 - [FAQ](https://zilliztech.github.io/vector-graph-rag/faq/) — common questions and troubleshooting
 

{vector_graph_rag-0.2.2/docs → vector_graph_rag-0.3.0/docs/architecture}/design-philosophy.md

@@ -1,5 +1,7 @@
 # Design Philosophy
 
+> The single-pass descriptions below cover the default generative reranker. Jev uses two-stage relation and passage scoring; see [models and reranking](../guides/reranking.md) for that pipeline and configuration.
+
 Vector Graph RAG is built on a simple but powerful observation: **you do not need a graph database to do Graph RAG**. By encoding entities, relations, and passages as vectors in Milvus, and replacing iterative LLM agents with a single reranking pass, we achieve competitive retrieval quality at a fraction of the operational and computational cost.
 
 This page explains the reasoning behind these choices, the trade-offs involved, and how the system compares to alternative approaches.
@@ -250,7 +252,7 @@ flowchart TB
 | **Vector Graph RAG** | 73.0% | **96.3%** | **94.1%** | **87.8%** |
 
 > [!INFO]
-> Recall@5 on standard multi-hop QA benchmarks. Vector Graph RAG achieves the highest average score while using fewer LLM calls and no graph database. See [Evaluation](evaluation.md) for methodology details.
+> Recall@5 on standard multi-hop QA benchmarks. Vector Graph RAG achieves the highest average score while using fewer LLM calls and no graph database. See [Evaluation](../evaluation.md) for methodology details.
 
 ### Key Differentiators
 

{vector_graph_rag-0.2.2/docs → vector_graph_rag-0.3.0/docs/architecture}/how-it-works.md

@@ -1,5 +1,7 @@
 # How It Works
 
+> The single-pass descriptions below cover the default generative reranker. Jev uses two-stage relation and passage scoring; see [models and reranking](../guides/reranking.md) for that pipeline and configuration.
+
 ## Overview
 
 Vector Graph RAG processes documents and answers questions through two main pipelines: **indexing** (offline) and **querying** (online).