mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-18 00:11:59 +00:00
口径起草一次到位:生成取数图并自动试运行,不再要求人工接一次运行
「不从指标定义编译 SQL」管的是事后比对的基准,不是起草。起草照样让模型写 SQL,但只允许 目录里的表和列、单条只读 SELECT、入口字段必须先声明;每条定义仍要能逐字对上原文。 起草成功即建工作流与 v1;试运行只跑取数与口径卡(derive.caliber_probe),不触发报告撰写, 也不会因为没有可用模型就判这份口径不行。接上一次运行保留为辅助入口。
This commit is contained in:
+261
-30
@@ -19,8 +19,10 @@
|
||||
- GET /api/ledger/calibers、GET /api/ledger/calibers/{workflow_id}/{version}/{node_id}(router,搭建者):口径可调用描述
|
||||
(app/ledger/descriptor.py):入口字段的 JSON Schema、依赖、能不能组合和出具;不返回 SQL 和参数值。
|
||||
- POST /api/ledger/drafts/extract、GET /api/ledger/drafts、GET/PATCH /api/ledger/drafts/{id}、POST …/{id}/dismiss、
|
||||
POST …/{id}/attach(router,搭建者):从业务文档起草口径(app/ledger/docdraft.py),草稿独立存在、不写进
|
||||
workflows.graph;attach 才按一次真实运行补上取数路径(app/ledger/docattach.py)。
|
||||
POST …/{id}/attach、GET …/{id}/trial(router,搭建者):从业务文档起草口径。主路径一次到位:模型读文档和数据目录,
|
||||
产出定义 + 取数 SQL + 入口字段 + 指标表达式(app/ledger/draftplan.py),服务端校验收成草稿图、建草稿工作流和 v1,
|
||||
后台自动只读试跑;草稿页给「定义 + 数 + 原文引用」。attach 保留为辅助入口:已经有跑对的答案时让它认这份定义
|
||||
(app/ledger/docattach.py)。
|
||||
这几个新接口都不放给访问密钥(auth/keys.KEY_ROUTES 不登记)。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
@@ -404,8 +406,142 @@ def _question_count(payload: dict[str, Any]) -> int:
|
||||
|
||||
|
||||
def _status_for(payload: dict[str, Any]) -> str:
|
||||
"""还有问题 → questions_open,否则 path_pending(等一次真实运行补取数路径)。"""
|
||||
return "questions_open" if _question_count(payload) else "path_pending"
|
||||
"""还有问题 → questions_open;没有问题且有图 → ready;没有图的老草稿 → path_pending。
|
||||
|
||||
questions_open 现在也有图和数,只是问题还没清完,不阻断试跑;path_pending 只留给这次改版之前起草、还没有取数路径的草稿。
|
||||
"""
|
||||
if _question_count(payload):
|
||||
return "questions_open"
|
||||
if payload.get("workflow_id") and payload.get("sql"):
|
||||
return "ready"
|
||||
return "path_pending"
|
||||
|
||||
|
||||
#: 试跑最多等多久(秒)和轮询间隔:和 trial_caliber 的 300 × 0.1 一致
|
||||
TRIAL_TIMEOUT_S = 30
|
||||
TRIAL_POLL_S = 0.1
|
||||
#: 运行到这里就是终态了(interrupted 归到 failed,接口契约只有三种状态)
|
||||
TERMINAL_RUN_STATUSES = ("succeeded", "failed", "cancelled", "interrupted")
|
||||
|
||||
|
||||
def _run_status(status: Any) -> str:
|
||||
"""运行状态 → 接口契约里的 succeeded / failed / running。"""
|
||||
if status == "succeeded":
|
||||
return "succeeded"
|
||||
if status in ("failed", "cancelled", "interrupted"):
|
||||
return "failed"
|
||||
return "running"
|
||||
|
||||
|
||||
def _source_tables(source: DataSource) -> dict[str, Any]:
|
||||
cache = source.schema_cache if isinstance(source.schema_cache, dict) else {}
|
||||
tables = cache.get("tables")
|
||||
return tables if isinstance(tables, dict) else {}
|
||||
|
||||
|
||||
async def _schema_material(session: AsyncSession, source: DataSource) -> tuple[str, set[str]]:
|
||||
"""这个数据源给模型看的表结构 + 数据目录文本,以及 SQL 允许出现的表名集合。
|
||||
|
||||
给模型的是「库概览 + 紧凑表名索引 + 前几十张表的字段/目录」(schema_view 的现成渲染),表名一律照目录原文,模型照着抄。
|
||||
allowed_tables 收全部探查到的表(含 schema 前缀写法):文本里被截掉详情的表也允许,因为索引里有名字。
|
||||
"""
|
||||
from app.data import catalog, schema_view
|
||||
|
||||
cache = source.schema_cache if isinstance(source.schema_cache, dict) else {}
|
||||
tables = _source_tables(source)
|
||||
if not tables:
|
||||
return "", set()
|
||||
entries = await catalog.read_catalog(session, source.id)
|
||||
notes = {table: entry.notes for table, entry in entries.items()}
|
||||
lines = [schema_view.overview_line(source, catalog_tables=sum(
|
||||
1 for entry in entries.values() if catalog.visible_notes(entry.notes)))]
|
||||
lines.append(schema_view.table_index(source, notes))
|
||||
for position, table in enumerate(tables):
|
||||
if position >= 60:
|
||||
break
|
||||
lines.append(schema_view.table_detail(source, table, catalog_notes=notes))
|
||||
schema = cache.get("schema")
|
||||
allowed: set[str] = set()
|
||||
for table in tables:
|
||||
allowed.add(str(table))
|
||||
if isinstance(schema, str) and schema:
|
||||
allowed.add(f"{schema}.{table}")
|
||||
return "\n\n".join(line for line in lines if line), allowed
|
||||
|
||||
|
||||
async def _save_trial(draft_id: str, trial: dict[str, str]) -> None:
|
||||
"""把试跑状态写进 draft.payload["trial"](用新会话:后台这一段和起草那段不是同一个事务)。"""
|
||||
async with SessionLocal() as fresh:
|
||||
row = await fresh.get(CaliberDraft, draft_id)
|
||||
if row is None or not isinstance(row.payload, dict):
|
||||
return
|
||||
body = dict(row.payload)
|
||||
body["trial"] = trial
|
||||
row.payload = body
|
||||
await fresh.commit()
|
||||
|
||||
|
||||
async def _run_trial(*, draft_id: str, workflow_id: str, graph: dict[str, Any], values: dict[str, Any],
|
||||
started_by: str | None) -> dict[str, str]:
|
||||
"""后台试跑草稿的取数与口径卡,返回 payload["trial"] 的形状(run_id / status / error)。
|
||||
|
||||
跑的是**探针图**(取数 + 口径卡,`derive.caliber_probe`),不是整张草稿图:草稿图里带着报告撰写节点,
|
||||
试跑只关心数对不对,不该为了一次试跑多花一次模型调用、也不该因为没有可用模型就判这份口径不行。
|
||||
|
||||
不复用 trial_caliber:那里要求「已发布」,草稿本来就没发布。来源记 caliber_trial;起来之后先写一次 run_id,
|
||||
页面这时就能去看运行;轮询到终态或者等满 TRIAL_TIMEOUT_S,没跑完就照实答 running。
|
||||
"""
|
||||
from app.engine.runner import run_manager
|
||||
from app.ledger.derive import NotDerivable, caliber_probe, load_pinned
|
||||
|
||||
card_id = next((n.get("id") for n in graph.get("nodes") or []
|
||||
if isinstance(n, dict) and n.get("type") == "metrics"), None)
|
||||
if not card_id:
|
||||
return {"run_id": "", "status": "failed", "error": "这份草稿没有口径卡,没有可试运行的指标"}
|
||||
try:
|
||||
async with SessionLocal() as read:
|
||||
pinned = await load_pinned(read, workflow_id, 1, str(card_id))
|
||||
target = caliber_probe(pinned).graph
|
||||
except NotDerivable as e:
|
||||
return {"run_id": "", "status": "failed", "error": f"口径卡不能派生探针:{e.message}"}
|
||||
|
||||
try:
|
||||
run = await run_manager.start(
|
||||
graph=target, input_payload=values, run_class="exploratory", origin_kind="caliber_trial",
|
||||
origin={"kind": "caliber_trial", "draft_id": draft_id, "workflow_id": workflow_id, "version": 1,
|
||||
"node_id": str(card_id)},
|
||||
started_by=started_by)
|
||||
except Exception as e: # noqa: BLE001 - 试跑发起失败不该把已经生成的草稿弄没
|
||||
logger.exception("草稿 %s 的试运行没有发起", draft_id)
|
||||
return {"run_id": "", "status": "failed", "error": f"试运行没有发起:{e}"}
|
||||
await _save_trial(draft_id, {"run_id": run.id, "status": "running", "error": ""})
|
||||
row: Run | None = None
|
||||
for _ in range(int(TRIAL_TIMEOUT_S / TRIAL_POLL_S)):
|
||||
async with SessionLocal() as poll:
|
||||
row = await poll.get(Run, run.id)
|
||||
if row is None or row.status in TERMINAL_RUN_STATUSES:
|
||||
break
|
||||
await asyncio.sleep(TRIAL_POLL_S)
|
||||
status = _run_status(row.status if row is not None else "running")
|
||||
error = str(row.error or "") if row is not None and status == "failed" else ""
|
||||
return {"run_id": run.id, "status": status, "error": error}
|
||||
|
||||
|
||||
async def _trial_metrics(run_id: str) -> list[dict[str, Any]]:
|
||||
"""试跑运行里口径卡上的指标值:复用证据接口读封存的现成函数,不另写指标集解析。"""
|
||||
from app.api.evidence import _sealed, _sealed_cards
|
||||
|
||||
try:
|
||||
sealed = await _sealed(run_id)
|
||||
cards = {node_id: card for node_id, _, card in _sealed_cards(sealed)}
|
||||
except Exception: # noqa: BLE001 - 证据读不出来就只给状态,不编造指标值
|
||||
logger.exception("试跑 %s 的指标值读不出来", run_id)
|
||||
return []
|
||||
card = cards.get("card") or next(iter(cards.values()), None)
|
||||
if not isinstance(card, dict):
|
||||
return []
|
||||
return [{k: m.get(k) for k in ("id", "name", "rendered", "value") if m.get(k) is not None}
|
||||
for m in card.get("metrics") or [] if isinstance(m, dict) and m.get("id")]
|
||||
|
||||
|
||||
def _draft_summary(draft: CaliberDraft) -> dict[str, Any]:
|
||||
@@ -466,12 +602,15 @@ def _doc_title(docs: list[Document]) -> str:
|
||||
|
||||
|
||||
async def _extract_in_background(draft_id: str) -> None:
|
||||
"""后台起草:读文档的段落、调一次模型、和已发布口径对齐,结果写回这一行。
|
||||
"""后台起草:读文档的段落和数据目录、调一次模型、校验收成草稿图、建草稿工作流、再跑一次试跑。
|
||||
|
||||
用新的会话:请求那一份在响应发出后就关了,后台接着用它写库是错的。失败写进 error、状态留在 drafting——
|
||||
草稿不是「被驳回」,人改完文档还能再来一次。
|
||||
用新的会话:请求那一份在响应发出后就关了,后台接着用它写库是错的。没有数据源或没有表结构时起草必须失败——SQL 只能
|
||||
对照真实目录写,没有目录就不让模型猜。个别指标不合格只丢那一条、写进 dropped / open_questions;SQL 本身不合格才整份
|
||||
失败(图跑不了,留着也没有意义)。
|
||||
"""
|
||||
from app.ledger import docdraft
|
||||
from app.core.artifact_store import graph_hash
|
||||
from app.db.models import WorkflowVersion
|
||||
from app.ledger import docdraft, draftplan
|
||||
|
||||
async with SessionLocal() as session:
|
||||
draft = await session.get(CaliberDraft, draft_id)
|
||||
@@ -496,25 +635,69 @@ async def _extract_in_background(draft_id: str) -> None:
|
||||
chunk_ids.append(chunk.id)
|
||||
entries.append({"document_id": doc.id, "title": doc.title or doc.source or doc.id,
|
||||
"chunk_ids": chunk_ids})
|
||||
datasource = None
|
||||
if draft.datasource_id:
|
||||
source = await session.get(DataSource, draft.datasource_id)
|
||||
if source is not None:
|
||||
datasource = {"name": source.name, "type": source.kind, "description": source.description}
|
||||
|
||||
source = await session.get(DataSource, draft.datasource_id) if draft.datasource_id else None
|
||||
if source is None:
|
||||
draft.error = "没有数据源:生成取数 SQL 必须对照数据目录里的表和列"
|
||||
draft.status = "failed"
|
||||
await session.commit()
|
||||
return
|
||||
tables_text, allowed_tables = await _schema_material(session, source)
|
||||
if not allowed_tables:
|
||||
draft.error = "这个数据源还没有表结构:先探查表结构,再起草口径"
|
||||
draft.status = "failed"
|
||||
await session.commit()
|
||||
return
|
||||
datasource = {"name": source.name, "type": source.kind, "description": source.description}
|
||||
|
||||
guidance = str(origin.get("guidance") or "")
|
||||
alignment: dict[str, list[Any]] = {"new": [], "duplicate": [], "conflict": []}
|
||||
try:
|
||||
result = await docdraft.extract(session, docs=entries, chunks=chunks,
|
||||
guidance=str(origin.get("guidance") or ""), datasource=datasource)
|
||||
result = await draftplan.plan(session, docs=entries, chunks=chunks, guidance=guidance,
|
||||
datasource=datasource, tables_text=tables_text)
|
||||
plan, problems = draftplan.normalize_plan(result, chunks, allowed_tables=allowed_tables)
|
||||
base = {
|
||||
"documents": entries, "metrics": plan["metrics"], "entry_fields": plan["entry_fields"],
|
||||
"sql": plan["sql"], "version": 1,
|
||||
"trial": {"run_id": "", "status": "running", "error": ""},
|
||||
"dropped": problems, "truncated": result["truncated"], "model_id": result["model_id"],
|
||||
}
|
||||
if not plan["sql"] or not plan["metrics"]:
|
||||
error = _problems_text(problems) or "模型没有给出可用的取数 SQL 和指标"
|
||||
draft.payload = {**base, "trial": {"run_id": "", "status": "failed", "error": error}}
|
||||
draft.model_id = result["model_id"] or None
|
||||
draft.error = error
|
||||
draft.status = "failed"
|
||||
await session.commit()
|
||||
return
|
||||
# 对齐要扫所有已发布口径:某一份读不出来不该让整份草稿失败,照实不做对齐(alignment 三个空列表)
|
||||
try:
|
||||
existing = await _published_metrics(session)
|
||||
except Exception: # noqa: BLE001 - 对齐是辅助信息,不是草稿本身
|
||||
logger.exception("读已发布口径失败,草稿 %s 不做对齐", draft_id)
|
||||
existing = []
|
||||
alignment = docdraft.alignment(plan["metrics"], existing)
|
||||
|
||||
plan["datasource"] = source.name
|
||||
graph = draftplan.build_graph(plan, name=draft.title,
|
||||
question=guidance or draft.title)
|
||||
questions = list(plan["open_questions"]) + [
|
||||
f"{p['name']}:{p['reason']}" for p in problems
|
||||
if p.get("name") not in ("sql", "metrics")]
|
||||
workflow = Workflow(
|
||||
name=(draft.title.strip() or "文档口径草稿")[:200],
|
||||
description=(f"从业务文档起草的口径:{len(plan['metrics'])} 个指标,取数 SQL 由模型对照数据目录生成,"
|
||||
f"后台自动只读试运行;人工审改后按受管级别发布"),
|
||||
graph=graph, status="draft", tags=["doc_draft"],
|
||||
origin={"kind": "doc_draft", "draft_id": draft.id, "datasource_id": source.id,
|
||||
"documents": [doc.id for doc in docs], "guidance": guidance})
|
||||
session.add(workflow)
|
||||
await session.flush()
|
||||
session.add(WorkflowVersion(workflow_id=workflow.id, version=1, graph=graph,
|
||||
graph_hash=graph_hash(graph), note="从业务文档一次生成"))
|
||||
payload = {
|
||||
"documents": entries, "metrics": result["metrics"], "dropped": result["dropped"],
|
||||
"open_questions": result["open_questions"],
|
||||
"alignment": docdraft.alignment(result["metrics"], existing),
|
||||
"truncated": result["truncated"], "model_id": result["model_id"],
|
||||
**base, "workflow_id": workflow.id, "open_questions": questions,
|
||||
"alignment": alignment,
|
||||
}
|
||||
except docdraft.DraftUnavailable as e:
|
||||
draft.error = str(e) or "AI 起草不可用"
|
||||
@@ -528,14 +711,31 @@ async def _extract_in_background(draft_id: str) -> None:
|
||||
await session.commit()
|
||||
return
|
||||
draft.payload = payload
|
||||
draft.workflow_id = workflow.id
|
||||
draft.model_id = result["model_id"] or None
|
||||
draft.error = None
|
||||
draft.status = _status_for(payload)
|
||||
await session.commit()
|
||||
values = {field["name"]: field.get("default") for field in plan["entry_fields"]
|
||||
if field.get("default") not in (None, "")}
|
||||
|
||||
try:
|
||||
trial = await _run_trial(draft_id=draft_id, workflow_id=workflow.id, graph=graph, values=values,
|
||||
started_by=draft.created_by)
|
||||
except Exception as e: # noqa: BLE001 - 试运行出错也要写进 payload,不能让界面停在「试运行中」
|
||||
logger.exception("草稿 %s 的试运行出错", draft_id)
|
||||
trial = {"run_id": "", "status": "failed", "error": f"试运行出错:{e}"}
|
||||
await _save_trial(draft_id, trial)
|
||||
|
||||
|
||||
def _problems_text(problems: list[dict[str, Any]]) -> str:
|
||||
"""把校验问题拼成一句给人看的原因(接口的 error 只有一个字段)。"""
|
||||
return ";".join(f"{p.get('name') or '问题'}:{p.get('reason') or ''}".strip(":")
|
||||
for p in problems if p.get("reason"))[:2000]
|
||||
|
||||
|
||||
class DraftExtractIn(BaseModel):
|
||||
"""从哪几份文档起草、起草时给模型看的附加要求。数据源只用来写清适用范围,不给表结构。"""
|
||||
"""从哪几份文档起草、起草时给模型看的附加要求。数据源必须给:它的表结构和目录是 SQL 的唯一依据。"""
|
||||
|
||||
documents: list[str] = Field(min_length=1, max_length=20)
|
||||
collection: str | None = Field(default=None, max_length=100)
|
||||
@@ -546,23 +746,29 @@ class DraftExtractIn(BaseModel):
|
||||
@router.post("/drafts/extract", status_code=201)
|
||||
async def draft_extract(payload: DraftExtractIn, background: BackgroundTasks,
|
||||
session: AsyncSession = Depends(get_session)) -> dict[str, Any]:
|
||||
"""从业务文档起草一份口径(app/ledger/docdraft.py):先建一行 drafting 立刻返回,模型在后台跑。
|
||||
"""从业务文档起草一份口径(app/ledger/draftplan.py):先建一行 drafting 立刻返回,模型在后台跑。
|
||||
|
||||
文档必须都存在(缺的回 422,一个草稿都不建);数据源给了也必须存在。草稿只产出定义,不产出取数,也不写进
|
||||
workflows.graph——path_pending 不是合法的图。抽取完的 payload / status 用 GET 看。"""
|
||||
文档必须都存在(缺的回 422,一个草稿都不建);数据源必须给、必须存在,而且已经探查到表结构——SQL 只能对照真实目录
|
||||
写,没有目录时让模型猜表,图跑不了。模型产出定义 + SQL + 入口字段后由服务端校验收成草稿图和 v1,后台自动只读试跑。
|
||||
起草完的 payload / status / trial 用 GET 看。"""
|
||||
from app.api.deps import current_principal, ensure_role
|
||||
|
||||
ensure_role("builder")
|
||||
doc_ids = list(dict.fromkeys(str(d) for d in payload.documents if str(d).strip()))
|
||||
if not doc_ids:
|
||||
raise HTTPException(422, "至少要给一份文档")
|
||||
if not payload.datasource_id:
|
||||
raise HTTPException(422, "生成取数 SQL 需要数据源:请选一个已经探查过表结构的数据源")
|
||||
found = {doc.id: doc for doc in (await session.execute(
|
||||
select(Document).where(Document.id.in_(doc_ids)))).scalars()}
|
||||
missing = [doc_id for doc_id in doc_ids if doc_id not in found]
|
||||
if missing:
|
||||
raise HTTPException(422, f"文档不存在,可能已被删除:{'、'.join(missing)}")
|
||||
if payload.datasource_id and await session.get(DataSource, payload.datasource_id) is None:
|
||||
source = await session.get(DataSource, payload.datasource_id)
|
||||
if source is None:
|
||||
raise HTTPException(422, "数据源不存在,可能已被删除")
|
||||
if not _source_tables(source):
|
||||
raise HTTPException(422, "这个数据源还没有表结构:先探查表结构,再起草口径")
|
||||
docs = [found[doc_id] for doc_id in doc_ids]
|
||||
draft = CaliberDraft(title=_doc_title(docs),
|
||||
collection=payload.collection or (docs[0].collection or "default"),
|
||||
@@ -576,8 +782,8 @@ async def draft_extract(payload: DraftExtractIn, background: BackgroundTasks,
|
||||
|
||||
|
||||
@router.get("/drafts")
|
||||
async def list_drafts(status: str | None = Query(default=None, description="按状态筛:drafting / questions_open / "
|
||||
"path_pending / attached / rejected / failed"),
|
||||
async def list_drafts(status: str | None = Query(default=None, description="按状态筛:drafting / ready / "
|
||||
"questions_open / path_pending / attached / rejected / failed"),
|
||||
session: AsyncSession = Depends(get_session)) -> dict[str, Any]:
|
||||
"""口径草稿列表,最近改过的在前。只给计数和状态,正文用 GET /api/ledger/drafts/{id} 看。"""
|
||||
from app.api.deps import ensure_role
|
||||
@@ -595,13 +801,38 @@ async def list_drafts(status: str | None = Query(default=None, description="按
|
||||
|
||||
@router.get("/drafts/{draft_id}")
|
||||
async def get_draft(draft_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]:
|
||||
"""一份草稿的完整内容:指标(含引用和 span)、丢弃原因、未决问题、和已发布口径的对齐结果、关联工作流名。"""
|
||||
"""一份草稿的完整内容:指标(含引用和 span)、取数 SQL、入口字段、试跑状态、丢弃原因、未决问题、和已发布口径的对齐
|
||||
结果、关联工作流名。"""
|
||||
from app.api.deps import ensure_role
|
||||
|
||||
ensure_role("builder")
|
||||
return await _draft_view(session, await _draft_or_404(session, draft_id))
|
||||
|
||||
|
||||
@router.get("/drafts/{draft_id}/trial")
|
||||
async def get_draft_trial(draft_id: str, session: AsyncSession = Depends(get_session)) -> dict[str, Any]:
|
||||
"""这份草稿的试跑:{run_id, status, metrics: [{id, name, rendered, value}], error}。
|
||||
|
||||
状态只有 succeeded / failed / running 三种;指标值读试跑运行封存的口径卡(和口径试跑同一个读法)。还没试跑(老草稿、
|
||||
起草失败)回 404。只读,不发起运行。"""
|
||||
from app.api.deps import ensure_role
|
||||
|
||||
ensure_role("builder")
|
||||
draft = await _draft_or_404(session, draft_id)
|
||||
payload = draft.payload if isinstance(draft.payload, dict) else {}
|
||||
trial = payload.get("trial") if isinstance(payload.get("trial"), dict) else {}
|
||||
run_id = trial.get("run_id")
|
||||
if not isinstance(run_id, str) or not run_id:
|
||||
raise HTTPException(404, "这份草稿还没有试运行")
|
||||
run = await session.get(Run, run_id)
|
||||
if run is None:
|
||||
return {"run_id": run_id, "status": _run_status(trial.get("status")), "metrics": [],
|
||||
"error": str(trial.get("error") or "")}
|
||||
status = _run_status(run.status)
|
||||
metrics = await _trial_metrics(run.id) if status == "succeeded" else []
|
||||
return {"run_id": run.id, "status": status, "metrics": metrics, "error": str(run.error or "")}
|
||||
|
||||
|
||||
def _check_metrics(metrics: Any) -> list[dict[str, Any]]:
|
||||
"""PATCH 换指标时只做结构校验(不重跑引用核对:引用是模型交的,人改过的段落没法再逐字对一遍)。"""
|
||||
if not isinstance(metrics, list):
|
||||
@@ -633,8 +864,8 @@ class DraftPatchIn(BaseModel):
|
||||
async def patch_draft(draft_id: str, payload: DraftPatchIn, session: AsyncSession = Depends(get_session)
|
||||
) -> dict[str, Any]:
|
||||
"""改一份草稿:metrics 整体替换(只做结构校验,不重跑引用核对);resolved 里的问题从跨指标和各指标的问题里删掉。
|
||||
据此重算状态(还有问题 → questions_open,否则 path_pending)。已经 attach 或驳回的草稿不改状态——那时它说的
|
||||
已经不是一份草稿了。"""
|
||||
据此重算状态(还有问题 → questions_open,否则有图 → ready、没有图的老草稿 → path_pending)。已经 attach 或驳回的
|
||||
草稿不改状态——那时它说的已经不是一份草稿了。"""
|
||||
from app.api.deps import ensure_role
|
||||
|
||||
ensure_role("builder")
|
||||
@@ -663,7 +894,7 @@ async def patch_draft(draft_id: str, payload: DraftPatchIn, session: AsyncSessio
|
||||
metrics = payload_data.get("metrics")
|
||||
# 起草失败的草稿补上真指标后要能往前走;没有指标时不重算,免得空草稿被当成「待接数据路径」
|
||||
if isinstance(metrics, list) and metrics and draft.status in ("drafting", "questions_open",
|
||||
"path_pending", "failed"):
|
||||
"path_pending", "ready", "failed"):
|
||||
draft.status = _status_for(payload_data)
|
||||
await session.commit()
|
||||
return await _draft_view(session, draft)
|
||||
|
||||
@@ -1094,12 +1094,12 @@ class WebhookDelivery(Base):
|
||||
|
||||
|
||||
class CaliberDraft(Base, TimestampMixin):
|
||||
"""从业务文档起草的一份口径(app/ledger/docdraft.py 的产出)。
|
||||
"""从业务文档起草的一份口径(app/ledger/draftplan.py 的产出)。
|
||||
|
||||
草稿在 path_pending 下没有取数路径,不是合法图(validate_graph 会挡),所以不写进 workflows.graph:另存一行,
|
||||
等 attach(app/ledger/docattach.py)按一次真实运行补上取数路径、人审过再进版本。payload 的形状见
|
||||
docdraft.extract 的返回(documents / metrics / dropped / open_questions / alignment / truncated / model_id),
|
||||
origin 记这一份草稿从哪些文档、用哪句话问出来的,attach 之后工作流 id 记在 workflow_id 上。
|
||||
主路径一次到位:模型读文档和数据目录,产出定义 + 取数 SQL + 入口字段 + 指标表达式;服务端校验收成草稿图,建一个
|
||||
status="draft" 的工作流和 v1,后台自动只读试跑。payload 的形状见接口契约(documents / metrics / entry_fields / sql /
|
||||
workflow_id / version / trial / open_questions / alignment / dropped / truncated / model_id),这张草稿对应的工作流 id
|
||||
记在 workflow_id 上。attach(app/ledger/docattach.py)保留为辅助入口:已经有跑对的答案时让它认这份定义。
|
||||
"""
|
||||
|
||||
__tablename__ = "caliber_drafts"
|
||||
@@ -1107,11 +1107,11 @@ class CaliberDraft(Base, TimestampMixin):
|
||||
id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
|
||||
title: Mapped[str] = mapped_column(String(200), default="")
|
||||
collection: Mapped[str] = mapped_column(String(100), default="default")
|
||||
# 起草时给模型看的数据源(只给名字和类型,用来写清适用范围);源删了草稿照旧在,只丢这一条线索
|
||||
# 起草时给模型看的数据源:表结构和数据目录是取数 SQL 的唯一依据;源删了草稿照旧在,只丢这一条线索
|
||||
datasource_id: Mapped[str | None] = mapped_column(
|
||||
ForeignKey("data_sources.id", ondelete="SET NULL"), default=None
|
||||
)
|
||||
# 同 docdraft.STATUSES:drafting | questions_open | path_pending | attached | rejected
|
||||
# 同 docdraft.STATUSES:drafting | ready | questions_open | path_pending | attached | rejected | failed
|
||||
status: Mapped[str] = mapped_column(String(20), default="drafting", index=True)
|
||||
payload: Mapped[dict[str, Any]] = mapped_column(default=dict)
|
||||
# 这份草稿从哪来:{"documents": [文档 id], "guidance": 用户补充要求}
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
"""业务文档 → 口径草稿:只产出定义,不产出取数(docs/design/next-round/02-口径账本.md 做法 8 的文档一侧)。
|
||||
"""业务文档 → 口径草稿的定义抽取,以及草稿共用的引用核对、对齐和合并(docs/design/next-round/02-口径账本.md 做法 8 的文档一侧)。
|
||||
|
||||
**为什么草稿只到定义为止。** 文档里写的是业务说法(名称、同义词、粒度、时间字段、过滤、分子分母、维度),不是库里的
|
||||
表、列和 SQL。取数必须来自一次真实运行:运行里执行过什么、结果对不对,只有运行本身能证明。所以这个模块的产出固定为
|
||||
定义卡需要的那几项,模型回复里一旦出现 SQL / 表名 / 列名字段,整条指标丢弃,不带着它往下走。
|
||||
**这条抽取路径只产出定义。** 主路径(定义 + 取数 SQL 一次到位)在 ledger/draftplan.py:那边读数据目录、由模型写 SQL、
|
||||
服务端建图并试跑。这里的 extract 仍然只抽定义,留给「已经有跑对的答案,让它认这份定义」的辅助路径(docattach);引用核对、
|
||||
对齐、合并定义这些规则两边共用,所以留在这个模块。
|
||||
|
||||
**为什么草稿不写成图。** path_pending 的草稿还没有取数路径,不是合法图(validate_graph 会挡),写进 workflows.graph
|
||||
只会让工作流列表和画布读到一个跑不了的版本。草稿先独立存在,等取数路径有了、人审过了再进版本。这个模块因此不碰
|
||||
数据库:纯逻辑 + 一次模型调用,调用方拿到结果自己决定存哪里。
|
||||
**为什么这个模块不写成图。** 它只负责把原文里的业务说法抽成定义卡需要的那几项:不碰取数、不碰数据库,纯逻辑加一次模型
|
||||
调用,调用方拿到结果自己决定存哪里。建图(取数 SQL → start / fetch / card / write / out)在 draftplan.build_graph,
|
||||
docattach 接上运行的那一路用的是 certify.build_graph。
|
||||
|
||||
**为什么引用要逐字核对。** 「文档里说过」是这份草稿唯一的事实来源。模型转述得再像,也要能在原文里按归一化空白
|
||||
(换行、制表、全角空格)定位到那一句;定位不到就不算引用。span 是原文下标,界面据此高亮,也是之后复核的依据。
|
||||
@@ -21,9 +21,11 @@ import re
|
||||
from collections.abc import Iterable, Mapping
|
||||
from typing import Any
|
||||
|
||||
#: 草稿的状态。path_pending 不是合法图,attached 之后取数路径才来自一次真实运行。
|
||||
#: failed 是起草这一步没跑成(没有可用模型、模型回复读不懂),和 rejected(人判它不是口径)不是一回事。
|
||||
STATUSES = ("drafting", "questions_open", "path_pending", "attached", "rejected", "failed")
|
||||
#: 草稿的状态。ready 是主路径的常态:图已生成(含取数 SQL)、没有未决问题、可试跑可签字发布;questions_open 有图也有数,
|
||||
#: 只是问题还没清完(不阻断试跑);path_pending 只留给这次改版之前起草、还没有取数路径的老草稿;attached 是经辅助入口接上
|
||||
#: 一次真实运行之后的。failed 是起草这一步没跑成(没有可用模型、模型回复读不懂、SQL 不合格),和 rejected(人判它不是口径)
|
||||
#: 不是一回事。
|
||||
STATUSES = ("drafting", "ready", "questions_open", "path_pending", "attached", "rejected", "failed")
|
||||
|
||||
#: 一次发给模型的总字数上限(按 chunk 边界截断,见 extract)
|
||||
MAX_INPUT_CHARS = 40000
|
||||
|
||||
@@ -0,0 +1,450 @@
|
||||
"""业务文档 + 数据目录 → 一份一次到位的口径草稿:定义、取数 SQL、入口字段、指标表达式(docs/design 做法 8 的主路径)。
|
||||
|
||||
**为什么这次要模型写 SQL。** 文档里只有业务说法,没有表名。但只抽定义,人还得自己去问一次数、再把运行 id 接回来,等于把
|
||||
「口径怎么写」拆成两段,谁都说不清草稿什么时候算数。主路径改成一次产出可试跑的图:模型读文档、对照数据目录写一条只读
|
||||
SELECT,服务端把 SQL、入口字段、口径卡、报告串成图,后台跑一次,草稿页直接给「定义 + 数 + 原文引用」。
|
||||
|
||||
**为什么目录是唯一依据。** 文档里没有表名列名,模型只能从调用方给的目录里挑。所以没有数据源、或数据源还没探查表结构时,
|
||||
调用方必须拒收(api/ledger 的 422):让模型凭空猜表,猜出来的图跑不了,还不如不做。normalize_plan 再核对一遍 SQL 里出现的
|
||||
表都在目录里,防止模型从示例、同义词里编出表名。
|
||||
|
||||
**为什么 SQL 只收单条只读 SELECT。** 草稿会在后台自动跑一次。多语句、DML/DDL、注释后藏的第二条都可能在试跑时改库;
|
||||
这里按 sqlglot 解析后的语句数判定,不靠字符串里有没有分号(字符串字面量里的分号不算)。注释里的第二条照样会被解析成
|
||||
第二条语句,所以也拒。
|
||||
|
||||
**为什么表达式必须是 cell(nodes.fetch, 0, '列名')。** 试跑和之后按口径出具都从口径卡读值。取数节点固定叫 fetch(见
|
||||
build_graph),单行结果取第 0 行的某一列;写成别的样子,卡上就没有值,图能建但出不了数。
|
||||
|
||||
**为什么引用核对还是照 docdraft 的老规矩。** 定义的事实来源还是文档原文。模型转述得再像,也要能在原文里逐字定位;一条
|
||||
引用都核不上的指标整条丢弃,写进 problems 交给人看。这里只做校验,不改 docdraft 的规则。
|
||||
|
||||
**为什么不落库、不导 app.api。** 这个模块是纯逻辑加一次模型调用:从哪读文档、允许哪些表、结果存成什么,都由调用方决定。
|
||||
测试注入假模型,不会发真实请求。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from collections.abc import Mapping
|
||||
from typing import Any
|
||||
|
||||
from app.ledger import docdraft
|
||||
|
||||
#: 一次发给模型的材料上限(按 chunk 边界截断;表目录先截到这个数以内)
|
||||
MAX_INPUT_CHARS = docdraft.MAX_INPUT_CHARS
|
||||
MAX_TABLES_CHARS = 24000
|
||||
#: 取数 SQL 的长度上限(字符)。再长的查询不是草稿该承载的
|
||||
MAX_SQL_CHARS = 20000
|
||||
|
||||
#: 入口字段能写的类型(apps/spec.FORM_TYPES 的子集;日期用 string + description 说清)
|
||||
ENTRY_TYPES = ("string", "number", "integer", "boolean")
|
||||
#: 指标里固定出现的字段(顺序照接口契约)
|
||||
METRIC_FIELDS = ("id", "name", "synonyms", "unit", "decimals", "expression", "definition", "open_questions")
|
||||
|
||||
#: SQL 模板里的入口占位符:{{ input.x }}(引号内外都认)
|
||||
_INPUT = re.compile(r"\{\{\s*input\.([A-Za-z_][\w-]*)\s*\}\}")
|
||||
#: 口径卡的取值表达式,列名可以用单引号或双引号
|
||||
_EXPRESSION = re.compile(r"^cell\(\s*nodes\.fetch\s*,\s*0\s*,\s*['\"]([^'\"]+)['\"]\s*\)$")
|
||||
#: 只读查询的根节点:普通 SELECT,或各分支都是 SELECT 的 UNION
|
||||
_WRITE_NODES = ("Insert", "Update", "Delete", "Create", "Drop", "Alter", "Merge", "TruncateTable", "Command")
|
||||
|
||||
_SYSTEM = """你是业务口径与取数模板的起草助手。读给定的业务文档和数据目录,一次产出一份可试跑的口径。
|
||||
|
||||
硬性约束:
|
||||
1. 只输出一个 JSON 对象,不要写解释,不要写 Markdown 代码块之外的话。
|
||||
2. sql 是取数模板,只能是**一条只读 SELECT**:不要多语句、不要 INSERT/UPDATE/DELETE/DDL,也不要在注释后面再藏一条。
|
||||
表和列只能来自「数据目录」,表名、列名照抄,不许猜、不许编。
|
||||
3. sql 里需要按入口筛选时写 '{{ input.字段名 }}'(字符串)或 {{ input.字段名 }}(数),并在 entry_fields 里声明同名
|
||||
字段;不要把日期、门店之类的字面量写死。
|
||||
4. 每条指标都要有 expression,固定写成 cell(nodes.fetch, 0, '列名'),列名是 sql 最外层 SELECT 的输出列名。
|
||||
5. 每条指标的定义必须带 citations:引用逐字抄原文,chunk 写材料里方括号内的 id。核对不上、或原文里没有依据的定义
|
||||
不要写进指标,写进 open_questions。
|
||||
6. 拿不准的不要猜,写进 open_questions,用一句问得清的话。不要编造文档里没有的数字、单位、生效日期。
|
||||
|
||||
输出格式:
|
||||
{
|
||||
"entry_fields": [
|
||||
{"name": "start", "type": "string", "required": true, "default": "", "description": "开始日期,格式 YYYY-MM-DD"}
|
||||
],
|
||||
"sql": "SELECT SUM(amount) AS gmv FROM orders WHERE paid_at >= '{{ input.start }}'",
|
||||
"metrics": [
|
||||
{
|
||||
"id": "m1",
|
||||
"name": "指标名称",
|
||||
"synonyms": ["同义词"],
|
||||
"unit": "单位(文档没写就留空)",
|
||||
"decimals": 2,
|
||||
"expression": "cell(nodes.fetch, 0, 'gmv')",
|
||||
"definition": {
|
||||
"text": "口径说明",
|
||||
"scope": "适用范围",
|
||||
"exclusions": ["不包含的情况"],
|
||||
"owner": "文档写明的负责人或部门",
|
||||
"effective_from": "生效日期(文档原文写法)",
|
||||
"citations": [{"chunk": "c1", "quote": "逐字原文"}]
|
||||
},
|
||||
"open_questions": ["还没说清、需要业务确认的问题"]
|
||||
}
|
||||
],
|
||||
"open_questions": ["跨指标、以及整条 SQL 还没把握的问题"]
|
||||
}
|
||||
"""
|
||||
|
||||
|
||||
def _collapse(text: str) -> str:
|
||||
return re.sub(r"\s+", " ", text).strip()
|
||||
|
||||
|
||||
def _order(chunks: Mapping[str, dict]) -> list[str]:
|
||||
def key(chunk_id: str) -> tuple[int, str]:
|
||||
chunk = chunks[chunk_id] if isinstance(chunks[chunk_id], Mapping) else {}
|
||||
ordinal = chunk.get("ordinal")
|
||||
return (ordinal if isinstance(ordinal, int) else 0, chunk_id)
|
||||
|
||||
return sorted(chunks, key=key)
|
||||
|
||||
|
||||
def _doc_line(doc: Any) -> str:
|
||||
if not isinstance(doc, Mapping):
|
||||
return str(doc)
|
||||
doc_id = doc.get("document_id") or doc.get("id") or ""
|
||||
title = doc.get("title") or doc.get("filename") or doc.get("name") or doc_id
|
||||
return f"- {doc_id}:{title}"
|
||||
|
||||
|
||||
def _chunk_block(chunk_id: str, chunk: Any) -> str:
|
||||
chunk = chunk if isinstance(chunk, Mapping) else {}
|
||||
ordinal = chunk.get("ordinal")
|
||||
where = f" · 第 {ordinal} 段" if isinstance(ordinal, int) else ""
|
||||
document = chunk.get("document_id") or ""
|
||||
return f"[{chunk_id}](文档 {document}{where})\n{chunk.get('content') or ''}"
|
||||
|
||||
|
||||
def _human(docs: list[dict], chunks: Mapping[str, dict], guidance: str, datasource: dict | None,
|
||||
tables_text: str) -> str:
|
||||
parts = ["文档清单:", *(_doc_line(doc) for doc in docs), "",
|
||||
"逐段原文(引用时 chunk 写方括号里的 id,quote 逐字抄):"]
|
||||
parts.extend(_chunk_block(chunk_id, chunks[chunk_id]) for chunk_id in _order(chunks))
|
||||
parts.append("")
|
||||
if datasource:
|
||||
bits = [str(datasource.get(key)) for key in ("name", "type", "dialect", "description")
|
||||
if datasource.get(key)]
|
||||
parts.append("数据源:{}".format(" · ".join(bits)))
|
||||
parts.append("数据目录(sql 只能用这里的表和列,表名列名照抄):")
|
||||
parts.append(tables_text.strip() or "(没有给出表结构,不能写 sql)")
|
||||
parts.append("")
|
||||
parts.append("用户补充要求:{}".format(guidance.strip() if guidance and guidance.strip() else "(无)"))
|
||||
return "\n".join(parts)
|
||||
|
||||
|
||||
def prompt(docs: list[dict], chunks: dict[str, dict], guidance: str = "", datasource: dict | None = None,
|
||||
tables_text: str = "") -> list[Any]:
|
||||
"""构造 system + human:文档原文 + 数据目录。目录是 sql 的唯一依据,和原文一样原样交给模型。"""
|
||||
from langchain_core.messages import HumanMessage, SystemMessage
|
||||
|
||||
return [SystemMessage(content=_SYSTEM),
|
||||
HumanMessage(content=_human(docs, chunks, guidance, datasource, tables_text))]
|
||||
|
||||
|
||||
def _chars(messages: list[Any]) -> int:
|
||||
return sum(len(str(getattr(message, "content", "") or "")) for message in messages)
|
||||
|
||||
|
||||
def _fit(docs: list[dict], chunks: dict[str, dict], guidance: str,
|
||||
datasource: dict | None, tables_text: str) -> tuple[dict[str, dict], str, bool]:
|
||||
"""把材料压到 MAX_INPUT_CHARS 以内:先截表目录尾部,再从后往前按 chunk 边界丢,最后截仅剩的那一段。
|
||||
|
||||
表目录先截:SQL 必须写在目录里的表上,目录比文档的细枝末节更硬;被截掉的是表详情,表名索引还在最前面。
|
||||
"""
|
||||
kept = dict(chunks)
|
||||
tables = tables_text
|
||||
truncated = False
|
||||
if len(tables) > MAX_TABLES_CHARS:
|
||||
tables = tables[:MAX_TABLES_CHARS]
|
||||
truncated = True
|
||||
|
||||
def size() -> int:
|
||||
return _chars(prompt(docs, kept, guidance, datasource, tables))
|
||||
|
||||
order = _order(kept)
|
||||
while size() > MAX_INPUT_CHARS and len(order) > 1:
|
||||
kept.pop(order.pop())
|
||||
truncated = True
|
||||
if size() > MAX_INPUT_CHARS and order:
|
||||
chunk_id = order[0]
|
||||
chunk = dict(kept[chunk_id]) if isinstance(kept[chunk_id], Mapping) else {}
|
||||
content = str(chunk.get("content") or "")
|
||||
excess = size() - MAX_INPUT_CHARS
|
||||
chunk["content"] = content[:max(0, len(content) - excess)]
|
||||
kept[chunk_id] = chunk
|
||||
truncated = True
|
||||
if size() > MAX_INPUT_CHARS:
|
||||
excess = size() - MAX_INPUT_CHARS
|
||||
tables = tables[:max(0, len(tables) - excess)]
|
||||
truncated = True
|
||||
return kept, tables, truncated
|
||||
|
||||
|
||||
async def plan(session: Any, *, docs: list[dict], chunks: dict[str, dict], guidance: str = "",
|
||||
datasource: dict | None = None, tables_text: str = "", model: Any = None) -> dict:
|
||||
"""一次模型调用,返回 {entry_fields, sql, metrics, open_questions, model_id, truncated}(未校验)。
|
||||
|
||||
不落库。model 可注入(测试用假对象:有 async ainvoke(messages),回复有 .content);不给就按设置解析,模型不可用时抛
|
||||
docdraft.DraftUnavailable。SQL 的对错、引用能不能核对,交给 normalize_plan。
|
||||
"""
|
||||
from app.engine.state import message_text
|
||||
|
||||
if model is None:
|
||||
from app.data.recipe_ai import resolve_draft_model
|
||||
|
||||
model, model_id, availability = await resolve_draft_model(session)
|
||||
if model is None or not getattr(availability, "available", False):
|
||||
raise docdraft.DraftUnavailable(getattr(availability, "reason", "") or "AI 起草不可用")
|
||||
else:
|
||||
named = getattr(model, "model_name", None) or getattr(model, "model", None)
|
||||
model_id = named if isinstance(named, str) else ""
|
||||
|
||||
kept, tables, truncated = _fit(docs, chunks, guidance, datasource, tables_text)
|
||||
reply = await model.ainvoke(prompt(docs, kept, guidance, datasource, tables))
|
||||
data = docdraft.parse_reply(message_text(reply))
|
||||
metrics = data.get("metrics")
|
||||
questions = data.get("open_questions")
|
||||
return {
|
||||
"entry_fields": data.get("entry_fields") if isinstance(data.get("entry_fields"), list) else [],
|
||||
"sql": data.get("sql") if isinstance(data.get("sql"), str) else "",
|
||||
"metrics": metrics if isinstance(metrics, list) else [],
|
||||
"open_questions": [q for q in questions if isinstance(q, str) and q.strip()]
|
||||
if isinstance(questions, list) else [],
|
||||
"model_id": model_id,
|
||||
"truncated": truncated,
|
||||
}
|
||||
|
||||
|
||||
# ==========================================================================
|
||||
# 校验
|
||||
# ==========================================================================
|
||||
|
||||
|
||||
def _entry_fields(value: Any, problems: list[dict]) -> list[dict]:
|
||||
"""入口字段归一化:名字必填、不重名;类型落回能认的几种,认不出的按文字。"""
|
||||
out: list[dict] = []
|
||||
seen: set[str] = set()
|
||||
for position, item in enumerate(value if isinstance(value, list) else [], start=1):
|
||||
if not isinstance(item, Mapping):
|
||||
problems.append({"name": f"第 {position} 个入口字段", "reason": "不是一个对象"})
|
||||
continue
|
||||
name = item.get("name")
|
||||
if not isinstance(name, str) or not name.strip():
|
||||
problems.append({"name": f"第 {position} 个入口字段", "reason": "缺少字段名"})
|
||||
continue
|
||||
name = name.strip()
|
||||
if name in seen:
|
||||
problems.append({"name": name, "reason": "入口字段重名"})
|
||||
continue
|
||||
seen.add(name)
|
||||
kind = item.get("type")
|
||||
if kind not in ENTRY_TYPES:
|
||||
kind = "string"
|
||||
default = item.get("default")
|
||||
if not isinstance(default, (str, int, float, bool)):
|
||||
default = None
|
||||
description = item.get("description")
|
||||
out.append({"name": name, "type": kind, "required": bool(item.get("required")),
|
||||
"default": default,
|
||||
"description": description.strip() if isinstance(description, str) else ""})
|
||||
return out
|
||||
|
||||
|
||||
def _sql_problem(sql: str, allowed_tables: set[str]) -> str | None:
|
||||
"""单条只读 SELECT、表都在目录里;不满足时返回一句给人看的原因。"""
|
||||
if len(sql) > MAX_SQL_CHARS:
|
||||
return f"SQL 超过 {MAX_SQL_CHARS} 字,草稿不承载这么长的查询"
|
||||
body = _INPUT.sub("?", sql)
|
||||
try:
|
||||
import sqlglot
|
||||
from sqlglot import exp
|
||||
except ImportError: # pragma: no cover - sqlglot 是现有依赖,装不上时照实拒
|
||||
return "没有 SQL 解析器,不能校验这条查询"
|
||||
try:
|
||||
statements = [item for item in sqlglot.parse(body) if item is not None]
|
||||
except Exception as e: # noqa: BLE001 - 语法错、方言特性:都按解析不了
|
||||
return f"SQL 解析不了:{e}"
|
||||
if len(statements) != 1:
|
||||
return "只能是一条语句:多语句、或注释后藏着第二条语句的,一律不收"
|
||||
tree = statements[0]
|
||||
if not isinstance(tree, (exp.Select, exp.Union)):
|
||||
return "只能是只读 SELECT"
|
||||
if isinstance(tree, exp.Union) and not all(isinstance(part, exp.Select) for part in tree.find_all(exp.Select)):
|
||||
return "只能是只读 SELECT"
|
||||
if any(tree.find(getattr(exp, name)) is not None for name in _WRITE_NODES):
|
||||
return "只能是只读 SELECT,不能有写操作或建表、删表这类语句"
|
||||
if isinstance(tree, exp.Select) and tree.args.get("into"):
|
||||
return "只能是只读 SELECT,不能把结果写进另一张表"
|
||||
cte_names = {str(cte.alias or "").casefold() for cte in tree.find_all(exp.CTE)}
|
||||
allowed = {str(name).casefold() for name in allowed_tables}
|
||||
used: list[str] = []
|
||||
for table in tree.find_all(exp.Table):
|
||||
name = str(table.name or "")
|
||||
short = name.rsplit(".", 1)[-1]
|
||||
if not name or name.casefold() in cte_names or short.casefold() in cte_names:
|
||||
continue
|
||||
db = str(table.db or "")
|
||||
keys = {name.casefold(), short.casefold()}
|
||||
if db:
|
||||
keys.add(f"{db}.{name}".casefold())
|
||||
if not (keys & allowed):
|
||||
used.append(name)
|
||||
if used:
|
||||
return f"SQL 用了数据目录里没有的表:{'、'.join(dict.fromkeys(used))}"
|
||||
if not any(True for table in tree.find_all(exp.Table)
|
||||
if str(table.name or "").casefold() not in cte_names):
|
||||
return "SQL 没有引用任何表:请对照数据目录写取数"
|
||||
return None
|
||||
|
||||
|
||||
def _metric(item: Mapping, position: int, problems: list[dict]) -> dict | None:
|
||||
"""一条已经过 docdraft 引用核对的指标:再查 expression,归一成契约里的字段。"""
|
||||
name = str(item.get("name") or "").strip()
|
||||
expression = item.get("expression")
|
||||
if not isinstance(expression, str) or not _EXPRESSION.match(expression.strip()):
|
||||
problems.append({"name": name or f"第 {position} 条",
|
||||
"reason": "expression 必须是 cell(nodes.fetch, 0, '列名'),列名用 sql 的输出列名"})
|
||||
return None
|
||||
definition = item.get("definition") if isinstance(item.get("definition"), Mapping) else {}
|
||||
citations = definition.get("citations") if isinstance(definition.get("citations"), list) else []
|
||||
decimals = item.get("decimals")
|
||||
if isinstance(decimals, bool) or not isinstance(decimals, int):
|
||||
decimals = None
|
||||
synonyms = item.get("synonyms")
|
||||
questions = item.get("open_questions")
|
||||
return {
|
||||
"id": str(item.get("id") or "").strip(),
|
||||
"name": name,
|
||||
"synonyms": [s.strip() for s in synonyms if isinstance(s, str) and s.strip()]
|
||||
if isinstance(synonyms, list) else [],
|
||||
"unit": item.get("unit") if isinstance(item.get("unit"), str) else "",
|
||||
"decimals": decimals,
|
||||
"expression": expression.strip(),
|
||||
"definition": {
|
||||
"text": definition.get("text") if isinstance(definition.get("text"), str) else "",
|
||||
"scope": definition.get("scope") if isinstance(definition.get("scope"), str) else "",
|
||||
"exclusions": [str(v) for v in definition.get("exclusions") or [] if isinstance(v, str)]
|
||||
if isinstance(definition.get("exclusions"), list) else [],
|
||||
"owner": definition.get("owner") if isinstance(definition.get("owner"), str) else "",
|
||||
"effective_from": definition.get("effective_from")
|
||||
if isinstance(definition.get("effective_from"), str) else "",
|
||||
"citations": citations,
|
||||
},
|
||||
"open_questions": [q for q in questions if isinstance(q, str) and q.strip()]
|
||||
if isinstance(questions, list) else [],
|
||||
}
|
||||
|
||||
|
||||
def normalize_plan(raw: Any, chunks: Mapping[str, dict], *, allowed_tables: set[str]) -> tuple[dict, list[dict]]:
|
||||
"""校验模型交回的草案。返回 (可落库的 plan, problems)。
|
||||
|
||||
problems 的形状是 {"name": …, "reason": …},name 能认出是哪一条就用名字,认不出按序号说。硬规则:SQL 单条只读、表都在
|
||||
目录里;每条指标的 expression 是 cell(nodes.fetch, 0, '列名');至少一条引用能在原文里逐字核对上(复用
|
||||
docdraft.normalize_metrics 的核对)。个别指标不合格只丢那一条,problems 里写清为什么;SQL 不合格时 plan["sql"] 为空,
|
||||
由调用方决定整份草稿算失败。
|
||||
"""
|
||||
body = raw if isinstance(raw, Mapping) else {}
|
||||
problems: list[dict] = []
|
||||
entry_fields = _entry_fields(body.get("entry_fields"), problems)
|
||||
|
||||
sql = body.get("sql")
|
||||
sql_text = sql.strip() if isinstance(sql, str) else ""
|
||||
if not sql_text:
|
||||
problems.append({"name": "sql", "reason": "没有给出取数 SQL"})
|
||||
else:
|
||||
reason = _sql_problem(sql_text, allowed_tables)
|
||||
if reason:
|
||||
problems.append({"name": "sql", "reason": reason})
|
||||
sql_text = ""
|
||||
else:
|
||||
declared = {field["name"] for field in entry_fields}
|
||||
missing = sorted(set(_INPUT.findall(sql_text)) - declared)
|
||||
if missing:
|
||||
problems.append({"name": "sql",
|
||||
"reason": f"SQL 用了没有声明的入口字段:{'、'.join(missing)}"})
|
||||
sql_text = ""
|
||||
|
||||
checked, dropped = docdraft.normalize_metrics(body.get("metrics"), dict(chunks))
|
||||
problems.extend(dropped)
|
||||
metrics: list[dict] = []
|
||||
seen_ids: set[str] = set()
|
||||
for position, item in enumerate(checked, start=1):
|
||||
metric = _metric(item, position, problems)
|
||||
if metric is None:
|
||||
continue
|
||||
if not metric["id"] or metric["id"] in seen_ids:
|
||||
metric["id"] = f"m{len(metrics) + 1}"
|
||||
while metric["id"] in seen_ids:
|
||||
metric["id"] += "_"
|
||||
seen_ids.add(metric["id"])
|
||||
metrics.append(metric)
|
||||
if not metrics:
|
||||
problems.append({"name": "metrics", "reason": "没有一条指标通过校验"})
|
||||
|
||||
questions = body.get("open_questions")
|
||||
plan_out = {
|
||||
"entry_fields": entry_fields,
|
||||
"sql": sql_text,
|
||||
"metrics": metrics,
|
||||
"open_questions": [q.strip() for q in questions if isinstance(q, str) and q.strip()]
|
||||
if isinstance(questions, list) else [],
|
||||
}
|
||||
return plan_out, problems
|
||||
|
||||
|
||||
# ==========================================================================
|
||||
# 建图(确定性,和 certify.build_graph 同一个形状)
|
||||
# ==========================================================================
|
||||
|
||||
|
||||
def build_graph(plan: dict, *, name: str, question: str = "") -> dict:
|
||||
"""草案 → 草稿图:start(input) → fetch(tool) → card(metrics) → write(report) → out(output),过 auto_layout。
|
||||
|
||||
plan["datasource"] 是取数节点指向的数据源名(调用方按这次的数据源补,不采信模型回复里的名字)。调用两次结果逐字一致:
|
||||
节点 id、坐标都由输入决定,没有时间戳。报告配置、出口契约照 certify.build_graph 的写法,发布门禁认的就是这一套
|
||||
(REPORT_POLICY、metrics_from、required)。
|
||||
"""
|
||||
from app.engine.governance import REPORT_POLICY
|
||||
from app.engine.layout import auto_layout
|
||||
from app.engine.schema import GraphSpec
|
||||
from app.ledger.certify import REPORT_INSTRUCTIONS, REPORT_INSTRUCTIONS_PARAMS
|
||||
from app.tools.datasource import QUERY_PREFIX
|
||||
|
||||
fields = [dict(f) for f in plan.get("entry_fields") or []]
|
||||
metrics = [dict(m) for m in plan.get("metrics") or []]
|
||||
source = str(plan.get("datasource") or "")
|
||||
report_cfg: dict[str, Any] = {}
|
||||
if fields:
|
||||
report_cfg["instructions"] = REPORT_INSTRUCTIONS_PARAMS.format(
|
||||
params=",".join(f"{f['name']} = {{{{ input.{f['name']} }}}}" for f in fields))
|
||||
else:
|
||||
report_cfg["instructions"] = REPORT_INSTRUCTIONS.format(question=question or name or "(问题)")
|
||||
report_cfg.update({key: value for key, value, _ in REPORT_POLICY})
|
||||
report_cfg["metrics_from"] = ["card"]
|
||||
contract: dict[str, Any] = {"report_from": "write", "metrics_from": "card",
|
||||
"required": [m["id"] for m in metrics]}
|
||||
chain = [
|
||||
{"id": "start", "type": "input", "position": {"x": 0, "y": 0},
|
||||
"data": {"label": "入口", "config": {"fields": fields}}},
|
||||
{"id": "fetch", "type": "tool", "position": {"x": 0, "y": 0},
|
||||
"data": {"label": "取数", "config": {"tool": f"{QUERY_PREFIX}{source}",
|
||||
"args": {"sql": str(plan.get("sql") or "")}}}},
|
||||
{"id": "card", "type": "metrics", "position": {"x": 0, "y": 0},
|
||||
"data": {"label": "口径卡", "config": {"caliber": (name.strip() or question or "口径")[:40],
|
||||
"caliber_version": "v1", "metrics": metrics}}},
|
||||
{"id": "write", "type": "report", "position": {"x": 0, "y": 0},
|
||||
"data": {"label": "报告", "config": report_cfg}},
|
||||
{"id": "out", "type": "output", "position": {"x": 0, "y": 0},
|
||||
"data": {"label": "出口", "config": {"fields": [{"name": "报告", "value": "{{ nodes.write.text }}"}],
|
||||
"contract": contract}}},
|
||||
]
|
||||
edges = [{"source": a["id"], "target": b["id"]} for a, b in zip(chain, chain[1:])]
|
||||
return auto_layout(GraphSpec.model_validate({"nodes": chain, "edges": edges})).model_dump(mode="json")
|
||||
|
||||
|
||||
__all__ = ["ENTRY_TYPES", "MAX_INPUT_CHARS", "MAX_SQL_CHARS", "MAX_TABLES_CHARS", "METRIC_FIELDS",
|
||||
"build_graph", "normalize_plan", "plan", "prompt"]
|
||||
@@ -1,47 +1,87 @@
|
||||
"""从业务文档起草口径(app/ledger/docdraft.py,/api/ledger/drafts…):草稿独立于工作流存在。
|
||||
"""从业务文档起草口径(app/ledger/draftplan.py + /api/ledger/drafts…):一次产出定义、SQL、入口和图。
|
||||
|
||||
- 抽取先建一行 drafting、在后台跑模型,结果写回 payload;缺文档 422、一个草稿都不建;
|
||||
- 草稿只产出定义:payload 里是 metrics / dropped / open_questions / alignment,没有 SQL;
|
||||
- PATCH 整体换指标、消掉已答清的问题并重算状态;dismiss 置 rejected 并写审计;列表给计数、按改过的先后排。
|
||||
- 抽取先建一行 drafting、在后台跑模型;结果写成草稿:payload 里有 metrics / sql / entry_fields / trial,工作流和 v1 已建;
|
||||
- 没有数据源、或数据源没有表结构时 422,一个草稿都不建;SQL 对照不上目录时草稿 failed;
|
||||
- 有未决问题 → questions_open(图和试跑照样有),没有 → ready;
|
||||
- PATCH 换指标 / 消问题并重算状态;dismiss 置 rejected 并写审计;列表给计数、按改过的先后排;
|
||||
- GET /drafts/{id}/trial 交回契约里的形状。
|
||||
|
||||
模型一律 monkeypatch 掉(docdraft.extract 换成一个固定结果),测试不发真实请求。
|
||||
模型一律注入假模型(monkeypatch resolve_draft_model),试跑也换成假的(不启动引擎),测试不发真实请求。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import copy
|
||||
import json
|
||||
import sys
|
||||
import types
|
||||
import uuid
|
||||
|
||||
import pytest
|
||||
from httpx import ASGITransport, AsyncClient
|
||||
from sqlalchemy import delete, select
|
||||
|
||||
from app.api import ledger as api_ledger
|
||||
from app.data import recipe_ai
|
||||
from app.db.base import SessionLocal
|
||||
from app.db.models import AuditEvent, CaliberDraft, Chunk, Document, Workflow
|
||||
from app.ledger import docdraft
|
||||
from app.db.models import (AuditEvent, CaliberDraft, Chunk, DataSource, Document, Run, Workflow,
|
||||
WorkflowVersion)
|
||||
from app.engine.schema import GraphSpec, validate_graph
|
||||
from app.main import app
|
||||
|
||||
METRIC = {
|
||||
"name": "已支付退款率",
|
||||
"synonyms": ["退款率"],
|
||||
"unit": "%",
|
||||
"grain": "日",
|
||||
"time_field": "支付时间",
|
||||
"filters": ["只算已支付"],
|
||||
"numerator": "已支付后退款的订单数",
|
||||
"denominator": "已支付订单数",
|
||||
"dimensions": ["门店"],
|
||||
"definition": {"text": "已支付订单里发生退款的比例", "scope": "全部门店", "exclusions": [], "owner": "运营",
|
||||
"effective_from": "2026-01-01",
|
||||
"citations": [{"chunk": "c1", "document_id": "d1", "span": [0, 2], "quote": "退款率"}]},
|
||||
"open_questions": ["退款算不算已支付当天的"],
|
||||
}
|
||||
#: 真实的试跑实现:autouse 的 fake_trial 会把它换掉,这一个用例换回来跑真引擎
|
||||
REAL_RUN_TRIAL = api_ledger._run_trial
|
||||
|
||||
#: 文档原文:两段,退款率的事实来源
|
||||
CHUNK_ONE = "退款率 = 已支付后退款的订单数 / 已支付订单数"
|
||||
CHUNK_TWO = "退款率按门店拆,只算已支付的订单"
|
||||
|
||||
|
||||
def result(metrics=None, questions=None, model_id="fake-model"):
|
||||
return {"metrics": copy.deepcopy(metrics if metrics is not None else [METRIC]),
|
||||
"dropped": [{"name": "第 2 条", "reason": "没有一条引用能在原文里逐字核对上"}],
|
||||
"open_questions": list(questions or []), "truncated": False, "model_id": model_id}
|
||||
def plan_reply(chunk_id: str, *, questions=None, sql: str | None = None, metrics=None) -> str:
|
||||
"""模型回复:一条指标,引用逐字抄原文。"""
|
||||
metric = {
|
||||
"id": "m1", "name": "已支付退款率", "synonyms": ["退款率"], "unit": "%", "decimals": 2,
|
||||
"expression": "cell(nodes.fetch, 0, 'refund_rate')",
|
||||
"definition": {"text": "已支付订单里发生退款的比例", "scope": "全部门店", "exclusions": [],
|
||||
"owner": "运营", "effective_from": "2026-01-01",
|
||||
"citations": [{"chunk": chunk_id, "quote": "只算已支付的订单"}]},
|
||||
"open_questions": [],
|
||||
}
|
||||
return json.dumps({
|
||||
"entry_fields": [{"name": "store", "type": "string", "required": False, "default": "",
|
||||
"description": "门店(留空是全部门店)"}],
|
||||
"sql": sql or "SELECT COUNT(*) * 1.0 AS refund_rate FROM orders WHERE status = 'paid' "
|
||||
"AND store = '{{ input.store }}'",
|
||||
"metrics": metrics if metrics is not None else [metric],
|
||||
"open_questions": list(questions or []),
|
||||
}, ensure_ascii=False)
|
||||
|
||||
|
||||
class FakeModel:
|
||||
"""起草模型:ainvoke 返回带 .content 的对象;按顺序交回复,交完重复最后一份。"""
|
||||
|
||||
model_name = "fake-model"
|
||||
|
||||
def __init__(self, replies: list[str]) -> None:
|
||||
self.replies = list(replies)
|
||||
self.calls: list[list] = []
|
||||
|
||||
async def ainvoke(self, messages):
|
||||
self.calls.append(list(messages))
|
||||
from types import SimpleNamespace
|
||||
|
||||
return SimpleNamespace(content=self.replies.pop(0) if len(self.replies) > 1 else self.replies[0])
|
||||
|
||||
|
||||
def fake_model(monkeypatch, *replies: str) -> FakeModel:
|
||||
model = FakeModel(list(replies))
|
||||
|
||||
async def resolve(_session):
|
||||
from types import SimpleNamespace
|
||||
|
||||
return model, model.model_name, SimpleNamespace(available=True, reason="")
|
||||
|
||||
monkeypatch.setattr(recipe_ai, "resolve_draft_model", resolve)
|
||||
return model
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
@@ -50,114 +90,230 @@ async def client():
|
||||
yield c
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
async def documents():
|
||||
"""建文档和段落(ordinal 故意倒着插,确认读出来按 ordinal 排)。段落 id 带上文档 id,测试之间不撞。
|
||||
测试结束删掉这几份文档、它们的段落和所有草稿。"""
|
||||
@pytest.fixture(autouse=True)
|
||||
async def fake_trial(monkeypatch):
|
||||
"""试跑换成写一行 succeeded 的运行:不启动引擎、不查库,接口和 payload 的形状照真的一样。"""
|
||||
made: list[str] = []
|
||||
|
||||
async def make(doc_id: str, *, title: str = "销售口径.md", collection: str = "default",
|
||||
chunks=((2, "退款率 = 已支付后退款的订单数 / 已支付订单数"), (1, "退款率按门店拆"))) -> str:
|
||||
async def start(*, draft_id, workflow_id, graph, values, started_by):
|
||||
run_id = f"run-draft-{uuid.uuid4().hex[:10]}"
|
||||
async with SessionLocal() as session:
|
||||
session.add(Run(id=run_id, workflow_id=workflow_id, status="succeeded", graph=graph,
|
||||
input=values, run_class="exploratory", origin_kind="caliber_trial",
|
||||
origin={"kind": "caliber_trial", "draft_id": draft_id,
|
||||
"workflow_id": workflow_id, "version": 1}))
|
||||
await session.commit()
|
||||
made.append(run_id)
|
||||
return {"run_id": run_id, "status": "succeeded", "error": ""}
|
||||
|
||||
monkeypatch.setattr(api_ledger, "_run_trial", start)
|
||||
yield made
|
||||
async with SessionLocal() as session:
|
||||
for run_id in made:
|
||||
row = await session.get(Run, run_id)
|
||||
if row is not None:
|
||||
await session.delete(row)
|
||||
await session.commit()
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
async def documents():
|
||||
"""建文档和段落(ordinal 故意倒着插,确认读出来按 ordinal 排)。测试结束删文档、段落、草稿和草稿建出的工作流。"""
|
||||
made: list[str] = []
|
||||
|
||||
async def make(doc_id: str, *, title: str = "销售口径.md", collection: str = "default") -> str:
|
||||
chunks = ((2, CHUNK_TWO), (1, CHUNK_ONE))
|
||||
async with SessionLocal() as session:
|
||||
session.add(Document(id=doc_id, collection=collection, title=title, source=title,
|
||||
content="".join(content for _, content in chunks), chunk_count=len(chunks)))
|
||||
for ordinal, content in chunks:
|
||||
session.add(Chunk(id=f"{doc_id}-{ordinal}", document_id=doc_id, ordinal=ordinal, content=content))
|
||||
session.add(Chunk(id=f"{doc_id}-{ordinal}", document_id=doc_id, ordinal=ordinal,
|
||||
content=content))
|
||||
await session.commit()
|
||||
made.append(doc_id)
|
||||
return doc_id
|
||||
|
||||
yield make
|
||||
async with SessionLocal() as session:
|
||||
drafts = (await session.execute(select(CaliberDraft))).scalars().all()
|
||||
workflow_ids = [draft.workflow_id for draft in drafts if draft.workflow_id]
|
||||
# attach 会把 workflow_id 换成接上的那一份;起草时建的那份仍在 payload 里,照样要清掉
|
||||
workflow_ids += [draft.payload.get("workflow_id") for draft in drafts
|
||||
if isinstance(draft.payload, dict) and draft.payload.get("workflow_id")]
|
||||
workflow_ids = list(dict.fromkeys(workflow_ids))
|
||||
for draft in drafts:
|
||||
await session.delete(draft)
|
||||
if workflow_ids:
|
||||
await session.execute(delete(WorkflowVersion).where(WorkflowVersion.workflow_id.in_(workflow_ids)))
|
||||
await session.execute(delete(Workflow).where(Workflow.id.in_(workflow_ids)))
|
||||
for doc_id in made:
|
||||
await session.execute(delete(Chunk).where(Chunk.document_id == doc_id))
|
||||
doc = await session.get(Document, doc_id)
|
||||
if doc is not None:
|
||||
await session.delete(doc)
|
||||
for draft in (await session.execute(select(CaliberDraft))).scalars():
|
||||
await session.delete(draft)
|
||||
await session.commit()
|
||||
|
||||
|
||||
def fake_extract(monkeypatch, *results: dict, seen: dict | None = None) -> None:
|
||||
"""把 docdraft.extract 换成固定结果:每次调用按顺序交一份,交完了重复最后一份。"""
|
||||
queue = list(results)
|
||||
@pytest.fixture
|
||||
async def datasource():
|
||||
"""一个有表结构的数据源:SQL 只能照这里的表写。"""
|
||||
source_id = f"ds-{uuid.uuid4().hex[:10]}"
|
||||
|
||||
async def extract(session, *, docs, chunks, guidance="", datasource=None, model=None):
|
||||
if seen is not None:
|
||||
seen.update(docs=docs, chunks=chunks, guidance=guidance, datasource=datasource)
|
||||
return copy.deepcopy(queue.pop(0) if len(queue) > 1 else queue[0])
|
||||
async def make(*, tables: bool = True) -> str:
|
||||
cache = {"tables": {"orders": {"columns": [
|
||||
{"name": "status", "type": "TEXT"}, {"name": "store", "type": "TEXT"},
|
||||
{"name": "amount", "type": "NUMERIC"}, {"name": "paid_at", "type": "TEXT"}]}}, "total": 1} \
|
||||
if tables else {}
|
||||
async with SessionLocal() as session:
|
||||
session.add(DataSource(id=source_id, name=f"shop_{uuid.uuid4().hex[:8]}", kind="sqlite",
|
||||
description="销售库", schema_cache=cache))
|
||||
await session.commit()
|
||||
return source_id
|
||||
|
||||
monkeypatch.setattr(docdraft, "extract", extract)
|
||||
yield make
|
||||
async with SessionLocal() as session:
|
||||
row = await session.get(DataSource, source_id)
|
||||
if row is not None:
|
||||
await session.delete(row)
|
||||
await session.commit()
|
||||
|
||||
|
||||
async def test_extract_reads_documents_in_order_and_stores_a_questions_open_draft(client, documents, monkeypatch):
|
||||
doc = await documents("d-draft-1")
|
||||
seen: dict = {}
|
||||
fake_extract(monkeypatch, result(questions=["按哪个时区结算"]), seen=seen)
|
||||
async def extract(client, doc: str, source_id: str, **extra) -> dict:
|
||||
body = (await client.post("/api/ledger/drafts/extract",
|
||||
json={"documents": [doc], "datasource_id": source_id, **extra})).json()
|
||||
return body
|
||||
|
||||
res = await client.post("/api/ledger/drafts/extract",
|
||||
json={"documents": [doc], "guidance": "只看已支付的订单"})
|
||||
assert res.status_code == 201, res.text
|
||||
body = res.json()
|
||||
assert set(body) == {"draft_id", "status"}
|
||||
# 抽取在后台跑:建行那一刻回 drafting,结果用 GET 看
|
||||
|
||||
# ==========================================================================
|
||||
# 主路径
|
||||
# ==========================================================================
|
||||
|
||||
async def test_extract_produces_a_ready_draft_with_a_graph_and_a_trial(client, documents, datasource, monkeypatch):
|
||||
doc = await documents("dd-1")
|
||||
source_id = await datasource()
|
||||
fake_model(monkeypatch, plan_reply(f"{doc}-2"))
|
||||
|
||||
body = await extract(client, doc, source_id)
|
||||
assert body["status"] == "drafting"
|
||||
|
||||
# 交给模型的是按 ordinal 排好的段落,标题和 guidance 也传下去了
|
||||
first, second = f"{doc}-1", f"{doc}-2"
|
||||
assert seen["docs"] == [{"document_id": doc, "title": "销售口径.md", "chunk_ids": [first, second]}]
|
||||
assert [seen["chunks"][c]["ordinal"] for c in (first, second)] == [1, 2]
|
||||
assert seen["chunks"][first]["document_id"] == doc
|
||||
assert seen["guidance"] == "只看已支付的订单" and seen["datasource"] is None
|
||||
|
||||
made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json()
|
||||
assert made["status"] == "questions_open" and made["title"] == "销售口径.md"
|
||||
assert made["workflow_id"] is None and made["workflow_name"] is None
|
||||
assert made["model_id"] == "fake-model"
|
||||
assert made["status"] == "ready"
|
||||
assert made["title"] == "销售口径.md"
|
||||
assert made["workflow_id"] and made["workflow_name"] == "销售口径.md"
|
||||
assert made["metric_count"] == 1 and made["question_count"] == 0
|
||||
assert [m["name"] for m in made["metrics"]] == ["已支付退款率"]
|
||||
assert made["metrics"][0]["definition"]["citations"][0]["span"] == [0, 2]
|
||||
assert made["open_questions"] == ["按哪个时区结算"]
|
||||
assert made["dropped"] == [{"name": "第 2 条", "reason": "没有一条引用能在原文里逐字核对上"}]
|
||||
assert set(made["alignment"]) == {"new", "duplicate", "conflict"}
|
||||
assert made["metrics"][0]["expression"] == "cell(nodes.fetch, 0, 'refund_rate')"
|
||||
assert made["metrics"][0]["definition"]["citations"][0]["span"] == [8, 16]
|
||||
assert made["sql"].startswith("SELECT COUNT(*)") and "{{ input.store }}" in made["sql"]
|
||||
assert [f["name"] for f in made["entry_fields"]] == ["store"]
|
||||
assert made["trial"]["run_id"] and made["trial"]["status"] == "succeeded"
|
||||
assert [d["document_id"] for d in made["documents"]] == [doc]
|
||||
assert made["documents"][0]["chunk_ids"] == [f"{doc}-1", f"{doc}-2"]
|
||||
assert made["alignment"]["new"] == ["已支付退款率"]
|
||||
assert made["truncated"] is False
|
||||
assert made["origin"] == {"documents": [doc], "guidance": "只看已支付的订单"}
|
||||
# 草稿不写进工作流:库里没有从它建出的图
|
||||
assert made["truncated"] is False and made["model_id"] == "fake-model"
|
||||
assert made["datasource_id"] == source_id
|
||||
|
||||
# 工作流和 v1 已建:合法的草稿图,取数指向这个数据源
|
||||
async with SessionLocal() as session:
|
||||
row = await session.get(CaliberDraft, body["draft_id"])
|
||||
assert row.workflow_id is None and row.payload["metrics"][0]["name"] == "已支付退款率"
|
||||
workflow = await session.get(Workflow, row.workflow_id)
|
||||
version = (await session.execute(select(WorkflowVersion).where(
|
||||
WorkflowVersion.workflow_id == row.workflow_id))).scalars().one()
|
||||
assert workflow.status == "draft" and workflow.tags == ["doc_draft"]
|
||||
assert version.version == 1 and version.graph == workflow.graph
|
||||
assert [n["id"] for n in workflow.graph["nodes"]] == ["start", "fetch", "card", "write", "out"]
|
||||
assert validate_graph(GraphSpec.model_validate(workflow.graph)).ok
|
||||
|
||||
# 试跑只读接口:契约里的形状
|
||||
trial = (await client.get(f"/api/ledger/drafts/{body['draft_id']}/trial")).json()
|
||||
assert set(trial) == {"run_id", "status", "metrics", "error"}
|
||||
assert trial["run_id"] == made["trial"]["run_id"] and trial["status"] == "succeeded"
|
||||
|
||||
|
||||
async def test_extract_without_open_questions_is_path_pending(client, documents, monkeypatch):
|
||||
doc = await documents("d-draft-2")
|
||||
fake_extract(monkeypatch, result(metrics=[{**METRIC, "open_questions": []}]))
|
||||
body = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()
|
||||
assert body["status"] == "drafting"
|
||||
async def test_open_questions_keep_the_draft_in_questions_open_but_still_run_it(
|
||||
client, documents, datasource, monkeypatch):
|
||||
doc = await documents("dd-2")
|
||||
source_id = await datasource()
|
||||
fake_model(monkeypatch, plan_reply(f"{doc}-2", questions=["退款算在哪一天"]))
|
||||
|
||||
body = await extract(client, doc, source_id)
|
||||
made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json()
|
||||
assert made["status"] == "path_pending"
|
||||
assert made["open_questions"] == [] and made["question_count"] == 0
|
||||
assert made["status"] == "questions_open"
|
||||
assert made["open_questions"] == ["退款算在哪一天"]
|
||||
assert made["workflow_id"] and made["sql"]
|
||||
assert made["trial"]["status"] == "succeeded"
|
||||
|
||||
|
||||
async def test_a_missing_document_is_refused_and_no_draft_is_created(client):
|
||||
res = await client.post("/api/ledger/drafts/extract", json={"documents": ["d-nope"]})
|
||||
async def test_a_missing_or_empty_datasource_is_refused_and_no_draft_is_created(client, documents, datasource):
|
||||
doc = await documents("dd-3")
|
||||
without = await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})
|
||||
assert without.status_code == 422 and "数据源" in without.text
|
||||
unknown = await client.post("/api/ledger/drafts/extract",
|
||||
json={"documents": [doc], "datasource_id": "ds-nope"})
|
||||
assert unknown.status_code == 422 and "数据源不存在" in unknown.text
|
||||
empty_source = await datasource(tables=False)
|
||||
empty = await client.post("/api/ledger/drafts/extract",
|
||||
json={"documents": [doc], "datasource_id": empty_source})
|
||||
assert empty.status_code == 422 and "表结构" in empty.text
|
||||
assert (await client.get("/api/ledger/drafts")).json()["drafts"] == []
|
||||
|
||||
|
||||
async def test_a_missing_document_is_refused_and_no_draft_is_created(client, datasource):
|
||||
source_id = await datasource()
|
||||
res = await client.post("/api/ledger/drafts/extract",
|
||||
json={"documents": ["d-nope"], "datasource_id": source_id})
|
||||
assert res.status_code == 422 and "d-nope" in res.text
|
||||
listed = (await client.get("/api/ledger/drafts")).json()
|
||||
assert listed["drafts"] == []
|
||||
assert (await client.get("/api/ledger/drafts")).json()["drafts"] == []
|
||||
|
||||
|
||||
async def test_patch_replaces_metrics_and_clears_resolved_questions(client, documents, monkeypatch):
|
||||
doc = await documents("d-draft-3")
|
||||
fake_extract(monkeypatch, result(questions=["按哪个时区结算"]))
|
||||
draft_id = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()["draft_id"]
|
||||
async def test_sql_outside_the_catalog_fails_the_draft_with_a_reason(client, documents, datasource, monkeypatch):
|
||||
doc = await documents("dd-4")
|
||||
source_id = await datasource()
|
||||
fake_model(monkeypatch, plan_reply(f"{doc}-2", sql="SELECT * FROM secrets"))
|
||||
|
||||
fixed_metric = {**copy.deepcopy(METRIC), "open_questions": [], "name": "已支付退款率(按支付日)"}
|
||||
body = await extract(client, doc, source_id)
|
||||
made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json()
|
||||
assert made["status"] == "failed" and made["workflow_id"] is None
|
||||
assert "secrets" in made["error"] and "数据目录" in made["error"]
|
||||
assert any("secrets" in d["reason"] for d in made["dropped"])
|
||||
assert not made.get("sql")
|
||||
assert (await client.get(f"/api/ledger/drafts/{body['draft_id']}/trial")).status_code == 404
|
||||
|
||||
|
||||
async def test_a_metric_with_a_bad_expression_is_dropped_but_the_draft_still_goes_on(
|
||||
client, documents, datasource, monkeypatch):
|
||||
doc = await documents("dd-5")
|
||||
source_id = await datasource()
|
||||
reply = json.loads(plan_reply(f"{doc}-2"))
|
||||
reply["metrics"].append({**reply["metrics"][0], "id": "m2", "name": "订单数", "expression": "SUM(amount)"})
|
||||
fake_model(monkeypatch, json.dumps(reply, ensure_ascii=False))
|
||||
|
||||
body = await extract(client, doc, source_id)
|
||||
made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json()
|
||||
# 一条好、一条坏:坏的那条进 dropped / open_questions,草稿照样 ready 之外还有图
|
||||
assert [m["id"] for m in made["metrics"]] == ["m1"]
|
||||
assert any(d["name"] == "订单数" and "cell(nodes.fetch, 0" in d["reason"] for d in made["dropped"])
|
||||
assert any("订单数" in q for q in made["open_questions"])
|
||||
assert made["status"] == "questions_open" and made["workflow_id"]
|
||||
|
||||
|
||||
# ==========================================================================
|
||||
# 改、驳回、列表、试跑接口
|
||||
# ==========================================================================
|
||||
|
||||
async def test_patch_replaces_metrics_and_clears_resolved_questions(client, documents, datasource, monkeypatch):
|
||||
doc = await documents("dd-6")
|
||||
source_id = await datasource()
|
||||
fake_model(monkeypatch, plan_reply(f"{doc}-2", questions=["按哪个时区结算"]))
|
||||
draft_id = (await extract(client, doc, source_id))["draft_id"]
|
||||
|
||||
fixed = {**copy.deepcopy(json.loads(plan_reply(f"{doc}-2"))["metrics"][0]), "name": "已支付退款率(按支付日)"}
|
||||
res = await client.patch(f"/api/ledger/drafts/{draft_id}",
|
||||
json={"title": "退款率口径", "metrics": [fixed_metric],
|
||||
"resolved": ["按哪个时区结算", "退款算不算已支付当天的"]})
|
||||
json={"title": "退款率口径", "metrics": [fixed],
|
||||
"resolved": ["按哪个时区结算"]})
|
||||
assert res.status_code == 200, res.text
|
||||
made = res.json()
|
||||
assert made["title"] == "退款率口径" and made["status"] == "path_pending"
|
||||
assert made["title"] == "退款率口径" and made["status"] == "ready"
|
||||
assert [m["name"] for m in made["metrics"]] == ["已支付退款率(按支付日)"]
|
||||
assert made["open_questions"] == [] and made["question_count"] == 0
|
||||
|
||||
@@ -169,14 +325,15 @@ async def test_patch_replaces_metrics_and_clears_resolved_questions(client, docu
|
||||
|
||||
# 还有问题(只换指标、带着新问题)→ questions_open
|
||||
res = await client.patch(f"/api/ledger/drafts/{draft_id}",
|
||||
json={"metrics": [{**fixed_metric, "open_questions": ["按哪个门店口径"]}]})
|
||||
json={"metrics": [{**fixed, "open_questions": ["按哪个门店口径"]}]})
|
||||
assert res.json()["status"] == "questions_open" and res.json()["question_count"] == 1
|
||||
|
||||
|
||||
async def test_dismiss_marks_rejected_and_writes_an_audit(client, documents, monkeypatch):
|
||||
doc = await documents("d-draft-4")
|
||||
fake_extract(monkeypatch, result())
|
||||
draft_id = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()["draft_id"]
|
||||
async def test_dismiss_marks_rejected_and_writes_an_audit(client, documents, datasource, monkeypatch):
|
||||
doc = await documents("dd-7")
|
||||
source_id = await datasource()
|
||||
fake_model(monkeypatch, plan_reply(f"{doc}-2"))
|
||||
draft_id = (await extract(client, doc, source_id))["draft_id"]
|
||||
|
||||
res = await client.post(f"/api/ledger/drafts/{draft_id}/dismiss", json={"note": "已经有口径了"})
|
||||
assert res.status_code == 200 and res.json()["status"] == "rejected"
|
||||
@@ -187,23 +344,23 @@ async def test_dismiss_marks_rejected_and_writes_an_audit(client, documents, mon
|
||||
assert (await client.get(f"/api/ledger/drafts/{draft_id}")).json()["status"] == "rejected"
|
||||
|
||||
|
||||
async def test_list_counts_orders_by_last_change_and_filters_by_status(client, documents, monkeypatch):
|
||||
first = await documents("d-draft-5", title="一.md")
|
||||
second = await documents("d-draft-6", title="二.md")
|
||||
fake_extract(monkeypatch,
|
||||
result(metrics=[METRIC, {**METRIC, "name": "退款金额", "open_questions": []}],
|
||||
questions=["按哪个时区结算"]),
|
||||
result(metrics=[{**METRIC, "open_questions": []}]))
|
||||
one = (await client.post("/api/ledger/drafts/extract", json={"documents": [first]})).json()["draft_id"]
|
||||
two = (await client.post("/api/ledger/drafts/extract", json={"documents": [second]})).json()["draft_id"]
|
||||
async def test_list_counts_orders_by_last_change_and_filters_by_status(client, documents, datasource, monkeypatch):
|
||||
first = await documents("dd-8", title="一.md")
|
||||
second = await documents("dd-9", title="二.md")
|
||||
source_id = await datasource()
|
||||
fake_model(monkeypatch,
|
||||
plan_reply(f"{first}-2", questions=["按哪个时区结算"]),
|
||||
plan_reply(f"{second}-2"))
|
||||
one = (await extract(client, first, source_id))["draft_id"]
|
||||
two = (await extract(client, second, source_id))["draft_id"]
|
||||
|
||||
listed = (await client.get("/api/ledger/drafts")).json()["drafts"]
|
||||
assert [d["id"] for d in listed] == [two, one]
|
||||
latest, earlier = listed
|
||||
assert (latest["title"], latest["status"], latest["metric_count"], latest["question_count"]) == \
|
||||
("二.md", "path_pending", 1, 0)
|
||||
assert (earlier["status"], earlier["metric_count"], earlier["question_count"]) == ("questions_open", 2, 2)
|
||||
assert earlier["workflow_id"] is None and earlier["created_at"] and earlier["error"] is None
|
||||
("二.md", "ready", 1, 0)
|
||||
assert (earlier["status"], earlier["metric_count"], earlier["question_count"]) == ("questions_open", 1, 1)
|
||||
assert earlier["workflow_id"] and earlier["created_at"] and earlier["error"] is None
|
||||
|
||||
only = (await client.get("/api/ledger/drafts", params={"status": "questions_open"})).json()["drafts"]
|
||||
assert [d["id"] for d in only] == [one]
|
||||
@@ -211,24 +368,57 @@ async def test_list_counts_orders_by_last_change_and_filters_by_status(client, d
|
||||
assert (await client.get("/api/ledger/drafts/d-nope")).status_code == 404
|
||||
|
||||
|
||||
async def test_a_model_that_is_unavailable_leaves_the_draft_with_an_error(client, documents, monkeypatch):
|
||||
doc = await documents("d-draft-7")
|
||||
async def test_trial_endpoint_returns_metric_values_from_the_run(client, documents, datasource, monkeypatch):
|
||||
doc = await documents("dd-10")
|
||||
source_id = await datasource()
|
||||
fake_model(monkeypatch, plan_reply(f"{doc}-2"))
|
||||
draft_id = (await extract(client, doc, source_id))["draft_id"]
|
||||
|
||||
async def unavailable(session, **kwargs):
|
||||
raise docdraft.DraftUnavailable("还没有接入可用的起草模型")
|
||||
async def metrics(_run_id):
|
||||
return [{"id": "m1", "name": "已支付退款率", "rendered": "3.2%", "value": 0.032}]
|
||||
|
||||
monkeypatch.setattr(docdraft, "extract", unavailable)
|
||||
body = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()
|
||||
monkeypatch.setattr(api_ledger, "_trial_metrics", metrics)
|
||||
res = await client.get(f"/api/ledger/drafts/{draft_id}/trial")
|
||||
assert res.status_code == 200, res.text
|
||||
body = res.json()
|
||||
assert body == {"run_id": body["run_id"], "status": "succeeded",
|
||||
"metrics": [{"id": "m1", "name": "已支付退款率", "rendered": "3.2%", "value": 0.032}],
|
||||
"error": ""}
|
||||
|
||||
# 没有试跑的老草稿
|
||||
async with SessionLocal() as session:
|
||||
session.add(CaliberDraft(id=f"draft-old-{uuid.uuid4().hex[:8]}", title="老草稿", status="path_pending",
|
||||
payload={"metrics": []}))
|
||||
await session.commit()
|
||||
old = (await session.execute(select(CaliberDraft.id).where(
|
||||
CaliberDraft.status == "path_pending"))).scalars().first()
|
||||
assert (await client.get(f"/api/ledger/drafts/{old}/trial")).status_code == 404
|
||||
|
||||
|
||||
async def test_a_model_that_is_unavailable_leaves_the_draft_with_an_error(client, documents, datasource,
|
||||
monkeypatch):
|
||||
doc = await documents("dd-11")
|
||||
source_id = await datasource()
|
||||
|
||||
async def unavailable(_session):
|
||||
from types import SimpleNamespace
|
||||
|
||||
return None, "", SimpleNamespace(available=False, reason="还没有接入可用的起草模型")
|
||||
|
||||
monkeypatch.setattr(recipe_ai, "resolve_draft_model", unavailable)
|
||||
body = await extract(client, doc, source_id)
|
||||
made = (await client.get(f"/api/ledger/drafts/{body['draft_id']}")).json()
|
||||
assert made["status"] == "failed" and made["error"] == "还没有接入可用的起草模型"
|
||||
assert made["metric_count"] == 0 and not made.get("metrics")
|
||||
|
||||
|
||||
async def test_attach_hands_the_draft_to_docattach_and_records_the_workflow(client, documents, monkeypatch):
|
||||
"""attach 只按约定调 app.ledger.docattach.attach(另一路实现):这里换成一个假的模块,看接线和写回。"""
|
||||
doc = await documents("d-draft-8")
|
||||
fake_extract(monkeypatch, result(metrics=[{**METRIC, "open_questions": []}]))
|
||||
draft_id = (await client.post("/api/ledger/drafts/extract", json={"documents": [doc]})).json()["draft_id"]
|
||||
async def test_attach_hands_the_draft_to_docattach_and_records_the_workflow(client, documents, datasource,
|
||||
monkeypatch):
|
||||
"""attach 只按约定调 app.ledger.docattach.attach(辅助入口):这里换成一个假的模块,看接线和写回。"""
|
||||
doc = await documents("dd-12")
|
||||
source_id = await datasource()
|
||||
fake_model(monkeypatch, plan_reply(f"{doc}-2"))
|
||||
draft_id = (await extract(client, doc, source_id))["draft_id"]
|
||||
|
||||
seen: dict = {}
|
||||
|
||||
@@ -257,3 +447,63 @@ async def test_attach_hands_the_draft_to_docattach_and_records_the_workflow(clie
|
||||
if workflow is not None:
|
||||
await session.delete(workflow)
|
||||
await session.commit()
|
||||
|
||||
|
||||
async def test_a_real_trial_run_feeds_the_trial_endpoint(client, documents, tmp_path, monkeypatch):
|
||||
"""真引擎跑一次草稿图:数从取数节点进口径卡,GET /trial 交回指标值(不 mock 试跑)。"""
|
||||
from app.engine.runner import run_manager
|
||||
from tests import ledger_samples as S
|
||||
|
||||
await run_manager.setup()
|
||||
run_id = None
|
||||
try:
|
||||
name = await S.fresh_source(tmp_path / "shop.db")
|
||||
async with SessionLocal() as session:
|
||||
row = (await session.execute(select(DataSource).where(DataSource.name == name))).scalar_one()
|
||||
row.schema_cache = {"tables": {"orders": {"columns": [
|
||||
{"name": "status", "type": "TEXT"}, {"name": "region", "type": "TEXT"},
|
||||
{"name": "amount", "type": "REAL"}, {"name": "paid_at", "type": "TEXT"}]}}, "total": 1}
|
||||
await session.commit()
|
||||
source_id = row.id
|
||||
doc = await documents("dd-real")
|
||||
reply = json.loads(plan_reply(f"{doc}-2"))
|
||||
reply["entry_fields"] = [{"name": "region", "type": "string", "required": False,
|
||||
"default": "east", "description": "区域"}]
|
||||
reply["sql"] = ("SELECT SUM(amount) AS gmv FROM orders WHERE status = 'paid' "
|
||||
"AND region = '{{ input.region }}'")
|
||||
reply["metrics"][0].update({"expression": "cell(nodes.fetch, 0, 'gmv')", "name": "已支付销售额",
|
||||
"unit": "元", "decimals": 2})
|
||||
fake_model(monkeypatch, json.dumps(reply, ensure_ascii=False))
|
||||
# 报告节点也要一个模型:用品自带的 mock 模型,正文引用卡上的指标,核对规则照过
|
||||
S.script(monkeypatch, "已支付销售额 [[m:m1]]。")
|
||||
monkeypatch.setattr(api_ledger, "_run_trial", REAL_RUN_TRIAL)
|
||||
|
||||
draft_id = (await extract(client, doc, source_id))["draft_id"]
|
||||
made = (await client.get(f"/api/ledger/drafts/{draft_id}")).json()
|
||||
assert made["status"] == "ready" and made["trial"]["status"] == "succeeded", made.get("error")
|
||||
run_id = made["trial"]["run_id"]
|
||||
|
||||
trial = (await client.get(f"/api/ledger/drafts/{draft_id}/trial")).json()
|
||||
assert trial["status"] == "succeeded" and trial["error"] == ""
|
||||
assert [m["id"] for m in trial["metrics"]] == ["m1"]
|
||||
assert trial["metrics"][0]["name"] == "已支付销售额"
|
||||
assert float(trial["metrics"][0]["value"]) == 156.5
|
||||
async with SessionLocal() as session:
|
||||
run = await session.get(Run, run_id)
|
||||
assert run.origin_kind == "caliber_trial" and run.run_class == "exploratory"
|
||||
assert not [n for n in (run.graph or {}).get("nodes") or [] if n.get("type") == "report"], \
|
||||
"试跑只跑取数与口径卡,不该触发报告撰写"
|
||||
assert run.origin["kind"] == "caliber_trial" and run.origin["draft_id"] == draft_id
|
||||
assert run.origin["workflow_id"] == made["workflow_id"] and run.origin["version"] == 1
|
||||
finally:
|
||||
await run_manager.shutdown()
|
||||
async with SessionLocal() as session:
|
||||
if run_id:
|
||||
row = await session.get(Run, run_id)
|
||||
if row is not None:
|
||||
await session.delete(row)
|
||||
source = (await session.execute(select(DataSource).where(
|
||||
DataSource.name == S.CURRENT["source"]))).scalars().first()
|
||||
if source is not None:
|
||||
await session.delete(source)
|
||||
await session.commit()
|
||||
|
||||
@@ -0,0 +1,200 @@
|
||||
"""口径一次起草的纯逻辑(app/ledger/draftplan.py)。
|
||||
|
||||
- SQL 只收单条只读 SELECT:多语句、注释后藏的第二条、写操作、目录外的表一律拒;
|
||||
- 指标表达式必须是 cell(nodes.fetch, 0, '列名');引用核不上的整条丢弃;
|
||||
- build_graph 两次调用逐字一致,且能过 GraphSpec / validate_graph;
|
||||
- plan 注入假模型(不发真实请求),材料里有表目录和原文。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from types import SimpleNamespace
|
||||
|
||||
import pytest
|
||||
|
||||
from app.engine.schema import GraphSpec, validate_graph
|
||||
from app.ledger import draftplan
|
||||
|
||||
CHUNK = "销售额按已支付订单的支付时间归期统计,退款订单不计入销售额。"
|
||||
CHUNKS = {"c1": {"ordinal": 1, "content": CHUNK, "document_id": "d1"}}
|
||||
TABLES = {"orders", "customers"}
|
||||
|
||||
METRIC = {
|
||||
"id": "m1",
|
||||
"name": "销售额",
|
||||
"synonyms": ["gmv"],
|
||||
"unit": "元",
|
||||
"decimals": 2,
|
||||
"expression": "cell(nodes.fetch, 0, 'gmv')",
|
||||
"definition": {"text": "已支付订单的销售额", "scope": "全部", "exclusions": [], "owner": "运营",
|
||||
"effective_from": "2026-01-01",
|
||||
"citations": [{"chunk": "c1", "quote": "销售额按已支付订单的支付时间归期统计"}]},
|
||||
"open_questions": [],
|
||||
}
|
||||
|
||||
|
||||
def raw(**extra):
|
||||
body = {
|
||||
"entry_fields": [{"name": "start", "type": "string", "required": True, "default": "2026-09-01",
|
||||
"description": "开始日期"}],
|
||||
"sql": "SELECT SUM(amount) AS gmv FROM orders WHERE paid_at >= '{{ input.start }}'",
|
||||
"metrics": [dict(METRIC)],
|
||||
"open_questions": [],
|
||||
}
|
||||
body.update(extra)
|
||||
return body
|
||||
|
||||
|
||||
def sql_problem(sql: str) -> str | None:
|
||||
plan, problems = draftplan.normalize_plan(raw(sql=sql), CHUNKS, allowed_tables=TABLES)
|
||||
assert plan["sql"] == ""
|
||||
reasons = [p["reason"] for p in problems if p["name"] == "sql"]
|
||||
assert reasons, problems
|
||||
return reasons[0]
|
||||
|
||||
|
||||
# ==========================================================================
|
||||
# normalize_plan:SQL 的硬规则
|
||||
# ==========================================================================
|
||||
|
||||
def test_a_read_only_select_over_the_catalog_is_kept():
|
||||
plan, problems = draftplan.normalize_plan(raw(), CHUNKS, allowed_tables=TABLES)
|
||||
assert plan["sql"].endswith("'{{ input.start }}'")
|
||||
assert [m["id"] for m in plan["metrics"]] == ["m1"]
|
||||
assert plan["entry_fields"][0]["name"] == "start"
|
||||
assert not [p for p in problems if p["name"] == "sql"]
|
||||
|
||||
|
||||
def test_multiple_statements_and_a_hidden_second_statement_are_refused():
|
||||
assert "只能是一条语句" in sql_problem(
|
||||
"SELECT SUM(amount) AS gmv FROM orders; DROP TABLE orders")
|
||||
# 注释后藏的第二条也解析成第二条语句
|
||||
assert "只能是一条语句" in sql_problem(
|
||||
"SELECT SUM(amount) AS gmv FROM orders; -- 收尾\nDELETE FROM orders")
|
||||
|
||||
|
||||
def test_writes_and_ddl_are_refused():
|
||||
assert "只读 SELECT" in sql_problem("DELETE FROM orders")
|
||||
assert "只读 SELECT" in sql_problem("UPDATE orders SET amount = 0")
|
||||
assert "只读 SELECT" in sql_problem("DROP TABLE orders")
|
||||
|
||||
|
||||
def test_tables_outside_the_catalog_are_refused():
|
||||
reason = sql_problem("SELECT * FROM secrets")
|
||||
assert "secrets" in reason and "数据目录" in reason
|
||||
# CTE 名字不是表;真正的表没在目录里照样拒
|
||||
reason = sql_problem("WITH x AS (SELECT * FROM secrets) SELECT * FROM x")
|
||||
assert "secrets" in reason
|
||||
|
||||
|
||||
def test_a_cte_over_a_catalog_table_is_allowed():
|
||||
plan, problems = draftplan.normalize_plan(
|
||||
raw(sql="WITH paid AS (SELECT amount FROM orders) SELECT SUM(amount) AS gmv FROM paid"),
|
||||
CHUNKS, allowed_tables=TABLES)
|
||||
assert plan["sql"].startswith("WITH paid")
|
||||
assert not [p for p in problems if p["name"] == "sql"]
|
||||
|
||||
|
||||
def test_an_undeclared_template_field_invalidates_the_sql():
|
||||
plan, problems = draftplan.normalize_plan(
|
||||
raw(sql="SELECT SUM(amount) AS gmv FROM orders WHERE paid_at >= '{{ input.nope }}'"),
|
||||
CHUNKS, allowed_tables=TABLES)
|
||||
assert plan["sql"] == ""
|
||||
assert any("nope" in p["reason"] for p in problems)
|
||||
|
||||
|
||||
# ==========================================================================
|
||||
# normalize_plan:指标
|
||||
# ==========================================================================
|
||||
|
||||
def test_a_bad_expression_drops_only_that_metric():
|
||||
plan, problems = draftplan.normalize_plan(
|
||||
raw(metrics=[{**METRIC, "expression": "SUM(amount)"}, {**dict(METRIC), "id": "m2"}]),
|
||||
CHUNKS, allowed_tables=TABLES)
|
||||
assert [m["id"] for m in plan["metrics"]] == ["m2"]
|
||||
assert any(p["name"] == "销售额" and "cell(nodes.fetch, 0" in p["reason"] for p in problems)
|
||||
|
||||
|
||||
def test_a_metric_whose_quotes_do_not_match_the_source_is_dropped():
|
||||
plan, problems = draftplan.normalize_plan(
|
||||
raw(metrics=[{**METRIC, "definition": {**METRIC["definition"],
|
||||
"citations": [{"chunk": "c1", "quote": "原文里没有这句"}]}}]),
|
||||
CHUNKS, allowed_tables=TABLES)
|
||||
assert plan["metrics"] == []
|
||||
assert any(p["name"] == "销售额" and "引用" in p["reason"] for p in problems)
|
||||
assert any(p["name"] == "metrics" for p in problems)
|
||||
|
||||
|
||||
def test_metric_ids_are_unique_and_entry_fields_are_normalized():
|
||||
plan, _problems = draftplan.normalize_plan(
|
||||
raw(entry_fields=[{"name": "start", "type": "date", "required": 1, "default": "2026-09-01"}],
|
||||
metrics=[dict(METRIC), {**dict(METRIC), "name": "订单数"}]),
|
||||
CHUNKS, allowed_tables=TABLES)
|
||||
assert [m["id"] for m in plan["metrics"]] == ["m1", "m2"]
|
||||
assert plan["entry_fields"][0]["type"] == "string"
|
||||
assert plan["entry_fields"][0]["required"] is True
|
||||
|
||||
|
||||
# ==========================================================================
|
||||
# build_graph
|
||||
# ==========================================================================
|
||||
|
||||
def test_build_graph_is_deterministic_and_passes_validation():
|
||||
plan, _ = draftplan.normalize_plan(raw(), CHUNKS, allowed_tables=TABLES)
|
||||
plan["datasource"] = "shop"
|
||||
first = draftplan.build_graph(plan, name="销售额口径", question="上周销售额")
|
||||
second = draftplan.build_graph(plan, name="销售额口径", question="上周销售额")
|
||||
assert first == second
|
||||
assert [node["id"] for node in first["nodes"]] == ["start", "fetch", "card", "write", "out"]
|
||||
fetch = next(node for node in first["nodes"] if node["id"] == "fetch")
|
||||
assert fetch["data"]["config"] == {"tool": "db_query__shop", "args": {"sql": plan["sql"]}}
|
||||
card = next(node for node in first["nodes"] if node["id"] == "card")
|
||||
assert card["data"]["config"]["metrics"][0]["id"] == "m1"
|
||||
contract = next(node for node in first["nodes"] if node["id"] == "out")["data"]["config"]["contract"]
|
||||
assert contract["metrics_from"] == "card" and contract["required"] == ["m1"]
|
||||
report = next(node for node in first["nodes"] if node["id"] == "write")["data"]["config"]
|
||||
assert report["numbers"] == "strict" and report["metrics_from"] == ["card"]
|
||||
result = validate_graph(GraphSpec.model_validate(first))
|
||||
assert result.ok, [issue.message for issue in result.issues if issue.level == "error"]
|
||||
|
||||
|
||||
# ==========================================================================
|
||||
# plan:注入假模型
|
||||
# ==========================================================================
|
||||
|
||||
class FakeModel:
|
||||
model_name = "fake-plan-model"
|
||||
|
||||
def __init__(self, text: str) -> None:
|
||||
self.text = text
|
||||
self.messages: list = []
|
||||
|
||||
async def ainvoke(self, messages):
|
||||
self.messages = messages
|
||||
return SimpleNamespace(content=self.text)
|
||||
|
||||
|
||||
async def test_plan_hands_the_model_the_table_catalog_and_the_source_text():
|
||||
model = FakeModel(json.dumps({**raw(), "model_id": "ignored"}, ensure_ascii=False))
|
||||
result = await draftplan.plan(
|
||||
None, docs=[{"document_id": "d1", "title": "销售口径.md"}], chunks=CHUNKS,
|
||||
guidance="只看已支付", datasource={"name": "shop", "type": "sqlite"},
|
||||
tables_text="表 orders(订单)\n amount 金额", model=model)
|
||||
assert result["model_id"] == "fake-plan-model"
|
||||
assert result["sql"].startswith("SELECT SUM(amount)")
|
||||
assert result["metrics"][0]["name"] == "销售额"
|
||||
human = model.messages[-1].content
|
||||
assert "表 orders" in human and "amount 金额" in human
|
||||
assert CHUNK in human and "只看已支付" in human
|
||||
|
||||
|
||||
async def test_plan_refuses_when_no_draft_model_is_available(monkeypatch):
|
||||
from app.data import recipe_ai
|
||||
from app.ledger import docdraft
|
||||
|
||||
async def resolve(_session):
|
||||
return None, "", SimpleNamespace(available=False, reason="还没有接入可用的起草模型")
|
||||
|
||||
monkeypatch.setattr(recipe_ai, "resolve_draft_model", resolve)
|
||||
with pytest.raises(docdraft.DraftUnavailable, match="起草模型"):
|
||||
await draftplan.plan(None, docs=[], chunks={})
|
||||
Reference in New Issue
Block a user