Praxis

The evidence-bound remediation agent for DataHub-governed data products.

Praxis takes one narrow but expensive incident all the way to a mergeable fix: a source field was renamed, a dbt model still projects the old field, and the break can propagate into a production ML path. It reads the exact DataHub schema and lineage, inspects the real dbt files, generates a minimal compatibility patch, verifies it in isolation, pauses for a named human decision, and publishes only confirmed outputs.

The differentiator is not another incident summary. It is a proof-carrying change set. Every candidate contains DataHub evidence URNs, before/after SHA-256 hashes, validation results, and a rollback instruction. Praxis re-reads the repository and repeats verification after approval, so a stale review can never be applied.

It runs three ways: a web UI for the human at the gate, an MCP server so an agent can drive it, and a DataHub Skill that composes DataHub's own MCP server for discovery with Praxis for the verified fix.

Three ways in

	Command	Needs
Sandbox UI, no credentials	python -m praxis	Python 3.10+
Live DataHub, one command	python setup/live_quickstart.py	Docker
As agent tools over MCP	python -m praxis.mcp	an MCP-capable agent host

Try it in 60 seconds

Python 3.10+ is the only requirement for the sandbox's structural verification path.

python -m praxis

For the same real dbt parse gate used in the Docker image:

pip install -r requirements-dbt.txt
python -m praxis

Open http://127.0.0.1:8787, select Start verified run, inspect the Evidence and Candidate tabs, and approve or reject the bundle. No credentials are required.

The sandbox is not a prerecorded UI. The backend loads a packaged DataHub-shaped incident fixture, reads the intentionally broken dbt project under sandbox/dbt_project, generates new files, validates them, persists a chained ledger, and serves the resulting artifacts. The source project is deliberately left unchanged; the approved bundle is written under .runtime/artifacts.

Docker is equally self-contained and includes the pinned DataHub SDK plus dbt/DuckDB parser. Sandbox needs no credentials; the same image supports live column-lineage and deployment evidence when DataHub is configured:

docker compose up --build

What the agent proves

1. The old source field is absent and its replacement is present.
2. At least one DataHub column-lineage path confirms downstream field impact.
3. DataHub entity lineage identifies the wider data/ML/dashboard blast radius.
4. The dbt repository contains exactly one safe projection to repair.
5. The candidate preserves every projected output in an enforced contract.
6. The SQL has no destructive operations and input hashes are still current.
7. dbt parse passes when dbt is installed; otherwise the UI says structurally verified and records the skipped check.
8. The exact candidate hashes still match immediately after human approval.

If any required proof is missing, Praxis stops before offering approval.

Outputs

Each successful sandbox run produces four inspectable artifacts:

• a one-line dbt compatibility repair;
• the existing dbt contract with enforcement enabled;
• a provenance manifest with DataHub URNs and input/output hashes;
• a complete verification report, including skipped checks.

The checked-in sample bundle is generated from the same code path by examples/regenerate.py. examples/README.md walks through each file and shows the one-line diff, so the output can be judged without running anything.

What it looks like

The human gate: tier, external systems, rollback, named approver.	Exact DataHub schema, ownership, failed assertion, column path.
Generated files, unified diffs, hashes, every verification check.	The SHA-256 chained ledger for the run.

Every screenshot in docs/screenshots/ is produced by demo-video/scripts/capture-ui.py, which drives the shipped server in a real browser rather than being posed by hand.

Demo film

demo-video/ builds the ~2:10 submission film with Remotion and Edge neural TTS. It is data-driven: demo-video/scripts/capture-trace.py drives this engine headlessly and every number, URN, hash and generated line on screen is read from that capture; the human-gate scene is a real screen recording of the product, not a mock-up. Render it with demo-video\render-final.ps1.

Live DataHub and GitHub

Install the official DataHub SDK only for live column-level lineage:

pip install -r requirements-datahub.txt

Set the integrations you want:

PRAXIS_TARGET_REPO=/absolute/path/to/your/dbt-project
PRAXIS_DBT_COMMAND=dbt

DATAHUB_GMS_URL=http://localhost:8080
DATAHUB_TOKEN=...
DATAHUB_UI_URL=http://localhost:9002

GITHUB_REPOSITORY=owner/repository
GITHUB_TOKEN=...
GITHUB_BASE_BRANCH=main

# Required for live integrations on a public/non-loopback bind.
PRAXIS_APPROVAL_TOKEN=...

In live mode Praxis uses DataHub GraphQL for the exact dataset schema, ownership, description, and entity blast radius, and the official lineage SDK for field paths. After approval it adds praxis.verified-impact only to URNs that DataHub confirms and appends a hash-bound memory note to the source dataset. It never reports an attempted write as a successful graph delta.

When GitHub is configured, Praxis creates one Git tree, one commit, and one draft pull request through the Git database API. Existing files are updated atomically; it does not make one commit per file. Without GitHub credentials, the local bundle remains the only repository output.

One command to a live graph

python setup/live_quickstart.py

Installs the pinned SDK, brings up DataHub Core 1.6.0, waits for GMS to answer GraphQL, and seeds a self-contained nine-entity graph: the post-rename source schema, two-hop column lineage, three ML features, a production model, its model group, its SageMaker deployment and a business-critical dashboard. No warehouse and no datapack. --serve starts Praxis on it, --stop tears it down.

Quickstart publishes GMS on host port 8080, which is a popular port. If something else already holds it the script says so in seconds rather than failing several minutes into container startup, and moves DataHub out of the way on request:

python setup/live_quickstart.py --gms-port 58080

The equivalent by hand:

datahub docker quickstart --version v1.6.0
DATAHUB_GMS_URL=http://localhost:8080 python setup/seed_ml_lineage.py

See credential boundaries before connecting a non-disposable deployment. In particular, the Quickstart datahub:datahub login is not a DataHub API token.

Drive it from an agent (MCP)

Praxis is also an MCP server, so an agent can resolve an incident, read the diff and the verification result, and put the decision in front of a human:

python -m praxis.mcp          # stdio JSON-RPC; --list-tools to inspect

Five tools: praxis_prepare_remediation, praxis_get_run, praxis_get_artifact, praxis_approve_remediation, praxis_integration_status.

.mcp.json registers Praxis alongside DataHub's own MCP server, which is the intended pairing — DataHub does discovery and lineage, Praxis does the part a conversational surface cannot: generate a change and refuse to hand it over unverified.

The agent cannot approve. praxis_approve_remediation requires a named human identity and an explicit human_approved flag that an agent is instructed never to set on a person's behalf. A refused approval leaves the run in waiting with nothing applied, and the tests assert it.

contrib/skills/datahub-verified-remediation/ is a DataHub Skill in the upstream datahub-skills layout that drives this whole workflow, plus an RFC for the append-only agent-memory aspect DataHub currently lacks. See contrib/.

References:

• DataHub lineage SDK
• DataHub description API
• DataHub tags API
• GitHub Git Trees API

Truth matrix

Mode	Reads	Writes after approval	Never does
Sandbox	Packaged evidence + local dbt project	Local review bundle	DataHub, GitHub, or source-repo mutation
Live DataHub	Exact DataHub schema + lineage + local dbt project	Confirmed DataHub tags/note; local bundle	Production traffic changes
Live + GitHub	Same as live	One atomic draft PR plus confirmed DataHub writes	Automatic merge or deployment
Agent over MCP	Same as the mode it is configured for	Nothing — an agent may prepare and inspect only	Approve on a human's behalf

Test and audit

python -m compileall -q praxis tests
python -m unittest discover -s tests -v
node --check praxis/public/app.js

The tests cover the DataHub 1.6 GraphQL schema, two approval races (at worker handoff and during the preparation slot release), restart-safe state, rejection safety, candidate generation, verification, path traversal, API authorization, SQLite migration, connector truthfulness, tamper detection, and the MCP surface — protocol handshake, stdio framing, path redaction, and the refusal that stops an agent approving its own work. See the architecture and contest audit for the detailed boundaries and remaining deployment checks.

Apache 2.0 licensed.