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

A knowledge graph your agents can trust: every answer cites its sources, the vocabulary is governed by a certified ontology, and the system says "I don't know" instead of guessing. Runs 100% locally.

🎯 Traditional RAG guesses based on similarity. VeritasGraph reasons based on structure — and refuses to answer when the evidence isn't there.

🌐 Live site · 🎮 Try the Studio live · ⭐ Star · 🍴 Fork · 💬 Discuss · 🐛 Report a bug

▶️ Watch the full talk & live demo on YouTube (27 mins)

✨ What's new

📑 Table of contents

1. Quick start
2. Architecture
3. Core concepts — attribution · ontology · compiler · governed mode · governance · PII · structured data
4. VeritasGraph Studio
5. Security model
6. MCP server
7. CLI
8. Configuration
9. API overview
10. Deployment
11. Development & tests
12. Examples & ecosystem
13. Vision RAG Python package (PyPI)
14. Why VeritasGraph?
15. Acknowledgments, awards & citation

🚀 Quick start

Option A — Local (Python + Ollama)

git clone https://github.com/bibinprathap/VeritasGraph.git && cd VeritasGraph
pip install -e ".[studio]"                  # Studio + the `veritasgraph` CLI
ollama serve & ollama pull qwen3:latest     # any local chat model

export STUDIO_API_TOKENS="$(openssl rand -hex 24):admin"   # auth is on by default
echo "${STUDIO_API_TOKENS%%:*}"                            # the token to paste into the UI

veritasgraph serve                          # http://127.0.0.1:8200/studio · API docs at /docs

Studio asks for the token the first time you open it and keeps it for the browser session. To run a local demo without auth, set STUDIO_AUTH=off (Studio logs a warning on startup); never do this on a shared or public host.

Option B — Docker Compose

STUDIO_API_TOKENS="$(openssl rand -hex 24):admin" docker compose up
docker compose exec ollama ollama pull qwen3:latest

Studio is published on 127.0.0.1:8200 only.

Option C — MCP server for your IDE agent

pip install -e .
VERITASGRAPH_MCP_MODE=read python -m veritasgraph_mcp     # or: veritasgraph mcp

See MCP server for IDE registration.

One-command end-to-end demo

This builds a graph and 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

🏗️ Architecture

flowchart LR
    subgraph Ingest
        D[Documents / graph.json imports] --> PII{PII policy}
        PII --> X["LLM extraction<br/>(steered by certified ontology)"]
    end
    subgraph Store["Shared SQLite store"]
        G[(Entities · relations · chunks)]
        O[(Ontology & glossary)]
        A[(Audit chain · snapshots · receipts)]
    end
    X --> G
    G <--> C["Ontology compiler<br/>normalize · merge · suggest · validate"]
    C <--> O
    subgraph Query
        Q[Question] --> ANS{"Answerability<br/>(governed mode)"}
        ANS -->|covered| R["Entity match + multi-hop traversal"]
        ANS -->|not covered| AB[Abstain]
        R --> L[Local LLM]
        L --> V{"Citation check<br/>(doc#chunk)"}
        V -->|grounded| OUT["Answer + citations + answer_id"]
        V -->|unknown citations| AB
    end
    G --> R
    O --> ANS
    OUT --> A
    subgraph Surfaces
        S[Studio UI & REST API]
        M[MCP server]
        CLI[veritasgraph CLI]
    end
    Surfaces --> Ingest
    Surfaces --> Query

Studio, MCP and the CLI are thin layers over the same engine and store. A graph built in Studio can be queried from your IDE, and a compile run from the CLI shows up in the Studio Ontology tab. A shared job lock ensures only one compiler runs at a time.

🧠 Core concepts

Attribution, citations and abstention

• Attribution is a data model, not a prompt. Provenance is stored at write time: every entity and relation keeps the chunk it came from (doc_xxx#n, or imp_xxx#n for imported graphs). This prevents hallucinated citations at read time.
• Deterministic retrieval. Graph traversal is reproducible, which separates the factual evidence trace from stochastic LLM generation.
• Strict citation check. Citations in the answer are compared with the sources that were actually retrieved. Mismatches are reported in unknown_citations and set grounded: false.
• Explicit abstention. If no entity matches the question, or governed mode can't ground the answer, the response sets abstained: true instead of guessing.

Ontology & business glossary

The ontology is the governed vocabulary of the graph:

• Entity types, e.g. Drug, Enzyme, Supplier.
• Predicates, e.g. inhibits, with optional domain/range constraints.
• Glossary terms: business definitions with synonyms, linked to entities.

stateDiagram-v2
    [*] --> proposed: propose (editor, MCP write, compile suggestion)
    proposed --> certified: certify (admin)
    certified --> deprecated: deprecate (admin)
    proposed --> deprecated: deprecate (admin)

Once vocabulary is certified, it changes how the system behaves:

• Extraction limits entity types to the certified list and maps synonyms to the certified predicate.
• Compile uses the same mapping rules to clean up the existing graph.
• Governed mode answers only when certified terms cover the question.

Manage it in the Studio Ontology tab, through /ontology in the REST API, or with the MCP tools get_ontology, search_terms, get_term and propose_term.

The ontology compiler

veritasgraph compile, POST /graphrag/compile, or a timer set with VERITASGRAPH_COMPILE_INTERVAL runs these stages:

Only unambiguous mappings to certified vocabulary change the graph. Everything else is a suggestion that you accept or reject in Studio or via /graphrag/suggestions. Rejected suggestions are fingerprinted and don't come back. Every run is recorded (/graphrag/compile/runs) and audited.

Governed mode, answerability and receipts

• POST /graphrag/answerable (MCP: check_answerable) tells an agent whether a question can be answered before it spends a model call.
• GET /graphrag/answers/{id} returns the receipt: question, mode, answer, citations, grounding and feedback.
• POST /graphrag/answers/{id}/feedback records a rating for the answer so it can be reviewed later. Any viewer can rate an answer.

Governance: audit, snapshots, merge

• Hash-chained audit log. Every write (ingest, import, compile, certify, merge, clear, restore) appends a SHA-256-chained event. GET /graphrag/audit/verify recomputes the chain and reports the event where it breaks (broken_at).
• Snapshots. Create, list and restore snapshots (/graphrag/snapshots). Clearing the graph always takes a snapshot first. Retention is set with VERITASGRAPH_SNAPSHOT_KEEP (default 20).
• Entity merge. POST /graphrag/entities/merge folds duplicates together and keeps their relations and provenance.
• Import / export. Bring in graph.json from Graphify, Understand-Anything, AI-Atlas or a generic node/edge file. Merge strategies are preserve_curated, skip_existing and overwrite, with a --dry-run preview.

PII policy

VERITASGRAPH_PII_POLICY controls what happens when ingested text contains email addresses, SSNs, credit card numbers (Luhn-validated), phone numbers or IP addresses:

PII in chunks is redacted on read for callers below VERITASGRAPH_PII_REVEAL_ROLE (default editor).

Structured data layer

Beyond documents, VeritasGraph can govern databases. Install with pip install -e ".[structured]" and set VG_STRUCTURED_DSN to a Postgres + pgvector store.

1. Connect a source read-only: PostgreSQL, MySQL/MariaDB, SQLite, DuckDB, ClickHouse, Trino, Hive ([structured-hive]), Snowflake or Databricks ([structured-saas]). Credentials are encrypted with VG_SECRET_KEY.
2. Sync the schema, then compile a semantic layer of datasets, fields, relationships, glossary terms and measures. These follow the same proposed → certified workflow.
3. Ask in natural language. The answer is generated SQL over certified objects, run under a statement timeout and a row cap, and returned with a receipt.

Source DSNs are guarded:

• A network allowlist (VG_STRUCTURED_ALLOWED_NETWORKS) controls which hosts can be reached.
• A file root (VG_STRUCTURED_FILE_ROOT) limits SQLite and DuckDB to approved paths.
• Dangerous driver options are refused.

See .env.structured.example for every setting, and the structured CLI / /structured API.

🖥️ VeritasGraph Studio

Studio is a local Agent Build Workspace (FastAPI + a single-page UI at /studio). You build a knowledge graph from your own documents, govern its vocabulary, and wire it into agents alongside tools, memory, data logging, guardrails and headroom-style context budgeting. You then chat with those agents and watch every stage of the orchestration pipeline.

🎮 Try the Studio live — a stable URL that always redirects to the currently running Studio tunnel.

Orchestration pipeline (per turn): Guardrails → Memory → Knowledge Graph → Headroom budget → Tools → Data log, with every step visible in the trace.

For full API details and curl recipes, see studio_api/README.md. For a guided enterprise scenario, see the Northwind Bank compliance playbook.

🔐 Security model

Auth is on by default. Studio refuses to start unless STUDIO_API_TOKENS is set or STUDIO_AUTH=off is set explicitly.

export STUDIO_API_TOKENS="tokenA:admin,tokenB:editor,tokenC:viewer"   # each token ≥ 24 chars

More controls:

• Public routes: only /health, /ready and /studio; the UI shell holds no data.
• SSRF protection: HTTP tools can't reach private, loopback or link-local addresses unless the address is listed in STUDIO_TOOL_ALLOWED_NETWORKS.
• CORS: set allowed origins with STUDIO_CORS_ORIGINS.
• MCP tiers: VERITASGRAPH_MCP_MODE limits which tools an MCP client can see. In the Studio MCP bridge, tools are also limited by the caller's role.
• PII: see PII policy.

🔌 MCP server

VeritasGraph ships a Model Context Protocol server: a zero-trust, air-gapped enterprise GraphRAG server for MCP. Claude Desktop, Cursor, VS Code, Windsurf, Cline and Continue connect over JSON-RPC 2.0 stdio with zero external data egress.

VERITASGRAPH_MCP_MODE=read python -m veritasgraph_mcp

Resources: veritasgraph://graph, veritasgraph://stats, veritasgraph://ontology. Tools that aren't in the active mode are reported as unknown tools.

See veritasgraph_mcp/README.md for Claude Desktop, Cursor and VS Code registration snippets.

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"]
}

🧰 CLI

pip install -e ".[studio]" installs the veritasgraph command:

veritasgraph serve --host 127.0.0.1 --port 8200       # run Studio
veritasgraph mcp                                      # run the MCP server (stdio)
veritasgraph migrate graph.json veritasgraph.db       # legacy JSON → SQLite
veritasgraph compile --actor ci                       # run the ontology compiler
veritasgraph export -o graph.json                     # export the graph
veritasgraph import graph.json --format auto --merge-strategy preserve_curated --dry-run

# Structured data layer (needs the [structured] extra + VG_STRUCTURED_DSN)
veritasgraph structured migrate                       # create/upgrade the semantic store
veritasgraph structured status
veritasgraph structured sync <connection>             # introspect a source schema
veritasgraph structured compile <connection>          # build semantic-layer proposals
veritasgraph structured reindex
veritasgraph structured ask "total revenue by region last quarter" --mode governed

The import command accepts --format values auto, graphify, understand_anything, ai_atlas and generic, and --source-type values curated, extracted and inferred.

⚙️ Configuration

The full reference is in studio_api/README.md.

🌐 API overview

The interactive OpenAPI docs are served at /docs. Main route groups:

TOKEN="${STUDIO_API_TOKENS%%:*}"
curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"question":"Which drugs inhibit CYP2C9?","mode":"governed"}' \
  http://127.0.0.1:8200/graphrag/query

🐳 Deployment

Provider support (OpenAI-compatible)

Studio talks to Ollama (OLLAMA_HOST). The structured layer and the GraphRAG pipeline in graphrag-ollama-config/ work with any OpenAI-compatible API. The structured layer stays local unless you set VG_LLM_ALLOW_REMOTE to allow a remote endpoint.

Azure OpenAI, OpenRouter, Anyscale and LocalAI are also supported.

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

🧪 Development & tests

pip install -e ".[studio,dev]"
ruff check veritasgraph studio_api veritasgraph_mcp
STUDIO_AUTH=off timeout 600 python -m pytest studio_api/tests tests -m "not ollama" -q \
  --ignore=studio_api/tests/test_e2e_playwright.py

CI runs ruff and pytest on Python 3.10 and 3.12. Browser end-to-end tests live in tests/studio-e2e (see VERITASGRAPH_PLAYWRIGHT_INTEGRATION_TESTS.md). Contributions are welcome; see CONTRIBUTING.md and SECURITY.md.

🧩 Examples & ecosystem

🏛️ Enterprise compliance — VeritasGraph + VeritasReason

GraphRAG is great at describing what documents say. Questions like "Which purchase orders violated our Segregation-of-Duties policy last quarter?" are rule-evaluation problems over structured records. VeritasReason is a deterministic reasoning engine (forward-chaining + Rete + SPARQL) that fires policy rules over a triple 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

python tests/test_policy_compliance_demo.py      # 30-second smoke test, stdlib only
pip install veritas-reason && veritasreason-policy-demo

The rules live in rules/sod_policy.yaml and the SQL → triple mapping in ingest_structured.py. See veritas-reason/plan.md for a walkthrough.

Built with VeritasGraph

• MeAkash77 / VeritasGraph-Enterprise-GraphRAG-Verifiable-AI-Platform — enterprise GraphRAG adapter and verifiable AI platform patterns.
• PTP063 / veritas-graph — derivative project and live deployment.
• 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.
• Minh-Tam-Solution / EndiorBot — enterprise chatbot built around graph-backed reasoning.
• NistorDorinGabriel / Proiect_Licenta — academic thesis extending VeritasGraph-inspired graph reasoning.

Building with VeritasGraph? Open a PR with a short repo description to be featured here.

📚 Guides & talks

• 📄 Build Governed AI Agents On-Prem (PDF): designing, wiring and shipping governed agents on your own infrastructure.
• ⚡ Live docs · 🎮 Live demo · 📖 Article · 📄 Research paper

📦 Vision RAG Python package (PyPI)

Note: the veritasgraph package on PyPI is the Vision RAG / tree + graph library. It is separate from the Studio / MCP / governance stack in this repository. Both install a veritasgraph command, so use separate virtual environments if you need both.

pip install veritasgraph            # basic (includes lite mode)
pip install veritasgraph[all]       # + web UI, Microsoft GraphRAG, YouTube/web ingestion
veritasgraph demo --mode=lite       # cloud APIs, no GPU   (--mode=local for Ollama)

from veritasgraph import VisionRAGPipeline, VisionRAGConfig

pipeline = VisionRAGPipeline(VisionRAGConfig(ingest_mode="document-centric"))  # tables stay intact
doc = pipeline.ingest_pdf("report.pdf")
print(pipeline.get_document_tree())                         # hierarchical "table of contents"
print(pipeline.navigate_to_section("Methodology")["breadcrumb"])
print(pipeline.query("What methodology was used?").answer)  # graph search with section context

Graph + Tree retrieval

Document Root
├── [1] Introduction
│   ├── [1.1] Background ←── Tree Navigation
│   └── [1.2] Objectives
├── [2] Methodology ←───────── Graph Links
│   └── relates_to ──────────→ [3.1] Findings
└── [3] Results

The package also includes an interactive PyVis graph explorer. It shows a query-aware subgraph, colors nodes by community, highlights query entities in red, and sizes nodes by number of connections.

Why VeritasGraph?

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, and where a wrong answer costs more than no answer.

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