AgentLab/backend/app/ledger/descriptor.py

"""口径可调用描述（descriptor）：给目录页、应用表单、外部集成一份机器可读的稳定描述（next-round 02 的后续）。

口径已经能按固定版本实例化（look/calibers 的查看结果、ledger/compose 的 use_caliber），但入口字段、依赖、能不能出具这些
契约只写在给模型看的文字里。这里把它们写成结构化的数据：

- 只列每个工作流**推荐发布版**（Workflow.published_version，K07：默认调用读推荐版，不机械取最高已发布版）里的
  **源头口径卡**（metrics 节点、caliber_from 为空），和 look/calibers、ledger/derive 的认法一致：转抄卡不列，
  源头才能复用；
- 入口字段用 ledger/derive.entry_fields，按 apps/forms.input_schema 转成 JSON Schema（和表单、use_caliber 校验同一个）；
- 依赖只从图里的取数节点认数据源和表名，**不返回 SQL、不返回参数值**（SQL 里可能写着遮罩值，组合时由服务端照抄）；
- 能不能组合按**每个指标**判（K08 S4，look/calibers.metric_options）：B 独有那条查询坏了、绑定对不上，只让 B 不可以选，
  A 照旧可组合；一个可选指标也没有才不能组合。另给这一版的两份闭包摘要——``closure``（不点名、整卡那份）与
  ``selectable_metrics`` / ``unavailable_metrics``（每个指标的摘要与原因），以及 ``computes_unselected``（共享 SQL 还在
  算哪些没选中的指标）。摘要与描述里只有 query_id、字段、工具、指纹这些，**没有 SQL 正文、没有参数值**；
- 出具只描述这一版的策略：级别、图里有没有人工节点或写外部系统的节点。全局的自动出具开关、每日上限是运行时条件，这里
  不查——descriptor 说的是「这一版允许什么」，不代表这次运行一定能出具。
"""
from __future__ import annotations

from typing import Any

from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession

from app.apps import versions as app_versions
from app.apps.backfill import graph_side_effect
from app.apps.forms import input_schema
from app.apps.tree import node_map
from app.db.models import Workflow
from app.ledger.derive import entry_fields
from app.look.calibers import metric_options, option_reason

#: 指标只写口径卡配置里真有的这几个键
METRIC_KEYS = ("id", "name", "unit", "decimals", "format", "kind", "definition", "params", "external", "rule",
               "assessment", "synonyms", "grain", "time_field", "numerator", "denominator", "dimensions", "filters", "contract")


async def list_calibers(session: AsyncSession, *, workflow_id: str | None = None) -> list[dict[str, Any]]:
    """每个工作流**推荐发布版**（Workflow.published_version）里的源头口径卡，一张卡一条描述。给了 workflow_id 只列那个工作流。

    K07：默认调用读的是**推荐版**（重新推上一版旧版之后，默认就跟着它走），不再机械地取「最高已发布版」——最高版
    只在升级发现里用（app/apps/publications.upgrade_of）。

    同一版图里的 graph_side_effect 按 (workflow_id, version) 只算一次：它要读子图、跑发布检查，比其余字段慢得多。"""
    from app.apps import publications

    query = select(Workflow).order_by(Workflow.name, Workflow.id)
    if workflow_id:
        query = query.where(Workflow.id == workflow_id)
    side_cache: dict[tuple[str, int], str | None] = {}
    out: list[dict[str, Any]] = []
    for workflow in (await session.execute(query)).scalars().all():
        row = await publications.recommended(session, workflow)
        if row is None:
            continue
        for node_id, node in node_map(row.graph or {}).items():
            if node["type"] != "metrics" or node["config"].get("caliber_from") not in (None, "", {}):
                continue
            made = await _describe(session, workflow, row, node_id, side_cache)
            if made is not None:
                out.append(made)
    return out


async def caliber_descriptor(session: AsyncSession, workflow_id: str, version: int,
                             node_id: str) -> dict[str, Any] | None:
    """一个工作流版本里一张源头口径卡的描述；工作流不存在、版本没发布过或已退役、节点不是源头口径卡时返回 None。"""
    workflow = await session.get(Workflow, str(workflow_id or ""))
    if workflow is None:
        return None
    row = await app_versions.version_row(session, workflow.id, int(version))
    if row is None or not app_versions.is_published(row, current=workflow.published_version):
        return None
    return await _describe(session, workflow, row, str(node_id), {})


async def _describe(session: AsyncSession, workflow: Workflow, row: Any, node_id: str,
                    side_cache: dict[tuple[str, int], str | None]) -> dict[str, Any] | None:
    """一张卡的描述；节点不是源头口径卡时返回 None。"""
    graph = row.graph or {}
    nodes = node_map(graph)
    card = nodes.get(node_id)
    if card is None or card["type"] != "metrics" or card["config"].get("caliber_from") not in (None, "", {}):
        return None
    cfg = card["config"]
    level = str(row.level or "")
    made = metric_options(graph, node_id, workflow_id=workflow.id, version=int(row.version))
    from app.apps import publications
    from app.data.caliber_identity import semantic_hash

    key = (workflow.id, int(row.version))
    if key not in side_cache:
        side_cache[key] = await graph_side_effect(session, graph, level=level or None)
    side_effect = side_cache[key]
    sources, tables = publications.fetch_dependencies(graph)
    publication = await publications.latest(session, workflow.id, int(row.version))
    reasons: list[str] = []
    if level != "governed":
        reasons.append("这一版是已发布级别，只支持一键出具")
    if side_effect is not None:
        reasons.append(f"这一版{side_effect}，不能替人再次执行")
    if not sources:
        reasons.append("这一版没有取数节点，账本不能按口径证明等价")
    return {
        "workflow_id": workflow.id,
        "workflow_name": workflow.name,
        "version": int(row.version),
        "level": level,
        "graph_hash": row.graph_hash,
        "semantic_hash": semantic_hash(graph, node_id),
        # K07：这一版的发布依据是哪一份清单（没有清单的是加这一机制之前发布的老资产，值为 null）
        "publication": ({"id": publication.id, "manifest": publication.manifest,
                         "proven": bool(publication.proven)}
                        if publication is not None else None),
        "card": {"node_id": node_id, "title": card["title"], "caliber": cfg.get("caliber"),
                 "caliber_version": cfg.get("caliber_version")},
        "metrics": [{k: m[k] for k in METRIC_KEYS if k in m}
                    for m in cfg.get("metrics") or []
                    if isinstance(m, dict) and m.get("id")],
        "entry_schema": input_schema(list(entry_fields(graph))),
        # 能不能组合按**每个指标**判（K08 S4）：B 独有那条查询坏了、绑定对不上，A 照旧可选；一个指标也选不了才不能组合。
        # 摘要里只有 query_id、字段、工具、指纹与共享声明，没有 SQL 正文、没有参数值
        "composable": made.composable,
        "compose_reason": option_reason(made),
        "closure": made.default,
        "selectable_metrics": [dict(m) for m in made.selectable],
        "unavailable_metrics": [dict(m) for m in made.unavailable],
        "computes_unselected": shared_queries(made),
        "dependencies": {"sources": sources, "tables": tables,
                         "catalog_versions": row.catalog_versions, "schema_versions": row.schema_versions},
        "issuance": {"level": level, "auto_issue": level == "governed" and side_effect is None and bool(sources),
                     "requires_independent_proof": True, "side_effects": side_effect, "reasons": reasons},
    }


def shared_queries(made: Any) -> list[dict[str, Any]]:
    """这几份摘要里「还在算没选中的指标」的查询：{query_id, node_id, metric_ids, computes_unselected}。

    按 (query_id, 这次选中的指标) 去重、按出现先后排：一张卡上几个指标共用一条 SQL 时，选谁、还在算谁一目了然（K08 S3
    不做投影，共享 SQL 原样保留）。整卡那一份加上每个可选指标那一份，只从闭包的摘要里收，不另解析一遍依赖。"""
    out: list[dict[str, Any]] = []
    seen: set[tuple[str, tuple[str, ...]]] = set()
    for summary in [made.default, *made.selectable]:
        for query in (summary or {}).get("queries") or []:
            others = [str(m) for m in query.get("computes_unselected") or []]
            read_by = [str(m) for m in query.get("metric_ids") or []]
            if not others or (str(query["query_id"]), tuple(read_by)) in seen:
                continue
            seen.add((str(query["query_id"]), tuple(read_by)))
            out.append({"query_id": query["query_id"], "node_id": query["node_id"],
                        "metric_ids": read_by, "computes_unselected": others})
    return out


__all__ = ["caliber_descriptor", "list_calibers", "shared_queries"]