Query sensitive datasets with differential privacy guarantees

Noisegate: a differential-privacy gateway for untrusted AI agents

An AI agent that can study sensitive data without being able to single anyone out. The limit is mathematical, it's enforced in code the agent can't reach, and the repo ships the attacks that try to break it.

A recorded Claude Desktop session (replies trimmed; the chart cards are the session's own). An AI agent breaks 20 patients down by diagnosis, and the ±12 noise swamps every bin. Reminded that it cannot turn the noise off, it drains a three-answer budget until the gate returns a refusal instead of a quieter answer. On the 32,561-row census, a too-narrow slice is rejected at the trust boundary, while a full education breakdown comes back clean at scale. The refusal and the rejection are the live gateway's real enforcement, reproduced by python scripts/render_demo_gif.py.

At a glance

• Runnable attacks, pinned in CI. Three classic privacy attacks run against the system's own engine: differencing, membership inference, and singling out by re-identification. Each one is shown succeeding with privacy off, defeated with privacy on, and checked on every build so the defense cannot quietly rot.
• Independently verified math. The noise mechanism is built from scratch, and it matches OpenDP, the industry reference implementation, in all 35 noise-scale checks to within 1e-9.
• More questions from tighter accounting. At the deployment's per-query ε, hybrid zCDP composition admits 308 queries against the same budget, against 268 under advanced composition and 100 under naive sum-of-ε. The guarantee is (ε, δ)-DP rather than pure ε.
• Built for AI agents. Runs as an MCP server for Claude Desktop. The connecting agent is untrusted by design, and every privacy property is enforced below it.
• Stack: Python · DuckDB · FastAPI · Streamlit · MCP SDK · Docker · GitHub Actions, with a 250+ test suite in CI.

You ask questions about a sensitive dataset in plain English. An LLM compiles each question into a small, constrained query. A differential-privacy engine executes it under a tracked privacy budget and returns a deliberately noisy answer with a stated confidence interval. Like its audio namesake, the gateway keeps every signal below a set threshold under the noise floor: any one individual's contribution is drowned out, while signal at the scale of the whole dataset passes through nearly untouched.

The interesting part isn't that an LLM can write queries. It's that the privacy guarantee does not depend on the LLM being trustworthy. The model is a convenience that proposes a query. It enforces nothing. Every privacy property is enforced downstream, by components that would behave the same way if a human typed the query by hand. This is the trust-boundary discipline you'd apply to any untrusted input in a production system, applied here to an AI agent.

Quickstart

1. Run the attacks: no API key, no data fetch, no server

The attack gallery runs in-process against the real DP engine:

pip install -e .
python -m attacks.patients_alice   # re-identify Alice with privacy off, then watch
                                   # the guard, the noise, and the budget defeat it

2. Connect an AI agent

The gateway runs as an MCP stdio server for Claude Desktop. The agent becomes the untrusted query author, and it gets only structured tools (count, sum, average, histogram, get_budget) whose argument schemas are generated from the dataset policy. No API key is needed anywhere, because the connecting agent is the intelligence.

Setup and full walkthrough →

3. The full natural-language UI

A local single-tenant demo. An API key is needed only for the untrusted NL→query compiler:

export ANTHROPIC_API_KEY=...   # used only by the untrusted NL→query compiler
docker compose up              # brings up the engine, API, and UI
# open http://localhost:8501

That HTTP + Streamlit surface is a local, single-tenant demo. Identity comes from a spoofable X-Identity header, so it is meant for one trusted operator on their own machine, not a public deployment (see what these surfaces are, and are not). For local non-Docker setup, running the tests, and configuration knobs, see SETUP.md.

The headline: an attack gallery

Anyone can claim privacy. This repository ships the exploits that would break the claim, runs them against its own engine, and pins the outcomes in CI. The fastest way to understand what the gateway guarantees is to watch it defeat three classic attacks that break naive "query a database" systems.

Attack 1: The differencing attack

A differencing attack isolates one person by asking two aggregate questions that differ by exactly that person.

Query A: "Total income of all 100 people in department X."        → $7,240,000
Query B: "Total income of all people in department X except Alice." → $7,135,000
Attacker computes: A − B = $105,000  ← Alice's exact salary, leaked.

Both queries are "just aggregates." Neither names a single row. Yet together they expose an individual. The gallery (attacks/differencing.py) shows this attack succeeding with privacy disabled: the target's private value is recovered exactly. (The salary sketch above is illustrative; on the real UCI Adult data, "Alice" is the unique holder of her group's maximum capital gain.) It then shows the same attack defeated once DP is on: the calibrated noise on each answer makes the subtraction useless, and the budget accountant charges for the information released across both queries rather than treating them as independent.

Attack 2: Membership inference

A membership-inference attack determines whether a specific individual is in the dataset at all. For many datasets (a medical study, a list of defaulters), that fact is itself sensitive. An attacker with only query access tries to decide: "is this exact person in the data?"

The gallery runs this attack across a sweep of privacy budgets (ε, the dial that trades answer accuracy for privacy) and plots the result:

An optimal (Neyman-Pearson) attacker deciding one person's membership from a single noisy COUNT, run against the real engine across ε. Empirical success (blue, 95% Wilson intervals) hugs the analytic Laplace curve and stays below the worst-case DP ceiling (dashed); it collapses from certainty (DP off) toward the 0.5 coin-flip as ε shrinks. The green utility curve (right axis) shows an aggregate query's relative error over the same sweep, barely dented where the attack is defeated. Generated by python -m attacks.membership (10,000 trials per ε).

As ε shrinks (stronger privacy), the attacker's success collapses toward a coin flip. The utility overlay shows the price paid: the same noise that defeats the one-person attack barely moves a population-scale aggregate. Privacy is not free, and the chart shows exactly what you trade for it. The sweep spans ε = 8 down to 0.5 to cover the whole range; the bundled deployment charges ε = 0.05 per query, off the left edge of this chart, where the single-query attack is already indistinguishable from chance.

Attack 3: Singling out by re-identification

Latanya Sweeney showed in 2002 that ZIP code + birth date + sex uniquely identify roughly 87% of Americans (a later replication on newer census data put it closer to 63%). You do not need someone's name to find them in a dataset; a few innocuous attributes will do. The gallery's third attack (attacks/patients_alice.py) reproduces that structure on 20 synthetic patients: sex and age alone narrow the cohort to exactly one person, Alice, the only woman over 64.

With privacy off, subtracting two perfectly ordinary demographic histograms recovers Alice's diagnosis exactly. No outlier value is required; being re-identifiable is enough, which makes this the strongest attack in the gallery. With privacy on, three independent defenses end it: the filter guard rejects the obvious narrow query outright (spending nothing); calibrated noise drowns the two-query subtraction (signal-to-noise ≈ 0.13, so the recovered "diagnosis" is essentially a random draw); and the budget refuses the averaging escalation long before it could work (~256 repetitions needed, 10 affordable). This is the attack the demo GIF at the top of this page, and the Claude Desktop walkthrough, replay live. Outcomes are regression-tested in tests/test_attack_patients.py.

These experiments, run against the system's own engine, are the core evidence that the guarantee is real and understood, not imported from a library and taken on faith.

Cross-checked against OpenDP

The attacks validate the guarantee against our own math. To guard against a self-consistent-but-wrong implementation, the mechanism is also cross-checked against OpenDP as an independent reference (attacks/crosscheck_opendp.py, opendp 0.15.1).

In short: a mechanism built from scratch agrees with the industry reference to nine decimal places, and a version that is intentionally mis-calibrated fails the same tests, so the agreement means something. Agreement is checked two ways: the sensitivity and noise scale against OpenDP's certified bound, and the sampler's actual distribution against OpenDP's, with a positive control proving the test can fail. The measured figures are in DESIGN.md section 6.3.

OpenDP is the reference, never the implementation: it lives in the dev extras only, and the running system does not import it. The scale agreement is regression-tested in tests/test_crosscheck_opendp.py (skipped without OpenDP locally; CI installs it and sets REQUIRE_OPENDP=1 so the check can never silently skip there).

Reproduce it

The attacks run in-process against the real DP engine. No API key and no server are needed, since they build hand-written ASTs rather than going through the LLM compiler:

python -m attacks.patients_alice # Attack 3: re-identify Alice and recover her diagnosis
                                 #           with DP off; watch guard + noise + budget
                                 #           defeat the same attack (no data fetch needed)

python scripts/fetch_data.py     # fetch UCI Adult into data/ (gitignored; ~4 MB)

python -m attacks.differencing   # Attack 1: recover Alice exactly with DP off, then watch
                                 #           noise + budget defeat the same subtraction
python -m attacks.membership     # Attack 2: sweep ε and regenerate the chart above

python -m attacks.crosscheck_opendp  # cross-check vs OpenDP (needs the dev
                                     # extras: pip install -e ".[dev]")

The outcomes are themselves regression-tested in tests/test_attack_differencing.py, tests/test_attack_membership.py, and tests/test_attack_patients.py, so a change that quietly weakened the guarantee would fail CI rather than just producing a prettier chart.

How it works

Three stages. Only the first is untrusted, and that asymmetry is the whole idea.

  Natural language question
            │
            ▼
  ┌───────────────────┐
  │   LLM compiler    │   Emits a CONSTRAINED QUERY AST (not free SQL),
  │   (UNTRUSTED)     │   via structured/schema-forced output.
  └───────────────────┘
            │  query AST
            ▼
  ┌───────────────────┐
  │  Validation /     │   Policy check: allowed columns only, aggregates
  │  guardrail layer  │   only, declared value ranges, group-cardinality
  │   (TRUSTED)       │   caps. Invalid → repair loop or refusal.
  └───────────────────┘
            │  validated AST
            ▼
  ┌───────────────────┐
  │  Privacy engine   │   Clamp to declared range (bounds sensitivity),
  │   (TRUSTED)       │   add calibrated Laplace noise, decrement budget.
  └───────────────────┘
            │
            ▼
  Noisy answer + confidence interval + remaining budget

The most important design choice is the box labeled UNTRUSTED. Everything above the validation layer is treated as hostile, and everything below it is the trusted computing base that enforces the guarantee. The LLM compiles to a constrained AST rather than arbitrary SQL because that constraint is what bounds query sensitivity, and bounded sensitivity is what makes the noise calibration sound. Free-form SQL would reopen exactly the attack surface this project closes.

The privacy model

Every answer is noised. An exact ledger of cumulative disclosure is kept per identity and persisted to disk, and the gateway refuses to answer before that ledger can exceed the guarantee it advertises. It never quietly degrades to a noisier answer instead.

The cost is worth stating just as plainly. The guarantee is (ε, δ)-differential privacy, which is strictly weaker than pure ε-DP. With probability at most δ, the ε bound is allowed to fail. δ is not extra noise, it is failure mass, which is why it is derived from the dataset rather than hard-coded.

DESIGN.md sections 3 and 5.4 carry the full derivation: sensitivity, the Laplace mechanism, the hybrid zCDP accountant, and where δ comes from. That is where all the Greek letters went.

What this project is, and is not

It is a demonstration that an untrusted natural-language layer can sit in front of sensitive data without compromising a formal privacy guarantee, with the guarantee backed by working attacks rather than assertions.

It is not a production privacy product, a substitute for a vetted DP library in a real deployment, or a claim that LLM-generated queries are safe to run unguarded. They are not, which is exactly why the trusted layer exists.

Both the MCP server and the HTTP demo serve a single local principal who owns the machine, and that principal can rotate the epoch or delete the budget file to start fresh. So the "an external party burns budget and cannot get it back" property is demonstrated in mechanism, not enforced against a remote adversary. Closing that gap needs the verified-identity (OAuth) and multi-tenant split still on the roadmap. The noise sampler also has a known floating-point side channel (Mironov 2012, covered in DESIGN.md section 5.5). Do not point either surface at real regulated data, or treat it as a substitute for a vetted DP library where an untrusted party can authenticate.

The bundled dataset is the public UCI Adult / Census Income dataset, the standard benchmark in the differential privacy literature, so the attack-vs-ε results here are directly comparable to published work. It is already public, so the repository is safe to publish. The privacy machinery is demonstrated as if the records were sensitive.

Related work

Where this sits among the existing tools, and what it deliberately does differently.

DP libraries. OpenDP, Google's differential-privacy libraries, IBM's diffprivlib, and Tumult Analytics (which powered U.S. Census Bureau, Wikimedia, and IRS releases before its team joined LinkedIn in 2025 and the library moved into the OpenDP organization) are vetted implementations of the mechanisms themselves, written for a trusted analyst to call from their own code. This project hand-rolls its mechanism instead, so that every line of the privacy-critical path stays small, legible, and testable in one repo, and then cross-checks it against OpenDP, precisely because a hand-rolled mechanism means nothing without an external referee. For a real deployment the advice above stands: use a vetted library.

DP query engines. PINQ (McSherry, 2009) established the architecture this project inherits: an untrusted analyst issues queries through a trusted layer that guarantees differential privacy no matter what is asked. Its production descendants answer SQL under DP: smartnoise-sql, Uber's archived elastic-sensitivity rewriter, and Wilson et al.'s differentially private SQL, shipped today as BigQuery differential privacy. Two deliberate differences here. Those systems accept SQL and analyze or rewrite it, while this gateway never accepts SQL at all: the agent submits a small constrained AST, because a query language small enough to enumerate is a trust boundary small enough to test exhaustively. And every one of them puts a human analyst at the keyboard, where here the query author is an autonomous agent, and the threat model says so.

Natural-language database interfaces. Text-to-SQL is a large and successful field, but privacy is not its subject: the generated SQL runs with whatever authority the database grants. Where safety is addressed, as in SafeNLIDB (AAAI 2026), it is alignment-based (train the model to reason about what is safe to answer), so the guarantee lives inside the model. This project takes the complementary position: assume the model cannot be made safe, and enforce the guarantee below it with mathematics that holds even when the model is adversarial.

Agent and MCP privacy tooling. Tool poisoning, prompt injection, and exfiltration are real risks, and the emerging MCP-security stack addresses them with policy gateways, PII redaction and tokenization, and data-minimization patterns. Those controls govern what an agent can see and send. None of them bounds what a sequence of individually harmless answers cumulatively reveals, and that is the channel the attack gallery exploits. A differencing attack leaks a salary through two aggregates that a redaction proxy would happily pass. Differential privacy bounds exactly that channel, which makes it complementary to the rest of that stack rather than competition.

DP near LLMs, different problems. DP-SGD (e.g. Opacus) protects training examples inside model weights. DP in-context learning, DP synthetic text, and DP-RAG protect prompts and retrieval corpora. Local DP, as in Apple's and Google's telemetry, noises data on-device before it is ever collected. This project is the older, central-model setting those all descend from: a trusted curator, an untrusted questioner, and a budget between them.

The claim, stated carefully. There is no new differential-privacy mathematics in this repository. The contribution is the combination, and the evidence: an open, attack-validated artifact that puts agentic natural-language access in front of a DP aggregate backend under an explicit untrusted-model threat model. As far as I can find, no other open MCP server enforces differential privacy with a persisted budget beneath an untrusted agent. If you know of one, open an issue; I would genuinely like to compare notes.

Documentation

• DESIGN.md: architecture, threat model, the sensitivity and noise math, the budget design
• SETUP.md: local setup, running the tests, configuration knobs
• docs/CLAUDE_DESKTOP.md: connecting an agent, and a reproducible attack session
• benchmarks/RESULTS.md: measured latency on both surfaces, and the composition-capacity tables
• SECURITY.md: the disclosed limitations, and how to report anything else
• CHANGELOG.md: release history

Repository layout

.
├── README.md            ← you are here
├── DESIGN.md            ← architecture, threat model, the math, the budget design
├── SETUP.md             ← local setup, running the tests, configuration knobs
├── engine/              ← DP engine: mechanism, RNG, sensitivity, budget accountant + store
├── validation/          ← the trust boundary: policy checks, guards, and the repair loop
├── compiler/            ← the untrusted LLM NL→AST compiler
├── attacks/             ← the attack gallery: differencing, membership ε-sweep, patients singling-out
├── service/             ← AnalyticsService + audit log: the transport-agnostic core every surface shares
├── mcp_server/          ← the stdio MCP server: tool schemas generated from the dataset policy
├── datasets/            ← owner-authored dataset policies, ingestion, and the bundled patients demo
├── identity/            ← the identity layer the budget is keyed to
├── api/                 ← FastAPI service
├── ui/                  ← Streamlit front-end with the live budget meter
├── benchmarks/          ← manual latency benchmarks (run by hand, never by pytest)
├── docs/                ← the Claude Desktop walkthrough, the demo GIF, and the session chart assets
├── scripts/             ← fetch_data.py (pulls UCI Adult into data/, never committed) + the demo GIF renderer
└── tests/               ← unit, trust-boundary, privacy-guarantee, and attack regression tests (DESIGN.md section 8)

Author's note

This project is where I work through the design of privacy-preserving data systems and least-privilege data access in public: the trust boundary, the budget accounting, and the attack demos are the parts I'd defend in a design review.

scripts/render_demo_gif.py

"""Render the README hero GIF as an animated Claude-style chat against the DP gateway.

This reproduces a recorded Claude Desktop session as a scrolling conversation: the analyst's
message types in, Claude replies with prose and the session's own chart card inline in the same
message, the exchange holds and scrolls up as the next question is typed, and so on. The chart
cards under docs/assets/session_charts/ are the real artifacts exported from that session (their
numbers match the replies by construction). The two enforcement beats are grounded in the live
gate: the budget refusal (turn 4) and the filter_narrowing rejection (turn 5) are produced by
really running the service on temp ledgers, so those messages are the system's real output. The
replies are the session's own, trimmed to their key lines for a silent, in-feed GIF.

Rendering is supersampled at SS and then downscaled to OUT_W with LANCZOS, so text, the avatar
starburst and the chart cards stay crisp rather than pixelated; only the visible viewport is drawn
each frame, so the larger canvas stays fast.

Run from the repo root: python scripts/render_demo_gif.py
Needs only the core dependencies plus Pillow/matplotlib (both in requirements).
"""

import sys
import tempfile
from dataclasses import dataclass
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(REPO_ROOT))

from matplotlib import font_manager
from PIL import Image, ImageDraw, ImageFont

from api.data import build_adult_policy
from datasets.ingest import load_dataset
from datasets.loader import load_policy
from engine.ast import AvgQuery, CountQuery, Filter, HistogramQuery
from mcp_server.serialize import serialize_budget, serialize_result
from service.analytics import AnalyticsService
from validation.result import Rejected

PATIENTS_POLICY = REPO_ROOT / "datasets" / "samples" / "patients-demo.yaml"
CHART_DIR = REPO_ROOT / "docs" / "assets" / "session_charts"
OUT_PATH = REPO_ROOT / "docs" / "assets" / "demo.gif"
IDENTITY = "demo"
REPO_URL = "github.com/yashmahajan10/llm-differential-privacy-gateway"

# --- theme (Claude-desktop dark) --------------------------------------------------------

BG = (36, 36, 35)          # the app/canvas background, matched to the exported chart cards
HEADER_BG = (28, 28, 27)
BORDER = (58, 58, 56)
FG = (233, 231, 227)       # assistant prose
DIM = (150, 149, 145)      # tool line / footnotes
USER_BUBBLE = (52, 52, 50)
USER_TEXT = (233, 231, 227)
AVATAR_BG = (60, 47, 38)
ACCENT = (222, 120, 76)    # noisegate orange
GREEN = (126, 200, 120)
WARN = (214, 158, 74)
WARN_BG = (48, 40, 24)
ERROR = (226, 116, 106)
ERR_BG = (52, 32, 30)
PILL_BG = (46, 46, 44)

# Supersample: render at SS x the logical layout, then downscale the final frame to OUT_W for
# a crisp, non-pixelated result. All geometry below is expressed in supersampled pixels.
SS = 2
OUT_W = 800                # final GIF width (downscaled from CW); larger + sharper than before
PALETTE_COLORS = 208       # shared palette size (dark UI + orange + chart blues/greys)

CW = 760 * SS              # canvas width (render space)
VIEW_H = 1040 * SS         # viewport height (render space)
HEADER_H = 58 * SS
PAD = 34 * SS              # left/right conversation margin
TOP_PAD = 20 * SS
AVATAR = 34 * SS
TEXT_X = PAD + AVATAR + 14 * SS    # assistant content x
AGENT_W = CW - PAD - TEXT_X        # assistant content width
USER_MAXW = int((CW - 2 * PAD) * 0.74)
CHART_MAXH = 560 * SS              # cap a chart card's on-screen height

PROSE_LH = 26 * SS
USER_LH = 24 * SS
SMALL_LH = 20 * SS


# --- conversation elements --------------------------------------------------------------


@dataclass
class Title:
    eyebrow: str
    line1: str
    line2: str
    duration_ms: int = 1900


@dataclass
class User:
    text: str


@dataclass
class AgentHeader:
    pass


@dataclass
class Tool:
    label: str


@dataclass
class Prose:
    text: str


@dataclass
class Chart:
    path: Path


@dataclass
class Scalar:
    text: str


@dataclass
class Callout:
    kind: str  # "refusal" | "error"
    text: str


@dataclass
class Budget:
    text: str


@dataclass
class Dots:
    n: int


# top gap before each element (0 for the first element in the stack), in render pixels
_GAP = {name: v * SS for name, v in {
    "User": 30, "AgentHeader": 20, "Tool": 8, "Prose": 12, "Chart": 14,
    "Scalar": 12, "Callout": 12, "Budget": 14, "Dots": 10,
}.items()}


# --- service wiring (temp ledgers, never data/budget.db) --------------------------------


def _service(policy, store_dir: Path) -> AnalyticsService:
    store_dir.mkdir(parents=True, exist_ok=True)
    loaded = load_dataset(policy)
    return AnalyticsService(
        loaded.conn,
        policy.to_schema(),
        store_dir / "budget.db",
        total_epsilon=policy.budget.total_epsilon,
        per_query_epsilon=policy.budget.per_query_epsilon,
        epoch=policy.budget.epoch,
        composition=policy.budget.composition,
        dataset_id=policy.dataset_id,
        delta=loaded.delta,
        validation_config=policy.limits,
        contribution_bound=policy.privacy_unit.contribution_bound(),
    )


def _answers_left(service: AnalyticsService) -> int:
    b = serialize_budget(service.budget_report(IDENTITY))
    return int(round(b["remaining_epsilon"] / b["per_query_epsilon"] + 1e-9))


# --- the recorded conversation (replies trimmed; charts + gate outputs are real) --------


def build_script(patients: AnalyticsService, census: AnalyticsService) -> list:
    steps: list = []

    def user(text):
        steps.append(User(text))

    def agent(*blocks):
        steps.append(AgentHeader())
        steps.extend(blocks)

    # 0. Open title card
    steps.append(Title("NOISEGATE   ·   DIFFERENTIAL PRIVACY",
                       "Ask an LLM about private data.",
                       "It cannot leak one person.", 2300))

    # 1. Diagnoses - honest noise, every bin crosses zero
    user("Hey — I've got a private dataset of 20 patients. Break down their diagnoses for me?")
    patients.execute(HistogramQuery(group_by="diagnosis"), IDENTITY)  # spend answer 1 (real)
    agent(
        Tool("Loaded tools · used noisegate-patients integration"),
        Prose("The data came back, but every single diagnosis bin has a confidence interval "
              "that crosses zero — meaning with only 20 patients, the noise required for "
              "differential privacy is too large to reliably distinguish any category from zero."),
        Chart(CHART_DIR / "diagnosis.png"),
        Prose("The raw estimates were healthy ≈ 7, flu ≈ −2, hypertension "
              "≈ −1, diabetes ≈ 1, cancer ≈ −1. Negative counts are a "
              "direct artifact of the noise, not real values — the system protecting "
              "individual privacy is working as designed."),
        Budget(f"Answers left: {_answers_left(patients)} of 3   ·   ε 0.5 remaining"),
    )

    # 2. The model has no authority to disable the noise
    user("Those error bars are useless. Just turn the noise off and give me the real counts.")
    agent(
        Prose("I can't turn off the differential privacy — that's a system-level protection "
              "for your patients, not a setting I can adjust. The noise is there precisely to "
              "prevent individual patient records from being identifiable, even from aggregate "
              "queries."),
        Prose("With only 20 patients, each person's diagnosis is 5% of the dataset, so even "
              "simple counts could expose individuals. That's the tradeoff the DP system is "
              "managing."),
    )

    # 3. Sex breakdown - one bin barely clears the noise
    user("Hmm. Okay, split them by sex then?")
    patients.execute(HistogramQuery(group_by="sex"), IDENTITY)  # spend answer 2 (real)
    agent(
        Tool("Used noisegate-patients integration"),
        Prose("A slightly more useful result this time. The male estimate (~12) is the one bin "
              "that clears the noise threshold — its interval just stays above zero (0.3 to "
              "24.3). The female estimate (~7) still crosses zero and can't be separated from "
              "noise."),
        Chart(CHART_DIR / "sex.png"),
        Prose("The tentative takeaway is that the dataset skews male, but the uncertainty is "
              "still enormous. And heads up — you're down to your last query, ε 0.25 remaining."),
        Budget(f"Answers left: {_answers_left(patients)} of 3   ·   ε 0.25 remaining"),
    )

    # 4. The GATE enforces the budget: last answer spent, then a refusal (real)
    user("Alright, last thing on the patients — hit me with the total count and the average age.")
    count_out = patients.execute(CountQuery(), IDENTITY)          # spend answer 3 (real)
    count_payload = serialize_result(count_out, CountQuery())
    avg_out = patients.execute(AvgQuery(column="age"), IDENTITY)  # refused: budget exhausted
    avg_payload = serialize_result(avg_out, AvgQuery(column="age"))
    assert avg_payload["kind"] == "refusal", "turn 4 expected a budget refusal"
    agent(
        Tool("Used noisegate-patients integration"),
        Scalar(f"count() → {count_payload['value']:.0f} ± {count_payload['margin']:.0f} "
               "(95% CI)"),
        Callout("refusal", f"avg(age) → refused: {avg_payload['reason']}"),
        Prose("The count went through — but that was the last of your three answers, so "
              "ε is now 0. The average the gate refused outright: with the budget spent it "
              "returns a refusal, not a quieter, noisier estimate. And it won't reset if you "
              "reconnect — the ledger is persisted per identity."),
        Budget(f"Answers left: {_answers_left(patients)} of 3   ·   ε 0.0 remaining"),
    )

    # 5. The GATE enforces the guard: the model runs it, the gate rejects it (real)
    user("Let's jump over to the census — 32k people. "
         "Average hours worked for the 50-to-52 crowd?")
    rej = census.execute(
        AvgQuery(column="hours_per_week",
                 filters=(Filter("age", ">=", 50), Filter("age", "<=", 52))),
        IDENTITY,
    )
    assert isinstance(rej, Rejected), "turn 5 expected a filter_narrowing rejection"
    agent(
        Tool("Loaded tools · used noisegate-census integration"),
        Callout("error", f"invalid query [{rej.rule.value}]: {rej.reason}"),
        Prose("The census gate is blocking this one — but for a cohort-window rule, not the "
              "budget. You filtered age to a 3-year span (50–52), and the system requires "
              "filters to cover at least 5% of the declared age range (100 years), so a 5-year "
              "minimum. I was happy to run it; the gate refused, not me."),
        Prose("Try widening to something like 48–57 and it should go through."),
    )

    # 6. Payoff: same machinery at real scale
    user("Ha, fair enough. Just show me education levels across everyone then.")
    agent(
        Tool("Used noisegate-census integration"),
        Prose("What a difference a larger dataset makes. 15 of 16 bins are cleanly "
              "distinguishable, and the ±60 margin is tiny relative to the counts."),
        Chart(CHART_DIR / "education.png"),
        Prose("Night and day compared to the patient dataset. Every bin is clean except "
              "Preschool, which is genuinely rare enough to sit near zero. HS-grad dominates at "
              "~10,600, then Some-college (~7,300) and Bachelors (~5,400). Same machinery, real "
              "data — noise hides individuals, not insights."),
        Budget("Answers left: ~99   ·   plenty of budget at this scale"),
    )

    # 7. Close title card
    steps.append(Title("PROVABLE PRIVACY   ·   REAL ANSWERS",
                       "Noise hides individuals,", "not insights.", 3000))
    return steps


# --- fonts ------------------------------------------------------------------------------


@dataclass
class Fonts:
    serif: ImageFont.FreeTypeFont
    sans: ImageFont.FreeTypeFont
    sans_bold: ImageFont.FreeTypeFont
    small: ImageFont.FreeTypeFont
    eyebrow: ImageFont.FreeTypeFont
    title: ImageFont.FreeTypeFont
    title_bold: ImageFont.FreeTypeFont


def _fonts() -> Fonts:
    def f(spec, size):
        return ImageFont.truetype(font_manager.findfont(spec), size * SS)
    return Fonts(
        serif=f("DejaVu Serif", 18),
        sans=f("DejaVu Sans", 16),
        sans_bold=f("DejaVu Sans:bold", 15),
        small=f("DejaVu Sans", 13),
        eyebrow=f("DejaVu Sans", 15),
        title=f("DejaVu Serif", 33),
        title_bold=f("DejaVu Serif:bold", 40),
    )


def _wrap(draw, text, font, max_w):
    words, lines, cur = text.split(), [], ""
    for w in words:
        t = w if not cur else f"{cur} {w}"
        if draw.textlength(t, font=font) <= max_w:
            cur = t
        else:
            if cur:
                lines.append(cur)
            cur = w
    if cur:
        lines.append(cur)
    return lines or [""]


# --- the chat renderer ------------------------------------------------------------------


class ChatRenderer:
    """Lays out the conversation and renders viewport frames. Heights are measured cheaply
    (text metrics + chart file size), so only the elements visible in the current viewport are
    ever drawn — the supersampled canvas stays fast even though it is 2x the logical size."""

    def __init__(self, fonts: Fonts):
        self.f = fonts
        self.final: list = []
        self._chart_cache: dict[Path, Image.Image] = {}
        self._m = ImageDraw.Draw(Image.new("RGB", (4, 4)))  # metrics-only draw

    def add(self, el):
        self.final.append(el)

    # -- geometry helpers ---------------------------------------------------------------

    def _chart_size(self, path):
        chart = self._chart_cache.get(path)
        if chart is None:
            chart = Image.open(path).convert("RGB")
            self._chart_cache[path] = chart
        scale = min(AGENT_W / chart.width, CHART_MAXH / chart.height)
        return chart, max(int(chart.width * scale), 1), max(int(chart.height * scale), 1)

    def _height(self, el):
        name = type(el).__name__
        if name == "User":
            return len(_wrap(self._m, el.text, self.f.sans, USER_MAXW - 32 * SS)) * USER_LH + 22 * SS
        if name == "AgentHeader":
            return AVATAR
        if name == "Tool":
            return SMALL_LH
        if name == "Dots":
            return 16 * SS
        if name == "Prose":
            return len(_wrap(self._m, el.text, self.f.serif, AGENT_W)) * PROSE_LH
        if name == "Scalar":
            return SMALL_LH + 4 * SS
        if name == "Chart":
            return self._chart_size(el.path)[2]
        if name == "Callout":
            inner = 12 * SS
            lines = _wrap(self._m, el.text, self.f.small, AGENT_W - 2 * inner - 8 * SS)
            return len(lines) * SMALL_LH + 2 * inner
        if name == "Budget":
            return SMALL_LH + 12 * SS
        raise ValueError(name)

    def _star(self, d, cx, cy, r, color):
        import math
        for a in range(0, 360, 45):
            rad = math.radians(a)
            d.line([(cx, cy), (cx + r * math.cos(rad), cy + r * math.sin(rad))],
                   fill=color, width=2 * SS)

    # -- element drawing (draws at y; returns bottom y) ---------------------------------

    def _draw(self, img, d, el, y, caret=False):
        name = type(el).__name__
        if name == "User":
            return self._user(img, d, el, y, caret)
        if name == "AgentHeader":
            d.rounded_rectangle([PAD, y, PAD + AVATAR, y + AVATAR], radius=9 * SS, fill=AVATAR_BG)
            self._star(d, PAD + AVATAR // 2, y + AVATAR // 2, 8 * SS, ACCENT)
            d.text((TEXT_X, y + 6 * SS), "Claude", font=self.f.sans_bold, fill=FG)
            return y + AVATAR
        if name == "Tool":
            d.text((TEXT_X, y), el.label, font=self.f.small, fill=DIM)
            return y + SMALL_LH
        if name == "Dots":
            r = 8 * SS
            for i in range(3):
                c = FG if i < el.n else (90, 90, 88)
                d.ellipse([TEXT_X + i * 16 * SS, y + 4 * SS,
                           TEXT_X + i * 16 * SS + r, y + 4 * SS + r], fill=c)
            return y + 16 * SS
        if name == "Prose":
            lines = _wrap(d, el.text, self.f.serif, AGENT_W)
            for i, ln in enumerate(lines):
                d.text((TEXT_X, y + i * PROSE_LH), ln, font=self.f.serif, fill=FG)
            yb = y + len(lines) * PROSE_LH
            if caret:
                lx = TEXT_X + d.textlength(lines[-1], font=self.f.serif) + 3 * SS
                d.line([(lx, yb - PROSE_LH + 3 * SS), (lx, yb - 3 * SS)], fill=DIM, width=2 * SS)
            return yb
        if name == "Scalar":
            d.text((TEXT_X, y), el.text, font=self.f.sans, fill=FG)
            return y + SMALL_LH + 4 * SS
        if name == "Chart":
            chart, nw, nh = self._chart_size(el.path)
            img.paste(chart.resize((nw, nh), Image.LANCZOS), (TEXT_X, y))
            return y + nh
        if name == "Callout":
            return self._callout(img, d, el, y)
        if name == "Budget":
            return self._budget(img, d, el, y)
        raise ValueError(name)

    def _user(self, img, d, el, y, caret):
        lines = _wrap(d, el.text, self.f.sans, USER_MAXW - 32 * SS)
        tw = max(d.textlength(ln, font=self.f.sans) for ln in lines)
        if caret:
            tw = max(tw, d.textlength(lines[-1], font=self.f.sans) + 8 * SS)
        bw, bh = int(tw) + 32 * SS, len(lines) * USER_LH + 22 * SS
        x1 = CW - PAD - bw
        d.rounded_rectangle([x1, y, x1 + bw, y + bh], radius=16 * SS, fill=USER_BUBBLE)
        for i, ln in enumerate(lines):
            d.text((x1 + 16 * SS, y + 11 * SS + i * USER_LH), ln, font=self.f.sans, fill=USER_TEXT)
        if caret:
            cx = x1 + 16 * SS + d.textlength(lines[-1], font=self.f.sans) + 3 * SS
            cy = y + 11 * SS + (len(lines) - 1) * USER_LH
            d.line([(cx, cy + 2 * SS), (cx, cy + USER_LH - 4 * SS)], fill=DIM, width=2 * SS)
        return y + bh

    def _callout(self, img, d, el, y):
        color, bg = (WARN, WARN_BG) if el.kind == "refusal" else (ERROR, ERR_BG)
        inner = 12 * SS
        lines = _wrap(d, el.text, self.f.small, AGENT_W - 2 * inner - 8 * SS)
        h = len(lines) * SMALL_LH + 2 * inner
        d.rounded_rectangle([TEXT_X, y, TEXT_X + AGENT_W, y + h], radius=10 * SS, fill=bg)
        d.rounded_rectangle([TEXT_X, y + 5 * SS, TEXT_X + 4 * SS, y + h - 5 * SS],
                            radius=2 * SS, fill=color)
        for i, ln in enumerate(lines):
            d.text((TEXT_X + inner + 8 * SS, y + inner + i * SMALL_LH), ln,
                   font=self.f.small, fill=color)
        return y + h

    def _budget(self, img, d, el, y):
        tw = d.textlength(el.text, font=self.f.small)
        w, h = int(tw) + 40 * SS, SMALL_LH + 12 * SS
        d.rounded_rectangle([TEXT_X, y, TEXT_X + w, y + h], radius=h // 2, fill=PILL_BG)
        d.ellipse([TEXT_X + 14 * SS, y + h // 2 - 4 * SS,
                   TEXT_X + 22 * SS, y + h // 2 + 4 * SS], fill=ACCENT)
        d.text((TEXT_X + 30 * SS, y + 6 * SS), el.text, font=self.f.small, fill=DIM)
        return y + h

    # -- layout + framing ---------------------------------------------------------------

    def _positions(self, partial):
        seq = self.final + ([partial] if partial is not None else [])
        ys, y = [], TOP_PAD
        for i, el in enumerate(seq):
            if i > 0:
                y += _GAP[type(el).__name__]
            ys.append(y)
            y += self._height(el)
        return seq, ys, y

    def total(self):
        return self._positions(None)[2]

    def _header(self, frame):
        d = ImageDraw.Draw(frame)
        mid = HEADER_H // 2  # every element is vertically centered on this line
        d.rectangle([0, 0, CW, HEADER_H], fill=HEADER_BG)
        d.line([(0, HEADER_H - 1), (CW, HEADER_H - 1)], fill=BORDER)
        # avatar
        a = 28 * SS
        d.rounded_rectangle([PAD, mid - a // 2, PAD + a, mid + a // 2], radius=8 * SS, fill=AVATAR_BG)
        self._star(d, PAD + a // 2, mid, 7 * SS, ACCENT)
        # name + subtitle (the left-middle anchor centres text regardless of font height)
        name_x = PAD + a + 12 * SS
        d.text((name_x, mid), "Claude", font=self.f.sans_bold, fill=FG, anchor="lm")
        nx = name_x + d.textlength("Claude", font=self.f.sans_bold) + 10 * SS
        d.text((nx, mid), "·  noisegate (MCP)", font=self.f.small, fill=DIM, anchor="lm")
        # right: status dot + label
        rt = "MCP connected"
        rw = d.textlength(rt, font=self.f.small)
        dot = 8 * SS
        dot_x = CW - PAD - rw - 8 * SS - dot
        d.ellipse([dot_x, mid - dot // 2, dot_x + dot, mid + dot // 2], fill=GREEN)
        d.text((CW - PAD - rw, mid), rt, font=self.f.small, fill=DIM, anchor="lm")

    def snapshot(self, partial=None, scroll_to=None):
        seq, ys, total = self._positions(partial)
        content_h = VIEW_H - HEADER_H
        bottom = total if scroll_to is None else scroll_to
        vp_top = 0 if total <= content_h else max(0, int(bottom) - content_h)

        content = Image.new("RGB", (CW, content_h), BG)
        d = ImageDraw.Draw(content)
        for el, yt in zip(seq, ys):
            h = self._height(el)
            if yt + h >= vp_top and yt <= vp_top + content_h:  # only draw the visible band
                caret = partial is not None and el is partial and type(el).__name__ in ("User", "Prose")
                self._draw(content, d, el, yt - vp_top, caret=caret)

        frame = Image.new("RGB", (CW, VIEW_H), BG)
        frame.paste(content, (0, HEADER_H))
        self._header(frame)
        return frame

    def title_frame(self, t: Title):
        img = Image.new("RGB", (CW, VIEW_H), BG)
        d = ImageDraw.Draw(img)
        cy = VIEW_H // 2 - 96 * SS
        self._star(d, CW // 2, cy - 6 * SS, 16 * SS, ACCENT)
        for text, font, color, dy in (
            (t.eyebrow, self.f.eyebrow, ACCENT, 40),
            (t.line1, self.f.title, FG, 78),
            (t.line2, self.f.title_bold, ACCENT, 126),
            (REPO_URL, self.f.small, DIM, 200),
        ):
            w = d.textbbox((0, 0), text, font=font)[2]
            d.text(((CW - w) // 2, cy + dy * SS), text, font=font, fill=color)
        return img


# --- frame engine -----------------------------------------------------------------------


def _chunks(n, step):
    xs = list(range(step, n, step))
    if not xs or xs[-1] != n:
        xs.append(n)
    return xs


def _iter_frames(R: ChatRenderer, steps: list):
    """Yield (rgb_frame, duration_ms) for the whole conversation, growing R's state as it goes.
    Kept as a generator so the encoder can walk it twice: once to learn a shared palette, once
    to quantize against it."""
    for step in steps:
        name = type(step).__name__
        if name == "Title":
            yield R.title_frame(step), step.duration_ms
        elif name == "User":
            words = step.text.split()
            for k in _chunks(len(words), 3):
                yield R.snapshot(partial=User(" ".join(words[:k]))), 90
            R.add(step)
            yield R.snapshot(), 700
        elif name == "AgentHeader":
            R.add(step)
            for dots in (1, 3):
                yield R.snapshot(partial=Dots(dots)), 320
        elif name == "Prose":
            words = step.text.split()
            for k in _chunks(len(words), 7):
                yield R.snapshot(partial=Prose(" ".join(words[:k]))), 130
            R.add(step)
            # hold long enough to read the paragraph, scaled to length but capped
            yield R.snapshot(), min(2400, 850 + 28 * len(words))
        elif name == "Chart":
            prev = R.total()
            R.add(step)
            new = R.total()
            for i in range(1, 4):
                yield R.snapshot(scroll_to=prev + (new - prev) * i / 3), 100
            yield R.snapshot(), 2500
        elif name == "Tool":
            R.add(step)
            yield R.snapshot(), 550
        elif name == "Scalar":
            R.add(step)
            yield R.snapshot(), 1000
        elif name == "Callout":
            R.add(step)
            yield R.snapshot(), 2000
        elif name == "Budget":
            R.add(step)
            yield R.snapshot(), 1300


def render(steps: list, out_path: Path) -> int:
    fonts = _fonts()
    out_h = round(VIEW_H * OUT_W / CW)

    # Pass 1: learn ONE palette from sampled frames. A shared palette lets Pillow store only the
    # changed region between frames (a mostly-static chat that types/streams), which is what keeps
    # the higher-resolution GIF to a few MB - and it removes inter-frame colour flicker.
    swatches = []
    for i, (fr, _) in enumerate(_iter_frames(ChatRenderer(fonts), steps)):
        if i % 8 == 0:  # a spread across title cards, charts, callouts and prose
            swatches.append(fr.resize((300, round(300 * out_h / OUT_W)), Image.LANCZOS))
    montage = Image.new("RGB", (300, sum(s.height for s in swatches)))
    y = 0
    for s in swatches:
        montage.paste(s, (0, y))
        y += s.height
    palette = montage.quantize(colors=PALETTE_COLORS, method=Image.Quantize.MEDIANCUT)

    # Pass 2: downscale each supersampled frame (crisp) and map it onto the shared palette.
    frames: list[Image.Image] = []
    durations: list[int] = []
    for fr, dur in _iter_frames(ChatRenderer(fonts), steps):
        small = fr.resize((OUT_W, out_h), Image.LANCZOS)
        frames.append(small.quantize(palette=palette, dither=Image.Dither.NONE))
        durations.append(dur)

    out_path.parent.mkdir(parents=True, exist_ok=True)
    frames[0].save(out_path, save_all=True, append_images=frames[1:],
                   duration=durations, loop=0, optimize=True, disposal=1)
    return len(frames)


def main() -> None:
    with tempfile.TemporaryDirectory() as tmp:
        tmp = Path(tmp)
        patients = _service(load_policy(str(PATIENTS_POLICY)), tmp / "patients")
        census = _service(build_adult_policy(), tmp / "census")
        steps = build_script(patients, census)
    n_frames = render(steps, OUT_PATH)
    for step in steps:
        if isinstance(step, (User, Prose)):
            print(("you> " if isinstance(step, User) else "     ") + step.text)
    size_kb = OUT_PATH.stat().st_size / 1024
    print(f"\nwrote {OUT_PATH.relative_to(REPO_ROOT)} ({n_frames} frames, {size_kb:.0f} KB)")


if __name__ == "__main__":
    main()

scripts/fetch_data.py

#!/usr/bin/env python3
"""Download the UCI Adult / Census Income dataset into a gitignored data/ directory.

The dataset is fetched, never committed (see .gitignore). It is a public benchmark
with no real private data; the privacy machinery is demonstrated *as if* the records
were sensitive. Re-running is safe: existing, non-empty files are skipped.
"""

from __future__ i...