vector-graph-rag 0.1.4__tar.gz → 0.2.0__tar.gz

vector_graph_rag-0.2.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

vector_graph_rag-0.2.0/CLAUDE.md

@@ -0,0 +1,92 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Vector Graph RAG implements Graph RAG using **pure vector search in Milvus** — no graph database (Neo4j etc.). Knowledge-graph entities and relations are stored as vectors; the graph's adjacency is encoded as ID lists in each record's metadata, and "graph traversal" is implemented as repeated `query`/`search` calls against Milvus by those IDs. The key algorithmic bet is replacing iterative LLM agent loops (IRCoT, multi-step reflection) with a **single-pass LLM reranking** step.
+
+## Commands
+
+This is a `uv` + `pyproject.toml` project. Use `uv` directly — never `pip` or `uv pip`.
+
+```bash
+uv sync --extra dev          # install with dev deps (pytest, ruff)
+uv sync --extra all          # everything (dev + api + hf)
+
+uv run pytest                # run all tests
+uv run pytest tests/test_graph.py            # single file
+uv run pytest tests/test_graph.py::test_name # single test
+uv run pytest -k metadata_filter             # by keyword
+
+uv run ruff check .          # lint
+uv run ruff format .         # format
+
+# API server (canonical entrypoint — used by README and Dockerfile)
+uv sync --extra api
+uv run uvicorn vector_graph_rag.api.app:app --host 0.0.0.0 --port 8000
+
+# Frontend (React + Vite)
+cd frontend && npm install && npm run dev
+
+# Evaluation (multi-hop QA benchmarks)
+uv run python evaluation/evaluate.py --dataset musique --method graph
+```
+
+Tests mock OpenAI and use Milvus Lite (a temp `.db` file per test via the `temp_milvus_uri` fixture in `tests/conftest.py`), so they run offline with no API key. `asyncio_mode = "auto"`, so async tests need no decorator.
+
+## Architecture
+
+### Indexing → Query pipeline
+
+```
+add_documents:  Documents → TripletExtractor (LLM) → GraphBuilder → embeddings → MilvusStore
+query:          Question → EntityExtractor → vector search → SubGraph.expand → LLMReranker → AnswerGenerator
+```
+
+`VectorGraphRAG` (`src/vector_graph_rag/rag.py`) is the user-facing facade that wires these components together. Read it first — its `add_documents` and `query` methods are the spine of the whole system.
+
+### Three Milvus collections
+
+`MilvusStore` (`storage/milvus.py`) manages **three collections** — `entities`, `relations`, `passages` (prefixed by `collection_prefix`). The graph structure lives entirely in metadata:
+
+- **Entity** metadata → `relation_ids`, `passage_ids`
+- **Relation** metadata → `entity_ids` (head, tail), `passage_ids`, plus structured `subject`/`predicate`/`object`
+- **Passage** metadata → `entity_ids`, `relation_ids`, **plus arbitrary user metadata** (used for the `filter` feature)
+
+Subgraph expansion (`graph/knowledge_graph.py`, `SubGraph`) is **lazy**: it holds IDs and fetches neighbor records from Milvus on demand during `expand(degree=...)` rather than loading the full graph into memory.
+
+### Important data-flow detail
+
+`add_documents` **drops and recreates all collections every call** (`rag.py` ~line 403) — it is a full rebuild, not an append. The retriever (`self._retriever`) is reset to `None` after any add and lazily rebuilt on the next query via `_ensure_retriever()`.
+
+### Retrieval specifics (`graph/retriever.py`)
+
+- Entity and relation searches each apply a **similarity threshold** (`entity_similarity_threshold` default `0.9`; relation default `-1.0` = keep all). Scores are kept when `score > threshold`.
+- **Eviction strategy**: if expanded relations exceed `relation_number_threshold` (default 1000), a vector search re-ranks them down to the threshold. Below it, relations are sorted by ID to match HippoRAG's deterministic behavior.
+- The `filter` parameter (a Milvus filter expression on passage metadata) flows through retrieval by first resolving allowed passage IDs, then filtering relations to those touching an allowed passage.
+
+### Component map
+
+- `llm/extractor.py` — `TripletExtractor` (doc → triplets) and `EntityExtractor` (query → entities); `processing_phrases` normalizes entity strings. Has an NER cache for evaluation (HippoRAG TSV format).
+- `llm/reranker.py` — `LLMReranker` (single-pass relation reranking) and `AnswerGenerator`.
+- `llm/cache.py` — disk cache for LLM responses (`use_llm_cache`).
+- `graph/builder.py` — `GraphBuilder` turns triplets into entity/relation/passage records + adjacency maps.
+- `graph/graph.py` — `Graph`, a higher-level CRUD interface over `MilvusStore` (used mainly by the API layer); entity/relation methods are private, users work at the passage level.
+- `storage/embeddings.py` — `EmbeddingModel`, supports OpenAI and (optional `[hf]` extra) HuggingFace models.
+
+### Configuration
+
+`config.py` `Settings` is a pydantic-settings `BaseSettings`. All settings read from env with the **`VGRAG_` prefix** (e.g. `VGRAG_LLM_MODEL`) or a `.env` file. `VectorGraphRAG.__init__` kwargs override env. The OpenAI key falls back to plain `OPENAI_API_KEY`. Note the default `embedding_model` is `text-embedding-3-large` (dimension 3072) in `Settings`, while the `create_rag` factory and docstrings default to `text-embedding-3-small` — keep `embedding_dimension` consistent with whatever model you set.
+
+### Two API directories — do not confuse them
+
+- `src/vector_graph_rag/api/app.py` — **the canonical, packaged API.** This is what the README, Dockerfile, and `uvicorn vector_graph_rag.api.app:app` use. Edit this one.
+- `api/` (repo root) — a separate standalone variant with a `sys.path` hack and its own `schemas.py`. Not the packaged entrypoint; treat as legacy unless a task explicitly concerns it.
+
+## Conventions
+
+- Code and comments in English. User-facing replies follow the user's language.
+- Methods prefixed with `_` on `MilvusStore`/`Graph` (e.g. `_insert_entities`, `_search_relations`) are internal entity/relation operations — the intended public surface is passage-level.
+- `Document` is `langchain_core.documents.Document`; pre-extracted triplets are passed via `metadata["triplets"]` as `[subject, predicate, object]` lists.
+- PyTorch install index is backend-specific (CPU on macOS/arm Linux, CUDA 12.4 on x86 Linux) via `[tool.uv.sources]`; the Dockerfile rewrites this based on the `TORCH_BACKEND` build arg.

{vector_graph_rag-0.1.4 → vector_graph_rag-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vector-graph-rag
-Version: 0.1.4
+Version: 0.2.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/
@@ -33,13 +33,24 @@ Requires-Dist: tenacity>=8.2.0
 Requires-Dist: tiktoken>=0.5.0
 Requires-Dist: tqdm>=4.65.0
 Provides-Extra: all
+Requires-Dist: einops>=0.8.2; extra == 'all'
 Requires-Dist: fastapi>=0.109.0; extra == 'all'
+Requires-Dist: google-genai>=1.0; extra == 'all'
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: huggingface-hub>=0.20; extra == 'all'
+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: 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: sentence-transformers>=3.0; extra == 'all'
+Requires-Dist: tokenizers>=0.15; extra == 'all'
 Requires-Dist: torch>=2.0.0; extra == 'all'
 Requires-Dist: transformers>=4.30.0; extra == 'all'
 Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'all'
+Requires-Dist: voyageai>=0.3; extra == 'all'
 Provides-Extra: api
 Requires-Dist: fastapi>=0.109.0; extra == 'api'
 Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'api'
@@ -49,13 +60,32 @@ 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: 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: jina
+Requires-Dist: httpx>=0.27; extra == 'jina'
 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'
+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: mistral
+Requires-Dist: mistralai>=1.0; extra == 'mistral'
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.4; extra == 'ollama'
+Provides-Extra: onnx
+Requires-Dist: huggingface-hub>=0.20; extra == 'onnx'
+Requires-Dist: onnxruntime<1.24,>=1.17; (python_version == '3.10') and extra == 'onnx'
+Requires-Dist: onnxruntime>=1.17; (python_version >= '3.11') and extra == 'onnx'
+Requires-Dist: tokenizers>=0.15; extra == 'onnx'
+Provides-Extra: voyage
+Requires-Dist: voyageai>=0.3; extra == 'voyage'
 Description-Content-Type: text/markdown
 
 <h1 align="center">
@@ -112,12 +142,15 @@ uv add "vector-graph-rag[loaders]"
 </details>
 
 <details>
-<summary><b>With local HuggingFace embedding models</b></summary>
+<summary><b>With additional embedding providers</b></summary>
 
 ```bash
-pip install "vector-graph-rag[hf]"
+pip install "vector-graph-rag[hf]"       # HuggingFace transformers
+pip install "vector-graph-rag[ollama]"   # Ollama
+pip install "vector-graph-rag[jina]"     # Jina AI
+pip install "vector-graph-rag[all]"      # all optional providers
 # or
-uv add "vector-graph-rag[hf]"
+uv add "vector-graph-rag[all]"
 ```
 
 </details>
@@ -129,7 +162,7 @@ from vector_graph_rag import VectorGraphRAG
 
 rag = VectorGraphRAG()  # reads OPENAI_API_KEY from environment
 
-rag.add_texts([
+rag.rebuild_texts([
     "Albert Einstein developed the theory of relativity.",
     "The theory of relativity revolutionized our understanding of space and time.",
 ])
@@ -146,7 +179,7 @@ print(result.answer)
 Skip LLM extraction if you already have knowledge graph triplets:
 
 ```python
-rag.add_documents_with_triplets([
+rag.rebuild_documents_with_triplets([
     {
         "passage": "Einstein developed relativity at Princeton.",
         "triplets": [
@@ -159,6 +192,47 @@ rag.add_documents_with_triplets([
 
 </details>
 
+<details>
+<summary>🔄 <b>Incremental document updates</b> — click to expand</summary>
+
+Use `upsert_documents_by_source()` when a source file, message, or page is
+created or modified. In Vector Graph RAG, a `Document` is a passage/chunk; the
+source object is identified by `metadata["source"]` or the explicit `source`
+argument. The method replaces only that source's chunks and graph references.
+
+```python
+from langchain_core.documents import Document
+
+rag.upsert_documents_by_source(
+    documents=[
+        Document(
+            page_content="Einstein developed relativity at Princeton.",
+            metadata={
+                "source": "sharepoint:file-123",
+                "triplets": [
+                    ["Einstein", "developed", "relativity"],
+                    ["Einstein", "worked at", "Princeton"],
+                ],
+            },
+        ),
+    ],
+    extract_triplets=False,
+)
+
+rag.delete_documents_by_source("sharepoint:file-123")
+```
+
+> **Migration note:** v0.1.5 exposed `upsert_documents(document_id=...)` and
+> `delete_documents(document_id)`. These names were removed in v0.2.0 because
+> `Document` means passage/chunk in this project. Use the `*_by_source()` APIs
+> shown above.
+
+The legacy `add_*` ingestion helpers rebuild the full knowledge base and are planned
+for removal in v1.0.0. For explicit full refreshes, use `rebuild_texts()`,
+`rebuild_documents()`, or `rebuild_documents_with_triplets()`.
+
+</details>
+
 <details>
 <summary>🌐 <b>Import from URLs and files</b> — click to expand</summary>
 
@@ -175,7 +249,7 @@ result = importer.import_sources([
 ])
 
 rag = VectorGraphRAG(milvus_uri="./my_graph.db")
-rag.add_documents(result.documents, extract_triplets=True)
+rag.rebuild_documents(result.documents, extract_triplets=True)
 
 result = rag.query("What did Einstein discover?")
 print(result.answer)
@@ -190,6 +264,7 @@ print(result.answer)
 rag = VectorGraphRAG(
     milvus_uri="./my_data.db",          # or remote Milvus / Zilliz Cloud
     llm_model="gpt-4o",
+    embedding_provider="openai",
     embedding_model="text-embedding-3-large",
     collection_prefix="my_project",     # isolate multiple datasets
 )
@@ -199,6 +274,7 @@ All settings can also be configured via environment variables with `VGRAG_` pref
 
 ```bash
 VGRAG_LLM_MODEL=gpt-4o
+VGRAG_EMBEDDING_PROVIDER=openai
 VGRAG_EMBEDDING_MODEL=text-embedding-3-large
 VGRAG_MILVUS_URI=http://localhost:19530
 ```

{vector_graph_rag-0.1.4 → vector_graph_rag-0.2.0}/README.md

@@ -52,12 +52,15 @@ uv add "vector-graph-rag[loaders]"
 </details>
 
 <details>
-<summary><b>With local HuggingFace embedding models</b></summary>
+<summary><b>With additional embedding providers</b></summary>
 
 ```bash
-pip install "vector-graph-rag[hf]"
+pip install "vector-graph-rag[hf]"       # HuggingFace transformers
+pip install "vector-graph-rag[ollama]"   # Ollama
+pip install "vector-graph-rag[jina]"     # Jina AI
+pip install "vector-graph-rag[all]"      # all optional providers
 # or
-uv add "vector-graph-rag[hf]"
+uv add "vector-graph-rag[all]"
 ```
 
 </details>
@@ -69,7 +72,7 @@ from vector_graph_rag import VectorGraphRAG
 
 rag = VectorGraphRAG()  # reads OPENAI_API_KEY from environment
 
-rag.add_texts([
+rag.rebuild_texts([
     "Albert Einstein developed the theory of relativity.",
     "The theory of relativity revolutionized our understanding of space and time.",
 ])
@@ -86,7 +89,7 @@ print(result.answer)
 Skip LLM extraction if you already have knowledge graph triplets:
 
 ```python
-rag.add_documents_with_triplets([
+rag.rebuild_documents_with_triplets([
     {
         "passage": "Einstein developed relativity at Princeton.",
         "triplets": [
@@ -99,6 +102,47 @@ rag.add_documents_with_triplets([
 
 </details>
 
+<details>
+<summary>🔄 <b>Incremental document updates</b> — click to expand</summary>
+
+Use `upsert_documents_by_source()` when a source file, message, or page is
+created or modified. In Vector Graph RAG, a `Document` is a passage/chunk; the
+source object is identified by `metadata["source"]` or the explicit `source`
+argument. The method replaces only that source's chunks and graph references.
+
+```python
+from langchain_core.documents import Document
+
+rag.upsert_documents_by_source(
+    documents=[
+        Document(
+            page_content="Einstein developed relativity at Princeton.",
+            metadata={
+                "source": "sharepoint:file-123",
+                "triplets": [
+                    ["Einstein", "developed", "relativity"],
+                    ["Einstein", "worked at", "Princeton"],
+                ],
+            },
+        ),
+    ],
+    extract_triplets=False,
+)
+
+rag.delete_documents_by_source("sharepoint:file-123")
+```
+
+> **Migration note:** v0.1.5 exposed `upsert_documents(document_id=...)` and
+> `delete_documents(document_id)`. These names were removed in v0.2.0 because
+> `Document` means passage/chunk in this project. Use the `*_by_source()` APIs
+> shown above.
+
+The legacy `add_*` ingestion helpers rebuild the full knowledge base and are planned
+for removal in v1.0.0. For explicit full refreshes, use `rebuild_texts()`,
+`rebuild_documents()`, or `rebuild_documents_with_triplets()`.
+
+</details>
+
 <details>
 <summary>🌐 <b>Import from URLs and files</b> — click to expand</summary>
 
@@ -115,7 +159,7 @@ result = importer.import_sources([
 ])
 
 rag = VectorGraphRAG(milvus_uri="./my_graph.db")
-rag.add_documents(result.documents, extract_triplets=True)
+rag.rebuild_documents(result.documents, extract_triplets=True)
 
 result = rag.query("What did Einstein discover?")
 print(result.answer)
@@ -130,6 +174,7 @@ print(result.answer)
 rag = VectorGraphRAG(
     milvus_uri="./my_data.db",          # or remote Milvus / Zilliz Cloud
     llm_model="gpt-4o",
+    embedding_provider="openai",
     embedding_model="text-embedding-3-large",
     collection_prefix="my_project",     # isolate multiple datasets
 )
@@ -139,6 +184,7 @@ All settings can also be configured via environment variables with `VGRAG_` pref
 
 ```bash
 VGRAG_LLM_MODEL=gpt-4o
+VGRAG_EMBEDDING_PROVIDER=openai
 VGRAG_EMBEDDING_MODEL=text-embedding-3-large
 VGRAG_MILVUS_URI=http://localhost:19530
 ```

{vector_graph_rag-0.1.4 → vector_graph_rag-0.2.0}/api/main.py

@@ -252,7 +252,7 @@ async def add_documents(documents: list[str]):
     """Add documents to the knowledge graph."""
     try:
         rag = get_rag()
-        rag.add_documents(documents)
+        rag.rebuild_texts(documents)
         return {"status": "ok", "message": f"Added {len(documents)} documents"}
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))

{vector_graph_rag-0.1.4 → vector_graph_rag-0.2.0}/docs/faq.md

@@ -37,11 +37,32 @@ Frequently asked questions about Vector Graph RAG — covering when to use it, c
     result = importer.import_sources(["/path/to/large_document.pdf"])
 
     rag = VectorGraphRAG(milvus_uri="./my_graph.db")
-    rag.add_documents(result.documents, extract_triplets=True)
+    rag.rebuild_documents(result.documents, extract_triplets=True)
     ```
 
     For very large corpora, consider using a remote Milvus instance rather than Milvus Lite for better performance and scalability.
 
+??? note "How do I update or delete one source document?"
+    Use `upsert_documents_by_source()` for source create/update and `delete_documents_by_source()` for delete. A source can be a file, web page, message, or another business-level object. Its parsed chunks are passed as LangChain `Document` objects, and each chunk should carry the same stable `metadata["source"]` value.
+
+    ```python
+    from langchain_core.documents import Document
+
+    rag.upsert_documents_by_source(
+        documents=[
+            Document(
+                page_content="Updated document chunk text.",
+                metadata={"source": "file-123", "page": 1},
+            )
+        ],
+        extract_triplets=True,
+    )
+
+    rag.delete_documents_by_source("file-123")
+    ```
+
+    Incremental updates replace only the chunks and graph references for that source value. They are not transactionally atomic, so avoid interrupting or concurrently mutating the same collection prefix during an update.
+
 ??? note "Can I use local/open-source LLMs?"
     Yes. Vector Graph RAG uses the OpenAI-compatible API format, so any LLM that exposes an OpenAI-compatible endpoint will work. This includes local models served via [Ollama](https://ollama.com/), [vLLM](https://github.com/vllm-project/vllm), [LM Studio](https://lmstudio.ai/), or any other OpenAI-compatible server. You can configure the base URL and model name when initializing the RAG instance. Keep in mind that triplet extraction and reranking quality depend heavily on the LLM's capability — weaker models may produce incomplete or inaccurate triplets, which directly affects retrieval quality. For best results, use a model with strong instruction-following and reasoning abilities.
 
@@ -70,7 +91,11 @@ Frequently asked questions about Vector Graph RAG — covering when to use it, c
     ```
 
 ??? note "Can I use my own embeddings?"
-    Vector Graph RAG uses OpenAI embedding models by default (`text-embedding-3-large`), but you can configure the embedding model via the `embedding_model` parameter. Any model accessible through the OpenAI-compatible API will work. If you are using a local HuggingFace embedding model, install the optional dependencies with `pip install "vector-graph-rag[hf]"`. The embedding dimensionality is detected automatically. Note that all entities, relations, and passages in a single graph must use the same embedding model — mixing models within one collection prefix is not supported.
+    Yes. New applications should set both `embedding_provider` and `embedding_model`.
+    Supported providers are `openai`, `huggingface`, `google`/`gemini`, `voyage`, `jina`, `mistral`, `ollama`, `local`, and `onnx`.
+    Install the matching optional extra, such as `vector-graph-rag[hf]`, `vector-graph-rag[ollama]`, or `vector-graph-rag[all]`.
+    If `embedding_provider` is omitted, Vector Graph RAG keeps a legacy provider inference path for compatibility, but that path is deprecated and planned for removal in v1.0.0.
+    The embedding dimensionality is detected automatically. All entities, relations, and passages in a single graph must use the same embedding provider and model — mixing embeddings within one collection prefix is not supported.
 
 ??? note "How do I deploy to production?"
     For production deployments, use a remote Milvus instance instead of Milvus Lite for better performance, scalability, and persistence. Run the FastAPI backend behind a reverse proxy (e.g., Nginx) with appropriate rate limiting and authentication. The frontend can be built as static files and served from any CDN or static file server.

{vector_graph_rag-0.1.4 → vector_graph_rag-0.2.0}/docs/getting-started.md

@@ -26,6 +26,12 @@
     pip install "vector-graph-rag[hf]"
     ```
 
+=== "With all embedding providers"
+
+    ```bash
+    pip install "vector-graph-rag[all]"
+    ```
+
 !!! note "Prerequisites"
     - Python 3.9+
     - An OpenAI API key (set `OPENAI_API_KEY` environment variable)
@@ -37,7 +43,7 @@ from vector_graph_rag import VectorGraphRAG
 
 rag = VectorGraphRAG()  # reads OPENAI_API_KEY from environment
 
-rag.add_texts([
+rag.rebuild_texts([
     "Albert Einstein developed the theory of relativity.",
     "The theory of relativity revolutionized our understanding of space and time.",
 ])
@@ -57,6 +63,7 @@ print(result.answer)
 rag = VectorGraphRAG(
     milvus_uri="./my_data.db",                    # local file (Milvus Lite)
     llm_model="gpt-4o",                           # LLM for extraction and reranking
+    embedding_provider="openai",                  # embedding provider
     embedding_model="text-embedding-3-large",      # embedding model
 )
 ```
@@ -126,10 +133,13 @@ finance_rag = VectorGraphRAG(milvus_uri="./data.db", collection_prefix="finance"
 
 ## Adding Documents
 
+!!! warning "Full rebuild vs incremental updates"
+    `add_texts()`, `add_documents()`, and `add_documents_with_triplets()` rebuild the full knowledge base for the current collection prefix. These legacy convenience APIs are planned for removal in v1.0.0. Use `rebuild_texts()`, `rebuild_documents()`, or `rebuild_documents_with_triplets()` for full refreshes. For source create/update/delete flows, use `upsert_documents_by_source()` and `delete_documents_by_source()`.
+
 ### From Text Strings
 
 ```python
-rag.add_texts([
+rag.rebuild_texts([
     "Einstein developed relativity at Princeton.",
     "The theory changed modern physics.",
 ])
@@ -140,7 +150,7 @@ rag.add_texts([
 Skip LLM extraction if you already have knowledge graph triplets:
 
 ```python
-rag.add_documents_with_triplets([
+rag.rebuild_documents_with_triplets([
     {
         "passage": "Einstein developed relativity at Princeton.",
         "triplets": [
@@ -166,12 +176,44 @@ result = importer.import_sources([
 ])
 
 rag = VectorGraphRAG(milvus_uri="./my_graph.db")
-rag.add_documents(result.documents, extract_triplets=True)
+rag.rebuild_documents(result.documents, extract_triplets=True)
 ```
 
 !!! warning "Loader dependencies"
     Install with `pip install "vector-graph-rag[loaders]"` to enable URL fetching and document conversion.
 
+### Incremental Updates
+
+Use `upsert_documents_by_source()` when a source file, page, or message is created or modified. In Vector Graph RAG, a `Document` is a passage/chunk, and `metadata["source"]` identifies the source object whose chunks should be replaced.
+
+```python
+from langchain_core.documents import Document
+
+rag.upsert_documents_by_source(
+    documents=[
+        Document(
+            page_content="Einstein developed relativity at Princeton.",
+            metadata={
+                "source": "sharepoint:file-123",
+                "triplets": [
+                    ["Einstein", "developed", "relativity"],
+                    ["Einstein", "worked at", "Princeton"],
+                ],
+            },
+        )
+    ],
+    extract_triplets=False,
+)
+
+rag.delete_documents_by_source("sharepoint:file-123")
+```
+
+!!! warning "v0.2.0 migration"
+    `upsert_documents(document_id=...)` and `delete_documents(document_id)` were removed because `Document` means passage/chunk in this project. Use `upsert_documents_by_source()` and `delete_documents_by_source()` with a stable `metadata["source"]` value instead.
+
+!!! note "Consistency model"
+    Incremental updates perform a source-level cascade across passages, entities, and relations. They are not transactionally atomic, so avoid interrupting or concurrently mutating the same collection prefix during an update.
+
 ## Querying
 
 ### Full Query Result

{vector_graph_rag-0.1.4 → vector_graph_rag-0.2.0}/docs/how-it-works.md

@@ -223,4 +223,4 @@ flowchart TD
     Triplet extraction and reranking quality depends heavily on the underlying LLM's capability. Weaker models may produce incomplete or inaccurate triplets, which directly affects retrieval quality.
 
 !!! warning "Graph Consistency"
-    The knowledge graph topology is maintained as a logical layer on top of Milvus via cross-referenced ID fields. Since Milvus does not support transactions, multi-step mutations (e.g., cascade deletes) are not atomic and may leave inconsistent state if interrupted. For best results, prefer batch construction via `add_documents()` over frequent incremental updates.
+    The knowledge graph topology is maintained as a logical layer on top of Milvus via cross-referenced ID fields. Since Milvus does not support transactions, multi-step mutations (e.g., source-level cascade updates) are not atomic and may leave inconsistent state if interrupted. Use `rebuild_documents()` for initial bulk indexing or full refreshes, and use `upsert_documents_by_source()` / `delete_documents_by_source()` for source updates when the write operation is expected to run to completion.

{vector_graph_rag-0.1.4 → vector_graph_rag-0.2.0}/docs/index.md

@@ -104,7 +104,7 @@ from vector_graph_rag import VectorGraphRAG
 
 rag = VectorGraphRAG()  # reads OPENAI_API_KEY from environment
 
-rag.add_texts([
+rag.rebuild_texts([
     "Albert Einstein developed the theory of relativity.",
     "The theory of relativity revolutionized our understanding of space and time.",
 ])
@@ -113,6 +113,9 @@ result = rag.query("What did Einstein develop?")
 print(result.answer)
 ```
 
+!!! note "Ingestion semantics"
+    The legacy `add_*` ingestion helpers rebuild the full knowledge base and are planned for removal in v1.0.0. Use `rebuild_texts()`, `rebuild_documents()`, or `rebuild_documents_with_triplets()` for full refreshes, and use `upsert_documents_by_source()` / `delete_documents_by_source()` when a source file, page, or message changes later.
+
 !!! tip "Getting Started"
     See the [Getting Started](getting-started.md) guide for installation and configuration options.