{"repo": "bibinprathap/veritasgraph", "files": {"README.md": {"4c5b97f941b29f5086695bcce0061c42e04e378b": {"t": 1785674370.6760633, "n": 22437, "h": "e4153dc773009fbf", "c": "# VeritasGraph — The Governed, On-Prem GraphRAG & Agent Framework\r\n\r\n**Stop chunking blindly. Combine Tree-Search structure with Knowledge-Graph reasoning — and wire it into governed AI agents. Runs 100% locally or in the cloud.**\r\n\r\n<img src=\"https://github.com/bibinprathap/VeritasGraph/blob/restored-main/VeritasGraph.jpeg?raw=true\" alt=\"VeritasGraph Logo\" width=\"140\">\r\n\r\n[![PyPI version](https://badge.fury.io/py/veritasgraph.svg)](https://badge.fury.io/py/veritasgraph)\r\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n[![CI](https://github.com/bibinprathap/VeritasGraph/actions/workflows/ci.yml/badge.svg)](https://github.com/bibinprathap/VeritasGraph/actions)\r\n[![GitHub Stars](https://img.shields.io/github/stars/bibinprathap/VeritasGraph?style=social)](https://github.com/bibinprathap/VeritasGraph)\r\n\r\n> **🎯 Traditional RAG guesses based on similarity. VeritasGraph reasons based on structure.**\r\n> Don't just find the document — understand the connection, then act on it with governed agents.\r\n\r\n⭐ [Star](https://github.com/bibinprathap/VeritasGraph) · 🍴 [Fork](https://github.com/bibinprathap/VeritasGraph/fork) · 💬 [Discuss](https://github.com/bibinprathap/VeritasGraph/discussions) · 🐛 [Report a bug](https://github.com/bibinprathap/VeritasGraph/issues)\r\n\r\n---\r\n\r\n## 📚 Featured Guide — Build Governed AI Agents On-Prem\r\n\r\nA complete walkthrough of designing, wiring, and shipping governed AI agents entirely on your own infrastructure.\r\n\r\n**[📄 Read the guide: *Build Governed AI Agents On-Prem* (PDF)](https://github.com/bibinprathap/VeritasGraph/blob/restored-main/Build-Governed-AI-Agents-On-Prem.pdf)**\r\n\r\n[![Build Governed AI Agents On-Prem — walkthrough](https://img.youtube.com/vi/sA7ReEgdJfg/maxresdefault.jpg)](https://youtu.be/sA7ReEgdJfg)\r\n[![Import Any graph.json into VeritasGraph Studio — Walkthrough](https://img.youtube.com/vi/Po2Z6QtqFks/maxresdefault.jpg)](https://youtu.be/Po2Z6QtqFks)\r\n> ▶️ **[Watch the walkthrough on YouTube](https://youtu.be/sA7ReEgdJfg)**\r\n\r\n---\r\n\r\n## 🚀 Quick Start (2 lines, no GPU)\r\n\r\n```bash\r\npip install veritasgraph\r\nveritasgraph demo --mode=lite\r\n```\r\n\r\nThat's it — an interactive demo using cloud APIs (OpenAI/Anthropic), no local models required.\r\n\r\n| Mode | Best For | Requirements |\r\n|------|----------|--------------|\r\n| `--mode=lite` | Quick demo, no GPU | OpenAI/Anthropic API key |\r\n| `--mode=local` | Privacy, offline use | Ollama + 8GB RAM |\r\n| `--mode=full` | Production, all features | Docker + Neo4j |\r\n\r\n```bash\r\nexport OPENAI_API_KEY=\"sk-...\"        # Lite: cloud APIs, zero setup\r\nveritasgraph demo --mode=lite\r\n\r\nveritasgraph demo --mode=local --model=llama3.2   # 100% offline with Ollama\r\nveritasgraph start --mode=full                    # full GraphRAG pipeline\r\n```\r\n\r\n<p align=\"center\">\r\n  <a href=\"https://colab.research.google.com/github/bibinprathap/VeritasGraph/blob/restored-main/graphrag-ollama-config/cookbook/veritasgraph_demo.ipynb\"><img src=\"https://img.shields.io/badge/Open%20in%20Colab-Vectorless%20RAG-blue?logo=googlecolab\" alt=\"Colab: Vectorless RAG\"/></a>\r\n  &nbsp;\r\n  <a href=\"https://colab.research.google.com/github/bibinprathap/VeritasGraph/blob/restored-main/graphrag-ollama-config/cookbook/vision_native_rag.ipynb\"><img src=\"https://img.shields.io/badge/Open%20in%20Colab-Vision%20RAG-blue?logo=googlecolab\" alt=\"Colab: Vision RAG\"/></a>\r\n  &nbsp;\r\n  <a href=\"https://colab.research.google.com/github/bibinprathap/VeritasGraph/blob/restored-main/cookbook/test_hierarchical_tree_accuracy.ipynb\"><img src=\"https://img.shields.io/badge/Open%20in%20Colab-Tree%20Accuracy-blue?logo=googlecolab\" alt=\"Colab: Tree Accuracy\"/></a>\r\n</p>\r\n\r\n**Useful links:** [⚡ Live docs](https://bibinprathap.github.io/VeritasGraph/index.html) · [🎮 Live demo](https://bibinprathap.github.io/VeritasGraph/demo/) · [📖 Article](https://medium.com/@bibinprathap/beyond-vector-search-building-trustworthy-enterprise-ai-with-the-veritasgraph-rag-pipeline-53fc8e9e8ff9) · [📄 Research paper](VeritasGraph%20-%20A%20Sovereign%20GraphRAG%20Framework%20for%20Enterprise-Grade%20AI%20with%20Verifiable%20Attribution.pdf)\r\n\r\n---\r\n\r\n## 🛠️ VeritasGraph Studio — Build, wire & test governed agents locally\r\n\r\n**Studio** is a local Agent Build Workspace (FastAPI + single-page UI) that lets you build a knowledge graph from your own documents and **wire it into agents** alongside tools, memory, data logging, guardrails, and headroom-style context budgeting — then chat with those agents live and watch every stage of the orchestration pipeline. Everything runs **100% locally** against [Ollama](https://ollama.com).\r\n\r\n\r\n\r\n> **[🎮 Try the Studio Live](https://bibinprathap.github.io/VeritasGraph/studio/)** — *stable URL that always redirects to the current running studio tunnel.*\r\n\r\n**Run it:**\r\n\r\n```bash\r\npip install -r requirements.txt\r\nollama serve & ollama pull qwen3:latest          # any local chat model\r\nSTUDIO_DATA_DIR=\"$PWD/studio_api/data\" \\\r\n  uvicorn studio_api.main:app --host 127.0.0.1 --port 8200 --log-level warning\r\n# Studio UI → http://localhost:8200/studio   ·   API docs → /docs\r\n```\r\n\r\n**One-command end-to-end demo** (builds a graph + drives a fully-wired agent through graph reasoning, memory recall, PII redaction, and a guardrail block):\r\n\r\n```bash\r\npython3 demos/agent-studio/sample_pipeline.py --model qwen3:latest\r\n```\r\n\r\n<details>\r\n<summary><b>What's inside — full Studio feature set</b></summary>\r\n\r\n- 🧩 **Knowledge Graph builder & explorer** — ingest text, extract entities/relationships locally, inspect nodes/edges with grounded evidence.\r\n- 🔎 **Graph Q&A with citations** — multi-hop answers backed by `[doc#chunk]` source attribution.\r\n- 🤖 **Agent workspace** — create/edit agents with model selection, prompt/persona settings, and per-agent capability toggles.\r\n- 🔀 **Governed orchestration pipeline** — per-turn flow of Guardrails → Memory → Knowledge Graph → Headroom budget → Tools → Data log, with full trace visibility.\r\n- 🧰 **Editable tools catalog** — add, edit, enable/disable, test, and delete tools directly in Studio.\r\n- 🌐 **External real tool support** — call real HTTP endpoints with configurable method, auth header, and custom headers.\r\n- 🔌 **MCP bridge integrations** — local MCP proxy connectors (e.g. Chrome DevTools MCP, Unity MCP) with health-aware probing.\r\n- 🛡️ **Guardrails** — PII redaction and policy-block controls with visible guardrail-block metrics.\r\n- 🧠 **Memory + Data logs** — per-agent short-term memory and interaction-log persistence.\r\n- 📈 **Evaluation & fine-tune simulation** — run eval suites, track pass-rate trends, and queue/monitor fine-tune jobs.\r\n- 💬 **Playground** — run governed agent conversations live and inspect the pipeline trace.\r\n- 📊 **KPI dashboard** — active agents, connected tools, eval pass rate, and guardrail-block counters.\r\n\r\nSee [`studio_api/README.md`](studio_api/README.md) for API and architecture, and [`docs/STUDIO_ENTERPRISE_TEST.md`](docs/STUDIO_ENTERPRISE_TEST.md) for enterprise test scenarios.\r\n\r\n</details>\r\n\r\n---\r\n\r\n## 🌳 + 🔗 Graph + Tree: the ultimate retrieval\r\n\r\n**Why choose?** VeritasGraph includes the hierarchical \"Table of Contents\" navigation of PageIndex **PLUS** the semantic reasoning of a Knowledge Graph.\r\n\r\n```\r\nDocument Root\r\n├── [1] Introduction\r\n│   ├── [1.1] Background ←── Tree Navigation\r\n│   └── [1.2] Objectives\r\n├── [2] Methodology ←───────── Graph Links\r\n│   └── relates_to ──────────→ [3.1] Findings\r\n└── [3] Results\r\n```\r\n\r\n### 📊 Feature comparison\r\n\r\n| Feature | Vector RAG | PageIndex | **VeritasGraph** |\r\n|---------|:----------:|:---------:|:----------------:|\r\n| **Retrieval type** | Similarity | Tree search | 🏆 Tree + Graph reasoning |\r\n| **Attribution** | ❌ Low | ⚠️ Medium | ✅ **100% verifiable** |\r\n| **Multi-hop reasoning** | ❌ | ❌ | ✅ |\r\n| **Tree navigation (TOC)** | ❌ | ✅ | ✅ |\r\n| **Semantic search** | ✅ | ❌ | ✅ |\r\n| **Cross-section linking** | ❌ | ❌ | ✅ |\r\n| **Visual graph explorer** | ❌ | ❌ | ✅ **Built-in UI** |\r\n| **100% local/private** | ⚠️ Varies | ❌ Cloud | ✅ **On-premise** |\r\n| **Open source** | ⚠️ Varies | ❌ Proprietary | ✅ **MIT license** |\r\n\r\n<p align=\"center\">\r\n  <img src=\"assets/veritasgraph-comparison.svg\" alt=\"Traditional RAG vs VeritasGraph comparison\" width=\"100%\">\r\n</p>\r\n\r\n---\r\n\r\n## 🎬 See it in action\r\n\r\n[![VeritasGraph Master Demo](https://img.youtube.com/vi/oa8ektm7nLY/maxresdefault.jpg)](https://youtu.be/oa8ektm7nLY)\r\n\r\n<p align=\"center\">\r\n  <a href=\"https://youtu.be/NGVDQbkY1wE\"><img src=\"https://img.youtube.com/vi/NGVDQbkY1wE/maxresdefault.jpg\" alt=\"Watch VeritasGraph build reasoning paths in real time\" width=\"45%\"></a>\r\n  &nbsp;\r\n  <a href=\"https://www.youtube.com/watch?v=8fz8RWgL04Y\"><img src=\"https://img.youtube.com/vi/8fz8RWgL04Y/maxresdefault.jpg\" alt=\"Convert charts & tables to knowledge graphs — Vision RAG tutorial\" width=\"45%\"></a>\r\n</p>\r\n\r\n> **💡 What you're seeing:** a query triggers multi-hop reasoning across the knowledge graph. Nodes light up as connections are discovered, showing exactly *how* the answer was found — not just *what* was found.\r\n\r\n---\r\n\r\n## 🔌 MCP Server — connect your IDE agent to VeritasGraph\r\n\r\nVeritasGraph ships a dedicated **[Model Context Protocol](https://modelcontextprotocol.io/) server** — *the first zero-trust, air-gapped Enterprise GraphRAG server for MCP.* Connect Claude Desktop, Cursor, VS Code, Windsurf, Cline, or Continue directly to the GraphRAG engine over JSON-RPC 2.0 stdio, with **zero external data egress**.\r\n\r\n```bash\r\npython -m veritasgraph_mcp     # from repo root (needs local Ollama for ingest/query)\r\n```\r\n\r\nTools: `veritasgraph_ingest_document`, `veritasgraph_query` (multi-hop answers with `[doc#chunk]` citations), `veritasgraph_search_entities`, `veritasgraph_get_graph`, `veritasgraph_clear_graph`. See [`veritasgraph_mcp/README.md`](veritasgraph_mcp/README.md) for IDE registration snippets.\r\n\r\n---\r\n\r\n## 📖 Python API\r\n\r\n```python\r\nfrom veritasgraph import VisionRAGPipeline\r\n\r\npipeline = VisionRAGPipeline()                 # auto-detects available models\r\ndoc = pipeline.ingest_pdf(\"document.pdf\")\r\nresult = pipeline.query(\"What are the key findings?\")\r\nprint(result.answer)\r\n```\r\n\r\n<details>\r\n<summary><b>🌳 Hierarchical tree navigation + graph search</b></summary>\r\n\r\n```python\r\nfrom veritasgraph import VisionRAGPipeline\r\n\r\npipeline = VisionRAGPipeline()\r\ndoc = pipeline.ingest_pdf(\"report.pdf\")\r\n\r\n# View the document's hierarchical structure (like a Table of Contents)\r\nprint(pipeline.get_document_tree())\r\n# Document Root\r\n# ├── [1] Introduction (pp. 1-5)\r\n# │   ├── [1.1] Background (pp. 1-2)\r\n# │   └── [1.2] Objectives (pp. 3-5)\r\n# └── [2] Methodology (pp. 6-15)\r\n\r\n# Navigate to a specific section (tree-based retrieval)\r\nsection = pipeline.navigate_to_section(\"Methodology\")\r\nprint(section['breadcrumb'])   # ['Document Root', 'Methodology']\r\n\r\n# Or use graph-based semantic search\r\nresult = pipeline.query(\"What methodology was used?\")\r\n# → answer with section context: \"📍 Location: Document > Methodology > Analysis Framework\"\r\n```\r\n\r\n</details>\r\n\r\n<details>\r\n<summary><b>🔧 Custom configuration & ingestion modes</b></summary>\r\n\r\n```python\r\nfrom veritasgraph import VisionRAGPipeline, VisionRAGConfig\r\n\r\nconfig = VisionRAGConfig(ingest_mode=\"document-centric\")  # tables stay intact!\r\npipeline = VisionRAGPipeline(config)\r\ndoc = pipeline.ingest_pdf(\"annual_report.pdf\")\r\n```\r\n\r\n| Mode | Description | Best For |\r\n|------|-------------|----------|\r\n| `document-centric` | Whole pages/sections as nodes (default) | Most documents |\r\n| `page` | Each page = one node | Slide decks, reports |\r\n| `section` | Each section = one node | Structured documents |\r\n| `chunk` | Traditional 500-token chunks | Legacy compatibility |\r\n\r\n</details>\r\n\r\n### CLI\r\n\r\n```bash\r\nveritasgraph --version                                    # show version\r\nveritasgraph info                                         # check dependencies\r\nveritasgraph init my_project                              # initialize a project\r\nveritasgraph ingest document.pdf --ingest-mode=document-centric   # Don't Chunk. Graph.\r\nveritasgraph ingest https://youtube.com/watch?v=xxx       # auto-extract transcript\r\nveritasgraph ingest https://example.com/article           # extract web article\r\n```\r\n\r\n### Installation options\r\n\r\n```bash\r\npip install veritasgraph            # basic (includes lite mode)\r\npip install veritasgraph[web]       # Gradio UI + visualization\r\npip install veritasgraph[graphrag]  # Microsoft GraphRAG integration\r\npip install veritasgraph[ingest]    # YouTube & web-article ingestion\r\npip install veritasgraph[all]       # everything\r\n```\r\n\r\n---\r\n\r\n## 🏛️ Enterprise Compliance — VeritasGraph + VeritasReason\r\n\r\nGraphRAG is brilliant at *describing* what your documents say. But enterprise questions like **\"Which purchase orders violated our Segregation-of-Duties policy last quarter?\"** are **rule-evaluation problems** over structured records — not similarity search.\r\n\r\nFor those, VeritasGraph ships a sister module: **[VeritasReason](veritas-reason/README_VERITASREASON.md)** — a deterministic reasoning engine (forward-chaining + Rete + SPARQL) that fires policy rules over a triplet store and returns auditable answers with W3C PROV-O provenance.\r\n\r\n```\r\n Policy PDFs ─┐                        ┌─ ingest_structured.py (SQL → triples + text)\r\n              ▼                        ▼\r\n      VeritasGraph GraphRAG      VeritasReason (TripletStore + RuleSet\r\n      (quotes policy text)       + ForwardChainer + PROV-O)\r\n              └──────────┬───────────────┘\r\n                         ▼\r\n             Compliance answer + violators table + clause citations\r\n```\r\n\r\n### 30-second smoke test (no install, stdlib only)\r\n\r\n```bash\r\npython tests/test_policy_compliance_demo.py\r\n```\r\n\r\nSeeds a fake ERP into a tiny in-memory triple store, evaluates four SoD rules from [rules/sod_policy.yaml](rules/sod_policy.yaml), and prints violators with citations:\r\n\r\n```\r\n✓ Reasoner fired. Detected 4 violation(s):\r\n  po:PO-2204 SOD-01   Approved & paid by emp:E118\r\n  po:PO-2301 SOD-02   Requested & approved by emp:E091\r\n  po:PO-2317 SOD-03   $48,750.00 approved by emp:E091 (role:Manager, not Director)\r\n  po:PO-2402 SOD-04   Vendor vendor:V77 related to approver emp:E140\r\n```\r\n\r\nOr install and run the packaged demo:\r\n\r\n```bash\r\npip install veritas-reason\r\nveritasreason-policy-demo\r\n```\r\n\r\n<p align=\"center\">\r\n  <img src=\"https://github.com/bibinprathap/VeritasGraph/blob/restored-main/demos/policy-compliance/demo.gif?raw=true\" alt=\"VeritasGraph + VeritasReason policy-compliance demo\" width=\"80%\">\r\n</p>\r\n\r\nThe same pattern applies to leave-policy violations (HRIS attendance), expense-report fraud (ledger + receipts), clinical protocol breaches (EHR + guidelines), or KYC/AML (transactions + watchlists). Define the SQL → triple mapping in [ingest_structured.py](graphrag-ollama-config/ingest_structured.py), write rules in `rules/*.yaml`, and ask in plain English. See [veritas-reason/plan.md](veritas-reason/plan.md) for a full walk-through.\r\n\r\n---\r\n\r\n## 🔗 Interactive Graph Visualization\r\n\r\nVeritasGraph includes an **interactive 2D knowledge-graph explorer** (PyVis) that visualizes entities and relationships in real time.\r\n\r\n![Graph Explorer](assets/graph-explorer.png)\r\n\r\n| Feature | Description |\r\n|---------|-------------|\r\n| **Query-aware subgraph** | Shows only entities related to your query |\r\n| **Community coloring** | Nodes grouped by community membership |\r\n| **Red highlight** | Query-related entities shown in red |\r\n| **Node sizing** | Bigger nodes = more connections |\r\n| **Interactive** | Drag, zoom, hover for entity details |\r\n| **Full graph explorer** | View the entire knowledge graph |\r\n\r\n---\r\n\r\n## ⚙️ Provider Support (OpenAI-compatible)\r\n\r\nVeritasGraph works with **any OpenAI-compatible API** — mix and match cloud and local:\r\n\r\n| Provider | API Base | API Key | Example Model |\r\n|----------|----------|---------|---------------|\r\n| **Ollama** (default) | `http://localhost:11434/v1` | `ollama` | `llama3.1-12k` |\r\n| **OpenAI** | `https://api.openai.com/v1` | `sk-proj-...` | `gpt-4-turbo-preview` |\r\n| **Groq** | `https://api.groq.com/openai/v1` | `gsk_...` | `llama-3.1-70b-versatile` |\r\n| **Together AI** | `https://api.together.xyz/v1` | your-key | `Meta-Llama-3.1-70B-Instruct-Turbo` |\r\n| **LM Studio** | `http://localhost:1234/v1` | `lm-studio` | (model loaded in LM Studio) |\r\n\r\nAlso supported: Azure OpenAI, OpenRouter, Anyscale, LocalAI, vLLM.\r\n\r\n```bash\r\ncd graphrag-ollama-config\r\ncp settings_openai.yaml settings.yaml\r\ncp .env.openai.example .env       # edit with your provider settings\r\npython -m graphrag.index --root . --config settings_openai.yaml\r\npython app.py\r\n```\r\n\r\n> ⚠️ **Embeddings must match your index.** If you indexed with `nomic-embed-text` (768 dims), you must query with the same model — switching embedding models requires **re-indexing**. Full details in [OPENAI_COMPATIBLE_API.md](graphrag-ollama-config/OPENAI_COMPATIBLE_API.md).\r\n\r\n---\r\n\r\n## 🐳 Deployment\r\n\r\n### Five-Minute Magic Onboarding (Docker)\r\n\r\nRun a full stack (Ollama + Neo4j + Gradio) with one command:\r\n\r\n```bash\r\ncd docker/five-minute-magic-onboarding\r\n# set your Neo4j password in .env, then:\r\ndocker compose up --build\r\n```\r\n\r\nServices: Gradio UI → http://127.0.0.1:7860 · Neo4j → http://localhost:7474 · Ollama → http://localhost:11434. See [`docker/five-minute-magic-onboarding/README.md`](docker/five-minute-magic-onboarding/README.md).\r\n\r\n### Share with your team (free)\r\n\r\n| Method | Duration | Local Ollama | Setup | Best For |\r\n|--------|----------|:------------:|-------|----------|\r\n| `python app.py --share` | 72 hours | ✅ | 1 min | Quick demos |\r\n| Ngrok tunnel | Unlimited* | ✅ | 5 min | Team evaluation |\r\n| Cloudflare tunnel | Unlimited* | ✅ | 5 min | Team evaluation |\r\n| Hugging Face Spaces | Permanent | ❌ (cloud LLM) | 15 min | Public showcase |\r\n\r\n_*Free tier has some limitations._\r\n\r\n---\r\n\r\n## 🏗️ Architecture\r\n\r\n```mermaid\r\ngraph TD\r\n    subgraph \"Indexing Pipeline (one-time)\"\r\n        A[Source Documents] --> B{Document Chunking};\r\n        B --> C{\"LLM Extraction<br/>(Entities & Relationships)\"};\r\n        C --> D[Vector Index];\r\n        C --> E[Knowledge Graph];\r\n    end\r\n    subgraph \"Query Pipeline (real-time)\"\r\n        F[User Query] --> G{Hybrid Retrieval Engine};\r\n        G -- \"1. Vector search for entry points\" --> D;\r\n        G -- \"2. Multi-hop graph traversal\" --> E;\r\n        G --> H{Pruning & Re-ranking};\r\n        H -- \"Rich context\" --> I{LoRA-Tuned LLM Core};\r\n        I -- \"Answer + provenance\" --> J{Attribution Layer};\r\n        J --> K[Attributed Answer];\r\n    end\r\n    style A fill:#f2f2f2,stroke:#333,stroke-width:2px\r\n    style F fill:#e6f7ff,stroke:#333,stroke-width:2px\r\n    style K fill:#e6ffe6,stroke:#333,stroke-width:2px\r\n```\r\n\r\n**The four stages:**\r\n\r\n1. **Automated Knowledge Graph construction** — chunk documents into `TextUnits`, extract `(head, relation, tail)` triplets, assemble nodes + edges in a graph DB (e.g. Neo4j).\r\n2. **Hybrid retrieval engine** — vector search finds entry nodes, multi-hop traversal uncovers hidden relationships, pruning & re-ranking keeps the most relevant facts.\r\n3. **LoRA-tuned reasoning core** — a locally hosted, LoRA-tuned open model generates attributed answers with efficient fine-tuning for reasoning + attribution.\r\n4. **Attribution & provenance layer** — propagates source IDs, chunks, and graph nodes into a structured, traceable JSON output.\r\n\r\n<details>\r\n<summary><b>On-premise prerequisites</b></summary>\r\n\r\n**Hardware:** 16+ CPU cores · 64GB+ RAM (128GB recommended) · NVIDIA GPU with 24GB+ VRAM (A100 / H100 / RTX 4090).\r\n**Software:** Docker & Docker Compose · Python 3.10+ · NVIDIA Container Toolkit.\r\nCopy `.env.example` → `.env` and populate with environment-specific values.\r\n\r\n</details>\r\n\r\n---\r\n\r\n## Why VeritasGraph?\r\n\r\n- ✅ **Fully on-premise & secure** — 100% control over your data and models.\r\n- ✅ **Verifiable attribution** — every claim traces back to its source.\r\n- ✅ **Advanced graph reasoning** — answers complex, multi-hop questions.\r\n- ✅ **Hierarchical tree + graph** — PageIndex-style TOC navigation with graph flexibility.\r\n- ✅ **Governed agents** — guardrails, memory, tools, and context budgeting wired together in Studio.\r\n- ✅ **Open-source & sovereign** — MIT-licensed, no vendor lock-in.\r\n\r\n**Who is it for?** Engineers building enterprise search, compliance assistants, research copilots, scientific literature explorers, and agent memory systems — anywhere \"the answer\" depends on how facts *connect*, not just whether they appear near each other in a vector index.\r\n\r\n---\r\n\r\n## 🙌 Acknowledgments\r\n\r\nBuilds on the foundational work of **HopRAG**, **Microsoft GraphRAG**, **LangChain & LlamaIndex**, and **Neo4j**.\r\n\r\n## 🏆 Awards & Citation\r\n\r\nPresented at the **International Conference on Applied Science and Future Technology (ICASF 2025)** — [📄 Appreciation Certificate](ICASF%202025%20-%20Appreciation%20Certificate.pdf).\r\n\r\n```bibtex\r\n@article{VeritasGraph2025,\r\n  title={VeritasGraph: A Sovereign GraphRAG Framework for Enterprise-Grade AI with Verifiable Attribution},\r\n  author={Bibin Prathap},\r\n  journal={International Conference on Applied Science and Future Technology (ICASF)},\r\n  year={2025}\r\n}\r\n```\r\n\r\n## Star History\r\n\r\n[![Star History Chart](https://api.star-history.com/svg?repos=bibinprathap/VeritasGraph&type=Date)](https://www.star-history.com/#bibinprathap/VeritasGraph&Date)\r\n\r\n---\r\n\r\n<p align=\"center\">\r\n  <a href=\"https://github.com/bibinprathap/VeritasGraph\"><img alt=\"stars\" src=\"https://img.shields.io/github/stars/bibinprathap/VeritasGraph\" /></a>\r\n  <a href=\"https://github.com/bibinprathap/VeritasGraph/issues\"><img alt=\"issues\" src=\"https://img.shields.io/github/issues/bibinprathap/VeritasGraph\" /></a>\r\n  <a href=\"https://github.com/bibinprathap/VeritasGraph/fork\"><img alt=\"forks\" src=\"https://img.shields.io/github/forks/bibinprathap/VeritasGraph\" /></a>\r\n  <img alt=\"license\" src=\"https://img.shields.io/github/license/bibinprathap/VeritasGraph\" />\r\n  <a href=\"https://linkedin.com/in/bibin-prathap-4a34a489/\"><img src=\"https://img.shields.io/badge/LinkedIn-blue?style=flat&logo=linkedin&labelColor=blue\"></a>\r\n</p>\r\n\r\n<p align=\"center\"><b>Licensed under MIT.</b> ⭐ Star the repo to follow the roadmap for open-source, governed GraphRAG.</p>\r\n"}, "632056cae851281aad5e8083d854b82a0f258621": {"t": 1785846878.7107856, "n": 22437, "h": "e4153dc773009fbf", "c": "# VeritasGraph — The Governed, On-Prem GraphRAG & Agent Framework\r\n\r\n**Stop chunking blindly. Combine Tree-Search structure with Knowledge-Graph reasoning — and wire it into governed AI agents. Runs 100% locally or in the cloud.**\r\n\r\n<img src=\"https://github.com/bibinprathap/VeritasGraph/blob/restored-main/VeritasGraph.jpeg?raw=true\" alt=\"VeritasGraph Logo\" width=\"140\">\r\n\r\n[![PyPI version](https://badge.fury.io/py/veritasgraph.svg)](https://badge.fury.io/py/veritasgraph)\r\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n[![CI](https://github.com/bibinprathap/VeritasGraph/actions/workflows/ci.yml/badge.svg)](https://github.com/bibinprathap/VeritasGraph/actions)\r\n[![GitHub Stars](https://img.shields.io/github/stars/bibinprathap/VeritasGraph?style=social)](https://github.com/bibinprathap/VeritasGraph)\r\n\r\n> **🎯 Traditional RAG guesses based on similarity. VeritasGraph reasons based on structure.**\r\n> Don't just find the document — understand the connection, then act on it with governed agents.\r\n\r\n⭐ [Star](https://github.com/bibinprathap/VeritasGraph) · 🍴 [Fork](https://github.com/bibinprathap/VeritasGraph/fork) · 💬 [Discuss](https://github.com/bibinprathap/VeritasGraph/discussions) · 🐛 [Report a bug](https://github.com/bibinprathap/VeritasGraph/issues)\r\n\r\n---\r\n\r\n## 📚 Featured Guide — Build Governed AI Agents On-Prem\r\n\r\nA complete walkthrough of designing, wiring, and shipping governed AI agents entirely on your own infrastructure.\r\n\r\n**[📄 Read the guide: *Build Governed AI Agents On-Prem* (PDF)](https://github.com/bibinprathap/VeritasGraph/blob/restored-main/Build-Governed-AI-Agents-On-Prem.pdf)**\r\n\r\n[![Build Governed AI Agents On-Prem — walkthrough](https://img.youtube.com/vi/sA7ReEgdJfg/maxresdefault.jpg)](https://youtu.be/sA7ReEgdJfg)\r\n[![Import Any graph.json into VeritasGraph Studio — Walkthrough](https://img.youtube.com/vi/Po2Z6QtqFks/maxresdefault.jpg)](https://youtu.be/Po2Z6QtqFks)\r\n> ▶️ **[Watch the walkthrough on YouTube](https://youtu.be/sA7ReEgdJfg)**\r\n\r\n---\r\n\r\n## 🚀 Quick Start (2 lines, no GPU)\r\n\r\n```bash\r\npip install veritasgraph\r\nveritasgraph demo --mode=lite\r\n```\r\n\r\nThat's it — an interactive demo using cloud APIs (OpenAI/Anthropic), no local models required.\r\n\r\n| Mode | Best For | Requirements |\r\n|------|----------|--------------|\r\n| `--mode=lite` | Quick demo, no GPU | OpenAI/Anthropic API key |\r\n| `--mode=local` | Privacy, offline use | Ollama + 8GB RAM |\r\n| `--mode=full` | Production, all features | Docker + Neo4j |\r\n\r\n```bash\r\nexport OPENAI_API_KEY=\"sk-...\"        # Lite: cloud APIs, zero setup\r\nveritasgraph demo --mode=lite\r\n\r\nveritasgraph demo --mode=local --model=llama3.2   # 100% offline with Ollama\r\nveritasgraph start --mode=full                    # full GraphRAG pipeline\r\n```\r\n\r\n<p align=\"center\">\r\n  <a href=\"https://colab.research.google.com/github/bibinprathap/VeritasGraph/blob/restored-main/graphrag-ollama-config/cookbook/veritasgraph_demo.ipynb\"><img src=\"https://img.shields.io/badge/Open%20in%20Colab-Vectorless%20RAG-blue?logo=googlecolab\" alt=\"Colab: Vectorless RAG\"/></a>\r\n  &nbsp;\r\n  <a href=\"https://colab.research.google.com/github/bibinprathap/VeritasGraph/blob/restored-main/graphrag-ollama-config/cookbook/vision_native_rag.ipynb\"><img src=\"https://img.shields.io/badge/Open%20in%20Colab-Vision%20RAG-blue?logo=googlecolab\" alt=\"Colab: Vision RAG\"/></a>\r\n  &nbsp;\r\n  <a href=\"https://colab.research.google.com/github/bibinprathap/VeritasGraph/blob/restored-main/cookbook/test_hierarchical_tree_accuracy.ipynb\"><img src=\"https://img.shields.io/badge/Open%20in%20Colab-Tree%20Accuracy-blue?logo=googlecolab\" alt=\"Colab: Tree Accuracy\"/></a>\r\n</p>\r\n\r\n**Useful links:** [⚡ Live docs](https://bibinprathap.github.io/VeritasGraph/index.html) · [🎮 Live demo](https://bibinprathap.github.io/VeritasGraph/demo/) · [📖 Article](https://medium.com/@bibinprathap/beyond-vector-search-building-trustworthy-enterprise-ai-with-the-veritasgraph-rag-pipeline-53fc8e9e8ff9) · [📄 Research paper](VeritasGraph%20-%20A%20Sovereign%20GraphRAG%20Framework%20for%20Enterprise-Grade%20AI%20with%20Verifiable%20Attribution.pdf)\r\n\r\n---\r\n\r\n## 🛠️ VeritasGraph Studio — Build, wire & test governed agents locally\r\n\r\n**Studio** is a local Agent Build Workspace (FastAPI + single-page UI) that lets you build a knowledge graph from your own documents and **wire it into agents** alongside tools, memory, data logging, guardrails, and headroom-style context budgeting — then chat with those agents live and watch every stage of the orchestration pipeline. Everything runs **100% locally** against [Ollama](https://ollama.com).\r\n\r\n\r\n\r\n> **[🎮 Try the Studio Live](https://bibinprathap.github.io/VeritasGraph/studio/)** — *stable URL that always redirects to the current running studio tunnel.*\r\n\r\n**Run it:**\r\n\r\n```bash\r\npip install -r requirements.txt\r\nollama serve & ollama pull qwen3:latest          # any local chat model\r\nSTUDIO_DATA_DIR=\"$PWD/studio_api/data\" \\\r\n  uvicorn studio_api.main:app --host 127.0.0.1 --port 8200 --log-level warning\r\n# Studio UI → http://localhost:8200/studio   ·   API docs → /docs\r\n```\r\n\r\n**One-command end-to-end demo** (builds a graph + drives a fully-wired agent through graph reasoning, memory recall, PII redaction, and a guardrail block):\r\n\r\n```bash\r\npython3 demos/agent-studio/sample_pipeline.py --model qwen3:latest\r\n```\r\n\r\n<details>\r\n<summary><b>What's inside — full Studio feature set</b></summary>\r\n\r\n- 🧩 **Knowledge Graph builder & explorer** — ingest text, extract entities/relationships locally, inspect nodes/edges with grounded evidence.\r\n- 🔎 **Graph Q&A with citations** — multi-hop answers backed by `[doc#chunk]` source attribution.\r\n- 🤖 **Agent workspace** — create/edit agents with model selection, prompt/persona settings, and per-agent capability toggles.\r\n- 🔀 **Governed orchestration pipeline** — per-turn flow of Guardrails → Memory → Knowledge Graph → Headroom budget → Tools → Data log, with full trace visibility.\r\n- 🧰 **Editable tools catalog** — add, edit, enable/disable, test, and delete tools directly in Studio.\r\n- 🌐 **External real tool support** — call real HTTP endpoints with configurable method, auth header, and custom headers.\r\n- 🔌 **MCP bridge integrations** — local MCP proxy connectors (e.g. Chrome DevTools MCP, Unity MCP) with health-aware probing.\r\n- 🛡️ **Guardrails** — PII redaction and policy-block controls with visible guardrail-block metrics.\r\n- 🧠 **Memory + Data logs** — per-agent short-term memory and interaction-log persistence.\r\n- 📈 **Evaluation & fine-tune simulation** — run eval suites, track pass-rate trends, and queue/monitor fine-tune jobs.\r\n- 💬 **Playground** — run governed agent conversations live and inspect the pipeline trace.\r\n- 📊 **KPI dashboard** — active agents, connected tools, eval pass rate, and guardrail-block counters.\r\n\r\nSee [`studio_api/README.md`](studio_api/README.md) for API and architecture, and [`docs/STUDIO_ENTERPRISE_TEST.md`](docs/STUDIO_ENTERPRISE_TEST.md) for enterprise test scenarios.\r\n\r\n</details>\r\n\r\n---\r\n\r\n## 🌳 + 🔗 Graph + Tree: the ultimate retrieval\r\n\r\n**Why choose?** VeritasGraph includes the hierarchical \"Table of Contents\" navigation of PageIndex **PLUS** the semantic reasoning of a Knowledge Graph.\r\n\r\n```\r\nDocument Root\r\n├── [1] Introduction\r\n│   ├── [1.1] Background ←── Tree Navigation\r\n│   └── [1.2] Objectives\r\n├── [2] Methodology ←───────── Graph Links\r\n│   └── relates_to ──────────→ [3.1] Findings\r\n└── [3] Results\r\n```\r\n\r\n### 📊 Feature comparison\r\n\r\n| Feature | Vector RAG | PageIndex | **VeritasGraph** |\r\n|---------|:----------:|:---------:|:----------------:|\r\n| **Retrieval type** | Similarity | Tree search | 🏆 Tree + Graph reasoning |\r\n| **Attribution** | ❌ Low | ⚠️ Medium | ✅ **100% verifiable** |\r\n| **Multi-hop reasoning** | ❌ | ❌ | ✅ |\r\n| **Tree navigation (TOC)** | ❌ | ✅ | ✅ |\r\n| **Semantic search** | ✅ | ❌ | ✅ |\r\n| **Cross-section linking** | ❌ | ❌ | ✅ |\r\n| **Visual graph explorer** | ❌ | ❌ | ✅ **Built-in UI** |\r\n| **100% local/private** | ⚠️ Varies | ❌ Cloud | ✅ **On-premise** |\r\n| **Open source** | ⚠️ Varies | ❌ Proprietary | ✅ **MIT license** |\r\n\r\n<p align=\"center\">\r\n  <img src=\"assets/veritasgraph-comparison.svg\" alt=\"Traditional RAG vs VeritasGraph comparison\" width=\"100%\">\r\n</p>\r\n\r\n---\r\n\r\n## 🎬 See it in action\r\n\r\n[![VeritasGraph Master Demo](https://img.youtube.com/vi/oa8ektm7nLY/maxresdefault.jpg)](https://youtu.be/oa8ektm7nLY)\r\n\r\n<p align=\"center\">\r\n  <a href=\"https://youtu.be/NGVDQbkY1wE\"><img src=\"https://img.youtube.com/vi/NGVDQbkY1wE/maxresdefault.jpg\" alt=\"Watch VeritasGraph build reasoning paths in real time\" width=\"45%\"></a>\r\n  &nbsp;\r\n  <a href=\"https://www.youtube.com/watch?v=8fz8RWgL04Y\"><img src=\"https://img.youtube.com/vi/8fz8RWgL04Y/maxresdefault.jpg\" alt=\"Convert charts & tables to knowledge graphs — Vision RAG tutorial\" width=\"45%\"></a>\r\n</p>\r\n\r\n> **💡 What you're seeing:** a query triggers multi-hop reasoning across the knowledge graph. Nodes light up as connections are discovered, showing exactly *how* the answer was found — not just *what* was found.\r\n\r\n---\r\n\r\n## 🔌 MCP Server — connect your IDE agent to VeritasGraph\r\n\r\nVeritasGraph ships a dedicated **[Model Context Protocol](https://modelcontextprotocol.io/) server** — *the first zero-trust, air-gapped Enterprise GraphRAG server for MCP.* Connect Claude Desktop, Cursor, VS Code, Windsurf, Cline, or Continue directly to the GraphRAG engine over JSON-RPC 2.0 stdio, with **zero external data egress**.\r\n\r\n```bash\r\npython -m veritasgraph_mcp     # from repo root (needs local Ollama for ingest/query)\r\n```\r\n\r\nTools: `veritasgraph_ingest_document`, `veritasgraph_query` (multi-hop answers with `[doc#chunk]` citations), `veritasgraph_search_entities`, `veritasgraph_get_graph`, `veritasgraph_clear_graph`. See [`veritasgraph_mcp/README.md`](veritasgraph_mcp/README.md) for IDE registration snippets.\r\n\r\n---\r\n\r\n## 📖 Python API\r\n\r\n```python\r\nfrom veritasgraph import VisionRAGPipeline\r\n\r\npipeline = VisionRAGPipeline()                 # auto-detects available models\r\ndoc = pipeline.ingest_pdf(\"document.pdf\")\r\nresult = pipeline.query(\"What are the key findings?\")\r\nprint(result.answer)\r\n```\r\n\r\n<details>\r\n<summary><b>🌳 Hierarchical tree navigation + graph search</b></summary>\r\n\r\n```python\r\nfrom veritasgraph import VisionRAGPipeline\r\n\r\npipeline = VisionRAGPipeline()\r\ndoc = pipeline.ingest_pdf(\"report.pdf\")\r\n\r\n# View the document's hierarchical structure (like a Table of Contents)\r\nprint(pipeline.get_document_tree())\r\n# Document Root\r\n# ├── [1] Introduction (pp. 1-5)\r\n# │   ├── [1.1] Background (pp. 1-2)\r\n# │   └── [1.2] Objectives (pp. 3-5)\r\n# └── [2] Methodology (pp. 6-15)\r\n\r\n# Navigate to a specific section (tree-based retrieval)\r\nsection = pipeline.navigate_to_section(\"Methodology\")\r\nprint(section['breadcrumb'])   # ['Document Root', 'Methodology']\r\n\r\n# Or use graph-based semantic search\r\nresult = pipeline.query(\"What methodology was used?\")\r\n# → answer with section context: \"📍 Location: Document > Methodology > Analysis Framework\"\r\n```\r\n\r\n</details>\r\n\r\n<details>\r\n<summary><b>🔧 Custom configuration & ingestion modes</b></summary>\r\n\r\n```python\r\nfrom veritasgraph import VisionRAGPipeline, VisionRAGConfig\r\n\r\nconfig = VisionRAGConfig(ingest_mode=\"document-centric\")  # tables stay intact!\r\npipeline = VisionRAGPipeline(config)\r\ndoc = pipeline.ingest_pdf(\"annual_report.pdf\")\r\n```\r\n\r\n| Mode | Description | Best For |\r\n|------|-------------|----------|\r\n| `document-centric` | Whole pages/sections as nodes (default) | Most documents |\r\n| `page` | Each page = one node | Slide decks, reports |\r\n| `section` | Each section = one node | Structured documents |\r\n| `chunk` | Traditional 500-token chunks | Legacy compatibility |\r\n\r\n</details>\r\n\r\n### CLI\r\n\r\n```bash\r\nveritasgraph --version                                    # show version\r\nveritasgraph info                                         # check dependencies\r\nveritasgraph init my_project                              # initialize a project\r\nveritasgraph ingest document.pdf --ingest-mode=document-centric   # Don't Chunk. Graph.\r\nveritasgraph ingest https://youtube.com/watch?v=xxx       # auto-extract transcript\r\nveritasgraph ingest https://example.com/article           # extract web article\r\n```\r\n\r\n### Installation options\r\n\r\n```bash\r\npip install veritasgraph            # basic (includes lite mode)\r\npip install veritasgraph[web]       # Gradio UI + visualization\r\npip install veritasgraph[graphrag]  # Microsoft GraphRAG integration\r\npip install veritasgraph[ingest]    # YouTube & web-article ingestion\r\npip install veritasgraph[all]       # everything\r\n```\r\n\r\n---\r\n\r\n## 🏛️ Enterprise Compliance — VeritasGraph + VeritasReason\r\n\r\nGraphRAG is brilliant at *describing* what your documents say. But enterprise questions like **\"Which purchase orders violated our Segregation-of-Duties policy last quarter?\"** are **rule-evaluation problems** over structured records — not similarity search.\r\n\r\nFor those, VeritasGraph ships a sister module: **[VeritasReason](veritas-reason/README_VERITASREASON.md)** — a deterministic reasoning engine (forward-chaining + Rete + SPARQL) that fires policy rules over a triplet store and returns auditable answers with W3C PROV-O provenance.\r\n\r\n```\r\n Policy PDFs ─┐                        ┌─ ingest_structured.py (SQL → triples + text)\r\n              ▼                        ▼\r\n      VeritasGraph GraphRAG      VeritasReason (TripletStore + RuleSet\r\n      (quotes policy text)       + ForwardChainer + PROV-O)\r\n              └──────────┬───────────────┘\r\n                         ▼\r\n             Compliance answer + violators table + clause citations\r\n```\r\n\r\n### 30-second smoke test (no install, stdlib only)\r\n\r\n```bash\r\npython tests/test_policy_compliance_demo.py\r\n```\r\n\r\nSeeds a fake ERP into a tiny in-memory triple store, evaluates four SoD rules from [rules/sod_policy.yaml](rules/sod_policy.yaml), and prints violators with citations:\r\n\r\n```\r\n✓ Reasoner fired. Detected 4 violation(s):\r\n  po:PO-2204 SOD-01   Approved & paid by emp:E118\r\n  po:PO-2301 SOD-02   Requested & approved by emp:E091\r\n  po:PO-2317 SOD-03   $48,750.00 approved by emp:E091 (role:Manager, not Director)\r\n  po:PO-2402 SOD-04   Vendor vendor:V77 related to approver emp:E140\r\n```\r\n\r\nOr install and run the packaged demo:\r\n\r\n```bash\r\npip install veritas-reason\r\nveritasreason-policy-demo\r\n```\r\n\r\n<p align=\"center\">\r\n  <img src=\"https://github.com/bibinprathap/VeritasGraph/blob/restored-main/demos/policy-compliance/demo.gif?raw=true\" alt=\"VeritasGraph + VeritasReason policy-compliance demo\" width=\"80%\">\r\n</p>\r\n\r\nThe same pattern applies to leave-policy violations (HRIS attendance), expense-report fraud (ledger + receipts), clinical protocol breaches (EHR + guidelines), or KYC/AML (transactions + watchlists). Define the SQL → triple mapping in [ingest_structured.py](graphrag-ollama-config/ingest_structured.py), write rules in `rules/*.yaml`, and ask in plain English. See [veritas-reason/plan.md](veritas-reason/plan.md) for a full walk-through.\r\n\r\n---\r\n\r\n## 🔗 Interactive Graph Visualization\r\n\r\nVeritasGraph includes an **interactive 2D knowledge-graph explorer** (PyVis) that visualizes entities and relationships in real time.\r\n\r\n![Graph Explorer](assets/graph-explorer.png)\r\n\r\n| Feature | Description |\r\n|---------|-------------|\r\n| **Query-aware subgraph** | Shows only entities related to your query |\r\n| **Community coloring** | Nodes grouped by community membership |\r\n| **Red highlight** | Query-related entities shown in red |\r\n| **Node sizing** | Bigger nodes = more connections |\r\n| **Interactive** | Drag, zoom, hover for entity details |\r\n| **Full graph explorer** | View the entire knowledge graph |\r\n\r\n---\r\n\r\n## ⚙️ Provider Support (OpenAI-compatible)\r\n\r\nVeritasGraph works with **any OpenAI-compatible API** — mix and match cloud and local:\r\n\r\n| Provider | API Base | API Key | Example Model |\r\n|----------|----------|---------|---------------|\r\n| **Ollama** (default) | `http://localhost:11434/v1` | `ollama` | `llama3.1-12k` |\r\n| **OpenAI** | `https://api.openai.com/v1` | `sk-proj-...` | `gpt-4-turbo-preview` |\r\n| **Groq** | `https://api.groq.com/openai/v1` | `gsk_...` | `llama-3.1-70b-versatile` |\r\n| **Together AI** | `https://api.together.xyz/v1` | your-key | `Meta-Llama-3.1-70B-Instruct-Turbo` |\r\n| **LM Studio** | `http://localhost:1234/v1` | `lm-studio` | (model loaded in LM Studio) |\r\n\r\nAlso supported: Azure OpenAI, OpenRouter, Anyscale, LocalAI, vLLM.\r\n\r\n```bash\r\ncd graphrag-ollama-config\r\ncp settings_openai.yaml settings.yaml\r\ncp .env.openai.example .env       # edit with your provider settings\r\npython -m graphrag.index --root . --config settings_openai.yaml\r\npython app.py\r\n```\r\n\r\n> ⚠️ **Embeddings must match your index.** If you indexed with `nomic-embed-text` (768 dims), you must query with the same model — switching embedding models requires **re-indexing**. Full details in [OPENAI_COMPATIBLE_API.md](graphrag-ollama-config/OPENAI_COMPATIBLE_API.md).\r\n\r\n---\r\n\r\n## 🐳 Deployment\r\n\r\n### Five-Minute Magic Onboarding (Docker)\r\n\r\nRun a full stack (Ollama + Neo4j + Gradio) with one command:\r\n\r\n```bash\r\ncd docker/five-minute-magic-onboarding\r\n# set your Neo4j password in .env, then:\r\ndocker compose up --build\r\n```\r\n\r\nServices: Gradio UI → http://127.0.0.1:7860 · Neo4j → http://localhost:7474 · Ollama → http://localhost:11434. See [`docker/five-minute-magic-onboarding/README.md`](docker/five-minute-magic-onboarding/README.md).\r\n\r\n### Share with your team (free)\r\n\r\n| Method | Duration | Local Ollama | Setup | Best For |\r\n|--------|----------|:------------:|-------|----------|\r\n| `python app.py --share` | 72 hours | ✅ | 1 min | Quick demos |\r\n| Ngrok tunnel | Unlimited* | ✅ | 5 min | Team evaluation |\r\n| Cloudflare tunnel | Unlimited* | ✅ | 5 min | Team evaluation |\r\n| Hugging Face Spaces | Permanent | ❌ (cloud LLM) | 15 min | Public showcase |\r\n\r\n_*Free tier has some limitations._\r\n\r\n---\r\n\r\n## 🏗️ Architecture\r\n\r\n```mermaid\r\ngraph TD\r\n    subgraph \"Indexing Pipeline (one-time)\"\r\n        A[Source Documents] --> B{Document Chunking};\r\n        B --> C{\"LLM Extraction<br/>(Entities & Relationships)\"};\r\n        C --> D[Vector Index];\r\n        C --> E[Knowledge Graph];\r\n    end\r\n    subgraph \"Query Pipeline (real-time)\"\r\n        F[User Query] --> G{Hybrid Retrieval Engine};\r\n        G -- \"1. Vector search for entry points\" --> D;\r\n        G -- \"2. Multi-hop graph traversal\" --> E;\r\n        G --> H{Pruning & Re-ranking};\r\n        H -- \"Rich context\" --> I{LoRA-Tuned LLM Core};\r\n        I -- \"Answer + provenance\" --> J{Attribution Layer};\r\n        J --> K[Attributed Answer];\r\n    end\r\n    style A fill:#f2f2f2,stroke:#333,stroke-width:2px\r\n    style F fill:#e6f7ff,stroke:#333,stroke-width:2px\r\n    style K fill:#e6ffe6,stroke:#333,stroke-width:2px\r\n```\r\n\r\n**The four stages:**\r\n\r\n1. **Automated Knowledge Graph construction** — chunk documents into `TextUnits`, extract `(head, relation, tail)` triplets, assemble nodes + edges in a graph DB (e.g. Neo4j).\r\n2. **Hybrid retrieval engine** — vector search finds entry nodes, multi-hop traversal uncovers hidden relationships, pruning & re-ranking keeps the most relevant facts.\r\n3. **LoRA-tuned reasoning core** — a locally hosted, LoRA-tuned open model generates attributed answers with efficient fine-tuning for reasoning + attribution.\r\n4. **Attribution & provenance layer** — propagates source IDs, chunks, and graph nodes into a structured, traceable JSON output.\r\n\r\n<details>\r\n<summary><b>On-premise prerequisites</b></summary>\r\n\r\n**Hardware:** 16+ CPU cores · 64GB+ RAM (128GB recommended) · NVIDIA GPU with 24GB+ VRAM (A100 / H100 / RTX 4090).\r\n**Software:** Docker & Docker Compose · Python 3.10+ · NVIDIA Container Toolkit.\r\nCopy `.env.example` → `.env` and populate with environment-specific values.\r\n\r\n</details>\r\n\r\n---\r\n\r\n## Why VeritasGraph?\r\n\r\n- ✅ **Fully on-premise & secure** — 100% control over your data and models.\r\n- ✅ **Verifiable attribution** — every claim traces back to its source.\r\n- ✅ **Advanced graph reasoning** — answers complex, multi-hop questions.\r\n- ✅ **Hierarchical tree + graph** — PageIndex-style TOC navigation with graph flexibility.\r\n- ✅ **Governed agents** — guardrails, memory, tools, and context budgeting wired together in Studio.\r\n- ✅ **Open-source & sovereign** — MIT-licensed, no vendor lock-in.\r\n\r\n**Who is it for?** Engineers building enterprise search, compliance assistants, research copilots, scientific literature explorers, and agent memory systems — anywhere \"the answer\" depends on how facts *connect*, not just whether they appear near each other in a vector index.\r\n\r\n---\r\n\r\n## 🙌 Acknowledgments\r\n\r\nBuilds on the foundational work of **HopRAG**, **Microsoft GraphRAG**, **LangChain & LlamaIndex**, and **Neo4j**.\r\n\r\n## 🏆 Awards & Citation\r\n\r\nPresented at the **International Conference on Applied Science and Future Technology (ICASF 2025)** — [📄 Appreciation Certificate](ICASF%202025%20-%20Appreciation%20Certificate.pdf).\r\n\r\n```bibtex\r\n@article{VeritasGraph2025,\r\n  title={VeritasGraph: A Sovereign GraphRAG Framework for Enterprise-Grade AI with Verifiable Attribution},\r\n  author={Bibin Prathap},\r\n  journal={International Conference on Applied Science and Future Technology (ICASF)},\r\n  year={2025}\r\n}\r\n```\r\n\r\n## Star History\r\n\r\n[![Star History Chart](https://api.star-history.com/svg?repos=bibinprathap/VeritasGraph&type=Date)](https://www.star-history.com/#bibinprathap/VeritasGraph&Date)\r\n\r\n---\r\n\r\n<p align=\"center\">\r\n  <a href=\"https://github.com/bibinprathap/VeritasGraph\"><img alt=\"stars\" src=\"https://img.shields.io/github/stars/bibinprathap/VeritasGraph\" /></a>\r\n  <a href=\"https://github.com/bibinprathap/VeritasGraph/issues\"><img alt=\"issues\" src=\"https://img.shields.io/github/issues/bibinprathap/VeritasGraph\" /></a>\r\n  <a href=\"https://github.com/bibinprathap/VeritasGraph/fork\"><img alt=\"forks\" src=\"https://img.shields.io/github/forks/bibinprathap/VeritasGraph\" /></a>\r\n  <img alt=\"license\" src=\"https://img.shields.io/github/license/bibinprathap/VeritasGraph\" />\r\n  <a href=\"https://linkedin.com/in/bibin-prathap-4a34a489/\"><img src=\"https://img.shields.io/badge/LinkedIn-blue?style=flat&logo=linkedin&labelColor=blue\"></a>\r\n</p>\r\n\r\n<p align=\"center\"><b>Licensed under MIT.</b> ⭐ Star the repo to follow the roadmap for open-source, governed GraphRAG.</p>\r\n"}}}}