Model Ledger

git for models — know what models you have deployed, where they run, what they depend on, and what changed.

CI License Python PyPI Downloads Docs

📖 Documentation · Quickstart · Concepts · Governance

model-ledger is a model inventory for any organization with deployed models. It discovers models, heuristic rules, and ETL across your platforms, maps the dependency graph automatically, and records every change as an immutable event. Unlike registries tied to a single platform (MLflow, SageMaker, W&B), it spans all of them — as one connected graph — and it's built to be driven by AI agents through a native MCP server.

Benchmarked at production scale: full inventory reconstruction over a ledger of 28.8k models and 212k events runs in under a second (CHANGELOG, v0.7.4).

Install

pip install model-ledger

The graph builds itself

Every model is a DataNode with typed input and output ports. When an output port name matches an input port name, connect() creates the dependency edge — no hand-wiring.

from model_ledger import Ledger, DataNode

ledger = Ledger()

ledger.add([
    DataNode("segmentation", platform="etl",      outputs=["customer_segments"]),
    DataNode("fraud_scorer", platform="ml",       inputs=["customer_segments"], outputs=["risk_scores"]),
    DataNode("fraud_alerts", platform="alerting", inputs=["risk_scores"]),
])
ledger.connect()

ledger.trace("fraud_alerts")
# ['segmentation', 'fraud_scorer', 'fraud_alerts']

Every mutation is recorded as an immutable Snapshot — an append-only event log that gives you full history and point-in-time reconstruction, because nothing is overwritten.

Talk to your inventory

The MCP server is a first-class surface — point Claude (or any MCP agent) at it:

pip install "model-ledger[mcp]"
claude mcp add model-ledger -- model-ledger mcp --demo

You: if we deprecate customer_features, what breaks?

Claude: 3 models consume it directly, 2 more transitively.

Documentation

Everything lives at block.github.io/model-ledger — and it can't drift, because the API reference is generated from source and every example runs in CI:

• Quickstart — install to your first dependency trace in 60 seconds
• Concepts — DataNode, Snapshot, and Composite, in three ideas
• Agents (MCP) — the eight-tool agent surface, with a worked transcript
• Connectors — discover from SQL, REST, GitHub, or your own platform
• Backends — in-memory, SQLite, JSON, Snowflake, or remote HTTP
• Governance — how the primitives map to SR 11‑7/SR 26‑2, the EU AI Act, and NIST AI RMF
• API reference — generated from the source

Architecture

flowchart LR
    subgraph Sources
        C1[SQL / REST / GitHub / Prefect<br/>connectors]
    end
    subgraph Core
        L[Ledger<br/>append-only event log,<br/>point-in-time reconstruction]
        G[Dependency graph]
        V[Compliance profiles<br/>SR 11-7/SR 26-2 · EU AI Act · NIST AI RMF]
    end
    subgraph Surfaces
        S1[Python SDK]
        S2[CLI]
        S3[REST API]
        S4[MCP server · 8 tools]
    end
    B1[(in-memory · SQLite · JSON ·<br/>Snowflake · remote HTTP)]
    C1 --> L
    L --> G
    L --> V
    L --- B1
    S1 --> L
    S2 --> L
    S3 --> L
    S4 --> L

For organizations

The OSS core handles discovery, graph building, change tracking, storage, the agent protocol, and compliance validation — the SR 11‑7/SR 26‑2, EU AI Act Annex IV, and NIST AI RMF profiles ship in model_ledger.validate. Your internal package provides only the thin layer on top: connector configs, custom connectors for internal platforms, and credentials. Thin config, not reimplemented logic.

Contributing

See CONTRIBUTING.md. All commits require DCO sign-off.

Security

See SECURITY.md for how to report vulnerabilities privately.

License

Apache-2.0. See LICENSE.

Created and maintained by Vignesh Narayanaswamy at Block.