AgentLab/backend/app/db/models.py

from __future__ import annotations

from datetime import datetime
from typing import Any

from sqlalchemy import (
    Float, ForeignKey, Index, Integer, LargeBinary, String, Text, UniqueConstraint,
)
from sqlalchemy.orm import Mapped, mapped_column, relationship

from app.db.base import Base, TimestampMixin, UTCDateTime, new_id, utcnow

# --------------------------------------------------------------------------
# 设置：模型供应商 / 用户偏好 / MCP / 自定义工具
# --------------------------------------------------------------------------


class Provider(Base, TimestampMixin):
    """一个模型接入点。api_key 落库前经 app.core.crypto 加密。"""

    __tablename__ = "providers"

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    name: Mapped[str] = mapped_column(String(100), unique=True)
    kind: Mapped[str] = mapped_column(String(32))  # anthropic | openai | openai_compatible | mock
    base_url: Mapped[str | None] = mapped_column(String(500), default=None)
    api_key: Mapped[str | None] = mapped_column(Text, default=None)  # 密文
    models: Mapped[list[Any]] = mapped_column(default=list)  # [{id, label, context, pricing}]
    default_model: Mapped[str | None] = mapped_column(String(200), default=None)
    enabled: Mapped[bool] = mapped_column(default=True)
    extra: Mapped[dict[str, Any]] = mapped_column(default=dict)


class DataSource(Base, TimestampMixin):
    """一个数据库接入点。password 落库前经 app.core.crypto 加密，和 Provider 同一套。

    readonly 默认为真，是刻意的安全基线：这里的 SQL 由模型生成，不是人写的。
    要写库就另建一个显式关掉只读的源，并且写操作会走人工审批——把"能写"这件事
    变成一个需要两次明确动作的决定，而不是默认状态。
    """

    __tablename__ = "data_sources"

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    name: Mapped[str] = mapped_column(String(100), unique=True)
    kind: Mapped[str] = mapped_column(String(32))  # mysql | postgres | oracle | sqlite
    host: Mapped[str | None] = mapped_column(String(255), default=None)
    port: Mapped[int | None] = mapped_column(Integer, default=None)
    database: Mapped[str | None] = mapped_column(String(255), default=None)
    username: Mapped[str | None] = mapped_column(String(128), default=None)
    password: Mapped[str | None] = mapped_column(Text, default=None)  # 密文
    # 驱动差异塞这里：Oracle 的 service_name/sid、MySQL 的 charset、SSL 参数…
    # 不给每种数据库加一列，否则表会长成各家方言的并集
    options: Mapped[dict[str, Any]] = mapped_column(default=dict)
    readonly: Mapped[bool] = mapped_column(default=True)
    # 给 Copilot 看的一句话："销售库，含订单/客户/产品"。它据此判断该查哪个源
    description: Mapped[str] = mapped_column(Text, default="")
    # 探查到的表结构。缓存下来，否则每次建图都要连一次生产库
    schema_cache: Mapped[dict[str, Any]] = mapped_column(default=dict)
    schema_synced_at: Mapped[datetime | None] = mapped_column(default=None)
    enabled: Mapped[bool] = mapped_column(default=True)
    # 最近一次测连接：{at, ok, latency_ms, error}。记在对象上，换台浏览器也看得到
    last_check: Mapped[dict[str, Any] | None] = mapped_column(default=None)
    # upload：上传表格建的源，连接信息由系统维护（data/table_versions.py），不许手改；
    # manual：手工登记的连接。按这个字段判断，而不是猜 database 的路径
    origin: Mapped[str] = mapped_column(String(20), default="manual")
    # 上传源当前启用的快照（source_snapshots.id）。查询、探查都从快照解析，
    # database 只作显示；手工源恒为 None
    current_snapshot_id: Mapped[str | None] = mapped_column(String(64), default=None)


# --------------------------------------------------------------------------
# 上传表格的版本：构建 → 导入记录 → 快照（data/table_versions.py）
# --------------------------------------------------------------------------


class TableBuild(Base):
    """一次解析的产物：同一个源、同一份原件、同一组解析选项、同一版解析器，只建一次库。

    id 是这四样的 sha256 全长，source_id 算在里面：两个源传同一个文件得到两个构建，
    互不引用——一个源删掉、回收，不会连带另一个源的库。库文件写好后是只读的（0444），
    之后不再改动；回收时删掉文件、记录留着（retired_at）备查。
    """

    __tablename__ = "table_builds"

    id: Mapped[str] = mapped_column(String(64), primary_key=True)
    source_id: Mapped[str] = mapped_column(String(32), index=True)
    raw_sha256: Mapped[str] = mapped_column(String(64), default="")
    options_sha256: Mapped[str] = mapped_column(String(64), default="")
    engine_ver: Mapped[str] = mapped_column(String(40), default="")
    options: Mapped[dict[str, Any]] = mapped_column(default=dict)
    db_path: Mapped[str] = mapped_column(Text, default="")
    db_sha256: Mapped[str] = mapped_column(String(64), default="")
    # 解析回执（tabular.LoadReport）：区域、跳过的工作表、类型转换、警告
    report: Mapped[dict[str, Any]] = mapped_column(default=dict)
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow)
    # 库文件被回收的时刻。为空表示文件还在
    retired_at: Mapped[datetime | None] = mapped_column(UTCDateTime, default=None)


class TableImport(Base):
    """一次上传。重传同一个文件也是一条新记录（指向同一个构建）：谁、何时、传了什么，都要留痕。

    不挂外键：数据源删掉以后，导入记录置 retired 留作审计，不跟着删。
    """

    __tablename__ = "table_imports"
    __table_args__ = (Index("ix_table_imports_source_seq", "source_id", "seq"),)

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    source_id: Mapped[str] = mapped_column(String(32))
    seq: Mapped[int] = mapped_column(Integer, default=0)
    build_id: Mapped[str] = mapped_column(String(64), default="")
    file_name: Mapped[str] = mapped_column(String(500), default="")
    file_size: Mapped[int] = mapped_column(Integer, default=0)
    raw_sha256: Mapped[str] = mapped_column(String(64), default="")
    # kept：原件在 uploads/raw 里；purged：清除过（purged 里记时间、署名、理由）；
    # absent：从来没有原件（迁移前的老上传只剩 .db）
    raw_state: Mapped[str] = mapped_column(String(20), default="kept")
    # active：当前快照里的那一期；superseded：被新上传替换、文件还在；retired：已回收或源已删除
    status: Mapped[str] = mapped_column(String(20), default="active", index=True)
    purged: Mapped[dict[str, Any] | None] = mapped_column(default=None)
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow)
    activated_at: Mapped[datetime | None] = mapped_column(UTCDateTime, default=None)


class SourceSnapshot(Base):
    """数据源的一个可查询版本：若干期导入合成的一个库，加上冻结的表结构。

    期 1 只有「每期替换」：一个快照就是一期导入，db_path 直接用那次构建的库。
    运行钉的是快照 id（runs.data_versions），表结构和数据出自同一个版本。
    """

    __tablename__ = "source_snapshots"

    id: Mapped[str] = mapped_column(String(64), primary_key=True)
    source_id: Mapped[str] = mapped_column(String(32), index=True)
    imports: Mapped[list[Any]] = mapped_column(default=list)  # import id 列表
    db_path: Mapped[str] = mapped_column(Text, default="")
    db_sha256: Mapped[str] = mapped_column(String(64), default="")
    schema_cache: Mapped[dict[str, Any]] = mapped_column(default=dict)
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow)
    # 没有运行、也不是当前版本时由回收标上；之后钉着它的请求明确报「版本不存在」
    retired_at: Mapped[datetime | None] = mapped_column(UTCDateTime, default=None)


class Setting(Base, TimestampMixin):
    """键值形式的用户设置，前端 Settings 页直接读写。"""

    __tablename__ = "settings"

    key: Mapped[str] = mapped_column(String(100), primary_key=True)
    value: Mapped[dict[str, Any]] = mapped_column(default=dict)


class McpServer(Base, TimestampMixin):
    __tablename__ = "mcp_servers"

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    name: Mapped[str] = mapped_column(String(100), unique=True)
    transport: Mapped[str] = mapped_column(String(20), default="stdio")  # stdio | http
    command: Mapped[str | None] = mapped_column(String(500), default=None)
    args: Mapped[list[Any]] = mapped_column(default=list)
    env: Mapped[dict[str, Any]] = mapped_column(default=dict)
    url: Mapped[str | None] = mapped_column(String(500), default=None)
    enabled: Mapped[bool] = mapped_column(default=True)
    # 最近一次探活的结果与工具清单缓存
    status: Mapped[str] = mapped_column(String(20), default="unknown")
    last_error: Mapped[str | None] = mapped_column(Text, default=None)
    tools_cache: Mapped[list[Any]] = mapped_column(default=list)
    # 最近一次连接的时刻和耗时（status / last_error 只有结论，没有「何时、多快」）
    last_check: Mapped[dict[str, Any] | None] = mapped_column(default=None)


class CustomTool(Base, TimestampMixin):
    """用户自定义工具：HTTP 调用模板，或跑在沙箱里的一段 Python。"""

    __tablename__ = "custom_tools"

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    name: Mapped[str] = mapped_column(String(100), unique=True)
    description: Mapped[str] = mapped_column(Text, default="")
    kind: Mapped[str] = mapped_column(String(20), default="http")  # http | python
    parameters: Mapped[dict[str, Any]] = mapped_column(default=dict)  # JSON Schema
    config: Mapped[dict[str, Any]] = mapped_column(default=dict)
    enabled: Mapped[bool] = mapped_column(default=True)


# --------------------------------------------------------------------------
# 工作流与版本
# --------------------------------------------------------------------------


class Workflow(Base, TimestampMixin):
    __tablename__ = "workflows"

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    name: Mapped[str] = mapped_column(String(200))
    description: Mapped[str] = mapped_column(Text, default="")
    graph: Mapped[dict[str, Any]] = mapped_column(default=dict)  # {nodes, edges, viewport}
    tags: Mapped[list[Any]] = mapped_column(default=list)
    version: Mapped[int] = mapped_column(Integer, default=1)
    is_template: Mapped[bool] = mapped_column(default=False)
    # 治理状态机：draft（随便改）→ published（有正式版本可跑）→ governed（发布需过治理 lint）
    status: Mapped[str] = mapped_column(String(20), default="draft")
    # 正式运行默认解析到这个版本；为空表示还没发布过
    published_version: Mapped[int | None] = mapped_column(Integer, default=None)
    published_by: Mapped[str | None] = mapped_column(String(100), default=None)

    versions: Mapped[list["WorkflowVersion"]] = relationship(
        back_populates="workflow", cascade="all, delete-orphan", lazy="selectin"
    )


class WorkflowVersion(Base, TimestampMixin):
    """每次保存留一份快照，便于回滚和对比不同编排的效果。"""

    __tablename__ = "workflow_versions"
    __table_args__ = (UniqueConstraint("workflow_id", "version"),)

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    workflow_id: Mapped[str] = mapped_column(ForeignKey("workflows.id", ondelete="CASCADE"))
    version: Mapped[int] = mapped_column(Integer)
    graph: Mapped[dict[str, Any]] = mapped_column(default=dict)
    note: Mapped[str] = mapped_column(Text, default="")
    # 图内容的 sha256 指纹（剔除 viewport）。formal run 钉住的就是它。
    graph_hash: Mapped[str | None] = mapped_column(String(64), default=None)
    # 这一版按哪一档发布的：published | governed。没发布过、或者是加这一列之前发布的为空。
    # 正式运行按不按受管出具看它，而不是工作流的 status——status 说的是当前画布，改一笔就退回 draft
    level: Mapped[str | None] = mapped_column(String(20), default=None)

    workflow: Mapped[Workflow] = relationship(back_populates="versions")


# --------------------------------------------------------------------------
# 运行、事件、审批
# --------------------------------------------------------------------------


class Run(Base, TimestampMixin):
    __tablename__ = "runs"

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    workflow_id: Mapped[str | None] = mapped_column(
        ForeignKey("workflows.id", ondelete="SET NULL"), default=None
    )
    workflow_name: Mapped[str] = mapped_column(String(200), default="")
    # LangGraph checkpointer 的 thread_id —— 持久化与恢复的锚点
    thread_id: Mapped[str] = mapped_column(String(64), index=True, default=new_id)
    # queued | running | interrupted | succeeded | failed | cancelled
    status: Mapped[str] = mapped_column(String(20), default="queued", index=True)
    graph: Mapped[dict[str, Any]] = mapped_column(default=dict)  # 执行时的图快照
    input: Mapped[dict[str, Any]] = mapped_column(default=dict)
    output: Mapped[dict[str, Any]] = mapped_column(default=dict)
    error: Mapped[str | None] = mapped_column(Text, default=None)
    usage: Mapped[dict[str, Any]] = mapped_column(default=dict)  # tokens / cost / 各节点耗时
    started_at: Mapped[datetime | None] = mapped_column(default=None)
    finished_at: Mapped[datetime | None] = mapped_column(default=None)
    last_seq: Mapped[int] = mapped_column(Integer, default=0)
    # formal：从不可变的 WorkflowVersion 发起，可复现、可出具
    # exploratory：画布试跑 / 裸 graph / 追问，结果只标探索性
    run_class: Mapped[str] = mapped_column(String(20), default="exploratory")
    version: Mapped[int | None] = mapped_column(Integer, default=None)
    version_hash: Mapped[str | None] = mapped_column(String(64), default=None)
    # 结束时对全部事件计算的清单哈希，事后改动事件流会被它戳穿
    manifest_hash: Mapped[str | None] = mapped_column(String(64), default=None)
    # 清单封到了哪一条事件（含）。之后追加的事件（复核批注之类）不在封存范围内；
    # 为空的是记录这一列之前封存的老运行，核对时按当时的口径算
    manifest_seq: Mapped[int | None] = mapped_column(Integer, default=None)
    started_by: Mapped[str | None] = mapped_column(String(100), default=None)
    # 第一次发起时实际生效的记忆域、知识库、工具审批默认值。恢复和接着跑沿用它们，
    # 而不是回落到 "default"——同一次运行前后两段必须查同一个库、守同一道门
    memory_scope: Mapped[str | None] = mapped_column(String(100), default=None)
    collection: Mapped[str | None] = mapped_column(String(100), default=None)
    approval_default: Mapped[str | None] = mapped_column(String(20), default=None)
    # MCP / 自定义工具信任三档在发起时的快照（tools/trust.py）。None 是升级前发起的运行：
    # 那时这两类工具不问人，恢复时也不能开始问，否则审批的答复会对错号
    tool_trust: Mapped[dict[str, Any] | None] = mapped_column(default=None)
    # agent 护栏的上限在发起时的快照（engine/guards.py）。None 是升级前发起的运行，走旧逻辑
    agent_limits: Mapped[dict[str, Any] | None] = mapped_column(default=None)
    # 失败时能定位到的节点。报错要能落到画布上的那张卡片，而不只是一句话
    error_node_id: Mapped[str | None] = mapped_column(String(64), default=None)
    # 发起时钉住的上传表格版本：{source_id: {"snapshot": 快照 id, "name": 源名}}。续跑、恢复沿用，
    # 回收（table_versions.gc）不删任何运行引用的快照。None 是升级前发起的运行
    data_versions: Mapped[dict[str, Any] | None] = mapped_column(default=None)

    events: Mapped[list["RunEvent"]] = relationship(
        back_populates="run", cascade="all, delete-orphan"
    )


class RunEvent(Base):
    """完整事件流落库 —— 这既是 trace，也是页面刷新后重建时间线的依据。"""

    __tablename__ = "run_events"
    __table_args__ = (Index("ix_run_events_run_seq", "run_id", "seq"),)

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    run_id: Mapped[str] = mapped_column(ForeignKey("runs.id", ondelete="CASCADE"))
    seq: Mapped[int] = mapped_column(Integer, default=0)
    type: Mapped[str] = mapped_column(String(40))
    node_id: Mapped[str | None] = mapped_column(String(64), default=None)
    ts: Mapped[float] = mapped_column(Float)
    data: Mapped[dict[str, Any]] = mapped_column(default=dict)

    run: Mapped[Run] = relationship(back_populates="events")


class Approval(Base, TimestampMixin):
    """一次人工介入请求。对应 LangGraph 的 interrupt。"""

    __tablename__ = "approvals"

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    run_id: Mapped[str] = mapped_column(ForeignKey("runs.id", ondelete="CASCADE"), index=True)
    node_id: Mapped[str] = mapped_column(String(64))
    interrupt_id: Mapped[str | None] = mapped_column(String(64), default=None)
    mode: Mapped[str] = mapped_column(String(20), default="approve")  # approve | input | edit
    title: Mapped[str] = mapped_column(String(300), default="")
    payload: Mapped[dict[str, Any]] = mapped_column(default=dict)  # 给人看的上下文
    schema_: Mapped[dict[str, Any]] = mapped_column("schema", default=dict)
    status: Mapped[str] = mapped_column(String(20), default="pending", index=True)
    response: Mapped[dict[str, Any]] = mapped_column(default=dict)
    resolved_at: Mapped[datetime | None] = mapped_column(default=None)
    # 责任归属：谁批的。没有 actor 的治理是空转。
    resolved_by: Mapped[str | None] = mapped_column(String(100), default=None)


class Artifact(Base, TimestampMixin):
    """工件引用表。

    文件本体按内容哈希存在 data/artifacts/ 下（同内容只一份）；
    这张表记录"哪个 run 的哪个节点产出了它"——溯源需要的正是这层归属。
    复合主键：同一工件被多个 run 产出时各记一行引用。
    """

    __tablename__ = "artifacts"
    __table_args__ = (Index("ix_artifacts_run", "run_id"),)

    id: Mapped[str] = mapped_column(String(64), primary_key=True)
    run_id: Mapped[str] = mapped_column(String(32), primary_key=True, default="")
    kind: Mapped[str] = mapped_column(String(32), default="node_output")  # node_output | tool_snapshot | metric_set
    node_id: Mapped[str | None] = mapped_column(String(64), default=None)
    size: Mapped[int] = mapped_column(Integer, default=0)
    meta: Mapped[dict[str, Any]] = mapped_column(default=dict)


# --------------------------------------------------------------------------
# 记忆、知识库、Skill
# --------------------------------------------------------------------------


class MemoryItem(Base, TimestampMixin):
    """长期记忆。scope 用来隔离不同 agent / 会话的记忆空间。"""

    __tablename__ = "memories"
    __table_args__ = (Index("ix_memories_scope_kind", "scope", "kind"),)

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    scope: Mapped[str] = mapped_column(String(100), default="default")
    kind: Mapped[str] = mapped_column(String(32), default="fact")  # fact | preference | episode
    content: Mapped[str] = mapped_column(Text)
    meta: Mapped[dict[str, Any]] = mapped_column(default=dict)
    embedding: Mapped[bytes | None] = mapped_column(LargeBinary, default=None)
    # 这条向量是谁产出的。没有它就无法判断存量向量还能不能和当前查询比对——
    # 换 embedder 之后维度对不上，cosine 直接 ValueError（512 vs 1536），
    # 而在此之前代码里没有任何地方能看出"这条是旧模型建的"
    embed_model: Mapped[str] = mapped_column(String(100), default="")
    embed_dim: Mapped[int] = mapped_column(Integer, default=0)
    importance: Mapped[float] = mapped_column(Float, default=0.5)
    last_used_at: Mapped[datetime | None] = mapped_column(default=None)
    use_count: Mapped[int] = mapped_column(Integer, default=0)


class Document(Base, TimestampMixin):
    """知识库里的一份原始文档。"""

    __tablename__ = "documents"

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    collection: Mapped[str] = mapped_column(String(100), default="default", index=True)
    title: Mapped[str] = mapped_column(String(300), default="")
    source: Mapped[str] = mapped_column(String(500), default="")  # 文件名 / URL
    mime: Mapped[str] = mapped_column(String(100), default="text/plain")
    content: Mapped[str] = mapped_column(Text, default="")
    meta: Mapped[dict[str, Any]] = mapped_column(default=dict)
    chunk_count: Mapped[int] = mapped_column(Integer, default=0)
    # 切块+算向量是在后台跑的：一个 10MB 文档配上远端 embedding 要几十分钟，
    # 压在 HTTP 请求里必然超时——而后端其实还在跑，界面显示失败、数据其实成功，
    # 比直接拒绝还糟。ready | processing | failed
    status: Mapped[str] = mapped_column(String(20), default="ready")
    error: Mapped[str] = mapped_column(Text, default="")

    chunks: Mapped[list["Chunk"]] = relationship(
        back_populates="document", cascade="all, delete-orphan"
    )


class Chunk(Base):
    __tablename__ = "chunks"
    __table_args__ = (Index("ix_chunks_collection", "collection"),)

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    document_id: Mapped[str] = mapped_column(ForeignKey("documents.id", ondelete="CASCADE"))
    collection: Mapped[str] = mapped_column(String(100), default="default")
    ordinal: Mapped[int] = mapped_column(Integer, default=0)
    content: Mapped[str] = mapped_column(Text)
    embedding: Mapped[bytes | None] = mapped_column(LargeBinary, default=None)
    # 这条向量是谁产出的。没有它就无法判断存量向量还能不能和当前查询比对——
    # 换 embedder 之后维度对不上，cosine 直接 ValueError（512 vs 1536），
    # 而在此之前代码里没有任何地方能看出"这条是旧模型建的"
    embed_model: Mapped[str] = mapped_column(String(100), default="")
    embed_dim: Mapped[int] = mapped_column(Integer, default=0)
    #: 分词后的 token 数。BM25 要按文档长度归一，存下来省得为算 avg_len 再扫一遍
    token_len: Mapped[int] = mapped_column(Integer, default=0)
    meta: Mapped[dict[str, Any]] = mapped_column(default=dict)

    document: Mapped[Document] = relationship(back_populates="chunks")


class ChunkTerm(Base):
    """倒排表：词 → 包含它的片段。

    在此之前每次检索都 `select(Chunk)` 全量载入，再在 Python 里**重建**一遍
    BM25 倒排——几百段无感，上万段就是秒级，而那正是知识库开始有用的规模。

    没用 SQLite 的 FTS5：它的 trigram 分词器要求查询至少三个字符，中文里
    「商家」「订单」「权限」这些两字词一个都召不回（实测）。而现有的分词器
    本来就做中文单字 + 二元组，自己存一张倒排表既保住召回，也不把知识库
    锁死在 SQLite 上。
    """

    __tablename__ = "chunk_terms"
    __table_args__ = (Index("ix_chunk_terms_lookup", "collection", "term"),)

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    chunk_id: Mapped[str] = mapped_column(
        ForeignKey("chunks.id", ondelete="CASCADE"), index=True
    )
    collection: Mapped[str] = mapped_column(String(100), default="default")
    term: Mapped[str] = mapped_column(String(64))
    tf: Mapped[int] = mapped_column(Integer, default=1)


class Skill(Base, TimestampMixin):
    """可复用的方法论：一段指令 + 可选的示例和推荐工具。

    节点可以挂载 skill，运行时把内容注入 system prompt —— 把"怎么做事"
    从工作流结构里抽出来单独管理和迭代。
    """

    __tablename__ = "skills"

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    name: Mapped[str] = mapped_column(String(100), unique=True)
    description: Mapped[str] = mapped_column(Text, default="")
    instructions: Mapped[str] = mapped_column(Text, default="")
    examples: Mapped[list[Any]] = mapped_column(default=list)
    suggested_tools: Mapped[list[Any]] = mapped_column(default=list)
    tags: Mapped[list[Any]] = mapped_column(default=list)
    enabled: Mapped[bool] = mapped_column(default=True)


# --------------------------------------------------------------------------
# 会话：把一串问答串成一次对话
# --------------------------------------------------------------------------


class Conversation(Base, TimestampMixin):
    """一次对话。

    在此之前"对话"只是前端内存里的一个数组：刷新页面就没了，而每一轮又各自
    从零建图、各起一条 checkpoint 线程，所以"上一轮问过什么"在系统里根本
    无处可查。追问「再按月份拆一下」会重新找一遍数据源，可能接到别的表。

    落成一张表之后，它同时承担两件事：给用户看的历史列表，和给模型看的上下文。

    kind 分两种，因为这两件事像但不是一回事：
      chat   —— 问数据页，一轮 = 一次「建图 → 跑图 → 出答案」，进左侧列表
      canvas —— 画布右栏的 Copilot，依附某张图，一轮 = 一次改图，不进列表
    """

    __tablename__ = "conversations"

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    title: Mapped[str] = mapped_column(String(200), default="")
    kind: Mapped[str] = mapped_column(String(20), default="chat", index=True)
    workflow_id: Mapped[str | None] = mapped_column(
        ForeignKey("workflows.id", ondelete="CASCADE"), default=None, index=True
    )
    archived: Mapped[bool] = mapped_column(default=False)
    # 列表按活跃度排。不能用 updated_at —— 改个标题就会把这条顶到最前面，
    # 而用户对"最近聊过的"的预期是按说话时间排，不是按编辑时间
    last_active_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, index=True)

    turns: Mapped[list["ConversationTurn"]] = relationship(
        back_populates="conversation",
        cascade="all, delete-orphan",
        order_by="ConversationTurn.seq",
    )


class ConversationTurn(Base, TimestampMixin):
    """一轮问答。

    run_id 可以为空：建图阶段就失败时压根没有 run，但这一轮仍然发生过，
    用户也该在历史里看到它失败了——只记成功的轮次，历史就成了一份美化过的
    记录，而人再回来时最想搞清楚的恰恰是上次卡在哪。
    """

    __tablename__ = "conversation_turns"
    __table_args__ = (Index("ix_conversation_turns_conv_seq", "conversation_id", "seq"),)

    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
    conversation_id: Mapped[str] = mapped_column(
        ForeignKey("conversations.id", ondelete="CASCADE"), index=True
    )
    seq: Mapped[int] = mapped_column(Integer, default=0)
    question: Mapped[str] = mapped_column(Text, default="")
    answer: Mapped[str] = mapped_column(Text, default="")
    # Copilot 对这张图的说明。画布那条路径上只有它，没有 answer
    explanation: Mapped[str] = mapped_column(Text, default="")
    graph: Mapped[dict[str, Any] | None] = mapped_column(default=None)
    run_id: Mapped[str | None] = mapped_column(
        ForeignKey("runs.id", ondelete="SET NULL"), default=None
    )
    # running | done | error
    status: Mapped[str] = mapped_column(String(20), default="running")
    error: Mapped[str] = mapped_column(Text, default="")
    # 跑完之后的复核结论（engine/review.py）：判定档位、给用户的异常说明、
    # 命中的信号清单。落库是因为它是答案的一部分——刷新页面后只剩一个
    # 看起来很完整的答案、而"它哪里不可靠"没了，比不复核更糟
    review: Mapped[dict[str, Any] | None] = mapped_column(default=None)
    # 这一轮的可信度元数据（出具档位、运行类别、未查库、结局、耗时、查库次数…），
    # 前端写、前端读。单独一列：塞在 review 里的话，没复核过的轮次 review 也不为空
    meta: Mapped[dict[str, Any] | None] = mapped_column(default=None)

    conversation: Mapped[Conversation] = relationship(back_populates="turns")