Get started

Ten minutes to a served star. Then three curves, one document each.

macOS, Linux, or Windows x64. Two things to install, git and uv, and the first step installs them. No API keys, no accounts, no cloud resources, and no administrator rights after the two installs. Everything below is keyless by design, and every command is quoted from the repository's own demo guide; pick your platform once and every block on the page follows.

The ten-minute path

Serve first, rebuild later.

Path A serves the released gold star in about two minutes. Path B replays the whole pipeline from raw data in about eight more. Start with A.

  1. Install git and uv.

    uv provisions the pinned Python 3.12 and every dependency; nothing else is installed globally. macOS offers to install git the first time you type it and Linux has it in every package manager, so the macOS and Linux line is uv alone. On Windows, use PowerShell, and open a new terminal after the installer runs so the shell sees uv. The guide's What you need carries the alternatives (winget for uv where a managed execution policy refuses the installer line, the git-scm installer and its portable build where the git line's request for approval is not yours to give) and the reason to clone to a short path.

    curl -LsSf https://astral.sh/uv/install.sh | sh
    winget install --id Git.Git -e
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  2. Clone and sync.

    One clone, one sync; the lines are the same on every platform.

    git clone https://github.com/metricminellc/metricmine.git
cd metricmine
uv sync

  3. Run the preflight.

    Eight checks on the platform, the interpreter, its trust store, uv, the locked toolchain, and the artifact, each with the command that fixes it, and exit 0 when the demo can run. Read it before the fetch, not after something fails.

    make doctor
    uv run mm doctor

  4. Fetch the released artifact.

    demo/demo.duckdb ships as a release asset. The committed digest manifest names the release to fetch it from and pins the asset's sha256, size, and content; the fetch verifies all three.

    make demo-fetch
    uv run mm demo-fetch

  5. List the categories.

    Expect three: airport_weather (13,014 rows), flights (166,158), and invoice_lines (44,721), each with its typed table, its authored subject, and its registry keys, on one long line. For a two-line proof that the server itself answers, uv run python scripts/serve_smoke.py launches it the way a desktop client does.

    uv run python -c "from metricmine.query import GoldWarehouse; print(GoldWarehouse().list_fact_categories())"

  6. Wire it into Claude Desktop.

    Merge this into claude_desktop_config.json, which Claude Desktop opens from Settings, Developer, Edit Config on either platform and creates when none exists yet (on macOS under Application Support/Claude; on Windows under %APPDATA%\Claude), replace the command path with your absolute clone path, quit Claude Desktop fully, and reopen it. A new chat lists metricmine-gold with five tools. The guide carries the note for the Microsoft Store build.

    {
  "mcpServers": {
    "metricmine-gold": {
      "command": "/absolute/path/to/metricmine/.venv/bin/python",
      "args": [
        "-m",
        "metricmine.server"
      ]
    }
  }
}
    {
  "mcpServers": {
    "metricmine-gold": {
      "command": "C:\\absolute\\path\\to\\metricmine\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "metricmine.server"
      ]
    }
  }
}

  7. Ask the first question.

    The answer should land on 29.44 minutes against 12.42, with 8.95 percent cancelled against 2.41, joined on the conformed airport code and the conformed calendar hour. The other six questions, with their measured answers, are on the demo page.

    Using the metricmine-gold tools: do flights departing New York in an hour with precipitation at their origin run later than flights in a dry hour, and are they cancelled more often? Say what you joined on and what the context told you.

Something off? Run the preflight again; it prints the three environment lines the local dbt lanes need, in your shell's form, and names the command that fixes whatever it found. The troubleshooting section, with the TLS note for python.org Pythons, a proxy entry, and a Windows group keyed to the error text Windows prints, is in docs/demo.md.

Path B

Replay the whole pipeline, keyless.

Path A is the demo; Path B is the proof behind it, and it provisions more: a second CPython 3.10 environment for the pinned connector and the vendored dbt package, so run it once Path A has answered a question. Every source is a committed sample pinned to its publisher's commit and digest, so the full path needs no key either. Steps one to four also run as one command, make demo (uv run mm demo on Windows). From the repo root:

export DBT_PROFILES_DIR="$PWD/transform"
export ADBC_DRIVER_PATH="$PWD/.adbc"
make driver
uv run dbt deps --project-dir transform
make ingest
uv run dbt run --project-dir transform --target local
uv run dbt test --project-dir transform --target local
make export-demo
uv run pytest -q
$env:DBT_PROFILES_DIR = "$PWD\transform"
$env:ADBC_DRIVER_PATH = "$PWD\.adbc"
uv run mm driver
uv run dbt deps --project-dir transform
uv run mm ingest
uv run dbt run --project-dir transform --target local
uv run dbt test --project-dir transform --target local
uv run mm export-demo
uv run pytest -q

What to expect: make ingest lands 247,555 bronze rows across seven tables exactly as they appear in the committed extracts; make driver registers the pinned DuckDB engine as dbt's driver; dbt run builds the 31 contracted models and ends Summary: 31 total | 31 success; dbt test runs every test and ends Summary: 303 total | 303 success; make export-demo rebuilds the artifact from your freshly built warehouse and verifies it content-equal by query; pytest runs the full suite, including the serving round trip, the declared-join gate, and the demo question set.

Three learning curves

One document each, and they point at each other.

A reader meets three curves at once: what the demo is showing, how to run the thing, and how to take the pattern home. Each has a document written for it.

What the demo shows.

Why these sources; each one from bytes to contract; every join and its justification; conformance and the three keys; the calendar; what the agent sees and where each word came from; the vintage effect as a lesson.

sources-explained.md · sources.md · demo.md

How to run it.

The planes, what is written against what is generated, the shells and the exports, the daily commands in dependency order, every recurring procedure, every gate with what its failure means, a symptom table, and a glossary.

operating.md · adoption.md

How to take it home.

The path every source took, step by step with the exact commands, validated by adding a source outside the demo to a fresh clone in under fifteen minutes; and the pattern map from the demo's decisions to situations in your own data.

adding-a-source.md · the pattern map

Working in the repository with Claude Code

Open it in Claude Code and start grounded.

The repository ships its own context layer. A few habits make the most of it.

  • Read before you build. CLAUDE.md names the document to read before touching contracts, gold models, the profiler, serving, the agent layer, or a new source. Claude Code reads it on its own; ask it to summarize the rule that applies to your change.

  • Plan mode for anything multi-file. The repository's convention is small reviewed pull requests, per-file commits with a why-body, and a sign-off on every commit.

  • Ask Oscar. The repository's resident guide is a read-only subagent (.claude/agents/oscar.md). Ask it how the system works, where a task is done, what a rule means, how to keep silver clean, or how the proposers draft contracts, and it answers from the repository's own files, citing the file and the line. Ask for a contract review and it runs the contract-review checklist over the file or the diff, prints a table with a verdict, and never edits. A relaxation without its gate is refused, not fixed.

  • Let the guard say no. The working-tree guard denies any path outside the repository before a tool runs. Stage external inputs into the tree first; that is the rule it enforces.

  • Keep the key out of the coding shell. The proposer stances and the eval lane read ANTHROPIC_API_KEY from the environment; everything else, including anything a coding agent runs, works in a shell without it. make demo, the tests, and CI never need a key.

The deeper shelf

Where the reasoning lives.

If you wantRead
Every architectural decision, versioneddocs/decisions/decision-register.md
The layer specs, ingestion through servingdocs/spec/
The evidence: findings, the signature test, gate breaksgate_proof_findings.md · signature-test.md · evidence/
The diagrams, SVG with Mermaid twinsdocs/diagrams/
The guardrails the coding agent works underCLAUDE.md
How to contribute, and what a pull request needsCONTRIBUTING.md
What changed since the last releaseCHANGELOG.md
The whole map of the documentationdocs/README.md

Next

Everything above is in one repository.

View on GitHubRead the docs