Agent¶

mars.agent.MarsAgentComputeBudget `dataclass` ¶

内置 Agent 单次计算的规模上限，不限制公共分析 API 或报告查询。

参数：

名称	类型	描述	默认
`max_features`	`int`	解析默认值后的特征数上限，默认沿用工具的 200 特征边界。	`200`
`max_current_rows`	`int`	当前样本行数上限。	`2000000`
`max_benchmark_rows`	`int`	基准样本行数上限。	`2000000`
`max_input_cells`	`int`	当前与基准行数之和乘以有效特征数的上限。	`40000000`
`max_groups`	`int`	当前与基准分组基数之和的保守上限，不包含整体行。	`120`
`max_time_windows`	`int`	当前与基准有效日期基数之和的上限，覆盖按日缺失明细。	`366`
`max_bins`	`int`	数值分箱参数或类别特征估算正常箱数的上限。	`50`
`max_estimated_rows`	`int`	汇总、趋势、分箱和按日明细的保守总行数上限。	`500000`
`max_estimated_cells`	`int`	按表宽度估算的结果单元格总数上限。	`10000000`

引发：

类型	描述
`ValueError`	任一上限不是正整数时抛出。

Notes

默认值用于交互式分析；选择依据和估算公式见 Agent 用户指南。估算不扫描数值特征，也不复制宽表；仅统计角色列和类别列的基数。

示例：

>>> MarsAgentComputeBudget(max_features=20).max_features
20

Experimental，最低 Python 3.10。仅从 mars.agent 导入；普通 MARS 不加载此模块。完整示例见风控分析 Agent。

mars.agent.MarsRiskAgent ¶

面向已登记数据的 Experimental 监控与分析 Agent。

参数：

名称	类型	描述	默认
`provider`	`MarsAgentProvider \| None`	同步模型接口；为空时仅可通过 execute_tool 使用确定性工具。	`None`
`max_iterations`	`int`	每轮用户请求允许的模型调用次数。	`8`
`max_tool_calls`	`int`	每轮最多执行的工具数，包含失败调用。	`24`
`max_context_chars`	`int`	系统提示、工具定义和消息的序列化字符上限，不是精确 token 预算。	`100000`
`max_result_chars`	`int`	单次工具 data 的序列化字符上限；表格通过分页控制大小。	`16000`
`compute_budget`	`MarsAgentComputeBudget \| None`	单次计算的规模上限；None 使用默认预算。独立于输出字符预算和报告查询。	`None`

引发：

类型	描述
`ValueError`	资源预算不是有效正整数或低于最小值时抛出。

Notes

首版使用同步、顺序工具执行。完整历史按轮保留；达到上下文上限后显式停止，不静默丢弃工具配对消息。调用方可 clear_history 后通过报告标识继续分析。

tools `property` ¶

tools: tuple[MarsAgentTool, ...]

返回模型可调用工具的独立副本。

execute_tool ¶

execute_tool(
    name: str,
    arguments: dict[str, Any],
    *,
    session: MarsAgentSession
) -> MarsAgentToolResult

不调用模型，直接执行相同校验和适配链路的领域工具。

参数：

名称	类型	描述	默认
`name`	`str`	工具名称。	必需
`arguments`	`dict[str, Any]`	工具 JSON 参数，执行前校验。	必需
`session`	`MarsAgentSession`	已登记数据及报告的会话。	必需

返回：

类型	描述
`MarsAgentToolResult`	结构化成功结果或可恢复错误；报告保存在 session 中。

引发：

类型	描述
`RuntimeError`	会话正在执行其他任务时抛出。

run ¶

run(
    prompt: str, *, session: MarsAgentSession
) -> MarsAgentResult

执行一轮自然语言任务并保留可继续追问的完整消息。

参数：

名称	类型	描述	默认
`prompt`	`str`	用户分析需求。	必需
`session`	`MarsAgentSession`	本轮使用的数据、报告和历史上下文。	必需

返回：

类型	描述
`MarsAgentResult`	回答、停止原因、报告引用和本轮工具记录。

引发：

类型	描述
`ValueError`	未配置 provider、输入为空或模型返回无效调用协议时抛出。
`RuntimeError`	会话正在执行其他任务时抛出。

Notes

Provider 异常向调用方传播；异常轮不提交消息，但已计算的报告仍可读取。取消或 API 重试策略由 provider 和调用方控制，不重复执行已完成的工具。

mars.agent.MarsAgentSession ¶

显式持有跨轮消息、已登记数据及报告的会话。

Notes

数据登记时只保存允许使用的列。标识不可覆盖，避免旧报告和新数据混淆。同一会话不支持并发运行；不同会话彼此隔离。进程退出后状态不保留。

messages `property` ¶

messages: tuple[MarsAgentMessage, ...]

返回完整消息副本，外部修改不会影响后续模型请求。

report_ids `property` ¶

report_ids: tuple[str, ...]

返回当前会话的报告标识。

register_dataset ¶

register_dataset(
    dataset_id: str,
    df: FrameLike,
    *,
    features: list[str],
    target: str | None = None,
    group_columns: list[str] | None = None,
    time_col: str | None = None,
    description: str = "",
    missing_values: list[int | float | str] | None = None,
    feature_metadata: FeatureMetadata | None = None,
    business_context: dict[str, Any] | None = None
) -> None

登记允许 Agent 使用的数据及明确业务角色。

参数：

名称	类型	描述	默认
`dataset_id`	`str`	会话内唯一标识，限字母、数字、下划线和连字符，最长 64 字符。	必需
`df`	`FrameLike`	Pandas 或 Polars 宽表。	必需
`features`	`list[str]`	允许分析的特征列，不能包含 target 或分组及日期列。	必需
`target`	`str \| None`	二分类标签；允许当前数据缺列，以表示尚无表现数据。	`None`
`group_columns`	`list[str] \| None`	允许模型选择的分组列。	`None`
`time_col`	`str \| None`	原始日期列。	`None`
`description`	`str`	业务口径说明，最长 1000 字符；将发送给模型。	`''`
`missing_values`	`list[int \| float \| str] \| None`	交由 MARS 处理的额外缺失值。	`None`
`feature_metadata`	`FeatureMetadata \| None`	可选业务字典或含 feature 列的 Pandas/Polars 表；仅保留已授权特征。	`None`
`business_context`	`dict[str, Any] \| None`	可选 JSON 业务上下文；交给画像和分箱报告。	`None`

引发：

类型	描述
`RuntimeError`	会话正在运行时抛出。

Notes

登记校验会在标识重复、字段无效或业务角色冲突时抛出 ValueError。

get_report ¶

get_report(report_id: str) -> MarsAgentReport

读取保留完整聚合表的本地报告副本。

参数：

名称	类型	描述	默认
`report_id`	`str`	当前会话报告标识。	必需

返回：

类型	描述
`MarsAgentReport`	结果快照，可用于本地验证或交给 reporting 层导出。

引发：

类型	描述
`KeyError`	报告不存在时抛出。

clear_history ¶

clear_history() -> None

清空完整会话历史，保留数据和报告。

引发：

类型	描述
`RuntimeError`	会话正在运行时抛出。

register_report ¶

register_report(
    report: object, *, report_id: str | None = None
) -> str

直接登记画像或分箱报告的快照，无需原始宽表或重新计算。

参数：

名称	类型	描述	默认
`report`	`object`	满足 mars.reporting.Report 公共契约的报告，或持有 report 的结果对象。	必需
`report_id`	`str \| None`	可选唯一标识；限字母、数字、下划线和连字符，最长 64 字符；None 自动分配。	`None`

返回：

类型	描述
`str`	可用于 get_report 和 Agent get_report_table 的报告标识。

引发：

类型	描述
`ValueError`	类型不支持、标识无效或重复时抛出。
`RuntimeError`	会话正在运行时抛出。

Notes

外部报告 dataset_id 为 None，metadata.source 记录来源；不伪造数据集。表和元数据保存为独立快照，之后修改原报告不影响会话。

示例：

>>> session = MarsAgentSession()
>>> report_id = session.register_report(profile.report)

mars.agent.MarsOpenAIProvider ¶

通过 Chat Completions 接口调用支持工具调用的模型。

参数：

名称	类型	描述	默认
`model`	`str`	服务端模型名称，由调用方显式指定。	必需
`api_key`	`str`	对应服务的凭据，不写入消息或日志。	必需
`base_url`	`str \| None`	兼容服务地址；为空时使用 SDK 默认地址。	`None`
`timeout`	`float`	单次请求超时秒数。	`60.0`
`max_retries`	`int`	SDK 的请求重试次数，不重复执行本地工具。	`2`
`max_tokens`	`int`	单次模型响应 token 上限。	`4096`

引发：

类型	描述
`ValueError`	模型、凭据或资源参数无效时抛出。

Notes

SDK 仅在创建实例时导入。使用自定义 MarsAgentProvider 无需安装 SDK。

chat ¶

chat(
    messages: list[MarsAgentMessage],
    *,
    system: str,
    tools: tuple[MarsAgentTool, ...]
) -> MarsAgentResponse

转换消息和工具协议并解析完整响应。

参数：

名称	类型	描述	默认
`messages`	`list[MarsAgentMessage]`	用户、助手和配对的工具结果。	必需
`system`	`str`	系统提示词。	必需
`tools`	`tuple[MarsAgentTool, ...]`	允许模型调用的工具定义。	必需

返回：

类型	描述
`MarsAgentResponse`	统一响应及真实停止原因。

引发：

类型	描述
`ValueError`	服务未返回候选，或工具参数不是有效 JSON 对象时抛出。

close ¶

close() -> None

关闭 SDK 客户端持有的 HTTP 连接。

mars.agent.MarsAgentProvider ¶

Bases: Protocol

运行器要求的同步模型接口，可由自定义后端或测试替身实现。

chat ¶

chat(
    messages: list[MarsAgentMessage],
    *,
    system: str,
    tools: tuple[MarsAgentTool, ...]
) -> MarsAgentResponse

获取一次完整模型响应。

参数：

名称	类型	描述	默认
`messages`	`list[MarsAgentMessage]`	当前会话消息副本。	必需
`system`	`str`	系统提示词和业务边界。	必需
`tools`	`tuple[MarsAgentTool, ...]`	当前可使用的工具。	必需

返回：

类型	描述
`MarsAgentResponse`	完整响应，工具参数仍由执行器验证。

mars.agent.MarsAgentMessage `dataclass` ¶

与模型厂商无关的会话消息。

参数：

名称	类型	描述	默认
`role`	`Literal['user', 'assistant', 'tool']`	消息角色，系统提示词由运行器单独提供。	必需
`content`	`str`	文本或 JSON 工具结果。	`''`
`tool_calls`	`tuple[MarsAgentToolCall, ...]`	助手发起的工具调用。	`()`
`tool_call_id`	`str \| None`	工具结果对应的调用标识。	`None`

mars.agent.MarsAgentResponse `dataclass` ¶

一次模型调用的完整响应。

参数：

名称	类型	描述	默认
`text`	`str`	模型输出文本。	`''`
`tool_calls`	`tuple[MarsAgentToolCall, ...]`	待执行的工具请求。	`()`
`finish_reason`	`str`	`stop` 表示完成，`tool_calls` 表示继续，其他原因视为未完成。	`'stop'`
`input_tokens`	`int`	模型服务返回的输入 token 数。	`0`
`output_tokens`	`int`	模型服务返回的输出 token 数。	`0`

mars.agent.MarsAgentTool `dataclass` ¶

模型可见的工具说明及参数约束。

参数：

名称	类型	描述	默认
`name`	`str`	工具名称。	必需
`description`	`str`	用途和业务边界。	必需
`parameters`	`dict[str, Any]`	工具输入的 JSON Schema。	必需

mars.agent.MarsAgentToolCall `dataclass` ¶

模型发起的一次结构化工具请求。

参数：

名称	类型	描述	默认
`id`	`str`	当前响应内唯一的调用标识。	必需
`name`	`str`	已登记的工具名称。	必需
`arguments`	`dict[str, Any]`	JSON 对象参数，执行前仍须校验。	`dict()`

mars.agent.MarsAgentToolResult `dataclass` ¶

工具执行结果及可定位的错误状态。

参数：

名称	类型	描述	默认
`call_id`	`str`	对应调用标识。	必需
`name`	`str`	工具名称。	必需
`success`	`bool`	工具是否成功。	必需
`data`	`dict[str, Any]`	经过大小限制的 JSON 结果。	`dict()`
`error_code`	`str \| None`	失败类别；成功时为空。	`None`
`error_message`	`str \| None`	不含底层数据值的错误提示。	`None`

mars.agent.MarsAgentReport `dataclass` ¶

会话内可追溯的 MARS 计算结果快照。

参数：

名称	类型	描述	默认
`id`	`str`	会话内唯一报告标识。	必需
`kind`	`str`	来源工具名称。	必需
`dataset_id`	`str \| None`	当前数据标识；外部报告未登记原始数据时为 None。	必需
`benchmark_id`	`str \| None`	基准数据标识。	必需
`tables`	`dict[str, DataFrame]`	规范命名的完整聚合结果表。	必需
`metadata`	`dict[str, Any]`	MARS 元数据及实际生效参数，仅保存在本地。	必需

mars.agent.MarsAgentResult `dataclass` ¶

一轮用户请求的回答和执行记录。

参数：

名称	类型	描述	默认
`text`	`str`	回答文本；模型结论仍需结合证据复核。	必需
`status`	`str`	`completed`、`incomplete` 或达到资源上限的停止原因。	必需
`iterations`	`int`	本轮模型调用次数。	必需
`tool_results`	`tuple[MarsAgentToolResult, ...]`	本轮工具调用记录。	`()`
`report_ids`	`tuple[str, ...]`	本轮创建或读取的报告，不代表文本中的结论已经自动验证。	`()`
`input_tokens`	`int`	本轮输入 token 累计量。	`0`
`output_tokens`	`int`	本轮输出 token 累计量。	`0`

Agent¶

mars.agent.MarsAgentComputeBudget dataclass ¶

mars.agent.MarsRiskAgent ¶

tools property ¶

execute_tool ¶

run ¶

mars.agent.MarsAgentSession ¶

messages property ¶

report_ids property ¶

register_dataset ¶

get_report ¶

clear_history ¶

register_report ¶

mars.agent.MarsOpenAIProvider ¶

chat ¶

close ¶

mars.agent.MarsAgentProvider ¶

chat ¶

mars.agent.MarsAgentMessage dataclass ¶

mars.agent.MarsAgentResponse dataclass ¶

mars.agent.MarsAgentTool dataclass ¶

mars.agent.MarsAgentToolCall dataclass ¶

mars.agent.MarsAgentToolResult dataclass ¶

mars.agent.MarsAgentReport dataclass ¶

mars.agent.MarsAgentResult dataclass ¶

mars.agent.MarsAgentComputeBudget `dataclass` ¶

tools `property` ¶

messages `property` ¶

report_ids `property` ¶

mars.agent.MarsAgentMessage `dataclass` ¶

mars.agent.MarsAgentResponse `dataclass` ¶

mars.agent.MarsAgentTool `dataclass` ¶

mars.agent.MarsAgentToolCall `dataclass` ¶

mars.agent.MarsAgentToolResult `dataclass` ¶

mars.agent.MarsAgentReport `dataclass` ¶

mars.agent.MarsAgentResult `dataclass` ¶