Veritasgraph README

VeritasGraph — The Governed, On-Prem GraphRAG & Agent Framework

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.

🎯 Traditional RAG guesses based on similarity. VeritasGraph reasons based on structure. Don't just find the document — understand the connection, then act on it with governed agents.

🌐 Live site · ⭐ Star · 🍴 Fork · 💬 Discuss · 🐛 Report a bug

python -m veritasgraph_mcp     # from repo root (needs local Ollama for ingest/query)

▶️️ Watch the Full Talk & Live Demo on YouTube (27 mins)

Why Vector RAG Breaks on Deep Research

• Attribution is a data model, not a prompt: Storing provenance at write time prevents hallucinated citations at read time.
• Deterministic retrieval: Graph traversal is fully reproducible, separating factual evidence traces from stochastic LLM generation.
• Explicit abstention: The agent identifies missing graph edges and returns "insufficient evidence" rather than guessing.

📚 Featured Guide — Build Governed AI Agents On-Prem

A complete walkthrough of designing, wiring, and shipping governed AI agents entirely on your own infrastructure.

📄 Read the guide: Build Governed AI Agents On-Prem (PDF)

▶️ Watch the walkthrough on YouTube

🚀 Quick Start (2 lines, no GPU)

pip install veritasgraph

veritasgraph demo --mode=lite

That's it — an interactive demo using cloud APIs (OpenAI/Anthropic), no local models required.

export OPENAI_API_KEY="sk-..."        # Lite: cloud APIs, zero setup

veritasgraph demo --mode=lite



veritasgraph demo --mode=local --model=llama3.2   # 100% offline with Ollama

veritasgraph start --mode=full                    # full GraphRAG pipeline

Useful links: ⚡ Live docs · 🎮 Live demo · 📖 Article · 📄 Research paper

🏥 Example Implementation — MedTrust Agent

MedTrust Agent is a complete, reproducible example implementation of the VeritasGraph governed-agent architecture, applied to medical and pharmaceutical workflows — a zero-trust, observable LLM agent framework (NEECON 2026 paper).

• Zero-trust control plane: least-privilege IAM with step-up authorization — no tool runs before authorization succeeds.
• Governed answers: mandatory [doc#chunk] citations; uncited answers are withheld or routed to human review.
• Tamper-evident audit: keyed, hash-chained audit log with published anchors.
• Honest evaluation: security measured directly from the running code (100% unauthorized actions blocked, Wilson 95% CIs), answer quality clearly labelled illustrative; 69 tests, a versioned 40-scenario suite, and a one-command reproduce script.

python -m medtrust.demo    # end-to-end governed demo, 100% offline

📄 Read the full write-up: MedTrust Agent README

🧩 Built with VeritasGraph

A growing ecosystem of projects is building on VeritasGraph for enterprise GraphRAG, agent orchestration, fact-checking, and governed reasoning.

Community projects and integrations

• MeAkash77 / VeritasGraph-Enterprise-GraphRAG-Verifiable-AI-Platform — enterprise GraphRAG adapter and verifiable AI platform patterns.
• PTP063 / veritas-graph — derivative project and live deployment using VeritasGraph concepts.
• RahulSagar2005 / multi-hop-rag — multi-hop retrieval and reasoning workflows.
• lukehungngo / agentwall — agent security and governance-oriented reasoning flows.
• gajanan229 / Fact-checker-Agent — evidence-focused fact-checking and explanation patterns.
• Minh-Tam-Solution / EndiorBot — enterprise chatbot and AI agent integration built around graph-backed reasoning.
• NistorDorinGabriel / Proiect_Licenta — academic thesis project extending VeritasGraph-inspired graph reasoning techniques.

If you are building with VeritasGraph and want to be featured here, open a PR or reach out with a short repo description and usage summary.

� Live Example — Floorplan-KG Takeoff Demo

A hosted, zero-setup example of VeritasGraph applied to construction drawings. Upload a floorplan PDF (or pick a bundled sample) and the engine extracts rooms, dimensions, openings, fixtures, and schedules — then builds a knowledge graph and quantity takeoff you can query, all with verifiable provenance back to the source sheet.

🏗️ Try the Floorplan-KG demo — free, no login; runs the live PyMuPDF/pdfplumber extraction pipeline.

• What it shows: PDF → structured rooms/dimensions/schedules → knowledge graph → CSV/XLSX takeoff export, with a VeritasGraph assist panel for grounded Q&A over the extracted graph.
• Why it matters: the same governed-attribution model that powers document RAG applies to geometry — every measured quantity traces back to a specific sheet and element rather than a guessed value.
• Example output: a single-sheet residential plan returns ~17 rooms and ~2,400 sq ft in under 200 ms.

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.

🎮 Try the Studio Live — stable URL that always redirects to the current running studio tunnel.

Run it:

pip install -r requirements.txt

ollama serve & ollama pull qwen3:latest          # any local chat model

STUDIO_DATA_DIR="$PWD/studio_api/data" \

  uvicorn studio_api.main:app --host 127.0.0.1 --port 8200 --log-level warning

# Studio UI → http://localhost:8200/studio   ·   API docs → /docs

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

python3 demos/agent-studio/sample_pipeline.py --model qwen3:latest

📋 Examples

# Backend (FastAPI on :8300)

cd clinical-kg/backend

pip install -r requirements.txt

python run.py



# Frontend (Next.js dashboard on :3200)

cd clinical-kg/frontend

npm install && npm run dev

cd municipality-incident-chatbot

pip install -r requirements.txt



# Interactive CLI

python cli.py

#   you> trash overflowing near the market | photo=garbage_overflow.jpg | zone=downtown



# Test suite

python -m pytest -q

Enterprise scenario — follow the Northwind Bank compliance test playbook for a guided walkthrough using realistic financial-services data.

For API-level examples and curl recipes, see studio_api/README.md.

🌳 + 🔗 Graph + Tree: the ultimate retrieval

Why choose? VeritasGraph includes the hierarchical "Table of Contents" navigation of PageIndex PLUS the semantic reasoning of a Knowledge Graph.

Document Root

├── [1] Introduction

│   ├── [1.1] Background ←── Tree Navigation

│   └── [1.2] Objectives

├── [2] Methodology ←───────── Graph Links

│   └── relates_to ──────────→ [3.1] Findings

└── [3] Results

📊 Feature comparison

🎬 See it in action

💡 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.

🔌 MCP Server — connect your IDE agent to VeritasGraph

VeritasGraph ships a dedicated Model Context Protocol 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.

python -m veritasgraph_mcp     # from repo root (needs local Ollama for ingest/query)

Tools: 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 for IDE registration snippets.

🏥 VeritasGraph-MCP Use Case — Production Medical AI on Azure

Real-world deployment: VeritasGraph MCP server running on Azure Functions with Azure AI Foundry, delivering GraphRAG-powered clinical decision support with verifiable citations and compliance-ready architecture.

Foundry Agent / MCP client

   → Identity (Entra ID + function key)

      → Azure Functions (Flex Consumption, 4 mcpToolTrigger tools)

         → veritasgraph-mcp + graphrag_engine

            → Azure OpenAI (extraction + reasoning)

            → Knowledge Graph

         → Durable Azure Files mount (externalized state)

         → Storage + App Insights (observability)

{

  "question": "Should we adjust warfarin for patient 4471 on amiodarone?",

  "answer": "Reduce the warfarin dose because amiodarone inhibits CYP2C9...",

  "citations": ["doc_warfarin_note#0", "doc_warfarin_note#1"],

  "reasoning_path": ["Amiodarone → CYP2C9", "CYP2C9 → Warfarin", "Warfarin → Bleeding Risk"]

}

📖 Python API

from veritasgraph import VisionRAGPipeline



pipeline = VisionRAGPipeline()                 # auto-detects available models

doc = pipeline.ingest_pdf("document.pdf")

result = pipeline.query("What are the key findings?")

print(result.answer)

from veritasgraph import VisionRAGPipeline



pipeline = VisionRAGPipeline()

doc = pipeline.ingest_pdf("report.pdf")



# View the document's hierarchical structure (like a Table of Contents)

print(pipeline.get_document_tree())

# Document Root

# ├── [1] Introduction (pp. 1-5)

# │   ├── [1.1] Background (pp. 1-2)

# │   └── [1.2] Objectives (pp. 3-5)

# └── [2] Methodology (pp. 6-15)



# Navigate to a specific section (tree-based retrieval)

section = pipeline.navigate_to_section("Methodology")

print(section['breadcrumb'])   # ['Document Root', 'Methodology']



# Or use graph-based semantic search

result = pipeline.query("What methodology was used?")

# → answer with section context: "📍 Location: Document > Methodology > Analysis Framework"

from veritasgraph import VisionRAGPipeline, VisionRAGConfig



config = VisionRAGConfig(ingest_mode="document-centric")  # tables stay intact!

pipeline = VisionRAGPipeline(config)

doc = pipeline.ingest_pdf("annual_report.pdf")

CLI

veritasgraph --version                                    # show version

veritasgraph info                                         # check dependencies

veritasgraph init my_project                              # initialize a project

veritasgraph ingest document.pdf --ingest-mode=document-centric   # Don't Chunk. Graph.

veritasgraph ingest https://youtube.com/watch?v=xxx       # auto-extract transcript

veritasgraph ingest https://example.com/article           # extract web article

Installation options

pip install veritasgraph            # basic (includes lite mode)

pip install veritasgraph[web]       # Gradio UI + visualization

pip install veritasgraph[graphrag]  # Microsoft GraphRAG integration

pip install veritasgraph[ingest]    # YouTube & web-article ingestion

pip install veritasgraph[all]       # everything

🏛️ Enterprise Compliance — VeritasGraph + VeritasReason

GraphRAG 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.

For those, VeritasGraph ships a sister module: VeritasReason — 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.

 Policy PDFs ─┐                        ┌─ ingest_structured.py (SQL → triples + text)

              ▼                        ▼

      VeritasGraph GraphRAG      VeritasReason (TripletStore + RuleSet

      (quotes policy text)       + ForwardChainer + PROV-O)

              └──────────┬───────────────┘

                         ▼

             Compliance answer + violators table + clause citations

30-second smoke test (no install, stdlib only)

python tests/test_policy_compliance_demo.py

Seeds a fake ERP into a tiny in-memory triple store, evaluates four SoD rules from rules/sod_policy.yaml, and prints violators with citations:

✓ Reasoner fired. Detected 4 violation(s):

  po:PO-2204 SOD-01   Approved & paid by emp:E118

  po:PO-2301 SOD-02   Requested & approved by emp:E091

  po:PO-2317 SOD-03   $48,750.00 approved by emp:E091 (role:Manager, not Director)

  po:PO-2402 SOD-04   Vendor vendor:V77 related to approver emp:E140

Or install and run the packaged demo:

pip install veritas-reason

veritasreason-policy-demo

The 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, write rules in rules/*.yaml, and ask in plain English. See veritas-reason/plan.md for a full walk-through.

🔗 Interactive Graph Visualization

VeritasGraph includes an interactive 2D knowledge-graph explorer (PyVis) that visualizes entities and relationships in real time.

⚙️ Provider Support (OpenAI-compatible)

VeritasGraph works with any OpenAI-compatible API — mix and match cloud and local:

Also supported: Azure OpenAI, OpenRouter, Anyscale, LocalAI, vLLM.

cd graphrag-ollama-config

cp settings_openai.yaml settings.yaml

cp .env.openai.example .env       # edit with your provider settings

python -m graphrag.index --root . --config settings_openai.yaml

python app.py

⚠️ 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.

🐳 Deployment

Five-Minute Magic Onboarding (Docker)

Run a full stack (Ollama + Neo4j + Gradio) with one command:

cd docker/five-minute-magic-onboarding

# set your Neo4j password in .env, then:

docker compose up --build

Services: Gradio UI → http://127.0.0.1:7860 · Neo4j → http://localhost:7474 · Ollama → http://localhost:11434. See docker/five-minute-magic-onboarding/README.md.

Share with your team (free)

*Free tier has some limitations.

🏗️ Architecture

graph TD

    subgraph "Indexing Pipeline (one-time)"

        A[Source Documents] --> B{Document Chunking};

        B --> C{"LLM Extraction<br/>(Entities & Relationships)"};

        C --> D[Vector Index];

        C --> E[Knowledge Graph];

    end

    subgraph "Query Pipeline (real-time)"

        F[User Query] --> G{Hybrid Retrieval Engine};

        G -- "1. Vector search for entry points" --> D;

        G -- "2. Multi-hop graph traversal" --> E;

        G --> H{Pruning & Re-ranking};

        H -- "Rich context" --> I{LoRA-Tuned LLM Core};

        I -- "Answer + provenance" --> J{Attribution Layer};

        J --> K[Attributed Answer];

    end

    style A fill:#f2f2f2,stroke:#333,stroke-width:2px

    style F fill:#e6f7ff,stroke:#333,stroke-width:2px

    style K fill:#e6ffe6,stroke:#333,stroke-width:2px

The four stages:

1. Automated Knowledge Graph construction — chunk documents into TextUnits, extract (head, relation, tail) triplets, assemble nodes + edges in a graph DB (e.g. Neo4j).
2. Hybrid retrieval engine — vector search finds entry nodes, multi-hop traversal uncovers hidden relationships, pruning & re-ranking keeps the most relevant facts.
3. LoRA-tuned reasoning core — a locally hosted, LoRA-tuned open model generates attributed answers with efficient fine-tuning for reasoning + attribution.
4. Attribution & provenance layer — propagates source IDs, chunks, and graph nodes into a structured, traceable JSON output.

Why VeritasGraph?

• ✅ Fully on-premise & secure — 100% control over your data and models.
• ✅ Verifiable attribution — every claim traces back to its source.
• ✅ Advanced graph reasoning — answers complex, multi-hop questions.
• ✅ Hierarchical tree + graph — PageIndex-style TOC navigation with graph flexibility.
• ✅ Governed agents — guardrails, memory, tools, and context budgeting wired together in Studio.
• ✅ Open-source & sovereign — MIT-licensed, no vendor lock-in.

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.

🙌 Acknowledgments

Builds on the foundational work of HopRAG, Microsoft GraphRAG, LangChain & LlamaIndex, and Neo4j.

🏆 Awards & Citation

Presented at the International Conference on Applied Science and Future Technology (ICASF 2025) — 📄 Appreciation Certificate.

@article{VeritasGraph2025,

  title={VeritasGraph: A Sovereign GraphRAG Framework for Enterprise-Grade AI with Verifiable Attribution},

  author={Bibin Prathap},

  journal={International Conference on Applied Science and Future Technology (ICASF)},

  year={2025}

}

Star History

Licensed under MIT. ⭐ Star the repo to follow the roadmap for open-source, governed GraphRAG.