Project Blackbox

Autonomous data incident repair, with proof!

Comment

◾️ BlackBox

Autonomous incident response for data pipelines, powered by DataHub.

BlackBox takes a plain-English data incident, investigates it across the real DataHub graph, proves the root cause with machine-checked evidence, repairs the pipeline, verifies the fix, and writes the resolution back into DataHub.

READ → PROVE → ACT → VERIFY → WRITE

🚨 The problem

The hardest data incidents are not always the ones where something crashes.

Sometimes every job is green.

The schema still validates.

The dashboard still loads.

And the number is completely wrong.

Our demo starts with exactly that kind of failure:

💰 Executive revenue suddenly jumps to 93.3× its expected value.

Nothing obvious broke.

All the on-call engineer tells BlackBox is:

“Revenue just jumped roughly 100×. Is this real?”

From there, BlackBox takes over the investigation.

🔎 What BlackBox does

BlackBox behaves more like an incident responder than a chatbot.

Starting from one symptom, it:

  1. Finds the affected KPI in DataHub.
  2. Reads the real contracts, ownership, metadata, and lineage.
  3. Walks upstream through the actual dependency graph.
  4. Creates competing hypotheses instead of committing to the first plausible explanation.
  5. Profiles the underlying data and eliminates distractors quantitatively.
  6. Proves the root cause through a machine-enforced evidence gate.
  7. Raises a real ACTIVE incident in DataHub.
  8. Waits for human authorization before changing the pipeline.
  9. Generates a constrained repair to the real transform.
  10. Rebuilds the warehouse and runs the complete verification suite.
  11. Produces a reviewable git engineering artifact.
  12. Resolves the incident and writes the remediation history back into DataHub.

🧩 The incident BlackBox solved

The executive revenue KPI jumped to 93.3× its expected baseline.

BlackBox traced the metric through DataHub and eventually isolated:

raw.raw_orders.amount

The root cause was a silent semantic change during the cloudpay_v2 migration.

The DataHub contract said the field represented dollars.

The new provider started sending integer cents.

Same schema.

Completely different meaning.

A convincing distractor

The FX feed was stale too.

That looked suspicious enough to be a reasonable root-cause candidate.

BlackBox profiled it and proved that the maximum FX movement was nowhere near large enough to explain a ~100× anomaly.

❌ FX hypothesis eliminated.

✅ Payment-provider unit change confirmed.

🧠 Why this is different from a normal LLM agent

Claude decides where to investigate.

Deterministic tools decide what is true.

That separation is the core of BlackBox.

The agent is free to:

🧭 choose which lineage branch to inspect 🧪 decide which cohort to profile 💭 create competing hypotheses 🛠️ design a repair

But it cannot simply decide that its own answer is correct.

Before BlackBox can advance a root cause, the system requires:

📍 DataHub lineage or metadata evidence 📊 quantitative evidence 🎯 evidence tied to the exact asset and field being blamed

If those requirements are not satisfied, the state transition is rejected.

The agent cannot talk its way past the gate.

🛡️ Safety envelope

Investigation can be autonomous.

Authority is deliberately constrained.

BlackBox enforces:

🔐 Human approval before pipeline mutation 📁 Repairs restricted to pipeline/transforms/*.sql ↩️ Failed or abandoned repairs are reverted 🧪 Full-suite verification before success 📈 KPI acceptance checks in addition to tests 🌿 Git publication restricted to blackbox/fix-* 🚫 Remote PR publication only after VERIFIED 🧠 DataHub is only marked resolved after the repair actually earns verification

We also hardened read-only DuckDB access at the connection layer after finding that a naive SELECT-only check could still expose local files.

⚙️ The repair

Once the root cause is proven, a human presses:

Repair & Verify

BlackBox generates a targeted repair to the actual transform.

It does not divide every value by 100.

It scopes the normalization specifically to the provider whose semantics changed.

Then BlackBox:

📝 writes the real SQL transform 🏗️ rebuilds the warehouse 🧪 runs all pipeline invariants 📊 recomputes the business KPI 🔍 compares the result against the committed healthy baseline

Final result

✅ 32 / 32 invariants passed

✅ Revenue restored from 93.3× → 0.93× its healthy baseline

✅ Incident reached WRITEBACK_COMPLETE

✅ DataHub incident resolved

✅ Remediation history written back to the catalog

🧨 We also try to break BlackBox

A demo that works once is not enough.

We built adversarial evaluations around ways an autonomous repair agent could fail.

🟢 Healthy-data control

On a healthy fixture, BlackBox must conclude:

NO_INCIDENT

It is not rewarded for inventing a problem just because someone asked it to investigate.

🔴 Bad-repair challenge

We deliberately inject a very convincing repair:

divide everything by 100.

That makes the headline KPI look correct.

But it corrupts historical data.

BlackBox rejects it because the historical invariants fail.

🧼 Evaluation contamination

BlackBox writes incident memory back into DataHub.

That created an unexpected eval problem: a previous remediation note could become an answer key for the next run.

Our reset now scrubs BlackBox-written DataHub state, and the eval harness hard-fails if contamination remains.

🗺️ How DataHub powers BlackBox

DataHub is not a decorative integration.

It is both the map BlackBox investigates with and the memory it leaves behind.

During investigation

🔍 Official DataHub MCP Server Used for discovery, entity context, and lineage traversal.

🧠 Agent Context Kit Used as an embedded native DataHub access path.

🧬 GraphQL + aspect reads Used where precise field-level and fineGrainedLineages evidence is required.

📚 Contracts and metadata BlackBox reads schemas, descriptions, field documentation, ownership, and tags.

🔗 Table + column lineage The agent follows the actual graph rather than relying on hard-coded pipeline topology.

During and after remediation

🚨 Native DataHub Incidents BlackBox raises an ACTIVE incident once the root cause is proven.

✅ RESOLVED / FIXED writeback The incident closes only after the repair passes verification.

📝 Dataset documentation BlackBox appends an incident-history remediation note.

🏷️ blackbox-remediated tag The affected asset carries a durable record that remediation occurred.

MCP, Agent Context Kit, and GraphQL are alternative routes to the same DataHub graph, not separate sources pretending to corroborate one another.

🧰 Built with

Agent + backend

🐍 Python ⚡ FastAPI 📦 Pydantic 🤖 Anthropic Claude 🦆 DuckDB 🧪 pytest

DataHub

🔵 DataHub OSS v1.7.0 🔌 DataHub MCP Server 🧠 Agent Context Kit 🧬 GraphQL / aspect reads 🐍 Python SDK v2 🚨 Native Incidents API 📝 Docs + tag writeback 🧩 DataHub Skills

Product

▲ Next.js 💙 TypeScript ⚛️ React 🕸️ React Flow 📡 Server-Sent Events 🎨 Tailwind CSS

Engineering

🌿 git 🐙 GitHub 📊 OpenTelemetry / Phoenix for optional observability

📦 A real engineering artifact

A deliberately PR-enabled verified run produced a real pull request opened through BlackBox's repair-publication path:

👉 BlackBox-generated PR #1

The PR contains the actual repair plus the evidence behind it:

🔎 blamed DataHub asset and field 📊 quantitative evidence 📝 real code diff 📉 before / after KPI 🧪 invariant results

Remote publication is intentionally opt-in.

The default demo never needs permission to push to GitHub, and publication failure cannot turn an already verified repair into a failed incident.

🔬 Reproducible without trusting the demo

Judges can inspect a complete autonomous run directly:

👉 examples/sample-incident

It contains:

📄 incident state 💬 full agent transcript 🩹 real repair patch 📋 final report

There is also a deterministic judge path:

make judge-check

It requires no Anthropic key, live DataHub instance, GitHub token, or Phoenix.

It verifies:

✅ backend tests ✅ healthy fixture ✅ 32 / 32 pipeline invariants ✅ frontend lint ✅ production frontend build ✅ tracked-secret scan

🌱 Contributing back to DataHub

BlackBox produced two upstream DataHub contributions during the hackathon.

🧩 datahub-skills#133 — Incident Investigation Skill

We generalized BlackBox's investigation methodology into a reusable, vendor-neutral DataHub Skill:

SYMPTOM → LINEAGE → HYPOTHESES → EVIDENCE → CONFIRM → REMEDIATE → VERIFY → WRITEBACK

Every documented command was tested against live DataHub OSS before opening the PR.

That work also surfaced several useful OSS behaviors around health objects, editable descriptions, incident queries, and incident mutations.

🛠️ datahub#19046 — Quickstart troubleshooting

While building BlackBox on macOS + Colima, datahub docker quickstart appeared to hang even though the Docker CLI worked normally.

We traced the problem to Docker context / DOCKER_HOST behavior and contributed troubleshooting documentation upstream.

Both contributions are open at submission time.

💡 What we learned

The most important thing we learned is that metadata changes what an AI agent is capable of reasoning about.

Without context:

“Maybe this field changed units.”

is a guess.

With:

📜 a contract saying the field contains major currency units

plus

🧬 lineage proving exactly how that field reaches the executive KPI

plus

📊 quantitative profiling of the observed values

the same idea becomes something the system can test and prove.

That led to the architecture we ended up trusting:

The model chooses where to look.

The system decides what is true.

The human controls when the agent is allowed to act.

🚀 What's next

BlackBox currently demonstrates the full loop on a deterministic retail pipeline.

The next steps are:

❄️ Snowflake integration ☁️ BigQuery integration 🔨 dbt-aware repair workflows 📏 DataHub-native assertions 🚦 multi-incident triage 🧠 reuse of DataHub remediation history for faster repeat incidents 🔐 richer production approval policies

◾️ BlackBox

Not another agent that tells an engineer what to do.

An agent that investigates, proves, repairs, verifies, and leaves the resolution behind for the next engineer.

Built With

  • agentcontextkit
  • arizephoenix
  • datahub
  • datahubmcp
  • duckdb
  • fastapi
  • git
  • github
  • graphql
  • next.js
  • opentelemetry
  • pydantic
  • pytest
  • python
  • react
  • reactflow
  • server-sentevents
  • tailwindcss
  • typescript
Share this project:

Updates