Metadata-Version: 2.4
Name: marivo
Version: 0.1.0
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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ibis-framework>=12.0.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas>=2.2.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: scipy>=1.13.0
Requires-Dist: tomli_w>=1.0
Provides-Extra: duckdb
Requires-Dist: ibis-framework[duckdb]>=12.0.0; extra == "duckdb"
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,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,mysql,postgres,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>=1.9; extra == "dev"
Requires-Dist: numpy>=1.26.0; extra == "dev"
Requires-Dist: pandas-stubs>=2.2.0; extra == "dev"
Requires-Dist: scipy-stubs>=1.14.1.0; extra == "dev"
Requires-Dist: import-linter>=2.0; extra == "dev"
Dynamic: license-file

# 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

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

## Quick Start

Scaffold a project with the CLI:

```bash
marivo init
```

`marivo init` creates the project skeleton (`marivo.toml`, `models/`, `.marivo/`)
and installs the `marivo-semantic` and `marivo-analysis` skills for Claude Code
and Codex, so a coding agent can author the semantic layer with you.

Declare semantics under `models/semantic/`, then load and analyze:

```python
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("sales.revenue")
region = session.catalog.get("sales.orders.region")

current = session.observe(revenue, timescope={"start": "2026-10-01", "end": "2027-01-01"}, grain="month", dimensions=[region])
baseline = session.observe(revenue, timescope={"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/`](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

```bash
python3 -m venv .venv
.venv/bin/pip install -e ".[dev,duckdb,trino]"
```

Repository commands run through the local virtualenv via `make`:

```bash
make lint
make typecheck
make examples-check
make test
make check
```

Read [`agent-guide.md`](agent-guide.md) before contributing. See
[`CONTRIBUTING.md`](CONTRIBUTING.md) for the full workflow.
</content>
</invoke>
