Metadata-Version: 2.4
Name: marivo
Version: 0.4.10
Summary: Python-native semantic modeling and analysis library for agentic analytics.
Author-email: li chengxiang <chengxiang.libra@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://marivo.io
Project-URL: Repository, https://github.com/chengxianglibra/marivo
Project-URL: Issues, https://github.com/chengxianglibra/marivo/issues
Keywords: semantic-layer,analytics,agentic-analysis,python-library
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ibis-framework>=12.0.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: packaging>=21.3
Requires-Dist: pandas<3.0.0,>=2.2.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: scipy>=1.13.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Requires-Dist: tomli_w>=1.0
Requires-Dist: typing-extensions>=4.8.0
Provides-Extra: duckdb
Requires-Dist: ibis-framework[duckdb]>=12.0.0; extra == "duckdb"
Provides-Extra: sqlite
Requires-Dist: ibis-framework[sqlite]>=12.0.0; extra == "sqlite"
Provides-Extra: trino
Requires-Dist: ibis-framework[trino]>=12.0.0; extra == "trino"
Provides-Extra: mysql
Requires-Dist: ibis-framework[mysql]>=12.0.0; extra == "mysql"
Provides-Extra: postgres
Requires-Dist: ibis-framework[postgres]>=12.0.0; extra == "postgres"
Provides-Extra: clickhouse
Requires-Dist: ibis-framework[clickhouse]>=12.0.0; extra == "clickhouse"
Provides-Extra: all
Requires-Dist: ibis-framework[clickhouse,duckdb,mysql,postgres,sqlite,trino]>=12.0.0; extra == "all"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
Provides-Extra: dev
Requires-Dist: ibis-framework[clickhouse,duckdb,postgres,sqlite,trino]>=12.0.0; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-xdist>=3; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=2.3; extra == "dev"
Requires-Dist: numpy>=1.26.0; extra == "dev"
Requires-Dist: pandas-stubs<3.0.0,>=2.2.0; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"
Requires-Dist: scipy-stubs>=1.14.1.0; extra == "dev"
Requires-Dist: import-linter>=2.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <a href="https://marivo.io" target="_blank">
    <img src="https://raw.githubusercontent.com/chengxianglibra/marivo/main/site/src/assets/marivo-mark.svg" alt="Marivo" width="128">
  </a>
</p>

<h1 align="center">Marivo</h1>

<p align="center">
  <em>A data analysis harness for AI agents that keeps business meaning, analytical steps, session state, and evidence connected.</em>
</p>

<p align="center">
  <a href="https://marivo.io/docs/latest/" target="_blank"><strong>Docs</strong></a> ·
  <a href="https://marivo.io/docs/latest/first-analysis/" target="_blank"><strong>First Analysis</strong></a> ·
  <a href="https://discord.gg/8WqCzeaYk" target="_blank"><strong>Discord</strong></a> ·
  <a href="https://marivo.io/blog/" target="_blank"><strong>Blog</strong></a>
</p>

<p align="center">
  <b>English</b>
  <b> | </b>
  <a href="README.zh-CN.md"><b>简体中文</b></a>
</p>

<p align="center">
  <a href="https://github.com/chengxianglibra/marivo/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/chengxianglibra/marivo/ci.yml?branch=main&label=CI" alt="CI"></a>
  <a href="https://pypi.org/project/marivo/"><img src="https://img.shields.io/pypi/v/marivo" alt="PyPI version"></a>
  <a href="https://pypi.org/project/marivo/"><img src="https://img.shields.io/pypi/pyversions/marivo" alt="Python versions"></a>
  <a href="https://github.com/chengxianglibra/marivo/blob/main/LICENSE"><img src="https://img.shields.io/github/license/chengxianglibra/marivo" alt="License"></a>
</p>

**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:

```bash
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](https://marivo.io/docs/latest/installation/).

Verify the selected environment once:

```bash
.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.

```python
import marivo

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

If the project already contains `marivo.toml` and `models/`, reuse its semantic layer.
For a new project, tell the agent which datasource and business outcome you need, then
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](https://marivo.io/docs/latest/installation/)
- [Quick Start](https://marivo.io/docs/latest/quick-start/)
- [First agent-guided analysis](https://marivo.io/docs/latest/first-analysis/)
- [Semantic Layer](https://marivo.io/docs/latest/concepts/semantic-layer/)
- [Analysis Workflow](https://marivo.io/docs/latest/concepts/analysis-workflow/)
- [Evidence](https://marivo.io/docs/latest/concepts/evidence/)

## Development

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

Use the repository entrypoints for checks:

```bash
make format
make lint
make typecheck
make test
make check
```

Read [`agent-guide.md`](agent-guide.md) before contributing. See
[`CONTRIBUTING.md`](CONTRIBUTING.md) for the full workflow.
