Write a Python function. elbi serves it to AI agents over the
Model Context Protocol as a versioned, cached tool.

That function is a derivation: declared inputs, a transform, a declared output format.

from elbi import Artifact, Context, Dataset, derivation, serve


@derivation(
    inputs={"sales": Dataset("sales")},
    serve=serve.table(title="Churn risk", max_rows=50),
)
def churn_risk(ctx: Context) -> Artifact:
    """Per-customer churn-risk scores from recent sales activity."""
    rows = ctx.input("sales").rows
    scored = [
        {"customer_id": r["customer_id"], "risk": 1 / (1 + float(r["amount"]))}
        for r in rows
    ]
    scored.sort(key=lambda r: r["risk"], reverse=True)
    return Artifact.table(scored)

elbi serve finds the function, runs it against whatever elbi.dev.yaml binds, and
publishes it. An agent calls run_churn_risk and reads back:

# Churn risk

| customer_id | risk |
| --- | --- |
| C-1021 | 0.5 |
| C-0820 | 0.2 |
| C-0640 | 0.1 |

That result is cached. It recomputes when the code changes or the sales data does,
and not otherwise.

Where this fits

An agent that writes fresh SQL against raw tables on every prompt gets it wrong, and
you find out downstream. Define the computation once instead, in Python, and hand
agents the result as a governed tool.

A derivation is any computation over data: a transform, an aggregate, a trained model.
That reaches questions a metrics-only semantic layer can't phrase, because it isn't
limited to metrics. It doesn't replace a semantic layer, though. A derivation can take
one as an input, including a governed model described with
OSI.

Installation

uv tool install elbi

Later, elbi update tells you whether a newer release exists and prints the right
command for however you installed it. It touches the network only when you run it;
nothing checks at startup or on a timer. See Upgrading.

Quick start

elbi init acme-data-context
cd acme-data-context
elbi serve

You don't need an API key to get going. elbi serve opens a chat UI at
http://localhost:7700 once it's ready, and serves the same derivations over MCP at
http://localhost:7700/mcp. The chat needs a model to talk to, so add one in Settings
when you send your first message, or export a key beforehand:

export ANTHROPIC_API_KEY=sk-ant-...

The first run takes 15-20 seconds longer than the ones after it. It's loading the
embedding model and setting up the local database, and the browser opens when the app
is genuinely ready rather than before. (uv sync comes later, for uv run pytest.
serve, validate and test all run from their own installed environment.)

Want the MCP endpoint on its own? Install elbi-cli instead and run elbi mcp. Same
derivations at http://localhost:7878/mcp, no chat UI, none of the heavier
dependencies, and no model key to configure. Whichever client you point at it brings
its own.

Connect a client

Point any MCP client at the URL that gets printed, from either serve or mcp. To
poke at it without one:

npx @modelcontextprotocol/inspector

Connect, then call the run_<name> tools. Claude Desktop, Cursor and your own agent
all take the same URL as an MCP server.

What you get

Bind data from local files (CSV, JSON, Parquet) or from a SQL database, and write
derivations over it as plain Python. Everything caches. Any MCP client can read or run
what you publish.

An agent can also propose a derivation. It gets verified under isolation and only
serves once a human certifies it; see agent-authored derivations.
You can gate a cleaning step on a machine-checkable
data contract, which checks types, ranges, keys and
referential integrity before anything is served. When the data outgrows memory, push
profiling and contract checks down to DuckDB or Polars.

Every derivation keeps its result history: how the certified
answer changed, and what moved it. Each version can go to MLflow. For any certified
derivation you can export a signed, offline-verifiable
certificate recording what the oracle checked and who signed
off.

There are two places to explore before you commit to anything. The
SQL workbench is deliberately ungoverned, and promotes a query to a
certified derivation in one click. The notebook is reactive, and
promotes a cell the same way. Both are authoring surfaces; the derivation is the
artifact.

On top of certified derivations you can build:

dashboards, where every tile binds to one, so a published
dashboard can only show numbers the oracle verified;
a feature store with point-in-time-correct training joins
and a low-latency online store, so there's no train/serve skew;
metrics defined once, a verified semantic layer that imports from
and exports to OSI, so every tool reads the
same sound number.

Monitor any metric or derivation against a learned baseline and
get alerted when a verified number moves, with the oracle's verdict attached.
Lineage and the catalog cover provenance, impact analysis and
search across every artifact. Orchestration materializes
assets that have gone stale, on a cron schedule or a data-change sensor, and keeps
per-asset run history. And you can validate any derivation against the
Open Derivation Spec.

Elbi runs on your machine. No account, no sign-in, and nothing leaves your network
unless you send it somewhere.

Documentation

Community

GitHub Discussions for questions, ideas, and show-and-tell.
Issues for bug reports and feature requests.

Contributing

We'd be glad of the help. CONTRIBUTING covers the
development setup, the test commands and our PR conventions; there's also a
Code of Conduct.

Security

Report vulnerabilities privately; the Security Policy says how.
Please don't open a public issue for one.

Running Elbi for a team

We built Elbi for one person: your machine, your data, an install that needs no account.
If you need it to serve several people, with single sign-on, user and group management
and per-object permissions, write to [email protected].

License

Apache-2.0, all of it: the specification, the SDK, the CLI, the agent runtime, the MCP
server, the web app, every verification gate. Use it for anything, commercial use
included. See LICENSE.