Repository avatar
AI Tools
v0.1.2
active

sentinel-proof

io.github.92kareeem/sentinel-proof

Checks an answer against its sources: numbers and citations verified, wrong ones fixed. No model.

Documentation

Sentinel

Stop deploying RAG toys.

Sentinel is the self-healing, zero-trust agentic RAG engine with deterministic grounding, cost governance, and an automated regression ratchet.

Every sentence it ships is cited and checked against the passage it cites. What it cannot verify, it refuses — and every refusal becomes a to-do item for whoever owns the documents. Every mistake a reader reports can become a permanent test that CI enforces.

Quickstart · Why Sentinel · Architecture · Benchmarks · Decisions · Learn the codebase

FastAPI · LangGraph · FAISS + BM25 · Groq / OpenAI / Azure / Anthropic / Ollama · React + TypeScript · AWS free tier

License: AGPL-3.0

Only need the hallucination check? The grounding gate is published on its own as sentinel-proof (PyPI, Apache-2.0): pip install sentinel-proof, no dependencies, no model calls. It checks every number and citation in an LLM answer against the retrieved passages, re-points wrong citations, strips unsupported claims and refuses what can't be grounded. Works with LangChain, LlamaIndex or any retriever. Try it in your browser: nothing is uploaded. Using an agent? sentinel-proof-mcp puts the same check behind one MCP tool for Claude Desktop, Claude Code, Cursor or any MCP client: uvx sentinel-proof-mcp.


60-second quickstart

You need Docker. You do not need Python, Node, an AWS account or, for the demo, an API key.

git clone https://github.com/92kareeem/sentinel-rag.git
cd sentinel-rag
cp .env.example .env        # optional: add a free Groq key from console.groq.com
docker compose up --build   # then open http://localhost:5173

On first start the API indexes the sample policy documents in corpus/. Then (steps 2–4 call a real model, so they need a provider key in .env):

  1. Click Chaos demo in the header and run all five attacks: prompt injection, PII leak, a planted hallucination, an out-of-scope question and budget exhaustion. Each card shows which layer stopped it, and the path the request took through the graph.
  2. Ask "What restocking fee applies in India?" and watch each verification stage stream in. Click a citation: your browser recomputes its SHA-256 and proves the quote is the exact span of the indexed file.
  3. Ask "What is the parental leave policy for contractors?" It refuses. Open Control plane → Corpus gaps and click Upload the missing document & re-verify: the question is asked again and now answers.
  4. Switch Acting as to Finance analyst and upload a document marked CONFIDENTIAL and shared with the finance role. Switch to Contractor or Other company and ask about it: it does not exist for them. The trace shows how many passages were hidden before anything was scored.

No key yet? The chaos demo still runs; model calls are replaced by deterministic stand-ins and labelled simulated. Fully air-gapped? docker compose --profile ollama up with LLM_PROVIDER=local.


Why Sentinel?

Most RAG stacks fail in production the same three ways: a fluent answer that the evidence does not support, a cost or latency spike nobody bounded, and a mistake fixed once that quietly comes back. Sentinel is built around those three failures.

Naive RAGTypical agentic RAGSentinel
Is the answer supported?Trusts the modelAn LLM judge grades the LLMLLM critic plus a deterministic grounding gate that cannot hallucinate: every number in a claim must appear in the passage it cites, and wrong citations are re-pointed or stripped (ADR 0003)
When it can't answerGuessesRetries until something comes outRefuses, with a reason code. A refusal is never repaired into a guess (0001) and never carries the rejected draft (0005)
Self-healingNoneLoops on the same inputBounded repair: one search rewrite that never alters the user's question (0006), then one model escalation, then refusal
Routing and costOne modelAn LLM decides which LLM to callA measured heuristic router (0002), hard token and deadline caps enforced inside provider calls, deterministic downgrade to the cheap model, per-call cost on every trace
Access controlFilter after search, if at allMetadata filter on the top-kTenant → role → clearance enforced before scoring: FAISS gets an ID selector, so forbidden rows are never ranked (0009)
ProvenanceA chunk idA chunk idA SHA-256 the reader can recompute: file checksum, character span, text
StreamingRaw tokensRaw tokensStage telemetry, never drafts. The answer arrives only after it is verified (0010)
Learning from failureNoneLogsEvery refusal is diagnosed, clustered and ranked for the document owner (0007)
Not repeating mistakesNoneAn average eval scoreA per-question regression ratchet: a reviewed failure becomes a test that, once it passes, fails CI if it ever comes back (0008)
Repeated questionsRe-runSemantic cache (can serve the wrong question's answer)Cache of verified answers only, keyed by index version and caller visibility (0011)

Use the grounding gate in your own stack

The gate that runs last in Sentinel is also a standalone, dependency-free, Apache-2.0 package: sentinel-proof. It works with any retriever and any model, and most RAG prompts need no change because it reads the [1], [2] citations they already produce.

pip install sentinel-proof
from sentinel_proof import verify, from_langchain

passages = from_langchain(retriever.invoke(question))   # or from_llamaindex(...), or plain strings
v = verify(llm_answer, passages, question, citation_style="numeric")

v.ok           # every number is in the evidence and every citation points where it says
v.answer       # the supported sentences, re-cited; fabricated claims stripped
v.safe_text()  # the answer, or refusal prose if too much was stripped: never the rejected draft

Per-claim detail (v.claims), repaired citations, provenance hashes and a CLI for CI are in the package README.


Architecture

flowchart LR
    subgraph Ingress["Guardrail ingress (before any model)"]
        A[API key → tenant, roles, clearance] --> V[Size + schema] --> I[Injection screen] --> P[PII scrub] --> Q[Quota] --> B[Cost governor]
    end

    B --> C{Verified-answer<br/>cache}
    C -- hit --> OUT
    C -- miss --> R[Heuristic router]
    R --> RET[Snapshot hybrid retriever<br/>FAISS + BM25 → RRF<br/>access enforced before scoring]
    RET --> S[Synthesizer<br/>evidence fenced as untrusted]
    S -- INSUFFICIENT_CONTEXT --> RW
    S --> CR[LLM critic]
    CR -- pass --> G[Deterministic<br/>grounding gate]
    CR -- fail --> RW
    G -- fail --> RW
    RW[Repair:<br/>1 · rewrite search query<br/>2 · escalate model] --> RET
    RW -- budget or attempts spent --> REF[Refusal funnel<br/>reason code, no draft]
    G -- pass --> OUT[Verified, cited answer]

    OUT --> T[(Trace)]
    REF --> T
    T --> CB[Casebook<br/>diagnose · cluster]
    CB --> GAP[Corpus gap work list]
    GAP -. owner uploads the missing doc .-> RET
    CB --> RAT[Regression ratchet<br/>human review → pending → enforced]
    RAT -. CI fails if a fixed mistake returns .-> CI[(CI)]

The flywheel. The repair loop heals one request. The casebook remembers what failed and why. The gap report sends corpus failures to the person who can fix them. The ratchet makes each fix permanent. That last loop is what turns a demo into a product that improves.

What each layer guarantees

LayerModuleGuarantee
Ingressguardrails/Injection patterns blocked, PII scrubbed before logs, traces or any provider, per-user quota, request budget allocated
Routeragents/router.pyDeterministic model choice; the trace records who decided
Retrieveragents/retriever.py, rag/Reads one immutable index snapshot per request; unauthorized rows never scored
Synthesizeragents/synthesizer.pyDocument text is fenced and labelled untrusted data, never instructions
Criticagents/critic.pyVerdicts are schema-validated; a malformed verdict fails closed and its tokens are still counted
Groundingguardrails/grounding.pyCitations point at retrieved text; numbers appear in the cited passage; unsupported sentences stripped; mostly-stripped answers rejected
Refusalagents/graph.pyOne funnel, three reason codes, prose generated from the code
Providersllm/One retry core for Groq, OpenAI, Azure, Anthropic and local models; the deadline bounds every attempt and every backoff
Publicationrag/index_store.py, rag/index_lock.pyImmutable versioned index, atomic pointer swap, DynamoDB lease lock across instances
Lifecycledocuments/registry.pyExplicit state machine with compare-and-set writes; publish contention dead-letters to a retryable state

The control plane

One dialog, four tabs, for whoever operates the system:

  • Telemetry: p50 and p95 latency, token burn per hour, estimated cost per answer, refusal, cache-hit and self-repair rates, budget downgrades, a per-node time and token profile, and hourly volume. All of it is computed on read from traces, so it costs nothing while nobody looks.
  • Corpus gaps: unanswered and reader-flagged questions, clustered by topic and ranked by frequency, each with the recommended fix and a one-click upload that re-asks the question.
  • Quality ratchet: failures waiting for review, promotion to a pending test with a reviewed reference answer, retirement with a reason, and the exact CLI command when the suite lives in git.
  • Traces: every request drawn as lanes of attempts, with what each node did, how long it took, what it cost, and where it repaired.

Benchmarks & evals

Two suites, two kinds of gate, both in evals/:

SuiteGateQuestion it answers
golden_dataset.json (20 questions, 3 unanswerable)Averages: faithfulness ≥ 0.75, unanswerable refusal ≥ 2/3Is the system good overall?
regressions.json (grows from real failures)Per question: every enforced item must passDid a mistake we already fixed come back?

Last full run (evals/report.md, judge openai/gpt-oss-20b):

MetricValue
Mean faithfulness (judged against retrieved context, ADR 0004)1.000
Mean completeness (judged against the reference)1.000
Retrieval hit-rate (top-5)100%
Unanswerable questions refused3 / 3
False refusals on answerable questions0 / 17
Mean tokens per query1,417

Measured improvements behind the decisions: refusal short-circuit took p95 from 25.3 s to 12.1 s (0001); retiring the LLM router removed a false refusal and 14% of tokens (0002).

make eval            # golden set + ratchet, live model; writes evals/report.md
make regressions     # just the ratchet, e.g. after a fix
python evals/promote.py list                  # failures not yet tests
python evals/promote.py promote <case_id>     # reviewed failure -> pending test
python evals/promote.py retire R001 --reason "policy changed"

The eval workflow runs nightly and on PRs labelled run-evals. Every PR runs the unit suites, lint, types, the frontend build, the Lambda image build and start, and a docker compose up smoke test that asserts every chaos scenario is caught.

Load test

Measured with JMeter against one API process capped at 2 CPUs, with a stand-in model answering in 300 ms so the numbers are Sentinel's own cost, not a provider's rate limit (method, full report). A rate counts as sustained when errors stay at or under 1% and p95 stays under 250 ms (no model call) or 2 s (full answer).

ScenarioSustainedp95 at that rate
Health check989/s114 ms
Prompt injection blocked before any model call989/s56 ms
Repeated question, served from the verified-answer cache248/s13 ms
New question, full verified answer (retrieval, two model calls, grounding gate)49/s1.6 s
New question, streamed39/s1.0 s

The first run found full answers capped at 10/s: every model call built a new HTTP client (SSL context, DNS, TCP connect), and the embedding engine spun eight threads in a two-CPU container. Fixing both cut CPU per answer from ~140 ms to ~23 ms, which raised full answers to 49/s, five times the original rate.

make bench           # needs Java 17+ and JMeter 5.6+; ~20 minutes

Choose your model

Set LLM_PROVIDER in .env. Every adapter shares one retry, deadline and circuit-breaker core, so failure behaviour is identical across vendors.

ProviderLLM_PROVIDERNotes
Groqgroq (default)Free tier, very low latency. openai/gpt-oss-20b and -120b by default
OpenAIopenaiOPENAI_API_KEY, OPENAI_MODEL_SIMPLE/COMPLEX
Azure OpenAIazureAZURE_OPENAI_ENDPOINT, deployment names as models
AnthropicanthropicANTHROPIC_API_KEY, ANTHROPIC_MODEL_SIMPLE/COMPLEX
Local / air-gappedlocalOllama or vLLM (OpenAI-compatible); docker compose --profile ollama up

Prices for cost telemetry live in backend/app/llm/pricing.py and can be corrected with LLM_PRICING_OVERRIDES without a release.


Access control

Every document has a tenant, the roles it is shared with (empty means only the uploader and tenant admins), and a classification: PUBLIC < INTERNAL < CONFIDENTIAL < RESTRICTED. A caller sees a document when it is in their tenant, they own it or hold a matching role or are a tenant admin, and their clearance is at least its level. Anything else is a 404, never a 403.

Local mode ships five identities for trying this from the browser:

API keyIdentity
demo-localacme · employee · INTERNAL
finance-localacme · finance · CONFIDENTIAL
contractor-localacme · contractor · PUBLIC
admin-localacme · tenant admin · RESTRICTED
globex-localglobex · employee · INTERNAL

Deploy on the AWS free tier

The same code runs serverless with STORAGE_BACKEND=aws: Lambda (container image, ONNX embeddings, no torch) behind a Function URL, DynamoDB for registry, casebook, traces, quotas and the publication lock, S3 for versioned index artifacts and uploads, SSM SecureString for the provider key, and CloudFront for the UI.

export AWS_ACCOUNT_ID=... AWS_REGION=ap-south-1
aws ssm put-parameter --name /sentinel/groq-api-key --type SecureString --value <key>
make ingest && make deploy     # idempotent; ends with a /healthz smoke test
python infra/seed_users.py     # issues hashed API keys

infra/deploy.sh creates or updates every resource with a least-privilege IAM role and no wildcards. Nothing runs on a schedule: telemetry and gap reports are computed on read, so an idle deployment costs nothing.


Run it without Docker

make install        # venv (outside OneDrive on Windows) + frontend deps
make ingest         # index ./corpus
make serve          # API on :8000 with the chaos demo enabled
make web            # UI on :5173
make check          # lint, types, backend and frontend tests

Architecture decisions

Every non-obvious choice is written down with the measurement behind it and the alternatives it rules out.

ADRDecision
0001A refusal is an outcome, not a failure to repair
0002The router uses a heuristic, not an LLM call
0003Grounding is deterministic, and deliberately weak
0004Faithfulness is judged against retrieved context
0005A refusal never carries the draft it rejected
0006The search query is not the user's question
0007Failures become a work list for the document owner
0008A fixed mistake becomes a permanent test
0009Access is enforced before scoring
0010Streaming carries stages, never drafts
0011Only verified answers are cached

New to the code? Follow the learning path: ten checkpoints, each with an offline exercise.


Known limitations

Stated plainly, because a system whose guarantees are precisely scoped is more trustworthy than one whose guarantees are overstated.

  • Grounding is lexical, not semantic. It catches unsupported numbers, fabricated citations and claims unrelated to their evidence. Whether a passage entails a claim is the critic's job, and the critic can be wrong (ADR 0003).
  • No OCR. Scanned PDFs are rejected with UNSUPPORTED_SCANNED_DOCUMENT rather than indexed as empty.
  • Follow-up questions are not resolved before retrieval. "What about contractors?" is searched literally.
  • Whole-document questions use top-k. "List every exception" gets the most similar passages, not all of them.
  • Supersession is not modelled. Two documents giving different refund windows are both evidence.
  • Identity is an API key mapped to a user record. There is no SSO or OIDC yet; the browser holds a quota-limited demo key.
  • On Lambda, streaming is buffered by the Function URL adapter: the result is identical, but progress arrives at the end. The answer cache is per warm container.
  • Regressions run against the eval corpus. Per-tenant regression runs against each tenant's own index are not built.
  • A tenant-wide document listing in AWS is a filtered scan. A tenant_id index is the upgrade at volume.

Repository layout

packages/sentinel-proof/  the grounding gate as a standalone Apache-2.0 package (pip install sentinel-proof)
packages/sentinel-proof-mcp/  the same check as an MCP server (pip install sentinel-proof-mcp)
playground/               browser playground for that package (GitHub Pages, Pyodide; nothing uploaded)
backend/app/agents/        LangGraph nodes and routing (graph.py is the whole state machine)
backend/app/guardrails/    auth, access, injection, PII, quota, cost governor, grounding (adapter over the package)
backend/app/llm/           provider adapters over one resilient HTTP core, pricing
backend/app/rag/           chunking, PDF, embeddings, FAISS/BM25, snapshots, cache, publication
backend/app/learning/      casebook (failures → work list) and ratchet (fixes → tests)
backend/app/api/           query pipeline, streaming, control plane, documents, chaos demo
frontend/                  React + TypeScript UI and control plane
evals/                     golden set, regression suite, judge prompts, promotion CLI
benchmarks/                JMeter load test, stand-in model, runner and report builder
corpus/                    the sample business documents that get indexed
docs/                      system guide, ADRs, learning path, benchmark reports (never indexed)
docker/ · infra/           compose images, Lambda image, idempotent AWS deploy

License

Sentinel is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). The sentinel-proof package is licensed separately under Apache-2.0, so the grounding gate can be used in any project. See CONTRIBUTING.md for how to get involved and SECURITY.md for reporting vulnerabilities.

You may use, modify and self-host it, including commercially. If you run a modified version as a network service, you must offer its users the source of your modifications under the same license. The PDF parser, PyMuPDF, is itself AGPL-3.0, which is why the project uses the same license.


Built by Syed Abdul Kareem Ahmed. If Sentinel saves you from shipping a confident wrong answer, a ⭐ helps others find it.

PYPI
sentinel-proof-mcp
Install Command
pip install sentinel-proof-mcp
Runtime: uvx