统一语义
数据源、实体、指标、维度和关系用 Python 声明，并通过 语义引用引用 —— 用名称与定义，而非原始表。
Marivo 是一个 Python 库 —— 不是托管服务，也不是聊天界面 —— 它让一个数据仓库变成 AI 智能体能够可靠分析的对象。它为智能体提供三样它们原本缺失的能力：固定每个指标 和维度含义的类型化 语义层、由类型化操作组成的以指标为中心 的分析流程，以及每一个结论背后可审计的证据链。
Marivo 不是 text-to-SQL 包装器。Python 声明是契约，ibis 表达式是执行 语言，类型化 frames 是分析步骤之间的边界 —— 这样智能体是在组合可信的构件，而不是生成原始 SQL 然后寄希望于它正确。
指标中心分析
智能体从可信指标出发，串联类型化意图：observe、比较、decompose、 correlate、forecast 和质量检查。
可信证据
操作记录证据项、命题和评估，任何结果都能追溯回产生它的输入。
就绪检查门禁
目录就绪检查在编写与访问问题解决之前，阻止未完成的语义对象进入分析。
为什么智能体驱动的数据分析需要 Marivo
Section titled “为什么智能体驱动的数据分析需要 Marivo”把智能体直接指向一个原始仓库、让它写 SQL，失败模式是可预见的：它会臆造连接、悄悄漏掉一个 必需的过滤条件、误读含义不清的列，并给出一个谁也无法核验的自信答案。每次查询都从零开始，于是 什么都不会累积，什么都无法审核。
Marivo 用一份智能体必须遵循的契约，取代“生成 SQL 然后碰运气”：
| 没有语义运行时 | 有了 Marivo |
|---|---|
| 每次查询都靠猜表名和列名 | 可信的 语义引用（sales.revenue），携带人工编写的含义与约束 |
| 每次都重新推导定义 | 一份纳入版本控制的声明式契约，在智能体与会话之间共享 |
| 自由拼写的 SQL，错误以错误数字的形式暴露 | 类型化意图与 frames —— 非法步骤在任何后端操作之前就大声报错 |
| 无法核验的结论 | 把每个结果链接回其输入的 证据链 |
| 半成品模型照样被分析 | 阻止未完成语义进入分析的 就绪检查门禁 |
最终得到的，是一个基于含义而非列名来推理的智能体，并且整个推理过程处在一个人类可以审核、 批准与重放的回路中。
- 声明：在
models/datasources/中声明数据源，在models/semantic/中声明 语义（领域、实体、维度、指标）—— 使用marivo.datasource（md）和marivo.semantic（ms）。 - 加载并设闸：
ms.load()构建目录；ms.readiness()在智能体所需的每个对象 都完整且可达之前阻止分析。 - 打开会话：从一个指导问题出发，并从目录解析出一个可信指标。
- 串联类型化意图 ——
observe → compare → decompose等 —— 每一步返回一个类型化 frame 并留下证据痕迹。
import marivo.analysis as mv
session = mv.session.get_or_create(name="revenue-check", question="Why did Q4 drop?")catalog = session.catalogrevenue = catalog.get("sales.revenue")region = 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)attribution = session.decompose(delta, axis=region)attribution.show()