Contracts before code.
Every dataset is shaped by a contract a person approved. Change the contract and the change is visible, versioned, and reversible. Under the hood: ODCS 3.1.0, enforced at build time and tested in CI.
Contract-driven data pipeline
Agents propose.
Humans approve.
MetricMine is an open source data pipeline that ends in an answer, not a table. AI drafts the data contracts. A person approves every change before deterministic code builds the warehouse. In the demo, seven public sources become one governed star with every join measured, all on one machine. Your own sources take the same path.
The flow
From raw data to a governed answer.
Machines do the repeatable work. People keep the judgment. Nothing reaches the warehouse without an approval on record.
- Raw data landsbronze · PyAirbyte · as received
- The profiler describes itdeterministic · committed
- An agent proposesODCS contract · versioned
- A human approvesevery change, no exceptions
- The engine builds golddbt + DuckDB · one star, three categories
- AI answers with meaningMCP serves data and expert context
Agents propose. Code executes. A human approves. The full architecture and its committed evidence live in the repository.
Measured, not claimed
What a test holds today.
Every number below links to the document or test in the repository that carries it. There are no performance, cost, or scale figures on this site by rule; the measured curves live with their environment in the repository.
7public sources, each pinned to a publisher artifact and a raw digestdocs/sources.md3fact categories in one star: flights, airport weather, invoice linesdocs/demo.md31 / 303dbt models and tests in one cold build, every one greendocs/demo.md, PASS=33422 of 31models emitted by the engine from approved contracts, never hand-writtenREADME.md13approved contracts, each carrying who proposed it and who merged itcontracts/42binding decisions in a versioned register, with 66 measured findings beside themdocs/decisions/0.9994measured completeness of the cross-category join, floor 0.99, held by a testtests/test_declared_joins.pyunder 15 minto add a source that is not in the demo, eight files by hand, in a fresh clonedocs/adding-a-source.md
Why it works this way
Built on three rules.
Most data contracts are documentation. MetricMine makes them the enforced interface between a pipeline and the AI agents that use it. Contracts generate models. Models generate contracts. Both are gated. A human approves every change.
Humans hold the gate.
AI proposes and explains. It never merges its own work. The agents hold no warehouse credentials and never write. A person approves every contract and every generated model before anything runs. Under the hood: two proposer agents, pull requests, an ownership manifest.
Deterministic and local.
The pipeline runs end to end on one machine. Same inputs, same outputs, every time: two machines that pull the same commit build the same gold. Built small by design, on standard parts. Under the hood: dbt Core and DuckDB.
Standard parts
Airbyte at the door. dbt and DuckDB in the middle. MCP at the edge.
Nothing in the pipeline is proprietary runtime. It is a dbt project with contracts enforced, fed by PyAirbyte, served over MCP, and the meaning lives in files a person can read.
Airbyte at the door.
Bronze lands through PyAirbyte, and the pipeline lands whatever its source list names. Airbyte publishes a catalog of 600+ connectors by its own count; the demo exercises the file connector, seven files deep.
one connector type exercised, many filesdbt and DuckDB in the middle.
The transforms are dbt Core models with enforced contracts. DuckDB is the local warehouse, chosen so the whole thing runs on one machine with no account. The contracts and the compiled context are warehouse-agnostic files in git; dbt profiles carry the execution plane, and a second adapter is an experiment, not a promise.
dbt Core v2 (dbt-oss 2.0), DuckDB 1.4.3 as the warehouse and as dbt's driverMCP at the edge.
A read-only MCP server serves the gold star through five tools over one shared query module, three layers deep. The demo guide wires it into Claude Desktop, and every answer can say which of its parts is a measurement and which is what an expert wrote.
list, schema, context, query, lookupBuilt to work with Claude Code
It comes with its own architect. Its name is Oscar.
MetricMine is not an alternative to Claude Code, dbt, or Airbyte. It is what sits between them. Silver is where meaning is decided, and that is human work with Claude Code beside you. Gold is mechanical, and the engine does it the same way every time. The narrow agents and the deterministic gates exist so the decisions that must be certain are never left to a model's best guess.
Clone the repository, open Claude Code, and ask for Oscar: a read-only subagent that knows the system from its own files. Ask how the pipeline works, where a task is done, what a rule or a decision means, how to keep silver clean, or how the proposers draft contracts, and Oscar answers with the file and the line. Ask for a contract review and it runs the checklist, prints a verdict, and stops. It never edits a file.
CLAUDE.md, what Oscar reads first: nineteen hard rules, the architecture boundaries, and the reading order for every spec.
The contract-review skill: the nine-item checklist behind every verdict Oscar gives, from the all-or-nothing column rule to the never-weaken gate.
The working-tree guard: a hook that denies any path outside the repository before a tool runs, deterministically.
The Claude Code Action: a mention in an issue or a pull request runs Claude Code on a runner, and it commits to a branch for a person to review and merge.
For engineers
Run it locally.
No cloud account, no cluster, no signup. git and uv, on macOS, Linux, or Windows x64; uv provisions the pinned Python 3.12. Two minutes to a served star; about eight more to rebuild everything from raw data. The step-by-step walkthrough, with the install lines and the preflight, is the ten-minute demo.
git clone https://github.com/metricminellc/metricmine.git
cd metricmine
uv sync
make doctor
make demo-fetch
uv run python -c "from metricmine.query import GoldWarehouse; print(GoldWarehouse().list_fact_categories())"git clone https://github.com/metricminellc/metricmine.git
cd metricmine
uv sync
uv run mm doctor
uv run mm demo-fetch
uv run python -c "from metricmine.query import GoldWarehouse; print(GoldWarehouse().list_fact_categories())"How the pieces meet
Two agents that only propose. One engine that only executes.
The agent layer runs along the top and ends at a person. The engine runs along the bottom and starts at the contract that person merged. Nothing crosses between them except through git.