Files
AgentLab/backend/app/ledger/store.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

147 lines
7.4 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.
"""口径账本的记法(docs/design/next-round/02-口径账本.md 做法 2,拍板 L8):比对结果存成内容寻址工件,不建新表。
一次比对 = 一份工件 kind=caliber_match(格式 agentlab.caliber_match/1)+ 一条封存之后追加的事件 ledger.matched
{artifact, manifest_hash, algo, counts, trigger}(engine/run_append 的 sealed 方式,同按需裁判的 evidence.judged):
- 工件内容只放比对本身:运行 id、对着哪一次封存(manifest_hash / manifest_seq)、算法版本、考虑过的口径版本(工作流、版本、
级别、graph_hash)、每条查询的状态和绑定、差异条目、列映射、每个数的标签、整题判断。不放时间、耗时、工作流名(名字会改,
界面读的时候再取):同一份封存、同一个算法版本、同一批口径,再比一次得到的工件一字不差、哈希一样。
- 工件引用的 meta 记 {calibers: [等价已证明的「工作流@版本」], related: [相关的], counts}:召回按旧版本反查、统计按种类数,
都只扫 artifacts(kind 有索引),不逐份读内容。
- 事件说的是「这一次封存的这份比对」:读的时候只认 manifest_hash 等于运行现在封存的那几条,取最后一条(之后口径有变、补比
过的,以最新的为准)。工件读不出、被改过、不是这次运行这次封存的,照实说读不出,不拿它标数。
trigger 是谁触发的:sealed(运行封存后马上比的)、backfill(启动时补比)、on_demand(打开账本时按需比的)。后两种是事后按
那时的口径回看的,界面据此写「按现在的口径回看」。它只在事件里,不进工件内容(不然同一份比对因为触发方式不同哈希就不同)。
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Any
from sqlalchemy import select
from app.core.events import EventType
from app.db.base import SessionLocal
from app.db.models import Run, RunEvent
#: 工件的种类和内容格式
KIND = "caliber_match"
FORMAT = "agentlab.caliber_match/1"
#: 比对算法的版本:绑定、证明、标签的规则改了就加一,界面和统计据此分得清是哪一版算法比的。
#: 2(第 3 波):认出助手选用的口径(查询 composed、标签 how=composed),指标的标签记它取自哪几条查询(queries,认证队列
#: 认「被报告引用的查询」用)
ALGO = "2"
#: 触发方式(见模块说明)
TRIGGERS = ("sealed", "backfill", "on_demand")
@dataclass(frozen=True)
class Recorded:
"""一次运行现在这次封存的最新一份比对。content 读不出时为 None,problem 写为什么。"""
artifact: str
seq: int
ts: Any
trigger: str
algo: str | None
content: dict[str, Any] | None
problem: str | None = None
@property
def retro(self) -> bool:
"""事后按那时的口径回看的(启动时补比、打开时按需比的),不是运行一封存就比的。"""
return self.trigger != "sealed"
#: 读不出比对工件时的说法
UNREADABLE = "比对记录读不出来(文件缺失)"
TAMPERED = "比对记录与哈希不一致,疑似被修改,不能用来标口径"
FOREIGN = "比对记录不属于这次运行的这次封存,不能用来标口径"
def counts_of(queries: list[dict[str, Any]]) -> dict[str, int]:
"""每种查询状态各几条(proven / composed / related / none / skipped),0 也写。"""
out = {status: 0 for status in ("proven", "composed", "related", "none", "skipped")}
for query in queries:
status = str(query.get("status") or "")
if status in out:
out[status] += 1
return out
def meta_of(content: dict[str, Any]) -> dict[str, Any]:
"""工件引用的 meta:{calibers: [等价已证明的「工作流@版本」], related: [相关的], counts}。"""
proven: list[str] = []
related: list[str] = []
for query in content.get("queries") or []:
for cand in query.get("candidates") or []:
key = str(cand.get("caliber") or "")
if not key:
continue
bucket = proven if cand.get("status") == "proven" else related
if key not in bucket:
bucket.append(key)
related = [key for key in related if key not in proven]
return {"calibers": sorted(proven), "related": sorted(related), "counts": counts_of(content.get("queries") or [])}
async def save(run_id: str, content: dict[str, Any], *, seal: tuple[int | None, str | None],
trigger: str) -> str | None:
"""存比对工件、追加 ledger.matched。返回工件 id;运行在比对期间换了封存(没抢到)时只存了工件、没追加事件,返回 None
(不算这次运行的比对:读的时候只认事件)。"""
from app.core.artifact_store import put_json
from app.engine.run_append import append_events
if trigger not in TRIGGERS:
raise ValueError(f"不认识的比对触发方式:{trigger}")
meta = meta_of(content)
artifact = await put_json(content, kind=KIND, run_id=run_id, meta=meta)
written = await append_events(run_id, [(EventType.LEDGER_MATCHED, None, {
"artifact": artifact, "manifest_hash": content.get("manifest_hash"), "algo": content.get("algo"),
"counts": meta["counts"], "trigger": trigger,
})], require="sealed", seal=seal)
return artifact if written else None
async def latest(run_id: str) -> Recorded | None:
"""这次运行现在这次封存的最新一份比对;没比对过(或者比对的是以前的封存)为 None。"""
from app.core.artifact_store import load
async with SessionLocal() as session:
manifest = await session.scalar(select(Run.manifest_hash).where(Run.id == run_id))
if not manifest:
return None
rows = (await session.execute(
select(RunEvent.seq, RunEvent.ts, RunEvent.data).where(
RunEvent.run_id == run_id, RunEvent.type == EventType.LEDGER_MATCHED)
.order_by(RunEvent.seq.desc()))).all()
for seq, ts, data in rows:
if not isinstance(data, dict) or data.get("manifest_hash") != manifest or not data.get("artifact"):
continue
artifact = str(data["artifact"])
trigger = str(data.get("trigger") or "sealed")
try:
content = load(artifact)
except ValueError:
return Recorded(artifact, seq, ts, trigger, data.get("algo"), None, TAMPERED)
if not isinstance(content, dict):
return Recorded(artifact, seq, ts, trigger, data.get("algo"), None, UNREADABLE)
if content.get("format") != FORMAT or content.get("run_id") != run_id \
or content.get("manifest_hash") != manifest:
return Recorded(artifact, seq, ts, trigger, data.get("algo"), None, FOREIGN)
return Recorded(artifact, seq, ts, trigger, data.get("algo"), content)
return None
async def matched_run_ids(session: Any, run_ids: list[str]) -> set[str]:
"""这几次运行里有过比对事件的(不管是哪一次封存的):启动补比据此跳过比过的。"""
if not run_ids:
return set()
rows = await session.execute(select(RunEvent.run_id).where(
RunEvent.run_id.in_(run_ids), RunEvent.type == EventType.LEDGER_MATCHED).distinct())
return {r for (r,) in rows}
__all__ = ["ALGO", "FORMAT", "KIND", "TRIGGERS", "Recorded", "counts_of", "latest", "matched_run_ids", "meta_of", "save"]