Files
AgentLab/backend/app/ledger/compose.py
T
ThearchyHelios 4f4ad48ad7 组合式问数:问数据的助手可以 use_caliber 选用已发布口径,服务端确定性内联实例化(口径账本做法 4,拍板 L3)
为什么:问数据以前看不到口径,也没有组合机制;子图做骨架的路走不通(子图证据不交回父图、使用者用不了子工作流)。改成助手只选口径、填参数,取数节点由服务端按固定版本照抄,证据照常封存、比对照常复证。

做了什么:
- 问数据的查看对象加 caliber(look/calibers 的 compose 模式):另给每张卡的入口字段(类型、必填、可选值、格式、缺省值)和「能不能组合」(ledger/derive.load_pinned 同一个认法),能组合的写出 use_caliber 的写法;仍不给 SQL。只给搭建者及以上:使用者的图里看得到拷进来的取数 SQL。
- 新增 ledger/compose.py:use_caliber {id, workflow_id, version, card, metrics, inputs} 经 derive.caliber_block(扩了 card_id、inputs 两项)实例化——取数节点照抄、id 加前缀、模板按参数渲染成字面 SQL,口径卡 id 就是操作 id、caliber_from 带改名映射。参数按入口字段过 apps/forms 校验,写进 SQL 引号里的不能带引号、裸写的只能是数;只能选这一轮看到的那一版、能组合的卡、卡上的指标;不合规拒收。
- GraphApplier 落地 use_caliber:节点、连线记进 seen(兜底重放照样在),入口连到第一个取数节点;转给界面的只有那一条操作带 result;拒收的原因经自查交回模型(GraphChecker.issues)。
- 提示:协议多一段 USE_CALIBER_PROMPT;LOOK_WHEN 里问数据那一条按细案改写(只在能选用口径时换)。运行时写 SQL 的 Agent 不看口径(L2)。
- 比对器认出助手选用的查询(从封存的图里读 caliber_from.nodes):证明了的标 composed「助手选用」,没能证明的照常是相关口径并说明;标签 how=composed,指标标签记取自哪几条查询;比对算法版本升到 2。
- 前端:问数据过程里 use_caliber 照实显示一行(选用了哪一版、生成几个节点;拒收写原因),节点数算进「新增几个步骤」;文案进 LEDGER_TEXT.use;check-decode 加一节。

测试:tests/test_ledger_compose.py(实例化确定性、各种拒收、查看文字不带 SQL、提示切换、落地与接线、拒收交回模型、剧本模型走一遍生成再真跑出 composed 标签、使用者不给口径)。
2026-10-16 16:35:28 +08:00

243 lines
13 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""组合式问数:口径做骨架,Agent 填缺口(docs/design/next-round/02-口径账本.md 做法 4,拍板 L3)。
问数据的助手看到已发布口径(look 的 caliber,问数据里另给入口字段和「能不能组合」,不给 SQL)之后,可以输出一行
{"op":"use_caliber","id":"c1","workflow_id":"…","version":3,"card":"card","metrics":["gmv"],"inputs":{"start":"…"}}
选用一份口径。**取数节点不让模型写**:由服务端按那一版确定性地内联实例化(ledger/derive.caliber_block,全站唯一的
派生图生成器)——口径卡读的取数节点照抄,节点 id 加前缀「c1_」,模板里的 {{ input.字段 }} 按 inputs 渲染成字面 SQL
(和运行时同一个渲染器);口径卡 id 就是 c1,caliber_from 固定到那一版的那张卡、带改名映射 {原 id: c1_原 id}
(metrics 运行时按它改写式子)。取数节点首尾相接、最后一个接口径卡;入口连到第一个取数节点(GraphApplier 接上)。
模型只管把口径卡 c1 接到报告、报告里引用 [[m:指标 id]]。
**为什么不用子图节点。** 子图的证据不交回父图(报告引用不到子图里的数),使用者也用不了子工作流(auth/chat_policy)。
内联实例化只用到 tool 和 metrics 两种已放行的节点,证据照常封存,比对也照常复证(ledger/match 认出这些查询是助手
选用的,标 composed「助手选用」,不标「等价已证明」:选哪份口径是助手凭问法判断的)。
**参数校验**(不合规拒收,原因交回模型改,GraphApplier.refusals):
- 只能选这一轮 look 能看到的那一版(每个工作流最新的已发布、未退役版本),而且那张卡能组合(derive.load_pinned:卡是
源头、每个输入都是取数节点第一行的格、取数模板只引用入口字段);
- inputs 只认口径入口声明的字段,没写的补缺省值,再过 apps/forms 同一套表单校验(类型、可选值、必填、格式);
- 参数要渲染进 SQL:写在引号里的不能带引号、反斜杠、换行;裸写的只能是数;写在注释里的不能带换行和注释结束符——
否则渲染出来的就不是那一版口径的 SQL 了;
- metrics 只能是这张卡上的指标 id;id 不能和图里已有的节点撞。
实例化是确定的:同样的版本、同样的操作得到一模一样的节点(测试锁住)。这里只是纯计算:版本快照由 look/calibers 的
CaliberKind 在开流之前用会话读好(GraphApplier.apply 是同步的,流里不碰库)。
"""
from __future__ import annotations
import copy
import json
import re
from collections.abc import Mapping
from dataclasses import dataclass, field
from typing import Any
from app.ledger.derive import Pinned, caliber_block
#: 操作名
OP = "use_caliber"
#: 拒收时的问题编号(自查交回模型、过程里照实写一行)
REFUSED = "ledger.use_caliber_refused"
#: 操作 id:口径卡的节点 id,取数节点加它做前缀。简短英文小写下划线(同节点 id 的约定)
_OP_ID = re.compile(r"^[a-z][a-z0-9_]{0,23}$")
_NUMBER = re.compile(r"^\s*-?\d+(?:\.\d+)?\s*$")
#: 写给模型的拒收说明(也上界面:过程里那一行)
NOT_LISTED = "只能选用这一轮查看到的已发布口径:「{workflow}」v{version} 不在里面(口径要先 look,版本以查看结果为准)"
WRONG_VERSION = "「{workflow}」这一轮能选用的是 v{latest}(最新的已发布版本),不是 v{version}"
CARD_UNKNOWN = "「{workflow}」v{version} 里没有口径卡「{card}」(有:{cards})"
CARD_AMBIGUOUS = "「{workflow}」v{version} 有几张口径卡({cards}),请在 card 里写选用哪一张"
NOT_COMPOSABLE = "「{workflow}」v{version} 的口径卡「{card}」不能组合:{reason}"
BAD_ID = "use_caliber 的 id 要写成简短的英文小写加下划线(例如 c1),它就是口径卡的节点 id,当前为「{id}」"
ID_TAKEN = "use_caliber 的 id「{id}」和图里已有的节点「{node}」撞了,请换一个"
NO_METRICS = "use_caliber 的 metrics 要写这张口径卡上要用的指标 id(有:{metrics})"
METRIC_UNKNOWN = "口径卡「{card}」上没有指标「{metric}」(有:{metrics})"
FIELD_UNKNOWN = "口径「{workflow}」的入口没有字段「{name}」(有:{fields})"
INPUTS_NOT_OBJECT = "use_caliber 的 inputs 要写成字段和值的对照(JSON 对象)"
QUOTED_VALUE = "参数「{name}」写在 SQL 的引号里,值里不能有引号、反斜杠或换行"
BARE_VALUE = "参数「{name}」直接写在 SQL 里(没有引号),只能是数,当前为「{value}」"
COMMENT_VALUE = "参数「{name}」写在 SQL 的注释里,值里不能有换行或注释结束符"
TEMPLATE_UNREADABLE = "取数节点的 SQL 模板认不出参数写在哪:{reason}"
class ComposeRefused(Exception):
"""不实例化这次选用:message 给模型看、也写进过程里那一行。"""
def __init__(self, message: str) -> None:
super().__init__(message)
self.message = message
@dataclass(frozen=True)
class Option:
"""这一轮能选用的一张口径卡:读好的那一版(pinned),或者不能组合的原因(reason)。"""
workflow_id: str
workflow_name: str
version: int
level: str
node_id: str
card: str
pinned: Pinned | None = None
reason: str | None = None
@property
def composable(self) -> bool:
return self.pinned is not None and self.reason is None
@dataclass
class Composed:
"""一次选用实例化出来的东西:要加的节点、连线(取数首尾相接、最后接口径卡),交给界面和模型的结果。"""
op_id: str
option: Option
nodes: list[dict[str, Any]]
edges: list[dict[str, Any]]
metrics: list[dict[str, Any]]
inputs: dict[str, Any] = field(default_factory=dict)
@property
def fetch_ids(self) -> list[str]:
return [str(n["id"]) for n in self.nodes if n.get("type") != "metrics"]
def result(self) -> dict[str, Any]:
"""交给界面(过程里那一行)、记进这一轮的操作流的结果。不放 SQL、不放参数值(参数值助手自己写的,界面不必再给)。"""
from app.ledger.labels import LEVEL_TEXT
return {"status": "ok", "workflow_id": self.option.workflow_id, "workflow_name": self.option.workflow_name,
"version": self.option.version, "level": self.option.level,
"level_text": LEVEL_TEXT.get(self.option.level, ""), "card": self.option.card, "card_id": self.op_id,
"fetches": self.fetch_ids, "metrics": [{"id": m["id"], "name": m["name"]} for m in self.metrics],
"nodes": len(self.nodes)}
def signature(op: Mapping[str, Any]) -> str:
"""一次选用的身份(接着写时重发的同一个操作认得出来):去掉服务端写上的结果。"""
return json.dumps({k: v for k, v in op.items() if k != "result"}, ensure_ascii=False, sort_keys=True, default=str)
def _names(items: list[str]) -> str:
return "、".join(items[:12]) or "无"
def _slot_contexts(pinned: Pinned) -> dict[str, set[str]]:
"""取数 SQL 模板里每个入口字段写在哪:{字段: {quoted / bare / comment}}。认不出的抛 ComposeRefused。"""
from app.data.sql_semantics import _NotComparable, _template_slots
out: dict[str, set[str]] = {}
for node in pinned.fetches:
args = ((node.get("data") or {}).get("config") or {}).get("args")
sql = args.get("sql") if isinstance(args, dict) else None
if not isinstance(sql, str):
continue
try:
spans, _ = _template_slots(sql)
except _NotComparable as e:
raise ComposeRefused(TEMPLATE_UNREADABLE.format(reason=str(e))) from None
for _, _, slot in spans:
out.setdefault(slot.field, set()).add(slot.context)
return out
def _value_problem(name: str, value: Any, contexts: set[str]) -> str | None:
text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False) \
if isinstance(value, (dict, list)) else str(value)
if "quoted" in contexts and any(ch in text for ch in ("'", "\\", "\n", "\r")):
return QUOTED_VALUE.format(name=name)
if "bare" in contexts and not (isinstance(value, (int, float)) and not isinstance(value, bool)) \
and not (isinstance(value, str) and _NUMBER.match(value)):
return BARE_VALUE.format(name=name, value=text[:40])
if "comment" in contexts and ("\n" in text or "\r" in text or "*/" in text):
return COMMENT_VALUE.format(name=name)
return None
def check_inputs(pinned: Pinned, inputs: Any) -> dict[str, Any]:
"""按口径入口的字段校验助手给的参数,补缺省值,交回要渲染进模板的那一份。不合规抛 ComposeRefused(一句一处)。"""
from app.apps.forms import input_schema, validate_form
if inputs is None:
inputs = {}
if not isinstance(inputs, dict):
raise ComposeRefused(INPUTS_NOT_OBJECT)
fields = {str(f.get("name")).strip(): f for f in pinned.entry_fields if isinstance(f.get("name"), str)}
if unknown := [k for k in inputs if k not in fields]:
raise ComposeRefused(FIELD_UNKNOWN.format(workflow=pinned.workflow_name, name=unknown[0],
fields=_names(list(fields))))
values = {name: copy.deepcopy(f.get("default")) for name, f in fields.items()
if f.get("default") not in (None, "")}
values.update({k: v for k, v in inputs.items() if v is not None and v != ""})
if errors := validate_form(input_schema(list(pinned.entry_fields)), values):
raise ComposeRefused(";".join(e["message"] for e in errors))
contexts = _slot_contexts(pinned)
for name, value in values.items():
if problem := _value_problem(name, value, contexts.get(name, set())):
raise ComposeRefused(problem)
return values
def instantiate(option: Option, op: Mapping[str, Any], *, taken: set[str]) -> Composed:
"""按选用的那一版确定性地实例化(见模块说明)。taken 是图里已有的节点 id。不合规抛 ComposeRefused。"""
pinned = option.pinned
if pinned is None or option.reason is not None:
raise ComposeRefused(NOT_COMPOSABLE.format(workflow=option.workflow_name, version=option.version,
card=option.card, reason=option.reason or "读不到这一版"))
op_id = str(op.get("id") or "").strip()
if not _OP_ID.match(op_id):
raise ComposeRefused(BAD_ID.format(id=op_id))
wanted = [str(m) for m in op.get("metrics") or [] if isinstance(m, (str, int))] \
if isinstance(op.get("metrics"), list) else []
on_card = {str(m["id"]): m for m in pinned.metrics}
if not wanted:
raise ComposeRefused(NO_METRICS.format(metrics=_names(list(on_card))))
if missing := [m for m in wanted if m not in on_card]:
raise ComposeRefused(METRIC_UNKNOWN.format(card=option.card, metric=missing[0], metrics=_names(list(on_card))))
values = check_inputs(pinned, op.get("inputs"))
block = caliber_block(pinned, prefix=f"{op_id}_", card_id=op_id, inputs=values)
if clash := next((str(n["id"]) for n in block.nodes if str(n["id"]) in taken), None):
raise ComposeRefused(ID_TAKEN.format(id=op_id, node=clash))
nodes = block.nodes
edges = [{"source": a["id"], "target": b["id"]} for a, b in zip(nodes, nodes[1:])]
metrics = [{"id": m, "name": str(on_card[m].get("name") or m)} for m in wanted]
return Composed(op_id=op_id, option=option, nodes=nodes, edges=edges, metrics=metrics, inputs=values)
class Composer:
"""GraphApplier 用的:这一轮能选用的口径卡(CaliberKind 在开流之前读好),按 use_caliber 实例化。"""
def __init__(self, options: list[Option]) -> None:
self.options = options
def pick(self, op: Mapping[str, Any]) -> Option:
workflow_id = str(op.get("workflow_id") or "").strip()
version = op.get("version")
cards = [o for o in self.options if o.workflow_id == workflow_id]
if not cards:
named = str(op.get("workflow_name") or workflow_id or "(没写工作流)")
raise ComposeRefused(NOT_LISTED.format(workflow=named, version=version))
name = cards[0].workflow_name
latest = cards[0].version
if str(version) != str(latest):
raise ComposeRefused(WRONG_VERSION.format(workflow=name, latest=latest, version=version))
card = str(op.get("card") or "").strip()
listed = [f"{o.card}({o.node_id})" for o in cards]
if card:
hit = next((o for o in cards if card in (o.node_id, o.card)), None)
if hit is None:
raise ComposeRefused(CARD_UNKNOWN.format(workflow=name, version=latest, card=card,
cards=_names(listed)))
return hit
if len(cards) > 1:
raise ComposeRefused(CARD_AMBIGUOUS.format(workflow=name, version=latest, cards=_names(listed)))
return cards[0]
def compose(self, op: Mapping[str, Any], *, taken: set[str]) -> Composed:
return instantiate(self.pick(op), op, taken=taken)
__all__ = ["OP", "REFUSED", "ComposeRefused", "Composed", "Composer", "Option", "check_inputs", "instantiate",
"signature"]