Metadata-Version: 2.4
Name: vector-graph-rag
Version: 0.1.3
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/
Project-URL: Repository, https://github.com/zilliztech/vector-graph-rag
Author: zc277584121
License: MIT
License-File: LICENSE
Keywords: graph-rag,knowledge-graph,llm,milvus,rag,vector-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: milvus-lite>=2.4.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pymilvus<2.6.10,>=2.4.0
Requires-Dist: python-multipart>=0.0.22
Requires-Dist: scipy>=1.10.0
Requires-Dist: setuptools<71
Requires-Dist: tenacity>=8.2.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: torch>=2.0.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: transformers>=4.30.0
Provides-Extra: all
Requires-Dist: fastapi>=0.109.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'
Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'all'
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: 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: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
Provides-Extra: loaders
Requires-Dist: lxml-html-clean; extra == 'loaders'
Requires-Dist: markitdown[docx,pdf]>=0.1.4; extra == 'loaders'
Requires-Dist: trafilatura>=2.0.0; extra == 'loaders'
Description-Content-Type: text/markdown

<h1 align="center">
  <img src="https://github.com/user-attachments/assets/60afcee1-049a-4d2c-845d-8953b4fae083" alt="" width="120" valign="middle">
  <br>
  Vector Graph RAG
</h1>

<p align="center">
  <strong>Graph RAG with pure vector search — no graph database needed.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/vector-graph-rag/"><img src="https://img.shields.io/pypi/v/vector-graph-rag?style=flat-square&color=blue" alt="PyPI"></a>
  <a href="https://pypi.org/project/vector-graph-rag/"><img src="https://img.shields.io/badge/python-%3E%3D3.10-blue?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
  <a href="https://github.com/zilliztech/vector-graph-rag/blob/main/LICENSE"><img src="https://img.shields.io/github/license/zilliztech/vector-graph-rag?style=flat-square" alt="License"></a>
  <a href="https://zilliztech.github.io/vector-graph-rag/"><img src="https://img.shields.io/badge/docs-vector--graph--rag-blue?style=flat-square" alt="Docs"></a>
  <a href="https://github.com/zilliztech/vector-graph-rag/stargazers"><img src="https://img.shields.io/github/stars/zilliztech/vector-graph-rag?style=flat-square" alt="Stars"></a>
  <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.

<p align="center">
  <img src="https://github.com/user-attachments/assets/1185b651-ed72-4408-9dcd-25a74b12835b" alt="Vector Graph RAG Demo" width="800">
</p>

## ✨ 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)
- **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

## 📦 Installation

```bash
pip install vector-graph-rag
# or
uv add vector-graph-rag
```

<details>
<summary><b>With document loaders (PDF, DOCX, web pages)</b></summary>

```bash
pip install "vector-graph-rag[loaders]"
# or
uv add "vector-graph-rag[loaders]"
```

</details>

## 🚀 Quick Start

```python
from vector_graph_rag import VectorGraphRAG

rag = VectorGraphRAG()  # reads OPENAI_API_KEY from environment

rag.add_texts([
    "Albert Einstein developed the theory of relativity.",
    "The theory of relativity revolutionized our understanding of space and time.",
])

result = rag.query("What did Einstein develop?")
print(result.answer)
```

> **Note:** Set `OPENAI_API_KEY` environment variable before running.

<details>
<summary>📄 <b>With pre-extracted triplets</b> — click to expand</summary>

Skip LLM extraction if you already have knowledge graph triplets:

```python
rag.add_documents_with_triplets([
    {
        "passage": "Einstein developed relativity at Princeton.",
        "triplets": [
            ["Einstein", "developed", "relativity"],
            ["Einstein", "worked at", "Princeton"],
        ],
    },
])
```

</details>

<details>
<summary>🌐 <b>Import from URLs and files</b> — click to expand</summary>

```python
from vector_graph_rag import VectorGraphRAG
from vector_graph_rag.loaders import DocumentImporter

# Import from URLs, PDFs, DOCX, etc. (with automatic chunking)
importer = DocumentImporter(chunk_size=1000, chunk_overlap=200)
result = importer.import_sources([
    "https://en.wikipedia.org/wiki/Albert_Einstein",
    "/path/to/document.pdf",
    "/path/to/report.docx",
])

rag = VectorGraphRAG(milvus_uri="./my_graph.db")
rag.add_documents(result.documents, extract_triplets=True)

result = rag.query("What did Einstein discover?")
print(result.answer)
```

</details>

<details>
<summary>⚙️ <b>Custom configuration</b> — click to expand</summary>

```python
rag = VectorGraphRAG(
    milvus_uri="./my_data.db",          # or remote Milvus / Zilliz Cloud
    llm_model="gpt-4o",
    embedding_model="text-embedding-3-large",
    collection_prefix="my_project",     # isolate multiple datasets
)
```

All settings can also be configured via environment variables with `VGRAG_` prefix or a `.env` file:

```bash
VGRAG_LLM_MODEL=gpt-4o
VGRAG_EMBEDDING_MODEL=text-embedding-3-large
VGRAG_MILVUS_URI=http://localhost:19530
```

</details>

> 📖 Full Python API reference → [Python API docs](https://zilliztech.github.io/vector-graph-rag/python-api/)

## 🔬 How It Works

**Indexing:**

```
Documents → Triplet Extraction (LLM) → Entities + Relations → Embedding → Milvus
```

**Query:**

```
Question → Entity Extraction → Vector Search → Subgraph Expansion → LLM Reranking → Answer
```

**Example:** *"What did Einstein develop?"*

1. Extract entity: `Einstein`
2. Vector search finds similar entities and relations in Milvus
3. Subgraph expansion collects neighboring relations
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/)

## 📊 Evaluation Results

Evaluated 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">
</p>

| Method | MuSiQue | HotpotQA | 2WikiMultiHopQA | Average |
|--------|---------|----------|-----------------|---------|
| Naive RAG | 55.6% | 90.8% | 73.7% | 73.4% |
| IRCoT + HippoRAG¹ | 57.6% | 83.0% | 93.9% | 78.2% |
| HippoRAG 2² | **74.7%** | **96.3%** | 90.4% | 87.1% |
| **Vector Graph RAG** | 73.0% | **96.3%** | **94.1%** | **87.8%** |

¹ [HippoRAG (NeurIPS 2024)](https://arxiv.org/abs/2405.14831)  ² [HippoRAG 2 (2025)](https://arxiv.org/abs/2502.14802)

> 📖 Detailed analysis and reproduction steps → [Evaluation](https://zilliztech.github.io/vector-graph-rag/evaluation/)

## 🗄️ Milvus Backend

Just change `milvus_uri` to switch between deployment modes:

**Milvus Lite** (default) — zero config, single-process, data stored in a local file. Great for prototyping and small datasets:

```python
rag = VectorGraphRAG(milvus_uri="./my_graph.db")  # just works
```

⭐ **Zilliz Cloud** — fully managed, [free tier available](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=vector-graph-rag-readme) — [sign up](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=vector-graph-rag-readme) 👇:

```python
rag = VectorGraphRAG(
    milvus_uri="https://in03-xxx.api.gcp-us-west1.zillizcloud.com",
    milvus_token="your-api-key",
)
```

<details>
<summary>⭐ Sign up for a free Zilliz Cloud cluster</summary>

You can [sign up](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=vector-graph-rag-readme) on Zilliz Cloud to get a free cluster and API key.

![Sign up and get API key](https://raw.githubusercontent.com/zilliztech/CodeIndexer/master/assets/signup_and_get_apikey.png)

</details>

<details>
<summary>Self-hosted Milvus Server (Docker) — for advanced users</summary>

If you need a dedicated Milvus instance for multi-user or team environments, you can deploy Milvus standalone with Docker Compose. This requires Docker and some infrastructure knowledge. See the [official installation guide](https://milvus.io/docs/install_standalone-docker-compose.md) for detailed steps.

```python
rag = VectorGraphRAG(milvus_uri="http://localhost:19530")
```

</details>

## 🖥️ Frontend & REST API

Vector Graph RAG includes a React-based frontend for interactive graph visualization and a FastAPI backend.

```bash
# Backend
uv sync --extra api
uv run uvicorn vector_graph_rag.api.app:app --host 0.0.0.0 --port 8000

# Frontend
cd frontend && npm install && npm run dev
```

<p align="center">
  <img src="https://github.com/user-attachments/assets/8cc8e594-aed7-4ef5-8c3b-e5ff54275b64" alt="Frontend — interactive graph visualization with 4-step retrieval" width="800">
</p>

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/health` | GET | Health check |
| `/api/graphs` | GET | List available graphs |
| `/api/graph/{name}/stats` | GET | Get graph statistics |
| `/api/query` | POST | Query the knowledge graph |
| `/api/documents` | POST | Add documents |
| `/api/import` | POST | Import from URLs/paths |
| `/api/upload` | POST | Upload files |

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/)

## 📚 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
- [Milvus](https://milvus.io/) — the vector database powering Vector Graph RAG
- [FAQ](https://zilliztech.github.io/vector-graph-rag/faq/) — common questions and troubleshooting

## Contributing

Bug reports, feature requests, and pull requests are welcome! For questions and discussions, join us on [Discord](https://discord.com/invite/FG6hMJStWu).

## 📄 License

[MIT](LICENSE)
