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

{vector_graph_rag-0.2.1 → 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.1 → 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.1
+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
@@ -42,6 +43,8 @@ Requires-Dist: mistralai>=1.0; extra == 'all'
 Requires-Dist: ollama>=0.4; extra == 'all'
 Requires-Dist: onnxruntime<1.24,>=1.17; (python_version == '3.10') and extra == 'all'
 Requires-Dist: onnxruntime>=1.17; (python_version >= '3.11') and extra == 'all'
+Requires-Dist: opentelemetry-api>=1.0; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.0; extra == 'all'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'all'
 Requires-Dist: pytest>=7.0.0; extra == 'all'
 Requires-Dist: ruff>=0.1.0; extra == 'all'
@@ -55,16 +58,24 @@ Provides-Extra: api
 Requires-Dist: fastapi>=0.109.0; extra == 'api'
 Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'api'
 Provides-Extra: dev
+Requires-Dist: opentelemetry-sdk>=1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docling
+Requires-Dist: docling>=2.0.0; extra == 'docling'
+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
@@ -75,8 +86,15 @@ Provides-Extra: local
 Requires-Dist: einops>=0.8.2; extra == 'local'
 Requires-Dist: sentence-transformers>=3.0; extra == 'local'
 Requires-Dist: torch>=2.0.0; extra == 'local'
+Provides-Extra: mineru
+Requires-Dist: lxml-html-clean; extra == 'mineru'
+Requires-Dist: markitdown[docx,pdf]>=0.1.4; extra == 'mineru'
+Requires-Dist: mineru[pipeline]>=3.0.0; extra == 'mineru'
+Requires-Dist: trafilatura>=2.0.0; extra == 'mineru'
 Provides-Extra: mistral
 Requires-Dist: mistralai>=1.0; extra == 'mistral'
+Provides-Extra: observability
+Requires-Dist: opentelemetry-api>=1.0; extra == 'observability'
 Provides-Extra: ollama
 Requires-Dist: ollama>=0.4; extra == 'ollama'
 Provides-Extra: onnx
@@ -107,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
 
@@ -155,6 +177,17 @@ uv add "vector-graph-rag[all]"
 
 </details>
 
+<details>
+<summary><b>With OpenTelemetry tracing</b></summary>
+
+```bash
+pip install "vector-graph-rag[observability]"
+# or
+uv add "vector-graph-rag[observability]"
+```
+
+</details>
+
 ## 🚀 Quick Start
 
 ```python
@@ -202,6 +235,8 @@ 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/guides/incremental-updates.md) for parser
+integration, source key design, and retry recommendations.
 
 ```python
 from langchain_core.documents import Document
@@ -211,7 +246,7 @@ rag.upsert_documents_by_source(
         Document(
             page_content="Einstein developed relativity at Princeton.",
             metadata={
-                "source": "sharepoint:file-123",
+                "source": "file:file-123",
                 "triplets": [
                     ["Einstein", "developed", "relativity"],
                     ["Einstein", "worked at", "Princeton"],
@@ -222,7 +257,7 @@ rag.upsert_documents_by_source(
     extract_triplets=False,
 )
 
-rag.delete_documents_by_source("sharepoint:file-123")
+rag.delete_documents_by_source("file:file-123")
 ```
 
 > **Migration note:** v0.1.5 exposed `upsert_documents(document_id=...)` and
@@ -236,6 +271,34 @@ for removal in v1.0.0. For explicit full refreshes, use `rebuild_texts()`,
 
 </details>
 
+<details>
+<summary>📈 <b>OpenTelemetry tracing</b> — click to expand</summary>
+
+Vector Graph RAG can emit OpenTelemetry spans for ingestion, loaders,
+embeddings, Milvus operations, retrieval, and generation. Configure the
+OpenTelemetry SDK/exporter in your application, then attach request context
+around RAG calls:
+
+```python
+from vector_graph_rag import VectorGraphRAG, observability_context
+
+rag = VectorGraphRAG(collection_prefix="my_project")
+
+with observability_context(
+    request_id="req-123",
+    tenant_id="tenant-a",
+    graph_name="my_project",
+    source="file-123",
+):
+    rag.upsert_documents_by_source(chunks, source="file-123")
+```
+
+The built-in spans avoid document text, prompts, query text, generated answers,
+filters, and full URLs by default. See the
+[Observability guide](docs/guides/observability.md) for setup details.
+
+</details>
+
 <details>
 <summary>🌐 <b>Import from URLs and files</b> — click to expand</summary>
 
@@ -284,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
 
@@ -308,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">
@@ -329,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:
@@ -397,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.1 → 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
 
@@ -65,6 +69,17 @@ uv add "vector-graph-rag[all]"
 
 </details>
 
+<details>
+<summary><b>With OpenTelemetry tracing</b></summary>
+
+```bash
+pip install "vector-graph-rag[observability]"
+# or
+uv add "vector-graph-rag[observability]"
+```
+
+</details>
+
 ## 🚀 Quick Start
 
 ```python
@@ -112,6 +127,8 @@ 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/guides/incremental-updates.md) for parser
+integration, source key design, and retry recommendations.
 
 ```python
 from langchain_core.documents import Document
@@ -121,7 +138,7 @@ rag.upsert_documents_by_source(
         Document(
             page_content="Einstein developed relativity at Princeton.",
             metadata={
-                "source": "sharepoint:file-123",
+                "source": "file:file-123",
                 "triplets": [
                     ["Einstein", "developed", "relativity"],
                     ["Einstein", "worked at", "Princeton"],
@@ -132,7 +149,7 @@ rag.upsert_documents_by_source(
     extract_triplets=False,
 )
 
-rag.delete_documents_by_source("sharepoint:file-123")
+rag.delete_documents_by_source("file:file-123")
 ```
 
 > **Migration note:** v0.1.5 exposed `upsert_documents(document_id=...)` and
@@ -146,6 +163,34 @@ for removal in v1.0.0. For explicit full refreshes, use `rebuild_texts()`,
 
 </details>
 
+<details>
+<summary>📈 <b>OpenTelemetry tracing</b> — click to expand</summary>
+
+Vector Graph RAG can emit OpenTelemetry spans for ingestion, loaders,
+embeddings, Milvus operations, retrieval, and generation. Configure the
+OpenTelemetry SDK/exporter in your application, then attach request context
+around RAG calls:
+
+```python
+from vector_graph_rag import VectorGraphRAG, observability_context
+
+rag = VectorGraphRAG(collection_prefix="my_project")
+
+with observability_context(
+    request_id="req-123",
+    tenant_id="tenant-a",
+    graph_name="my_project",
+    source="file-123",
+):
+    rag.upsert_documents_by_source(chunks, source="file-123")
+```
+
+The built-in spans avoid document text, prompts, query text, generated answers,
+filters, and full URLs by default. See the
+[Observability guide](docs/guides/observability.md) for setup details.
+
+</details>
+
 <details>
 <summary>🌐 <b>Import from URLs and files</b> — click to expand</summary>
 
@@ -194,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
 
@@ -218,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">
@@ -239,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:
@@ -307,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.1/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.1/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).