Marivo

A data analysis harness for AI agents that keeps business meaning, analytical steps, session state, and evidence connected.

Docs · First Analysis · Discord · Blog

English | 简体中文

Marivo is a Python framework that helps AI agents analyze business data through shared semantics, typed analysis operations, persistent sessions, and recorded evidence. It turns an open-ended business question into a reviewable investigation.

Highlights

• 🧭 shared semantics: define metrics, dimensions, relationships, and guardrails once instead of rebuilding them in every query
• 🧮 typed analysis: move through explicit operators with bounded inputs, outputs, and failure modes
• 🗂️ persistent sessions: keep the question, intermediate results, and artifacts together so an investigation can resume
• 🔎 traceable evidence: keep findings connected to source results, analytical scope, and limitations

Marivo is not a hosted chat UI or a Text-to-SQL wrapper. The agent works with declared business meaning and bounded analytical operations instead of rebuilding metrics, joins, and analysis logic in every SQL query.

Why Marivo

Giving an agent raw schemas and asking it to generate SQL leaves important choices implicit: what a metric means, which records belong in it, how tables relate, which comparison is valid, and what evidence supports the answer. Those choices can drift between prompts and are difficult to review after the fact.

Marivo makes them explicit and reusable. Business definitions live in a code-managed semantic layer, analysis proceeds through typed operations, and material results stay connected to the session and evidence that produced them.

Four core capabilities

Semantic Layer

Python declarations define datasource bindings, entities, relationships, metrics, dimensions, and guardrails under stable references. An agent can inspect evidence and draft definitions; the user or business owner confirms their business meaning.

Typed Analysis DSL

Typed operators such as observe, compare, and attribute give the agent explicit analytical actions and return typed result objects. Invalid or unsupported steps fail through the contract instead of being hidden inside free-form SQL.

Analysis Session

Each project-local investigation keeps its question, intermediate results, artifacts, and history together. The agent can continue an analysis without recreating context or repeating completed work.

Evidence Engine

Deterministic typed findings remain connected to their source results and are projected into bounded, operator-specific digests. Marivo does not use an LLM or make cross-artifact judgments: the agent owns synthesis and next-step choice, while typed inference boundaries, omissions, and exact audit reads keep the conclusion reviewable.

Before analysis starts, readiness checks the technical handoff for the required semantic objects. It blocks incomplete definitions without treating technical readiness as approval of their business meaning.

How you use Marivo

1. Install and initialize a project. Marivo creates the project structure and makes the bundled marivo-semantic and marivo-analysis skills available to compatible agents.
2. Prepare the semantic layer. Reuse the definitions in an existing project, or let an agent use marivo-semantic to draft what a new project needs.
3. State the business question. The agent uses marivo-analysis to check readiness, choose typed analysis steps, preserve evidence, and return the conclusion and limitations.

You confirm choices that materially affect business meaning or how the conclusion will be used. You do not need to write Python, select operators, manage the analysis session, or specify evidence fields.

Quick Start

Marivo requires Python 3.10 or newer. Enter the directory that will contain the project, then run:

curl -fsSL https://marivo.io/install.sh | bash

The installer uses uv to prepare a project-local environment and initializes the current directory. It runs on macOS, Linux, WSL, and Windows through Git Bash, MSYS2, or Cygwin. For manual installation, datasource extras, supported platforms, and troubleshooting, see Installation.

Marivo also works directly in an empty current directory after package installation. marivo init only materializes optional configuration, empty project directories, and agent skill links; it is not a runtime prerequisite.

Verify the selected environment once:

.venv/bin/python -m marivo doctor

On Windows, use .venv/Scripts/python.exe -m marivo doctor.

Then use the selected project interpreter for focused help.

import marivo

marivo.help()
marivo.help("authoring")
marivo.help("analysis")
marivo.help("semantic.metric")
marivo.help("analysis.observe")

marivo.help() introduces Marivo's core concepts and routes to two secondary roots. Use marivo.help("authoring") to connect data and define governed semantics; use marivo.help("analysis") to discover typed analysis. Follow the qualified routes from those pages rather than depending on short-name disambiguation. Focused help also accepts registered public types, errors, and member targets when they are already known or obtained from a live result.

If the project already contains marivo.toml and models/, reuse its semantic layer. For a new empty project, tell the agent which datasource and business outcome you need; Marivo creates authored and runtime directories when they are first needed. Confirm the proposed metric meaning before analysis.

Once a metric is ready, ask a business question naturally:

Use Marivo to explain why the approved sales.revenue metric decreased last quarter compared with the same period a year earlier. Start with regional differences, then give me the conclusion, key evidence, and limitations.

The bundled skills handle catalog inspection, readiness, operator selection, session management, and evidence collection.

Documentation

• Installation
• Quick Start
• First agent-guided analysis
• Semantic Layer
• Analysis Workflow
• Evidence

Development

uv venv --python 3.10 --seed
uv pip install --python .venv/bin/python -e ".[dev,duckdb,trino]"

Use the repository entrypoints for checks:

make format
make lint
make typecheck
make test
make check

Read AGENTS.md before contributing. See CONTRIBUTING.md for the full workflow.