mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-16 07:21:58 +00:00
09949fc8ac
- 模型接入:支持跨 Anthropic / OpenAI 兼容网关显式关闭深度思考(thinking=off / effort=low),对不识别推理参数的网关自动剥离重发并做进程级记忆 - 快速直查:收敛直查图推理预算(max_steps=4),杜绝长思维链与多轮现场盲探 - 语义指标与预命中:Oracle / PostgreSQL 分组聚合补充 DESC NULLS LAST;基于关系图、逆表频共享键与低基数统计(1..20 distinct)实现零硬编码的通用关联维表发现、分类列抽样及全空分组折叠诊断 - 零延迟数字证据:支持纯数字文本编码(含前导零)无损回绑、多表同行实体键与列序号消歧,结合上下文事实白名单与冲突守卫消除误报并保留防编造拦截
223 lines
10 KiB
Python
223 lines
10 KiB
Python
"""独立语义指标库内置只读工具:metric_query。
|
||
|
||
设计原则:
|
||
1. 只执行 status="enabled" 的已启用指标卡片(SemanticMetric),确定性编译为单条只读 SELECT 语句。
|
||
2. 底层委托对应数据源的 `db_query__<源名>` 工具执行:自动继承上传快照版本锁定(data_versions)、
|
||
普通使用者结果遮罩(MASK_RESULTS_OPTION)、只读守卫(READ_ONLY_OPTION)、数据目录 SQL 检查(SqlChecker)
|
||
以及内容寻址查询快照落盘(query_snapshot),运行证据链与 `db_query__` 完全一致。
|
||
3. 支持按日期区间(date_from / date_to)、时间序列趋势(group_by_date / time_grain)、业务维度下钻(group_by)
|
||
与标准业务实体值过滤(filters,自动把业务别名翻译为目标源底层编码)。
|
||
4. 当单日查询返回空或全 NULL 且配置了业务时间列时,在同一次调用结果内附带底表最新可用日期 `latest_available_date`,
|
||
消除 Agent 多轮探查开销。
|
||
"""
|
||
from __future__ import annotations
|
||
|
||
from collections.abc import Mapping
|
||
import json
|
||
from typing import Any
|
||
|
||
from pydantic import BaseModel, Field, model_validator
|
||
|
||
from app.data import catalog
|
||
from app.data.engine import masked_columns
|
||
from app.data.entities import list_entities
|
||
from app.data.names import name_key
|
||
from app.data.semantic_metrics import (
|
||
MetricInvalid,
|
||
MetricNotFound,
|
||
compile_metric_sql,
|
||
find_companion_lookup_tables,
|
||
get_metric,
|
||
is_empty_metric_result,
|
||
probe_latest_metric_date,
|
||
)
|
||
from app.db.base import SessionLocal
|
||
from app.db.models import DataSource
|
||
from app.tools.datasource import QUERY_PREFIX
|
||
from app.tools.registry import ToolContext, ToolGuide, Versions, build_tools, register
|
||
|
||
METRIC_QUERY = "metric_query"
|
||
|
||
METRIC_GUIDE = ToolGuide(
|
||
id="semantic_metric.method@1",
|
||
text=(
|
||
"【语义指标查询纪律】\n"
|
||
"当用户提问命中已启用的独立语义指标(metric_key)时,优先调用 `metric_query` 获取标准口径结果:\n"
|
||
"- 查某一天传 `date_from` 与 `date_to` 为同一日期;查趋势或近 N 日明细传区间并设 `group_by_date=true`;\n"
|
||
"- 按业务维度拆分传 `group_by`(填指标声明的维度 key);按实体或维度筛选传 `filters`(可直接传业务名称,系统自动翻译底层编码);\n"
|
||
"- 若返回结果附带 `latest_available_date`(例如当日 T+1 尚未入库),可据此说明当日暂无数据或按需再查最新日期。"
|
||
),
|
||
)
|
||
|
||
|
||
class MetricQueryArgs(BaseModel):
|
||
"""按已启用的语义指标卡片(SemanticMetric)执行确定性聚合取数。"""
|
||
|
||
metric: str = Field(description="要查询的语义指标 key、指标 id 或唯一指标名称")
|
||
date_from: str | None = Field(default=None, description="可选:起始业务日期 YYYY-MM-DD(闭区间)")
|
||
date_to: str | None = Field(default=None, description="可选:结束业务日期 YYYY-MM-DD(闭区间)")
|
||
group_by_date: bool = Field(default=False, description="是否按时间序列分组输出趋势(如逐日/逐月)")
|
||
time_grain: str | None = Field(
|
||
default=None,
|
||
description="可选:时间分组粒度 day | month | hour(配合 group_by_date=true 使用,默认按指标设定)",
|
||
)
|
||
group_by: list[str] = Field(
|
||
default_factory=list,
|
||
description="可选:按指标声明的维度 key 分组下钻,例如 ['area', 'store']",
|
||
)
|
||
filters: dict[str, Any] = Field(
|
||
default_factory=dict,
|
||
description="可选:按指标声明的维度过滤,例如 {'area': '西区'}(关联了标准业务实体的维度会自动翻译物理编码)",
|
||
)
|
||
limit: int = Field(default=200, ge=1, le=1000, description="分组查询最多返回行数,默认 200")
|
||
|
||
@model_validator(mode="before")
|
||
@classmethod
|
||
def _accept_metric_key_aliases(cls, data: Any) -> Any:
|
||
if isinstance(data, dict) and "metric" not in data:
|
||
for alt in ("metric_key", "key", "metric_id"):
|
||
if alt in data and data[alt] is not None:
|
||
copied = dict(data)
|
||
copied["metric"] = copied.pop(alt)
|
||
return copied
|
||
return data
|
||
|
||
|
||
@register(
|
||
name=METRIC_QUERY,
|
||
description="按已启用的独立语义指标卡片查询标准口径数值、时间趋势或维度拆解明细(自动应用有效记录过滤与标准业务实体编码转换)",
|
||
category="data",
|
||
args_schema=MetricQueryArgs,
|
||
dangerous=False,
|
||
needs_context=True,
|
||
guide=METRIC_GUIDE,
|
||
)
|
||
async def run_metric_query(
|
||
ctx: ToolContext,
|
||
metric: str,
|
||
date_from: str | None = None,
|
||
date_to: str | None = None,
|
||
group_by_date: bool = False,
|
||
time_grain: str | None = None,
|
||
group_by: list[str] | None = None,
|
||
filters: dict[str, Any] | None = None,
|
||
limit: int = 200,
|
||
) -> str:
|
||
async with SessionLocal() as session:
|
||
try:
|
||
row = await get_metric(session, metric)
|
||
except MetricNotFound as exc:
|
||
return f"查询失败:{exc}"
|
||
if row.status != "enabled":
|
||
return f"查询失败:指标「{row.name}({row.key})」当前状态为 {row.status},未启用"
|
||
ds = await session.get(DataSource, row.source_id)
|
||
if ds is None or not ds.enabled:
|
||
return f"查询失败:指标「{row.name}」关联的数据源不可用或已停用"
|
||
|
||
entities = await list_entities(session)
|
||
try:
|
||
sql, alignments = compile_metric_sql(
|
||
row,
|
||
source=ds,
|
||
entities=entities,
|
||
date_from=date_from,
|
||
date_to=date_to,
|
||
group_by_date=group_by_date,
|
||
time_grain=time_grain,
|
||
group_by=group_by or [],
|
||
filters=filters or {},
|
||
limit=limit,
|
||
)
|
||
except MetricInvalid as exc:
|
||
return f"查询失败:{exc}"
|
||
|
||
sub_ctx = ctx
|
||
if sub_ctx.data_versions is Versions.UNSET and not sub_ctx.run_id:
|
||
# 工具试用等非运行上下文默认读当前版本
|
||
from dataclasses import replace
|
||
|
||
sub_ctx = replace(ctx, data_versions=Versions.CURRENT)
|
||
|
||
query_tool_name = f"{QUERY_PREFIX}{ds.name}"
|
||
built = await build_tools([query_tool_name], sub_ctx, session=session)
|
||
if not built:
|
||
return f"查询失败:无法初始化数据源「{ds.name}」的查询工具"
|
||
|
||
raw_res = await built[0].ainvoke({"sql": sql, "limit": limit})
|
||
raw_str = raw_res if isinstance(raw_res, str) else json.dumps(raw_res, ensure_ascii=False, default=str)
|
||
if not raw_str.lstrip().startswith("{"):
|
||
return raw_str
|
||
|
||
try:
|
||
payload = json.loads(raw_str)
|
||
except ValueError:
|
||
return raw_str
|
||
|
||
payload["metric"] = {
|
||
"id": row.id,
|
||
"key": row.key,
|
||
"name": row.name,
|
||
"unit": row.unit or "",
|
||
}
|
||
if alignments:
|
||
payload["entity_alignments"] = alignments
|
||
|
||
has_groups = bool(group_by_date or group_by)
|
||
rows_data = payload.get("rows") if isinstance(payload.get("rows"), list) else []
|
||
all_metric_null = bool(
|
||
has_groups
|
||
and rows_data
|
||
and all(isinstance(r, (list, tuple)) and len(r) >= 2 and r[-1] is None for r in rows_data)
|
||
)
|
||
if all_metric_null:
|
||
payload["all_metric_values_null"] = True
|
||
payload["null_group_row_count"] = len(rows_data)
|
||
if len(rows_data) > 5:
|
||
payload["rows"] = rows_data[:5]
|
||
|
||
is_empty_or_null = is_empty_metric_result(rows_data, has_groups=has_groups) or all_metric_null
|
||
cache = ds.schema_cache if isinstance(ds.schema_cache, Mapping) else {}
|
||
tables_map = (cache.get("tables") or {}) if isinstance(cache, Mapping) else {}
|
||
if is_empty_or_null and isinstance(tables_map, Mapping) and row.table_name:
|
||
resolved_tbl = catalog.resolve_table_name(cache, row.table_name) or row.table_name
|
||
masked_set = {name_key(c) for c in masked_columns(ds.options)}
|
||
entries = await catalog.read_catalog(session, ds.id)
|
||
vis_by_tbl = {t: catalog.visible_notes(e.notes) for t, e in entries.items()}
|
||
v_notes = vis_by_tbl.get(resolved_tbl) or {}
|
||
v_filt = str((v_notes.get("valid_filter") or {}).get("value") or "").strip() if isinstance(v_notes.get("valid_filter"), Mapping) else ""
|
||
v_dedup = str((v_notes.get("dedup") or {}).get("value") or "").strip() if isinstance(v_notes.get("dedup"), Mapping) else ""
|
||
companions = find_companion_lookup_tables(
|
||
tables_map,
|
||
[resolved_tbl],
|
||
visible_by_table=vis_by_tbl,
|
||
masked_set=masked_set,
|
||
)
|
||
hint_bits: list[str] = []
|
||
if v_filt and v_filt.lower() not in (row.filter_sql or "").lower():
|
||
hint_bits.append(f"目录有效过滤 `{v_filt}`")
|
||
if v_dedup:
|
||
hint_bits.append(f"去重与分层提示「{v_dedup}」")
|
||
if companions:
|
||
comp_desc = "、".join(
|
||
f"`{c['table_name']}`(关联列 `{', '.join(c['source_columns'])}`)"
|
||
for c in companions[:2]
|
||
)
|
||
hint_bits.append(f"关联维表或配置表 {comp_desc}")
|
||
if hint_bits:
|
||
payload["diagnostic_hint"] = (
|
||
f"本次指标结果为空或全为 NULL;底表 `{resolved_tbl}` 存在 {';'.join(hint_bits)},"
|
||
"若需排查分类口径或维度映射,请在单轮内并行联查核实。"
|
||
)
|
||
|
||
if is_empty_or_null and row.date_column:
|
||
latest_date = await probe_latest_metric_date(
|
||
ds,
|
||
table_name=row.table_name,
|
||
date_column=row.date_column,
|
||
filter_sql=row.filter_sql or "",
|
||
)
|
||
if latest_date:
|
||
payload["latest_available_date"] = latest_date
|
||
|
||
return json.dumps(payload, ensure_ascii=False, default=str)
|