语义层
数据源、实体、指标、维度和关系都用 Python 声明，并通过 语义引用引用。分析面对的是名称和定义，而不是原始表。
Marivo 是一个 Python 库，不是托管服务，也不是聊天界面。它把数据仓库整理成 AI 智能体可以按契约分析的对象：用类型化的语义层固定每个指标和维度的含义， 用类型化操作组织以指标为中心的分析流程，并为每个结论保留可审计的证据链。
Marivo 不是 text-to-SQL 包装器。Python 声明是契约，ibis 表达式是执行语言， 类型化 frames 是分析步骤之间的边界。智能体组合的是经过声明的构件，而不是临时生成一段原始 SQL 再假设它正确。
以指标为中心的分析
智能体从可信指标出发，串联类型化意图：observe、比较、attribute、 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 → attribute等 —— 每一步返回一个类型化 frame，并写入证据。
第一次运行分析
Section titled “第一次运行分析”import marivo.analysis as mv
session = mv.session.get_or_create(name="revenue-check", question="Why did Q4 drop?")catalog = session.catalogrevenue = catalog.get("metric.sales.revenue")region = 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)attribution = session.attribute(delta, axes=[region])attribution.show()