GitHub - robert-vetter/tessera: A trust layer for enterprise AI agents: answers traceable to their evidence, with a score for how much to trust them.

The agent can only say what it can prove — and only do what you approve.

An open, deterministic evidence layer for AI agents. Every answer is built from claims that each trace back to the exact source record behind them; what can't be proven is refused, not guessed. Every action an agent takes is drafted only from verified claims, previewed exactly, and executed only behind your approval — with a receipt. Faithfulness is a number in CI, not a vibe.

▶ Try it live (no signup, read-only): https://robert-vetter-tessera.hf.space — ask a question, see each claim's verifier chip, click through to the evidence, watch a refusal, run an action to a receipt. 📊 The benchmark — evidence-gated vs. the same engine ungated, same corpus and verifier, no LLM judge: docs/BENCHMARK.md. 🔌 MCP-native — plug it in as your agent's evidence oracle: uv run tessera-mcp.

A tessera is a single tile in a mosaic: many small, heterogeneous pieces assembled into one coherent, verifiable picture — which is what this system does with enterprise data.

The one-paragraph version

Enterprise AI rarely fails because the language model is weak. It fails because nobody can trust the answer: the system silently mixes incompatible sources, invents details that sound plausible, and offers no way to trace a claim back to where it came from — let alone to measure how faithful it was. Tessera is an open framework that ingests heterogeneous enterprise data (database tables, spreadsheets, documents, logs, tickets), resolves the entities scattered across those sources into a single unified knowledge graph, and answers questions through a conversational interface in which every individual claim is grounded in a traceable path back to the source records that support it. On top of that, Tessera ships a benchmark harness that turns "do you trust this AI?" from a feeling into a metric — a faithfulness score, measured on synthetic and curated data, that you can watch go up as the system improves.

Why this exists

In 2025 an AI agent deleted a production database during a code freeze, then fabricated data and misreported whether a rollback was possible. The industry's post-mortem consensus — dry-runs, approval gates, blast-radius previews, draft-only credentials — is Tessera's action model. On top of it, Tessera adds the half most tools skip: an agent's statements are gated too, not just its actions — no claim without a traceable path to evidence, and a refusal where there is none. All of it deterministic, with no model vendor inside the trust path, so the guarantees hold on-prem and do not move when a model changes. (An optional LLM may narrate an answer; it never attests.)

What Tessera does — four pillars

1. Universal ingestion. Pull in structured sources (relational tables, CSVs, exports) and unstructured ones (documents, runbooks, logs, tickets, chat threads) through one consistent intake path.
2. Cross-source entity resolution → one knowledge graph. Recognize that "Acme Corp" in a database, "ACME" in a contract PDF, and "acme-prod" in a deployment log are the same entity, and weave all sources into a single graph that can be queried as one.
3. Grounded conversational reasoning with provenance. Answer questions in natural language where the system routes simple lookups and multi-step reasoning differently, and where every sentence in the answer is backed by a citation path through the graph to the underlying records. No untraceable claims.
4. Quantified trust. A built-in evaluation harness — driven by synthetic data generation and a curated gold set — that scores faithfulness (is every claim supported by evidence?), coverage, and answer quality, so improvements are measurable rather than vibes.

Two reference verticals, one engine

The same core engine powers two deliberately different demonstrations, to prove the engine generalizes:

• Business Data Copilot — ask questions across a company's structured records and documents and get grounded, cited answers. — uv run tessera
• DevEx Copilot — point it at CI/CD logs, pull-request diffs, and ticket history; get root-cause hypotheses for failed pipelines and grounded summaries of what a change actually does. — uv run tessera-devex

As of Phase 3 both verticals run and both are measured — on a core whose files are byte-identical between the phase-2 and phase-3 tags (ADR 0008): the generalization claim is an empty git diff, not a promise. Phase 4 completed the symmetry — the business answer layer lives in tessera/business/ beside tessera/devex/, each vertical owns its claim grammars (ADR 0011) — and added the Joule-style session over both:

uv run tessera-chat
# one conversational door: explainable routing, numbered claims, :show N to
# walk provenance (records, locators, resolution assertions), :trust for the
# recorded numbers — and a live verifier check on every answer.

What makes it genuinely hard (the honest version)

Grounded RAG exists. Knowledge graphs exist. Entity resolution exists. What is rare — and what this project is actually about — is doing all of them together, across structured and unstructured data at once, with a uniform provenance model and a faithfulness metric that holds the whole thing accountable. Most systems pick one modality, skip provenance, and never measure faithfulness at all. Tessera treats measurable trust as the headline feature, not an afterthought.

Evidence-gated actions — over MCP

An agent talks to Tessera over the Model Context Protocol (uv run tessera-mcp, the opt-in agent extra), and the trust contract is measured to survive the protocol across four boundaries:

• Read-only grounded tools — claims, provenance, and principled refusals (ADR 0022).
• Propose-and-approve action drafts — an incident from a root-cause analysis, a pr_summary from a change; each field traces to a verifier-passing claim or it is not proposed (ADR 0023).
• A dry-run payload preview — the exact GitHub request a drafted action would send, every value traced to a verified field (ADR 0024).
• Effectful execution behind approval — gated on a fully-grounded payload, run by a simulated actuator that sends nothing by default, with an opt-in real path behind a credential and an approval (ADR 0025).

Tessera drafts, verifies, renders, and simulates; nothing is sent from this repository — a human or agent approves and sends. (It did send exactly once, on the record: a real GitHub issue from a grounded incident, behind approval, with a committed receipt.)

Built toward SAP, not around it. The deterministic, on-prem posture is the point: it runs on SAP AI Core / Generative AI Hub (model adapter contract-tested; runbook in docs/DEPLOYMENT.md, ADR 0012), persists to SAP HANA Cloud (in-database embeddings recorded online; the knowledge-graph-engine mirror is contract-tested), grounds answers on the real gated SALT dataset (docs/SALT_REAL.md), and offers a Joule-style surface (uv run tessera-chat) whose optional narration can never add facts (ADR 0013). The full team-by-team mapping is in docs/SAP_ALIGNMENT.md.

Development setup

The project uses uv for Python environment and dependency management. From a fresh clone:

uv sync                      # create the environment from uv.lock
uv run pre-commit install    # one-time: enable local commit gates

Run the full quality gate — the exact checks CI runs (format, lint, strict types, tests) — with bash scripts/gate.sh; the eval is uv run tessera-eval and the secret scan uv run pre-commit run gitleaks --all-files.

No toolchain? Use the container

A Dockerfile and a devcontainer provide a clean, pinned environment with no host setup beyond Docker:

docker build -t tessera-dev .          # build the pinned image
docker run --rm tessera-dev pytest     # run the test suite inside it

Or open the folder in VS Code / GitHub Codespaces and "Reopen in Container" — the environment builds and syncs automatically.

Try the demo

The fastest way to see it is the one-page web surface — ask a question, get claims with per-claim verifier chips, click through to the exact evidence, watch a principled refusal, and run an action from draft → dry-run payload → approval → receipt (all simulated; it holds no credential):

Live, no install: https://robert-vetter-tessera.hf.space — the same surface, hosted key-free on a Hugging Face Space (deploy/hf-space/).

uv run tessera-ui            # → http://127.0.0.1:8033  (stdlib-only, zero JS)

To host it (key-free, public read-only) and the 3-minute demo script + one-pager: docs/DEMO.md. The surface is a strict consumer of the same trust objects the MCP server exposes (ADR 0027); a real Claude agent doing the same three things through those tools is recorded at data/agent_session/TRANSCRIPT.md.

On your own repository (Milestone 18, ADR 0028): point Tessera at any public GitHub repo's CI history and ask why a run failed — grounded RCA with the same claim-level provenance, over a local, gitignored, scrubbed snapshot (answers are offline; an optional no-scope GITHUB_TOKEN unlocks failed-run logs — see .env.example):

uv run tessera connect github astral-sh/uv     # bounded snapshot → var/connect/
# connect prints a ready-to-run `ask` with a real failed-run id from the snapshot
# (run ids expire with GitHub's ~90-day log retention — use the suggested one):
uv run tessera ask astral-sh/uv "Why did run <run-id> fail?"

On your own CSV + Markdown (Milestone 18, ADR 0029): describe a directory with a small tessera.toml and get the same grounded, provenance-carrying answers — with multi-field entity resolution and an honest refusal when a name is ambiguous. A committed public-domain demo corpus is included:

uv run tessera ingest data/ingest_demo
uv run tessera ask data/ingest_demo "What do you know about Santa Fe?"
uv run tessera ask data/ingest_demo "Tell me about Portland"   # → ambiguous, refused

Both BYO paths are packaged as a design-partner offer — clone to a grounded, provenance-complete answer on your own data in under 30 minutes: Pilot in a day.

uv run tessera is the CLI equivalent — one routed door: a deterministic router decides whether your question is a simple lookup, a one-entity cross-source composition, or multi-step reasoning — and prints its route and reason above the answer. Every claim traces to the specific source behind it; what cannot be answered honestly is refused with the reason.

uv run tessera
# One entity named → cross-source composition: identity (customer + address
# rows), a fully-sourced order total, and the entity's agreement clauses.

uv run tessera "Compare Müller Logistik and Nordwind Logistik totals."
# Two entities → multi-step: per-entity sourced totals + a conclusion citing
# both row sets.

uv run tessera "Which entity has the highest total order value in EUR?"
# A ranking → multi-step superlative, scoped to one currency. Without the
# currency scope it refuses: a single ranking would silently mix currencies.

uv run tessera "What colour is the sky?"
# No evidence shares its terms → a principled refusal, not a guess.

There is still no model: routing, retrieval, resolution, and reasoning are all deterministic and offline (ADR 0003, ADR 0006) — which is what keeps the trust numbers below auditable.

The eval harness

Trust is measured, so the eval is runnable from the start — and it scores each vertical as a separate battery (ADR 0009), including the first real connector (GitHub Actions) measured the same way:

uv run tessera-eval
# [business]       gold (11):     faithfulness 1.000 (floor), coverage 1.000, quality 1.000
# [business]       synthetic (53): faithfulness 1.000 (floor), coverage 1.000, quality 1.000
# [devex]          gold (9):      faithfulness 1.000 (floor), coverage 0.950, quality 0.889
# [devex]          synthetic (24): faithfulness 1.000 (floor), coverage 1.000, quality 1.000
# [github_actions] gold (5):      faithfulness 1.000 (floor), coverage 0.833, quality 0.800
# [github_actions] synthetic (8):  faithfulness 1.000 (floor), coverage 1.000, quality 1.000

Those two sub-1.0 gold numbers are deliberate and honest — embedding-closable misses kept visible in CI, faithfulness gated at 1.0 throughout:

• github_actions 0.833: a question in pure out-of-log vocabulary ("is the published documentation site unreachable for visitors?") shares zero tokens with the real Pages-deploy log, so offline lexical retrieval misses it.
• devex 0.950: the undeclared checkout-svc abbreviation (difflib 0.846, just under the 0.85 threshold) leaves the on-call uncited — a faithful partial.

Both close on SAP — HANA Cloud in-database VECTOR_EMBEDDING + COSINE_SIMILARITY — in one recorded online run: github_actions → 1.000 / 1.000 (semantic retrieval over a finer-chunked log surfaces the 404 line, ADR 0017) and devex → 1.000 / 1.000 (an embedding-assisted, stem-gated resolution regime resolves checkout-svc, ADR 0016), each earned — distinct entities stay unmerged. CI stays offline and key-free, so the public numbers are 0.833 / 0.950; the closes are timestamped measurements in eval/history.jsonl, not CI gates.

The numbers are real and auditable, scored against the answers the engine actually produces over hand-curated gold sets in eval/gold/ plus per-vertical synthetic batteries enumerated from the data:

• Faithfulness — every emitted claim is deterministically supported by its cited evidence. It is a hard floor of 1.0 for every battery (an unsupported claim fails the build) and is provably able to fail: tests inject known-unfaithful claims — including a fabricated "recurring failure" — and confirm the metric catches them, so the 1.0 is earned, not tautological.
• Coverage — how much of the expected evidence the answers surface. The 1.000s were earned through three recorded trust loops, not assumed. The first two closed named, planted misses (business: the Lumière document mention, 0.929; devex: the notif-svc on-call row at similarity 0.429, 0.917) with the smallest honest mechanism — a Unicode-folding fix (ADR 0004 addendum) and a declared catalog alias (ADR 0010). The third is the strongest: a miss no one planted, surfaced by the real GitHub Actions connector (its logs mark failures ##[error], not the synthetic shape) — coverage 0.000 → 1.000, closed deterministically (ADR 0014). The whole trail is in eval/history.jsonl and told in the write-up.
• Quality — gold answers correct / refusals refused.

The README badge shows the minimum gold faithfulness across batteries — a regression in either vertical turns it red.

Definition and what the number does (and does not) prove: ADR 0005.

The Faithfulness Floor benchmark puts the gate itself under measurement: the same corpora, cases, and verifier, with the engine's own retrieval run ungated (retrieve-and-recite) as the baseline. Offline-deterministic, no LLM judge, CI-pinned so the published tables cannot drift — and the baseline column is honest about where recitation wins. Trustworthy-outcome rates on the gold sets: 1.000 / 0.889 / 0.800 gated vs 0.182 / 0.222 / 0.000 ungated (business / devex / github_actions). Report + how to attack it: docs/BENCHMARK.md; reproduce with uv run tessera-benchmark.

Knowledge graph & entity resolution

The ingested records are assembled into an in-process knowledge graph, and a non-destructive resolution layer recognizes when records across the two sources name the same real entity — e.g. the customer master's "Müller Logistik GmbH", the address master's "Mueller Logistik Gmbh", and the agreement that names the same firm. Resolution is additive and reversible: a same-entity assertion records why (the matched names + a similarity score) and a confidence, and withdrawing it leaves the raw records untouched — merges are never destructive. Matching is deterministic and multi-field (name + address), with tunable thresholds; it is honest about precision/recall and about known misses (a reference that drops a legal form isn't linked yet). A character match is stem-gated so a long shared generic suffix can't collapse distinct firms (Granite/Pyrite Logistik GmbH): the names must also share a distinctive, non-generic signal, with genericness derived from the corpus (difflib precision 0.50 → 1.00 on the labelled pair-set). On top of the name decision, two further deterministic signals are folded in as an ordered, two-way gate (most decisive first): a registration key (VATRegistration) and then the address. A contradicting field vetoes an over-merge of two same-named firms; an agreeing one bridges a double-typo pair. So two distinct "Hanseatic Trading GmbH" firms at different addresses stay separate on the address, and two distinct "Havel Kontor GmbH" firms at the same address stay separate on their different VATs — the floor the address alone can't reach (the ambiguous-name questions correctly refuse instead of answering one wrong entity — a measured quality 0.900 → 1.000 on the address pair, 0.909 → 1.000 on the key pair). The key is an exact match (a structured identity, not fuzzy), so it also overrides a postal disagreement for a genuine same-firm pair. All fully offline and CI-reproducible. Design and trade-offs: ADR 0004, ADR 0018, ADR 0019, ADR 0020.

Cross-source answers

Composing over that graph gives the Phase 1 payoff — one grounded answer that combines a database row and a document clause about the same resolved entity:

uv run tessera-compose "Summarise Müller Logistik: its sales orders and agreement terms."
# Resolves the entity, then answers with its sales total AND its agreement's
# renewal terms — each claim traced to a row or a clause.

The one synthesis it performs — the entity's total net order value — is summed over its sales rows with every summand cited, and it refuses to sum across different currencies rather than invent a number (try uv run tessera-compose "What is Atlas Trading's total order value?"). General multi-step reasoning and question routing are a later phase.

The DevEx Copilot

The same engine, pointed at developer/operations data (Phase 3):

uv run tessera-devex
# "Why did run R-1042 fail?" → the run's outcome row, the exact failing log
# lines, a recurrence link to the earlier run with the same error signature,
# and the incident ticket that documented it — every claim cited.

uv run tessera-devex "What does PR-201 actually change?"
# The PR's metadata, the diff hunk by hunk, and a verified link to the
# motivating ticket (DEVEX-204).

uv run tessera-devex "Why did run R-1041 fail?"
# That run PASSED — the premise is refused, not confabulated.

The interesting honesty cases are behaviours, not prose: the first occurrence of a failure gets no recurrence claim (there is nothing prior); a PR that names no ticket gets a summary without one; cross-source assertions ("this same signature appeared before") are emitted in a grammar the faithfulness verifier recomputes against every cited record.

The agent surface (MCP)

Tessera's thesis is a trust layer for AI agents — so it is callable by one. The tessera-mcp server exposes the engine over the Model Context Protocol — read-only grounded tools (ADR 0022), propose-and-approve action drafts (ADR 0023), a dry-run payload preview (ADR 0024), and effectful execution behind approval, simulated by default (ADR 0025):

uv sync --extra agent          # opt-in SDK; the default graph + CI stay pure-stdlib
uv run tessera-mcp             # the MCP server over stdio
# tools: list_domains · ground(domain, question) · assertions(domain, record_id)
#        list_actions · draft_action(action, domain, question)
#        preview_payload(action, domain, question)
#        execute_action(action, domain, question)   # simulated; sends nothing

ground routes a question through the same deterministic engine and returns JSON-native claims — each with full provenance inline and a per-claim verifier verdict (the eval's own is_supported, run at the boundary) — or a refusal carried explicitly, so an agent can never mistake a refusal for an answer. draft_action goes one step further: it maps a grounded answer into a structured proposal (an incident from an RCA, a pr_summary from a change) whose every field is a verbatim claim or evidence fragment carrying its own verified verdict — all_grounded is true only when every field passes — and an incompatible or refused grounding is carried as a refusal, never drafted over. preview_payload goes one boundary further still: it renders the exact GitHub request that proposal would send — a create-issue for an incident, a PR comment for a pr_summary — where every value traces to a verified field and the body is byte-reconstructable from those fields, or the payload is withheld (rendered only when all_grounded). execute_action takes the last step: it runs the grounded action through a simulated actuator that records the exact request and sends nothing — gated on a fully-grounded payload, so nothing executes over ungrounded ground — returning an ExecutionReceipt (the lossless request + its grounded slots + the outcome). A real GitHub actuator exists as an opt-in seam (double-gated on approval and a credential, so sent=True is earned), but the MCP surface wires the simulated actuator only — the server holds no credential and can never send. Tessera drafts, verifies, renders, and simulates; nothing is sent from this repository ({owner}/{repo} stay unbound; the real actuator's network is never invoked in CI) — a human or agent approves and sends outside Tessera (the honest edge). The trust contract is measured to survive the protocol for answers, actions, payloads, and executions: the boundary projections are lossless and faithfulness stays 1.0 over every gold case, every data-derived action, every data-derived payload, and every data-derived execution (tests/test_boundary.py, tests/test_actions_boundary.py, tests/test_payloads_boundary.py, tests/test_execution_boundary.py). A captured real client↔server session — grounded answers, the ER trail, a drafted incident and PR summary, a rendered create-issue and PR-comment payload, a simulated execution of each, and carried refusals — is committed at data/mcp_session/TRANSCRIPT.md. And the last edge has been crossed — exactly once, on the record (Milestone 15): a maintainer-approved, best-effort-idempotent (ADR 0026) real one-shot created tessera-exec-oneshot#1 from a grounded incident over a real CI failure; the scrubbed ExecutionReceipt is committed at data/execution/. The default actuator everywhere — tests, CI, the MCP surface — remains the simulated one; CI never touches the real network.

Data

Both modalities arrive through one ingestion path:

• Structured — data/salt_synthetic/, synthetic data generated by scripts/generate_salt_synthetic.py using the schema of SAP's SALT (Sales Autocompletion Linked Business Tables; arXiv:2501.03413): the same tables, columns, and join keys. We ship synthetic data because real SALT is access-gated (CC-BY-NC-SA) and redistributing a derived sample is legally unclear; using SALT's real schema means the actual dataset is a drop-in. Regenerate it deterministically with uv run python scripts/generate_salt_synthetic.py. See data/salt_synthetic/NOTICE. Tessera has since run on the real gated SALT dataset — deterministic FK-linked grounding with claim-level provenance on the actual records, plus the measured finding that real SALT is fully anonymized (its difficulty is relational, not lexical): docs/SALT_REAL.md. No real SALT data is committed; the run is reproducible with gated access.
• Unstructured — data/business_docs/, a small corpus of authored agreements/correspondence that reference the same synthetic customers under variant name forms (so entity resolution is genuine) and carry information the tables lack (renewal clauses, terms, special conditions).
• DevEx — data/devex_synthetic/, the second vertical's corpus: pipeline runs + logs, PRs + unified diffs, tickets, a service catalog, and an on-call export. Generated by scripts/generate_devex_synthetic.py with no RNG — every record a fixed, reviewable literal — including recurring failure signatures across runs and an incident ticket, PR↔ticket references, and service-name variants with measured resolution outcomes (two of which deliberately do not resolve).

All of it deliberately contains entity-resolution difficulty, and every planted miss is named in the data's README rather than hidden.

Repository map

Status

Phases 0–4 complete, plus fifteen post-roadmap milestones (see docs/STATUS.md and the changelog): both verticals run on one measured engine, the faithfulness floor is gated in CI, and the Joule-style session and SAP deployment path are in place. When every number had reached 1.000, milestone 5 made the eval able to fail again — the first real connector (GitHub Actions) surfaced a miss no one planted (coverage 0.000 → 1.000, closed deterministically), multi-hop answers and free-form phrasing landed, and scale and the ER over-merge risk were measured. Milestones 6–7 then acted on the embeddings trigger on SAP HANA Cloud — closing an error-class synonymy retrieval miss, then carrying embeddings into ER recall and log granularity. Milestone 8 cured the generic-suffix ER over-merge by stem-gating the deterministic pass (difflib precision 0.50 → 1.00, fully offline, ADR 0018). Milestone 9 made ER multi-field — the address is a second deterministic signal that splits two distinct firms sharing a name, closing the M8 residuals with a measured before/after (business gold quality 0.900 → 1.000) and the demo clusters provably unchanged except the one intended split (ADR 0019). Milestone 10 added the registration key (VATRegistration) as the most decisive field, closing the last floor the address couldn't reach — two distinct firms with the same name and the same address, split on their different VATs (0.909 → 1.000), with no engine logic change (it reuses the M9 exact-equality gate; ADR 0020). With the ER lever spent, milestones 11–14 opened the agentic dimension: M11 exposed the engine to AI agents over MCP as read-only grounded tools and measured the trust contract across the protocol (ADR 0022); M12 extended it from answers to propose-and-approve action drafts, every field verifier-checked (ADR 0023); M13 carried it one boundary further to the dry-run executable-payload preview — the exact GitHub request a drafted action would send, every value traced to a verified field, rendered but never sent (ADR 0024); and milestone 14 reached effectful execution behind approval — a simulated actuator that sends nothing (the CI-verifiable core) plus an opt-in real path, both gated on a fully-grounded payload, with an execution receipt as the trust record (ADR 0025). Each of the four boundaries is measured to preserve faithfulness 1.0. The write-up tells the story — including what is honestly not yet done (more connectors, the registry-only ER floor, and true million-record scale). Milestone 15 crossed the last edge of the execution arc — actually sending behind approval, best-effort idempotent (ADR 0026), exactly once, recorded as a committed scrubbed receipt (data/execution/ → tessera-exec-oneshot#1) — and Milestone 16 preceded it with a full self-audit and trust-path hardening (docs/AUDIT_2026-07-02.md). Act 2 then made it a product: milestone 17 put the demo live for humans (the hosted web surface + a recorded session of a real Claude agent grounded only through the MCP tools), milestone 18 made it usable on your data (tessera connect github, tessera ingest, the pilot runbook), and milestone 19 made it launch-ready — the Faithfulness Floor benchmark, the registry artifacts, a run on the real gated SALT dataset, and the HANA knowledge-graph mirror seam. The plan: docs/ROADMAP2.md, grounded in the audit and a sourced market snapshot (docs/MARKET.md).

License

Code is MIT (intended). The synthetic dataset under data/salt_synthetic/ is also covered by the project's MIT license — it is our own generated data and carries no third-party encumbrance. It is modeled on the schema of SAP's SALT dataset (credited in data/salt_synthetic/NOTICE); the real SALT dataset is gated and is not redistributed here.