Marivo
Metric-centered analysis runtime for AI agents.
Marivo is a Python library — not a hosted service or a chat UI — that turns a data warehouse into something an AI agent can analyze reliably. It is not a text-to-SQL wrapper: Python declarations are the contract, ibis expressions are the execution language, and typed frames are the boundary between analysis steps.
- Unified semantics — Datasources, entities, metrics, dimensions, and
relationships are declared in Python and addressed by semantic ref
(
sales.revenue), not raw table or column names. - Metric-centered analysis — Sessions start from a trusted metric and chain typed intents (observe, compare, decompose, correlate, forecast), each returning a typed frame.
- Trustworthy evidence — Every operator records findings, propositions, and assessments, so any conclusion can be traced back to its inputs.
- Readiness gates —
catalog.readiness()blocks incomplete semantic objects from analysis until authoring and access issues are resolved.
Requirements
Python 3.12 or newer.
Installation
pip install marivo
Install the backend extra that matches your datasource:
| Backend | Install command |
|---|---|
| DuckDB | pip install "marivo[duckdb]" |
| MySQL | pip install "marivo[mysql]" |
| Postgres | pip install "marivo[postgres]" |
| ClickHouse | pip install "marivo[clickhouse]" |
| Trino | pip install "marivo[trino]" |
| All packaged backends | pip install "marivo[all]" |
Marivo is deployed by installing the library where the agent runs, checking in
the models/ declarations, and providing datasource secrets through environment
variables referenced by *_env fields. There is no separate server.
If setup fails, run the read-only doctor first:
marivo doctor
marivo doctor --semantic
marivo doctor --datasource warehouse --connect
The default doctor checks installation, project layout, datasource declarations,
backend extras, secret references, and existing .marivo/ state without
connecting to databases or writing secrets. Use --semantic for semantic
load/readiness diagnostics and --connect only when you intentionally want a
live datasource round-trip.
Quick Start
Scaffold a project with the CLI:
marivo --version
marivo init
marivo init creates the project skeleton (marivo.toml, models/, .marivo/)
and installs the marivo-semantic and marivo-analysis skills into the shared
.agents/skills directory plus Claude Code and Codex compatibility directories,
so a coding agent can author the semantic layer with you.
Declare semantics under models/semantic/, then load and analyze:
import marivo.semantic as ms
import marivo.analysis as mv
catalog = ms.load()
report = catalog.readiness()
if report.status == "blocked":
report.show() # resolve blockers before analysis
session = mv.session.get_or_create(name="revenue-check", question="Why did Q4 drop?")
revenue = session.catalog.get("metric.sales.revenue")
region = session.catalog.get("dimension.sales.orders.region")
current = session.observe(revenue, time_scope={"start": "2026-10-01", "end": "2027-01-01"}, grain="month", dimensions=[region])
baseline = session.observe(revenue, time_scope={"start": "2025-10-01", "end": "2026-01-01"}, grain="month", dimensions=[region])
delta = session.compare(current, baseline)
session.decompose(delta, axis=region).show()
In-project help is available at every surface: ms.help() and mv.help() list
the surface; ms.help("metric") and mv.help("observe") drill into a symbol.
Documentation
Full guides live in the documentation site (built from site/):
- Installation — install,
marivo init, deploy. - Quick Start — author declarations, load a catalog, run a first analysis.
- Concepts — semantic layer, analysis workflow, readiness, and evidence.
Maintained agent guidance lives in marivo/skills/marivo-semantic and
marivo/skills/marivo-analysis.
Development
python3 -m venv .venv
.venv/bin/pip install -e ".[dev,duckdb,trino]"
Repository commands run through the local virtualenv via make:
make lint
make typecheck
make examples-check
make test
make check
Read agent-guide.md before contributing. See
CONTRIBUTING.md for the full workflow.
1 maintainer
Metadata
1 maintainer
Release files for marivo 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| marivo-0.3.0.tar.gz | 866.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| marivo-0.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.5 MB
Release files / marivo-0.3.0.tar.gz
| Download URL | marivo-0.3.0.tar.gz |
|---|---|
| Size | 866.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bf28bc34ef5156ac98cbb4708cb421afccc7d557cd11a6555c8ceae477c5f75e
|
|
BLAKE2b-256 checksum How to use checksums |
82e9102ddcd8cb389eb91fd13d04d78a52a8a53d0b5cff57251c7bf16a2364aa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 8, 2026.
Transparency logRelease files / marivo-0.3.0-py3-none-any.whl
| Download URL | marivo-0.3.0-py3-none-any.whl |
|---|---|
| Size | 604.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
55b627e7220e9ed7f2aecd2fdc77622cf65479fec5c0ef8a8bf08f904d57c43b
|
|
BLAKE2b-256 checksum How to use checksums |
50c2ea7fc0989661856adb3da77d7f7cb549a4fa8628a3ceed0e75492cb02da7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 8, 2026.
Transparency log
