docs: add design philosophy, use cases, and enrich documentation

- Add design philosophy: no graph DB, single-pass LLM reranking,
  knowledge-intensive domain focus
- Add use cases page with domain examples (legal, finance, medical,
  literature, academic)
- Update README features to highlight key differentiators
- Enrich getting-started with collection_prefix and milvus_db usage
- Add comparison table with other RAG approaches

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: zc277584121

README.md

@@ -1,15 +1,15 @@
 # Vector Graph RAG
 
-🔗 A Graph RAG implementation using pure vector search with Milvus.
+Graph RAG with pure vector search — no graph database needed, single-pass LLM reranking, optimized for knowledge-intensive domains.
 
 ## ✨ Features
 
-- **🚀 No Graph Database Required** - Pure vector search approach, no need for Neo4j or other graph databases
-- **📦 Zero Configuration** - Uses Milvus Lite by default, works out of the box with a single file
-- **🎯 High Accuracy** - LLM-based reranking for precise relation filtering
-- **🔍 Multi-hop Reasoning** - Subgraph expansion enables complex multi-hop question answering
-- **📊 State-of-the-Art Performance** - Outperforms HippoRAG on multi-hop QA benchmarks (87.8% avg Recall@5)
-- **🛠️ Simple API** - Just 3 lines of code to get started
+- **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
 

docs/getting-started.md

@@ -33,16 +33,40 @@ print(result.answer)
 !!! note
     Set the `OPENAI_API_KEY` environment variable before running.
 
-## Custom Configuration
+## Configuration
+
+### Basic
 
 ```python
 rag = VectorGraphRAG(
-    milvus_uri="./my_data.db",
+    milvus_uri="./my_data.db",       # local file (Milvus Lite)
     llm_model="gpt-4o",
     embedding_model="text-embedding-3-large",
 )
 ```
 
+### With Remote Milvus
+
+```python
+rag = VectorGraphRAG(
+    milvus_uri="http://localhost:19530",
+    milvus_db="my_database",           # optional: specify database
+    collection_prefix="my_project",    # optional: isolate collections
+)
+```
+
+Collections will be named `my_project_vgrag_entities`, `my_project_vgrag_relations`, `my_project_vgrag_passages`.
+
+### Multiple Knowledge Bases
+
+Use `collection_prefix` to maintain separate graphs in the same Milvus instance:
+
+```python
+# Different documents → different prefixes
+legal_rag = VectorGraphRAG(milvus_uri="./data.db", collection_prefix="legal")
+finance_rag = VectorGraphRAG(milvus_uri="./data.db", collection_prefix="finance")
+```
+
 ## With Pre-extracted Triplets
 
 Skip LLM extraction if you already have knowledge graph triplets:
@@ -61,7 +85,7 @@ rag.add_documents_with_triplets([
 
 ## Import from URLs and Files
 
-Import web pages, PDFs, and other documents:
+Import web pages, PDFs, and other documents with automatic chunking:
 
 ```bash
 pip install "vector-graph-rag[loaders]"

docs/how-it-works.md

@@ -1,10 +1,46 @@
 # How It Works
 
-## Overview
+## Design Philosophy
 
-Vector Graph RAG builds a knowledge graph stored entirely in a vector database (Milvus). It uses vector similarity search instead of graph traversal to find relevant entities and relations, eliminating the need for a separate graph database.
+Vector Graph RAG is built on three key principles:
 
-## Indexing Pipeline
+### 1. No Graph Database
+
+Traditional Graph RAG systems store knowledge in a graph database (Neo4j, ArangoDB, etc.) and use graph traversal queries (Cypher, Gremlin) to retrieve relevant subgraphs. This adds operational complexity: another database to deploy, a query language to learn, schema to maintain.
+
+We store the entire knowledge graph — entities, relations, and passages — as vectors in Milvus. Retrieval becomes vector similarity search, which is simple, scalable, and requires no additional infrastructure.
+
+### 2. Single-Pass LLM Reranking
+
+Many RAG systems use iterative, agentic retrieval — the LLM decides what to retrieve next, reflects on results, and repeats. For example:
+
+- **IRCoT** (Interleaving Retrieval with Chain-of-Thought) alternates between retrieval and reasoning over multiple rounds
+- **Self-RAG** uses the LLM to critique and re-retrieve documents
+- **Agentic RAG** gives the LLM tools to search iteratively
+
+These approaches are powerful but expensive — each iteration costs an LLM call, adding latency and cost.
+
+Vector Graph RAG uses a **single LLM reranking pass**. After vector search and subgraph expansion produce candidate relations, the LLM scores them once. This is sufficient because the vector search + subgraph expansion already provides high-quality candidates, and a single reranking step can effectively filter the best results.
+
+### 3. Knowledge-Intensive Domains
+
+Vector Graph RAG is especially effective for **knowledge-intensive content** — documents where dense factual relationships are the core value:
+
+| Domain | Why Graph RAG Helps |
+|--------|-------------------|
+| **Legal** | Statutes reference other statutes, precedents cite precedents — graph captures these cross-references |
+| **Finance** | Company relationships, ownership chains, transaction flows form natural graphs |
+| **Medical** | Drug interactions, symptom-disease-treatment pathways are inherently relational |
+| **Literature** | Character relationships, plot connections, thematic links across chapters |
+| **Academic** | Citation networks, concept dependencies, methodology chains |
+
+In these domains, naive RAG often fails because the answer requires connecting facts across multiple documents. The knowledge graph captures these connections explicitly.
+
+---
+
+## Architecture
+
+### Indexing Pipeline
 
 ```mermaid
 flowchart LR
@@ -18,7 +54,7 @@ flowchart LR
 2. **Entity & Relation Storage** — Entities and relations are stored as vectors in Milvus collections.
 3. **Embedding** — All text is embedded for vector similarity search.
 
-## Query Pipeline
+### Query Pipeline
 
 ```mermaid
 flowchart LR
@@ -32,7 +68,7 @@ flowchart LR
 1. **Entity Extraction** — Extract key entities from the user's question.
 2. **Vector Search** — Find similar entities and relations in Milvus.
 3. **Subgraph Expansion** — Collect candidate relations by expanding around matched entities.
-4. **LLM Reranking** — Use an LLM to score and filter the most relevant relations.
+4. **LLM Reranking** — Use an LLM to score and filter the most relevant relations (single pass).
 5. **Answer Generation** — Generate the final answer from the selected context.
 
 ## Worked Example
@@ -57,13 +93,23 @@ flowchart TD
     VS --> SE["Subgraph expansion → candidate relations"]
     SE --> R1["(Einstein, developed, theory of relativity)"]
     SE --> R2["(Einstein, worked at, Princeton)"]
-    R1 --> LLM["LLM reranking"]
+    R1 --> LLM["LLM reranking (single pass)"]
     R2 --> LLM
-    LLM --> A["✅ Einstein developed the theory of relativity."]
+    LLM --> A["Einstein developed the theory of relativity."]
 ```
 
 1. Extract entity: `Einstein`
 2. Vector search finds similar entities and relations
 3. Subgraph expansion collects candidate relations
-4. **LLM reranking** selects `(Einstein, developed, theory of relativity)`
+4. **LLM reranking** selects `(Einstein, developed, theory of relativity)` — one call, no iteration
 5. Generate answer: *"Einstein developed the theory of relativity."*
+
+## Comparison with Other Approaches
+
+| Approach | Graph DB | LLM Calls per Query | Iterative | Complexity |
+|----------|----------|---------------------|-----------|------------|
+| **Naive RAG** | No | 1 (generation) | No | Low |
+| **IRCoT** | No | Multiple (retrieve + reason loops) | Yes | High |
+| **HippoRAG** | No | 1-2 | No | Medium |
+| **Microsoft GraphRAG** | Yes (Neo4j) | Multiple | Yes | High |
+| **Vector Graph RAG** | **No** | **2** (rerank + generation) | **No** | **Low** |

docs/index.md

@@ -1,15 +1,25 @@
 # Vector Graph RAG
 
-A Graph RAG implementation using pure vector search with [Milvus](https://milvus.io/).
+Graph RAG with pure vector search — no graph database needed, single-pass LLM reranking, optimized for knowledge-intensive domains.
+
+## Why Vector Graph RAG?
+
+Most Graph RAG systems require a dedicated graph database (Neo4j, etc.) and complex multi-step retrieval with iterative LLM calls. Vector Graph RAG takes a fundamentally different approach:
+
+- **No graph database** — The entire knowledge graph lives in Milvus as vectors. No extra infrastructure, no schema management, no graph query language.
+- **Single-pass reranking** — Unlike agentic approaches (IRCoT, multi-step reflection), we call the LLM just once to rerank candidate relations. This is simpler, faster, and cheaper.
+- **Knowledge-intensive friendly** — Designed for domains where dense factual knowledge matters: legal documents, financial reports, medical literature, novels, and more.
 
 ## Features
 
-- **No Graph Database Required** — Pure vector search approach, no need for Neo4j or other graph databases
-- **Zero Configuration** — Uses Milvus Lite by default, works out of the box with a single file
-- **High Accuracy** — LLM-based reranking for precise relation filtering
-- **Multi-hop Reasoning** — Subgraph expansion enables complex multi-hop question answering
-- **State-of-the-Art Performance** — Outperforms HippoRAG on multi-hop QA benchmarks (87.8% avg Recall@5)
-- **Simple API** — Just 3 lines of code to get started
+| | |
+|---|---|
+| **No Graph Database** | Pure vector search with Milvus — no Neo4j, no ArangoDB, no extra infra |
+| **Single-Pass Reranking** | One LLM call, no iterative agent loops like IRCoT |
+| **Knowledge-Intensive** | Optimized for legal, finance, medical, literature domains |
+| **Zero Configuration** | Milvus Lite by default, works out of the box |
+| **Multi-hop Reasoning** | Subgraph expansion for complex multi-hop QA |
+| **State-of-the-Art** | 87.8% avg Recall@5 on standard benchmarks |
 
 ## Quick Example
 
@@ -27,7 +37,7 @@ result = rag.query("What did Einstein develop?")
 print(result.answer)
 ```
 
-## Performance at a Glance
+## Performance
 
 | Method | MuSiQue | HotpotQA | 2WikiMultiHopQA | Average |
 |--------|---------|----------|-----------------|---------|

docs/use-cases.md

@@ -0,0 +1,130 @@
+# Use Cases
+
+Vector Graph RAG is designed for **knowledge-intensive domains** where documents contain dense factual relationships and answers often require connecting information across multiple sources.
+
+## When to Use Graph RAG vs Naive RAG
+
+**Use Naive RAG when:**
+
+- Questions can be answered from a single passage
+- Content is self-contained (e.g., FAQ, product docs)
+- Low latency is critical and accuracy trade-off is acceptable
+
+**Use Vector Graph RAG when:**
+
+- Answers require connecting facts across multiple documents
+- Content has rich entity relationships (people, organizations, concepts)
+- Multi-hop reasoning is needed ("Who worked with X at Y?")
+- Domain has dense factual knowledge
+
+## Domain Examples
+
+### Legal
+
+Legal documents are full of cross-references: statutes cite other statutes, court opinions reference precedents, contracts refer to defined terms across sections.
+
+```python
+rag = VectorGraphRAG(collection_prefix="legal_contracts")
+
+rag.add_texts([
+    "Section 3.1 defines the indemnification obligations of the Seller.",
+    "Under Section 5.2, breach of Section 3.1 triggers termination rights.",
+    "The Buyer may exercise termination rights within 30 days of notice.",
+])
+
+result = rag.query("What happens if the Seller breaches indemnification obligations?")
+# Graph connects: Seller → indemnification (3.1) → breach triggers termination (5.2) → 30 days
+```
+
+### Finance
+
+Financial data forms natural graphs: companies own subsidiaries, executives serve on boards, transactions flow between entities.
+
+```python
+rag = VectorGraphRAG(collection_prefix="financial_reports")
+
+rag.add_texts([
+    "Berkshire Hathaway acquired See's Candies in 1972 for $25 million.",
+    "See's Candies generated $383 million in pre-tax earnings by 2007.",
+    "Warren Buffett has called See's the ideal business.",
+])
+
+result = rag.query("How has Berkshire's candy acquisition performed?")
+# Graph connects: Berkshire → acquired See's → earnings growth → Buffett's assessment
+```
+
+### Medical & Biomedical
+
+Drug interactions, symptom-disease-treatment pathways, and clinical trial relationships are inherently relational.
+
+```python
+rag = VectorGraphRAG(collection_prefix="medical_literature")
+
+rag.add_texts([
+    "Metformin is the first-line treatment for type 2 diabetes.",
+    "Patients on metformin should have renal function monitored.",
+    "Impaired renal function may require dose adjustment or alternative therapy.",
+])
+
+result = rag.query("What monitoring is needed for first-line diabetes treatment?")
+# Graph connects: diabetes → metformin (first-line) → renal monitoring → dose adjustment
+```
+
+### Literature & Novels
+
+Character relationships, plot events, and thematic connections across chapters benefit from graph representation.
+
+```python
+from vector_graph_rag.loaders import DocumentImporter
+
+importer = DocumentImporter(chunk_size=1500, chunk_overlap=200)
+result = importer.import_sources(["/path/to/novel.pdf"])
+
+rag = VectorGraphRAG(collection_prefix="novel_analysis")
+rag.add_documents(result.documents, extract_triplets=True)
+
+result = rag.query("How does the protagonist's relationship with the antagonist evolve?")
+# Graph captures character interactions across the entire novel
+```
+
+### Academic Research
+
+Citation networks, concept dependencies, and cross-paper methodology comparisons.
+
+```python
+from vector_graph_rag.loaders import DocumentImporter
+
+importer = DocumentImporter(chunk_size=1000, chunk_overlap=200)
+result = importer.import_sources([
+    "/path/to/paper1.pdf",
+    "/path/to/paper2.pdf",
+    "/path/to/paper3.pdf",
+])
+
+rag = VectorGraphRAG(collection_prefix="research_survey")
+rag.add_documents(result.documents, extract_triplets=True)
+
+result = rag.query("What methods achieve the best performance on this task?")
+# Graph connects methods, results, and comparisons across papers
+```
+
+## Organizing Multiple Knowledge Bases
+
+Use `collection_prefix` to separate different document sets in the same Milvus instance:
+
+```python
+# Each domain gets its own isolated graph
+legal_rag = VectorGraphRAG(milvus_uri="http://localhost:19530", collection_prefix="legal")
+finance_rag = VectorGraphRAG(milvus_uri="http://localhost:19530", collection_prefix="finance")
+medical_rag = VectorGraphRAG(milvus_uri="http://localhost:19530", collection_prefix="medical")
+```
+
+Or use `milvus_db` for database-level isolation:
+
+```python
+rag = VectorGraphRAG(
+    milvus_uri="http://localhost:19530",
+    milvus_db="production",
+    collection_prefix="legal_v2",
+)
+```

mkdocs.yml

@@ -46,4 +46,5 @@ nav:
   - Home: index.md
   - Getting Started: getting-started.md
   - How It Works: how-it-works.md
+  - Use Cases: use-cases.md
   - Evaluation: evaluation.md