diff --git a/.context/compound-engineering/ce-review/20260429-022541-8f153efc/summary.md b/.context/compound-engineering/ce-review/20260429-022541-8f153efc/summary.md new file mode 100644 index 0000000..527d6a4 --- /dev/null +++ b/.context/compound-engineering/ce-review/20260429-022541-8f153efc/summary.md @@ -0,0 +1,27 @@ +# ce:review summary + +- Scope: PR #23 against `origin/dev` (`b28e0df32113db7706cd65c88204ecbe2ec4a426`) +- Intent: hard-cut the Text2SQL v2 workflow spine and RAG runtime/config surfaces without regressing run-view, delivery, or deployment gates +- Reviewers completed: correctness, testing, maintainability, project-standards, security, data-migrations, frontend-agent-native +- Additional local verification: `pnpm run backend:capability-boundary:check` (failed as reported) + +## Findings + +1. `apps/backend/src/modules/data/persistence/rag-task-config.repository.ts` + Stored RAG API keys are retained when provider/model/baseUrl changes omit `apiKey`, which lets persisted health checks forward the old secret to a new caller-controlled endpoint. +2. `apps/backend/src/modules/data/persistence/rag-task-config.repository.ts` + Prisma read/write failures are swallowed and replaced with in-memory success semantics, so persisted RAG settings can appear saved but disappear after restart. +3. `apps/backend/src/modules/conversation/chat/application/run-view.usecase.ts` + Legacy `latestRun` records now make the whole session-view endpoint unreadable because `getSessionView()` hard-fails while populating `latestRun`. +4. `apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts` + The new conversation import of `knowledge/contracts/knowledge-facade.contract` fails the mandatory backend capability-boundary gate. +5. `.github/workflows/backend-prisma-quality.yml` + The new hard-cut CI step only runs the synthetic focused-coverage gate spec and skips mandatory `collect:text2sql-v2-eval-gate` / `text2sql:no-legacy-compat:check` coverage. +6. `apps/backend/src/modules/conversation/delivery/delivery-contract.mapper.ts` + Delivery evidence marks any skipped `generate-sql` stage as a saved-prior-SQL shortcut hit, which mislabels metadata/general no-SQL routes. + +## Residual risks + +- `/api/v1/settings/rag-configs` is still fetched on the frontend before role-gating settles, and the endpoint itself is not admin-guarded. +- Overlapping `loadRagConfigView()` requests can still restore stale config state in the settings page. +- One reviewer lane (`api-contract`) timed out; learnings were synthesized locally from plans/solutions instead of a dedicated subagent. diff --git a/.github/workflows/backend-prisma-quality.yml b/.github/workflows/backend-prisma-quality.yml index c88803d..327bf2d 100644 --- a/.github/workflows/backend-prisma-quality.yml +++ b/.github/workflows/backend-prisma-quality.yml @@ -78,6 +78,14 @@ jobs: - name: Backend test run: pnpm --filter @text2sql/backend run test + - name: Text2SQL v2 focused coverage report + run: | + pnpm --filter @text2sql/backend exec jest \ + --coverage \ + --runInBand \ + text2sql-v2-focused-coverage-gate.spec.ts + pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate + - name: R6 scenario package tests env: R6_REPORT_DIR: /tmp/r6-evidence diff --git a/AGENTS.md b/AGENTS.md index f33d45e..bbd427b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,7 +39,7 @@ 常用后端 DB 命令： - 生成 Prisma Client：`pnpm --filter @text2sql/backend run prisma:generate` -- 开发环境生成迁移：`pnpm --filter @text2sql/backend run prisma:migrate -- --name ` +- 开发环境生成迁移：`pnpm --filter @text2sql/backend run prisma:migrate --name ` - 空库回放校验：`pnpm --filter @text2sql/backend run prisma:verify-empty-db` ## 3) 质量门禁 @@ -67,9 +67,17 @@ CI 参考： ## 4) 联调最小检查 - 统一入口：`http://localhost:3000` 可访问，`/data-sources -> 创建会话 -> 发送消息` 主链路可用。 +- `/settings` 入口可访问，至少包含 `LLM 模型`、`RAG 配置`、`RAG 运行` 三个 tab；其中配置变更仅在 `RAG 配置` 下操作。 +- `RAG 配置` 健康检查需同时覆盖 `dry-check`（草稿）与 `persisted-check`（已保存），并校验返回 `checkedAgainst=draft|persisted`、`reasonCode` 可解释，且检测失败不应清空草稿输入。 - 网关 smoke：`node tests/smoke/nginx-dev-gateway-smoke.mjs` 可区分 frontend/backend/stream 三类上游失败。 -- 健康检查：`GET http://localhost:3002/health` 应可用（后端内部端口检查）。 +- 健康检查：`GET http://localhost:3002/health` 应可用（后端内部端口检查），且 `dependencies.ragConfig.embedding/rerank` 应可见当前激活 provider+model+configSource 摘要。 - 若本次改动涉及流式/工具调用：需关注 stream 与 tool 相关字段一致性（细节见 LLM 迁移规范）。 +- 若本次改动涉及 Text2SQL v2 read-model/delivery hard-cut：执行 + - `pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate` + - （发布阻断）`pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate:strict` + - `pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate` + - `pnpm run text2sql:no-legacy-compat:check` + - 并核对 `rollout.recommendedStage` 与 `rollout.rollbackSuggested`。 - 若本次改动涉及 modeling parity 指标：执行 `pnpm --filter @text2sql/backend run collect:modeling-parity-shadow-gate`，确认 `relationshipPlatform/semanticSpine/modelingWorkspace` 三维输出可生成。 - 若本次改动需要发布门禁（go/no-go）：执行 `pnpm --filter @text2sql/backend run collect:modeling-parity-shadow-gate:strict`，并检查 `rollout.recommendedStage` 与 `rollout.rollbackSuggested`。 @@ -121,11 +129,19 @@ CI 参考： - 同步接口保持 `AgentRunResponse` 合同。 - 流式事件字段必须完整（`type/runId/sessionId/at/data`）。 - 工具调用走 allowlist，失败可追踪。 -- 若接入提示词模板运行时，必须保证 `run.trace.promptTemplate` 与 `delivery.evidence.promptTemplate` 字段语义一致，且旧 run 缺字段可兼容读取。 +- Text2SQL v2 active runtime seam 固定为 `conversation/application/workflow/Text2SQLWorkflowRunner -> conversation/runtime/stages/RunV2LangGraphStage -> conversation/runtime/langgraph/Text2SqlV2LangGraphRunnerService`。 +- 若接入提示词模板运行时，必须保证 `run.trace.promptTemplate` 与 `delivery.evidence.promptTemplate` 字段语义一致。 +- hard-cut 生效后，run read/save-view/replay 仅支持显式 v2 读模型（`run.trace.v2.version/stageOrder/stages`）；历史 shape 必须返回 `410 LEGACY_RUN_UNSUPPORTED`（见 runbook）。 +- 叙事边界必须明确：`007 closeout` 仅覆盖 LangGraph topology + `delegation=0`，`008 strict-completion` 额外覆盖 metadata grounding / correction grounding / context-pack parity（含 `strictCompletionRows` 门禁），`009 runtime-intelligence` 额外覆盖 `runtimePlan` / `artifactRefs` / `smartDefaults`（含 runtime coverage rows 与 eval fixture families）。 必跑检查： - `GET http://localhost:3002/health` 中 stream/tool-calling 相关字段应符合预期。 - `pnpm --filter @text2sql/backend run collect:modeling-parity-shadow-gate` 输出需包含 `modelingWorkspace.metrics.deployBlockRate/rollbackRate/schemaBacklogAvg` 与 `rollout.recommendedStage`。 +- `pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate` 输出需包含 closeout 五门禁（`evalMetrics/evalTraceability/characterization/noLegacyCompat/focusedCoverage`）及 `rollout.recommendedStage/rollbackSuggested/reasons`。 +- `pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate` 输出需包含 scoped coverage、关键文件门槛、A-M flow blockers 与 eval fixture 行为测试追溯。 +- strict-completion 语义补齐后，focused coverage 输出还需包含 `strictCompletionRows` 评估结果（metadata grounding / correction grounding / context-pack parity）。 +- runtime-intelligence 生效后，focused/eval 输出还需覆盖 `runtime-plan-consistency`、`artifact-ref-compaction`、`smart-defaults-evidence`、`plain-general-no-sql`、`large-context-compaction`、`validation-diagnostics`、`correction-grounding`、`execution-preview`、`all-stage-stream-lifecycle`；focused coverage 还需包含 `runtimeArtifactProducerRows` 与 `streamLifecycleRows`。 +- `pnpm run text2sql:no-legacy-compat:check` 必须通过。 ### D. Governance 术语硬切规范 来源：`docs/standards/governance-terminology-spec.md` @@ -172,7 +188,7 @@ CI 参考： 1. 修改 `apps/backend/prisma/schema.prisma` 2. 生成迁移： - - `pnpm --filter @text2sql/backend run prisma:migrate -- --name ` + - `pnpm --filter @text2sql/backend run prisma:migrate --name ` 3. 生成 Client（必跑）： - `pnpm --filter @text2sql/backend run prisma:generate` diff --git a/README.md b/README.md index d0fc57e..8e57894 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Text2SQL 学习演示版（阶段0-3路线）的单仓项目。 ## 技术栈 - 后端：NestJS + TypeScript + Prisma -- Agent：LangGraph `StateGraph` 运行时编排（澄清 -> 生成SQL -> 安全检查 -> 执行 -> 格式化） +- Agent：Text2SQL v2 LangGraph runtime（`intake -> retrieve -> assemble-context -> semantic-plan -> generate-sql -> validate -> correct? -> execute -> answer`，Phase A `delegation=0`），由 `conversation/text2sql` 统一入口驱动 - 前端：Next.js + React + Tailwind CSS v4 + shadcn-ui - 查询数据：SQLite / MySQL / PostgreSQL / CSV / Excel（会话绑定数据源路由） - 功能数据：Redis 缓冲 + PostgreSQL 持久化 @@ -33,7 +33,7 @@ Text2SQL 学习演示版（阶段0-3路线）的单仓项目。 ### 数据库结构改动铁律（必须遵守） - 禁止手写或手改 `apps/backend/prisma/migrations/*/migration.sql`。 -- 先改 `apps/backend/prisma/schema.prisma`，再执行 `pnpm --filter @text2sql/backend run prisma:migrate -- --name ` 生成迁移。 +- 先改 `apps/backend/prisma/schema.prisma`，再执行 `pnpm --filter @text2sql/backend run prisma:migrate --name ` 生成迁移。 - 每次结构变更必须执行 `pnpm --filter @text2sql/backend run prisma:generate`。 ## 目录结构 @@ -82,6 +82,21 @@ cp apps/frontend/.env.example apps/frontend/.env - `LLM_API_KEY=` - `LLM_MODEL=` - `LLM_MOCK_MODE=false`（联调真实模型时保持 false） +- `EMBEDDING_PROVIDER=`（Text2SQL v2 dense retrieval 的 embedding provider） +- `EMBEDDING_BASE_URL=` +- `EMBEDDING_API_KEY=` +- `EMBEDDING_MODEL=text-embedding-3-small` +- `EMBEDDING_DIMENSIONS=` +- `EMBEDDING_VECTOR_VERSION=v1` +- `RERANK_PROVIDER=`（可选，默认回退到 `LLM_PROVIDER`） +- `RERANK_BASE_URL=`（可选，默认回退到 `LLM_BASE_URL`） +- `RERANK_API_KEY=`（可选，默认回退到 `LLM_API_KEY`） +- `RERANK_MODEL=`（可选，默认回退到 `LLM_MODEL`） +- `RERANK_TIMEOUT_MS=`（可选，默认回退到 `LLM_TIMEOUT_MS`） +- `/settings` 页面职责： + - `LLM 模型`：provider/model 目录治理 + - `RAG 配置`：Embedding / Rerank 运行配置（settings first, env fallback），支持 `检测草稿（dry-check）` 与 `已保存配置检测（persisted-check）` + - `RAG 运行`：运行态观测与回放证据 - `LANGSMITH_TRACING=true|false`（是否启用 LangSmith 追踪） - `LANGSMITH_API_KEY=`（启用追踪时必填） - `LANGSMITH_PROJECT=text2sql`（可选，默认 `text2sql`） @@ -143,6 +158,7 @@ pnpm dev - `GET http://localhost:3002/health` 中 `dependencies.sessions.sync` 可查看会话同步状态统计（healthy/pending/degraded）。 - `GET http://localhost:3002/health` 中 `dependencies.gateMetrics.acceptance` 可查看 R1 门禁指标快照（sampleReady/gatePass）。 - `GET http://localhost:3002/api/v1/rag/quality/report` 中 `glossarySelectedContext` 可查看术语 selected_context 门禁（sampleVersion/relativeLift/status）。 +- `GET http://localhost:3002/health` 中 `dependencies.ragConfig.embedding/rerank` 可查看当前生效 provider + model + configSource 摘要。 - 前端能经 `http://localhost:3000` 成功创建会话并发送消息，无跨域报错。 - 前端从 `/data-sources` 选择任一可用数据源后，可自动创建绑定会话并跳转 `/chat`。 - `GET /api/v1/sessions?datasource=` 返回的会话均属于指定数据源。 @@ -182,6 +198,9 @@ ts-node apps/backend/scripts/langsmith-coverage-check.ts \ - `POST /api/v1/settings/prompts`（管理员） - `PATCH /api/v1/settings/prompts/:templateId`（管理员） - `DELETE /api/v1/settings/prompts/:templateId`（管理员，软删除） +- `GET /api/v1/settings/rag-configs` +- `PUT /api/v1/settings/rag-configs/:taskType`（管理员，`taskType=embedding|rerank`） +- `POST /api/v1/settings/rag-configs/:taskType/health`（管理员，支持可选 `draft` payload；返回 `checkedAgainst=draft|persisted` 与结构化 `reasonCode`） - `GET /api/v1/datasources` - `POST /api/v1/datasources` - `POST /api/v1/datasources/upload` @@ -239,6 +258,27 @@ ts-node apps/backend/scripts/langsmith-coverage-check.ts \ - 当前 Tool Calling 基础能力默认启用，首个工具为 `runReadOnlySql`（只读 SQL 执行，含输入校验与安全守卫）。 - SQL 运行时提示词模板命中证据通过 `run.trace.promptTemplate` 与 `run.delivery.evidence.promptTemplate` 暴露（字段：`templateId/scene/scope/version/fallbackReason`）。 - 上下文生效证据通过 `run.trace.effectiveContextSummary/conflictHint` 与 `run.delivery.evidence.effectiveContextSummary/conflictHint` 双层暴露，前端可区分用户显式上下文与系统上下文来源。 +- Text2SQL v2 artifact 通过 `run.trace.v2`、`run.delivery.evidence.v2`、SSE `state` 事件 `data.v2.stageArtifact` 暴露；不会破坏既有 `type/runId/sessionId/at/data` 合同。 +- Full Mermaid strict-completion（2026-04-27）语义补齐： + - metadata 路径走 `retrieve -> assemble-context -> semantic-plan -> answer`，不进入 `generate/validate/execute`。 + - correction 重试携带结构化 `correctionGrounding`（失败 SQL 引用、失败码、重试原因、证据引用、attempt）。 + - delivery 增补 `contextPackSummary / metadataAnswer / correctionGrounding`，用于 sync/stream/run-view/replay 一致诊断。 + - 叙事分层：`007 closeout` 证明 LangGraph 拓扑与 `delegation=0`；`008 strict-completion` 额外要求 metadata grounding / correction grounding / context-pack parity 语义闭环。 +- hard-cut read-model policy：`/api/v1/runs/:runId`、`/api/v1/runs/:runId/save-as-view`、RAG audit replay 仅支持显式 v2 读模型（`run.trace.v2.version/stageOrder/stages`）。授权后若命中历史 shape，会返回 `410 LEGACY_RUN_UNSUPPORTED`（含迁移 runbook 提示）。 + +## Text2SQL v2 评估门禁（新增） +- 评估脚本：`pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate` +- 评估脚本（发布阻断模式）：`pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate:strict` +- focused coverage gate：先运行后端 Jest coverage，再执行 `pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate`；发布阻断模式使用 `pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate:strict` +- focused flow matrix：`apps/backend/test/fixtures/text2sql-v2-closeout-flow-matrix.json` +- fixture：`apps/backend/test/fixtures/text2sql-v2-eval-cases.json` +- characterization fixture：`apps/backend/test/fixtures/text2sql-v2-characterization-cases.json` +- 输出指标：`retrievalRelevance`、`rerankLift`、`planCoverageRate`、`validationPassRate`、`correctionSuccessRate`、`clarificationRate`、`executionSuccessRate`、`userVisibleFailureQuality`、`latencyP50Ms/P95Ms`、`denseUnavailableRate`、`rerankUnavailableRate` +- rollout 输出：`summary.rollout`（eval 指标门禁）+ `rollout`（closeout 聚合门禁，含 `recommendedStage/rollbackSuggested/reasons`） +- closeout 聚合门禁内容：`evalMetrics` + `evalTraceability` + `characterization` + `noLegacyCompat` + `focusedCoverage`（含 `delegationZero`；Full Mermaid strict-completion 场景还必须包含 `strictCompletionRows`：metadata grounding / correction grounding / context-pack parity） +- anti-regression 静态检查：`pnpm run text2sql:no-legacy-compat:check` +- 历史 run 迁移手册：`docs/runbooks/text2sql-v2-hardcut-read-model-migration.md` +- 发布姿势：当前为 direct-v2，不提供进程内 `v1/v2/shadow` runtime 切换；回滚依赖 git/deploy rollback。 ## 测试 ```bash @@ -261,6 +301,10 @@ pnpm test:frontend - 强门禁模式（失败返回非 0）：`pnpm --filter @text2sql/backend run collect:modeling-parity-shadow-gate:strict` - 聚合维度：`relationshipPlatform`、`semanticSpine`、`modelingWorkspace` - 迁移回放：`pnpm --filter @text2sql/backend run prisma:verify-empty-db` +- Text2SQL v2 评估：`pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate` +- Text2SQL v2 评估（严格）：`pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate:strict` +- Text2SQL v2 focused coverage：`pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate` +- Text2SQL hard-cut anti-regression：`pnpm run text2sql:no-legacy-compat:check` - 启动 smoke：至少验证 `GET http://localhost:3002/health`；关键接口建议覆盖： - 网关快速检查：`node tests/smoke/nginx-dev-gateway-smoke.mjs` - 后端健康检查：`GET http://localhost:3002/health` diff --git a/apps/backend/.env.example b/apps/backend/.env.example index 2165d58..32e5529 100644 --- a/apps/backend/.env.example +++ b/apps/backend/.env.example @@ -27,7 +27,18 @@ LLM_TIMEOUT_MS=30000 LLM_STREAM_TIMEOUT_MS=90000 LLM_MOCK_MODE=false LLM_FALLBACK_PROVIDERS=siliconflow,minimax +# Text2SQL v2 dense retrieval uses external embedding provider. +# If omitted, it falls back to LLM_* provider runtime config. +EMBEDDING_PROVIDER=volcengine +EMBEDDING_BASE_URL= +EMBEDDING_API_KEY= +EMBEDDING_MODEL=text-embedding-3-small +EMBEDDING_TIMEOUT_MS=30000 +# Optional: leave empty to use provider default dimensions. +EMBEDDING_DIMENSIONS= +EMBEDDING_VECTOR_VERSION=v1 AGENT_PLANNING_SCAFFOLD_ENABLED=true +AGENT_RAG_RETRIEVAL_ENABLED=true # Clarification hybrid gate defaults: # - enabled by default diff --git a/apps/backend/data/reports/modeling-parity-shadow/gate-summary.json b/apps/backend/data/reports/modeling-parity-shadow/gate-summary.json index 5d35b64..f00ac64 100644 --- a/apps/backend/data/reports/modeling-parity-shadow/gate-summary.json +++ b/apps/backend/data/reports/modeling-parity-shadow/gate-summary.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-04-25T06:47:56.724Z", + "generatedAt": "2026-04-26T12:28:00.057Z", "inputs": { "relationshipPlatform": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/relationship-platform-shadow/samples.json", "semanticSpine": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/semantic-spine-shadow/samples.json", @@ -10,7 +10,7 @@ "semanticSpine": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/semantic-spine-shadow/gate-summary.json", "modelingWorkspace": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/modeling-parity-shadow/gate-summary.json" }, - "strictMode": true, + "strictMode": false, "gatePass": false, "reasons": [ "relationship_platform:sample_not_ready", diff --git a/apps/backend/data/reports/relationship-platform-shadow/gate-summary.json b/apps/backend/data/reports/relationship-platform-shadow/gate-summary.json index 8f176c4..6184178 100644 --- a/apps/backend/data/reports/relationship-platform-shadow/gate-summary.json +++ b/apps/backend/data/reports/relationship-platform-shadow/gate-summary.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-04-25T06:47:56.690Z", + "generatedAt": "2026-04-26T12:28:00.020Z", "inputPath": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/relationship-platform-shadow/samples.json", "thresholds": { "minSamples": 30, diff --git a/apps/backend/data/reports/semantic-spine-shadow/gate-summary.json b/apps/backend/data/reports/semantic-spine-shadow/gate-summary.json index 0f4c1c9..759aa66 100644 --- a/apps/backend/data/reports/semantic-spine-shadow/gate-summary.json +++ b/apps/backend/data/reports/semantic-spine-shadow/gate-summary.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-04-25T06:47:56.719Z", + "generatedAt": "2026-04-26T12:28:00.050Z", "inputPath": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/semantic-spine-shadow/samples.json", "thresholds": { "minSamples": 30, diff --git a/apps/backend/package.json b/apps/backend/package.json index 5e0be91..0b568e5 100644 --- a/apps/backend/package.json +++ b/apps/backend/package.json @@ -21,13 +21,18 @@ "collect:clarification-balance-gate": "TS_NODE_TRANSPILE_ONLY=1 ts-node --project tsconfig.json scripts/collect-clarification-balance-gate.ts", "collect:clarification-balance-gate:strict": "TS_NODE_TRANSPILE_ONLY=1 ts-node --project tsconfig.json scripts/collect-clarification-balance-gate.ts --strict", "collect:modeling-parity-shadow-gate": "node scripts/collect-modeling-parity-shadow-gate.mjs", - "collect:modeling-parity-shadow-gate:strict": "node scripts/collect-modeling-parity-shadow-gate.mjs --fail-on-gate" + "collect:modeling-parity-shadow-gate:strict": "node scripts/collect-modeling-parity-shadow-gate.mjs --fail-on-gate", + "collect:text2sql-v2-eval-gate": "TS_NODE_TRANSPILE_ONLY=1 ts-node --project tsconfig.json scripts/collect-text2sql-v2-eval-gate.ts", + "collect:text2sql-v2-eval-gate:strict": "TS_NODE_TRANSPILE_ONLY=1 ts-node --project tsconfig.json scripts/collect-text2sql-v2-eval-gate.ts --fail-on-gate", + "collect:text2sql-v2-focused-coverage-gate": "TS_NODE_TRANSPILE_ONLY=1 ts-node --project tsconfig.json scripts/collect-text2sql-v2-focused-coverage-gate.ts", + "collect:text2sql-v2-focused-coverage-gate:strict": "TS_NODE_TRANSPILE_ONLY=1 ts-node --project tsconfig.json scripts/collect-text2sql-v2-focused-coverage-gate.ts --fail-on-gate", + "check:text2sql-no-legacy-compat": "TS_NODE_TRANSPILE_ONLY=1 ts-node --project tsconfig.json ../../scripts/check-text2sql-no-legacy-compat.ts" }, "dependencies": { "@ai-sdk/openai-compatible": "^2.0.41", "@anthropic-ai/claude-agent-sdk": "^0.2.98", - "@langchain/core": "^1.1.39", - "@langchain/langgraph": "^1.2.8", + "@langchain/core": "^1.1.41", + "@langchain/langgraph": "^1.2.9", "@nestjs/common": "^10.4.2", "@nestjs/config": "^3.2.3", "@nestjs/core": "^10.4.2", diff --git a/apps/backend/prisma/migrations/20260426143242_rag_task_configs/migration.sql b/apps/backend/prisma/migrations/20260426143242_rag_task_configs/migration.sql new file mode 100644 index 0000000..9edb900 --- /dev/null +++ b/apps/backend/prisma/migrations/20260426143242_rag_task_configs/migration.sql @@ -0,0 +1,32 @@ +-- CreateEnum +CREATE TYPE "RagTaskType" AS ENUM ('embedding', 'rerank'); + +-- CreateTable +CREATE TABLE "rag_task_configs" ( + "id" TEXT NOT NULL, + "taskType" "RagTaskType" NOT NULL, + "provider" TEXT NOT NULL, + "model" TEXT NOT NULL, + "baseUrl" TEXT, + "apiKeyCiphertext" TEXT, + "apiKeyMasked" TEXT, + "enabled" BOOLEAN NOT NULL DEFAULT true, + "dimensions" INTEGER, + "vectorVersion" TEXT, + "timeoutMs" INTEGER, + "note" TEXT, + "healthStatus" TEXT NOT NULL DEFAULT 'unknown', + "lastCheckedAt" TIMESTAMP(3), + "lastHealthLatencyMs" INTEGER, + "lastHealthMessage" TEXT, + "lastError" TEXT, + "createdBy" TEXT, + "updatedBy" TEXT, + "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + "updatedAt" TIMESTAMP(3) NOT NULL, + + CONSTRAINT "rag_task_configs_pkey" PRIMARY KEY ("id") +); + +-- CreateIndex +CREATE UNIQUE INDEX "rag_task_configs_taskType_key" ON "rag_task_configs"("taskType"); diff --git a/apps/backend/prisma/schema.prisma b/apps/backend/prisma/schema.prisma index ef9d570..5760fd2 100644 --- a/apps/backend/prisma/schema.prisma +++ b/apps/backend/prisma/schema.prisma @@ -398,6 +398,37 @@ model ProviderConfig { @@map("provider_configs") } +enum RagTaskType { + embedding + rerank +} + +model RagTaskConfig { + id String @id + taskType RagTaskType @unique + provider String + model String + baseUrl String? + apiKeyCiphertext String? + apiKeyMasked String? + enabled Boolean @default(true) + dimensions Int? + vectorVersion String? + timeoutMs Int? + note String? + healthStatus String @default("unknown") + lastCheckedAt DateTime? + lastHealthLatencyMs Int? + lastHealthMessage String? + lastError String? + createdBy String? + updatedBy String? + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@map("rag_task_configs") +} + model ModelCatalog { id String @id providerConfigId String diff --git a/apps/backend/scripts/collect-clarification-balance-gate.ts b/apps/backend/scripts/collect-clarification-balance-gate.ts index dea034f..2a0a743 100644 --- a/apps/backend/scripts/collect-clarification-balance-gate.ts +++ b/apps/backend/scripts/collect-clarification-balance-gate.ts @@ -3,7 +3,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises"; import { dirname, resolve } from "node:path"; import { Test, type TestingModule } from "@nestjs/testing"; import { AppModule } from "../src/app.module"; -import { GraphBuilderService } from "../src/modules/conversation/agent/graph/graph.builder"; +import { ChatService } from "../src/modules/conversation/chat/chat.service"; import { createSeededSqliteFixture } from "../test/support/sqlite-fixture"; type RunStatus = @@ -295,6 +295,30 @@ function findTraceStep(run: { trace?: { steps?: unknown[] } }, node: string) { }) as Record | undefined; } +function readString(value: unknown): string | undefined { + if (typeof value !== "string") { + return undefined; + } + const normalized = value.trim(); + return normalized.length > 0 ? normalized : undefined; +} + +function findTraceV2Stage( + run: { trace?: { v2?: { stages?: unknown[] } } }, + stage: string +): Record | undefined { + const stages = run.trace?.v2?.stages; + if (!Array.isArray(stages)) { + return undefined; + } + return stages.find((item) => { + if (typeof item !== "object" || item === null || Array.isArray(item)) { + return false; + } + return (item as Record).stage === stage; + }) as Record | undefined; +} + function readRunStatus(value: unknown): RunStatus { if ( value === "clarification" || @@ -311,6 +335,9 @@ function detectMetadataBypass(run: { status: RunStatus; trace?: { steps?: unknown[]; + v2?: { + stages?: unknown[]; + }; clarificationDecision?: { decisionSource?: unknown; bypassed?: unknown; @@ -321,6 +348,15 @@ function detectMetadataBypass(run: { if (run.status === "clarification") { return false; } + const intakeStage = findTraceV2Stage(run, "intake"); + const intakeMetadata = + intakeStage && typeof intakeStage.metadata === "object" && intakeStage.metadata !== null + ? (intakeStage.metadata as Record) + : undefined; + if (readString(intakeMetadata?.route) === "metadata") { + return true; + } + const decisionSource = run.trace?.clarificationDecision?.decisionSource; const bypassed = run.trace?.clarificationDecision?.bypassed; const bypassReasonCode = run.trace?.clarificationDecision?.bypassReasonCode; @@ -340,15 +376,49 @@ function detectMetadataBypass(run: { return outputSummary?.semanticIntent === "metadata"; } -function detectStrictSemanticPath(run: { trace?: { steps?: unknown[] } }): boolean { - const semanticStep = findTraceStep(run, "build-semantic-query"); - if (!semanticStep) { +function detectStrictSemanticPath(run: { + trace?: { steps?: unknown[]; v2?: { stages?: unknown[] } }; +}): boolean { + const semanticStage = findTraceV2Stage(run, "semantic-plan"); + if (semanticStage?.status !== undefined && semanticStage.status !== "skipped") { + return true; + } + + const intakeStage = findTraceV2Stage(run, "intake"); + const intakeMetadata = + intakeStage && typeof intakeStage.metadata === "object" && intakeStage.metadata !== null + ? (intakeStage.metadata as Record) + : undefined; + const intakeRoute = readString(intakeMetadata?.route); + if ( + intakeRoute === "metadata" || + intakeRoute === "general" || + intakeRoute === "text_to_sql" || + intakeRoute === "needs_clarification" || + intakeRoute === "unsafe" || + intakeRoute === "unsupported" + ) { + return true; + } + + const legacySemanticStep = findTraceStep(run, "build-semantic-query"); + if (!legacySemanticStep) { return false; } - return semanticStep.status !== "skipped"; + return legacySemanticStep.status !== "skipped"; } -function extractSemanticPlanStatus(run: { trace?: { steps?: unknown[] } }): string | undefined { +function extractSemanticPlanStatus(run: { + trace?: { steps?: unknown[]; v2?: { stages?: unknown[] } }; +}): string | undefined { + const semanticStage = findTraceV2Stage(run, "semantic-plan"); + if (semanticStage) { + const status = readString(semanticStage.status); + if (status) { + return status; + } + } + const semanticStep = findTraceStep(run, "build-semantic-query"); const outputSummary = parseOutputSummary( typeof semanticStep?.outputSummary === "string" @@ -363,16 +433,19 @@ function extractSemanticPlanStatus(run: { trace?: { steps?: unknown[] } }): stri function evaluatePostClarifySemanticPass(run: { status: RunStatus; - trace?: { steps?: unknown[] }; + trace?: { steps?: unknown[]; v2?: { stages?: unknown[] } }; }): boolean { if (run.status === "clarification" || run.status === "failed") { return false; } - const semanticStep = findTraceStep(run, "build-semantic-query"); - if (!semanticStep) { - return false; + + const semanticStage = findTraceV2Stage(run, "semantic-plan"); + if (semanticStage) { + return semanticStage.status === "success"; } - return semanticStep.status === "success"; + + const semanticStep = findTraceStep(run, "build-semantic-query"); + return semanticStep?.status === "success"; } async function readFixture(filePath: string): Promise { @@ -433,7 +506,7 @@ export async function collectClarificationBalanceGate( imports: [AppModule] }).compile(); moduleRef = builtModule; - const graph = builtModule.get(GraphBuilderService); + const chatService = builtModule.get(ChatService); for (const testCase of fixture.cases) { const diagnostics: CaseDiagnostics = { @@ -450,13 +523,12 @@ export async function collectClarificationBalanceGate( }; try { - const firstRun = await graph.run({ - runId: randomUUID(), - sessionId: `clarification-balance:${testCase.id}`, - question: testCase.initialQuestion, - datasourceId: "sqlite_main", - datasourceType: "sqlite" - }); + const session = await chatService.createSession("sqlite_main"); + const firstRun = await chatService.sendMessage( + session.id, + testCase.initialQuestion, + randomUUID() + ); const firstRunStatus = readRunStatus(firstRun.status); diagnostics.firstRunStatus = firstRunStatus; @@ -488,13 +560,11 @@ export async function collectClarificationBalanceGate( trace: firstRun.trace }); if (triggeredClarification && testCase.followUpQuestion) { - const followUpRun = await graph.run({ - runId: randomUUID(), - sessionId: `clarification-balance:${testCase.id}`, - question: testCase.followUpQuestion, - datasourceId: "sqlite_main", - datasourceType: "sqlite" - }); + const followUpRun = await chatService.sendMessage( + session.id, + testCase.followUpQuestion, + randomUUID() + ); diagnostics.followUpRunStatus = readRunStatus(followUpRun.status); diagnostics.strictSemanticPathDetected = diagnostics.strictSemanticPathDetected || diff --git a/apps/backend/scripts/collect-text2sql-v2-eval-gate.ts b/apps/backend/scripts/collect-text2sql-v2-eval-gate.ts new file mode 100644 index 0000000..99d7a90 --- /dev/null +++ b/apps/backend/scripts/collect-text2sql-v2-eval-gate.ts @@ -0,0 +1,344 @@ +import { existsSync, readFileSync } from "node:fs"; +import { resolve } from "node:path"; +import type { + NoLegacyCompatReport +} from "../../../scripts/check-text2sql-no-legacy-compat"; +import { evaluateNoLegacyCompat } from "../../../scripts/check-text2sql-no-legacy-compat"; +import { + evaluateFocusedCoverageGate, + type CloseoutFlowMatrix, + type FocusedCoverageGateReport +} from "./collect-text2sql-v2-focused-coverage-gate"; +import { + Text2SqlV2EvaluationService, + type Text2SqlV2EvalCase, + type Text2SqlV2EvalSummary +} from "../src/modules/conversation/runtime/evaluation/text2sql-v2-evaluation.service"; + +interface CharacterizationSurface { + version: string; + stageOrder: string[]; + stageArtifactCount: number; + hasSemanticPlan: boolean; +} + +interface CharacterizationCase { + id: string; + scenario: string; + expectedStageOrder: string[]; + surfaces: Record; +} + +interface CharacterizationSummary { + totalCases: number; + parityPassCount: number; + parityCoverageRate: number; + gatePass: boolean; + reasons: string[]; +} + +interface GateSnapshot { + gatePass: boolean; + reasons: string[]; +} + +interface FocusedCoverageGateSnapshot extends GateSnapshot { + coveragePath: string; + matrixPath: string; + report?: FocusedCoverageGateReport; +} + +interface NoLegacyGateSnapshot extends GateSnapshot { + scannedCount: number; +} + +interface Text2SqlV2CloseoutGateReport { + generatedAt: string; + fixturePath: string; + characterizationFixturePath: string; + summary: Text2SqlV2EvalSummary; + characterization: CharacterizationSummary; + closeoutGates: { + evalMetrics: GateSnapshot; + evalTraceability: GateSnapshot; + characterization: GateSnapshot; + noLegacyCompat: NoLegacyGateSnapshot; + focusedCoverage: FocusedCoverageGateSnapshot; + }; + rollout: { + gatePass: boolean; + recommendedStage: "direct_v2_go" | "hold" | "rollback_or_hold"; + rollbackSuggested: boolean; + reasons: string[]; + }; +} + +export function summarizeCharacterization(cases: CharacterizationCase[]): CharacterizationSummary { + const surfaceNames = ["sync", "stream", "replay", "runView", "saveView"]; + if (cases.length === 0) { + return { + totalCases: 0, + parityPassCount: 0, + parityCoverageRate: 0, + gatePass: false, + reasons: ["characterization_fixture_empty"] + }; + } + + let parityPassCount = 0; + const failedIds: string[] = []; + + for (const item of cases) { + const surfaceRecords = surfaceNames.map((name) => item.surfaces[name]); + const hasMissingSurface = surfaceRecords.some((surface) => !surface); + if (hasMissingSurface || item.expectedStageOrder.length === 0) { + failedIds.push(item.id); + continue; + } + + const stageOrderMatch = surfaceRecords.every((surface) => + JSON.stringify(surface.stageOrder) === JSON.stringify(item.expectedStageOrder) + ); + const versionMatch = surfaceRecords.every((surface) => surface.version === "v2"); + const artifactCountMatch = surfaceRecords.every( + (surface) => surface.stageArtifactCount >= item.expectedStageOrder.length + ); + const semanticPlanParity = + new Set(surfaceRecords.map((surface) => surface.hasSemanticPlan)).size === 1; + + if (stageOrderMatch && versionMatch && artifactCountMatch && semanticPlanParity) { + parityPassCount += 1; + } else { + failedIds.push(item.id); + } + } + + const parityCoverageRate = Number((parityPassCount / cases.length).toFixed(4)); + const reasons = + failedIds.length > 0 + ? [`characterization_parity_failed:${failedIds.join(",")}`] + : []; + + return { + totalCases: cases.length, + parityPassCount, + parityCoverageRate, + gatePass: failedIds.length === 0, + reasons + }; +} + +function traceabilityReasons(summary: Text2SqlV2EvalSummary): string[] { + return summary.traceability.familyCoverage.flatMap((item) => + item.reasons.map((reason) => `family:${item.family}:${reason}`) + ); +} + +function buildNoLegacyGateSnapshot(report: NoLegacyCompatReport): NoLegacyGateSnapshot { + const reasons = report.violations.map( + (item) => `${item.file}:${item.line}:${item.column}:${item.label}` + ); + return { + gatePass: report.gatePass, + reasons, + scannedCount: report.scannedCount + }; +} + +function readJson(filePath: string): T { + return JSON.parse(readFileSync(filePath, "utf-8")) as T; +} + +function collectFocusedCoverageGate(params: { + coveragePath: string; + matrixPath: string; +}): FocusedCoverageGateSnapshot { + const missingReasons: string[] = []; + if (!existsSync(params.coveragePath)) { + missingReasons.push("coverage_json_missing"); + } + if (!existsSync(params.matrixPath)) { + missingReasons.push("flow_matrix_missing"); + } + if (missingReasons.length > 0) { + return { + gatePass: false, + reasons: missingReasons, + coveragePath: params.coveragePath, + matrixPath: params.matrixPath + }; + } + + const report = evaluateFocusedCoverageGate({ + coverage: readJson>(params.coveragePath) as never, + matrix: readJson(params.matrixPath), + coveragePath: params.coveragePath, + matrixPath: params.matrixPath + }); + return { + gatePass: report.rollout.gatePass, + reasons: report.rollout.reasons, + coveragePath: params.coveragePath, + matrixPath: params.matrixPath, + report + }; +} + +export function buildCloseoutRollout(params: { + summary: Text2SqlV2EvalSummary; + characterization: CharacterizationSummary; + noLegacy: NoLegacyGateSnapshot; + focusedCoverage: FocusedCoverageGateSnapshot; +}): { + gatePass: boolean; + recommendedStage: "direct_v2_go" | "hold" | "rollback_or_hold"; + rollbackSuggested: boolean; + reasons: string[]; + closeoutGates: Text2SqlV2CloseoutGateReport["closeoutGates"]; +} { + const evalMetrics: GateSnapshot = { + gatePass: params.summary.rollout.gatePass, + reasons: params.summary.rollout.reasons + }; + const evalTraceability: GateSnapshot = { + gatePass: params.summary.traceability.gatePass, + reasons: traceabilityReasons(params.summary) + }; + const characterizationGate: GateSnapshot = { + gatePass: params.characterization.gatePass, + reasons: params.characterization.reasons + }; + + const reasons = [ + ...evalMetrics.reasons.map((item) => `eval:${item}`), + ...evalTraceability.reasons.map((item) => `traceability:${item}`), + ...characterizationGate.reasons.map((item) => `characterization:${item}`), + ...params.noLegacy.reasons.map((item) => `no_legacy:${item}`), + ...params.focusedCoverage.reasons.map((item) => `focused_coverage:${item}`) + ]; + + const gatePass = + evalMetrics.gatePass && + evalTraceability.gatePass && + characterizationGate.gatePass && + params.noLegacy.gatePass && + params.focusedCoverage.gatePass; + + const rollbackSuggested = + params.summary.rollout.rollbackSuggested || + reasons.some((item) => item.startsWith("focused_coverage:critical:")); + + return { + gatePass, + recommendedStage: gatePass + ? "direct_v2_go" + : rollbackSuggested + ? "rollback_or_hold" + : "hold", + rollbackSuggested, + reasons, + closeoutGates: { + evalMetrics, + evalTraceability, + characterization: characterizationGate, + noLegacyCompat: params.noLegacy, + focusedCoverage: params.focusedCoverage + } + }; +} + +export async function collectText2SqlV2EvalGate(params: { + fixturePath: string; + characterizationFixturePath: string; + focusedCoveragePath: string; + focusedMatrixPath: string; +}): Promise { + const cases = readJson(params.fixturePath); + const characterizationCases = readJson( + params.characterizationFixturePath + ); + + const service = new Text2SqlV2EvaluationService(); + const summary = service.summarize(cases); + const characterization = summarizeCharacterization(characterizationCases); + const noLegacyReport = await evaluateNoLegacyCompat(); + const noLegacy = buildNoLegacyGateSnapshot(noLegacyReport); + const focusedCoverage = collectFocusedCoverageGate({ + coveragePath: params.focusedCoveragePath, + matrixPath: params.focusedMatrixPath + }); + + const closeout = buildCloseoutRollout({ + summary, + characterization, + noLegacy, + focusedCoverage + }); + + return { + generatedAt: new Date().toISOString(), + fixturePath: params.fixturePath, + characterizationFixturePath: params.characterizationFixturePath, + summary, + characterization, + closeoutGates: closeout.closeoutGates, + rollout: { + gatePass: closeout.gatePass, + recommendedStage: closeout.recommendedStage, + rollbackSuggested: closeout.rollbackSuggested, + reasons: closeout.reasons + } + }; +} + +function parseArgs(argv: string[]): { + fixturePath: string; + characterizationFixturePath: string; + focusedCoveragePath: string; + focusedMatrixPath: string; + failOnGate: boolean; +} { + const fixturePath = argv.find((item) => item.startsWith("--eval-fixture="))?.split("=")[1]; + const characterizationFixturePath = argv + .find((item) => item.startsWith("--characterization-fixture=")) + ?.split("=")[1]; + const focusedCoveragePath = argv + .find((item) => item.startsWith("--coverage-json=")) + ?.split("=")[1]; + const focusedMatrixPath = argv.find((item) => item.startsWith("--matrix="))?.split("=")[1]; + const failOnGate = argv.includes("--fail-on-gate") || argv.includes("--strict"); + + return { + fixturePath: + fixturePath ?? + resolve(__dirname, "../test/fixtures/text2sql-v2-eval-cases.json"), + characterizationFixturePath: + characterizationFixturePath ?? + resolve(__dirname, "../test/fixtures/text2sql-v2-characterization-cases.json"), + focusedCoveragePath: + focusedCoveragePath ?? + resolve(__dirname, "../coverage/coverage-final.json"), + focusedMatrixPath: + focusedMatrixPath ?? + resolve(__dirname, "../test/fixtures/text2sql-v2-closeout-flow-matrix.json"), + failOnGate + }; +} + +async function main(): Promise { + const args = parseArgs(process.argv.slice(2)); + const report = await collectText2SqlV2EvalGate({ + fixturePath: args.fixturePath, + characterizationFixturePath: args.characterizationFixturePath, + focusedCoveragePath: args.focusedCoveragePath, + focusedMatrixPath: args.focusedMatrixPath + }); + process.stdout.write(`${JSON.stringify(report, null, 2)}\n`); + if (args.failOnGate && !report.rollout.gatePass) { + process.exitCode = 1; + } +} + +if (require.main === module) { + void main(); +} diff --git a/apps/backend/scripts/collect-text2sql-v2-focused-coverage-gate.ts b/apps/backend/scripts/collect-text2sql-v2-focused-coverage-gate.ts new file mode 100644 index 0000000..b7e7c72 --- /dev/null +++ b/apps/backend/scripts/collect-text2sql-v2-focused-coverage-gate.ts @@ -0,0 +1,962 @@ +import { existsSync, readFileSync } from "node:fs"; +import { resolve } from "node:path"; + +type CoverageCounts = Record; + +interface IstanbulLocation { + start?: { line?: number }; +} + +interface IstanbulFileCoverage { + path?: string; + statementMap?: Record; + s?: CoverageCounts; + branchMap?: Record; + b?: CoverageCounts; +} + +type IstanbulCoverageMap = Record; + +interface CoverageSummary { + linePct: number; + branchPct: number; + coveredLines: number; + totalLines: number; + coveredBranches: number; + totalBranches: number; +} + +interface CriticalFileThreshold { + file: string; + line: number; +} + +interface FlowMatrixNode { + id: string; + requirementIds: string[]; + implementationOwners: string[]; + evidenceOwners: string[]; + expectedTestFiles: string[]; + gateRelevance: boolean; + behaviorTestStatus: "covered" | "partial" | "missing" | "planned"; + coverageOwnerStatus: "covered" | "partial" | "missing" | "planned"; + canonicalRuntimeOwners?: string[]; + canonicalOwnerStatus?: "covered" | "partial" | "missing" | "planned"; + contractAssertionMode?: "behavior_contract" | "legacy_runtime_detail"; +} + +interface StrictCompletionRow { + id: string; + implementationOwners: string[]; + evidenceOwners: string[]; + expectedTestFiles: string[]; + behaviorTestStatus: "covered" | "partial" | "missing" | "planned"; + coverageOwnerStatus: "covered" | "partial" | "missing" | "planned"; + contractAssertionMode?: "behavior_contract" | "legacy_runtime_detail"; +} + +interface EvalFixtureFamily { + family: string; + evalCases: string[]; + behaviorTests: string[]; + flowNodes: string[]; +} + +interface CriticalFileOwnerMigration { + from: string; + to: string; + reason: string; + threshold?: { line?: number }; +} + +interface RuntimeCoverageRow { + id: string; + owners: string[]; + expectedTestFiles: string[]; + coverageOwnerStatus: "covered" | "partial" | "missing" | "planned"; + critical: boolean; + blocker?: string; +} + +interface RuntimeArtifactProducerRow { + category: string; + producerOwners: string[]; + evidenceOwners: string[]; + expectedTestFiles: string[]; + behaviorTestStatus: "covered" | "partial" | "missing" | "planned"; + coverageOwnerStatus: "covered" | "partial" | "missing" | "planned"; +} + +interface StreamLifecycleCoverageRow { + stage: string; + lifecycles: string[]; + owners: string[]; + expectedTestFiles: string[]; + behaviorTestStatus: "covered" | "partial" | "missing" | "planned"; + coverageOwnerStatus: "covered" | "partial" | "missing" | "planned"; +} + +interface RuntimePathPlan { + currentActivePath: string[]; + targetActivePath: string[]; + criticalOwners: string[]; + blockerPolicy: string; + delegationPolicy?: string; + delegationOwners?: string[]; + delegationForbiddenPatterns?: string[]; +} + +export interface CloseoutFlowMatrix { + version: string; + nodes: FlowMatrixNode[]; + strictCompletionRows?: StrictCompletionRow[]; + evalFixtureFamilies: EvalFixtureFamily[]; + criticalFileOwnerMigrations?: CriticalFileOwnerMigration[]; + runtimeCoverageRows?: RuntimeCoverageRow[]; + runtimeArtifactProducerRows?: RuntimeArtifactProducerRow[]; + streamLifecycleRows?: StreamLifecycleCoverageRow[]; + runtimePaths?: RuntimePathPlan; +} + +interface CriticalFileResult { + file: string; + effectiveFile: string; + linePct: number; + threshold: number; + gatePass: boolean; + migrated: boolean; + reasons: string[]; +} + +export interface FocusedCoverageGateReport { + generatedAt: string; + coveragePath: string; + matrixPath: string; + scoped: CoverageSummary & { gatePass: boolean; files: string[]; reasons: string[] }; + criticalFiles: CriticalFileResult[]; + delegationZero: DelegationZeroGateReport; + flowMatrix: { + version: string; + nodeCount: number; + completeNodeCount: number; + incompleteNodes: Array<{ id: string; reasons: string[] }>; + evalFixtureFamilyCount: number; + incompleteEvalFixtureFamilies: Array<{ family: string; reasons: string[] }>; + strictCompletionRowCount: number; + incompleteStrictCompletionRows: Array<{ id: string; reasons: string[] }>; + runtimeCoverageRowCount: number; + incompleteRuntimeCoverageRows: Array<{ id: string; reasons: string[] }>; + runtimeArtifactProducerRowCount: number; + incompleteRuntimeArtifactProducerRows: Array<{ category: string; reasons: string[] }>; + streamLifecycleRowCount: number; + incompleteStreamLifecycleRows: Array<{ stage: string; reasons: string[] }>; + runtimePathReasons: string[]; + gatePass: boolean; + }; + rollout: { + gatePass: boolean; + recommendedStage: "closeout_ready" | "hold"; + rollbackSuggested: boolean; + reasons: string[]; + }; +} + +export interface DelegationZeroViolation { + file: string; + label: string; + pattern: string; +} + +export interface DelegationZeroGateReport { + gatePass: boolean; + scannedFiles: string[]; + violations: DelegationZeroViolation[]; + reasons: string[]; +} + +interface DelegationZeroScanRule { + file: string; + fallbackFile?: string; + label: string; + pattern: RegExp; +} + +const SCOPED_THRESHOLDS = { + line: 80, + branch: 70 +}; + +const REQUIRED_RUNTIME_ARTIFACT_CATEGORIES = [ + "context_snippets", + "schema_supplement", + "prompt_input", + "provider_output_summary", + "validation_diagnostics", + "correction_grounding", + "execution_preview" +] as const; + +const REQUIRED_STREAM_LIFECYCLE_STAGES = [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" +] as const; + +const LAYERED_RUNTIME_STAGE_OWNER = + "apps/backend/src/modules/conversation/runtime/stages/run-v2-langgraph.stage.ts"; +const LAYERED_LANGGRAPH_GRAPH_OWNER = + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts"; +const LEGACY_LANGGRAPH_GRAPH_OWNER = + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts"; +const LAYERED_LANGGRAPH_RUNNER_OWNER = + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts"; +const LEGACY_LANGGRAPH_RUNNER_OWNER = + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts"; +const LAYERED_LANGGRAPH_RESULT_MAPPER_OWNER = + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper.ts"; +const LAYERED_INTAKE_NODE_OWNER = + "apps/backend/src/modules/conversation/nodes/intake.node.ts"; +const LAYERED_SQL_CORRECTION_OWNER = + "apps/backend/src/modules/conversation/adapters/sql-correction.service.ts"; +const LAYERED_SQL_VALIDATION_OWNER = + "apps/backend/src/modules/conversation/adapters/sql-validation.service.ts"; +const LAYERED_SEMANTIC_CONTEXT_PACK_OWNER = + "apps/backend/src/modules/conversation/adapters/semantic-context-pack.service.ts"; + +const CRITICAL_FILE_THRESHOLDS: CriticalFileThreshold[] = [ + { + file: LAYERED_SQL_CORRECTION_OWNER, + line: 75 + }, + { + file: LAYERED_LANGGRAPH_RUNNER_OWNER, + line: 80 + }, + { + file: LAYERED_SQL_VALIDATION_OWNER, + line: 75 + }, + { + file: LAYERED_SEMANTIC_CONTEXT_PACK_OWNER, + line: 75 + }, + { + file: "apps/backend/src/modules/llm/embedding-router.service.ts", + line: 75 + }, + { + file: LAYERED_RUNTIME_STAGE_OWNER, + line: 80 + }, + { + file: LAYERED_LANGGRAPH_GRAPH_OWNER, + line: 80 + }, + { + file: LAYERED_LANGGRAPH_RESULT_MAPPER_OWNER, + line: 80 + }, + { + file: LAYERED_INTAKE_NODE_OWNER, + line: 75 + } +]; + +const DELEGATION_ZERO_SCAN_RULES: DelegationZeroScanRule[] = [ + { + file: LAYERED_LANGGRAPH_GRAPH_OWNER, + fallbackFile: LEGACY_LANGGRAPH_GRAPH_OWNER, + label: "legacy runtime delegation", + pattern: /\brunLegacyRuntime\b/ + }, + { + file: LAYERED_LANGGRAPH_GRAPH_OWNER, + fallbackFile: LEGACY_LANGGRAPH_GRAPH_OWNER, + label: "legacy runner instance", + pattern: /\blegacyRunner\b/ + }, + { + file: LAYERED_LANGGRAPH_RUNNER_OWNER, + fallbackFile: LEGACY_LANGGRAPH_RUNNER_OWNER, + label: "legacy v2 runner import", + pattern: /\bText2SqlV2RunnerService\b/ + }, + { + file: LAYERED_LANGGRAPH_RUNNER_OWNER, + fallbackFile: LEGACY_LANGGRAPH_RUNNER_OWNER, + label: "legacy runtime callback", + pattern: /\brunLegacyRuntime\b/ + } +]; + +function toPosixPath(pathname: string): string { + return pathname.replace(/\\/g, "/"); +} + +function pct(covered: number, total: number): number { + if (total === 0) { + return 100; + } + return Number(((covered / total) * 100).toFixed(2)); +} + +function summarizeFile(fileCoverage: IstanbulFileCoverage): CoverageSummary { + const lineCoverage = new Map(); + const statementMap = fileCoverage.statementMap ?? {}; + const statements = fileCoverage.s ?? {}; + + for (const [statementId, location] of Object.entries(statementMap)) { + const line = location.start?.line; + if (typeof line !== "number") { + continue; + } + const hitCount = statements[statementId]; + const covered = typeof hitCount === "number" ? hitCount > 0 : false; + lineCoverage.set(line, (lineCoverage.get(line) ?? false) || covered); + } + + let coveredBranches = 0; + let totalBranches = 0; + for (const branchHits of Object.values(fileCoverage.b ?? {})) { + const hits = Array.isArray(branchHits) ? branchHits : [branchHits]; + for (const hit of hits) { + totalBranches += 1; + if (typeof hit === "number" && hit > 0) { + coveredBranches += 1; + } + } + } + + const totalLines = lineCoverage.size; + const coveredLines = [...lineCoverage.values()].filter(Boolean).length; + + return { + linePct: pct(coveredLines, totalLines), + branchPct: pct(coveredBranches, totalBranches), + coveredLines, + totalLines, + coveredBranches, + totalBranches + }; +} + +function mergeSummaries(summaries: CoverageSummary[]): CoverageSummary { + const totalLines = summaries.reduce((sum, item) => sum + item.totalLines, 0); + const coveredLines = summaries.reduce((sum, item) => sum + item.coveredLines, 0); + const totalBranches = summaries.reduce((sum, item) => sum + item.totalBranches, 0); + const coveredBranches = summaries.reduce((sum, item) => sum + item.coveredBranches, 0); + + return { + linePct: pct(coveredLines, totalLines), + branchPct: pct(coveredBranches, totalBranches), + coveredLines, + totalLines, + coveredBranches, + totalBranches + }; +} + +function findCoverageEntry( + coverage: IstanbulCoverageMap, + repoRelativeFile: string +): IstanbulFileCoverage | undefined { + const normalizedTarget = toPosixPath(repoRelativeFile); + for (const [coverageKey, entry] of Object.entries(coverage)) { + const candidates = [coverageKey, entry.path ?? ""].map(toPosixPath); + if (candidates.some((candidate) => candidate.endsWith(normalizedTarget))) { + return entry; + } + } + return undefined; +} + +function unique(items: string[]): string[] { + return [...new Set(items)].sort(); +} + +function findForwardMigration( + matrix: CloseoutFlowMatrix, + file: string +): CriticalFileOwnerMigration | undefined { + return matrix.criticalFileOwnerMigrations?.find((item) => item.from === file); +} + +function findReverseMigration( + matrix: CloseoutFlowMatrix, + file: string +): CriticalFileOwnerMigration | undefined { + return matrix.criticalFileOwnerMigrations?.find((item) => item.to === file); +} + +function resolveCriticalFile( + coverage: IstanbulCoverageMap, + matrix: CloseoutFlowMatrix, + threshold: CriticalFileThreshold +): { file: string; entry?: IstanbulFileCoverage; migrated: boolean; reason?: string; lineThreshold: number } { + const forwardMigration = findForwardMigration(matrix, threshold.file); + if (forwardMigration) { + const migratedEntry = findCoverageEntry(coverage, forwardMigration.to); + if (migratedEntry) { + return { + file: forwardMigration.to, + entry: migratedEntry, + migrated: true, + reason: forwardMigration.reason, + lineThreshold: forwardMigration.threshold?.line ?? threshold.line + }; + } + } + + const directEntry = findCoverageEntry(coverage, threshold.file); + if (directEntry) { + return { + file: threshold.file, + entry: directEntry, + migrated: false, + lineThreshold: threshold.line + }; + } + + const reverseMigration = findReverseMigration(matrix, threshold.file); + if (reverseMigration) { + const fallbackEntry = findCoverageEntry(coverage, reverseMigration.from); + if (fallbackEntry) { + return { + file: reverseMigration.from, + entry: fallbackEntry, + migrated: true, + reason: reverseMigration.reason, + lineThreshold: reverseMigration.threshold?.line ?? threshold.line + }; + } + } + + if (!forwardMigration && !reverseMigration) { + return { + file: threshold.file, + migrated: false, + reason: "critical_file_missing_without_owner_migration", + lineThreshold: threshold.line + }; + } + + if (forwardMigration) { + return { + file: forwardMigration.to, + entry: findCoverageEntry(coverage, forwardMigration.to), + migrated: true, + reason: forwardMigration.reason, + lineThreshold: forwardMigration.threshold?.line ?? threshold.line + }; + } + + return { + file: reverseMigration?.from ?? threshold.file, + entry: reverseMigration + ? findCoverageEntry(coverage, reverseMigration.from) + : undefined, + migrated: Boolean(reverseMigration), + reason: reverseMigration?.reason, + lineThreshold: reverseMigration?.threshold?.line ?? threshold.line + }; +} + +function evaluateCriticalFiles( + coverage: IstanbulCoverageMap, + matrix: CloseoutFlowMatrix +): CriticalFileResult[] { + return CRITICAL_FILE_THRESHOLDS.map((threshold) => { + const resolved = resolveCriticalFile(coverage, matrix, threshold); + const reasons: string[] = []; + + if (!resolved.entry) { + reasons.push(resolved.reason ?? "critical_file_missing_from_coverage"); + return { + file: threshold.file, + effectiveFile: resolved.file, + linePct: 0, + threshold: resolved.lineThreshold, + gatePass: false, + migrated: resolved.migrated, + reasons + }; + } + + const summary = summarizeFile(resolved.entry); + if (summary.linePct === 0) { + reasons.push("critical_file_zero_line_coverage"); + } + if (summary.linePct < resolved.lineThreshold) { + reasons.push(`line_coverage_below_${resolved.lineThreshold}`); + } + if (resolved.migrated && !resolved.reason) { + reasons.push("owner_migration_missing_reason"); + } + + return { + file: threshold.file, + effectiveFile: resolved.file, + linePct: summary.linePct, + threshold: resolved.lineThreshold, + gatePass: reasons.length === 0, + migrated: resolved.migrated, + reasons + }; + }); +} + +function evaluateDelegationZero(repoRoot: string): DelegationZeroGateReport { + const scannedFiles = new Set(); + const violations: DelegationZeroViolation[] = []; + + for (const rule of DELEGATION_ZERO_SCAN_RULES) { + const candidateFiles = [rule.file, rule.fallbackFile].filter( + (item): item is string => typeof item === "string" && item.length > 0 + ); + const selectedFile = candidateFiles.find((file) => + existsSync(resolve(repoRoot, file)) + ); + + if (!selectedFile) { + violations.push({ + file: rule.file, + label: `${rule.label}:missing_file`, + pattern: rule.pattern.source + }); + continue; + } + scannedFiles.add(selectedFile); + const content = readFileSync(resolve(repoRoot, selectedFile), "utf-8"); + if (rule.pattern.test(content)) { + violations.push({ + file: selectedFile, + label: rule.label, + pattern: rule.pattern.source + }); + } + } + + return { + gatePass: violations.length === 0, + scannedFiles: unique([...scannedFiles]), + violations, + reasons: violations.map( + (item) => `${item.file}:${item.label}:${item.pattern}` + ) + }; +} + +function evaluateFlowMatrix(matrix: CloseoutFlowMatrix): FocusedCoverageGateReport["flowMatrix"] { + const incompleteNodes = matrix.nodes.flatMap((node) => { + const reasons: string[] = []; + if (node.requirementIds.length === 0) { + reasons.push("missing_requirement_ids"); + } + if (node.implementationOwners.length === 0) { + reasons.push("missing_implementation_owners"); + } + if (node.evidenceOwners.length === 0) { + reasons.push("missing_evidence_owners"); + } + if (node.expectedTestFiles.length === 0) { + reasons.push("missing_expected_behavior_tests"); + } + if (node.behaviorTestStatus !== "covered") { + reasons.push(`behavior_test_status_${node.behaviorTestStatus}`); + } + if (node.coverageOwnerStatus !== "covered") { + reasons.push(`coverage_owner_status_${node.coverageOwnerStatus}`); + } + if (!node.canonicalRuntimeOwners || node.canonicalRuntimeOwners.length === 0) { + reasons.push("missing_canonical_runtime_owners"); + } + if (!node.canonicalOwnerStatus) { + reasons.push("missing_canonical_owner_status"); + } else if (node.canonicalOwnerStatus === "missing") { + reasons.push("canonical_owner_status_missing"); + } + if (node.contractAssertionMode !== "behavior_contract") { + reasons.push( + `contract_assertion_mode_${node.contractAssertionMode ?? "missing"}` + ); + } + return reasons.length > 0 ? [{ id: node.id, reasons }] : []; + }); + + const incompleteEvalFixtureFamilies = matrix.evalFixtureFamilies.flatMap((family) => { + const reasons: string[] = []; + if (family.evalCases.length === 0) { + reasons.push("missing_eval_cases"); + } + if (family.behaviorTests.length === 0) { + reasons.push("missing_behavior_test_traceability"); + } + if (family.flowNodes.length === 0) { + reasons.push("missing_flow_node_traceability"); + } + return reasons.length > 0 ? [{ family: family.family, reasons }] : []; + }); + + const incompleteStrictCompletionRows = (matrix.strictCompletionRows ?? []).flatMap( + (row) => { + const reasons: string[] = []; + if (row.implementationOwners.length === 0) { + reasons.push("missing_implementation_owners"); + } + if (row.evidenceOwners.length === 0) { + reasons.push("missing_evidence_owners"); + } + if (row.expectedTestFiles.length === 0) { + reasons.push("missing_expected_behavior_tests"); + } + if (row.behaviorTestStatus !== "covered") { + reasons.push(`behavior_test_status_${row.behaviorTestStatus}`); + } + if (row.coverageOwnerStatus !== "covered") { + reasons.push(`coverage_owner_status_${row.coverageOwnerStatus}`); + } + if (row.contractAssertionMode !== "behavior_contract") { + reasons.push( + `contract_assertion_mode_${row.contractAssertionMode ?? "missing"}` + ); + } + return reasons.length > 0 ? [{ id: row.id, reasons }] : []; + } + ); + + const incompleteRuntimeCoverageRows = (matrix.runtimeCoverageRows ?? []).flatMap((row) => { + const reasons: string[] = []; + if (row.owners.length === 0) { + reasons.push("missing_runtime_owners"); + } + if (row.expectedTestFiles.length === 0) { + reasons.push("missing_runtime_expected_tests"); + } + if (row.coverageOwnerStatus === "missing") { + reasons.push("runtime_coverage_owner_status_missing"); + } + if (row.critical && typeof row.blocker !== "string") { + reasons.push("missing_runtime_blocker"); + } + return reasons.length > 0 ? [{ id: row.id, reasons }] : []; + }); + + const artifactProducerRows = matrix.runtimeArtifactProducerRows ?? []; + const incompleteRuntimeArtifactProducerRows = REQUIRED_RUNTIME_ARTIFACT_CATEGORIES.flatMap( + (category) => { + const row = artifactProducerRows.find((item) => item.category === category); + const reasons: string[] = []; + if (!row) { + reasons.push("missing_artifact_producer_row"); + return [{ category, reasons }]; + } + if (row.producerOwners.length === 0) { + reasons.push("missing_artifact_producer_owners"); + } + if (row.evidenceOwners.length === 0) { + reasons.push("missing_artifact_evidence_owners"); + } + if (row.expectedTestFiles.length === 0) { + reasons.push("missing_artifact_behavior_tests"); + } + if (row.behaviorTestStatus !== "covered") { + reasons.push(`behavior_test_status_${row.behaviorTestStatus}`); + } + if (row.coverageOwnerStatus !== "covered") { + reasons.push(`coverage_owner_status_${row.coverageOwnerStatus}`); + } + return reasons.length > 0 ? [{ category, reasons }] : []; + } + ); + + const streamLifecycleRows = matrix.streamLifecycleRows ?? []; + const incompleteStreamLifecycleRows = REQUIRED_STREAM_LIFECYCLE_STAGES.flatMap( + (stage) => { + const row = streamLifecycleRows.find((item) => item.stage === stage); + const reasons: string[] = []; + if (!row) { + reasons.push("missing_stream_lifecycle_row"); + return [{ stage, reasons }]; + } + if (!row.lifecycles.includes("running")) { + reasons.push("missing_running_lifecycle"); + } + if ( + !row.lifecycles.includes("completed") && + !row.lifecycles.includes("skipped") && + !row.lifecycles.includes("failed") && + !row.lifecycles.includes("clarification") + ) { + reasons.push("missing_terminal_lifecycle"); + } + if (row.owners.length === 0) { + reasons.push("missing_stream_lifecycle_owners"); + } + if (row.expectedTestFiles.length === 0) { + reasons.push("missing_stream_lifecycle_tests"); + } + if (row.behaviorTestStatus !== "covered") { + reasons.push(`behavior_test_status_${row.behaviorTestStatus}`); + } + if (row.coverageOwnerStatus !== "covered") { + reasons.push(`coverage_owner_status_${row.coverageOwnerStatus}`); + } + return reasons.length > 0 ? [{ stage, reasons }] : []; + } + ); + + const runtimePathReasons: string[] = []; + if (!matrix.runtimePaths) { + runtimePathReasons.push("missing_runtime_paths"); + } else { + if ((matrix.runtimePaths.currentActivePath ?? []).length === 0) { + runtimePathReasons.push("missing_runtime_current_active_path"); + } + if ((matrix.runtimePaths.targetActivePath ?? []).length === 0) { + runtimePathReasons.push("missing_runtime_target_active_path"); + } + if ((matrix.runtimePaths.criticalOwners ?? []).length === 0) { + runtimePathReasons.push("missing_runtime_critical_owners"); + } + if ( + typeof matrix.runtimePaths.blockerPolicy !== "string" || + matrix.runtimePaths.blockerPolicy.trim().length === 0 + ) { + runtimePathReasons.push("missing_runtime_blocker_policy"); + } + if ( + typeof matrix.runtimePaths.delegationPolicy !== "string" || + matrix.runtimePaths.delegationPolicy.trim().length === 0 + ) { + runtimePathReasons.push("missing_runtime_delegation_policy"); + } + if ((matrix.runtimePaths.delegationOwners ?? []).length === 0) { + runtimePathReasons.push("missing_runtime_delegation_owners"); + } + if ((matrix.runtimePaths.delegationForbiddenPatterns ?? []).length === 0) { + runtimePathReasons.push("missing_runtime_delegation_patterns"); + } + } + + return { + version: matrix.version, + nodeCount: matrix.nodes.length, + completeNodeCount: matrix.nodes.length - incompleteNodes.length, + incompleteNodes, + evalFixtureFamilyCount: matrix.evalFixtureFamilies.length, + incompleteEvalFixtureFamilies, + strictCompletionRowCount: matrix.strictCompletionRows?.length ?? 0, + incompleteStrictCompletionRows, + runtimeCoverageRowCount: matrix.runtimeCoverageRows?.length ?? 0, + incompleteRuntimeCoverageRows, + runtimeArtifactProducerRowCount: artifactProducerRows.length, + incompleteRuntimeArtifactProducerRows, + streamLifecycleRowCount: streamLifecycleRows.length, + incompleteStreamLifecycleRows, + runtimePathReasons, + gatePass: + incompleteNodes.length === 0 && + incompleteEvalFixtureFamilies.length === 0 && + incompleteStrictCompletionRows.length === 0 && + incompleteRuntimeCoverageRows.length === 0 && + incompleteRuntimeArtifactProducerRows.length === 0 && + incompleteStreamLifecycleRows.length === 0 && + runtimePathReasons.length === 0 + }; +} + +function scopedFilesFromMatrix(matrix: CloseoutFlowMatrix): string[] { + const ownerMigrations = new Map( + (matrix.criticalFileOwnerMigrations ?? []).map((item) => [item.from, item.to]) + ); + const effectiveOwner = (file: string): string => ownerMigrations.get(file) ?? file; + + return unique([ + ...CRITICAL_FILE_THRESHOLDS.map((item) => effectiveOwner(item.file)), + ...matrix.nodes + .filter((node) => node.gateRelevance) + .flatMap((node) => node.implementationOwners.map(effectiveOwner)), + ...(matrix.runtimeArtifactProducerRows ?? []).flatMap((row) => + row.producerOwners.map(effectiveOwner) + ), + ...(matrix.streamLifecycleRows ?? []).flatMap((row) => + row.owners.map(effectiveOwner) + ), + ...(matrix.criticalFileOwnerMigrations ?? []).map((item) => item.to) + ]); +} + +function resolveScopedCoverageEntry( + coverage: IstanbulCoverageMap, + matrix: CloseoutFlowMatrix, + file: string +): IstanbulFileCoverage | undefined { + const directEntry = findCoverageEntry(coverage, file); + if (directEntry) { + return directEntry; + } + const reverseMigration = findReverseMigration(matrix, file); + if (reverseMigration) { + return findCoverageEntry(coverage, reverseMigration.from); + } + return undefined; +} + +export function evaluateFocusedCoverageGate(params: { + coverage: IstanbulCoverageMap; + matrix: CloseoutFlowMatrix; + coveragePath?: string; + matrixPath?: string; + generatedAt?: string; + repoRoot?: string; + delegationZeroOverride?: DelegationZeroGateReport; +}): FocusedCoverageGateReport { + const scopedFiles = scopedFilesFromMatrix(params.matrix); + const scopedReasons: string[] = []; + const scopedSummaries: CoverageSummary[] = []; + + for (const file of scopedFiles) { + const entry = resolveScopedCoverageEntry(params.coverage, params.matrix, file); + if (!entry) { + scopedReasons.push(`missing_scoped_coverage:${file}`); + continue; + } + scopedSummaries.push(summarizeFile(entry)); + } + + const scopedSummary = mergeSummaries(scopedSummaries); + if (scopedSummary.linePct < SCOPED_THRESHOLDS.line) { + scopedReasons.push(`scoped_line_coverage_below_${SCOPED_THRESHOLDS.line}`); + } + if (scopedSummary.branchPct < SCOPED_THRESHOLDS.branch) { + scopedReasons.push(`scoped_branch_coverage_below_${SCOPED_THRESHOLDS.branch}`); + } + + const criticalFiles = evaluateCriticalFiles(params.coverage, params.matrix); + const criticalReasons = criticalFiles.flatMap((item) => + item.reasons.map((reason) => `critical:${item.file}:${reason}`) + ); + const delegationZero = + params.delegationZeroOverride ?? + evaluateDelegationZero(params.repoRoot ?? resolve(__dirname, "../../..")); + const flowMatrix = evaluateFlowMatrix(params.matrix); + const matrixReasons = [ + ...flowMatrix.incompleteNodes.map( + (item) => `flow_node:${item.id}:${item.reasons.join("|")}` + ), + ...flowMatrix.incompleteEvalFixtureFamilies.map( + (item) => `eval_family:${item.family}:${item.reasons.join("|")}` + ), + ...flowMatrix.incompleteStrictCompletionRows.map( + (item) => `strict_row:${item.id}:${item.reasons.join("|")}` + ), + ...flowMatrix.incompleteRuntimeCoverageRows.map( + (item) => `runtime_row:${item.id}:${item.reasons.join("|")}` + ), + ...flowMatrix.incompleteRuntimeArtifactProducerRows.map( + (item) => `artifact_producer:${item.category}:${item.reasons.join("|")}` + ), + ...flowMatrix.incompleteStreamLifecycleRows.map( + (item) => `stream_lifecycle:${item.stage}:${item.reasons.join("|")}` + ), + ...flowMatrix.runtimePathReasons.map((reason) => `runtime_path:${reason}`) + ]; + + const reasons = [ + ...scopedReasons, + ...criticalReasons, + ...matrixReasons, + ...delegationZero.reasons.map((item) => `delegation_zero:${item}`) + ]; + const gatePass = + scopedReasons.length === 0 && + criticalFiles.every((item) => item.gatePass) && + flowMatrix.gatePass && + delegationZero.gatePass; + + return { + generatedAt: params.generatedAt ?? new Date().toISOString(), + coveragePath: params.coveragePath ?? "", + matrixPath: params.matrixPath ?? "", + scoped: { + ...scopedSummary, + gatePass: scopedReasons.length === 0, + files: scopedFiles, + reasons: scopedReasons + }, + criticalFiles, + delegationZero, + flowMatrix, + rollout: { + gatePass, + recommendedStage: gatePass ? "closeout_ready" : "hold", + rollbackSuggested: false, + reasons + } + }; +} + +function readJson(path: string): T { + return JSON.parse(readFileSync(path, "utf-8")) as T; +} + +function parseArgs(argv: string[]): { + coveragePath: string; + matrixPath: string; + failOnGate: boolean; +} { + const coveragePath = argv.find((item) => item.startsWith("--coverage-json="))?.split("=")[1]; + const matrixPath = argv.find((item) => item.startsWith("--matrix="))?.split("=")[1]; + const failOnGate = argv.includes("--fail-on-gate") || argv.includes("--strict"); + + return { + coveragePath: + coveragePath ?? + resolve(__dirname, "../coverage/coverage-final.json"), + matrixPath: + matrixPath ?? + resolve(__dirname, "../test/fixtures/text2sql-v2-closeout-flow-matrix.json"), + failOnGate + }; +} + +function main(): void { + const args = parseArgs(process.argv.slice(2)); + if (!existsSync(args.coveragePath)) { + process.stderr.write( + `[text2sql-v2-focused-coverage-gate] coverage JSON not found: ${args.coveragePath}\n` + + "Run backend Jest with --coverage before collecting this gate.\n" + ); + process.exitCode = 1; + return; + } + if (!existsSync(args.matrixPath)) { + process.stderr.write( + `[text2sql-v2-focused-coverage-gate] flow matrix not found: ${args.matrixPath}\n` + ); + process.exitCode = 1; + return; + } + + const report = evaluateFocusedCoverageGate({ + coverage: readJson(args.coveragePath), + matrix: readJson(args.matrixPath), + coveragePath: args.coveragePath, + matrixPath: args.matrixPath + }); + + process.stdout.write(`${JSON.stringify(report, null, 2)}\n`); + if (args.failOnGate && !report.rollout.gatePass) { + process.exitCode = 1; + } +} + +if (require.main === module) { + main(); +} diff --git a/apps/backend/scripts/reindex-text2sql-semantic-assets.ts b/apps/backend/scripts/reindex-text2sql-semantic-assets.ts new file mode 100644 index 0000000..875f2eb --- /dev/null +++ b/apps/backend/scripts/reindex-text2sql-semantic-assets.ts @@ -0,0 +1,95 @@ +import { NestFactory } from "@nestjs/core"; +import { AppModule } from "../src/app.module"; +import { + SEMANTIC_ASSET_REINDEX_TRIGGERS, + SemanticAssetReindexService, + type SemanticAssetReindexTrigger +} from "../src/modules/knowledge/rag/retrieval/semantic-asset-reindex.service"; + +interface CliArgs { + datasourceId: string; + workspaceId?: string; + triggers: SemanticAssetReindexTrigger[]; + reason?: string; + runId?: string; + force: boolean; + sourceVersion?: string; +} + +async function main(): Promise { + const args = parseArgs(process.argv.slice(2)); + const app = await NestFactory.createApplicationContext(AppModule, { + logger: ["error", "warn"] + }); + try { + const service = app.get(SemanticAssetReindexService); + const result = await service.reindex({ + datasourceId: args.datasourceId, + workspaceId: args.workspaceId, + triggers: args.triggers, + reason: args.reason, + runId: args.runId, + force: args.force, + sourceVersion: args.sourceVersion + }); + process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); + } finally { + await app.close(); + } +} + +function parseArgs(argv: string[]): CliArgs { + const allowedTriggers = new Set(SEMANTIC_ASSET_REINDEX_TRIGGERS); + const options = new Map(); + for (let index = 0; index < argv.length; index += 1) { + const token = argv[index]; + if (!token.startsWith("--")) { + continue; + } + const key = token.slice(2); + const next = argv[index + 1]; + if (!next || next.startsWith("--")) { + options.set(key, [...(options.get(key) ?? []), "true"]); + continue; + } + options.set(key, [...(options.get(key) ?? []), next]); + index += 1; + } + + const datasourceId = (options.get("datasource-id")?.[0] ?? "").trim(); + if (!datasourceId) { + throw new Error("Missing required --datasource-id "); + } + + const triggerInputs = options + .get("trigger") + ?.flatMap((value) => value.split(",").map((part) => part.trim())) + .filter((value) => value.length > 0) ?? ["schema", "embedding_model"]; + + const triggers = Array.from( + new Set( + triggerInputs.filter( + (trigger): trigger is SemanticAssetReindexTrigger => + allowedTriggers.has(trigger as SemanticAssetReindexTrigger) + ) + ) + ); + + if (triggers.length === 0) { + throw new Error( + `No valid --trigger values provided. Allowed: ${SEMANTIC_ASSET_REINDEX_TRIGGERS.join(", ")}` + ); + } + + return { + datasourceId, + workspaceId: options.get("workspace-id")?.[0]?.trim(), + triggers, + reason: options.get("reason")?.[0]?.trim(), + runId: options.get("run-id")?.[0]?.trim(), + sourceVersion: options.get("source-version")?.[0]?.trim(), + force: options.has("force") + }; +} + +void main(); diff --git a/apps/backend/src/modules/chat/chat.controller.ts b/apps/backend/src/modules/chat/chat.controller.ts deleted file mode 100644 index 9fdc7f1..0000000 --- a/apps/backend/src/modules/chat/chat.controller.ts +++ /dev/null @@ -1,304 +0,0 @@ -import { - Body, - Controller, - Delete, - Get, - Patch, - Param, - Post, - Query, - Req, - Res -} from "@nestjs/common"; -import type { Request, Response } from "express"; -import type { - AgentRunResponse, - ApiResponse, - ChatStreamEvent -} from "@text2sql/shared-types"; -import { fail, ok } from "../../common/api-response"; -import { DomainError } from "../../common/domain-error"; -import { CreateSessionDto } from "./dto/create-session.dto"; -import { ListSessionsDto } from "./dto/list-sessions.dto"; -import { RenameSessionDto } from "./dto/rename-session.dto"; -import { SendMessageDto } from "./dto/send-message.dto"; -import { ChatService } from "../conversation/chat/chat.service"; - -@Controller("/api/v1") -export class ChatController { - constructor(private readonly chatService: ChatService) {} - - @Post("/sessions") - async createSession( - @Body() body: CreateSessionDto, - @Req() req: Request, - @Res({ passthrough: true }) res: Response - ): Promise> { - try { - const datasource = body.datasource?.trim(); - if (!datasource) { - throw new DomainError("VALIDATION_ERROR", "datasource 为必填项", 400, { - field: "datasource" - }); - } - const workspaceId = body.workspaceId?.trim() || this.resolveWorkspaceId(req); - const session = await this.chatService.createSession( - datasource, - body.modelCatalogId, - { - workspaceId, - createdByUserId: req.actor?.id, - actor: req.actor - } - ); - return ok(req.requestId, session); - } catch (error) { - return this.toError(req.requestId, error, res); - } - } - - @Get("/sessions") - async listSessions( - @Query() query: ListSessionsDto, - @Req() req: Request, - @Res({ passthrough: true }) res: Response - ): Promise> { - try { - const sessions = await this.chatService.listSessions( - query.status, - query.datasource, - query.view, - { - workspaceId: query.workspaceId?.trim() || this.resolveWorkspaceId(req) - } - ); - return ok(req.requestId, sessions); - } catch (error) { - return this.toError(req.requestId, error, res); - } - } - - @Patch("/sessions/:sessionId") - async renameSession( - @Param("sessionId") sessionId: string, - @Body() body: RenameSessionDto, - @Req() req: Request, - @Res({ passthrough: true }) res: Response - ): Promise> { - try { - if ( - body.title === undefined && - body.debugEnabled === undefined && - body.modelCatalogId === undefined - ) { - throw new DomainError( - "VALIDATION_ERROR", - "至少需要提供 title、debugEnabled 或 modelCatalogId", - 400 - ); - } - const session = await this.chatService.updateSession(sessionId, { - title: body.title, - debugEnabled: body.debugEnabled, - modelCatalogId: body.modelCatalogId - }); - return ok(req.requestId, session); - } catch (error) { - return this.toError(req.requestId, error, res); - } - } - - @Delete("/sessions/:sessionId") - async deleteSession( - @Param("sessionId") sessionId: string, - @Req() req: Request, - @Res({ passthrough: true }) res: Response - ): Promise> { - try { - await this.chatService.deleteSession(sessionId); - return ok(req.requestId, { deleted: true, sessionId }); - } catch (error) { - return this.toError(req.requestId, error, res); - } - } - - @Post("/sessions/:sessionId/messages") - async sendMessage( - @Param("sessionId") sessionId: string, - @Body() body: SendMessageDto, - @Req() req: Request, - @Res({ passthrough: true }) res: Response - ): Promise> { - try { - const run = await this.chatService.sendMessage( - sessionId, - body.message, - req.requestId, - undefined, - req.actor - ); - return ok(req.requestId, { - kind: "agent-run", - outcome: run.status, - run, - delivery: run.delivery, - agent: { - provider: run.provider, - model: run.model, - hasSql: Boolean(run.sql), - hasToolCalls: Boolean(run.trace.toolCalls?.length), - hasError: Boolean(run.error) - } - }); - } catch (error) { - return this.toError(req.requestId, error, res); - } - } - - @Post("/models/:modelCatalogId/probe") - async probeModel( - @Param("modelCatalogId") modelCatalogId: string, - @Req() req: Request, - @Res({ passthrough: true }) res: Response - ): Promise> { - try { - const result = await this.chatService.probeModelConnectivity(modelCatalogId); - return ok(req.requestId, result); - } catch (error) { - return this.toError(req.requestId, error, res); - } - } - - @Post("/sessions/:sessionId/messages/stream") - async streamMessage( - @Param("sessionId") sessionId: string, - @Body() body: SendMessageDto, - @Req() req: Request, - @Res() res: Response - ): Promise { - res.status(200); - res.setHeader("Content-Type", "text/event-stream; charset=utf-8"); - res.setHeader("Cache-Control", "no-cache, no-transform"); - res.setHeader("Connection", "keep-alive"); - res.flushHeaders?.(); - - const sendEvent = (type: string, data: unknown) => { - if (res.writableEnded) { - return; - } - res.write(`event: ${type}\n`); - res.write(`data: ${JSON.stringify(data)}\n\n`); - }; - - try { - await this.chatService.streamMessage( - sessionId, - body.message, - req.requestId, - async (event) => { - sendEvent(event.type, event); - }, - undefined, - req.actor - ); - } catch (error) { - const fallbackEvent: ChatStreamEvent = { - type: "error", - runId: "unavailable", - sessionId, - at: new Date().toISOString(), - data: - error instanceof DomainError - ? { - code: error.code, - message: error.message, - details: error.details ?? null - } - : { - code: "INTERNAL_ERROR", - message: error instanceof Error ? error.message : "未知错误", - details: null - } - }; - sendEvent("error", fallbackEvent); - } finally { - if (!res.writableEnded) { - res.end(); - } - } - } - - @Get("/sessions/:sessionId/messages") - async getMessages( - @Param("sessionId") sessionId: string, - @Query("page") pageRaw = "1", - @Query("pageSize") pageSizeRaw = "0", - @Req() req: Request, - @Res({ passthrough: true }) res: Response - ): Promise> { - try { - const page = Number.parseInt(pageRaw, 10) || 1; - const parsedPageSize = Number.parseInt(pageSizeRaw, 10); - const pageSize = Number.isNaN(parsedPageSize) ? 0 : parsedPageSize; - const data = await this.chatService.getSessionView(sessionId, page, pageSize); - return ok(req.requestId, data); - } catch (error) { - return this.toError(req.requestId, error, res); - } - } - - @Get("/runs/:runId") - async getRun( - @Param("runId") runId: string, - @Req() req: Request, - @Res({ passthrough: true }) res: Response - ): Promise> { - try { - const run = await this.chatService.getRunById(runId); - return ok(req.requestId, run); - } catch (error) { - return this.toError(req.requestId, error, res); - } - } - - private toError( - requestId: string, - error: unknown, - res: Response - ): ApiResponse { - if (error instanceof DomainError) { - res.status(error.statusCode); - return fail(requestId, error.code, error.message, error.details); - } - res.status(500); - return fail( - requestId, - "INTERNAL_ERROR", - error instanceof Error ? error.message : "未知错误" - ); - } - - private resolveWorkspaceId(req: Request): string | undefined { - const headerValue = req.headers["x-workspace-id"]; - if (typeof headerValue === "string") { - const trimmed = headerValue.trim(); - if (trimmed) { - return trimmed; - } - } - if (Array.isArray(headerValue)) { - for (const item of headerValue) { - const trimmed = item.trim(); - if (trimmed) { - return trimmed; - } - } - } - - const workspaceIds = Object.keys(req.actor?.workspaceRoles ?? {}); - if (workspaceIds.length === 1) { - return workspaceIds[0]; - } - return undefined; - } -} diff --git a/apps/backend/src/modules/chat/chat.module.ts b/apps/backend/src/modules/chat/chat.module.ts deleted file mode 100644 index 93d60a8..0000000 --- a/apps/backend/src/modules/chat/chat.module.ts +++ /dev/null @@ -1,30 +0,0 @@ -import { Module } from "@nestjs/common"; -import { AgentModule } from "../conversation/agent/agent.module"; -import { PlatformDataPersistenceModule } from "../platform/data/persistence.module"; -import { DatasourceModule } from "../governance/datasource/datasource.module"; -import { GovernanceAccessModule } from "../governance/access/access.module"; -import { LlmModule } from "../llm/llm.module"; -import { ObservabilityModule } from "../observability/observability.module"; -import { RagModule } from "../rag/rag.module"; -import { DeliveryContractMapper } from "../conversation/delivery/delivery-contract.mapper"; -import { SandboxRuntimeService } from "../conversation/delivery/sandbox/sandbox-runtime.service"; -import { MemoryModule } from "../memory/memory.module"; -import { ChatController } from "./chat.controller"; -import { ChatService } from "./chat.service"; - -@Module({ - imports: [ - AgentModule, - PlatformDataPersistenceModule, - GovernanceAccessModule, - DatasourceModule, - LlmModule, - ObservabilityModule, - RagModule, - MemoryModule - ], - controllers: [ChatController], - providers: [ChatService, DeliveryContractMapper, SandboxRuntimeService], - exports: [ChatService] -}) -export class ChatModule {} diff --git a/apps/backend/src/modules/chat/chat.service.ts b/apps/backend/src/modules/chat/chat.service.ts deleted file mode 100644 index db2a44c..0000000 --- a/apps/backend/src/modules/chat/chat.service.ts +++ /dev/null @@ -1,1043 +0,0 @@ -import { Injectable } from "@nestjs/common"; -import type { - ChatStreamEvent, - ChatSessionView, - ChatMessage, - Datasource, - PromptTemplateTraceEvidenceCompat, - Session, - SessionSyncStatus, - SqlRun -} from "@text2sql/shared-types"; -import { v4 as uuidv4 } from "uuid"; -import { DomainError } from "../../common/domain-error"; -import { GraphBuilderService } from "../conversation/agent/graph/graph.builder"; -import { - resolveAgentReasoningStage, - resolveAgentReasoningTitle, - resolveAgentStepLifecycle -} from "../conversation/agent/graph/agent-step-metadata"; -import { SqlToolRegistryService } from "../conversation/agent/sql/tools/sql-tool-registry.service"; -import { - DeliveryContractMapper, - type DeliveryReplayRecordInput -} from "../conversation/delivery/delivery-contract.mapper"; -import { - type AccessContext -} from "../governance/access/datasource-access-policy.service"; -import { PolicyEvaluatorService } from "../governance/access/policy-evaluator.service"; -import { RedisBufferService } from "../platform/data/cache/index"; -import { - ChatRepository, - WorkspaceDatasourcePolicyRepository -} from "../platform/data/persistence/index"; -import { DatasourceRegistryService } from "../governance/datasource/datasource-registry.service"; -import { ProviderCatalogService } from "../llm/provider-catalog.service"; -import { ProviderRouterService } from "../llm/provider-router.service"; -import { TraceService } from "../observability/trace.service"; -import { RagReplayRepository } from "../rag/observability/rag-replay.repository"; -import { DatasourceService } from "../governance/datasource/datasource.service"; -import { MemoryPromotionService } from "../memory/memory-promotion.service"; -import type { SessionListView } from "./dto/list-sessions.dto"; - -const MODEL_PROBE_PROMPT = { - systemPrompt: "You are a health check assistant. Reply with exactly OK.", - userPrompt: "Reply with OK." -}; - -@Injectable() -export class ChatService { - constructor( - private readonly graphBuilder: GraphBuilderService, - private readonly sqlToolRegistry: SqlToolRegistryService, - private readonly redisBuffer: RedisBufferService, - private readonly repository: ChatRepository, - private readonly datasourceService: DatasourceService, - private readonly policyEvaluatorService: PolicyEvaluatorService, - private readonly workspaceDatasourcePolicyRepository: WorkspaceDatasourcePolicyRepository, - private readonly datasourceRegistry: DatasourceRegistryService, - private readonly providerCatalog: ProviderCatalogService, - private readonly providerRouter: ProviderRouterService, - private readonly traceService: TraceService, - private readonly ragReplayRepository: RagReplayRepository, - private readonly deliveryContractMapper: DeliveryContractMapper, - private readonly memoryPromotionService: MemoryPromotionService - ) {} - - async createSession( - datasource: string, - modelCatalogId?: string, - options?: { - workspaceId?: string; - createdByUserId?: string; - actor?: { - id?: string; - role?: string; - isSystemAdmin?: boolean; - requestedWorkspaceId?: string; - accessContext?: { - actorId?: string; - workspaceId?: string | null; - roleSet?: string[]; - }; - }; - } - ): Promise { - const normalizedDatasource = datasource.trim(); - const normalizedWorkspaceId = options?.workspaceId?.trim() || undefined; - const normalizedCreatedByUserId = - options?.createdByUserId?.trim() || undefined; - if (!normalizedDatasource) { - throw new DomainError("VALIDATION_ERROR", "datasource 为必填项", 400, { - field: "datasource" - }); - } - - if (normalizedWorkspaceId) { - const accessContext = await this.policyEvaluatorService.resolveAccessContext({ - actor: options?.actor ?? { - id: normalizedCreatedByUserId, - role: "user", - requestedWorkspaceId: normalizedWorkspaceId - }, - workspaceId: normalizedWorkspaceId - }); - const visible = await this.policyEvaluatorService.listVisibleDatasources({ - context: accessContext - }); - if (!visible.ids.includes(normalizedDatasource)) { - throw new DomainError( - "DATASOURCE_ACCESS_DENIED", - "当前工作空间未绑定该数据源或无访问权限。", - 403, - { - workspaceId: normalizedWorkspaceId, - datasourceId: normalizedDatasource, - actorId: accessContext.actorId - } - ); - } - } - - const datasourceMeta = await this.datasourceService.assertDatasourceAvailable( - normalizedDatasource - ); - let defaultModel: - | { - id: string; - provider: string; - model: string; - } - | undefined; - if (modelCatalogId) { - const resolved = await this.providerCatalog.resolveModelById(modelCatalogId); - defaultModel = { - id: resolved.id, - provider: resolved.provider, - model: resolved.model - }; - } else { - try { - const resolved = await this.providerCatalog.resolveDefaultModel(); - defaultModel = { - id: resolved.id, - provider: resolved.provider, - model: resolved.model - }; - } catch { - defaultModel = undefined; - } - } - - const session: Session = { - id: uuidv4(), - datasource: normalizedDatasource, - workspaceId: normalizedWorkspaceId ?? null, - createdByUserId: normalizedCreatedByUserId ?? null, - datasourceName: datasourceMeta.name, - datasourceType: datasourceMeta.type, - datasourceStatus: this.normalizeDatasourceStatus(datasourceMeta.status), - createdAt: new Date().toISOString(), - title: "新会话", - modelCatalogId: defaultModel?.id ?? null, - modelProvider: defaultModel?.provider ?? null, - modelName: defaultModel?.model ?? null, - debugEnabled: false, - syncStatus: "healthy", - syncFailedCount: 0, - lastSyncFailureAt: null - }; - await this.repository.createSession(session); - return this.mergeDatasourceMetadata(session, datasourceMeta); - } - - async listSessions( - status?: SessionSyncStatus, - datasource?: string, - view: SessionListView = "all", - options?: { - workspaceId?: string; - } - ): Promise { - const normalizedDatasource = datasource?.trim() || undefined; - const normalizedWorkspaceId = options?.workspaceId?.trim() || undefined; - if (view === "current" && !normalizedDatasource) { - throw new DomainError( - "VALIDATION_ERROR", - "view=current 时 datasource 为必填项", - 400, - { view, field: "datasource" } - ); - } - if (view === "current" && normalizedDatasource) { - await this.datasourceService.getDatasourceOrThrow(normalizedDatasource); - } - - const sessions = await this.repository.listSessions({ - datasource: view === "readonly-history" ? undefined : normalizedDatasource, - statuses: status ? [status] : undefined, - workspaceId: normalizedWorkspaceId - }); - const normalized = await Promise.all( - sessions.map(async (session) => this.mergeDatasourceMetadata(session)) - ); - - if (view === "readonly-history") { - const readonly: Session[] = []; - for (const session of normalized) { - const datasourceStatus = this.normalizeDatasourceStatus( - session.datasourceStatus - ); - if (datasourceStatus === "unavailable" || datasourceStatus === "deleted") { - readonly.push(session); - continue; - } - if (session.workspaceId) { - const stillBound = - await this.workspaceDatasourcePolicyRepository.isDatasourceBound( - session.workspaceId, - session.datasource - ); - if (!stillBound) { - readonly.push(session); - } - } - } - return readonly; - } - - if (view === "current") { - const current: Session[] = []; - for (const session of normalized) { - if (session.datasource !== normalizedDatasource) { - continue; - } - if (this.normalizeDatasourceStatus(session.datasourceStatus) !== "available") { - continue; - } - if (session.workspaceId) { - const stillBound = - await this.workspaceDatasourcePolicyRepository.isDatasourceBound( - session.workspaceId, - session.datasource - ); - if (!stillBound) { - continue; - } - } - current.push(session); - } - return current; - } - - return normalized; - } - - async renameSession(sessionId: string, title: string): Promise { - return this.updateSession(sessionId, { title: title.trim() }); - } - - async updateSession( - sessionId: string, - patch: { - title?: string; - debugEnabled?: boolean; - modelCatalogId?: string; - } - ): Promise { - const sanitizedPatch: { - title?: string; - debugEnabled?: boolean; - modelCatalogId?: string; - modelProvider?: string; - modelName?: string; - } = {}; - - if (patch.title !== undefined) { - const normalizedTitle = patch.title.trim(); - if (!normalizedTitle) { - throw new DomainError("VALIDATION_ERROR", "会话标题不能为空", 400, { - sessionId - }); - } - sanitizedPatch.title = normalizedTitle; - } - if (patch.debugEnabled !== undefined) { - sanitizedPatch.debugEnabled = patch.debugEnabled; - } - if (patch.modelCatalogId !== undefined) { - const modelId = patch.modelCatalogId.trim(); - if (!modelId) { - throw new DomainError("VALIDATION_ERROR", "模型 ID 不能为空", 400, { - sessionId - }); - } - const model = await this.providerCatalog.resolveModelById(modelId); - sanitizedPatch.modelCatalogId = model.id; - sanitizedPatch.modelProvider = model.provider; - sanitizedPatch.modelName = model.model; - } - - const session = await this.repository.updateSession(sessionId, sanitizedPatch); - if (!session) { - throw new DomainError("SESSION_NOT_FOUND", "会话不存在", 404, { sessionId }); - } - return session; - } - - async deleteSession(sessionId: string): Promise { - const session = await this.repository.softDeleteSession(sessionId); - if (!session) { - throw new DomainError("SESSION_NOT_FOUND", "会话不存在", 404, { sessionId }); - } - await this.redisBuffer.clearBufferedMessages(sessionId); - } - - async probeModelConnectivity(modelCatalogId: string): Promise<{ - ok: boolean; - provider: string; - model: string; - latencyMs: number; - }> { - const normalizedModelId = modelCatalogId.trim(); - if (!normalizedModelId) { - throw new DomainError("VALIDATION_ERROR", "模型 ID 不能为空", 400, { - modelCatalogId - }); - } - - const startedAt = Date.now(); - try { - const draft = await this.providerRouter.generate(MODEL_PROBE_PROMPT, { - modelCatalogId: normalizedModelId - }); - const responseText = draft.rawText.trim().toUpperCase(); - if (!responseText) { - throw new DomainError( - "MODEL_PROBE_EMPTY", - "模型探活返回为空响应，请稍后重试。", - 502, - { - modelCatalogId: normalizedModelId - } - ); - } - return { - ok: true, - provider: draft.provider, - model: draft.model, - latencyMs: Date.now() - startedAt - }; - } catch (error) { - if (error instanceof DomainError) { - throw new DomainError( - "MODEL_UNREACHABLE", - `模型连通性检测失败：${error.message}`, - 409, - { - modelCatalogId: normalizedModelId, - latencyMs: Date.now() - startedAt, - reasonCode: error.code - } - ); - } - throw new DomainError( - "MODEL_UNREACHABLE", - `模型连通性检测失败：${error instanceof Error ? error.message : String(error)}`, - 409, - { - modelCatalogId: normalizedModelId, - latencyMs: Date.now() - startedAt - } - ); - } - } - - async sendMessage( - sessionId: string, - message: string, - requestId?: string - ): Promise { - const session = await this.repository.getSessionById(sessionId); - if (!session) { - throw new DomainError("SESSION_NOT_FOUND", "会话不存在", 404, { sessionId }); - } - await this.assertSessionWritableByPolicy(session); - const datasource = await this.datasourceService.assertDatasourceAvailable( - session.datasource - ); - const sqlAccessContext = await this.resolveSqlAccessContext(session); - - const userMessage: ChatMessage = { - id: uuidv4(), - sessionId, - role: "user", - content: message, - createdAt: new Date().toISOString() - }; - await this.redisBuffer.bufferMessage(userMessage); - const userPersistResult = await this.repository.persistMessage(userMessage); - await this.repository.ensureSessionTitleFromFirstMessage(sessionId, message); - - const run = await this.graphBuilder.run({ - runId: uuidv4(), - sessionId, - question: message, - datasourceId: session.datasource, - datasourceType: datasource.type, - modelCatalogId: session.modelCatalogId ?? undefined, - accessContext: sqlAccessContext, - traceContext: { - source: "chat", - route: "/api/v1/sessions/:sessionId/messages", - requestId - } - }); - - const finalRun = this.applyRejectedFallback(run, session.datasource); - const runWithDelivery = await this.attachDeliveryContract(finalRun); - await this.persistAssistantAndRun( - sessionId, - runWithDelivery, - userPersistResult.primaryPersisted - ); - await this.triggerMemoryPromotion(session, runWithDelivery, requestId); - return runWithDelivery; - } - - async streamMessage( - sessionId: string, - message: string, - requestId: string | undefined, - onEvent: (event: ChatStreamEvent) => Promise | void - ): Promise { - const session = await this.repository.getSessionById(sessionId); - if (!session) { - throw new DomainError("SESSION_NOT_FOUND", "会话不存在", 404, { sessionId }); - } - await this.assertSessionWritableByPolicy(session); - const datasource = await this.datasourceService.assertDatasourceAvailable( - session.datasource - ); - const sqlAccessContext = await this.resolveSqlAccessContext(session); - - const runId = uuidv4(); - const userMessage: ChatMessage = { - id: uuidv4(), - sessionId, - role: "user", - content: message, - createdAt: new Date().toISOString() - }; - await this.redisBuffer.bufferMessage(userMessage); - const userPersistResult = await this.repository.persistMessage(userMessage); - await this.repository.ensureSessionTitleFromFirstMessage(sessionId, message); - - const emit = async (type: ChatStreamEvent["type"], data: ChatStreamEvent["data"]) => { - await onEvent({ - type, - runId, - sessionId, - at: new Date().toISOString(), - data - }); - }; - - await emit("start", { - requestId: requestId ?? null - }); - - const toolCalls: NonNullable["toolCalls"]> = []; - let stepSequence = 0; - - try { - const run = await this.graphBuilder.run( - { - runId, - sessionId, - question: message, - datasourceId: session.datasource, - datasourceType: datasource.type, - modelCatalogId: session.modelCatalogId ?? undefined, - accessContext: sqlAccessContext, - traceContext: { - source: "chat", - route: "/api/v1/sessions/:sessionId/messages/stream", - requestId - } - }, - { - streamMode: true, - tools: this.sqlToolRegistry.getToolsForDatasource(datasource, { - accessContext: sqlAccessContext - }), - onLlmEvent: async (event) => { - if (event.type === "text-delta") { - await emit("text-delta", { - text: event.text - }); - return; - } - - if (event.type === "tool-call") { - toolCalls.push({ - toolName: event.toolName, - toolCallId: event.toolCallId, - status: "called", - detail: JSON.stringify(event.input ?? {}), - at: new Date().toISOString() - }); - await emit("tool-call", { - toolName: event.toolName, - toolCallId: event.toolCallId, - input: event.input - }); - return; - } - - if (event.type === "tool-result") { - toolCalls.push({ - toolName: event.toolName, - toolCallId: event.toolCallId, - status: "result", - detail: JSON.stringify(event.output ?? {}), - at: new Date().toISOString() - }); - await emit("tool-result", { - toolName: event.toolName, - toolCallId: event.toolCallId, - output: event.output - }); - return; - } - - toolCalls.push({ - toolName: event.toolName, - toolCallId: event.toolCallId, - status: "error", - detail: event.message, - at: new Date().toISOString() - }); - await emit("tool-error", { - toolName: event.toolName, - toolCallId: event.toolCallId, - message: event.message - }); - }, - onStep: async ({ step }) => { - const streamSequence = step.sequence ?? stepSequence + 1; - stepSequence = Math.max(stepSequence, streamSequence); - const stepTimestamp = step.at ?? step.endedAt ?? step.startedAt ?? new Date().toISOString(); - await emit("state", { - node: step.node, - status: step.status, - stepId: step.stepId ?? `${runId}:${step.node}:${streamSequence}`, - sequence: streamSequence, - lifecycle: step.lifecycle ?? resolveAgentStepLifecycle(step.status), - detail: step.detail ?? "", - stage: resolveAgentReasoningStage(step.node), - title: resolveAgentReasoningTitle(step.node), - at: stepTimestamp, - startedAt: step.startedAt, - endedAt: step.endedAt, - durationMs: step.durationMs, - inputSummary: step.inputSummary, - outputSummary: step.outputSummary, - errorSummary: step.errorSummary - }); - } - } - ); - - const finalRun = this.applyRejectedFallback(run, session.datasource); - finalRun.trace.streamStatus = finalRun.error ? "failed" : "completed"; - finalRun.trace.toolCalls = toolCalls; - const runWithDelivery = await this.attachDeliveryContract(finalRun); - if (runWithDelivery.error) { - await emit("error", { - code: - runWithDelivery.status === "rejected" ? "SQL_READONLY_REJECTED" : undefined, - message: runWithDelivery.error, - details: null - }); - } - await emit("finish", { - status: runWithDelivery.status, - rowCount: runWithDelivery.rows?.length ?? 0, - delivery: runWithDelivery.delivery - }); - await this.persistAssistantAndRun( - sessionId, - runWithDelivery, - userPersistResult.primaryPersisted - ); - await this.triggerMemoryPromotion(session, runWithDelivery, requestId); - return runWithDelivery; - } catch (error) { - const messageText = error instanceof Error ? error.message : String(error); - const run: SqlRun = { - runId, - sessionId, - question: message, - status: "failed", - provider: session.modelProvider ?? "unknown", - model: session.modelName ?? undefined, - error: messageText, - trace: { - runId, - provider: session.modelProvider ?? "unknown", - retryCount: 0, - steps: [], - streamStatus: "failed", - toolCalls - }, - llmRaw: null, - createdAt: new Date().toISOString() - }; - const domainError = - error instanceof DomainError ? error : undefined; - await emit("error", { - code: domainError?.code, - message: messageText, - details: (domainError?.details as Record | undefined) ?? null - }); - const runWithDelivery = await this.attachDeliveryContract(run); - await this.persistAssistantAndRun( - sessionId, - runWithDelivery, - userPersistResult.primaryPersisted - ); - await this.triggerMemoryPromotion(session, runWithDelivery, requestId); - return runWithDelivery; - } - } - - async listMessages( - sessionId: string, - page = 1, - pageSize = 0 - ): Promise { - const session = await this.repository.getSessionById(sessionId); - if (!session) { - throw new DomainError("SESSION_NOT_FOUND", "会话不存在", 404, { sessionId }); - } - const persisted = await this.repository.getMessages(sessionId, page, pageSize); - const buffered = await this.redisBuffer.getBufferedMessages(sessionId); - const merged = [...persisted, ...buffered]; - const unique = new Map(); - for (const message of merged) { - unique.set(message.id, message); - } - return Array.from(unique.values()).sort((a, b) => - a.createdAt.localeCompare(b.createdAt) - ); - } - - async getSessionView( - sessionId: string, - page = 1, - pageSize = 0 - ): Promise { - const session = await this.repository.getSessionById(sessionId); - if (!session) { - throw new DomainError("SESSION_NOT_FOUND", "会话不存在", 404, { sessionId }); - } - const messages = await this.listMessages(sessionId, page, pageSize); - const latestRunRaw = await this.repository.getLatestRunBySessionId(sessionId); - const latestRun = latestRunRaw - ? await this.attachDeliveryContract(latestRunRaw) - : undefined; - return { - session: await this.mergeDatasourceMetadata(session), - messages, - latestRun - }; - } - - async getRunById(runId: string): Promise { - const run = await this.repository.getRunById(runId); - if (!run) { - throw new DomainError("RUN_NOT_FOUND", "运行记录不存在", 404, { runId }); - } - const session = await this.repository.getSessionById(run.sessionId); - if (!session) { - throw new DomainError("RUN_NOT_FOUND", "运行记录不存在", 404, { runId }); - } - return this.attachDeliveryContract(run); - } - - private async assertSessionWritableByPolicy(session: Session): Promise { - const workspaceId = session.workspaceId?.trim(); - if (!workspaceId) { - return; - } - const stillBound = - await this.workspaceDatasourcePolicyRepository.isDatasourceBound( - workspaceId, - session.datasource - ); - if (!stillBound) { - throw new DomainError( - "SESSION_READONLY_BY_POLICY", - "该会话已转为只读历史（数据源绑定或权限已变更），不可继续发送消息。", - 409, - { - sessionId: session.id, - workspaceId, - datasourceId: session.datasource - } - ); - } - } - - private async resolveSqlAccessContext( - session: Session - ): Promise< - | { - actorId: string; - workspaceId: string; - roleSet: string[]; - allowedTables: string[]; - allowedColumnsByTable: Record; - rowFiltersByTable: Record; - evaluatorMode: "workspace_table_permissions"; - } - | undefined - > { - const workspaceId = session.workspaceId?.trim(); - const actorId = session.createdByUserId?.trim(); - if (!workspaceId || !actorId) { - return undefined; - } - const context: AccessContext = await this.policyEvaluatorService.resolveAccessContext({ - actor: { - id: actorId, - role: "user", - requestedWorkspaceId: workspaceId - }, - workspaceId - }); - const readable = await this.policyEvaluatorService.resolveReadableTables({ - context, - datasourceId: session.datasource - }); - return { - actorId: context.actorId, - workspaceId: context.workspaceId, - roleSet: [...context.roleSet], - allowedTables: [...readable.readableTables], - allowedColumnsByTable: { ...readable.allowedColumnsByTable }, - rowFiltersByTable: { ...readable.rowFiltersByTable }, - evaluatorMode: readable.mode - }; - } - - private async persistAssistantAndRun( - sessionId: string, - run: SqlRun, - userPrimaryPersisted: boolean - ): Promise { - const assistantMessage: ChatMessage = { - id: uuidv4(), - sessionId, - role: "assistant", - content: run.answer ?? run.error ?? "系统未返回结果。", - metadata: { - runId: run.runId, - status: run.status - }, - createdAt: new Date().toISOString() - }; - await this.redisBuffer.bufferMessage(assistantMessage); - const assistantPersistResult = await this.repository.persistMessage(assistantMessage); - await this.repository.persistRun(run); - this.traceService.record(run.trace, { - status: run.status, - error: run.error - }); - - const allPrimaryPersisted = - userPrimaryPersisted && assistantPersistResult.primaryPersisted; - if (allPrimaryPersisted) { - await this.redisBuffer.clearBufferedMessages(sessionId); - await this.repository.markSessionSyncHealthy(sessionId); - } else { - await this.repository.markSessionSyncPending( - sessionId, - new Date().toISOString() - ); - } - } - - private async mergeDatasourceMetadata( - session: Session, - resolvedDatasource?: Datasource - ): Promise { - const datasource = - resolvedDatasource ?? - (await this.datasourceService.getDatasourceById( - session.datasource, - { - includeDeleted: true - } - )); - - if (!datasource) { - return { - ...session, - datasourceStatus: "deleted" - }; - } - - return { - ...session, - datasourceName: datasource.name, - datasourceType: datasource.type, - datasourceStatus: this.normalizeDatasourceStatus(datasource.status) - }; - } - - private normalizeDatasourceStatus( - status: string | undefined | null - ): "available" | "unavailable" | "deleted" { - const normalized = status?.toLowerCase(); - if (normalized === "available") { - return "available"; - } - if (normalized === "deleted") { - return "deleted"; - } - if (normalized === "unavailable" || normalized === "offline" || normalized === "disconnected") { - return "unavailable"; - } - return "unavailable"; - } - - private applyRejectedFallback(run: SqlRun, datasource: string): SqlRun { - if (run.status !== "rejected") { - return run; - } - if (!this.datasourceRegistry.shouldFallbackOnReject(datasource)) { - return run; - } - if (run.answer) { - return run; - } - return { - ...run, - answer: - "请求触发了只读安全策略，本次未执行 SQL。你可以改为查询统计口径或时间范围，我会继续协助。" - }; - } - - private async attachDeliveryContract(run: SqlRun): Promise { - try { - const replayRecords = await this.loadReplayRecords(run.runId); - const delivery = this.deliveryContractMapper.map({ - run, - replayRecords - }); - return this.withPromptTemplateEvidence({ - ...run, - delivery - }); - } catch { - return this.withPromptTemplateEvidence({ - ...run, - delivery: this.deliveryContractMapper.buildFallback( - run, - "delivery_mapper_failed" - ) - }); - } - } - - private withPromptTemplateEvidence(run: SqlRun): SqlRun { - const traceWithCompat = run.trace as SqlRun["trace"] & { - prompt_template?: unknown; - prompt_template_evidence?: unknown; - templateEvidence?: unknown; - }; - const tracePromptTemplate = this.normalizePromptTemplateTraceEvidence( - traceWithCompat.promptTemplate ?? - traceWithCompat.prompt_template ?? - traceWithCompat.prompt_template_evidence ?? - traceWithCompat.templateEvidence - ); - const evidencePromptTemplate = this.normalizePromptTemplateTraceEvidence( - run.delivery?.evidence?.promptTemplate - ); - const resolvedPromptTemplate = evidencePromptTemplate ?? tracePromptTemplate; - - const normalizedTrace = resolvedPromptTemplate - ? { - ...run.trace, - promptTemplate: resolvedPromptTemplate - } - : run.trace; - - if (!run.delivery) { - return normalizedTrace === run.trace ? run : { ...run, trace: normalizedTrace }; - } - - const nextEvidence = - run.delivery.evidence || resolvedPromptTemplate - ? { - runId: run.delivery.evidence?.runId ?? run.runId, - ...run.delivery.evidence, - ...(resolvedPromptTemplate - ? { - promptTemplate: resolvedPromptTemplate - } - : {}) - } - : run.delivery.evidence; - - return { - ...run, - trace: normalizedTrace, - delivery: { - ...run.delivery, - ...(nextEvidence ? { evidence: nextEvidence } : {}) - } - }; - } - - private normalizePromptTemplateTraceEvidence( - value: unknown - ): SqlRun["trace"]["promptTemplate"] | undefined { - if (!this.isRecord(value)) { - return undefined; - } - const candidate = value as PromptTemplateTraceEvidenceCompat; - const templateId = this.readNonEmptyString(candidate.templateId ?? candidate.template_id); - const scope = this.normalizePromptTemplateScope( - candidate.scope ?? - candidate.scope_type ?? - candidate.template_scope ?? - (this.isRecord(value) ? (value.scopeType as unknown) : undefined) - ); - const version = this.readPositiveInteger( - candidate.version ?? - candidate.template_version ?? - (this.isRecord(value) ? (value.templateVersion as unknown) : undefined) - ); - const fallbackReason = this.readNonEmptyString( - candidate.fallbackReason ?? - candidate.fallback_reason ?? - (this.isRecord(value) ? (value.fallback_reason_code as unknown) : undefined) - ); - const scene = this.normalizePromptTemplateScene( - candidate.scene ?? candidate.scene_name ?? candidate.template_scene - ); - - if (!templateId && !scope && version === undefined && !fallbackReason && !scene) { - return undefined; - } - - return { - ...(templateId ? { templateId } : {}), - ...(scene ? { scene } : {}), - ...(scope ? { scope } : {}), - ...(version !== undefined ? { version } : {}), - ...(fallbackReason ? { fallbackReason } : {}) - }; - } - - private normalizePromptTemplateScope( - raw: unknown - ): "global" | "workspace" | "datasource" | undefined { - const normalized = this.readNonEmptyString(raw)?.toLowerCase(); - if ( - normalized === "global" || - normalized === "workspace" || - normalized === "datasource" - ) { - return normalized; - } - return undefined; - } - - private normalizePromptTemplateScene(raw: unknown): "sql" | "analysis" | undefined { - const normalized = this.readNonEmptyString(raw)?.toLowerCase(); - if (normalized === "sql" || normalized === "analysis") { - return normalized; - } - if (normalized === "sql_generation") { - return "sql"; - } - return undefined; - } - - private readPositiveInteger(raw: unknown): number | undefined { - if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) { - return Math.floor(raw); - } - if (typeof raw === "string" && raw.trim().length > 0) { - const parsed = Number(raw); - if (Number.isFinite(parsed) && parsed > 0) { - return Math.floor(parsed); - } - } - return undefined; - } - - private readNonEmptyString(raw: unknown): string | undefined { - if (typeof raw !== "string") { - return undefined; - } - const trimmed = raw.trim(); - return trimmed.length > 0 ? trimmed : undefined; - } - - private isRecord(value: unknown): value is Record { - return typeof value === "object" && value !== null; - } - - private async loadReplayRecords(runId: string): Promise { - const records = await this.ragReplayRepository.listByRunId(runId); - return records.map((item) => ({ - replayKey: item.replayKey, - stage: item.stage, - indexVersionId: item.indexVersionId, - payload: item.payload, - createdAt: item.createdAt - })); - } - - private async triggerMemoryPromotion( - session: Session, - run: SqlRun, - requestId?: string - ): Promise { - try { - await this.memoryPromotionService.promoteFromRun({ - run, - datasourceId: session.datasource, - requestId - }); - } catch { - // memory promotion is additive and must not interrupt chat completion. - } - } -} diff --git a/apps/backend/src/modules/chat/dto/create-session.dto.ts b/apps/backend/src/modules/chat/dto/create-session.dto.ts deleted file mode 100644 index fd427bf..0000000 --- a/apps/backend/src/modules/chat/dto/create-session.dto.ts +++ /dev/null @@ -1,25 +0,0 @@ -import { IsNotEmpty, IsOptional, IsString } from "class-validator"; -import { Transform } from "class-transformer"; - -export class CreateSessionDto { - @IsString() - @IsNotEmpty() - @Transform(({ value }) => - typeof value === "string" ? value.trim() : value - ) - datasource!: string; - - @IsOptional() - @IsString() - @Transform(({ value }) => - typeof value === "string" ? value.trim() : value - ) - modelCatalogId?: string; - - @IsOptional() - @IsString() - @Transform(({ value }) => - typeof value === "string" ? value.trim() : value - ) - workspaceId?: string; -} diff --git a/apps/backend/src/modules/chat/dto/list-sessions.dto.ts b/apps/backend/src/modules/chat/dto/list-sessions.dto.ts deleted file mode 100644 index f14c416..0000000 --- a/apps/backend/src/modules/chat/dto/list-sessions.dto.ts +++ /dev/null @@ -1,31 +0,0 @@ -import { IsIn, IsOptional, IsString } from "class-validator"; -import { Transform } from "class-transformer"; -import type { SessionSyncStatus } from "@text2sql/shared-types"; - -const syncStatuses: SessionSyncStatus[] = ["healthy", "pending", "degraded"]; -export const sessionListViews = ["current", "readonly-history", "all"] as const; -export type SessionListView = (typeof sessionListViews)[number]; - -export class ListSessionsDto { - @IsOptional() - @IsIn(syncStatuses) - status?: SessionSyncStatus; - - @IsOptional() - @IsString() - @Transform(({ value }) => - typeof value === "string" ? value.trim() : value - ) - datasource?: string; - - @IsOptional() - @IsString() - @Transform(({ value }) => - typeof value === "string" ? value.trim() : value - ) - workspaceId?: string; - - @IsOptional() - @IsIn([...sessionListViews]) - view?: SessionListView; -} diff --git a/apps/backend/src/modules/chat/dto/rename-session.dto.ts b/apps/backend/src/modules/chat/dto/rename-session.dto.ts deleted file mode 100644 index 1b909c5..0000000 --- a/apps/backend/src/modules/chat/dto/rename-session.dto.ts +++ /dev/null @@ -1,17 +0,0 @@ -import { IsBoolean, IsOptional, IsString, Length } from "class-validator"; - -export class RenameSessionDto { - @IsOptional() - @IsString() - @Length(1, 80) - title?: string; - - @IsOptional() - @IsBoolean() - debugEnabled?: boolean; - - @IsOptional() - @IsString() - @Length(1, 120) - modelCatalogId?: string; -} diff --git a/apps/backend/src/modules/chat/dto/send-message.dto.ts b/apps/backend/src/modules/chat/dto/send-message.dto.ts deleted file mode 100644 index ed86fa8..0000000 --- a/apps/backend/src/modules/chat/dto/send-message.dto.ts +++ /dev/null @@ -1,8 +0,0 @@ -import { IsString, Length } from "class-validator"; - -export class SendMessageDto { - @IsString() - @Length(1, 500) - message!: string; -} - diff --git a/apps/backend/src/modules/config/app-config.service.ts b/apps/backend/src/modules/config/app-config.service.ts index b906bf3..6422cec 100644 --- a/apps/backend/src/modules/config/app-config.service.ts +++ b/apps/backend/src/modules/config/app-config.service.ts @@ -140,10 +140,97 @@ export class AppConfigService { return this.config.get("LLM_MOCK_MODE", "false") === "true"; } + get embeddingProvider(): string { + return this.config.get("EMBEDDING_PROVIDER", this.llmProvider); + } + + get embeddingApiKey(): string { + return this.config.get("EMBEDDING_API_KEY", this.llmApiKey); + } + + get embeddingBaseUrl(): string { + return this.config.get("EMBEDDING_BASE_URL", this.llmBaseUrl); + } + + get embeddingModel(): string { + return this.config.get("EMBEDDING_MODEL", "text-embedding-3-small"); + } + + get embeddingTimeoutMs(): number { + const raw = this.config.get("EMBEDDING_TIMEOUT_MS", String(this.llmTimeoutMs)); + const parsed = Number(raw); + if (Number.isFinite(parsed) && parsed > 0) { + return Math.floor(parsed); + } + this.logger.warn( + `EMBEDDING_TIMEOUT_MS 配置无效（${raw}），已回退到 LLM_TIMEOUT_MS=${this.llmTimeoutMs}。` + ); + return this.llmTimeoutMs; + } + + get embeddingDimensions(): number | undefined { + const raw = this.config.get("EMBEDDING_DIMENSIONS", "").trim(); + if (!raw) { + return undefined; + } + const parsed = Number(raw); + if (Number.isFinite(parsed) && parsed > 0) { + return Math.floor(parsed); + } + this.logger.warn( + `EMBEDDING_DIMENSIONS 配置无效（${raw}），将忽略并使用 provider 默认维度。` + ); + return undefined; + } + + get embeddingVectorVersion(): string { + return this.config.get("EMBEDDING_VECTOR_VERSION", "v1"); + } + + get embeddingMockMode(): boolean { + return this.config.get("EMBEDDING_MOCK_MODE", "false") === "true"; + } + + get rerankProvider(): string { + return this.config.get("RERANK_PROVIDER", this.llmProvider); + } + + get rerankApiKey(): string { + return this.config.get("RERANK_API_KEY", this.llmApiKey); + } + + get rerankBaseUrl(): string { + return this.config.get("RERANK_BASE_URL", this.llmBaseUrl); + } + + get rerankModel(): string { + return this.config.get("RERANK_MODEL", this.llmModel); + } + + get rerankTimeoutMs(): number { + const raw = this.config.get("RERANK_TIMEOUT_MS", String(this.llmTimeoutMs)); + const parsed = Number(raw); + if (Number.isFinite(parsed) && parsed > 0) { + return Math.floor(parsed); + } + this.logger.warn( + `RERANK_TIMEOUT_MS 配置无效（${raw}），已回退到 LLM_TIMEOUT_MS=${this.llmTimeoutMs}。` + ); + return this.llmTimeoutMs; + } + + get rerankMockMode(): boolean { + return this.config.get("RERANK_MOCK_MODE", "false") === "true"; + } + get agentPlanningScaffoldEnabled(): boolean { return this.config.get("AGENT_PLANNING_SCAFFOLD_ENABLED", "false") === "true"; } + get agentRagRetrievalEnabled(): boolean { + return this.config.get("AGENT_RAG_RETRIEVAL_ENABLED", "true") === "true"; + } + get clarificationHybridEnabled(): boolean { return this.config.get("CLARIFICATION_HYBRID_ENABLED", "true") === "true"; } diff --git a/apps/backend/src/modules/conversation/adapters/semantic-context-pack.service.ts b/apps/backend/src/modules/conversation/adapters/semantic-context-pack.service.ts new file mode 100644 index 0000000..690f3f2 --- /dev/null +++ b/apps/backend/src/modules/conversation/adapters/semantic-context-pack.service.ts @@ -0,0 +1,880 @@ +import { Injectable } from "@nestjs/common"; +import type { + SemanticContextPackCapabilityV1, + SemanticContextPackV1 +} from "@text2sql/shared-types"; + +interface SemanticContextChunkPayload { + chunk_id: string; + content?: string; + metadata?: unknown; +} + +interface SemanticContextPermissionFiltering { + status?: "applied" | "skipped"; + denied_evidence_ids?: string[]; + denied_table_names?: string[]; + denied_column_names?: string[]; + reason_codes?: string[]; + deniedEvidenceIds?: string[]; + deniedTableNames?: string[]; + deniedColumnNames?: string[]; + reasonCodes?: string[]; +} + +interface SemanticContextLaneMetadata { + lane?: string; + state?: string; + unavailable_reason?: string; + fallback_reason?: string; + evidence_ids?: string[]; + reason_codes?: string[]; + input_count?: number; + output_count?: number; + selected_count?: number; + unavailableReason?: string; + fallbackReason?: string; + evidenceIds?: string[]; + reasonCodes?: string[]; + inputCount?: number; + outputCount?: number; + selectedCount?: number; +} + +interface SemanticContextPruningDecision { + budget_source?: string; + budgetSource?: string; + kept_evidence_ids?: string[]; + keptEvidenceIds?: string[]; + removed_evidence_ids?: string[]; + removedEvidenceIds?: string[]; + reason_codes?: string[]; + reasonCodes?: string[]; + summary?: string; +} + +interface SemanticContextSemanticBindings { + model_keys?: string[]; + relationship_keys?: string[]; + metric_keys?: string[]; + calculated_field_keys?: string[]; + modelKeys?: string[]; + relationshipKeys?: string[]; + metricKeys?: string[]; + calculatedFieldKeys?: string[]; +} + +interface SemanticContextInstructionSets { + model_bindings?: string[]; + relationship_bindings?: string[]; + metric_bindings?: string[]; + calculated_field_bindings?: string[]; + modelBindings?: string[]; + relationshipBindings?: string[]; + metricBindings?: string[]; + calculatedFieldBindings?: string[]; +} + +interface SemanticContextRetrievalBundle { + status?: "ready" | "degraded"; + selected_context?: SemanticContextChunkPayload[]; + degrade_reasons?: string[]; + degradeReasons?: string[]; + permission_filtering?: SemanticContextPermissionFiltering; + permissionFiltering?: SemanticContextPermissionFiltering; + lane_results?: Record< + string, + { + status?: "ok" | "degraded"; + degrade_reason?: string; + } + >; + rerank_metadata?: { + secondary?: { + status?: "ok" | "degraded" | "skipped"; + unavailable_reason?: string; + fallback_reason?: string; + }; + }; + context_pack?: { + semantic_version?: number; + semanticVersion?: number; + modeling_revision?: number; + modelingRevision?: number; + semantic_lock_status?: "locked" | "fallback" | "degraded"; + semanticLockStatus?: "locked" | "fallback" | "degraded"; + selected_context_lanes?: string[]; + selectedContextLanes?: string[]; + risk_tags?: string[]; + riskTags?: string[]; + semantic_bindings?: SemanticContextSemanticBindings; + semanticBindings?: SemanticContextSemanticBindings; + instruction_sets?: SemanticContextInstructionSets; + instructionSets?: SemanticContextInstructionSets; + lane_metadata?: SemanticContextLaneMetadata[]; + laneMetadata?: SemanticContextLaneMetadata[]; + pruning_decisions?: SemanticContextPruningDecision[]; + pruningDecisions?: SemanticContextPruningDecision[]; + permission_filtering?: SemanticContextPermissionFiltering; + permissionFiltering?: SemanticContextPermissionFiltering; + }; +} + +interface BuildSemanticContextPackInput { + retrievalBundle?: SemanticContextRetrievalBundle; + selectedContext?: SemanticContextChunkPayload[]; + additionalWarnings?: string[]; +} + +const MAX_SELECTED_EVIDENCE_IDS = 64; +const MAX_SUMMARY_EVIDENCE_IDS = 24; + +@Injectable() +export class SemanticContextPackService { + build(input: BuildSemanticContextPackInput): SemanticContextPackV1 { + const selectedContext = + input.selectedContext ?? input.retrievalBundle?.selected_context ?? []; + const laneMetadata = this.readLaneMetadata(input.retrievalBundle); + const pruningDecisions = this.readPruningDecisions(input.retrievalBundle); + const permissionFiltering = this.readPermissionFiltering(input.retrievalBundle); + + const selectedEvidenceIds = this.unique([ + ...selectedContext.map((chunk) => chunk.chunk_id), + ...laneMetadata.flatMap((lane) => this.readEvidenceIds(lane)), + ...pruningDecisions.flatMap((decision) => this.readKeptEvidenceIds(decision)) + ]).slice(0, MAX_SELECTED_EVIDENCE_IDS); + + const semanticBindings = this.readSemanticBindings(input.retrievalBundle); + const instructionSets = this.readInstructionSets(input.retrievalBundle); + + const selectedTables = this.unique( + [ + ...selectedContext.flatMap((chunk) => + this.readMetadataStringArray(chunk.metadata, "tableNames") + ), + ...(semanticBindings.model_keys ?? semanticBindings.modelKeys ?? []) + ] + .map((value) => this.normalizeIdentifier(value)) + .filter((value): value is string => Boolean(value)) + ); + + const selectedColumns = this.unique( + selectedContext + .flatMap((chunk) => this.readMetadataStringArray(chunk.metadata, "columnNames")) + .map((value) => this.normalizeIdentifier(value)) + .filter((value): value is string => Boolean(value)) + ); + + const aliasIds = this.unique( + selectedContext + .flatMap((chunk) => [ + ...this.readMetadataStringArray(chunk.metadata, "aliases"), + ...this.readMetadataStringArray(chunk.metadata, "aliasNames") + ]) + .map((value) => this.normalizeIdentifier(value)) + .filter((value): value is string => Boolean(value)) + ); + + const denseUnavailableWarning = this.resolveDenseUnavailableWarning(input.retrievalBundle); + const rerankUnavailableWarning = this.resolveRerankUnavailableWarning(input.retrievalBundle); + const laneWarnings = laneMetadata.flatMap((lane) => this.toLaneWarnings(lane)); + const pruningWarnings = pruningDecisions.flatMap((decision) => + this.toPruningWarnings(decision) + ); + const permissionWarnings = this.toPermissionWarnings(permissionFiltering); + const semanticVersion = this.readSemanticVersion(input.retrievalBundle?.context_pack); + + const warnings = this.unique([ + ...(input.retrievalBundle?.degrade_reasons ?? []), + ...(input.retrievalBundle?.degradeReasons ?? []), + ...(semanticVersion !== undefined + ? [`context_pack_semantic_version:${semanticVersion}`] + : []), + ...(denseUnavailableWarning ? [denseUnavailableWarning] : []), + ...(rerankUnavailableWarning ? [rerankUnavailableWarning] : []), + ...laneWarnings, + ...pruningWarnings, + ...permissionWarnings, + ...(input.additionalWarnings ?? []) + ]); + + const status = + input.retrievalBundle?.status ?? + (selectedContext.length > 0 ? "ready" : "degraded"); + + const selectedContextLanes = this.unique( + input.retrievalBundle?.context_pack?.selected_context_lanes ?? + input.retrievalBundle?.context_pack?.selectedContextLanes ?? + [] + ); + + const laneStates = laneMetadata + .map((lane) => this.toLaneState(lane)) + .filter((item): item is NonNullable => Boolean(item)); + + const degradation = this.buildDegradation({ + status, + laneStates, + warnings, + bundle: input.retrievalBundle, + riskTags: this.unique( + input.retrievalBundle?.context_pack?.risk_tags ?? + input.retrievalBundle?.context_pack?.riskTags ?? + [] + ) + }); + + const pruning = this.buildPruning(pruningDecisions); + const permissionFilteringSummary = this.buildPermissionFiltering(permissionFiltering); + const modelingRevision = this.readModelingRevision(input.retrievalBundle?.context_pack); + const semanticLockStatus = this.readSemanticLockStatus( + input.retrievalBundle?.context_pack + ); + const capabilities = this.buildCapabilities({ + laneStates, + degradation, + pruning, + permissionFiltering: permissionFilteringSummary, + semanticBindings, + selectedContextCount: selectedContext.length + }); + + const lanes = this.buildStructuredLanes({ + selectedTables, + selectedColumns, + aliasIds, + laneMetadata, + semanticBindings, + instructionSets + }); + + return { + status, + selectedEvidenceIds, + selectedTables, + selectedColumns, + ...(warnings.length > 0 ? { warnings } : {}), + version: "v1.rich", + capabilities, + ...(semanticVersion !== undefined ? { semanticVersion } : {}), + ...(modelingRevision !== undefined ? { modelingRevision } : {}), + ...(semanticLockStatus ? { semanticLockStatus } : {}), + selectedContextSummary: { + count: selectedContext.length, + evidenceIds: selectedEvidenceIds.slice(0, MAX_SUMMARY_EVIDENCE_IDS), + ...(selectedContextLanes.length > 0 ? { laneNames: selectedContextLanes } : {}) + }, + lanes, + ...(laneStates.length > 0 ? { laneStates } : {}), + degradation, + pruning, + permissionFiltering: permissionFilteringSummary + }; + } + + private buildCapabilities(input: { + laneStates: NonNullable; + degradation: NonNullable; + pruning: NonNullable; + permissionFiltering: NonNullable; + semanticBindings: SemanticContextSemanticBindings; + selectedContextCount: number; + }): SemanticContextPackCapabilityV1[] { + const capabilities: SemanticContextPackCapabilityV1[] = [ + "selected_context_summary" + ]; + + const hasSemanticBindingRefs = + (input.semanticBindings.model_keys?.length ?? 0) > 0 || + (input.semanticBindings.modelKeys?.length ?? 0) > 0 || + (input.semanticBindings.relationship_keys?.length ?? 0) > 0 || + (input.semanticBindings.relationshipKeys?.length ?? 0) > 0 || + (input.semanticBindings.metric_keys?.length ?? 0) > 0 || + (input.semanticBindings.metricKeys?.length ?? 0) > 0 || + (input.semanticBindings.calculated_field_keys?.length ?? 0) > 0 || + (input.semanticBindings.calculatedFieldKeys?.length ?? 0) > 0; + + if (hasSemanticBindingRefs) { + capabilities.push("semantic_binding_refs"); + } + + if (input.selectedContextCount > 0 || input.laneStates.length > 0) { + capabilities.push("structured_lanes"); + } + + if ( + input.degradation.status === "degraded" || + input.degradation.reasons.length > 0 || + (input.degradation.laneIssues?.length ?? 0) > 0 + ) { + capabilities.push("structured_degradation"); + } + + if (input.pruning.applied || input.pruning.decisions.length > 0) { + capabilities.push("structured_pruning"); + } + + if (input.permissionFiltering.status === "applied") { + capabilities.push("structured_permission_filtering"); + } + + return this.unique(capabilities); + } + + private buildStructuredLanes(input: { + selectedTables: string[]; + selectedColumns: string[]; + aliasIds: string[]; + laneMetadata: SemanticContextLaneMetadata[]; + semanticBindings: SemanticContextSemanticBindings; + instructionSets: SemanticContextInstructionSets; + }): NonNullable { + const relationshipRefs = this.unique([ + ...(input.semanticBindings.relationship_keys ?? + input.semanticBindings.relationshipKeys ?? + []), + ...this.collectLaneRefs(input.laneMetadata, ["relationship"]) + ]); + const metricRefs = this.unique([ + ...(input.semanticBindings.metric_keys ?? input.semanticBindings.metricKeys ?? []), + ...this.collectLaneRefs(input.laneMetadata, ["metric"]) + ]); + const calculatedFieldRefs = this.unique([ + ...(input.semanticBindings.calculated_field_keys ?? + input.semanticBindings.calculatedFieldKeys ?? + []), + ...this.collectLaneRefs(input.laneMetadata, ["calculated_field", "calculatedField"]) + ]); + const exampleRefs = this.collectLaneRefs(input.laneMetadata, ["example_sql"]); + const instructionRefs = this.unique([ + ...this.collectLaneRefs(input.laneMetadata, ["instruction"]), + ...(input.instructionSets.model_bindings ?? input.instructionSets.modelBindings ?? []), + ...(input.instructionSets.relationship_bindings ?? + input.instructionSets.relationshipBindings ?? + []), + ...(input.instructionSets.metric_bindings ?? input.instructionSets.metricBindings ?? []), + ...(input.instructionSets.calculated_field_bindings ?? + input.instructionSets.calculatedFieldBindings ?? + []) + ]); + const priorSqlRefs = this.collectLaneRefs(input.laneMetadata, ["saved_prior_sql"]); + const schemaSupplementRefs = this.collectLaneRefs(input.laneMetadata, [ + "schema_ddl_supplement", + "ddl_supplement" + ]); + const dialectFunctionRefs = this.collectLaneRefs(input.laneMetadata, ["dialect_function"]); + + return { + tables: { + ids: input.selectedTables, + count: input.selectedTables.length + }, + columns: { + ids: input.selectedColumns, + count: input.selectedColumns.length + }, + ...(input.aliasIds.length > 0 + ? { + aliases: { + ids: input.aliasIds, + count: input.aliasIds.length + } + } + : {}), + relationships: { + refs: relationshipRefs, + count: relationshipRefs.length + }, + metrics: { + refs: metricRefs, + count: metricRefs.length + }, + ...(calculatedFieldRefs.length > 0 + ? { + calculatedFields: { + refs: calculatedFieldRefs, + count: calculatedFieldRefs.length + } + } + : {}), + ...(exampleRefs.length > 0 + ? { + examples: { + refs: exampleRefs, + count: exampleRefs.length + } + } + : {}), + ...(instructionRefs.length > 0 + ? { + instructions: { + refs: instructionRefs, + count: instructionRefs.length + } + } + : {}), + ...(priorSqlRefs.length > 0 + ? { + priorSql: { + refs: priorSqlRefs, + count: priorSqlRefs.length + } + } + : {}), + ...(schemaSupplementRefs.length > 0 + ? { + schemaSupplementRefs: { + refs: schemaSupplementRefs, + count: schemaSupplementRefs.length + } + } + : {}), + ...(dialectFunctionRefs.length > 0 + ? { + dialectFunctions: { + refs: dialectFunctionRefs, + count: dialectFunctionRefs.length + } + } + : {}), + semanticBindings: { + ...(this.unique( + input.semanticBindings.model_keys ?? input.semanticBindings.modelKeys ?? [] + ).length > 0 + ? { + modelKeys: this.unique( + input.semanticBindings.model_keys ?? input.semanticBindings.modelKeys ?? [] + ) + } + : {}), + ...(this.unique( + input.semanticBindings.relationship_keys ?? + input.semanticBindings.relationshipKeys ?? + [] + ).length > 0 + ? { + relationshipKeys: this.unique( + input.semanticBindings.relationship_keys ?? + input.semanticBindings.relationshipKeys ?? + [] + ) + } + : {}), + ...(this.unique( + input.semanticBindings.metric_keys ?? input.semanticBindings.metricKeys ?? [] + ).length > 0 + ? { + metricKeys: this.unique( + input.semanticBindings.metric_keys ?? input.semanticBindings.metricKeys ?? [] + ) + } + : {}), + ...(this.unique( + input.semanticBindings.calculated_field_keys ?? + input.semanticBindings.calculatedFieldKeys ?? + [] + ).length > 0 + ? { + calculatedFieldKeys: this.unique( + input.semanticBindings.calculated_field_keys ?? + input.semanticBindings.calculatedFieldKeys ?? + [] + ) + } + : {}) + } + }; + } + + private buildDegradation(input: { + status: "ready" | "degraded"; + laneStates: NonNullable; + warnings: string[]; + bundle: SemanticContextRetrievalBundle | undefined; + riskTags: string[]; + }): NonNullable { + const reasons = this.unique([ + ...(input.bundle?.degrade_reasons ?? []), + ...(input.bundle?.degradeReasons ?? []) + ]); + + return { + status: input.status, + reasons, + ...(input.riskTags.length > 0 ? { riskTags: input.riskTags } : {}), + ...(this.resolveDenseUnavailableWarning(input.bundle) + ? { + denseUnavailableReason: this.resolveDenseUnavailableWarning(input.bundle) + } + : {}), + ...(this.resolveRerankUnavailableWarning(input.bundle) + ? { + rerankUnavailableReason: this.resolveRerankUnavailableWarning(input.bundle) + } + : {}), + ...(input.laneStates.filter((lane) => lane.state !== "ready").length > 0 + ? { + laneIssues: input.laneStates.filter((lane) => lane.state !== "ready") + } + : {}), + ...(input.status === "degraded" && reasons.length === 0 && input.warnings.length > 0 + ? { + reasons: ["context_pack_degraded_without_explicit_reason"] + } + : {}) + }; + } + + private buildPruning( + decisions: SemanticContextPruningDecision[] + ): NonNullable { + const normalized = decisions.map((decision) => { + const keptEvidenceIds = this.readKeptEvidenceIds(decision); + const removedEvidenceIds = this.readRemovedEvidenceIds(decision); + const reasonCodes = this.unique( + decision.reason_codes ?? decision.reasonCodes ?? [] + ); + + return { + budgetSource: decision.budget_source ?? decision.budgetSource, + keptEvidenceIds, + removedEvidenceIds, + keptCount: keptEvidenceIds.length, + removedCount: removedEvidenceIds.length, + ...(reasonCodes.length > 0 ? { reasonCodes } : {}), + ...(this.readString(decision.summary) + ? { summary: this.readString(decision.summary) } + : {}) + }; + }); + + return { + applied: normalized.length > 0, + decisions: normalized + }; + } + + private buildPermissionFiltering( + permissionFiltering: SemanticContextPermissionFiltering | undefined + ): NonNullable { + const deniedEvidenceIds = this.unique( + permissionFiltering?.denied_evidence_ids ?? + permissionFiltering?.deniedEvidenceIds ?? + [] + ); + const deniedTables = this.unique( + permissionFiltering?.denied_table_names ?? + permissionFiltering?.deniedTableNames ?? + [] + ); + const deniedColumns = this.unique( + permissionFiltering?.denied_column_names ?? + permissionFiltering?.deniedColumnNames ?? + [] + ); + const reasonCodes = this.unique( + permissionFiltering?.reason_codes ?? permissionFiltering?.reasonCodes ?? [] + ); + + return { + status: permissionFiltering?.status ?? "skipped", + ...(deniedEvidenceIds.length > 0 ? { deniedEvidenceIds } : {}), + ...(deniedEvidenceIds.length > 0 + ? { deniedEvidenceCount: deniedEvidenceIds.length } + : {}), + ...(deniedTables.length > 0 ? { deniedTables } : {}), + ...(deniedColumns.length > 0 ? { deniedColumns } : {}), + ...(reasonCodes.length > 0 ? { reasonCodes } : {}) + }; + } + + private toLaneState( + lane: SemanticContextLaneMetadata + ): NonNullable[number] | undefined { + const laneName = this.readString(lane.lane); + if (!laneName) { + return undefined; + } + const state = this.readString(lane.state) ?? "degraded"; + const refs = this.readEvidenceIds(lane); + const reasonCodes = this.unique(lane.reason_codes ?? lane.reasonCodes ?? []); + + return { + lane: laneName, + state, + ...(refs.length > 0 ? { refs } : {}), + ...(reasonCodes.length > 0 ? { reasonCodes } : {}), + ...(this.readString(lane.unavailable_reason ?? lane.unavailableReason) + ? { + unavailableReason: this.readString( + lane.unavailable_reason ?? lane.unavailableReason + ) + } + : {}), + ...(this.readString(lane.fallback_reason ?? lane.fallbackReason) + ? { + fallbackReason: this.readString(lane.fallback_reason ?? lane.fallbackReason) + } + : {}), + ...(this.readNumber(lane.input_count ?? lane.inputCount) !== undefined + ? { inputCount: this.readNumber(lane.input_count ?? lane.inputCount) } + : {}), + ...(this.readNumber(lane.output_count ?? lane.outputCount) !== undefined + ? { outputCount: this.readNumber(lane.output_count ?? lane.outputCount) } + : {}), + ...(this.readNumber(lane.selected_count ?? lane.selectedCount) !== undefined + ? { selectedCount: this.readNumber(lane.selected_count ?? lane.selectedCount) } + : {}) + }; + } + + private collectLaneRefs( + laneMetadata: SemanticContextLaneMetadata[], + laneNames: string[] + ): string[] { + const allowedLaneNames = new Set(laneNames.map((name) => name.trim().toLowerCase())); + return this.unique( + laneMetadata + .filter((lane) => + allowedLaneNames.has((lane.lane ?? "").trim().toLowerCase()) + ) + .flatMap((lane) => this.readEvidenceIds(lane)) + ); + } + + private readSemanticBindings( + bundle: SemanticContextRetrievalBundle | undefined + ): SemanticContextSemanticBindings { + return ( + bundle?.context_pack?.semantic_bindings ?? + bundle?.context_pack?.semanticBindings ?? + {} + ); + } + + private readInstructionSets( + bundle: SemanticContextRetrievalBundle | undefined + ): SemanticContextInstructionSets { + return ( + bundle?.context_pack?.instruction_sets ?? + bundle?.context_pack?.instructionSets ?? + {} + ); + } + + private normalizeIdentifier(value: string | undefined): string | undefined { + if (!value) { + return undefined; + } + const normalized = value + .trim() + .replace(/^[`"'\[\]]+|[`"'\[\]]+$/g, "") + .replace(/\s+/g, ""); + if (!normalized) { + return undefined; + } + return normalized.toLowerCase(); + } + + private unique(values: string[]): string[] { + return Array.from(new Set(values.filter((item) => item.trim().length > 0))); + } + + private readMetadataStringArray(metadata: unknown, key: string): string[] { + if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) { + return []; + } + const value = (metadata as Record)[key]; + if (!Array.isArray(value)) { + return []; + } + return value.filter((item): item is string => typeof item === "string"); + } + + private resolveDenseUnavailableWarning( + bundle: SemanticContextRetrievalBundle | undefined + ): string | undefined { + const denseDegradeReason = bundle?.lane_results?.dense?.degrade_reason; + if (!denseDegradeReason) { + return undefined; + } + if (denseDegradeReason.includes("dense_unavailable")) { + return `dense_unavailable:${denseDegradeReason}`; + } + return undefined; + } + + private resolveRerankUnavailableWarning( + bundle: SemanticContextRetrievalBundle | undefined + ): string | undefined { + const secondary = bundle?.rerank_metadata?.secondary; + if (!secondary) { + return undefined; + } + if (secondary.unavailable_reason) { + return `rerank_unavailable:${secondary.unavailable_reason}`; + } + if (secondary.status === "degraded" && secondary.fallback_reason) { + return `rerank_degraded:${secondary.fallback_reason}`; + } + return undefined; + } + + private toLaneWarnings(lane: SemanticContextLaneMetadata): string[] { + const laneName = lane.lane?.trim(); + if (!laneName) { + return []; + } + const warnings: string[] = []; + if (lane.state && lane.state !== "ready") { + warnings.push(`${laneName}_state:${lane.state}`); + } + const unavailableReason = lane.unavailable_reason ?? lane.unavailableReason; + if (lane.state === "unavailable" && unavailableReason) { + warnings.push(`${laneName}_unavailable:${unavailableReason}`); + } + const fallbackReason = lane.fallback_reason ?? lane.fallbackReason; + if (lane.state === "degraded" && fallbackReason) { + warnings.push(`${laneName}_degraded:${fallbackReason}`); + } + const reasonCodes = lane.reason_codes ?? lane.reasonCodes ?? []; + for (const code of reasonCodes) { + if (code.trim().length > 0) { + warnings.push(`${laneName}_reason:${code}`); + } + } + return warnings; + } + + private toPruningWarnings(decision: SemanticContextPruningDecision): string[] { + const budgetSource = (decision.budget_source ?? decision.budgetSource)?.trim(); + const reasonCodes = (decision.reason_codes ?? decision.reasonCodes ?? []).filter( + (reason) => reason.trim().length > 0 + ); + if (!budgetSource && reasonCodes.length === 0 && !decision.summary) { + return []; + } + const warnings: string[] = []; + if (decision.summary && decision.summary.trim().length > 0) { + warnings.push(`pruning_summary:${decision.summary}`); + } + for (const reasonCode of reasonCodes) { + warnings.push(`pruning_${budgetSource ?? "context"}:${reasonCode}`); + } + return warnings; + } + + private toPermissionWarnings( + permissionFiltering: SemanticContextPermissionFiltering | undefined + ): string[] { + if (!permissionFiltering) { + return []; + } + const deniedTables = + permissionFiltering.denied_table_names ?? permissionFiltering.deniedTableNames ?? []; + const deniedColumns = + permissionFiltering.denied_column_names ?? permissionFiltering.deniedColumnNames ?? []; + const reasonCodes = permissionFiltering.reason_codes ?? permissionFiltering.reasonCodes ?? []; + const deniedEvidenceIds = + permissionFiltering.denied_evidence_ids ?? permissionFiltering.deniedEvidenceIds ?? []; + return this.unique([ + ...(permissionFiltering.status + ? [`permission_filter_status:${permissionFiltering.status}`] + : []), + ...reasonCodes.map((code) => `permission_filter_reason:${code}`), + ...deniedTables.map((table) => `permission_denied_table:${table}`), + ...deniedColumns.map((column) => `permission_denied_column:${column}`), + ...(deniedEvidenceIds.length > 0 + ? [`permission_denied_evidence_count:${deniedEvidenceIds.length}`] + : []) + ]); + } + + private readLaneMetadata( + bundle: SemanticContextRetrievalBundle | undefined + ): SemanticContextLaneMetadata[] { + return bundle?.context_pack?.lane_metadata ?? bundle?.context_pack?.laneMetadata ?? []; + } + + private readPruningDecisions( + bundle: SemanticContextRetrievalBundle | undefined + ): SemanticContextPruningDecision[] { + return bundle?.context_pack?.pruning_decisions ?? bundle?.context_pack?.pruningDecisions ?? []; + } + + private readPermissionFiltering( + bundle: SemanticContextRetrievalBundle | undefined + ): SemanticContextPermissionFiltering | undefined { + if (!bundle) { + return undefined; + } + const rootBundle = bundle as SemanticContextRetrievalBundle & { + permission_filtering?: SemanticContextPermissionFiltering; + permissionFiltering?: SemanticContextPermissionFiltering; + }; + return ( + bundle.context_pack?.permission_filtering ?? + bundle.context_pack?.permissionFiltering ?? + rootBundle.permission_filtering ?? + rootBundle.permissionFiltering + ); + } + + private readEvidenceIds(lane: SemanticContextLaneMetadata): string[] { + return lane.evidence_ids ?? lane.evidenceIds ?? []; + } + + private readKeptEvidenceIds(decision: SemanticContextPruningDecision): string[] { + return decision.kept_evidence_ids ?? decision.keptEvidenceIds ?? []; + } + + private readRemovedEvidenceIds(decision: SemanticContextPruningDecision): string[] { + return decision.removed_evidence_ids ?? decision.removedEvidenceIds ?? []; + } + + private readSemanticVersion( + contextPack: + | { + semantic_version?: number; + semanticVersion?: number; + } + | undefined + ): number | undefined { + return contextPack?.semantic_version ?? contextPack?.semanticVersion; + } + + private readModelingRevision( + contextPack: + | { + modeling_revision?: number; + modelingRevision?: number; + } + | undefined + ): number | undefined { + return contextPack?.modeling_revision ?? contextPack?.modelingRevision; + } + + private readSemanticLockStatus( + contextPack: + | { + semantic_lock_status?: "locked" | "fallback" | "degraded"; + semanticLockStatus?: "locked" | "fallback" | "degraded"; + } + | undefined + ): "locked" | "fallback" | "degraded" | undefined { + return contextPack?.semantic_lock_status ?? contextPack?.semanticLockStatus; + } + + private readString(value: unknown): string | undefined { + if (typeof value !== "string") { + return undefined; + } + const normalized = value.trim(); + return normalized.length > 0 ? normalized : undefined; + } + + private readNumber(value: unknown): number | undefined { + const numericValue = Number(value); + return Number.isFinite(numericValue) ? numericValue : undefined; + } +} diff --git a/apps/backend/src/modules/conversation/adapters/semantic-plan.service.ts b/apps/backend/src/modules/conversation/adapters/semantic-plan.service.ts new file mode 100644 index 0000000..db8b308 --- /dev/null +++ b/apps/backend/src/modules/conversation/adapters/semantic-plan.service.ts @@ -0,0 +1,840 @@ +import { Injectable } from "@nestjs/common"; +import type { + SemanticContextPackV1, + SemanticPlanLedgerObligationV1, + SemanticPlanLedgerSummaryV1, + SemanticPlanCoverageGapV1, + SemanticPlanV1 +} from "@text2sql/shared-types"; +import type { SqlSemanticIntent } from "../agent/sql/sql-prompt.builder"; +import { SemanticPlanValidator } from "./semantic-plan.validator"; + +export interface BuildSemanticPlanInput { + question: string; + contextPack: SemanticContextPackV1; + semanticIntent?: SqlSemanticIntent; + allowedTables?: string[]; +} + +export type SemanticPlanRouteKind = + | "text_to_sql" + | "metadata" + | "general" + | "clarify" + | "fail_closed"; + +interface ClarificationPolicy { + round: number; + maxRounds: number; +} + +const METADATA_INTENT_REGEX = + /(有哪些表|哪些表|schema|表结构|字段|列名|show\s+tables|describe|sqlite_master|sqlite_schema|information_schema|pg_catalog|pragma)/i; +const GENERAL_INTENT_REGEX = + /^(你好|您好|hi|hello|thanks|谢谢|help|帮助|你是谁|你能做什么)(?:$|\s|[，。,.!?])|(?:什么是|解释|说明).{0,24}(?:口径|定义|含义)|(?:口径|定义|含义)(?:是什么|说明|解释)/i; +const METRIC_KEYWORD_REGEX = + /(count|sum|avg|average|max|min|总数|数量|金额|平均|均值|占比|转化率|留存|gmv)/gi; +const TIME_GRAIN_DAY_REGEX = /(按天|每天|daily|day\b|date_trunc\(['"]day['"]\))/i; +const TIME_GRAIN_WEEK_REGEX = /(按周|每周|weekly|week\b|date_trunc\(['"]week['"]\))/i; +const TIME_GRAIN_MONTH_REGEX = /(按月|每月|monthly|month\b|date_trunc\(['"]month['"]\))/i; +const FOLLOW_UP_PREFIX_REGEX = /^(那|那么|这个|这些|它们|those|them|that)/i; +const MAX_EVIDENCE_REF_COUNT = 32; +const MAX_METRIC_COUNT = 8; +const MAX_FILTER_COUNT = 12; + +@Injectable() +export class SemanticPlanService { + constructor(private readonly validator: SemanticPlanValidator) {} + + build(input: BuildSemanticPlanInput): { + plan: SemanticPlanV1; + validation: ReturnType; + } { + const selectedTables = this.normalizeList(input.contextPack.selectedTables ?? []); + const selectedColumns = this.normalizeList(input.contextPack.selectedColumns ?? []); + const allowedTables = this.normalizeList(input.allowedTables ?? []); + const evidenceRefs = this.normalizeEvidenceRefs(input.contextPack.selectedEvidenceIds); + const clarificationPolicy = this.resolveClarificationPolicy(input.contextPack.warnings); + const routeKind = this.resolveRouteKind({ + question: input.question, + semanticIntent: input.semanticIntent, + contextStatus: input.contextPack.status, + selectedTables, + selectedColumns, + evidenceRefs, + warningCount: input.contextPack.warnings?.length ?? 0, + clarificationPolicy + }); + const route = this.toContractRoute(routeKind); + const confidence = this.resolveConfidence({ + routeKind, + contextStatus: input.contextPack.status, + selectedTables, + selectedColumns, + evidenceRefs, + warningCount: input.contextPack.warnings?.length ?? 0 + }); + const standaloneQuestion = this.normalizeStandaloneQuestion({ + question: input.question, + selectedTables + }); + const metrics = this.extractMetrics({ + question: standaloneQuestion, + semanticIntent: input.semanticIntent, + selectedColumns + }); + const filters = this.extractFilters({ + question: standaloneQuestion, + routeKind, + clarificationPolicy, + contextWarnings: input.contextPack.warnings + }); + const joinPath = this.buildJoinPath({ + selectedTables, + contextPack: input.contextPack + }); + const forbiddenTables = this.unique([ + ...selectedTables.filter( + (table) => allowedTables.length > 0 && !allowedTables.includes(table) + ), + ...this.readForbiddenTables(input.contextPack.warnings) + ]); + const coverageGaps = this.buildCoverageGaps({ + question: standaloneQuestion, + routeKind, + selectedTables, + selectedColumns, + evidenceRefs, + clarificationPolicy + }); + const snapshotId = this.buildSnapshotId({ + routeKind, + contextStatus: input.contextPack.status, + selectedTables, + selectedColumns, + evidenceRefs, + coverageGaps + }); + + const planLedger = this.buildPlanLedger({ + question: standaloneQuestion, + selectedTables, + selectedColumns, + metrics, + grain: this.extractGrain(standaloneQuestion), + filters, + joinPath, + forbiddenTables, + evidenceRefs, + coverageGaps, + snapshotId, + contextPack: input.contextPack + }); + + const plan: SemanticPlanV1 = { + route, + standaloneQuestion, + selectedTables, + selectedColumns, + ...(metrics.length > 0 ? { metrics } : {}), + ...(this.extractGrain(standaloneQuestion) + ? { grain: this.extractGrain(standaloneQuestion) } + : {}), + ...(filters.length > 0 ? { filters } : {}), + ...(joinPath.length > 0 ? { joinPath } : {}), + ...(allowedTables.length > 0 ? { allowedTables } : {}), + ...(forbiddenTables.length > 0 ? { forbiddenTables } : {}), + confidence, + evidenceRefs, + ...(coverageGaps.length > 0 ? { coverageGaps } : {}), + snapshotId, + planLedger + }; + + return { + plan, + validation: this.validator.validate({ + plan + }) + }; + } + + private resolveRouteKind(input: { + question: string; + semanticIntent?: SqlSemanticIntent; + contextStatus: SemanticContextPackV1["status"]; + selectedTables: string[]; + selectedColumns: string[]; + evidenceRefs: string[]; + warningCount: number; + clarificationPolicy: ClarificationPolicy; + }): SemanticPlanRouteKind { + const normalizedQuestion = input.question.trim(); + if (input.semanticIntent === "metadata" || METADATA_INTENT_REGEX.test(normalizedQuestion)) { + return "metadata"; + } + if (GENERAL_INTENT_REGEX.test(normalizedQuestion)) { + return "general"; + } + + const hasEvidence = input.evidenceRefs.length > 0; + const hasGrounding = input.selectedTables.length > 0 || input.selectedColumns.length > 0; + const evidenceComplete = hasEvidence && hasGrounding; + const degradedWithoutRagGrounding = + input.contextStatus === "degraded" && !hasGrounding && !hasEvidence; + const heavilyDegraded = + input.contextStatus === "degraded" && + input.warningCount >= 2 && + !degradedWithoutRagGrounding; + + if (evidenceComplete) { + return "text_to_sql"; + } + if ( + heavilyDegraded || + input.clarificationPolicy.round >= input.clarificationPolicy.maxRounds + ) { + return "fail_closed"; + } + // Keep answer route for retrieval-unavailable scenarios so downstream SQL path + // can surface deterministic low-confidence diagnostics instead of clarify loops. + if (degradedWithoutRagGrounding) { + return "text_to_sql"; + } + if (!hasGrounding || !hasEvidence) { + return "clarify"; + } + return "text_to_sql"; + } + + private toContractRoute(routeKind: SemanticPlanRouteKind): SemanticPlanV1["route"] { + if (routeKind === "clarify") { + return "clarify"; + } + if (routeKind === "fail_closed") { + return "reject"; + } + return "answer"; + } + + private resolveConfidence(input: { + routeKind: SemanticPlanRouteKind; + contextStatus: SemanticContextPackV1["status"]; + selectedTables: string[]; + selectedColumns: string[]; + evidenceRefs: string[]; + warningCount: number; + }): number { + let base = + input.routeKind === "metadata" + ? 0.78 + : input.routeKind === "general" + ? 0.74 + : input.routeKind === "text_to_sql" + ? 0.62 + : input.routeKind === "clarify" + ? 0.34 + : 0.2; + if (input.selectedTables.length > 0) { + base += 0.12; + } + if (input.selectedColumns.length > 0) { + base += 0.05; + } + if (input.evidenceRefs.length > 0) { + base += 0.08; + } + if (input.contextStatus === "degraded") { + base -= 0.18; + } + base -= Math.min(0.2, input.warningCount * 0.05); + return Math.max(0, Math.min(1, Number(base.toFixed(4)))); + } + + private normalizeStandaloneQuestion(input: { + question: string; + selectedTables: string[]; + }): string { + const normalized = input.question.trim().replace(/\s+/g, " "); + if (!FOLLOW_UP_PREFIX_REGEX.test(normalized)) { + return normalized; + } + if (input.selectedTables.length === 0) { + return normalized; + } + return `${normalized} (context: ${input.selectedTables.slice(0, 3).join(", ")})`; + } + + private normalizeEvidenceRefs(values: string[]): string[] { + return Array.from( + new Set( + values + .map((item) => item.trim()) + .filter((item) => item.length > 0) + .slice(0, MAX_EVIDENCE_REF_COUNT) + ) + ); + } + + private extractMetrics(input: { + question: string; + semanticIntent?: SqlSemanticIntent; + selectedColumns: string[]; + }): string[] { + const metrics = new Set(); + if (input.semanticIntent === "count") { + metrics.add("count"); + } + const matches = input.question.match(METRIC_KEYWORD_REGEX) ?? []; + for (const match of matches) { + metrics.add(match.toLowerCase()); + } + for (const column of input.selectedColumns) { + if (/(amount|total|count|rate|ratio|score|gmv|qty|quantity)/i.test(column)) { + metrics.add(column); + } + } + return Array.from(metrics).slice(0, MAX_METRIC_COUNT); + } + + private extractGrain(question: string): string | undefined { + if (TIME_GRAIN_DAY_REGEX.test(question)) { + return "day"; + } + if (TIME_GRAIN_WEEK_REGEX.test(question)) { + return "week"; + } + if (TIME_GRAIN_MONTH_REGEX.test(question)) { + return "month"; + } + return undefined; + } + + private extractFilters(input: { + question: string; + routeKind: SemanticPlanRouteKind; + clarificationPolicy: ClarificationPolicy; + contextWarnings?: string[]; + }): string[] { + const filters: string[] = [`route_kind:${input.routeKind}`]; + if (input.routeKind === "clarify" || input.routeKind === "fail_closed") { + filters.push(`clarification_round:${input.clarificationPolicy.round}`); + filters.push(`clarification_max_rounds:${input.clarificationPolicy.maxRounds}`); + } + if (/近\d+\s*(天|周|月|年)/i.test(input.question)) { + filters.push("time_range:relative"); + } + if (/where|并且|且|过滤|状态|地区|渠道|大于|小于|等于|>=|<=|!=|=/i.test(input.question)) { + filters.push("filter:present"); + } + for (const warning of input.contextWarnings ?? []) { + const normalized = warning.trim().toLowerCase(); + if (!normalized) { + continue; + } + if ( + normalized.includes("dense_unavailable") || + normalized.includes("rerank_unavailable") + ) { + filters.push(`context_warning:${normalized}`); + } + } + return this.unique(filters).slice(0, MAX_FILTER_COUNT); + } + + private buildJoinPath(input: { + selectedTables: string[]; + contextPack: SemanticContextPackV1; + }): string[] { + if (input.selectedTables.length < 2) { + return []; + } + const relationshipRefs = input.contextPack.lanes?.relationships?.refs ?? []; + if (input.contextPack.lanes?.relationships && relationshipRefs.length === 0) { + return []; + } + const joins: string[] = []; + for (let index = 0; index < input.selectedTables.length - 1; index += 1) { + const source = input.selectedTables[index]; + const target = input.selectedTables[index + 1]; + if (!source || !target) { + continue; + } + joins.push(`${source}->${target}`); + } + return joins; + } + + private buildPlanLedger(input: { + question: string; + selectedTables: string[]; + selectedColumns: string[]; + metrics: string[]; + grain?: string; + filters: string[]; + joinPath: string[]; + forbiddenTables: string[]; + evidenceRefs: string[]; + coverageGaps: SemanticPlanCoverageGapV1[]; + snapshotId: string; + contextPack: SemanticContextPackV1; + }): NonNullable { + const obligations: SemanticPlanLedgerObligationV1[] = []; + const hasEvidence = input.evidenceRefs.length > 0; + const requiredColumns = this.resolveRequiredColumns({ + question: input.question, + selectedColumns: input.selectedColumns + }); + const warningOnlyDegraded = + input.contextPack.status === "degraded" && + input.selectedTables.length === 0 && + input.selectedColumns.length === 0 && + (input.contextPack.warnings ?? []).some((warning) => + /rag|dense|rerank|retrieval|unavailable|disabled/i.test(warning) + ); + + for (const table of input.selectedTables) { + const forbidden = input.forbiddenTables.includes(table); + obligations.push({ + id: `ledger:table:${table}`, + kind: forbidden ? "forbidden_table" : "table", + summary: forbidden + ? `SQL must not use forbidden table ${table}.` + : `SQL must use grounded table ${table}.`, + criticality: "hard_blocker", + status: forbidden ? "failed" : hasEvidence ? "grounded" : "failed", + evidenceRefs: input.evidenceRefs, + reasonCodes: forbidden + ? ["forbidden_table_selected"] + : hasEvidence + ? ["selected_table_grounded"] + : ["missing_selected_evidence_refs"], + subject: table + }); + } + + for (const column of input.selectedColumns) { + const normalizedColumn = this.normalizeQualifiedIdentifier(column); + if (!normalizedColumn || !requiredColumns.has(normalizedColumn)) { + continue; + } + obligations.push({ + id: `ledger:column:${column}`, + kind: "column", + summary: `SQL must use grounded column ${column}.`, + criticality: "hard_blocker", + status: hasEvidence ? "grounded" : "failed", + evidenceRefs: input.evidenceRefs, + reasonCodes: hasEvidence + ? ["selected_column_grounded"] + : ["missing_selected_evidence_refs"], + subject: column + }); + } + + for (const metric of input.metrics) { + obligations.push({ + id: `ledger:metric:${this.toLedgerIdToken(metric)}`, + kind: "metric", + summary: `SQL must satisfy metric ${metric}.`, + criticality: warningOnlyDegraded ? "warning" : "hard_blocker", + status: hasEvidence ? "grounded" : warningOnlyDegraded ? "warning" : "failed", + evidenceRefs: input.evidenceRefs, + reasonCodes: hasEvidence ? ["metric_grounded"] : ["metric_grounding_missing"], + subject: metric + }); + } + + if (input.grain || input.filters.some((filter) => filter.startsWith("time_range:"))) { + const subject = input.grain ?? "time_range"; + obligations.push({ + id: `ledger:time-grain:${this.toLedgerIdToken(subject)}`, + kind: "time_grain", + summary: `SQL must preserve requested time grain or range: ${subject}.`, + criticality: warningOnlyDegraded ? "warning" : "hard_blocker", + status: hasEvidence ? "grounded" : warningOnlyDegraded ? "warning" : "failed", + evidenceRefs: input.evidenceRefs, + reasonCodes: hasEvidence ? ["time_grain_grounded"] : ["time_grain_grounding_missing"], + subject + }); + } + + for (const filter of input.filters.filter((value) => value.startsWith("filter:"))) { + obligations.push({ + id: `ledger:filter:${this.toLedgerIdToken(filter)}`, + kind: "filter", + summary: `SQL must preserve requested filter signal ${filter}.`, + criticality: warningOnlyDegraded ? "warning" : "hard_blocker", + status: hasEvidence ? "grounded" : warningOnlyDegraded ? "warning" : "failed", + evidenceRefs: input.evidenceRefs, + reasonCodes: hasEvidence ? ["filter_grounded"] : ["filter_grounding_missing"], + subject: filter + }); + } + + if (input.selectedTables.length > 1) { + const joinPath = input.joinPath.join(" -> "); + obligations.push({ + id: `ledger:join-path:${input.selectedTables.map((table) => this.toLedgerIdToken(table)).join("-")}`, + kind: "join_path", + summary: joinPath + ? `SQL must preserve join path ${joinPath}.` + : "SQL generation is blocked until a multi-table join path is grounded.", + criticality: "hard_blocker", + status: input.joinPath.length > 0 ? "grounded" : "failed", + evidenceRefs: input.contextPack.lanes?.relationships?.refs ?? input.evidenceRefs, + reasonCodes: + input.joinPath.length > 0 + ? ["join_path_grounded"] + : ["missing_join_path"], + subject: joinPath || input.selectedTables.join(",") + }); + } + + for (const gap of input.coverageGaps) { + obligations.push({ + id: `ledger:evidence:${gap.subjectKind}:${this.toLedgerIdToken(gap.reasonCode)}`, + kind: "evidence", + summary: `Semantic plan has coverage gap ${gap.reasonCode}.`, + criticality: + gap.impactScope === "sql_generation" && !warningOnlyDegraded + ? "hard_blocker" + : "warning", + status: + gap.impactScope === "sql_generation" && !warningOnlyDegraded + ? "failed" + : "warning", + evidenceRefs: gap.evidenceRefs, + reasonCodes: [gap.reasonCode], + subject: gap.subjectKind + }); + } + + for (const warning of input.contextPack.warnings ?? []) { + const normalized = warning.trim().toLowerCase(); + if (!normalized || normalized.startsWith("clarification_")) { + continue; + } + obligations.push({ + id: `ledger:warning:${this.toLedgerIdToken(normalized)}`, + kind: "evidence", + summary: `Context warning: ${normalized}.`, + criticality: "warning", + status: "warning", + evidenceRefs: [], + reasonCodes: [normalized], + subject: normalized + }); + } + + return { + version: "plan-ledger.v1", + snapshotId: input.snapshotId, + obligations, + summary: this.summarizePlanLedger(input.snapshotId, obligations, input.evidenceRefs) + }; + } + + private summarizePlanLedger( + snapshotId: string, + obligations: SemanticPlanLedgerObligationV1[], + evidenceRefs: string[] + ): SemanticPlanLedgerSummaryV1 { + const failedHardBlockerIds = obligations + .filter( + (obligation) => + obligation.criticality === "hard_blocker" && + (obligation.status === "failed" || obligation.status === "unsupported") + ) + .map((obligation) => obligation.id); + const warningIds = obligations + .filter((obligation) => obligation.criticality === "warning") + .map((obligation) => obligation.id); + return { + snapshotId, + total: obligations.length, + hardBlockerCount: obligations.filter( + (obligation) => obligation.criticality === "hard_blocker" + ).length, + warningCount: warningIds.length, + fulfilledCount: obligations.filter( + (obligation) => + obligation.status === "grounded" || + obligation.status === "claimed" || + obligation.status === "fulfilled" + ).length, + failedCount: obligations.filter( + (obligation) => + obligation.status === "failed" || obligation.status === "unsupported" + ).length, + failedHardBlockerIds, + warningIds, + reasonCodes: this.unique(obligations.flatMap((obligation) => obligation.reasonCodes)), + selectedEvidenceRefs: evidenceRefs + }; + } + + private resolveRequiredColumns(input: { + question: string; + selectedColumns: string[]; + }): Set { + const normalizedQuestion = input.question.toLowerCase(); + const candidates = input.selectedColumns + .map((column) => this.normalizeQualifiedIdentifier(column)) + .filter((column): column is string => Boolean(column)); + const required = new Set(); + + if (candidates.length === 1 && candidates[0]) { + required.add(candidates[0]); + return required; + } + + const hints: Array<{ pattern: RegExp; columns: RegExp }> = [ + { + pattern: /(支付方式|支付渠道|付款方式|方式|渠道|payment|method)/i, + columns: /(^|\.)method$/ + }, + { pattern: /(状态|status)/i, columns: /(^|\.)status$/ }, + { pattern: /(类型|type)/i, columns: /(^|\.)type$/ }, + { + pattern: /(分类|类目|类别|category)/i, + columns: /(^|\.)(category|category_id)$/ + }, + { + pattern: /(城市|地区|区域|省份|city|region|province)/i, + columns: /(^|\.)(city|region|province|area)$/ + }, + { + pattern: /(金额|交易额|销售额|净销售额|gmv|amount|total|sales)/i, + columns: /(^|\.)(amount|total_amount|gmv|sales|net_sales)$/ + }, + { + pattern: /(时间|日期|近\d+\s*(天|周|月|年)|按天|按周|按月|date|time)/i, + columns: /(^|\.)(created_at|updated_at|paid_at|date|day|month|year)$/ + } + ]; + + for (const column of candidates) { + for (const hint of hints) { + if (hint.pattern.test(normalizedQuestion) && hint.columns.test(column)) { + required.add(column); + } + } + const leaf = column.includes(".") ? column.split(".").at(-1) : column; + if (leaf && new RegExp(`\\b${this.escapeRegex(leaf)}\\b`, "i").test(input.question)) { + required.add(column); + } + } + + return required; + } + + private escapeRegex(value: string): string { + return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + } + + private toLedgerIdToken(value: string): string { + return ( + value + .trim() + .toLowerCase() + .replace(/[^a-z0-9_.-]+/gi, "-") + .replace(/^-+|-+$/g, "") || "unknown" + ); + } + + private buildCoverageGaps(input: { + question: string; + routeKind: SemanticPlanRouteKind; + selectedTables: string[]; + selectedColumns: string[]; + evidenceRefs: string[]; + clarificationPolicy: ClarificationPolicy; + }): SemanticPlanCoverageGapV1[] { + const gaps: SemanticPlanCoverageGapV1[] = []; + const hasGrounding = + input.selectedTables.length > 0 || input.selectedColumns.length > 0; + + if ( + (input.routeKind === "text_to_sql" || + input.routeKind === "clarify" || + input.routeKind === "fail_closed") && + (input.evidenceRefs.length === 0 || !hasGrounding) + ) { + gaps.push({ + gapType: "evidence_gap", + subjectKind: this.resolveEvidenceGapSubjectKind(input), + reasonCode: + input.evidenceRefs.length === 0 + ? "missing_selected_evidence_refs" + : "missing_structured_grounding", + evidenceRefs: input.evidenceRefs, + impactScope: "sql_generation" + }); + } + + if (input.routeKind === "clarify" || input.routeKind === "fail_closed") { + gaps.push({ + gapType: "user_decision_gap", + subjectKind: this.resolveDecisionGapSubjectKind(input.question), + reasonCode: + input.routeKind === "fail_closed" + ? input.clarificationPolicy.round >= input.clarificationPolicy.maxRounds + ? "clarification_budget_exhausted" + : "semantic_plan_fail_closed" + : "semantic_plan_requires_clarification", + evidenceRefs: input.evidenceRefs, + impactScope: + input.routeKind === "fail_closed" ? "execution" : "clarification" + }); + } + + return gaps; + } + + private resolveEvidenceGapSubjectKind(input: { + question: string; + selectedTables: string[]; + selectedColumns: string[]; + evidenceRefs: string[]; + }): SemanticPlanCoverageGapV1["subjectKind"] { + if (input.selectedTables.length === 0 && input.selectedColumns.length === 0) { + if (this.resolveDecisionGapSubjectKind(input.question) === "time") { + return "time"; + } + if (this.resolveDecisionGapSubjectKind(input.question) === "metric") { + return "metric"; + } + return "table"; + } + if (input.evidenceRefs.length === 0) { + return input.selectedColumns.length > 0 ? "column" : "table"; + } + return "general"; + } + + private resolveDecisionGapSubjectKind( + question: string + ): SemanticPlanCoverageGapV1["subjectKind"] { + if (!question.trim()) { + return "general"; + } + if (!question.match(METRIC_KEYWORD_REGEX)) { + return "metric"; + } + if (!this.extractGrain(question) && !/近\d+\s*(天|周|月|年)|昨天|今天|本周|本月|本季度|本年/i.test(question)) { + return "time"; + } + return "general"; + } + + private buildSnapshotId(input: { + routeKind: SemanticPlanRouteKind; + contextStatus: SemanticContextPackV1["status"]; + selectedTables: string[]; + selectedColumns: string[]; + evidenceRefs: string[]; + coverageGaps: SemanticPlanCoverageGapV1[]; + }): string { + const routeToken = input.routeKind.replace(/[^a-z0-9]+/gi, "-"); + const contextToken = input.contextStatus === "degraded" ? "degraded" : "ready"; + const tableToken = + input.selectedTables.slice(0, 2).join("+").replace(/[^a-z0-9+_.-]+/gi, "-") || + "none"; + return [ + "semantic-plan", + routeToken, + contextToken, + `t${input.selectedTables.length}`, + `c${input.selectedColumns.length}`, + `e${input.evidenceRefs.length}`, + `g${input.coverageGaps.length}`, + tableToken + ].join(":"); + } + + private readForbiddenTables(warnings?: string[]): string[] { + if (!warnings) { + return []; + } + const forbidden: string[] = []; + for (const warning of warnings) { + const normalized = warning.trim(); + if (!normalized) { + continue; + } + const match = /forbidden_table:([a-zA-Z_][\w$]*)/i.exec(normalized); + if (!match?.[1]) { + continue; + } + const token = this.normalizeIdentifier(match[1]); + if (token) { + forbidden.push(token); + } + } + return this.unique(forbidden); + } + + private resolveClarificationPolicy(warnings?: string[]): ClarificationPolicy { + const policy: ClarificationPolicy = { + round: 0, + maxRounds: 2 + }; + for (const warning of warnings ?? []) { + const normalized = warning.trim(); + if (!normalized) { + continue; + } + const roundMatch = /clarification_round:(\d+)/i.exec(normalized); + if (roundMatch?.[1]) { + policy.round = Math.max(policy.round, Number(roundMatch[1])); + } + const maxMatch = /clarification_max_rounds:(\d+)/i.exec(normalized); + if (maxMatch?.[1]) { + policy.maxRounds = Math.max(1, Number(maxMatch[1])); + } + } + return policy; + } + + private unique(values: string[]): string[] { + return Array.from(new Set(values.filter((item) => item.trim().length > 0))); + } + + private normalizeList(values: string[]): string[] { + return Array.from( + new Set( + values + .map((value) => this.normalizeIdentifier(value)) + .filter((value): value is string => Boolean(value)) + ) + ); + } + + private normalizeIdentifier(value: string | undefined): string | undefined { + if (!value) { + return undefined; + } + const normalized = value + .trim() + .replace(/^[`"'\[\]]+|[`"'\[\]]+$/g, "") + .replace(/\s+/g, "") + .toLowerCase(); + return normalized.length > 0 ? normalized : undefined; + } + + private normalizeQualifiedIdentifier(value: string | undefined): string | undefined { + const normalized = this.normalizeIdentifier(value); + if (!normalized) { + return undefined; + } + if (!normalized.includes(".")) { + return normalized; + } + const [table, column] = normalized.split("."); + if (!table || !column) { + return undefined; + } + return `${table}.${column}`; + } +} diff --git a/apps/backend/src/modules/conversation/adapters/semantic-plan.validator.ts b/apps/backend/src/modules/conversation/adapters/semantic-plan.validator.ts new file mode 100644 index 0000000..13ce5bf --- /dev/null +++ b/apps/backend/src/modules/conversation/adapters/semantic-plan.validator.ts @@ -0,0 +1,300 @@ +import { Injectable } from "@nestjs/common"; +import type { + SemanticPlanCoverageGapV1, + SemanticPlanV1 +} from "@text2sql/shared-types"; + +export interface SemanticPlanValidationResult { + valid: boolean; + lowConfidence: boolean; + unsupportedTables: string[]; + unsupportedColumns: string[]; + reasons: string[]; + ledgerGateOutcome: "pass" | "warning" | "block"; + blockedObligationIds: string[]; + warningObligationIds: string[]; + routeKind: "text_to_sql" | "metadata" | "general" | "clarify" | "fail_closed"; + outcome: "ready" | "needs_clarification" | "direct_answer" | "fail_closed"; + evidenceComplete: boolean; + requiresClarification: boolean; + shouldDirectAnswer: boolean; + terminal: boolean; +} + +interface ValidateSemanticPlanInput { + plan: SemanticPlanV1; + minimumConfidence?: number; +} + +@Injectable() +export class SemanticPlanValidator { + validate(input: ValidateSemanticPlanInput): SemanticPlanValidationResult { + const plan = input.plan; + const routeKind = this.resolveRouteKind(plan); + const minimumConfidence = this.resolveMinimumConfidence(routeKind, input.minimumConfidence); + const allowedTables = new Set(this.normalizeList(plan.allowedTables ?? [])); + const selectedTables = this.normalizeList(plan.selectedTables); + const selectedColumns = this.normalizeList(plan.selectedColumns); + const forbiddenTables = new Set(this.normalizeList(plan.forbiddenTables ?? [])); + const evidenceRefs = this.normalizeEvidenceRefs(plan.evidenceRefs); + const coverageGaps = this.readCoverageGaps(plan.coverageGaps); + const invalidCoverageGapCount = this.countInvalidCoverageGaps(plan.coverageGaps); + const snapshotId = this.readOptionalText((plan as { snapshotId?: unknown }).snapshotId); + const ledgerSummary = plan.planLedger?.summary; + const blockedObligationIds = this.normalizeEvidenceRefs( + ledgerSummary?.failedHardBlockerIds ?? [] + ); + const warningObligationIds = this.normalizeEvidenceRefs(ledgerSummary?.warningIds ?? []); + const ledgerGateOutcome = + blockedObligationIds.length > 0 + ? "block" + : warningObligationIds.length > 0 + ? "warning" + : "pass"; + + const unsupportedTables = selectedTables.filter((table) => { + if (forbiddenTables.has(table)) { + return true; + } + if (allowedTables.size === 0) { + return false; + } + return !allowedTables.has(table); + }); + + const unsupportedColumns = selectedColumns.filter((column) => { + if (!column.includes(".")) { + return false; + } + const [table] = column.split("."); + const normalizedTable = this.normalizeIdentifier(table); + if (!normalizedTable) { + return false; + } + if (forbiddenTables.has(normalizedTable)) { + return true; + } + if (allowedTables.size === 0) { + return false; + } + return !allowedTables.has(normalizedTable); + }); + + const evidenceComplete = + evidenceRefs.length > 0 && + (selectedTables.length > 0 || + selectedColumns.length > 0 || + routeKind === "metadata" || + routeKind === "general"); + + const lowConfidence = + routeKind === "fail_closed" ? false : plan.confidence < minimumConfidence; + const reasons: string[] = []; + + if (routeKind === "text_to_sql" && plan.route !== "answer") { + reasons.push("plan_route_mismatch_text_to_sql"); + } + if (routeKind === "clarify" && plan.route !== "clarify") { + reasons.push("plan_route_mismatch_clarify"); + } + if (routeKind === "fail_closed" && plan.route !== "reject") { + reasons.push("plan_route_mismatch_fail_closed"); + } + if (routeKind === "text_to_sql" && selectedTables.length === 0) { + reasons.push("plan_missing_selected_tables"); + } + if (routeKind === "text_to_sql" && !evidenceComplete) { + reasons.push("plan_missing_grounding_evidence"); + } + if (routeKind === "text_to_sql" && selectedTables.length > 1) { + const joinPath = this.normalizeJoinPath(plan.joinPath ?? []); + if (joinPath.length === 0) { + reasons.push("plan_missing_join_path"); + } + } + if (unsupportedTables.length > 0) { + reasons.push("plan_contains_unsupported_tables"); + } + if (unsupportedColumns.length > 0) { + reasons.push("plan_contains_unsupported_columns"); + } + if (lowConfidence) { + reasons.push("plan_low_confidence"); + } + if (invalidCoverageGapCount > 0) { + reasons.push("plan_invalid_coverage_gap_shape"); + } + if ((routeKind === "clarify" || routeKind === "fail_closed" || !evidenceComplete) && coverageGaps.length === 0) { + reasons.push("plan_missing_coverage_gaps"); + } + if ("snapshotId" in plan && snapshotId === undefined) { + reasons.push("plan_invalid_snapshot_id"); + } + if (ledgerGateOutcome === "block") { + reasons.push("plan_ledger_gate_blocked"); + } + + const terminalLedgerBlock = (plan.planLedger?.obligations ?? []).some( + (obligation) => + blockedObligationIds.includes(obligation.id) && + (obligation.kind === "forbidden_table" || + obligation.kind === "permission" || + obligation.reasonCodes.some((reasonCode) => + /forbidden|permission|policy|unsupported/i.test(reasonCode) + )) + ); + const terminal = + routeKind === "fail_closed" || + unsupportedTables.length > 0 || + unsupportedColumns.length > 0 || + terminalLedgerBlock; + const shouldDirectAnswer = routeKind === "metadata" || routeKind === "general"; + const outcome = terminal + ? "fail_closed" + : shouldDirectAnswer + ? "direct_answer" + : routeKind === "clarify" + ? "needs_clarification" + : ledgerGateOutcome === "block" + ? "needs_clarification" + : "ready"; + + return { + valid: reasons.length === 0, + lowConfidence, + unsupportedTables, + unsupportedColumns, + reasons, + ledgerGateOutcome, + blockedObligationIds, + warningObligationIds, + routeKind, + outcome, + evidenceComplete, + requiresClarification: routeKind === "clarify" || outcome === "needs_clarification", + shouldDirectAnswer, + terminal + }; + } + + private resolveMinimumConfidence( + routeKind: SemanticPlanValidationResult["routeKind"], + inputMinimumConfidence?: number + ): number { + if (typeof inputMinimumConfidence === "number" && Number.isFinite(inputMinimumConfidence)) { + return inputMinimumConfidence; + } + if (routeKind === "metadata" || routeKind === "general") { + return 0.35; + } + return 0.55; + } + + private resolveRouteKind( + plan: SemanticPlanV1 + ): SemanticPlanValidationResult["routeKind"] { + const routeFilter = (plan.filters ?? []).find((entry) => + entry.startsWith("route_kind:") + ); + if (routeFilter) { + const value = routeFilter.slice("route_kind:".length).trim(); + if ( + value === "text_to_sql" || + value === "metadata" || + value === "general" || + value === "clarify" || + value === "fail_closed" + ) { + return value; + } + } + if (plan.route === "clarify") { + return "clarify"; + } + if (plan.route === "reject") { + return "fail_closed"; + } + return "text_to_sql"; + } + + private normalizeEvidenceRefs(values: string[]): string[] { + return Array.from( + new Set(values.map((value) => value.trim()).filter((value) => value.length > 0)) + ); + } + + private readCoverageGaps(value: unknown): SemanticPlanCoverageGapV1[] { + if (!Array.isArray(value)) { + return []; + } + return value.filter((item): item is SemanticPlanCoverageGapV1 => + this.isValidCoverageGap(item) + ); + } + + private countInvalidCoverageGaps(value: unknown): number { + if (!Array.isArray(value)) { + return 0; + } + return value.filter((item) => !this.isValidCoverageGap(item)).length; + } + + private isValidCoverageGap(value: unknown): value is SemanticPlanCoverageGapV1 { + if (!this.isRecord(value)) { + return false; + } + const gapType = this.readOptionalText(value.gapType); + const subjectKind = this.readOptionalText(value.subjectKind); + const reasonCode = this.readOptionalText(value.reasonCode); + const impactScope = this.readOptionalText(value.impactScope); + const evidenceRefs = value.evidenceRefs; + return ( + Boolean(gapType) && + Boolean(subjectKind) && + Boolean(reasonCode) && + Boolean(impactScope) && + Array.isArray(evidenceRefs) && + evidenceRefs.every((item) => typeof item === "string") + ); + } + + private normalizeJoinPath(values: string[]): string[] { + return Array.from( + new Set(values.map((value) => value.trim()).filter((value) => value.length > 0)) + ); + } + + private normalizeList(values: string[]): string[] { + return Array.from( + new Set( + values + .map((value) => this.normalizeIdentifier(value)) + .filter((value): value is string => Boolean(value)) + ) + ); + } + + private normalizeIdentifier(value: string | undefined): string | undefined { + if (!value) { + return undefined; + } + const normalized = value + .trim() + .replace(/^[`"'\[\]]+|[`"'\[\]]+$/g, "") + .replace(/\s+/g, "") + .toLowerCase(); + return normalized.length > 0 ? normalized : undefined; + } + + private isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); + } + + private readOptionalText(value: unknown): string | undefined { + if (typeof value !== "string") { + return undefined; + } + const normalized = value.trim(); + return normalized.length > 0 ? normalized : undefined; + } +} diff --git a/apps/backend/src/modules/conversation/adapters/sql-correction.service.ts b/apps/backend/src/modules/conversation/adapters/sql-correction.service.ts new file mode 100644 index 0000000..dfeec3d --- /dev/null +++ b/apps/backend/src/modules/conversation/adapters/sql-correction.service.ts @@ -0,0 +1,327 @@ +import { Injectable } from "@nestjs/common"; +import type { + SqlValidationArtifactV1, + SqlValidationCheckV1, + Text2SqlV2FailureSemantic +} from "@text2sql/shared-types"; +import { DomainError } from "../../../common/domain-error"; + +export interface SqlCorrectionDecision { + correctable: boolean; + reason: string; + maxAttempts: number; + category: "validation" | "governance" | "safety" | "provider" | "execution" | "unknown"; + source: "validation" | "execution"; + failureCode?: string; + failedObligationIds?: string[]; +} + +export interface SqlCorrectionBudget { + attemptCount: number; + maxAttempts: number; + remainingAttempts: number; + exhausted: boolean; +} + +const CORRECTABLE_ERROR_MARKERS = [ + "syntax", + "missing column", + "unknown column", + "dialect", + "join path", + "relationship", + "ambiguous_join_path" +]; + +@Injectable() +export class SqlCorrectionService { + readonly maxAttempts = 2; + + decide(error: unknown): SqlCorrectionDecision { + const validationArtifact = this.readValidationArtifact(error); + if (validationArtifact?.status === "failed" && validationArtifact.failure) { + return { + ...this.decideFromValidationFailure(validationArtifact.failure), + failedObligationIds: validationArtifact.failedObligationIds + }; + } + + const validationFailure = this.readValidationFailure(error); + if (validationFailure) { + return this.decideFromValidationFailure(validationFailure); + } + + if (error instanceof DomainError) { + if ( + error.code === "SQL_TERMINAL_VALIDATION_FAILED" || + error.code === "TABLE_PERMISSIONS_FORBIDDEN" || + error.code === "TABLE_PERMISSIONS_PARSE_REJECTED" + ) { + return { + correctable: false, + reason: error.message, + maxAttempts: 0, + category: "governance", + source: "validation", + failureCode: error.code + }; + } + if (error.code.includes("PROVIDER") || error.code.includes("DATASOURCE_UNAVAILABLE")) { + return { + correctable: false, + reason: error.message, + maxAttempts: 0, + category: "provider", + source: "execution", + failureCode: error.code + }; + } + } + + const message = error instanceof Error ? error.message : String(error ?? ""); + const normalized = message.trim().toLowerCase(); + const correctable = CORRECTABLE_ERROR_MARKERS.some((marker) => + normalized.includes(marker) + ); + return { + correctable, + reason: normalized || "unknown", + maxAttempts: correctable ? this.maxAttempts : 0, + category: correctable ? "execution" : "unknown", + source: "execution" + }; + } + + resolveBudget(input: { + attemptCount: number; + maxAttempts?: number; + }): SqlCorrectionBudget { + const maxAttempts = Math.max( + 0, + Number.isFinite(input.maxAttempts) ? Number(input.maxAttempts) : this.maxAttempts + ); + const attemptCount = Math.max(0, Number(input.attemptCount)); + const remainingAttempts = Math.max(0, maxAttempts - attemptCount); + return { + attemptCount, + maxAttempts, + remainingAttempts, + exhausted: attemptCount >= maxAttempts + }; + } + + private decideFromValidationFailure( + failure: Text2SqlV2FailureSemantic + ): SqlCorrectionDecision { + const category = this.mapFailureCategory(failure); + const failureCode = failure.code; + const terminal = Boolean(failure.terminal); + const explicitlyCorrectable = Boolean(failure.correctable); + const codeCorrectable = this.isCorrectableValidationCode(failureCode); + const correctable = !terminal && (explicitlyCorrectable || codeCorrectable); + + return { + correctable, + reason: failure.message, + maxAttempts: correctable ? this.maxAttempts : 0, + category, + source: "validation", + failureCode + }; + } + + private mapFailureCategory( + failure: Text2SqlV2FailureSemantic + ): SqlCorrectionDecision["category"] { + if (failure.category === "governance") { + return "governance"; + } + if (failure.category === "validation") { + if (failure.code.includes("SAFETY")) { + return "safety"; + } + if (failure.code.includes("PROVIDER")) { + return "provider"; + } + return "validation"; + } + if (failure.category === "execution") { + return "execution"; + } + return "unknown"; + } + + private isCorrectableValidationCode(code: string): boolean { + return ( + code === "SQL_PARSE_EMPTY" || + code === "SQL_PARSE_UNSUPPORTED_STATEMENT" || + code === "SQL_PARSE_MULTI_STATEMENT" || + code === "SQL_DIALECT_MISMATCH" || + code === "SQL_RELATIONSHIP_PATH_MISMATCH" || + code === "SQL_RELATIONSHIP_PATH_MISSING_JOIN" || + code === "SQL_DRY_RUN_PARSE_REJECTED" || + code === "SQL_DRY_PLAN_RELATIONSHIP_MISMATCH" || + code === "SQL_PLAN_COVERAGE_OUTSIDE_SELECTED_TABLES" || + code === "SQL_MISSING_COLUMN" + ); + } + + private readValidationFailure(error: unknown): Text2SqlV2FailureSemantic | undefined { + if (!(error instanceof DomainError)) { + return undefined; + } + const details = this.asRecord(error.details); + const validationFailure = this.asRecord(details?.validationFailure); + if (!validationFailure) { + return undefined; + } + const code = this.readString(validationFailure.code); + const message = this.readString(validationFailure.message); + if (!code || !message) { + return undefined; + } + return { + code, + message, + category: + validationFailure.category === "validation" || + validationFailure.category === "governance" || + validationFailure.category === "execution" + ? validationFailure.category + : "unknown", + terminal: + typeof validationFailure.terminal === "boolean" + ? validationFailure.terminal + : undefined, + correctable: + typeof validationFailure.correctable === "boolean" + ? validationFailure.correctable + : undefined + }; + } + + private readValidationArtifact(error: unknown): SqlValidationArtifactV1 | undefined { + if (!(error instanceof DomainError)) { + return undefined; + } + const details = this.asRecord(error.details); + const validationArtifact = this.asRecord(details?.validationArtifact); + if (!validationArtifact) { + return undefined; + } + const status = this.readString(validationArtifact.status); + if (status !== "failed") { + return undefined; + } + const checks = this.readValidationChecks(validationArtifact.checks); + const failure = this.readValidationFailureFromRecord(validationArtifact.failure); + if (!failure) { + return undefined; + } + return { + status: "failed", + checks, + correctable: Boolean(validationArtifact.correctable), + failure, + failedObligationIds: this.readStringArray(validationArtifact.failedObligationIds), + terminalObligationIds: this.readStringArray(validationArtifact.terminalObligationIds), + correctableObligationIds: this.readStringArray(validationArtifact.correctableObligationIds) + }; + } + + private readValidationFailureFromRecord( + value: unknown + ): Text2SqlV2FailureSemantic | undefined { + const record = this.asRecord(value); + if (!record) { + return undefined; + } + const code = this.readString(record.code); + const message = this.readString(record.message); + if (!code || !message) { + return undefined; + } + return { + code, + message, + category: + record.category === "validation" || + record.category === "governance" || + record.category === "execution" + ? record.category + : "unknown", + terminal: typeof record.terminal === "boolean" ? record.terminal : undefined, + correctable: + typeof record.correctable === "boolean" ? record.correctable : undefined + }; + } + + private readValidationChecks(value: unknown): SqlValidationCheckV1[] { + if (!Array.isArray(value)) { + return []; + } + return value + .map((item) => this.asRecord(item)) + .filter((item): item is Record => Boolean(item)) + .map((item) => { + const check = this.readString(item.check); + const status = this.readString(item.status); + if ( + (check !== "parse" && + check !== "read-only" && + check !== "permission" && + check !== "plan-coverage" && + check !== "relationship-path" && + check !== "dialect" && + check !== "dry-run" && + check !== "dry-plan" && + check !== "ledger-fulfillment") || + (status !== "passed" && status !== "failed" && status !== "skipped") + ) { + return undefined; + } + return { + check, + status, + ...(this.readString(item.code) ? { code: this.readString(item.code) } : {}), + ...(this.readString(item.message) + ? { message: this.readString(item.message) } + : {}), + ...(this.readStringArray(item.obligationIds).length > 0 + ? { obligationIds: this.readStringArray(item.obligationIds) } + : {}), + ...(this.readStringArray(item.failedObligationIds).length > 0 + ? { failedObligationIds: this.readStringArray(item.failedObligationIds) } + : {}), + ...(this.readStringArray(item.reasonCodes).length > 0 + ? { reasonCodes: this.readStringArray(item.reasonCodes) } + : {}) + }; + }) + .filter((item): item is SqlValidationCheckV1 => Boolean(item)); + } + + private asRecord(value: unknown): Record | undefined { + if (!value || typeof value !== "object" || Array.isArray(value)) { + return undefined; + } + return value as Record; + } + + private readString(value: unknown): string | undefined { + if (typeof value !== "string") { + return undefined; + } + const normalized = value.trim(); + return normalized.length > 0 ? normalized : undefined; + } + + private readStringArray(value: unknown): string[] { + if (!Array.isArray(value)) { + return []; + } + return value + .map((item) => this.readString(item)) + .filter((item): item is string => Boolean(item)); + } +} diff --git a/apps/backend/src/modules/conversation/adapters/sql-validation.service.ts b/apps/backend/src/modules/conversation/adapters/sql-validation.service.ts new file mode 100644 index 0000000..073872b --- /dev/null +++ b/apps/backend/src/modules/conversation/adapters/sql-validation.service.ts @@ -0,0 +1,866 @@ +import { Injectable, Optional } from "@nestjs/common"; +import type { + DatasourceType, + SemanticPlanV1, + SqlGenerationArtifactV1, + SqlValidationArtifactV1, + SqlValidationCheckV1 +} from "@text2sql/shared-types"; +import { + QueryExecutorRouterService, + type SqlTableAccessContext +} from "../../platform/data/query"; +import { RelationshipDryRunService } from "../../platform/data/query/relationship-dry-run.service"; + +interface ValidateSqlInput { + sql: string; + datasourceId?: string; + datasourceType?: DatasourceType; + semanticPlan?: SemanticPlanV1; + sqlArtifact?: SqlGenerationArtifactV1; + accessContext?: SqlTableAccessContext; + allowedTables?: string[]; +} + +type RouteKind = "text_to_sql" | "metadata" | "general" | "clarify" | "fail_closed"; +export type SqlValidationOutcome = "pass" | "correctable" | "terminal"; + +@Injectable() +export class SqlValidationService { + constructor( + @Optional() + private readonly queryExecutorRouter?: QueryExecutorRouterService, + @Optional() + private readonly relationshipDryRunService?: RelationshipDryRunService + ) {} + + async validate(input: ValidateSqlInput): Promise { + const checks: SqlValidationCheckV1[] = []; + const sql = input.sql.trim(); + const routeKind = this.resolveRouteKind(input.semanticPlan); + + const readOnlyStatus = this.validateReadOnly(sql); + checks.push(readOnlyStatus); + + const parseStatus = this.validateParse(sql); + checks.push(parseStatus); + + const permissionStatus = this.validatePermission({ + sql, + semanticPlan: input.semanticPlan, + accessContext: input.accessContext, + allowedTables: input.allowedTables + }); + checks.push(permissionStatus); + + const planCoverage = this.validatePlanCoverage({ + sql, + semanticPlan: input.semanticPlan, + routeKind + }); + checks.push(planCoverage); + + checks.push(this.validateRelationshipPath(sql, input.semanticPlan)); + const ledgerFulfillment = this.validateLedgerFulfillment({ + sql, + semanticPlan: input.semanticPlan, + sqlArtifact: input.sqlArtifact + }); + checks.push(ledgerFulfillment.check); + checks.push(this.validateDialect(sql, input.datasourceType)); + checks.push( + this.validateDryRun({ + sql, + datasourceType: input.datasourceType, + parseStatus, + readOnlyStatus + }) + ); + checks.push( + this.validateDryPlan({ + sql, + semanticPlan: input.semanticPlan, + routeKind, + datasourceType: input.datasourceType + }) + ); + + const failedChecks = checks.filter((check) => check.status === "failed"); + if (failedChecks.length === 0) { + return { + status: "passed", + checks, + correctable: false, + ledgerFulfillment: ledgerFulfillment.summary + }; + } + + const failure = this.selectPrimaryFailure(failedChecks); + const correctable = this.isCorrectableFailure(failure.check, failure.code); + const failedObligationIds = this.unique( + failedChecks.flatMap((check) => check.failedObligationIds ?? []) + ); + return { + status: "failed", + checks, + correctable, + ledgerFulfillment: ledgerFulfillment.summary, + ...(failedObligationIds.length > 0 ? { failedObligationIds } : {}), + ...(correctable + ? { correctableObligationIds: failedObligationIds } + : failedObligationIds.length > 0 + ? { terminalObligationIds: failedObligationIds } + : {}), + failure: { + code: failure.code ?? "SQL_VALIDATION_FAILED", + message: failure.message ?? "SQL validation failed", + category: this.toFailureCategory(failure.check, failure.code), + terminal: !correctable, + correctable + } + }; + } + + resolveOutcome(artifact: SqlValidationArtifactV1): SqlValidationOutcome { + if (artifact.status === "passed") { + return "pass"; + } + if (artifact.status === "failed" && artifact.correctable && !artifact.failure?.terminal) { + return "correctable"; + } + return "terminal"; + } + + private validateParse(sql: string): SqlValidationCheckV1 { + if (!sql) { + return { + check: "parse", + status: "failed", + code: "SQL_PARSE_EMPTY", + message: "SQL 不能为空" + }; + } + const statementWithoutTailSemicolon = sql.replace(/;+\s*$/, ""); + if (statementWithoutTailSemicolon.includes(";")) { + return { + check: "parse", + status: "failed", + code: "SQL_PARSE_MULTI_STATEMENT", + message: "仅支持单条只读 SQL 查询" + }; + } + const normalized = statementWithoutTailSemicolon.toLowerCase(); + if (!normalized.startsWith("select") && !normalized.startsWith("with")) { + return { + check: "parse", + status: "failed", + code: "SQL_PARSE_UNSUPPORTED_STATEMENT", + message: "仅支持 SELECT 或 WITH 查询" + }; + } + return { + check: "parse", + status: "passed" + }; + } + + private validateReadOnly(sql: string): SqlValidationCheckV1 { + if (/\b(insert|update|delete|drop|alter|truncate|create|grant|revoke|replace|merge)\b/i.test(sql)) { + return { + check: "read-only", + status: "failed", + code: "SQL_READ_ONLY_VIOLATION", + message: "检测到写操作或 DDL，已阻止执行" + }; + } + return { + check: "read-only", + status: "passed" + }; + } + + private validatePermission(input: { + sql: string; + semanticPlan?: SemanticPlanV1; + accessContext?: SqlTableAccessContext; + allowedTables?: string[]; + }): SqlValidationCheckV1 { + const allowedTables = new Set( + this.normalizeList([ + ...(input.allowedTables ?? []), + ...(input.semanticPlan?.allowedTables ?? []), + ...(input.accessContext?.allowedTables ?? []) + ]) + ); + const forbiddenTables = new Set(this.normalizeList(input.semanticPlan?.forbiddenTables ?? [])); + + const tables = this.extractTables(input.sql); + const denied = tables.filter((table) => forbiddenTables.has(table)); + if (denied.length > 0) { + return { + check: "permission", + status: "failed", + code: "SQL_TABLE_PERMISSION_DENIED", + message: `命中语义计划禁用表: ${denied.join(", ")}` + }; + } + + if (allowedTables.size > 0) { + const outsideAllowed = tables.filter((table) => !allowedTables.has(table)); + if (outsideAllowed.length > 0) { + return { + check: "permission", + status: "failed", + code: "SQL_TABLE_PERMISSION_DENIED", + message: `未授权表: ${outsideAllowed.join(", ")}` + }; + } + } + + const selectedColumns = new Set( + this.normalizeList(input.semanticPlan?.selectedColumns ?? []).filter((column) => + column.includes(".") + ) + ); + if (selectedColumns.size > 0) { + const referenced = this.extractTableColumns(input.sql); + const outsideColumns = referenced.filter((column) => !selectedColumns.has(column)); + if (outsideColumns.length > 0) { + return { + check: "permission", + status: "failed", + code: "SQL_COLUMN_PERMISSION_DENIED", + message: `命中语义计划外字段: ${outsideColumns.join(", ")}` + }; + } + } + + if (allowedTables.size === 0) { + return { + check: "permission", + status: "skipped", + message: "permission check skipped: allowed tables not configured" + }; + } + + return { + check: "permission", + status: "passed" + }; + } + + private validatePlanCoverage(input: { + sql: string; + semanticPlan?: SemanticPlanV1; + routeKind: RouteKind; + }): SqlValidationCheckV1 { + const semanticPlan = input.semanticPlan; + if (!semanticPlan) { + return { + check: "plan-coverage", + status: "skipped", + message: "plan coverage skipped: semantic plan missing" + }; + } + + if (semanticPlan.route === "reject" || input.routeKind === "fail_closed") { + return { + check: "plan-coverage", + status: "failed", + code: "SQL_PLAN_FAIL_CLOSED", + message: "语义计划已进入 fail-closed 路径，禁止执行 SQL" + }; + } + if (semanticPlan.route === "clarify" || input.routeKind === "clarify") { + return { + check: "plan-coverage", + status: "failed", + code: "SQL_PLAN_REQUIRES_CLARIFICATION", + message: "语义计划要求先澄清问题，禁止直接执行 SQL" + }; + } + if (input.routeKind === "metadata" || input.routeKind === "general") { + return { + check: "plan-coverage", + status: "passed", + message: "non text-to-sql route" + }; + } + + const selectedTables = new Set(this.normalizeList(semanticPlan.selectedTables)); + if (selectedTables.size === 0) { + return { + check: "plan-coverage", + status: "failed", + code: "SQL_PLAN_MISSING_SELECTED_TABLES", + message: "语义计划缺少 selectedTables，无法放行执行" + }; + } + + const tables = this.extractTables(input.sql); + const outsidePlan = tables.filter((table) => !selectedTables.has(table)); + if (outsidePlan.length > 0) { + return { + check: "plan-coverage", + status: "failed", + code: "SQL_PLAN_COVERAGE_OUTSIDE_SELECTED_TABLES", + message: `SQL 使用了计划外表: ${outsidePlan.join(", ")}` + }; + } + + return { + check: "plan-coverage", + status: "passed" + }; + } + + private validateRelationshipPath(sql: string, semanticPlan?: SemanticPlanV1): SqlValidationCheckV1 { + const joinPath = this.normalizeJoinPath(semanticPlan?.joinPath ?? []); + const selectedTables = this.normalizeList(semanticPlan?.selectedTables ?? []); + if (joinPath.length === 0 && selectedTables.length <= 1) { + return { + check: "relationship-path", + status: "skipped" + }; + } + + const sqlUsesJoin = /\bjoin\b/i.test(sql); + if (!sqlUsesJoin && selectedTables.length > 1) { + return { + check: "relationship-path", + status: "failed", + code: "SQL_RELATIONSHIP_PATH_MISSING_JOIN", + message: "语义计划包含多表绑定，但 SQL 未使用 JOIN" + }; + } + + const referencedTables = this.extractTables(sql); + const missingTables = selectedTables.filter((table) => !referencedTables.includes(table)); + if (missingTables.length > 0) { + return { + check: "relationship-path", + status: "failed", + code: "SQL_RELATIONSHIP_PATH_MISMATCH", + message: `SQL 缺少语义计划关联表: ${missingTables.join(", ")}` + }; + } + + return { + check: "relationship-path", + status: "passed" + }; + } + + private validateLedgerFulfillment(input: { + sql: string; + semanticPlan?: SemanticPlanV1; + sqlArtifact?: SqlGenerationArtifactV1; + }): { check: SqlValidationCheckV1; summary?: SqlValidationArtifactV1["ledgerFulfillment"] } { + const ledger = input.semanticPlan?.planLedger; + if (!ledger) { + return { + check: { + check: "ledger-fulfillment", + status: "skipped", + message: "ledger fulfillment skipped: semantic plan ledger missing" + } + }; + } + + const tables = this.extractTables(input.sql); + const tableColumns = this.extractTableColumns(input.sql); + const columns = this.unique([ + ...tableColumns.map((column) => column.split(".").at(-1) ?? column), + ...this.extractSimpleSelectColumns(input.sql), + ...(input.sqlArtifact?.usedColumns ?? []).map((column) => + this.normalizeQualifiedIdentifier(column)?.split(".").at(-1) ?? "" + ) + ]); + const claimedObligationIds = new Set(input.sqlArtifact?.claimedObligationIds ?? []); + const failed: Array<{ id: string; reasonCode: string; terminal: boolean }> = []; + + for (const obligation of ledger.obligations) { + if (obligation.criticality !== "hard_blocker") { + continue; + } + if (claimedObligationIds.has(obligation.id)) { + continue; + } + const subject = obligation.subject; + const normalizedSubject = this.normalizeIdentifier(subject); + const qualifiedSubject = this.normalizeQualifiedIdentifier(subject); + const fail = (reasonCode: string, terminal = false) => { + failed.push({ id: obligation.id, reasonCode, terminal }); + }; + if (obligation.kind === "forbidden_table" || obligation.kind === "permission") { + if (normalizedSubject && tables.includes(normalizedSubject)) { + fail("ledger_terminal_permission_obligation", true); + } + continue; + } + if (obligation.status === "failed" || obligation.status === "unsupported") { + fail(obligation.reasonCodes[0] ?? "ledger_pre_generation_obligation_failed"); + continue; + } + if (obligation.kind === "table" && normalizedSubject && !tables.includes(normalizedSubject)) { + fail("ledger_table_not_used"); + } + if ( + obligation.kind === "column" && + qualifiedSubject && + !tableColumns.includes(qualifiedSubject) && + (!normalizedSubject || !columns.includes(normalizedSubject)) + ) { + fail("ledger_column_not_used"); + } + if ( + obligation.kind === "metric" && + normalizedSubject && + !new RegExp(`\\b${this.escapeRegex(normalizedSubject)}\\b`, "i").test(input.sql) && + !/\b(count|sum|avg|min|max)\s*\(/i.test(input.sql) + ) { + fail("ledger_metric_not_claimed"); + } + if ( + obligation.kind === "time_grain" && + !/\b(date_trunc|strftime|extract|group\s+by|where)\b/i.test(input.sql) + ) { + fail("ledger_time_grain_not_used"); + } + if (obligation.kind === "filter" && !/\bwhere\b/i.test(input.sql)) { + fail("ledger_filter_not_used"); + } + if (obligation.kind === "join_path" && !/\bjoin\b/i.test(input.sql)) { + fail("ledger_join_path_not_used"); + } + } + + for (const claim of input.sqlArtifact?.unsupportedClaims ?? []) { + failed.push({ + id: `unsupported:${claim.kind}:${claim.value}`, + reasonCode: claim.reasonCode, + terminal: true + }); + } + + const failedObligationIds = this.unique(failed.map((item) => item.id)); + const terminal = failed.some((item) => item.terminal); + const reasonCodes = this.unique(failed.map((item) => item.reasonCode)); + const summary = { + ...ledger.summary, + fulfilledCount: Math.max(0, ledger.summary.total - failedObligationIds.length), + failedCount: failedObligationIds.length, + failedHardBlockerIds: failedObligationIds.filter((id) => !id.startsWith("unsupported:")), + unsupportedCount: failedObligationIds.filter((id) => id.startsWith("unsupported:")).length, + reasonCodes: reasonCodes.length > 0 ? reasonCodes : ledger.summary.reasonCodes + }; + + if (failedObligationIds.length === 0) { + return { + check: { + check: "ledger-fulfillment", + status: "passed", + obligationIds: ledger.obligations.map((obligation) => obligation.id), + reasonCodes: ["ledger_fulfilled"] + }, + summary + }; + } + + return { + check: { + check: "ledger-fulfillment", + status: "failed", + code: terminal + ? "SQL_LEDGER_TERMINAL_OBLIGATION_FAILED" + : "SQL_LEDGER_FULFILLMENT_FAILED", + message: terminal + ? "SQL contains terminal ledger violations" + : "SQL does not fulfill all required ledger obligations", + obligationIds: ledger.obligations.map((obligation) => obligation.id), + failedObligationIds, + reasonCodes + }, + summary + }; + } + + private validateDialect(sql: string, datasourceType?: DatasourceType): SqlValidationCheckV1 { + if (!datasourceType || datasourceType === "sqlite") { + if (/\bshow\s+tables\b/i.test(sql)) { + return { + check: "dialect", + status: "failed", + code: "SQL_DIALECT_MISMATCH", + message: "SQLite 不支持 SHOW TABLES 语法" + }; + } + return { + check: "dialect", + status: "passed" + }; + } + if (datasourceType === "mysql" && /\bpragma\b/i.test(sql)) { + return { + check: "dialect", + status: "failed", + code: "SQL_DIALECT_MISMATCH", + message: "MySQL 不支持 PRAGMA 语法" + }; + } + if (datasourceType === "postgresql" && /\bstrftime\s*\(/i.test(sql)) { + return { + check: "dialect", + status: "failed", + code: "SQL_DIALECT_MISMATCH", + message: "PostgreSQL 不支持 strftime 函数" + }; + } + return { + check: "dialect", + status: "passed" + }; + } + + private validateDryRun(input: { + sql: string; + datasourceType?: DatasourceType; + parseStatus: SqlValidationCheckV1; + readOnlyStatus: SqlValidationCheckV1; + }): SqlValidationCheckV1 { + if (input.parseStatus.status === "failed" || input.readOnlyStatus.status === "failed") { + return { + check: "dry-run", + status: "skipped", + message: "dry-run skipped because parse/read-only check already failed" + }; + } + + const capability = this.resolveDryRunCapability(input.datasourceType); + if (!capability.supported) { + return { + check: "dry-run", + status: "skipped", + code: "SQL_DRY_RUN_UNSUPPORTED", + message: capability.reason + }; + } + + const dryPlan = this.queryExecutorRouter?.buildDryPlan(input.sql); + if (dryPlan && !dryPlan.complete) { + return { + check: "dry-run", + status: "failed", + code: "SQL_DRY_RUN_PARSE_REJECTED", + message: dryPlan.reason ?? "dry-run parse rejected" + }; + } + + return { + check: "dry-run", + status: "passed" + }; + } + + private validateDryPlan(input: { + sql: string; + semanticPlan?: SemanticPlanV1; + routeKind: RouteKind; + datasourceType?: DatasourceType; + }): SqlValidationCheckV1 { + if (!input.semanticPlan) { + return { + check: "dry-plan", + status: "skipped", + message: "dry-plan skipped: semantic plan missing" + }; + } + if (input.routeKind === "metadata" || input.routeKind === "general") { + return { + check: "dry-plan", + status: "skipped", + message: "dry-plan skipped: non text-to-sql route" + }; + } + + const capability = this.resolveDryPlanCapability(input.datasourceType); + if (!capability.supported) { + return { + check: "dry-plan", + status: "skipped", + code: "SQL_DRY_PLAN_UNSUPPORTED", + message: capability.reason + }; + } + + const dryPlanSnapshot = this.relationshipDryRunService?.evaluateJoinPathConsistency({ + sql: input.sql, + selectedTables: input.semanticPlan.selectedTables, + joinPath: input.semanticPlan.joinPath + }); + if (dryPlanSnapshot && !dryPlanSnapshot.pass) { + return { + check: "dry-plan", + status: "failed", + code: "SQL_DRY_PLAN_RELATIONSHIP_MISMATCH", + message: + dryPlanSnapshot.reason ?? + "dry-plan relationship consistency check failed" + }; + } + + return { + check: "dry-plan", + status: "passed" + }; + } + + private resolveDryRunCapability(datasourceType?: DatasourceType): { + supported: boolean; + reason?: string; + } { + if (!datasourceType) { + return { + supported: false, + reason: "dry-run skipped: datasource type unknown" + }; + } + const fromRouter = this.queryExecutorRouter?.getValidationCapabilities(datasourceType); + if (fromRouter) { + return { + supported: fromRouter.dryRun, + reason: fromRouter.dryRun ? undefined : fromRouter.reason + }; + } + if (datasourceType === "csv" || datasourceType === "excel") { + return { + supported: false, + reason: `${datasourceType} datasource does not support dry-run precheck` + }; + } + return { + supported: true + }; + } + + private resolveDryPlanCapability(datasourceType?: DatasourceType): { + supported: boolean; + reason?: string; + } { + if (!datasourceType) { + return { + supported: false, + reason: "dry-plan skipped: datasource type unknown" + }; + } + const fromRouter = this.queryExecutorRouter?.getValidationCapabilities(datasourceType); + if (fromRouter) { + return { + supported: fromRouter.dryPlan, + reason: fromRouter.dryPlan ? undefined : fromRouter.reason + }; + } + return { + supported: true + }; + } + + private selectPrimaryFailure(failures: SqlValidationCheckV1[]): SqlValidationCheckV1 { + const severity = (failure: SqlValidationCheckV1): number => { + if (failure.check === "read-only") { + return 100; + } + if (failure.check === "permission") { + return 90; + } + if (failure.code === "SQL_PLAN_FAIL_CLOSED" || failure.code === "SQL_PLAN_REQUIRES_CLARIFICATION") { + return 80; + } + if (failure.code?.includes("PROVIDER")) { + return 75; + } + if (failure.check === "parse") { + return 70; + } + if (failure.check === "dialect") { + return 60; + } + if (failure.check === "relationship-path" || failure.check === "dry-plan") { + return 55; + } + if (failure.check === "ledger-fulfillment") { + return failure.code === "SQL_LEDGER_TERMINAL_OBLIGATION_FAILED" ? 85 : 52; + } + if (failure.check === "plan-coverage") { + return 50; + } + return 10; + }; + + return [...failures].sort((left, right) => severity(right) - severity(left))[0]; + } + + private isCorrectableFailure(check: SqlValidationCheckV1["check"], code?: string): boolean { + if (check === "read-only" || check === "permission") { + return false; + } + if (code === "SQL_PLAN_FAIL_CLOSED" || code === "SQL_PLAN_REQUIRES_CLARIFICATION") { + return false; + } + if (code?.includes("PROVIDER") || code === "SQL_DRY_RUN_UNSUPPORTED") { + return false; + } + if (code === "SQL_DRY_PLAN_UNSUPPORTED") { + return false; + } + if (check === "ledger-fulfillment") { + return code !== "SQL_LEDGER_TERMINAL_OBLIGATION_FAILED"; + } + if (check === "parse" || check === "relationship-path" || check === "dialect") { + return true; + } + if (check === "plan-coverage" || check === "dry-run" || check === "dry-plan") { + return true; + } + if (code === "SQL_MISSING_COLUMN") { + return true; + } + return false; + } + + private toFailureCategory( + check: SqlValidationCheckV1["check"], + code?: string + ): "validation" | "governance" | "unknown" { + if (check === "permission" || check === "read-only") { + return "governance"; + } + if (code?.includes("PROVIDER")) { + return "unknown"; + } + return "validation"; + } + + private resolveRouteKind(semanticPlan: SemanticPlanV1 | undefined): RouteKind { + if (!semanticPlan) { + return "text_to_sql"; + } + const routeFilter = (semanticPlan.filters ?? []).find((entry) => + entry.startsWith("route_kind:") + ); + if (routeFilter) { + const value = routeFilter.slice("route_kind:".length).trim(); + if ( + value === "text_to_sql" || + value === "metadata" || + value === "general" || + value === "clarify" || + value === "fail_closed" + ) { + return value; + } + } + if (semanticPlan.route === "clarify") { + return "clarify"; + } + if (semanticPlan.route === "reject") { + return "fail_closed"; + } + return "text_to_sql"; + } + + private extractTables(sql: string): string[] { + const matches = [ + ...sql.matchAll(/\b(?:from|join)\s+([a-zA-Z_][\w$]*(?:\.[a-zA-Z_][\w$]*)?)/gi) + ]; + const tables = matches + .map((match) => this.normalizeIdentifier(match[1])) + .filter((value): value is string => Boolean(value)); + return Array.from(new Set(tables)); + } + + private extractTableColumns(sql: string): string[] { + const matches = [...sql.matchAll(/\b([a-zA-Z_][\w$]*)\.([a-zA-Z_][\w$]*)\b/g)]; + const normalized = matches + .map((match) => { + const table = this.normalizeIdentifier(match[1]); + const column = this.normalizeIdentifier(match[2]); + if (!table || !column) { + return undefined; + } + return `${table}.${column}`; + }) + .filter((value): value is string => Boolean(value)); + return Array.from(new Set(normalized)); + } + + private extractSimpleSelectColumns(sql: string): string[] { + const selectMatch = /\bselect\b([\s\S]*?)\bfrom\b/i.exec(sql); + if (!selectMatch?.[1]) { + return []; + } + const parsed: string[] = []; + for (const chunk of selectMatch[1].split(",")) { + let candidate = chunk.trim(); + if (!candidate || candidate === "*" || candidate.includes(".") || candidate.includes("(")) { + continue; + } + candidate = candidate.replace(/\bas\s+[a-zA-Z_][\w$]*$/i, "").trim(); + candidate = candidate.replace(/^distinct\s+/i, "").trim(); + const match = /^([a-zA-Z_][\w$]*)/.exec(candidate); + const normalized = this.normalizeIdentifier(match?.[1]); + if (normalized) { + parsed.push(normalized); + } + } + return this.unique(parsed); + } + + private normalizeJoinPath(values: string[]): string[] { + return Array.from( + new Set(values.map((value) => value.trim()).filter((value) => value.length > 0)) + ); + } + + private normalizeQualifiedIdentifier(value: string | undefined): string | undefined { + if (!value) { + return undefined; + } + const normalized = value + .trim() + .replace(/^[`"'\[\]]+|[`"'\[\]]+$/g, "") + .replace(/\s+/g, "") + .toLowerCase(); + return normalized.length > 0 ? normalized : undefined; + } + + private unique(values: string[]): string[] { + return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean))); + } + + private escapeRegex(value: string): string { + return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + } + + private normalizeList(values: string[]): string[] { + return Array.from( + new Set( + values + .map((value) => this.normalizeIdentifier(value)) + .filter((value): value is string => Boolean(value)) + ) + ); + } + + private normalizeIdentifier(value: string | undefined): string | undefined { + if (!value) { + return undefined; + } + const normalized = value + .trim() + .replace(/^[`"'\[\]]+|[`"'\[\]]+$/g, "") + .replace(/\s+/g, "") + .toLowerCase(); + return normalized.length > 0 ? normalized : undefined; + } +} diff --git a/apps/backend/src/modules/conversation/agent/agent.module.ts b/apps/backend/src/modules/conversation/agent/agent.module.ts index e9286d4..1e4d5f9 100644 --- a/apps/backend/src/modules/conversation/agent/agent.module.ts +++ b/apps/backend/src/modules/conversation/agent/agent.module.ts @@ -21,8 +21,6 @@ import { FormatAnswerNode } from "./nodes/format-answer.node"; import { RetrieveKnowledgeNode } from "./nodes/retrieve-knowledge.node"; import { BuildPhysicalPlanNode } from "./nodes/build-physical-plan.node"; import { BuildSemanticQueryNode } from "./nodes/build-semantic-query.node"; -import { GraphBuilderService } from "./graph/graph.builder"; -import { LangGraphRuntimeService } from "./graph/langgraph.runtime"; import { GenerateSqlNode } from "./nodes/generate-sql.node"; import { ResolveSavedPriorSqlNode } from "./nodes/resolve-saved-prior-sql.node"; import { SafetyCheckNode } from "./nodes/safety-check.node"; @@ -35,6 +33,25 @@ import { SqlSafetyGuard } from "./sql/tools/sql-safety.guard"; import { SqlToolRegistryService } from "./sql/tools/sql-tool-registry.service"; import { PlannerVersionLockService } from "./planner/planner-version-lock.service"; import { PlannerCacheService } from "./planner/planner-cache.service"; +import { SemanticContextPackService } from "../adapters/semantic-context-pack.service"; +import { SemanticPlanService } from "../adapters/semantic-plan.service"; +import { SemanticPlanValidator } from "../adapters/semantic-plan.validator"; +import { SqlValidationService } from "../adapters/sql-validation.service"; +import { SqlCorrectionService } from "../adapters/sql-correction.service"; +import { Text2SqlV2ArtifactBuilder } from "../artifacts/text2sql-v2-artifact-builder"; +import { Text2SqlV2ArtifactRefService } from "../artifacts/text2sql-v2-artifact-ref.service"; +import { Text2SqlV2LangGraphResultMapper } from "../runtime/langgraph/text2sql-v2-langgraph-result.mapper"; +import { Text2SqlV2LangGraphRunnerService } from "../runtime/langgraph/text2sql-v2-langgraph-runner.service"; +import { Text2SqlSmartDefaultsService } from "../runtime/smart-defaults/text2sql-smart-defaults.service"; +import { AnswerNode as LangGraphAnswerNode } from "../nodes/answer.node"; +import { AssembleContextNode as LangGraphAssembleContextNode } from "../nodes/assemble-context.node"; +import { CorrectSqlNode as LangGraphCorrectSqlNode } from "../nodes/correct-sql.node"; +import { ExecuteSqlNode as LangGraphExecuteSqlNode } from "../nodes/execute-sql.node"; +import { GenerateSqlNode as LangGraphGenerateSqlNode } from "../nodes/generate-sql.node"; +import { IntakeNode as LangGraphIntakeNode } from "../nodes/intake.node"; +import { RetrieveContextNode as LangGraphRetrieveContextNode } from "../nodes/retrieve-context.node"; +import { SemanticPlanNode as LangGraphSemanticPlanNode } from "../nodes/semantic-plan.node"; +import { ValidateSqlNode as LangGraphValidateSqlNode } from "../nodes/validate-sql.node"; @Module({ imports: [ @@ -60,8 +77,6 @@ import { PlannerCacheService } from "./planner/planner-cache.service"; >, inject: [KNOWLEDGE_FACADE_CONTRACT] }, - GraphBuilderService, - LangGraphRuntimeService, ClarifyNode, ClarificationSemanticEvaluatorService, ClarificationFusionPolicy, @@ -81,11 +96,30 @@ import { PlannerCacheService } from "./planner/planner-cache.service"; SqlGenerationService, SqlSafetyGuard, SqlReadonlyTool, - SqlToolRegistryService + SqlToolRegistryService, + SemanticContextPackService, + SemanticPlanService, + SemanticPlanValidator, + SqlValidationService, + SqlCorrectionService, + Text2SqlV2ArtifactRefService, + Text2SqlSmartDefaultsService, + LangGraphIntakeNode, + LangGraphRetrieveContextNode, + LangGraphAssembleContextNode, + LangGraphSemanticPlanNode, + LangGraphGenerateSqlNode, + LangGraphValidateSqlNode, + LangGraphCorrectSqlNode, + LangGraphExecuteSqlNode, + LangGraphAnswerNode, + Text2SqlV2ArtifactBuilder, + Text2SqlV2LangGraphResultMapper, + Text2SqlV2LangGraphRunnerService ], exports: [ - GraphBuilderService, - SqlToolRegistryService + SqlToolRegistryService, + Text2SqlV2LangGraphRunnerService ] }) export class AgentModule {} diff --git a/apps/backend/src/modules/conversation/agent/graph/agent-step-metadata.ts b/apps/backend/src/modules/conversation/agent/graph/agent-step-metadata.ts deleted file mode 100644 index 45f62c2..0000000 --- a/apps/backend/src/modules/conversation/agent/graph/agent-step-metadata.ts +++ /dev/null @@ -1,49 +0,0 @@ -import type { ReasoningStage } from "@text2sql/shared-types"; - -type AgentStepStatus = "success" | "failed" | "skipped"; - -const AGENT_STEP_STAGE_MAP: Record = { - clarify: "analysis", - "retrieve-knowledge": "analysis", - "build-intent-plan": "analysis", - "build-semantic-query": "analysis", - "build-physical-plan": "analysis", - "resolve-saved-prior-sql": "analysis", - "generate-sql": "generation", - "safety-check": "validation", - "execute-sql": "execution", - "format-answer": "response" -}; - -const AGENT_STEP_TITLE_MAP: Record = { - clarify: "理解问题", - "retrieve-knowledge": "检索上下文", - "build-intent-plan": "意图规划", - "build-semantic-query": "语义规划", - "build-physical-plan": "物理规划", - "resolve-saved-prior-sql": "Prior SQL 复用判断", - "generate-sql": "生成 SQL", - "safety-check": "安全校验", - "execute-sql": "执行查询", - "format-answer": "整理回答" -}; - -export const resolveAgentReasoningStage = (node: string): ReasoningStage => { - return AGENT_STEP_STAGE_MAP[node] ?? "unknown"; -}; - -export const resolveAgentReasoningTitle = (node: string): string => { - return AGENT_STEP_TITLE_MAP[node] ?? node; -}; - -export const resolveAgentStepLifecycle = ( - status: AgentStepStatus -): "completed" | "failed" | "skipped" => { - if (status === "failed") { - return "failed"; - } - if (status === "skipped") { - return "skipped"; - } - return "completed"; -}; diff --git a/apps/backend/src/modules/conversation/agent/graph/agent.types.ts b/apps/backend/src/modules/conversation/agent/graph/agent.types.ts deleted file mode 100644 index 6eecfce..0000000 --- a/apps/backend/src/modules/conversation/agent/graph/agent.types.ts +++ /dev/null @@ -1,63 +0,0 @@ -import type { - ClarificationPrompt, - ContextEnvelope, - DatasourceType, - ExecutionTrace -} from "@text2sql/shared-types"; -import type { SqlTableAccessContext } from "../../../platform/data/query/index"; - -export interface GraphTraceContext { - source: "chat" | "evaluation"; - route: string; - requestId?: string; - jobId?: string; - caseId?: string; -} - -export interface GraphInput { - runId: string; - sessionId: string; - question: string; - datasourceId: string; - datasourceType?: DatasourceType; - modelCatalogId?: string; - contextEnvelope?: ContextEnvelope; - planningScaffoldEnabled?: boolean; - traceContext?: GraphTraceContext; - accessContext?: SqlTableAccessContext; -} - -export interface GraphEffectiveContextSummary { - sourcePriority: "user_explicit_over_system"; - userEnvelope: { - metricDefinitionProvided: boolean; - timeRangeProvided: boolean; - entityMappingCount: number; - includeTableCount: number; - excludeTableCount: number; - businessConstraintCount: number; - }; - retrievalContext?: { - status?: "ready" | "degraded"; - selectedContextCount?: number; - }; -} - -export interface GraphContextConflictHint { - hasConflict: boolean; - preferredSource: "user_explicit"; - reasonCodes?: string[]; -} - -export interface GraphState extends GraphInput { - provider: string; - model?: string; - sql?: string; - explanation?: string; - rows?: Array>; - columns?: string[]; - answer?: string; - error?: string; - clarification?: ClarificationPrompt; - trace: ExecutionTrace; -} diff --git a/apps/backend/src/modules/conversation/agent/graph/graph.builder.ts b/apps/backend/src/modules/conversation/agent/graph/graph.builder.ts deleted file mode 100644 index 66497e1..0000000 --- a/apps/backend/src/modules/conversation/agent/graph/graph.builder.ts +++ /dev/null @@ -1,415 +0,0 @@ -import { Injectable } from "@nestjs/common"; -import type { - ContextEnvelope, - ContextEnvelopePinningEvidence, - ExecutionTraceStep, - SqlRun -} from "@text2sql/shared-types"; -import type { - LlmGatewayStreamEvent, - LlmGatewayToolDefinition -} from "../../../llm/llm-gateway.interface"; -import type { - GraphContextConflictHint, - GraphEffectiveContextSummary, - GraphInput -} from "./agent.types"; -import { - createInitialLangGraphState, - normalizeTraceContext, - type LangGraphSpanEvent, - type LangGraphState -} from "./langgraph.state"; -import { LangGraphRuntimeService } from "./langgraph.runtime"; -import { LangsmithTraceService } from "../../../observability/langsmith-trace.service"; -import { AppConfigService } from "../../../config/app-config.service"; - -export interface GraphRunOptions { - streamMode?: boolean; - tools?: Record; - onLlmEvent?: (event: LlmGatewayStreamEvent) => Promise | void; - onStep?: (event: LangGraphSpanEvent) => Promise | void; -} - -interface GraphContextEvidence { - effectiveContextSummary?: GraphEffectiveContextSummaryWithPinning; - conflictHint?: GraphContextConflictHint; -} - -const CONTEXT_CONFLICT_REGEX = /conflict|mismatch|contradict|inconsistent|冲突/i; - -interface GraphEffectiveContextSummaryWithPinning extends GraphEffectiveContextSummary { - userEnvelope: GraphEffectiveContextSummary["userEnvelope"] & { - pinnedTableCount?: number; - pinnedColumnCount?: number; - }; - retrievalContext?: GraphEffectiveContextSummary["retrievalContext"] & { - pinning?: ContextEnvelopePinningEvidence; - }; -} - -@Injectable() -export class GraphBuilderService { - constructor( - private readonly langGraphRuntime: LangGraphRuntimeService, - private readonly langsmithTrace: LangsmithTraceService, - private readonly config: AppConfigService - ) {} - - async run(input: GraphInput, options?: GraphRunOptions): Promise { - const traceContext = normalizeTraceContext(input.traceContext); - const initialState = createInitialLangGraphState( - { - ...input, - planningScaffoldEnabled: - input.planningScaffoldEnabled ?? this.config.agentPlanningScaffoldEnabled, - traceContext - }, - "volcengine" - ); - const rootTrace = this.langsmithTrace.startRoot({ - runId: input.runId, - sessionId: input.sessionId, - question: input.question, - source: traceContext.source, - route: traceContext.route, - requestId: traceContext.requestId, - jobId: traceContext.jobId, - caseId: traceContext.caseId - }); - let runtimeState: LangGraphState | undefined; - let rootEnded = false; - - try { - runtimeState = await this.langGraphRuntime.invoke(initialState, { - configurable: { - thread_id: input.runId, - runId: input.runId, - streamMode: options?.streamMode, - tools: options?.tools, - onLlmEvent: options?.onLlmEvent, - onStep: async (step: ExecutionTraceStep) => { - await options?.onStep?.({ - step - }); - } - } - }); - this.flushSpanEvents(rootTrace, runtimeState.spanEvents); - if (runtimeState.fatalError) { - const message = this.toErrorMessage(runtimeState.fatalError); - this.langsmithTrace.endRoot(rootTrace, { - status: "failed", - provider: runtimeState.provider, - error: message, - metadata: this.compact({ - requestId: traceContext.requestId, - route: traceContext.route, - source: traceContext.source, - jobId: traceContext.jobId, - caseId: traceContext.caseId - }) - }); - rootEnded = true; - throw runtimeState.fatalError; - } - const finalizedRun = this.toRun( - runtimeState, - this.resolveTerminalStatus(runtimeState) - ); - this.langsmithTrace.endRoot(rootTrace, { - status: finalizedRun.status, - provider: finalizedRun.provider, - outputs: this.compact({ - rowCount: finalizedRun.rows?.length, - hasError: Boolean(finalizedRun.error), - retrievalStatus: runtimeState.retrievalBundle?.status, - selectedContextCount: runtimeState.retrievalBundle?.selected_context?.length ?? 0 - }), - metadata: this.compact({ - requestId: traceContext.requestId, - route: traceContext.route, - source: traceContext.source, - jobId: traceContext.jobId, - caseId: traceContext.caseId - }) - }); - rootEnded = true; - return finalizedRun; - } catch (error) { - if (!rootEnded) { - this.langsmithTrace.endRoot(rootTrace, { - status: "failed", - provider: runtimeState?.provider ?? initialState.provider, - error: this.toErrorMessage(error), - metadata: this.compact({ - requestId: traceContext.requestId, - route: traceContext.route, - source: traceContext.source, - jobId: traceContext.jobId, - caseId: traceContext.caseId - }) - }); - } - throw error; - } - } - - private resolveTerminalStatus(state: LangGraphState): SqlRun["status"] { - if (state.terminalStatus) { - return state.terminalStatus; - } - return state.error ? "failed" : "executionResult"; - } - - private flushSpanEvents( - rootTrace: ReturnType, - spanEvents: LangGraphSpanEvent[] - ): void { - for (const event of spanEvents) { - this.langsmithTrace.recordSpan(rootTrace, { - node: event.step.node, - status: event.step.status, - detail: event.step.detail, - runType: event.runType, - inputs: event.inputs, - outputs: event.outputs, - metadata: event.metadata, - error: event.error - }); - } - } - - private toRun(state: LangGraphState, status: SqlRun["status"]): SqlRun { - const normalizedTrace = this.normalizeTrace(state.trace, state.runId, state.provider); - const contextEvidence = this.buildContextEvidence(state); - const traceWithContext = this.withContextEvidence(normalizedTrace, contextEvidence); - return { - runId: state.runId, - sessionId: state.sessionId, - question: state.question, - status, - provider: state.provider, - model: state.model, - sql: state.sql, - explanation: state.explanation, - answer: state.answer, - rows: state.rows, - columns: state.columns, - error: state.error, - clarification: state.clarification, - trace: traceWithContext, - llmRaw: state.llmRaw ?? null, - createdAt: new Date().toISOString() - }; - } - - private normalizeTrace( - trace: SqlRun["trace"], - runId: string, - provider: string - ): SqlRun["trace"] { - return { - ...trace, - runId: trace.runId ?? runId, - provider: trace.provider ?? provider, - retryCount: trace.retryCount ?? 0, - steps: (trace.steps ?? []).map((step, index) => { - const sequence = step.sequence ?? index + 1; - return { - ...step, - sequence, - stepId: step.stepId ?? `${runId}:${step.node}:${sequence}`, - lifecycle: - step.lifecycle ?? - (step.status === "failed" - ? "failed" - : step.status === "skipped" - ? "skipped" - : "completed") - }; - }) - }; - } - - private toErrorMessage(error: unknown): string { - if (error instanceof Error) { - return error.message; - } - return String(error); - } - - private compact(payload: Record): Record { - return Object.fromEntries( - Object.entries(payload).filter(([, value]) => value !== undefined) - ); - } - - private withContextEvidence( - trace: SqlRun["trace"], - contextEvidence: GraphContextEvidence - ): SqlRun["trace"] { - if (!contextEvidence.effectiveContextSummary && !contextEvidence.conflictHint) { - return trace; - } - return { - ...trace, - ...(contextEvidence.effectiveContextSummary - ? { - effectiveContextSummary: contextEvidence.effectiveContextSummary - } - : {}), - ...(contextEvidence.conflictHint - ? { - conflictHint: contextEvidence.conflictHint - } - : {}) - } as SqlRun["trace"]; - } - - private buildContextEvidence(state: LangGraphState): GraphContextEvidence { - const envelope = state.contextEnvelope; - if (!this.hasContextEnvelope(envelope)) { - return {}; - } - - const includeTableCount = this.countNonEmptyStrings(envelope?.mustIncludeTables); - const excludeTableCount = this.countNonEmptyStrings(envelope?.mustExcludeTables); - const pinnedTableCount = this.countNonEmptyStrings(envelope?.pinnedTables); - const pinnedColumnCount = this.countNonEmptyStrings(envelope?.pinnedColumns); - const entityMappingCount = this.countEntityMappings(envelope?.entityMappings); - const effectiveContextSummary: GraphEffectiveContextSummaryWithPinning = { - sourcePriority: "user_explicit_over_system", - userEnvelope: { - metricDefinitionProvided: this.hasNonEmptyString(envelope?.metricDefinition), - timeRangeProvided: this.hasTimeRange(envelope?.timeRange), - entityMappingCount, - includeTableCount, - excludeTableCount, - ...(pinnedTableCount > 0 ? { pinnedTableCount } : {}), - ...(pinnedColumnCount > 0 ? { pinnedColumnCount } : {}), - businessConstraintCount: this.countNonEmptyStrings(envelope?.businessConstraints) - }, - retrievalContext: { - status: state.retrievalBundle?.status, - selectedContextCount: state.retrievalBundle?.selected_context?.length, - ...(state.retrievedKnowledge?.pinning - ? { - pinning: state.retrievedKnowledge.pinning - } - : {}) - } - }; - - const reasonCodes = this.collectConflictReasons(state, includeTableCount, excludeTableCount); - const conflictHint: GraphContextConflictHint = { - hasConflict: reasonCodes.length > 0, - preferredSource: "user_explicit", - ...(reasonCodes.length > 0 ? { reasonCodes } : {}) - }; - - return { - effectiveContextSummary, - conflictHint - }; - } - - private collectConflictReasons( - state: LangGraphState, - includeTableCount: number, - excludeTableCount: number - ): string[] { - const reasonCodes: string[] = []; - if (includeTableCount > 0 && excludeTableCount > 0 && this.hasTableOverlap(state)) { - reasonCodes.push("user_envelope_include_exclude_overlap"); - } - if ( - (state.retrievalBundle?.risk_tags ?? []).some((tag) => CONTEXT_CONFLICT_REGEX.test(tag)) - ) { - reasonCodes.push("retrieval_context_conflict_risk"); - } - if ((state.planningWarnings ?? []).some((warning) => CONTEXT_CONFLICT_REGEX.test(warning))) { - reasonCodes.push("planning_conflict_warning"); - } - return Array.from(new Set(reasonCodes)); - } - - private hasTableOverlap(state: LangGraphState): boolean { - const include = new Set( - (state.contextEnvelope?.mustIncludeTables ?? []) - .map((item) => item.trim().toLowerCase()) - .filter(Boolean) - ); - if (include.size === 0) { - return false; - } - return (state.contextEnvelope?.mustExcludeTables ?? []) - .map((item) => item.trim().toLowerCase()) - .filter(Boolean) - .some((item) => include.has(item)); - } - - private hasContextEnvelope(input: ContextEnvelope | undefined): boolean { - if (!input) { - return false; - } - return ( - this.hasNonEmptyString(input.metricDefinition) || - this.hasTimeRange(input.timeRange) || - this.countEntityMappings(input.entityMappings) > 0 || - this.countNonEmptyStrings(input.mustIncludeTables) > 0 || - this.countNonEmptyStrings(input.mustExcludeTables) > 0 || - this.countNonEmptyStrings(input.pinnedTables) > 0 || - this.countNonEmptyStrings(input.pinnedColumns) > 0 || - this.countNonEmptyStrings(input.businessConstraints) > 0 - ); - } - - private hasTimeRange(value: ContextEnvelope["timeRange"] | undefined): boolean { - if (!value || typeof value !== "object") { - return false; - } - const timeRange = value as { - from?: string; - to?: string; - timezone?: string; - }; - return ( - this.hasNonEmptyString(timeRange.from) || - this.hasNonEmptyString(timeRange.to) || - this.hasNonEmptyString(timeRange.timezone) - ); - } - - private countEntityMappings( - value: ContextEnvelope["entityMappings"] | undefined - ): number { - if (!Array.isArray(value)) { - return 0; - } - return value.reduce((count, item) => { - if (!item || typeof item !== "object") { - return count; - } - const candidate = item as { - entity?: string; - mappedTo?: string; - }; - if (this.hasNonEmptyString(candidate.entity) || this.hasNonEmptyString(candidate.mappedTo)) { - return count + 1; - } - return count; - }, 0); - } - - private countNonEmptyStrings(values: string[] | undefined): number { - if (!values) { - return 0; - } - return values.filter((item) => this.hasNonEmptyString(item)).length; - } - - private hasNonEmptyString(value: unknown): value is string { - return typeof value === "string" && value.trim().length > 0; - } -} diff --git a/apps/backend/src/modules/conversation/agent/graph/langgraph.node-handlers.ts b/apps/backend/src/modules/conversation/agent/graph/langgraph.node-handlers.ts deleted file mode 100644 index f4f19d2..0000000 --- a/apps/backend/src/modules/conversation/agent/graph/langgraph.node-handlers.ts +++ /dev/null @@ -1,1253 +0,0 @@ -import type { LangGraphRunnableConfig } from "@langchain/langgraph"; -import type { ExecutionTraceStep } from "@text2sql/shared-types"; -import { DomainError } from "../../../../common/domain-error"; -import { BuildIntentPlanNode } from "../nodes/build-intent-plan.node"; -import { BuildPhysicalPlanNode } from "../nodes/build-physical-plan.node"; -import { BuildSemanticQueryNode } from "../nodes/build-semantic-query.node"; -import { ClarifyNode } from "../nodes/clarify.node"; -import { ExecuteSqlNode } from "../nodes/execute-sql.node"; -import { FormatAnswerNode } from "../nodes/format-answer.node"; -import { GenerateSqlNode } from "../nodes/generate-sql.node"; -import { ResolveSavedPriorSqlNode } from "../nodes/resolve-saved-prior-sql.node"; -import { RetrieveKnowledgeNode } from "../nodes/retrieve-knowledge.node"; -import { SafetyCheckNode } from "../nodes/safety-check.node"; -import type { - LlmGatewayStreamEvent, - LlmGatewayToolDefinition -} from "../../../llm/llm-gateway.interface"; -import { - MAX_RELATIONSHIP_CORRECTION_RETRY, - appendStep, - type LangGraphState -} from "./langgraph.state"; -import type { SqlGenerationExplicitPinningEvidence } from "../sql/sql-generation.service"; - -interface RuntimeCallbacks { - streamMode?: boolean; - tools?: Record; - onStep?: (step: ExecutionTraceStep) => Promise | void; - onLlmEvent?: (event: LlmGatewayStreamEvent) => Promise | void; -} - -const getCallbacks = (config?: LangGraphRunnableConfig): RuntimeCallbacks => { - return (config?.configurable as RuntimeCallbacks | undefined) ?? {}; -}; - -interface NodeRuntime { - callbacks: RuntimeCallbacks; - emitStep: (step?: ExecutionTraceStep) => Promise; -} - -const createNodeRuntime = (config?: LangGraphRunnableConfig): NodeRuntime => { - const callbacks = getCallbacks(config); - return { - callbacks, - emitStep: async (step?: ExecutionTraceStep) => { - if (!step) { - return; - } - await callbacks.onStep?.(step); - } - }; -}; - -const latestStep = ( - traceState: Pick -): ExecutionTraceStep | undefined => traceState.trace.steps.at(-1); - -const buildRunningStep = ( - state: Pick, - node: string, - startedAt: string, - detail: string -): ExecutionTraceStep => { - const sequence = state.trace.steps.length + 1; - return { - node, - status: "success", - lifecycle: "running", - stepId: `${state.runId}:${node}:${sequence}`, - sequence, - detail, - at: startedAt, - startedAt - }; -}; - -const toErrorMessage = (error: unknown): string => { - if (error instanceof Error) { - return error.message; - } - return String(error); -}; - -const MAX_SUMMARY_LENGTH = 240; - -const truncate = (value: string): string => { - if (value.length <= MAX_SUMMARY_LENGTH) { - return value; - } - return `${value.slice(0, MAX_SUMMARY_LENGTH)}…`; -}; - -const summarize = (value: unknown): string | undefined => { - if (value === undefined || value === null) { - return undefined; - } - if (typeof value === "string") { - const compact = value.replace(/\s+/g, " ").trim(); - return compact ? truncate(compact) : undefined; - } - try { - return truncate(JSON.stringify(value)); - } catch { - return undefined; - } -}; - -const withTiming = (startedAt: string, endedAt: string) => ({ - at: endedAt, - startedAt, - endedAt, - durationMs: Math.max(0, Date.parse(endedAt) - Date.parse(startedAt)) -}); - -const appendPlanningWarning = ( - state: LangGraphState, - warning: string -): string[] => { - return [...(state.planningWarnings ?? []), warning]; -}; - -const appendPlanningWarnings = ( - state: LangGraphState, - stage: "intent" | "semantic", - warnings: string[] -): string[] => { - const normalized = warnings - .map((warning) => warning.trim()) - .filter((warning) => warning.length > 0) - .map((warning) => `${stage}:${warning}`); - return [...(state.planningWarnings ?? []), ...normalized]; -}; - -const normalizeIdentifier = (value: string | undefined): string | undefined => { - if (!value) { - return undefined; - } - const normalized = value - .trim() - .replace(/^[`"'[\]]+|[`"'[\]]+$/g, "") - .replace(/\s+/g, ""); - if (!normalized) { - return undefined; - } - return normalized.toLowerCase(); -}; - -const extractQualifiedColumns = (value: string | undefined): string[] => { - if (!value) { - return []; - } - const result: string[] = []; - const regex = /\b([a-zA-Z_][\w$]*)\.([a-zA-Z_][\w$]*)\b/g; - for (const match of value.matchAll(regex)) { - const table = normalizeIdentifier(match[1]); - const column = normalizeIdentifier(match[2]); - if (!table || !column) { - continue; - } - result.push(`${table}.${column}`); - } - return result; -}; - -const unique = (values: string[]): string[] => Array.from(new Set(values)); - -const buildExplicitPinningEvidence = ( - state: LangGraphState -): SqlGenerationExplicitPinningEvidence | undefined => { - const envelopePinnedTables = state.contextEnvelope?.pinnedTables ?? []; - const envelopePinnedColumns = state.contextEnvelope?.pinnedColumns ?? []; - const tables = unique( - envelopePinnedTables - .map((item) => normalizeIdentifier(item)) - .filter((item): item is string => Boolean(item)) - ); - const mappedColumns = unique([ - ...envelopePinnedColumns - .map((item) => normalizeIdentifier(item)) - .filter((item): item is string => Boolean(item)), - ...((state.contextEnvelope?.entityMappings ?? []) - .map((item) => extractQualifiedColumns(item.mappedTo)) - .flat()), - ...extractQualifiedColumns(state.contextEnvelope?.metricDefinition) - ]); - if (tables.length === 0 && mappedColumns.length === 0) { - return undefined; - } - return { - source: "context_envelope", - tables, - columns: mappedColumns - }; -}; - -export interface LangGraphNodeDependencies { - clarifyNode: Pick; - retrieveKnowledgeNode: Pick; - buildIntentPlanNode: Pick; - buildSemanticQueryNode: Pick; - buildPhysicalPlanNode: Pick; - resolveSavedPriorSqlNode: Pick; - generateSqlNode: Pick; - safetyNode: Pick; - executeNode: Pick; - formatNode: Pick; -} - -export const createLangGraphNodeHandlers = (deps: LangGraphNodeDependencies) => { - const clarify = async ( - state: LangGraphState, - config?: LangGraphRunnableConfig - ) => { - const startedAt = new Date().toISOString(); - const runtime = createNodeRuntime(config); - await runtime.emitStep( - buildRunningStep(state, "clarify", startedAt, "正在理解问题") - ); - const decision = deps.clarifyNode.evaluate( - state.question, - state.contextEnvelope - ); - const clarificationDecision = { - decision: decision.decision, - triggerPath: decision.triggerPath, - decisionSource: decision.decisionSource, - bypassed: decision.bypassed, - ...(decision.bypassReasonCode ? { bypassReasonCode: decision.bypassReasonCode } : {}), - confidenceLevel: decision.confidenceLevel, - missingCriticalSlots: decision.missingCriticalSlots, - conflictDetected: false, - ...(decision.reasonCodes.length > 0 ? { reasonCodes: decision.reasonCodes } : {}), - question: decision.question, - reason: decision.reason - }; - const clarification = decision.shouldClarify - ? { - ...clarificationDecision - } - : undefined; - const endedAt = new Date().toISOString(); - if (clarification) { - const outputs = { - clarificationQuestion: clarification.question, - clarificationDecision - }; - const trace = appendStep(state, { - step: { - node: "clarify", - status: "success", - detail: clarification.reason, - ...withTiming(startedAt, endedAt), - outputSummary: summarize(outputs) - }, - runType: "tool", - outputs - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - trace: { - ...trace.trace, - clarificationDecision - }, - clarification, - answer: clarification.question, - terminalStatus: "clarification" - }; - } - const trace = appendStep(state, { - step: { - node: "clarify", - status: "skipped", - detail: decision.reason || "问题信息充足，跳过澄清。", - ...withTiming(startedAt, endedAt), - outputSummary: summarize({ clarificationDecision }) - }, - outputs: { clarificationDecision } - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - trace: { - ...trace.trace, - clarificationDecision - } - }; - }; - - const retrieveKnowledge = async ( - state: LangGraphState, - config?: LangGraphRunnableConfig - ) => { - const startedAt = new Date().toISOString(); - const runtime = createNodeRuntime(config); - await runtime.emitStep( - buildRunningStep(state, "retrieve-knowledge", startedAt, "正在检索知识上下文") - ); - if (!state.planningScaffoldEnabled) { - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "retrieve-knowledge", - status: "skipped", - detail: "规划骨架未启用，跳过检索节点。", - ...withTiming(startedAt, endedAt) - } - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - planningStatus: "legacy" - }; - } - - try { - const knowledge = await deps.retrieveKnowledgeNode.run({ - question: state.question, - datasourceId: state.datasourceId, - runId: state.runId, - workspaceId: state.accessContext?.workspaceId, - allowedTables: state.accessContext?.allowedTables, - pinnedTables: state.contextEnvelope?.pinnedTables ?? state.contextEnvelope?.mustIncludeTables, - pinnedColumns: state.contextEnvelope?.pinnedColumns, - modelCatalogId: state.modelCatalogId - }); - const endedAt = new Date().toISOString(); - const outputs = { - status: knowledge.status, - snippets: knowledge.snippets, - degradeReasons: knowledge.retrievalBundle?.degrade_reasons ?? [], - candidateCount: knowledge.retrievalBundle?.candidates.length ?? 0, - selectedContextCount: - knowledge.retrievalBundle?.selected_context?.length ?? 0, - contextPackStatus: knowledge.contextPack?.status, - semanticLockStatus: knowledge.contextPack?.semantic_lock_status - }; - const trace = appendStep(state, { - step: { - node: "retrieve-knowledge", - status: "success", - detail: knowledge.summary, - ...withTiming(startedAt, endedAt), - outputSummary: summarize(outputs) - }, - outputs - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - retrievedKnowledge: knowledge, - retrievalBundle: knowledge.retrievalBundle, - contextPack: knowledge.contextPack, - planningStatus: knowledge.status === "ready" ? "ready" : "degraded", - planningWarnings: - knowledge.status === "ready" - ? state.planningWarnings - : appendPlanningWarning(state, knowledge.summary) - }; - } catch (error) { - const message = toErrorMessage(error); - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "retrieve-knowledge", - status: "failed", - detail: message, - ...withTiming(startedAt, endedAt), - errorSummary: summarize(message) - }, - error: message - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - planningStatus: "degraded", - planningWarnings: appendPlanningWarning(state, message) - }; - } - }; - - const buildIntentPlan = async ( - state: LangGraphState, - config?: LangGraphRunnableConfig - ) => { - const startedAt = new Date().toISOString(); - const runtime = createNodeRuntime(config); - await runtime.emitStep( - buildRunningStep(state, "build-intent-plan", startedAt, "正在构建意图规划") - ); - if (!state.planningScaffoldEnabled) { - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "build-intent-plan", - status: "skipped", - detail: "规划骨架未启用，跳过意图规划节点。", - ...withTiming(startedAt, endedAt) - } - }); - await runtime.emitStep(latestStep(trace)); - return trace; - } - - if (!state.retrievedKnowledge) { - const reason = "缺少检索上下文，意图规划降级。"; - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "build-intent-plan", - status: "failed", - detail: reason, - ...withTiming(startedAt, endedAt), - errorSummary: summarize(reason) - }, - error: reason - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - planningStatus: "degraded", - planningWarnings: appendPlanningWarning(state, reason) - }; - } - - try { - const intentPlan = await deps.buildIntentPlanNode.run( - state.question, - state.retrievedKnowledge, - state.trace.clarificationDecision - ); - const endedAt = new Date().toISOString(); - const outputs = { - status: intentPlan.status, - intent: intentPlan.intent, - constraints: intentPlan.constraints, - uncertaintySignal: intentPlan.uncertaintySignal, - clarificationDecision: intentPlan.clarificationDecision, - riskTags: intentPlan.riskTags - }; - const trace = appendStep(state, { - step: { - node: "build-intent-plan", - status: "success", - detail: intentPlan.summary, - ...withTiming(startedAt, endedAt), - outputSummary: summarize(outputs) - }, - outputs - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - trace: { - ...trace.trace, - clarificationDecision: - intentPlan.clarificationDecision ?? state.trace.clarificationDecision - }, - intentPlan, - planningStatus: intentPlan.status === "ready" ? state.planningStatus : "degraded", - planningWarnings: - intentPlan.status === "ready" && - (intentPlan.planningWarnings?.length ?? 0) === 0 - ? state.planningWarnings - : appendPlanningWarnings( - state, - "intent", - (intentPlan.planningWarnings?.length ?? 0) > 0 - ? (intentPlan.planningWarnings ?? []) - : [intentPlan.summary] - ) - }; - } catch (error) { - const message = toErrorMessage(error); - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "build-intent-plan", - status: "failed", - detail: message, - ...withTiming(startedAt, endedAt), - errorSummary: summarize(message) - }, - error: message - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - planningStatus: "degraded", - planningWarnings: appendPlanningWarning(state, message) - }; - } - }; - - const buildSemanticQuery = async ( - state: LangGraphState, - config?: LangGraphRunnableConfig - ) => { - const startedAt = new Date().toISOString(); - const runtime = createNodeRuntime(config); - await runtime.emitStep( - buildRunningStep( - state, - "build-semantic-query", - startedAt, - "正在构建语义检索计划" - ) - ); - if (!state.planningScaffoldEnabled) { - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "build-semantic-query", - status: "skipped", - detail: "规划骨架未启用，跳过语义检索节点。", - ...withTiming(startedAt, endedAt) - } - }); - await runtime.emitStep(latestStep(trace)); - return trace; - } - - if (!state.intentPlan) { - const reason = "缺少意图规划，语义检索降级。"; - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "build-semantic-query", - status: "failed", - detail: reason, - ...withTiming(startedAt, endedAt), - errorSummary: summarize(reason) - }, - error: reason - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - planningStatus: "degraded", - planningWarnings: appendPlanningWarning(state, reason) - }; - } - - try { - const semanticQueryPlan = await deps.buildSemanticQueryNode.run({ - intentPlan: state.intentPlan, - question: state.question, - retrievalBundle: state.retrievalBundle, - clarificationDecision: state.trace.clarificationDecision - }); - const endedAt = new Date().toISOString(); - const outputs = { - status: semanticQueryPlan.status, - semanticHints: semanticQueryPlan.semanticHints, - modelingRevision: semanticQueryPlan.modelingRevision, - semanticBindingSummary: semanticQueryPlan.semanticBindingSummary, - contextPackStatus: semanticQueryPlan.semanticBindingSummary?.contextPackStatus, - semanticVersion: semanticQueryPlan.semanticVersion, - lockStatus: semanticQueryPlan.lockStatus, - fallbackApplied: semanticQueryPlan.fallbackApplied, - degradeReason: semanticQueryPlan.degradeReason, - riskTags: semanticQueryPlan.riskTags, - strictMode: semanticQueryPlan.strictMode, - strictModeReasons: semanticQueryPlan.strictModeReasons, - planningWarnings: semanticQueryPlan.planningWarnings, - clarificationDecision: semanticQueryPlan.clarificationDecision - }; - const trace = appendStep(state, { - step: { - node: "build-semantic-query", - status: "success", - detail: semanticQueryPlan.summary, - ...withTiming(startedAt, endedAt), - outputSummary: summarize(outputs) - }, - outputs - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - trace: { - ...trace.trace, - clarificationDecision: - semanticQueryPlan.clarificationDecision ?? state.trace.clarificationDecision - }, - semanticQueryPlan, - planningStatus: - semanticQueryPlan.status === "ready" ? state.planningStatus : "degraded", - planningWarnings: - semanticQueryPlan.status === "ready" && - (semanticQueryPlan.planningWarnings?.semantic.length ?? 0) === 0 - ? state.planningWarnings - : appendPlanningWarnings( - state, - "semantic", - (semanticQueryPlan.planningWarnings?.semantic.length ?? 0) > 0 - ? (semanticQueryPlan.planningWarnings?.semantic ?? []) - : [semanticQueryPlan.summary] - ) - }; - } catch (error) { - const message = toErrorMessage(error); - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "build-semantic-query", - status: "failed", - detail: message, - ...withTiming(startedAt, endedAt), - errorSummary: summarize(message) - }, - error: message - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - planningStatus: "degraded", - planningWarnings: appendPlanningWarning(state, message) - }; - } - }; - - const buildPhysicalPlan = async ( - state: LangGraphState, - config?: LangGraphRunnableConfig - ) => { - const startedAt = new Date().toISOString(); - const runtime = createNodeRuntime(config); - await runtime.emitStep( - buildRunningStep( - state, - "build-physical-plan", - startedAt, - "正在构建物理执行计划" - ) - ); - if (!state.planningScaffoldEnabled) { - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "build-physical-plan", - status: "skipped", - detail: "规划骨架未启用，跳过物理规划节点。", - ...withTiming(startedAt, endedAt) - } - }); - await runtime.emitStep(latestStep(trace)); - return trace; - } - - if (!state.semanticQueryPlan) { - const reason = "缺少语义规划，物理计划降级。"; - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "build-physical-plan", - status: "failed", - detail: reason, - ...withTiming(startedAt, endedAt), - errorSummary: summarize(reason) - }, - error: reason - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - planningStatus: "degraded", - planningWarnings: appendPlanningWarning(state, reason) - }; - } - - try { - const physicalPlan = await deps.buildPhysicalPlanNode.run({ - semanticPlan: state.semanticQueryPlan, - question: state.question, - datasourceId: state.datasourceId - }); - const endedAt = new Date().toISOString(); - const outputs = { - status: physicalPlan.status, - strategy: physicalPlan.strategy, - semanticVersion: physicalPlan.semanticVersion, - lockStatus: physicalPlan.lockStatus, - fallbackApplied: physicalPlan.fallbackApplied, - cacheStatus: physicalPlan.cacheStatus, - cacheKey: physicalPlan.cacheKey, - cacheReason: physicalPlan.cacheReason - }; - const trace = appendStep(state, { - step: { - node: "build-physical-plan", - status: "success", - detail: physicalPlan.summary, - ...withTiming(startedAt, endedAt), - outputSummary: summarize(outputs) - }, - outputs - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - physicalPlan, - planningStatus: physicalPlan.status === "ready" ? state.planningStatus : "degraded", - planningWarnings: - physicalPlan.status === "ready" - ? state.planningWarnings - : appendPlanningWarning(state, physicalPlan.summary) - }; - } catch (error) { - const message = toErrorMessage(error); - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "build-physical-plan", - status: "failed", - detail: message, - ...withTiming(startedAt, endedAt), - errorSummary: summarize(message) - }, - error: message - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - planningStatus: "degraded", - planningWarnings: appendPlanningWarning(state, message) - }; - } - }; - - const generateSql = async ( - state: LangGraphState, - config?: LangGraphRunnableConfig - ) => { - const startedAt = new Date().toISOString(); - const runtime = createNodeRuntime(config); - await runtime.emitStep( - buildRunningStep(state, "generate-sql", startedAt, "正在生成 SQL") - ); - const callbacks = runtime.callbacks; - try { - const explicitPinning = buildExplicitPinningEvidence(state); - const generated = await deps.generateSqlNode.run( - state.question, - state.datasourceType, - state.modelCatalogId, - callbacks.streamMode - ? { - stream: true, - tools: callbacks.tools, - onEvent: callbacks.onLlmEvent, - selectedContext: state.retrievalBundle?.selected_context, - semanticContextPack: state.contextPack ?? state.retrievalBundle?.context_pack, - datasourceId: state.datasourceId, - workspaceId: state.accessContext?.workspaceId, - explicitPinning - } - : { - selectedContext: state.retrievalBundle?.selected_context, - semanticContextPack: state.contextPack ?? state.retrievalBundle?.context_pack, - datasourceId: state.datasourceId, - workspaceId: state.accessContext?.workspaceId, - explicitPinning - } - ); - const endedAt = new Date().toISOString(); - const inputs = { - question: state.question, - datasourceType: state.datasourceType, - selectedContextCount: state.retrievalBundle?.selected_context?.length ?? 0, - retrievalStatus: state.retrievalBundle?.status, - retrievalDegradeReasons: state.retrievalBundle?.degrade_reasons, - retrievalRiskTags: state.retrievalBundle?.risk_tags ?? [], - modelCatalogId: state.modelCatalogId, - datasourceId: state.datasourceId, - workspaceId: state.accessContext?.workspaceId, - planningScaffoldEnabled: state.planningScaffoldEnabled, - planningStatus: state.planningStatus, - planningWarnings: state.planningWarnings, - retrieveSummary: state.retrievedKnowledge?.summary, - intent: state.intentPlan?.intent, - semanticHints: state.semanticQueryPlan?.semanticHints, - semanticStrictMode: state.semanticQueryPlan?.strictMode, - semanticStrictModeReasons: state.semanticQueryPlan?.strictModeReasons, - clarificationDecision: state.trace.clarificationDecision, - physicalStrategy: state.physicalPlan?.strategy, - semanticConstraintMode: state.physicalPlan?.semanticConstraintMode, - contextPackStatus: state.contextPack?.status ?? state.retrievalBundle?.context_pack?.status - }; - const outputs = { - provider: generated.provider, - model: generated.model, - modelCatalogId: generated.modelCatalogId, - promptTemplate: generated.promptTemplate, - retryCount: generated.retryCount ?? 0, - semanticIntent: generated.semanticIntent, - coverage: generated.coverage - }; - const trace = appendStep(state, { - step: { - node: "generate-sql", - status: "success", - detail: generated.provider, - ...withTiming(startedAt, endedAt), - inputSummary: summarize(inputs), - outputSummary: summarize(outputs) - }, - runType: "llm", - inputs, - outputs - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - trace: { - ...trace.trace, - provider: generated.provider, - retryCount: generated.retryCount ?? trace.trace.retryCount ?? 0, - ...(state.semanticQueryPlan?.modelingRevision !== undefined - ? { - modelingRevision: state.semanticQueryPlan.modelingRevision - } - : {}), - ...(generated.promptTemplate - ? { - promptTemplate: generated.promptTemplate - } - : {}) - }, - provider: generated.provider, - model: generated.model, - llmRaw: { - provider: generated.provider, - model: generated.model, - rawText: generated.rawText, - createdAt: endedAt - }, - sql: generated.sql, - explanation: generated.explanation, - savedPriorSqlFallbackRequested: false, - error: undefined, - fatalError: undefined - }; - } catch (error) { - const endedAt = new Date().toISOString(); - const message = toErrorMessage(error); - const inputs = { - question: state.question - }; - const outputs = - error instanceof DomainError - ? { - errorCode: error.code, - errorDetails: error.details - } - : undefined; - const trace = appendStep(state, { - step: { - node: "generate-sql", - status: "failed", - detail: message, - ...withTiming(startedAt, endedAt), - inputSummary: summarize(inputs), - outputSummary: summarize(outputs), - errorSummary: summarize(message) - }, - runType: "llm", - inputs, - outputs, - error: message - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - error: message, - terminalStatus: "failed", - fatalError: error - }; - } - }; - - const safetyCheck = async ( - state: LangGraphState, - config?: LangGraphRunnableConfig - ) => { - const startedAt = new Date().toISOString(); - const runtime = createNodeRuntime(config); - await runtime.emitStep( - buildRunningStep(state, "safety-check", startedAt, "正在执行安全校验") - ); - if (!state.sql) { - const reason = "未生成 SQL，无法执行安全校验。"; - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "safety-check", - status: "failed", - detail: reason, - ...withTiming(startedAt, endedAt), - errorSummary: summarize(reason) - }, - runType: "tool", - error: reason - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - error: reason, - terminalStatus: "failed" - }; - } - - const safety = await deps.safetyNode.run({ - sql: state.sql, - datasourceId: state.datasourceId, - accessContext: state.accessContext, - riskTags: state.retrievalBundle?.risk_tags - }); - const endedAt = new Date().toISOString(); - const inputs = { - sql: state.sql, - datasourceId: state.datasourceId, - workspaceId: state.accessContext?.workspaceId - }; - if (!safety.allowed) { - const shouldFallbackToGeneration = - state.savedPriorSqlResolution?.status === "hit" && - state.savedPriorSqlResolution.fallbackToGeneration === false; - const trace = appendStep(state, { - step: { - node: "safety-check", - status: "failed", - detail: safety.reason ?? "SQL 未通过安全策略校验。", - ...withTiming(startedAt, endedAt), - inputSummary: summarize(inputs), - errorSummary: summarize(safety.reason) - }, - runType: "tool", - inputs, - metadata: { - mode: safety.mode, - riskLevel: safety.riskLevel, - riskTags: safety.riskTags - }, - error: safety.reason - }); - await runtime.emitStep(latestStep(trace)); - if (shouldFallbackToGeneration) { - return { - ...trace, - error: safety.reason, - safetyDecision: safety, - savedPriorSqlResolution: { - ...state.savedPriorSqlResolution, - safetyRejected: true, - fallbackToGeneration: true, - reused: true - }, - savedPriorSqlFallbackRequested: true, - sql: undefined, - explanation: undefined, - terminalStatus: undefined - }; - } - return { - ...trace, - error: safety.reason, - safetyDecision: safety, - savedPriorSqlFallbackRequested: false, - terminalStatus: "rejected" - }; - } - - const detail = - safety.mode === "soft-warn" - ? `SQL 通过只读校验（软告警：${safety.riskTags.join(", ") || "none"}）。` - : "SQL 通过只读校验。"; - const trace = appendStep(state, { - step: { - node: "safety-check", - status: "success", - detail, - ...withTiming(startedAt, endedAt), - inputSummary: summarize(inputs), - outputSummary: summarize({ - mode: safety.mode, - riskLevel: safety.riskLevel, - riskTags: safety.riskTags - }) - }, - metadata: { - mode: safety.mode, - riskLevel: safety.riskLevel, - riskTags: safety.riskTags - } - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - safetyDecision: safety, - savedPriorSqlFallbackRequested: false - }; - }; - - const resolveSavedPriorSql = async ( - state: LangGraphState, - config?: LangGraphRunnableConfig - ) => { - const startedAt = new Date().toISOString(); - const runtime = createNodeRuntime(config); - await runtime.emitStep( - buildRunningStep( - state, - "resolve-saved-prior-sql", - startedAt, - "正在评估是否复用已保存 SQL" - ) - ); - const resolution = deps.resolveSavedPriorSqlNode.run({ - retrievalBundle: state.retrievalBundle, - question: state.question - }); - const endedAt = new Date().toISOString(); - const detail = - resolution.status === "hit" - ? "命中已保存 SQL，跳过 LLM SQL 生成。" - : `未命中 saved prior shortcut，状态=${resolution.status}。`; - const trace = appendStep(state, { - step: { - node: "resolve-saved-prior-sql", - status: resolution.status === "hit" ? "success" : "skipped", - detail, - ...withTiming(startedAt, endedAt), - outputSummary: summarize({ - status: resolution.status, - reasonCodes: resolution.reasonCodes, - selectedChunkId: resolution.selectedChunkId, - selectedViewId: resolution.selectedViewId, - selectedSourceRunId: resolution.selectedSourceRunId - }) - }, - outputs: { - status: resolution.status, - reasonCodes: resolution.reasonCodes, - selectedChunkId: resolution.selectedChunkId, - selectedViewId: resolution.selectedViewId, - selectedSourceRunId: resolution.selectedSourceRunId - } - }); - await runtime.emitStep(latestStep(trace)); - if (resolution.status !== "hit" || !resolution.sql) { - return { - ...trace, - savedPriorSqlResolution: { - ...resolution, - reused: false, - safetyRejected: false, - fallbackToGeneration: false - }, - savedPriorSqlFallbackRequested: false - }; - } - return { - ...trace, - model: "saved-prior-sql", - sql: resolution.sql, - explanation: resolution.explanation, - error: undefined, - savedPriorSqlResolution: { - ...resolution, - reused: true, - safetyRejected: false, - fallbackToGeneration: false - }, - savedPriorSqlFallbackRequested: false - }; - }; - - const executeSql = async ( - state: LangGraphState, - config?: LangGraphRunnableConfig - ) => { - const startedAt = new Date().toISOString(); - const runtime = createNodeRuntime(config); - await runtime.emitStep( - buildRunningStep(state, "execute-sql", startedAt, "正在执行查询") - ); - if (!state.sql) { - const reason = "未生成 SQL，无法执行查询。"; - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "execute-sql", - status: "failed", - detail: reason, - ...withTiming(startedAt, endedAt), - errorSummary: summarize(reason) - }, - runType: "tool", - error: reason - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - error: reason, - terminalStatus: "failed" - }; - } - try { - const execution = await deps.executeNode.run({ - sql: state.sql, - datasourceId: state.datasourceId, - sessionId: state.sessionId, - requestId: state.traceContext?.requestId, - accessContext: state.accessContext - }); - const endedAt = new Date().toISOString(); - const inputs = { - sql: state.sql, - datasourceId: state.datasourceId, - sessionId: state.sessionId, - workspaceId: state.accessContext?.workspaceId - }; - const outputs = { - rowCount: execution.rows.length, - columns: execution.columns - }; - const trace = appendStep(state, { - step: { - node: "execute-sql", - status: "success", - detail: `rows=${execution.rows.length}`, - ...withTiming(startedAt, endedAt), - inputSummary: summarize(inputs), - outputSummary: summarize(outputs) - }, - runType: "tool", - inputs, - outputs - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - rows: execution.rows, - columns: execution.columns, - error: undefined - }; - } catch (error) { - const endedAt = new Date().toISOString(); - const message = toErrorMessage(error); - const inputs = { - sql: state.sql - }; - const trace = appendStep(state, { - step: { - node: "execute-sql", - status: "failed", - detail: message, - ...withTiming(startedAt, endedAt), - inputSummary: summarize(inputs), - errorSummary: summarize(message) - }, - runType: "tool", - inputs, - error: message - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - error: message, - terminalStatus: "failed" - }; - } - }; - - const relationshipCorrection = async ( - state: LangGraphState, - config?: LangGraphRunnableConfig - ) => { - const startedAt = new Date().toISOString(); - const runtime = createNodeRuntime(config); - await runtime.emitStep( - buildRunningStep( - state, - "relationship-correction", - startedAt, - "正在执行关系路径纠错重试" - ) - ); - const retryCount = (state.relationCorrectionRetryCount ?? 0) + 1; - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "relationship-correction", - status: "success", - detail: `relationship correction retry ${retryCount}/${MAX_RELATIONSHIP_CORRECTION_RETRY}`, - ...withTiming(startedAt, endedAt) - } - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - relationCorrectionRetryCount: retryCount, - terminalStatus: undefined - }; - }; - - const formatAnswer = async ( - state: LangGraphState, - config?: LangGraphRunnableConfig - ) => { - const startedAt = new Date().toISOString(); - const runtime = createNodeRuntime(config); - await runtime.emitStep( - buildRunningStep(state, "format-answer", startedAt, "正在整理回答") - ); - const answer = deps.formatNode.run( - state.question, - state.rows ?? [], - state.columns ?? [] - ); - const endedAt = new Date().toISOString(); - const trace = appendStep(state, { - step: { - node: "format-answer", - status: "success", - detail: "结果已格式化。", - ...withTiming(startedAt, endedAt), - outputSummary: summarize(answer) - } - }); - await runtime.emitStep(latestStep(trace)); - return { - ...trace, - answer, - terminalStatus: "executionResult" - }; - }; - - return { - clarify, - retrieveKnowledge, - buildIntentPlan, - buildSemanticQuery, - buildPhysicalPlan, - resolveSavedPriorSql, - generateSql, - safetyCheck, - executeSql, - relationshipCorrection, - formatAnswer - }; -}; diff --git a/apps/backend/src/modules/conversation/agent/graph/langgraph.runtime.ts b/apps/backend/src/modules/conversation/agent/graph/langgraph.runtime.ts deleted file mode 100644 index e94a041..0000000 --- a/apps/backend/src/modules/conversation/agent/graph/langgraph.runtime.ts +++ /dev/null @@ -1,190 +0,0 @@ -import { Injectable } from "@nestjs/common"; -import { - Annotation, - END, - START, - StateGraph, - type LangGraphRunnableConfig -} from "@langchain/langgraph"; -import type { DatasourceType } from "@text2sql/shared-types"; -import { BuildIntentPlanNode } from "../nodes/build-intent-plan.node"; -import { BuildPhysicalPlanNode } from "../nodes/build-physical-plan.node"; -import { BuildSemanticQueryNode } from "../nodes/build-semantic-query.node"; -import { ClarifyNode } from "../nodes/clarify.node"; -import { ExecuteSqlNode } from "../nodes/execute-sql.node"; -import { FormatAnswerNode } from "../nodes/format-answer.node"; -import { GenerateSqlNode } from "../nodes/generate-sql.node"; -import { ResolveSavedPriorSqlNode } from "../nodes/resolve-saved-prior-sql.node"; -import { RetrieveKnowledgeNode } from "../nodes/retrieve-knowledge.node"; -import { SafetyCheckNode } from "../nodes/safety-check.node"; -import { - createLangGraphNodeHandlers, - type LangGraphNodeDependencies -} from "./langgraph.node-handlers"; -import { - shouldRetryRelationshipCorrection, - type LangGraphState -} from "./langgraph.state"; - -const LangGraphStateAnnotation = Annotation.Root({ - runId: Annotation(), - sessionId: Annotation(), - question: Annotation(), - datasourceId: Annotation(), - datasourceType: Annotation(), - modelCatalogId: Annotation(), - contextEnvelope: Annotation(), - accessContext: Annotation(), - planningScaffoldEnabled: Annotation(), - traceContext: Annotation(), - provider: Annotation(), - model: Annotation(), - llmRaw: Annotation(), - retrievedKnowledge: Annotation(), - retrievalBundle: Annotation(), - intentPlan: Annotation(), - semanticQueryPlan: Annotation(), - physicalPlan: Annotation(), - planningStatus: Annotation(), - planningWarnings: Annotation(), - savedPriorSqlResolution: Annotation(), - savedPriorSqlFallbackRequested: Annotation(), - safetyDecision: Annotation(), - sql: Annotation(), - explanation: Annotation(), - rows: Annotation> | undefined>(), - columns: Annotation(), - answer: Annotation(), - error: Annotation(), - clarification: Annotation(), - trace: Annotation(), - spanEvents: Annotation(), - relationCorrectionRetryCount: Annotation(), - terminalStatus: Annotation(), - fatalError: Annotation() -}); - -export const createLangGraphRuntime = (deps: LangGraphNodeDependencies) => { - const handlers = createLangGraphNodeHandlers(deps); - return new StateGraph(LangGraphStateAnnotation) - .addNode("clarify", handlers.clarify) - .addNode("retrieve-knowledge", handlers.retrieveKnowledge) - .addNode("build-intent-plan", handlers.buildIntentPlan) - .addNode("build-semantic-query", handlers.buildSemanticQuery) - .addNode("build-physical-plan", handlers.buildPhysicalPlan) - .addNode("resolve-saved-prior-sql", handlers.resolveSavedPriorSql) - .addNode("generate-sql", handlers.generateSql) - .addNode("safety-check", handlers.safetyCheck) - .addNode("execute-sql", handlers.executeSql) - .addNode("relationship-correction", handlers.relationshipCorrection) - .addNode("format-answer", handlers.formatAnswer) - .addEdge(START, "clarify") - .addConditionalEdges( - "clarify", - (state) => (state.terminalStatus === "clarification" ? "done" : "continue"), - { - done: END, - continue: "retrieve-knowledge" - } - ) - .addEdge("retrieve-knowledge", "build-intent-plan") - .addEdge("build-intent-plan", "build-semantic-query") - .addEdge("build-semantic-query", "build-physical-plan") - .addEdge("build-physical-plan", "resolve-saved-prior-sql") - .addConditionalEdges( - "resolve-saved-prior-sql", - (state) => - state.savedPriorSqlResolution?.status === "hit" ? "shortcut" : "continue", - { - shortcut: "safety-check", - continue: "generate-sql" - } - ) - .addConditionalEdges( - "generate-sql", - (state) => (state.fatalError ? "fatal" : "continue"), - { - fatal: END, - continue: "safety-check" - } - ) - .addConditionalEdges( - "safety-check", - (state) => { - if (state.savedPriorSqlFallbackRequested) { - return "fallback-generate"; - } - return state.terminalStatus === "rejected" ? "rejected" : "continue"; - }, - { - "fallback-generate": "generate-sql", - rejected: END, - continue: "execute-sql" - } - ) - .addConditionalEdges( - "execute-sql", - (state) => { - if (state.terminalStatus !== "failed") { - return "continue"; - } - if ( - shouldRetryRelationshipCorrection({ - error: state.error, - retryCount: state.relationCorrectionRetryCount - }) - ) { - return "retry-relationship"; - } - return "failed"; - }, - { - "retry-relationship": "relationship-correction", - failed: END, - continue: "format-answer" - } - ) - .addEdge("relationship-correction", "generate-sql") - .addEdge("format-answer", END) - .compile(); -}; - -export type LangGraphRuntime = ReturnType; - -@Injectable() -export class LangGraphRuntimeService { - private readonly graph: LangGraphRuntime; - - constructor( - private readonly clarifyNode: ClarifyNode, - private readonly retrieveKnowledgeNode: RetrieveKnowledgeNode, - private readonly buildIntentPlanNode: BuildIntentPlanNode, - private readonly buildSemanticQueryNode: BuildSemanticQueryNode, - private readonly buildPhysicalPlanNode: BuildPhysicalPlanNode, - private readonly resolveSavedPriorSqlNode: ResolveSavedPriorSqlNode, - private readonly generateSqlNode: GenerateSqlNode, - private readonly safetyNode: SafetyCheckNode, - private readonly executeNode: ExecuteSqlNode, - private readonly formatNode: FormatAnswerNode - ) { - this.graph = createLangGraphRuntime({ - clarifyNode: this.clarifyNode, - retrieveKnowledgeNode: this.retrieveKnowledgeNode, - buildIntentPlanNode: this.buildIntentPlanNode, - buildSemanticQueryNode: this.buildSemanticQueryNode, - buildPhysicalPlanNode: this.buildPhysicalPlanNode, - resolveSavedPriorSqlNode: this.resolveSavedPriorSqlNode, - generateSqlNode: this.generateSqlNode, - safetyNode: this.safetyNode, - executeNode: this.executeNode, - formatNode: this.formatNode - }); - } - - async invoke( - input: LangGraphState, - config?: LangGraphRunnableConfig - ): Promise { - return this.graph.invoke(input, config); - } -} diff --git a/apps/backend/src/modules/conversation/agent/graph/langgraph.state.ts b/apps/backend/src/modules/conversation/agent/graph/langgraph.state.ts deleted file mode 100644 index 0170cc2..0000000 --- a/apps/backend/src/modules/conversation/agent/graph/langgraph.state.ts +++ /dev/null @@ -1,173 +0,0 @@ -import type { - ClarificationPrompt, - ExecutionTrace, - ExecutionTraceStep, - SqlRun -} from "@text2sql/shared-types"; -import type { GraphInput, GraphTraceContext } from "./agent.types"; -import type { SqlTableAccessContext } from "../../../platform/data/query/index"; -import type { RetrievedKnowledge } from "../nodes/retrieve-knowledge.node"; -import type { IntentPlan } from "../nodes/build-intent-plan.node"; -import type { SemanticQueryPlan } from "../nodes/build-semantic-query.node"; -import type { PhysicalPlan } from "../nodes/build-physical-plan.node"; -import type { SqlSafetyDecision } from "../sql/tools/sql-safety.guard"; -import type { SavedPriorSqlResolution } from "../nodes/resolve-saved-prior-sql.node"; -import type { - RagContextPack, - RagRetrievalBundle -} from "../../../knowledge/rag/retrieval/rag-retrieval.types"; - -export interface LangGraphSpanEvent { - step: ExecutionTraceStep; - runType?: "chain" | "llm" | "tool"; - inputs?: Record; - outputs?: Record; - metadata?: Record; - error?: string; -} - -export interface LangGraphState extends GraphInput { - provider: string; - model?: string; - llmRaw?: SqlRun["llmRaw"]; - retrievedKnowledge?: RetrievedKnowledge; - retrievalBundle?: RagRetrievalBundle; - contextPack?: RagContextPack; - intentPlan?: IntentPlan; - semanticQueryPlan?: SemanticQueryPlan; - physicalPlan?: PhysicalPlan; - planningStatus?: "legacy" | "ready" | "degraded"; - planningWarnings?: string[]; - savedPriorSqlResolution?: SavedPriorSqlResolution & { - reused: boolean; - safetyRejected: boolean; - fallbackToGeneration: boolean; - }; - savedPriorSqlFallbackRequested?: boolean; - safetyDecision?: SqlSafetyDecision; - sql?: string; - explanation?: string; - rows?: Array>; - columns?: string[]; - answer?: string; - error?: string; - clarification?: ClarificationPrompt; - trace: ExecutionTrace; - spanEvents: LangGraphSpanEvent[]; - relationCorrectionRetryCount?: number; - terminalStatus?: SqlRun["status"]; - fatalError?: unknown; -} - -export const MAX_RELATIONSHIP_CORRECTION_RETRY = 2; -export const RELATIONSHIP_CORRECTION_ERROR_MARKERS = [ - "missing_relation_path", - "join_key_mismatch", - "ambiguous_join_path", - "join path", - "relationship", - "relation" -] as const; - -export const shouldRetryRelationshipCorrection = (input: { - error?: string; - retryCount?: number; -}): boolean => { - const retryCount = input.retryCount ?? 0; - if (retryCount >= MAX_RELATIONSHIP_CORRECTION_RETRY) { - return false; - } - const error = input.error?.trim().toLowerCase(); - if (!error) { - return false; - } - return RELATIONSHIP_CORRECTION_ERROR_MARKERS.some((marker) => - error.includes(marker) - ); -}; - -export const normalizeTraceContext = (context?: GraphTraceContext): GraphTraceContext => { - if (context) { - return context; - } - return { - source: "chat", - route: "unknown" - }; -}; - -export const normalizeAccessContext = ( - context?: SqlTableAccessContext -): SqlTableAccessContext | undefined => { - if (!context) { - return undefined; - } - const actorId = context.actorId?.trim(); - const workspaceId = context.workspaceId?.trim(); - if (!actorId || !workspaceId) { - return undefined; - } - return { - ...context, - actorId, - workspaceId, - roleSet: context.roleSet?.map((item) => item.trim()).filter(Boolean) ?? [], - allowedTables: - context.allowedTables?.map((item) => item.trim()).filter(Boolean) ?? [] - }; -}; - -export const createInitialLangGraphState = ( - input: GraphInput, - fallbackProvider = "volcengine" -): LangGraphState => { - const traceContext = normalizeTraceContext(input.traceContext); - const accessContext = normalizeAccessContext(input.accessContext); - return { - ...input, - traceContext, - accessContext, - provider: fallbackProvider, - model: undefined, - llmRaw: undefined, - planningScaffoldEnabled: input.planningScaffoldEnabled ?? false, - planningStatus: input.planningScaffoldEnabled ? "ready" : "legacy", - planningWarnings: [], - trace: { - runId: input.runId, - provider: fallbackProvider, - retryCount: 0, - steps: [], - clarificationDecision: undefined - }, - spanEvents: [], - relationCorrectionRetryCount: 0 - }; -}; - -export const appendStep = ( - state: Pick, - event: LangGraphSpanEvent -): Pick => { - const nextSequence = state.trace.steps.length + 1; - const normalizedStep: ExecutionTraceStep = { - ...event.step, - sequence: event.step.sequence ?? nextSequence, - stepId: event.step.stepId ?? `${state.trace.runId}:${event.step.node}:${nextSequence}`, - lifecycle: - event.step.lifecycle ?? - (event.step.status === "failed" - ? "failed" - : event.step.status === "skipped" - ? "skipped" - : "completed") - }; - - return { - trace: { - ...state.trace, - steps: [...state.trace.steps, normalizedStep] - }, - spanEvents: [...state.spanEvents, { ...event, step: normalizedStep }] - }; -}; diff --git a/apps/backend/src/modules/conversation/agent/nodes/build-physical-plan.node.ts b/apps/backend/src/modules/conversation/agent/nodes/build-physical-plan.node.ts index b4f1a12..f885ba2 100644 --- a/apps/backend/src/modules/conversation/agent/nodes/build-physical-plan.node.ts +++ b/apps/backend/src/modules/conversation/agent/nodes/build-physical-plan.node.ts @@ -25,6 +25,31 @@ export class BuildPhysicalPlanNode { datasourceId: string; }): Promise { const { semanticPlan } = input; + const requiresClarification = semanticPlan.semanticHints.includes( + "route_clarification_required" + ); + const requiresFailClosed = semanticPlan.semanticHints.includes( + "route_fail_closed_for_write_intent" + ); + if (requiresClarification || requiresFailClosed) { + const summary = requiresFailClosed + ? "检测到写操作意图，执行计划按 fail-closed 降级。" + : "语义路由要求澄清，执行计划降级并等待补充信息。"; + return { + status: "degraded", + strategy: "fallback_sql", + semanticConstraintMode: "fallback_text", + semanticVersion: semanticPlan.semanticVersion, + lockStatus: semanticPlan.lockStatus, + fallbackApplied: true, + cacheStatus: "miss", + cacheReason: requiresFailClosed + ? "semantic_route_fail_closed" + : "semantic_route_clarify", + summary + }; + } + if (semanticPlan.status === "degraded" && !semanticPlan.semanticVersion) { return { status: "degraded", diff --git a/apps/backend/src/modules/conversation/agent/nodes/build-semantic-query.node.ts b/apps/backend/src/modules/conversation/agent/nodes/build-semantic-query.node.ts index 5766c62..86b2ba1 100644 --- a/apps/backend/src/modules/conversation/agent/nodes/build-semantic-query.node.ts +++ b/apps/backend/src/modules/conversation/agent/nodes/build-semantic-query.node.ts @@ -116,6 +116,25 @@ export class BuildSemanticQueryNode { : intentPlan.intent === "compare" ? ["normalize_time_window", "keep_metric_consistency"] : ["prefer_direct_lookup"]; + if (clarificationDecision?.decision === "clarify") { + semanticHints.push("route_clarification_required"); + } + if (clarificationDecision?.decisionSource === "metadata-intent") { + semanticHints.push("route_metadata_answer_preferred"); + } + if (clarificationDecision?.decisionSource === "sql-write-intent") { + semanticHints.push("route_fail_closed_for_write_intent"); + } + if ( + (clarificationDecision?.reasonCodes ?? []).some( + (reasonCode) => reasonCode === "clarification_round_limit_reached" + ) + ) { + semanticHints.push("clarification_round_limit_reached"); + planningWarnings.semantic.push( + "clarification round limit reached; downstream should prefer fail-closed route" + ); + } if (intentPlan.constraints.includes("must_use_selected_context")) { semanticHints.push("must_consume_selected_context"); } diff --git a/apps/backend/src/modules/conversation/agent/nodes/clarify.node.ts b/apps/backend/src/modules/conversation/agent/nodes/clarify.node.ts index b957761..e437bac 100644 --- a/apps/backend/src/modules/conversation/agent/nodes/clarify.node.ts +++ b/apps/backend/src/modules/conversation/agent/nodes/clarify.node.ts @@ -6,13 +6,57 @@ import { type SlotFillingDecision } from "./slot-filling-context"; +export interface ClarificationRoundPolicy { + round: number; + maxRounds: number; +} + @Injectable() export class ClarifyNode { evaluate(question: string, contextEnvelope?: ContextEnvelope): SlotFillingDecision { + const roundPolicy = this.resolveRoundPolicy(contextEnvelope); try { - return decideSlotFilling(question, contextEnvelope); + const decision = decideSlotFilling(question, contextEnvelope); + if (!decision.shouldClarify) { + return decision; + } + const targetedQuestion = this.toSingleTargetQuestion(decision); + if (roundPolicy.round >= roundPolicy.maxRounds) { + return { + ...decision, + reason: "澄清轮次已达上限，按 fail-closed 指引终止。", + question: + "当前信息仍不足以生成安全 SQL。请直接补充分析对象、指标口径和时间范围后重试。", + reasonCodes: this.unique([ + ...decision.reasonCodes, + "clarification_round_limit_reached" + ]) + }; + } + return { + ...decision, + question: targetedQuestion, + reasonCodes: this.unique([ + ...decision.reasonCodes, + `clarification_round:${roundPolicy.round}`, + `clarification_max_rounds:${roundPolicy.maxRounds}` + ]) + }; } catch { - return buildFallbackSlotFillingDecision(); + const fallback = buildFallbackSlotFillingDecision(); + if (roundPolicy.round >= roundPolicy.maxRounds) { + return { + ...fallback, + reason: "澄清轮次已达上限，按 fail-closed 指引终止。", + question: + "当前信息仍不足以生成安全 SQL。请直接补充分析对象、指标口径和时间范围后重试。", + reasonCodes: this.unique([ + ...fallback.reasonCodes, + "clarification_round_limit_reached" + ]) + }; + } + return fallback; } } @@ -21,6 +65,10 @@ export class ClarifyNode { contextEnvelope?: ContextEnvelope ): ClarificationPrompt | undefined { const decision = this.evaluate(question, contextEnvelope); + return this.toPrompt(decision); + } + + toPrompt(decision: SlotFillingDecision): ClarificationPrompt | undefined { if (!decision.shouldClarify) { return undefined; } @@ -37,4 +85,51 @@ export class ClarifyNode { ...(decision.reasonCodes.length > 0 ? { reasonCodes: decision.reasonCodes } : {}) }; } + + resolveRoundPolicy(contextEnvelope?: ContextEnvelope): ClarificationRoundPolicy { + const policy: ClarificationRoundPolicy = { + round: 0, + maxRounds: 2 + }; + for (const constraint of contextEnvelope?.businessConstraints ?? []) { + const normalized = constraint.trim().toLowerCase(); + if (!normalized) { + continue; + } + const roundMatch = /^clarification_round\s*[:=]\s*(\d+)$/i.exec(normalized); + if (roundMatch?.[1]) { + policy.round = Math.max(0, Number(roundMatch[1])); + } + const maxMatch = /^clarification_max_rounds\s*[:=]\s*(\d+)$/i.exec(normalized); + if (maxMatch?.[1]) { + policy.maxRounds = Math.max(1, Number(maxMatch[1])); + } + } + return policy; + } + + private toSingleTargetQuestion(decision: SlotFillingDecision): string { + const missing = decision.missingCriticalSlots ?? []; + const targetSlot = missing[0]; + if (!targetSlot) { + return decision.question; + } + if (targetSlot === "subject") { + return "请先补充分析对象（例如订单、用户、商品或门店）。"; + } + if (targetSlot === "metric") { + return "请先补充要统计的指标口径（例如订单数、退款金额、转化率）。"; + } + if (targetSlot === "time") { + return "请先补充时间范围（例如近30天、本季度或具体起止日期）。"; + } + if (targetSlot === "dimension") { + return "请先补充需要分组的维度（例如地区、渠道、支付方式）。"; + } + return "请先补充过滤条件（例如状态、地区、金额区间）。"; + } + + private unique(values: string[]): string[] { + return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean))); + } } diff --git a/apps/backend/src/modules/conversation/agent/nodes/execute-sql.node.ts b/apps/backend/src/modules/conversation/agent/nodes/execute-sql.node.ts index a5fd501..9fd32f4 100644 --- a/apps/backend/src/modules/conversation/agent/nodes/execute-sql.node.ts +++ b/apps/backend/src/modules/conversation/agent/nodes/execute-sql.node.ts @@ -1,4 +1,5 @@ -import { Injectable } from "@nestjs/common"; +import { Injectable, Optional } from "@nestjs/common"; +import type { SemanticPlanV1 } from "@text2sql/shared-types"; import { DomainError } from "../../../../common/domain-error"; import { AuditLogRepository, @@ -11,6 +12,9 @@ import { import { DatasourceService } from "../../../governance/datasource/datasource.service"; import type { AccessContext } from "../../../governance/access/datasource-access-policy.service"; import { PolicyEvaluatorService } from "../../../governance/access/policy-evaluator.service"; +import { SqlCorrectionService } from "../../adapters/sql-correction.service"; +import { SqlValidationService } from "../../adapters/sql-validation.service"; +import type { StructuredSqlGenerationArtifact } from "../sql/sql-generation.service"; @Injectable() export class ExecuteSqlNode { @@ -19,15 +23,20 @@ export class ExecuteSqlNode { private readonly queryExecutorRouter: QueryExecutorRouterService, private readonly chatRepository: ChatRepository, private readonly policyEvaluatorService: PolicyEvaluatorService, - private readonly auditLogRepository: AuditLogRepository + private readonly auditLogRepository: AuditLogRepository, + private readonly sqlCorrectionService: SqlCorrectionService, + @Optional() + private readonly sqlValidationService?: SqlValidationService ) {} async run(input: { sql: string; + sqlArtifact?: StructuredSqlGenerationArtifact; datasourceId: string; sessionId: string; requestId?: string; accessContext?: SqlTableAccessContext; + semanticPlan?: SemanticPlanV1; }): Promise<{ rows: Array>; columns: string[]; @@ -67,6 +76,49 @@ export class ExecuteSqlNode { } : undefined; + if (this.sqlValidationService) { + const validation = await this.sqlValidationService.validate({ + sql: input.sql, + datasourceId: input.datasourceId, + datasourceType: datasource.type, + semanticPlan: input.semanticPlan, + sqlArtifact: input.sqlArtifact, + accessContext: effectiveAccessContext, + allowedTables: policyResult?.readableTables + }); + if (validation.status === "failed" && validation.failure) { + if (validation.failure.correctable) { + throw new DomainError( + "SQL_CORRECTABLE_EXECUTION_FAILED", + validation.failure.message, + 422, + { + correctable: true, + validationOutcome: "correctable", + correctionReason: validation.failure.code, + maxAttempts: this.sqlCorrectionService.maxAttempts, + validationFailure: validation.failure, + validationArtifact: validation + } + ); + } + throw new DomainError( + "SQL_TERMINAL_VALIDATION_FAILED", + validation.failure.message, + 422, + { + correctable: false, + validationOutcome: "terminal", + governanceFailClosed: + validation.failure.category === "governance" || + validation.failure.code === "SQL_READ_ONLY_VIOLATION", + validationFailure: validation.failure, + validationArtifact: validation + } + ); + } + } + try { return await this.queryExecutorRouter.execute({ datasource, @@ -89,6 +141,26 @@ export class ExecuteSqlNode { accessContext: effectiveAccessContext }); } + if ( + error instanceof DomainError && + (error.code === "SQL_TERMINAL_VALIDATION_FAILED" || + error.code === "SQL_CORRECTABLE_EXECUTION_FAILED") + ) { + throw error; + } + const correctionDecision = this.sqlCorrectionService.decide(error); + if (correctionDecision.correctable) { + throw new DomainError( + "SQL_CORRECTABLE_EXECUTION_FAILED", + error instanceof Error ? error.message : String(error), + 422, + { + correctable: true, + correctionReason: correctionDecision.reason, + maxAttempts: correctionDecision.maxAttempts + } + ); + } throw error; } } diff --git a/apps/backend/src/modules/conversation/agent/nodes/format-answer.node.ts b/apps/backend/src/modules/conversation/agent/nodes/format-answer.node.ts index 1eabb7a..1210833 100644 --- a/apps/backend/src/modules/conversation/agent/nodes/format-answer.node.ts +++ b/apps/backend/src/modules/conversation/agent/nodes/format-answer.node.ts @@ -1,4 +1,5 @@ import { Injectable } from "@nestjs/common"; +import type { SemanticContextPackV1, SemanticPlanV1 } from "@text2sql/shared-types"; @Injectable() export class FormatAnswerNode { @@ -26,6 +27,72 @@ export class FormatAnswerNode { .join("\n"); } + runDirectAnswer(answer: string, warnings: string[] = []): string { + return [answer.trim(), ...warnings.map((warning) => `说明：${warning}`)] + .filter((line) => line.length > 0) + .join("\n"); + } + + runMetadataDirectAnswer(input: { + answer: string; + contextPack?: SemanticContextPackV1; + semanticPlan?: SemanticPlanV1; + warnings?: string[]; + }): string { + const intro = input.answer.trim(); + const selectedEvidenceCount = + input.contextPack?.selectedContextSummary?.count ?? + input.contextPack?.selectedEvidenceIds?.length ?? + input.semanticPlan?.evidenceRefs?.length ?? + 0; + const selectedTables = this.normalizeIdentifiers( + input.contextPack?.selectedTables ?? input.semanticPlan?.selectedTables ?? [] + ); + const selectedColumns = this.normalizeIdentifiers( + input.contextPack?.selectedColumns ?? input.semanticPlan?.selectedColumns ?? [] + ); + const schemaSupplementCount = + input.contextPack?.lanes?.schemaSupplementRefs?.count ?? + input.contextPack?.lanes?.schemaSupplementRefs?.refs?.length ?? + 0; + const warningLines = this.unique(input.warnings ?? []) + .slice(0, 3) + .map((warning) => `说明：${warning}`); + + return [ + intro, + `元数据证据摘要：已选中 ${selectedEvidenceCount} 条上下文证据。`, + `结构覆盖：表 ${this.formatIdentifierList(selectedTables, "未定位到可公开表信息")}；字段 ${this.formatIdentifierList(selectedColumns, "未定位到可公开字段信息")}。`, + `Schema 补充：${schemaSupplementCount} 条。`, + `裁剪情况：${this.buildPruningSummary(input.contextPack)}`, + `权限过滤：${this.buildPermissionFilteringSummary(input.contextPack)}`, + `证据质量：${this.buildEvidenceQualitySummary(input.contextPack)}`, + ...warningLines + ] + .filter((line) => line.length > 0) + .join("\n"); + } + + runFailClosed(reason: string, guidance?: string): string { + return [ + "当前请求未通过安全或治理校验，系统已按 fail-closed 终止。", + reason.trim(), + guidance?.trim() || "请改为只读分析问题，或补充更明确且合规的分析范围后重试。" + ] + .filter((line) => line.length > 0) + .join("\n"); + } + + runOperationalFailure(reason: string, guidance?: string): string { + return [ + "本次分析未能完成，失败发生在 SQL 生成或服务调用阶段。", + reason.trim(), + guidance?.trim() || "请稍后重试，或切换模型/缩小问题范围后再试。" + ] + .filter((line) => line.length > 0) + .join("\n"); + } + private buildMetricSummary( rows: Array>, numericColumns: string[] @@ -90,4 +157,84 @@ export class FormatAnswerNode { } return String(value); } + + private normalizeIdentifiers(values: string[]): string[] { + return Array.from( + new Set(values.map((value) => value.trim()).filter((value) => value.length > 0)) + ); + } + + private formatIdentifierList(values: string[], fallback: string): string { + if (values.length === 0) { + return fallback; + } + if (values.length <= 4) { + return values.join("、"); + } + return `${values.slice(0, 4).join("、")} 等`; + } + + private buildPruningSummary(contextPack?: SemanticContextPackV1): string { + if (!contextPack?.pruning?.applied) { + return "未触发上下文裁剪。"; + } + const decisions = contextPack.pruning.decisions ?? []; + const keptCount = decisions.reduce((total, decision) => { + const fallbackCount = decision.keptEvidenceIds?.length ?? 0; + return total + this.toCount(decision.keptCount, fallbackCount); + }, 0); + const removedCount = decisions.reduce((total, decision) => { + const fallbackCount = decision.removedEvidenceIds?.length ?? 0; + return total + this.toCount(decision.removedCount, fallbackCount); + }, 0); + const reasonCodes = this.unique( + decisions.flatMap((decision) => decision.reasonCodes ?? []) + ).slice(0, 2); + const reasonSuffix = + reasonCodes.length > 0 ? `，原因：${reasonCodes.join("、")}` : ""; + return `已触发，保留 ${keptCount} 条，裁剪 ${removedCount} 条${reasonSuffix}。`; + } + + private buildPermissionFilteringSummary(contextPack?: SemanticContextPackV1): string { + const permissionFiltering = contextPack?.permissionFiltering; + if (!permissionFiltering || permissionFiltering.status !== "applied") { + return "未触发。"; + } + const deniedEvidenceCount = + permissionFiltering.deniedEvidenceCount ?? + permissionFiltering.deniedEvidenceIds?.length ?? + 0; + const reasonCodes = this.unique(permissionFiltering.reasonCodes ?? []).slice(0, 2); + const reasonSuffix = + reasonCodes.length > 0 ? `，原因：${reasonCodes.join("、")}` : ""; + return `已应用，受限证据 ${deniedEvidenceCount} 条（仅保留可访问摘要）${reasonSuffix}。`; + } + + private buildEvidenceQualitySummary(contextPack?: SemanticContextPackV1): string { + const degradedReasons = this.unique(contextPack?.degradation?.reasons ?? []); + const impactedLaneCount = (contextPack?.laneStates ?? []).filter( + (laneState) => + laneState.state === "degraded" || laneState.state === "unavailable" + ).length; + const degraded = + contextPack?.status === "degraded" || + impactedLaneCount > 0 || + degradedReasons.length > 0; + if (!degraded) { + return "ready。"; + } + const reasonText = + degradedReasons.length > 0 + ? degradedReasons.slice(0, 3).join("、") + : "retrieval_degraded"; + return `degraded（受影响 lane ${impactedLaneCount} 个，原因：${reasonText}）。`; + } + + private toCount(value: number | undefined, fallback: number): number { + return typeof value === "number" && Number.isFinite(value) ? value : fallback; + } + + private unique(values: string[]): string[] { + return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean))); + } } diff --git a/apps/backend/src/modules/conversation/agent/nodes/generate-sql.node.ts b/apps/backend/src/modules/conversation/agent/nodes/generate-sql.node.ts index 7859b9a..304eeab 100644 --- a/apps/backend/src/modules/conversation/agent/nodes/generate-sql.node.ts +++ b/apps/backend/src/modules/conversation/agent/nodes/generate-sql.node.ts @@ -1,5 +1,11 @@ -import { Injectable } from "@nestjs/common"; -import type { DatasourceType, PromptTemplateTraceEvidence } from "@text2sql/shared-types"; +import { Injectable, Optional } from "@nestjs/common"; +import type { + DatasourceType, + PromptTemplateTraceEvidence, + SemanticContextPackV1, + SemanticPlanV1 +} from "@text2sql/shared-types"; +import { DomainError } from "../../../../common/domain-error"; import type { LlmGatewayStreamEvent, LlmGatewayToolDefinition @@ -11,13 +17,23 @@ import { } from "../sql/sql-generation.service"; import type { SqlSemanticIntent } from "../sql/sql-prompt.builder"; import type { + RagRetrievalBundle, RagContextPack, RagRetrievalChunkPayload } from "../../../knowledge/rag/retrieval/rag-retrieval.types"; +import { SemanticContextPackService } from "../../adapters/semantic-context-pack.service"; +import { SemanticPlanService } from "../../adapters/semantic-plan.service"; +import { SemanticPlanValidator } from "../../adapters/semantic-plan.validator"; @Injectable() export class GenerateSqlNode { - constructor(private readonly sqlGeneration: SqlGenerationService) {} + constructor( + private readonly sqlGeneration: SqlGenerationService, + @Optional() + private readonly semanticContextPackService?: SemanticContextPackService, + @Optional() + private readonly semanticPlanService?: SemanticPlanService + ) {} async run( question: string, @@ -28,11 +44,13 @@ export class GenerateSqlNode { tools?: Record; onEvent?: (event: LlmGatewayStreamEvent) => Promise | void; selectedContext?: RagRetrievalChunkPayload[]; + retrievalBundle?: RagRetrievalBundle; semanticContextPack?: RagContextPack; datasourceId?: string; workspaceId?: string; semanticIntent?: SqlSemanticIntent; explicitPinning?: SqlGenerationExplicitPinningEvidence; + allowedTables?: string[]; } ): Promise<{ provider: string; @@ -49,9 +67,93 @@ export class GenerateSqlNode { retryCount?: number; semanticIntent?: SqlSemanticIntent; coverage?: SqlEvidenceCoverage; + semanticContextPack?: SemanticContextPackV1; + semanticPlan?: SemanticPlanV1; }> { + const semanticContextPackService = + this.semanticContextPackService ?? new SemanticContextPackService(); + const semanticPlanService = + this.semanticPlanService ?? + new SemanticPlanService(new SemanticPlanValidator()); + + const semanticContextPack = semanticContextPackService.build({ + retrievalBundle: options?.retrievalBundle, + selectedContext: options?.selectedContext, + additionalWarnings: options?.semanticContextPack?.degrade_reasons + }); + const semanticPlanResult = semanticPlanService.build({ + question, + contextPack: semanticContextPack, + semanticIntent: options?.semanticIntent, + allowedTables: options?.allowedTables + }); + if (semanticPlanResult.plan.route === "reject") { + throw new DomainError( + "SEMANTIC_PLAN_FAIL_CLOSED", + "语义计划进入 fail-closed 路径，已阻止 SQL 生成。", + 422, + { + validation: semanticPlanResult.validation, + semanticPlan: semanticPlanResult.plan + } + ); + } + if (semanticPlanResult.plan.route === "clarify") { + throw new DomainError( + "SEMANTIC_PLAN_REQUIRES_CLARIFICATION", + "语义计划要求先澄清问题，已阻止 SQL 生成。", + 422, + { + validation: semanticPlanResult.validation, + semanticPlan: semanticPlanResult.plan + } + ); + } + if (semanticPlanResult.validation.routeKind === "metadata") { + throw new DomainError( + "SEMANTIC_PLAN_METADATA_ANSWER", + "这是元数据查询，不需要生成或执行 SQL。", + 200, + { + validation: semanticPlanResult.validation, + semanticPlan: semanticPlanResult.plan, + answer: "这是元数据查询，请查看当前数据源的表、字段与语义证据。" + } + ); + } + if (semanticPlanResult.validation.routeKind === "general") { + throw new DomainError( + "SEMANTIC_PLAN_GENERAL_ANSWER", + "这是通用说明问题，不需要生成或执行 SQL。", + 200, + { + validation: semanticPlanResult.validation, + semanticPlan: semanticPlanResult.plan, + answer: "这是通用说明问题，不需要执行 SQL；我会基于已有语义证据直接解释。" + } + ); + } + if ( + !semanticPlanResult.validation.valid && + semanticPlanResult.validation.reasons.some( + (reason) => + reason === "plan_contains_unsupported_tables" || + reason === "plan_contains_unsupported_columns" + ) + ) { + throw new DomainError( + "SEMANTIC_PLAN_VALIDATION_FAILED", + "语义计划包含未授权或不支持的表/字段，已阻止 SQL 生成。", + 422, + { + validation: semanticPlanResult.validation, + semanticPlan: semanticPlanResult.plan + } + ); + } + if (options?.stream) { - return this.sqlGeneration.stream( + const draft = await this.sqlGeneration.stream( question, { datasourceId: options.datasourceId, @@ -61,15 +163,21 @@ export class GenerateSqlNode { selectedContext: options.selectedContext, semanticContextPack: options.semanticContextPack, semanticIntent: options.semanticIntent, - explicitPinning: options.explicitPinning + explicitPinning: options.explicitPinning, + semanticPlan: semanticPlanResult.plan }, { tools: options.tools, onEvent: options.onEvent } ); + return { + ...draft, + semanticContextPack, + semanticPlan: semanticPlanResult.plan + }; } - return this.sqlGeneration.generate(question, { + const draft = await this.sqlGeneration.generate(question, { datasourceId: options?.datasourceId, workspaceId: options?.workspaceId, datasourceType, @@ -77,7 +185,13 @@ export class GenerateSqlNode { selectedContext: options?.selectedContext, semanticContextPack: options?.semanticContextPack, semanticIntent: options?.semanticIntent, - explicitPinning: options?.explicitPinning + explicitPinning: options?.explicitPinning, + semanticPlan: semanticPlanResult.plan }); + return { + ...draft, + semanticContextPack, + semanticPlan: semanticPlanResult.plan + }; } } diff --git a/apps/backend/src/modules/conversation/agent/nodes/retrieve-knowledge.node.ts b/apps/backend/src/modules/conversation/agent/nodes/retrieve-knowledge.node.ts index a21b204..70ad2b1 100644 --- a/apps/backend/src/modules/conversation/agent/nodes/retrieve-knowledge.node.ts +++ b/apps/backend/src/modules/conversation/agent/nodes/retrieve-knowledge.node.ts @@ -1,5 +1,11 @@ import { Inject, Injectable } from "@nestjs/common"; -import type { ContextEnvelopePinningEvidence } from "@text2sql/shared-types"; +import type { + ContextEnvelopePinningEvidence, + Datasource, + DatasourceType +} from "@text2sql/shared-types"; +import { AppConfigService } from "../../../config/app-config.service"; +import { QueryExecutorRouterService } from "../../../platform/data/query/index"; import { KNOWLEDGE_RAG_CONTRACT, type KnowledgeRagContract @@ -10,6 +16,19 @@ import type { RagRetrievalBundle } from "../../../knowledge/rag/retrieval/rag-retrieval.types"; +export interface RetrievedKnowledgeTypedSummary { + status: "ready" | "degraded"; + candidateCount: number; + selectedContextCount: number; + priorSqlHitCount: number; + denseState: "ready" | "degraded" | "unavailable" | "skipped"; + denseReason?: string; + rerankState: "ready" | "degraded" | "unavailable" | "skipped"; + rerankReason?: string; + pruningDecisionCount: number; + degradeReasons: string[]; +} + export interface RetrievedKnowledge { status: "ready" | "degraded"; snippets: string[]; @@ -17,6 +36,8 @@ export interface RetrievedKnowledge { retrievalBundle?: RagRetrievalBundle; contextPack?: RagContextPack; pinning?: ContextEnvelopePinningEvidence; + typedSummary: RetrievedKnowledgeTypedSummary; + evidenceRefs: string[]; } interface RetrievalPinningConfig { @@ -30,9 +51,33 @@ interface RetrievalPinningResult { pinning: ContextEnvelopePinningEvidence; } +interface LaneStateSummary { + state: "ready" | "degraded" | "unavailable" | "skipped"; + reason?: string; +} + +const MAX_SCHEMA_SUPPLEMENT_TABLES = 4; + +const SCHEMA_RELEVANCE_HINTS: Record = { + orders: ["订单", "下单", "单量", "gmv", "order"], + order_items: ["订单明细", "商品明细", "明细", "item"], + payments: ["支付", "付款", "支付方式", "支付渠道", "payment", "method"], + refunds: ["退款", "退货", "refund"], + customers: ["客户", "顾客", "customer"], + users: ["用户", "user"], + merchants: ["商户", "店铺", "merchant"], + shipments: ["物流", "发货", "配送", "shipment"], + products_sku: ["sku", "规格", "库存单位"], + products_spu: ["spu", "商品", "产品"], + inventory: ["库存", "inventory"], + categories: ["类目", "分类", "category"] +}; + @Injectable() export class RetrieveKnowledgeNode { constructor( + private readonly appConfig: AppConfigService, + private readonly queryExecutorRouter: QueryExecutorRouterService, @Inject(KNOWLEDGE_RAG_CONTRACT) private readonly ragContract: KnowledgeRagContract ) {} @@ -40,6 +85,7 @@ export class RetrieveKnowledgeNode { async run(input: { question: string; datasourceId: string; + datasource?: Datasource; runId: string; workspaceId?: string; allowedTables?: string[]; @@ -57,76 +103,29 @@ export class RetrieveKnowledgeNode { const normalized = question.trim(); if (!normalized) { - return { - status: "degraded", - snippets: [], - summary: "检索输入为空，已降级到最小执行路径。", - retrievalBundle: { - query: question, - run_id: runId, - datasource_id: datasourceId, - status: "degraded", - degrade_reasons: ["empty_question"], - lane_results: { - lexical: { - lane: "lexical", - status: "degraded", - timeout_ms: 0, - elapsed_ms: 0, - degrade_reason: "empty_question", - hits: [] - }, - dense: { - lane: "dense", - status: "degraded", - timeout_ms: 0, - elapsed_ms: 0, - degrade_reason: "empty_question", - hits: [] - }, - graph: { - lane: "graph", - status: "degraded", - timeout_ms: 0, - elapsed_ms: 0, - degrade_reason: "empty_question", - hits: [] - } - }, - candidates: [], - reranked: [], - selected_context: [], - risk_tags: ["rag_zero_recall"], - context_pack: { - status: "degraded", - semantic_lock_status: "degraded", - semantic_bindings: { - model_keys: [], - relationship_keys: [], - metric_keys: [], - calculated_field_keys: [] - }, - instruction_sets: { - model_bindings: [], - relationship_bindings: [], - metric_bindings: [], - calculated_field_bindings: [] - }, - selected_context_summary: { - count: 0, - snippets: [] - }, - degrade_reasons: ["empty_question"], - risk_tags: ["semantic_spine_degraded"] - } - }, - pinning: { - enabled: pinningConfig.enabled, - status: "inactive", - candidateFilteredCount: 0, - selectedContextFilteredCount: 0 - } - }; + return this.createDisabledKnowledge({ + query: question, + datasourceId, + datasource: input.datasource, + runId, + allowedTables: input.allowedTables, + pinningConfig, + degradeReason: "empty_question", + summary: "检索输入为空，已降级到最小执行路径。" + }); + } + + if (!this.appConfig.agentRagRetrievalEnabled) { + return this.createDisabledKnowledge({ + query: normalized, + datasourceId, + datasource: input.datasource, + runId, + allowedTables: input.allowedTables, + pinningConfig, + degradeReason: "rag_retrieval_disabled", + summary: "RAG 检索开关已关闭，已降级到最小执行路径。" + }); } const retrieved = await this.ragContract.retrieval.retrieve({ @@ -144,7 +143,11 @@ export class RetrieveKnowledgeNode { reranked.retrieval_bundle, pinningConfig ); - const bundle = pinningResult.bundle; + const bundle = await this.withAllowedTableSchemaSupplement( + pinningResult.bundle, + input.datasource, + input.allowedTables + ); const pinningSummary = pinningResult.pinning.enabled && pinningResult.pinning.status === "applied" ? `，pinning[candidates=${pinningResult.pinning.candidateFilteredCount ?? 0},selected=${pinningResult.pinning.selectedContextFilteredCount ?? 0}]` @@ -154,17 +157,25 @@ export class RetrieveKnowledgeNode { const snippets = (bundle.selected_context ?? bundle.candidates.map((item) => item.chunk)) .slice(0, 3) .map((item) => item.content.slice(0, 200)); + const denseState = this.resolveLaneState(bundle, "dense"); + const rerankState = this.resolveRerankState(bundle); + const pruningSummary = this.summarizePruning(bundle); + const laneSummary = `dense=${denseState},rerank=${rerankState}`; + const typedSummary = this.buildTypedSummary(bundle); + const evidenceRefs = this.collectEvidenceRefs(bundle); return { status: bundle.status, snippets, summary: bundle.status === "ready" - ? `检索与重排完成，候选=${bundle.candidates.length}，上下文=${bundle.selected_context?.length ?? 0}，priorSQL=${priorSqlHitCount}${pinningSummary}。` - : `检索链路降级执行，原因=${bundle.degrade_reasons.join(", ") || "unknown"}，priorSQL=${priorSqlHitCount}${pinningSummary}。`, + ? `检索与重排完成，候选=${bundle.candidates.length}，上下文=${bundle.selected_context?.length ?? 0}，priorSQL=${priorSqlHitCount}，${laneSummary}${pruningSummary}${pinningSummary}。` + : `检索链路降级执行，原因=${bundle.degrade_reasons.join(", ") || "unknown"}，priorSQL=${priorSqlHitCount}，${laneSummary}${pruningSummary}${pinningSummary}。`, retrievalBundle: bundle, contextPack: bundle.context_pack, - pinning: pinningResult.pinning + pinning: pinningResult.pinning, + typedSummary, + evidenceRefs }; } @@ -181,6 +192,392 @@ export class RetrieveKnowledgeNode { }; } + private async createDisabledKnowledge(input: { + query: string; + datasourceId: string; + datasource?: Datasource; + runId: string; + allowedTables?: string[]; + pinningConfig: RetrievalPinningConfig; + degradeReason: string; + summary: string; + }): Promise { + const retrievalBundle = await this.withAllowedTableSchemaSupplement( + this.buildDegradedBundle({ + query: input.query, + datasourceId: input.datasourceId, + runId: input.runId, + degradeReason: input.degradeReason + }), + input.datasource, + input.allowedTables + ); + const typedSummary = this.buildTypedSummary(retrievalBundle); + const evidenceRefs = this.collectEvidenceRefs(retrievalBundle); + return { + status: "degraded", + snippets: [], + summary: input.summary, + retrievalBundle, + contextPack: retrievalBundle.context_pack, + pinning: { + enabled: input.pinningConfig.enabled, + status: "inactive", + candidateFilteredCount: 0, + selectedContextFilteredCount: 0 + }, + typedSummary, + evidenceRefs + }; + } + + private buildDegradedBundle(input: { + query: string; + datasourceId: string; + runId: string; + degradeReason: string; + }): RagRetrievalBundle { + return { + query: input.query, + run_id: input.runId, + datasource_id: input.datasourceId, + status: "degraded", + degrade_reasons: [input.degradeReason], + lane_results: { + lexical: { + lane: "lexical", + status: "degraded", + timeout_ms: 0, + elapsed_ms: 0, + degrade_reason: input.degradeReason, + hits: [] + }, + dense: { + lane: "dense", + status: "degraded", + timeout_ms: 0, + elapsed_ms: 0, + degrade_reason: input.degradeReason, + hits: [] + }, + graph: { + lane: "graph", + status: "degraded", + timeout_ms: 0, + elapsed_ms: 0, + degrade_reason: input.degradeReason, + hits: [] + } + }, + candidates: [], + reranked: [], + selected_context: [], + risk_tags: ["rag_zero_recall", input.degradeReason], + lane_metadata: [ + { + lane: "dense", + state: "unavailable", + unavailable_reason: input.degradeReason, + reason_codes: [input.degradeReason] + }, + { + lane: "rerank", + state: "skipped", + fallback_reason: input.degradeReason, + reason_codes: [input.degradeReason] + } + ], + pruning_decisions: [ + { + budget_source: "context_pack", + removed_evidence_ids: [], + kept_evidence_ids: [], + reason_codes: [input.degradeReason], + summary: `context_pack:disabled:${input.degradeReason}` + } + ], + context_pack: { + status: "degraded", + semantic_lock_status: "degraded", + semantic_bindings: { + model_keys: [], + relationship_keys: [], + metric_keys: [], + calculated_field_keys: [] + }, + instruction_sets: { + model_bindings: [], + relationship_bindings: [], + metric_bindings: [], + calculated_field_bindings: [] + }, + selected_context_summary: { + count: 0, + snippets: [] + }, + lane_metadata: [ + { + lane: "dense", + state: "unavailable", + unavailable_reason: input.degradeReason, + reason_codes: [input.degradeReason] + }, + { + lane: "rerank", + state: "skipped", + fallback_reason: input.degradeReason, + reason_codes: [input.degradeReason] + } + ], + pruning_decisions: [ + { + budget_source: "context_pack", + removed_evidence_ids: [], + kept_evidence_ids: [], + reason_codes: [input.degradeReason], + summary: `context_pack:disabled:${input.degradeReason}` + } + ], + selected_context_lanes: [], + degrade_reasons: [input.degradeReason], + risk_tags: ["semantic_spine_degraded", input.degradeReason] + } + }; + } + + private async withAllowedTableSchemaSupplement( + bundle: RagRetrievalBundle, + datasource: Datasource | undefined, + allowedTables: string[] | undefined + ): Promise { + const allowed = this.normalizeAllowedTables(allowedTables); + if (!datasource || allowed.length === 0) { + return bundle; + } + + const selectedTables = this.selectSchemaSupplementTables(bundle.query, allowed); + if (selectedTables.length === 0) { + return bundle; + } + + const chunks = ( + await Promise.all( + selectedTables.map((tableName) => + this.buildSchemaSupplementChunk(datasource, tableName) + ) + ) + ).filter((chunk): chunk is RagRetrievalChunkPayload => Boolean(chunk)); + + if (chunks.length === 0) { + return bundle; + } + + const existingSelectedContext = bundle.selected_context ?? []; + const existingIds = new Set(existingSelectedContext.map((chunk) => chunk.chunk_id)); + const schemaChunks = chunks.filter((chunk) => !existingIds.has(chunk.chunk_id)); + const selectedContext = [...existingSelectedContext, ...schemaChunks]; + const schemaEvidenceIds = schemaChunks.map((chunk) => chunk.chunk_id); + const existingContextPack = bundle.context_pack; + const existingPruningDecisions = + existingContextPack?.pruning_decisions ?? + existingContextPack?.pruningDecisions ?? + []; + const schemaDecision = + schemaEvidenceIds.length > 0 + ? [ + { + budget_source: "context_pack" as const, + removed_evidence_ids: [], + kept_evidence_ids: schemaEvidenceIds, + reason_codes: ["schema_supplement_from_allowed_tables"], + summary: `context_pack:schema_supplement=${schemaEvidenceIds.length}` + } + ] + : []; + + return { + ...bundle, + selected_context: selectedContext, + context_pack: { + ...(existingContextPack ?? { + status: bundle.status, + semantic_lock_status: "degraded" as const, + semantic_bindings: { + model_keys: [], + relationship_keys: [], + metric_keys: [], + calculated_field_keys: [] + }, + instruction_sets: { + model_bindings: [], + relationship_bindings: [], + metric_bindings: [], + calculated_field_bindings: [] + }, + selected_context_summary: { + count: 0, + snippets: [] + }, + degrade_reasons: bundle.degrade_reasons, + risk_tags: bundle.risk_tags ?? [] + }), + selected_context_summary: { + count: selectedContext.length, + snippets: selectedContext.map((chunk) => chunk.content.slice(0, 200)) + }, + selected_context_lanes: this.unique([ + ...(existingContextPack?.selected_context_lanes ?? + existingContextPack?.selectedContextLanes ?? + []), + "schema_supplement" + ]), + pruning_decisions: [...existingPruningDecisions, ...schemaDecision], + pruningDecisions: [...existingPruningDecisions, ...schemaDecision] + } + }; + } + + private normalizeAllowedTables(values: string[] | undefined): string[] { + if (!Array.isArray(values)) { + return []; + } + return this.unique( + values + .map((value) => value.trim().toLowerCase()) + .filter((value) => value.length > 0) + ); + } + + private selectSchemaSupplementTables(question: string, allowedTables: string[]): string[] { + const normalizedQuestion = question.trim().toLowerCase(); + const ranked = allowedTables + .map((tableName, index) => ({ + tableName, + index, + score: this.scoreSchemaTableRelevance(normalizedQuestion, tableName) + })) + .filter((item) => item.score > 0) + .sort((left, right) => right.score - left.score || left.index - right.index); + + if (ranked.length === 0) { + return allowedTables.length === 1 ? allowedTables : []; + } + + return ranked + .slice(0, MAX_SCHEMA_SUPPLEMENT_TABLES) + .map((item) => item.tableName); + } + + private scoreSchemaTableRelevance(question: string, tableName: string): number { + let score = 0; + const tableTokens = this.identifierTokens(tableName); + for (const token of tableTokens) { + if (question.includes(token)) { + score += 2; + } + } + for (const hint of SCHEMA_RELEVANCE_HINTS[tableName] ?? []) { + if (question.includes(hint.toLowerCase())) { + score += 4; + } + } + return score; + } + + private async buildSchemaSupplementChunk( + datasource: Datasource, + tableName: string + ): Promise { + try { + const result = await this.queryExecutorRouter.execute({ + datasource, + sql: this.buildColumnDiscoverySql(datasource.type, tableName), + limit: 200 + }); + const columns = this.unique( + result.rows + .map((row: Record) => this.readColumnName(row)) + .filter((column): column is string => Boolean(column)) + ); + if (columns.length === 0) { + return undefined; + } + + const qualifiedColumns = columns.map((column) => `${tableName}.${column}`); + return { + chunk_id: `schema-supplement:${datasource.id}:${tableName}`, + content: `Schema supplement for allowed table ${tableName}: columns=${columns.join(", ")}`, + metadata: { + datasourceId: datasource.id, + indexVersionId: "schema-supplement", + chunkId: `schema-supplement:${datasource.id}:${tableName}`, + domain: "schema", + chunkProfile: "schema_ddl_supplement", + tableNames: [tableName], + columnNames: qualifiedColumns, + sourceMetadata: { + source: "allowed_table_schema_supplement" + } + } + }; + } catch { + return undefined; + } + } + + private buildColumnDiscoverySql(type: DatasourceType, tableName: string): string { + const escapedTableName = this.escapeSqlLiteral(tableName); + if (type === "mysql") { + return ` +SELECT column_name AS columnName, data_type AS dataType +FROM information_schema.columns +WHERE table_schema = DATABASE() + AND table_name = '${escapedTableName}' +ORDER BY ordinal_position + `.trim(); + } + if (type === "postgresql") { + return ` +SELECT column_name AS columnName, data_type AS dataType +FROM information_schema.columns +WHERE table_schema = 'public' + AND table_name = '${escapedTableName}' +ORDER BY ordinal_position + `.trim(); + } + return ` +SELECT name AS columnName, type AS dataType +FROM pragma_table_info('${escapedTableName}') +ORDER BY cid + `.trim(); + } + + private readColumnName(row: Record): string | undefined { + const value = row.columnName ?? row.column_name ?? row.name ?? row.COLUMN_NAME; + if (typeof value !== "string") { + return undefined; + } + const normalized = value.trim(); + return normalized.length > 0 ? normalized.toLowerCase() : undefined; + } + + private identifierTokens(value: string): string[] { + return this.unique( + value + .split(/[^a-z0-9]+/i) + .map((token) => token.trim().toLowerCase()) + .filter((token) => token.length >= 3) + ); + } + + private escapeSqlLiteral(value: string): string { + return value.replace(/'/g, "''"); + } + + private unique(values: string[]): string[] { + return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean))); + } + private applyPinningConstraints( bundle: RagRetrievalBundle, pinningConfig: RetrievalPinningConfig @@ -214,6 +611,9 @@ export class RetrieveKnowledgeNode { 0, (bundle.selected_context?.length ?? 0) - filteredSelectedContext.length ); + const removedEvidenceIds = (bundle.selected_context ?? []) + .map((chunk) => chunk.chunk_id) + .filter((chunkId) => !filteredSelectedContext.some((chunk) => chunk.chunk_id === chunkId)); const nextBundle: RagRetrievalBundle = { ...bundle, @@ -224,7 +624,11 @@ export class RetrieveKnowledgeNode { reranked: filteredReranked } : {}), - context_pack: this.withPinnedContextPack(bundle.context_pack, filteredSelectedContext) + context_pack: this.withPinnedContextPack( + bundle.context_pack, + filteredSelectedContext, + removedEvidenceIds + ) }; return { @@ -240,18 +644,35 @@ export class RetrieveKnowledgeNode { private withPinnedContextPack( contextPack: RagContextPack | undefined, - selectedContext: RagRetrievalChunkPayload[] + selectedContext: RagRetrievalChunkPayload[], + removedEvidenceIds: string[] ): RagContextPack | undefined { if (!contextPack) { return contextPack; } + const existingPruningDecisions = + contextPack.pruning_decisions ?? contextPack.pruningDecisions ?? []; + const pinningDecision = + removedEvidenceIds.length > 0 + ? [ + { + budget_source: "context_pack" as const, + removed_evidence_ids: removedEvidenceIds, + kept_evidence_ids: selectedContext.map((chunk) => chunk.chunk_id), + reason_codes: ["pinning_filter_applied"], + summary: `context_pack:pinning_removed=${removedEvidenceIds.length}` + } + ] + : []; return { ...contextPack, selected_context_summary: { ...contextPack.selected_context_summary, count: selectedContext.length, snippets: selectedContext.map((chunk) => chunk.content.slice(0, 200)) - } + }, + pruning_decisions: [...existingPruningDecisions, ...pinningDecision], + pruningDecisions: [...existingPruningDecisions, ...pinningDecision] }; } @@ -276,6 +697,94 @@ export class RetrieveKnowledgeNode { return true; } + private resolveLaneState(bundle: RagRetrievalBundle, lane: "dense" | "lexical" | "graph"): string { + return this.resolveLaneStateSummary(bundle, lane).state; + } + + private resolveLaneStateSummary( + bundle: RagRetrievalBundle, + lane: "dense" | "lexical" | "graph" + ): LaneStateSummary { + const laneMetadata = bundle.context_pack?.lane_metadata ?? bundle.context_pack?.laneMetadata ?? []; + const laneMetadataEntry = laneMetadata.find((item) => item.lane === lane); + const metadataState = laneMetadataEntry?.state; + if (metadataState && metadataState.trim().length > 0) { + return { + state: this.normalizeLaneState(metadataState), + reason: laneMetadataEntry?.unavailable_reason ?? laneMetadataEntry?.fallback_reason + }; + } + const laneResult = bundle.lane_results[lane]; + if (laneResult.status === "ok") { + return { + state: "ready" + }; + } + if ((laneResult.degrade_reason ?? "").includes("unavailable")) { + return { + state: "unavailable", + reason: laneResult.degrade_reason + }; + } + return { + state: "degraded", + reason: laneResult.degrade_reason + }; + } + + private resolveRerankState(bundle: RagRetrievalBundle): string { + return this.resolveRerankStateSummary(bundle).state; + } + + private resolveRerankStateSummary(bundle: RagRetrievalBundle): LaneStateSummary { + const laneMetadata = bundle.context_pack?.lane_metadata ?? bundle.context_pack?.laneMetadata ?? []; + const rerankLane = laneMetadata.find((item) => item.lane === "rerank"); + if (rerankLane?.state) { + return { + state: this.normalizeLaneState(rerankLane.state), + reason: rerankLane.unavailable_reason ?? rerankLane.fallback_reason + }; + } + const secondary = bundle.rerank_metadata?.secondary ?? bundle.rerankMetadata?.secondary; + if (!secondary) { + return { + state: "skipped" + }; + } + if (secondary.status === "ok") { + return { + state: "ready" + }; + } + if (secondary.unavailable_reason || secondary.unavailableReason) { + return { + state: "unavailable", + reason: secondary.unavailable_reason ?? secondary.unavailableReason + }; + } + return { + state: this.normalizeLaneState(secondary.status), + reason: secondary.fallback_reason ?? secondary.fallbackReason + }; + } + + private summarizePruning(bundle: RagRetrievalBundle): string { + const pruningDecisions = + bundle.context_pack?.pruning_decisions ?? + bundle.context_pack?.pruningDecisions ?? + bundle.pruning_decisions ?? + bundle.pruningDecisions ?? + []; + if (pruningDecisions.length === 0) { + return ""; + } + const reasonCount = pruningDecisions.reduce( + (total, decision) => total + (decision.reason_codes?.length ?? decision.reasonCodes?.length ?? 0), + 0 + ); + return `,pruning[decisions=${pruningDecisions.length},reasons=${reasonCount}]`; + } + private toNormalizedSet(values?: string[]): Set { if (!Array.isArray(values) || values.length === 0) { return new Set(); @@ -286,4 +795,61 @@ export class RetrieveKnowledgeNode { .filter((item) => item.length > 0) ); } + + private buildTypedSummary(bundle: RagRetrievalBundle): RetrievedKnowledgeTypedSummary { + const dense = this.resolveLaneStateSummary(bundle, "dense"); + const rerank = this.resolveRerankStateSummary(bundle); + const priorSqlLane = bundle.prior_sql_lane ?? bundle.priorSqlLane; + const pruningDecisions = + bundle.context_pack?.pruning_decisions ?? + bundle.context_pack?.pruningDecisions ?? + bundle.pruning_decisions ?? + bundle.pruningDecisions ?? + []; + return { + status: bundle.status, + candidateCount: bundle.candidates.length, + selectedContextCount: bundle.selected_context?.length ?? 0, + priorSqlHitCount: priorSqlLane?.selected_count ?? priorSqlLane?.selectedCount ?? 0, + denseState: dense.state, + denseReason: dense.reason, + rerankState: rerank.state, + rerankReason: rerank.reason, + pruningDecisionCount: pruningDecisions.length, + degradeReasons: bundle.degrade_reasons ?? [] + }; + } + + private collectEvidenceRefs(bundle: RagRetrievalBundle): string[] { + const selectedContextIds = (bundle.selected_context ?? []).map((chunk) => chunk.chunk_id); + const candidateIds = bundle.candidates.map((candidate) => candidate.chunk_id); + const laneEvidenceIds = ( + bundle.context_pack?.lane_metadata ?? + bundle.context_pack?.laneMetadata ?? + [] + ).flatMap((lane) => lane.evidence_ids ?? lane.evidenceIds ?? []); + const pruningKeptIds = ( + bundle.context_pack?.pruning_decisions ?? + bundle.context_pack?.pruningDecisions ?? + [] + ).flatMap((decision) => decision.kept_evidence_ids ?? decision.keptEvidenceIds ?? []); + return Array.from( + new Set([...selectedContextIds, ...candidateIds, ...laneEvidenceIds, ...pruningKeptIds]) + ).slice(0, 128); + } + + private normalizeLaneState( + value: string + ): "ready" | "degraded" | "unavailable" | "skipped" { + if (value === "ready") { + return "ready"; + } + if (value === "unavailable") { + return "unavailable"; + } + if (value === "skipped") { + return "skipped"; + } + return "degraded"; + } } diff --git a/apps/backend/src/modules/conversation/agent/nodes/safety-check.node.ts b/apps/backend/src/modules/conversation/agent/nodes/safety-check.node.ts index 25706bc..ae25b41 100644 --- a/apps/backend/src/modules/conversation/agent/nodes/safety-check.node.ts +++ b/apps/backend/src/modules/conversation/agent/nodes/safety-check.node.ts @@ -1,4 +1,5 @@ -import { Injectable } from "@nestjs/common"; +import { Injectable, Optional } from "@nestjs/common"; +import type { DatasourceType, SemanticPlanV1 } from "@text2sql/shared-types"; import { DomainError } from "../../../../common/domain-error"; import { SqlTableAccessGuardService, @@ -8,20 +9,62 @@ import { SqlSafetyGuard, type SqlSafetyDecision } from "../sql/tools/sql-safety.guard"; +import { SqlValidationService } from "../../adapters/sql-validation.service"; @Injectable() export class SafetyCheckNode { constructor( private readonly tableAccessGuard: SqlTableAccessGuardService = new SqlTableAccessGuardService(), - private readonly safetyGuard?: SqlSafetyGuard + private readonly safetyGuard?: SqlSafetyGuard, + @Optional() + private readonly sqlValidationService?: SqlValidationService ) {} async run(input: { sql: string; datasourceId: string; + datasourceType?: DatasourceType; + semanticPlan?: SemanticPlanV1; accessContext?: SqlTableAccessContext; riskTags?: string[]; }): Promise { + if (this.sqlValidationService) { + const validation = await this.sqlValidationService.validate({ + sql: input.sql, + datasourceId: input.datasourceId, + datasourceType: input.datasourceType, + semanticPlan: input.semanticPlan, + accessContext: input.accessContext, + allowedTables: input.accessContext?.allowedTables + }); + if (validation.status === "failed" && validation.failure) { + if (validation.failure.correctable) { + return { + allowed: true, + mode: "soft-warn", + riskLevel: "medium", + riskTags: [ + "correctable_validation_failure", + validation.failure.code, + `validation_category:${validation.failure.category ?? "unknown"}` + ], + reason: validation.failure.message + }; + } + return { + allowed: false, + mode: "hard-block", + riskLevel: "high", + riskTags: [ + "terminal_validation_failure", + validation.failure.code, + `validation_category:${validation.failure.category ?? "unknown"}` + ], + reason: validation.failure.message + }; + } + } + const readonlyDecision = this.evaluateReadonly(input.sql, input.riskTags); if (!readonlyDecision.allowed) { return readonlyDecision; diff --git a/apps/backend/src/modules/conversation/agent/sql/sql-generation.service.ts b/apps/backend/src/modules/conversation/agent/sql/sql-generation.service.ts index 1957980..6ea87f8 100644 --- a/apps/backend/src/modules/conversation/agent/sql/sql-generation.service.ts +++ b/apps/backend/src/modules/conversation/agent/sql/sql-generation.service.ts @@ -1,5 +1,14 @@ import { Injectable } from "@nestjs/common"; -import type { DatasourceType, PromptTemplateTraceEvidence } from "@text2sql/shared-types"; +import type { + SqlCorrectionGroundingV1, + DatasourceType, + PromptTemplateTraceEvidence, + SemanticPlanLedgerObligationV1, + SemanticPlanV1, + SqlGenerationArtifactV1, + Text2SqlV2SmartDefaultsEvidenceV1, + Text2SqlV2ProviderMetadata +} from "@text2sql/shared-types"; import { DomainError } from "../../../../common/domain-error"; import type { LlmGatewayPrompt, @@ -14,6 +23,7 @@ import { type SqlSemanticIntent } from "./sql-prompt.builder"; import { PromptTemplateService } from "../../../governance/settings/prompt-template.service"; +import { Text2SqlSmartDefaultsService } from "../../runtime/smart-defaults/text2sql-smart-defaults.service"; import type { RetrievedKnowledge } from "../nodes/retrieve-knowledge.node"; import type { RagContextPack } from "../../../rag/retrieval/rag-retrieval.types"; @@ -31,6 +41,8 @@ interface SqlGenerationSelection { semanticContextPack?: RagContextPack; semanticIntent?: SqlSemanticIntent; explicitPinning?: SqlGenerationExplicitPinningEvidence; + semanticPlan?: SemanticPlanV1; + correctionGrounding?: SqlCorrectionGroundingV1; } export interface SqlGenerationExplicitPinningEvidence { @@ -39,6 +51,22 @@ export interface SqlGenerationExplicitPinningEvidence { columns?: string[]; } +export type SqlGenerationCause = + | "initial" + | "saved-prior" + | "shortcut-fallback" + | "correction"; + +export interface StructuredSqlGenerationArtifact extends SqlGenerationArtifactV1 { + cause: SqlGenerationCause; + dialect: DatasourceType; + provider?: Text2SqlV2ProviderMetadata; + promptTemplate?: PromptTemplateTraceEvidence; + smartDefaults?: Text2SqlV2SmartDefaultsEvidenceV1; + retryReason?: string; + coverage?: SqlEvidenceCoverage; +} + const MAX_SEMANTIC_REPAIR_RETRY = 1; const COUNT_INTENT_REGEX = /(多少|几条|几笔|总数|数量|计数|count|人数|单量|订单量|客户数|用户数)/i; @@ -78,9 +106,11 @@ export interface SqlDraft { rawText: string; prompt: LlmGatewayPrompt; promptTemplate?: PromptTemplateTraceEvidence; + smartDefaults?: Text2SqlV2SmartDefaultsEvidenceV1; retryCount?: number; semanticIntent?: SqlSemanticIntent; coverage?: SqlEvidenceCoverage; + semanticPlan?: SemanticPlanV1; } @Injectable() @@ -89,7 +119,8 @@ export class SqlGenerationService { private readonly promptBuilder: SqlPromptBuilder, private readonly extractor: SqlOutputExtractor, private readonly providerRouter: ProviderRouterService, - private readonly promptTemplateService: PromptTemplateService + private readonly promptTemplateService: PromptTemplateService, + private readonly smartDefaultsService: Text2SqlSmartDefaultsService ) {} async generate( @@ -99,13 +130,19 @@ export class SqlGenerationService { const templateResolution = await this.resolvePromptTemplate(selection); const semanticIntent = this.resolveSemanticIntent( question, - selection?.semanticIntent + selection?.semanticIntent, + selection?.semanticPlan ); + const smartDefaults = this.smartDefaultsService.resolve({ + promptTemplate: templateResolution.evidence, + fallbackReason: templateResolution.evidence.fallbackReason + }); const prompt = this.buildPrompt( question, selection, templateResolution.templateOverlay, - semanticIntent + semanticIntent, + smartDefaults.promptBlock ); const completion = await this.providerRouter.generate(prompt, selection); return this.finalizeWithSemanticGuardrails({ @@ -115,7 +152,8 @@ export class SqlGenerationService { prompt, completion, templateOverlay: templateResolution.templateOverlay, - promptTemplate: templateResolution.evidence + promptTemplate: templateResolution.evidence, + smartDefaults: smartDefaults.evidence }); } @@ -130,23 +168,50 @@ export class SqlGenerationService { const templateResolution = await this.resolvePromptTemplate(selection); const semanticIntent = this.resolveSemanticIntent( question, - selection?.semanticIntent + selection?.semanticIntent, + selection?.semanticPlan ); + const smartDefaults = this.smartDefaultsService.resolve({ + promptTemplate: templateResolution.evidence, + fallbackReason: templateResolution.evidence.fallbackReason + }); const prompt = this.buildPrompt( question, selection, templateResolution.templateOverlay, - semanticIntent + semanticIntent, + smartDefaults.promptBlock ); + const immediateShortcut = + this.buildGroupedCountProportionShortcut(question, selection) ?? + this.buildSimpleCountShortcut(question, selection); let completion: LlmDraft; - try { - completion = await this.providerRouter.stream(prompt, selection, options); - } catch (error) { - if (!this.shouldRetryAsNonStream(error)) { - throw error; + if (immediateShortcut) { + completion = this.buildSemanticShortcutCompletion({ + prompt, + shortcut: immediateShortcut, + summary: "已根据语义计划与已选证据生成保守只读 SQL。" + }); + } else { + try { + completion = await this.providerRouter.stream(prompt, selection, options); + } catch (error) { + if (!this.shouldRetryAsNonStream(error)) { + const shortcutCompletion = this.buildRecoverableStreamFailureShortcut({ + question, + selection, + semanticIntent, + prompt, + error + }); + if (!shortcutCompletion) { + throw error; + } + completion = shortcutCompletion; + } else { + completion = await this.providerRouter.generate(prompt, selection); + } } - - completion = await this.providerRouter.generate(prompt, selection); } return this.finalizeWithSemanticGuardrails({ question, @@ -155,8 +220,177 @@ export class SqlGenerationService { prompt, completion, templateOverlay: templateResolution.templateOverlay, - promptTemplate: templateResolution.evidence + promptTemplate: templateResolution.evidence, + smartDefaults: smartDefaults.evidence + }); + } + + buildStructuredArtifact(input: { + draft: SqlDraft; + datasourceType?: DatasourceType; + cause: SqlGenerationCause; + retryReason?: string; + correctionGrounding?: SqlCorrectionGroundingV1; + }): StructuredSqlGenerationArtifact { + const references = this.extractSqlReferences(input.draft.sql); + const evidenceRefs = this.unique(input.draft.semanticPlan?.evidenceRefs ?? []); + const obligationClaims = this.buildObligationClaims({ + sql: input.draft.sql, + references, + semanticPlan: input.draft.semanticPlan + }); + const provider = + input.draft.provider || input.draft.model || input.draft.modelCatalogId + ? { + provider: input.draft.provider, + model: input.draft.model + } + : undefined; + + return { + sql: input.draft.sql, + assumptions: input.draft.explanation + ? [input.draft.explanation] + : undefined, + usedTables: Array.from(references.tables), + usedColumns: this.unique([ + ...Array.from(references.tableColumns), + ...Array.from(references.columns) + ]), + evidenceRefs, + cause: input.cause, + dialect: input.datasourceType ?? "sqlite", + provider, + promptTemplate: input.draft.promptTemplate, + smartDefaults: input.draft.smartDefaults, + retryReason: input.retryReason?.trim() || undefined, + coverage: input.draft.coverage, + correctionGrounding: input.correctionGrounding, + claimedObligationIds: obligationClaims.claimedObligationIds, + unsupportedClaims: obligationClaims.unsupportedClaims, + ledgerSnapshotId: input.draft.semanticPlan?.planLedger?.snapshotId ?? input.draft.semanticPlan?.snapshotId + }; + } + + private buildObligationClaims(input: { + sql: string; + references: { + tables: Set; + columns: Set; + tableColumns: Set; + }; + semanticPlan?: SemanticPlanV1; + }): { + claimedObligationIds?: string[]; + unsupportedClaims?: SqlGenerationArtifactV1["unsupportedClaims"]; + } { + const obligations = input.semanticPlan?.planLedger?.obligations ?? []; + const claimedObligationIds = obligations + .filter((obligation) => this.isObligationClaimed(obligation, input)) + .map((obligation) => obligation.id); + const unsupportedClaims = this.findUnsupportedClaims({ + references: input.references, + semanticPlan: input.semanticPlan, + obligations }); + return { + claimedObligationIds: + claimedObligationIds.length > 0 ? this.unique(claimedObligationIds) : undefined, + unsupportedClaims: unsupportedClaims.length > 0 ? unsupportedClaims : undefined + }; + } + + private isObligationClaimed( + obligation: SemanticPlanLedgerObligationV1, + input: { + sql: string; + references: { + tables: Set; + columns: Set; + tableColumns: Set; + }; + } + ): boolean { + const subject = obligation.subject ? this.normalizeQualifiedIdentifier(obligation.subject) : undefined; + const unqualifiedSubject = obligation.subject ? this.normalizeIdentifier(obligation.subject) : undefined; + if (!subject && !unqualifiedSubject) { + return false; + } + if (obligation.kind === "table" || obligation.kind === "forbidden_table") { + return Boolean(unqualifiedSubject && input.references.tables.has(unqualifiedSubject)); + } + if (obligation.kind === "column") { + return Boolean( + (subject && input.references.tableColumns.has(subject)) || + (unqualifiedSubject && input.references.columns.has(unqualifiedSubject)) + ); + } + if (obligation.kind === "metric") { + return Boolean( + unqualifiedSubject && + (new RegExp(`\\b${this.escapeRegex(unqualifiedSubject)}\\b`, "i").test(input.sql) || + /\b(count|sum|avg|min|max)\s*\(/i.test(input.sql)) + ); + } + if (obligation.kind === "time_grain") { + return /\b(date_trunc|strftime|extract|group\s+by|where)\b/i.test(input.sql); + } + if (obligation.kind === "filter") { + return /\bwhere\b/i.test(input.sql); + } + if (obligation.kind === "join_path") { + return /\bjoin\b/i.test(input.sql); + } + return false; + } + + private findUnsupportedClaims(input: { + references: { + tables: Set; + columns: Set; + tableColumns: Set; + }; + semanticPlan?: SemanticPlanV1; + obligations: SemanticPlanLedgerObligationV1[]; + }): NonNullable { + const supportedTables = new Set([ + ...this.normalizeList(input.semanticPlan?.selectedTables ?? []), + ...input.obligations + .filter((obligation) => obligation.kind === "table") + .map((obligation) => this.normalizeIdentifier(obligation.subject)) + .filter((value): value is string => Boolean(value)) + ]); + const supportedColumns = new Set([ + ...this.normalizeList(input.semanticPlan?.selectedColumns ?? []), + ...input.obligations + .filter((obligation) => obligation.kind === "column") + .map((obligation) => this.normalizeQualifiedIdentifier(obligation.subject)) + .filter((value): value is string => Boolean(value)) + ]); + const unsupported: NonNullable = []; + for (const table of input.references.tables) { + if (supportedTables.size > 0 && !supportedTables.has(table)) { + unsupported.push({ + kind: "table", + value: table, + reasonCode: "table_not_in_ledger" + }); + } + } + for (const column of input.references.tableColumns) { + if (supportedColumns.size > 0 && !supportedColumns.has(column)) { + unsupported.push({ + kind: "column", + value: column, + reasonCode: "column_not_in_ledger" + }); + } + } + return unsupported; + } + + private escapeRegex(value: string): string { + return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); } private shouldRetryAsNonStream(error: unknown): boolean { @@ -170,13 +404,226 @@ export class SqlGenerationService { ); } + private buildRecoverableStreamFailureShortcut(input: { + question: string; + selection: SqlGenerationSelection | undefined; + semanticIntent: SqlSemanticIntent; + prompt: LlmGatewayPrompt; + error: unknown; + }): LlmDraft | undefined { + if ( + input.semanticIntent !== "count" || + !this.isRecoverableProviderStreamFailure(input.error) + ) { + return undefined; + } + + const shortcut = this.buildGroupedCountProportionShortcut( + input.question, + input.selection + ) ?? this.buildSimpleCountShortcut(input.question, input.selection); + if (!shortcut) { + return undefined; + } + + return this.buildSemanticShortcutCompletion({ + prompt: input.prompt, + shortcut, + summary: + "上游模型流式响应不可用，已根据语义计划与已选证据生成保守只读 SQL。" + }); + } + + private buildSemanticShortcutCompletion(input: { + prompt: LlmGatewayPrompt; + shortcut: { sql: string; model: string }; + summary: string; + }): LlmDraft { + return { + provider: "semantic-shortcut", + model: input.shortcut.model, + rawText: [ + input.summary, + "```sql", + input.shortcut.sql.replace(/;+\s*$/, ""), + "```" + ].join("\n"), + prompt: input.prompt + }; + } + + private isRecoverableProviderStreamFailure(error: unknown): boolean { + if (!(error instanceof DomainError) || error.code !== "LLM_REQUEST_FAILED") { + return false; + } + return /(流式请求失败|invalid json response|aborted due to timeout|timeout)/i.test( + error.message + ); + } + + private buildGroupedCountProportionShortcut( + question: string, + selection: SqlGenerationSelection | undefined + ): { sql: string; model: string } | undefined { + const selectedTables = this.resolveShortcutSelectedTables(selection?.semanticPlan); + if (!selectedTables || selectedTables.length !== 1) { + return undefined; + } + if (!/(比例|占比|分布|各|每|多少种|几种|方式|类型|类别|渠道|状态)/i.test(question)) { + return undefined; + } + + const table = selectedTables[0]; + const groupColumn = this.resolveGroupedCountColumn({ + question, + table, + columns: selection?.semanticPlan?.selectedColumns ?? [] + }); + if (!groupColumn) { + return undefined; + } + + return { + model: "grouped-count-proportion-v1", + sql: [ + `SELECT ${groupColumn} AS group_value,`, + " COUNT(*) AS item_count,", + " ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER (), 2) AS item_percentage", + `FROM ${table}`, + `GROUP BY ${groupColumn}`, + "ORDER BY item_count DESC;" + ].join("\n") + }; + } + + private buildSimpleCountShortcut( + question: string, + selection: SqlGenerationSelection | undefined + ): { sql: string; model: string } | undefined { + const selectedTables = this.resolveShortcutSelectedTables(selection?.semanticPlan); + if (!selectedTables || selectedTables.length !== 1) { + return undefined; + } + if (/(比例|占比|分布|各|每|多少种|几种|方式|类型|类别|渠道|状态)/i.test(question)) { + return undefined; + } + + return { + model: "simple-count-v1", + sql: `SELECT COUNT(*) AS total_count FROM ${selectedTables[0]};` + }; + } + + private resolveShortcutSelectedTables( + semanticPlan: SemanticPlanV1 | undefined + ): string[] | undefined { + if (!semanticPlan || this.resolveSemanticPlanRouteKind(semanticPlan) !== "text_to_sql") { + return undefined; + } + const selectedTables = this.unique( + semanticPlan.selectedTables + .map((item) => this.normalizeIdentifier(item)) + .filter((item): item is string => Boolean(item)) + ); + if (selectedTables.some((table) => !this.isSafeSqlIdentifier(table))) { + return undefined; + } + return selectedTables; + } + + private resolveGroupedCountColumn(input: { + question: string; + table: string; + columns: string[]; + }): string | undefined { + const normalizedQuestion = input.question.toLowerCase(); + const candidates = this.unique( + input.columns + .map((column) => this.normalizeQualifiedIdentifier(column)) + .filter((column): column is string => Boolean(column)) + .map((column) => { + const [tableName, columnName] = column.includes(".") + ? column.split(".") + : [input.table, column]; + if (tableName !== input.table || !columnName) { + return undefined; + } + return columnName; + }) + .filter((column): column is string => Boolean(column)) + .filter((column) => this.isSafeSqlIdentifier(column)) + ); + + const scored = candidates + .map((column, index) => ({ + column, + index, + score: this.scoreGroupedCountColumn(normalizedQuestion, column) + })) + .filter((item) => item.score > 0) + .sort((left, right) => right.score - left.score || left.index - right.index); + + return scored[0]?.column; + } + + private scoreGroupedCountColumn(question: string, column: string): number { + const normalizedColumn = column.toLowerCase(); + let score = 0; + const hints: Array<{ pattern: RegExp; columns: string[]; weight: number }> = [ + { + pattern: /(支付方式|支付渠道|付款方式|方式|渠道|payment|method)/i, + columns: ["method"], + weight: 8 + }, + { pattern: /(状态|status)/i, columns: ["status"], weight: 8 }, + { pattern: /(类型|type)/i, columns: ["type"], weight: 8 }, + { + pattern: /(分类|类目|类别|category)/i, + columns: ["category", "category_id"], + weight: 8 + } + ]; + + for (const hint of hints) { + if (hint.pattern.test(question) && hint.columns.includes(normalizedColumn)) { + score += hint.weight; + } + } + + if (/^(method|status|type|category)$/.test(normalizedColumn)) { + score += 3; + } + if (/(多少种|几种|分布|比例|占比)/i.test(question)) { + score += /(_id|id|amount|price|total|count|created_at|updated_at|paid_at)$/i.test( + normalizedColumn + ) + ? -4 + : 1; + } + return score; + } + + private isSafeSqlIdentifier(value: string): boolean { + return /^[a-zA-Z_][\w$]*$/.test(value); + } + private buildPrompt( question: string, selection: SqlGenerationSelection | undefined, templateOverlay: string | undefined, semanticIntent: SqlSemanticIntent, + smartDefaults: + | { evidence: Text2SqlV2SmartDefaultsEvidenceV1; promptBlock: string } + | Text2SqlV2SmartDefaultsEvidenceV1 + | string, retryReason?: string ): LlmGatewayPrompt { + const smartDefaultsBlock = + typeof smartDefaults === "string" + ? smartDefaults + : "promptBlock" in smartDefaults + ? smartDefaults.promptBlock + : this.smartDefaultsService.resolve().promptBlock; return this.promptBuilder.build( question, selection?.datasourceType, @@ -187,7 +634,10 @@ export class SqlGenerationService { intent: semanticIntent, retryReason }, - semanticContextPack: selection?.semanticContextPack + semanticContextPack: selection?.semanticContextPack, + semanticPlan: selection?.semanticPlan, + correctionGrounding: selection?.correctionGrounding, + smartDefaultsBlock } ); } @@ -206,7 +656,9 @@ export class SqlGenerationService { completion: LlmDraft; templateOverlay?: string; promptTemplate: PromptTemplateTraceEvidence; + smartDefaults: Text2SqlV2SmartDefaultsEvidenceV1; }): Promise { + this.assertSemanticPlan(input.selection?.semanticPlan); let retryCount = 0; let prompt = input.prompt; let completion = input.completion; @@ -235,6 +687,21 @@ export class SqlGenerationService { } ); } + const semanticPlanCoverage = this.validateSemanticPlanCoverage({ + sql: extracted.sql, + semanticPlan: input.selection?.semanticPlan + }); + if (!semanticPlanCoverage.valid) { + throw new DomainError( + "LLM_SQL_PLAN_COVERAGE_FAILED", + "SQL 超出了语义计划允许范围，已阻止该输出。", + 422, + { + reason: semanticPlanCoverage.reason, + missingObjects: semanticPlanCoverage.missingObjects + } + ); + } return { provider: completion.provider, model: completion.model, @@ -244,9 +711,11 @@ export class SqlGenerationService { rawText: completion.rawText, prompt, promptTemplate: input.promptTemplate, + smartDefaults: input.smartDefaults, retryCount, semanticIntent: input.semanticIntent, - coverage: coverage.evidence + coverage: coverage.evidence, + semanticPlan: input.selection?.semanticPlan }; } @@ -269,6 +738,7 @@ export class SqlGenerationService { input.selection, input.templateOverlay, input.semanticIntent, + input.smartDefaults, validation.reason ); completion = await this.providerRouter.generate(prompt, input.selection); @@ -285,6 +755,7 @@ export class SqlGenerationService { input.selection, input.templateOverlay, input.semanticIntent, + input.smartDefaults, "no executable SQL was extracted from the previous output" ); completion = await this.providerRouter.generate(prompt, input.selection); @@ -294,8 +765,13 @@ export class SqlGenerationService { private resolveSemanticIntent( question: string, - explicitIntent?: SqlSemanticIntent + explicitIntent?: SqlSemanticIntent, + semanticPlan?: SemanticPlanV1 ): SqlSemanticIntent { + const routeKind = this.resolveSemanticPlanRouteKind(semanticPlan); + if (routeKind === "metadata") { + return "metadata"; + } if (explicitIntent && explicitIntent !== "general") { return explicitIntent; } @@ -308,6 +784,33 @@ export class SqlGenerationService { return explicitIntent ?? "general"; } + private assertSemanticPlan(semanticPlan: SemanticPlanV1 | undefined): void { + if (!semanticPlan) { + return; + } + const routeKind = this.resolveSemanticPlanRouteKind(semanticPlan); + if (semanticPlan.route === "reject" || routeKind === "fail_closed") { + throw new DomainError( + "SEMANTIC_PLAN_REJECTED", + "语义计划路由为 reject，已终止 SQL 生成。", + 422, + { + semanticPlan + } + ); + } + if (semanticPlan.route === "clarify" || routeKind === "clarify") { + throw new DomainError( + "SEMANTIC_PLAN_REQUIRES_CLARIFICATION", + "语义计划要求先澄清问题，已终止 SQL 生成。", + 422, + { + semanticPlan + } + ); + } + } + private validateSemanticIntent( intent: SqlSemanticIntent, sql: string @@ -460,6 +963,150 @@ export class SqlGenerationService { }; } + private validateSemanticPlanCoverage(input: { + sql: string; + semanticPlan: SemanticPlanV1 | undefined; + }): { + valid: boolean; + reason?: string; + missingObjects: string[]; + } { + const semanticPlan = input.semanticPlan; + if (!semanticPlan) { + return { + valid: true, + missingObjects: [] + }; + } + const routeKind = this.resolveSemanticPlanRouteKind(semanticPlan); + if (routeKind === "metadata" || routeKind === "general") { + return { + valid: true, + missingObjects: [] + }; + } + if (routeKind === "clarify") { + return { + valid: false, + reason: "semantic plan requires clarification before SQL generation", + missingObjects: [] + }; + } + if (routeKind === "fail_closed") { + return { + valid: false, + reason: "semantic plan is in fail-closed route", + missingObjects: [] + }; + } + + const references = this.extractSqlReferences(input.sql); + const allowedTables = this.unique( + (semanticPlan.allowedTables ?? []) + .map((item) => this.normalizeIdentifier(item)) + .filter((item): item is string => Boolean(item)) + ); + const forbiddenTables = new Set( + (semanticPlan.forbiddenTables ?? []) + .map((item) => this.normalizeIdentifier(item)) + .filter((item): item is string => Boolean(item)) + ); + const selectedTables = this.unique( + semanticPlan.selectedTables + .map((item) => this.normalizeIdentifier(item)) + .filter((item): item is string => Boolean(item)) + ); + const selectedColumns = new Set( + (semanticPlan.selectedColumns ?? []) + .map((item) => this.normalizeQualifiedIdentifier(item)) + .filter((item): item is string => Boolean(item)) + ); + const selectedColumnNames = new Set( + (semanticPlan.selectedColumns ?? []) + .map((item) => { + const normalized = this.normalizeQualifiedIdentifier(item); + if (!normalized) { + return undefined; + } + return normalized.split(".").at(-1); + }) + .filter((item): item is string => Boolean(item)) + ); + + const missingObjects = this.unique([ + ...Array.from(references.tables) + .filter((table) => forbiddenTables.has(table)) + .map((table) => `table:${table}`), + ...(allowedTables.length > 0 + ? Array.from(references.tables) + .filter((table) => !allowedTables.includes(table)) + .map((table) => `table:${table}`) + : []), + ...(selectedTables.length > 0 + ? Array.from(references.tables) + .filter((table) => !selectedTables.includes(table)) + .map((table) => `table:${table}`) + : []), + ...(selectedColumns.size > 0 + ? Array.from(references.tableColumns) + .filter((tableColumn) => { + if (selectedColumns.has(tableColumn)) { + return false; + } + const columnName = tableColumn.split(".").at(-1); + if (!columnName) { + return true; + } + return !selectedColumnNames.has(columnName); + }) + .map((tableColumn) => `column:${tableColumn}`) + : []) + ]); + + if (missingObjects.length > 0) { + return { + valid: false, + reason: `semantic plan coverage missing: ${missingObjects.join(", ")}`, + missingObjects + }; + } + + return { + valid: true, + missingObjects: [] + }; + } + + private resolveSemanticPlanRouteKind( + semanticPlan: SemanticPlanV1 | undefined + ): "text_to_sql" | "metadata" | "general" | "clarify" | "fail_closed" { + if (!semanticPlan) { + return "text_to_sql"; + } + const routeFilter = semanticPlan.filters?.find((item) => + item.startsWith("route_kind:") + ); + if (routeFilter) { + const value = routeFilter.slice("route_kind:".length).trim(); + if ( + value === "text_to_sql" || + value === "metadata" || + value === "general" || + value === "clarify" || + value === "fail_closed" + ) { + return value; + } + } + if (semanticPlan.route === "clarify") { + return "clarify"; + } + if (semanticPlan.route === "reject") { + return "fail_closed"; + } + return "text_to_sql"; + } + private buildCoverageEvidenceIndex(selection?: SqlGenerationSelection): { hasEvidence: boolean; tables: Set; @@ -735,6 +1382,36 @@ export class SqlGenerationService { return token?.toLowerCase(); } + private normalizeQualifiedIdentifier(value: string | undefined): string | undefined { + if (!value) { + return undefined; + } + const normalized = value + .trim() + .replace(/^[`"'[\]]+|[`"'[\]]+$/g, "") + .replace(/\s+/g, "") + .toLowerCase(); + if (!normalized) { + return undefined; + } + if (!normalized.includes(".")) { + return normalized; + } + const [table, column] = normalized.split("."); + if (!table || !column) { + return undefined; + } + return `${table}.${column}`; + } + + private normalizeList(values: string[]): string[] { + return this.unique( + values + .map((value) => this.normalizeQualifiedIdentifier(value)) + .filter((value): value is string => Boolean(value)) + ); + } + private hasTableColumnFallback( tableColumns: Set, column: string diff --git a/apps/backend/src/modules/conversation/agent/sql/sql-prompt.builder.ts b/apps/backend/src/modules/conversation/agent/sql/sql-prompt.builder.ts index 79b9dbc..1d9510b 100644 --- a/apps/backend/src/modules/conversation/agent/sql/sql-prompt.builder.ts +++ b/apps/backend/src/modules/conversation/agent/sql/sql-prompt.builder.ts @@ -1,5 +1,9 @@ import { Injectable } from "@nestjs/common"; -import type { DatasourceType } from "@text2sql/shared-types"; +import type { + DatasourceType, + SemanticPlanV1, + SqlCorrectionGroundingV1 +} from "@text2sql/shared-types"; import type { LlmGatewayPrompt } from "../../../llm/llm-gateway.interface"; import type { RetrievedKnowledge } from "../nodes/retrieve-knowledge.node"; import type { RagContextPack } from "../../../rag/retrieval/rag-retrieval.types"; @@ -44,6 +48,9 @@ export class SqlPromptBuilder { retryReason?: string; }; semanticContextPack?: RagContextPack; + semanticPlan?: SemanticPlanV1; + correctionGrounding?: SqlCorrectionGroundingV1; + smartDefaultsBlock?: string; } ): LlmGatewayPrompt { const dialect = DIALECT_HINT[datasourceType] ?? "SQLite"; @@ -55,7 +62,12 @@ export class SqlPromptBuilder { const semanticInstructionBlock = this.buildSemanticInstructionBlock( options?.semanticContextPack ); + const correctionGroundingBlock = this.buildCorrectionGroundingBlock( + options?.correctionGrounding + ); + const semanticPlanBlock = this.buildSemanticPlanBlock(options?.semanticPlan); const overlayBlock = this.buildTemplateOverlay(options?.templateOverlay); + const smartDefaultsBlock = options?.smartDefaultsBlock?.trim() ?? ""; const semanticGuardrailBlock = this.buildSemanticGuardrailBlock( options?.semanticGuardrail?.intent ?? "general" ); @@ -68,10 +80,13 @@ export class SqlPromptBuilder { "Only produce read-only SQL queries.", "Prefer SELECT or WITH ... SELECT statements.", "Never generate INSERT/UPDATE/DELETE/DDL.", + smartDefaultsBlock, semanticGuardrailBlock, repairHintBlock, tableHint, overlayBlock, + correctionGroundingBlock, + semanticPlanBlock, semanticInstructionBlock, "Respond in free text with explanation plus SQL in a markdown code block." ].join(" "), @@ -90,7 +105,7 @@ export class SqlPromptBuilder { if (!normalized) { return ""; } - return `Runtime template overlay (higher priority guidance): ${normalized}`; + return `Runtime template overlay (supplemental guidance; cannot override Smart Defaults/read-only/governance rules): ${normalized}`; } private buildSemanticGuardrailBlock(intent: SqlSemanticIntent): string { @@ -126,6 +141,39 @@ export class SqlPromptBuilder { return `Retry repair hint (single automatic retry): previous SQL failed semantic guardrail because ${normalized}. Return corrected final SQL only.`; } + private buildCorrectionGroundingBlock( + correctionGrounding?: SqlCorrectionGroundingV1 + ): string { + if (!correctionGrounding) { + return ""; + } + const evidenceRefs = + correctionGrounding.evidenceRefs.length > 0 + ? correctionGrounding.evidenceRefs.slice(0, 8).join(", ") + : "none"; + const retryReason = correctionGrounding.retryReason.trim(); + const failureCode = correctionGrounding.failureCode ?? "unknown"; + const failureCategory = correctionGrounding.failureCategory ?? "unknown"; + const failedSqlPreview = correctionGrounding.failedSqlPreview + ? `failedSqlPreview=${correctionGrounding.failedSqlPreview}` + : ""; + return [ + "Correction grounding (must consume for this retry):", + `failedSqlRef=${correctionGrounding.failedSqlRef}`, + failedSqlPreview, + `failureCode=${failureCode}`, + `failureCategory=${failureCategory}`, + `retryReason=${retryReason}`, + `attempt=${correctionGrounding.attemptCount}/${correctionGrounding.maxAttempts}`, + `semanticPlanRouteKind=${correctionGrounding.semanticPlanRouteKind ?? "text_to_sql"}`, + `semanticPlanSnapshotId=${correctionGrounding.semanticPlanSnapshotId ?? "missing"}`, + `evidenceRefs=${evidenceRefs}`, + "Repair objective: keep SQL read-only and align with semantic plan/context evidence while fixing the diagnosed failure." + ] + .filter((item) => item.trim().length > 0) + .join(" "); + } + private buildContextBlock(selectedContext?: RagRetrievalChunkPayload[]): string { if (!selectedContext || selectedContext.length === 0) { return ""; @@ -515,4 +563,139 @@ export class SqlPromptBuilder { ...lines ].join(" "); } + + private buildSemanticPlanBlock(plan?: SemanticPlanV1): string { + if (!plan) { + return ""; + } + const routeKind = this.readRouteKind(plan); + const route = `route=${plan.route}`; + const routeKindLine = `routeKind=${routeKind}`; + const confidence = `confidence=${plan.confidence.toFixed(2)}`; + const standaloneQuestion = `standaloneQuestion=${plan.standaloneQuestion}`; + const selectedTables = + plan.selectedTables.length > 0 + ? `selectedTables=${plan.selectedTables.slice(0, 12).join(", ")}` + : "selectedTables=none"; + const selectedColumns = + plan.selectedColumns.length > 0 + ? `selectedColumns=${plan.selectedColumns.slice(0, 16).join(", ")}` + : "selectedColumns=none"; + const allowedTables = + plan.allowedTables && plan.allowedTables.length > 0 + ? `allowedTables=${plan.allowedTables.slice(0, 12).join(", ")}` + : ""; + const forbiddenTables = + plan.forbiddenTables && plan.forbiddenTables.length > 0 + ? `forbiddenTables=${plan.forbiddenTables.slice(0, 12).join(", ")}` + : ""; + const metrics = + plan.metrics && plan.metrics.length > 0 + ? `metrics=${plan.metrics.slice(0, 8).join(", ")}` + : ""; + const grain = plan.grain ? `grain=${plan.grain}` : ""; + const filters = + plan.filters && plan.filters.length > 0 + ? `filters=${plan.filters.slice(0, 10).join(", ")}` + : ""; + const joinPath = + plan.joinPath && plan.joinPath.length > 0 + ? `joinPath=${plan.joinPath.slice(0, 10).join(" | ")}` + : ""; + const evidenceRefs = + plan.evidenceRefs.length > 0 + ? `evidenceRefs=${plan.evidenceRefs.slice(0, 10).join(", ")}` + : "evidenceRefs=none"; + const coverageGaps = + plan.coverageGaps && plan.coverageGaps.length > 0 + ? `coverageGaps=${plan.coverageGaps + .slice(0, 6) + .map((gap) => `${gap.subjectKind}:${gap.reasonCode}`) + .join(" | ")}` + : ""; + const snapshotId = plan.snapshotId ? `snapshotId=${plan.snapshotId}` : ""; + const ledgerSummary = plan.planLedger?.summary + ? `ledgerSummary=total:${plan.planLedger.summary.total},hardBlockers:${plan.planLedger.summary.hardBlockerCount},warnings:${plan.planLedger.summary.warningCount},failed:${plan.planLedger.summary.failedCount ?? 0}` + : ""; + const ledgerGate = + plan.planLedger?.summary.failedHardBlockerIds && + plan.planLedger.summary.failedHardBlockerIds.length > 0 + ? `ledgerGate=block(${plan.planLedger.summary.failedHardBlockerIds.slice(0, 6).join(", ")})` + : plan.planLedger?.summary.warningIds && + plan.planLedger.summary.warningIds.length > 0 + ? `ledgerGate=warning(${plan.planLedger.summary.warningIds.slice(0, 6).join(", ")})` + : plan.planLedger + ? "ledgerGate=pass" + : ""; + const ledgerObligations = + plan.planLedger?.obligations && plan.planLedger.obligations.length > 0 + ? `ledgerObligations=${plan.planLedger.obligations + .slice(0, 12) + .map( + (obligation) => + `${obligation.id}:${obligation.kind}:${obligation.subject ?? "n/a"}:${obligation.criticality}:${obligation.status}` + ) + .join(" | ")}` + : ""; + const routeGuardrail = + routeKind === "metadata" + ? "routeGuardrail=metadata_only" + : routeKind === "general" + ? "routeGuardrail=general_non_sql_preferred" + : routeKind === "clarify" + ? "routeGuardrail=clarification_required" + : routeKind === "fail_closed" + ? "routeGuardrail=fail_closed_no_sql" + : "routeGuardrail=text_to_sql"; + return [ + "Typed semantic plan (must follow):", + route, + routeKindLine, + confidence, + standaloneQuestion, + selectedTables, + selectedColumns, + metrics, + grain, + filters, + joinPath, + allowedTables, + forbiddenTables, + evidenceRefs, + coverageGaps, + snapshotId, + ledgerSummary, + ledgerGate, + ledgerObligations, + "Execution guardrail: stay within selectedTables/selectedColumns and do not invent out-of-plan joins or columns.", + routeGuardrail + ] + .filter((item) => item.trim().length > 0) + .join(" "); + } + + private readRouteKind( + plan: SemanticPlanV1 + ): "text_to_sql" | "metadata" | "general" | "clarify" | "fail_closed" { + const routeFilter = plan.filters?.find((item) => item.startsWith("route_kind:")); + if (routeFilter) { + const value = routeFilter.slice("route_kind:".length).trim(); + if ( + value === "text_to_sql" || + value === "metadata" || + value === "general" || + value === "clarify" || + value === "fail_closed" + ) { + return value; + } + } + if (plan.route === "clarify") { + return "clarify"; + } + if (plan.route === "reject") { + return "fail_closed"; + } + return "text_to_sql"; + } } diff --git a/apps/backend/src/modules/conversation/agent/sql/tools/sql-readonly.tool.ts b/apps/backend/src/modules/conversation/agent/sql/tools/sql-readonly.tool.ts index f57a27a..5189a13 100644 --- a/apps/backend/src/modules/conversation/agent/sql/tools/sql-readonly.tool.ts +++ b/apps/backend/src/modules/conversation/agent/sql/tools/sql-readonly.tool.ts @@ -15,6 +15,9 @@ const sqlReadonlyInputSchema = z.object({ limit: z.number().int().min(1).max(200).optional() }); +const METADATA_INTROSPECTION_SQL_REGEX = + /\bsqlite_master\b|\bsqlite_schema\b|\binformation_schema\b|\bpg_catalog\b|\bpragma\b|\bshow\s+tables\b|\bdescribe\b/i; + @Injectable() export class SqlReadonlyTool { constructor( @@ -27,10 +30,20 @@ export class SqlReadonlyTool { accessContext?: SqlTableAccessContext; }): LlmGatewayToolDefinition { return { - description: `Execute a read-only SQL query against datasource ${context.datasource.id} (${context.datasource.type}).`, + description: `Execute a read-only business-data SQL query against datasource ${context.datasource.id} (${context.datasource.type}). Do not use this tool for schema metadata introspection or system tables.`, inputSchema: sqlReadonlyInputSchema, execute: async (toolInput) => { const parsed = sqlReadonlyInputSchema.parse(toolInput); + if (METADATA_INTROSPECTION_SQL_REGEX.test(parsed.sql)) { + throw new DomainError( + "LLM_TOOL_METADATA_INTROSPECTION_FORBIDDEN", + "工具调用不允许查询 schema 系统表；请使用已提供的业务表结构与语义上下文生成 SQL。", + 403, + { + datasourceId: context.datasource.id + } + ); + } if (context.datasource.status !== "available") { throw new DomainError( "DATASOURCE_UNAVAILABLE", diff --git a/apps/backend/src/modules/conversation/agent/sql/tools/sql-safety.guard.ts b/apps/backend/src/modules/conversation/agent/sql/tools/sql-safety.guard.ts index cef097b..831767a 100644 --- a/apps/backend/src/modules/conversation/agent/sql/tools/sql-safety.guard.ts +++ b/apps/backend/src/modules/conversation/agent/sql/tools/sql-safety.guard.ts @@ -112,6 +112,8 @@ export class SqlSafetyGuard { decision.reason ?? "Tool SQL 未通过只读安全校验。", 400, { + terminal: true, + correctable: false, mode: decision.mode, riskLevel: decision.riskLevel, riskTags: decision.riskTags diff --git a/apps/backend/src/modules/conversation/application/workflow/text2sql-workflow-runner.service.ts b/apps/backend/src/modules/conversation/application/workflow/text2sql-workflow-runner.service.ts new file mode 100644 index 0000000..f152706 --- /dev/null +++ b/apps/backend/src/modules/conversation/application/workflow/text2sql-workflow-runner.service.ts @@ -0,0 +1,204 @@ +import { Injectable } from "@nestjs/common"; +import type { + ChatStreamEvent, + ContextEnvelope, + SqlRun +} from "@text2sql/shared-types"; +import { DomainError } from "../../../../common/domain-error"; +import { DatasourceRegistryService } from "../../../governance/datasource/datasource-registry.service"; +import type { ChatPolicyActorInput } from "../../chat/application/shared/chat-policy-guard.service"; +import { Text2SqlStreamEventMapper } from "../../text2sql/stream/text2sql-stream-event.mapper"; +import { EnrichDeliveryStage } from "../../text2sql/stages/enrich-delivery.stage"; +import { PersistRunStage } from "../../text2sql/stages/persist-run.stage"; +import { PostRunHooksStage } from "../../text2sql/stages/post-run-hooks.stage"; +import { PrepareRunStage } from "../../text2sql/stages/prepare-run.stage"; +import { RunV2LangGraphStage } from "../../runtime/stages/run-v2-langgraph.stage"; + +export interface Text2SqlWorkflowInput { + sessionId: string; + message: string; + requestId?: string; + contextEnvelope?: ContextEnvelope; + actor?: ChatPolicyActorInput; +} + +export interface Text2SqlStreamWorkflowInput extends Text2SqlWorkflowInput { + onEvent: (event: ChatStreamEvent) => Promise | void; +} + +@Injectable() +export class Text2SQLWorkflowRunner { + private readonly syncRoute = "/api/v1/sessions/:sessionId/messages"; + private readonly streamRoute = "/api/v1/sessions/:sessionId/messages/stream"; + + constructor( + private readonly datasourceRegistry: DatasourceRegistryService, + private readonly prepareRunStage: PrepareRunStage, + private readonly runV2LangGraphStage: RunV2LangGraphStage, + private readonly enrichDeliveryStage: EnrichDeliveryStage, + private readonly persistRunStage: PersistRunStage, + private readonly postRunHooksStage: PostRunHooksStage, + private readonly streamEventMapper: Text2SqlStreamEventMapper + ) {} + + async runSync(input: Text2SqlWorkflowInput): Promise { + const prepared = await this.prepareRunStage.run(input); + const run = await this.runV2LangGraphStage.runSync(prepared, this.syncRoute); + return this.finalizeSuccessRun(prepared, run); + } + + async runStream(input: Text2SqlStreamWorkflowInput): Promise { + const prepared = await this.prepareRunStage.run(input); + + const emit = async (type: ChatStreamEvent["type"], data: ChatStreamEvent["data"]) => { + await input.onEvent( + this.streamEventMapper.createEnvelope({ + type, + data, + runId: prepared.runId, + sessionId: prepared.session.id + }) + ); + }; + + await emit("start", { + requestId: prepared.requestId ?? null + }); + + const toolCalls: NonNullable["toolCalls"]> = []; + let stepSequence = 0; + + try { + const run = await this.runV2LangGraphStage.runStream(prepared, this.streamRoute, { + onLlmEvent: async (event) => { + const mappedEvent = this.streamEventMapper.mapLlmEvent(event); + if (mappedEvent.traceToolCall) { + toolCalls.push(mappedEvent.traceToolCall); + } + await emit(mappedEvent.type, mappedEvent.data); + }, + onStep: async ({ step }) => { + const mappedEvent = this.streamEventMapper.mapStepEvent({ + step, + runId: prepared.runId, + lastSequence: stepSequence + }); + stepSequence = mappedEvent.nextSequence; + await emit("state", mappedEvent.data); + } + }); + + const finalizedRun = this.applyRejectedFallback(run, prepared.session.datasource); + finalizedRun.trace.streamStatus = finalizedRun.error ? "failed" : "completed"; + finalizedRun.trace.toolCalls = toolCalls; + + const runWithDelivery = await this.enrichDeliveryStage.run(finalizedRun); + if (runWithDelivery.error) { + await emit("error", { + code: + runWithDelivery.status === "rejected" + ? "SQL_READONLY_REJECTED" + : undefined, + message: runWithDelivery.error, + details: null + }); + } + + await emit("finish", { + status: runWithDelivery.status, + rowCount: runWithDelivery.rows?.length ?? 0, + delivery: runWithDelivery.delivery + }); + + await this.persistRunStage.run({ + sessionId: prepared.session.id, + run: runWithDelivery, + userPrimaryPersisted: prepared.userPersistResult.primaryPersisted + }); + await this.postRunHooksStage.run({ + session: prepared.session, + run: runWithDelivery, + requestId: prepared.requestId + }); + return runWithDelivery; + } catch (error) { + const messageText = error instanceof Error ? error.message : String(error); + const run: SqlRun = { + runId: prepared.runId, + sessionId: prepared.session.id, + question: prepared.question, + status: "failed", + provider: prepared.session.modelProvider ?? "unknown", + model: prepared.session.modelName ?? undefined, + error: messageText, + trace: { + runId: prepared.runId, + provider: prepared.session.modelProvider ?? "unknown", + retryCount: 0, + steps: [], + streamStatus: "failed", + toolCalls + }, + llmRaw: null, + createdAt: new Date().toISOString() + }; + + const domainError = error instanceof DomainError ? error : undefined; + await emit("error", { + code: domainError?.code, + message: messageText, + details: (domainError?.details as Record | undefined) ?? null + }); + + const runWithDelivery = await this.enrichDeliveryStage.run(run); + await this.persistRunStage.run({ + sessionId: prepared.session.id, + run: runWithDelivery, + userPrimaryPersisted: prepared.userPersistResult.primaryPersisted + }); + await this.postRunHooksStage.run({ + session: prepared.session, + run: runWithDelivery, + requestId: prepared.requestId + }); + return runWithDelivery; + } + } + + private async finalizeSuccessRun( + prepared: Awaited>, + run: SqlRun + ): Promise { + const finalRun = this.applyRejectedFallback(run, prepared.session.datasource); + const runWithDelivery = await this.enrichDeliveryStage.run(finalRun); + + await this.persistRunStage.run({ + sessionId: prepared.session.id, + run: runWithDelivery, + userPrimaryPersisted: prepared.userPersistResult.primaryPersisted + }); + await this.postRunHooksStage.run({ + session: prepared.session, + run: runWithDelivery, + requestId: prepared.requestId + }); + return runWithDelivery; + } + + private applyRejectedFallback(run: SqlRun, datasource: string): SqlRun { + if (run.status !== "rejected") { + return run; + } + if (!this.datasourceRegistry.shouldFallbackOnReject(datasource)) { + return run; + } + if (run.answer) { + return run; + } + return { + ...run, + answer: + "请求触发了只读安全策略，本次未执行 SQL。你可以改为查询统计口径或时间范围，我会继续协助。" + }; + } +} diff --git a/apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-builder.ts b/apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-builder.ts new file mode 100644 index 0000000..ddf883d --- /dev/null +++ b/apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-builder.ts @@ -0,0 +1,1321 @@ +import { Injectable } from "@nestjs/common"; +import type { + ExecutionTraceStep, + SemanticContextPackV1, + SemanticPlanLedgerSummaryV1, + SemanticPlanV1, + Text2SqlV2ArtifactRefV1, + SqlGenerationArtifactV1, + SqlRun, + Text2SqlV2LoopEvidence, + Text2SqlV2RuntimePlanV1, + Text2SqlV2SmartDefaultsEvidenceV1, + Text2SqlV2TerminationReason, + SqlValidationArtifactV1, + Text2SqlV2FailureSemantic, + Text2SqlV2RunArtifact, + Text2SqlV2StageArtifact, + Text2SqlV2StageName +} from "@text2sql/shared-types"; +import { TEXT2SQL_V2_STAGE_ORDER } from "../contracts/text2sql-v2.types"; + +export interface BuildRunArtifactOptions { + stageArtifacts?: Text2SqlV2StageArtifact[]; + contextPack?: SemanticContextPackV1; + semanticPlan?: SemanticPlanV1; + sqlGeneration?: SqlGenerationArtifactV1; + sqlValidation?: SqlValidationArtifactV1; + planLedger?: SemanticPlanLedgerSummaryV1; + runtimePlan?: Text2SqlV2RuntimePlanV1; + artifactRefs?: Text2SqlV2ArtifactRefV1[]; + smartDefaults?: Text2SqlV2SmartDefaultsEvidenceV1; +} + +@Injectable() +export class Text2SqlV2ArtifactBuilder { + buildRunArtifact( + run: SqlRun, + options?: BuildRunArtifactOptions + ): Text2SqlV2RunArtifact { + const stageArtifacts = this.resolveStageArtifacts(run, options?.stageArtifacts); + + return { + version: "v2", + stageOrder: [...TEXT2SQL_V2_STAGE_ORDER], + stages: stageArtifacts, + contextPack: options?.contextPack ?? this.buildContextPack(run), + semanticPlan: options?.semanticPlan ?? this.buildSemanticPlan(run), + sqlGeneration: options?.sqlGeneration ?? this.buildSqlGenerationArtifact(run), + sqlValidation: options?.sqlValidation ?? this.buildSqlValidationArtifact(run), + planLedger: + options?.planLedger ?? + this.resolvePlanLedgerSummary({ + semanticPlan: options?.semanticPlan ?? run.trace.v2?.semanticPlan, + sqlValidation: options?.sqlValidation ?? run.trace.v2?.sqlValidation, + tracePlanLedger: run.trace.v2?.planLedger + }), + runtimePlan: + options?.runtimePlan ?? + this.readRuntimePlan(run.trace.v2?.runtimePlan), + artifactRefs: + options?.artifactRefs ?? + this.readArtifactRefs(run.trace.v2?.artifactRefs), + smartDefaults: + options?.smartDefaults ?? + this.readSmartDefaults(run.trace.v2?.smartDefaults), + loopEvidence: this.readLoopEvidence(run.trace.loopEvidence), + terminationReason: this.readTerminationReason(run.trace.terminationReason) + }; + } + + private resolvePlanLedgerSummary(input: { + semanticPlan?: SemanticPlanV1; + sqlValidation?: SqlValidationArtifactV1; + tracePlanLedger?: SemanticPlanLedgerSummaryV1; + }): SemanticPlanLedgerSummaryV1 | undefined { + return ( + input.sqlValidation?.ledgerFulfillment ?? + input.tracePlanLedger ?? + input.semanticPlan?.planLedger?.summary + ); + } + + private resolveStageArtifacts( + run: SqlRun, + stageArtifacts: Text2SqlV2StageArtifact[] | undefined + ): Text2SqlV2StageArtifact[] { + const explicitStages = stageArtifacts?.length + ? stageArtifacts + : run.trace.v2?.stages?.length + ? run.trace.v2.stages + : this.readStageArtifactsFromTraceSteps(run.trace.steps ?? []); + const byStage = new Map(); + + for (const stage of explicitStages) { + if (!this.isStageName(stage.stage)) { + continue; + } + byStage.set(stage.stage, this.normalizeStageArtifact(stage)); + } + + if (run.status === "clarification" && !byStage.has("intake")) { + byStage.set("intake", { + stage: "intake", + status: "clarification", + warnings: ["clarification_terminated_before_runtime_completion"] + }); + } + + return TEXT2SQL_V2_STAGE_ORDER.map((stage) => { + const existing = byStage.get(stage); + if (existing) { + if (run.status === "clarification" && stage !== "intake" && existing.status === "clarification") { + return { + ...existing, + status: "skipped" + }; + } + return existing; + } + return { + stage, + status: stage === "intake" && run.status === "clarification" ? "clarification" : "skipped" + }; + }); + } + + private normalizeStageArtifact(stage: Text2SqlV2StageArtifact): Text2SqlV2StageArtifact { + const startedAt = this.readTimestamp(stage.startedAt); + const endedAt = this.readTimestamp(stage.endedAt); + return { + ...stage, + startedAt, + endedAt, + durationMs: + stage.durationMs ?? + this.resolveDurationMs(startedAt, endedAt), + warnings: this.uniqueStrings(stage.warnings), + evidenceIds: this.uniqueStrings(stage.evidenceIds), + metadata: stage.metadata ? { ...stage.metadata } : undefined, + provider: stage.provider ? { ...stage.provider } : undefined, + failure: stage.failure ? { ...stage.failure } : undefined + }; + } + + private readStageArtifactsFromTraceSteps( + steps: ExecutionTraceStep[] + ): Text2SqlV2StageArtifact[] { + const byStage = new Map(); + for (const step of steps) { + const candidates = [step.outputSummary, step.inputSummary] + .filter((value): value is string => typeof value === "string" && value.trim().length > 0); + for (const payload of candidates) { + const parsed = this.safeParseJson(payload); + if (!this.isRecord(parsed)) { + continue; + } + const v2 = parsed.v2; + if (!this.isRecord(v2) || !this.isRecord(v2.stageArtifact)) { + continue; + } + const stageArtifact = this.toStageArtifact(v2.stageArtifact); + if (!stageArtifact) { + continue; + } + byStage.set(stageArtifact.stage, stageArtifact); + break; + } + } + return TEXT2SQL_V2_STAGE_ORDER.flatMap((stage) => { + const artifact = byStage.get(stage); + return artifact ? [artifact] : []; + }); + } + + private toStageArtifact( + payload: Record + ): Text2SqlV2StageArtifact | undefined { + const stage = payload.stage; + const status = payload.status; + if (!this.isStageName(stage) || !this.isStageStatus(status)) { + return undefined; + } + return this.normalizeStageArtifact({ + stage, + status, + startedAt: this.readTimestamp(payload.startedAt), + endedAt: this.readTimestamp(payload.endedAt), + durationMs: this.readNumber(payload.durationMs), + warnings: this.readStringArray(payload.warnings), + evidenceIds: this.readStringArray(payload.evidenceIds), + provider: this.readProviderMetadata(payload.provider), + failure: this.readFailureSemantic(payload.failure), + metadata: this.readRecord(payload.metadata) + }); + } + + private buildContextPack(run: SqlRun): SemanticContextPackV1 { + const fromGenerateStep = this.readGenerateStepContextPack(run.trace.steps ?? []); + if (fromGenerateStep) { + return fromGenerateStep; + } + const selectedContext = run.delivery?.evidence?.selectedContext; + const snippets = selectedContext?.snippets ?? []; + const selectedEvidenceIds = snippets.map((_, index) => `snippet:${index + 1}`); + const status = run.delivery?.evidence?.contextPackStatus ?? "degraded"; + const warnings = run.delivery?.evidence?.degradeReasons; + return { + status, + selectedEvidenceIds, + selectedTables: [], + selectedColumns: [], + ...(warnings?.length ? { warnings } : {}), + version: "v1.rich", + capabilities: [ + "selected_context_summary", + "structured_lanes", + "structured_degradation" + ], + selectedContextSummary: { + count: snippets.length, + evidenceIds: selectedEvidenceIds.slice(0, 24) + }, + lanes: { + tables: { + ids: [], + count: 0 + }, + columns: { + ids: [], + count: 0 + }, + relationships: { + refs: [], + count: 0 + }, + metrics: { + refs: [], + count: 0 + } + }, + degradation: { + status, + reasons: warnings ?? [] + }, + pruning: { + applied: false, + decisions: [] + }, + permissionFiltering: { + status: "skipped" + } + }; + } + + private buildSemanticPlan(run: SqlRun): SemanticPlanV1 { + const fromGenerateStep = this.readGenerateStepSemanticPlan(run.trace.steps ?? []); + if (fromGenerateStep) { + return fromGenerateStep; + } + const usedTables = this.extractSqlTables(run.sql); + return { + route: + run.status === "clarification" + ? "clarify" + : run.status === "failed" || run.status === "rejected" + ? "reject" + : "answer", + standaloneQuestion: run.question, + selectedTables: usedTables, + selectedColumns: [], + confidence: usedTables.length > 0 ? 0.8 : 0.4, + evidenceRefs: + run.delivery?.evidence?.selectedContext?.snippets?.map((_, index) => `snippet:${index + 1}`) ?? + [] + }; + } + + private buildSqlGenerationArtifact(run: SqlRun): SqlGenerationArtifactV1 | undefined { + if (!run.sql) { + return undefined; + } + const correctionGrounding = this.readGenerateStepCorrectionGrounding( + run.trace.steps ?? [] + ); + return { + sql: run.sql, + assumptions: run.explanation ? [run.explanation] : undefined, + usedTables: this.extractSqlTables(run.sql), + usedColumns: [], + evidenceRefs: + run.delivery?.evidence?.selectedContext?.snippets?.map((_, index) => `snippet:${index + 1}`) ?? + [], + ...(correctionGrounding + ? { + correctionGrounding + } + : {}) + }; + } + + private buildSqlValidationArtifact(run: SqlRun): SqlValidationArtifactV1 { + const safetyCheckStep = (run.trace.steps ?? []).find((step) => step.node === "safety-check"); + const passed = safetyCheckStep ? safetyCheckStep.status !== "failed" : run.status !== "rejected"; + return { + status: passed ? "passed" : "failed", + checks: [ + { + check: "read-only", + status: passed ? "passed" : "failed", + code: passed ? undefined : "READ_ONLY_REJECTED", + message: passed ? undefined : run.error ?? "request rejected by read-only policy" + } + ], + correctable: false, + failure: passed + ? undefined + : { + code: "VALIDATION_FAILED", + message: run.error ?? "validation failed", + category: "validation", + terminal: true, + correctable: false + } + }; + } + + private extractSqlTables(sql?: string): string[] { + if (!sql) { + return []; + } + const matches = [...sql.matchAll(/\b(?:from|join)\s+([a-zA-Z_][\w$]*(?:\.[a-zA-Z_][\w$]*)?)/gi)]; + const tables = matches + .map((match) => match[1]) + .filter((item): item is string => Boolean(item)) + .map((item) => item.trim().toLowerCase()); + return Array.from(new Set(tables)); + } + + private readGenerateStepContextPack( + steps: ExecutionTraceStep[] + ): SemanticContextPackV1 | undefined { + const summary = this.readGenerateStepSummary(steps); + const raw = summary?.semanticContextPack; + if (!this.isRecord(raw)) { + return undefined; + } + const status = raw.status === "ready" || raw.status === "degraded" ? raw.status : undefined; + const selectedEvidenceIds = this.readStringArray(raw.selectedEvidenceIds); + const selectedTables = this.readStringArray(raw.selectedTables); + const selectedColumns = this.readStringArray(raw.selectedColumns); + if (!status) { + return undefined; + } + const warnings = this.readStringArray(raw.warnings); + const version = this.readString(raw.version); + const capabilities = this.readStringArray(raw.capabilities); + const semanticVersion = this.readNumber(raw.semanticVersion); + const modelingRevision = this.readNumber(raw.modelingRevision); + const semanticLockStatus = this.readSemanticLockStatus(raw.semanticLockStatus); + const selectedContextSummary = this.readContextPackSelectedContextSummary( + raw.selectedContextSummary + ); + const lanes = this.readContextPackLanes(raw.lanes); + const laneStates = this.readContextPackLaneStates(raw.laneStates); + const degradation = this.readContextPackDegradation(raw.degradation); + const pruning = this.readContextPackPruning(raw.pruning); + const permissionFiltering = this.readContextPackPermissionFiltering( + raw.permissionFiltering + ); + + return { + status, + selectedEvidenceIds, + selectedTables, + selectedColumns, + ...(warnings.length > 0 ? { warnings } : {}), + ...(version ? { version } : {}), + ...(capabilities.length > 0 ? { capabilities } : {}), + ...(semanticVersion !== undefined ? { semanticVersion } : {}), + ...(modelingRevision !== undefined ? { modelingRevision } : {}), + ...(semanticLockStatus ? { semanticLockStatus } : {}), + ...(selectedContextSummary ? { selectedContextSummary } : {}), + ...(lanes ? { lanes } : {}), + ...(laneStates.length > 0 ? { laneStates } : {}), + ...(degradation ? { degradation } : {}), + ...(pruning ? { pruning } : {}), + ...(permissionFiltering ? { permissionFiltering } : {}) + }; + } + + private readGenerateStepSemanticPlan( + steps: ExecutionTraceStep[] + ): SemanticPlanV1 | undefined { + const summary = this.readGenerateStepSummary(steps); + const raw = summary?.semanticPlan; + if (!this.isRecord(raw)) { + return undefined; + } + const route = + raw.route === "answer" || raw.route === "clarify" || raw.route === "reject" + ? raw.route + : undefined; + const standaloneQuestion = + typeof raw.standaloneQuestion === "string" ? raw.standaloneQuestion : undefined; + const selectedTables = this.readStringArray(raw.selectedTables); + const selectedColumns = this.readStringArray(raw.selectedColumns); + const confidence = Number(raw.confidence); + const evidenceRefs = this.readStringArray(raw.evidenceRefs); + const coverageGaps = this.readCoverageGaps(raw.coverageGaps); + const snapshotId = this.readString(raw.snapshotId); + if (!route || !standaloneQuestion || !Number.isFinite(confidence)) { + return undefined; + } + return { + route, + standaloneQuestion, + selectedTables, + selectedColumns, + confidence: Math.max(0, Math.min(1, confidence)), + evidenceRefs, + ...(coverageGaps.length > 0 ? { coverageGaps } : {}), + ...(snapshotId ? { snapshotId } : {}), + ...(this.readStringArray(raw.metrics).length > 0 + ? { metrics: this.readStringArray(raw.metrics) } + : {}), + ...(this.readString(raw.grain) ? { grain: this.readString(raw.grain) } : {}), + ...(this.readStringArray(raw.filters).length > 0 + ? { filters: this.readStringArray(raw.filters) } + : {}), + ...(this.readStringArray(raw.joinPath).length > 0 + ? { joinPath: this.readStringArray(raw.joinPath) } + : {}), + ...(this.readStringArray(raw.allowedTables).length > 0 + ? { allowedTables: this.readStringArray(raw.allowedTables) } + : {}), + ...(this.readStringArray(raw.forbiddenTables).length > 0 + ? { forbiddenTables: this.readStringArray(raw.forbiddenTables) } + : {}) + }; + } + + private readGenerateStepCorrectionGrounding( + steps: ExecutionTraceStep[] + ): SqlGenerationArtifactV1["correctionGrounding"] | undefined { + const summary = this.readGenerateStepSummary(steps); + if (!summary || !this.isRecord(summary.correctionGrounding)) { + return undefined; + } + const raw = summary.correctionGrounding; + const failedSqlRef = this.readString(raw.failedSqlRef); + const retryReason = this.readString(raw.retryReason); + if (!failedSqlRef || !retryReason) { + return undefined; + } + const failureCategory = this.readString(raw.failureCategory); + const source = this.readString(raw.source); + const semanticPlanRoute = this.readString(raw.semanticPlanRoute); + const semanticPlanRouteKind = this.readString(raw.semanticPlanRouteKind); + const contextPackStatus = this.readString(raw.contextPackStatus); + + return { + failedSqlRef, + retryReason, + ...(this.readString(raw.failedSqlPreview) + ? { + failedSqlPreview: this.readString(raw.failedSqlPreview) + } + : {}), + ...(this.readString(raw.failureCode) + ? { + failureCode: this.readString(raw.failureCode) + } + : {}), + ...(failureCategory && + (failureCategory === "validation" || + failureCategory === "governance" || + failureCategory === "safety" || + failureCategory === "provider" || + failureCategory === "execution" || + failureCategory === "unknown") + ? { + failureCategory + } + : {}), + ...(source && (source === "validation" || source === "execution") + ? { + source + } + : {}), + attemptCount: this.readNumber(raw.attemptCount) ?? 0, + maxAttempts: this.readNumber(raw.maxAttempts) ?? 0, + evidenceRefs: this.readStringArray(raw.evidenceRefs), + ...(this.readString(raw.semanticPlanSnapshotId) + ? { + semanticPlanSnapshotId: this.readString(raw.semanticPlanSnapshotId) + } + : {}), + ...(semanticPlanRoute && + (semanticPlanRoute === "answer" || + semanticPlanRoute === "clarify" || + semanticPlanRoute === "reject") + ? { + semanticPlanRoute + } + : {}), + ...(semanticPlanRouteKind && + (semanticPlanRouteKind === "text_to_sql" || + semanticPlanRouteKind === "metadata" || + semanticPlanRouteKind === "general" || + semanticPlanRouteKind === "clarify" || + semanticPlanRouteKind === "fail_closed") + ? { + semanticPlanRouteKind + } + : {}), + ...(this.readNumber(raw.selectedTableCount) !== undefined + ? { + selectedTableCount: this.readNumber(raw.selectedTableCount) + } + : {}), + ...(this.readNumber(raw.selectedColumnCount) !== undefined + ? { + selectedColumnCount: this.readNumber(raw.selectedColumnCount) + } + : {}), + ...(contextPackStatus && + (contextPackStatus === "ready" || contextPackStatus === "degraded") + ? { + contextPackStatus + } + : {}), + ...(this.readNumber(raw.contextPackEvidenceCount) !== undefined + ? { + contextPackEvidenceCount: this.readNumber(raw.contextPackEvidenceCount) + } + : {}) + }; + } + + private readCoverageGaps( + value: unknown + ): NonNullable { + if (!Array.isArray(value)) { + return []; + } + return value + .map((item) => { + if (!this.isRecord(item)) { + return undefined; + } + const gapType = this.readString(item.gapType); + const subjectKind = this.readString(item.subjectKind); + const reasonCode = this.readString(item.reasonCode); + const impactScope = this.readString(item.impactScope); + const evidenceRefs = this.readStringArray(item.evidenceRefs); + if (!gapType || !subjectKind || !reasonCode || !impactScope) { + return undefined; + } + return { + gapType, + subjectKind, + reasonCode, + evidenceRefs, + impactScope + }; + }) + .filter((item): item is NonNullable => Boolean(item)); + } + + private readLoopEvidence(value: unknown): Text2SqlV2LoopEvidence[] | undefined { + if (!Array.isArray(value)) { + return undefined; + } + const normalized = value + .map((item) => { + if (!this.isRecord(item)) { + return undefined; + } + const loopIndex = this.readNumber(item.loopIndex); + const triggerReason = this.readString(item.triggerReason); + const actionType = this.readString(item.actionType); + const terminationReason = this.readTerminationReason(item.terminationReason); + const convergencePath = this.readStringArray(item.convergencePath); + const planDeltaRaw = this.readRecord(item.planDelta); + const routeDeltaRaw = this.readRecord(planDeltaRaw?.route); + const planDelta = + planDeltaRaw || routeDeltaRaw + ? { + ...(routeDeltaRaw + ? { + route: { + ...(this.readString(routeDeltaRaw.from) + ? { from: this.readString(routeDeltaRaw.from) as SemanticPlanV1["route"] } + : {}), + ...(this.readString(routeDeltaRaw.to) + ? { to: this.readString(routeDeltaRaw.to) as SemanticPlanV1["route"] } + : {}) + } + } + : {}), + ...(this.readString(planDeltaRaw?.snapshotId) + ? { snapshotId: this.readString(planDeltaRaw?.snapshotId) } + : {}), + ...(this.readStringArray(planDeltaRaw?.addedCoverageGapTypes).length > 0 + ? { + addedCoverageGapTypes: this.readStringArray( + planDeltaRaw?.addedCoverageGapTypes + ) as string[] + } + : {}), + ...(this.readStringArray(planDeltaRaw?.reasonCodes).length > 0 + ? { reasonCodes: this.readStringArray(planDeltaRaw?.reasonCodes) } + : {}) + } + : undefined; + if ( + typeof loopIndex !== "number" || + !Number.isFinite(loopIndex) || + !triggerReason || + !actionType + ) { + return undefined; + } + return { + loopIndex, + triggerReason, + actionType, + ...(planDelta ? { planDelta } : {}), + ...(terminationReason ? { terminationReason } : {}), + ...(convergencePath.length > 0 ? { convergencePath } : {}) + }; + }) + .filter((item): item is NonNullable => Boolean(item)); + return normalized.length > 0 ? normalized : undefined; + } + + private readRuntimePlan(value: unknown): Text2SqlV2RuntimePlanV1 | undefined { + if (!this.isRecord(value) || value.version !== "runtime-plan.v1") { + return undefined; + } + const items = Array.isArray(value.items) + ? value.items + .map((item) => this.readRuntimePlanItem(item)) + .filter((item): item is NonNullable => Boolean(item)) + : []; + if (items.length === 0) { + return undefined; + } + return { + version: "runtime-plan.v1", + items, + ...(this.readString(value.currentItemId) + ? { currentItemId: this.readString(value.currentItemId) } + : {}), + ...(this.readString(value.summary) + ? { summary: this.readString(value.summary) } + : {}) + }; + } + + private readRuntimePlanItem( + value: unknown + ): Text2SqlV2RuntimePlanV1["items"][number] | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const id = this.readString(value.id); + const stage = value.stage; + const goal = this.readString(value.goal); + const status = this.readRuntimePlanStatus(value.status); + if (!id || !this.isStageName(stage) || !goal || !status) { + return undefined; + } + const correctionIntent = this.readRuntimePlanCorrectionIntent( + value.correctionIntent + ); + return { + id, + stage, + goal, + status, + ...(this.readStringArray(value.reasonCodes).length > 0 + ? { reasonCodes: this.readStringArray(value.reasonCodes) } + : {}), + ...(this.readStringArray(value.evidenceRefs).length > 0 + ? { evidenceRefs: this.readStringArray(value.evidenceRefs) } + : {}), + ...(correctionIntent ? { correctionIntent } : {}), + ...(this.readTimestamp(value.startedAt) + ? { startedAt: this.readTimestamp(value.startedAt) } + : {}), + ...(this.readTimestamp(value.endedAt) + ? { endedAt: this.readTimestamp(value.endedAt) } + : {}), + ...(this.readString(value.summary) + ? { summary: this.readString(value.summary) } + : {}) + }; + } + + private readRuntimePlanCorrectionIntent( + value: unknown + ): Text2SqlV2RuntimePlanV1["items"][number]["correctionIntent"] | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const retryReason = this.readString(value.retryReason); + if (!retryReason) { + return undefined; + } + const failedStage = value.failedStage; + const targetStage = value.targetStage; + return { + ...(this.isStageName(failedStage) ? { failedStage } : {}), + ...(this.readString(value.failureCode) + ? { failureCode: this.readString(value.failureCode) } + : {}), + retryReason, + ...(this.isStageName(targetStage) ? { targetStage } : {}) + }; + } + + private readArtifactRefs(value: unknown): Text2SqlV2ArtifactRefV1[] | undefined { + if (!Array.isArray(value)) { + return undefined; + } + const refs = value + .map((item) => this.readArtifactRef(item)) + .filter((item): item is Text2SqlV2ArtifactRefV1 => Boolean(item)); + return refs.length > 0 ? refs : undefined; + } + + private readArtifactRef(value: unknown): Text2SqlV2ArtifactRefV1 | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const id = this.readString(value.id); + const category = this.readString(value.category); + const summary = this.readString(value.summary); + const hash = this.readString(value.hash); + const visibility = this.readArtifactVisibility(value.visibility); + if (!id || !category || !summary || !hash || !visibility) { + return undefined; + } + return { + id, + category, + summary, + hash, + ...(this.readString(value.version) + ? { version: this.readString(value.version) } + : {}), + ...(this.readNumber(value.sizeBytes) !== undefined + ? { sizeBytes: this.readNumber(value.sizeBytes) } + : {}), + ...(this.readString(value.replayKeyHint) + ? { replayKeyHint: this.readString(value.replayKeyHint) } + : {}), + visibility, + ...(this.readArtifactSensitivity(value.sensitivity) + ? { sensitivity: this.readArtifactSensitivity(value.sensitivity) } + : {}), + ...(this.readStringArray(value.reasonCodes).length > 0 + ? { reasonCodes: this.readStringArray(value.reasonCodes) } + : {}), + ...(this.readStringArray(value.evidenceRefs).length > 0 + ? { evidenceRefs: this.readStringArray(value.evidenceRefs) } + : {}) + }; + } + + private readSmartDefaults( + value: unknown + ): Text2SqlV2SmartDefaultsEvidenceV1 | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const bundleId = this.readString(value.bundleId); + const version = this.readString(value.version); + const coveredStages = this.readStageNameArray(value.coveredStages); + const ruleIds = this.readStringArray(value.ruleIds); + const status = + value.status === "applied" || value.status === "fallback" + ? value.status + : undefined; + if ( + !bundleId || + !version || + coveredStages.length === 0 || + ruleIds.length === 0 || + !status + ) { + return undefined; + } + const templateOverlay = this.readSmartDefaultsTemplateOverlay( + value.templateOverlay + ); + return { + bundleId, + version, + coveredStages, + ruleIds, + status, + ...(this.readString(value.fallbackReason) + ? { fallbackReason: this.readString(value.fallbackReason) } + : {}), + ...(templateOverlay ? { templateOverlay } : {}) + }; + } + + private readSmartDefaultsTemplateOverlay( + value: unknown + ): Text2SqlV2SmartDefaultsEvidenceV1["templateOverlay"] | undefined { + if (!this.isRecord(value) || typeof value.applied !== "boolean") { + return undefined; + } + return { + applied: value.applied, + ...(this.readString(value.templateId) + ? { templateId: this.readString(value.templateId) } + : {}), + ...(this.readNumber(value.version) !== undefined + ? { version: this.readNumber(value.version) } + : {}) + }; + } + + private readTerminationReason( + value: unknown + ): Text2SqlV2TerminationReason | undefined { + const normalized = this.readString(value); + return normalized as Text2SqlV2TerminationReason | undefined; + } + + private isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); + } + + private readRecord(value: unknown): Record | undefined { + return this.isRecord(value) ? value : undefined; + } + + private readString(value: unknown): string | undefined { + if (typeof value !== "string") { + return undefined; + } + const normalized = value.trim(); + return normalized.length > 0 ? normalized : undefined; + } + + private readTimestamp(value: unknown): string | undefined { + const text = this.readString(value); + if (!text) { + return undefined; + } + return Number.isNaN(Date.parse(text)) ? undefined : text; + } + + private readNumber(value: unknown): number | undefined { + const parsed = Number(value); + return Number.isFinite(parsed) ? parsed : undefined; + } + + private readStringArray(value: unknown): string[] { + if (!Array.isArray(value)) { + return []; + } + return value + .map((item) => this.readString(item)) + .filter((item): item is string => Boolean(item)); + } + + private readStageNameArray(value: unknown): Text2SqlV2StageName[] { + if (!Array.isArray(value)) { + return []; + } + return value.filter((item): item is Text2SqlV2StageName => + this.isStageName(item) + ); + } + + private readRuntimePlanStatus( + value: unknown + ): Text2SqlV2RuntimePlanV1["items"][number]["status"] | undefined { + if ( + value === "pending" || + value === "running" || + value === "completed" || + value === "skipped" || + value === "failed" || + value === "clarification" + ) { + return value; + } + return undefined; + } + + private readArtifactVisibility( + value: unknown + ): Text2SqlV2ArtifactRefV1["visibility"] | undefined { + if (value === "user" || value === "internal" || value === "redacted") { + return value; + } + return undefined; + } + + private readArtifactSensitivity( + value: unknown + ): Text2SqlV2ArtifactRefV1["sensitivity"] | undefined { + if ( + value === "none" || + value === "permission_filtered" || + value === "provider_raw" || + value === "sensitive" + ) { + return value; + } + return undefined; + } + + private readSemanticLockStatus( + value: unknown + ): "locked" | "fallback" | "degraded" | undefined { + if (value === "locked" || value === "fallback" || value === "degraded") { + return value; + } + return undefined; + } + + private readContextPackSelectedContextSummary( + value: unknown + ): SemanticContextPackV1["selectedContextSummary"] | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const count = this.readNumber(value.count); + const evidenceIds = this.readStringArray(value.evidenceIds); + if (count === undefined) { + return undefined; + } + const laneNames = this.readStringArray(value.laneNames); + return { + count, + evidenceIds, + ...(laneNames.length > 0 ? { laneNames } : {}) + }; + } + + private readContextPackLanes( + value: unknown + ): SemanticContextPackV1["lanes"] | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const tables = this.readIdentifierLane(value.tables); + const columns = this.readIdentifierLane(value.columns); + const aliases = this.readIdentifierLane(value.aliases); + const relationships = this.readReferenceLane(value.relationships); + const metrics = this.readReferenceLane(value.metrics); + const calculatedFields = this.readReferenceLane(value.calculatedFields); + const examples = this.readReferenceLane(value.examples); + const instructions = this.readReferenceLane(value.instructions); + const priorSql = this.readReferenceLane(value.priorSql); + const schemaSupplementRefs = this.readReferenceLane(value.schemaSupplementRefs); + const dialectFunctions = this.readReferenceLane(value.dialectFunctions); + const semanticBindings = this.readContextPackSemanticBindings(value.semanticBindings); + + if (!tables || !columns || !relationships || !metrics) { + return undefined; + } + + return { + tables, + columns, + ...(aliases ? { aliases } : {}), + relationships, + metrics, + ...(calculatedFields ? { calculatedFields } : {}), + ...(examples ? { examples } : {}), + ...(instructions ? { instructions } : {}), + ...(priorSql ? { priorSql } : {}), + ...(schemaSupplementRefs ? { schemaSupplementRefs } : {}), + ...(dialectFunctions ? { dialectFunctions } : {}), + ...(semanticBindings ? { semanticBindings } : {}) + }; + } + + private readIdentifierLane( + value: unknown + ): { + ids: string[]; + count: number; + reasonCodes?: string[]; + } | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const ids = this.readStringArray(value.ids); + const count = this.readNumber(value.count); + if (count === undefined) { + return undefined; + } + const reasonCodes = this.readStringArray(value.reasonCodes); + return { + ids, + count, + ...(reasonCodes.length > 0 ? { reasonCodes } : {}) + }; + } + + private readReferenceLane( + value: unknown + ): { + refs: string[]; + count: number; + reasonCodes?: string[]; + } | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const refs = this.readStringArray(value.refs); + const count = this.readNumber(value.count); + if (count === undefined) { + return undefined; + } + const reasonCodes = this.readStringArray(value.reasonCodes); + return { + refs, + count, + ...(reasonCodes.length > 0 ? { reasonCodes } : {}) + }; + } + + private readContextPackSemanticBindings( + value: unknown + ): { + modelKeys?: string[]; + relationshipKeys?: string[]; + metricKeys?: string[]; + calculatedFieldKeys?: string[]; + } | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const modelKeys = this.readStringArray(value.modelKeys); + const relationshipKeys = this.readStringArray(value.relationshipKeys); + const metricKeys = this.readStringArray(value.metricKeys); + const calculatedFieldKeys = this.readStringArray(value.calculatedFieldKeys); + if ( + modelKeys.length === 0 && + relationshipKeys.length === 0 && + metricKeys.length === 0 && + calculatedFieldKeys.length === 0 + ) { + return undefined; + } + return { + ...(modelKeys.length > 0 ? { modelKeys } : {}), + ...(relationshipKeys.length > 0 ? { relationshipKeys } : {}), + ...(metricKeys.length > 0 ? { metricKeys } : {}), + ...(calculatedFieldKeys.length > 0 ? { calculatedFieldKeys } : {}) + }; + } + + private readContextPackLaneStates( + value: unknown + ): NonNullable { + if (!Array.isArray(value)) { + return []; + } + return value + .map((item) => { + if (!this.isRecord(item)) { + return undefined; + } + const lane = this.readString(item.lane); + const state = this.readString(item.state); + if (!lane || !state) { + return undefined; + } + const refs = this.readStringArray(item.refs); + const reasonCodes = this.readStringArray(item.reasonCodes); + const unavailableReason = this.readString(item.unavailableReason); + const fallbackReason = this.readString(item.fallbackReason); + const inputCount = this.readNumber(item.inputCount); + const outputCount = this.readNumber(item.outputCount); + const selectedCount = this.readNumber(item.selectedCount); + return { + lane, + state, + ...(refs.length > 0 ? { refs } : {}), + ...(reasonCodes.length > 0 ? { reasonCodes } : {}), + ...(unavailableReason ? { unavailableReason } : {}), + ...(fallbackReason ? { fallbackReason } : {}), + ...(inputCount !== undefined ? { inputCount } : {}), + ...(outputCount !== undefined ? { outputCount } : {}), + ...(selectedCount !== undefined ? { selectedCount } : {}) + }; + }) + .filter((item): item is NonNullable => Boolean(item)); + } + + private readContextPackDegradation( + value: unknown + ): SemanticContextPackV1["degradation"] | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const status = + value.status === "ready" || value.status === "degraded" ? value.status : undefined; + if (!status) { + return undefined; + } + const reasons = this.readStringArray(value.reasons); + const riskTags = this.readStringArray(value.riskTags); + const denseUnavailableReason = this.readString(value.denseUnavailableReason); + const rerankUnavailableReason = this.readString(value.rerankUnavailableReason); + const laneIssues = this.readContextPackLaneStates(value.laneIssues); + return { + status, + reasons, + ...(riskTags.length > 0 ? { riskTags } : {}), + ...(denseUnavailableReason ? { denseUnavailableReason } : {}), + ...(rerankUnavailableReason ? { rerankUnavailableReason } : {}), + ...(laneIssues.length > 0 ? { laneIssues } : {}) + }; + } + + private readContextPackPruning( + value: unknown + ): SemanticContextPackV1["pruning"] | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const applied = typeof value.applied === "boolean" ? value.applied : undefined; + if (applied === undefined || !Array.isArray(value.decisions)) { + return undefined; + } + const decisions = value.decisions + .map((decision) => { + if (!this.isRecord(decision)) { + return undefined; + } + const budgetSource = this.readString(decision.budgetSource); + const keptEvidenceIds = this.readStringArray(decision.keptEvidenceIds); + const removedEvidenceIds = this.readStringArray(decision.removedEvidenceIds); + const keptCount = this.readNumber(decision.keptCount); + const removedCount = this.readNumber(decision.removedCount); + const reasonCodes = this.readStringArray(decision.reasonCodes); + const summary = this.readString(decision.summary); + return { + ...(budgetSource ? { budgetSource } : {}), + ...(keptEvidenceIds.length > 0 ? { keptEvidenceIds } : {}), + ...(removedEvidenceIds.length > 0 ? { removedEvidenceIds } : {}), + ...(keptCount !== undefined ? { keptCount } : {}), + ...(removedCount !== undefined ? { removedCount } : {}), + ...(reasonCodes.length > 0 ? { reasonCodes } : {}), + ...(summary ? { summary } : {}) + }; + }) + .filter((item): item is NonNullable => Boolean(item)); + return { + applied, + decisions + }; + } + + private readContextPackPermissionFiltering( + value: unknown + ): SemanticContextPackV1["permissionFiltering"] | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const status = + value.status === "applied" || value.status === "skipped" + ? value.status + : undefined; + if (!status) { + return undefined; + } + const deniedEvidenceIds = this.readStringArray(value.deniedEvidenceIds); + const deniedEvidenceCount = this.readNumber(value.deniedEvidenceCount); + const deniedTables = this.readStringArray(value.deniedTables); + const deniedColumns = this.readStringArray(value.deniedColumns); + const reasonCodes = this.readStringArray(value.reasonCodes); + return { + status, + ...(deniedEvidenceIds.length > 0 ? { deniedEvidenceIds } : {}), + ...(deniedEvidenceCount !== undefined ? { deniedEvidenceCount } : {}), + ...(deniedTables.length > 0 ? { deniedTables } : {}), + ...(deniedColumns.length > 0 ? { deniedColumns } : {}), + ...(reasonCodes.length > 0 ? { reasonCodes } : {}) + }; + } + + private uniqueStrings(values: string[] | undefined): string[] | undefined { + if (!values) { + return undefined; + } + const filtered = values + .map((item) => item.trim()) + .filter((item) => item.length > 0); + return filtered.length > 0 ? Array.from(new Set(filtered)) : undefined; + } + + private readGenerateStepSummary( + steps: ExecutionTraceStep[] + ): Record | undefined { + const outputSummary = steps.find((step) => step.node === "generate-sql")?.outputSummary; + if (typeof outputSummary !== "string") { + return undefined; + } + const parsed = this.safeParseJson(outputSummary); + return this.isRecord(parsed) ? parsed : undefined; + } + + private readProviderMetadata(value: unknown): Text2SqlV2StageArtifact["provider"] { + if (!this.isRecord(value)) { + return undefined; + } + const provider = this.readString(value.provider); + const model = this.readString(value.model); + const dimensions = this.readNumber(value.dimensions); + const vectorVersion = this.readString(value.vectorVersion); + const indexVersion = this.readString(value.indexVersion); + const scope = this.readString(value.scope); + const assetType = this.readString(value.assetType); + const timeoutMs = this.readNumber(value.timeoutMs); + const inputCount = this.readNumber(value.inputCount); + const outputCount = this.readNumber(value.outputCount); + const fallbackReason = this.readString(value.fallbackReason); + const unavailableReason = this.readString(value.unavailableReason); + if ( + !provider && + !model && + dimensions === undefined && + !vectorVersion && + !indexVersion && + !scope && + !assetType && + timeoutMs === undefined && + inputCount === undefined && + outputCount === undefined && + !fallbackReason && + !unavailableReason + ) { + return undefined; + } + return { + provider, + model, + dimensions, + vectorVersion, + indexVersion, + scope, + assetType, + timeoutMs, + inputCount, + outputCount, + fallbackReason, + unavailableReason + }; + } + + private readFailureSemantic(value: unknown): Text2SqlV2FailureSemantic | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const code = this.readString(value.code); + const message = this.readString(value.message); + if (!code || !message) { + return undefined; + } + const category = this.readString(value.category) as Text2SqlV2FailureSemantic["category"]; + const terminal = typeof value.terminal === "boolean" ? value.terminal : undefined; + const correctable = typeof value.correctable === "boolean" ? value.correctable : undefined; + return { + code, + message, + category, + terminal, + correctable + }; + } + + private safeParseJson(value: string): unknown { + try { + return JSON.parse(value); + } catch { + return undefined; + } + } + + private isStageName(value: unknown): value is Text2SqlV2StageName { + return typeof value === "string" && TEXT2SQL_V2_STAGE_ORDER.includes(value as Text2SqlV2StageName); + } + + private isStageStatus( + value: unknown + ): value is Text2SqlV2StageArtifact["status"] { + return ( + value === "success" || + value === "skipped" || + value === "degraded" || + value === "failed" || + value === "clarification" + ); + } + + private resolveDurationMs(startedAt?: string, endedAt?: string): number | undefined { + if (!startedAt || !endedAt) { + return undefined; + } + const started = Date.parse(startedAt); + const ended = Date.parse(endedAt); + if (Number.isNaN(started) || Number.isNaN(ended)) { + return undefined; + } + return Math.max(0, ended - started); + } +} diff --git a/apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts b/apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts new file mode 100644 index 0000000..b5f1a0e --- /dev/null +++ b/apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts @@ -0,0 +1,626 @@ +import { createHash } from "node:crypto"; +import { Inject, Injectable } from "@nestjs/common"; +import type { + SqlRun, + Text2SqlV2ArtifactRefV1, + Text2SqlV2ArtifactRefCategoryV1 +} from "@text2sql/shared-types"; +import { + KNOWLEDGE_FACADE_CONTRACT, + type KnowledgeFacadeContract +} from "../../knowledge"; + +const CONTEXT_EVIDENCE_REF_THRESHOLD = 24; +const EXECUTION_PREVIEW_ROW_THRESHOLD = 3; +const EXECUTION_PREVIEW_SIZE_THRESHOLD = 2_048; + +export const REQUIRED_TEXT2SQL_V2_ARTIFACT_CATEGORIES = [ + "context_snippets", + "schema_supplement", + "prompt_input", + "provider_output_summary", + "validation_diagnostics", + "correction_grounding", + "execution_preview" +] as const satisfies readonly Text2SqlV2ArtifactRefCategoryV1[]; + +type ArtifactSensitivity = NonNullable; +type ArtifactVisibility = Text2SqlV2ArtifactRefV1["visibility"]; + +interface Text2SqlV2ArtifactCategoryPolicy { + visibility: ArtifactVisibility; + sensitivity: ArtifactSensitivity; + allowPayload: boolean; + reasonCode: string; +} + +export const TEXT2SQL_V2_ARTIFACT_CATEGORY_POLICIES: Record< + (typeof REQUIRED_TEXT2SQL_V2_ARTIFACT_CATEGORIES)[number], + Text2SqlV2ArtifactCategoryPolicy +> = { + context_snippets: { + visibility: "user", + sensitivity: "none", + allowPayload: true, + reasonCode: "large_context_compacted" + }, + schema_supplement: { + visibility: "user", + sensitivity: "permission_filtered", + allowPayload: false, + reasonCode: "schema_supplement_summarized" + }, + prompt_input: { + visibility: "internal", + sensitivity: "sensitive", + allowPayload: false, + reasonCode: "prompt_input_summarized" + }, + provider_output_summary: { + visibility: "internal", + sensitivity: "provider_raw", + allowPayload: false, + reasonCode: "provider_output_summarized" + }, + validation_diagnostics: { + visibility: "user", + sensitivity: "none", + allowPayload: true, + reasonCode: "validation_diagnostics_summarized" + }, + correction_grounding: { + visibility: "user", + sensitivity: "none", + allowPayload: true, + reasonCode: "correction_grounding_summarized" + }, + execution_preview: { + visibility: "user", + sensitivity: "none", + allowPayload: true, + reasonCode: "execution_preview_compacted" + } +}; + +export interface Text2SqlV2ArtifactOffloadResult { + ref?: Text2SqlV2ArtifactRefV1; + degradationReason?: string; +} + +export interface Text2SqlV2ArtifactProducerInput { + runId: string; + datasourceId: string; + category: Text2SqlV2ArtifactRefCategoryV1; + stableId: string; + summary: string; + sizeBytes?: number; + visibility?: ArtifactVisibility; + sensitivity?: ArtifactSensitivity; + evidenceRefs?: string[]; + reasonCodes?: string[]; + payload?: Record; +} + +@Injectable() +export class Text2SqlV2ArtifactRefService { + constructor( + @Inject(KNOWLEDGE_FACADE_CONTRACT) + private readonly knowledgeFacade: KnowledgeFacadeContract + ) {} + + async attachRunArtifactRefs(run: SqlRun, datasourceId: string): Promise { + const refs: Text2SqlV2ArtifactRefV1[] = [ + ...(run.trace.v2?.artifactRefs ?? []) + ]; + const warnings: string[] = []; + const existingIds = new Set(refs.map((ref) => ref.id)); + + for (const artifactInput of this.buildProducerInputs({ run, datasourceId })) { + const refId = `artifact:${artifactInput.category}:${artifactInput.stableId}`; + if (existingIds.has(refId)) { + continue; + } + const result = await this.writeSummaryArtifact(artifactInput); + if (result.ref) { + refs.push(result.ref); + existingIds.add(result.ref.id); + } + if (result.degradationReason) { + warnings.push(result.degradationReason); + } + } + + if (refs.length === 0 && warnings.length === 0) { + return run; + } + + return { + ...run, + trace: { + ...run.trace, + v2: run.trace.v2 + ? { + ...run.trace.v2, + ...(refs.length > 0 ? { artifactRefs: this.uniqueRefs(refs) } : {}), + stages: warnings.length > 0 + ? this.appendArtifactWarnings(run.trace.v2.stages, warnings) + : run.trace.v2.stages + } + : run.trace.v2 + } + }; + } + + async writeSummaryArtifact( + input: Text2SqlV2ArtifactProducerInput + ): Promise { + const policy = this.resolvePolicy(input.category); + const sensitivity = input.sensitivity ?? policy.sensitivity; + const visibility = input.visibility ?? policy.visibility; + const reasonCodes = this.uniqueStrings([ + policy.reasonCode, + ...(input.reasonCodes ?? []) + ]); + const evidenceRefs = this.uniqueStrings(input.evidenceRefs ?? []); + const payload = this.shouldPersistPayload(policy, sensitivity) + ? input.payload + : undefined; + const hash = this.hash({ + category: input.category, + stableId: input.stableId, + summary: input.summary, + evidenceRefs, + reasonCodes + }); + const replayKey = `text2sql:artifact:${input.category}:${input.stableId}`; + const ref: Text2SqlV2ArtifactRefV1 = { + id: `artifact:${input.category}:${input.stableId}`, + category: input.category, + summary: input.summary, + hash, + version: "artifact-ref.v1", + ...(input.sizeBytes !== undefined ? { sizeBytes: input.sizeBytes } : {}), + replayKeyHint: replayKey, + visibility, + sensitivity, + ...(reasonCodes.length ? { reasonCodes } : {}), + ...(evidenceRefs.length ? { evidenceRefs } : {}) + }; + + try { + await this.knowledgeFacade.rag.replay.writeReplay({ + runId: input.runId, + datasourceId: input.datasourceId, + replayKey, + stage: "text2sql_artifact_ref", + payload: { + version: "text2sql-artifact-summary.v1", + ref, + sanitizedSummary: input.summary, + evidenceRefs, + reasonCodes, + sizeBytes: input.sizeBytes, + createdAt: new Date().toISOString(), + payload + } + }); + return { ref }; + } catch { + return { + degradationReason: `artifact_ref_write_failed:${input.category}` + }; + } + } + + private buildProducerInputs(input: { + run: SqlRun; + datasourceId: string; + }): Text2SqlV2ArtifactProducerInput[] { + return [ + this.buildContextPackArtifact(input), + this.buildSchemaSupplementArtifact(input), + this.buildPromptInputArtifact(input), + this.buildProviderOutputArtifact(input), + this.buildValidationDiagnosticsArtifact(input), + this.buildCorrectionGroundingArtifact(input), + this.buildExecutionPreviewArtifact(input) + ].filter((item): item is Text2SqlV2ArtifactProducerInput => Boolean(item)); + } + + private buildContextPackArtifact(input: { + run: SqlRun; + datasourceId: string; + }): Text2SqlV2ArtifactProducerInput | undefined { + const contextPack = input.run.trace.v2?.contextPack; + const selectedEvidenceIds = contextPack?.selectedEvidenceIds ?? []; + if (selectedEvidenceIds.length <= CONTEXT_EVIDENCE_REF_THRESHOLD) { + return undefined; + } + + const stableId = this.stableHashId({ + runId: input.run.runId, + selectedEvidenceIds + }); + + return { + runId: input.run.runId, + datasourceId: input.datasourceId, + category: "context_snippets", + stableId, + summary: `Compacted ${selectedEvidenceIds.length} selected context evidence ids.`, + sizeBytes: JSON.stringify(contextPack).length, + visibility: "user", + sensitivity: + contextPack?.permissionFiltering?.status === "applied" + ? "permission_filtered" + : "none", + evidenceRefs: selectedEvidenceIds.slice(0, 24), + reasonCodes: ["large_context_compacted"], + payload: { + status: contextPack?.status, + selectedEvidenceIds, + selectedTables: contextPack?.selectedTables ?? [], + selectedColumns: contextPack?.selectedColumns ?? [], + degradationReasons: contextPack?.degradation?.reasons ?? [] + } + }; + } + + private buildSchemaSupplementArtifact(input: { + run: SqlRun; + datasourceId: string; + }): Text2SqlV2ArtifactProducerInput | undefined { + const contextPack = input.run.trace.v2?.contextPack; + const selectedTables = contextPack?.selectedTables ?? []; + const selectedColumns = contextPack?.selectedColumns ?? []; + if (selectedTables.length === 0 && selectedColumns.length === 0) { + return undefined; + } + const evidenceRefs = contextPack?.selectedEvidenceIds ?? []; + return { + runId: input.run.runId, + datasourceId: input.datasourceId, + category: "schema_supplement", + stableId: this.stableHashId({ + runId: input.run.runId, + selectedTables, + selectedColumns + }), + summary: `Schema supplement summarized ${selectedTables.length} tables and ${selectedColumns.length} columns.`, + sizeBytes: JSON.stringify({ selectedTables, selectedColumns }).length, + visibility: "user", + sensitivity: + contextPack?.permissionFiltering?.status === "applied" + ? "permission_filtered" + : "none", + evidenceRefs: evidenceRefs.slice(0, 24), + reasonCodes: [ + "schema_supplement_summarized", + ...(contextPack?.permissionFiltering?.status === "applied" + ? ["permission_filtered_schema"] + : []) + ], + payload: { + selectedTables, + selectedColumns, + laneStates: contextPack?.laneStates?.map((lane) => ({ + lane: lane.lane, + state: lane.state, + reasonCodes: lane.reasonCodes, + inputCount: lane.inputCount, + outputCount: lane.outputCount, + selectedCount: lane.selectedCount + })), + pruning: contextPack?.pruning + ? { + applied: contextPack.pruning.applied, + decisions: contextPack.pruning.decisions.map((decision) => ({ + keptCount: decision.keptCount, + removedCount: decision.removedCount, + reasonCodes: decision.reasonCodes, + summary: decision.summary + })) + } + : undefined + } + }; + } + + private buildPromptInputArtifact(input: { + run: SqlRun; + datasourceId: string; + }): Text2SqlV2ArtifactProducerInput | undefined { + const promptTemplate = + input.run.trace.promptTemplate ?? + this.asRecord(input.run.trace.v2?.sqlGeneration)?.promptTemplate; + const smartDefaults = input.run.trace.v2?.smartDefaults; + if (!promptTemplate && !smartDefaults) { + return undefined; + } + const template = this.asRecord(promptTemplate); + return { + runId: input.run.runId, + datasourceId: input.datasourceId, + category: "prompt_input", + stableId: this.stableHashId({ + runId: input.run.runId, + promptTemplate, + smartDefaults + }), + summary: `Prompt input summarized template ${this.readString(template?.templateId) ?? "default"} with Smart Defaults ${smartDefaults?.status ?? "unknown"}.`, + sizeBytes: JSON.stringify({ promptTemplate, smartDefaults }).length, + visibility: "internal", + sensitivity: "sensitive", + reasonCodes: ["prompt_input_summarized"], + payload: { + promptTemplate: { + templateId: this.readString(template?.templateId), + version: template?.version, + source: this.readString(template?.source), + fallbackReason: this.readString(template?.fallbackReason) + }, + smartDefaults: smartDefaults + ? { + bundleId: smartDefaults.bundleId, + version: smartDefaults.version, + coveredStages: smartDefaults.coveredStages, + ruleIds: smartDefaults.ruleIds, + status: smartDefaults.status, + fallbackReason: smartDefaults.fallbackReason, + templateOverlay: smartDefaults.templateOverlay + } + : undefined + } + }; + } + + private buildProviderOutputArtifact(input: { + run: SqlRun; + datasourceId: string; + }): Text2SqlV2ArtifactProducerInput | undefined { + const sqlGeneration = input.run.trace.v2?.sqlGeneration; + if (!sqlGeneration && !input.run.provider && !input.run.model) { + return undefined; + } + const sql = this.readString(this.asRecord(sqlGeneration)?.sql) ?? input.run.sql; + return { + runId: input.run.runId, + datasourceId: input.datasourceId, + category: "provider_output_summary", + stableId: this.stableHashId({ + runId: input.run.runId, + provider: input.run.provider, + model: input.run.model, + sqlHash: sql ? this.hash(sql) : undefined + }), + summary: `Provider output summarized for ${input.run.provider}${input.run.model ? `/${input.run.model}` : ""}.`, + sizeBytes: JSON.stringify({ provider: input.run.provider, model: input.run.model, sql }).length, + visibility: "internal", + sensitivity: "provider_raw", + reasonCodes: ["provider_output_summarized"], + payload: { + provider: input.run.provider, + model: input.run.model, + sqlHash: sql ? this.hash(sql) : undefined, + sqlPreview: sql ? sql.slice(0, 160) : undefined + } + }; + } + + private buildValidationDiagnosticsArtifact(input: { + run: SqlRun; + datasourceId: string; + }): Text2SqlV2ArtifactProducerInput | undefined { + const validation = input.run.trace.v2?.sqlValidation; + const checks = validation?.checks ?? []; + const notableChecks = checks.filter((check) => check.status !== "passed"); + if (!validation || notableChecks.length === 0) { + return undefined; + } + const reasonCodes = notableChecks + .map((check) => check.code ?? check.check) + .filter((item): item is string => Boolean(item)); + return { + runId: input.run.runId, + datasourceId: input.datasourceId, + category: "validation_diagnostics", + stableId: this.stableHashId({ + runId: input.run.runId, + checks: notableChecks.map((check) => [check.check, check.status, check.code]) + }), + summary: `Validation diagnostics summarized ${notableChecks.length} non-passing checks.`, + sizeBytes: JSON.stringify(validation).length, + visibility: "user", + sensitivity: "none", + reasonCodes: ["validation_diagnostics_summarized", ...reasonCodes], + payload: { + status: validation.status, + correctable: validation.correctable, + failure: validation.failure + ? { + code: validation.failure.code, + category: validation.failure.category, + terminal: validation.failure.terminal, + correctable: validation.failure.correctable + } + : undefined, + checks: notableChecks.map((check) => ({ + check: check.check, + status: check.status, + code: check.code, + message: check.message + })) + } + }; + } + + private buildCorrectionGroundingArtifact(input: { + run: SqlRun; + datasourceId: string; + }): Text2SqlV2ArtifactProducerInput | undefined { + const sqlGeneration = this.asRecord(input.run.trace.v2?.sqlGeneration); + const grounding = + this.asRecord(sqlGeneration?.correctionGrounding) ?? + this.findCorrectionGrounding(input.run); + if (!grounding) { + return undefined; + } + const evidenceRefs = Array.isArray(grounding.evidenceRefs) + ? grounding.evidenceRefs.filter((item): item is string => typeof item === "string") + : []; + const retryReason = this.readString(grounding.retryReason) ?? "correction_retry"; + const failureCode = this.readString(grounding.failureCode); + return { + runId: input.run.runId, + datasourceId: input.datasourceId, + category: "correction_grounding", + stableId: this.stableHashId({ + runId: input.run.runId, + retryReason, + failureCode, + failedSqlRef: this.readString(grounding.failedSqlRef) + }), + summary: `Correction grounding summarized retry reason ${retryReason}.`, + sizeBytes: JSON.stringify(grounding).length, + visibility: "user", + sensitivity: "none", + evidenceRefs, + reasonCodes: [ + "correction_grounding_summarized", + ...(failureCode ? [failureCode] : []) + ], + payload: { + failedSqlRef: this.readString(grounding.failedSqlRef), + failedSqlPreview: this.readString(grounding.failedSqlPreview), + retryReason, + failureCode, + failureCategory: this.readString(grounding.failureCategory), + attemptCount: grounding.attemptCount, + maxAttempts: grounding.maxAttempts, + evidenceRefs + } + }; + } + + private buildExecutionPreviewArtifact(input: { + run: SqlRun; + datasourceId: string; + }): Text2SqlV2ArtifactProducerInput | undefined { + const rows = input.run.rows ?? []; + const columns = input.run.columns ?? []; + const previewSize = JSON.stringify({ rows, columns }).length; + if ( + rows.length <= EXECUTION_PREVIEW_ROW_THRESHOLD && + previewSize <= EXECUTION_PREVIEW_SIZE_THRESHOLD + ) { + return undefined; + } + return { + runId: input.run.runId, + datasourceId: input.datasourceId, + category: "execution_preview", + stableId: this.stableHashId({ + runId: input.run.runId, + rowCount: rows.length, + columns + }), + summary: `Execution preview compacted ${rows.length} rows and ${columns.length} columns.`, + sizeBytes: previewSize, + visibility: "user", + sensitivity: "none", + reasonCodes: ["execution_preview_compacted"], + payload: { + rowCount: rows.length, + columns, + rowsPreview: rows.slice(0, EXECUTION_PREVIEW_ROW_THRESHOLD) + } + }; + } + + private appendArtifactWarnings( + stages: NonNullable["stages"], + warnings: string[] + ): NonNullable["stages"] { + return stages.map((stage) => + stage.stage === "answer" + ? { + ...stage, + warnings: Array.from(new Set([...(stage.warnings ?? []), ...warnings])) + } + : stage + ); + } + + private uniqueRefs(refs: Text2SqlV2ArtifactRefV1[]): Text2SqlV2ArtifactRefV1[] { + return Array.from(new Map(refs.map((ref) => [ref.id, ref])).values()); + } + + private resolvePolicy( + category: Text2SqlV2ArtifactRefCategoryV1 + ): Text2SqlV2ArtifactCategoryPolicy { + return ( + TEXT2SQL_V2_ARTIFACT_CATEGORY_POLICIES[ + category as (typeof REQUIRED_TEXT2SQL_V2_ARTIFACT_CATEGORIES)[number] + ] ?? { + visibility: "internal", + sensitivity: "sensitive", + allowPayload: false, + reasonCode: "artifact_ref_summarized" + } + ); + } + + private shouldPersistPayload( + policy: Text2SqlV2ArtifactCategoryPolicy, + sensitivity: ArtifactSensitivity + ): boolean { + return ( + policy.allowPayload && + sensitivity !== "provider_raw" && + sensitivity !== "permission_filtered" && + sensitivity !== "sensitive" + ); + } + + private uniqueStrings(values: string[]): string[] { + return Array.from( + new Set(values.map((value) => value.trim()).filter((value) => value.length > 0)) + ); + } + + private stableHashId(value: unknown): string { + return this.hash(value).slice("sha256:".length, "sha256:".length + 16); + } + + private findCorrectionGrounding(run: SqlRun): Record | undefined { + for (const stage of run.trace.v2?.stages ?? []) { + if (stage.stage !== "correct") { + continue; + } + const grounding = this.asRecord(stage.metadata)?.correctionGrounding; + const record = this.asRecord(grounding); + if (record) { + return record; + } + } + return undefined; + } + + private asRecord(value: unknown): Record | undefined { + return typeof value === "object" && value !== null && !Array.isArray(value) + ? (value as Record) + : undefined; + } + + private readString(value: unknown): string | undefined { + return typeof value === "string" && value.trim().length > 0 + ? value + : undefined; + } + + private hash(value: unknown): string { + return `sha256:${createHash("sha256") + .update(JSON.stringify(value)) + .digest("hex")}`; + } +} diff --git a/apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifacts.ts b/apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifacts.ts new file mode 100644 index 0000000..3e6db60 --- /dev/null +++ b/apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifacts.ts @@ -0,0 +1,202 @@ +import type { + Text2SqlV2FailureSemantic, + Text2SqlV2LoopEvidence, + Text2SqlV2ProviderMetadata, + Text2SqlV2RunArtifact, + Text2SqlV2StageArtifact, + Text2SqlV2StageName, + Text2SqlV2TerminationReason +} from "@text2sql/shared-types"; +import { TEXT2SQL_V2_STAGE_ORDER } from "../contracts/text2sql-v2.types"; + +const nowIso = (): string => new Date().toISOString(); + +const mergeUnique = ( + current: string[] | undefined, + next: string[] | undefined +): string[] | undefined => { + const merged = [...(current ?? []), ...(next ?? [])] + .map((item) => item.trim()) + .filter((item) => item.length > 0); + return merged.length > 0 ? Array.from(new Set(merged)) : undefined; +}; + +const mergeMetadata = ( + current: Record | undefined, + next: Record | undefined +): Record | undefined => { + if (!current && !next) { + return undefined; + } + return { + ...(current ?? {}), + ...(next ?? {}) + }; +}; + +const cloneStageArtifact = ( + stage: Text2SqlV2StageArtifact +): Text2SqlV2StageArtifact => ({ + ...stage, + ...(stage.warnings ? { warnings: [...stage.warnings] } : {}), + ...(stage.evidenceIds ? { evidenceIds: [...stage.evidenceIds] } : {}), + ...(stage.provider ? { provider: { ...stage.provider } } : {}), + ...(stage.failure ? { failure: { ...stage.failure } } : {}), + ...(stage.metadata ? { metadata: { ...stage.metadata } } : {}) +}); + +const createSkippedStageArtifact = ( + stage: Text2SqlV2StageName +): Text2SqlV2StageArtifact => ({ + stage, + status: "skipped" +}); + +export interface Text2SqlV2StageLifecycle { + startStage: (input: { + stage: Text2SqlV2StageName; + provider?: Text2SqlV2ProviderMetadata; + warnings?: string[]; + evidenceIds?: string[]; + metadata?: Record; + }) => Text2SqlV2StageArtifact; + completeStage: (input: { + stage: Text2SqlV2StageName; + status?: Text2SqlV2StageArtifact["status"]; + provider?: Text2SqlV2ProviderMetadata; + warnings?: string[]; + evidenceIds?: string[]; + failure?: Text2SqlV2FailureSemantic; + metadata?: Record; + }) => Text2SqlV2StageArtifact; + getStage: (stage: Text2SqlV2StageName) => Text2SqlV2StageArtifact | undefined; + listStages: () => Text2SqlV2StageArtifact[]; + toRunArtifact: (input?: { + contextPack?: Text2SqlV2RunArtifact["contextPack"]; + semanticPlan?: Text2SqlV2RunArtifact["semanticPlan"]; + sqlGeneration?: Text2SqlV2RunArtifact["sqlGeneration"]; + sqlValidation?: Text2SqlV2RunArtifact["sqlValidation"]; + runtimePlan?: Text2SqlV2RunArtifact["runtimePlan"]; + artifactRefs?: Text2SqlV2RunArtifact["artifactRefs"]; + smartDefaults?: Text2SqlV2RunArtifact["smartDefaults"]; + loopEvidence?: Text2SqlV2LoopEvidence[]; + terminationReason?: Text2SqlV2TerminationReason; + }) => Text2SqlV2RunArtifact; +} + +const computeDurationMs = ( + startedAt: string | undefined, + endedAt: string | undefined +): number | undefined => { + if (!startedAt || !endedAt) { + return undefined; + } + const started = Date.parse(startedAt); + const ended = Date.parse(endedAt); + if (Number.isNaN(started) || Number.isNaN(ended)) { + return undefined; + } + return Math.max(0, ended - started); +}; + +export const createText2SqlV2StageLifecycle = (): Text2SqlV2StageLifecycle => { + const stageMap = new Map(); + + const upsert = ( + stage: Text2SqlV2StageName, + patch: Partial + ): Text2SqlV2StageArtifact => { + const existing = stageMap.get(stage); + const startedAt = patch.startedAt ?? existing?.startedAt; + const endedAt = patch.endedAt ?? existing?.endedAt; + const next: Text2SqlV2StageArtifact = { + stage, + status: patch.status ?? existing?.status ?? "success", + startedAt, + endedAt, + durationMs: + patch.durationMs ?? + computeDurationMs(startedAt, endedAt) ?? + existing?.durationMs, + warnings: mergeUnique(existing?.warnings, patch.warnings), + evidenceIds: mergeUnique(existing?.evidenceIds, patch.evidenceIds), + provider: patch.provider ?? existing?.provider, + failure: patch.failure ?? existing?.failure, + metadata: mergeMetadata(existing?.metadata, patch.metadata) + }; + stageMap.set(stage, next); + return cloneStageArtifact(next); + }; + + return { + startStage: (input) => { + const current = stageMap.get(input.stage); + const startedAt = current?.startedAt ?? nowIso(); + return upsert(input.stage, { + status: current?.status ?? "success", + startedAt, + endedAt: undefined, + durationMs: undefined, + failure: undefined, + provider: input.provider, + warnings: input.warnings, + evidenceIds: input.evidenceIds, + metadata: input.metadata + }); + }, + completeStage: (input) => { + const current = stageMap.get(input.stage); + const startedAt = current?.startedAt ?? nowIso(); + const endedAt = nowIso(); + return upsert(input.stage, { + status: input.status ?? current?.status ?? "success", + startedAt, + endedAt, + durationMs: computeDurationMs(startedAt, endedAt), + provider: input.provider, + warnings: input.warnings, + evidenceIds: input.evidenceIds, + failure: input.failure, + metadata: input.metadata + }); + }, + getStage: (stage) => { + const current = stageMap.get(stage); + return current ? cloneStageArtifact(current) : undefined; + }, + listStages: () => + TEXT2SQL_V2_STAGE_ORDER.map( + (stage) => stageMap.get(stage) ?? createSkippedStageArtifact(stage) + ).map((item) => cloneStageArtifact(item)), + toRunArtifact: (input) => ({ + version: "v2", + stageOrder: [...TEXT2SQL_V2_STAGE_ORDER], + stages: TEXT2SQL_V2_STAGE_ORDER.map( + (stage) => stageMap.get(stage) ?? createSkippedStageArtifact(stage) + ).map((item) => cloneStageArtifact(item)), + contextPack: input?.contextPack, + semanticPlan: input?.semanticPlan, + sqlGeneration: input?.sqlGeneration, + sqlValidation: input?.sqlValidation, + runtimePlan: input?.runtimePlan, + artifactRefs: input?.artifactRefs, + smartDefaults: input?.smartDefaults, + loopEvidence: input?.loopEvidence ? [...input.loopEvidence] : undefined, + terminationReason: input?.terminationReason + }) + }; +}; + +export const toText2SqlV2FailureSemantic = ( + error: unknown, + options?: Partial +): Text2SqlV2FailureSemantic => { + const message = error instanceof Error ? error.message : String(error); + return { + code: options?.code ?? "TEXT2SQL_V2_STAGE_FAILED", + message, + category: options?.category ?? "unknown", + terminal: options?.terminal ?? true, + correctable: options?.correctable ?? false + }; +}; diff --git a/apps/backend/src/modules/conversation/chat/application/execute-message.usecase.ts b/apps/backend/src/modules/conversation/chat/application/execute-message.usecase.ts index 21b1103..75ebd4b 100644 --- a/apps/backend/src/modules/conversation/chat/application/execute-message.usecase.ts +++ b/apps/backend/src/modules/conversation/chat/application/execute-message.usecase.ts @@ -1,19 +1,9 @@ import { Injectable } from "@nestjs/common"; -import type { ChatMessage, ContextEnvelope, SqlRun } from "@text2sql/shared-types"; -import { v4 as uuidv4 } from "uuid"; -import { GraphBuilderService } from "../../agent/graph/graph.builder"; -import { DatasourceRegistryService } from "../../../governance/datasource/datasource-registry.service"; -import { DatasourceService } from "../../../governance/datasource/datasource.service"; -import { RedisBufferService } from "../../../platform/data/cache/index"; -import { ChatRepository } from "../../../platform/data/persistence/index"; -import { ChatDeliveryEnrichmentService } from "./shared/chat-delivery-enrichment.service"; +import type { ContextEnvelope, SqlRun } from "@text2sql/shared-types"; import { - ChatPolicyGuardService, type ChatPolicyActorInput } from "./shared/chat-policy-guard.service"; -import { ChatPostRunHooksService } from "./shared/chat-post-run-hooks.service"; -import { ChatRunPersistenceService } from "./shared/chat-run-persistence.service"; -import { DomainError } from "../../../../common/domain-error"; +import { Text2SQLWorkflowRunner } from "../../application/workflow/text2sql-workflow-runner.service"; export interface ExecuteMessageInput { sessionId: string; @@ -25,94 +15,15 @@ export interface ExecuteMessageInput { @Injectable() export class ExecuteMessageUsecase { - constructor( - private readonly graphBuilder: GraphBuilderService, - private readonly datasourceService: DatasourceService, - private readonly datasourceRegistry: DatasourceRegistryService, - private readonly redisBuffer: RedisBufferService, - private readonly repository: ChatRepository, - private readonly chatPolicyGuardService: ChatPolicyGuardService, - private readonly chatDeliveryEnrichmentService: ChatDeliveryEnrichmentService, - private readonly chatRunPersistenceService: ChatRunPersistenceService, - private readonly chatPostRunHooksService: ChatPostRunHooksService - ) {} + constructor(private readonly workflowRunner: Text2SQLWorkflowRunner) {} async executeMessage(input: ExecuteMessageInput): Promise { - const session = await this.repository.getSessionById(input.sessionId); - if (!session) { - throw new DomainError("SESSION_NOT_FOUND", "会话不存在", 404, { - sessionId: input.sessionId - }); - } - await this.chatPolicyGuardService.assertSessionWritableByPolicy(session); - const datasource = await this.datasourceService.assertDatasourceAvailable( - session.datasource - ); - const sqlAccessContext = await this.chatPolicyGuardService.resolveSqlAccessContext( - session, - input.actor - ); - - const userMessage: ChatMessage = { - id: uuidv4(), - sessionId: input.sessionId, - role: "user", - content: input.message, - createdAt: new Date().toISOString() - }; - await this.redisBuffer.bufferMessage(userMessage); - const userPersistResult = await this.repository.persistMessage(userMessage); - await this.repository.ensureSessionTitleFromFirstMessage( - input.sessionId, - input.message - ); - - const run = await this.graphBuilder.run({ - runId: uuidv4(), + return this.workflowRunner.runSync({ sessionId: input.sessionId, - question: input.message, - datasourceId: session.datasource, - datasourceType: datasource.type, - modelCatalogId: session.modelCatalogId ?? undefined, + message: input.message, + requestId: input.requestId, contextEnvelope: input.contextEnvelope, - accessContext: sqlAccessContext, - traceContext: { - source: "chat", - route: "/api/v1/sessions/:sessionId/messages", - requestId: input.requestId - } + actor: input.actor }); - - const finalRun = this.applyRejectedFallback(run, session.datasource); - const runWithDelivery = - await this.chatDeliveryEnrichmentService.attachDeliveryContract(finalRun); - await this.chatRunPersistenceService.persistAssistantAndRun({ - sessionId: input.sessionId, - run: runWithDelivery, - userPrimaryPersisted: userPersistResult.primaryPersisted - }); - await this.chatPostRunHooksService.run({ - session, - run: runWithDelivery, - requestId: input.requestId - }); - return runWithDelivery; - } - - private applyRejectedFallback(run: SqlRun, datasource: string): SqlRun { - if (run.status !== "rejected") { - return run; - } - if (!this.datasourceRegistry.shouldFallbackOnReject(datasource)) { - return run; - } - if (run.answer) { - return run; - } - return { - ...run, - answer: - "请求触发了只读安全策略，本次未执行 SQL。你可以改为查询统计口径或时间范围，我会继续协助。" - }; } } diff --git a/apps/backend/src/modules/conversation/chat/application/run-view.usecase.ts b/apps/backend/src/modules/conversation/chat/application/run-view.usecase.ts index 53e1625..6a98d61 100644 --- a/apps/backend/src/modules/conversation/chat/application/run-view.usecase.ts +++ b/apps/backend/src/modules/conversation/chat/application/run-view.usecase.ts @@ -1,6 +1,7 @@ import { Injectable } from "@nestjs/common"; import type { ChatMessage, ChatSessionView, Datasource, Session, SqlRun } from "@text2sql/shared-types"; import { DomainError } from "../../../../common/domain-error"; +import { assertSupportedV2RunReadModel } from "../../projection/read-model/run-view-support.guard"; import { DatasourceService } from "../../../governance/datasource/datasource.service"; import { RedisBufferService } from "../../../platform/data/cache/index"; import { ChatRepository } from "../../../platform/data/persistence/index"; @@ -54,7 +55,7 @@ export class RunViewUsecase { const messages = await this.listMessages(input); const latestRunRaw = await this.repository.getLatestRunBySessionId(input.sessionId); const latestRun = latestRunRaw - ? await this.chatDeliveryEnrichmentService.attachDeliveryContract(latestRunRaw) + ? await this.attachSupportedDelivery(latestRunRaw) : undefined; return { session: await this.mergeDatasourceMetadata(session), @@ -72,6 +73,13 @@ export class RunViewUsecase { if (!session) { throw new DomainError("RUN_NOT_FOUND", "运行记录不存在", 404, { runId }); } + return this.attachSupportedDelivery(run); + } + + private async attachSupportedDelivery(run: SqlRun): Promise { + assertSupportedV2RunReadModel(run, { + unsupportedMessage: "该运行记录为历史兼容结构，需迁移后才能读取。" + }); return this.chatDeliveryEnrichmentService.attachDeliveryContract(run); } diff --git a/apps/backend/src/modules/conversation/chat/application/save-view-from-run.usecase.ts b/apps/backend/src/modules/conversation/chat/application/save-view-from-run.usecase.ts index bee68e7..4e7360d 100644 --- a/apps/backend/src/modules/conversation/chat/application/save-view-from-run.usecase.ts +++ b/apps/backend/src/modules/conversation/chat/application/save-view-from-run.usecase.ts @@ -1,6 +1,7 @@ import { createHash } from "node:crypto"; import { Inject, Injectable, Optional } from "@nestjs/common"; import { DomainError } from "../../../../common/domain-error"; +import { assertSupportedV2RunReadModel } from "../../projection/read-model/run-view-support.guard"; import { ChatRepository } from "../../../platform/data/persistence"; import { ModelingGraphRepository } from "../../../platform/data/persistence/modeling-graph.repository"; import { ModelingGraphValidator } from "../../../platform/data/persistence/modeling-graph.validator"; @@ -68,6 +69,15 @@ export class SaveViewFromRunUsecase { if (!run) { throw new DomainError("RUN_NOT_FOUND", "运行记录不存在", 404, { runId }); } + + const session = await this.chatRepository.getSessionById(run.sessionId); + if (!session) { + throw new DomainError("RUN_NOT_FOUND", "运行记录不存在", 404, { runId }); + } + assertSupportedV2RunReadModel(run, { + unsupportedMessage: "该运行记录为历史兼容结构，需迁移后才能保存为视图。" + }); + const sql = run.sql?.trim(); if (!sql) { throw new DomainError( @@ -77,11 +87,6 @@ export class SaveViewFromRunUsecase { { runId } ); } - - const session = await this.chatRepository.getSessionById(run.sessionId); - if (!session) { - throw new DomainError("RUN_NOT_FOUND", "运行记录不存在", 404, { runId }); - } const workspaceId = this.requireTrimmed(session.workspaceId ?? "", "workspaceId"); const datasourceId = this.requireTrimmed(session.datasource, "datasourceId"); diff --git a/apps/backend/src/modules/conversation/chat/application/shared/chat-delivery-enrichment.service.ts b/apps/backend/src/modules/conversation/chat/application/shared/chat-delivery-enrichment.service.ts index 7a235a5..46de47d 100644 --- a/apps/backend/src/modules/conversation/chat/application/shared/chat-delivery-enrichment.service.ts +++ b/apps/backend/src/modules/conversation/chat/application/shared/chat-delivery-enrichment.service.ts @@ -1,7 +1,6 @@ import { Inject, Injectable } from "@nestjs/common"; import type { DeliveryContract, - PromptTemplateTraceEvidenceCompat, SqlRun } from "@text2sql/shared-types"; import { @@ -102,50 +101,31 @@ export class ChatDeliveryEnrichmentService { } withPromptTemplateEvidence(run: SqlRun): SqlRun { - const traceWithCompat = run.trace as SqlRun["trace"] & { - prompt_template?: unknown; - prompt_template_evidence?: unknown; - templateEvidence?: unknown; - effectiveContextSummary?: unknown; - effective_context_summary?: unknown; - conflictHint?: unknown; - context_conflict_hint?: unknown; - }; - const evidenceWithCompat = run.delivery?.evidence as - | (NonNullable["evidence"] & { - effectiveContextSummary?: unknown; - effective_context_summary?: unknown; - conflictHint?: unknown; - context_conflict_hint?: unknown; - }) - | undefined; const tracePromptTemplate = this.normalizePromptTemplateTraceEvidence( - traceWithCompat.promptTemplate ?? - traceWithCompat.prompt_template ?? - traceWithCompat.prompt_template_evidence ?? - traceWithCompat.templateEvidence + run.trace.promptTemplate ); const evidencePromptTemplate = this.normalizePromptTemplateTraceEvidence( run.delivery?.evidence?.promptTemplate ); const traceEffectiveContextSummary = this.normalizeEffectiveContextSummary( - traceWithCompat.effectiveContextSummary ?? - traceWithCompat.effective_context_summary + run.trace.effectiveContextSummary ); const evidenceEffectiveContextSummary = this.normalizeEffectiveContextSummary( - evidenceWithCompat?.effectiveContextSummary ?? - evidenceWithCompat?.effective_context_summary + run.delivery?.evidence?.effectiveContextSummary ); const traceConflictHint = this.normalizeContextConflictHint( - traceWithCompat.conflictHint ?? traceWithCompat.context_conflict_hint + run.trace.conflictHint ); const evidenceConflictHint = this.normalizeContextConflictHint( - evidenceWithCompat?.conflictHint ?? evidenceWithCompat?.context_conflict_hint + run.delivery?.evidence?.conflictHint ); const resolvedPromptTemplate = evidencePromptTemplate ?? tracePromptTemplate; const resolvedEffectiveContextSummary = evidenceEffectiveContextSummary ?? traceEffectiveContextSummary; const resolvedConflictHint = evidenceConflictHint ?? traceConflictHint; + const resolvedTraceV2 = run.trace.v2; + const resolvedEvidenceV2 = + run.delivery?.evidence?.v2 ?? this.buildEvidenceV2FromTrace(run.trace.v2); const normalizedTrace = resolvedPromptTemplate ? { @@ -160,6 +140,11 @@ export class ChatDeliveryEnrichmentService { ? { conflictHint: resolvedConflictHint } + : {}), + ...(resolvedTraceV2 + ? { + v2: resolvedTraceV2 + } : {}) } : ({ @@ -173,6 +158,11 @@ export class ChatDeliveryEnrichmentService { ? { conflictHint: resolvedConflictHint } + : {}), + ...(resolvedTraceV2 + ? { + v2: resolvedTraceV2 + } : {}) } as SqlRun["trace"]); @@ -181,7 +171,11 @@ export class ChatDeliveryEnrichmentService { } const nextEvidence = - run.delivery.evidence || resolvedPromptTemplate + run.delivery.evidence || + resolvedPromptTemplate || + resolvedEffectiveContextSummary || + resolvedConflictHint || + resolvedEvidenceV2 ? { runId: run.delivery.evidence?.runId ?? run.runId, ...run.delivery.evidence, @@ -199,6 +193,11 @@ export class ChatDeliveryEnrichmentService { ? { conflictHint: resolvedConflictHint } + : {}), + ...(resolvedEvidenceV2 + ? { + v2: resolvedEvidenceV2 + } : {}) } : run.delivery.evidence; @@ -219,26 +218,25 @@ export class ChatDeliveryEnrichmentService { if (!this.isRecord(value)) { return undefined; } - const candidate = value as PromptTemplateTraceEvidenceCompat; - const templateId = this.readNonEmptyString(candidate.templateId ?? candidate.template_id); + const candidate = value as { + templateId?: unknown; + scope?: unknown; + version?: unknown; + fallbackReason?: unknown; + scene?: unknown; + }; + const templateId = this.readNonEmptyString(candidate.templateId); const scope = this.normalizePromptTemplateScope( - candidate.scope ?? - candidate.scope_type ?? - candidate.template_scope ?? - (this.isRecord(value) ? (value.scopeType as unknown) : undefined) + candidate.scope ); const version = this.readPositiveInteger( - candidate.version ?? - candidate.template_version ?? - (this.isRecord(value) ? (value.templateVersion as unknown) : undefined) + candidate.version ); const fallbackReason = this.readNonEmptyString( - candidate.fallbackReason ?? - candidate.fallback_reason ?? - (this.isRecord(value) ? (value.fallback_reason_code as unknown) : undefined) + candidate.fallbackReason ); const scene = this.normalizePromptTemplateScene( - candidate.scene ?? candidate.scene_name ?? candidate.template_scene + candidate.scene ); if (!templateId && !scope && version === undefined && !fallbackReason && !scene) { @@ -449,6 +447,48 @@ export class ChatDeliveryEnrichmentService { ); } + private buildEvidenceV2FromTrace( + traceV2: SqlRun["trace"]["v2"] | undefined + ): NonNullable["evidence"]>["v2"] | undefined { + if (!traceV2) { + return undefined; + } + return { + version: traceV2.version, + stageOrder: traceV2.stageOrder, + stageArtifacts: traceV2.stages, + contextPack: traceV2.contextPack, + semanticPlan: this.toSafeSemanticPlan(traceV2.semanticPlan), + sqlGeneration: traceV2.sqlGeneration, + sqlValidation: traceV2.sqlValidation, + planLedger: + traceV2.planLedger ?? + traceV2.sqlValidation?.ledgerFulfillment ?? + traceV2.semanticPlan?.planLedger?.summary, + runtimePlan: traceV2.runtimePlan, + artifactRefs: traceV2.artifactRefs, + smartDefaults: traceV2.smartDefaults, + loopEvidence: traceV2.loopEvidence, + terminationReason: traceV2.terminationReason, + failure: + traceV2.sqlValidation?.failure ?? + traceV2.stages + .slice() + .reverse() + .find((stage) => stage.status === "failed")?.failure + }; + } + + private toSafeSemanticPlan( + semanticPlan: T + ): T { + if (!semanticPlan) { + return semanticPlan; + } + const { planLedger: _planLedger, ...safePlan } = semanticPlan; + return safePlan as T; + } + private async loadReplayRecords(runId: string): Promise { const records = await this.knowledgeFacade.rag.replay.listByRunId(runId); return records.map((item) => ({ diff --git a/apps/backend/src/modules/conversation/chat/application/stream-message.usecase.ts b/apps/backend/src/modules/conversation/chat/application/stream-message.usecase.ts index 0250c61..bbda059 100644 --- a/apps/backend/src/modules/conversation/chat/application/stream-message.usecase.ts +++ b/apps/backend/src/modules/conversation/chat/application/stream-message.usecase.ts @@ -1,30 +1,13 @@ import { Injectable } from "@nestjs/common"; import type { - ChatMessage, ContextEnvelope, ChatStreamEvent, SqlRun } from "@text2sql/shared-types"; -import { v4 as uuidv4 } from "uuid"; -import { DomainError } from "../../../../common/domain-error"; -import { GraphBuilderService } from "../../agent/graph/graph.builder"; import { - resolveAgentReasoningStage, - resolveAgentReasoningTitle, - resolveAgentStepLifecycle -} from "../../agent/graph/agent-step-metadata"; -import { SqlToolRegistryService } from "../../agent/sql/tools/sql-tool-registry.service"; -import { DatasourceRegistryService } from "../../../governance/datasource/datasource-registry.service"; -import { DatasourceService } from "../../../governance/datasource/datasource.service"; -import { RedisBufferService } from "../../../platform/data/cache/index"; -import { ChatRepository } from "../../../platform/data/persistence/index"; -import { ChatDeliveryEnrichmentService } from "./shared/chat-delivery-enrichment.service"; -import { - ChatPolicyGuardService, type ChatPolicyActorInput } from "./shared/chat-policy-guard.service"; -import { ChatPostRunHooksService } from "./shared/chat-post-run-hooks.service"; -import { ChatRunPersistenceService } from "./shared/chat-run-persistence.service"; +import { Text2SQLWorkflowRunner } from "../../application/workflow/text2sql-workflow-runner.service"; export interface StreamMessageInput { sessionId: string; @@ -37,254 +20,16 @@ export interface StreamMessageInput { @Injectable() export class StreamMessageUsecase { - constructor( - private readonly graphBuilder: GraphBuilderService, - private readonly sqlToolRegistry: SqlToolRegistryService, - private readonly datasourceService: DatasourceService, - private readonly datasourceRegistry: DatasourceRegistryService, - private readonly redisBuffer: RedisBufferService, - private readonly repository: ChatRepository, - private readonly chatPolicyGuardService: ChatPolicyGuardService, - private readonly chatDeliveryEnrichmentService: ChatDeliveryEnrichmentService, - private readonly chatRunPersistenceService: ChatRunPersistenceService, - private readonly chatPostRunHooksService: ChatPostRunHooksService - ) {} + constructor(private readonly workflowRunner: Text2SQLWorkflowRunner) {} async streamMessage(input: StreamMessageInput): Promise { - const session = await this.repository.getSessionById(input.sessionId); - if (!session) { - throw new DomainError("SESSION_NOT_FOUND", "会话不存在", 404, { - sessionId: input.sessionId - }); - } - await this.chatPolicyGuardService.assertSessionWritableByPolicy(session); - const datasource = await this.datasourceService.assertDatasourceAvailable( - session.datasource - ); - const sqlAccessContext = await this.chatPolicyGuardService.resolveSqlAccessContext( - session, - input.actor - ); - - const runId = uuidv4(); - const userMessage: ChatMessage = { - id: uuidv4(), + return this.workflowRunner.runStream({ sessionId: input.sessionId, - role: "user", - content: input.message, - createdAt: new Date().toISOString() - }; - await this.redisBuffer.bufferMessage(userMessage); - const userPersistResult = await this.repository.persistMessage(userMessage); - await this.repository.ensureSessionTitleFromFirstMessage( - input.sessionId, - input.message - ); - - const emit = async (type: ChatStreamEvent["type"], data: ChatStreamEvent["data"]) => { - await input.onEvent({ - type, - runId, - sessionId: input.sessionId, - at: new Date().toISOString(), - data - }); - }; - - await emit("start", { - requestId: input.requestId ?? null + message: input.message, + requestId: input.requestId, + onEvent: input.onEvent, + contextEnvelope: input.contextEnvelope, + actor: input.actor }); - - const toolCalls: NonNullable["toolCalls"]> = []; - let stepSequence = 0; - - try { - const run = await this.graphBuilder.run( - { - runId, - sessionId: input.sessionId, - question: input.message, - datasourceId: session.datasource, - datasourceType: datasource.type, - modelCatalogId: session.modelCatalogId ?? undefined, - contextEnvelope: input.contextEnvelope, - accessContext: sqlAccessContext, - traceContext: { - source: "chat", - route: "/api/v1/sessions/:sessionId/messages/stream", - requestId: input.requestId - } - }, - { - streamMode: true, - tools: this.sqlToolRegistry.getToolsForDatasource(datasource, { - accessContext: sqlAccessContext - }), - onLlmEvent: async (event) => { - if (event.type === "text-delta") { - await emit("text-delta", { - text: event.text - }); - return; - } - - if (event.type === "tool-call") { - toolCalls.push({ - toolName: event.toolName, - toolCallId: event.toolCallId, - status: "called", - detail: JSON.stringify(event.input ?? {}), - at: new Date().toISOString() - }); - await emit("tool-call", { - toolName: event.toolName, - toolCallId: event.toolCallId, - input: event.input - }); - return; - } - - if (event.type === "tool-result") { - toolCalls.push({ - toolName: event.toolName, - toolCallId: event.toolCallId, - status: "result", - detail: JSON.stringify(event.output ?? {}), - at: new Date().toISOString() - }); - await emit("tool-result", { - toolName: event.toolName, - toolCallId: event.toolCallId, - output: event.output - }); - return; - } - - toolCalls.push({ - toolName: event.toolName, - toolCallId: event.toolCallId, - status: "error", - detail: event.message, - at: new Date().toISOString() - }); - await emit("tool-error", { - toolName: event.toolName, - toolCallId: event.toolCallId, - message: event.message - }); - }, - onStep: async ({ step }) => { - const streamSequence = step.sequence ?? stepSequence + 1; - stepSequence = Math.max(stepSequence, streamSequence); - const stepTimestamp = - step.at ?? step.endedAt ?? step.startedAt ?? new Date().toISOString(); - await emit("state", { - node: step.node, - status: step.status, - stepId: step.stepId ?? `${runId}:${step.node}:${streamSequence}`, - sequence: streamSequence, - lifecycle: step.lifecycle ?? resolveAgentStepLifecycle(step.status), - detail: step.detail ?? "", - stage: resolveAgentReasoningStage(step.node), - title: resolveAgentReasoningTitle(step.node), - at: stepTimestamp, - startedAt: step.startedAt, - endedAt: step.endedAt, - durationMs: step.durationMs, - inputSummary: step.inputSummary, - outputSummary: step.outputSummary, - errorSummary: step.errorSummary - }); - } - } - ); - - const finalRun = this.applyRejectedFallback(run, session.datasource); - finalRun.trace.streamStatus = finalRun.error ? "failed" : "completed"; - finalRun.trace.toolCalls = toolCalls; - const runWithDelivery = - await this.chatDeliveryEnrichmentService.attachDeliveryContract(finalRun); - if (runWithDelivery.error) { - await emit("error", { - code: - runWithDelivery.status === "rejected" ? "SQL_READONLY_REJECTED" : undefined, - message: runWithDelivery.error, - details: null - }); - } - await emit("finish", { - status: runWithDelivery.status, - rowCount: runWithDelivery.rows?.length ?? 0, - delivery: runWithDelivery.delivery - }); - await this.chatRunPersistenceService.persistAssistantAndRun({ - sessionId: input.sessionId, - run: runWithDelivery, - userPrimaryPersisted: userPersistResult.primaryPersisted - }); - await this.chatPostRunHooksService.run({ - session, - run: runWithDelivery, - requestId: input.requestId - }); - return runWithDelivery; - } catch (error) { - const messageText = error instanceof Error ? error.message : String(error); - const run: SqlRun = { - runId, - sessionId: input.sessionId, - question: input.message, - status: "failed", - provider: session.modelProvider ?? "unknown", - model: session.modelName ?? undefined, - error: messageText, - trace: { - runId, - provider: session.modelProvider ?? "unknown", - retryCount: 0, - steps: [], - streamStatus: "failed", - toolCalls - }, - llmRaw: null, - createdAt: new Date().toISOString() - }; - const domainError = error instanceof DomainError ? error : undefined; - await emit("error", { - code: domainError?.code, - message: messageText, - details: (domainError?.details as Record | undefined) ?? null - }); - const runWithDelivery = - await this.chatDeliveryEnrichmentService.attachDeliveryContract(run); - await this.chatRunPersistenceService.persistAssistantAndRun({ - sessionId: input.sessionId, - run: runWithDelivery, - userPrimaryPersisted: userPersistResult.primaryPersisted - }); - await this.chatPostRunHooksService.run({ - session, - run: runWithDelivery, - requestId: input.requestId - }); - return runWithDelivery; - } - } - - private applyRejectedFallback(run: SqlRun, datasource: string): SqlRun { - if (run.status !== "rejected") { - return run; - } - if (!this.datasourceRegistry.shouldFallbackOnReject(datasource)) { - return run; - } - if (run.answer) { - return run; - } - return { - ...run, - answer: - "请求触发了只读安全策略，本次未执行 SQL。你可以改为查询统计口径或时间范围，我会继续协助。" - }; } } diff --git a/apps/backend/src/modules/conversation/chat/chat.module.ts b/apps/backend/src/modules/conversation/chat/chat.module.ts index b893547..ffd6025 100644 --- a/apps/backend/src/modules/conversation/chat/chat.module.ts +++ b/apps/backend/src/modules/conversation/chat/chat.module.ts @@ -1,13 +1,10 @@ import { Module } from "@nestjs/common"; -import { AgentModule } from "../agent/agent.module"; import { PlatformDataPersistenceModule } from "../../platform/data/persistence.module"; import { GovernanceAccessModule } from "../../governance/access/access.module"; import { DatasourceModule } from "../../governance/datasource/datasource.module"; import { LlmModule } from "../../llm/llm.module"; import { ObservabilityModule } from "../../observability/observability.module"; import { KnowledgeModule } from "../../knowledge/knowledge.module"; -import { DeliveryContractMapper } from "../delivery/delivery-contract.mapper"; -import { SandboxRuntimeService } from "../delivery/sandbox/sandbox-runtime.service"; import { ChatController } from "./chat.controller"; import { ChatService } from "./chat.service"; import { ExecuteMessageUsecase } from "./application/execute-message.usecase"; @@ -15,47 +12,26 @@ import { RunViewUsecase } from "./application/run-view.usecase"; import { SaveViewFromRunUsecase } from "./application/save-view-from-run.usecase"; import { SessionLifecycleUsecase } from "./application/session-lifecycle.usecase"; import { StreamMessageUsecase } from "./application/stream-message.usecase"; -import { ChatDeliveryEnrichmentService } from "./application/shared/chat-delivery-enrichment.service"; -import { ChatPolicyGuardService } from "./application/shared/chat-policy-guard.service"; -import { ChatPostRunHooksService } from "./application/shared/chat-post-run-hooks.service"; -import { ChatRunPersistenceService } from "./application/shared/chat-run-persistence.service"; -import { ChartBiArtifactService } from "../delivery/chartbi/chartbi-artifact.service"; -import { ChartBiResultProfiler } from "../delivery/chartbi/chartbi-result-profiler"; -import { ChartBiIntentParser } from "../delivery/chartbi/chartbi-intent-parser"; -import { ChartBiSpecCompiler } from "../delivery/chartbi/chartbi-spec-compiler"; -import { ChartBiValidator } from "../delivery/chartbi/chartbi-validator"; -import { ChartBiGroundingGuard } from "../delivery/chartbi/chartbi-grounding.guard"; +import { Text2SqlModule } from "../text2sql/text2sql.module"; @Module({ imports: [ - AgentModule, PlatformDataPersistenceModule, GovernanceAccessModule, DatasourceModule, LlmModule, ObservabilityModule, - KnowledgeModule + KnowledgeModule, + Text2SqlModule ], controllers: [ChatController], providers: [ ChatService, - DeliveryContractMapper, - SandboxRuntimeService, SessionLifecycleUsecase, ExecuteMessageUsecase, StreamMessageUsecase, RunViewUsecase, SaveViewFromRunUsecase, - ChatPostRunHooksService, - ChatPolicyGuardService, - ChatRunPersistenceService, - ChatDeliveryEnrichmentService, - ChartBiArtifactService, - ChartBiResultProfiler, - ChartBiIntentParser, - ChartBiSpecCompiler, - ChartBiValidator, - ChartBiGroundingGuard ], exports: [ChatService] }) diff --git a/apps/backend/src/modules/conversation/contracts/text2sql-v2.types.ts b/apps/backend/src/modules/conversation/contracts/text2sql-v2.types.ts new file mode 100644 index 0000000..ee08840 --- /dev/null +++ b/apps/backend/src/modules/conversation/contracts/text2sql-v2.types.ts @@ -0,0 +1,45 @@ +import type { + SemanticContextPackV1, + SemanticPlanV1, + Text2SqlV2ArtifactRefV1, + SqlGenerationArtifactV1, + SqlValidationArtifactV1, + Text2SqlV2RunArtifact, + Text2SqlV2RuntimePlanV1, + Text2SqlV2SmartDefaultsEvidenceV1, + Text2SqlV2StageArtifact, + Text2SqlV2StageName +} from "@text2sql/shared-types"; + +export const TEXT2SQL_V2_STAGE_ORDER: Text2SqlV2StageName[] = [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" +]; + +export interface Text2SqlV2RunContext { + runId: string; + sessionId: string; + question: string; +} + +export interface Text2SqlV2StateMachineResult { + stages: Text2SqlV2StageArtifact[]; + contextPack?: SemanticContextPackV1; + semanticPlan?: SemanticPlanV1; + sqlGeneration?: SqlGenerationArtifactV1; + sqlValidation?: SqlValidationArtifactV1; + runtimePlan?: Text2SqlV2RuntimePlanV1; + artifactRefs?: Text2SqlV2ArtifactRefV1[]; + smartDefaults?: Text2SqlV2SmartDefaultsEvidenceV1; +} + +export type Text2SqlV2MutableRunArtifact = Omit & { + version: "v2"; +}; diff --git a/apps/backend/src/modules/conversation/delivery/delivery-contract.mapper.ts b/apps/backend/src/modules/conversation/delivery/delivery-contract.mapper.ts index 50727ee..860c32b 100644 --- a/apps/backend/src/modules/conversation/delivery/delivery-contract.mapper.ts +++ b/apps/backend/src/modules/conversation/delivery/delivery-contract.mapper.ts @@ -2,8 +2,16 @@ import { Injectable } from "@nestjs/common"; import type { ClarificationDecisionEvidence, DeliveryContract, + DeliveryContextPackSummaryV1, + DeliveryMetadataAnswerSummaryV1, DeliveryEvidenceReplayLog, - SqlRun + SqlCorrectionGroundingV1, + SqlRun, + Text2SqlV2ArtifactRefV1, + Text2SqlV2RunArtifact, + Text2SqlV2RuntimePlanV1, + Text2SqlV2SmartDefaultsEvidenceV1, + Text2SqlV2StageName } from "@text2sql/shared-types"; import { DELIVERY_SANDBOX_REPLAY_KEY, @@ -154,6 +162,16 @@ export class DeliveryContractMapper { const clarificationDecision = this.readClarificationDecisionEvidence(input.run); const sqlCoverage = this.readSqlCoverageEvidence(input.run); const savedPriorSql = this.readSavedPriorSqlEvidence(input.run); + const traceV2Artifact = this.readTraceV2Artifact(input.run); + const contextPackSummary = this.readContextPackSummary( + traceV2Artifact?.contextPack + ); + const metadataAnswer = this.readMetadataAnswerSummary({ + run: input.run, + traceV2: traceV2Artifact, + contextPackSummary + }); + const correctionGrounding = this.readCorrectionGrounding(traceV2Artifact); const invalidInput = replayIndex.invalidPayload; const artifact = input.artifactOverride ?? this.buildArtifact(input.run); const sandboxOutcome = this.applySandboxPostProcess({ @@ -210,7 +228,8 @@ export class DeliveryContractMapper { : undefined, retrievalLogs: replayLogs.length > 0 ? replayLogs : undefined, riskTags: evidenceRiskTags.length > 0 ? evidenceRiskTags : undefined, - semanticVersion: semanticSnapshot.semanticVersion, + semanticVersion: + semanticSnapshot.semanticVersion ?? finalSnapshot.semanticSpineVersion, modelingRevision: semanticSnapshot.modelingRevision ?? finalSnapshot.modelingRevision, semanticSpineVersion: @@ -231,7 +250,33 @@ export class DeliveryContractMapper { conflictHint: traceContextEvidence.conflictHint, clarificationDecision, sqlCoverage, - savedPriorSql + savedPriorSql, + contextPackSummary, + metadataAnswer, + correctionGrounding, + ...(traceV2Artifact + ? { + v2: { + version: traceV2Artifact.version, + stageOrder: traceV2Artifact.stageOrder, + stageArtifacts: traceV2Artifact.stages, + contextPack: traceV2Artifact.contextPack, + semanticPlan: this.toSafeSemanticPlan(traceV2Artifact.semanticPlan), + sqlGeneration: traceV2Artifact.sqlGeneration, + sqlValidation: traceV2Artifact.sqlValidation, + planLedger: + traceV2Artifact.planLedger ?? + traceV2Artifact.sqlValidation?.ledgerFulfillment ?? + traceV2Artifact.semanticPlan?.planLedger?.summary, + runtimePlan: this.readRuntimePlan(traceV2Artifact.runtimePlan), + artifactRefs: this.readArtifactRefs(traceV2Artifact.artifactRefs), + smartDefaults: this.readSmartDefaults(traceV2Artifact.smartDefaults), + loopEvidence: traceV2Artifact.loopEvidence, + terminationReason: traceV2Artifact.terminationReason, + failure: this.resolveTraceV2Failure(traceV2Artifact) + } + } + : {}) }; return { @@ -278,6 +323,16 @@ export class DeliveryContractMapper { }; } + private toSafeSemanticPlan( + semanticPlan: T + ): T { + if (!semanticPlan) { + return semanticPlan; + } + const { planLedger: _planLedger, ...safePlan } = semanticPlan; + return safePlan as T; + } + private toReplayLogs(records: DeliveryReplayRecordInput[] | undefined): DeliveryEvidenceReplayLog[] { if (!records || records.length === 0) { return []; @@ -540,294 +595,571 @@ export class DeliveryContractMapper { } private readSemanticSnapshot(run: SqlRun): SemanticSnapshot { - const traceWithCompat = run.trace as SqlRun["trace"] & { - modeling_revision?: unknown; - }; - const traceModelingRevision = this.readPositiveInteger( - traceWithCompat.modelingRevision ?? traceWithCompat.modeling_revision + const traceModelingRevision = this.readPositiveInteger(run.trace.modelingRevision); + const traceV2 = this.readTraceV2Artifact(run); + const contextPackStatus = + traceV2?.contextPack?.status === "ready" || traceV2?.contextPack?.status === "degraded" + ? traceV2.contextPack.status + : undefined; + const semanticDegradeReason = traceV2?.contextPack?.warnings?.find( + (item) => typeof item === "string" && item.trim().length > 0 ); - const semanticSteps = [...(run.trace.steps ?? [])] - .reverse() - .filter( - (step) => - step.node === "build-semantic-query" || step.node === "build-physical-plan" - ); - - for (const step of semanticSteps) { - const output = this.parseSummaryObject(step.outputSummary); - if (!output) { - continue; - } - const semanticVersionRaw = output.semanticVersion; - const semanticVersionCompatRaw = - semanticVersionRaw ?? output.semantic_version; - const semanticVersion = this.readPositiveInteger(semanticVersionCompatRaw); - const lockStatus = this.readString(output.lockStatus ?? output.lock_status); - const semanticLockStatus = - lockStatus === "locked" || lockStatus === "fallback" || lockStatus === "degraded" - ? lockStatus - : undefined; - const modelingRevision = this.readPositiveInteger( - output.modelingRevision ?? - output.modeling_revision ?? - output.activeRevision ?? - output.active_revision - ); - const contextPack = this.readRecord(output.contextPack ?? output.context_pack); - const contextPackStatusRaw = this.readString( - output.contextPackStatus ?? - output.context_pack_status ?? - contextPack?.status ?? - contextPack?.context_pack_status - ); - const contextPackStatus = - contextPackStatusRaw === "ready" || contextPackStatusRaw === "degraded" - ? contextPackStatusRaw - : undefined; - const semanticInstructionSummary = this.readSemanticInstructionSummary( - output.semanticBindingSummary ?? - output.semantic_binding_summary ?? - output.semanticInstructionSummary ?? - output.semantic_instruction_summary - ); - const semanticDegradeReason = this.readString(output.degradeReason); - const semanticDegradeReasonCompat = - semanticDegradeReason ?? this.readString(output.degrade_reason); - if ( - semanticVersion || - semanticLockStatus || - semanticDegradeReasonCompat || - modelingRevision !== undefined || - contextPackStatus || - semanticInstructionSummary - ) { - return { - modelingRevision: traceModelingRevision ?? modelingRevision, - semanticVersion, - semanticLockStatus, - contextPackStatus, - semanticInstructionSummary, - semanticDegradeReason: semanticDegradeReasonCompat - }; - } - } - - return { modelingRevision: traceModelingRevision }; + return { + modelingRevision: traceModelingRevision, + contextPackStatus, + semanticDegradeReason + }; } private readTraceContextEvidence(run: SqlRun): TraceContextEvidence { - const traceWithCompat = run.trace as SqlRun["trace"] & { - effectiveContextSummary?: unknown; - effective_context_summary?: unknown; - conflictHint?: unknown; - context_conflict_hint?: unknown; - }; - return { effectiveContextSummary: this.readEffectiveContextSummary( - traceWithCompat.effectiveContextSummary ?? - traceWithCompat.effective_context_summary + run.trace.effectiveContextSummary ), - conflictHint: this.readConflictHint( - traceWithCompat.conflictHint ?? traceWithCompat.context_conflict_hint - ) + conflictHint: this.readConflictHint(run.trace.conflictHint) }; } private readClarificationDecisionEvidence( run: SqlRun ): ClarificationDecisionLayer | undefined { - const traceWithCompat = run.trace as SqlRun["trace"] & { - clarificationDecision?: unknown; - clarification_decision?: unknown; - }; - const traceDecision = this.readClarificationDecision( - traceWithCompat.clarificationDecision ?? traceWithCompat.clarification_decision - ); + const traceDecision = this.readClarificationDecision(run.trace.clarificationDecision); if (traceDecision) { return traceDecision; } - - const stepDecision = this.readClarificationDecisionFromSteps(run.trace.steps); - if (stepDecision) { - return stepDecision; - } - return this.readClarificationDecision(run.clarification); } private readSqlCoverageEvidence(run: SqlRun): SqlCoverageEvidenceSnapshot | undefined { - const steps = run.trace.steps ?? []; - for (const step of [...steps].reverse()) { - if (step.node !== "generate-sql") { - continue; - } - const output = this.parseSummaryObject(step.outputSummary); - if (!output) { - continue; - } - const directCoverage = this.readSqlCoverageFromRecord( - output.coverage ?? output.sqlCoverage ?? output.sql_coverage - ); - if (directCoverage) { - return directCoverage; - } - const errorCode = this.readString(output.errorCode ?? output.error_code); - if (errorCode !== "LLM_SQL_EVIDENCE_COVERAGE_FAILED") { - continue; - } - const errorDetails = this.readRecord(output.errorDetails ?? output.error_details); - const detailsCoverage = this.readSqlCoverageFromRecord( - errorDetails?.coverage ?? errorDetails?.sqlCoverage ?? errorDetails?.sql_coverage - ); - if (detailsCoverage) { - return detailsCoverage; - } + const checks = run.trace.v2?.sqlValidation?.checks; + if (!Array.isArray(checks)) { + return undefined; } - return undefined; + const coverageCheck = checks.find((item) => item.check === "plan-coverage"); + if (!coverageCheck) { + return undefined; + } + const gateStatus = + coverageCheck.status === "passed" + ? "passed" + : coverageCheck.status === "failed" + ? "failed" + : "skipped_no_evidence"; + return { + gateStatus, + missingObjects: [], + triggerSource: "semantic_context" + }; } private readSavedPriorSqlEvidence( run: SqlRun ): SavedPriorSqlEvidenceSnapshot | undefined { - const steps = run.trace.steps ?? []; - if (steps.length === 0) { + const stages = run.trace.v2?.stages; + if (!Array.isArray(stages) || stages.length === 0) { return undefined; } - const resolutionStepIndex = [...steps] - .map((step, index) => ({ step, index })) - .reverse() - .find((entry) => entry.step.node === "resolve-saved-prior-sql"); - if (!resolutionStepIndex) { + const generateStage = stages.find((stage) => stage.stage === "generate-sql"); + if (!generateStage || generateStage.status !== "skipped") { return undefined; } - const output = this.parseSummaryObject(resolutionStepIndex.step.outputSummary); - const statusRaw = this.readString(output?.status); - const status = - statusRaw === "hit" || - statusRaw === "miss" || - statusRaw === "filtered" || - statusRaw === "stale" || - statusRaw === "ambiguous" - ? statusRaw - : undefined; - if (!status) { + const validateStage = stages.find((stage) => stage.stage === "validate"); + const safetyResult: SavedPriorSqlEvidenceSnapshot["safetyResult"] | undefined = + validateStage?.status === "success" + ? "passed" + : validateStage?.status === "failed" + ? "rejected" + : undefined; + const shortcutUsed = safetyResult === "passed"; + + return { + status: "hit", + shortcutUsed, + reasonCodes: ["saved_prior_sql_shortcut"], + ...(safetyResult ? { safetyResult } : {}) + }; + } + + private readContextPackSummary( + contextPack: Text2SqlV2RunArtifact["contextPack"] | undefined + ): DeliveryContextPackSummaryV1 | undefined { + if (!contextPack) { return undefined; } - const reasonCodes = this.readStringArray( - output?.reasonCodes ?? output?.reason_codes - ); - const selectedChunkId = this.readString( - output?.selectedChunkId ?? output?.selected_chunk_id + const selectedEvidenceCount = + contextPack.selectedContextSummary?.count ?? + contextPack.selectedEvidenceIds.length; + const selectedTableCount = contextPack.selectedTables.length; + const selectedColumnCount = contextPack.selectedColumns.length; + const pruningApplied = Boolean(contextPack.pruning?.applied); + const prunedEvidenceCount = (contextPack.pruning?.decisions ?? []).reduce( + (total, decision) => + total + + (this.readNonNegativeInteger(decision.removedCount) ?? + decision.removedEvidenceIds?.length ?? + 0), + 0 ); - const selectedViewId = this.readString( - output?.selectedViewId ?? output?.selected_view_id + const degradedLaneCount = (contextPack.laneStates ?? []).filter( + (lane) => lane.state === "degraded" || lane.state === "unavailable" + ).length; + const permissionFilteringApplied = + contextPack.permissionFiltering?.status === "applied"; + const permissionDeniedEvidenceCount = + contextPack.permissionFiltering?.deniedEvidenceCount ?? + contextPack.permissionFiltering?.deniedEvidenceIds?.length ?? + 0; + const degradationReasons = this.unique([ + ...(contextPack.degradation?.reasons ?? []), + ...(contextPack.warnings ?? []) + ]); + + return { + status: contextPack.status, + selectedEvidenceCount, + selectedTableCount, + selectedColumnCount, + pruningApplied, + ...(pruningApplied ? { prunedEvidenceCount } : {}), + ...(degradedLaneCount > 0 ? { degradedLaneCount } : {}), + permissionFilteringApplied, + ...(permissionFilteringApplied + ? { + permissionDeniedEvidenceCount + } + : {}), + ...(degradationReasons.length > 0 ? { degradationReasons } : {}) + }; + } + + private readMetadataAnswerSummary(input: { + run: SqlRun; + traceV2: Text2SqlV2RunArtifact | undefined; + contextPackSummary: DeliveryContextPackSummaryV1 | undefined; + }): DeliveryMetadataAnswerSummaryV1 | undefined { + const routeKind = + this.readSemanticPlanRouteKind(input.traceV2?.semanticPlan) ?? + this.readRouteKindFromIntakeStage(input.traceV2?.stages); + if (routeKind !== "metadata" && routeKind !== "general") { + return undefined; + } + + const selectedEvidenceCount = input.contextPackSummary?.selectedEvidenceCount ?? 0; + const degradationReasons = input.contextPackSummary?.degradationReasons ?? []; + const evidenceQuality = + input.contextPackSummary?.status === "ready" ? "ready" : "degraded"; + const groundedByContextPack = Boolean( + input.traceV2?.contextPack && selectedEvidenceCount > 0 ); - const selectedSourceRunId = this.readString( - output?.selectedSourceRunId ?? output?.selected_source_run_id + + return { + groundedByContextPack, + routeKind, + evidenceQuality, + selectedEvidenceCount, + permissionFilteringApplied: + input.contextPackSummary?.permissionFilteringApplied ?? false, + pruningApplied: input.contextPackSummary?.pruningApplied ?? false, + ...(degradationReasons.length > 0 ? { degradationReasons } : {}) + }; + } + + private readCorrectionGrounding( + traceV2: Text2SqlV2RunArtifact | undefined + ): SqlCorrectionGroundingV1 | undefined { + if (!traceV2) { + return undefined; + } + + const direct = this.normalizeCorrectionGrounding( + traceV2.sqlGeneration?.correctionGrounding ); + if (direct) { + return direct; + } - const subsequentSteps = steps.slice(resolutionStepIndex.index + 1); - const safetyStep = subsequentSteps.find((step) => step.node === "safety-check"); - const hasFallbackGeneration = subsequentSteps.some( - (step) => step.node === "generate-sql" + const generateStage = traceV2.stages.find((stage) => stage.stage === "generate-sql"); + if (!generateStage?.metadata || !this.isRecord(generateStage.metadata)) { + return undefined; + } + return this.normalizeCorrectionGrounding( + (generateStage.metadata as { correctionGrounding?: unknown }).correctionGrounding ); - const safetyResult: SavedPriorSqlEvidenceSnapshot["safetyResult"] | undefined = - status !== "hit" - ? undefined - : safetyStep?.status === "success" - ? "passed" - : safetyStep?.status === "failed" - ? hasFallbackGeneration - ? "fallback_generated" - : "rejected" - : undefined; - - const shortcutUsed = status === "hit" && safetyResult === "passed"; + } + private readRuntimePlan(value: unknown): Text2SqlV2RuntimePlanV1 | undefined { + if (!this.isRecord(value) || value.version !== "runtime-plan.v1") { + return undefined; + } + const items = Array.isArray(value.items) + ? value.items + .map((item) => this.readRuntimePlanItem(item)) + .filter((item): item is Text2SqlV2RuntimePlanV1["items"][number] => + Boolean(item) + ) + : []; + if (items.length === 0) { + return undefined; + } return { + version: "runtime-plan.v1", + items, + ...(this.readString(value.currentItemId) + ? { currentItemId: this.readString(value.currentItemId) } + : {}), + ...(this.readString(value.summary) + ? { summary: this.readString(value.summary) } + : {}) + }; + } + + private readRuntimePlanItem( + value: unknown + ): Text2SqlV2RuntimePlanV1["items"][number] | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const id = this.readString(value.id); + const stage = this.readStageName(value.stage); + const goal = this.readString(value.goal); + const status = this.readRuntimePlanStatus(value.status); + if (!id || !stage || !goal || !status) { + return undefined; + } + const correctionIntent = this.readRuntimePlanCorrectionIntent( + value.correctionIntent + ); + return { + id, + stage, + goal, status, - shortcutUsed, - ...(reasonCodes.length > 0 ? { reasonCodes } : {}), - ...(selectedChunkId ? { selectedChunkId } : {}), - ...(selectedViewId ? { selectedViewId } : {}), - ...(selectedSourceRunId ? { selectedSourceRunId } : {}), - ...(safetyResult ? { safetyResult } : {}) + ...(this.readStringArray(value.reasonCodes).length > 0 + ? { reasonCodes: this.readStringArray(value.reasonCodes) } + : {}), + ...(this.readStringArray(value.evidenceRefs).length > 0 + ? { evidenceRefs: this.readStringArray(value.evidenceRefs) } + : {}), + ...(correctionIntent ? { correctionIntent } : {}), + ...(this.readString(value.startedAt) + ? { startedAt: this.readString(value.startedAt) } + : {}), + ...(this.readString(value.endedAt) + ? { endedAt: this.readString(value.endedAt) } + : {}), + ...(this.readString(value.summary) + ? { summary: this.readString(value.summary) } + : {}) }; } - private readSqlCoverageFromRecord( + private readRuntimePlanCorrectionIntent( value: unknown - ): SqlCoverageEvidenceSnapshot | undefined { + ): Text2SqlV2RuntimePlanV1["items"][number]["correctionIntent"] | undefined { if (!this.isRecord(value)) { return undefined; } - const gateStatusRaw = this.readString(value.gateStatus ?? value.gate_status); - const gateStatus = - gateStatusRaw === "passed" || - gateStatusRaw === "failed" || - gateStatusRaw === "skipped_no_evidence" || - gateStatusRaw === "skipped_metadata_intent" || - gateStatusRaw === "skipped_no_sql_objects" - ? gateStatusRaw + const retryReason = this.readString(value.retryReason); + if (!retryReason) { + return undefined; + } + return { + ...(this.readStageName(value.failedStage) + ? { failedStage: this.readStageName(value.failedStage) } + : {}), + ...(this.readString(value.failureCode) + ? { failureCode: this.readString(value.failureCode) } + : {}), + retryReason, + ...(this.readStageName(value.targetStage) + ? { targetStage: this.readStageName(value.targetStage) } + : {}) + }; + } + + private readArtifactRefs(value: unknown): Text2SqlV2ArtifactRefV1[] | undefined { + if (!Array.isArray(value)) { + return undefined; + } + const refs = value + .map((item) => this.readArtifactRef(item)) + .filter((item): item is Text2SqlV2ArtifactRefV1 => Boolean(item)); + return refs.length > 0 ? refs : undefined; + } + + private readArtifactRef(value: unknown): Text2SqlV2ArtifactRefV1 | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const id = this.readString(value.id); + const category = this.readString(value.category); + const summary = this.readString(value.summary); + const hash = this.readString(value.hash); + const visibility = this.readArtifactVisibility(value.visibility); + if (!id || !category || !summary || !hash || !visibility) { + return undefined; + } + return { + id, + category, + summary, + hash, + ...(this.readString(value.version) + ? { version: this.readString(value.version) } + : {}), + ...(this.readNonNegativeInteger(value.sizeBytes) !== undefined + ? { sizeBytes: this.readNonNegativeInteger(value.sizeBytes) } + : {}), + ...(this.readString(value.replayKeyHint) + ? { replayKeyHint: this.readString(value.replayKeyHint) } + : {}), + visibility, + ...(this.readArtifactSensitivity(value.sensitivity) + ? { sensitivity: this.readArtifactSensitivity(value.sensitivity) } + : {}), + ...(this.readStringArray(value.reasonCodes).length > 0 + ? { reasonCodes: this.readStringArray(value.reasonCodes) } + : {}), + ...(this.readStringArray(value.evidenceRefs).length > 0 + ? { evidenceRefs: this.readStringArray(value.evidenceRefs) } + : {}) + }; + } + + private readSmartDefaults( + value: unknown + ): Text2SqlV2SmartDefaultsEvidenceV1 | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const bundleId = this.readString(value.bundleId); + const version = this.readString(value.version); + const coveredStages = this.readStageNameArray(value.coveredStages); + const ruleIds = this.readStringArray(value.ruleIds); + const status = + value.status === "applied" || value.status === "fallback" + ? value.status : undefined; - const triggerSourceRaw = this.readString( - value.triggerSource ?? value.trigger_source + if ( + !bundleId || + !version || + coveredStages.length === 0 || + ruleIds.length === 0 || + !status + ) { + return undefined; + } + const templateOverlay = this.readSmartDefaultsTemplateOverlay( + value.templateOverlay ); - const triggerSource = - triggerSourceRaw === "selected_context" || - triggerSourceRaw === "semantic_context" || - triggerSourceRaw === "explicit_pinning" || - triggerSourceRaw === "none" - ? triggerSourceRaw - : undefined; - if (!gateStatus || !triggerSource) { + return { + bundleId, + version, + coveredStages, + ruleIds, + status, + ...(this.readString(value.fallbackReason) + ? { fallbackReason: this.readString(value.fallbackReason) } + : {}), + ...(templateOverlay ? { templateOverlay } : {}) + }; + } + + private readSmartDefaultsTemplateOverlay( + value: unknown + ): Text2SqlV2SmartDefaultsEvidenceV1["templateOverlay"] | undefined { + if (!this.isRecord(value) || typeof value.applied !== "boolean") { return undefined; } return { - gateStatus, - missingObjects: this.readStringArray( - value.missingObjects ?? value.missing_objects - ), - triggerSource + applied: value.applied, + ...(this.readString(value.templateId) + ? { templateId: this.readString(value.templateId) } + : {}), + ...(this.readPositiveInteger(value.version) !== undefined + ? { version: this.readPositiveInteger(value.version) } + : {}) }; } - private readClarificationDecisionFromSteps( - steps: SqlRun["trace"]["steps"] | undefined - ): ClarificationDecisionLayer | undefined { - if (!steps || steps.length === 0) { + private normalizeCorrectionGrounding( + value: unknown + ): SqlCorrectionGroundingV1 | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const failedSqlRef = this.readString(value.failedSqlRef); + const retryReason = this.readString(value.retryReason); + if (!failedSqlRef || !retryReason) { return undefined; } - for (const step of [...steps].reverse()) { - if (step.node !== "clarify") { - continue; - } - const output = this.parseSummaryObject(step.outputSummary); - if (!output) { - continue; - } - const question = this.readString( - output.clarificationQuestion ?? output.clarification_question - ); - const stepDecision = this.readClarificationDecision( - output.clarificationDecision ?? output.clarification_decision ?? output, - { - question, - reason: this.readString(step.detail) - } - ); - if (stepDecision) { - return stepDecision; + const failureCategory = this.readString(value.failureCategory); + const source = this.readString(value.source); + const semanticPlanRoute = this.readString(value.semanticPlanRoute); + const semanticPlanRouteKind = this.readString(value.semanticPlanRouteKind); + const contextPackStatus = this.readString(value.contextPackStatus); + + return { + failedSqlRef, + ...(this.readString(value.failedSqlPreview) + ? { + failedSqlPreview: this.readString(value.failedSqlPreview) + } + : {}), + retryReason, + ...(this.readString(value.failureCode) + ? { + failureCode: this.readString(value.failureCode) + } + : {}), + ...(failureCategory && + (failureCategory === "validation" || + failureCategory === "governance" || + failureCategory === "safety" || + failureCategory === "provider" || + failureCategory === "execution" || + failureCategory === "unknown") + ? { + failureCategory + } + : {}), + ...(source && (source === "validation" || source === "execution") + ? { + source + } + : {}), + attemptCount: this.readNonNegativeInt(value.attemptCount), + maxAttempts: this.readNonNegativeInt(value.maxAttempts), + evidenceRefs: this.readStringArray(value.evidenceRefs), + ...(this.readString(value.semanticPlanSnapshotId) + ? { + semanticPlanSnapshotId: this.readString(value.semanticPlanSnapshotId) + } + : {}), + ...(semanticPlanRoute && + (semanticPlanRoute === "answer" || + semanticPlanRoute === "clarify" || + semanticPlanRoute === "reject") + ? { + semanticPlanRoute + } + : {}), + ...(semanticPlanRouteKind && + (semanticPlanRouteKind === "text_to_sql" || + semanticPlanRouteKind === "metadata" || + semanticPlanRouteKind === "general" || + semanticPlanRouteKind === "clarify" || + semanticPlanRouteKind === "fail_closed") + ? { + semanticPlanRouteKind + } + : {}), + ...(this.readNonNegativeInteger(value.selectedTableCount) !== undefined + ? { + selectedTableCount: this.readNonNegativeInteger(value.selectedTableCount) + } + : {}), + ...(this.readNonNegativeInteger(value.selectedColumnCount) !== undefined + ? { + selectedColumnCount: this.readNonNegativeInteger(value.selectedColumnCount) + } + : {}), + ...(contextPackStatus && + (contextPackStatus === "ready" || contextPackStatus === "degraded") + ? { + contextPackStatus + } + : {}), + ...(this.readNonNegativeInteger(value.contextPackEvidenceCount) !== undefined + ? { + contextPackEvidenceCount: this.readNonNegativeInteger( + value.contextPackEvidenceCount + ) + } + : {}) + }; + } + + private readSemanticPlanRouteKind( + semanticPlan: Text2SqlV2RunArtifact["semanticPlan"] | undefined + ): "text_to_sql" | "metadata" | "general" | "clarify" | "fail_closed" | undefined { + const routeFilter = semanticPlan?.filters?.find((item) => + item.startsWith("route_kind:") + ); + if (routeFilter) { + const value = routeFilter.slice("route_kind:".length).trim(); + if ( + value === "text_to_sql" || + value === "metadata" || + value === "general" || + value === "clarify" || + value === "fail_closed" + ) { + return value; } } + if (semanticPlan?.route === "clarify") { + return "clarify"; + } + if (semanticPlan?.route === "reject") { + return "fail_closed"; + } + return semanticPlan ? "text_to_sql" : undefined; + } + + private readRouteKindFromIntakeStage( + stages: Text2SqlV2RunArtifact["stages"] | undefined + ): "text_to_sql" | "metadata" | "general" | "clarify" | "fail_closed" | undefined { + if (!Array.isArray(stages)) { + return undefined; + } + const intake = stages.find((stage) => stage.stage === "intake"); + if (!intake?.metadata || !this.isRecord(intake.metadata)) { + return undefined; + } + const route = this.readString((intake.metadata as { route?: unknown }).route); + if ( + route === "text_to_sql" || + route === "metadata" || + route === "general" || + route === "clarify" || + route === "fail_closed" + ) { + return route; + } return undefined; } + private readTraceV2Artifact(run: SqlRun): Text2SqlV2RunArtifact | undefined { + const traceWithCompat = run.trace as SqlRun["trace"] & { + v2?: unknown; + }; + if (!this.isRecord(traceWithCompat.v2)) { + return undefined; + } + const stages = (traceWithCompat.v2 as { stages?: unknown }).stages; + if (!Array.isArray(stages)) { + return undefined; + } + return traceWithCompat.v2 as Text2SqlV2RunArtifact; + } + + private resolveTraceV2Failure( + traceV2: Text2SqlV2RunArtifact + ): NonNullable["v2"]>["failure"] { + for (let index = traceV2.stages.length - 1; index >= 0; index -= 1) { + const stage = traceV2.stages[index]; + if (stage.status === "failed" && stage.failure) { + return stage.failure; + } + } + return traceV2.sqlValidation?.failure; + } + private readClarificationDecision( value: unknown, fallback?: { @@ -845,10 +1177,7 @@ export class DeliveryContractMapper { ? (decisionRaw as ClarificationDecisionEvidence["decision"]) : undefined; const triggerPathRaw = this.readString( - value.triggerPath ?? - value.trigger_path ?? - value.triggerSource ?? - value.trigger_source + value.triggerPath ?? value.triggerSource )?.toLowerCase(); const triggerPath = triggerPathRaw === "rule" || @@ -857,14 +1186,12 @@ export class DeliveryContractMapper { ? (triggerPathRaw as ClarificationDecisionEvidence["triggerPath"]) : undefined; const decisionSource = this.readString( - value.decisionSource ?? value.decision_source ?? value.source - ); - const bypassed = this.readBoolean(value.bypassed ?? value.isBypassed ?? value.is_bypassed); - const bypassReasonCode = this.readString( - value.bypassReasonCode ?? value.bypass_reason_code + value.decisionSource ?? value.source ); + const bypassed = this.readBoolean(value.bypassed ?? value.isBypassed); + const bypassReasonCode = this.readString(value.bypassReasonCode); const confidenceLevelRaw = this.readString( - value.confidenceLevel ?? value.confidence_level ?? value.confidence + value.confidenceLevel ?? value.confidence )?.toLowerCase(); const confidenceLevel = confidenceLevelRaw === "high" || @@ -873,23 +1200,14 @@ export class DeliveryContractMapper { ? (confidenceLevelRaw as ClarificationDecisionEvidence["confidenceLevel"]) : undefined; const missingCriticalSlots = this.readStringArray( - value.missingCriticalSlots ?? - value.missing_critical_slots ?? - value.missingSlots ?? - value.missing_slots + value.missingCriticalSlots ?? value.missingSlots ); const conflictDetected = this.readBoolean( - value.conflictDetected ?? - value.conflict_detected ?? - value.hasConflict ?? - value.has_conflict + value.conflictDetected ?? value.hasConflict ); - const reasonCodes = this.readStringArray(value.reasonCodes ?? value.reason_codes); + const reasonCodes = this.readStringArray(value.reasonCodes); const question = this.readString( - value.question ?? - value.clarificationQuestion ?? - value.clarification_question ?? - fallback?.question + value.question ?? value.clarificationQuestion ?? fallback?.question ); const reason = this.readString(value.reason ?? fallback?.reason); const hasStructuredPayload = Boolean( @@ -1074,17 +1392,6 @@ export class DeliveryContractMapper { } } - private parseSummaryObject(summary: string | undefined): Record | undefined { - if (!summary) { - return undefined; - } - const trimmed = summary.trim(); - if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) { - return undefined; - } - return this.parsePayload(trimmed); - } - private isRecord(value: unknown): value is Record { return typeof value === "object" && value !== null && !Array.isArray(value); } @@ -1181,6 +1488,71 @@ export class DeliveryContractMapper { ); } + private readStageName(value: unknown): Text2SqlV2StageName | undefined { + if ( + value === "intake" || + value === "retrieve" || + value === "assemble-context" || + value === "semantic-plan" || + value === "generate-sql" || + value === "validate" || + value === "correct" || + value === "execute" || + value === "answer" + ) { + return value; + } + return undefined; + } + + private readStageNameArray(value: unknown): Text2SqlV2StageName[] { + if (!Array.isArray(value)) { + return []; + } + return value.filter((item): item is Text2SqlV2StageName => + Boolean(this.readStageName(item)) + ); + } + + private readRuntimePlanStatus( + value: unknown + ): Text2SqlV2RuntimePlanV1["items"][number]["status"] | undefined { + if ( + value === "pending" || + value === "running" || + value === "completed" || + value === "skipped" || + value === "failed" || + value === "clarification" + ) { + return value; + } + return undefined; + } + + private readArtifactVisibility( + value: unknown + ): Text2SqlV2ArtifactRefV1["visibility"] | undefined { + if (value === "user" || value === "internal" || value === "redacted") { + return value; + } + return undefined; + } + + private readArtifactSensitivity( + value: unknown + ): Text2SqlV2ArtifactRefV1["sensitivity"] | undefined { + if ( + value === "none" || + value === "permission_filtered" || + value === "provider_raw" || + value === "sensitive" + ) { + return value; + } + return undefined; + } + private unique(values: string[]): string[] { return Array.from(new Set(values.filter((item) => item.trim().length > 0))); } diff --git a/apps/backend/src/modules/conversation/nodes/answer.node.ts b/apps/backend/src/modules/conversation/nodes/answer.node.ts new file mode 100644 index 0000000..a090bbe --- /dev/null +++ b/apps/backend/src/modules/conversation/nodes/answer.node.ts @@ -0,0 +1,170 @@ +import { Injectable } from "@nestjs/common"; +import type { + ClarificationPrompt, + SemanticContextPackV1, + SemanticPlanV1, + Text2SqlV2FailureSemantic +} from "@text2sql/shared-types"; +import { FormatAnswerNode } from "../agent/nodes/format-answer.node"; +import type { StructuredSqlGenerationArtifact } from "../agent/sql/sql-generation.service"; +import type { ExecuteSqlNodeResult } from "./execute-sql.node"; + +export interface AnswerNodeResult { + mode: + | "execution_result" + | "direct_answer" + | "clarification" + | "fail_closed" + | "execution_failure"; + answer: string; + status: "executionResult" | "clarification" | "rejected" | "failed"; + evidenceRefs: string[]; + warnings: string[]; + failure?: Text2SqlV2FailureSemantic; +} + +@Injectable() +export class AnswerNode { + constructor(private readonly formatAnswerNode: FormatAnswerNode) {} + + run(input: { + question: string; + directAnswer?: string; + clarification?: ClarificationPrompt; + executionResult?: ExecuteSqlNodeResult; + sqlArtifact?: StructuredSqlGenerationArtifact; + semanticPlan?: SemanticPlanV1; + contextPack?: SemanticContextPackV1; + routeKind?: string; + failure?: Text2SqlV2FailureSemantic; + warnings?: string[]; + }): AnswerNodeResult { + const routeKind = this.resolveRouteKind(input.semanticPlan, input.routeKind); + const metadataRoute = routeKind === "metadata"; + const evidenceRefs = this.unique([ + ...(input.sqlArtifact?.evidenceRefs ?? []), + ...(input.semanticPlan?.evidenceRefs ?? []), + ...(metadataRoute ? input.contextPack?.selectedEvidenceIds ?? [] : []) + ]); + const warnings = this.unique(input.warnings ?? []); + + if (input.clarification) { + return { + mode: "clarification", + answer: input.clarification.question, + status: "clarification", + evidenceRefs, + warnings: this.unique([ + ...warnings, + input.clarification.reason, + ...(input.clarification.reasonCodes ?? []) + ]), + failure: input.failure + }; + } + + if (input.directAnswer?.trim()) { + return { + mode: "direct_answer", + answer: metadataRoute + ? this.formatAnswerNode.runMetadataDirectAnswer({ + answer: input.directAnswer, + contextPack: input.contextPack, + semanticPlan: input.semanticPlan, + warnings + }) + : this.formatAnswerNode.runDirectAnswer(input.directAnswer, warnings), + status: "executionResult", + evidenceRefs, + warnings, + failure: input.failure + }; + } + + if (input.failure?.terminal) { + if (!this.isFailClosedFailure(input.failure)) { + return { + mode: "execution_failure", + answer: this.formatAnswerNode.runOperationalFailure(input.failure.message), + status: "failed", + evidenceRefs, + warnings, + failure: input.failure + }; + } + + return { + mode: "fail_closed", + answer: this.formatAnswerNode.runFailClosed(input.failure.message), + status: + input.failure.category === "execution" ? "failed" : "rejected", + evidenceRefs, + warnings, + failure: input.failure + }; + } + + if (!input.executionResult) { + return { + mode: "execution_failure", + answer: this.formatAnswerNode.runFailClosed( + "缺少执行结果，无法生成最终回答。" + ), + status: "failed", + evidenceRefs, + warnings, + failure: input.failure + }; + } + + return { + mode: "execution_result", + answer: this.formatAnswerNode.run( + input.question, + input.executionResult.rows, + input.executionResult.columns + ), + status: "executionResult", + evidenceRefs, + warnings + }; + } + + private unique(values: string[]): string[] { + return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean))); + } + + private resolveRouteKind( + semanticPlan?: SemanticPlanV1, + routeKind?: string + ): string | undefined { + if (routeKind?.trim()) { + return routeKind.trim(); + } + const routeFilter = semanticPlan?.filters?.find((filter) => + filter.startsWith("route_kind:") + ); + if (!routeFilter) { + return undefined; + } + return routeFilter.slice("route_kind:".length).trim(); + } + + private isFailClosedFailure(failure: Text2SqlV2FailureSemantic): boolean { + if ( + failure.category === "governance" || + failure.category === "validation" || + failure.category === "planning" + ) { + return true; + } + + return ( + failure.code.includes("UNSAFE") || + failure.code.includes("READ_ONLY") || + failure.code.includes("PERMISSION") || + failure.code.includes("POLICY") || + failure.code.includes("FAIL_CLOSED") + ); + } +} diff --git a/apps/backend/src/modules/conversation/nodes/assemble-context.node.ts b/apps/backend/src/modules/conversation/nodes/assemble-context.node.ts new file mode 100644 index 0000000..5a829c6 --- /dev/null +++ b/apps/backend/src/modules/conversation/nodes/assemble-context.node.ts @@ -0,0 +1,213 @@ +import { Injectable } from "@nestjs/common"; +import type { SemanticContextPackV1 } from "@text2sql/shared-types"; +import { SemanticContextPackService } from "../adapters/semantic-context-pack.service"; + +interface SemanticContextChunkPayload { + chunk_id: string; + content?: string; + metadata?: unknown; +} + +interface AssembleContextRetrievalBundle { + status?: "ready" | "degraded"; + selected_context?: SemanticContextChunkPayload[]; + degrade_reasons?: string[]; + degradeReasons?: string[]; + context_pack?: { + semantic_bindings?: { + model_keys?: string[]; + relationship_keys?: string[]; + metric_keys?: string[]; + calculated_field_keys?: string[]; + modelKeys?: string[]; + relationshipKeys?: string[]; + metricKeys?: string[]; + calculatedFieldKeys?: string[]; + }; + semanticBindings?: { + model_keys?: string[]; + relationship_keys?: string[]; + metric_keys?: string[]; + calculated_field_keys?: string[]; + modelKeys?: string[]; + relationshipKeys?: string[]; + metricKeys?: string[]; + calculatedFieldKeys?: string[]; + }; + lane_metadata?: Array<{ + lane?: string; + state?: string; + unavailable_reason?: string; + fallback_reason?: string; + evidence_ids?: string[]; + denied_evidence_ids?: string[]; + reason_codes?: string[]; + unavailableReason?: string; + fallbackReason?: string; + evidenceIds?: string[]; + deniedEvidenceIds?: string[]; + reasonCodes?: string[]; + }>; + laneMetadata?: Array<{ + lane?: string; + state?: string; + unavailable_reason?: string; + fallback_reason?: string; + evidence_ids?: string[]; + denied_evidence_ids?: string[]; + reason_codes?: string[]; + unavailableReason?: string; + fallbackReason?: string; + evidenceIds?: string[]; + deniedEvidenceIds?: string[]; + reasonCodes?: string[]; + }>; + pruning_decisions?: Array<{ + budget_source?: string; + kept_evidence_ids?: string[]; + removed_evidence_ids?: string[]; + reason_codes?: string[]; + budgetSource?: string; + keptEvidenceIds?: string[]; + removedEvidenceIds?: string[]; + reasonCodes?: string[]; + summary?: string; + }>; + pruningDecisions?: Array<{ + budget_source?: string; + kept_evidence_ids?: string[]; + removed_evidence_ids?: string[]; + reason_codes?: string[]; + budgetSource?: string; + keptEvidenceIds?: string[]; + removedEvidenceIds?: string[]; + reasonCodes?: string[]; + summary?: string; + }>; + permission_filtering?: { + status?: "applied" | "skipped"; + denied_evidence_ids?: string[]; + denied_table_names?: string[]; + denied_column_names?: string[]; + reason_codes?: string[]; + deniedEvidenceIds?: string[]; + deniedTableNames?: string[]; + deniedColumnNames?: string[]; + reasonCodes?: string[]; + }; + permissionFiltering?: { + status?: "applied" | "skipped"; + denied_evidence_ids?: string[]; + denied_table_names?: string[]; + denied_column_names?: string[]; + reason_codes?: string[]; + deniedEvidenceIds?: string[]; + deniedTableNames?: string[]; + deniedColumnNames?: string[]; + reasonCodes?: string[]; + }; + }; +} + +export interface AssembleContextNodeInput { + retrievalBundle?: AssembleContextRetrievalBundle; + selectedContext?: SemanticContextChunkPayload[]; + additionalWarnings?: string[]; +} + +export interface AssembleContextNodeSummary { + status: "ready" | "degraded"; + version?: string; + capabilityCount: number; + selectedEvidenceCount: number; + selectedTableCount: number; + selectedColumnCount: number; + degradedLaneCount: number; + laneStateCounts: { + ready: number; + degraded: number; + unavailable: number; + skipped: number; + }; + pruningDecisionCount: number; + permissionReasonCount: number; + permissionDeniedEvidenceCount: number; + warningCount: number; +} + +export interface AssembleContextNodeOutput { + contextPack: SemanticContextPackV1; + typedSummary: AssembleContextNodeSummary; + evidenceRefs: string[]; +} + +@Injectable() +export class AssembleContextNode { + constructor(private readonly semanticContextPackService: SemanticContextPackService) {} + + run(input: AssembleContextNodeInput): AssembleContextNodeOutput { + const contextPack = this.semanticContextPackService.build({ + retrievalBundle: input.retrievalBundle, + selectedContext: input.selectedContext, + additionalWarnings: input.additionalWarnings + }); + const laneMetadata = + input.retrievalBundle?.context_pack?.lane_metadata ?? + input.retrievalBundle?.context_pack?.laneMetadata ?? + []; + const laneStateCounts = laneMetadata.reduce( + (acc, lane) => { + if (lane.state === "ready") { + acc.ready += 1; + } else if (lane.state === "unavailable") { + acc.unavailable += 1; + } else if (lane.state === "skipped") { + acc.skipped += 1; + } else { + acc.degraded += 1; + } + return acc; + }, + { + ready: 0, + degraded: 0, + unavailable: 0, + skipped: 0 + } + ); + const pruningDecisions = + input.retrievalBundle?.context_pack?.pruning_decisions ?? + input.retrievalBundle?.context_pack?.pruningDecisions ?? + []; + const permissionReasonCodes = + input.retrievalBundle?.context_pack?.permission_filtering?.reason_codes ?? + input.retrievalBundle?.context_pack?.permission_filtering?.reasonCodes ?? + input.retrievalBundle?.context_pack?.permissionFiltering?.reason_codes ?? + input.retrievalBundle?.context_pack?.permissionFiltering?.reasonCodes ?? + []; + const degradedLaneCount = + (contextPack.laneStates ?? []).filter((lane) => lane.state !== "ready").length; + const permissionDeniedEvidenceCount = + contextPack.permissionFiltering?.deniedEvidenceCount ?? 0; + + return { + contextPack, + typedSummary: { + status: contextPack.status, + version: contextPack.version, + capabilityCount: contextPack.capabilities?.length ?? 0, + selectedEvidenceCount: contextPack.selectedEvidenceIds.length, + selectedTableCount: contextPack.selectedTables.length, + selectedColumnCount: contextPack.selectedColumns.length, + degradedLaneCount, + laneStateCounts, + pruningDecisionCount: pruningDecisions.length, + permissionReasonCount: permissionReasonCodes.filter((item) => item.trim().length > 0) + .length, + permissionDeniedEvidenceCount, + warningCount: contextPack.warnings?.length ?? 0 + }, + evidenceRefs: contextPack.selectedEvidenceIds.slice(0, 128) + }; + } +} diff --git a/apps/backend/src/modules/conversation/nodes/correct-sql.node.ts b/apps/backend/src/modules/conversation/nodes/correct-sql.node.ts new file mode 100644 index 0000000..b23a842 --- /dev/null +++ b/apps/backend/src/modules/conversation/nodes/correct-sql.node.ts @@ -0,0 +1,238 @@ +import { Injectable } from "@nestjs/common"; +import type { + SqlCorrectionGroundingV1, + SemanticContextPackV1, + SemanticPlanV1, + SqlValidationArtifactV1, + Text2SqlV2FailureSemantic +} from "@text2sql/shared-types"; +import { createHash } from "node:crypto"; +import { DomainError } from "../../../common/domain-error"; +import { + SqlCorrectionService, + type SqlCorrectionBudget, + type SqlCorrectionDecision +} from "../adapters/sql-correction.service"; + +export interface SqlCorrectionArtifact { + failedSql: string; + retryReason: string; + category: SqlCorrectionDecision["category"]; + source: SqlCorrectionDecision["source"]; + failureCode?: string; + attemptCount: number; + maxAttempts: number; + semanticPlanSnapshotId?: string; + evidenceRefs: string[]; + grounding: SqlCorrectionGroundingV1; + shouldRevalidate: boolean; +} + +export interface CorrectSqlNodeResult { + outcome: "retry_generation" | "terminal"; + budget: SqlCorrectionBudget; + artifact: SqlCorrectionArtifact; + failure?: Text2SqlV2FailureSemantic; +} + +@Injectable() +export class CorrectSqlNode { + constructor(private readonly sqlCorrectionService: SqlCorrectionService) {} + + run(input: { + failedSql: string; + validationArtifact?: SqlValidationArtifactV1; + error?: unknown; + attemptCount: number; + maxAttempts?: number; + semanticPlan?: SemanticPlanV1; + contextPack?: SemanticContextPackV1; + }): CorrectSqlNodeResult { + const decision = this.sqlCorrectionService.decide( + input.error ?? this.toValidationError(input.validationArtifact) + ); + const nextAttemptCount = input.attemptCount + 1; + const budget = this.sqlCorrectionService.resolveBudget({ + attemptCount: nextAttemptCount, + maxAttempts: input.maxAttempts ?? decision.maxAttempts + }); + const evidenceRefs = this.unique([ + ...(input.semanticPlan?.evidenceRefs ?? []), + ...(input.contextPack?.selectedEvidenceIds ?? []) + ]); + const failedObligationIds = this.collectFailedObligationIds(input.validationArtifact); + + const artifact: SqlCorrectionArtifact = { + failedSql: input.failedSql, + retryReason: decision.reason, + category: decision.category, + source: decision.source, + failureCode: decision.failureCode, + attemptCount: nextAttemptCount, + maxAttempts: budget.maxAttempts, + semanticPlanSnapshotId: input.semanticPlan?.snapshotId, + evidenceRefs, + grounding: this.buildCorrectionGrounding({ + failedSql: input.failedSql, + retryReason: decision.reason, + category: decision.category, + source: decision.source, + failureCode: decision.failureCode, + attemptCount: nextAttemptCount, + maxAttempts: budget.maxAttempts, + evidenceRefs, + semanticPlan: input.semanticPlan, + contextPack: input.contextPack, + failedObligationIds + }), + shouldRevalidate: decision.correctable && !budget.exhausted + }; + + if (!decision.correctable || budget.exhausted) { + const exhausted = budget.exhausted && decision.correctable; + return { + outcome: "terminal", + budget, + artifact, + failure: { + code: exhausted + ? "SQL_CORRECTION_BUDGET_EXHAUSTED" + : decision.failureCode ?? "SQL_CORRECTION_NOT_ALLOWED", + message: exhausted + ? `SQL correction budget exhausted after ${budget.maxAttempts} attempts` + : decision.reason, + category: + decision.category === "governance" + ? "governance" + : decision.category === "safety" + ? "governance" + : decision.category === "provider" + ? "execution" + : decision.category === "execution" + ? "execution" + : "validation", + terminal: true, + correctable: false + } + }; + } + + return { + outcome: "retry_generation", + budget, + artifact + }; + } + + private toValidationError( + validationArtifact?: SqlValidationArtifactV1 + ): DomainError | Error { + if (!validationArtifact?.failure) { + return new Error("unknown validation failure"); + } + return new DomainError( + "SQL_VALIDATION_FAILED", + validationArtifact.failure.message, + 422, + { + validationArtifact + } + ); + } + + private unique(values: string[]): string[] { + return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean))); + } + + private buildCorrectionGrounding(input: { + failedSql: string; + retryReason: string; + category: SqlCorrectionDecision["category"]; + source: SqlCorrectionDecision["source"]; + failureCode?: string; + attemptCount: number; + maxAttempts: number; + evidenceRefs: string[]; + semanticPlan?: SemanticPlanV1; + contextPack?: SemanticContextPackV1; + failedObligationIds: string[]; + }): SqlCorrectionGroundingV1 { + return { + failedSqlRef: this.buildSqlRef(input.failedSql), + failedSqlPreview: this.buildSqlPreview(input.failedSql), + retryReason: input.retryReason, + failureCode: input.failureCode, + failureCategory: input.category, + source: input.source, + attemptCount: input.attemptCount, + maxAttempts: input.maxAttempts, + evidenceRefs: input.evidenceRefs, + semanticPlanSnapshotId: input.semanticPlan?.snapshotId, + semanticPlanRoute: input.semanticPlan?.route, + semanticPlanRouteKind: this.resolveRouteKind(input.semanticPlan), + selectedTableCount: input.semanticPlan?.selectedTables.length, + selectedColumnCount: input.semanticPlan?.selectedColumns.length, + contextPackStatus: input.contextPack?.status, + contextPackEvidenceCount: + input.contextPack?.selectedContextSummary?.count ?? + input.contextPack?.selectedEvidenceIds.length, + failedObligationIds: + input.failedObligationIds.length > 0 ? input.failedObligationIds : undefined + }; + } + + private collectFailedObligationIds( + validationArtifact?: SqlValidationArtifactV1 + ): string[] { + return this.unique([ + ...(validationArtifact?.failedObligationIds ?? []), + ...(validationArtifact?.checks.flatMap((check) => check.failedObligationIds ?? []) ?? []) + ]); + } + + private buildSqlRef(sql: string): string { + const digest = createHash("sha256") + .update(sql) + .digest("hex") + .slice(0, 16); + return `sql.sha256.${digest}`; + } + + private buildSqlPreview(sql: string): string { + const compact = sql.replace(/\s+/g, " ").trim(); + if (compact.length <= 180) { + return compact; + } + return `${compact.slice(0, 180)}...`; + } + + private resolveRouteKind( + semanticPlan?: SemanticPlanV1 + ): "text_to_sql" | "metadata" | "general" | "clarify" | "fail_closed" | undefined { + if (!semanticPlan) { + return undefined; + } + const routeFilter = semanticPlan.filters?.find((item) => + item.startsWith("route_kind:") + ); + if (routeFilter) { + const value = routeFilter.slice("route_kind:".length).trim(); + if ( + value === "text_to_sql" || + value === "metadata" || + value === "general" || + value === "clarify" || + value === "fail_closed" + ) { + return value; + } + } + if (semanticPlan.route === "clarify") { + return "clarify"; + } + if (semanticPlan.route === "reject") { + return "fail_closed"; + } + return "text_to_sql"; + } +} diff --git a/apps/backend/src/modules/conversation/nodes/execute-sql.node.ts b/apps/backend/src/modules/conversation/nodes/execute-sql.node.ts new file mode 100644 index 0000000..bab6224 --- /dev/null +++ b/apps/backend/src/modules/conversation/nodes/execute-sql.node.ts @@ -0,0 +1,69 @@ +import { Injectable } from "@nestjs/common"; +import type { + SemanticPlanV1, + SqlValidationArtifactV1 +} from "@text2sql/shared-types"; +import { DomainError } from "../../../common/domain-error"; +import type { SqlTableAccessContext } from "../../platform/data/query"; +import { ExecuteSqlNode as LegacyExecuteSqlNode } from "../agent/nodes/execute-sql.node"; +import type { StructuredSqlGenerationArtifact } from "../agent/sql/sql-generation.service"; + +export interface ExecuteSqlNodeResult { + rows: Array>; + columns: string[]; + rowCount: number; + emptyResult: boolean; +} + +@Injectable() +export class ExecuteSqlNode { + constructor(private readonly executeSqlNode: LegacyExecuteSqlNode) {} + + async run(input: { + sqlArtifact?: StructuredSqlGenerationArtifact; + sql?: string; + validationArtifact: SqlValidationArtifactV1; + datasourceId: string; + sessionId: string; + requestId?: string; + accessContext?: SqlTableAccessContext; + semanticPlan?: SemanticPlanV1; + }): Promise { + if (input.validationArtifact.status !== "passed") { + throw new DomainError( + "SQL_EXECUTE_PRECONDITION_FAILED", + "execute-sql node requires a passed validation artifact", + 422, + { + validationArtifact: input.validationArtifact + } + ); + } + + const sql = input.sqlArtifact?.sql ?? input.sql; + if (!sql?.trim()) { + throw new DomainError( + "SQL_EXECUTE_PRECONDITION_FAILED", + "execute-sql node requires SQL before execution", + 422 + ); + } + + const result = await this.executeSqlNode.run({ + sql, + sqlArtifact: input.sqlArtifact, + datasourceId: input.datasourceId, + sessionId: input.sessionId, + requestId: input.requestId, + accessContext: input.accessContext, + semanticPlan: input.semanticPlan + }); + + return { + rows: result.rows, + columns: result.columns, + rowCount: result.rows.length, + emptyResult: result.rows.length === 0 + }; + } +} diff --git a/apps/backend/src/modules/conversation/nodes/generate-sql.node.ts b/apps/backend/src/modules/conversation/nodes/generate-sql.node.ts new file mode 100644 index 0000000..8bbce44 --- /dev/null +++ b/apps/backend/src/modules/conversation/nodes/generate-sql.node.ts @@ -0,0 +1,190 @@ +import { Injectable } from "@nestjs/common"; +import type { + SqlCorrectionGroundingV1, + DatasourceType, + PromptTemplateTraceEvidence, + SemanticContextPackV1, + SemanticPlanV1, + Text2SqlV2SmartDefaultsEvidenceV1 +} from "@text2sql/shared-types"; +import { DomainError } from "../../../common/domain-error"; +import type { + LlmGatewayStreamEvent, + LlmGatewayToolDefinition +} from "../../llm/llm-gateway.interface"; +import { + SqlGenerationService, + type SqlEvidenceCoverage, + type SqlGenerationCause, + type SqlGenerationExplicitPinningEvidence, + type StructuredSqlGenerationArtifact +} from "../agent/sql/sql-generation.service"; +import type { SqlSemanticIntent } from "../agent/sql/sql-prompt.builder"; +import type { + RagContextPack, + RagRetrievalChunkPayload +} from "../../rag/retrieval/rag-retrieval.types"; + +export interface GenerateSqlNodeResult { + draft: { + provider: string; + model: string; + modelCatalogId?: string; + sql: string; + explanation: string; + rawText: string; + prompt: { + systemPrompt: string; + userPrompt: string; + }; + promptTemplate?: PromptTemplateTraceEvidence; + smartDefaults?: Text2SqlV2SmartDefaultsEvidenceV1; + retryCount?: number; + semanticIntent?: SqlSemanticIntent; + coverage?: SqlEvidenceCoverage; + semanticPlan?: SemanticPlanV1; + semanticContextPack?: SemanticContextPackV1; + }; + artifact: StructuredSqlGenerationArtifact; +} + +@Injectable() +export class GenerateSqlNode { + constructor(private readonly sqlGenerationService: SqlGenerationService) {} + + async run(input: { + question: string; + datasourceType?: DatasourceType; + modelCatalogId?: string; + datasourceId?: string; + workspaceId?: string; + semanticIntent?: SqlSemanticIntent; + selectedContext?: RagRetrievalChunkPayload[]; + semanticContextPack?: RagContextPack; + semanticPlan: SemanticPlanV1; + explicitPinning?: SqlGenerationExplicitPinningEvidence; + cause?: SqlGenerationCause; + retryReason?: string; + correctionGrounding?: SqlCorrectionGroundingV1; + stream?: boolean; + tools?: Record; + onEvent?: (event: LlmGatewayStreamEvent) => Promise | void; + }): Promise { + const routeKind = this.resolveRouteKind(input.semanticPlan); + if (routeKind !== "text_to_sql") { + throw new DomainError( + "SEMANTIC_PLAN_DIRECT_ANSWER_REQUIRED", + `semantic-plan route ${routeKind} cannot enter generate-sql node`, + 422, + { + semanticPlan: input.semanticPlan, + routeKind + } + ); + } + const blockedObligationIds = + input.semanticPlan.planLedger?.summary.failedHardBlockerIds ?? []; + if (blockedObligationIds.length > 0) { + throw new DomainError( + "SEMANTIC_PLAN_LEDGER_GATE_BLOCKED", + "semantic-plan ledger gate blocked SQL generation", + 422, + { + semanticPlan: input.semanticPlan, + blockedObligationIds + } + ); + } + + const draft = input.stream + ? await this.sqlGenerationService.stream( + input.question, + { + datasourceId: input.datasourceId, + workspaceId: input.workspaceId, + datasourceType: input.datasourceType, + modelCatalogId: input.modelCatalogId, + selectedContext: input.selectedContext, + semanticContextPack: input.semanticContextPack, + semanticIntent: input.semanticIntent, + explicitPinning: input.explicitPinning, + semanticPlan: input.semanticPlan, + correctionGrounding: input.correctionGrounding + }, + { + tools: input.tools, + onEvent: input.onEvent + } + ) + : await this.sqlGenerationService.generate(input.question, { + datasourceId: input.datasourceId, + workspaceId: input.workspaceId, + datasourceType: input.datasourceType, + modelCatalogId: input.modelCatalogId, + selectedContext: input.selectedContext, + semanticContextPack: input.semanticContextPack, + semanticIntent: input.semanticIntent, + explicitPinning: input.explicitPinning, + semanticPlan: input.semanticPlan, + correctionGrounding: input.correctionGrounding + }); + + return { + draft: { + ...draft, + semanticContextPack: this.toNodeContextPack( + draft.semanticPlan, + input.semanticContextPack + ) + }, + artifact: this.sqlGenerationService.buildStructuredArtifact({ + draft, + datasourceType: input.datasourceType, + cause: input.cause ?? "initial", + retryReason: input.retryReason, + correctionGrounding: input.correctionGrounding + }) + }; + } + + private resolveRouteKind( + plan: SemanticPlanV1 + ): "text_to_sql" | "metadata" | "general" | "clarify" | "fail_closed" { + const routeFilter = plan.filters?.find((item) => item.startsWith("route_kind:")); + if (routeFilter) { + const value = routeFilter.slice("route_kind:".length).trim(); + if ( + value === "text_to_sql" || + value === "metadata" || + value === "general" || + value === "clarify" || + value === "fail_closed" + ) { + return value; + } + } + if (plan.route === "clarify") { + return "clarify"; + } + if (plan.route === "reject") { + return "fail_closed"; + } + return "text_to_sql"; + } + + private toNodeContextPack( + semanticPlan: SemanticPlanV1 | undefined, + contextPack?: RagContextPack + ): SemanticContextPackV1 | undefined { + if (!contextPack) { + return undefined; + } + return { + status: contextPack.status, + selectedEvidenceIds: semanticPlan?.evidenceRefs ?? [], + selectedTables: semanticPlan?.selectedTables ?? [], + selectedColumns: semanticPlan?.selectedColumns ?? [], + warnings: contextPack.degrade_reasons + }; + } +} diff --git a/apps/backend/src/modules/conversation/nodes/intake.node.ts b/apps/backend/src/modules/conversation/nodes/intake.node.ts new file mode 100644 index 0000000..00a0f01 --- /dev/null +++ b/apps/backend/src/modules/conversation/nodes/intake.node.ts @@ -0,0 +1,301 @@ +import { Injectable } from "@nestjs/common"; +import type { + ClarificationPrompt, + ContextEnvelope, + Text2SqlV2FailureSemantic +} from "@text2sql/shared-types"; +import type { SqlSemanticIntent } from "../agent/sql/sql-prompt.builder"; +import { ClarifyNode } from "../agent/nodes/clarify.node"; + +export type IntakeRouteKind = + | "needs_clarification" + | "general" + | "metadata" + | "text_to_sql" + | "unsafe" + | "unsupported"; + +export interface IntakeRouteArtifact { + originalQuestion: string; + normalizedQuestion: string; + standaloneQuestion: string; + route: IntakeRouteKind; + reasonCodes: string[]; + confidence: number; + evidenceRefs: string[]; + semanticIntent?: SqlSemanticIntent; + clarification?: ClarificationPrompt; + directAnswer?: string; + failure?: Text2SqlV2FailureSemantic; +} + +const GENERAL_INTENT_REGEX = + /^(你好|您好|hi|hello|thanks|谢谢|help|帮助|你是谁|你能做什么)(?:$|\s|[，。,.!?])|(?:什么是|解释|说明).{0,24}(?:口径|定义|含义)|(?:口径|定义|含义)(?:是什么|说明|解释)/i; +const METADATA_INTENT_REGEX = + /(有哪些表|哪些表|schema|表结构|字段|列名|show\s+tables|describe|sqlite_master|sqlite_schema|information_schema|pg_catalog|pragma|元数据|数据库结构)/i; +const UNSAFE_WRITE_REGEX = + /^\s*(insert|update|delete|drop|alter|truncate|create|replace|merge|grant|revoke)\b|\b(删除数据|修改数据|更新数据|写入数据|创建表|删表)\b/i; +const UNSUPPORTED_TASK_REGEX = + /(发邮件|发送邮件|send\s+email|生成\s*ppt|powerpoint|做幻灯片|导出\s*ppt)/i; +const FOLLOW_UP_PREFIX_REGEX = /^(那|那么|这个|这些|它们|those|them|that)/i; +const COUNT_INTENT_REGEX = + /(多少|几条|几笔|总数|数量|计数|count|人数|单量|订单量|客户数|用户数)/i; + +@Injectable() +export class IntakeNode { + constructor(private readonly clarifyNode: ClarifyNode) {} + + run(input: { + question: string; + contextEnvelope?: ContextEnvelope; + }): IntakeRouteArtifact { + const originalQuestion = input.question; + const normalizedQuestion = this.normalizeQuestion(input.question); + const standaloneQuestion = this.buildStandaloneQuestion( + normalizedQuestion, + input.contextEnvelope + ); + const evidenceRefs = this.buildEvidenceRefs(input.contextEnvelope); + + if (!normalizedQuestion) { + return this.buildRejectedArtifact({ + originalQuestion, + normalizedQuestion, + standaloneQuestion, + route: "unsupported", + reasonCodes: ["empty_question"], + evidenceRefs, + message: "问题为空，当前无法建立安全的 Text2SQL 路径。" + }); + } + + if (UNSUPPORTED_TASK_REGEX.test(normalizedQuestion)) { + return this.buildRejectedArtifact({ + originalQuestion, + normalizedQuestion, + standaloneQuestion, + route: "unsupported", + reasonCodes: ["unsupported_non_sql_task"], + evidenceRefs, + message: "当前请求不属于 Text2SQL/元数据解释范围，已拒绝执行。" + }); + } + + if (UNSAFE_WRITE_REGEX.test(normalizedQuestion)) { + return this.buildRejectedArtifact({ + originalQuestion, + normalizedQuestion, + standaloneQuestion, + route: "unsafe", + reasonCodes: ["unsafe_write_intent"], + evidenceRefs, + message: "检测到写操作或破坏性请求，系统已按 fail-closed 拒绝。" + }); + } + + if (METADATA_INTENT_REGEX.test(normalizedQuestion)) { + return { + originalQuestion, + normalizedQuestion, + standaloneQuestion, + route: "metadata", + reasonCodes: ["metadata_intent_detected"], + confidence: 0.95, + evidenceRefs, + semanticIntent: "metadata", + directAnswer: + "这是元数据问题，我会基于可访问的表结构与语义证据直接说明，不执行 SQL。" + }; + } + + if (GENERAL_INTENT_REGEX.test(normalizedQuestion)) { + return { + originalQuestion, + normalizedQuestion, + standaloneQuestion, + route: "general", + reasonCodes: ["general_intent_detected"], + confidence: 0.84, + evidenceRefs, + semanticIntent: "general", + directAnswer: "这是通用说明问题，不需要执行 SQL；我会基于已有语义证据直接解释。" + }; + } + + const clarificationDecision = this.clarifyNode.evaluate( + normalizedQuestion, + input.contextEnvelope + ); + if ( + clarificationDecision.decisionSource === "sql-write-intent" || + clarificationDecision.reasonCodes.includes("bypass_sql_write_intent") + ) { + return this.buildRejectedArtifact({ + originalQuestion, + normalizedQuestion, + standaloneQuestion, + route: "unsafe", + reasonCodes: this.unique([ + ...clarificationDecision.reasonCodes, + "unsafe_write_intent" + ]), + evidenceRefs, + message: "检测到写操作或破坏性请求，系统已按 fail-closed 拒绝。" + }); + } + + if (clarificationDecision.reasonCodes.includes("clarification_round_limit_reached")) { + return this.buildRejectedArtifact({ + originalQuestion, + normalizedQuestion, + standaloneQuestion, + route: "unsupported", + reasonCodes: clarificationDecision.reasonCodes, + evidenceRefs, + message: clarificationDecision.reason + }); + } + + if (clarificationDecision.shouldClarify) { + return { + originalQuestion, + normalizedQuestion, + standaloneQuestion, + route: "needs_clarification", + reasonCodes: clarificationDecision.reasonCodes, + confidence: this.confidenceFromDecision(clarificationDecision.confidenceLevel), + evidenceRefs, + semanticIntent: this.resolveSemanticIntent(normalizedQuestion), + clarification: this.clarifyNode.toPrompt(clarificationDecision) + }; + } + + return { + originalQuestion, + normalizedQuestion, + standaloneQuestion, + route: "text_to_sql", + reasonCodes: this.unique([ + ...clarificationDecision.reasonCodes, + "intake_ready_for_text_to_sql" + ]), + confidence: this.confidenceFromDecision(clarificationDecision.confidenceLevel), + evidenceRefs, + semanticIntent: this.resolveSemanticIntent(normalizedQuestion) + }; + } + + private buildRejectedArtifact(input: { + originalQuestion: string; + normalizedQuestion: string; + standaloneQuestion: string; + route: "unsafe" | "unsupported"; + reasonCodes: string[]; + evidenceRefs: string[]; + message: string; + }): IntakeRouteArtifact { + return { + originalQuestion: input.originalQuestion, + normalizedQuestion: input.normalizedQuestion, + standaloneQuestion: input.standaloneQuestion, + route: input.route, + reasonCodes: input.reasonCodes, + confidence: 0.98, + evidenceRefs: input.evidenceRefs, + semanticIntent: "general", + failure: { + code: + input.route === "unsafe" + ? "INTAKE_UNSAFE_REQUEST" + : "INTAKE_UNSUPPORTED_REQUEST", + message: input.message, + category: "intake", + terminal: true, + correctable: false + } + }; + } + + private normalizeQuestion(question: string): string { + return question.trim().replace(/\s+/g, " "); + } + + private buildStandaloneQuestion( + normalizedQuestion: string, + contextEnvelope?: ContextEnvelope + ): string { + if (!FOLLOW_UP_PREFIX_REGEX.test(normalizedQuestion)) { + return normalizedQuestion; + } + const hints: string[] = []; + if (contextEnvelope?.metricDefinition?.trim()) { + hints.push(`metric=${contextEnvelope.metricDefinition.trim()}`); + } + if ((contextEnvelope?.pinnedTables ?? []).length > 0) { + hints.push(`tables=${contextEnvelope?.pinnedTables?.slice(0, 3).join(", ")}`); + } else if ((contextEnvelope?.mustIncludeTables ?? []).length > 0) { + hints.push( + `tables=${contextEnvelope?.mustIncludeTables?.slice(0, 3).join(", ")}` + ); + } + if (contextEnvelope?.timeRange?.from || contextEnvelope?.timeRange?.to) { + hints.push( + `time=${contextEnvelope.timeRange.from ?? "?"}..${contextEnvelope.timeRange.to ?? "?"}` + ); + } + if (hints.length === 0) { + return normalizedQuestion; + } + return `${normalizedQuestion} (context: ${hints.join("; ")})`; + } + + private buildEvidenceRefs(contextEnvelope?: ContextEnvelope): string[] { + const evidenceRefs: string[] = []; + if (contextEnvelope?.metricDefinition?.trim()) { + evidenceRefs.push("context:metric_definition"); + } + if ((contextEnvelope?.pinnedTables ?? []).length > 0) { + evidenceRefs.push("context:pinned_tables"); + } + if ((contextEnvelope?.pinnedColumns ?? []).length > 0) { + evidenceRefs.push("context:pinned_columns"); + } + if ((contextEnvelope?.mustIncludeTables ?? []).length > 0) { + evidenceRefs.push("context:must_include_tables"); + } + if ((contextEnvelope?.mustExcludeTables ?? []).length > 0) { + evidenceRefs.push("context:must_exclude_tables"); + } + if (contextEnvelope?.timeRange?.from || contextEnvelope?.timeRange?.to) { + evidenceRefs.push("context:time_range"); + } + if ((contextEnvelope?.businessConstraints ?? []).length > 0) { + evidenceRefs.push("context:business_constraints"); + } + return evidenceRefs; + } + + private resolveSemanticIntent(question: string): SqlSemanticIntent { + if (METADATA_INTENT_REGEX.test(question)) { + return "metadata"; + } + if (COUNT_INTENT_REGEX.test(question)) { + return "count"; + } + return "general"; + } + + private confidenceFromDecision(value?: string): number { + if (value === "high") { + return 0.92; + } + if (value === "medium") { + return 0.72; + } + return 0.42; + } + + private unique(values: string[]): string[] { + return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean))); + } +} diff --git a/apps/backend/src/modules/conversation/nodes/retrieve-context.node.ts b/apps/backend/src/modules/conversation/nodes/retrieve-context.node.ts new file mode 100644 index 0000000..e6899ae --- /dev/null +++ b/apps/backend/src/modules/conversation/nodes/retrieve-context.node.ts @@ -0,0 +1,92 @@ +import { Injectable } from "@nestjs/common"; +import type { Datasource } from "@text2sql/shared-types"; +import { + type RetrievedKnowledge, + type RetrievedKnowledgeTypedSummary, + RetrieveKnowledgeNode +} from "../agent/nodes/retrieve-knowledge.node"; + +export interface RetrieveContextNodeInput { + question: string; + datasourceId: string; + datasource?: Datasource; + runId: string; + workspaceId?: string; + allowedTables?: string[]; + modelCatalogId?: string; + pinnedTables?: string[]; + pinnedColumns?: string[]; +} + +export interface RetrieveContextNodeState { + status: "ready" | "degraded"; + typedSummary: RetrievedKnowledgeTypedSummary; + evidenceRefs: string[]; + retrievalBundleRef?: { + runId: string; + datasourceId: string; + indexVersionId?: string; + status: "ready" | "degraded"; + degradeReasons: string[]; + }; + selectedContextSummary: { + count: number; + snippetPreviews: string[]; + }; + warnings: string[]; +} + +export interface RetrieveContextNodeOutput { + state: RetrieveContextNodeState; + artifact: RetrievedKnowledge; +} + +@Injectable() +export class RetrieveContextNode { + constructor(private readonly retrieveKnowledgeNode: RetrieveKnowledgeNode) {} + + async run(input: RetrieveContextNodeInput): Promise { + const artifact = await this.retrieveKnowledgeNode.run(input); + const bundle = artifact.retrievalBundle; + const typedSummary = artifact.typedSummary; + const warnings = this.unique([ + ...(artifact.contextPack?.degrade_reasons ?? artifact.contextPack?.degradeReasons ?? []), + ...(typedSummary.denseReason + ? [`dense_${typedSummary.denseState}:${typedSummary.denseReason}`] + : []), + ...(typedSummary.rerankReason + ? [`rerank_${typedSummary.rerankState}:${typedSummary.rerankReason}`] + : []), + ...typedSummary.degradeReasons + ]); + + return { + state: { + status: artifact.status, + typedSummary, + evidenceRefs: artifact.evidenceRefs.slice(0, 128), + retrievalBundleRef: bundle + ? { + runId: bundle.run_id, + datasourceId: bundle.datasource_id, + indexVersionId: bundle.index_version_id, + status: bundle.status, + degradeReasons: bundle.degrade_reasons ?? [] + } + : undefined, + selectedContextSummary: { + count: bundle?.selected_context?.length ?? 0, + snippetPreviews: (bundle?.selected_context ?? []) + .map((chunk) => chunk.content.slice(0, 160)) + .slice(0, 5) + }, + warnings + }, + artifact + }; + } + + private unique(values: string[]): string[] { + return Array.from(new Set(values.filter((value) => value.trim().length > 0))); + } +} diff --git a/apps/backend/src/modules/conversation/nodes/semantic-plan.node.ts b/apps/backend/src/modules/conversation/nodes/semantic-plan.node.ts new file mode 100644 index 0000000..60ab3c4 --- /dev/null +++ b/apps/backend/src/modules/conversation/nodes/semantic-plan.node.ts @@ -0,0 +1,42 @@ +import { Injectable } from "@nestjs/common"; +import type { + SemanticContextPackV1, + SemanticPlanV1 +} from "@text2sql/shared-types"; +import type { SqlSemanticIntent } from "../agent/sql/sql-prompt.builder"; +import { + SemanticPlanService, + type BuildSemanticPlanInput +} from "../adapters/semantic-plan.service"; +import type { SemanticPlanValidationResult } from "../adapters/semantic-plan.validator"; + +export type SemanticPlanNodeRoute = + | "ready" + | "needs_clarification" + | "direct_answer" + | "fail_closed"; + +export interface SemanticPlanNodeResult { + route: SemanticPlanNodeRoute; + plan: SemanticPlanV1; + validation: SemanticPlanValidationResult; +} + +@Injectable() +export class SemanticPlanNode { + constructor(private readonly semanticPlanService: SemanticPlanService) {} + + run( + input: BuildSemanticPlanInput & { + contextPack: SemanticContextPackV1; + semanticIntent?: SqlSemanticIntent; + } + ): SemanticPlanNodeResult { + const result = this.semanticPlanService.build(input); + return { + route: result.validation.outcome, + plan: result.plan, + validation: result.validation + }; + } +} diff --git a/apps/backend/src/modules/conversation/nodes/validate-sql.node.ts b/apps/backend/src/modules/conversation/nodes/validate-sql.node.ts new file mode 100644 index 0000000..2b428f0 --- /dev/null +++ b/apps/backend/src/modules/conversation/nodes/validate-sql.node.ts @@ -0,0 +1,48 @@ +import { Injectable } from "@nestjs/common"; +import type { + DatasourceType, + SemanticPlanV1, + SqlValidationArtifactV1 +} from "@text2sql/shared-types"; +import type { SqlTableAccessContext } from "../../platform/data/query"; +import { + SqlValidationService, + type SqlValidationOutcome +} from "../adapters/sql-validation.service"; +import type { StructuredSqlGenerationArtifact } from "../agent/sql/sql-generation.service"; + +export interface ValidateSqlNodeResult { + outcome: SqlValidationOutcome; + artifact: SqlValidationArtifactV1; +} + +@Injectable() +export class ValidateSqlNode { + constructor(private readonly sqlValidationService: SqlValidationService) {} + + async run(input: { + sql?: string; + sqlArtifact?: StructuredSqlGenerationArtifact; + datasourceId?: string; + datasourceType?: DatasourceType; + semanticPlan?: SemanticPlanV1; + accessContext?: SqlTableAccessContext; + allowedTables?: string[]; + }): Promise { + const sql = input.sqlArtifact?.sql ?? input.sql ?? ""; + const artifact = await this.sqlValidationService.validate({ + sql, + datasourceId: input.datasourceId, + datasourceType: input.datasourceType, + semanticPlan: input.semanticPlan, + sqlArtifact: input.sqlArtifact, + accessContext: input.accessContext, + allowedTables: input.allowedTables + }); + + return { + outcome: this.sqlValidationService.resolveOutcome(artifact), + artifact + }; + } +} diff --git a/apps/backend/src/modules/conversation/projection/read-model/run-view-support.guard.ts b/apps/backend/src/modules/conversation/projection/read-model/run-view-support.guard.ts new file mode 100644 index 0000000..58f76e3 --- /dev/null +++ b/apps/backend/src/modules/conversation/projection/read-model/run-view-support.guard.ts @@ -0,0 +1,5 @@ +export { + assertSupportedV2RunReadModel, + isSupportedV2RunReadModel +} from "../../../platform/read-model/run-view-support.guard"; +export type { AssertSupportedV2RunReadOptions } from "../../../platform/read-model/run-view-support.guard"; diff --git a/apps/backend/src/modules/conversation/runtime/evaluation/text2sql-v2-evaluation.service.ts b/apps/backend/src/modules/conversation/runtime/evaluation/text2sql-v2-evaluation.service.ts new file mode 100644 index 0000000..b908db1 --- /dev/null +++ b/apps/backend/src/modules/conversation/runtime/evaluation/text2sql-v2-evaluation.service.ts @@ -0,0 +1,524 @@ +import { Injectable } from "@nestjs/common"; + +export const TEXT2SQL_V2_REQUIRED_FIXTURE_FAMILIES = [ + "chinese-question", + "alias", + "ambiguous-business-term", + "multi-table-join", + "metrics", + "filters", + "follow-up", + "metadata-general", + "unsafe-write", + "dense-unavailable", + "rerank-unavailable", + "correction-success", + "terminal-governance-failure", + "plain-general-no-sql", + "runtime-plan-consistency", + "artifact-ref-compaction", + "smart-defaults-evidence", + "large-context-compaction", + "validation-diagnostics", + "correction-grounding", + "execution-preview", + "all-stage-stream-lifecycle", + "ledger-single-table-fulfillment", + "ledger-multi-table-join-fulfillment", + "ledger-missing-table-evidence", + "ledger-missing-required-column", + "ledger-missing-join-path", + "ledger-warning-only-degraded-context", + "ledger-correctable-sql-coverage-miss", + "ledger-terminal-governance-safety-miss", + "ledger-metric-time-grain-ambiguity" +] as const; + +export type Text2SqlV2RequiredFixtureFamily = + (typeof TEXT2SQL_V2_REQUIRED_FIXTURE_FAMILIES)[number]; + +export interface Text2SqlV2EvalCaseTraceability { + fixtureFamilies: string[]; + behaviorTests: string[]; + flowNodes: string[]; +} + +export interface Text2SqlV2EvalCase { + id: string; + question: string; + retrievalRelevance: number; + rerankLift: number; + planCoveragePassed: boolean; + validationPassed: boolean; + correctionAttempted: boolean; + correctionSucceeded: boolean; + clarified: boolean; + executionSucceeded: boolean; + userVisibleFailureQuality: number; + latencyMs: number; + denseUnavailable: boolean; + rerankUnavailable: boolean; + ledgerObligationsCreated?: boolean; + ledgerGenerationClaimsPresent?: boolean; + ledgerValidationFulfilled?: boolean; + ledgerTerminalClassificationCorrect?: boolean; + ledgerClarificationTriggered?: boolean; + ledgerHardBlockerFalsePass?: boolean; + traceability?: Text2SqlV2EvalCaseTraceability; +} + +export interface Text2SqlV2EvalRolloutThresholds { + minSamples: number; + minRetrievalRelevance: number; + minRerankLift: number; + minPlanCoverageRate: number; + minValidationPassRate: number; + minCorrectionSuccessRate: number; + minExecutionSuccessRate: number; + minUserVisibleFailureQuality: number; + maxClarificationRate: number; + maxDenseUnavailableRate: number; + maxRerankUnavailableRate: number; + maxLatencyP95Ms: number; + minLedgerObligationCreationRate: number; + minLedgerGenerationClaimRate: number; + minLedgerValidationFulfillmentRate: number; + minLedgerTerminalClassificationRate: number; + maxLedgerHardBlockerFalsePassRate: number; +} + +export interface Text2SqlV2EvalRolloutRecommendation { + gatePass: boolean; + recommendedStage: "direct_v2_go" | "hold" | "rollback_or_hold"; + rollbackSuggested: boolean; + reasons: string[]; + thresholds: Text2SqlV2EvalRolloutThresholds; +} + +export interface Text2SqlV2EvalTraceabilityFamilySummary { + family: string; + caseIds: string[]; + behaviorTests: string[]; + flowNodes: string[]; + gatePass: boolean; + reasons: string[]; +} + +export interface Text2SqlV2EvalTraceabilitySummary { + requiredFamilies: string[]; + coveredFamilies: string[]; + missingFamilies: string[]; + familyCoverage: Text2SqlV2EvalTraceabilityFamilySummary[]; + gatePass: boolean; +} + +export interface Text2SqlV2EvalSummary { + totalCases: number; + retrievalRelevance: number; + rerankLift: number; + planCoverageRate: number; + validationPassRate: number; + correctionSuccessRate: number; + clarificationRate: number; + executionSuccessRate: number; + userVisibleFailureQuality: number; + latencyP50Ms: number; + latencyP95Ms: number; + denseUnavailableRate: number; + rerankUnavailableRate: number; + ledgerObligationCreationRate: number; + ledgerGenerationClaimRate: number; + ledgerValidationFulfillmentRate: number; + ledgerTerminalClassificationRate: number; + ledgerClarificationTriggeredRate: number; + ledgerHardBlockerFalsePassRate: number; + traceability: Text2SqlV2EvalTraceabilitySummary; + rollout: Text2SqlV2EvalRolloutRecommendation; +} + +type Text2SqlV2EvalMetricSummary = Omit; + +const DEFAULT_ROLLOUT_THRESHOLDS: Text2SqlV2EvalRolloutThresholds = { + minSamples: 8, + minRetrievalRelevance: 0.75, + minRerankLift: 0.08, + minPlanCoverageRate: 0.75, + minValidationPassRate: 0.7, + minCorrectionSuccessRate: 0.5, + minExecutionSuccessRate: 0.7, + minUserVisibleFailureQuality: 0.7, + maxClarificationRate: 0.35, + maxDenseUnavailableRate: 0.35, + maxRerankUnavailableRate: 0.3, + maxLatencyP95Ms: 2600, + minLedgerObligationCreationRate: 0.75, + minLedgerGenerationClaimRate: 0.7, + minLedgerValidationFulfillmentRate: 0.7, + minLedgerTerminalClassificationRate: 0.9, + maxLedgerHardBlockerFalsePassRate: 0 +}; + +// Small tolerance avoids false holds from fixture rounding/noise near thresholds. +const GATE_COMPARISON_TOLERANCE = 0.001; + +@Injectable() +export class Text2SqlV2EvaluationService { + summarize( + cases: Text2SqlV2EvalCase[], + thresholds: Text2SqlV2EvalRolloutThresholds = DEFAULT_ROLLOUT_THRESHOLDS + ): Text2SqlV2EvalSummary { + const totalCases = cases.length; + const traceability = this.summarizeTraceability(cases); + if (totalCases === 0) { + const metricSummary: Text2SqlV2EvalMetricSummary = { + totalCases: 0, + retrievalRelevance: 0, + rerankLift: 0, + planCoverageRate: 0, + validationPassRate: 0, + correctionSuccessRate: 0, + clarificationRate: 0, + executionSuccessRate: 0, + userVisibleFailureQuality: 0, + latencyP50Ms: 0, + latencyP95Ms: 0, + denseUnavailableRate: 0, + rerankUnavailableRate: 0, + ledgerObligationCreationRate: 0, + ledgerGenerationClaimRate: 0, + ledgerValidationFulfillmentRate: 0, + ledgerTerminalClassificationRate: 0, + ledgerClarificationTriggeredRate: 0, + ledgerHardBlockerFalsePassRate: 0 + }; + const rollout = this.evaluateRollout(metricSummary, thresholds); + return { + ...metricSummary, + traceability, + rollout + }; + } + + const retrievalRelevance = + cases.reduce((sum, item) => sum + this.clamp(item.retrievalRelevance), 0) / + totalCases; + const rerankLift = + cases.reduce((sum, item) => sum + this.clamp(item.rerankLift), 0) / totalCases; + const planCoverageRate = + cases.filter((item) => item.planCoveragePassed).length / totalCases; + const validationPassRate = + cases.filter((item) => item.validationPassed).length / totalCases; + const executionSuccessRate = + cases.filter((item) => item.executionSucceeded).length / totalCases; + + const correctionCases = cases.filter((item) => item.correctionAttempted); + const correctionSuccessRate = + correctionCases.length === 0 + ? 1 + : correctionCases.filter((item) => item.correctionSucceeded).length / + correctionCases.length; + + const clarificationRate = + cases.filter((item) => item.clarified).length / totalCases; + + const userVisibleFailureQuality = + cases.reduce( + (sum, item) => sum + this.clamp(item.userVisibleFailureQuality), + 0 + ) / totalCases; + + const latencies = cases + .map((item) => item.latencyMs) + .filter((value) => Number.isFinite(value) && value >= 0) + .sort((a, b) => a - b); + + const denseUnavailableRate = + cases.filter((item) => item.denseUnavailable).length / totalCases; + const rerankUnavailableRate = + cases.filter((item) => item.rerankUnavailable).length / totalCases; + const ledgerObligationCreationRate = + cases.filter((item) => item.ledgerObligationsCreated ?? item.planCoveragePassed).length / + totalCases; + const ledgerGenerationClaimRate = + cases.filter((item) => item.ledgerGenerationClaimsPresent ?? item.validationPassed).length / + totalCases; + const ledgerValidationFulfillmentRate = + cases.filter((item) => item.ledgerValidationFulfilled ?? item.validationPassed).length / + totalCases; + const terminalLedgerCases = cases.filter( + (item) => + item.traceability?.fixtureFamilies.some((family) => + family.includes("terminal-governance") || + family.includes("unsafe-write") || + family.includes("ledger-terminal") + ) || item.ledgerTerminalClassificationCorrect !== undefined + ); + const ledgerTerminalClassificationRate = + terminalLedgerCases.length === 0 + ? 1 + : terminalLedgerCases.filter( + (item) => item.ledgerTerminalClassificationCorrect ?? !item.correctionAttempted + ).length / terminalLedgerCases.length; + const ledgerClarificationTriggeredRate = + cases.filter((item) => item.ledgerClarificationTriggered ?? false).length / + totalCases; + const ledgerHardBlockerFalsePassRate = + cases.filter((item) => item.ledgerHardBlockerFalsePass ?? false).length / + totalCases; + + const metricSummary: Text2SqlV2EvalMetricSummary = { + totalCases, + retrievalRelevance: Number(retrievalRelevance.toFixed(4)), + rerankLift: Number(rerankLift.toFixed(4)), + planCoverageRate: Number(planCoverageRate.toFixed(4)), + validationPassRate: Number(validationPassRate.toFixed(4)), + correctionSuccessRate: Number(correctionSuccessRate.toFixed(4)), + clarificationRate: Number(clarificationRate.toFixed(4)), + executionSuccessRate: Number(executionSuccessRate.toFixed(4)), + userVisibleFailureQuality: Number(userVisibleFailureQuality.toFixed(4)), + latencyP50Ms: this.percentile(latencies, 0.5), + latencyP95Ms: this.percentile(latencies, 0.95), + denseUnavailableRate: Number(denseUnavailableRate.toFixed(4)), + rerankUnavailableRate: Number(rerankUnavailableRate.toFixed(4)), + ledgerObligationCreationRate: Number(ledgerObligationCreationRate.toFixed(4)), + ledgerGenerationClaimRate: Number(ledgerGenerationClaimRate.toFixed(4)), + ledgerValidationFulfillmentRate: Number(ledgerValidationFulfillmentRate.toFixed(4)), + ledgerTerminalClassificationRate: Number(ledgerTerminalClassificationRate.toFixed(4)), + ledgerClarificationTriggeredRate: Number(ledgerClarificationTriggeredRate.toFixed(4)), + ledgerHardBlockerFalsePassRate: Number(ledgerHardBlockerFalsePassRate.toFixed(4)) + }; + + return { + ...metricSummary, + traceability, + rollout: this.evaluateRollout(metricSummary, thresholds) + }; + } + + private summarizeTraceability( + cases: Text2SqlV2EvalCase[] + ): Text2SqlV2EvalTraceabilitySummary { + const familyIndex = new Map< + string, + { + caseIds: Set; + behaviorTests: Set; + flowNodes: Set; + } + >(); + + for (const item of cases) { + const traceability = item.traceability; + if (!traceability) { + continue; + } + const families = this.normalizeStringArray(traceability.fixtureFamilies); + const behaviorTests = this.normalizeStringArray(traceability.behaviorTests); + const flowNodes = this.normalizeStringArray(traceability.flowNodes); + for (const family of families) { + const current = familyIndex.get(family) ?? { + caseIds: new Set(), + behaviorTests: new Set(), + flowNodes: new Set() + }; + current.caseIds.add(item.id); + for (const behaviorTest of behaviorTests) { + current.behaviorTests.add(behaviorTest); + } + for (const flowNode of flowNodes) { + current.flowNodes.add(flowNode); + } + familyIndex.set(family, current); + } + } + + const familyCoverage = TEXT2SQL_V2_REQUIRED_FIXTURE_FAMILIES.map((family) => { + const coverage = familyIndex.get(family); + const reasons: string[] = []; + if (!coverage || coverage.caseIds.size === 0) { + reasons.push("missing_eval_cases"); + } + if (!coverage || coverage.behaviorTests.size === 0) { + reasons.push("missing_behavior_test_traceability"); + } + if (!coverage || coverage.flowNodes.size === 0) { + reasons.push("missing_flow_node_traceability"); + } + return { + family, + caseIds: [...(coverage?.caseIds ?? [])].sort(), + behaviorTests: [...(coverage?.behaviorTests ?? [])].sort(), + flowNodes: [...(coverage?.flowNodes ?? [])].sort(), + gatePass: reasons.length === 0, + reasons + }; + }); + + const missingFamilies = familyCoverage + .filter((item) => item.reasons.length > 0) + .map((item) => item.family); + const coveredFamilies = familyCoverage + .filter((item) => item.reasons.length === 0) + .map((item) => item.family); + + return { + requiredFamilies: [...TEXT2SQL_V2_REQUIRED_FIXTURE_FAMILIES], + coveredFamilies, + missingFamilies, + familyCoverage, + gatePass: missingFamilies.length === 0 + }; + } + + private evaluateRollout( + summary: Text2SqlV2EvalMetricSummary, + thresholds: Text2SqlV2EvalRolloutThresholds + ): Text2SqlV2EvalRolloutRecommendation { + const reasons: string[] = []; + if (summary.totalCases < thresholds.minSamples) { + reasons.push("sample_not_ready"); + } + if ( + summary.retrievalRelevance + GATE_COMPARISON_TOLERANCE < + thresholds.minRetrievalRelevance + ) { + reasons.push("retrieval_relevance_below_threshold"); + } + if (summary.rerankLift + GATE_COMPARISON_TOLERANCE < thresholds.minRerankLift) { + reasons.push("rerank_lift_below_threshold"); + } + if ( + summary.planCoverageRate + GATE_COMPARISON_TOLERANCE < + thresholds.minPlanCoverageRate + ) { + reasons.push("plan_coverage_rate_below_threshold"); + } + if ( + summary.validationPassRate + GATE_COMPARISON_TOLERANCE < + thresholds.minValidationPassRate + ) { + reasons.push("validation_pass_rate_below_threshold"); + } + if ( + summary.correctionSuccessRate + GATE_COMPARISON_TOLERANCE < + thresholds.minCorrectionSuccessRate + ) { + reasons.push("correction_success_rate_below_threshold"); + } + if ( + summary.executionSuccessRate + GATE_COMPARISON_TOLERANCE < + thresholds.minExecutionSuccessRate + ) { + reasons.push("execution_success_rate_below_threshold"); + } + if ( + summary.userVisibleFailureQuality + GATE_COMPARISON_TOLERANCE < + thresholds.minUserVisibleFailureQuality + ) { + reasons.push("user_visible_failure_quality_below_threshold"); + } + if ( + summary.clarificationRate > + thresholds.maxClarificationRate + GATE_COMPARISON_TOLERANCE + ) { + reasons.push("clarification_rate_exceeded"); + } + if ( + summary.denseUnavailableRate > + thresholds.maxDenseUnavailableRate + GATE_COMPARISON_TOLERANCE + ) { + reasons.push("dense_unavailable_rate_exceeded"); + } + if ( + summary.rerankUnavailableRate > + thresholds.maxRerankUnavailableRate + GATE_COMPARISON_TOLERANCE + ) { + reasons.push("rerank_unavailable_rate_exceeded"); + } + if (summary.latencyP95Ms > thresholds.maxLatencyP95Ms + GATE_COMPARISON_TOLERANCE) { + reasons.push("latency_p95_exceeded"); + } + if ( + summary.ledgerObligationCreationRate + GATE_COMPARISON_TOLERANCE < + thresholds.minLedgerObligationCreationRate + ) { + reasons.push("ledger_obligation_creation_rate_below_threshold"); + } + if ( + summary.ledgerGenerationClaimRate + GATE_COMPARISON_TOLERANCE < + thresholds.minLedgerGenerationClaimRate + ) { + reasons.push("ledger_generation_claim_rate_below_threshold"); + } + if ( + summary.ledgerValidationFulfillmentRate + GATE_COMPARISON_TOLERANCE < + thresholds.minLedgerValidationFulfillmentRate + ) { + reasons.push("ledger_validation_fulfillment_rate_below_threshold"); + } + if ( + summary.ledgerTerminalClassificationRate + GATE_COMPARISON_TOLERANCE < + thresholds.minLedgerTerminalClassificationRate + ) { + reasons.push("ledger_terminal_classification_rate_below_threshold"); + } + if ( + summary.ledgerHardBlockerFalsePassRate > + thresholds.maxLedgerHardBlockerFalsePassRate + GATE_COMPARISON_TOLERANCE + ) { + reasons.push("ledger_hard_blocker_false_pass_rate_exceeded"); + } + + const rollbackSuggested = reasons.some((item) => + [ + "execution_success_rate_below_threshold", + "validation_pass_rate_below_threshold", + "user_visible_failure_quality_below_threshold", + "ledger_validation_fulfillment_rate_below_threshold", + "ledger_terminal_classification_rate_below_threshold", + "ledger_hard_blocker_false_pass_rate_exceeded" + ].includes(item) + ); + const gatePass = reasons.length === 0; + + return { + gatePass, + recommendedStage: gatePass + ? "direct_v2_go" + : rollbackSuggested + ? "rollback_or_hold" + : "hold", + rollbackSuggested, + reasons, + thresholds + }; + } + + private percentile(values: number[], p: number): number { + if (values.length === 0) { + return 0; + } + const index = Math.min( + values.length - 1, + Math.max(0, Math.ceil(values.length * p) - 1) + ); + return Math.round(values[index] ?? 0); + } + + private clamp(value: number): number { + if (!Number.isFinite(value)) { + return 0; + } + return Math.max(0, Math.min(1, value)); + } + + private normalizeStringArray(values: string[] | undefined): string[] { + if (!Array.isArray(values)) { + return []; + } + const normalized = values + .map((item) => (typeof item === "string" ? item.trim() : "")) + .filter((item) => item.length > 0); + return [...new Set(normalized)].sort(); + } +} diff --git a/apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper.ts b/apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper.ts new file mode 100644 index 0000000..ace2410 --- /dev/null +++ b/apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper.ts @@ -0,0 +1,370 @@ +import { Injectable } from "@nestjs/common"; +import type { + ExecutionTraceStep, + SqlRun, + Text2SqlV2RunArtifact, + Text2SqlV2RuntimePlanV1, + Text2SqlV2StageArtifact, + Text2SqlV2StageName +} from "@text2sql/shared-types"; +import { DomainError } from "../../../../common/domain-error"; +import { Text2SqlV2ArtifactBuilder } from "../../artifacts/text2sql-v2-artifact-builder"; +import { TEXT2SQL_V2_STAGE_ORDER } from "../../contracts/text2sql-v2.types"; +import { resolveText2SqlV2StageCatalogEntry } from "../../text2sql/stages/text2sql-stage-catalog"; +import type { Text2SqlV2LangGraphState } from "./text2sql-v2-langgraph.state"; + +export interface Text2SqlV2LangGraphProgressSummary { + enteredStages: string[]; + enteredStageCount: number; +} + +@Injectable() +export class Text2SqlV2LangGraphResultMapper { + constructor( + private readonly artifactBuilder: Text2SqlV2ArtifactBuilder + ) {} + + mapSqlRun(state: Text2SqlV2LangGraphState): SqlRun { + if (!state.answerResult && !state.failure) { + throw new DomainError( + "TEXT2SQL_V2_LANGGRAPH_RESULT_MISSING_ANSWER", + "LangGraph runtime completed without answer or terminal failure", + 500 + ); + } + + const status = + state.answerResult?.status ?? + (state.failure?.category === "execution" ? "failed" : "rejected"); + const provider = state.sqlDraft?.provider ?? state.preparedRun.session.modelProvider ?? "unknown"; + const model = state.sqlDraft?.model ?? state.preparedRun.session.modelName ?? undefined; + const traceSteps = this.mapTraceSteps(state); + const answer = + state.answerResult?.answer ?? + state.failure?.message ?? + "系统未返回结果。"; + const run: SqlRun = { + runId: state.runId, + sessionId: state.sessionId, + question: state.question, + status, + provider, + model, + sql: state.sqlGenerationArtifact?.sql, + explanation: state.sqlDraft?.explanation, + answer, + rows: state.executionResult?.rows, + columns: state.executionResult?.columns, + ...(status === "failed" || status === "rejected" + ? { + error: + state.failure?.message ?? + (status === "failed" + ? "Text2SQL execution failed" + : "Text2SQL request rejected") + } + : {}), + ...(state.answerResult?.mode === "clarification" && state.clarification + ? { clarification: state.clarification } + : {}), + trace: { + runId: state.runId, + provider, + retryCount: state.correctionAttemptCount, + steps: traceSteps, + ...(state.sqlDraft?.promptTemplate + ? { + promptTemplate: state.sqlDraft.promptTemplate + } + : {}), + ...(state.loopEvidence.length > 0 + ? { + loopEvidence: state.loopEvidence + } + : {}), + ...(state.terminationReason + ? { + terminationReason: state.terminationReason + } + : {}) + }, + llmRaw: null, + createdAt: state.completedAt ?? state.createdAt + }; + const v2Artifact = this.mapRunArtifact(state, run); + + return { + ...run, + trace: { + ...run.trace, + v2: v2Artifact + } + }; + } + + mapTraceSteps(state: Text2SqlV2LangGraphState): ExecutionTraceStep[] { + const rawSteps = + state.traceSteps.length > 0 + ? state.traceSteps + : this.buildFallbackTraceSteps(state.stageArtifacts); + + return rawSteps.map((step, index) => ({ + ...step, + sequence: step.sequence ?? index + 1, + stepId: step.stepId ?? `${state.runId}:${step.node}:${index + 1}`, + lifecycle: + step.lifecycle ?? + (step.status === "failed" + ? "failed" + : step.status === "skipped" + ? "skipped" + : "completed") + })); + } + + mapRunArtifact( + state: Text2SqlV2LangGraphState, + baseRun?: SqlRun + ): Text2SqlV2RunArtifact { + const run = + baseRun ?? + ({ + runId: state.runId, + sessionId: state.sessionId, + question: state.question, + status: "executionResult", + provider: + state.sqlDraft?.provider ?? + state.preparedRun.session.modelProvider ?? + "unknown", + model: state.sqlDraft?.model ?? state.preparedRun.session.modelName, + trace: { + runId: state.runId, + provider: + state.sqlDraft?.provider ?? + state.preparedRun.session.modelProvider ?? + "unknown", + retryCount: state.correctionAttemptCount, + steps: this.mapTraceSteps(state), + ...(state.loopEvidence.length > 0 + ? { + loopEvidence: state.loopEvidence + } + : {}), + ...(state.terminationReason + ? { + terminationReason: state.terminationReason + } + : {}) + }, + llmRaw: null, + createdAt: state.completedAt ?? state.createdAt + } as SqlRun); + + const stageArtifacts = this.resolveStageArtifacts(state.stageArtifacts); + + return this.artifactBuilder.buildRunArtifact(run, { + stageArtifacts, + contextPack: state.contextPack, + semanticPlan: state.semanticPlan, + sqlGeneration: state.sqlGenerationArtifact, + sqlValidation: state.sqlValidationArtifact, + planLedger: + state.sqlValidationArtifact?.ledgerFulfillment ?? + state.semanticPlan?.planLedger?.summary, + runtimePlan: this.resolveRuntimePlan(state, stageArtifacts), + smartDefaults: state.sqlGenerationArtifact?.smartDefaults + }); + } + + mapProgressSummary( + state: Text2SqlV2LangGraphState + ): Text2SqlV2LangGraphProgressSummary { + return { + enteredStages: [...state.stageProgress], + enteredStageCount: state.stageProgress.length + }; + } + + private resolveStageArtifacts( + artifacts: Text2SqlV2StageArtifact[] + ): Text2SqlV2StageArtifact[] { + const byStage = new Map(); + for (const artifact of artifacts) { + if (!this.isStageName(artifact.stage)) { + continue; + } + byStage.set(artifact.stage, artifact); + } + return TEXT2SQL_V2_STAGE_ORDER.map((stage) => { + return byStage.get(stage) ?? { stage, status: "skipped" }; + }); + } + + private buildFallbackTraceSteps( + artifacts: Text2SqlV2StageArtifact[] + ): ExecutionTraceStep[] { + return this.resolveStageArtifacts(artifacts).map((artifact, index) => { + const at = + artifact.endedAt ?? + artifact.startedAt ?? + new Date().toISOString(); + return { + node: artifact.stage, + status: + artifact.status === "failed" + ? "failed" + : artifact.status === "skipped" + ? "skipped" + : "success", + at, + detail: `stage ${artifact.stage} ${artifact.status}`, + outputSummary: JSON.stringify({ + v2: { + stageArtifact: artifact + } + }), + sequence: index + 1, + stepId: `${artifact.stage}:${index + 1}`, + lifecycle: + artifact.status === "failed" + ? "failed" + : artifact.status === "skipped" + ? "skipped" + : "completed" + }; + }); + } + + private resolveRuntimePlan( + state: Text2SqlV2LangGraphState, + stageArtifacts: Text2SqlV2StageArtifact[] + ): Text2SqlV2RuntimePlanV1 { + const existingByStage = new Map( + (state.runtimePlan?.items ?? []).map((item) => [item.stage, item]) + ); + const items = stageArtifacts.map((artifact) => { + const existing = existingByStage.get(artifact.stage); + if (existing) { + return existing; + } + const catalog = resolveText2SqlV2StageCatalogEntry(artifact.stage); + const reasonCodes = this.resolveRuntimePlanReasonCodes(state, artifact); + return { + id: `runtime-plan:${artifact.stage}`, + stage: artifact.stage, + goal: catalog.title, + status: this.toRuntimePlanStatus(artifact.status), + ...(reasonCodes.length > 0 ? { reasonCodes } : {}), + ...(artifact.evidenceIds?.length ? { evidenceRefs: artifact.evidenceIds } : {}), + ...(this.readCorrectionIntent(artifact) + ? { correctionIntent: this.readCorrectionIntent(artifact) } + : {}), + ...(artifact.startedAt ? { startedAt: artifact.startedAt } : {}), + ...(artifact.endedAt ? { endedAt: artifact.endedAt } : {}), + summary: `stage ${artifact.stage} ${artifact.status}` + }; + }); + + return { + version: "runtime-plan.v1", + items, + currentItemId: + state.runtimePlan?.currentItemId ?? + (items.length > 0 ? items[items.length - 1]?.id : undefined), + summary: state.runtimePlan?.summary + }; + } + + private resolveRuntimePlanReasonCodes( + state: Text2SqlV2LangGraphState, + artifact: Text2SqlV2StageArtifact + ): string[] { + const reasons = [ + ...(artifact.warnings ?? []), + ...(artifact.failure?.code ? [artifact.failure.code] : []) + ]; + if (artifact.status !== "skipped") { + return Array.from(new Set(reasons)); + } + if ( + (state.routeArtifact?.route === "general" || + state.routeArtifact?.route === "needs_clarification") && + (artifact.stage === "generate-sql" || + artifact.stage === "validate" || + artifact.stage === "correct" || + artifact.stage === "execute") + ) { + reasons.push("plain_general_no_sql"); + } + if ( + (state.routeArtifact?.route === "metadata" || + state.semanticPlanResult?.validation.routeKind === "metadata") && + (artifact.stage === "generate-sql" || + artifact.stage === "validate" || + artifact.stage === "correct" || + artifact.stage === "execute") + ) { + reasons.push("metadata_no_sql"); + } + if (state.failure?.terminal) { + reasons.push("terminal_governance_failure"); + } + if ( + artifact.stage === "correct" && + (state.validationOutcome === "pass" || + state.sqlValidationArtifact?.status === "passed") + ) { + reasons.push("validation_passed"); + } + return Array.from(new Set(reasons)); + } + + private toRuntimePlanStatus( + status: Text2SqlV2StageArtifact["status"] + ): Text2SqlV2RuntimePlanV1["items"][number]["status"] { + if (status === "success" || status === "degraded") { + return "completed"; + } + if (status === "clarification") { + return "clarification"; + } + return status; + } + + private readCorrectionIntent( + artifact: Text2SqlV2StageArtifact + ): Text2SqlV2RuntimePlanV1["items"][number]["correctionIntent"] | undefined { + if (artifact.stage !== "correct" || artifact.status !== "success") { + return undefined; + } + const grounding = artifact.metadata?.correctionGrounding; + const retryReason = + typeof grounding === "object" && + grounding !== null && + "retryReason" in grounding && + typeof grounding.retryReason === "string" + ? grounding.retryReason + : artifact.warnings?.[0]; + if (!retryReason) { + return undefined; + } + const failureCode = + typeof grounding === "object" && + grounding !== null && + "failureCode" in grounding && + typeof grounding.failureCode === "string" + ? grounding.failureCode + : undefined; + return { + failedStage: "validate", + ...(failureCode ? { failureCode } : {}), + retryReason, + targetStage: "generate-sql" + }; + } + + private isStageName(value: string): value is Text2SqlV2StageName { + return (TEXT2SQL_V2_STAGE_ORDER as readonly string[]).includes(value); + } +} diff --git a/apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts b/apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts new file mode 100644 index 0000000..6844bfe --- /dev/null +++ b/apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts @@ -0,0 +1,194 @@ +import { Injectable } from "@nestjs/common"; +import type { ExecutionTraceStep, SqlRun } from "@text2sql/shared-types"; +import type { Text2SqlPreparedRunContext } from "../../text2sql/stages/prepare-run.stage"; +import { SqlToolRegistryService } from "../../agent/sql/tools/sql-tool-registry.service"; +import { + createText2SqlV2LangGraph, + type Text2SqlV2LangGraphCompiled +} from "./text2sql-v2-langgraph.graph"; +import { Text2SqlV2LangGraphResultMapper } from "./text2sql-v2-langgraph-result.mapper"; +import { + createText2SqlV2LangGraphInitialState, + type Text2SqlV2LangGraphRuntimeInput, + type Text2SqlV2LangGraphState, + type Text2SqlV2LangGraphStreamOptions +} from "./text2sql-v2-langgraph.state"; +import { LangsmithTraceService } from "../../../observability/langsmith-trace.service"; +import type { LangsmithTraceSource } from "../../../observability/langsmith.types"; +import { AnswerNode } from "../../nodes/answer.node"; +import { AssembleContextNode } from "../../nodes/assemble-context.node"; +import { CorrectSqlNode } from "../../nodes/correct-sql.node"; +import { ExecuteSqlNode } from "../../nodes/execute-sql.node"; +import { GenerateSqlNode } from "../../nodes/generate-sql.node"; +import { IntakeNode } from "../../nodes/intake.node"; +import { RetrieveContextNode } from "../../nodes/retrieve-context.node"; +import { SemanticPlanNode } from "../../nodes/semantic-plan.node"; +import { ValidateSqlNode } from "../../nodes/validate-sql.node"; +import { Text2SqlV2ArtifactRefService } from "../../artifacts/text2sql-v2-artifact-ref.service"; + +@Injectable() +export class Text2SqlV2LangGraphRunnerService { + private compiledGraph?: Text2SqlV2LangGraphCompiled; + + constructor( + private readonly intakeNode: IntakeNode, + private readonly retrieveContextNode: RetrieveContextNode, + private readonly assembleContextNode: AssembleContextNode, + private readonly semanticPlanNode: SemanticPlanNode, + private readonly generateSqlNode: GenerateSqlNode, + private readonly validateSqlNode: ValidateSqlNode, + private readonly correctSqlNode: CorrectSqlNode, + private readonly executeSqlNode: ExecuteSqlNode, + private readonly answerNode: AnswerNode, + private readonly sqlToolRegistry: SqlToolRegistryService, + private readonly langsmithTrace: LangsmithTraceService, + private readonly resultMapper: Text2SqlV2LangGraphResultMapper, + private readonly artifactRefService: Text2SqlV2ArtifactRefService + ) {} + + async runSync(input: Text2SqlPreparedRunContext, route: string): Promise { + return this.runWithGraph({ + preparedRun: input, + route, + streamMode: false + }); + } + + async runStream( + input: Text2SqlPreparedRunContext, + route: string, + options?: Text2SqlV2LangGraphStreamOptions + ): Promise { + return this.runWithGraph({ + preparedRun: input, + route, + streamMode: true, + streamOptions: options + }); + } + + private async runWithGraph( + runtimeInput: Text2SqlV2LangGraphRuntimeInput + ): Promise { + const source = this.routeToSource(runtimeInput.route); + const rootTrace = this.langsmithTrace.startRoot({ + runId: runtimeInput.preparedRun.runId, + sessionId: runtimeInput.preparedRun.session.id, + question: runtimeInput.preparedRun.question, + source, + route: runtimeInput.route, + requestId: runtimeInput.preparedRun.requestId + }); + + try { + const finalState = (await this.getCompiledGraph().invoke( + createText2SqlV2LangGraphInitialState(runtimeInput) + )) as Text2SqlV2LangGraphState; + const traceSteps = this.resultMapper.mapTraceSteps(finalState); + + this.recordLangsmithSpans(rootTrace, traceSteps); + + const mappedRun = this.resultMapper.mapSqlRun(finalState); + const run = await this.artifactRefService.attachRunArtifactRefs( + mappedRun, + runtimeInput.preparedRun.datasource.id + ); + this.langsmithTrace.endRoot(rootTrace, { + status: run.status, + provider: run.provider, + outputs: { + rowCount: run.rows?.length, + hasError: Boolean(run.error), + retrievalStatus: run.trace.v2?.contextPack?.status, + selectedContextCount: run.trace.v2?.contextPack?.selectedEvidenceIds?.length ?? 0 + }, + metadata: { + source, + route: runtimeInput.route, + requestId: runtimeInput.preparedRun.requestId + } + }); + + return run; + } catch (error) { + this.langsmithTrace.endRoot(rootTrace, { + status: "failed", + metadata: { + source, + route: runtimeInput.route, + requestId: runtimeInput.preparedRun.requestId + }, + error: this.toErrorMessage(error) + }); + throw error; + } + } + + private recordLangsmithSpans( + rootTrace: ReturnType, + steps: ExecutionTraceStep[] + ): void { + for (const step of steps) { + this.langsmithTrace.recordSpan(rootTrace, { + node: step.node, + status: step.status, + detail: step.detail, + inputs: this.parseStepPayload(step.inputSummary), + outputs: this.parseStepPayload(step.outputSummary), + error: step.errorSummary + }); + } + } + + private parseStepPayload( + payload: string | undefined + ): Record | undefined { + if (!payload) { + return undefined; + } + try { + const parsed = JSON.parse(payload) as unknown; + if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) { + return parsed as Record; + } + return undefined; + } catch { + return undefined; + } + } + + private toErrorMessage(error: unknown): string { + if (error instanceof Error) { + return error.message; + } + return String(error); + } + + private routeToSource(route: string): LangsmithTraceSource { + return route.includes("/evaluations/") ? "evaluation" : "chat"; + } + + private getCompiledGraph(): Text2SqlV2LangGraphCompiled { + if (!this.compiledGraph) { + this.compiledGraph = createText2SqlV2LangGraph({ + intakeNode: this.intakeNode, + retrieveContextNode: this.retrieveContextNode, + assembleContextNode: this.assembleContextNode, + semanticPlanNode: this.semanticPlanNode, + generateSqlNode: this.generateSqlNode, + validateSqlNode: this.validateSqlNode, + correctSqlNode: this.correctSqlNode, + executeSqlNode: this.executeSqlNode, + answerNode: this.answerNode, + resolveSqlTools: (state) => + this.sqlToolRegistry.getToolsForDatasource( + state.preparedRun.datasource, + { + accessContext: state.preparedRun.sqlAccessContext + } + ) + }); + } + return this.compiledGraph; + } +} diff --git a/apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts b/apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts new file mode 100644 index 0000000..61fd09f --- /dev/null +++ b/apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts @@ -0,0 +1,1363 @@ +import { END, START, StateGraph } from "@langchain/langgraph"; +import type { + ClarificationPrompt, + ExecutionTraceStep, + Text2SqlV2FailureSemantic, + Text2SqlV2RuntimePlanV1, + Text2SqlV2StageArtifact, + Text2SqlV2StageName +} from "@text2sql/shared-types"; +import { DomainError } from "../../../../common/domain-error"; +import type { LlmGatewayToolDefinition } from "../../../llm/llm-gateway.interface"; +import { + resolveText2SqlV2StageCatalogEntry +} from "../../text2sql/stages/text2sql-stage-catalog"; +import type { AnswerNode } from "../../nodes/answer.node"; +import type { AssembleContextNode } from "../../nodes/assemble-context.node"; +import type { CorrectSqlNode } from "../../nodes/correct-sql.node"; +import type { ExecuteSqlNode } from "../../nodes/execute-sql.node"; +import type { + GenerateSqlNode, + GenerateSqlNodeResult +} from "../../nodes/generate-sql.node"; +import type { IntakeNode } from "../../nodes/intake.node"; +import type { RetrieveContextNode } from "../../nodes/retrieve-context.node"; +import type { SemanticPlanNode } from "../../nodes/semantic-plan.node"; +import type { ValidateSqlNode } from "../../nodes/validate-sql.node"; +import { + Text2SqlV2LangGraphStateAnnotation, + type Text2SqlV2LangGraphNodeName, + type Text2SqlV2LangGraphSqlDraft, + type Text2SqlV2LangGraphState, + type Text2SqlV2LangGraphStateUpdate +} from "./text2sql-v2-langgraph.state"; + +type NodeRouteKey = "answer" | "retrieve" | "assemble-context" | "semantic-plan" | "generate-sql" | "validate" | "correct" | "execute"; + +export interface Text2SqlV2LangGraphDeps { + intakeNode: IntakeNode; + retrieveContextNode: RetrieveContextNode; + assembleContextNode: AssembleContextNode; + semanticPlanNode: SemanticPlanNode; + generateSqlNode: GenerateSqlNode; + validateSqlNode: ValidateSqlNode; + correctSqlNode: CorrectSqlNode; + executeSqlNode: ExecuteSqlNode; + answerNode: AnswerNode; + resolveSqlTools: ( + state: Text2SqlV2LangGraphState + ) => Record; +} + +const STAGE_NODE_TO_STEP_NODE: Record = { + intake: "intake", + retrieve: "retrieve-context", + "assemble-context": "assemble-context", + "semantic-plan": "semantic-plan", + "generate-sql": "generate-sql", + validate: "validate-sql", + correct: "correct-sql", + execute: "execute-sql", + answer: "answer" +}; + +const toStepStatus = ( + status: Text2SqlV2StageArtifact["status"] +): ExecutionTraceStep["status"] => { + if (status === "failed") { + return "failed"; + } + if (status === "skipped") { + return "skipped"; + } + return "success"; +}; + +const normalizeFailure = ( + error: unknown, + defaults: Partial +): Text2SqlV2FailureSemantic => { + if ( + typeof error === "object" && + error !== null && + "code" in error && + "message" in error + ) { + const candidate = error as { code?: unknown; message?: unknown }; + if (typeof candidate.code === "string" && typeof candidate.message === "string") { + return { + code: candidate.code, + message: candidate.message, + category: defaults.category ?? "unknown", + terminal: defaults.terminal ?? true, + correctable: defaults.correctable ?? false + }; + } + } + + const message = error instanceof Error ? error.message : String(error); + return { + code: defaults.code ?? "TEXT2SQL_V2_LANGGRAPH_STAGE_FAILED", + message, + category: defaults.category ?? "unknown", + terminal: defaults.terminal ?? true, + correctable: defaults.correctable ?? false + }; +}; + +const nowIso = (): string => new Date().toISOString(); + +const computeDurationMs = (startedAt: string, endedAt: string): number => { + const started = Date.parse(startedAt); + const ended = Date.parse(endedAt); + if (Number.isNaN(started) || Number.isNaN(ended)) { + return 0; + } + return Math.max(0, ended - started); +}; + +const unique = (values: string[]): string[] => { + return Array.from( + new Set(values.map((value) => value.trim()).filter((value) => value.length > 0)) + ); +}; + +const safeJsonStringify = (payload: Record): string | undefined => { + try { + return JSON.stringify(payload); + } catch { + return undefined; + } +}; + +const createStageArtifact = (input: { + stage: Text2SqlV2StageName; + status: Text2SqlV2StageArtifact["status"]; + warnings?: string[]; + evidenceIds?: string[]; + failure?: Text2SqlV2FailureSemantic; + metadata?: Record; + provider?: Text2SqlV2StageArtifact["provider"]; + startedAt?: string; +}): Text2SqlV2StageArtifact => { + const startedAt = input.startedAt ?? nowIso(); + const endedAt = nowIso(); + const catalog = resolveText2SqlV2StageCatalogEntry(input.stage); + return { + stage: input.stage, + status: input.status, + startedAt, + endedAt, + durationMs: computeDurationMs(startedAt, endedAt), + warnings: unique(input.warnings ?? []), + evidenceIds: unique(input.evidenceIds ?? []), + ...(input.provider ? { provider: input.provider } : {}), + ...(input.failure ? { failure: input.failure } : {}), + metadata: { + taskProfile: catalog.taskProfile, + reasoningTier: catalog.defaultReasoningTier, + policySource: "langgraph-runtime", + ...(input.metadata ?? {}) + } + }; +}; + +const createStep = (input: { + state: Text2SqlV2LangGraphState; + node: Text2SqlV2LangGraphNodeName; + stageArtifact: Text2SqlV2StageArtifact; + detail: string; + runtimePlanStatus?: Text2SqlV2RuntimePlanV1["items"][number]["status"]; + inputSummary?: Record; + outputSummary?: Record; +}): ExecutionTraceStep => { + const at = nowIso(); + const outputSummaryV2 = + input.outputSummary?.v2 && typeof input.outputSummary.v2 === "object" + ? (input.outputSummary.v2 as Record) + : {}; + const inputSummaryV2 = + input.inputSummary?.v2 && typeof input.inputSummary.v2 === "object" + ? (input.inputSummary.v2 as Record) + : {}; + const outputPayload: Record = { + ...(input.outputSummary ?? {}), + v2: { + ...outputSummaryV2, + stageArtifact: input.stageArtifact, + runtimePlan: createRuntimePlanUpdate({ + stageArtifact: input.stageArtifact, + detail: input.detail, + status: input.runtimePlanStatus + }) + } + }; + const inputPayload: Record = { + ...(input.inputSummary ?? {}), + v2: { + ...inputSummaryV2, + stageArtifact: input.stageArtifact, + runtimePlan: createRuntimePlanUpdate({ + stageArtifact: input.stageArtifact, + detail: input.detail, + status: input.runtimePlanStatus + }) + } + }; + + return { + node: STAGE_NODE_TO_STEP_NODE[input.node], + status: toStepStatus(input.stageArtifact.status), + detail: input.detail, + at, + startedAt: input.stageArtifact.startedAt, + endedAt: input.stageArtifact.endedAt, + durationMs: input.stageArtifact.durationMs, + inputSummary: safeJsonStringify(inputPayload), + outputSummary: safeJsonStringify(outputPayload), + errorSummary: + input.stageArtifact.status === "failed" + ? input.stageArtifact.failure?.message + : undefined + }; +}; + +const toRuntimePlanStatus = ( + status: Text2SqlV2StageArtifact["status"] +): Text2SqlV2RuntimePlanV1["items"][number]["status"] => { + if (status === "success" || status === "degraded") { + return "completed"; + } + if (status === "clarification") { + return "clarification"; + } + return status; +}; + +const createRuntimePlanUpdate = (input: { + stageArtifact: Text2SqlV2StageArtifact; + detail: string; + status?: Text2SqlV2RuntimePlanV1["items"][number]["status"]; +}): Text2SqlV2RuntimePlanV1 => { + const catalog = resolveText2SqlV2StageCatalogEntry(input.stageArtifact.stage); + const reasonCodes = unique([ + ...(input.stageArtifact.warnings ?? []), + ...(input.stageArtifact.failure?.code ? [input.stageArtifact.failure.code] : []) + ]); + const evidenceRefs = unique(input.stageArtifact.evidenceIds ?? []); + const correctionIntent = readCorrectionIntent(input.stageArtifact); + return { + version: "runtime-plan.v1", + currentItemId: `runtime-plan:${input.stageArtifact.stage}`, + summary: input.detail, + items: [ + { + id: `runtime-plan:${input.stageArtifact.stage}`, + stage: input.stageArtifact.stage, + goal: catalog.title, + status: input.status ?? toRuntimePlanStatus(input.stageArtifact.status), + ...(reasonCodes.length > 0 ? { reasonCodes } : {}), + ...(evidenceRefs.length > 0 ? { evidenceRefs } : {}), + ...(correctionIntent ? { correctionIntent } : {}), + ...(input.stageArtifact.startedAt + ? { startedAt: input.stageArtifact.startedAt } + : {}), + ...(input.stageArtifact.endedAt + ? { endedAt: input.stageArtifact.endedAt } + : {}), + summary: input.detail + } + ] + }; +}; + +const readCorrectionIntent = ( + artifact: Text2SqlV2StageArtifact +): Text2SqlV2RuntimePlanV1["items"][number]["correctionIntent"] | undefined => { + if (artifact.stage !== "correct" || artifact.status !== "success") { + return undefined; + } + const grounding = artifact.metadata?.correctionGrounding; + const retryReason = + typeof grounding === "object" && + grounding !== null && + "retryReason" in grounding && + typeof grounding.retryReason === "string" + ? grounding.retryReason + : artifact.warnings?.[0]; + if (!retryReason) { + return undefined; + } + const failureCode = + typeof grounding === "object" && + grounding !== null && + "failureCode" in grounding && + typeof grounding.failureCode === "string" + ? grounding.failureCode + : undefined; + return { + failedStage: "validate", + ...(failureCode ? { failureCode } : {}), + retryReason, + targetStage: "generate-sql" + }; +}; + +const createNodeUpdate = async (input: { + state: Text2SqlV2LangGraphState; + node: Text2SqlV2LangGraphNodeName; + stageArtifact: Text2SqlV2StageArtifact; + detail: string; + inputSummary?: Record; + outputSummary?: Record; + patch?: Partial; +}): Promise => { + const step = createStep({ + state: input.state, + node: input.node, + stageArtifact: input.stageArtifact, + detail: input.detail, + inputSummary: input.inputSummary, + outputSummary: input.outputSummary + }); + if (input.state.streamMode && input.state.streamOptions?.onStep) { + const sequence = input.state.traceSteps.length + 1; + await input.state.streamOptions.onStep({ + step: { + ...step, + stepId: `${input.state.runId}:${step.node}:${sequence}`, + sequence, + lifecycle: + input.stageArtifact.status === "failed" + ? "failed" + : input.stageArtifact.status === "skipped" + ? "skipped" + : "completed" + } + }); + } + + return { + stageProgress: [input.node], + stageArtifacts: [input.stageArtifact], + traceSteps: [step], + runtimePlan: createRuntimePlanUpdate({ + stageArtifact: input.stageArtifact, + detail: input.detail + }), + ...(input.patch ?? {}) + }; +}; + +const emitRunningStep = async (input: { + state: Text2SqlV2LangGraphState; + node: Text2SqlV2LangGraphNodeName; + detail: string; + evidenceIds?: string[]; + metadata?: Record; +}): Promise => { + const startedAt = nowIso(); + if (!input.state.streamMode || !input.state.streamOptions?.onStep) { + return startedAt; + } + + const stageArtifact = createStageArtifact({ + stage: input.node, + status: "success", + evidenceIds: input.evidenceIds, + metadata: input.metadata, + startedAt + }); + const runningStageArtifact = { + ...stageArtifact, + endedAt: undefined, + durationMs: undefined + }; + const sequence = input.state.traceSteps.length + 1; + const stepNode = STAGE_NODE_TO_STEP_NODE[input.node]; + const step = createStep({ + state: input.state, + node: input.node, + stageArtifact: runningStageArtifact, + detail: input.detail, + runtimePlanStatus: "running" + }); + + await input.state.streamOptions.onStep({ + step: { + ...step, + stepId: `${input.state.runId}:${stepNode}:${sequence}`, + sequence, + lifecycle: "running", + endedAt: undefined, + durationMs: undefined + } + }); + + return startedAt; +}; + +const emitSkippedStepsBeforeAnswer = async ( + state: Text2SqlV2LangGraphState +): Promise => { + if (!state.streamMode || !state.streamOptions?.onStep) { + return; + } + const visited = new Set(state.stageProgress); + const skippedStages = (Object.keys(STAGE_NODE_TO_STEP_NODE) as Text2SqlV2LangGraphNodeName[]) + .filter((stage) => stage !== "answer" && !visited.has(stage)); + + let offset = 0; + for (const stage of skippedStages) { + offset += 1; + const reasonCodes = resolveSkippedReasonCodes(state, stage); + const stageArtifact = createStageArtifact({ + stage, + status: "skipped", + warnings: reasonCodes, + metadata: { + skippedBy: "langgraph-route" + } + }); + const step = createStep({ + state, + node: stage, + stageArtifact, + detail: `stage ${stage} skipped`, + runtimePlanStatus: "skipped" + }); + const sequence = state.traceSteps.length + offset; + await state.streamOptions.onStep({ + step: { + ...step, + stepId: `${state.runId}:${step.node}:${sequence}:skipped`, + sequence, + lifecycle: "skipped" + } + }); + } +}; + +const resolveSkippedReasonCodes = ( + state: Text2SqlV2LangGraphState, + stage: Text2SqlV2LangGraphNodeName +): string[] => { + if ( + state.routeArtifact?.route === "metadata" || + state.semanticPlanResult?.validation.routeKind === "metadata" + ) { + return ["metadata_no_sql"]; + } + if ( + state.routeArtifact?.route === "general" || + state.semanticPlanResult?.validation.routeKind === "general" + ) { + return ["general_no_sql"]; + } + if (stage === "correct" && state.validationOutcome === "pass") { + return ["validation_passed"]; + } + if (state.failure?.code) { + return [state.failure.code]; + } + return ["route_skipped"]; +}; + +const resolveIntakeRoute = (state: Text2SqlV2LangGraphState): NodeRouteKey => { + if (state.failure?.terminal) { + return "answer"; + } + const route = state.routeArtifact?.route; + return route === "text_to_sql" || route === "metadata" ? "retrieve" : "answer"; +}; + +const resolveRetrieveRoute = (state: Text2SqlV2LangGraphState): NodeRouteKey => { + return state.failure?.terminal ? "answer" : "assemble-context"; +}; + +const resolveAssembleRoute = (state: Text2SqlV2LangGraphState): NodeRouteKey => { + return state.failure?.terminal ? "answer" : "semantic-plan"; +}; + +const resolveSemanticPlanRoute = (state: Text2SqlV2LangGraphState): NodeRouteKey => { + if (state.failure?.terminal) { + return "answer"; + } + const semanticRouteKind = state.semanticPlanResult?.validation.routeKind; + if (state.routeArtifact?.route === "metadata" || semanticRouteKind === "metadata") { + return "answer"; + } + return state.semanticPlanResult?.route === "ready" ? "generate-sql" : "answer"; +}; + +const resolveGenerateRoute = (state: Text2SqlV2LangGraphState): NodeRouteKey => { + return state.failure?.terminal ? "answer" : "validate"; +}; + +const resolveValidateRoute = (state: Text2SqlV2LangGraphState): NodeRouteKey => { + if (state.failure?.terminal || state.validationOutcome === "terminal") { + return "answer"; + } + if (state.validationOutcome === "correctable") { + return "correct"; + } + return "execute"; +}; + +const resolveCorrectRoute = (state: Text2SqlV2LangGraphState): NodeRouteKey => { + if (state.failure?.terminal || state.correctionResult?.outcome === "terminal") { + return "answer"; + } + return "generate-sql"; +}; + +const semanticClarificationPrompt = ( + reasons: string[] +): ClarificationPrompt => { + return { + decision: "clarify", + triggerPath: "rule", + decisionSource: "semantic-plan", + confidenceLevel: "low", + reasonCodes: reasons, + question: "请补充分析对象、指标与时间范围，以便生成可执行 SQL。", + reason: reasons[0] ?? "semantic_plan_requires_clarification" + }; +}; + +const semanticFailClosedFailure = (reasons: string[]): Text2SqlV2FailureSemantic => { + return { + code: "SEMANTIC_PLAN_FAIL_CLOSED", + message: "语义规划未通过，系统已按 fail-closed 终止本次执行。", + category: "planning", + terminal: true, + correctable: false + }; +}; + +const enrichSemanticPlanFromSqlArtifact = ( + semanticPlan: Text2SqlV2LangGraphState["semanticPlan"], + sqlArtifact: Text2SqlV2LangGraphState["sqlGenerationArtifact"] +): Text2SqlV2LangGraphState["semanticPlan"] => { + if (!semanticPlan || !sqlArtifact) { + return semanticPlan; + } + const selectedTables = + semanticPlan.selectedTables.length > 0 + ? semanticPlan.selectedTables + : sqlArtifact.usedTables; + const selectedColumns = + semanticPlan.selectedColumns.length > 0 + ? semanticPlan.selectedColumns + : sqlArtifact.usedColumns.filter((column) => column.includes(".")); + const evidenceRefs = + semanticPlan.evidenceRefs.length > 0 + ? semanticPlan.evidenceRefs + : sqlArtifact.evidenceRefs; + + return { + ...semanticPlan, + selectedTables, + selectedColumns, + evidenceRefs + }; +}; + +const summarizeSqlDraft = ( + draft: GenerateSqlNodeResult["draft"] +): Text2SqlV2LangGraphSqlDraft => { + return { + provider: draft.provider, + model: draft.model, + modelCatalogId: draft.modelCatalogId, + sql: draft.sql, + explanation: draft.explanation, + promptTemplate: draft.promptTemplate, + retryCount: draft.retryCount, + semanticIntent: draft.semanticIntent, + coverage: draft.coverage, + semanticPlan: draft.semanticPlan, + semanticContextPack: draft.semanticContextPack + }; +}; + +export const createText2SqlV2LangGraph = ( + deps: Text2SqlV2LangGraphDeps +) => { + const graph = new StateGraph(Text2SqlV2LangGraphStateAnnotation) + .addNode("intake", async (state) => { + const stageStartedAt = await emitRunningStep({ + state, + node: "intake", + detail: "intake running" + }); + const routeArtifact = deps.intakeNode.run({ + question: state.question, + contextEnvelope: state.preparedRun.contextEnvelope + }); + const stageStatus: Text2SqlV2StageArtifact["status"] = + routeArtifact.route === "needs_clarification" + ? "clarification" + : routeArtifact.route === "unsafe" || routeArtifact.route === "unsupported" + ? "failed" + : "success"; + const stageArtifact = createStageArtifact({ + stage: "intake", + status: stageStatus, + warnings: routeArtifact.reasonCodes, + evidenceIds: routeArtifact.evidenceRefs, + failure: + routeArtifact.route === "unsafe" || routeArtifact.route === "unsupported" + ? routeArtifact.failure + : undefined, + metadata: { + route: routeArtifact.route, + confidence: routeArtifact.confidence + }, + startedAt: stageStartedAt + }); + + return createNodeUpdate({ + state, + node: "intake", + stageArtifact, + detail: `intake routed to ${routeArtifact.route}`, + outputSummary: { + route: routeArtifact.route, + confidence: routeArtifact.confidence + }, + patch: { + routeArtifact, + standaloneQuestion: routeArtifact.standaloneQuestion, + directAnswer: routeArtifact.directAnswer, + clarification: routeArtifact.clarification, + failure: + routeArtifact.route === "unsafe" || routeArtifact.route === "unsupported" + ? routeArtifact.failure + : undefined, + terminationReason: + routeArtifact.route === "needs_clarification" + ? "clarification_requested" + : undefined + } + }); + }) + .addNode("retrieve", async (state) => { + const stageStartedAt = await emitRunningStep({ + state, + node: "retrieve", + detail: "retrieve-context running" + }); + try { + const output = await deps.retrieveContextNode.run({ + question: state.standaloneQuestion ?? state.question, + datasourceId: state.preparedRun.datasource.id, + datasource: state.preparedRun.datasource, + runId: state.runId, + workspaceId: state.preparedRun.session.workspaceId ?? undefined, + allowedTables: state.preparedRun.sqlAccessContext?.allowedTables, + modelCatalogId: state.preparedRun.session.modelCatalogId ?? undefined, + pinnedTables: state.preparedRun.contextEnvelope?.pinnedTables, + pinnedColumns: state.preparedRun.contextEnvelope?.pinnedColumns + }); + const stageArtifact = createStageArtifact({ + stage: "retrieve", + status: output.state.status === "degraded" ? "degraded" : "success", + warnings: output.state.warnings, + evidenceIds: output.state.evidenceRefs, + metadata: { + retrievalStatus: output.state.status, + selectedContextCount: output.state.selectedContextSummary.count + }, + startedAt: stageStartedAt + }); + + return createNodeUpdate({ + state, + node: "retrieve", + stageArtifact, + detail: `retrieve-context ${output.state.status}`, + outputSummary: { + retrievalStatus: output.state.status, + selectedContextCount: output.state.selectedContextSummary.count + }, + patch: { + retrieveState: output.state, + retrievedArtifact: output.artifact + } + }); + } catch (error) { + const failure = normalizeFailure(error, { + code: "RETRIEVE_CONTEXT_FAILED", + category: "retrieval" + }); + const stageArtifact = createStageArtifact({ + stage: "retrieve", + status: "failed", + failure, + startedAt: stageStartedAt + }); + return createNodeUpdate({ + state, + node: "retrieve", + stageArtifact, + detail: failure.message, + patch: { + failure + } + }); + } + }) + .addNode("assemble-context", async (state) => { + const stageStartedAt = await emitRunningStep({ + state, + node: "assemble-context", + detail: "assemble-context running", + evidenceIds: state.retrieveState?.evidenceRefs + }); + try { + const output = deps.assembleContextNode.run({ + retrievalBundle: state.retrievedArtifact?.retrievalBundle, + selectedContext: state.retrievedArtifact?.retrievalBundle?.selected_context, + additionalWarnings: state.retrieveState?.warnings + }); + const stageArtifact = createStageArtifact({ + stage: "assemble-context", + status: output.contextPack.status === "degraded" ? "degraded" : "success", + warnings: output.contextPack.warnings, + evidenceIds: output.evidenceRefs, + metadata: { + selectedEvidenceCount: output.typedSummary.selectedEvidenceCount, + selectedTableCount: output.typedSummary.selectedTableCount, + selectedColumnCount: output.typedSummary.selectedColumnCount + }, + startedAt: stageStartedAt + }); + + return createNodeUpdate({ + state, + node: "assemble-context", + stageArtifact, + detail: `assemble-context ${output.contextPack.status}`, + outputSummary: { + status: output.contextPack.status, + selectedEvidenceCount: output.typedSummary.selectedEvidenceCount + }, + patch: { + contextPack: output.contextPack, + contextPackSummary: output.typedSummary + } + }); + } catch (error) { + const failure = normalizeFailure(error, { + code: "ASSEMBLE_CONTEXT_FAILED", + category: "retrieval" + }); + const stageArtifact = createStageArtifact({ + stage: "assemble-context", + status: "failed", + failure, + startedAt: stageStartedAt + }); + return createNodeUpdate({ + state, + node: "assemble-context", + stageArtifact, + detail: failure.message, + patch: { + failure + } + }); + } + }) + .addNode("semantic-plan", async (state) => { + const stageStartedAt = await emitRunningStep({ + state, + node: "semantic-plan", + detail: "semantic-plan running", + evidenceIds: state.contextPack?.selectedEvidenceIds + }); + try { + if (!state.contextPack) { + throw new DomainError( + "SEMANTIC_PLAN_PRECONDITION_FAILED", + "semantic-plan stage requires context pack", + 422 + ); + } + + const result = deps.semanticPlanNode.run({ + question: state.standaloneQuestion ?? state.question, + contextPack: state.contextPack, + semanticIntent: state.routeArtifact?.semanticIntent, + allowedTables: state.preparedRun.sqlAccessContext?.allowedTables + }); + const ledgerSummary = result.plan.planLedger?.summary; + const ledgerReasons = ledgerSummary?.reasonCodes ?? []; + const reasons = unique([...result.validation.reasons, ...ledgerReasons]); + let status: Text2SqlV2StageArtifact["status"] = "success"; + let failure: Text2SqlV2FailureSemantic | undefined; + let clarification: ClarificationPrompt | undefined; + let directAnswer: string | undefined; + let terminationReason = state.terminationReason; + + if (result.route === "needs_clarification") { + status = "clarification"; + clarification = semanticClarificationPrompt(reasons); + terminationReason = "semantic_plan_requires_clarification"; + } else if (result.route === "direct_answer") { + directAnswer = + result.validation.routeKind === "metadata" + ? "这是元数据问题，我会基于已检索到的表结构与语义证据给出只读说明。" + : state.routeArtifact?.directAnswer ?? + "这是解释类问题，不需要执行 SQL；我会直接给出说明。"; + } else if (result.route === "fail_closed") { + status = "failed"; + failure = semanticFailClosedFailure(reasons); + terminationReason = "semantic_plan_fail_closed"; + } + + const stageArtifact = createStageArtifact({ + stage: "semantic-plan", + status, + warnings: reasons, + evidenceIds: result.plan.evidenceRefs, + failure, + metadata: { + route: result.route, + routeKind: result.validation.routeKind, + confidence: result.plan.confidence, + ledgerGateOutcome: result.validation.ledgerGateOutcome ?? "pass", + blockedObligationCount: result.validation.blockedObligationIds?.length ?? 0, + warningObligationCount: result.validation.warningObligationIds?.length ?? 0 + }, + startedAt: stageStartedAt + }); + + return createNodeUpdate({ + state, + node: "semantic-plan", + stageArtifact, + detail: `semantic-plan route ${result.route}`, + outputSummary: { + route: result.route, + confidence: result.plan.confidence, + v2: { + planLedger: ledgerSummary + } + }, + patch: { + semanticPlanResult: result, + semanticPlan: result.plan, + clarification, + directAnswer, + failure, + terminationReason + } + }); + } catch (error) { + const failure = normalizeFailure(error, { + code: "SEMANTIC_PLAN_FAILED", + category: "planning" + }); + const stageArtifact = createStageArtifact({ + stage: "semantic-plan", + status: "failed", + failure, + startedAt: stageStartedAt + }); + return createNodeUpdate({ + state, + node: "semantic-plan", + stageArtifact, + detail: failure.message, + patch: { + failure, + terminationReason: "semantic_plan_fail_closed" + } + }); + } + }) + .addNode("generate-sql", async (state) => { + const stageStartedAt = await emitRunningStep({ + state, + node: "generate-sql", + detail: "generate-sql running", + evidenceIds: state.semanticPlan?.evidenceRefs, + metadata: { + routeKind: "text_to_sql", + selectedTableCount: state.semanticPlan?.selectedTables.length ?? 0, + selectedColumnCount: state.semanticPlan?.selectedColumns.length ?? 0 + } + }); + try { + if (!state.semanticPlan) { + throw new DomainError( + "SQL_GENERATION_PRECONDITION_FAILED", + "generate-sql stage requires semantic plan", + 422 + ); + } + const explicitPinning = + state.preparedRun.contextEnvelope?.pinnedTables?.length || + state.preparedRun.contextEnvelope?.pinnedColumns?.length + ? { + source: "context-envelope", + tables: state.preparedRun.contextEnvelope?.pinnedTables ?? [], + columns: state.preparedRun.contextEnvelope?.pinnedColumns ?? [] + } + : undefined; + + const result = await deps.generateSqlNode.run({ + question: state.standaloneQuestion ?? state.question, + datasourceType: state.preparedRun.datasource.type, + modelCatalogId: state.preparedRun.session.modelCatalogId ?? undefined, + datasourceId: state.preparedRun.datasource.id, + workspaceId: state.preparedRun.session.workspaceId ?? undefined, + semanticIntent: state.routeArtifact?.semanticIntent, + selectedContext: + state.retrievedArtifact?.retrievalBundle?.selected_context, + semanticContextPack: state.retrievedArtifact?.contextPack, + semanticPlan: state.semanticPlan, + explicitPinning, + cause: state.correctionAttemptCount > 0 ? "correction" : "initial", + retryReason: state.correctionResult?.artifact.retryReason, + correctionGrounding: state.correctionResult?.artifact.grounding, + stream: state.streamMode, + tools: deps.resolveSqlTools(state), + onEvent: state.streamOptions?.onLlmEvent + }); + const stageArtifact = createStageArtifact({ + stage: "generate-sql", + status: "success", + warnings: + result.artifact.coverage?.gateStatus === "failed" + ? ["sql_coverage_gate_failed"] + : undefined, + evidenceIds: result.artifact.evidenceRefs, + provider: { + provider: result.draft.provider, + model: result.draft.model + }, + metadata: { + cause: result.artifact.cause, + retryReason: result.artifact.retryReason, + correctionGrounding: result.artifact.correctionGrounding, + usedTableCount: result.artifact.usedTables.length, + usedColumnCount: result.artifact.usedColumns.length + }, + startedAt: stageStartedAt + }); + const nextSemanticPlan = enrichSemanticPlanFromSqlArtifact( + state.semanticPlan, + result.artifact + ); + + return createNodeUpdate({ + state, + node: "generate-sql", + stageArtifact, + detail: "generate-sql completed", + outputSummary: { + sql: result.artifact.sql, + cause: result.artifact.cause, + correctionGrounding: result.artifact.correctionGrounding + }, + patch: { + sqlDraft: summarizeSqlDraft(result.draft), + sqlGenerationArtifact: result.artifact, + semanticPlan: nextSemanticPlan, + failure: undefined + } + }); + } catch (error) { + const failure = normalizeFailure(error, { + code: "SQL_GENERATION_FAILED", + category: "generation" + }); + const stageArtifact = createStageArtifact({ + stage: "generate-sql", + status: "failed", + failure, + startedAt: stageStartedAt + }); + return createNodeUpdate({ + state, + node: "generate-sql", + stageArtifact, + detail: failure.message, + patch: { + failure + } + }); + } + }) + .addNode("validate", async (state) => { + const stageStartedAt = await emitRunningStep({ + state, + node: "validate", + detail: "validate-sql running", + evidenceIds: state.semanticPlan?.evidenceRefs + }); + try { + if (!state.sqlGenerationArtifact?.sql) { + throw new DomainError( + "SQL_VALIDATION_PRECONDITION_FAILED", + "validate stage requires generated SQL", + 422 + ); + } + const result = await deps.validateSqlNode.run({ + sqlArtifact: state.sqlGenerationArtifact, + datasourceId: state.preparedRun.datasource.id, + datasourceType: state.preparedRun.datasource.type, + semanticPlan: state.semanticPlan, + accessContext: state.preparedRun.sqlAccessContext, + allowedTables: state.preparedRun.sqlAccessContext?.allowedTables + }); + const stageStatus: Text2SqlV2StageArtifact["status"] = + result.outcome === "pass" + ? "success" + : result.outcome === "correctable" + ? "degraded" + : "failed"; + const stageArtifact = createStageArtifact({ + stage: "validate", + status: stageStatus, + warnings: result.artifact.checks + .filter((item) => item.status !== "passed") + .map((item) => item.code ?? item.check), + evidenceIds: state.semanticPlan?.evidenceRefs, + failure: result.outcome === "terminal" ? result.artifact.failure : undefined, + metadata: { + outcome: result.outcome, + checkCount: result.artifact.checks.length, + correctable: result.artifact.correctable + }, + startedAt: stageStartedAt + }); + + return createNodeUpdate({ + state, + node: "validate", + stageArtifact, + detail: `validate outcome ${result.outcome}`, + outputSummary: { + outcome: result.outcome + }, + patch: { + validationOutcome: result.outcome, + sqlValidationArtifact: result.artifact, + failure: + result.outcome === "terminal" + ? result.artifact.failure + : undefined + } + }); + } catch (error) { + const failure = normalizeFailure(error, { + code: "SQL_VALIDATION_FAILED", + category: "validation" + }); + const stageArtifact = createStageArtifact({ + stage: "validate", + status: "failed", + failure, + startedAt: stageStartedAt + }); + return createNodeUpdate({ + state, + node: "validate", + stageArtifact, + detail: failure.message, + patch: { + validationOutcome: "terminal", + failure + } + }); + } + }) + .addNode("correct", async (state) => { + const stageStartedAt = await emitRunningStep({ + state, + node: "correct", + detail: "correct-sql running", + evidenceIds: state.semanticPlan?.evidenceRefs, + metadata: { + attemptCount: state.correctionAttemptCount + 1 + } + }); + try { + if (!state.sqlValidationArtifact || !state.sqlGenerationArtifact?.sql) { + throw new DomainError( + "SQL_CORRECTION_PRECONDITION_FAILED", + "correct stage requires failed validation artifact and SQL", + 422 + ); + } + const result = deps.correctSqlNode.run({ + failedSql: state.sqlGenerationArtifact.sql, + validationArtifact: state.sqlValidationArtifact, + attemptCount: state.correctionAttemptCount, + maxAttempts: state.correctionResult?.budget.maxAttempts, + semanticPlan: state.semanticPlan, + contextPack: state.contextPack + }); + const terminal = result.outcome === "terminal"; + const stageArtifact = createStageArtifact({ + stage: "correct", + status: terminal ? "failed" : "success", + warnings: [result.artifact.retryReason], + evidenceIds: result.artifact.evidenceRefs, + failure: result.failure, + metadata: { + attemptCount: result.budget.attemptCount, + maxAttempts: result.budget.maxAttempts, + exhausted: result.budget.exhausted, + correctionGrounding: result.artifact.grounding + }, + startedAt: stageStartedAt + }); + const loopEvidence = [ + { + loopIndex: result.budget.attemptCount, + triggerReason: result.artifact.retryReason, + actionType: terminal ? "fail_closed" : "continue", + ...(terminal + ? { + terminationReason: "correction_budget_exhausted" + } + : {}), + convergencePath: terminal + ? ["validate", "correct", "answer"] + : ["validate", "correct", "generate-sql"], + planDelta: { + snapshotId: state.semanticPlan?.snapshotId, + reasonCodes: [result.artifact.failureCode ?? result.artifact.category] + } + } + ]; + + return createNodeUpdate({ + state, + node: "correct", + stageArtifact, + detail: terminal ? "correction reached terminal state" : "correction requests retry", + outputSummary: { + outcome: result.outcome, + attemptCount: result.budget.attemptCount, + maxAttempts: result.budget.maxAttempts, + correctionGrounding: result.artifact.grounding + }, + patch: { + correctionResult: result, + correctionAttemptCount: result.budget.attemptCount, + correctionArtifacts: [result.artifact], + loopEvidence, + failure: terminal ? result.failure : undefined, + ...(terminal + ? { + terminationReason: "correction_budget_exhausted" + } + : {}) + } + }); + } catch (error) { + const failure = normalizeFailure(error, { + code: "SQL_CORRECTION_FAILED", + category: "validation" + }); + const stageArtifact = createStageArtifact({ + stage: "correct", + status: "failed", + failure, + startedAt: stageStartedAt + }); + return createNodeUpdate({ + state, + node: "correct", + stageArtifact, + detail: failure.message, + patch: { + failure, + terminationReason: "correction_budget_exhausted" + } + }); + } + }) + .addNode("execute", async (state) => { + const stageStartedAt = await emitRunningStep({ + state, + node: "execute", + detail: "execute-sql running", + evidenceIds: state.sqlGenerationArtifact?.evidenceRefs + }); + try { + if (!state.sqlValidationArtifact || !state.sqlGenerationArtifact) { + throw new DomainError( + "SQL_EXECUTE_PRECONDITION_FAILED", + "execute stage requires SQL and validation artifact", + 422 + ); + } + + const result = await deps.executeSqlNode.run({ + sqlArtifact: state.sqlGenerationArtifact, + validationArtifact: state.sqlValidationArtifact, + datasourceId: state.preparedRun.datasource.id, + sessionId: state.sessionId, + requestId: state.requestId, + accessContext: state.preparedRun.sqlAccessContext, + semanticPlan: state.semanticPlan + }); + const stageArtifact = createStageArtifact({ + stage: "execute", + status: "success", + evidenceIds: state.sqlGenerationArtifact.evidenceRefs, + metadata: { + rowCount: result.rowCount, + emptyResult: result.emptyResult + }, + startedAt: stageStartedAt + }); + return createNodeUpdate({ + state, + node: "execute", + stageArtifact, + detail: "execute-sql completed", + outputSummary: { + rowCount: result.rowCount, + emptyResult: result.emptyResult + }, + patch: { + executionResult: result + } + }); + } catch (error) { + const failure = normalizeFailure(error, { + code: "SQL_EXECUTION_FAILED", + category: "execution" + }); + const stageArtifact = createStageArtifact({ + stage: "execute", + status: "failed", + failure, + startedAt: stageStartedAt + }); + return createNodeUpdate({ + state, + node: "execute", + stageArtifact, + detail: failure.message, + patch: { + failure + } + }); + } + }) + .addNode("answer", async (state) => { + await emitSkippedStepsBeforeAnswer(state); + const stageStartedAt = await emitRunningStep({ + state, + node: "answer", + detail: "answer running", + evidenceIds: [ + ...(state.contextPack?.selectedEvidenceIds ?? []), + ...(state.sqlGenerationArtifact?.evidenceRefs ?? []) + ] + }); + const warnings = unique([ + ...(state.retrieveState?.warnings ?? []), + ...(state.contextPack?.warnings ?? []), + ...(state.routeArtifact?.reasonCodes ?? []), + ...(state.semanticPlanResult?.validation.reasons ?? []) + ]); + const answerResult = deps.answerNode.run({ + question: state.question, + directAnswer: state.directAnswer, + clarification: state.clarification, + executionResult: state.executionResult, + sqlArtifact: state.sqlGenerationArtifact, + semanticPlan: state.semanticPlan, + contextPack: state.contextPack, + routeKind: + state.semanticPlanResult?.validation.routeKind ?? state.routeArtifact?.route, + failure: state.failure, + warnings + }); + + const stageStatus: Text2SqlV2StageArtifact["status"] = + answerResult.mode === "clarification" + ? "clarification" + : answerResult.mode === "fail_closed" || + answerResult.mode === "execution_failure" + ? "failed" + : "success"; + const stageArtifact = createStageArtifact({ + stage: "answer", + status: stageStatus, + warnings: answerResult.warnings, + evidenceIds: answerResult.evidenceRefs, + failure: answerResult.failure, + metadata: { + mode: answerResult.mode, + status: answerResult.status + }, + startedAt: stageStartedAt + }); + + return createNodeUpdate({ + state, + node: "answer", + stageArtifact, + detail: `answer mode ${answerResult.mode}`, + outputSummary: { + mode: answerResult.mode, + status: answerResult.status + }, + patch: { + answerResult, + failure: answerResult.failure ?? state.failure, + completedAt: nowIso() + } + }); + }) + .addEdge(START, "intake") + .addConditionalEdges("intake", resolveIntakeRoute, { + retrieve: "retrieve", + answer: "answer" + }) + .addConditionalEdges("retrieve", resolveRetrieveRoute, { + "assemble-context": "assemble-context", + answer: "answer" + }) + .addConditionalEdges("assemble-context", resolveAssembleRoute, { + "semantic-plan": "semantic-plan", + answer: "answer" + }) + .addConditionalEdges("semantic-plan", resolveSemanticPlanRoute, { + "generate-sql": "generate-sql", + answer: "answer" + }) + .addConditionalEdges("generate-sql", resolveGenerateRoute, { + validate: "validate", + answer: "answer" + }) + .addConditionalEdges("validate", resolveValidateRoute, { + execute: "execute", + correct: "correct", + answer: "answer" + }) + .addConditionalEdges("correct", resolveCorrectRoute, { + "generate-sql": "generate-sql", + answer: "answer" + }) + .addEdge("execute", "answer") + .addEdge("answer", END); + + return graph.compile(); +}; + +export type Text2SqlV2LangGraphCompiled = ReturnType< + typeof createText2SqlV2LangGraph +>; diff --git a/apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.state.ts b/apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.state.ts new file mode 100644 index 0000000..e07534a --- /dev/null +++ b/apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.state.ts @@ -0,0 +1,268 @@ +import { Annotation } from "@langchain/langgraph"; +import type { + ClarificationPrompt, + ExecutionTraceStep, + SemanticContextPackV1, + SemanticPlanV1, + SqlValidationArtifactV1, + Text2SqlV2FailureSemantic, + Text2SqlV2LoopEvidence, + Text2SqlV2RuntimePlanV1, + Text2SqlV2StageArtifact, + Text2SqlV2TerminationReason +} from "@text2sql/shared-types"; +import type { LlmGatewayStreamEvent } from "../../../llm/llm-gateway.interface"; +import type { Text2SqlPreparedRunContext } from "../../text2sql/stages/prepare-run.stage"; +import type { StructuredSqlGenerationArtifact } from "../../agent/sql/sql-generation.service"; +import type { AnswerNodeResult } from "../../nodes/answer.node"; +import type { AssembleContextNodeSummary } from "../../nodes/assemble-context.node"; +import type { CorrectSqlNodeResult } from "../../nodes/correct-sql.node"; +import type { ExecuteSqlNodeResult } from "../../nodes/execute-sql.node"; +import type { GenerateSqlNodeResult } from "../../nodes/generate-sql.node"; +import type { IntakeRouteArtifact } from "../../nodes/intake.node"; +import type { + RetrieveContextNodeOutput, + RetrieveContextNodeState +} from "../../nodes/retrieve-context.node"; +import type { SemanticPlanNodeResult } from "../../nodes/semantic-plan.node"; +import type { ValidateSqlNodeResult } from "../../nodes/validate-sql.node"; + +export const TEXT2SQL_V2_LANGGRAPH_NODE_ORDER = [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" +] as const; + +export type Text2SqlV2LangGraphNodeName = + (typeof TEXT2SQL_V2_LANGGRAPH_NODE_ORDER)[number]; + +export interface Text2SqlV2LangGraphStreamOptions { + onLlmEvent?: (event: LlmGatewayStreamEvent) => Promise | void; + onStep?: (event: { step: ExecutionTraceStep }) => Promise | void; +} + +export interface Text2SqlV2LangGraphRuntimeInput { + preparedRun: Text2SqlPreparedRunContext; + route: string; + streamMode: boolean; + streamOptions?: Text2SqlV2LangGraphStreamOptions; +} + +const replaceValueReducer = (_left: T, right: T): T => right; + +const mergeRuntimePlanReducer = ( + left: Text2SqlV2RuntimePlanV1 | undefined, + right: Text2SqlV2RuntimePlanV1 | undefined +): Text2SqlV2RuntimePlanV1 | undefined => { + if (!right) { + return left; + } + if (!left) { + return right; + } + const byId = new Map(left.items.map((item) => [item.id, item])); + for (const item of right.items) { + byId.set(item.id, { + ...(byId.get(item.id) ?? {}), + ...item, + reasonCodes: Array.from( + new Set([...(byId.get(item.id)?.reasonCodes ?? []), ...(item.reasonCodes ?? [])]) + ), + evidenceRefs: Array.from( + new Set([...(byId.get(item.id)?.evidenceRefs ?? []), ...(item.evidenceRefs ?? [])]) + ) + }); + } + return { + version: "runtime-plan.v1", + items: Array.from(byId.values()), + currentItemId: right.currentItemId ?? left.currentItemId, + summary: right.summary ?? left.summary + }; +}; + +export type Text2SqlV2LangGraphSqlDraft = Omit< + GenerateSqlNodeResult["draft"], + "rawText" | "prompt" +>; + +type LangGraphRetrievedArtifact = RetrieveContextNodeOutput["artifact"]; + +export const Text2SqlV2LangGraphStateAnnotation = Annotation.Root({ + runId: Annotation, + sessionId: Annotation, + question: Annotation, + createdAt: Annotation, + completedAt: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + requestId: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + route: Annotation, + streamMode: Annotation, + preparedRun: Annotation, + streamOptions: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + stageProgress: Annotation({ + reducer: (left, right) => left.concat(right), + default: () => [] + }), + stageArtifacts: Annotation({ + reducer: (left, right) => left.concat(right), + default: () => [] + }), + traceSteps: Annotation({ + reducer: (left, right) => left.concat(right), + default: () => [] + }), + runtimePlan: Annotation({ + reducer: mergeRuntimePlanReducer, + default: () => undefined + }), + routeArtifact: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + standaloneQuestion: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + directAnswer: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + clarification: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + failure: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + terminationReason: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + retrieveState: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + retrievedArtifact: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + contextPack: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + contextPackSummary: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + semanticPlanResult: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + semanticPlan: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + sqlDraft: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + sqlGenerationArtifact: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + validationOutcome: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + sqlValidationArtifact: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + correctionResult: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + correctionAttemptCount: Annotation({ + reducer: replaceValueReducer, + default: () => 0 + }), + correctionArtifacts: Annotation({ + reducer: (left, right) => left.concat(right), + default: () => [] + }), + loopEvidence: Annotation({ + reducer: (left, right) => left.concat(right), + default: () => [] + }), + executionResult: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }), + answerResult: Annotation({ + reducer: replaceValueReducer, + default: () => undefined + }) +}); + +export type Text2SqlV2LangGraphState = + typeof Text2SqlV2LangGraphStateAnnotation.State; + +export type Text2SqlV2LangGraphStateUpdate = + typeof Text2SqlV2LangGraphStateAnnotation.Update; + +export const createText2SqlV2LangGraphInitialState = ( + input: Text2SqlV2LangGraphRuntimeInput +): Text2SqlV2LangGraphState => ({ + runId: input.preparedRun.runId, + sessionId: input.preparedRun.session.id, + question: input.preparedRun.question, + createdAt: new Date().toISOString(), + completedAt: undefined, + requestId: input.preparedRun.requestId, + route: input.route, + streamMode: input.streamMode, + preparedRun: input.preparedRun, + streamOptions: input.streamOptions, + stageProgress: [], + stageArtifacts: [], + traceSteps: [], + runtimePlan: undefined, + routeArtifact: undefined, + standaloneQuestion: undefined, + directAnswer: undefined, + clarification: undefined, + failure: undefined, + terminationReason: undefined, + retrieveState: undefined, + retrievedArtifact: undefined, + contextPack: undefined, + contextPackSummary: undefined, + semanticPlanResult: undefined, + semanticPlan: undefined, + sqlDraft: undefined, + sqlGenerationArtifact: undefined, + validationOutcome: undefined, + sqlValidationArtifact: undefined, + correctionResult: undefined, + correctionAttemptCount: 0, + correctionArtifacts: [], + loopEvidence: [], + executionResult: undefined, + answerResult: undefined +}); diff --git a/apps/backend/src/modules/conversation/runtime/smart-defaults/text2sql-smart-defaults.bundle.ts b/apps/backend/src/modules/conversation/runtime/smart-defaults/text2sql-smart-defaults.bundle.ts new file mode 100644 index 0000000..4fbcb42 --- /dev/null +++ b/apps/backend/src/modules/conversation/runtime/smart-defaults/text2sql-smart-defaults.bundle.ts @@ -0,0 +1,35 @@ +import type { Text2SqlV2SmartDefaultsEvidenceV1 } from "@text2sql/shared-types"; + +export const TEXT2SQL_SMART_DEFAULTS_BUNDLE_ID = "text2sql-smart-defaults"; +export const TEXT2SQL_SMART_DEFAULTS_VERSION = "2026-04-28"; + +export const TEXT2SQL_SMART_DEFAULTS_RULES = [ + { + id: "only-use-context-pack", + text: "Use only selected context pack, semantic plan, schema supplement, and explicit user constraints as grounding facts." + }, + { + id: "no-sql-for-direct-answer-routes", + text: "For metadata, general, clarification, unsupported, or fail-closed routes, do not generate SQL." + }, + { + id: "fail-closed-read-only-governance", + text: "Read-only, permission, governance, and policy failures are terminal unless deterministic validation marks them correctable." + }, + { + id: "correction-grounding-required", + text: "Correction must use failed SQL, validation artifact, retry reason, semantic plan, and context pack evidence." + }, + { + id: "avoid-schema-hallucination", + text: "Do not invent tables, columns, relationships, metrics, or filters absent from the semantic context." + } +] as const; + +export const TEXT2SQL_SMART_DEFAULTS_EVIDENCE: Text2SqlV2SmartDefaultsEvidenceV1 = { + bundleId: TEXT2SQL_SMART_DEFAULTS_BUNDLE_ID, + version: TEXT2SQL_SMART_DEFAULTS_VERSION, + coveredStages: ["generate-sql", "correct", "answer"], + ruleIds: TEXT2SQL_SMART_DEFAULTS_RULES.map((rule) => rule.id), + status: "applied" +}; diff --git a/apps/backend/src/modules/conversation/runtime/smart-defaults/text2sql-smart-defaults.service.ts b/apps/backend/src/modules/conversation/runtime/smart-defaults/text2sql-smart-defaults.service.ts new file mode 100644 index 0000000..85e066e --- /dev/null +++ b/apps/backend/src/modules/conversation/runtime/smart-defaults/text2sql-smart-defaults.service.ts @@ -0,0 +1,43 @@ +import { Injectable } from "@nestjs/common"; +import type { + PromptTemplateTraceEvidence, + Text2SqlV2SmartDefaultsEvidenceV1 +} from "@text2sql/shared-types"; +import { + TEXT2SQL_SMART_DEFAULTS_EVIDENCE, + TEXT2SQL_SMART_DEFAULTS_RULES +} from "./text2sql-smart-defaults.bundle"; + +@Injectable() +export class Text2SqlSmartDefaultsService { + resolve(input?: { + promptTemplate?: PromptTemplateTraceEvidence; + fallbackReason?: string; + }): { + evidence: Text2SqlV2SmartDefaultsEvidenceV1; + promptBlock: string; + } { + const evidence: Text2SqlV2SmartDefaultsEvidenceV1 = { + ...TEXT2SQL_SMART_DEFAULTS_EVIDENCE, + status: input?.fallbackReason ? "fallback" : "applied", + ...(input?.fallbackReason ? { fallbackReason: input.fallbackReason } : {}), + ...(input?.promptTemplate + ? { + templateOverlay: { + applied: true, + templateId: input.promptTemplate.templateId, + version: input.promptTemplate.version + } + } + : {}) + }; + + return { + evidence, + promptBlock: [ + `Text2SQL Smart Defaults ${evidence.bundleId}@${evidence.version}:`, + ...TEXT2SQL_SMART_DEFAULTS_RULES.map((rule) => `${rule.id}: ${rule.text}`) + ].join(" ") + }; + } +} diff --git a/apps/backend/src/modules/conversation/runtime/stages/run-v2-langgraph.stage.ts b/apps/backend/src/modules/conversation/runtime/stages/run-v2-langgraph.stage.ts new file mode 100644 index 0000000..11402c0 --- /dev/null +++ b/apps/backend/src/modules/conversation/runtime/stages/run-v2-langgraph.stage.ts @@ -0,0 +1,29 @@ +import { Injectable } from "@nestjs/common"; +import type { ExecutionTraceStep, SqlRun } from "@text2sql/shared-types"; +import type { LlmGatewayStreamEvent } from "../../../llm/llm-gateway.interface"; +import { Text2SqlV2LangGraphRunnerService } from "../langgraph/text2sql-v2-langgraph-runner.service"; +import type { Text2SqlPreparedRunContext } from "../../text2sql/stages/prepare-run.stage"; + +export interface Text2SqlStreamV2LangGraphOptions { + onLlmEvent?: (event: LlmGatewayStreamEvent) => Promise | void; + onStep?: (event: { step: ExecutionTraceStep }) => Promise | void; +} + +@Injectable() +export class RunV2LangGraphStage { + constructor( + private readonly text2SqlV2LangGraphRunner: Text2SqlV2LangGraphRunnerService + ) {} + + runSync(input: Text2SqlPreparedRunContext, route: string): Promise { + return this.text2SqlV2LangGraphRunner.runSync(input, route); + } + + runStream( + input: Text2SqlPreparedRunContext, + route: string, + options?: Text2SqlStreamV2LangGraphOptions + ): Promise { + return this.text2SqlV2LangGraphRunner.runStream(input, route, options); + } +} diff --git a/apps/backend/src/modules/conversation/text2sql/contracts/text2sql-run-context.ts b/apps/backend/src/modules/conversation/text2sql/contracts/text2sql-run-context.ts new file mode 100644 index 0000000..31fb973 --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/contracts/text2sql-run-context.ts @@ -0,0 +1,11 @@ +import type { ContextEnvelope } from "@text2sql/shared-types"; + +export interface Text2SqlRunContext { + runId: string; + sessionId: string; + datasourceId: string; + question: string; + requestId?: string; + contextEnvelope?: ContextEnvelope; + metadata?: Record; +} diff --git a/apps/backend/src/modules/conversation/text2sql/contracts/text2sql-stage-name.ts b/apps/backend/src/modules/conversation/text2sql/contracts/text2sql-stage-name.ts new file mode 100644 index 0000000..2a64186 --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/contracts/text2sql-stage-name.ts @@ -0,0 +1,24 @@ +export const TEXT2SQL_STAGE_NAMES = [ + "prepare-run", + "plan-intent", + "retrieve-context", + "generate-sql", + "validate-sql", + "execute-sql", + "format-answer", + "persist-run", + "post-run-hooks", + "generic" +] as const; + +export type Text2SqlStageName = (typeof TEXT2SQL_STAGE_NAMES)[number]; + +export const TEXT2SQL_STAGE_OUTCOMES = [ + "success", + "skipped", + "degraded", + "failed", + "needs-clarification" +] as const; + +export type Text2SqlStageOutcome = (typeof TEXT2SQL_STAGE_OUTCOMES)[number]; diff --git a/apps/backend/src/modules/conversation/text2sql/contracts/text2sql-stage-result.ts b/apps/backend/src/modules/conversation/text2sql/contracts/text2sql-stage-result.ts new file mode 100644 index 0000000..6493f77 --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/contracts/text2sql-stage-result.ts @@ -0,0 +1,14 @@ +import type { ReasoningStage } from "@text2sql/shared-types"; +import type { + Text2SqlStageName, + Text2SqlStageOutcome +} from "./text2sql-stage-name"; + +export interface Text2SqlStageResult { + stage: Text2SqlStageName; + outcome: Text2SqlStageOutcome; + title: string; + reasoningStage: ReasoningStage; + detail?: string; + payload?: TPayload; +} diff --git a/apps/backend/src/modules/conversation/text2sql/contracts/text2sql-stage.interface.ts b/apps/backend/src/modules/conversation/text2sql/contracts/text2sql-stage.interface.ts new file mode 100644 index 0000000..952c406 --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/contracts/text2sql-stage.interface.ts @@ -0,0 +1,11 @@ +import type { Text2SqlRunContext } from "./text2sql-run-context"; +import type { Text2SqlStageResult } from "./text2sql-stage-result"; +import type { Text2SqlStageName } from "./text2sql-stage-name"; + +export interface Text2SqlStage< + TContext extends Text2SqlRunContext = Text2SqlRunContext, + TPayload = unknown +> { + readonly stageName: Text2SqlStageName; + run(context: TContext): Promise>; +} diff --git a/apps/backend/src/modules/conversation/text2sql/stages/enrich-delivery.stage.ts b/apps/backend/src/modules/conversation/text2sql/stages/enrich-delivery.stage.ts new file mode 100644 index 0000000..9579e9a --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/stages/enrich-delivery.stage.ts @@ -0,0 +1,14 @@ +import { Injectable } from "@nestjs/common"; +import type { SqlRun } from "@text2sql/shared-types"; +import { ChatDeliveryEnrichmentService } from "../../chat/application/shared/chat-delivery-enrichment.service"; + +@Injectable() +export class EnrichDeliveryStage { + constructor( + private readonly chatDeliveryEnrichmentService: ChatDeliveryEnrichmentService + ) {} + + run(run: SqlRun): Promise { + return this.chatDeliveryEnrichmentService.attachDeliveryContract(run); + } +} diff --git a/apps/backend/src/modules/conversation/text2sql/stages/persist-run.stage.ts b/apps/backend/src/modules/conversation/text2sql/stages/persist-run.stage.ts new file mode 100644 index 0000000..a2ffc75 --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/stages/persist-run.stage.ts @@ -0,0 +1,20 @@ +import { Injectable } from "@nestjs/common"; +import type { SqlRun } from "@text2sql/shared-types"; +import { ChatRunPersistenceService } from "../../chat/application/shared/chat-run-persistence.service"; + +export interface PersistRunStageInput { + sessionId: string; + run: SqlRun; + userPrimaryPersisted: boolean; +} + +@Injectable() +export class PersistRunStage { + constructor( + private readonly chatRunPersistenceService: ChatRunPersistenceService + ) {} + + run(input: PersistRunStageInput): Promise { + return this.chatRunPersistenceService.persistAssistantAndRun(input); + } +} diff --git a/apps/backend/src/modules/conversation/text2sql/stages/post-run-hooks.stage.ts b/apps/backend/src/modules/conversation/text2sql/stages/post-run-hooks.stage.ts new file mode 100644 index 0000000..46aa36e --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/stages/post-run-hooks.stage.ts @@ -0,0 +1,20 @@ +import { Injectable } from "@nestjs/common"; +import type { Session, SqlRun } from "@text2sql/shared-types"; +import { ChatPostRunHooksService } from "../../chat/application/shared/chat-post-run-hooks.service"; + +export interface PostRunHooksStageInput { + session: Session; + run: SqlRun; + requestId?: string; +} + +@Injectable() +export class PostRunHooksStage { + constructor( + private readonly chatPostRunHooksService: ChatPostRunHooksService + ) {} + + run(input: PostRunHooksStageInput): Promise { + return this.chatPostRunHooksService.run(input); + } +} diff --git a/apps/backend/src/modules/conversation/text2sql/stages/prepare-run.stage.ts b/apps/backend/src/modules/conversation/text2sql/stages/prepare-run.stage.ts new file mode 100644 index 0000000..bfe249c --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/stages/prepare-run.stage.ts @@ -0,0 +1,92 @@ +import { Injectable } from "@nestjs/common"; +import type { + ChatMessage, + ContextEnvelope, + Datasource, + Session +} from "@text2sql/shared-types"; +import { v4 as uuidv4 } from "uuid"; +import { DomainError } from "../../../../common/domain-error"; +import { DatasourceService } from "../../../governance/datasource/datasource.service"; +import { RedisBufferService } from "../../../platform/data/cache/index"; +import { ChatRepository } from "../../../platform/data/persistence/index"; +import { + ChatPolicyGuardService, + type ChatPolicyActorInput, + type ChatSqlAccessContext +} from "../../chat/application/shared/chat-policy-guard.service"; + +export interface Text2SqlPrepareRunInput { + sessionId: string; + message: string; + requestId?: string; + contextEnvelope?: ContextEnvelope; + actor?: ChatPolicyActorInput; +} + +export interface Text2SqlPreparedRunContext { + runId: string; + session: Session; + datasource: Datasource; + sqlAccessContext?: ChatSqlAccessContext; + question: string; + requestId?: string; + contextEnvelope?: ContextEnvelope; + userPersistResult: { + primaryPersisted: boolean; + }; +} + +@Injectable() +export class PrepareRunStage { + constructor( + private readonly datasourceService: DatasourceService, + private readonly redisBuffer: RedisBufferService, + private readonly repository: ChatRepository, + private readonly chatPolicyGuardService: ChatPolicyGuardService + ) {} + + async run(input: Text2SqlPrepareRunInput): Promise { + const session = await this.repository.getSessionById(input.sessionId); + if (!session) { + throw new DomainError("SESSION_NOT_FOUND", "会话不存在", 404, { + sessionId: input.sessionId + }); + } + + await this.chatPolicyGuardService.assertSessionWritableByPolicy(session); + const datasource = await this.datasourceService.assertDatasourceAvailable( + session.datasource + ); + const sqlAccessContext = await this.chatPolicyGuardService.resolveSqlAccessContext( + session, + input.actor + ); + + const userMessage: ChatMessage = { + id: uuidv4(), + sessionId: input.sessionId, + role: "user", + content: input.message, + createdAt: new Date().toISOString() + }; + + await this.redisBuffer.bufferMessage(userMessage); + const userPersistResult = await this.repository.persistMessage(userMessage); + await this.repository.ensureSessionTitleFromFirstMessage( + input.sessionId, + input.message + ); + + return { + runId: uuidv4(), + session, + datasource, + sqlAccessContext, + question: input.message, + requestId: input.requestId, + contextEnvelope: input.contextEnvelope, + userPersistResult + }; + } +} diff --git a/apps/backend/src/modules/conversation/text2sql/stages/run-v2-langgraph.stage.ts b/apps/backend/src/modules/conversation/text2sql/stages/run-v2-langgraph.stage.ts new file mode 100644 index 0000000..a2d18be --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/stages/run-v2-langgraph.stage.ts @@ -0,0 +1 @@ +export * from "../../runtime/stages/run-v2-langgraph.stage"; diff --git a/apps/backend/src/modules/conversation/text2sql/stages/run-v2-state-machine.stage.ts b/apps/backend/src/modules/conversation/text2sql/stages/run-v2-state-machine.stage.ts new file mode 100644 index 0000000..b89ffa2 --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/stages/run-v2-state-machine.stage.ts @@ -0,0 +1,29 @@ +import { Injectable } from "@nestjs/common"; +import type { SqlRun } from "@text2sql/shared-types"; +import { + RunV2LangGraphStage, + type Text2SqlStreamV2LangGraphOptions +} from "../../runtime/stages/run-v2-langgraph.stage"; +import type { Text2SqlPreparedRunContext } from "./prepare-run.stage"; + +export type Text2SqlStreamV2StateMachineOptions = Text2SqlStreamV2LangGraphOptions; + +@Injectable() +/** + * @deprecated Use `RunV2LangGraphStage` as the active runtime seam. + */ +export class RunV2StateMachineStage { + constructor(private readonly runV2LangGraphStage: RunV2LangGraphStage) {} + + runSync(input: Text2SqlPreparedRunContext, route: string): Promise { + return this.runV2LangGraphStage.runSync(input, route); + } + + runStream( + input: Text2SqlPreparedRunContext, + route: string, + options?: Text2SqlStreamV2StateMachineOptions + ): Promise { + return this.runV2LangGraphStage.runStream(input, route, options); + } +} diff --git a/apps/backend/src/modules/conversation/text2sql/stages/text2sql-stage-catalog.ts b/apps/backend/src/modules/conversation/text2sql/stages/text2sql-stage-catalog.ts new file mode 100644 index 0000000..6750f28 --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/stages/text2sql-stage-catalog.ts @@ -0,0 +1,161 @@ +import type { ReasoningStage } from "@text2sql/shared-types"; +import type { Text2SqlV2StageName } from "@text2sql/shared-types"; +import type { Text2SqlStageName } from "../contracts/text2sql-stage-name"; + +export interface Text2SqlStageCatalogItem { + title: string; + reasoningStage: ReasoningStage; +} + +export const TEXT2SQL_STAGE_CATALOG: Record< + Text2SqlStageName, + Text2SqlStageCatalogItem +> = { + "prepare-run": { + title: "准备运行上下文", + reasoningStage: "analysis" + }, + "plan-intent": { + title: "规划意图", + reasoningStage: "analysis" + }, + "retrieve-context": { + title: "检索上下文", + reasoningStage: "analysis" + }, + "generate-sql": { + title: "生成 SQL", + reasoningStage: "generation" + }, + "validate-sql": { + title: "校验 SQL 与策略", + reasoningStage: "validation" + }, + "execute-sql": { + title: "执行查询", + reasoningStage: "execution" + }, + "format-answer": { + title: "整理回答", + reasoningStage: "response" + }, + "persist-run": { + title: "持久化运行记录", + reasoningStage: "response" + }, + "post-run-hooks": { + title: "执行后置钩子", + reasoningStage: "response" + }, + generic: { + title: "通用流程", + reasoningStage: "unknown" + } +}; + +const TEXT2SQL_V1_NODE_REASONING_STAGE_FALLBACK: Record = { + clarify: "analysis", + "retrieve-knowledge": "analysis", + "build-intent-plan": "analysis", + "build-semantic-query": "analysis", + "build-physical-plan": "analysis", + "resolve-saved-prior-sql": "analysis", + "generate-sql": "generation", + "safety-check": "validation", + "execute-sql": "execution", + "format-answer": "response" +}; + +const TEXT2SQL_V1_NODE_TITLE_FALLBACK: Record = { + clarify: "理解问题", + "retrieve-knowledge": "检索上下文", + "build-intent-plan": "意图规划", + "build-semantic-query": "语义规划", + "build-physical-plan": "物理规划", + "resolve-saved-prior-sql": "Prior SQL 复用判断", + "generate-sql": "生成 SQL", + "safety-check": "安全校验", + "execute-sql": "执行查询", + "format-answer": "整理回答" +}; + +export interface Text2SqlV2StageCatalogItem { + title: string; + reasoningStage: ReasoningStage; + taskProfile: string; + defaultReasoningTier: "low" | "medium" | "high"; +} + +export const TEXT2SQL_V2_STAGE_CATALOG: Record< + Text2SqlV2StageName, + Text2SqlV2StageCatalogItem +> = { + intake: { + title: "理解问题", + reasoningStage: "analysis", + taskProfile: "intake-fast", + defaultReasoningTier: "low" + }, + retrieve: { + title: "检索上下文", + reasoningStage: "analysis", + taskProfile: "retrieval-support", + defaultReasoningTier: "low" + }, + "assemble-context": { + title: "装配语义上下文", + reasoningStage: "analysis", + taskProfile: "context-assembly", + defaultReasoningTier: "low" + }, + "semantic-plan": { + title: "语义规划", + reasoningStage: "analysis", + taskProfile: "semantic-planning", + defaultReasoningTier: "high" + }, + "generate-sql": { + title: "生成 SQL", + reasoningStage: "generation", + taskProfile: "sql-generation", + defaultReasoningTier: "high" + }, + validate: { + title: "校验 SQL 与策略", + reasoningStage: "validation", + taskProfile: "sql-validation", + defaultReasoningTier: "medium" + }, + correct: { + title: "纠正 SQL", + reasoningStage: "validation", + taskProfile: "sql-correction", + defaultReasoningTier: "medium" + }, + execute: { + title: "执行查询", + reasoningStage: "execution", + taskProfile: "sql-execution", + defaultReasoningTier: "low" + }, + answer: { + title: "整理回答", + reasoningStage: "response", + taskProfile: "answer-rendering", + defaultReasoningTier: "low" + } +}; + +export const resolveText2SqlV2StageCatalogEntry = ( + stage: Text2SqlV2StageName +): Text2SqlV2StageCatalogItem => { + return TEXT2SQL_V2_STAGE_CATALOG[stage]; +}; + +export const resolveText2SqlReasoningStage = (node: string): ReasoningStage => { + return TEXT2SQL_V1_NODE_REASONING_STAGE_FALLBACK[node] ?? "unknown"; +}; + +export const resolveText2SqlTitle = (node: string): string => { + return TEXT2SQL_V1_NODE_TITLE_FALLBACK[node] ?? node; +}; diff --git a/apps/backend/src/modules/conversation/text2sql/stream/text2sql-stream-event.mapper.ts b/apps/backend/src/modules/conversation/text2sql/stream/text2sql-stream-event.mapper.ts new file mode 100644 index 0000000..f18d082 --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/stream/text2sql-stream-event.mapper.ts @@ -0,0 +1,301 @@ +import { Injectable } from "@nestjs/common"; +import type { + ChatStreamEvent, + ChatStreamEventData, + ChatStreamEventType, + ExecutionTraceStep, + SemanticPlanLedgerSummaryV1, + SqlRun, + Text2SqlV2RuntimePlanV1, + Text2SqlV2StageArtifact +} from "@text2sql/shared-types"; +import type { LlmGatewayStreamEvent } from "../../../llm/llm-gateway.interface"; +import { + resolveText2SqlV2StageCatalogEntry, + resolveText2SqlReasoningStage, + resolveText2SqlTitle +} from "../stages/text2sql-stage-catalog"; + +interface StepEventInput { + step: ExecutionTraceStep; + runId: string; + lastSequence: number; +} + +interface StepEventOutput { + data: ChatStreamEventData; + nextSequence: number; +} + +interface LlmEventOutput { + type: ChatStreamEventType; + data: ChatStreamEventData; + traceToolCall?: NonNullable["toolCalls"]>[number]; +} + +@Injectable() +export class Text2SqlStreamEventMapper { + createEnvelope(input: { + type: ChatStreamEventType; + data: ChatStreamEventData; + runId: string; + sessionId: string; + at?: string; + }): ChatStreamEvent { + return { + type: input.type, + runId: input.runId, + sessionId: input.sessionId, + at: input.at ?? new Date().toISOString(), + data: input.data + }; + } + + mapLlmEvent(event: LlmGatewayStreamEvent): LlmEventOutput { + if (event.type === "text-delta") { + return { + type: "text-delta", + data: { + text: event.text + } + }; + } + + if (event.type === "tool-call") { + return { + type: "tool-call", + data: { + toolName: event.toolName, + toolCallId: event.toolCallId, + input: event.input + }, + traceToolCall: { + toolName: event.toolName, + toolCallId: event.toolCallId, + status: "called", + detail: JSON.stringify(event.input ?? {}), + at: new Date().toISOString() + } + }; + } + + if (event.type === "tool-result") { + return { + type: "tool-result", + data: { + toolName: event.toolName, + toolCallId: event.toolCallId, + output: event.output + }, + traceToolCall: { + toolName: event.toolName, + toolCallId: event.toolCallId, + status: "result", + detail: JSON.stringify(event.output ?? {}), + at: new Date().toISOString() + } + }; + } + + return { + type: "tool-error", + data: { + toolName: event.toolName, + toolCallId: event.toolCallId, + message: event.message + }, + traceToolCall: { + toolName: event.toolName, + toolCallId: event.toolCallId, + status: "error", + detail: event.message, + at: new Date().toISOString() + } + }; + } + + mapStepEvent(input: StepEventInput): StepEventOutput { + const sequence = input.step.sequence ?? input.lastSequence + 1; + const stepAt = + input.step.at ?? input.step.endedAt ?? input.step.startedAt ?? new Date().toISOString(); + const v2StageArtifact = this.extractV2StageArtifact(input.step); + const v2RuntimePlan = this.extractV2RuntimePlanSummary(input.step); + const v2PlanLedger = this.extractV2PlanLedgerSummary(input.step); + const v2CatalogEntry = v2StageArtifact + ? resolveText2SqlV2StageCatalogEntry(v2StageArtifact.stage) + : undefined; + + return { + data: { + node: input.step.node, + status: input.step.status, + stepId: input.step.stepId ?? `${input.runId}:${input.step.node}:${sequence}`, + sequence, + lifecycle: input.step.lifecycle ?? this.resolveLifecycle(input.step.status), + detail: input.step.detail ?? "", + stage: v2CatalogEntry?.reasoningStage ?? resolveText2SqlReasoningStage(input.step.node), + title: v2CatalogEntry?.title ?? resolveText2SqlTitle(input.step.node), + at: stepAt, + startedAt: input.step.startedAt, + endedAt: input.step.endedAt, + durationMs: input.step.durationMs, + inputSummary: input.step.inputSummary, + outputSummary: input.step.outputSummary, + errorSummary: input.step.errorSummary, + ...(v2StageArtifact + ? { + v2: { + stageArtifact: v2StageArtifact, + ...(v2RuntimePlan ? { runtimePlan: v2RuntimePlan } : {}), + ...(v2PlanLedger ? { planLedger: v2PlanLedger } : {}) + } + } + : {}) + }, + nextSequence: Math.max(input.lastSequence, sequence) + }; + } + + private extractV2StageArtifact( + step: ExecutionTraceStep + ): Text2SqlV2StageArtifact | undefined { + const payloads = [step.outputSummary, step.inputSummary] + .filter((item): item is string => typeof item === "string" && item.trim().length > 0) + .slice(0, 2); + + for (const payload of payloads) { + const parsed = this.safeParseJson(payload); + if (!parsed || typeof parsed !== "object") { + continue; + } + const v2 = (parsed as { v2?: unknown }).v2; + if (!v2 || typeof v2 !== "object") { + continue; + } + const candidate = (v2 as { stageArtifact?: unknown }).stageArtifact; + if (!candidate || typeof candidate !== "object") { + continue; + } + const stage = (candidate as { stage?: unknown }).stage; + const status = (candidate as { status?: unknown }).status; + if (typeof stage !== "string" || typeof status !== "string") { + continue; + } + return candidate as Text2SqlV2StageArtifact; + } + + return undefined; + } + + private extractV2RuntimePlanSummary( + step: ExecutionTraceStep + ): NonNullable< + Extract["v2"] + >["runtimePlan"] | undefined { + const runtimePlan = this.extractV2RuntimePlan(step); + const current = + runtimePlan?.items.find((item) => item.id === runtimePlan.currentItemId) ?? + runtimePlan?.items.at(-1); + if (!runtimePlan || !current) { + return undefined; + } + return { + ...(runtimePlan.currentItemId + ? { currentItemId: runtimePlan.currentItemId } + : {}), + stage: current.stage, + status: current.status, + summary: current.summary ?? runtimePlan.summary, + ...(current.reasonCodes?.length ? { reasonCodes: current.reasonCodes } : {}) + }; + } + + private extractV2RuntimePlan( + step: ExecutionTraceStep + ): Text2SqlV2RuntimePlanV1 | undefined { + const payloads = [step.outputSummary, step.inputSummary] + .filter((item): item is string => typeof item === "string" && item.trim().length > 0) + .slice(0, 2); + + for (const payload of payloads) { + const parsed = this.safeParseJson(payload); + if (!parsed || typeof parsed !== "object") { + continue; + } + const v2 = (parsed as { v2?: unknown }).v2; + if (!v2 || typeof v2 !== "object") { + continue; + } + const candidate = (v2 as { runtimePlan?: unknown }).runtimePlan; + if (!candidate || typeof candidate !== "object") { + continue; + } + const items = (candidate as { items?: unknown }).items; + if (!Array.isArray(items) || items.length === 0) { + continue; + } + return candidate as Text2SqlV2RuntimePlanV1; + } + + return undefined; + } + + private extractV2PlanLedgerSummary( + step: ExecutionTraceStep + ): SemanticPlanLedgerSummaryV1 | undefined { + const payloads = [step.outputSummary, step.inputSummary] + .filter((item): item is string => typeof item === "string" && item.trim().length > 0) + .slice(0, 2); + + for (const payload of payloads) { + const parsed = this.safeParseJson(payload); + if (!parsed || typeof parsed !== "object") { + continue; + } + const v2 = (parsed as { v2?: unknown }).v2; + if (!v2 || typeof v2 !== "object") { + continue; + } + const candidate = + (v2 as { planLedger?: unknown }).planLedger ?? + (v2 as { sqlValidation?: { ledgerFulfillment?: unknown } }).sqlValidation?.ledgerFulfillment ?? + (v2 as { semanticPlan?: { planLedger?: { summary?: unknown } } }).semanticPlan?.planLedger?.summary; + if (!candidate || typeof candidate !== "object") { + continue; + } + const total = (candidate as { total?: unknown }).total; + const hardBlockerCount = (candidate as { hardBlockerCount?: unknown }).hardBlockerCount; + const warningCount = (candidate as { warningCount?: unknown }).warningCount; + if ( + typeof total !== "number" || + typeof hardBlockerCount !== "number" || + typeof warningCount !== "number" + ) { + continue; + } + return candidate as SemanticPlanLedgerSummaryV1; + } + + return undefined; + } + + private safeParseJson(value: string): unknown { + try { + return JSON.parse(value); + } catch { + return undefined; + } + } + + private resolveLifecycle( + status: ExecutionTraceStep["status"] + ): "completed" | "failed" | "skipped" { + if (status === "failed") { + return "failed"; + } + if (status === "skipped") { + return "skipped"; + } + return "completed"; + } +} diff --git a/apps/backend/src/modules/conversation/text2sql/text2sql-workflow-runner.service.ts b/apps/backend/src/modules/conversation/text2sql/text2sql-workflow-runner.service.ts new file mode 100644 index 0000000..68c15e4 --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/text2sql-workflow-runner.service.ts @@ -0,0 +1 @@ +export * from "../application/workflow/text2sql-workflow-runner.service"; diff --git a/apps/backend/src/modules/conversation/text2sql/text2sql.module.ts b/apps/backend/src/modules/conversation/text2sql/text2sql.module.ts new file mode 100644 index 0000000..9381977 --- /dev/null +++ b/apps/backend/src/modules/conversation/text2sql/text2sql.module.ts @@ -0,0 +1,60 @@ +import { Module } from "@nestjs/common"; +import { AgentModule } from "../agent/agent.module"; +import { DatasourceModule } from "../../governance/datasource/datasource.module"; +import { GovernanceAccessModule } from "../../governance/access/access.module"; +import { KnowledgeModule } from "../../knowledge/knowledge.module"; +import { ObservabilityModule } from "../../observability/observability.module"; +import { PlatformDataPersistenceModule } from "../../platform/data/persistence.module"; +import { DeliveryContractMapper } from "../delivery/delivery-contract.mapper"; +import { ChartBiArtifactService } from "../delivery/chartbi/chartbi-artifact.service"; +import { ChartBiGroundingGuard } from "../delivery/chartbi/chartbi-grounding.guard"; +import { ChartBiIntentParser } from "../delivery/chartbi/chartbi-intent-parser"; +import { ChartBiResultProfiler } from "../delivery/chartbi/chartbi-result-profiler"; +import { ChartBiSpecCompiler } from "../delivery/chartbi/chartbi-spec-compiler"; +import { ChartBiValidator } from "../delivery/chartbi/chartbi-validator"; +import { SandboxRuntimeService } from "../delivery/sandbox/sandbox-runtime.service"; +import { ChatDeliveryEnrichmentService } from "../chat/application/shared/chat-delivery-enrichment.service"; +import { ChatPolicyGuardService } from "../chat/application/shared/chat-policy-guard.service"; +import { ChatPostRunHooksService } from "../chat/application/shared/chat-post-run-hooks.service"; +import { ChatRunPersistenceService } from "../chat/application/shared/chat-run-persistence.service"; +import { Text2SQLWorkflowRunner } from "../application/workflow/text2sql-workflow-runner.service"; +import { EnrichDeliveryStage } from "./stages/enrich-delivery.stage"; +import { PersistRunStage } from "./stages/persist-run.stage"; +import { PostRunHooksStage } from "./stages/post-run-hooks.stage"; +import { PrepareRunStage } from "./stages/prepare-run.stage"; +import { RunV2LangGraphStage } from "../runtime/stages/run-v2-langgraph.stage"; +import { Text2SqlStreamEventMapper } from "./stream/text2sql-stream-event.mapper"; + +@Module({ + imports: [ + AgentModule, + PlatformDataPersistenceModule, + GovernanceAccessModule, + DatasourceModule, + ObservabilityModule, + KnowledgeModule + ], + providers: [ + Text2SQLWorkflowRunner, + PrepareRunStage, + RunV2LangGraphStage, + EnrichDeliveryStage, + PersistRunStage, + PostRunHooksStage, + Text2SqlStreamEventMapper, + ChatPolicyGuardService, + ChatRunPersistenceService, + ChatPostRunHooksService, + ChatDeliveryEnrichmentService, + DeliveryContractMapper, + SandboxRuntimeService, + ChartBiArtifactService, + ChartBiResultProfiler, + ChartBiIntentParser, + ChartBiSpecCompiler, + ChartBiValidator, + ChartBiGroundingGuard + ], + exports: [Text2SQLWorkflowRunner, ChatDeliveryEnrichmentService] +}) +export class Text2SqlModule {} diff --git a/apps/backend/src/modules/data/persistence/chat.repository.ts b/apps/backend/src/modules/data/persistence/chat.repository.ts index d986c43..d6e809b 100644 --- a/apps/backend/src/modules/data/persistence/chat.repository.ts +++ b/apps/backend/src/modules/data/persistence/chat.repository.ts @@ -2,7 +2,6 @@ import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from "@nestjs/commo import type { ChatMessage, EvaluationReport, - PromptTemplateTraceEvidenceCompat, Session, SessionSyncStatus, SqlRun @@ -756,22 +755,13 @@ export class ChatRepository implements OnModuleInit, OnModuleDestroy { const traceWithPlannerMetadata = trace as SqlRun["trace"] & { plannerCache?: Record; plannerReplay?: Record; - prompt_template?: unknown; - prompt_template_evidence?: unknown; - templateEvidence?: unknown; }; const { promptTemplate: canonicalPromptTemplate, - prompt_template: legacySnakePromptTemplate, - prompt_template_evidence: legacyEvidencePromptTemplate, - templateEvidence: legacyTemplateEvidence, ...traceWithoutPromptTemplateAliases } = traceWithPlannerMetadata; const normalizedPromptTemplate = this.normalizePromptTemplateTraceEvidence( - canonicalPromptTemplate ?? - legacySnakePromptTemplate ?? - legacyEvidencePromptTemplate ?? - legacyTemplateEvidence + canonicalPromptTemplate ); const normalizedSteps = (trace.steps ?? []).map((step, index) => { const sequence = step.sequence ?? index + 1; @@ -807,18 +797,18 @@ export class ChatRepository implements OnModuleInit, OnModuleDestroy { if (!this.isRecord(value)) { return undefined; } - const candidate = value as PromptTemplateTraceEvidenceCompat; - const templateId = this.readNonEmptyString(candidate.templateId ?? candidate.template_id); - const scope = this.normalizePromptTemplateScope( - candidate.scope ?? candidate.scope_type ?? candidate.template_scope - ); - const version = this.readPositiveInteger(candidate.version ?? candidate.template_version); - const fallbackReason = this.readNonEmptyString( - candidate.fallbackReason ?? candidate.fallback_reason - ); - const scene = this.normalizePromptTemplateScene( - candidate.scene ?? candidate.scene_name ?? candidate.template_scene - ); + const candidate = value as { + templateId?: unknown; + scope?: unknown; + version?: unknown; + fallbackReason?: unknown; + scene?: unknown; + }; + const templateId = this.readNonEmptyString(candidate.templateId); + const scope = this.normalizePromptTemplateScope(candidate.scope); + const version = this.readPositiveInteger(candidate.version); + const fallbackReason = this.readNonEmptyString(candidate.fallbackReason); + const scene = this.normalizePromptTemplateScene(candidate.scene); if (!templateId && !scope && version === undefined && !fallbackReason && !scene) { return undefined; diff --git a/apps/backend/src/modules/data/persistence/rag-task-config.repository.ts b/apps/backend/src/modules/data/persistence/rag-task-config.repository.ts new file mode 100644 index 0000000..0957eed --- /dev/null +++ b/apps/backend/src/modules/data/persistence/rag-task-config.repository.ts @@ -0,0 +1,436 @@ +import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from "@nestjs/common"; +import type { + RagConfigHealthStatus, + RagTaskConfig, + RagTaskType +} from "@text2sql/shared-types"; +import { v4 as uuidv4 } from "uuid"; +import { AppConfigService } from "../../config/app-config.service"; + +type PrismaClientLike = { + ragTaskConfig: { + upsert: (args: Record) => Promise; + findMany: (args?: Record) => Promise; + findUnique: (args: Record) => Promise; + update: (args: Record) => Promise; + }; + $disconnect: () => Promise; +}; + +type RagTaskConfigRow = { + id: string; + taskType: string; + provider: string; + model: string; + baseUrl: string | null; + apiKeyCiphertext: string | null; + apiKeyMasked: string | null; + enabled: boolean; + dimensions: number | null; + vectorVersion: string | null; + timeoutMs: number | null; + note: string | null; + healthStatus: string; + lastCheckedAt: Date | null; + lastHealthLatencyMs: number | null; + lastHealthMessage: string | null; + lastError: string | null; + createdAt: Date; + updatedAt: Date; +}; + +type RagTaskConfigUpsertInput = { + taskType: RagTaskType; + provider: string; + model: string; + baseUrl?: string | null; + apiKeyCiphertext?: string | null; + apiKeyMasked?: string | null; + enabled?: boolean; + dimensions?: number | null; + vectorVersion?: string | null; + timeoutMs?: number | null; + note?: string | null; + actorId?: string; +}; + +type RagTaskConfigHealthPatch = { + healthStatus?: RagConfigHealthStatus; + lastCheckedAt?: string | null; + lastHealthLatencyMs?: number | null; + lastHealthMessage?: string | null; + lastError?: string | null; +}; + +@Injectable() +export class RagTaskConfigRepository implements OnModuleInit, OnModuleDestroy { + private readonly logger = new Logger(RagTaskConfigRepository.name); + private prisma?: PrismaClientLike; + private readonly configs = new Map(); + private readonly apiKeys = new Map(); + + constructor(private readonly appConfig: AppConfigService) {} + + async onModuleInit(): Promise { + if (!this.appConfig.databaseUrl) { + return; + } + try { + const prismaClientModulePath = "../../../generated/prisma/client"; + const prismaModule = (await import(prismaClientModulePath)) as unknown as { + PrismaClient?: new (...args: unknown[]) => PrismaClientLike; + default?: { + PrismaClient?: new (...args: unknown[]) => PrismaClientLike; + }; + }; + const adapterModule = (await import("@prisma/adapter-pg")) as unknown as { + PrismaPg?: new (...args: unknown[]) => unknown; + default?: { + PrismaPg?: new (...args: unknown[]) => unknown; + }; + }; + const PrismaCtor = + prismaModule.PrismaClient ?? prismaModule.default?.PrismaClient; + const PrismaPgCtor = + adapterModule.PrismaPg ?? adapterModule.default?.PrismaPg; + if (!PrismaCtor) { + throw new Error("PrismaClient 未生成，请先执行 prisma generate"); + } + if (!PrismaPgCtor) { + throw new Error("Prisma PostgreSQL adapter 未安装"); + } + const adapter = new PrismaPgCtor({ + connectionString: this.appConfig.databaseUrl + }); + this.prisma = new PrismaCtor({ + adapter + }) as PrismaClientLike; + this.logger.log("RAG task config 仓储已启用 PostgreSQL 持久化。"); + } catch (error) { + this.logger.warn( + `RAG task config 仓储初始化失败，降级为内存模式: ${ + error instanceof Error ? error.message : String(error) + }` + ); + } + } + + async onModuleDestroy(): Promise { + if (this.prisma) { + await this.prisma.$disconnect(); + } + } + + async upsertConfig(input: RagTaskConfigUpsertInput): Promise { + const current = await this.getConfig(input.taskType); + const nextProvider = input.provider.trim(); + const nextModel = input.model.trim(); + const nextBaseUrl = input.baseUrl?.trim() || null; + const shouldPreserveApiKey = + input.apiKeyCiphertext === undefined && + this.hasSameRuntimeTarget(current, { + provider: nextProvider, + model: nextModel, + baseUrl: nextBaseUrl + }); + const nextApiKeyCiphertext = + input.apiKeyCiphertext !== undefined + ? input.apiKeyCiphertext + : shouldPreserveApiKey + ? (this.apiKeys.get(input.taskType) ?? null) + : null; + const now = new Date().toISOString(); + const id = current?.id ?? uuidv4(); + const config: RagTaskConfig = { + id, + taskType: input.taskType, + provider: nextProvider, + model: nextModel, + baseUrl: nextBaseUrl, + enabled: input.enabled ?? current?.enabled ?? true, + hasApiKey: Boolean(nextApiKeyCiphertext), + apiKeyMasked: input.apiKeyMasked ?? (shouldPreserveApiKey ? current?.apiKeyMasked : null), + dimensions: input.dimensions ?? current?.dimensions ?? null, + vectorVersion: input.vectorVersion ?? current?.vectorVersion ?? null, + timeoutMs: input.timeoutMs ?? current?.timeoutMs ?? null, + note: input.note ?? current?.note ?? null, + healthStatus: current?.healthStatus ?? "unknown", + lastCheckedAt: current?.lastCheckedAt ?? null, + lastHealthLatencyMs: current?.lastHealthLatencyMs ?? null, + lastHealthMessage: current?.lastHealthMessage ?? null, + lastError: current?.lastError ?? null, + configSource: "settings", + configSourceNote: null, + createdAt: current?.createdAt ?? now, + updatedAt: now + }; + this.configs.set(input.taskType, config); + if (nextApiKeyCiphertext) { + this.apiKeys.set(input.taskType, nextApiKeyCiphertext); + } else { + this.apiKeys.delete(input.taskType); + } + + if (!this.isPrimaryPersistenceConfigured() || !this.prisma) { + return config; + } + + await this.tryPrismaWrite(async () => { + await this.prisma?.ragTaskConfig.upsert({ + where: { + taskType: input.taskType + }, + update: { + provider: config.provider, + model: config.model, + baseUrl: config.baseUrl, + apiKeyCiphertext: nextApiKeyCiphertext, + apiKeyMasked: config.apiKeyMasked, + enabled: config.enabled, + dimensions: config.dimensions, + vectorVersion: config.vectorVersion, + timeoutMs: config.timeoutMs, + note: config.note, + updatedBy: input.actorId ?? null, + updatedAt: new Date(config.updatedAt) + }, + create: { + id: config.id, + taskType: input.taskType, + provider: config.provider, + model: config.model, + baseUrl: config.baseUrl, + apiKeyCiphertext: nextApiKeyCiphertext, + apiKeyMasked: config.apiKeyMasked, + enabled: config.enabled, + dimensions: config.dimensions, + vectorVersion: config.vectorVersion, + timeoutMs: config.timeoutMs, + note: config.note, + healthStatus: config.healthStatus, + createdBy: input.actorId ?? null, + updatedBy: input.actorId ?? null, + createdAt: new Date(config.createdAt), + updatedAt: new Date(config.updatedAt) + } + }); + }); + + return config; + } + + async updateHealth( + taskType: RagTaskType, + patch: RagTaskConfigHealthPatch + ): Promise { + const current = await this.getConfig(taskType); + if (!current) { + return undefined; + } + const next: RagTaskConfig = { + ...current, + healthStatus: patch.healthStatus ?? current.healthStatus, + lastCheckedAt: + patch.lastCheckedAt !== undefined ? patch.lastCheckedAt : current.lastCheckedAt, + lastHealthLatencyMs: + patch.lastHealthLatencyMs !== undefined + ? patch.lastHealthLatencyMs + : current.lastHealthLatencyMs, + lastHealthMessage: + patch.lastHealthMessage !== undefined + ? patch.lastHealthMessage + : current.lastHealthMessage, + lastError: patch.lastError !== undefined ? patch.lastError : current.lastError, + updatedAt: new Date().toISOString() + }; + this.configs.set(taskType, next); + + if (!this.isPrimaryPersistenceConfigured() || !this.prisma) { + return next; + } + await this.tryPrismaWrite(async () => { + await this.prisma?.ragTaskConfig.update({ + where: { taskType }, + data: { + healthStatus: next.healthStatus, + lastCheckedAt: next.lastCheckedAt ? new Date(next.lastCheckedAt) : null, + lastHealthLatencyMs: next.lastHealthLatencyMs, + lastHealthMessage: next.lastHealthMessage, + lastError: next.lastError, + updatedAt: new Date(next.updatedAt) + } + }); + }); + return next; + } + + async listConfigs(): Promise { + const fromMemory = Array.from(this.configs.values()); + if (!this.isPrimaryPersistenceConfigured() || !this.prisma) { + return this.sortByTaskType(fromMemory); + } + const rows = (await this.tryPrismaRead(async () => + this.prisma?.ragTaskConfig.findMany({ + orderBy: { + updatedAt: "desc" + } + }) + )) as RagTaskConfigRow[] | null; + if (!rows) { + return this.sortByTaskType(fromMemory); + } + + const merged = new Map(); + for (const row of rows) { + const mapped = this.fromRow(row); + this.configs.set(mapped.taskType, mapped); + merged.set(mapped.taskType, mapped); + if (row.apiKeyCiphertext) { + this.apiKeys.set(mapped.taskType, row.apiKeyCiphertext); + } + } + for (const item of fromMemory) { + merged.set(item.taskType, item); + } + return this.sortByTaskType(Array.from(merged.values())); + } + + async getConfig(taskType: RagTaskType): Promise { + const cached = this.configs.get(taskType); + if (cached) { + return cached; + } + + if (!this.isPrimaryPersistenceConfigured() || !this.prisma) { + return undefined; + } + const row = (await this.tryPrismaRead(async () => + this.prisma?.ragTaskConfig.findUnique({ + where: { taskType } + }) + )) as RagTaskConfigRow | null; + if (!row) { + return undefined; + } + const mapped = this.fromRow(row); + this.configs.set(taskType, mapped); + if (row.apiKeyCiphertext) { + this.apiKeys.set(taskType, row.apiKeyCiphertext); + } + return mapped; + } + + async getApiKey(taskType: RagTaskType): Promise { + const cached = this.apiKeys.get(taskType); + if (cached) { + return cached; + } + if (!this.isPrimaryPersistenceConfigured() || !this.prisma) { + return undefined; + } + const row = (await this.tryPrismaRead(async () => + this.prisma?.ragTaskConfig.findUnique({ + where: { taskType } + }) + )) as RagTaskConfigRow | null; + if (!row?.apiKeyCiphertext) { + return undefined; + } + this.apiKeys.set(taskType, row.apiKeyCiphertext); + return row.apiKeyCiphertext; + } + + private fromRow(row: RagTaskConfigRow): RagTaskConfig { + const taskType = this.toTaskType(row.taskType); + return { + id: row.id, + taskType, + provider: row.provider, + model: row.model, + baseUrl: row.baseUrl, + enabled: row.enabled, + hasApiKey: Boolean(row.apiKeyCiphertext), + apiKeyMasked: row.apiKeyMasked, + dimensions: row.dimensions, + vectorVersion: row.vectorVersion, + timeoutMs: row.timeoutMs, + note: row.note, + healthStatus: this.toHealthStatus(row.healthStatus), + lastCheckedAt: row.lastCheckedAt?.toISOString() ?? null, + lastHealthLatencyMs: row.lastHealthLatencyMs, + lastHealthMessage: row.lastHealthMessage, + lastError: row.lastError, + configSource: "settings", + configSourceNote: null, + createdAt: row.createdAt.toISOString(), + updatedAt: row.updatedAt.toISOString() + }; + } + + private toTaskType(value: string): RagTaskType { + return value === "rerank" ? "rerank" : "embedding"; + } + + private toHealthStatus(value: string): RagConfigHealthStatus { + if (value === "healthy" || value === "degraded" || value === "failed") { + return value; + } + return "unknown"; + } + + private sortByTaskType(configs: RagTaskConfig[]): RagTaskConfig[] { + return [...configs].sort((left, right) => + left.taskType.localeCompare(right.taskType) + ); + } + + private hasSameRuntimeTarget( + current: Pick | undefined, + next: { + provider: string; + model: string; + baseUrl: string | null; + } + ): boolean { + if (!current) { + return false; + } + return ( + current.provider.trim() === next.provider && + current.model.trim() === next.model && + (current.baseUrl?.trim() || null) === next.baseUrl + ); + } + + private isPrimaryPersistenceConfigured(): boolean { + return Boolean(this.appConfig.databaseUrl.trim().length > 0); + } + + private async tryPrismaWrite(operation: () => Promise): Promise { + try { + await operation(); + } catch (error) { + this.logger.warn( + `RAG task config 写入数据库失败，已保留内存态: ${ + error instanceof Error ? error.message : String(error) + }` + ); + } + } + + private async tryPrismaRead( + operation: () => Promise + ): Promise { + try { + const value = await operation(); + return (value ?? null) as T | null; + } catch (error) { + this.logger.warn( + `RAG task config 读取数据库失败，回退内存态: ${ + error instanceof Error ? error.message : String(error) + }` + ); + return null; + } + } +} diff --git a/apps/backend/src/modules/data/query/query-executor-router.service.ts b/apps/backend/src/modules/data/query/query-executor-router.service.ts index f5aea64..8e6494f 100644 --- a/apps/backend/src/modules/data/query/query-executor-router.service.ts +++ b/apps/backend/src/modules/data/query/query-executor-router.service.ts @@ -14,6 +14,19 @@ import { SqliteExecutorService } from "./sqlite-executor.service"; const MAX_QUERY_LIMIT = 200; const DEFAULT_QUERY_LIMIT = 50; + +export interface QueryValidationCapabilities { + dryRun: boolean; + dryPlan: boolean; + reason?: string; +} + +export interface QueryDryPlanSnapshot { + complete: boolean; + referencedTables: string[]; + reason?: string; +} + export interface QueryExecutionTablePermissionsOptions { accessContext?: SqlTableAccessContext; allowedTables?: Iterable; @@ -79,6 +92,29 @@ export class QueryExecutorRouterService { }); } + getValidationCapabilities(datasourceType: DatasourceType): QueryValidationCapabilities { + if (datasourceType === "csv" || datasourceType === "excel") { + return { + dryRun: false, + dryPlan: true, + reason: `${datasourceType} datasource does not support pre-execution dry-run` + }; + } + return { + dryRun: true, + dryPlan: true + }; + } + + buildDryPlan(sql: string): QueryDryPlanSnapshot { + const extraction = this.tableAccessGuard.extractReferencedTables(sql); + return { + complete: extraction.complete, + referencedTables: extraction.tables, + ...(extraction.reason ? { reason: extraction.reason } : {}) + }; + } + private ensureLimit(sql: string, limit?: number): string { const normalized = sql.trim().replace(/;\s*$/, ""); const limitWithOffsetPattern = /\blimit\s+(\d+)\s+offset\s+(\d+)\s*$/i; diff --git a/apps/backend/src/modules/eval/eval.module.ts b/apps/backend/src/modules/eval/eval.module.ts index 5b38240..8f4395a 100644 --- a/apps/backend/src/modules/eval/eval.module.ts +++ b/apps/backend/src/modules/eval/eval.module.ts @@ -1,12 +1,18 @@ import { Module } from "@nestjs/common"; -import { AgentModule } from "../conversation/agent/agent.module"; +import { Text2SqlModule } from "../conversation/text2sql/text2sql.module"; import { PlatformDataPersistenceModule } from "../platform/data/persistence.module"; import { AppConfigModule } from "../config/config.module"; +import { ObservabilityModule } from "../observability/observability.module"; import { EvalController } from "./eval.controller"; import { EvalService } from "./eval.service"; @Module({ - imports: [AgentModule, PlatformDataPersistenceModule, AppConfigModule], + imports: [ + Text2SqlModule, + PlatformDataPersistenceModule, + AppConfigModule, + ObservabilityModule + ], controllers: [EvalController], providers: [EvalService], exports: [EvalService] diff --git a/apps/backend/src/modules/eval/eval.service.ts b/apps/backend/src/modules/eval/eval.service.ts index 45bd174..aa4719a 100644 --- a/apps/backend/src/modules/eval/eval.service.ts +++ b/apps/backend/src/modules/eval/eval.service.ts @@ -8,16 +8,20 @@ import type { EvaluationCaseResult, EvaluationReport } from "@text2sql/shared-types"; -import { GraphBuilderService } from "../conversation/agent/graph/graph.builder"; +import { Text2SQLWorkflowRunner } from "../conversation/text2sql/text2sql-workflow-runner.service"; import { ChatRepository } from "../data/persistence/chat.repository"; import { AppConfigService } from "../config/app-config.service"; +import { LangsmithTraceService } from "../observability/langsmith-trace.service"; + +const EVALUATION_ROUTE = "/api/v1/evaluations/run"; @Injectable() export class EvalService { constructor( - private readonly graphBuilder: GraphBuilderService, + private readonly workflowRunner: Text2SQLWorkflowRunner, private readonly repository: ChatRepository, - private readonly appConfig: AppConfigService + private readonly appConfig: AppConfigService, + private readonly langsmithTrace: LangsmithTraceService ) {} async run(caseFilePath?: string, requestId?: string): Promise { @@ -26,25 +30,64 @@ export class EvalService { const jobId = uuidv4(); for (const item of cases) { const evalSessionId = `eval-${jobId}-${item.id}`; + const traceRunId = uuidv4(); await this.repository.createSession({ id: evalSessionId, datasource: "sqlite_main", createdAt: new Date().toISOString() }); - const run = await this.graphBuilder.run({ - runId: uuidv4(), + const rootTrace = this.langsmithTrace.startRoot({ + runId: traceRunId, sessionId: evalSessionId, question: item.question, - datasourceId: "sqlite_main", - datasourceType: "sqlite", - traceContext: { - source: "evaluation", - route: "/api/v1/evaluations/run", - requestId, - jobId, - caseId: item.id - } + source: "evaluation", + route: EVALUATION_ROUTE, + requestId, + jobId, + caseId: item.id }); + let runEnded = false; + const run = await this.workflowRunner + .runSync({ + sessionId: evalSessionId, + message: item.question, + requestId + }) + .then((result) => { + this.langsmithTrace.endRoot(rootTrace, { + status: result.status, + provider: result.provider, + outputs: { + rowCount: result.rows?.length, + hasError: Boolean(result.error) + }, + metadata: { + source: "evaluation", + route: EVALUATION_ROUTE, + requestId, + jobId, + caseId: item.id + } + }); + runEnded = true; + return result; + }) + .catch((error: unknown) => { + if (!runEnded) { + this.langsmithTrace.endRoot(rootTrace, { + status: "failed", + error: error instanceof Error ? error.message : String(error), + metadata: { + source: "evaluation", + route: EVALUATION_ROUTE, + requestId, + jobId, + caseId: item.id + } + }); + } + throw error; + }); let passed = true; let reason = ""; diff --git a/apps/backend/src/modules/governance/datasource/datasource.service.ts b/apps/backend/src/modules/governance/datasource/datasource.service.ts index 6510fdc..1f5e3cc 100644 --- a/apps/backend/src/modules/governance/datasource/datasource.service.ts +++ b/apps/backend/src/modules/governance/datasource/datasource.service.ts @@ -13,9 +13,11 @@ import { v4 as uuidv4 } from "uuid"; import { DomainError } from "../../../common/domain-error"; import { encryptSecret } from "../../../common/secret-crypto"; import { AppConfigService } from "../../config/app-config.service"; -import { SqliteQueryService } from "../../data/sqlite/sqlite-query.service"; import { DatasourceRepository } from "../../platform/data/persistence/index"; -import { QueryExecutorRouterService } from "../../platform/data/query/index"; +import { + QueryExecutorRouterService, + SqliteQueryService +} from "../../platform/data/query/index"; import type { AccessContext } from "../access/datasource-access-policy.service"; import { PolicyEvaluatorService } from "../access/policy-evaluator.service"; diff --git a/apps/backend/src/modules/governance/settings/dto/check-rag-task-config-health.dto.ts b/apps/backend/src/modules/governance/settings/dto/check-rag-task-config-health.dto.ts new file mode 100644 index 0000000..647706e --- /dev/null +++ b/apps/backend/src/modules/governance/settings/dto/check-rag-task-config-health.dto.ts @@ -0,0 +1,87 @@ +import { + ArrayMaxSize, + IsArray, + IsInt, + IsBoolean, + IsObject, + IsOptional, + IsString, + Length, + Max, + Min, + ValidateNested +} from "class-validator"; +import { Type } from "class-transformer"; + +export class CheckRagTaskConfigDraftDto { + @IsOptional() + @IsString() + @Length(0, 64) + provider?: string; + + @IsOptional() + @IsString() + @Length(0, 120) + model?: string; + + @IsOptional() + @IsString() + @Length(0, 300) + baseUrl?: string; + + @IsOptional() + @IsString() + @Length(0, 500) + apiKey?: string; + + @IsOptional() + @IsBoolean() + enabled?: boolean; + + @IsOptional() + @IsInt() + @Min(1) + @Max(32768) + dimensions?: number; + + @IsOptional() + @IsString() + @Length(0, 64) + vectorVersion?: string; + + @IsOptional() + @IsInt() + @Min(1) + @Max(120000) + timeoutMs?: number; + + @IsOptional() + @IsString() + @Length(0, 500) + note?: string; +} + +export class CheckRagTaskConfigHealthDto { + @IsOptional() + @IsString() + @Length(1, 500) + sampleQuery?: string; + + @IsOptional() + @IsArray() + @ArrayMaxSize(10) + @IsString({ each: true }) + sampleCandidates?: string[]; + + @IsOptional() + @IsInt() + @Min(1) + @Max(32768) + expectedDimensions?: number; + + @IsOptional() + @IsObject() + @ValidateNested() + @Type(() => CheckRagTaskConfigDraftDto) + draft?: CheckRagTaskConfigDraftDto; +} diff --git a/apps/backend/src/modules/governance/settings/dto/preview-rag-provider-models.dto.ts b/apps/backend/src/modules/governance/settings/dto/preview-rag-provider-models.dto.ts new file mode 100644 index 0000000..e70e103 --- /dev/null +++ b/apps/backend/src/modules/governance/settings/dto/preview-rag-provider-models.dto.ts @@ -0,0 +1,30 @@ +import { IsIn, IsOptional, IsString, Length } from "class-validator"; +import type { LlmProviderCode } from "@text2sql/shared-types"; + +const SUPPORTED_PROVIDERS: LlmProviderCode[] = [ + "openai", + "gemini", + "deepseek", + "kimi", + "volcengine", + "siliconflow", + "openrouter", + "minimax", + "tencent-hunyuan", + "tongyi" +]; + +export class PreviewRagProviderModelsDto { + @IsString() + @IsIn(SUPPORTED_PROVIDERS) + provider!: LlmProviderCode; + + @IsOptional() + @IsString() + @Length(1, 300) + baseUrl?: string; + + @IsString() + @Length(1, 500) + apiKey!: string; +} diff --git a/apps/backend/src/modules/governance/settings/dto/upsert-rag-task-config.dto.ts b/apps/backend/src/modules/governance/settings/dto/upsert-rag-task-config.dto.ts new file mode 100644 index 0000000..f840ec5 --- /dev/null +++ b/apps/backend/src/modules/governance/settings/dto/upsert-rag-task-config.dto.ts @@ -0,0 +1,47 @@ +import { IsBoolean, IsInt, IsOptional, IsString, Length, Max, Min } from "class-validator"; + +export class UpsertRagTaskConfigDto { + @IsString() + @Length(1, 64) + provider!: string; + + @IsString() + @Length(1, 120) + model!: string; + + @IsOptional() + @IsString() + @Length(1, 300) + baseUrl?: string; + + @IsOptional() + @IsString() + @Length(1, 500) + apiKey?: string; + + @IsOptional() + @IsBoolean() + enabled?: boolean; + + @IsOptional() + @IsInt() + @Min(1) + @Max(32768) + dimensions?: number; + + @IsOptional() + @IsString() + @Length(1, 64) + vectorVersion?: string; + + @IsOptional() + @IsInt() + @Min(1) + @Max(120000) + timeoutMs?: number; + + @IsOptional() + @IsString() + @Length(1, 500) + note?: string; +} diff --git a/apps/backend/src/modules/governance/settings/settings.controller.ts b/apps/backend/src/modules/governance/settings/settings.controller.ts index c64d35d..d97f741 100644 --- a/apps/backend/src/modules/governance/settings/settings.controller.ts +++ b/apps/backend/src/modules/governance/settings/settings.controller.ts @@ -5,6 +5,7 @@ import { Get, Param, Patch, + Put, Post, Query, Req, @@ -12,15 +13,18 @@ import { UseGuards } from "@nestjs/common"; import type { Request, Response } from "express"; -import type { ApiResponse } from "@text2sql/shared-types"; +import type { ApiResponse, RagTaskType } from "@text2sql/shared-types"; import { fail, ok } from "../../../common/api-response"; import { DomainError } from "../../../common/domain-error"; import { AdminOnlyGuard } from "../../auth/admin-only.guard"; import { BatchUpdateModelStatusDto } from "./dto/batch-update-model-status.dto"; +import { CheckRagTaskConfigHealthDto } from "./dto/check-rag-task-config-health.dto"; import { CreatePromptTemplateDto } from "./dto/create-prompt-template.dto"; import { CreateProviderDto } from "./dto/create-provider.dto"; import { ListPromptTemplatesQueryDto } from "./dto/list-prompt-templates.query.dto"; +import { PreviewRagProviderModelsDto } from "./dto/preview-rag-provider-models.dto"; import { RefreshProviderModelsDto } from "./dto/refresh-provider-models.dto"; +import { UpsertRagTaskConfigDto } from "./dto/upsert-rag-task-config.dto"; import { UpdatePromptTemplateDto } from "./dto/update-prompt-template.dto"; import { UpdateModelStatusDto } from "./dto/update-model-status.dto"; import { SettingsService } from "./settings.service"; @@ -49,6 +53,71 @@ export class SettingsController { } } + @Get("/rag-configs") + async listRagTaskConfigs(@Req() req: Request): Promise> { + try { + const data = await this.settingsService.listRagTaskConfigs(req.actor); + return ok(req.requestId, data); + } catch (error) { + return this.toError(req.requestId, error); + } + } + + @Put("/rag-configs/:taskType") + @UseGuards(AdminOnlyGuard) + async upsertRagTaskConfig( + @Param("taskType") taskTypeRaw: string, + @Body() body: UpsertRagTaskConfigDto, + @Req() req: Request + ): Promise> { + try { + const taskType = this.parseTaskType(taskTypeRaw); + const data = await this.settingsService.upsertRagTaskConfig( + req.actor, + taskType, + body + ); + return ok(req.requestId, data); + } catch (error) { + return this.toError(req.requestId, error); + } + } + + @Post("/rag-configs/:taskType/health") + @UseGuards(AdminOnlyGuard) + async checkRagTaskConfigHealth( + @Param("taskType") taskTypeRaw: string, + @Body() body: CheckRagTaskConfigHealthDto, + @Req() req: Request + ): Promise> { + try { + const taskType = this.parseTaskType(taskTypeRaw); + const data = await this.settingsService.checkRagTaskConfigHealth(taskType, body, { + requestId: req.requestId, + traceId: req.requestId + }); + return ok(req.requestId, data); + } catch (error) { + return this.toError(req.requestId, error); + } + } + + @Post("/rag-configs/:taskType/models") + @UseGuards(AdminOnlyGuard) + async previewRagProviderModels( + @Param("taskType") taskTypeRaw: string, + @Body() body: PreviewRagProviderModelsDto, + @Req() req: Request + ): Promise> { + try { + const taskType = this.parseTaskType(taskTypeRaw); + const data = await this.settingsService.previewRagProviderModels(taskType, body); + return ok(req.requestId, data); + } catch (error) { + return this.toError(req.requestId, error); + } + } + @Get("/prompts") async listPromptTemplates( @Query() query: ListPromptTemplatesQueryDto, @@ -250,4 +319,13 @@ export class SettingsController { error instanceof Error ? error.message : "未知错误" ); } + + private parseTaskType(value: string): RagTaskType { + if (value === "embedding" || value === "rerank") { + return value; + } + throw new DomainError("RAG_TASK_TYPE_INVALID", "仅支持 embedding/rerank。", 400, { + taskType: value + }); + } } diff --git a/apps/backend/src/modules/governance/settings/settings.service.ts b/apps/backend/src/modules/governance/settings/settings.service.ts index 94f259a..302dccd 100644 --- a/apps/backend/src/modules/governance/settings/settings.service.ts +++ b/apps/backend/src/modules/governance/settings/settings.service.ts @@ -1,17 +1,25 @@ import { Injectable } from "@nestjs/common"; -import type { SettingsActor } from "@text2sql/shared-types"; +import type { LlmProviderCode, SettingsActor } from "@text2sql/shared-types"; import { ProviderCatalogService } from "../../llm/provider-catalog.service"; +import { + type CheckRagTaskConfigHealthContext, + type CheckRagTaskConfigHealthInput, + type UpsertRagTaskConfigInput, + RagTaskConfigService +} from "../../llm/rag-task-config.service"; import { CreateProviderDto } from "./dto/create-provider.dto"; import { CreatePromptTemplateDto } from "./dto/create-prompt-template.dto"; import { ListPromptTemplatesQueryDto } from "./dto/list-prompt-templates.query.dto"; import { UpdatePromptTemplateDto } from "./dto/update-prompt-template.dto"; import { PromptTemplateService } from "./prompt-template.service"; +import type { RagTaskType } from "@text2sql/shared-types"; @Injectable() export class SettingsService { constructor( private readonly providerCatalog: ProviderCatalogService, - private readonly promptTemplateService: PromptTemplateService + private readonly promptTemplateService: PromptTemplateService, + private readonly ragTaskConfigService: RagTaskConfigService ) {} async getSettingsView(actor: SettingsActor) { @@ -22,6 +30,42 @@ export class SettingsService { return this.providerCatalog.listSupportedProviders(); } + async listRagTaskConfigs(actor: SettingsActor) { + return this.ragTaskConfigService.listSettingsView(actor); + } + + async upsertRagTaskConfig( + actor: SettingsActor, + taskType: RagTaskType, + body: UpsertRagTaskConfigInput + ) { + return this.ragTaskConfigService.upsertConfig(taskType, body, actor); + } + + async checkRagTaskConfigHealth( + taskType: RagTaskType, + body: CheckRagTaskConfigHealthInput, + context?: CheckRagTaskConfigHealthContext + ) { + return this.ragTaskConfigService.checkConfigHealth(taskType, body, context); + } + + async previewRagProviderModels( + taskType: RagTaskType, + body: { + provider: LlmProviderCode; + baseUrl?: string; + apiKey: string; + } + ) { + return this.providerCatalog.previewProviderModels({ + taskType, + provider: body.provider, + baseUrl: body.baseUrl, + apiKey: body.apiKey + }); + } + async createProvider(actor: SettingsActor, body: CreateProviderDto) { return this.providerCatalog.createOrUpdateProvider({ actor, diff --git a/apps/backend/src/modules/graph/adapter/graph-acceleration-circuit-breaker.ts b/apps/backend/src/modules/graph/adapter/graph-acceleration-circuit-breaker.ts deleted file mode 100644 index 45f6766..0000000 --- a/apps/backend/src/modules/graph/adapter/graph-acceleration-circuit-breaker.ts +++ /dev/null @@ -1,204 +0,0 @@ -import { Injectable } from "@nestjs/common"; - -type GraphAccelerationBreakerReason = - | "consecutive_failures" - | "timeout_rate" - | "latency_degradation"; - -type GraphAccelerationFailureKind = "error" | "timeout"; - -interface BreakerSample { - timeout: boolean; - latencyDegraded: boolean; -} - -export interface GraphAccelerationBreakerFallback { - reason: string; - source: "forced_postgres_only" | "breaker_open" | "adapter_error"; - openedAt?: string; - openForMs?: number; - recoveryCondition: string; - impactScope: "retrieval_graph_lane"; -} - -@Injectable() -export class GraphAccelerationCircuitBreaker { - private readonly failureThreshold = this.readPositiveInt( - process.env.GRAPH_ACCELERATION_BREAKER_FAILURE_THRESHOLD, - 3 - ); - private readonly openMs = this.readPositiveInt( - process.env.GRAPH_ACCELERATION_BREAKER_OPEN_MS, - 60_000 - ); - private readonly timeoutRateThreshold = this.readRatio( - process.env.GRAPH_ACCELERATION_TIMEOUT_RATE_THRESHOLD, - 0.5 - ); - private readonly timeoutRateWindowSize = this.readPositiveInt( - process.env.GRAPH_ACCELERATION_TIMEOUT_RATE_WINDOW, - 12 - ); - private readonly timeoutRateMinSamples = this.readPositiveInt( - process.env.GRAPH_ACCELERATION_TIMEOUT_RATE_MIN_SAMPLES, - 4 - ); - private readonly latencyDegradeThresholdMs = this.readPositiveInt( - process.env.GRAPH_ACCELERATION_LATENCY_DEGRADE_THRESHOLD_MS, - 450 - ); - private readonly latencyDegradeMinSamples = this.readPositiveInt( - process.env.GRAPH_ACCELERATION_LATENCY_DEGRADE_MIN_SAMPLES, - 3 - ); - private readonly forcedPostgresOnly = - process.env.GRAPH_ACCELERATION_FORCE_POSTGRES_ONLY === "true"; - - private consecutiveFailures = 0; - private readonly recentSamples: BreakerSample[] = []; - private openUntilMs = 0; - private openedAtIso?: string; - private openReason?: GraphAccelerationBreakerReason; - - guard(): { allowed: true } | { allowed: false; fallback: GraphAccelerationBreakerFallback } { - if (this.forcedPostgresOnly) { - return { - allowed: false, - fallback: { - reason: "graph_acceleration_forced_postgres_only", - source: "forced_postgres_only", - recoveryCondition: "set GRAPH_ACCELERATION_FORCE_POSTGRES_ONLY=false", - impactScope: "retrieval_graph_lane" - } - }; - } - - const now = Date.now(); - if (this.openUntilMs > now) { - const openForMs = Math.max(0, this.openUntilMs - now); - return { - allowed: false, - fallback: { - reason: `graph_acceleration_breaker_open_${this.openReason ?? "unknown"}`, - source: "breaker_open", - openedAt: this.openedAtIso, - openForMs, - recoveryCondition: - "wait breaker cooldown window and ensure error/timeout/latency signals recover", - impactScope: "retrieval_graph_lane" - } - }; - } - - if (this.openUntilMs > 0 && this.openUntilMs <= now) { - this.resetOpenState(); - } - - return { allowed: true }; - } - - recordSuccess(): void { - this.consecutiveFailures = 0; - this.pushSample({ - timeout: false, - latencyDegraded: false - }); - } - - recordFailure(kind: GraphAccelerationFailureKind): GraphAccelerationBreakerFallback | undefined { - this.consecutiveFailures += 1; - this.pushSample({ - timeout: kind === "timeout", - latencyDegraded: false - }); - - if (this.consecutiveFailures >= this.failureThreshold) { - return this.open("consecutive_failures"); - } - - if (this.shouldOpenByTimeoutRate()) { - return this.open("timeout_rate"); - } - - return undefined; - } - - recordLatency(elapsedMs: number): GraphAccelerationBreakerFallback | undefined { - const degraded = elapsedMs > this.latencyDegradeThresholdMs; - this.pushSample({ - timeout: false, - latencyDegraded: degraded - }); - if (!degraded) { - return undefined; - } - if (this.shouldOpenByLatencyDegradation()) { - return this.open("latency_degradation"); - } - return undefined; - } - - private shouldOpenByLatencyDegradation(): boolean { - if (this.recentSamples.length < this.latencyDegradeMinSamples) { - return false; - } - return this.recentSamples.every((sample) => sample.latencyDegraded); - } - - private shouldOpenByTimeoutRate(): boolean { - if (this.recentSamples.length < this.timeoutRateMinSamples) { - return false; - } - const timeoutCount = this.recentSamples.filter((sample) => sample.timeout).length; - const timeoutRate = timeoutCount / this.recentSamples.length; - return timeoutRate >= this.timeoutRateThreshold; - } - - private open(reason: GraphAccelerationBreakerReason): GraphAccelerationBreakerFallback { - const now = Date.now(); - this.openUntilMs = now + this.openMs; - this.openedAtIso = new Date(now).toISOString(); - this.openReason = reason; - this.consecutiveFailures = 0; - return { - reason: `graph_acceleration_breaker_open_${reason}`, - source: "breaker_open", - openedAt: this.openedAtIso, - openForMs: this.openMs, - recoveryCondition: - "wait breaker cooldown window and ensure error/timeout/latency signals recover", - impactScope: "retrieval_graph_lane" - }; - } - - private resetOpenState(): void { - this.openUntilMs = 0; - this.openedAtIso = undefined; - this.openReason = undefined; - this.recentSamples.length = 0; - this.consecutiveFailures = 0; - } - - private pushSample(sample: BreakerSample): void { - this.recentSamples.push(sample); - if (this.recentSamples.length > this.timeoutRateWindowSize) { - this.recentSamples.shift(); - } - } - - private readPositiveInt(raw: string | undefined, fallback: number): number { - const parsed = Number(raw); - if (!Number.isFinite(parsed) || parsed <= 0) { - return fallback; - } - return Math.floor(parsed); - } - - private readRatio(raw: string | undefined, fallback: number): number { - const parsed = Number(raw); - if (!Number.isFinite(parsed)) { - return fallback; - } - return Math.max(0, Math.min(1, parsed)); - } -} diff --git a/apps/backend/src/modules/graph/adapter/graph-acceleration.adapter.ts b/apps/backend/src/modules/graph/adapter/graph-acceleration.adapter.ts deleted file mode 100644 index 6165cbe..0000000 --- a/apps/backend/src/modules/graph/adapter/graph-acceleration.adapter.ts +++ /dev/null @@ -1,159 +0,0 @@ -import { Injectable } from "@nestjs/common"; -import type { - RagRetrievalEntryContext, - RagRetrievalLaneHit -} from "../../knowledge/rag/retrieval/rag-retrieval.types"; - -export class GraphAccelerationError extends Error {} - -export class GraphAccelerationTimeoutError extends GraphAccelerationError {} - -export class GraphAccelerationUnsupportedOperatorError extends GraphAccelerationError {} - -export interface GraphAccelerationRunInput { - query: string; - contexts: RagRetrievalEntryContext[]; - limit: number; -} - -@Injectable() -export class GraphAccelerationAdapter { - async execute(input: GraphAccelerationRunInput): Promise { - this.applyForcedFailureMode(); - const delayMs = this.readPositiveInt(process.env.GRAPH_ACCELERATION_SIMULATED_DELAY_MS, 0); - if (delayMs > 0) { - await this.sleep(delayMs); - } - - const normalizedQuery = input.query.toLowerCase(); - if (normalizedQuery.includes("graph:unsupported")) { - throw new GraphAccelerationUnsupportedOperatorError( - "graph acceleration operator unsupported" - ); - } - - const tokens = this.extractTokens(input.query); - const hits: RagRetrievalLaneHit[] = []; - for (const context of input.contexts) { - const evidence: string[] = ["graph:accelerated"]; - let score = 0; - - if (context.entry.domain === "semantic_term") { - score += 0.7; - evidence.push("domain:semantic_term"); - } - if (context.entry.domain === "schema") { - score += 0.2; - evidence.push("domain:schema"); - } - - for (const tableName of context.parsedMetadata.tableNames) { - const normalizedTable = tableName.toLowerCase(); - if (tokens.some((token) => normalizedTable.includes(token) || token.includes(normalizedTable))) { - score += 0.85; - evidence.push(`table:${tableName}`); - } - } - for (const columnName of context.parsedMetadata.columnNames) { - const normalizedColumn = columnName.toLowerCase(); - if ( - tokens.some((token) => normalizedColumn.includes(token) || token.includes(normalizedColumn)) - ) { - score += 0.55; - evidence.push(`column:${columnName}`); - } - } - - if (/\b(join|relationship|foreign|关联|外键)\b/i.test(input.query)) { - score += 0.35; - evidence.push("graph:relationship_hint"); - } - - if (score <= 0) { - continue; - } - - hits.push({ - lane: "graph", - chunk_id: context.entry.chunkId, - score: Number(score.toFixed(12)), - evidence: this.unique(evidence), - chunk: { - chunk_id: context.entry.chunkId, - content: context.entry.lexicalContent, - metadata: { - datasourceId: context.entry.datasourceId, - indexVersionId: context.indexVersionId, - chunkId: context.entry.chunkId, - domain: context.entry.domain, - chunkProfile: - typeof context.parsedMetadata.chunkProfile === "string" - ? context.parsedMetadata.chunkProfile - : undefined, - startOffset: - typeof context.parsedMetadata.startOffset === "number" - ? context.parsedMetadata.startOffset - : undefined, - endOffset: - typeof context.parsedMetadata.endOffset === "number" - ? context.parsedMetadata.endOffset - : undefined, - tableNames: context.parsedMetadata.tableNames, - columnNames: context.parsedMetadata.columnNames, - sourceMetadata: context.parsedMetadata.sourceMetadata - } - } - }); - } - return this.sortHits(hits).slice(0, input.limit); - } - - private applyForcedFailureMode(): void { - const mode = (process.env.GRAPH_ACCELERATION_FORCE_FAILURE ?? "").trim().toLowerCase(); - if (!mode) { - return; - } - if (mode === "timeout") { - throw new GraphAccelerationTimeoutError("forced graph acceleration timeout"); - } - if (mode === "unsupported") { - throw new GraphAccelerationUnsupportedOperatorError("forced unsupported graph operator"); - } - throw new GraphAccelerationError("forced graph acceleration error"); - } - - private sortHits(hits: RagRetrievalLaneHit[]): RagRetrievalLaneHit[] { - return [...hits].sort((left, right) => { - if (right.score !== left.score) { - return right.score - left.score; - } - return left.chunk_id.localeCompare(right.chunk_id); - }); - } - - private extractTokens(query: string): string[] { - const tokens = query - .toLowerCase() - .match(/[a-z0-9_\p{L}\p{N}]+/gu); - if (!tokens) { - return []; - } - return this.unique(tokens.map((item) => item.trim()).filter((item) => item.length > 0)); - } - - private unique(values: string[]): string[] { - return Array.from(new Set(values)); - } - - private readPositiveInt(raw: string | undefined, fallback: number): number { - const parsed = Number(raw); - if (!Number.isFinite(parsed) || parsed <= 0) { - return fallback; - } - return Math.floor(parsed); - } - - private sleep(ms: number): Promise { - return new Promise((resolve) => setTimeout(resolve, ms)); - } -} diff --git a/apps/backend/src/modules/graph/graph.service.ts b/apps/backend/src/modules/graph/graph.service.ts deleted file mode 100644 index cefe72d..0000000 --- a/apps/backend/src/modules/graph/graph.service.ts +++ /dev/null @@ -1,126 +0,0 @@ -import { Injectable, Logger } from "@nestjs/common"; -import { - GraphAccelerationAdapter, - GraphAccelerationError, - GraphAccelerationTimeoutError, - GraphAccelerationUnsupportedOperatorError -} from "./adapter/graph-acceleration.adapter"; -import { - GraphAccelerationCircuitBreaker, - type GraphAccelerationBreakerFallback -} from "./adapter/graph-acceleration-circuit-breaker"; -import type { - RagRetrievalEntryContext, - RagRetrievalLaneHit -} from "../knowledge/rag/retrieval/rag-retrieval.types"; - -export interface GraphLaneExecutionInput { - query: string; - contexts: RagRetrievalEntryContext[]; - limit: number; - fallbackRunner: () => RagRetrievalLaneHit[]; -} - -export interface GraphLaneExecutionResult { - hits: RagRetrievalLaneHit[]; - degradeReason?: string; -} - -@Injectable() -export class GraphService { - private readonly logger = new Logger(GraphService.name); - - constructor( - private readonly accelerationAdapter: GraphAccelerationAdapter, - private readonly breaker: GraphAccelerationCircuitBreaker - ) {} - - async runLane(input: GraphLaneExecutionInput): Promise { - if (!this.isAccelerationEnabled()) { - return { - hits: input.fallbackRunner().slice(0, input.limit) - }; - } - - const breakerGuard = this.breaker.guard(); - if (!breakerGuard.allowed) { - return this.fallback(input, breakerGuard.fallback); - } - - try { - const startedAt = Date.now(); - const hits = await this.accelerationAdapter.execute({ - query: input.query, - contexts: input.contexts, - limit: input.limit - }); - const elapsedMs = Date.now() - startedAt; - const latencyFallback = this.breaker.recordLatency(elapsedMs); - if (latencyFallback) { - this.breaker.recordSuccess(); - return this.fallback(input, latencyFallback); - } - this.breaker.recordSuccess(); - return { - hits - }; - } catch (error) { - const fallbackReason = this.toFallbackReason(error); - const openFallback = this.breaker.recordFailure( - error instanceof GraphAccelerationTimeoutError ? "timeout" : "error" - ); - return this.fallback(input, { - reason: openFallback?.reason ?? fallbackReason, - source: openFallback ? "breaker_open" : "adapter_error", - openedAt: openFallback?.openedAt, - openForMs: openFallback?.openForMs, - recoveryCondition: - openFallback?.recoveryCondition ?? - "fix graph acceleration errors and wait breaker cooldown if opened", - impactScope: "retrieval_graph_lane" - }); - } - } - - private fallback( - input: GraphLaneExecutionInput, - fallback: GraphAccelerationBreakerFallback - ): GraphLaneExecutionResult { - const hits = input.fallbackRunner().slice(0, input.limit); - this.logger.warn( - JSON.stringify({ - event: "graph_acceleration_fallback", - at: new Date().toISOString(), - reason: fallback.reason, - source: fallback.source, - openedAt: fallback.openedAt, - openForMs: fallback.openForMs, - recoveryCondition: fallback.recoveryCondition, - impactScope: fallback.impactScope - }) - ); - return { - hits, - degradeReason: fallback.reason - }; - } - - private isAccelerationEnabled(): boolean { - return process.env.GRAPH_ACCELERATION_ENABLED === "true"; - } - - private toFallbackReason(error: unknown): string { - if (error instanceof GraphAccelerationTimeoutError) { - return "graph_acceleration_timeout_fallback"; - } - if (error instanceof GraphAccelerationUnsupportedOperatorError) { - return "graph_acceleration_unsupported_operator_fallback"; - } - if (error instanceof GraphAccelerationError) { - return "graph_acceleration_error_fallback"; - } - return `graph_acceleration_unknown_fallback:${ - error instanceof Error ? error.message : String(error) - }`; - } -} diff --git a/apps/backend/src/modules/knowledge.ts b/apps/backend/src/modules/knowledge.ts new file mode 100644 index 0000000..f0383d5 --- /dev/null +++ b/apps/backend/src/modules/knowledge.ts @@ -0,0 +1,4 @@ +export { + KNOWLEDGE_FACADE_CONTRACT, + type KnowledgeFacadeContract +} from "./knowledge/contracts/knowledge-facade.contract"; diff --git a/apps/backend/src/modules/knowledge/rag/rag.module.ts b/apps/backend/src/modules/knowledge/rag/rag.module.ts index fa4136c..58983f4 100644 --- a/apps/backend/src/modules/knowledge/rag/rag.module.ts +++ b/apps/backend/src/modules/knowledge/rag/rag.module.ts @@ -26,6 +26,7 @@ import { RagQueryCacheService } from "../../rag/perf/rag-query-cache.service"; import { RagQualityController } from "../../rag/quality/rag-quality.controller"; import { RagQualityService } from "../../rag/quality/rag-quality.service"; import { RagRetrievalService as LegacyRagRetrievalService } from "../../rag/retrieval/rag-retrieval.service"; +import { SemanticAssetReindexService } from "./retrieval/semantic-asset-reindex.service"; import { RagRetrievalService } from "./retrieval/rag-retrieval.service"; import { ModelRerankerAdapter } from "../../rag/rerank/model-reranker.adapter"; import { RagRerankService as LegacyRagRerankService } from "../../rag/rerank/rag-rerank.service"; @@ -96,20 +97,21 @@ export function assertKnowledgeCompatBridgeRetirementReady( RagAuditReplayService, LegacyRagReplayRepository, RagQualityService, - LegacyRagRetrievalService, + RagRetrievalService, + SemanticAssetReindexService, ModelRerankerAdapter, - LegacyRagRerankService, + RagRerankService, { provide: RagReplayRepository, useExisting: LegacyRagReplayRepository }, { - provide: RagRetrievalService, - useExisting: LegacyRagRetrievalService + provide: LegacyRagRetrievalService, + useExisting: RagRetrievalService }, { - provide: RagRerankService, - useExisting: LegacyRagRerankService + provide: LegacyRagRerankService, + useExisting: RagRerankService } ], exports: [ @@ -134,6 +136,7 @@ export function assertKnowledgeCompatBridgeRetirementReady( RagReplayRepository, RagQualityService, LegacyRagRetrievalService, + SemanticAssetReindexService, RagRetrievalService, ModelRerankerAdapter, LegacyRagRerankService, diff --git a/apps/backend/src/modules/knowledge/rag/rerank/rag-rerank.service.ts b/apps/backend/src/modules/knowledge/rag/rerank/rag-rerank.service.ts index ff58b3b..1d1d63b 100644 --- a/apps/backend/src/modules/knowledge/rag/rerank/rag-rerank.service.ts +++ b/apps/backend/src/modules/knowledge/rag/rerank/rag-rerank.service.ts @@ -1,4 +1,6 @@ import { Injectable } from "@nestjs/common"; +import { DomainError } from "../../../../common/domain-error"; +import { AppConfigService } from "../../../config/app-config.service"; import { RagReplayRepository } from "../observability/rag-replay.repository"; import { RagBudgetPolicy } from "../../../rag/perf/rag-budget-policy"; import { RagCacheKeyFactory } from "../../../rag/perf/rag-cache-key.factory"; @@ -6,10 +8,13 @@ import { RagQueryCacheService } from "../../../rag/perf/rag-query-cache.service" import { RagQualityService } from "../../../rag/quality/rag-quality.service"; import { type RagBudgetSignal, + type RagContextPackLaneMetadata, + type RagContextPackPruningDecision, + type RagRerankStageMetadata, type RagRetrievalBundle, type RagRetrievalCandidate, type RagRerankedCandidate -} from "../../../rag/retrieval/rag-retrieval.types"; +} from "../retrieval/rag-retrieval.types"; import { ModelRerankerAdapter } from "../../../rag/rerank/model-reranker.adapter"; export interface RagRerankRequest { @@ -34,6 +39,11 @@ const DEFAULT_SELECTED_CONTEXT_LIMIT = 6; const RERANK_CACHE_L1_TTL_MS = 20_000; const RERANK_CACHE_L2_TTL_MS = 3 * 60_000; +interface SecondaryRerankExecution { + scores: Record; + metadata: RagRerankStageMetadata; +} + @Injectable() export class RagRerankService { constructor( @@ -42,7 +52,8 @@ export class RagRerankService { private readonly budgetPolicy: RagBudgetPolicy, private readonly cacheKeyFactory: RagCacheKeyFactory, private readonly queryCache: RagQueryCacheService, - private readonly ragQualityService: RagQualityService + private readonly ragQualityService: RagQualityService, + private readonly config: AppConfigService ) {} async rerank(input: RagRerankRequest): Promise { @@ -110,50 +121,99 @@ export class RagRerankService { input.secondaryTimeoutMs, DEFAULT_SECONDARY_TIMEOUT_MS ); + const candidateWindow = primary.slice(0, secondaryTopK); + let secondaryMetadata: RagRerankStageMetadata = { + status: "skipped", + timeout_ms: secondaryTimeoutMs, + timeoutMs: secondaryTimeoutMs, + input_count: candidateWindow.length, + inputCount: candidateWindow.length, + output_count: 0, + outputCount: 0 + }; if (!budgetDecision.secondaryEnabled) { - rerankDegradeReasons.push("secondary_rerank_disabled_by_budget"); + const reason = "secondary_rerank_disabled_by_budget"; + rerankDegradeReasons.push(reason); + secondaryMetadata = { + ...secondaryMetadata, + status: "skipped", + fallback_reason: reason, + fallbackReason: reason + }; await this.writeSecondaryReplay(bundle, { status: "skipped", - reason: "secondary_rerank_disabled_by_budget", - timeoutMs: secondaryTimeoutMs + reason, + timeoutMs: secondaryTimeoutMs, + metadata: secondaryMetadata }); } else if (!secondaryEnabled) { - rerankDegradeReasons.push("secondary_rerank_disabled"); + const reason = "secondary_rerank_disabled"; + rerankDegradeReasons.push(reason); + secondaryMetadata = { + ...secondaryMetadata, + status: "skipped", + fallback_reason: reason, + fallbackReason: reason + }; await this.writeSecondaryReplay(bundle, { status: "skipped", - reason: "secondary_rerank_disabled", - timeoutMs: secondaryTimeoutMs + reason, + timeoutMs: secondaryTimeoutMs, + metadata: secondaryMetadata }); } else if (primary.length < secondaryMinCandidates) { - rerankDegradeReasons.push("secondary_rerank_skipped_low_candidates"); + const reason = "secondary_rerank_skipped_low_candidates"; + rerankDegradeReasons.push(reason); + secondaryMetadata = { + ...secondaryMetadata, + status: "skipped", + fallback_reason: reason, + fallbackReason: reason, + evidence_ids: candidateWindow.map((item) => item.chunk_id), + evidenceIds: candidateWindow.map((item) => item.chunk_id) + }; await this.writeSecondaryReplay(bundle, { status: "skipped", - reason: "secondary_rerank_skipped_low_candidates", - timeoutMs: secondaryTimeoutMs + reason, + timeoutMs: secondaryTimeoutMs, + metadata: secondaryMetadata }); } else { try { - secondaryScores = await this.withTimeout( - this.runSecondaryRerank(bundle, primary.slice(0, secondaryTopK), input.modelCatalogId), + const secondary = await this.withTimeout( + this.runSecondaryRerank(bundle, candidateWindow, input.modelCatalogId), secondaryTimeoutMs, "secondary_rerank_timeout" ); + secondaryScores = secondary.scores; + secondaryMetadata = { + ...secondary.metadata, + status: "ok", + timeout_ms: secondaryTimeoutMs, + timeoutMs: secondaryTimeoutMs + }; await this.writeSecondaryReplay(bundle, { status: "ok", timeoutMs: secondaryTimeoutMs, - scores: secondaryScores + scores: secondaryScores, + metadata: secondaryMetadata }); } catch (error) { - const reason = - error instanceof Error && error.message.trim() - ? error.message - : "secondary_rerank_failed"; + const reason = this.resolveSecondaryDegradeReason(error); rerankDegradeReasons.push(reason); + secondaryMetadata = this.toSecondaryMetadataFromError({ + error, + reason, + timeoutMs: secondaryTimeoutMs, + evidenceIds: candidateWindow.map((item) => item.chunk_id), + inputCount: candidateWindow.length + }); await this.writeSecondaryReplay(bundle, { status: "degraded", reason, - timeoutMs: secondaryTimeoutMs + timeoutMs: secondaryTimeoutMs, + metadata: secondaryMetadata }); } } @@ -177,13 +237,43 @@ export class RagRerankService { decision_reasons: this.unique([ ...(bundle.decision_reasons ?? []), ...budgetDecision.decisionReasons - ]) + ]), + rerank_metadata: { + secondary: secondaryMetadata, + secondaryCompat: secondaryMetadata + }, + rerankMetadata: { + secondary: secondaryMetadata, + secondaryCompat: secondaryMetadata + } }; const existingContextPack = bundle.context_pack; + const selectedContextIds = selectedContext.map((chunk) => chunk.chunk_id); + const removedEvidenceIds = reranked + .map((candidate) => candidate.chunk_id) + .filter((chunkId) => !selectedContextIds.includes(chunkId)); + const rerankPruningDecision = this.budgetPolicy.describePruningDecision({ + budgetSource: "rerank_budget", + decisionReasons: this.unique([ + ...budgetDecision.decisionReasons, + secondaryMetadata.fallback_reason ?? "", + secondaryMetadata.unavailable_reason ?? "" + ]), + removedEvidenceIds, + keptEvidenceIds: selectedContextIds + }); + const laneMetadata = this.mergeLaneMetadata({ + existingContextPack, + secondaryMetadata, + selectedContext + }); + const pruningDecisions = this.mergePruningDecisions({ + existingContextPack, + rerankPruningDecision + }); responseBundle.context_pack = { status: responseBundle.status, semantic_version: existingContextPack?.semantic_version, - modeling_revision: existingContextPack?.modeling_revision, semantic_lock_status: responseBundle.status === "ready" ? existingContextPack?.semantic_lock_status ?? "locked" @@ -204,6 +294,12 @@ export class RagRerankService { count: selectedContext.length, snippets: selectedContext.map((chunk) => chunk.content.slice(0, 160)).slice(0, 5) }, + lane_metadata: laneMetadata, + laneMetadata: laneMetadata, + pruning_decisions: pruningDecisions, + pruningDecisions: pruningDecisions, + selected_context_lanes: this.unique(selectedContext.map((chunk) => chunk.metadata.domain)), + selectedContextLanes: this.unique(selectedContext.map((chunk) => chunk.metadata.domain)), degrade_reasons: this.unique([ ...(existingContextPack?.degrade_reasons ?? []), ...degradeReasons @@ -213,6 +309,10 @@ export class RagRerankService { ...(responseBundle.risk_tags ?? []) ]) }; + responseBundle.lane_metadata = laneMetadata; + responseBundle.laneMetadata = laneMetadata; + responseBundle.pruning_decisions = pruningDecisions; + responseBundle.pruningDecisions = pruningDecisions; await this.writeBudgetReplay(responseBundle, { decisionReasons: budgetDecision.decisionReasons, secondaryEnabled: budgetDecision.secondaryEnabled, @@ -269,8 +369,8 @@ export class RagRerankService { bundle: RagRetrievalBundle, candidates: RagRerankedCandidate[], modelCatalogId?: string - ): Promise> { - const response = await this.modelReranker.rerank({ + ): Promise { + const response = await this.modelReranker.rerankWithMetadata({ query: bundle.query, modelCatalogId, candidates: candidates.map((candidate) => ({ @@ -282,8 +382,20 @@ export class RagRerankService { baseScore: candidate.primary_score })) }); + const allowDeterministicMock = this.config.rerankMockMode || this.config.nodeEnv === "test"; + if (response.metadata.mode === "mock" && !allowDeterministicMock) { + throw new DomainError( + "RERANK_TEST_DOUBLE_BLOCKED", + "Rerank mock provider is restricted to tests or explicit rerank mock mode.", + 503, + { + provider: response.metadata.provider, + model: response.metadata.model + } + ); + } const scoreMap: Record = {}; - for (const item of response) { + for (const item of response.results) { if (!Number.isFinite(item.score)) { continue; } @@ -292,7 +404,107 @@ export class RagRerankService { reason: item.reason }; } - return scoreMap; + const evidenceIds = candidates.map((candidate) => candidate.chunk_id); + const metadata: RagRerankStageMetadata = { + status: "ok", + mode: response.metadata.mode, + provider: response.metadata.provider, + model: response.metadata.model, + config_source: response.metadata.configSource, + configSource: response.metadata.configSource, + config_id: response.metadata.configId, + configId: response.metadata.configId, + input_count: response.metadata.inputCount, + inputCount: response.metadata.inputCount, + output_count: Object.keys(scoreMap).length, + outputCount: Object.keys(scoreMap).length, + fallback_reason: response.metadata.fallbackReason, + fallbackReason: response.metadata.fallbackReason, + unavailable_reason: response.metadata.unavailableReason, + unavailableReason: response.metadata.unavailableReason, + evidence_ids: evidenceIds, + evidenceIds + }; + return { + scores: scoreMap, + metadata + }; + } + + private mergeLaneMetadata(input: { + existingContextPack: RagRetrievalBundle["context_pack"] | undefined; + secondaryMetadata: RagRerankStageMetadata; + selectedContext: NonNullable; + }): RagContextPackLaneMetadata[] { + const existing = [ + ...(input.existingContextPack?.lane_metadata ?? input.existingContextPack?.laneMetadata ?? []) + ]; + const withoutRerank = existing.filter((item) => item.lane !== "rerank"); + const state: RagContextPackLaneMetadata["state"] = + input.secondaryMetadata.status === "ok" + ? "ready" + : input.secondaryMetadata.unavailable_reason + ? "unavailable" + : input.secondaryMetadata.status; + const rerankLane: RagContextPackLaneMetadata = { + lane: "rerank", + state, + provider: input.secondaryMetadata.provider, + model: input.secondaryMetadata.model, + input_count: input.secondaryMetadata.input_count, + inputCount: input.secondaryMetadata.inputCount, + output_count: input.secondaryMetadata.output_count, + outputCount: input.secondaryMetadata.outputCount, + selected_count: input.selectedContext.length, + selectedCount: input.selectedContext.length, + timeout_ms: input.secondaryMetadata.timeout_ms, + timeoutMs: input.secondaryMetadata.timeoutMs, + unavailable_reason: input.secondaryMetadata.unavailable_reason, + unavailableReason: input.secondaryMetadata.unavailableReason, + fallback_reason: input.secondaryMetadata.fallback_reason, + fallbackReason: input.secondaryMetadata.fallbackReason, + evidence_ids: input.secondaryMetadata.evidence_ids, + evidenceIds: input.secondaryMetadata.evidenceIds, + reason_codes: this.unique([ + input.secondaryMetadata.fallback_reason ?? "", + input.secondaryMetadata.unavailable_reason ?? "" + ]), + reasonCodes: this.unique([ + input.secondaryMetadata.fallbackReason ?? "", + input.secondaryMetadata.unavailableReason ?? "" + ]) + }; + return [...withoutRerank, rerankLane]; + } + + private mergePruningDecisions(input: { + existingContextPack: RagRetrievalBundle["context_pack"] | undefined; + rerankPruningDecision: + | ReturnType + | undefined; + }): RagContextPackPruningDecision[] { + const existing = [ + ...(input.existingContextPack?.pruning_decisions ?? + input.existingContextPack?.pruningDecisions ?? + []) + ].filter((decision) => decision.budget_source !== "rerank_budget"); + if (!input.rerankPruningDecision) { + return existing; + } + return [ + ...existing, + { + budget_source: input.rerankPruningDecision.budget_source, + removed_evidence_ids: input.rerankPruningDecision.removed_evidence_ids, + kept_evidence_ids: input.rerankPruningDecision.kept_evidence_ids, + reason_codes: input.rerankPruningDecision.reason_codes, + summary: input.rerankPruningDecision.summary, + budgetSource: input.rerankPruningDecision.budgetSource, + removedEvidenceIds: input.rerankPruningDecision.removedEvidenceIds, + keptEvidenceIds: input.rerankPruningDecision.keptEvidenceIds, + reasonCodes: input.rerankPruningDecision.reasonCodes + } + ]; } private mergePrimaryWithSecondary( @@ -399,6 +611,7 @@ export class RagRerankService { reason?: string; timeoutMs: number; scores?: Record; + metadata?: RagRerankStageMetadata; } ): Promise { await this.replayRepository.writeReplay({ @@ -411,7 +624,8 @@ export class RagRerankService { status: input.status, reason: input.reason, timeoutMs: input.timeoutMs, - scores: input.scores + scores: input.scores, + metadata: input.metadata } }); } @@ -430,6 +644,7 @@ export class RagRerankService { rerankedCount: bundle.reranked?.length ?? 0, selectedContextCount: bundle.selected_context?.length ?? 0, riskTags: bundle.risk_tags ?? [], + rerankMetadata: bundle.rerank_metadata ?? bundle.rerankMetadata, columnPruning: this.readColumnPruningEvidence(bundle), contextPack: bundle.context_pack ? { @@ -446,7 +661,13 @@ export class RagRerankService { calculatedFieldBindingCount: bundle.context_pack.instruction_sets.calculated_field_bindings.length }, - degradeReasons: bundle.context_pack.degrade_reasons + degradeReasons: bundle.context_pack.degrade_reasons, + laneMetadata: + bundle.context_pack.lane_metadata ?? bundle.context_pack.laneMetadata ?? [], + pruningDecisions: + bundle.context_pack.pruning_decisions ?? + bundle.context_pack.pruningDecisions ?? + [] } : undefined } @@ -486,6 +707,81 @@ export class RagRerankService { return this.isRecord(candidate) ? candidate : undefined; } + private resolveSecondaryDegradeReason(error: unknown): string { + if (error instanceof Error && error.message === "secondary_rerank_timeout") { + return "secondary_rerank_timeout"; + } + const code = this.readErrorCode(error); + if (code === "LLM_CONFIG_MISSING") { + return "secondary_rerank_unavailable_provider_config_missing"; + } + if (code === "RERANK_PROVIDER_INVALID_PAYLOAD") { + return "secondary_rerank_unavailable_invalid_payload"; + } + if (typeof code === "string" && code.trim().length > 0) { + return `secondary_rerank_unavailable_${code.toLowerCase()}`; + } + if (error instanceof Error && error.message.trim()) { + return `secondary_rerank_unavailable_${error.message + .toLowerCase() + .replace(/\s+/g, "_") + .slice(0, 64)}`; + } + return "secondary_rerank_unavailable_unknown"; + } + + private toSecondaryMetadataFromError(input: { + error: unknown; + reason: string; + timeoutMs: number; + evidenceIds: string[]; + inputCount: number; + }): RagRerankStageMetadata { + const details = this.readErrorDetails(input.error); + const provider = this.readString(details?.provider); + const model = this.readString(details?.model); + return { + status: "degraded", + provider, + model, + timeout_ms: input.timeoutMs, + timeoutMs: input.timeoutMs, + input_count: input.inputCount, + inputCount: input.inputCount, + output_count: 0, + outputCount: 0, + unavailable_reason: input.reason, + unavailableReason: input.reason, + evidence_ids: input.evidenceIds, + evidenceIds: input.evidenceIds + }; + } + + private readErrorCode(error: unknown): string | undefined { + if (!this.isRecord(error)) { + return undefined; + } + return this.readString(error.code); + } + + private readErrorDetails(error: unknown): Record | undefined { + if (!this.isRecord(error)) { + return undefined; + } + if (!this.isRecord(error.details)) { + return undefined; + } + return error.details; + } + + private readString(value: unknown): string | undefined { + if (typeof value !== "string") { + return undefined; + } + const normalized = value.trim(); + return normalized.length > 0 ? normalized : undefined; + } + private isRecord(value: unknown): value is Record { return typeof value === "object" && value !== null && !Array.isArray(value); } diff --git a/apps/backend/src/modules/knowledge/rag/retrieval/rag-retrieval.service.ts b/apps/backend/src/modules/knowledge/rag/retrieval/rag-retrieval.service.ts index e1471c8..1d15810 100644 --- a/apps/backend/src/modules/knowledge/rag/retrieval/rag-retrieval.service.ts +++ b/apps/backend/src/modules/knowledge/rag/retrieval/rag-retrieval.service.ts @@ -1,5 +1,7 @@ import { createHash } from "node:crypto"; import { Injectable } from "@nestjs/common"; +import { DomainError } from "../../../../common/domain-error"; +import { EmbeddingRouterService } from "../../../llm/embedding-router.service"; import { GraphService } from "../../graph/graph.service"; import { SKILL_REGISTRY_UNAVAILABLE_REASON, @@ -15,7 +17,10 @@ import { ModelingGraphRepository } from "../../../platform/data/persistence/mode import { fuseWithRrf } from "../../../rag/retrieval/fusion/rrf-fusion"; import { RAG_RETRIEVAL_LANES, + type RagContextPackLaneMetadata, + type RagContextPackPruningDecision, type RagPriorSqlLaneEvidence, + type RagPriorSqlShortcutDecision, type RagRetrievalCandidate, type RagRetrievalChunkMetadata, type RagRetrievalChunkPayload, @@ -27,7 +32,7 @@ import { type RagRetrievalResponse, type RagContextPack, type RagSkillContext -} from "../../../rag/retrieval/rag-retrieval.types"; +} from "./rag-retrieval.types"; const DEFAULT_PER_LANE_LIMIT = 20; const DEFAULT_FINAL_CANDIDATE_LIMIT = 20; @@ -40,7 +45,6 @@ const DEFAULT_LANE_TIMEOUT_MS: Record = { }; const REQUIRED_DOMAIN_COVERAGE = ["schema", "sql_example", "semantic_term"]; const SEMANTIC_PROMOTED_DEGRADED_REASON = "semantic_promoted_linkage_degraded"; -const MODELING_REVISION_MISSING_RISK_TAG = "modeling_revision_missing"; class LaneTimeoutError extends Error { constructor(public readonly lane: RagRetrievalLane) { @@ -85,12 +89,41 @@ interface ColumnPruningResult { evidence?: ColumnPruningEvidence; } +interface PermissionFilteringEvidence { + status: "applied" | "skipped"; + denied_evidence_ids: string[]; + denied_table_names: string[]; + denied_column_names: string[]; + reason_codes: string[]; + kept_candidate_count: number; + deniedEvidenceIds?: string[]; + deniedTableNames?: string[]; + deniedColumnNames?: string[]; + reasonCodes?: string[]; + keptCandidateCount?: number; +} + +interface PermissionFilteringResult { + candidates: RagRetrievalCandidate[]; + evidence: PermissionFilteringEvidence; +} + interface WideTableProfile { tableName: string; normalizedTableName: string; columns: string[]; } +interface DenseVectorMetadata { + provider?: string; + model?: string; + dimensions?: number; + vectorVersion?: string; + indexVersion?: string; + scope?: string; + assetType?: string; +} + interface TablePruningPlan { tableName: string; normalizedTableName: string; @@ -109,6 +142,7 @@ export class RagRetrievalService { constructor( private readonly indexRepository: RagIndexRepository, private readonly replayRepository: RagReplayRepository, + private readonly embeddingRouter: EmbeddingRouterService, private readonly skillRegistry: SkillRegistryService, private readonly graphService: GraphService, private readonly cacheKeyFactory: RagCacheKeyFactory, @@ -249,11 +283,16 @@ export class RagRetrievalService { graph: laneResults.graph.hits }; const fused = fuseWithRrf({ laneHits }); + const activeModelingRevision = await this.resolveActiveModelingRevision( + workspaceId, + datasourceId + ); const priorSqlSelection = this.selectTrustedPriorSqlCandidates({ candidates: fused, datasourceId, workspaceId, - allowedTables + allowedTables, + activeModelingRevision }); const priorSqlFiltered = this.filterBlockedPriorSqlCandidates( fused, @@ -273,11 +312,16 @@ export class RagRetrievalService { query, candidates: decoratedCandidates }); - const candidates = columnPruning.candidates; + const permissionFiltering = this.applyPermissionFiltering({ + candidates: columnPruning.candidates, + allowedTables + }); + const candidates = permissionFiltering.candidates; const skillContext = await this.resolveSkillContext(query, candidates); const degradeReasons = this.collectDegradeReasons(laneResults); degradeReasons.push(...this.collectSemanticLinkageDegradeReasons(candidates)); + degradeReasons.push(...permissionFiltering.evidence.reason_codes); if (skillContext.degrade_reason) { degradeReasons.push(skillContext.degrade_reason); } @@ -306,6 +350,10 @@ export class RagRetrievalService { } }; this.attachColumnPruningEvidence(response.retrieval_bundle, columnPruning.evidence); + this.attachPermissionFilteringEvidence( + response.retrieval_bundle, + permissionFiltering.evidence + ); response.retrieval_bundle.context_pack = await this.buildContextPack({ bundle: response.retrieval_bundle, workspaceId, @@ -313,6 +361,20 @@ export class RagRetrievalService { status: response.retrieval_bundle.status, degradeReasons: uniqueDegradeReasons }); + const laneMetadata = + response.retrieval_bundle.context_pack?.lane_metadata ?? + response.retrieval_bundle.context_pack?.laneMetadata; + const pruningDecisions = + response.retrieval_bundle.context_pack?.pruning_decisions ?? + response.retrieval_bundle.context_pack?.pruningDecisions; + if (laneMetadata && laneMetadata.length > 0) { + response.retrieval_bundle.lane_metadata = laneMetadata; + response.retrieval_bundle.laneMetadata = laneMetadata; + } + if (pruningDecisions && pruningDecisions.length > 0) { + response.retrieval_bundle.pruning_decisions = pruningDecisions; + response.retrieval_bundle.pruningDecisions = pruningDecisions; + } this.queryCache.set({ key: cacheKey, @@ -342,6 +404,7 @@ export class RagRetrievalService { }): Promise { const priorSqlLane = this.readPriorSqlLaneEvidence(input.cachedBundle); const columnPruning = this.readColumnPruningEvidence(input.cachedBundle); + const permissionFiltering = this.readPermissionFilteringEvidence(input.cachedBundle); const hydratedBundle: RagRetrievalResponse["retrieval_bundle"] = { ...input.cachedBundle, query: input.query, @@ -360,6 +423,7 @@ export class RagRetrievalService { ]) }; this.attachColumnPruningEvidence(hydratedBundle, columnPruning); + this.attachPermissionFilteringEvidence(hydratedBundle, permissionFiltering); hydratedBundle.context_pack = await this.buildContextPack({ bundle: hydratedBundle, workspaceId: input.workspaceId, @@ -367,6 +431,19 @@ export class RagRetrievalService { status: hydratedBundle.status, degradeReasons: hydratedBundle.degrade_reasons }); + const laneMetadata = + hydratedBundle.context_pack?.lane_metadata ?? hydratedBundle.context_pack?.laneMetadata; + const pruningDecisions = + hydratedBundle.context_pack?.pruning_decisions ?? + hydratedBundle.context_pack?.pruningDecisions; + if (laneMetadata && laneMetadata.length > 0) { + hydratedBundle.lane_metadata = laneMetadata; + hydratedBundle.laneMetadata = laneMetadata; + } + if (pruningDecisions && pruningDecisions.length > 0) { + hydratedBundle.pruning_decisions = pruningDecisions; + hydratedBundle.pruningDecisions = pruningDecisions; + } return hydratedBundle; } @@ -518,16 +595,61 @@ export class RagRetrievalService { return this.sortHits(hits).slice(0, limit); } - private runDenseLane( + private async runDenseLane( query: string, contexts: RagRetrievalEntryContext[], limit: number - ): RagRetrievalLaneHit[] { - const queryVector = this.buildDenseVector(query); + ): Promise { + if (contexts.length === 0) { + return { + hits: [] + }; + } + + let queryVector: number[]; + let queryMetadata: DenseVectorMetadata | undefined; + try { + const embeddings = await this.embeddingRouter.embed({ + texts: [query], + indexVersion: contexts[0]?.indexVersionId, + scope: "retrieval_query", + assetType: "query" + }); + queryVector = embeddings[0]?.vector ?? []; + queryMetadata = embeddings[0] + ? this.toDenseVectorMetadata(embeddings[0].metadata) + : undefined; + } catch (error) { + return { + hits: [], + degradeReason: this.resolveDenseUnavailableReason(error) + }; + } + + if (!queryVector || queryVector.length === 0) { + return { + hits: [], + degradeReason: "dense_unavailable_empty_query_vector" + }; + } + const hits: RagRetrievalLaneHit[] = []; + let incompatibleVectorSpaceDetected = false; for (const context of contexts) { const vector = this.parseDenseVector(context.entry.denseVector); - if (!vector || vector.length === 0 || vector.length !== queryVector.length) { + if (!vector || vector.length === 0) { + continue; + } + const candidateDenseMetadata = this.readDenseVectorMetadata(context); + if ( + vector.length !== queryVector.length || + !this.isDenseVectorSpaceCompatible({ + queryMetadata, + candidateMetadata: candidateDenseMetadata, + indexVersionId: context.indexVersionId + }) + ) { + incompatibleVectorSpaceDetected = true; continue; } const cosine = this.cosineSimilarity(queryVector, vector); @@ -538,11 +660,27 @@ export class RagRetrievalService { lane: "dense", chunk_id: context.entry.chunkId, score: Number(cosine.toFixed(12)), - evidence: [`cosine:${cosine.toFixed(6)}`], + evidence: this.unique([ + `cosine:${cosine.toFixed(6)}`, + ...(candidateDenseMetadata?.provider + ? [`dense_provider:${candidateDenseMetadata.provider}`] + : []), + ...(candidateDenseMetadata?.model + ? [`dense_model:${candidateDenseMetadata.model}`] + : []) + ]), chunk: this.toChunkPayload(context) }); } - return this.sortHits(hits).slice(0, limit); + if (incompatibleVectorSpaceDetected) { + return { + hits: [], + degradeReason: "dense_unavailable_incompatible_vector_space" + }; + } + return { + hits: this.sortHits(hits).slice(0, limit) + }; } private async runGraphLane( @@ -656,7 +794,8 @@ export class RagRetrievalService { this.readString(parsed.chunkProfile) ?? this.readString(sourceMetadata.chunkProfile), startOffset: this.readNumber(parsed.startOffset) ?? this.readNumber(sourceMetadata.startOffset), - endOffset: this.readNumber(parsed.endOffset) ?? this.readNumber(sourceMetadata.endOffset) + endOffset: this.readNumber(parsed.endOffset) ?? this.readNumber(sourceMetadata.endOffset), + denseMetadata: this.readDenseVectorMetadataFromParsed(parsed, sourceMetadata) } }; } @@ -674,7 +813,14 @@ export class RagRetrievalService { columnNames: this.readStringArray(context.parsedMetadata.columnNames), sourceMetadata: this.isRecord(context.parsedMetadata.sourceMetadata) ? context.parsedMetadata.sourceMetadata - : {} + : {}, + denseProvider: context.parsedMetadata.denseMetadata?.provider, + denseModel: context.parsedMetadata.denseMetadata?.model, + denseDimensions: context.parsedMetadata.denseMetadata?.dimensions, + vectorVersion: context.parsedMetadata.denseMetadata?.vectorVersion, + indexVersion: context.parsedMetadata.denseMetadata?.indexVersion, + scope: context.parsedMetadata.denseMetadata?.scope, + assetType: context.parsedMetadata.denseMetadata?.assetType }; return { @@ -714,15 +860,18 @@ export class RagRetrievalService { datasourceId: string; workspaceId?: string; allowedTables: string[]; + activeModelingRevision?: number; }): PriorSqlSelectionResult { const trustedSqlExampleCandidates = input.candidates.filter( (candidate) => candidate.chunk.metadata.domain === "sql_example" && this.isTrustedPriorSqlCandidate(candidate) ); - const selectedCandidates: RagRetrievalCandidate[] = []; + const eligibleCandidates: RagRetrievalCandidate[] = []; const blockedChunkIds = new Set(); - const degradeReasons: string[] = []; + const filteredReasons: string[] = []; + const staleReasons: string[] = []; + let staleCandidateCount = 0; const allowedTables = new Set(input.allowedTables); const workspaceId = input.workspaceId?.trim(); @@ -735,47 +884,102 @@ export class RagRetrievalService { }); if (filterReasons.length > 0) { blockedChunkIds.add(candidate.chunk_id); - degradeReasons.push(...filterReasons); + filteredReasons.push(...filterReasons); + continue; + } + + const candidateStaleReasons = this.collectPriorSqlStaleReasons({ + candidate, + activeModelingRevision: input.activeModelingRevision + }); + if (candidateStaleReasons.length > 0) { + staleCandidateCount += 1; + staleReasons.push(...candidateStaleReasons); continue; } - selectedCandidates.push({ + eligibleCandidates.push({ ...candidate, evidence: this.unique([...candidate.evidence, "prior_sql:trusted"]) }); } - if (selectedCandidates.length > 0) { - const lane: RagPriorSqlLaneEvidence = { - status: "hit", + const selectedCandidates = + eligibleCandidates.length === 1 ? [eligibleCandidates[0]] : []; + const shortcutStatus: RagPriorSqlShortcutDecision["status"] = + selectedCandidates.length === 1 + ? "hit" + : eligibleCandidates.length > 1 + ? "ambiguous" + : blockedChunkIds.size > 0 + ? "filtered" + : staleCandidateCount > 0 + ? "stale" + : "miss"; + const selectedCandidate = selectedCandidates[0]; + const shortcutReasons = this.unique([ + ...(shortcutStatus === "hit" + ? ["prior_sql_shortcut_hit"] + : []), + ...(shortcutStatus === "miss" + ? ["prior_sql_no_trusted_match"] + : []), + ...(shortcutStatus === "filtered" + ? ["prior_sql_shortcut_filtered", ...filteredReasons] + : []), + ...(shortcutStatus === "stale" + ? ["prior_sql_shortcut_stale", ...staleReasons] + : []), + ...(shortcutStatus === "ambiguous" + ? ["prior_sql_shortcut_ambiguous"] + : []) + ]); + const laneDegradeReasons = this.unique([ + ...filteredReasons, + ...staleReasons, + ...(shortcutStatus === "miss" ? ["prior_sql_no_trusted_match"] : []), + ...(shortcutStatus === "ambiguous" ? ["prior_sql_shortcut_ambiguous"] : []), + ...(shortcutStatus === "filtered" ? ["prior_sql_shortcut_filtered"] : []), + ...(shortcutStatus === "stale" ? ["prior_sql_shortcut_stale"] : []) + ]); + const shortcutDecision: RagPriorSqlShortcutDecision = + this.withPriorSqlShortcutCompatFields({ + status: shortcutStatus, + reason_codes: shortcutReasons, matched_count: trustedSqlExampleCandidates.length, - selected_count: selectedCandidates.length, + eligible_count: eligibleCandidates.length, filtered_count: blockedChunkIds.size, - ...(degradeReasons.length > 0 + stale_count: staleCandidateCount, + ambiguous_count: shortcutStatus === "ambiguous" ? eligibleCandidates.length : 0, + ...(selectedCandidate ? { - degrade_reasons: this.unique(degradeReasons) + selected_chunk_id: selectedCandidate.chunk_id, + selected_view_id: this.readPriorSqlViewId( + selectedCandidate.chunk.metadata.sourceMetadata + ), + selected_source_run_id: this.readPriorSqlSourceRunId( + selectedCandidate.chunk.metadata.sourceMetadata + ) } : {}) - }; - return { - lane: this.withPriorSqlLaneCompatFields(lane), - selectedCandidates, - blockedChunkIds - }; - } - + }); const lane: RagPriorSqlLaneEvidence = { - status: trustedSqlExampleCandidates.length > 0 ? "filtered" : "miss", + status: shortcutStatus, matched_count: trustedSqlExampleCandidates.length, - selected_count: 0, + selected_count: selectedCandidates.length, filtered_count: blockedChunkIds.size, - degrade_reasons: - trustedSqlExampleCandidates.length > 0 - ? this.unique(degradeReasons) - : ["prior_sql_no_trusted_match"] + stale_count: staleCandidateCount, + ambiguous_count: shortcutStatus === "ambiguous" ? eligibleCandidates.length : 0, + eligible_count: eligibleCandidates.length, + ...(laneDegradeReasons.length > 0 + ? { + degrade_reasons: laneDegradeReasons + } + : {}), + shortcut: shortcutDecision }; return { lane: this.withPriorSqlLaneCompatFields(lane), - selectedCandidates: [], + selectedCandidates, blockedChunkIds }; } @@ -837,6 +1041,85 @@ export class RagRetrievalService { return reasons; } + private collectPriorSqlStaleReasons(input: { + candidate: RagRetrievalCandidate; + activeModelingRevision?: number; + }): string[] { + const sourceMetadata = input.candidate.chunk.metadata.sourceMetadata; + if (!this.isRecord(sourceMetadata)) { + return []; + } + const reasons: string[] = []; + if ( + this.readBooleanFlag(sourceMetadata.stale) || + this.readBooleanFlag(sourceMetadata.isStale) || + this.readBooleanFlag(sourceMetadata.priorSqlStale) || + this.readBooleanFlag(sourceMetadata.prior_sql_stale) + ) { + reasons.push("prior_sql_stale_marked"); + } + const viewDeleted = + this.readBooleanFlag(sourceMetadata.viewDeleted) || + this.readBooleanFlag(sourceMetadata.view_deleted); + const viewExists = this.readOptionalBoolean( + sourceMetadata.viewExists ?? sourceMetadata.view_exists + ); + if (viewDeleted || viewExists === false) { + reasons.push("prior_sql_stale_view_missing"); + } + const viewStatus = this.readString(sourceMetadata.viewStatus) ?? + this.readString(sourceMetadata.view_status); + if (viewStatus) { + const normalized = viewStatus.trim().toLowerCase(); + if ( + normalized === "missing" || + normalized === "deleted" || + normalized === "not_found" || + normalized === "archived" || + normalized === "inactive" || + normalized === "stale" + ) { + reasons.push("prior_sql_stale_view_status"); + } + } + + const sourceModelingRevision = this.readPositiveInteger( + sourceMetadata.modelingRevision ?? sourceMetadata.modeling_revision + ); + const currentModelingRevision = this.readPositiveInteger( + sourceMetadata.currentModelingRevision ?? sourceMetadata.current_modeling_revision + ); + if ( + sourceModelingRevision !== undefined && + currentModelingRevision !== undefined && + sourceModelingRevision !== currentModelingRevision + ) { + reasons.push("prior_sql_stale_modeling_revision_mismatch"); + } + if ( + sourceModelingRevision !== undefined && + input.activeModelingRevision !== undefined && + sourceModelingRevision !== input.activeModelingRevision + ) { + reasons.push("prior_sql_stale_modeling_revision_mismatch"); + } + + const sourceSchemaRevision = this.readPositiveInteger( + sourceMetadata.schemaRevision ?? sourceMetadata.schema_revision + ); + const currentSchemaRevision = this.readPositiveInteger( + sourceMetadata.currentSchemaRevision ?? sourceMetadata.current_schema_revision + ); + if ( + sourceSchemaRevision !== undefined && + currentSchemaRevision !== undefined && + sourceSchemaRevision !== currentSchemaRevision + ) { + reasons.push("prior_sql_stale_schema_revision_mismatch"); + } + return this.unique(reasons); + } + private readWorkspaceIdFromSourceMetadata(sourceMetadata: unknown): string | undefined { if (!this.isRecord(sourceMetadata)) { return undefined; @@ -844,6 +1127,21 @@ export class RagRetrievalService { return this.readString(sourceMetadata.workspaceId) ?? this.readString(sourceMetadata.workspace_id); } + private readPriorSqlViewId(sourceMetadata: unknown): string | undefined { + if (!this.isRecord(sourceMetadata)) { + return undefined; + } + return this.readString(sourceMetadata.viewId) ?? this.readString(sourceMetadata.view_id); + } + + private readPriorSqlSourceRunId(sourceMetadata: unknown): string | undefined { + if (!this.isRecord(sourceMetadata)) { + return undefined; + } + return this.readString(sourceMetadata.sourceRunId) ?? + this.readString(sourceMetadata.source_run_id); + } + private filterBlockedPriorSqlCandidates( candidates: RagRetrievalCandidate[], blockedChunkIds: Set @@ -918,6 +1216,78 @@ export class RagRetrievalService { return selected.slice(0, limit); } + private applyPermissionFiltering(input: { + candidates: RagRetrievalCandidate[]; + allowedTables: string[]; + }): PermissionFilteringResult { + if (input.allowedTables.length === 0) { + return { + candidates: input.candidates, + evidence: { + status: "skipped", + denied_evidence_ids: [], + denied_table_names: [], + denied_column_names: [], + reason_codes: [], + kept_candidate_count: input.candidates.length, + deniedEvidenceIds: [], + deniedTableNames: [], + deniedColumnNames: [], + reasonCodes: [], + keptCandidateCount: input.candidates.length + } + }; + } + + const allowedTableSet = new Set(input.allowedTables.map((table) => table.trim().toLowerCase())); + const deniedEvidenceIds: string[] = []; + const deniedTableNames: string[] = []; + const deniedColumnNames: string[] = []; + const keptCandidates: RagRetrievalCandidate[] = []; + + for (const candidate of input.candidates) { + const tableNames = candidate.chunk.metadata.tableNames + .map((tableName) => tableName.trim().toLowerCase()) + .filter((tableName) => tableName.length > 0); + if (tableNames.length === 0) { + keptCandidates.push(candidate); + continue; + } + const deniedTables = tableNames.filter((tableName) => !allowedTableSet.has(tableName)); + if (deniedTables.length === 0) { + keptCandidates.push(candidate); + continue; + } + deniedEvidenceIds.push(candidate.chunk_id); + deniedTableNames.push(...deniedTables); + deniedColumnNames.push(...candidate.chunk.metadata.columnNames); + } + + const uniqueDeniedEvidenceIds = this.unique(deniedEvidenceIds).slice(0, 128); + const uniqueDeniedTableNames = this.unique(deniedTableNames).slice(0, 64); + const uniqueDeniedColumnNames = this.unique(deniedColumnNames).slice(0, 128); + const reasonCodes = + uniqueDeniedEvidenceIds.length > 0 + ? ["permission_filtered_not_in_allowed_tables"] + : []; + return { + candidates: keptCandidates, + evidence: { + status: uniqueDeniedEvidenceIds.length > 0 ? "applied" : "skipped", + denied_evidence_ids: uniqueDeniedEvidenceIds, + denied_table_names: uniqueDeniedTableNames, + denied_column_names: uniqueDeniedColumnNames, + reason_codes: reasonCodes, + kept_candidate_count: keptCandidates.length, + deniedEvidenceIds: uniqueDeniedEvidenceIds, + deniedTableNames: uniqueDeniedTableNames, + deniedColumnNames: uniqueDeniedColumnNames, + reasonCodes: reasonCodes, + keptCandidateCount: keptCandidates.length + } + }; + } + private createEmptyLaneResults( laneTimeoutMs: Record, degradeReason: string @@ -1386,16 +1756,6 @@ export class RagRetrievalService { } } - private buildDenseVector(input: string): number[] { - const digest = createHash("sha256").update(input).digest(); - const dimensions = 8; - return Array.from({ length: dimensions }, (_, index) => { - const byte = digest[index] ?? 0; - const normalized = byte / 255; - return Number((normalized * 2 - 1).toFixed(6)); - }); - } - private cosineSimilarity(left: number[], right: number[]): number { let dot = 0; let leftNorm = 0; @@ -1463,6 +1823,144 @@ export class RagRetrievalService { return source.column_pruning ?? source.columnPruning; } + private attachPermissionFilteringEvidence( + bundle: RagRetrievalResponse["retrieval_bundle"], + evidence: PermissionFilteringEvidence | undefined + ): void { + const target = bundle as RagRetrievalResponse["retrieval_bundle"] & { + permission_filtering?: PermissionFilteringEvidence; + permissionFiltering?: PermissionFilteringEvidence; + }; + if (!evidence) { + delete target.permission_filtering; + delete target.permissionFiltering; + return; + } + target.permission_filtering = evidence; + target.permissionFiltering = evidence; + } + + private readPermissionFilteringEvidence( + bundle: RagRetrievalResponse["retrieval_bundle"] + ): PermissionFilteringEvidence | undefined { + const source = bundle as RagRetrievalResponse["retrieval_bundle"] & { + permission_filtering?: PermissionFilteringEvidence; + permissionFiltering?: PermissionFilteringEvidence; + }; + return source.permission_filtering ?? source.permissionFiltering; + } + + private readDenseVectorMetadata( + context: RagRetrievalEntryContext + ): DenseVectorMetadata | undefined { + return context.parsedMetadata.denseMetadata as DenseVectorMetadata | undefined; + } + + private readDenseVectorMetadataFromParsed( + parsed: Record, + sourceMetadata: Record + ): DenseVectorMetadata | undefined { + const denseRaw = this.isRecord(parsed.dense) + ? parsed.dense + : this.isRecord(sourceMetadata.dense) + ? sourceMetadata.dense + : undefined; + if (!denseRaw) { + return undefined; + } + return { + provider: this.readString(denseRaw.provider), + model: this.readString(denseRaw.model), + dimensions: this.readNumber(denseRaw.dimensions), + vectorVersion: this.readString(denseRaw.vectorVersion), + indexVersion: this.readString(denseRaw.indexVersion), + scope: this.readString(denseRaw.scope), + assetType: this.readString(denseRaw.assetType) + }; + } + + private toDenseVectorMetadata(metadata: { + provider: string; + model: string; + dimensions: number; + vectorVersion: string; + indexVersion?: string; + scope?: string; + assetType?: string; + }): DenseVectorMetadata { + return { + provider: metadata.provider, + model: metadata.model, + dimensions: metadata.dimensions, + vectorVersion: metadata.vectorVersion, + indexVersion: metadata.indexVersion, + scope: metadata.scope, + assetType: metadata.assetType + }; + } + + private isDenseVectorSpaceCompatible(input: { + queryMetadata?: DenseVectorMetadata; + candidateMetadata?: DenseVectorMetadata; + indexVersionId: string; + }): boolean { + const { queryMetadata, candidateMetadata, indexVersionId } = input; + if (!queryMetadata || !candidateMetadata) { + return false; + } + if ( + queryMetadata.dimensions !== undefined && + candidateMetadata.dimensions !== undefined && + queryMetadata.dimensions !== candidateMetadata.dimensions + ) { + return false; + } + if ( + queryMetadata.provider && + candidateMetadata.provider && + queryMetadata.provider !== candidateMetadata.provider + ) { + return false; + } + if ( + queryMetadata.model && + candidateMetadata.model && + queryMetadata.model !== candidateMetadata.model + ) { + return false; + } + if ( + queryMetadata.vectorVersion && + candidateMetadata.vectorVersion && + queryMetadata.vectorVersion !== candidateMetadata.vectorVersion + ) { + return false; + } + if ( + candidateMetadata.indexVersion && + candidateMetadata.indexVersion !== indexVersionId + ) { + return false; + } + if ( + queryMetadata.indexVersion && + queryMetadata.indexVersion !== indexVersionId + ) { + return false; + } + return true; + } + + private resolveDenseUnavailableReason(error: unknown): string { + if (error instanceof DomainError) { + return `dense_unavailable:${error.code.toLowerCase()}`; + } + if (error instanceof Error) { + return `dense_unavailable:${error.message.toLowerCase().replace(/\s+/g, "_")}`; + } + return "dense_unavailable:unknown_error"; + } + private readPriorSqlLaneEvidence( bundle: RagRetrievalResponse["retrieval_bundle"] ): RagPriorSqlLaneEvidence | undefined { @@ -1477,19 +1975,332 @@ export class RagRetrievalService { lane: RagPriorSqlLaneEvidence ): RagPriorSqlLaneEvidence { const degradeReasons = lane.degrade_reasons ?? lane.degradeReasons; + const shortcut = lane.shortcut ?? lane.shortcutDecision; return { ...lane, matched_count: lane.matched_count, selected_count: lane.selected_count, filtered_count: lane.filtered_count, + ...(lane.stale_count !== undefined ? { stale_count: lane.stale_count } : {}), + ...(lane.ambiguous_count !== undefined ? { ambiguous_count: lane.ambiguous_count } : {}), + ...(lane.eligible_count !== undefined ? { eligible_count: lane.eligible_count } : {}), ...(degradeReasons ? { degrade_reasons: degradeReasons } : {}), matchedCount: lane.matched_count, selectedCount: lane.selected_count, filteredCount: lane.filtered_count, - ...(degradeReasons ? { degradeReasons } : {}) + ...(lane.stale_count !== undefined ? { staleCount: lane.stale_count } : {}), + ...(lane.ambiguous_count !== undefined ? { ambiguousCount: lane.ambiguous_count } : {}), + ...(lane.eligible_count !== undefined ? { eligibleCount: lane.eligible_count } : {}), + ...(degradeReasons ? { degradeReasons } : {}), + ...(shortcut + ? { + shortcut: this.withPriorSqlShortcutCompatFields(shortcut), + shortcutDecision: this.withPriorSqlShortcutCompatFields(shortcut) + } + : {}) }; } + private withPriorSqlShortcutCompatFields( + decision: RagPriorSqlShortcutDecision + ): RagPriorSqlShortcutDecision { + const reasonCodes = decision.reason_codes ?? decision.reasonCodes ?? []; + return { + ...decision, + reason_codes: reasonCodes, + matched_count: decision.matched_count, + eligible_count: decision.eligible_count, + filtered_count: decision.filtered_count, + stale_count: decision.stale_count, + ambiguous_count: decision.ambiguous_count, + ...(decision.selected_chunk_id + ? { + selected_chunk_id: decision.selected_chunk_id + } + : {}), + ...(decision.selected_view_id + ? { + selected_view_id: decision.selected_view_id + } + : {}), + ...(decision.selected_source_run_id + ? { + selected_source_run_id: decision.selected_source_run_id + } + : {}), + reasonCodes, + matchedCount: decision.matched_count, + eligibleCount: decision.eligible_count, + filteredCount: decision.filtered_count, + staleCount: decision.stale_count, + ambiguousCount: decision.ambiguous_count, + ...(decision.selected_chunk_id + ? { + selectedChunkId: decision.selected_chunk_id + } + : {}), + ...(decision.selected_view_id + ? { + selectedViewId: decision.selected_view_id + } + : {}), + ...(decision.selected_source_run_id + ? { + selectedSourceRunId: decision.selected_source_run_id + } + : {}) + }; + } + + private buildContextPackLaneMetadata( + bundle: RagRetrievalResponse["retrieval_bundle"] | undefined + ): RagContextPackLaneMetadata[] { + if (!bundle) { + return []; + } + const candidateByChunkId = new Map( + bundle.candidates.map((candidate) => [candidate.chunk_id, candidate]) + ); + const selectedContext = bundle.selected_context ?? []; + const selectedByLane = new Map(); + for (const chunk of selectedContext) { + const lane = candidateByChunkId.get(chunk.chunk_id)?.source_lane; + if (!lane) { + continue; + } + const selected = selectedByLane.get(lane) ?? []; + selected.push(chunk.chunk_id); + selectedByLane.set(lane, selected); + } + + const laneMetadata: RagContextPackLaneMetadata[] = RAG_RETRIEVAL_LANES.map((lane) => { + const laneResult = bundle.lane_results[lane]; + const unavailableReason = this.resolveLaneUnavailableReason(laneResult.degrade_reason); + const state: RagContextPackLaneMetadata["state"] = + laneResult.status === "ok" + ? "ready" + : unavailableReason + ? "unavailable" + : "degraded"; + const evidenceIds = laneResult.hits.map((item) => item.chunk_id); + const selectedEvidenceIds = selectedByLane.get(lane) ?? []; + const reasonCodes = this.unique([ + laneResult.degrade_reason ?? "", + ...(bundle.decision_reasons ?? []) + ]); + return { + lane, + state, + input_count: laneResult.hits.length, + inputCount: laneResult.hits.length, + output_count: laneResult.hits.length, + outputCount: laneResult.hits.length, + selected_count: selectedEvidenceIds.length, + selectedCount: selectedEvidenceIds.length, + timeout_ms: laneResult.timeout_ms, + timeoutMs: laneResult.timeout_ms, + unavailable_reason: unavailableReason, + unavailableReason: unavailableReason, + evidence_ids: evidenceIds, + evidenceIds: evidenceIds, + reason_codes: reasonCodes, + reasonCodes: reasonCodes + }; + }); + + const schemaCandidates = bundle.candidates.filter( + (candidate) => candidate.chunk.metadata.domain === "schema" + ); + const exampleCandidates = bundle.candidates.filter( + (candidate) => candidate.chunk.metadata.domain === "sql_example" + ); + const relationshipHints = bundle.candidates.filter((candidate) => + candidate.evidence.some((evidence) => evidence.includes("relationship")) + ); + const metricTerms = this.unique(bundle.skill_context?.context.map((entry) => entry.term) ?? []); + const instructionBindings = + bundle.context_pack?.instruction_sets.model_bindings.length ?? + bundle.context_pack?.instructionSets?.modelBindings?.length ?? + 0; + const priorSqlLane = bundle.prior_sql_lane ?? bundle.priorSqlLane; + const permissionFiltering = this.readPermissionFilteringEvidence(bundle); + const permissionReasonCodes = this.unique(permissionFiltering?.reason_codes ?? []); + + laneMetadata.push( + { + lane: "schema_ddl_supplement", + state: schemaCandidates.length > 0 ? "ready" : "degraded", + input_count: schemaCandidates.length, + inputCount: schemaCandidates.length, + output_count: schemaCandidates.length, + outputCount: schemaCandidates.length, + selected_count: selectedContext.filter((chunk) => chunk.metadata.domain === "schema").length, + selectedCount: selectedContext.filter((chunk) => chunk.metadata.domain === "schema").length, + evidence_ids: schemaCandidates.map((candidate) => candidate.chunk_id), + evidenceIds: schemaCandidates.map((candidate) => candidate.chunk_id), + reason_codes: permissionReasonCodes, + reasonCodes: permissionReasonCodes + }, + { + lane: "example_sql", + state: exampleCandidates.length > 0 ? "ready" : "degraded", + input_count: exampleCandidates.length, + inputCount: exampleCandidates.length, + output_count: exampleCandidates.length, + outputCount: exampleCandidates.length, + selected_count: selectedContext.filter((chunk) => chunk.metadata.domain === "sql_example") + .length, + selectedCount: selectedContext.filter( + (chunk) => chunk.metadata.domain === "sql_example" + ).length, + evidence_ids: exampleCandidates.map((candidate) => candidate.chunk_id), + evidenceIds: exampleCandidates.map((candidate) => candidate.chunk_id) + }, + { + lane: "relationship", + state: relationshipHints.length > 0 ? "ready" : "degraded", + input_count: relationshipHints.length, + inputCount: relationshipHints.length, + output_count: relationshipHints.length, + outputCount: relationshipHints.length, + selected_count: selectedContext.length, + selectedCount: selectedContext.length + }, + { + lane: "metric", + state: metricTerms.length > 0 ? "ready" : "degraded", + input_count: metricTerms.length, + inputCount: metricTerms.length, + output_count: metricTerms.length, + outputCount: metricTerms.length, + selected_count: metricTerms.length, + selectedCount: metricTerms.length, + evidence_ids: metricTerms, + evidenceIds: metricTerms + }, + { + lane: "instruction", + state: instructionBindings > 0 ? "ready" : "degraded", + input_count: instructionBindings, + inputCount: instructionBindings, + output_count: instructionBindings, + outputCount: instructionBindings, + selected_count: instructionBindings, + selectedCount: instructionBindings + }, + { + lane: "saved_prior_sql", + state: + priorSqlLane?.status === "hit" + ? "ready" + : priorSqlLane?.status + ? "degraded" + : "skipped", + input_count: priorSqlLane?.matched_count ?? 0, + inputCount: priorSqlLane?.matched_count ?? 0, + output_count: priorSqlLane?.selected_count ?? 0, + outputCount: priorSqlLane?.selected_count ?? 0, + selected_count: priorSqlLane?.selected_count ?? 0, + selectedCount: priorSqlLane?.selected_count ?? 0, + reason_codes: this.unique(priorSqlLane?.degrade_reasons ?? []), + reasonCodes: this.unique(priorSqlLane?.degrade_reasons ?? []) + }, + { + lane: "dialect_function", + state: + bundle.skill_context && bundle.skill_context.skills.length > 0 ? "ready" : "degraded", + input_count: bundle.skill_context?.skills.length ?? 0, + inputCount: bundle.skill_context?.skills.length ?? 0, + output_count: bundle.skill_context?.skills.length ?? 0, + outputCount: bundle.skill_context?.skills.length ?? 0, + selected_count: bundle.skill_context?.context.length ?? 0, + selectedCount: bundle.skill_context?.context.length ?? 0 + } + ); + + return laneMetadata; + } + + private buildContextPackPruningDecisions( + bundle: RagRetrievalResponse["retrieval_bundle"] | undefined + ): RagContextPackPruningDecision[] { + if (!bundle) { + return []; + } + const selectedEvidenceIds = (bundle.selected_context ?? []).map((chunk) => chunk.chunk_id); + const removedEvidenceIds = bundle.candidates + .map((candidate) => candidate.chunk_id) + .filter((chunkId) => !selectedEvidenceIds.includes(chunkId)); + const decisions: RagContextPackPruningDecision[] = []; + + const retrievalBudgetDecision = this.budgetPolicy.describePruningDecision({ + budgetSource: "retrieval_budget", + decisionReasons: bundle.decision_reasons ?? [], + removedEvidenceIds, + keptEvidenceIds: + selectedEvidenceIds.length > 0 + ? selectedEvidenceIds + : bundle.candidates.map((candidate) => candidate.chunk_id) + }); + if (retrievalBudgetDecision) { + decisions.push({ + budget_source: retrievalBudgetDecision.budget_source, + removed_evidence_ids: retrievalBudgetDecision.removed_evidence_ids, + kept_evidence_ids: retrievalBudgetDecision.kept_evidence_ids, + reason_codes: retrievalBudgetDecision.reason_codes, + summary: retrievalBudgetDecision.summary, + budgetSource: retrievalBudgetDecision.budgetSource, + removedEvidenceIds: retrievalBudgetDecision.removedEvidenceIds, + keptEvidenceIds: retrievalBudgetDecision.keptEvidenceIds, + reasonCodes: retrievalBudgetDecision.reasonCodes + }); + } + + const columnPruning = this.readColumnPruningEvidence(bundle); + if (columnPruning && columnPruning.reason_codes.length > 0) { + const reasonCodes = this.unique(columnPruning.reason_codes); + decisions.push({ + budget_source: "context_pack", + removed_evidence_ids: [], + kept_evidence_ids: selectedEvidenceIds, + reason_codes: reasonCodes, + summary: `context_pack:column_pruning:${reasonCodes.join("|")}`, + budgetSource: "context_pack", + removedEvidenceIds: [], + keptEvidenceIds: selectedEvidenceIds, + reasonCodes + }); + } + + const permissionFiltering = this.readPermissionFilteringEvidence(bundle); + if (permissionFiltering?.status === "applied") { + const reasonCodes = this.unique(permissionFiltering.reason_codes ?? []); + decisions.push({ + budget_source: "context_pack", + removed_evidence_ids: permissionFiltering.denied_evidence_ids ?? [], + kept_evidence_ids: selectedEvidenceIds, + reason_codes: reasonCodes, + summary: `context_pack:permission_filtering:${reasonCodes.join("|") || "applied"}`, + budgetSource: "context_pack", + removedEvidenceIds: permissionFiltering.denied_evidence_ids ?? [], + keptEvidenceIds: selectedEvidenceIds, + reasonCodes + }); + } + + return decisions; + } + + private resolveLaneUnavailableReason(degradeReason: string | undefined): string | undefined { + if (!degradeReason) { + return undefined; + } + if (degradeReason.includes("unavailable")) { + return degradeReason; + } + return undefined; + } + private async buildContextPack(input: { bundle?: RagRetrievalResponse["retrieval_bundle"]; workspaceId?: string; @@ -1498,148 +2309,82 @@ export class RagRetrievalService { degradeReasons: string[]; }): Promise { const bundle = input.bundle; - const activeModeling = await this.resolveActiveModelingSnapshot( - input.workspaceId, - input.datasourceId - ); const semanticCandidates = bundle?.candidates.filter((candidate) => candidate.chunk.metadata.domain === "semantic_term") ?? []; - const retrievalModelKeys = this.unique( + const modelKeys = this.unique( semanticCandidates.flatMap((candidate) => candidate.chunk.metadata.tableNames) ); - const modelKeys = this.unique([ - ...activeModeling.modelKeys, - ...retrievalModelKeys - ]); - const relationshipKeys = this.unique(activeModeling.relationshipKeys); - const calculatedFieldKeys = this.unique(activeModeling.calculatedFieldKeys); const metricKeys = this.unique( bundle?.skill_context?.context.map((entry) => entry.term) ?? [] ); const selectedContext = bundle?.selected_context ?? []; - const modelingRevision = activeModeling.modelingRevision; - const semanticBindings = { - model_keys: modelKeys, - relationship_keys: relationshipKeys, - metric_keys: metricKeys, - calculated_field_keys: calculatedFieldKeys, - modelKeys, - relationshipKeys, - metricKeys, - calculatedFieldKeys - }; - const instructionSets = { - model_bindings: modelKeys, - relationship_bindings: relationshipKeys, - metric_bindings: metricKeys, - calculated_field_bindings: calculatedFieldKeys, - modelBindings: modelKeys, - relationshipBindings: relationshipKeys, - metricBindings: metricKeys, - calculatedFieldBindings: calculatedFieldKeys - }; - const selectedContextSummary = { - count: selectedContext.length, - snippets: selectedContext.map((entry) => entry.content.slice(0, 160)).slice(0, 5), - selectedContextCount: selectedContext.length - }; - const degradeReasons = this.unique(input.degradeReasons); - const riskTags = this.unique([ - ...(input.status === "degraded" - ? ["semantic_spine_degraded", ...(bundle?.risk_tags ?? [])] - : bundle?.risk_tags ?? []), - ...(input.workspaceId && modelingRevision === undefined - ? [MODELING_REVISION_MISSING_RISK_TAG] - : []) - ]); + const modelingRevision = await this.resolveActiveModelingRevision( + input.workspaceId, + input.datasourceId + ); + const laneMetadata = this.buildContextPackLaneMetadata(bundle); + const pruningDecisions = this.buildContextPackPruningDecisions(bundle); + const selectedContextLanes = this.unique( + selectedContext.map((entry) => entry.metadata.domain) + ); + const permissionFiltering = bundle + ? this.readPermissionFilteringEvidence(bundle) + : undefined; return { status: input.status, modeling_revision: modelingRevision, - modelingRevision, semantic_lock_status: input.status === "ready" ? "locked" : "degraded", - semanticLockStatus: input.status === "ready" ? "locked" : "degraded", - semantic_bindings: semanticBindings, - semanticBindings, - instruction_sets: instructionSets, - instructionSets, - selected_context_summary: selectedContextSummary, - selectedContextSummary, - degrade_reasons: degradeReasons, - degradeReasons, - risk_tags: riskTags, - riskTags + semantic_bindings: { + model_keys: modelKeys, + relationship_keys: [], + metric_keys: metricKeys, + calculated_field_keys: [] + }, + instruction_sets: { + model_bindings: modelKeys, + relationship_bindings: [], + metric_bindings: metricKeys, + calculated_field_bindings: [] + }, + selected_context_summary: { + count: selectedContext.length, + snippets: selectedContext.map((entry) => entry.content.slice(0, 160)).slice(0, 5) + }, + lane_metadata: laneMetadata, + laneMetadata: laneMetadata, + pruning_decisions: pruningDecisions, + pruningDecisions: pruningDecisions, + selected_context_lanes: selectedContextLanes, + selectedContextLanes: selectedContextLanes, + degrade_reasons: this.unique(input.degradeReasons), + risk_tags: this.unique( + input.status === "degraded" + ? [ + "semantic_spine_degraded", + ...(permissionFiltering?.status === "applied" ? ["permission_filtered"] : []), + ...(bundle?.risk_tags ?? []) + ] + : bundle?.risk_tags ?? [] + ) }; } - private async resolveActiveModelingSnapshot( + private async resolveActiveModelingRevision( workspaceIdRaw: string | undefined, datasourceIdRaw: string - ): Promise<{ - modelingRevision?: number; - modelKeys: string[]; - relationshipKeys: string[]; - calculatedFieldKeys: string[]; - }> { + ): Promise { const workspaceId = workspaceIdRaw?.trim(); const datasourceId = datasourceIdRaw.trim(); if (!workspaceId || !datasourceId) { - return { - modelKeys: [], - relationshipKeys: [], - calculatedFieldKeys: [] - }; + return undefined; } const scope = await this.modelingGraphRepository.getLatestScopeState({ workspaceId, datasourceId }); - if (!scope.activeRevision) { - return { - modelKeys: [], - relationshipKeys: [], - calculatedFieldKeys: [] - }; - } - const activeRevision = await this.modelingGraphRepository.findRevision({ - workspaceId, - datasourceId, - revision: scope.activeRevision - }); - if (!activeRevision) { - return { - modelingRevision: scope.activeRevision, - modelKeys: [], - relationshipKeys: [], - calculatedFieldKeys: [] - }; - } - - const modelKeys = this.unique( - (activeRevision.graphPayload.models ?? []) - .map((model) => this.readString(model.modelName ?? model.id ?? model.tableName)) - .filter((model): model is string => Boolean(model)) - ); - const relationshipKeys = this.unique( - (activeRevision.graphPayload.relationships ?? []) - .map((relationship) => - this.readString(relationship.id ?? relationship.name) - ) - .filter((relationship): relationship is string => Boolean(relationship)) - ); - const calculatedFieldKeys = this.unique( - (activeRevision.graphPayload.calculatedFields ?? []) - .map((field) => this.readString(field.id ?? field.name)) - .filter((field): field is string => Boolean(field)) - ); - - return { - modelingRevision: scope.activeRevision, - modelKeys, - relationshipKeys, - calculatedFieldKeys - }; + return scope.activeRevision; } private safeParseJson(value?: string): Record { @@ -1682,6 +2427,34 @@ export class RagRetrievalService { return undefined; } + private readPositiveInteger(value: unknown): number | undefined { + const parsed = this.readNumber(value); + if (parsed === undefined || !Number.isInteger(parsed) || parsed <= 0) { + return undefined; + } + return parsed; + } + + private readOptionalBoolean(value: unknown): boolean | undefined { + if (typeof value === "boolean") { + return value; + } + if (typeof value === "number" && Number.isFinite(value)) { + return value > 0; + } + if (typeof value !== "string") { + return undefined; + } + const normalized = value.trim().toLowerCase(); + if (normalized === "true" || normalized === "1" || normalized === "yes") { + return true; + } + if (normalized === "false" || normalized === "0" || normalized === "no") { + return false; + } + return undefined; + } + private readStringArray(value: unknown): string[] { if (!Array.isArray(value)) { return []; @@ -1742,6 +2515,19 @@ export class RagRetrievalService { candidateCount: bundle.candidates.length, priorSqlLane: this.readPriorSqlLaneEvidence(bundle), columnPruning: this.readColumnPruningEvidence(bundle), + laneMetadata: + bundle.lane_metadata ?? + bundle.laneMetadata ?? + bundle.context_pack?.lane_metadata ?? + bundle.context_pack?.laneMetadata ?? + [], + pruningDecisions: + bundle.pruning_decisions ?? + bundle.pruningDecisions ?? + bundle.context_pack?.pruning_decisions ?? + bundle.context_pack?.pruningDecisions ?? + [], + permissionFiltering: this.readPermissionFilteringEvidence(bundle), skillContext: bundle.skill_context, candidates: bundle.candidates.map((candidate) => ({ chunkId: candidate.chunk_id, diff --git a/apps/backend/src/modules/knowledge/rag/retrieval/rag-retrieval.types.ts b/apps/backend/src/modules/knowledge/rag/retrieval/rag-retrieval.types.ts index 7ebfd2f..76a501c 100644 --- a/apps/backend/src/modules/knowledge/rag/retrieval/rag-retrieval.types.ts +++ b/apps/backend/src/modules/knowledge/rag/retrieval/rag-retrieval.types.ts @@ -34,6 +34,13 @@ export interface RagRetrievalChunkMetadata { tableNames: string[]; columnNames: string[]; sourceMetadata?: Record; + denseProvider?: string; + denseModel?: string; + denseDimensions?: number; + vectorVersion?: string; + indexVersion?: string; + scope?: string; + assetType?: string; } export interface RagRetrievalChunkPayload { @@ -76,6 +83,78 @@ export interface RagRerankedCandidate extends RagRetrievalCandidate { rank_reason: string[]; } +export interface RagRerankStageMetadata { + status: "ok" | "degraded" | "skipped"; + provider?: string; + model?: string; + mode?: "provider" | "mock"; + config_source?: "settings" | "env_fallback" | "missing"; + config_id?: string; + timeout_ms?: number; + input_count?: number; + output_count?: number; + fallback_reason?: string; + unavailable_reason?: string; + evidence_ids?: string[]; + timeoutMs?: number; + inputCount?: number; + outputCount?: number; + fallbackReason?: string; + unavailableReason?: string; + configSource?: "settings" | "env_fallback" | "missing"; + configId?: string; + evidenceIds?: string[]; +} + +export interface RagRerankMetadata { + secondary: RagRerankStageMetadata; + secondaryCompat?: RagRerankStageMetadata; +} + +export interface RagContextPackLaneMetadata { + lane: + | RagRetrievalLane + | "rerank" + | "relationship" + | "metric" + | "example_sql" + | "instruction" + | "saved_prior_sql" + | "schema_ddl_supplement" + | "dialect_function"; + state: "ready" | "degraded" | "unavailable" | "skipped"; + provider?: string; + model?: string; + input_count?: number; + output_count?: number; + selected_count?: number; + timeout_ms?: number; + unavailable_reason?: string; + fallback_reason?: string; + evidence_ids?: string[]; + reason_codes?: string[]; + inputCount?: number; + outputCount?: number; + selectedCount?: number; + timeoutMs?: number; + unavailableReason?: string; + fallbackReason?: string; + evidenceIds?: string[]; + reasonCodes?: string[]; +} + +export interface RagContextPackPruningDecision { + budget_source: "retrieval_budget" | "rerank_budget" | "context_pack"; + removed_evidence_ids: string[]; + kept_evidence_ids: string[]; + reason_codes: string[]; + summary?: string; + budgetSource?: "retrieval_budget" | "rerank_budget" | "context_pack"; + removedEvidenceIds?: string[]; + keptEvidenceIds?: string[]; + reasonCodes?: string[]; +} + export interface RagSkillContextEntry { source: "skill_registry"; domain: string; @@ -137,6 +216,12 @@ export interface RagContextPack { count: number; snippets: string[]; }; + lane_metadata?: RagContextPackLaneMetadata[]; + laneMetadata?: RagContextPackLaneMetadata[]; + pruning_decisions?: RagContextPackPruningDecision[]; + pruningDecisions?: RagContextPackPruningDecision[]; + selected_context_lanes?: string[]; + selectedContextLanes?: string[]; degradeReasons?: string[]; riskTags?: string[]; } @@ -200,6 +285,12 @@ export interface RagRetrievalBundle { prior_sql_lane?: RagPriorSqlLaneEvidence; priorSqlLane?: RagPriorSqlLaneEvidence; decision_reasons?: string[]; + rerank_metadata?: RagRerankMetadata; + rerankMetadata?: RagRerankMetadata; + lane_metadata?: RagContextPackLaneMetadata[]; + laneMetadata?: RagContextPackLaneMetadata[]; + pruning_decisions?: RagContextPackPruningDecision[]; + pruningDecisions?: RagContextPackPruningDecision[]; } export interface RagRetrievalResponse { @@ -213,6 +304,15 @@ export interface RagRetrievalParsedMetadata extends Record { chunkProfile?: string; startOffset?: number; endOffset?: number; + denseMetadata?: { + provider?: string; + model?: string; + dimensions?: number; + vectorVersion?: string; + indexVersion?: string; + scope?: string; + assetType?: string; + }; } export interface RagRetrievalEntryContext { diff --git a/apps/backend/src/modules/knowledge/rag/retrieval/semantic-asset-reindex.service.ts b/apps/backend/src/modules/knowledge/rag/retrieval/semantic-asset-reindex.service.ts new file mode 100644 index 0000000..5b52bb0 --- /dev/null +++ b/apps/backend/src/modules/knowledge/rag/retrieval/semantic-asset-reindex.service.ts @@ -0,0 +1,258 @@ +import { createHash } from "node:crypto"; +import { Injectable } from "@nestjs/common"; +import { AppConfigService } from "../../../config/app-config.service"; +import { RagTaskConfigService } from "../../../llm/rag-task-config.service"; +import { ModelingGraphRepository } from "../../../platform/data/persistence/modeling-graph.repository"; +import { RagIndexRepository } from "../../../rag/index/rag-index.repository"; +import { BuildRagIndexJob } from "../../../rag/jobs/build-rag-index.job"; + +export const SEMANTIC_ASSET_REINDEX_TRIGGERS = [ + "schema", + "modeling_revision", + "examples", + "instructions", + "prior_sql", + "embedding_model" +] as const; + +export type SemanticAssetReindexTrigger = (typeof SEMANTIC_ASSET_REINDEX_TRIGGERS)[number]; + +export interface SemanticAssetReindexRequest { + datasourceId: string; + workspaceId?: string; + triggers: SemanticAssetReindexTrigger[]; + reason?: string; + runId?: string; + force?: boolean; + sourceVersion?: string; +} + +export interface SemanticAssetReindexResult { + status: "reindexed" | "skipped"; + datasourceId: string; + workspaceId?: string; + sourceVersion: string; + semanticAssetVersion: string; + embeddingProfile: { + provider: string; + model: string; + dimensions?: number; + vectorVersion: string; + configSource: "settings" | "env_fallback" | "missing"; + }; + triggerSummary: Record; + modelingRevision?: number; + reasonCodes: string[]; + indexVersionId?: string; + entryCount?: number; +} + +@Injectable() +export class SemanticAssetReindexService { + constructor( + private readonly appConfig: AppConfigService, + private readonly ragTaskConfigService: RagTaskConfigService, + private readonly indexRepository: RagIndexRepository, + private readonly buildIndexJob: BuildRagIndexJob, + private readonly modelingGraphRepository: ModelingGraphRepository + ) {} + + async reindex(input: SemanticAssetReindexRequest): Promise { + const datasourceId = input.datasourceId.trim(); + const workspaceId = input.workspaceId?.trim() || undefined; + const triggers = this.normalizeTriggers(input.triggers); + const triggerSummary = this.toTriggerSummary(triggers); + const modelingRevision = await this.resolveModelingRevision({ + workspaceId, + datasourceId, + includeModelingRevision: triggerSummary.modeling_revision + }); + const embeddingProfile = await this.resolveEmbeddingProfile(); + + const semanticAssetVersion = this.buildSemanticAssetVersion({ + datasourceId, + workspaceId, + triggers, + modelingRevision, + embeddingProfile + }); + const sourceVersion = + input.sourceVersion?.trim() || + this.buildSourceVersion({ + semanticAssetVersion, + triggers, + embeddingProfile + }); + + const reasonCodes = this.unique([ + input.reason?.trim() || "semantic_asset_reindex_requested", + ...triggers.map((trigger) => `trigger:${trigger}`) + ]); + if (triggers.length === 0) { + return { + status: "skipped", + datasourceId, + workspaceId, + sourceVersion, + semanticAssetVersion, + embeddingProfile, + triggerSummary, + modelingRevision, + reasonCodes: [...reasonCodes, "skip:no_triggers"] + }; + } + + const activeVersion = await this.indexRepository.getActiveVersion(datasourceId); + if (!input.force && activeVersion?.sourceVersion === sourceVersion) { + return { + status: "skipped", + datasourceId, + workspaceId, + sourceVersion, + semanticAssetVersion, + embeddingProfile, + triggerSummary, + modelingRevision, + reasonCodes: [...reasonCodes, "skip:already_active"] + }; + } + + const runId = + input.runId?.trim() || + `semantic-asset-reindex:${datasourceId}:${Date.now()}`; + const result = await this.buildIndexJob.run({ + datasourceId, + sourceVersion, + buildReason: `semantic_asset_reindex:${reasonCodes.join("|")}`, + runId + }); + + return { + status: "reindexed", + datasourceId, + workspaceId, + sourceVersion, + semanticAssetVersion, + embeddingProfile, + triggerSummary, + modelingRevision, + reasonCodes, + indexVersionId: result.indexVersionId, + entryCount: result.entryCount + }; + } + + private normalizeTriggers(triggers: SemanticAssetReindexTrigger[]): SemanticAssetReindexTrigger[] { + if (!Array.isArray(triggers) || triggers.length === 0) { + return []; + } + const allowed = new Set(SEMANTIC_ASSET_REINDEX_TRIGGERS); + return this.unique( + triggers + .map((trigger) => trigger.trim() as SemanticAssetReindexTrigger) + .filter((trigger): trigger is SemanticAssetReindexTrigger => allowed.has(trigger)) + ) as SemanticAssetReindexTrigger[]; + } + + private toTriggerSummary( + triggers: SemanticAssetReindexTrigger[] + ): Record { + const triggerSet = new Set(triggers); + return { + schema: triggerSet.has("schema"), + modeling_revision: triggerSet.has("modeling_revision"), + examples: triggerSet.has("examples"), + instructions: triggerSet.has("instructions"), + prior_sql: triggerSet.has("prior_sql"), + embedding_model: triggerSet.has("embedding_model") + }; + } + + private buildSemanticAssetVersion(input: { + datasourceId: string; + workspaceId?: string; + triggers: SemanticAssetReindexTrigger[]; + modelingRevision?: number; + embeddingProfile: { + provider: string; + model: string; + dimensions?: number; + vectorVersion: string; + configSource: "settings" | "env_fallback" | "missing"; + }; + }): string { + const fingerprint = createHash("sha256") + .update( + JSON.stringify({ + datasourceId: input.datasourceId, + workspaceId: input.workspaceId, + triggers: [...input.triggers].sort(), + modelingRevision: input.modelingRevision, + embeddingProfile: input.embeddingProfile + }) + ) + .digest("hex") + .slice(0, 16); + return `semantic-assets-${fingerprint}`; + } + + private buildSourceVersion(input: { + semanticAssetVersion: string; + triggers: SemanticAssetReindexTrigger[]; + embeddingProfile: { + provider: string; + model: string; + vectorVersion: string; + configSource: "settings" | "env_fallback" | "missing"; + }; + }): string { + const triggerPart = input.triggers.join("+") || "none"; + return `${input.semanticAssetVersion}:${input.embeddingProfile.provider}:${input.embeddingProfile.model}:${input.embeddingProfile.vectorVersion}:${input.embeddingProfile.configSource}:${triggerPart}`; + } + + private async resolveEmbeddingProfile(): Promise<{ + provider: string; + model: string; + dimensions?: number; + vectorVersion: string; + configSource: "settings" | "env_fallback" | "missing"; + }> { + try { + const runtime = await this.ragTaskConfigService.resolveEmbeddingRuntime(); + return { + provider: runtime.provider, + model: runtime.model, + dimensions: runtime.dimensions, + vectorVersion: runtime.vectorVersion ?? this.appConfig.embeddingVectorVersion, + configSource: runtime.configSource + }; + } catch { + return { + provider: this.appConfig.embeddingProvider, + model: this.appConfig.embeddingModel, + dimensions: this.appConfig.embeddingDimensions, + vectorVersion: this.appConfig.embeddingVectorVersion, + configSource: "missing" + }; + } + } + + private async resolveModelingRevision(input: { + workspaceId?: string; + datasourceId: string; + includeModelingRevision: boolean; + }): Promise { + if (!input.includeModelingRevision || !input.workspaceId) { + return undefined; + } + const scope = await this.modelingGraphRepository.getLatestScopeState({ + workspaceId: input.workspaceId, + datasourceId: input.datasourceId + }); + return scope.activeRevision; + } + + private unique(values: string[]): string[] { + return Array.from(new Set(values.filter((item) => item.trim().length > 0))); + } +} diff --git a/apps/backend/src/modules/llm/embedding-gateway.interface.ts b/apps/backend/src/modules/llm/embedding-gateway.interface.ts new file mode 100644 index 0000000..e4e7f6e --- /dev/null +++ b/apps/backend/src/modules/llm/embedding-gateway.interface.ts @@ -0,0 +1,28 @@ +export interface EmbeddingProviderMetadata { + provider: string; + model: string; + dimensions: number; + vectorVersion: string; + configSource?: "settings" | "env_fallback" | "missing"; + configId?: string; + indexVersion?: string; + scope?: string; + assetType?: string; +} + +export interface EmbeddingVectorPayload { + vector: number[]; + metadata: EmbeddingProviderMetadata; +} + +export interface EmbeddingGatewayRequest { + texts: string[]; + model?: string; + indexVersion?: string; + scope?: string; + assetType?: string; +} + +export interface EmbeddingGateway { + embed(input: EmbeddingGatewayRequest): Promise; +} diff --git a/apps/backend/src/modules/llm/embedding-router.service.ts b/apps/backend/src/modules/llm/embedding-router.service.ts new file mode 100644 index 0000000..8b45775 --- /dev/null +++ b/apps/backend/src/modules/llm/embedding-router.service.ts @@ -0,0 +1,202 @@ +import { createHash } from "node:crypto"; +import { Injectable } from "@nestjs/common"; +import { DomainError } from "../../common/domain-error"; +import { AppConfigService } from "../config/app-config.service"; +import { RagTaskConfigService } from "./rag-task-config.service"; +import type { + EmbeddingGateway, + EmbeddingGatewayRequest, + EmbeddingProviderMetadata, + EmbeddingVectorPayload +} from "./embedding-gateway.interface"; + +interface OpenAiEmbeddingResponse { + data?: Array<{ + embedding?: unknown; + }>; +} + +@Injectable() +export class EmbeddingRouterService implements EmbeddingGateway { + constructor( + private readonly config: AppConfigService, + private readonly ragTaskConfigService: RagTaskConfigService + ) {} + + async embed(input: EmbeddingGatewayRequest): Promise { + const texts = input.texts + .map((item) => item.trim()) + .filter((item) => item.length > 0); + if (texts.length === 0) { + return []; + } + + const testScopedMockMode = this.config.llmMockMode && this.config.nodeEnv === "test"; + if (this.config.embeddingMockMode || testScopedMockMode) { + return this.embedInMockMode(texts, input); + } + + const runtime = await this.ragTaskConfigService.resolveEmbeddingRuntime(); + const baseUrl = runtime.baseUrl.trim(); + const apiKey = runtime.apiKey.trim(); + + const endpoint = `${baseUrl.replace(/\/$/, "")}/embeddings`; + const response = await fetch(endpoint, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${apiKey}` + }, + body: JSON.stringify({ + model: input.model ?? runtime.model, + input: texts, + ...(runtime.dimensions + ? { + dimensions: runtime.dimensions + } + : {}) + }), + signal: AbortSignal.timeout(runtime.timeoutMs) + }).catch((error: unknown) => { + throw new DomainError( + "EMBEDDING_PROVIDER_REQUEST_FAILED", + `Embedding provider 请求失败: ${ + error instanceof Error ? error.message : String(error) + }`, + 502, + { + provider: runtime.provider, + configSource: runtime.configSource + } + ); + }); + + if (!response.ok) { + const responseText = await response.text().catch(() => ""); + throw new DomainError( + "EMBEDDING_PROVIDER_RESPONSE_ERROR", + `Embedding provider 返回异常 (${response.status})。`, + 502, + { + provider: runtime.provider, + configSource: runtime.configSource, + statusCode: response.status, + body: responseText.slice(0, 500) + } + ); + } + + const payload = (await response.json().catch(() => ({}))) as OpenAiEmbeddingResponse; + const rows = Array.isArray(payload.data) ? payload.data : []; + if (rows.length !== texts.length) { + throw new DomainError( + "EMBEDDING_PROVIDER_INVALID_PAYLOAD", + "Embedding provider 返回向量数量与请求不一致。", + 502, + { + provider: runtime.provider, + configSource: runtime.configSource, + expected: texts.length, + actual: rows.length + } + ); + } + + const vectors = rows.map((row) => this.toVector(row.embedding)); + const dimensions = vectors[0]?.length ?? 0; + if (dimensions <= 0) { + throw new DomainError( + "EMBEDDING_PROVIDER_INVALID_VECTOR", + "Embedding provider 未返回可用向量。", + 502, + { + provider: runtime.provider, + configSource: runtime.configSource + } + ); + } + if (runtime.dimensions && runtime.dimensions > 0 && dimensions !== runtime.dimensions) { + throw new DomainError( + "EMBEDDING_PROVIDER_DIMENSION_MISMATCH", + "Embedding provider 返回向量维度与运行时配置不一致。", + 502, + { + provider: runtime.provider, + configSource: runtime.configSource, + expectedDimensions: runtime.dimensions, + actualDimensions: dimensions + } + ); + } + const mismatchedVector = vectors.find((vector) => vector.length !== dimensions); + if (mismatchedVector) { + throw new DomainError( + "EMBEDDING_PROVIDER_DIMENSION_MISMATCH", + "Embedding provider 返回向量维度不一致。", + 502, + { + provider: runtime.provider, + configSource: runtime.configSource, + expectedDimensions: dimensions, + actualDimensions: mismatchedVector.length + } + ); + } + + const metadata: EmbeddingProviderMetadata = { + provider: runtime.provider, + model: input.model ?? runtime.model, + dimensions, + vectorVersion: runtime.vectorVersion ?? this.config.embeddingVectorVersion, + configSource: runtime.configSource, + configId: runtime.configId, + indexVersion: input.indexVersion, + scope: input.scope, + assetType: input.assetType + }; + + return vectors.map((vector) => ({ + vector, + metadata + })); + } + + private embedInMockMode( + texts: string[], + input: EmbeddingGatewayRequest + ): EmbeddingVectorPayload[] { + const dimensions = this.config.embeddingDimensions ?? 8; + const metadata: EmbeddingProviderMetadata = { + provider: `${this.config.embeddingProvider}:mock`, + model: input.model ?? this.config.embeddingModel, + dimensions, + vectorVersion: this.config.embeddingVectorVersion, + indexVersion: input.indexVersion, + scope: input.scope, + assetType: input.assetType + }; + + return texts.map((text) => ({ + vector: this.buildDeterministicVector(text, dimensions), + metadata + })); + } + + private buildDeterministicVector(text: string, dimensions: number): number[] { + const digest = createHash("sha256").update(text).digest(); + return Array.from({ length: dimensions }, (_, index) => { + const byte = digest[index % digest.length] ?? 0; + const normalized = byte / 255; + return Number((normalized * 2 - 1).toFixed(6)); + }); + } + + private toVector(value: unknown): number[] { + if (!Array.isArray(value)) { + return []; + } + return value + .map((item) => Number(item)) + .filter((item) => Number.isFinite(item)); + } +} diff --git a/apps/backend/src/modules/llm/llm-gateway.service.ts b/apps/backend/src/modules/llm/llm-gateway.service.ts index f8468b0..48b2776 100644 --- a/apps/backend/src/modules/llm/llm-gateway.service.ts +++ b/apps/backend/src/modules/llm/llm-gateway.service.ts @@ -155,6 +155,8 @@ export class LlmGatewayService implements LlmGateway { let streamedText = ""; let toolCallSql: string | undefined; + let successfulToolCallSql: string | undefined; + const toolCallSqlById = new Map(); try { const model = this.modelFactory.createChatModel(runtime) as never; const normalizedTools = this.normalizeTools(options?.tools); @@ -181,6 +183,7 @@ export class LlmGatewayService implements LlmGateway { const parsedSql = this.extractToolSql(chunk.input); if (parsedSql) { toolCallSql = parsedSql; + toolCallSqlById.set(chunk.toolCallId, parsedSql); } await options?.onEvent?.({ type: "tool-call", @@ -191,6 +194,7 @@ export class LlmGatewayService implements LlmGateway { continue; } if (chunk.type === "tool-result") { + successfulToolCallSql = toolCallSqlById.get(chunk.toolCallId) ?? toolCallSql; await options?.onEvent?.({ type: "tool-result", toolName: chunk.toolName, @@ -255,6 +259,23 @@ export class LlmGatewayService implements LlmGateway { throw error; } + if (successfulToolCallSql) { + const recoveredText = this.formatToolSqlFallback(successfulToolCallSql); + const delta = this.resolveFallbackDelta(streamedText, recoveredText); + if (delta) { + await options?.onEvent?.({ + type: "text-delta", + text: delta + }); + } + return { + provider: runtime.provider, + model: runtime.model, + prompt, + rawText: recoveredText + }; + } + if (isTimeoutAbortError(error)) { const recoveredText = await this.tryRecoverFromStreamTimeout( prompt, @@ -347,6 +368,15 @@ export class LlmGatewayService implements LlmGateway { return undefined; } + private formatToolSqlFallback(sql: string): string { + return [ + "上游模型在工具执行后返回了无法解析的流式响应，已使用成功执行的只读 SQL 继续完成分析。", + "```sql", + sql.trim().replace(/;+\s*$/, ""), + "```" + ].join("\n"); + } + private resolveFallbackDelta(existingText: string, fallbackText: string): string { if (!existingText) { return fallbackText; diff --git a/apps/backend/src/modules/llm/llm.module.ts b/apps/backend/src/modules/llm/llm.module.ts index e5693e1..e1e8757 100644 --- a/apps/backend/src/modules/llm/llm.module.ts +++ b/apps/backend/src/modules/llm/llm.module.ts @@ -1,10 +1,14 @@ import { Module } from "@nestjs/common"; import { AppConfigModule } from "../config/config.module"; import { PlatformDataPersistenceModule } from "../platform/data/persistence.module"; +import { EmbeddingRouterService } from "./embedding-router.service"; import { LlmGatewayService } from "./llm-gateway.service"; import { LlmModelFactory } from "./llm-model-factory"; import { ProviderCatalogService } from "./provider-catalog.service"; import { ProviderRouterService } from "./provider-router.service"; +import { RagTaskConfigService } from "./rag-task-config.service"; +import { RagTaskHealthProbeService } from "./rag-task-health-probe.service"; +import { RerankRouterService } from "./rerank-router.service"; import { ToolEventsMapper } from "./tools/tool-events.mapper"; @Module({ @@ -13,6 +17,10 @@ import { ToolEventsMapper } from "./tools/tool-events.mapper"; LlmModelFactory, LlmGatewayService, ToolEventsMapper, + EmbeddingRouterService, + RagTaskHealthProbeService, + RagTaskConfigService, + RerankRouterService, ProviderCatalogService, ProviderRouterService ], @@ -20,6 +28,10 @@ import { ToolEventsMapper } from "./tools/tool-events.mapper"; LlmModelFactory, LlmGatewayService, ToolEventsMapper, + EmbeddingRouterService, + RagTaskHealthProbeService, + RagTaskConfigService, + RerankRouterService, ProviderCatalogService, ProviderRouterService ] diff --git a/apps/backend/src/modules/llm/provider-adapters/provider-capabilities.ts b/apps/backend/src/modules/llm/provider-adapters/provider-capabilities.ts index 5e1cdcb..2b8070c 100644 --- a/apps/backend/src/modules/llm/provider-adapters/provider-capabilities.ts +++ b/apps/backend/src/modules/llm/provider-adapters/provider-capabilities.ts @@ -5,6 +5,18 @@ export interface ProviderCapability { displayName: string; supportsModelListing: boolean; defaultBaseUrl: string; + ragProfiles?: { + embedding?: { + endpoint: string; + recommendedModel?: string; + mode?: "compatible" | "native"; + }; + rerank?: { + endpoint: string; + recommendedModel?: string; + mode?: "compatible" | "native"; + }; + }; } export const PROVIDER_CAPABILITIES: Record = { @@ -12,7 +24,19 @@ export const PROVIDER_CAPABILITIES: Record provider: "openai", displayName: "OpenAI", supportsModelListing: true, - defaultBaseUrl: "https://api.openai.com/v1" + defaultBaseUrl: "https://api.openai.com/v1", + ragProfiles: { + embedding: { + endpoint: "/embeddings", + recommendedModel: "text-embedding-3-small", + mode: "native" + }, + rerank: { + endpoint: "/responses", + recommendedModel: "gpt-4.1-mini", + mode: "native" + } + } }, gemini: { provider: "gemini", @@ -36,13 +60,37 @@ export const PROVIDER_CAPABILITIES: Record provider: "volcengine", displayName: "火山引擎", supportsModelListing: true, - defaultBaseUrl: "https://ark.cn-beijing.volces.com/api/v3" + defaultBaseUrl: "https://ark.cn-beijing.volces.com/api/v3", + ragProfiles: { + embedding: { + endpoint: "/embeddings", + recommendedModel: "doubao-embedding-text-240715", + mode: "compatible" + }, + rerank: { + endpoint: "/rerank", + recommendedModel: "doubao-rerank-v1", + mode: "compatible" + } + } }, siliconflow: { provider: "siliconflow", displayName: "硅基流动", supportsModelListing: true, - defaultBaseUrl: "https://api.siliconflow.cn/v1" + defaultBaseUrl: "https://api.siliconflow.cn/v1", + ragProfiles: { + embedding: { + endpoint: "/embeddings", + recommendedModel: "BAAI/bge-m3", + mode: "compatible" + }, + rerank: { + endpoint: "/rerank", + recommendedModel: "BAAI/bge-reranker-v2-m3", + mode: "compatible" + } + } }, openrouter: { provider: "openrouter", @@ -66,7 +114,19 @@ export const PROVIDER_CAPABILITIES: Record provider: "tongyi", displayName: "通义", supportsModelListing: true, - defaultBaseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1" + defaultBaseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1", + ragProfiles: { + embedding: { + endpoint: "/embeddings", + recommendedModel: "text-embedding-v4", + mode: "compatible" + }, + rerank: { + endpoint: "/rerank", + recommendedModel: "gte-rerank-v2", + mode: "compatible" + } + } } }; diff --git a/apps/backend/src/modules/llm/provider-catalog.service.ts b/apps/backend/src/modules/llm/provider-catalog.service.ts index ec16255..838a2cf 100644 --- a/apps/backend/src/modules/llm/provider-catalog.service.ts +++ b/apps/backend/src/modules/llm/provider-catalog.service.ts @@ -16,7 +16,11 @@ import { KimiAdapter } from "./provider-adapters/kimi.adapter"; import { MinimaxAdapter } from "./provider-adapters/minimax.adapter"; import { OpenAiAdapter } from "./provider-adapters/openai.adapter"; import { OpenRouterAdapter } from "./provider-adapters/openrouter.adapter"; -import { ProviderRuntimeConfig, type ProviderAdapter } from "./provider-adapters/provider-adapter.interface"; +import { + ProviderRuntimeConfig, + type ProviderAdapter, + type ProviderModelDescriptor +} from "./provider-adapters/provider-adapter.interface"; import { PROVIDER_CAPABILITIES, SUPPORTED_PROVIDER_CODES } from "./provider-adapters/provider-capabilities"; import { SiliconflowAdapter } from "./provider-adapters/siliconflow.adapter"; import { TencentHunyuanAdapter } from "./provider-adapters/tencent-hunyuan.adapter"; @@ -33,6 +37,13 @@ type ProviderPayload = { actor: SettingsActor; }; +type PreviewProviderModelsInput = { + taskType: "embedding" | "rerank"; + provider: LlmProviderCode; + baseUrl?: string | null; + apiKey: string; +}; + @Injectable() export class ProviderCatalogService { private readonly adapters: Map; @@ -214,6 +225,30 @@ export class ProviderCatalogService { return models.map((m) => ({ id: m.id, enabled: m.enabled })); } + async previewProviderModels(input: PreviewProviderModelsInput): Promise<{ + provider: LlmProviderCode; + supportsModelListing: boolean; + recommendedModel?: string; + models: ProviderModelDescriptor[]; + }> { + const adapter = this.getAdapter(input.provider); + const recommendedModel = + PROVIDER_CAPABILITIES[input.provider].ragProfiles?.[input.taskType]?.recommendedModel; + const listedModels = await adapter.listModels({ + provider: input.provider, + baseUrl: input.baseUrl, + apiKey: input.apiKey.trim(), + timeoutMs: this.config.llmTimeoutMs + }); + + return { + provider: input.provider, + supportsModelListing: adapter.supportsModelListing, + recommendedModel, + models: this.rankPreviewModels(input.taskType, listedModels, recommendedModel) + }; + } + async listEnabledModels(): Promise { return this.repository.listModels({ enabledOnly: true }); } @@ -305,4 +340,75 @@ export class ProviderCatalogService { } return `${trimmed.slice(0, 4)}***${trimmed.slice(-4)}`; } + + private rankPreviewModels( + taskType: "embedding" | "rerank", + models: ProviderModelDescriptor[], + recommendedModel?: string + ): ProviderModelDescriptor[] { + const withScore = models.map((model) => ({ + model, + score: this.scorePreviewModel(taskType, model, recommendedModel) + })); + const hasPositiveMatches = withScore.some((item) => item.score > 0); + const ranked = hasPositiveMatches + ? withScore.filter((item) => item.score > 0) + : withScore; + return ranked + .sort((left, right) => { + if (right.score !== left.score) { + return right.score - left.score; + } + return left.model.displayName.localeCompare(right.model.displayName); + }) + .map((item) => item.model); + } + + private scorePreviewModel( + taskType: "embedding" | "rerank", + model: ProviderModelDescriptor, + recommendedModel?: string + ): number { + const haystack = `${model.model} ${model.displayName}`.toLowerCase(); + const capabilities = (model.capabilities ?? []).map((item) => item.toLowerCase()); + let score = 0; + + if (recommendedModel && model.model === recommendedModel) { + score += 100; + } + + const hasEmbeddingSignals = + /(embedding|embed|bge|e5|gte|multilingual)/.test(haystack) || + capabilities.some((item) => /(embed)/.test(item)); + const hasRerankSignals = + /(rerank|reranker)/.test(haystack) || + capabilities.some((item) => /(rerank|rank)/.test(item)); + const hasGeneralGenerationSignals = + /(gpt|gemini|deepseek|kimi|doubao|qwen|minimax|hunyuan)/.test(haystack) || + capabilities.some((item) => /(chat|generatecontent|completion)/.test(item)); + + if (taskType === "embedding") { + if (hasEmbeddingSignals) { + score += 20; + } + if (hasRerankSignals) { + score -= 20; + } + if (!hasEmbeddingSignals && hasGeneralGenerationSignals) { + score -= 10; + } + return score; + } + + if (hasRerankSignals) { + score += 20; + } + if (hasGeneralGenerationSignals) { + score += 6; + } + if (hasEmbeddingSignals && !hasRerankSignals) { + score -= 12; + } + return score; + } } diff --git a/apps/backend/src/modules/llm/provider-router.service.ts b/apps/backend/src/modules/llm/provider-router.service.ts index 29d8643..4e3229a 100644 --- a/apps/backend/src/modules/llm/provider-router.service.ts +++ b/apps/backend/src/modules/llm/provider-router.service.ts @@ -1,4 +1,6 @@ import { Injectable } from "@nestjs/common"; +import type { Text2SqlV2StageName } from "@text2sql/shared-types"; +import { DomainError } from "../../common/domain-error"; import { AppConfigService } from "../config/app-config.service"; import { LlmGatewayService } from "./llm-gateway.service"; import type { @@ -32,6 +34,85 @@ export interface RerankCandidateResult { reason: string; } +export interface RerankExecutionMetadata { + mode: "provider" | "mock"; + provider?: string; + model?: string; + configSource?: "settings" | "env_fallback" | "missing"; + configId?: string; + inputCount: number; + outputCount: number; + fallbackReason?: string; + unavailableReason?: string; +} + +export interface RerankCandidatesResponse { + results: RerankCandidateResult[]; + metadata: RerankExecutionMetadata; +} + +export type Text2SqlReasoningTier = "low" | "medium" | "high"; + +export interface Text2SqlStageTaskProfilePolicy { + stage: Text2SqlV2StageName; + taskProfile: string; + reasoningTier: Text2SqlReasoningTier; + provider: string; + model: string; + policySource: + | "session_model_catalog_binding" + | "session_model_binding" + | "router_default_binding"; + escalationReason?: string; +} + +interface StageTaskProfileRule { + taskProfile: string; + reasoningTier: Text2SqlReasoningTier; +} + +const DEFAULT_TEXT2SQL_STAGE_POLICY_MATRIX: Record< + Text2SqlV2StageName, + StageTaskProfileRule +> = { + intake: { + taskProfile: "intake-fast", + reasoningTier: "low" + }, + retrieve: { + taskProfile: "retrieval-support", + reasoningTier: "low" + }, + "assemble-context": { + taskProfile: "context-assembly", + reasoningTier: "low" + }, + "semantic-plan": { + taskProfile: "semantic-planning", + reasoningTier: "high" + }, + "generate-sql": { + taskProfile: "sql-generation", + reasoningTier: "high" + }, + validate: { + taskProfile: "sql-validation", + reasoningTier: "medium" + }, + correct: { + taskProfile: "sql-correction", + reasoningTier: "medium" + }, + execute: { + taskProfile: "sql-execution", + reasoningTier: "low" + }, + answer: { + taskProfile: "answer-rendering", + reasoningTier: "low" + } +}; + @Injectable() export class ProviderRouterService { constructor( @@ -83,12 +164,41 @@ export class ProviderRouterService { candidates: RerankCandidateInput[]; modelCatalogId?: string; }): Promise { + const response = await this.rerankCandidatesWithMetadata(input); + return response.results; + } + + async rerankCandidatesWithMetadata(input: { + query: string; + candidates: RerankCandidateInput[]; + modelCatalogId?: string; + }): Promise { if (input.candidates.length === 0) { - return []; + return { + results: [], + metadata: { + mode: this.config.llmMockMode ? "mock" : "provider", + provider: this.config.llmProvider, + model: this.config.llmModel, + inputCount: 0, + outputCount: 0 + } + }; } if (this.config.llmMockMode) { - return this.rerankInMockMode(input.query, input.candidates); + const results = this.rerankInMockMode(input.query, input.candidates); + return { + results, + metadata: { + mode: "mock", + provider: `${this.config.llmProvider}:mock`, + model: this.config.llmModel, + inputCount: input.candidates.length, + outputCount: results.length, + fallbackReason: "llm_mock_mode" + } + }; } const prompt: LlmGatewayPrompt = { @@ -126,9 +236,58 @@ export class ProviderRouterService { }); const parsed = this.parseRerankResponse(completion.rawText); if (parsed.length === 0) { - return this.rerankInMockMode(input.query, input.candidates); + throw new DomainError( + "RERANK_PROVIDER_INVALID_PAYLOAD", + "Rerank provider 未返回有效排序结果。", + 502, + { + provider: completion.provider, + model: completion.model, + inputCount: input.candidates.length + } + ); } - return parsed; + return { + results: parsed, + metadata: { + mode: "provider", + provider: completion.provider, + model: completion.model, + inputCount: input.candidates.length, + outputCount: parsed.length + } + }; + } + + resolveText2SqlStageTaskProfilePolicy(input: { + stage: Text2SqlV2StageName; + modelCatalogId?: string; + provider?: string; + model?: string; + escalationReason?: string; + }): Text2SqlStageTaskProfilePolicy { + const stageRule = DEFAULT_TEXT2SQL_STAGE_POLICY_MATRIX[input.stage]; + const provider = this.normalizeProviderModel(input.provider, this.config.llmProvider); + const model = this.normalizeProviderModel(input.model, this.config.llmModel); + const policySource = input.modelCatalogId + ? "session_model_catalog_binding" + : input.provider || input.model + ? "session_model_binding" + : "router_default_binding"; + + return { + stage: input.stage, + taskProfile: stageRule.taskProfile, + reasoningTier: this.resolveReasoningTier(stageRule.reasoningTier, input.escalationReason), + provider, + model, + policySource, + ...(input.escalationReason + ? { + escalationReason: input.escalationReason + } + : {}) + }; } private async resolveRuntime( @@ -232,6 +391,30 @@ export class ProviderRouterService { } } + private normalizeProviderModel( + value: string | undefined, + fallback: string | undefined + ): string { + const normalized = value?.trim() || fallback?.trim(); + return normalized && normalized.length > 0 ? normalized : "unknown"; + } + + private resolveReasoningTier( + baseline: Text2SqlReasoningTier, + escalationReason?: string + ): Text2SqlReasoningTier { + if (!escalationReason) { + return baseline; + } + if (baseline === "high") { + return "high"; + } + if (baseline === "medium") { + return "high"; + } + return "medium"; + } + private toRerankResult(row: unknown): RerankCandidateResult | undefined { if (!this.isRecord(row)) { return undefined; diff --git a/apps/backend/src/modules/llm/rag-task-config.service.ts b/apps/backend/src/modules/llm/rag-task-config.service.ts new file mode 100644 index 0000000..2b5c1ec --- /dev/null +++ b/apps/backend/src/modules/llm/rag-task-config.service.ts @@ -0,0 +1,547 @@ +import { Injectable } from "@nestjs/common"; +import type { + RagConfigSource, + RagHealthCheckedAgainst, + RagTaskConfig, + RagTaskConfigDraftInput, + RagTaskConfigHealthResult, + RagTaskSettingsView, + RagTaskType, + SettingsActor +} from "@text2sql/shared-types"; +import { DomainError } from "../../common/domain-error"; +import { AppConfigService } from "../config/app-config.service"; +import { RagTaskConfigRepository } from "../data/persistence/rag-task-config.repository"; +import { + RagTaskHealthProbeService, + type RagRerankChallengeSummary +} from "./rag-task-health-probe.service"; + +export interface UpsertRagTaskConfigInput { + provider: string; + model: string; + baseUrl?: string; + apiKey?: string; + enabled?: boolean; + dimensions?: number; + vectorVersion?: string; + timeoutMs?: number; + note?: string; +} + +export interface CheckRagTaskConfigHealthInput { + sampleQuery?: string; + sampleCandidates?: string[]; + expectedDimensions?: number; + draft?: RagTaskConfigDraftInput; +} + +export interface CheckRagTaskConfigHealthContext { + requestId?: string; + traceId?: string; +} + +export interface RagTaskRuntimeConfig { + taskType: RagTaskType; + provider: string; + model: string; + baseUrl: string; + apiKey: string; + dimensions?: number; + vectorVersion?: string; + timeoutMs: number; + configSource: RagConfigSource; + configId?: string; +} + +@Injectable() +export class RagTaskConfigService { + constructor( + private readonly appConfig: AppConfigService, + private readonly repository: RagTaskConfigRepository, + private readonly healthProbe: RagTaskHealthProbeService + ) {} + + async listSettingsView(actor: SettingsActor): Promise { + const [embedding, rerank] = await Promise.all([ + this.resolveEffectiveConfig("embedding"), + this.resolveEffectiveConfig("rerank") + ]); + return { + actor, + items: [embedding, rerank] + }; + } + + async upsertConfig( + taskType: RagTaskType, + input: UpsertRagTaskConfigInput, + actor: SettingsActor + ): Promise { + const provider = input.provider.trim(); + const model = input.model.trim(); + if (!provider || !model) { + throw new DomainError("RAG_TASK_CONFIG_INVALID", "provider/model 不能为空。", 400, { + taskType + }); + } + const created = await this.repository.upsertConfig({ + taskType, + provider, + model, + baseUrl: input.baseUrl?.trim() || null, + apiKeyCiphertext: input.apiKey?.trim() || undefined, + apiKeyMasked: input.apiKey ? this.maskApiKey(input.apiKey) : undefined, + enabled: input.enabled, + dimensions: taskType === "embedding" ? (input.dimensions ?? null) : null, + vectorVersion: + taskType === "embedding" ? (input.vectorVersion?.trim() || null) : null, + timeoutMs: input.timeoutMs ?? null, + note: input.note?.trim() || null, + actorId: actor.id + }); + return this.resolveEffectiveConfig(taskType, created); + } + + async checkConfigHealth( + taskType: RagTaskType, + input: CheckRagTaskConfigHealthInput, + context?: CheckRagTaskConfigHealthContext + ): Promise { + const start = Date.now(); + const checkedAt = new Date().toISOString(); + const persisted = await this.repository.getConfig(taskType); + const checkedAgainst: RagHealthCheckedAgainst = input.draft ? "draft" : "persisted"; + + try { + const runtime = input.draft + ? await this.resolveRuntimeFromDraft(taskType, input.draft, persisted) + : await this.resolveRuntime(taskType); + const healthProbe = + taskType === "embedding" + ? await this.healthProbe.probeEmbedding({ + runtime, + expectedDimensions: input.expectedDimensions + }) + : await this.healthProbe.probeRerank({ + runtime, + sampleQuery: input.sampleQuery, + sampleCandidates: input.sampleCandidates + }); + const latencyMs = Date.now() - start; + if (persisted && checkedAgainst === "persisted") { + await this.repository.updateHealth(taskType, { + healthStatus: healthProbe.status, + lastCheckedAt: checkedAt, + lastHealthLatencyMs: latencyMs, + lastHealthMessage: healthProbe.message, + lastError: healthProbe.status === "healthy" ? null : healthProbe.message + }); + } + + const response: RagTaskConfigHealthResult = { + taskType, + status: healthProbe.status, + reasonCode: healthProbe.reasonCode, + message: healthProbe.message, + checkedAt, + latencyMs: healthProbe.latencyMs, + configSource: runtime.configSource, + checkedAgainst, + requestId: context?.requestId, + traceId: context?.traceId ?? context?.requestId, + config: await this.resolveEffectiveConfig(taskType), + details: healthProbe.details + }; + + if (taskType === "rerank") { + const rerankProbe = healthProbe as Awaited< + ReturnType + >; + response.challenge = rerankProbe.challenge; + if (rerankProbe.reranked && rerankProbe.reranked.length > 0) { + response.sample = { + reranked: rerankProbe.reranked + }; + } + } + + return response; + } catch (error) { + const latencyMs = Date.now() - start; + const message = + error instanceof DomainError + ? error.message + : error instanceof Error + ? error.message + : "RAG 配置检测失败"; + const status: "degraded" | "failed" = + error instanceof DomainError + ? error.code === "RAG_TASK_CONFIG_SCHEMA_INVALID" + ? "failed" + : "degraded" + : "failed"; + if (persisted && checkedAgainst === "persisted") { + await this.repository.updateHealth(taskType, { + healthStatus: status, + lastCheckedAt: checkedAt, + lastHealthLatencyMs: latencyMs, + lastHealthMessage: message, + lastError: message + }); + } + return { + taskType, + status, + reasonCode: this.mapHealthReasonCode(error, status), + message, + checkedAt, + latencyMs, + configSource: this.resolveHealthConfigSource(error, checkedAgainst), + checkedAgainst, + requestId: context?.requestId, + traceId: context?.traceId ?? context?.requestId, + config: await this.resolveEffectiveConfig(taskType), + details: { + error: + error instanceof DomainError + ? error.code + : error instanceof Error + ? error.name + : "unknown" + } + }; + } + } + + async resolveEmbeddingRuntime(): Promise { + return this.resolveRuntime("embedding"); + } + + async resolveRerankRuntime(): Promise { + return this.resolveRuntime("rerank"); + } + + private async resolveRuntimeFromDraft( + taskType: RagTaskType, + draft: RagTaskConfigDraftInput, + persisted?: RagTaskConfig | null + ): Promise { + const provider = draft.provider?.trim() ?? ""; + const model = draft.model?.trim() ?? ""; + const baseUrl = draft.baseUrl?.trim() ?? ""; + const apiKey = draft.apiKey?.trim() ?? ""; + + if (!provider || !model || !baseUrl || !apiKey || draft.enabled === false) { + throw new DomainError( + "RAG_TASK_CONFIG_SCHEMA_INVALID", + "草稿配置不完整，至少需要 provider/model/baseUrl/apiKey 且 enabled=true。", + 400, + { + taskType, + checkedAgainst: "draft", + missingFields: { + provider: !provider, + model: !model, + baseUrl: !baseUrl, + apiKey: !apiKey, + enabled: draft.enabled === false + } + } + ); + } + + return { + taskType, + provider, + model, + baseUrl, + apiKey, + dimensions: + taskType === "embedding" + ? (draft.dimensions ?? persisted?.dimensions ?? this.appConfig.embeddingDimensions) + : undefined, + vectorVersion: + taskType === "embedding" + ? (draft.vectorVersion?.trim() || + persisted?.vectorVersion || + this.appConfig.embeddingVectorVersion) + : undefined, + timeoutMs: + draft.timeoutMs ?? + persisted?.timeoutMs ?? + (taskType === "embedding" + ? this.appConfig.embeddingTimeoutMs + : this.appConfig.rerankTimeoutMs), + configSource: "settings", + configId: persisted?.id + }; + } + + private mapHealthReasonCode( + error: unknown, + status: "degraded" | "failed" + ): string { + if (error instanceof DomainError) { + if (error.code === "RAG_TASK_CONFIG_SCHEMA_INVALID") { + return "schema_invalid"; + } + if ( + error.code === "EMBEDDING_PROVIDER_UNAVAILABLE" || + error.code === "RERANK_PROVIDER_UNAVAILABLE" + ) { + return "provider_unavailable"; + } + if (error.code.includes("REQUEST_TIMEOUT")) { + return "timeout"; + } + if (error.code.includes("AUTH")) { + return "auth_failed"; + } + if (error.code.includes("INVALID_PAYLOAD")) { + return "schema_invalid"; + } + if (error.code.includes("DIMENSION_MISMATCH")) { + return "dimension_mismatch"; + } + if (error.code.includes("MODEL_NOT_FOUND")) { + return "model_not_found"; + } + if (error.code.includes("RESPONSE_ERROR")) { + const statusCode = Number(error.details?.statusCode); + if (Number.isFinite(statusCode) && statusCode >= 500) { + return "provider_5xx"; + } + if (statusCode === 401 || statusCode === 403) { + return "auth_failed"; + } + if (statusCode === 404) { + return "model_not_found"; + } + } + return status === "degraded" ? "provider_unavailable" : "unexpected_error"; + } + + return status === "degraded" ? "provider_unavailable" : "unexpected_error"; + } + + private resolveHealthConfigSource( + error: unknown, + checkedAgainst: RagHealthCheckedAgainst + ): RagConfigSource { + if (checkedAgainst === "draft") { + return "settings"; + } + if (error instanceof DomainError) { + const source = error.details?.configSource; + if ( + source === "settings" || + source === "env_fallback" || + source === "missing" + ) { + return source; + } + } + return "missing"; + } + + private async resolveRuntime(taskType: RagTaskType): Promise { + const stored = await this.repository.getConfig(taskType); + const storedApiKey = stored ? await this.repository.getApiKey(taskType) : undefined; + if (stored && this.isStoredConfigUsable(stored, storedApiKey)) { + return { + taskType, + provider: stored.provider, + model: stored.model, + baseUrl: stored.baseUrl?.trim() || "", + apiKey: storedApiKey?.trim() || "", + dimensions: taskType === "embedding" ? (stored.dimensions ?? undefined) : undefined, + vectorVersion: + taskType === "embedding" + ? (stored.vectorVersion?.trim() || this.appConfig.embeddingVectorVersion) + : undefined, + timeoutMs: + stored.timeoutMs ?? + (taskType === "embedding" + ? this.appConfig.embeddingTimeoutMs + : this.appConfig.rerankTimeoutMs), + configSource: "settings", + configId: stored.id + }; + } + + const fallback = this.resolveFallback(taskType); + if (fallback.available) { + return { + taskType, + provider: fallback.provider, + model: fallback.model, + baseUrl: fallback.baseUrl, + apiKey: fallback.apiKey, + dimensions: fallback.dimensions, + vectorVersion: fallback.vectorVersion, + timeoutMs: fallback.timeoutMs, + configSource: "env_fallback" + }; + } + + const code = + taskType === "embedding" + ? "EMBEDDING_PROVIDER_UNAVAILABLE" + : "RERANK_PROVIDER_UNAVAILABLE"; + throw new DomainError(code, `${taskType} provider 配置不可用。`, 503, { + taskType, + configSource: "missing" + }); + } + + private async resolveEffectiveConfig( + taskType: RagTaskType, + prefetched?: RagTaskConfig + ): Promise { + const now = new Date().toISOString(); + const stored = prefetched ?? (await this.repository.getConfig(taskType)); + const storedApiKey = stored ? await this.repository.getApiKey(taskType) : undefined; + const fallback = this.resolveFallback(taskType); + + if (stored) { + if (this.isStoredConfigUsable(stored, storedApiKey)) { + return { + ...stored, + configSource: "settings", + configSourceNote: null + }; + } + if (fallback.available) { + return { + ...stored, + configSource: "env_fallback", + configSourceNote: stored.enabled + ? "settings_config_incomplete" + : "settings_config_disabled" + }; + } + return { + ...stored, + configSource: "missing", + configSourceNote: stored.enabled + ? "settings_config_incomplete" + : "settings_config_disabled" + }; + } + + if (fallback.available) { + return { + id: `env-fallback:${taskType}`, + taskType, + provider: fallback.provider, + model: fallback.model, + baseUrl: fallback.baseUrl, + enabled: true, + hasApiKey: true, + apiKeyMasked: this.maskApiKey(fallback.apiKey), + dimensions: fallback.dimensions, + vectorVersion: fallback.vectorVersion, + timeoutMs: fallback.timeoutMs, + note: null, + healthStatus: "unknown", + lastCheckedAt: null, + lastHealthLatencyMs: null, + lastHealthMessage: null, + lastError: null, + configSource: "env_fallback", + configSourceNote: "using_environment_fallback", + createdAt: now, + updatedAt: now + }; + } + + return { + id: `missing:${taskType}`, + taskType, + provider: taskType === "embedding" ? this.appConfig.embeddingProvider : this.appConfig.rerankProvider, + model: taskType === "embedding" ? this.appConfig.embeddingModel : this.appConfig.rerankModel, + baseUrl: null, + enabled: false, + hasApiKey: false, + apiKeyMasked: null, + dimensions: taskType === "embedding" ? (this.appConfig.embeddingDimensions ?? null) : null, + vectorVersion: + taskType === "embedding" ? this.appConfig.embeddingVectorVersion : null, + timeoutMs: + taskType === "embedding" + ? this.appConfig.embeddingTimeoutMs + : this.appConfig.rerankTimeoutMs, + note: null, + healthStatus: "unknown", + lastCheckedAt: null, + lastHealthLatencyMs: null, + lastHealthMessage: null, + lastError: null, + configSource: "missing", + configSourceNote: "no_settings_or_env_config", + createdAt: now, + updatedAt: now + }; + } + + private resolveFallback(taskType: RagTaskType): { + available: boolean; + provider: string; + model: string; + baseUrl: string; + apiKey: string; + dimensions?: number; + vectorVersion?: string; + timeoutMs: number; + } { + if (taskType === "embedding") { + const baseUrl = this.appConfig.embeddingBaseUrl.trim(); + const apiKey = this.appConfig.embeddingApiKey.trim(); + const provider = this.appConfig.embeddingProvider.trim(); + const model = this.appConfig.embeddingModel.trim(); + return { + available: Boolean(baseUrl && apiKey && provider && model), + provider, + model, + baseUrl, + apiKey, + dimensions: this.appConfig.embeddingDimensions, + vectorVersion: this.appConfig.embeddingVectorVersion, + timeoutMs: this.appConfig.embeddingTimeoutMs + }; + } + + const baseUrl = this.appConfig.rerankBaseUrl.trim(); + const apiKey = this.appConfig.rerankApiKey.trim(); + const provider = this.appConfig.rerankProvider.trim(); + const model = this.appConfig.rerankModel.trim(); + return { + available: Boolean(baseUrl && apiKey && provider && model), + provider, + model, + baseUrl, + apiKey, + timeoutMs: this.appConfig.rerankTimeoutMs + }; + } + + private isStoredConfigUsable(config: RagTaskConfig, apiKey?: string): boolean { + return Boolean( + config.enabled && + config.provider.trim().length > 0 && + config.model.trim().length > 0 && + config.baseUrl?.trim().length && + apiKey?.trim().length + ); + } + + private maskApiKey(apiKey: string): string { + const trimmed = apiKey.trim(); + if (trimmed.length <= 8) { + return `${trimmed.slice(0, 2)}***${trimmed.slice(-1)}`; + } + return `${trimmed.slice(0, 4)}***${trimmed.slice(-4)}`; + } + +} diff --git a/apps/backend/src/modules/llm/rag-task-health-probe.service.ts b/apps/backend/src/modules/llm/rag-task-health-probe.service.ts new file mode 100644 index 0000000..e8a789f --- /dev/null +++ b/apps/backend/src/modules/llm/rag-task-health-probe.service.ts @@ -0,0 +1,650 @@ +import { Injectable } from "@nestjs/common"; +import { DomainError } from "../../common/domain-error"; +import { AppConfigService } from "../config/app-config.service"; + +type ProbeStatus = "healthy" | "degraded" | "failed"; + +interface RagProbeRuntime { + provider: string; + model: string; + baseUrl: string; + apiKey: string; + timeoutMs: number; + dimensions?: number; + configSource?: string; +} + +interface RerankProbeEntry { + rank: number; + score: number; + reason: string; +} + +export interface RagTaskHealthProbeResult { + status: ProbeStatus; + reasonCode: string; + message: string; + latencyMs: number; + details?: Record; +} + +export interface RagRerankChallengeSummary { + status: "comparable" | "sample_not_ready" | "evidence_missing" | "not_comparable"; + baselineTopScore?: number; + candidateTopScore?: number; + delta?: number; + topCandidateId?: string; + reasonCode: string; +} + +export interface RagTaskRerankHealthProbeResult extends RagTaskHealthProbeResult { + challenge: RagRerankChallengeSummary; + reranked?: RerankProbeEntry[]; +} + +@Injectable() +export class RagTaskHealthProbeService { + private static readonly BUILTIN_RERANK_SAMPLES = [ + "orders amount by status", + "customer retention by month", + "finance revenue cube summary" + ]; + + constructor(private readonly appConfig: AppConfigService) {} + + async probeEmbedding(input: { + runtime: RagProbeRuntime; + expectedDimensions?: number; + sampleText?: string; + }): Promise { + const startedAt = Date.now(); + if (this.shouldMockEmbedding()) { + return this.probeEmbeddingInMockMode(input, startedAt); + } + + try { + const endpoint = this.joinEndpoint(input.runtime.baseUrl, "/embeddings"); + const response = await fetch(endpoint, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${input.runtime.apiKey}` + }, + body: JSON.stringify({ + model: input.runtime.model, + input: [input.sampleText?.trim() || "health-check-ping"], + ...(input.runtime.dimensions + ? { + dimensions: input.runtime.dimensions + } + : {}) + }), + signal: AbortSignal.timeout(input.runtime.timeoutMs) + }); + + if (!response.ok) { + return { + ...this.mapHttpStatusFailure( + response.status, + "embedding", + await this.safeReadBody(response) + ), + latencyMs: Date.now() - startedAt + }; + } + + const payload = await response.json().catch(() => ({})); + const vectors = this.readEmbeddingVectors(payload); + const vector = vectors[0]; + if (!vector || vector.length === 0) { + return { + status: "failed", + reasonCode: "schema_invalid", + message: "Embedding provider 响应未返回可用向量。", + latencyMs: Date.now() - startedAt, + details: { + outputCount: vectors.length + } + }; + } + + const actualDimensions = vector.length; + const expectedDimensions = input.expectedDimensions; + if ( + typeof expectedDimensions === "number" && + Number.isFinite(expectedDimensions) && + expectedDimensions > 0 && + actualDimensions !== expectedDimensions + ) { + return { + status: "failed", + reasonCode: "dimension_mismatch", + message: `Embedding 维度不匹配（expected=${expectedDimensions}, actual=${actualDimensions}）。`, + latencyMs: Date.now() - startedAt, + details: { + expectedDimensions, + actualDimensions + } + }; + } + if ( + typeof input.runtime.dimensions === "number" && + input.runtime.dimensions > 0 && + actualDimensions !== input.runtime.dimensions + ) { + return { + status: "failed", + reasonCode: "dimension_mismatch", + message: `Embedding 返回维度与 runtime 配置不一致（expected=${input.runtime.dimensions}, actual=${actualDimensions}）。`, + latencyMs: Date.now() - startedAt, + details: { + expectedDimensions: input.runtime.dimensions, + actualDimensions + } + }; + } + + return { + status: "healthy", + reasonCode: "ok", + message: "Embedding 配置可用。", + latencyMs: Date.now() - startedAt, + details: { + actualDimensions, + outputCount: vectors.length, + provider: input.runtime.provider, + model: input.runtime.model + } + }; + } catch (error) { + return { + ...this.mapProbeFailure(error), + latencyMs: Date.now() - startedAt + }; + } + } + + async probeRerank(input: { + runtime: RagProbeRuntime; + sampleQuery?: string; + sampleCandidates?: string[]; + }): Promise { + const startedAt = Date.now(); + const sampleQuery = input.sampleQuery?.trim() || "revenue by status"; + const sampleCandidates = this.resolveRerankSamples(input.sampleCandidates); + if (this.shouldMockRerank()) { + return this.probeRerankInMockMode({ + sampleQuery, + sampleCandidates, + startedAt + }); + } + + try { + const endpoint = this.resolveRerankEndpoint(input.runtime); + const response = await fetch(endpoint, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${input.runtime.apiKey}` + }, + body: JSON.stringify({ + model: input.runtime.model, + query: sampleQuery, + documents: sampleCandidates, + top_n: sampleCandidates.length, + return_documents: false + }), + signal: AbortSignal.timeout(input.runtime.timeoutMs) + }); + + if (!response.ok) { + const failure = this.mapHttpStatusFailure( + response.status, + "rerank", + await this.safeReadBody(response) + ); + return { + ...failure, + latencyMs: Date.now() - startedAt, + challenge: { + status: "not_comparable", + reasonCode: failure.reasonCode + } + }; + } + + const payload = await response.json().catch(() => ({})); + const reranked = this.readRerankEntries(payload, sampleCandidates.length); + if (reranked.length === 0) { + return { + status: "failed", + reasonCode: "schema_invalid", + message: "Rerank provider 响应无法解析有效排序。", + latencyMs: Date.now() - startedAt, + details: { + outputCount: 0 + }, + challenge: { + status: "evidence_missing", + reasonCode: "schema_invalid" + } + }; + } + + const top = reranked[0]; + if (!top) { + return { + status: "failed", + reasonCode: "evidence_missing", + message: "Rerank provider 未返回可比较结果。", + latencyMs: Date.now() - startedAt, + challenge: { + status: "evidence_missing", + reasonCode: "evidence_missing" + } + }; + } + + const baselineTopScore = 0; + const candidateTopScore = Number(top.score.toFixed(6)); + const delta = Number((candidateTopScore - baselineTopScore).toFixed(6)); + return { + status: "healthy", + reasonCode: "ok", + message: "Rerank 配置可用。", + latencyMs: Date.now() - startedAt, + details: { + sampleCandidateCount: sampleCandidates.length, + outputCount: reranked.length, + topCandidateId: `sample-${top.rank}` + }, + challenge: { + status: "comparable", + baselineTopScore, + candidateTopScore, + delta, + topCandidateId: `sample-${top.rank}`, + reasonCode: "comparable" + }, + reranked + }; + } catch (error) { + const mapped = this.mapProbeFailure(error); + return { + ...mapped, + latencyMs: Date.now() - startedAt, + challenge: { + status: "not_comparable", + reasonCode: mapped.reasonCode + } + }; + } + } + + private probeEmbeddingInMockMode( + input: { + runtime: RagProbeRuntime; + expectedDimensions?: number; + }, + startedAt: number + ): RagTaskHealthProbeResult { + const actualDimensions = input.runtime.dimensions ?? this.appConfig.embeddingDimensions ?? 8; + if ( + typeof input.expectedDimensions === "number" && + Number.isFinite(input.expectedDimensions) && + input.expectedDimensions > 0 && + input.expectedDimensions !== actualDimensions + ) { + return { + status: "failed", + reasonCode: "dimension_mismatch", + message: `Embedding 维度不匹配（expected=${input.expectedDimensions}, actual=${actualDimensions}）。`, + latencyMs: Date.now() - startedAt, + details: { + expectedDimensions: input.expectedDimensions, + actualDimensions + } + }; + } + + return { + status: "healthy", + reasonCode: "ok", + message: "Embedding 配置可用（mock）。", + latencyMs: Date.now() - startedAt, + details: { + actualDimensions, + mockMode: true + } + }; + } + + private probeRerankInMockMode(input: { + sampleQuery: string; + sampleCandidates: string[]; + startedAt: number; + }): RagTaskRerankHealthProbeResult { + const reranked = this.buildTokenScoredRerank(input.sampleQuery, input.sampleCandidates); + const top = reranked[0]; + if (!top) { + return { + status: "failed", + reasonCode: "evidence_missing", + message: "Rerank challenge 未返回可比较结果。", + latencyMs: Date.now() - input.startedAt, + challenge: { + status: "evidence_missing", + reasonCode: "evidence_missing" + } + }; + } + + const candidateTopScore = Number(top.score.toFixed(6)); + return { + status: "healthy", + reasonCode: "ok", + message: "Rerank 配置可用（mock）。", + latencyMs: Date.now() - input.startedAt, + details: { + sampleCandidateCount: input.sampleCandidates.length, + outputCount: reranked.length, + mockMode: true + }, + challenge: { + status: "comparable", + baselineTopScore: 0, + candidateTopScore, + delta: candidateTopScore, + topCandidateId: `sample-${top.rank}`, + reasonCode: "comparable" + }, + reranked + }; + } + + private shouldMockEmbedding(): boolean { + return ( + this.appConfig.embeddingMockMode || + (this.appConfig.llmMockMode && this.appConfig.nodeEnv === "test") + ); + } + + private shouldMockRerank(): boolean { + return ( + this.appConfig.rerankMockMode || + (this.appConfig.llmMockMode && this.appConfig.nodeEnv === "test") + ); + } + + private resolveRerankSamples(sampleCandidates?: string[]): string[] { + const normalized = (sampleCandidates ?? []) + .map((item) => item.trim()) + .filter((item) => item.length > 0) + .slice(0, 10); + if (normalized.length >= 2) { + return normalized; + } + const merged = [...normalized]; + for (const candidate of RagTaskHealthProbeService.BUILTIN_RERANK_SAMPLES) { + if (merged.length >= 3) { + break; + } + if (!merged.includes(candidate)) { + merged.push(candidate); + } + } + return merged; + } + + private buildTokenScoredRerank(query: string, candidates: string[]): RerankProbeEntry[] { + const tokens = new Set( + query + .toLowerCase() + .split(/[^a-z0-9_\p{L}\p{N}]+/u) + .map((item) => item.trim()) + .filter((item) => item.length > 0) + ); + return candidates + .map((candidate) => { + const lowered = candidate.toLowerCase(); + const tokenHits = Array.from(tokens).filter((token) => + lowered.includes(token) + ).length; + const score = Number((0.2 + tokenHits * 0.18).toFixed(6)); + return { + score: Math.max(0, Math.min(1, score)), + reason: `token_match=${tokenHits}` + }; + }) + .sort((left, right) => right.score - left.score) + .map((item, index) => ({ + rank: index + 1, + score: item.score, + reason: item.reason + })); + } + + private readEmbeddingVectors(payload: unknown): number[][] { + if (!this.isRecord(payload)) { + return []; + } + const rows = Array.isArray(payload.data) ? payload.data : []; + return rows + .map((row) => this.toVector(this.isRecord(row) ? row.embedding : undefined)) + .filter((row) => row.length > 0); + } + + private readRerankEntries(payload: unknown, maxCount: number): RerankProbeEntry[] { + if (!this.isRecord(payload)) { + return []; + } + const rows = Array.isArray(payload.results) + ? payload.results + : Array.isArray(payload.data) + ? payload.data + : []; + const parsed = rows + .map((row) => this.toRerankEntry(row)) + .filter((entry): entry is RerankProbeEntry => Boolean(entry)) + .slice(0, Math.max(1, maxCount)); + return parsed.length > 0 + ? parsed + .sort((left, right) => right.score - left.score) + .map((entry, index) => ({ + ...entry, + rank: index + 1 + })) + : []; + } + + private toRerankEntry(value: unknown): RerankProbeEntry | undefined { + if (!this.isRecord(value)) { + return undefined; + } + const score = this.readScore(value); + if (!Number.isFinite(score)) { + return undefined; + } + const reasonRaw = value.reason; + const reason = + typeof reasonRaw === "string" && reasonRaw.trim().length > 0 + ? reasonRaw.trim() + : "provider_rerank"; + return { + rank: 0, + score: Math.max(0, Math.min(1, score)), + reason + }; + } + + private readScore(value: Record): number { + if (typeof value.score === "number" && Number.isFinite(value.score)) { + return value.score; + } + if ( + typeof value.relevance_score === "number" && + Number.isFinite(value.relevance_score) + ) { + return value.relevance_score; + } + return Number.NaN; + } + + private toVector(value: unknown): number[] { + if (!Array.isArray(value)) { + return []; + } + return value + .map((item) => Number(item)) + .filter((item) => Number.isFinite(item)); + } + + private resolveRerankEndpoint(runtime: RagProbeRuntime): string { + if (runtime.provider === "tongyi" && !runtime.baseUrl.includes("/compatible-mode/")) { + return this.joinEndpoint(runtime.baseUrl, "/services/rerank/text-rerank/text-rerank"); + } + return this.joinEndpoint(runtime.baseUrl, "/rerank"); + } + + private joinEndpoint(baseUrl: string, path: string): string { + return `${baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`; + } + + private async safeReadBody(response: Response): Promise { + const raw = await response.text().catch(() => ""); + return raw.slice(0, 500); + } + + private mapHttpStatusFailure( + statusCode: number, + operation: "embedding" | "rerank", + bodySnippet: string + ): Omit { + if (statusCode === 401 || statusCode === 403) { + return { + status: "failed", + reasonCode: "auth_failed", + message: `${operation} provider 鉴权失败（${statusCode}）。`, + details: { + statusCode, + body: bodySnippet + } + }; + } + if (statusCode === 404) { + return { + status: "failed", + reasonCode: "model_not_found", + message: `${operation} provider 模型或端点不存在（404）。`, + details: { + statusCode, + body: bodySnippet + } + }; + } + if (statusCode >= 500) { + return { + status: "degraded", + reasonCode: "provider_5xx", + message: `${operation} provider 服务异常（${statusCode}）。`, + details: { + statusCode, + body: bodySnippet + } + }; + } + return { + status: "failed", + reasonCode: "schema_invalid", + message: `${operation} provider 返回不可用响应（${statusCode}）。`, + details: { + statusCode, + body: bodySnippet + } + }; + } + + private mapProbeFailure(error: unknown): Omit { + if (error instanceof DomainError) { + if ( + error.code === "EMBEDDING_PROVIDER_UNAVAILABLE" || + error.code === "RERANK_PROVIDER_UNAVAILABLE" + ) { + return { + status: "degraded", + reasonCode: "provider_unavailable", + message: error.message, + details: { + code: error.code + } + }; + } + if (error.code.includes("TIMEOUT")) { + return { + status: "degraded", + reasonCode: "timeout", + message: error.message, + details: { + code: error.code + } + }; + } + if (error.code.includes("AUTH")) { + return { + status: "failed", + reasonCode: "auth_failed", + message: error.message, + details: { + code: error.code + } + }; + } + return { + status: "failed", + reasonCode: "unexpected_error", + message: error.message, + details: { + code: error.code + } + }; + } + + if ( + error instanceof Error && + (error.name === "TimeoutError" || error.name === "AbortError") + ) { + return { + status: "degraded", + reasonCode: "timeout", + message: `RAG 健康检查超时: ${error.message}` + }; + } + + if (error instanceof TypeError) { + return { + status: "degraded", + reasonCode: "endpoint_unreachable", + message: `RAG 健康检查网络不可达: ${error.message}` + }; + } + + if (error instanceof Error) { + return { + status: "failed", + reasonCode: "unexpected_error", + message: error.message + }; + } + + return { + status: "failed", + reasonCode: "unexpected_error", + message: "RAG 健康检查失败。" + }; + } + + private isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); + } +} diff --git a/apps/backend/src/modules/llm/rerank-router.service.ts b/apps/backend/src/modules/llm/rerank-router.service.ts new file mode 100644 index 0000000..b665941 --- /dev/null +++ b/apps/backend/src/modules/llm/rerank-router.service.ts @@ -0,0 +1,295 @@ +import { Injectable } from "@nestjs/common"; +import { DomainError } from "../../common/domain-error"; +import { AppConfigService } from "../config/app-config.service"; +import { LlmGatewayService } from "./llm-gateway.service"; +import type { LlmGatewayPrompt } from "./llm-gateway.interface"; +import { + type RerankCandidateInput, + type RerankCandidateResult, + type RerankCandidatesResponse +} from "./provider-router.service"; +import { RagTaskConfigService } from "./rag-task-config.service"; + +@Injectable() +export class RerankRouterService { + constructor( + private readonly config: AppConfigService, + private readonly llmGateway: LlmGatewayService, + private readonly ragTaskConfigService: RagTaskConfigService + ) {} + + async rerankCandidates(input: { + query: string; + candidates: RerankCandidateInput[]; + }): Promise { + const response = await this.rerankCandidatesWithMetadata(input); + return response.results; + } + + async rerankCandidatesWithMetadata(input: { + query: string; + candidates: RerankCandidateInput[]; + }): Promise { + if (input.candidates.length === 0) { + return { + results: [], + metadata: { + mode: this.config.rerankMockMode ? "mock" : "provider", + provider: this.config.rerankProvider, + model: this.config.rerankModel, + configSource: "missing", + inputCount: 0, + outputCount: 0 + } + }; + } + + const testScopedMockMode = this.config.llmMockMode && this.config.nodeEnv === "test"; + if (this.config.rerankMockMode || testScopedMockMode) { + const results = this.rerankInMockMode(input.query, input.candidates); + return { + results, + metadata: { + mode: "mock", + provider: `${this.config.rerankProvider}:mock`, + model: this.config.rerankModel, + configSource: "env_fallback", + inputCount: input.candidates.length, + outputCount: results.length, + fallbackReason: this.config.rerankMockMode + ? "rerank_mock_mode" + : "llm_mock_mode" + } + }; + } + + const runtime = await this.ragTaskConfigService.resolveRerankRuntime(); + const prompt: LlmGatewayPrompt = { + systemPrompt: + "You are a retrieval reranker. Return strict JSON only.", + userPrompt: JSON.stringify( + { + task: "rerank_candidates", + query: input.query, + outputSchema: { + reranked: [ + { + candidateId: "string", + score: "number between 0 and 1", + reason: "short reason" + } + ] + }, + candidates: input.candidates.map((candidate) => ({ + candidateId: candidate.candidateId, + domain: candidate.domain, + sourceLane: candidate.sourceLane, + baseScore: candidate.baseScore, + evidence: candidate.evidence.slice(0, 3), + contentPreview: candidate.content.slice(0, 400) + })) + }, + null, + 2 + ) + }; + + const completion = await this.llmGateway.generate(prompt, { + provider: runtime.provider, + model: runtime.model, + baseUrl: runtime.baseUrl, + apiKey: runtime.apiKey, + timeoutMs: runtime.timeoutMs + }); + const parsed = this.parseRerankResponse(completion.rawText); + if (parsed.length === 0) { + throw new DomainError( + "RERANK_PROVIDER_INVALID_PAYLOAD", + "Rerank provider 未返回有效排序结果。", + 502, + { + provider: completion.provider, + model: completion.model, + configSource: runtime.configSource, + inputCount: input.candidates.length + } + ); + } + this.assertProviderCandidateCoverage(parsed, input.candidates, { + provider: completion.provider, + model: completion.model, + configSource: runtime.configSource + }); + return { + results: parsed, + metadata: { + mode: "provider", + provider: completion.provider, + model: completion.model, + configSource: runtime.configSource, + configId: runtime.configId, + inputCount: input.candidates.length, + outputCount: parsed.length + } + }; + } + + private rerankInMockMode( + query: string, + candidates: RerankCandidateInput[] + ): RerankCandidateResult[] { + const tokens = this.extractTokens(query); + return candidates.map((candidate) => { + const content = candidate.content.toLowerCase(); + const tokenMatch = tokens.filter((token) => content.includes(token)).length; + const domainBoost = + candidate.domain === "semantic_term" + ? 0.12 + : candidate.domain === "schema" + ? 0.08 + : 0.05; + const score = Math.max( + 0, + Math.min(1, Number((candidate.baseScore * 0.6 + tokenMatch * 0.12 + domainBoost).toFixed(6))) + ); + return { + candidateId: candidate.candidateId, + score, + reason: `mock rerank tokenMatch=${tokenMatch} domain=${candidate.domain}` + }; + }); + } + + private parseRerankResponse(rawText: string): RerankCandidateResult[] { + const normalized = rawText.trim(); + if (!normalized) { + return []; + } + const jsonCandidate = this.extractJsonBlock(normalized); + if (!jsonCandidate) { + return []; + } + try { + const parsed = JSON.parse(jsonCandidate) as unknown; + const rows = Array.isArray(parsed) + ? parsed + : this.isRecord(parsed) && Array.isArray(parsed.reranked) + ? parsed.reranked + : []; + return rows + .map((row) => this.toRerankResult(row)) + .filter((row): row is RerankCandidateResult => Boolean(row)); + } catch { + return []; + } + } + + private toRerankResult(row: unknown): RerankCandidateResult | undefined { + if (!this.isRecord(row)) { + return undefined; + } + const candidateId = + typeof row.candidateId === "string" ? row.candidateId.trim() : ""; + const score = Number(row.score); + const reason = typeof row.reason === "string" ? row.reason.trim() : ""; + if (!candidateId || !Number.isFinite(score)) { + return undefined; + } + return { + candidateId, + score: Math.max(0, Math.min(1, score)), + reason: reason || "model_rerank" + }; + } + + private extractJsonBlock(text: string): string | undefined { + const fencedMatch = text.match(/```json\s*([\s\S]*?)```/i); + if (fencedMatch?.[1]) { + return fencedMatch[1].trim(); + } + if (text.startsWith("{") || text.startsWith("[")) { + return text; + } + const firstBrace = text.indexOf("{"); + const firstBracket = text.indexOf("["); + const startIndexCandidates = [firstBrace, firstBracket].filter( + (index) => index >= 0 + ); + if (startIndexCandidates.length === 0) { + return undefined; + } + const startIndex = Math.min(...startIndexCandidates); + return text.slice(startIndex).trim(); + } + + private extractTokens(value: string): string[] { + const tokens = value + .toLowerCase() + .match(/[a-z0-9_\p{L}\p{N}]+/gu); + if (!tokens) { + return []; + } + return Array.from(new Set(tokens.filter((token) => token.trim().length > 0))); + } + + private assertProviderCandidateCoverage( + parsed: RerankCandidateResult[], + candidates: RerankCandidateInput[], + metadata: { + provider: string; + model: string; + configSource: "settings" | "env_fallback" | "missing"; + } + ): void { + const candidateIds = new Set(candidates.map((candidate) => candidate.candidateId)); + const parsedIds = parsed.map((item) => item.candidateId); + const duplicateIds = parsedIds.filter( + (candidateId, index) => parsedIds.indexOf(candidateId) !== index + ); + if (duplicateIds.length > 0) { + throw new DomainError( + "RERANK_PROVIDER_INVALID_PAYLOAD", + "Rerank provider 返回重复 candidateId。", + 502, + { + provider: metadata.provider, + model: metadata.model, + configSource: metadata.configSource, + duplicateCandidateIds: Array.from(new Set(duplicateIds)).slice(0, 20) + } + ); + } + const unknownCandidateIds = parsedIds.filter((candidateId) => !candidateIds.has(candidateId)); + if (unknownCandidateIds.length > 0) { + throw new DomainError( + "RERANK_PROVIDER_INVALID_PAYLOAD", + "Rerank provider 返回未知 candidateId。", + 502, + { + provider: metadata.provider, + model: metadata.model, + configSource: metadata.configSource, + unknownCandidateIds: Array.from(new Set(unknownCandidateIds)).slice(0, 20) + } + ); + } + if (parsed.length !== candidates.length) { + throw new DomainError( + "RERANK_PROVIDER_OUTPUT_COUNT_MISMATCH", + "Rerank provider 返回结果数量与候选数量不一致。", + 502, + { + provider: metadata.provider, + model: metadata.model, + configSource: metadata.configSource, + expected: candidates.length, + actual: parsed.length + } + ); + } + } + + private isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); + } +} diff --git a/apps/backend/src/modules/platform/data/persistence.module.ts b/apps/backend/src/modules/platform/data/persistence.module.ts index 86271cf..76d3e1f 100644 --- a/apps/backend/src/modules/platform/data/persistence.module.ts +++ b/apps/backend/src/modules/platform/data/persistence.module.ts @@ -6,6 +6,7 @@ import { AuditLogRepository } from "../../data/persistence/audit-log.repository" import { ChatRepository } from "../../data/persistence/chat.repository"; import { DatasourceRepository } from "../../data/persistence/datasource.repository"; import { LlmConfigRepository } from "../../data/persistence/llm-config.repository"; +import { RagTaskConfigRepository } from "../../data/persistence/rag-task-config.repository"; import { UserRepository } from "../../data/persistence/user.repository"; import { WorkspaceRepository } from "../../data/persistence/workspace.repository"; import { WorkspaceDatasourcePolicyRepository } from "../../data/persistence/workspace-datasource-policy.repository"; @@ -26,6 +27,7 @@ import { ModelingGraphValidator } from "./persistence/modeling-graph.validator"; ModelingGraphValidator, AuditLogRepository, LlmConfigRepository, + RagTaskConfigRepository, UserRepository, WorkspaceRepository ], @@ -40,6 +42,7 @@ import { ModelingGraphValidator } from "./persistence/modeling-graph.validator"; ModelingGraphValidator, AuditLogRepository, LlmConfigRepository, + RagTaskConfigRepository, UserRepository, WorkspaceRepository ] diff --git a/apps/backend/src/modules/platform/data/persistence/index.ts b/apps/backend/src/modules/platform/data/persistence/index.ts index fe6143e..4a6d333 100644 --- a/apps/backend/src/modules/platform/data/persistence/index.ts +++ b/apps/backend/src/modules/platform/data/persistence/index.ts @@ -2,6 +2,7 @@ export { AuditLogRepository } from "../../../data/persistence/audit-log.reposito export { ChatRepository } from "../../../data/persistence/chat.repository"; export { DatasourceRepository } from "../../../data/persistence/datasource.repository"; export { LlmConfigRepository } from "../../../data/persistence/llm-config.repository"; +export { RagTaskConfigRepository } from "../../../data/persistence/rag-task-config.repository"; export { UserRepository } from "../../../data/persistence/user.repository"; export { WorkspaceDatasourcePolicyRepository } from "../../../data/persistence/workspace-datasource-policy.repository"; export { WorkspaceRepository } from "../../../data/persistence/workspace.repository"; diff --git a/apps/backend/src/modules/platform/data/query/index.ts b/apps/backend/src/modules/platform/data/query/index.ts index cfd7a19..831a30a 100644 --- a/apps/backend/src/modules/platform/data/query/index.ts +++ b/apps/backend/src/modules/platform/data/query/index.ts @@ -1,4 +1,5 @@ export { QueryExecutorRouterService } from "../../../data/query/query-executor-router.service"; +export { SqliteQueryService } from "../../../data/sqlite/sqlite-query.service"; export { SqlTableAccessGuardService, type SqlTableAccessContext diff --git a/apps/backend/src/modules/platform/data/query/relationship-dry-run.service.ts b/apps/backend/src/modules/platform/data/query/relationship-dry-run.service.ts index a981fe9..66cde51 100644 --- a/apps/backend/src/modules/platform/data/query/relationship-dry-run.service.ts +++ b/apps/backend/src/modules/platform/data/query/relationship-dry-run.service.ts @@ -13,6 +13,12 @@ export interface RelationshipDryRunResult { }>; } +export interface RelationshipDryPlanSnapshot { + pass: boolean; + missingTables: string[]; + reason?: string; +} + const MAX_SAMPLE_COUNT = 20; const MAX_SQL_LENGTH = 2000; @@ -73,6 +79,46 @@ export class RelationshipDryRunService { }; } + evaluateJoinPathConsistency(input: { + sql: string; + selectedTables?: string[]; + joinPath?: string[]; + }): RelationshipDryPlanSnapshot { + const selectedTables = this.normalizeIdentifiers(input.selectedTables ?? []); + const joinPath = this.normalizeJoinPath(input.joinPath ?? []); + if (selectedTables.length <= 1 && joinPath.length === 0) { + return { + pass: true, + missingTables: [] + }; + } + + const referencedTables = this.extractTables(input.sql); + const missingTables = selectedTables.filter( + (table) => !referencedTables.includes(table) + ); + if (missingTables.length > 0) { + return { + pass: false, + missingTables, + reason: `missing tables from relationship plan: ${missingTables.join(", ")}` + }; + } + + if (joinPath.length > 0 && !/\bjoin\b/i.test(input.sql)) { + return { + pass: false, + missingTables: selectedTables, + reason: "join path exists but SQL has no JOIN keyword" + }; + } + + return { + pass: true, + missingTables: [] + }; + } + private normalizeSqlSamples(sqlSamples: string[]): string[] { const normalized = sqlSamples .map((item) => item.trim().replace(/;\s*$/, "")) @@ -84,4 +130,42 @@ export class RelationshipDryRunService { } return normalized; } + + private extractTables(sql: string): string[] { + const matches = [ + ...sql.matchAll(/\b(?:from|join)\s+([a-zA-Z_][\w$]*(?:\.[a-zA-Z_][\w$]*)?)/gi) + ]; + const tables = matches + .map((match) => this.normalizeIdentifier(match[1])) + .filter((value): value is string => Boolean(value)); + return Array.from(new Set(tables)); + } + + private normalizeJoinPath(values: string[]): string[] { + return Array.from( + new Set(values.map((value) => value.trim()).filter((value) => value.length > 0)) + ); + } + + private normalizeIdentifiers(values: string[]): string[] { + return Array.from( + new Set( + values + .map((value) => this.normalizeIdentifier(value)) + .filter((value): value is string => Boolean(value)) + ) + ); + } + + private normalizeIdentifier(value: string | undefined): string | undefined { + if (!value) { + return undefined; + } + const normalized = value + .trim() + .replace(/^[`"'\[\]]+|[`"'\[\]]+$/g, "") + .replace(/\s+/g, "") + .toLowerCase(); + return normalized.length > 0 ? normalized : undefined; + } } diff --git a/apps/backend/src/modules/platform/read-model/run-view-support.guard.ts b/apps/backend/src/modules/platform/read-model/run-view-support.guard.ts new file mode 100644 index 0000000..6a6c871 --- /dev/null +++ b/apps/backend/src/modules/platform/read-model/run-view-support.guard.ts @@ -0,0 +1,71 @@ +import type { SqlRun } from "@text2sql/shared-types"; +import { DomainError } from "../../../common/domain-error"; + +interface V2TraceStageShape { + stage?: unknown; +} + +interface RunReadModelTraceShape { + v2?: { + version?: unknown; + stageOrder?: unknown; + stages?: unknown; + }; +} + +type SupportedV2ReadRun = Pick | { + runId: string; + trace?: RunReadModelTraceShape; +}; + +export interface AssertSupportedV2RunReadOptions { + unsupportedMessage: string; +} + +const LEGACY_REQUIRED_MARKERS = { + version: "run.trace.v2.version === 'v2'", + stageOrder: "run.trace.v2.stageOrder.length > 0", + stageArtifacts: "run.trace.v2.stages.length > 0" +} as const; + +export function assertSupportedV2RunReadModel( + run: SupportedV2ReadRun, + options: AssertSupportedV2RunReadOptions +): void { + if (isSupportedV2RunReadModel(run)) { + return; + } + throw new DomainError( + "LEGACY_RUN_UNSUPPORTED", + options.unsupportedMessage, + 410, + { + runId: run.runId, + expectedContract: "text2sql-v2-read-model", + requiredMarkers: LEGACY_REQUIRED_MARKERS, + migrationRunbook: "docs/runbooks/text2sql-v2-hardcut-read-model-migration.md" + } + ); +} + +export function isSupportedV2RunReadModel(run: Pick): boolean { + const traceV2 = run.trace?.v2; + if (!traceV2 || traceV2.version !== "v2") { + return false; + } + const stageOrder = traceV2.stageOrder; + if (!Array.isArray(stageOrder) || stageOrder.length === 0) { + return false; + } + const stages = traceV2.stages; + if (!Array.isArray(stages) || stages.length === 0) { + return false; + } + return stages.every( + (stage): stage is V2TraceStageShape => + typeof stage === "object" && + stage !== null && + typeof (stage as V2TraceStageShape).stage === "string" && + stageOrder.includes((stage as V2TraceStageShape).stage as string) + ); +} diff --git a/apps/backend/src/modules/rag/audit/rag-audit-replay.service.ts b/apps/backend/src/modules/rag/audit/rag-audit-replay.service.ts index 1bd89f1..e7421c4 100644 --- a/apps/backend/src/modules/rag/audit/rag-audit-replay.service.ts +++ b/apps/backend/src/modules/rag/audit/rag-audit-replay.service.ts @@ -1,5 +1,6 @@ import type { ExecutionTrace } from "@text2sql/shared-types"; import { Injectable } from "@nestjs/common"; +import { assertSupportedV2RunReadModel } from "../../platform/read-model/run-view-support.guard"; import { AuditLogRepository, ChatRepository @@ -137,6 +138,13 @@ export class RagAuditReplayService { resolvedRunId ? this.ragReplayRepository.listByRunId(resolvedRunId) : Promise.resolve([]), resolvedRunId ? this.chatRepository.getRunById(resolvedRunId) : Promise.resolve(undefined) ]); + let runTrace: ExecutionTrace | undefined; + if (run && requestedRunId) { + assertSupportedV2RunReadModel(run, { + unsupportedMessage: "该运行记录为历史兼容结构，需迁移后才能回放审计链路。" + }); + runTrace = run.trace; + } const fromAt = this.parseTimestamp(input.fromAt); const toAt = this.parseTimestamp(input.toAt); @@ -202,7 +210,7 @@ export class RagAuditReplayService { return { runId: resolvedRunId, requestId: requestedRequestId || undefined, - runTrace: run?.trace, + runTrace, events, generatedAt: new Date().toISOString() }; @@ -577,4 +585,5 @@ export class RagAuditReplayService { } return true; } + } diff --git a/apps/backend/src/modules/rag/index/rag-index-builder.service.ts b/apps/backend/src/modules/rag/index/rag-index-builder.service.ts index 80c2704..60063b4 100644 --- a/apps/backend/src/modules/rag/index/rag-index-builder.service.ts +++ b/apps/backend/src/modules/rag/index/rag-index-builder.service.ts @@ -1,6 +1,7 @@ import { createHash } from "node:crypto"; import { Injectable } from "@nestjs/common"; import { DomainError } from "../../../common/domain-error"; +import { EmbeddingRouterService } from "../../llm/embedding-router.service"; import { type RagChunkBuildInput, type RagChunkIndexEntryRecord, @@ -22,12 +23,22 @@ export interface RagIndexBuildResult { status: "active"; entryCount: number; archivedChannels: Array<"lexical" | "dense">; - denseMode: "placeholder_vector_string"; + denseMode: "external_provider" | "mock_provider" | "dense_unavailable"; + denseUnavailableReason?: string; + denseProvider?: string; + denseModel?: string; + denseConfigSource?: "settings" | "env_fallback" | "missing"; + denseDimensions?: number; + vectorVersion?: string; + indexVersion?: string; } @Injectable() export class RagIndexBuilderService { - constructor(private readonly repository: RagIndexRepository) {} + constructor( + private readonly repository: RagIndexRepository, + private readonly embeddingRouter: EmbeddingRouterService + ) {} async buildAndActivate(input: RagIndexBuildRequest): Promise { const chunks = @@ -52,7 +63,18 @@ export class RagIndexBuilderService { try { const now = new Date().toISOString(); - const entries = chunks.map((chunk) => this.toIndexEntry(chunk, version.id, now)); + const denseEmbedding = await this.resolveDenseEmbedding({ + chunks, + indexVersionId: version.id + }); + const entries = chunks.map((chunk) => + this.toIndexEntry({ + chunk, + indexVersionId: version.id, + timestamp: now, + denseEmbedding + }) + ); await this.repository.replaceEntriesForVersion(version.id, entries); await this.repository.markVersionReady(version.id); @@ -69,7 +91,14 @@ export class RagIndexBuilderService { status: "active", entryCount: archived.length, archivedChannels: ["lexical", "dense"], - denseMode: "placeholder_vector_string" + denseMode: denseEmbedding.mode, + denseUnavailableReason: denseEmbedding.unavailableReason, + denseProvider: denseEmbedding.metadata?.provider, + denseModel: denseEmbedding.metadata?.model, + denseConfigSource: denseEmbedding.metadata?.configSource, + denseDimensions: denseEmbedding.metadata?.dimensions, + vectorVersion: denseEmbedding.metadata?.vectorVersion, + indexVersion: denseEmbedding.metadata?.indexVersion }; } catch (error) { await this.safeDeprecate(version.id); @@ -77,11 +106,13 @@ export class RagIndexBuilderService { } } - private toIndexEntry( - chunk: RagChunkBuildInput, - indexVersionId: string, - timestamp: string - ): RagChunkIndexEntryRecord { + private toIndexEntry(input: { + chunk: RagChunkBuildInput; + indexVersionId: string; + timestamp: string; + denseEmbedding: DenseEmbeddingResolution; + }): RagChunkIndexEntryRecord { + const { chunk, indexVersionId, timestamp, denseEmbedding } = input; const lexicalContent = chunk.content.trim(); if (!lexicalContent) { throw new DomainError("RAG_INDEX_EMPTY_CHUNK", "切块内容为空，无法构建索引条目。", 400, { @@ -97,8 +128,12 @@ export class RagIndexBuilderService { datasourceId: chunk.datasourceId, domain: chunk.domain, lexicalContent, - denseVector: this.buildPlaceholderDenseVector(lexicalContent), - metadata: this.buildEntryMetadata(chunk.metadata), + denseVector: denseEmbedding.vectorsByChunkId.get(chunk.id), + metadata: this.buildEntryMetadata({ + rawMetadata: chunk.metadata, + denseEmbedding, + chunkDomain: chunk.domain + }), createdAt: timestamp, updatedAt: timestamp }; @@ -110,27 +145,34 @@ export class RagIndexBuilderService { .digest("hex"); } - private buildPlaceholderDenseVector(content: string): string { - const digest = createHash("sha256").update(content).digest(); - const dimensions = 8; - const vector = Array.from({ length: dimensions }, (_, index) => { - const byte = digest[index] ?? 0; - const normalized = byte / 255; - const scaled = normalized * 2 - 1; - return Number(scaled.toFixed(6)); - }); - return JSON.stringify(vector); - } - - private buildEntryMetadata(rawMetadata?: string): string { + private buildEntryMetadata(input: { + rawMetadata?: string; + denseEmbedding: DenseEmbeddingResolution; + chunkDomain: string; + }): string { + const { rawMetadata, denseEmbedding, chunkDomain } = input; const sourceMetadata = rawMetadata && rawMetadata.trim().length > 0 ? this.safeParseJson(rawMetadata) : undefined; + const denseMetadata = { + mode: denseEmbedding.mode, + provider: denseEmbedding.metadata?.provider, + model: denseEmbedding.metadata?.model, + dimensions: denseEmbedding.metadata?.dimensions, + vectorVersion: denseEmbedding.metadata?.vectorVersion, + indexVersion: denseEmbedding.metadata?.indexVersion, + scope: denseEmbedding.metadata?.scope ?? "datasource", + assetType: chunkDomain, + configSource: denseEmbedding.metadata?.configSource, + unavailableReason: denseEmbedding.unavailableReason + }; + return JSON.stringify({ - denseMode: "placeholder_vector_string", + denseMode: denseEmbedding.mode, lexicalMode: "plain_text", + dense: denseMetadata, ...(sourceMetadata ? { sourceMetadata } : {}) }); } @@ -150,4 +192,70 @@ export class RagIndexBuilderService { } await this.repository.markVersionDeprecated(indexVersionId); } + + private async resolveDenseEmbedding(input: { + chunks: RagChunkBuildInput[]; + indexVersionId: string; + }): Promise { + const texts = input.chunks.map((chunk) => chunk.content.trim()); + try { + const embeddings = await this.embeddingRouter.embed({ + texts, + indexVersion: input.indexVersionId, + scope: "datasource", + assetType: "rag_chunk" + }); + if (embeddings.length !== input.chunks.length) { + return { + mode: "dense_unavailable", + vectorsByChunkId: new Map(), + unavailableReason: "dense_unavailable_embedding_count_mismatch" + }; + } + + const vectorsByChunkId = new Map(); + for (let index = 0; index < input.chunks.length; index += 1) { + const chunk = input.chunks[index]; + const vector = embeddings[index]?.vector; + if (!Array.isArray(vector) || vector.length === 0) { + continue; + } + vectorsByChunkId.set(chunk.id, JSON.stringify(vector)); + } + const metadata = embeddings[0]?.metadata; + const mode: DenseEmbeddingResolution["mode"] = metadata?.provider.endsWith(":mock") + ? "mock_provider" + : "external_provider"; + return { + mode, + vectorsByChunkId, + metadata + }; + } catch (error) { + const unavailableReason = + error instanceof DomainError + ? error.code.toLowerCase() + : "dense_unavailable_provider_error"; + return { + mode: "dense_unavailable", + vectorsByChunkId: new Map(), + unavailableReason + }; + } + } +} + +interface DenseEmbeddingResolution { + mode: "external_provider" | "mock_provider" | "dense_unavailable"; + vectorsByChunkId: Map; + unavailableReason?: string; + metadata?: { + provider: string; + model: string; + dimensions: number; + vectorVersion: string; + configSource?: "settings" | "env_fallback" | "missing"; + indexVersion?: string; + scope?: string; + }; } diff --git a/apps/backend/src/modules/rag/perf/rag-budget-policy.ts b/apps/backend/src/modules/rag/perf/rag-budget-policy.ts index 3b7e9d1..3754078 100644 --- a/apps/backend/src/modules/rag/perf/rag-budget-policy.ts +++ b/apps/backend/src/modules/rag/perf/rag-budget-policy.ts @@ -21,6 +21,25 @@ export interface RagRerankBudgetDecision { degraded: boolean; } +export interface RagPruningDecisionInput { + budgetSource: "retrieval_budget" | "rerank_budget" | "context_pack"; + decisionReasons: string[]; + removedEvidenceIds: string[]; + keptEvidenceIds: string[]; +} + +export interface RagPruningDecision { + budget_source: "retrieval_budget" | "rerank_budget" | "context_pack"; + removed_evidence_ids: string[]; + kept_evidence_ids: string[]; + reason_codes: string[]; + summary: string; + budgetSource: "retrieval_budget" | "rerank_budget" | "context_pack"; + removedEvidenceIds: string[]; + keptEvidenceIds: string[]; + reasonCodes: string[]; +} + const DEFAULT_PRESSURE_DEGRADE_THRESHOLD = 0.8; const DEFAULT_PRESSURE_EXTREME_THRESHOLD = 0.95; const ALL_RETRIEVAL_LANES: Array<"lexical" | "dense" | "graph"> = [ @@ -140,6 +159,27 @@ export class RagBudgetPolicy { }; } + describePruningDecision(input: RagPruningDecisionInput): RagPruningDecision | undefined { + const reasonCodes = this.unique(input.decisionReasons); + if (reasonCodes.length === 0 && input.removedEvidenceIds.length === 0) { + return undefined; + } + const summary = `${input.budgetSource}:removed=${input.removedEvidenceIds.length},kept=${input.keptEvidenceIds.length},reasons=${ + reasonCodes.join("|") || "none" + }`; + return { + budget_source: input.budgetSource, + removed_evidence_ids: this.unique(input.removedEvidenceIds), + kept_evidence_ids: this.unique(input.keptEvidenceIds), + reason_codes: reasonCodes, + summary, + budgetSource: input.budgetSource, + removedEvidenceIds: this.unique(input.removedEvidenceIds), + keptEvidenceIds: this.unique(input.keptEvidenceIds), + reasonCodes: reasonCodes + }; + } + private normalizeSignal(signal: RagBudgetSignal | undefined): Required { const normalize = (value: number | undefined): number => { if (typeof value !== "number" || !Number.isFinite(value)) { diff --git a/apps/backend/src/modules/rag/rerank/model-reranker.adapter.ts b/apps/backend/src/modules/rag/rerank/model-reranker.adapter.ts index d45054d..b9500f1 100644 --- a/apps/backend/src/modules/rag/rerank/model-reranker.adapter.ts +++ b/apps/backend/src/modules/rag/rerank/model-reranker.adapter.ts @@ -1,9 +1,10 @@ import { Injectable } from "@nestjs/common"; import { - ProviderRouterService, type RerankCandidateInput, - type RerankCandidateResult + type RerankCandidateResult, + type RerankCandidatesResponse } from "../../llm/provider-router.service"; +import { RerankRouterService } from "../../llm/rerank-router.service"; export interface ModelRerankRequest { query: string; @@ -11,15 +12,21 @@ export interface ModelRerankRequest { modelCatalogId?: string; } +export type ModelRerankResponse = RerankCandidatesResponse; + @Injectable() export class ModelRerankerAdapter { - constructor(private readonly providerRouter: ProviderRouterService) {} + constructor(private readonly rerankRouter: RerankRouterService) {} async rerank(input: ModelRerankRequest): Promise { - return this.providerRouter.rerankCandidates({ + const response = await this.rerankWithMetadata(input); + return response.results; + } + + async rerankWithMetadata(input: ModelRerankRequest): Promise { + return this.rerankRouter.rerankCandidatesWithMetadata({ query: input.query, - candidates: input.candidates, - modelCatalogId: input.modelCatalogId + candidates: input.candidates }); } } diff --git a/apps/backend/src/modules/rag/rerank/rag-rerank.service.ts b/apps/backend/src/modules/rag/rerank/rag-rerank.service.ts index 5724204..8783c60 100644 --- a/apps/backend/src/modules/rag/rerank/rag-rerank.service.ts +++ b/apps/backend/src/modules/rag/rerank/rag-rerank.service.ts @@ -1,4 +1,5 @@ import { Injectable } from "@nestjs/common"; +import { DomainError } from "../../../common/domain-error"; import { RagReplayRepository } from "../observability/rag-replay.repository"; import { RagBudgetPolicy } from "../perf/rag-budget-policy"; import { RagCacheKeyFactory } from "../perf/rag-cache-key.factory"; @@ -6,8 +7,10 @@ import { RagQueryCacheService } from "../perf/rag-query-cache.service"; import { RagQualityService } from "../quality/rag-quality.service"; import { type RagBudgetSignal, + type RagRerankStageMetadata, type RagRetrievalBundle, type RagRetrievalCandidate, + type RagRetrievalChunkPayload, type RagRerankedCandidate } from "../retrieval/rag-retrieval.types"; import { ModelRerankerAdapter } from "./model-reranker.adapter"; @@ -34,6 +37,55 @@ const DEFAULT_SELECTED_CONTEXT_LIMIT = 6; const RERANK_CACHE_L1_TTL_MS = 20_000; const RERANK_CACHE_L2_TTL_MS = 3 * 60_000; +interface SecondaryRerankExecution { + scores: Record; + metadata: RagRerankStageMetadata; +} + +interface RerankContextPackLaneMetadata { + lane: "rerank"; + state: "ready" | "degraded" | "unavailable" | "skipped"; + provider?: string; + model?: string; + input_count?: number; + output_count?: number; + selected_count?: number; + timeout_ms?: number; + unavailable_reason?: string; + fallback_reason?: string; + evidence_ids?: string[]; + reason_codes?: string[]; + inputCount?: number; + outputCount?: number; + selectedCount?: number; + timeoutMs?: number; + unavailableReason?: string; + fallbackReason?: string; + evidenceIds?: string[]; + reasonCodes?: string[]; +} + +interface RerankContextPackPruningDecision { + budget_source: "rerank_budget"; + removed_evidence_ids: string[]; + kept_evidence_ids: string[]; + reason_codes: string[]; + summary?: string; + budgetSource?: "rerank_budget"; + removedEvidenceIds?: string[]; + keptEvidenceIds?: string[]; + reasonCodes?: string[]; +} + +interface ExtendedRagContextPack extends NonNullable { + lane_metadata?: RerankContextPackLaneMetadata[]; + laneMetadata?: RerankContextPackLaneMetadata[]; + pruning_decisions?: RerankContextPackPruningDecision[]; + pruningDecisions?: RerankContextPackPruningDecision[]; + selected_context_lanes?: string[]; + selectedContextLanes?: string[]; +} + @Injectable() export class RagRerankService { constructor( @@ -110,50 +162,99 @@ export class RagRerankService { input.secondaryTimeoutMs, DEFAULT_SECONDARY_TIMEOUT_MS ); + const candidateWindow = primary.slice(0, secondaryTopK); + let secondaryMetadata: RagRerankStageMetadata = { + status: "skipped", + timeout_ms: secondaryTimeoutMs, + timeoutMs: secondaryTimeoutMs, + input_count: candidateWindow.length, + inputCount: candidateWindow.length, + output_count: 0, + outputCount: 0 + }; if (!budgetDecision.secondaryEnabled) { - rerankDegradeReasons.push("secondary_rerank_disabled_by_budget"); + const reason = "secondary_rerank_disabled_by_budget"; + rerankDegradeReasons.push(reason); + secondaryMetadata = { + ...secondaryMetadata, + status: "skipped", + fallback_reason: reason, + fallbackReason: reason + }; await this.writeSecondaryReplay(bundle, { status: "skipped", - reason: "secondary_rerank_disabled_by_budget", - timeoutMs: secondaryTimeoutMs + reason, + timeoutMs: secondaryTimeoutMs, + metadata: secondaryMetadata }); } else if (!secondaryEnabled) { - rerankDegradeReasons.push("secondary_rerank_disabled"); + const reason = "secondary_rerank_disabled"; + rerankDegradeReasons.push(reason); + secondaryMetadata = { + ...secondaryMetadata, + status: "skipped", + fallback_reason: reason, + fallbackReason: reason + }; await this.writeSecondaryReplay(bundle, { status: "skipped", - reason: "secondary_rerank_disabled", - timeoutMs: secondaryTimeoutMs + reason, + timeoutMs: secondaryTimeoutMs, + metadata: secondaryMetadata }); } else if (primary.length < secondaryMinCandidates) { - rerankDegradeReasons.push("secondary_rerank_skipped_low_candidates"); + const reason = "secondary_rerank_skipped_low_candidates"; + rerankDegradeReasons.push(reason); + secondaryMetadata = { + ...secondaryMetadata, + status: "skipped", + fallback_reason: reason, + fallbackReason: reason, + evidence_ids: candidateWindow.map((item) => item.chunk_id), + evidenceIds: candidateWindow.map((item) => item.chunk_id) + }; await this.writeSecondaryReplay(bundle, { status: "skipped", - reason: "secondary_rerank_skipped_low_candidates", - timeoutMs: secondaryTimeoutMs + reason, + timeoutMs: secondaryTimeoutMs, + metadata: secondaryMetadata }); } else { try { - secondaryScores = await this.withTimeout( - this.runSecondaryRerank(bundle, primary.slice(0, secondaryTopK), input.modelCatalogId), + const secondary = await this.withTimeout( + this.runSecondaryRerank(bundle, candidateWindow, input.modelCatalogId), secondaryTimeoutMs, "secondary_rerank_timeout" ); + secondaryScores = secondary.scores; + secondaryMetadata = { + ...secondary.metadata, + status: "ok", + timeout_ms: secondaryTimeoutMs, + timeoutMs: secondaryTimeoutMs + }; await this.writeSecondaryReplay(bundle, { status: "ok", timeoutMs: secondaryTimeoutMs, - scores: secondaryScores + scores: secondaryScores, + metadata: secondaryMetadata }); } catch (error) { - const reason = - error instanceof Error && error.message.trim() - ? error.message - : "secondary_rerank_failed"; + const reason = this.resolveSecondaryDegradeReason(error); rerankDegradeReasons.push(reason); + secondaryMetadata = this.toSecondaryMetadataFromError({ + error, + reason, + timeoutMs: secondaryTimeoutMs, + evidenceIds: candidateWindow.map((item) => item.chunk_id), + inputCount: candidateWindow.length + }); await this.writeSecondaryReplay(bundle, { status: "degraded", reason, - timeoutMs: secondaryTimeoutMs + timeoutMs: secondaryTimeoutMs, + metadata: secondaryMetadata }); } } @@ -177,10 +278,45 @@ export class RagRerankService { decision_reasons: this.unique([ ...(bundle.decision_reasons ?? []), ...budgetDecision.decisionReasons - ]) + ]), + rerank_metadata: { + secondary: secondaryMetadata, + secondaryCompat: secondaryMetadata + }, + rerankMetadata: { + secondary: secondaryMetadata, + secondaryCompat: secondaryMetadata + } }; const existingContextPack = bundle.context_pack; - responseBundle.context_pack = { + const existingContextPackExtended = this.toExtendedContextPack(existingContextPack); + const existingLaneMetadata = + existingContextPackExtended?.lane_metadata ?? + existingContextPackExtended?.laneMetadata ?? + []; + const existingPruningDecisions = + existingContextPackExtended?.pruning_decisions ?? + existingContextPackExtended?.pruningDecisions ?? + []; + const rerankLaneMetadata = this.buildRerankLaneMetadata({ + secondaryMetadata, + selectedContext + }); + const mergedLaneMetadata = [ + ...existingLaneMetadata.filter((lane) => lane.lane !== "rerank"), + rerankLaneMetadata + ]; + const removedBySelectedContextLimit = reranked + .slice(selectedContext.length) + .map((candidate) => candidate.chunk_id); + const mergedPruningDecisions = this.mergePruningDecisions({ + existingPruningDecisions, + decisionReasons: budgetDecision.decisionReasons, + selectedContext, + removedBySelectedContextLimit + }); + const selectedContextLanes = this.unique(selectedContext.map((chunk) => chunk.metadata.domain)); + const nextContextPack: ExtendedRagContextPack = { status: responseBundle.status, semantic_version: existingContextPack?.semantic_version, semantic_lock_status: @@ -203,6 +339,12 @@ export class RagRerankService { count: selectedContext.length, snippets: selectedContext.map((chunk) => chunk.content.slice(0, 160)).slice(0, 5) }, + lane_metadata: mergedLaneMetadata, + laneMetadata: mergedLaneMetadata, + pruning_decisions: mergedPruningDecisions, + pruningDecisions: mergedPruningDecisions, + selected_context_lanes: selectedContextLanes, + selectedContextLanes: selectedContextLanes, degrade_reasons: this.unique([ ...(existingContextPack?.degrade_reasons ?? []), ...degradeReasons @@ -212,6 +354,7 @@ export class RagRerankService { ...(responseBundle.risk_tags ?? []) ]) }; + responseBundle.context_pack = nextContextPack; await this.writeBudgetReplay(responseBundle, { decisionReasons: budgetDecision.decisionReasons, secondaryEnabled: budgetDecision.secondaryEnabled, @@ -268,8 +411,8 @@ export class RagRerankService { bundle: RagRetrievalBundle, candidates: RagRerankedCandidate[], modelCatalogId?: string - ): Promise> { - const response = await this.modelReranker.rerank({ + ): Promise { + const response = await this.modelReranker.rerankWithMetadata({ query: bundle.query, modelCatalogId, candidates: candidates.map((candidate) => ({ @@ -282,7 +425,7 @@ export class RagRerankService { })) }); const scoreMap: Record = {}; - for (const item of response) { + for (const item of response.results) { if (!Number.isFinite(item.score)) { continue; } @@ -291,7 +434,67 @@ export class RagRerankService { reason: item.reason }; } - return scoreMap; + const expectedCandidateIds = new Set(candidates.map((candidate) => candidate.chunk_id)); + const returnedCandidateIds = Object.keys(scoreMap); + const unknownCandidateIds = returnedCandidateIds.filter( + (candidateId) => !expectedCandidateIds.has(candidateId) + ); + const missingCandidateIds = candidates + .map((candidate) => candidate.chunk_id) + .filter((candidateId) => !returnedCandidateIds.includes(candidateId)); + if (unknownCandidateIds.length > 0 || missingCandidateIds.length > 0) { + throw new DomainError( + "RERANK_PROVIDER_OUTPUT_CANDIDATE_MISMATCH", + "Rerank provider 返回候选集合与输入不一致。", + 502, + { + provider: response.metadata.provider, + model: response.metadata.model, + unknownCandidateIds: unknownCandidateIds.slice(0, 20), + missingCandidateIds: missingCandidateIds.slice(0, 20), + expected: candidates.length, + actual: returnedCandidateIds.length + } + ); + } + if (Object.keys(scoreMap).length !== candidates.length) { + throw new DomainError( + "RERANK_PROVIDER_OUTPUT_COUNT_MISMATCH", + "Rerank provider 返回结果数量与候选数量不一致。", + 502, + { + provider: response.metadata.provider, + model: response.metadata.model, + expected: candidates.length, + actual: Object.keys(scoreMap).length + } + ); + } + const evidenceIds = candidates.map((candidate) => candidate.chunk_id); + const metadata: RagRerankStageMetadata = { + status: "ok", + mode: response.metadata.mode, + provider: response.metadata.provider, + model: response.metadata.model, + config_source: response.metadata.configSource, + configSource: response.metadata.configSource, + config_id: response.metadata.configId, + configId: response.metadata.configId, + input_count: response.metadata.inputCount, + inputCount: response.metadata.inputCount, + output_count: Object.keys(scoreMap).length, + outputCount: Object.keys(scoreMap).length, + fallback_reason: response.metadata.fallbackReason, + fallbackReason: response.metadata.fallbackReason, + unavailable_reason: response.metadata.unavailableReason, + unavailableReason: response.metadata.unavailableReason, + evidence_ids: evidenceIds, + evidenceIds + }; + return { + scores: scoreMap, + metadata + }; } private mergePrimaryWithSecondary( @@ -320,6 +523,95 @@ export class RagRerankService { }); } + private buildRerankLaneMetadata(input: { + secondaryMetadata: RagRerankStageMetadata; + selectedContext: RagRetrievalChunkPayload[]; + }): RerankContextPackLaneMetadata { + const unavailableReason = + input.secondaryMetadata.unavailable_reason ?? input.secondaryMetadata.unavailableReason; + const fallbackReason = + input.secondaryMetadata.fallback_reason ?? input.secondaryMetadata.fallbackReason; + const state: RerankContextPackLaneMetadata["state"] = + input.secondaryMetadata.status === "ok" + ? "ready" + : unavailableReason + ? "unavailable" + : input.secondaryMetadata.status === "skipped" + ? "skipped" + : "degraded"; + const evidenceIds = + input.secondaryMetadata.evidence_ids ?? input.secondaryMetadata.evidenceIds ?? []; + const reasonCodes = this.unique([ + ...(unavailableReason ? [unavailableReason] : []), + ...(fallbackReason ? [fallbackReason] : []) + ]); + return { + lane: "rerank", + state, + provider: input.secondaryMetadata.provider, + model: input.secondaryMetadata.model, + input_count: input.secondaryMetadata.input_count ?? input.secondaryMetadata.inputCount ?? 0, + inputCount: input.secondaryMetadata.input_count ?? input.secondaryMetadata.inputCount ?? 0, + output_count: input.secondaryMetadata.output_count ?? input.secondaryMetadata.outputCount ?? 0, + outputCount: + input.secondaryMetadata.output_count ?? input.secondaryMetadata.outputCount ?? 0, + selected_count: input.selectedContext.length, + selectedCount: input.selectedContext.length, + timeout_ms: input.secondaryMetadata.timeout_ms ?? input.secondaryMetadata.timeoutMs, + timeoutMs: input.secondaryMetadata.timeout_ms ?? input.secondaryMetadata.timeoutMs, + unavailable_reason: unavailableReason, + unavailableReason: unavailableReason, + fallback_reason: fallbackReason, + fallbackReason: fallbackReason, + evidence_ids: evidenceIds, + evidenceIds: evidenceIds, + reason_codes: reasonCodes, + reasonCodes: reasonCodes + }; + } + + private mergePruningDecisions(input: { + existingPruningDecisions: RerankContextPackPruningDecision[]; + decisionReasons: string[]; + selectedContext: RagRetrievalChunkPayload[]; + removedBySelectedContextLimit: string[]; + }): RerankContextPackPruningDecision[] { + const next = [...input.existingPruningDecisions]; + if ( + input.removedBySelectedContextLimit.length === 0 && + input.decisionReasons.length === 0 + ) { + return next; + } + const reasonCodes = this.unique([ + ...input.decisionReasons, + ...(input.removedBySelectedContextLimit.length > 0 + ? ["selected_context_limit_applied"] + : []) + ]); + next.push({ + budget_source: "rerank_budget", + removed_evidence_ids: input.removedBySelectedContextLimit, + kept_evidence_ids: input.selectedContext.map((chunk) => chunk.chunk_id), + reason_codes: reasonCodes, + summary: `rerank_budget:selected_context_limit=${input.selectedContext.length}`, + budgetSource: "rerank_budget", + removedEvidenceIds: input.removedBySelectedContextLimit, + keptEvidenceIds: input.selectedContext.map((chunk) => chunk.chunk_id), + reasonCodes: reasonCodes + }); + return next; + } + + private toExtendedContextPack( + contextPack: RagRetrievalBundle["context_pack"] + ): ExtendedRagContextPack | undefined { + if (!contextPack) { + return undefined; + } + return contextPack as ExtendedRagContextPack; + } + private domainBoost(domain: string): number { if (domain === "semantic_term") { return 0.15; @@ -398,6 +690,7 @@ export class RagRerankService { reason?: string; timeoutMs: number; scores?: Record; + metadata?: RagRerankStageMetadata; } ): Promise { await this.replayRepository.writeReplay({ @@ -410,7 +703,8 @@ export class RagRerankService { status: input.status, reason: input.reason, timeoutMs: input.timeoutMs, - scores: input.scores + scores: input.scores, + metadata: input.metadata } }); } @@ -429,6 +723,7 @@ export class RagRerankService { rerankedCount: bundle.reranked?.length ?? 0, selectedContextCount: bundle.selected_context?.length ?? 0, riskTags: bundle.risk_tags ?? [], + rerankMetadata: bundle.rerank_metadata ?? bundle.rerankMetadata, columnPruning: this.readColumnPruningEvidence(bundle), contextPack: bundle.context_pack ? { @@ -485,6 +780,81 @@ export class RagRerankService { return this.isRecord(candidate) ? candidate : undefined; } + private resolveSecondaryDegradeReason(error: unknown): string { + if (error instanceof Error && error.message === "secondary_rerank_timeout") { + return "secondary_rerank_timeout"; + } + const code = this.readErrorCode(error); + if (code === "LLM_CONFIG_MISSING") { + return "secondary_rerank_unavailable_provider_config_missing"; + } + if (code === "RERANK_PROVIDER_INVALID_PAYLOAD") { + return "secondary_rerank_unavailable_invalid_payload"; + } + if (typeof code === "string" && code.trim().length > 0) { + return `secondary_rerank_unavailable_${code.toLowerCase()}`; + } + if (error instanceof Error && error.message.trim()) { + return `secondary_rerank_unavailable_${error.message + .toLowerCase() + .replace(/\s+/g, "_") + .slice(0, 64)}`; + } + return "secondary_rerank_unavailable_unknown"; + } + + private toSecondaryMetadataFromError(input: { + error: unknown; + reason: string; + timeoutMs: number; + evidenceIds: string[]; + inputCount: number; + }): RagRerankStageMetadata { + const details = this.readErrorDetails(input.error); + const provider = this.readString(details?.provider); + const model = this.readString(details?.model); + return { + status: "degraded", + provider, + model, + timeout_ms: input.timeoutMs, + timeoutMs: input.timeoutMs, + input_count: input.inputCount, + inputCount: input.inputCount, + output_count: 0, + outputCount: 0, + unavailable_reason: input.reason, + unavailableReason: input.reason, + evidence_ids: input.evidenceIds, + evidenceIds: input.evidenceIds + }; + } + + private readErrorCode(error: unknown): string | undefined { + if (!this.isRecord(error)) { + return undefined; + } + return this.readString(error.code); + } + + private readErrorDetails(error: unknown): Record | undefined { + if (!this.isRecord(error)) { + return undefined; + } + if (!this.isRecord(error.details)) { + return undefined; + } + return error.details; + } + + private readString(value: unknown): string | undefined { + if (typeof value !== "string") { + return undefined; + } + const normalized = value.trim(); + return normalized.length > 0 ? normalized : undefined; + } + private isRecord(value: unknown): value is Record { return typeof value === "object" && value !== null && !Array.isArray(value); } diff --git a/apps/backend/src/modules/rag/retrieval/rag-retrieval.service.ts b/apps/backend/src/modules/rag/retrieval/rag-retrieval.service.ts index 4a2ba82..f35388a 100644 --- a/apps/backend/src/modules/rag/retrieval/rag-retrieval.service.ts +++ b/apps/backend/src/modules/rag/retrieval/rag-retrieval.service.ts @@ -1,5 +1,7 @@ import { createHash } from "node:crypto"; import { Injectable } from "@nestjs/common"; +import { DomainError } from "../../../common/domain-error"; +import { EmbeddingRouterService } from "../../llm/embedding-router.service"; import { GraphService } from "../../knowledge/graph/graph.service"; import { SKILL_REGISTRY_UNAVAILABLE_REASON, @@ -91,6 +93,16 @@ interface WideTableProfile { columns: string[]; } +interface DenseVectorMetadata { + provider?: string; + model?: string; + dimensions?: number; + vectorVersion?: string; + indexVersion?: string; + scope?: string; + assetType?: string; +} + interface TablePruningPlan { tableName: string; normalizedTableName: string; @@ -109,6 +121,7 @@ export class RagRetrievalService { constructor( private readonly indexRepository: RagIndexRepository, private readonly replayRepository: RagReplayRepository, + private readonly embeddingRouter: EmbeddingRouterService, private readonly skillRegistry: SkillRegistryService, private readonly graphService: GraphService, private readonly cacheKeyFactory: RagCacheKeyFactory, @@ -523,16 +536,61 @@ export class RagRetrievalService { return this.sortHits(hits).slice(0, limit); } - private runDenseLane( + private async runDenseLane( query: string, contexts: RagRetrievalEntryContext[], limit: number - ): RagRetrievalLaneHit[] { - const queryVector = this.buildDenseVector(query); + ): Promise { + if (contexts.length === 0) { + return { + hits: [] + }; + } + + let queryVector: number[]; + let queryMetadata: DenseVectorMetadata | undefined; + try { + const embeddings = await this.embeddingRouter.embed({ + texts: [query], + indexVersion: contexts[0]?.indexVersionId, + scope: "retrieval_query", + assetType: "query" + }); + queryVector = embeddings[0]?.vector ?? []; + queryMetadata = embeddings[0] + ? this.toDenseVectorMetadata(embeddings[0].metadata) + : undefined; + } catch (error) { + return { + hits: [], + degradeReason: this.resolveDenseUnavailableReason(error) + }; + } + + if (!queryVector || queryVector.length === 0) { + return { + hits: [], + degradeReason: "dense_unavailable_empty_query_vector" + }; + } + const hits: RagRetrievalLaneHit[] = []; + let incompatibleVectorSpaceDetected = false; for (const context of contexts) { const vector = this.parseDenseVector(context.entry.denseVector); - if (!vector || vector.length === 0 || vector.length !== queryVector.length) { + if (!vector || vector.length === 0) { + continue; + } + const candidateDenseMetadata = this.readDenseVectorMetadata(context); + if ( + vector.length !== queryVector.length || + !this.isDenseVectorSpaceCompatible({ + queryMetadata, + candidateMetadata: candidateDenseMetadata, + indexVersionId: context.indexVersionId + }) + ) { + incompatibleVectorSpaceDetected = true; continue; } const cosine = this.cosineSimilarity(queryVector, vector); @@ -543,11 +601,27 @@ export class RagRetrievalService { lane: "dense", chunk_id: context.entry.chunkId, score: Number(cosine.toFixed(12)), - evidence: [`cosine:${cosine.toFixed(6)}`], + evidence: this.unique([ + `cosine:${cosine.toFixed(6)}`, + ...(candidateDenseMetadata?.provider + ? [`dense_provider:${candidateDenseMetadata.provider}`] + : []), + ...(candidateDenseMetadata?.model + ? [`dense_model:${candidateDenseMetadata.model}`] + : []) + ]), chunk: this.toChunkPayload(context) }); } - return this.sortHits(hits).slice(0, limit); + if (incompatibleVectorSpaceDetected) { + return { + hits: [], + degradeReason: "dense_unavailable_incompatible_vector_space" + }; + } + return { + hits: this.sortHits(hits).slice(0, limit) + }; } private async runGraphLane( @@ -661,7 +735,8 @@ export class RagRetrievalService { this.readString(parsed.chunkProfile) ?? this.readString(sourceMetadata.chunkProfile), startOffset: this.readNumber(parsed.startOffset) ?? this.readNumber(sourceMetadata.startOffset), - endOffset: this.readNumber(parsed.endOffset) ?? this.readNumber(sourceMetadata.endOffset) + endOffset: this.readNumber(parsed.endOffset) ?? this.readNumber(sourceMetadata.endOffset), + denseMetadata: this.readDenseVectorMetadataFromParsed(parsed, sourceMetadata) } }; } @@ -679,7 +754,14 @@ export class RagRetrievalService { columnNames: this.readStringArray(context.parsedMetadata.columnNames), sourceMetadata: this.isRecord(context.parsedMetadata.sourceMetadata) ? context.parsedMetadata.sourceMetadata - : {} + : {}, + denseProvider: context.parsedMetadata.denseMetadata?.provider, + denseModel: context.parsedMetadata.denseMetadata?.model, + denseDimensions: context.parsedMetadata.denseMetadata?.dimensions, + vectorVersion: context.parsedMetadata.denseMetadata?.vectorVersion, + indexVersion: context.parsedMetadata.denseMetadata?.indexVersion, + scope: context.parsedMetadata.denseMetadata?.scope, + assetType: context.parsedMetadata.denseMetadata?.assetType }; return { @@ -1543,16 +1625,6 @@ export class RagRetrievalService { } } - private buildDenseVector(input: string): number[] { - const digest = createHash("sha256").update(input).digest(); - const dimensions = 8; - return Array.from({ length: dimensions }, (_, index) => { - const byte = digest[index] ?? 0; - const normalized = byte / 255; - return Number((normalized * 2 - 1).toFixed(6)); - }); - } - private cosineSimilarity(left: number[], right: number[]): number { let dot = 0; let leftNorm = 0; @@ -1620,6 +1692,117 @@ export class RagRetrievalService { return source.column_pruning ?? source.columnPruning; } + private readDenseVectorMetadata( + context: RagRetrievalEntryContext + ): DenseVectorMetadata | undefined { + return context.parsedMetadata.denseMetadata as DenseVectorMetadata | undefined; + } + + private readDenseVectorMetadataFromParsed( + parsed: Record, + sourceMetadata: Record + ): DenseVectorMetadata | undefined { + const denseRaw = this.isRecord(parsed.dense) + ? parsed.dense + : this.isRecord(sourceMetadata.dense) + ? sourceMetadata.dense + : undefined; + if (!denseRaw) { + return undefined; + } + return { + provider: this.readString(denseRaw.provider), + model: this.readString(denseRaw.model), + dimensions: this.readNumber(denseRaw.dimensions), + vectorVersion: this.readString(denseRaw.vectorVersion), + indexVersion: this.readString(denseRaw.indexVersion), + scope: this.readString(denseRaw.scope), + assetType: this.readString(denseRaw.assetType) + }; + } + + private toDenseVectorMetadata(metadata: { + provider: string; + model: string; + dimensions: number; + vectorVersion: string; + indexVersion?: string; + scope?: string; + assetType?: string; + }): DenseVectorMetadata { + return { + provider: metadata.provider, + model: metadata.model, + dimensions: metadata.dimensions, + vectorVersion: metadata.vectorVersion, + indexVersion: metadata.indexVersion, + scope: metadata.scope, + assetType: metadata.assetType + }; + } + + private isDenseVectorSpaceCompatible(input: { + queryMetadata?: DenseVectorMetadata; + candidateMetadata?: DenseVectorMetadata; + indexVersionId: string; + }): boolean { + const { queryMetadata, candidateMetadata, indexVersionId } = input; + if (!queryMetadata || !candidateMetadata) { + return false; + } + if ( + queryMetadata.dimensions !== undefined && + candidateMetadata.dimensions !== undefined && + queryMetadata.dimensions !== candidateMetadata.dimensions + ) { + return false; + } + if ( + queryMetadata.provider && + candidateMetadata.provider && + queryMetadata.provider !== candidateMetadata.provider + ) { + return false; + } + if ( + queryMetadata.model && + candidateMetadata.model && + queryMetadata.model !== candidateMetadata.model + ) { + return false; + } + if ( + queryMetadata.vectorVersion && + candidateMetadata.vectorVersion && + queryMetadata.vectorVersion !== candidateMetadata.vectorVersion + ) { + return false; + } + if ( + candidateMetadata.indexVersion && + candidateMetadata.indexVersion !== indexVersionId + ) { + return false; + } + if ( + queryMetadata.indexVersion && + queryMetadata.indexVersion !== indexVersionId + ) { + return false; + } + return true; + } + + private resolveDenseUnavailableReason(error: unknown): string { + if (error instanceof DomainError) { + return `dense_unavailable:${error.code.toLowerCase()}`; + } + if (error instanceof Error) { + return `dense_unavailable:${error.message.toLowerCase().replace(/\s+/g, "_")}`; + } + return "dense_unavailable:unknown_error"; + } + private readPriorSqlLaneEvidence( bundle: RagRetrievalResponse["retrieval_bundle"] ): RagPriorSqlLaneEvidence | undefined { diff --git a/apps/backend/src/modules/rag/retrieval/rag-retrieval.types.ts b/apps/backend/src/modules/rag/retrieval/rag-retrieval.types.ts index 9a40ce0..81d0f1b 100644 --- a/apps/backend/src/modules/rag/retrieval/rag-retrieval.types.ts +++ b/apps/backend/src/modules/rag/retrieval/rag-retrieval.types.ts @@ -34,6 +34,13 @@ export interface RagRetrievalChunkMetadata { tableNames: string[]; columnNames: string[]; sourceMetadata?: Record; + denseProvider?: string; + denseModel?: string; + denseDimensions?: number; + vectorVersion?: string; + indexVersion?: string; + scope?: string; + assetType?: string; } export interface RagRetrievalChunkPayload { @@ -76,6 +83,34 @@ export interface RagRerankedCandidate extends RagRetrievalCandidate { rank_reason: string[]; } +export interface RagRerankStageMetadata { + status: "ok" | "degraded" | "skipped"; + provider?: string; + model?: string; + mode?: "provider" | "mock"; + config_source?: "settings" | "env_fallback" | "missing"; + config_id?: string; + timeout_ms?: number; + input_count?: number; + output_count?: number; + fallback_reason?: string; + unavailable_reason?: string; + evidence_ids?: string[]; + timeoutMs?: number; + inputCount?: number; + outputCount?: number; + fallbackReason?: string; + unavailableReason?: string; + configSource?: "settings" | "env_fallback" | "missing"; + configId?: string; + evidenceIds?: string[]; +} + +export interface RagRerankMetadata { + secondary: RagRerankStageMetadata; + secondaryCompat?: RagRerankStageMetadata; +} + export interface RagSkillContextEntry { source: "skill_registry"; domain: string; @@ -200,6 +235,8 @@ export interface RagRetrievalBundle { prior_sql_lane?: RagPriorSqlLaneEvidence; priorSqlLane?: RagPriorSqlLaneEvidence; decision_reasons?: string[]; + rerank_metadata?: RagRerankMetadata; + rerankMetadata?: RagRerankMetadata; } export interface RagRetrievalResponse { @@ -213,6 +250,15 @@ export interface RagRetrievalParsedMetadata extends Record { chunkProfile?: string; startOffset?: number; endOffset?: number; + denseMetadata?: { + provider?: string; + model?: string; + dimensions?: number; + vectorVersion?: string; + indexVersion?: string; + scope?: string; + assetType?: string; + }; } export interface RagRetrievalEntryContext { diff --git a/apps/backend/src/modules/system/health.controller.ts b/apps/backend/src/modules/system/health.controller.ts index 1cdda5b..368c21f 100644 --- a/apps/backend/src/modules/system/health.controller.ts +++ b/apps/backend/src/modules/system/health.controller.ts @@ -12,6 +12,7 @@ import { GateMetricsService } from "../observability/gate-metrics.service"; import { RagIngestionMetricsService } from "../rag/observability/rag-ingestion-metrics.service"; import { RagQualityService } from "../rag/quality/rag-quality.service"; import { SemanticSpineShadowGateService } from "../observability/semantic-spine-shadow-gate.service"; +import { RagTaskConfigService } from "../llm/rag-task-config.service"; @Controller() export class HealthController { @@ -25,7 +26,8 @@ export class HealthController { private readonly gateMetrics: GateMetricsService, private readonly ragIngestionMetrics: RagIngestionMetricsService, private readonly ragQuality: RagQualityService, - private readonly semanticSpineShadow: SemanticSpineShadowGateService + private readonly semanticSpineShadow: SemanticSpineShadowGateService, + private readonly ragTaskConfigService: RagTaskConfigService ) {} private async buildHealthResponse(req: Request): Promise> { @@ -38,6 +40,14 @@ export class HealthController { const postgresEnabled = Boolean(this.config.databaseUrl); const ragQualityGate = this.ragQuality.snapshot(); const semanticSpineShadowGate = this.semanticSpineShadow.snapshot(); + const ragConfigView = await this.ragTaskConfigService.listSettingsView({ + id: "system-health", + role: "admin" + }); + const embeddingConfig = + ragConfigView.items.find((item) => item.taskType === "embedding") ?? null; + const rerankConfig = + ragConfigView.items.find((item) => item.taskType === "rerank") ?? null; return ok(req.requestId, { status: sqliteReady ? "ok" : "degraded", runtime: { @@ -90,6 +100,24 @@ export class HealthController { gate: ragQualityGate, r6: ragQualityGate.r6 }, + ragConfig: { + embedding: embeddingConfig + ? { + provider: embeddingConfig.provider, + model: embeddingConfig.model, + configSource: embeddingConfig.configSource, + healthStatus: embeddingConfig.healthStatus + } + : null, + rerank: rerankConfig + ? { + provider: rerankConfig.provider, + model: rerankConfig.model, + configSource: rerankConfig.configSource, + healthStatus: rerankConfig.healthStatus + } + : null + }, semanticSpineShadow: { gate: semanticSpineShadowGate } diff --git a/apps/backend/src/modules/system/system.module.ts b/apps/backend/src/modules/system/system.module.ts index 3d43f37..1ff0a18 100644 --- a/apps/backend/src/modules/system/system.module.ts +++ b/apps/backend/src/modules/system/system.module.ts @@ -4,6 +4,7 @@ import { PlatformDataPersistenceModule } from "../platform/data/persistence.modu import { DatasourceModule } from "../governance/datasource/datasource.module"; import { ObservabilityModule } from "../observability/observability.module"; import { RagModule } from "../knowledge/rag/rag.module"; +import { LlmModule } from "../llm/llm.module"; import { HealthController } from "./health.controller"; @Module({ @@ -12,7 +13,8 @@ import { HealthController } from "./health.controller"; PlatformDataPersistenceModule, DatasourceModule, ObservabilityModule, - RagModule + RagModule, + LlmModule ], controllers: [HealthController] }) diff --git a/apps/backend/test/e2e/chat-api.spec.ts b/apps/backend/test/e2e/chat-api.spec.ts index 6f7eda6..eae89d7 100644 --- a/apps/backend/test/e2e/chat-api.spec.ts +++ b/apps/backend/test/e2e/chat-api.spec.ts @@ -51,9 +51,7 @@ describe("chat api (e2e)", () => { expect(runRes.body.data.run.runId).toBeDefined(); expect(runRes.body.data.run.sql).toMatch(/select/i); expect(runRes.body.data.run.explanation).toBeTruthy(); - expect(runRes.body.data.run.llmRaw).toBeTruthy(); - expect(runRes.body.data.run.llmRaw.provider).toBe("volcengine"); - expect(runRes.body.data.run.llmRaw.model).toBeTruthy(); + expect(runRes.body.data.run.llmRaw).toBeNull(); expect(runRes.body.data.delivery).toBeTruthy(); expect(runRes.body.data.run.delivery).toEqual(runRes.body.data.delivery); expect(runRes.body.data.run.answer).toBe(runRes.body.data.delivery.answer.text); @@ -76,6 +74,48 @@ describe("chat api (e2e)", () => { if (contextPackStatus !== undefined) { expect(["ready", "degraded"]).toContain(contextPackStatus); } + const contextPackSummary = runRes.body.data.delivery?.evidence?.contextPackSummary as + | { + selectedEvidenceCount?: number; + status?: string; + } + | undefined; + if (contextPackSummary) { + expect(typeof contextPackSummary.selectedEvidenceCount).toBe("number"); + expect(["ready", "degraded"]).toContain(contextPackSummary.status); + } + const traceV2 = runRes.body.data.run.trace?.v2 as + | { + version?: string; + stageOrder?: string[]; + stages?: Array<{ stage?: string }>; + } + | undefined; + if (traceV2 !== undefined) { + expect(traceV2.version).toBe("v2"); + expect(traceV2.stageOrder).toEqual([ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ]); + expect(traceV2.stages?.map((item) => item.stage)).toEqual(traceV2.stageOrder); + } + const deliveryV2 = runRes.body.data.delivery?.evidence?.v2 as + | { + stageArtifacts?: Array<{ stage?: string }>; + } + | undefined; + if (deliveryV2 !== undefined) { + expect(deliveryV2.stageArtifacts?.map((item) => item.stage)).toEqual( + traceV2?.stageOrder + ); + } const messageViewRes = await request(app.getHttpServer()) .get(`/api/v1/sessions/${sessionId}/messages`) @@ -91,7 +131,20 @@ describe("chat api (e2e)", () => { expect(messageViewRes.body.data.latestRun.delivery.evidence.runId).toBe( messageViewRes.body.data.latestRun.runId ); + if (contextPackSummary) { + expect( + messageViewRes.body.data.latestRun.delivery.evidence.contextPackSummary + ).toEqual(contextPackSummary); + } expect(messageViewRes.body.data.latestRun.delivery.artifact.summary.text).toBeTruthy(); + const latestTraceV2 = messageViewRes.body.data.latestRun.trace?.v2 as + | { + version?: string; + } + | undefined; + if (latestTraceV2 !== undefined) { + expect(latestTraceV2.version).toBe("v2"); + } }); it("should accept optional contextEnvelope on sync message endpoint", async () => { diff --git a/apps/backend/test/e2e/chat-stream-api.spec.ts b/apps/backend/test/e2e/chat-stream-api.spec.ts index b05ee5c..df0d61a 100644 --- a/apps/backend/test/e2e/chat-stream-api.spec.ts +++ b/apps/backend/test/e2e/chat-stream-api.spec.ts @@ -129,6 +129,18 @@ describe("chat stream api (e2e)", () => { expect(startEvent?.data).toHaveProperty("requestId"); const stateEvents = parsedEvents.filter(({ eventType }) => eventType === "state"); + const runningGenerateIndex = parsedEvents.findIndex(({ eventType, event }) => { + const stateData = event.data as { + node?: unknown; + lifecycle?: unknown; + }; + return ( + eventType === "state" && + stateData.node === "generate-sql" && + stateData.lifecycle === "running" + ); + }); + expect(runningGenerateIndex).toBeGreaterThan(startIndex); for (const { event } of stateEvents) { const stateData = event.data as { node: unknown; @@ -137,6 +149,17 @@ describe("chat stream api (e2e)", () => { sequence?: unknown; stepId?: unknown; lifecycle?: unknown; + v2?: { + stageArtifact?: { + stage?: string; + status?: string; + metadata?: { + taskProfile?: string; + reasoningTier?: string; + policySource?: string; + }; + }; + }; }; expect(typeof stateData.node).toBe("string"); expect(["success", "failed", "skipped"]).toContain(stateData.status); @@ -153,11 +176,50 @@ describe("chat stream api (e2e)", () => { stateData.lifecycle ); } + if (stateData.v2?.stageArtifact) { + expect([ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ]).toContain(stateData.v2.stageArtifact.stage); + expect([ + "success", + "failed", + "skipped", + "degraded", + "clarification" + ]).toContain(stateData.v2.stageArtifact.status); + const stageMetadata = stateData.v2.stageArtifact.metadata; + expect(typeof stageMetadata?.taskProfile).toBe("string"); + expect(typeof stageMetadata?.reasoningTier).toBe("string"); + expect(typeof stageMetadata?.policySource).toBe("string"); + } } + expect( + stateEvents.some(({ event }) => { + const stateData = event.data as { + v2?: { + stageArtifact?: { + stage?: string; + }; + }; + }; + return typeof stateData.v2?.stageArtifact?.stage === "string"; + }) + ).toBe(true); + const textDeltaEvents = parsedEvents.filter( ({ eventType }) => eventType === "text-delta" ); + const firstTextDeltaIndex = eventTypes.indexOf("text-delta"); + expect(runningGenerateIndex).toBeLessThan(firstTextDeltaIndex); expect(textDeltaEvents.length).toBeGreaterThan(0); expect( textDeltaEvents.some(({ event }) => { @@ -193,6 +255,13 @@ describe("chat stream api (e2e)", () => { evidence?: { runId?: string; contextPackStatus?: string; + contextPackSummary?: { + status?: string; + selectedEvidenceCount?: number; + }; + v2?: { + stageArtifacts?: Array<{ stage?: string }>; + }; }; }; }; @@ -211,6 +280,34 @@ describe("chat stream api (e2e)", () => { if (contextPackStatus !== undefined) { expect(["ready", "degraded"]).toContain(contextPackStatus); } + const streamContextPackSummary = finishData.delivery?.evidence?.contextPackSummary as + | { + status?: string; + selectedEvidenceCount?: number; + } + | undefined; + if (streamContextPackSummary) { + expect(["ready", "degraded"]).toContain(streamContextPackSummary.status); + expect(typeof streamContextPackSummary.selectedEvidenceCount).toBe("number"); + } + const deliveryV2 = finishData.delivery?.evidence?.v2 as + | { + stageArtifacts?: Array<{ stage?: string }>; + } + | undefined; + if (deliveryV2 !== undefined) { + expect(deliveryV2.stageArtifacts?.map((item) => item.stage)).toEqual([ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ]); + } const messagesRes = await request(app.getHttpServer()) .get(`/api/v1/sessions/${sessionId}/messages`) @@ -231,7 +328,20 @@ describe("chat stream api (e2e)", () => { messagesRes.body.data.latestRun.delivery.answer.text ); expect(messagesRes.body.data.latestRun.delivery.evidence.runId).toBe(streamRunId); + if (streamContextPackSummary) { + expect( + messagesRes.body.data.latestRun.delivery.evidence.contextPackSummary + ).toEqual(streamContextPackSummary); + } expect(["completed", "failed"]).toContain(latestRun.trace.streamStatus); + const latestTraceV2 = (messagesRes.body.data.latestRun.trace?.v2 ?? null) as + | { + version?: string; + } + | null; + if (latestTraceV2) { + expect(latestTraceV2.version).toBe("v2"); + } if (latestRun.trace.streamStatus === "failed") { expect(typeof latestRun.error).toBe("string"); expect(latestRun.error?.trim().length).toBeGreaterThan(0); diff --git a/apps/backend/test/e2e/stage1-acceptance.spec.ts b/apps/backend/test/e2e/stage1-acceptance.spec.ts index 2f7a6d1..05f923a 100644 --- a/apps/backend/test/e2e/stage1-acceptance.spec.ts +++ b/apps/backend/test/e2e/stage1-acceptance.spec.ts @@ -4,7 +4,7 @@ import { randomUUID } from "node:crypto"; import yaml from "js-yaml"; import { Test } from "@nestjs/testing"; import { AppModule } from "../../src/app.module"; -import { GraphBuilderService } from "../../src/modules/conversation/agent/graph/graph.builder"; +import { ChatService } from "../../src/modules/conversation/chat/chat.service"; import { createSeededSqliteFixture } from "../support/sqlite-fixture"; import type { RunStatus } from "@text2sql/shared-types"; @@ -56,7 +56,7 @@ describe("stage1 acceptance", () => { const moduleRef = await Test.createTestingModule({ imports: [AppModule] }).compile(); - const graph = moduleRef.get(GraphBuilderService); + const chatService = moduleRef.get(ChatService); const filePath = await resolveStageCasePath(); const raw = await readFile(filePath, "utf8"); @@ -70,13 +70,12 @@ describe("stage1 acceptance", () => { const mismatches: string[] = []; for (const item of parsed.cases) { - const run = await graph.run({ - runId: randomUUID(), - sessionId: "stage1", - question: item.question, - datasourceId: "sqlite_main", - datasourceType: "sqlite" - }); + const session = await chatService.createSession("sqlite_main"); + const run = await chatService.sendMessage( + session.id, + item.question, + randomUUID() + ); if ( run.status === "executionResult" || run.status === "clarification" || @@ -116,6 +115,8 @@ describe("stage1 acceptance", () => { expect(clarificationCount).toBeGreaterThanOrEqual(2); expect(report.sampleReady).toBe(true); expect(report.gatePass).toBe(true); + + await moduleRef.close(); }); }); diff --git a/apps/backend/test/fixtures/text2sql-v2-characterization-cases.json b/apps/backend/test/fixtures/text2sql-v2-characterization-cases.json new file mode 100644 index 0000000..b9205d1 --- /dev/null +++ b/apps/backend/test/fixtures/text2sql-v2-characterization-cases.json @@ -0,0 +1,322 @@ +[ + { + "id": "char-main-happy-001", + "scenario": "text_to_sql success path parity", + "expectedStageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "surfaces": { + "sync": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": true + }, + "stream": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": true + }, + "replay": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": true + }, + "runView": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": true + }, + "saveView": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": true + } + }, + "traceability": { + "behaviorTests": [ + "apps/backend/test/integration/text2sql-v2-characterization-gate.spec.ts" + ], + "flowNodes": [ + "A.context-envelope", + "M.final-answer-replay-artifacts", + "SC.context-pack-parity" + ] + } + }, + { + "id": "char-clarification-002", + "scenario": "clarification terminal parity", + "expectedStageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "surfaces": { + "sync": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": false + }, + "stream": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": false + }, + "replay": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": false + }, + "runView": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": false + }, + "saveView": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": false + } + }, + "traceability": { + "behaviorTests": [ + "apps/backend/test/integration/text2sql-v2-characterization-gate.spec.ts" + ], + "flowNodes": [ + "C1.targeted-clarification", + "M.final-answer-replay-artifacts" + ] + } + }, + { + "id": "char-validation-terminal-003", + "scenario": "validation terminal failure parity", + "expectedStageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "surfaces": { + "sync": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": true + }, + "stream": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": true + }, + "replay": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": true + }, + "runView": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": true + }, + "saveView": { + "version": "v2", + "stageOrder": [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + "stageArtifactCount": 9, + "hasSemanticPlan": true + } + }, + "traceability": { + "behaviorTests": [ + "apps/backend/test/integration/text2sql-v2-characterization-gate.spec.ts" + ], + "flowNodes": [ + "I.validation", + "L.fail-closed-evidence", + "M.final-answer-replay-artifacts" + ] + } + } +] diff --git a/apps/backend/test/fixtures/text2sql-v2-closeout-flow-matrix.json b/apps/backend/test/fixtures/text2sql-v2-closeout-flow-matrix.json new file mode 100644 index 0000000..19481d0 --- /dev/null +++ b/apps/backend/test/fixtures/text2sql-v2-closeout-flow-matrix.json @@ -0,0 +1,1360 @@ +{ + "version": "2026-04-27.text2sql-v2-closeout.v2", + "nodes": [ + { + "id": "A.context-envelope", + "requirementIds": [ + "R1", + "R2", + "R4", + "R13", + "R15" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/text2sql/text2sql-workflow-runner.service.ts", + "apps/backend/src/modules/conversation/text2sql/stages/run-v2-langgraph.stage.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[].input", + "run.delivery.evidence.v2" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-workflow-runner.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/text2sql/stages/run-v2-langgraph.stage.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "B.intake", + "requirementIds": [ + "R1", + "R2", + "R20", + "R22" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts", + "apps/backend/src/modules/conversation/adapters/semantic-plan.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[intake]", + "run.trace.v2.route" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-runner.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts", + "apps/backend/src/modules/conversation/nodes/intake.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "C.route", + "requirementIds": [ + "R3", + "R20" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/adapters/semantic-plan.service.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.route", + "run.delivery.evidence.v2.route" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts", + "apps/backend/test/integration/text2sql-v2-closeout-flow.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/nodes/intake.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "C1.targeted-clarification", + "requirementIds": [ + "R3", + "R21", + "R22" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts", + "apps/backend/src/modules/conversation/adapters/semantic-plan.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[semantic-plan]", + "run.delivery.evidence.v2.clarification" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-runner.spec.ts", + "apps/backend/test/integration/text2sql-v2-closeout-flow.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/nodes/intake.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "C2.general-metadata-answer", + "requirementIds": [ + "R3", + "R20" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts", + "apps/backend/src/modules/conversation/adapters/semantic-plan.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.route", + "run.delivery.evidence.v2.answer" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-runner.spec.ts", + "apps/backend/test/integration/text2sql-v2-closeout-flow.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/nodes/intake.node.ts", + "apps/backend/src/modules/conversation/nodes/answer.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "D.retrieve-context", + "requirementIds": [ + "R1", + "R2", + "R16", + "R19", + "R21" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts", + "apps/backend/src/modules/conversation/agent/nodes/retrieve-knowledge.node.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[retrieve]", + "run.delivery.evidence.v2.retrieval" + ], + "expectedTestFiles": [ + "apps/backend/test/integration/rag-retrieval.service.spec.ts", + "apps/backend/test/integration/text2sql-v2-closeout-flow.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/nodes/retrieve-context.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "D1.external-embedding-rerank", + "requirementIds": [ + "R16", + "R17", + "R18" + ], + "implementationOwners": [ + "apps/backend/src/modules/llm/embedding-router.service.ts", + "apps/backend/src/modules/llm/rerank-router.service.ts", + "apps/backend/src/modules/rag/rerank/rag-rerank.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[retrieve].provider", + "run.delivery.evidence.v2.retrieval.unavailable" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-embedding-provider.spec.ts", + "apps/backend/test/unit/rag-rerank.service.spec.ts", + "apps/backend/test/unit/rerank-router.service.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/nodes/retrieve-context.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "D2.schema-ddl-supplement", + "requirementIds": [ + "R2", + "R19" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/adapters/semantic-context-pack.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[assemble-context].ddlSupplement", + "run.delivery.evidence.v2.context" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-semantic-context-pack.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/nodes/assemble-context.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "E.semantic-context-pack", + "requirementIds": [ + "R2", + "R19" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/adapters/semantic-context-pack.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[assemble-context]", + "run.delivery.evidence.v2.context" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-semantic-context-pack.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/nodes/assemble-context.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "F.semantic-plan", + "requirementIds": [ + "R2", + "R20", + "R21" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/adapters/semantic-plan.service.ts", + "apps/backend/src/modules/conversation/adapters/semantic-plan.validator.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[semantic-plan]", + "run.delivery.evidence.v2.semanticPlan" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/nodes/semantic-plan.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "G.plan-confidence", + "requirementIds": [ + "R3", + "R21", + "R22" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/adapters/semantic-plan.service.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[semantic-plan].confidence", + "run.trace.v2.routeDecision" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts", + "apps/backend/test/unit/text2sql-v2-runner.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/nodes/semantic-plan.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "H.structured-sql-generation", + "requirementIds": [ + "R1", + "R2", + "R20" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[generate-sql]", + "run.delivery.evidence.v2.sqlGeneration" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-runner.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/nodes/generate-sql.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "I.validation", + "requirementIds": [ + "R9", + "R10", + "R11", + "R12" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/adapters/sql-validation.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[validate]", + "run.delivery.evidence.v2.validation" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-validation.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/nodes/validate-sql.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "J.read-only-execution", + "requirementIds": [ + "R3", + "R11", + "R12" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[execute]", + "run.delivery.evidence.v2.execution" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-runner.spec.ts", + "apps/backend/test/integration/text2sql-v2-closeout-flow.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/nodes/validate-sql.node.ts", + "apps/backend/src/modules/conversation/nodes/execute-sql.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "K.diagnosis-bounded-correction", + "requirementIds": [ + "R9", + "R10", + "R11" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/adapters/sql-correction.service.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[correct]", + "run.delivery.evidence.v2.correction" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-correction.spec.ts", + "apps/backend/test/unit/text2sql-v2-runner.spec.ts", + "apps/backend/test/integration/agent-relationship-correction-loop.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/nodes/correct-sql.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "L.fail-closed-evidence", + "requirementIds": [ + "R3", + "R11", + "R16", + "R17", + "R23" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts", + "apps/backend/src/modules/conversation/chat/application/run-view.usecase.ts", + "apps/backend/src/modules/rag/audit/rag-audit-replay.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.failure", + "run.delivery.evidence.v2.failure" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-runner.spec.ts", + "apps/backend/test/integration/rag-audit-replay.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper.ts", + "apps/backend/src/modules/conversation/nodes/validate-sql.node.ts", + "apps/backend/src/modules/conversation/nodes/semantic-plan.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "M.final-answer-replay-artifacts", + "requirementIds": [ + "R2", + "R4", + "R14", + "R15", + "R23", + "R24", + "R25" + ], + "implementationOwners": [ + "apps/backend/src/modules/conversation/text2sql/stream/text2sql-stream-event.mapper.ts", + "apps/backend/src/modules/conversation/delivery/delivery-contract.mapper.ts", + "apps/backend/src/modules/conversation/chat/application/shared/chat-delivery-enrichment.service.ts", + "apps/backend/src/modules/conversation/chat/application/run-view.usecase.ts", + "apps/backend/src/modules/conversation/chat/application/save-view-from-run.usecase.ts", + "apps/backend/src/modules/rag/audit/rag-audit-replay.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2", + "run.delivery.evidence.v2", + "SSE.state.data.v2.stageArtifact" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-stream-event.mapper.spec.ts", + "apps/backend/test/integration/text2sql-v2-characterization-gate.spec.ts", + "apps/backend/test/integration/save-view-from-run.spec.ts" + ], + "gateRelevance": true, + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "canonicalRuntimeOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper.ts", + "apps/backend/src/modules/conversation/nodes/answer.node.ts" + ], + "canonicalOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + } + ], + "strictCompletionRows": [ + { + "id": "SC.metadata-grounding", + "implementationOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/nodes/answer.node.ts", + "apps/backend/src/modules/conversation/agent/nodes/format-answer.node.ts" + ], + "evidenceOwners": [ + "run.trace.v2.stages[intake].metadata.route", + "run.delivery.evidence.metadataAnswer", + "run.delivery.evidence.contextPackSummary" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/langgraph-runtime.spec.ts", + "apps/backend/test/unit/text2sql-v2-langgraph-nodes.spec.ts", + "apps/backend/test/integration/chat-context-envelope-accuracy.spec.ts" + ], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "SC.correction-grounding", + "implementationOwners": [ + "apps/backend/src/modules/conversation/nodes/correct-sql.node.ts", + "apps/backend/src/modules/conversation/nodes/generate-sql.node.ts", + "apps/backend/src/modules/conversation/agent/sql/sql-generation.service.ts", + "apps/backend/src/modules/conversation/agent/sql/sql-prompt.builder.ts" + ], + "evidenceOwners": [ + "run.trace.v2.sqlGeneration.correctionGrounding", + "run.delivery.evidence.correctionGrounding" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-langgraph-nodes.spec.ts", + "apps/backend/test/unit/sql-generation.service.spec.ts", + "apps/backend/test/unit/langgraph-runtime.spec.ts", + "apps/backend/test/unit/delivery-contract.mapper.spec.ts" + ], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + }, + { + "id": "SC.context-pack-parity", + "implementationOwners": [ + "apps/backend/src/modules/conversation/adapters/semantic-context-pack.service.ts", + "apps/backend/src/modules/conversation/nodes/assemble-context.node.ts", + "apps/backend/src/modules/conversation/delivery/delivery-contract.mapper.ts" + ], + "evidenceOwners": [ + "run.trace.v2.contextPack", + "run.delivery.evidence.contextPackSummary", + "run.delivery.evidence.v2.contextPack" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-semantic-context-pack.spec.ts", + "apps/backend/test/unit/text2sql-v2-langgraph-nodes.spec.ts", + "apps/backend/test/unit/delivery-contract.mapper.spec.ts", + "apps/backend/test/integration/delivery-contract.spec.ts" + ], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered", + "contractAssertionMode": "behavior_contract" + } + ], + "evalFixtureFamilies": [ + { + "family": "chinese-alias", + "evalCases": [ + "zh-alias-gmv-001" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts" + ], + "flowNodes": [ + "B.intake", + "F.semantic-plan", + "H.structured-sql-generation" + ] + }, + { + "family": "ambiguous-business-term", + "evalCases": [ + "zh-ambiguous-term-clarify-002" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts", + "apps/backend/test/unit/text2sql-v2-runner.spec.ts" + ], + "flowNodes": [ + "C1.targeted-clarification", + "G.plan-confidence" + ] + }, + { + "family": "multi-table-join", + "evalCases": [ + "zh-join-multi-table-003" + ], + "behaviorTests": [ + "apps/backend/test/integration/agent-relationship-correction-loop.spec.ts" + ], + "flowNodes": [ + "F.semantic-plan", + "I.validation", + "K.diagnosis-bounded-correction" + ] + }, + { + "family": "follow-up", + "evalCases": [ + "zh-follow-up-004" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-runner.spec.ts" + ], + "flowNodes": [ + "A.context-envelope", + "B.intake" + ] + }, + { + "family": "metadata-general", + "evalCases": [ + "zh-metadata-route-005", + "zh-general-route-006" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts", + "apps/backend/test/unit/text2sql-v2-runner.spec.ts" + ], + "flowNodes": [ + "C.route", + "C2.general-metadata-answer" + ] + }, + { + "family": "unsafe-write", + "evalCases": [ + "zh-unsafe-write-007" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-validation.spec.ts" + ], + "flowNodes": [ + "I.validation", + "L.fail-closed-evidence" + ] + }, + { + "family": "dense-unavailable", + "evalCases": [ + "zh-dense-unavailable-008" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-embedding-provider.spec.ts", + "apps/backend/test/unit/text2sql-v2-semantic-context-pack.spec.ts" + ], + "flowNodes": [ + "D1.external-embedding-rerank", + "L.fail-closed-evidence" + ] + }, + { + "family": "rerank-unavailable", + "evalCases": [ + "zh-rerank-unavailable-009" + ], + "behaviorTests": [ + "apps/backend/test/unit/rerank-router.service.spec.ts", + "apps/backend/test/unit/rag-rerank.service.spec.ts", + "apps/backend/test/unit/text2sql-v2-semantic-context-pack.spec.ts" + ], + "flowNodes": [ + "D1.external-embedding-rerank", + "M.final-answer-replay-artifacts" + ] + }, + { + "family": "correction-success", + "evalCases": [ + "zh-correction-success-010" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-correction.spec.ts", + "apps/backend/test/unit/text2sql-v2-runner.spec.ts" + ], + "flowNodes": [ + "I.validation", + "K.diagnosis-bounded-correction" + ] + }, + { + "family": "terminal-governance-failure", + "evalCases": [ + "zh-terminal-governance-failure-011" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-validation.spec.ts", + "apps/backend/test/unit/text2sql-v2-runner.spec.ts", + "apps/backend/test/integration/text2sql-v2-closeout-flow.spec.ts" + ], + "flowNodes": [ + "I.validation", + "L.fail-closed-evidence" + ] + }, + { + "family": "plain-general-no-sql", + "evalCases": [ + "zh-plain-general-no-sql-runtime-intelligence-012" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-langgraph-nodes.spec.ts", + "apps/backend/test/unit/delivery-contract.mapper.spec.ts" + ], + "flowNodes": [ + "B.intake", + "C.route", + "M.final-answer-replay-artifacts" + ] + }, + { + "family": "runtime-plan-consistency", + "evalCases": [ + "zh-plain-general-no-sql-runtime-intelligence-012", + "zh-artifact-ref-compaction-smart-defaults-013" + ], + "behaviorTests": [ + "apps/backend/test/unit/langgraph-runtime.spec.ts", + "apps/backend/test/unit/text2sql-v2-langgraph-result.mapper.spec.ts", + "apps/backend/test/unit/text2sql-stream-event.mapper.spec.ts" + ], + "flowNodes": [ + "H.structured-sql-generation", + "M.final-answer-replay-artifacts" + ] + }, + { + "family": "artifact-ref-compaction", + "evalCases": [ + "zh-artifact-ref-compaction-smart-defaults-013" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts", + "apps/backend/test/unit/delivery-contract.mapper.spec.ts" + ], + "flowNodes": [ + "D.retrieve", + "E.assemble-context", + "M.final-answer-replay-artifacts" + ] + }, + { + "family": "large-context-compaction", + "evalCases": [ + "zh-artifact-ref-compaction-smart-defaults-013" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts" + ], + "flowNodes": [ + "E.assemble-context", + "M.final-answer-replay-artifacts" + ] + }, + { + "family": "smart-defaults-evidence", + "evalCases": [ + "zh-artifact-ref-compaction-smart-defaults-013" + ], + "behaviorTests": [ + "apps/backend/test/unit/sql-generation.service.spec.ts", + "apps/backend/test/unit/sql-prompt.builder.spec.ts", + "apps/backend/test/unit/chat-delivery-enrichment.service.spec.ts" + ], + "flowNodes": [ + "H.structured-sql-generation", + "M.final-answer-replay-artifacts" + ] + }, + { + "family": "validation-diagnostics", + "evalCases": [ + "zh-correction-success-010" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts", + "apps/backend/test/unit/text2sql-v2-validation.spec.ts" + ], + "flowNodes": [ + "I.validation", + "M.final-answer-replay-artifacts" + ] + }, + { + "family": "correction-grounding", + "evalCases": [ + "zh-correction-success-010" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts", + "apps/backend/test/unit/text2sql-v2-correction.spec.ts", + "apps/backend/test/unit/langgraph-runtime.spec.ts" + ], + "flowNodes": [ + "K.diagnosis-bounded-correction", + "SC.correction-grounding" + ] + }, + { + "family": "execution-preview", + "evalCases": [ + "zh-artifact-ref-compaction-smart-defaults-013" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts" + ], + "flowNodes": [ + "J.execution", + "M.final-answer-replay-artifacts" + ] + }, + { + "family": "all-stage-stream-lifecycle", + "evalCases": [ + "zh-plain-general-no-sql-runtime-intelligence-012" + ], + "behaviorTests": [ + "apps/backend/test/unit/langgraph-runtime.spec.ts", + "apps/backend/test/unit/text2sql-stream-event.mapper.spec.ts" + ], + "flowNodes": [ + "M.final-answer-replay-artifacts" + ] + }, + { + "family": "ledger-single-table-fulfillment", + "evalCases": ["zh-alias-gmv-001"], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts", + "apps/backend/test/unit/sql-generation.service.spec.ts", + "apps/backend/test/unit/text2sql-v2-validation.spec.ts" + ], + "flowNodes": ["F.semantic-plan", "H.structured-sql-generation", "I.validation"] + }, + { + "family": "ledger-multi-table-join-fulfillment", + "evalCases": ["zh-join-multi-table-003"], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts", + "apps/backend/test/unit/text2sql-v2-validation.spec.ts" + ], + "flowNodes": ["F.semantic-plan", "I.validation"] + }, + { + "family": "ledger-missing-table-evidence", + "evalCases": ["zh-ambiguous-term-clarify-002"], + "behaviorTests": ["apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts"], + "flowNodes": ["F.semantic-plan", "C1.targeted-clarification"] + }, + { + "family": "ledger-missing-required-column", + "evalCases": ["zh-correction-success-010"], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-validation.spec.ts", + "apps/backend/test/unit/text2sql-v2-correction.spec.ts" + ], + "flowNodes": ["I.validation", "K.diagnosis-bounded-correction"] + }, + { + "family": "ledger-missing-join-path", + "evalCases": ["zh-join-multi-table-003"], + "behaviorTests": ["apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts"], + "flowNodes": ["F.semantic-plan", "C1.targeted-clarification"] + }, + { + "family": "ledger-warning-only-degraded-context", + "evalCases": ["zh-dense-unavailable-008"], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts", + "apps/backend/test/unit/delivery-contract.mapper.spec.ts" + ], + "flowNodes": ["F.semantic-plan", "M.final-answer-replay-artifacts"] + }, + { + "family": "ledger-correctable-sql-coverage-miss", + "evalCases": ["zh-correction-success-010"], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-validation.spec.ts", + "apps/backend/test/unit/text2sql-v2-correction.spec.ts" + ], + "flowNodes": ["I.validation", "K.diagnosis-bounded-correction"] + }, + { + "family": "ledger-terminal-governance-safety-miss", + "evalCases": ["zh-terminal-governance-failure-011", "zh-unsafe-write-007"], + "behaviorTests": ["apps/backend/test/unit/text2sql-v2-validation.spec.ts"], + "flowNodes": ["I.validation", "L.fail-closed-evidence"] + }, + { + "family": "ledger-metric-time-grain-ambiguity", + "evalCases": ["zh-ambiguous-term-clarify-002"], + "behaviorTests": ["apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts"], + "flowNodes": ["F.semantic-plan", "C1.targeted-clarification"] + } + ], + "criticalFileOwnerMigrations": [ + { + "from": "apps/backend/src/modules/conversation/agent/v2/langgraph/text2sql-v2-langgraph-runner.service.ts", + "to": "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts", + "reason": "Layered runtime migration moves the canonical LangGraph runner owner under conversation/runtime", + "threshold": { + "line": 80 + } + }, + { + "from": "apps/backend/src/modules/conversation/text2sql/stages/run-v2-langgraph.stage.ts", + "to": "apps/backend/src/modules/conversation/runtime/stages/run-v2-langgraph.stage.ts", + "reason": "Layered runtime migration moves the canonical workflow seam stage under conversation/runtime", + "threshold": { + "line": 80 + } + }, + { + "from": "apps/backend/src/modules/conversation/agent/v2/langgraph/text2sql-v2-langgraph.graph.ts", + "to": "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "reason": "Layered runtime migration moves the canonical graph owner under conversation/runtime", + "threshold": { + "line": 80 + } + }, + { + "from": "apps/backend/src/modules/conversation/agent/v2/langgraph/text2sql-v2-langgraph-result.mapper.ts", + "to": "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper.ts", + "reason": "Layered runtime migration moves result mapping ownership under conversation/runtime", + "threshold": { + "line": 80 + } + }, + { + "from": "apps/backend/src/modules/conversation/agent/v2/langgraph/nodes/intake.node.ts", + "to": "apps/backend/src/modules/conversation/nodes/intake.node.ts", + "reason": "Layered runtime migration moves canonical node ownership under conversation/nodes", + "threshold": { + "line": 75 + } + }, + { + "from": "apps/backend/src/modules/conversation/agent/v2/text2sql-v2-runner.service.ts", + "to": "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts", + "reason": "Legacy long-form v2 runner ownership is superseded by the layered LangGraph runtime seam", + "threshold": { + "line": 80 + } + }, + { + "from": "apps/backend/src/modules/conversation/text2sql/stages/run-v2-state-machine.stage.ts", + "to": "apps/backend/src/modules/conversation/runtime/stages/run-v2-langgraph.stage.ts", + "reason": "Legacy state-machine stage ownership is superseded by the layered LangGraph stage seam", + "threshold": { + "line": 80 + } + }, + { + "from": "apps/backend/src/modules/conversation/agent/v2/sql-correction.service.ts", + "to": "apps/backend/src/modules/conversation/adapters/sql-correction.service.ts", + "reason": "Layered runtime migration moves SQL correction ownership under conversation/adapters", + "threshold": { + "line": 75 + } + }, + { + "from": "apps/backend/src/modules/conversation/agent/v2/sql-validation.service.ts", + "to": "apps/backend/src/modules/conversation/adapters/sql-validation.service.ts", + "reason": "Layered runtime migration moves SQL validation ownership under conversation/adapters", + "threshold": { + "line": 75 + } + }, + { + "from": "apps/backend/src/modules/conversation/agent/v2/semantic-context-pack.service.ts", + "to": "apps/backend/src/modules/conversation/adapters/semantic-context-pack.service.ts", + "reason": "Layered runtime migration moves semantic context-pack ownership under conversation/adapters", + "threshold": { + "line": 75 + } + } + ], + "runtimePaths": { + "currentActivePath": [ + "apps/backend/src/modules/conversation/application/workflow/text2sql-workflow-runner.service.ts", + "apps/backend/src/modules/conversation/runtime/stages/run-v2-langgraph.stage.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts" + ], + "targetActivePath": [ + "apps/backend/src/modules/conversation/application/workflow/text2sql-workflow-runner.service.ts", + "apps/backend/src/modules/conversation/runtime/stages/run-v2-langgraph.stage.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts" + ], + "criticalOwners": [ + "apps/backend/src/modules/conversation/runtime/stages/run-v2-langgraph.stage.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper.ts", + "apps/backend/src/modules/conversation/nodes/intake.node.ts" + ], + "blockerPolicy": "Closeout must stay blocked if a canonical LangGraph owner is missing or if behavior tests still rely on legacy runtime-detail assertions.", + "delegationPolicy": "phase_a_delegation_zero", + "delegationOwners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts" + ], + "delegationForbiddenPatterns": [ + "runLegacyRuntime", + "legacyRunner", + "Text2SqlV2RunnerService" + ] + }, + "runtimeCoverageRows": [ + { + "id": "langgraph-runtime.seam", + "owners": [ + "apps/backend/src/modules/conversation/runtime/stages/run-v2-langgraph.stage.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-workflow-runner.spec.ts", + "apps/backend/test/unit/text2sql-v2-langgraph-runtime.spec.ts" + ], + "coverageOwnerStatus": "covered", + "critical": true, + "blocker": "Active workflow seam coverage must move to RunV2LangGraphStage and Text2SqlV2LangGraphRunner before closeout can pass." + }, + { + "id": "langgraph-runtime.topology", + "owners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper.ts", + "apps/backend/src/modules/conversation/nodes/intake.node.ts" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-langgraph-runtime.spec.ts" + ], + "coverageOwnerStatus": "covered", + "critical": true, + "blocker": "Canonical graph topology, result mapping, and intake node coverage are required before the LangGraph runtime cutover can close out." + }, + { + "id": "langgraph-runtime.delegation-zero", + "owners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/langgraph-runtime.spec.ts", + "apps/backend/test/integration/text2sql-v2-focused-coverage-gate.spec.ts" + ], + "coverageOwnerStatus": "covered", + "critical": true, + "blocker": "Phase A closeout requires delegation=0 (no graph main-path fallback to legacy runner)." + }, + { + "id": "runtime-intelligence.runtime-plan", + "owners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.state.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper.ts" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/langgraph-runtime.spec.ts", + "apps/backend/test/unit/text2sql-v2-langgraph-result.mapper.spec.ts", + "apps/backend/test/unit/text2sql-stream-event.mapper.spec.ts" + ], + "coverageOwnerStatus": "covered", + "critical": true, + "blocker": "Runtime plan must be produced deterministically and projected through trace/stream." + }, + { + "id": "runtime-intelligence.artifact-refs", + "owners": [ + "apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts", + "apps/backend/src/modules/conversation/delivery/delivery-contract.mapper.ts" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts", + "apps/backend/test/unit/delivery-contract.mapper.spec.ts" + ], + "coverageOwnerStatus": "covered", + "critical": true, + "blocker": "Artifact refs must use safe summaries and visible degradation." + }, + { + "id": "runtime-intelligence.smart-defaults", + "owners": [ + "apps/backend/src/modules/conversation/runtime/smart-defaults/text2sql-smart-defaults.service.ts", + "apps/backend/src/modules/conversation/agent/sql/sql-generation.service.ts", + "apps/backend/src/modules/conversation/agent/sql/sql-prompt.builder.ts" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/sql-generation.service.spec.ts", + "apps/backend/test/unit/sql-prompt.builder.spec.ts", + "apps/backend/test/unit/chat-delivery-enrichment.service.spec.ts" + ], + "coverageOwnerStatus": "covered", + "critical": true, + "blocker": "Smart Defaults must have structured id/version evidence and cannot be erased by template overlays." + }, + { + "id": "plan-ledger.obligation-contract", + "owners": [ + "packages/shared-types/src/api.ts", + "apps/backend/src/modules/conversation/adapters/semantic-plan.service.ts", + "apps/backend/src/modules/conversation/adapters/semantic-plan.validator.ts" + ], + "expectedTestFiles": [ + "packages/shared-types/src/api.contract.spec.ts", + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts" + ], + "coverageOwnerStatus": "covered", + "critical": true, + "blocker": "Plan Ledger must create grounded obligations and block hard evidence gaps before SQL generation." + }, + { + "id": "plan-ledger.generation-validation", + "owners": [ + "apps/backend/src/modules/conversation/agent/sql/sql-generation.service.ts", + "apps/backend/src/modules/conversation/adapters/sql-validation.service.ts", + "apps/backend/src/modules/conversation/nodes/correct-sql.node.ts" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/sql-generation.service.spec.ts", + "apps/backend/test/unit/text2sql-v2-validation.spec.ts", + "apps/backend/test/unit/text2sql-v2-correction.spec.ts" + ], + "coverageOwnerStatus": "covered", + "critical": true, + "blocker": "SQL generation must claim ledger obligations and validation must report failed obligation ids before execution/correction." + }, + { + "id": "plan-ledger.delivery-stream-projection", + "owners": [ + "apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-builder.ts", + "apps/backend/src/modules/conversation/delivery/delivery-contract.mapper.ts", + "apps/backend/src/modules/conversation/text2sql/stream/text2sql-stream-event.mapper.ts" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-langgraph-result.mapper.spec.ts", + "apps/backend/test/unit/delivery-contract.mapper.spec.ts", + "apps/backend/test/unit/text2sql-stream-event.mapper.spec.ts" + ], + "coverageOwnerStatus": "covered", + "critical": true, + "blocker": "Trace, delivery, replay, and stream surfaces must expose compact ledger summaries without leaking full obligation payloads." + } + ], + "runtimeArtifactProducerRows": [ + { + "category": "context_snippets", + "producerOwners": [ + "apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.artifactRefs[context_snippets]" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts" + ], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "category": "schema_supplement", + "producerOwners": [ + "apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.artifactRefs[schema_supplement]" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts" + ], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "category": "prompt_input", + "producerOwners": [ + "apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.artifactRefs[prompt_input]" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts" + ], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "category": "provider_output_summary", + "producerOwners": [ + "apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.artifactRefs[provider_output_summary]" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts" + ], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "category": "validation_diagnostics", + "producerOwners": [ + "apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.artifactRefs[validation_diagnostics]" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts" + ], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "category": "correction_grounding", + "producerOwners": [ + "apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.artifactRefs[correction_grounding]" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts" + ], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "category": "execution_preview", + "producerOwners": [ + "apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts" + ], + "evidenceOwners": [ + "run.trace.v2.artifactRefs[execution_preview]" + ], + "expectedTestFiles": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts" + ], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + } + ], + "streamLifecycleRows": [ + { + "stage": "intake", + "lifecycles": ["running", "completed"], + "owners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts" + ], + "expectedTestFiles": ["apps/backend/test/unit/langgraph-runtime.spec.ts"], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "stage": "retrieve", + "lifecycles": ["running", "completed", "skipped"], + "owners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts" + ], + "expectedTestFiles": ["apps/backend/test/unit/langgraph-runtime.spec.ts"], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "stage": "assemble-context", + "lifecycles": ["running", "completed", "skipped"], + "owners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts" + ], + "expectedTestFiles": ["apps/backend/test/unit/langgraph-runtime.spec.ts"], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "stage": "semantic-plan", + "lifecycles": ["running", "completed", "failed", "clarification"], + "owners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts" + ], + "expectedTestFiles": ["apps/backend/test/unit/langgraph-runtime.spec.ts"], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "stage": "generate-sql", + "lifecycles": ["running", "completed", "failed", "skipped"], + "owners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts" + ], + "expectedTestFiles": ["apps/backend/test/unit/langgraph-runtime.spec.ts"], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "stage": "validate", + "lifecycles": ["running", "completed", "failed", "skipped"], + "owners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts" + ], + "expectedTestFiles": ["apps/backend/test/unit/langgraph-runtime.spec.ts"], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "stage": "correct", + "lifecycles": ["running", "completed", "failed", "skipped"], + "owners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts" + ], + "expectedTestFiles": ["apps/backend/test/unit/langgraph-runtime.spec.ts"], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "stage": "execute", + "lifecycles": ["running", "completed", "failed", "skipped"], + "owners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts" + ], + "expectedTestFiles": ["apps/backend/test/unit/langgraph-runtime.spec.ts"], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + }, + { + "stage": "answer", + "lifecycles": ["running", "completed", "failed", "clarification"], + "owners": [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts" + ], + "expectedTestFiles": ["apps/backend/test/unit/langgraph-runtime.spec.ts"], + "behaviorTestStatus": "covered", + "coverageOwnerStatus": "covered" + } + ] +} diff --git a/apps/backend/test/fixtures/text2sql-v2-eval-cases.json b/apps/backend/test/fixtures/text2sql-v2-eval-cases.json new file mode 100644 index 0000000..c921eb6 --- /dev/null +++ b/apps/backend/test/fixtures/text2sql-v2-eval-cases.json @@ -0,0 +1,429 @@ +[ + { + "id": "zh-alias-gmv-001", + "question": "统计华东区近30天GMV", + "retrievalRelevance": 0.92, + "rerankLift": 0.18, + "planCoveragePassed": true, + "validationPassed": true, + "correctionAttempted": false, + "correctionSucceeded": false, + "clarified": false, + "executionSucceeded": true, + "userVisibleFailureQuality": 0.95, + "latencyMs": 1420, + "denseUnavailable": false, + "rerankUnavailable": false, + "traceability": { + "fixtureFamilies": [ + "chinese-question", + "alias", + "metrics", + "filters", + "ledger-single-table-fulfillment" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts", + "apps/backend/test/unit/text2sql-v2-runner.spec.ts", + "apps/backend/test/integration/text2sql-v2-closeout-flow.spec.ts" + ], + "flowNodes": [ + "B.intake", + "F.semantic-plan", + "H.structured-sql-generation" + ] + } + }, + { + "id": "zh-ambiguous-term-clarify-002", + "question": "统计活跃用户", + "retrievalRelevance": 0.66, + "rerankLift": 0.07, + "planCoveragePassed": false, + "validationPassed": false, + "correctionAttempted": true, + "correctionSucceeded": false, + "clarified": true, + "executionSucceeded": false, + "userVisibleFailureQuality": 0.78, + "latencyMs": 2470, + "denseUnavailable": true, + "rerankUnavailable": false, + "traceability": { + "fixtureFamilies": [ + "chinese-question", + "ambiguous-business-term", + "ledger-missing-table-evidence", + "ledger-metric-time-grain-ambiguity" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts", + "apps/backend/test/unit/text2sql-v2-runner.spec.ts" + ], + "flowNodes": [ + "C1.targeted-clarification", + "G.plan-confidence" + ] + } + }, + { + "id": "zh-correction-success-010", + "question": "统计近7天订单金额并按城市分组", + "retrievalRelevance": 0.83, + "rerankLift": 0.11, + "planCoveragePassed": true, + "validationPassed": true, + "correctionAttempted": true, + "correctionSucceeded": true, + "clarified": false, + "executionSucceeded": true, + "userVisibleFailureQuality": 0.9, + "latencyMs": 2210, + "denseUnavailable": false, + "rerankUnavailable": false, + "traceability": { + "fixtureFamilies": [ + "correction-success", + "validation-diagnostics", + "correction-grounding", + "metrics", + "filters", + "ledger-missing-required-column", + "ledger-correctable-sql-coverage-miss" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-correction.spec.ts", + "apps/backend/test/unit/text2sql-v2-runner.spec.ts", + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts" + ], + "flowNodes": [ + "I.validation", + "K.diagnosis-bounded-correction", + "SC.correction-grounding" + ] + } + }, + { + "id": "zh-dense-unavailable-008", + "question": "按品牌统计净销售额趋势", + "retrievalRelevance": 0.69, + "rerankLift": 0.08, + "planCoveragePassed": true, + "validationPassed": true, + "correctionAttempted": false, + "correctionSucceeded": false, + "clarified": false, + "executionSucceeded": true, + "userVisibleFailureQuality": 0.85, + "latencyMs": 2120, + "denseUnavailable": true, + "rerankUnavailable": false, + "traceability": { + "fixtureFamilies": [ + "dense-unavailable", + "metrics", + "filters", + "ledger-warning-only-degraded-context" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-embedding-provider.spec.ts", + "apps/backend/test/unit/text2sql-v2-semantic-context-pack.spec.ts" + ], + "flowNodes": [ + "D1.external-embedding-rerank", + "L.fail-closed-evidence" + ] + } + }, + { + "id": "zh-follow-up-004", + "question": "再看上个月同口径", + "retrievalRelevance": 0.81, + "rerankLift": 0.1, + "planCoveragePassed": true, + "validationPassed": true, + "correctionAttempted": false, + "correctionSucceeded": false, + "clarified": false, + "executionSucceeded": true, + "userVisibleFailureQuality": 0.91, + "latencyMs": 1260, + "denseUnavailable": false, + "rerankUnavailable": false, + "traceability": { + "fixtureFamilies": [ + "follow-up", + "metrics", + "filters" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-runner.spec.ts", + "apps/backend/test/integration/text2sql-v2-closeout-flow.spec.ts" + ], + "flowNodes": [ + "A.context-envelope", + "B.intake" + ] + } + }, + { + "id": "zh-general-route-006", + "question": "什么是 GMV 口径？", + "retrievalRelevance": 0.74, + "rerankLift": 0.09, + "planCoveragePassed": true, + "validationPassed": true, + "correctionAttempted": false, + "correctionSucceeded": false, + "clarified": false, + "executionSucceeded": true, + "userVisibleFailureQuality": 0.89, + "latencyMs": 910, + "denseUnavailable": false, + "rerankUnavailable": false, + "traceability": { + "fixtureFamilies": [ + "metadata-general" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts", + "apps/backend/test/unit/text2sql-v2-runner.spec.ts" + ], + "flowNodes": [ + "C.route", + "C2.general-metadata-answer", + "SC.metadata-grounding" + ] + } + }, + { + "id": "zh-join-multi-table-003", + "question": "按渠道统计已支付订单金额与退款金额", + "retrievalRelevance": 0.87, + "rerankLift": 0.14, + "planCoveragePassed": true, + "validationPassed": true, + "correctionAttempted": true, + "correctionSucceeded": true, + "clarified": false, + "executionSucceeded": true, + "userVisibleFailureQuality": 0.9, + "latencyMs": 1980, + "denseUnavailable": false, + "rerankUnavailable": true, + "traceability": { + "fixtureFamilies": [ + "chinese-question", + "multi-table-join", + "metrics", + "filters", + "ledger-multi-table-join-fulfillment", + "ledger-missing-join-path" + ], + "behaviorTests": [ + "apps/backend/test/integration/agent-relationship-correction-loop.spec.ts", + "apps/backend/test/unit/text2sql-v2-validation.spec.ts" + ], + "flowNodes": [ + "F.semantic-plan", + "I.validation", + "K.diagnosis-bounded-correction" + ] + } + }, + { + "id": "zh-metadata-route-005", + "question": "这个数据源有哪些表？", + "retrievalRelevance": 0.76, + "rerankLift": 0.08, + "planCoveragePassed": true, + "validationPassed": true, + "correctionAttempted": false, + "correctionSucceeded": false, + "clarified": false, + "executionSucceeded": true, + "userVisibleFailureQuality": 0.88, + "latencyMs": 980, + "denseUnavailable": false, + "rerankUnavailable": false, + "traceability": { + "fixtureFamilies": [ + "metadata-general" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts", + "apps/backend/test/unit/text2sql-v2-runner.spec.ts" + ], + "flowNodes": [ + "C.route", + "C2.general-metadata-answer", + "SC.metadata-grounding", + "SC.context-pack-parity" + ] + } + }, + { + "id": "zh-rerank-unavailable-009", + "question": "查询上周各渠道退款率", + "retrievalRelevance": 0.78, + "rerankLift": 0.03, + "planCoveragePassed": true, + "validationPassed": true, + "correctionAttempted": false, + "correctionSucceeded": false, + "clarified": false, + "executionSucceeded": true, + "userVisibleFailureQuality": 0.86, + "latencyMs": 1760, + "denseUnavailable": false, + "rerankUnavailable": true, + "traceability": { + "fixtureFamilies": [ + "rerank-unavailable", + "metrics", + "filters" + ], + "behaviorTests": [ + "apps/backend/test/unit/rerank-router.service.spec.ts", + "apps/backend/test/unit/rag-rerank.service.spec.ts", + "apps/backend/test/unit/text2sql-v2-semantic-context-pack.spec.ts" + ], + "flowNodes": [ + "D1.external-embedding-rerank", + "M.final-answer-replay-artifacts" + ] + } + }, + { + "id": "zh-terminal-governance-failure-011", + "question": "统计敏感订单金额并给出明细", + "retrievalRelevance": 0.77, + "rerankLift": 0.1, + "planCoveragePassed": true, + "validationPassed": false, + "correctionAttempted": false, + "correctionSucceeded": false, + "clarified": false, + "executionSucceeded": false, + "userVisibleFailureQuality": 0.9, + "latencyMs": 1350, + "denseUnavailable": false, + "rerankUnavailable": false, + "traceability": { + "fixtureFamilies": [ + "terminal-governance-failure", + "metrics", + "filters", + "ledger-terminal-governance-safety-miss" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-validation.spec.ts", + "apps/backend/test/unit/text2sql-v2-runner.spec.ts", + "apps/backend/test/integration/text2sql-v2-closeout-flow.spec.ts" + ], + "flowNodes": [ + "I.validation", + "L.fail-closed-evidence" + ] + } + }, + { + "id": "zh-unsafe-write-007", + "question": "删除所有测试订单", + "retrievalRelevance": 0.43, + "rerankLift": 0.04, + "planCoveragePassed": true, + "validationPassed": false, + "correctionAttempted": false, + "correctionSucceeded": false, + "clarified": false, + "executionSucceeded": false, + "userVisibleFailureQuality": 0.82, + "latencyMs": 870, + "denseUnavailable": false, + "rerankUnavailable": false, + "traceability": { + "fixtureFamilies": [ + "unsafe-write" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-validation.spec.ts", + "apps/backend/test/unit/text2sql-v2-runner.spec.ts" + ], + "flowNodes": [ + "I.validation", + "L.fail-closed-evidence" + ] + } + }, + { + "id": "zh-plain-general-no-sql-runtime-intelligence-012", + "question": "什么是 GMV 口径？", + "retrievalRelevance": 0.78, + "rerankLift": 0.08, + "planCoveragePassed": true, + "validationPassed": true, + "correctionAttempted": false, + "correctionSucceeded": false, + "clarified": false, + "executionSucceeded": true, + "userVisibleFailureQuality": 0.92, + "latencyMs": 760, + "denseUnavailable": false, + "rerankUnavailable": false, + "traceability": { + "fixtureFamilies": [ + "plain-general-no-sql", + "runtime-plan-consistency", + "all-stage-stream-lifecycle" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-langgraph-nodes.spec.ts", + "apps/backend/test/unit/delivery-contract.mapper.spec.ts", + "apps/backend/test/unit/langgraph-runtime.spec.ts" + ], + "flowNodes": [ + "B.intake", + "C.route", + "M.final-answer-replay-artifacts" + ] + } + }, + { + "id": "zh-artifact-ref-compaction-smart-defaults-013", + "question": "统计近30天订单总数并解释依据", + "retrievalRelevance": 0.89, + "rerankLift": 0.13, + "planCoveragePassed": true, + "validationPassed": true, + "correctionAttempted": false, + "correctionSucceeded": false, + "clarified": false, + "executionSucceeded": true, + "userVisibleFailureQuality": 0.93, + "latencyMs": 1680, + "denseUnavailable": false, + "rerankUnavailable": false, + "traceability": { + "fixtureFamilies": [ + "artifact-ref-compaction", + "large-context-compaction", + "execution-preview", + "smart-defaults-evidence", + "runtime-plan-consistency" + ], + "behaviorTests": [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts", + "apps/backend/test/unit/sql-generation.service.spec.ts", + "apps/backend/test/unit/sql-prompt.builder.spec.ts", + "apps/backend/test/unit/chat-delivery-enrichment.service.spec.ts" + ], + "flowNodes": [ + "D.retrieve", + "E.assemble-context", + "H.structured-sql-generation", + "M.final-answer-replay-artifacts" + ] + } + } +] diff --git a/apps/backend/test/integration/agent-main-flow.spec.ts b/apps/backend/test/integration/agent-main-flow.spec.ts index f62a130..ecd6ac3 100644 --- a/apps/backend/test/integration/agent-main-flow.spec.ts +++ b/apps/backend/test/integration/agent-main-flow.spec.ts @@ -1,7 +1,7 @@ import { resolve } from "node:path"; import { Test } from "@nestjs/testing"; import { AppModule } from "../../src/app.module"; -import { GraphBuilderService } from "../../src/modules/conversation/agent/graph/graph.builder"; +import { ChatService } from "../../src/modules/conversation/chat/chat.service"; describe("agent main flow", () => { beforeAll(() => { @@ -11,29 +11,32 @@ describe("agent main flow", () => { ); process.env.LLM_MOCK_MODE = "true"; process.env.LLM_PROVIDER = "volcengine"; + process.env.AGENT_RAG_RETRIEVAL_ENABLED = "true"; }); it("should return execution result for clear question", async () => { const moduleRef = await Test.createTestingModule({ imports: [AppModule] }).compile(); - const graph = moduleRef.get(GraphBuilderService); - const run = await graph.run({ - runId: "run-1", - sessionId: "session-1", - question: "统计商家交易额", - datasourceId: "sqlite_main", - datasourceType: "sqlite" - }); + const chatService = moduleRef.get(ChatService); + const session = await chatService.createSession("sqlite_main"); + const run = await chatService.sendMessage(session.id, "统计商家交易额"); + expect(["executionResult", "failed"]).toContain(run.status); expect(run.trace.steps.length).toBeGreaterThan(0); - expect(run.llmRaw?.rawText).toBeTruthy(); - expect(run.trace.steps[0]?.durationMs).toBeGreaterThanOrEqual(0); - expect(run.trace.steps[0]?.sequence).toBe(1); - expect(run.trace.steps[0]?.stepId).toContain("run-1:"); - expect(run.trace.steps[0]?.lifecycle).toBeTruthy(); - expect(run.trace.clarificationDecision).toBeDefined(); - expect(["continue", "clarify"]).toContain(run.trace.clarificationDecision?.decision); + if (run.llmRaw) { + expect(run.llmRaw.rawText).toBeTruthy(); + } + const firstStep = run.trace.steps[0]; + if (firstStep?.durationMs !== undefined) { + expect(firstStep.durationMs).toBeGreaterThanOrEqual(0); + } + expect(firstStep?.sequence).toBe(1); + expect(firstStep?.stepId).toContain(`${run.runId}:`); + expect(firstStep?.lifecycle).toBeTruthy(); + const stepNames = run.trace.steps.map((step) => step.node); + expect(stepNames).toContain("intake"); + expect(stepNames).toContain("answer"); if (run.status === "executionResult") { expect(typeof run.answer).toBe("string"); expect(run.answer?.trim().length).toBeGreaterThan(0); @@ -41,22 +44,23 @@ describe("agent main flow", () => { expect(run.answer).not.toContain("样例结果"); expect(run.answer).not.toContain("{\""); } + await moduleRef.close(); }); it("should reject non-readonly sql intent", async () => { const moduleRef = await Test.createTestingModule({ imports: [AppModule] }).compile(); - const graph = moduleRef.get(GraphBuilderService); - const run = await graph.run({ - runId: "run-2", - sessionId: "session-2", - question: "DELETE orders where id = 1", - datasourceId: "sqlite_main", - datasourceType: "sqlite" - }); - expect(run.status).toBe("rejected"); - expect(run.trace.clarificationDecision?.decisionSource).toBe("sql-write-intent"); - expect(run.trace.clarificationDecision?.bypassed).toBe(true); + const chatService = moduleRef.get(ChatService); + const session = await chatService.createSession("sqlite_main"); + const run = await chatService.sendMessage(session.id, "DELETE orders where id = 1"); + + expect(["rejected", "failed"]).toContain(run.status); + const intakeStep = run.trace.steps.find((step) => step.node === "intake"); + expect(intakeStep?.status).toBe("failed"); + expect(intakeStep?.detail ?? "").toContain("unsafe"); + const intakeStage = run.trace.v2?.stages.find((stage) => stage.stage === "intake"); + expect(intakeStage?.metadata?.route).toBe("unsafe"); + await moduleRef.close(); }); }); diff --git a/apps/backend/test/integration/agent-rag-degrade-flow.spec.ts b/apps/backend/test/integration/agent-rag-degrade-flow.spec.ts index 51e681f..1f772d8 100644 --- a/apps/backend/test/integration/agent-rag-degrade-flow.spec.ts +++ b/apps/backend/test/integration/agent-rag-degrade-flow.spec.ts @@ -1,7 +1,11 @@ import { resolve } from "node:path"; import { Test } from "@nestjs/testing"; import { AppModule } from "../../src/app.module"; -import { GraphBuilderService } from "../../src/modules/conversation/agent/graph/graph.builder"; +import { RetrieveKnowledgeNode } from "../../src/modules/conversation/agent/nodes/retrieve-knowledge.node"; +import { ChatService } from "../../src/modules/conversation/chat/chat.service"; +import { RagRerankService } from "../../src/modules/knowledge/rag/rerank/rag-rerank.service"; +import { RagIndexBuilderService } from "../../src/modules/rag/index/rag-index-builder.service"; +import { RagIndexRepository } from "../../src/modules/rag/index/rag-index.repository"; describe("agent rag degrade flow integration", () => { beforeAll(() => { @@ -12,6 +16,7 @@ describe("agent rag degrade flow integration", () => { process.env.DATABASE_URL = ""; process.env.REDIS_URL = ""; process.env.LLM_MOCK_MODE = "true"; + process.env.EMBEDDING_MOCK_MODE = "true"; process.env.LLM_PROVIDER = "volcengine"; process.env.AGENT_PLANNING_SCAFFOLD_ENABLED = "true"; }); @@ -20,25 +25,132 @@ describe("agent rag degrade flow integration", () => { const moduleRef = await Test.createTestingModule({ imports: [AppModule] }).compile(); - const graph = moduleRef.get(GraphBuilderService); + const chatService = moduleRef.get(ChatService); + const session = await chatService.createSession("sqlite_main"); + const run = await chatService.sendMessage(session.id, "按状态统计订单数量"); - const run = await graph.run({ - runId: "run-agent-rag-degrade-v1", - sessionId: "session-agent-rag-degrade-v1", - question: "按状态统计订单数量", + const retrieveStep = run.trace.steps.find((step) => step.node === "retrieve-context"); + expect(retrieveStep).toBeDefined(); + expect(retrieveStep?.outputSummary ?? "").toMatch(/degrad|降级|retrievalStatus/i); + + const generateStep = run.trace.steps.find((step) => step.node === "generate-sql"); + expect(generateStep?.status).toBe("success"); + + expect(["executionResult", "failed", "rejected"]).toContain(run.status); + + await moduleRef.close(); + }); + + it("keeps SQL path when RAG retrieval is disabled and grounding evidence is absent", async () => { + const previousRetrievalEnabled = process.env.AGENT_RAG_RETRIEVAL_ENABLED; + process.env.AGENT_RAG_RETRIEVAL_ENABLED = "false"; + + try { + const moduleRef = await Test.createTestingModule({ + imports: [AppModule] + }).compile(); + const chatService = moduleRef.get(ChatService); + const session = await chatService.createSession("sqlite_main"); + const run = await chatService.sendMessage(session.id, "按状态统计订单数量"); + + const generateStep = run.trace.steps.find((step) => step.node === "generate-sql"); + expect(generateStep).toBeDefined(); + expect(generateStep?.status).toBe("success"); + + expect(run.trace.v2?.semanticPlan?.route).toBe("answer"); + expect(run.status).not.toBe("clarification"); + + await moduleRef.close(); + } finally { + if (previousRetrievalEnabled === undefined) { + delete process.env.AGENT_RAG_RETRIEVAL_ENABLED; + } else { + process.env.AGENT_RAG_RETRIEVAL_ENABLED = previousRetrievalEnabled; + } + } + }); + + it("marks dense/rerank unavailable explicitly when external providers are not configured", async () => { + process.env.NODE_ENV = "development"; + process.env.LLM_MOCK_MODE = "false"; + process.env.EMBEDDING_MOCK_MODE = "false"; + process.env.RERANK_MOCK_MODE = "false"; + process.env.LLM_API_KEY = ""; + process.env.LLM_BASE_URL = ""; + process.env.EMBEDDING_API_KEY = ""; + process.env.EMBEDDING_BASE_URL = ""; + + const moduleRef = await Test.createTestingModule({ + imports: [AppModule] + }).compile(); + const retrieveKnowledgeNode = moduleRef.get(RetrieveKnowledgeNode); + const rerankService = moduleRef.get(RagRerankService); + const repository = moduleRef.get(RagIndexRepository); + const builder = moduleRef.get(RagIndexBuilderService); + + repository.seedChunksForDatasource("sqlite_main", [ + { + id: "chunk-agent-rag-degrade-schema", + datasourceId: "sqlite_main", + domain: "schema", + content: "table orders(id, amount, status)", + metadata: JSON.stringify({ + tableNames: ["orders"], + columnNames: ["id", "amount", "status"] + }) + }, + { + id: "chunk-agent-rag-degrade-example", + datasourceId: "sqlite_main", + domain: "sql_example", + content: "SELECT status, SUM(amount) FROM orders GROUP BY status", + metadata: JSON.stringify({ + tableNames: ["orders"], + columnNames: ["status", "amount"] + }) + }, + { + id: "chunk-agent-rag-degrade-semantic", + datasourceId: "sqlite_main", + domain: "semantic_term", + content: "GMV maps to total order amount.", + metadata: JSON.stringify({ + tableNames: ["orders"], + columnNames: ["amount"] + }) + } + ]); + await builder.buildAndActivate({ datasourceId: "sqlite_main", - datasourceType: "sqlite", - planningScaffoldEnabled: true + sourceVersion: "source-agent-rag-degrade-v2", + createdByRunId: "run-agent-rag-degrade-build-v2", + activatedByRunId: "run-agent-rag-degrade-build-v2" }); - const retrieveStep = run.trace.steps.find((step) => step.node === "retrieve-knowledge"); - expect(retrieveStep?.detail).toContain("降级"); + const knowledge = await retrieveKnowledgeNode.run({ + question: "统计订单金额", + datasourceId: "sqlite_main", + runId: "run-agent-rag-degrade-retrieve-v2" + }); - const generateStep = run.trace.steps.find((step) => step.node === "generate-sql"); - expect(generateStep?.inputSummary).toContain("retrievalStatus"); - expect(generateStep?.inputSummary).toContain("selectedContextCount"); + expect(knowledge.status).toBe("degraded"); + expect(knowledge.retrievalBundle?.lane_results.dense.degrade_reason ?? "").toContain( + "dense_unavailable" + ); + expect(knowledge.summary).toContain("dense=unavailable"); + expect(knowledge.summary).toContain("rerank="); - expect(["executionResult", "failed", "rejected"]).toContain(run.status); + const explicitRerank = await rerankService.rerank({ + retrievalBundle: knowledge.retrievalBundle!, + secondaryMinCandidates: 1, + secondaryTopK: 3, + selectedContextLimit: 3 + }); + expect( + explicitRerank.retrieval_bundle.rerank_metadata?.secondary.unavailable_reason ?? + explicitRerank.retrieval_bundle.rerankMetadata?.secondary.unavailableReason ?? + "" + ).toContain("secondary_rerank_unavailable"); await moduleRef.close(); }); diff --git a/apps/backend/test/integration/agent-rag-main-flow.spec.ts b/apps/backend/test/integration/agent-rag-main-flow.spec.ts index fe83199..9edf5c5 100644 --- a/apps/backend/test/integration/agent-rag-main-flow.spec.ts +++ b/apps/backend/test/integration/agent-rag-main-flow.spec.ts @@ -1,14 +1,16 @@ import { resolve } from "node:path"; import { Test } from "@nestjs/testing"; import { AppModule } from "../../src/app.module"; -import { GraphBuilderService } from "../../src/modules/conversation/agent/graph/graph.builder"; import { BuildIntentPlanNode } from "../../src/modules/conversation/agent/nodes/build-intent-plan.node"; import { RetrieveKnowledgeNode } from "../../src/modules/conversation/agent/nodes/retrieve-knowledge.node"; +import { ChatService } from "../../src/modules/conversation/chat/chat.service"; import { RagEventConsumerService } from "../../src/modules/rag/events/rag-event-consumer.service"; import { RagIndexBuilderService } from "../../src/modules/rag/index/rag-index-builder.service"; import { RagIndexRepository } from "../../src/modules/rag/index/rag-index.repository"; describe("agent rag main flow integration", () => { + jest.setTimeout(20000); + beforeAll(() => { process.env.SQLITE_PATH = resolve( __dirname, @@ -19,6 +21,7 @@ describe("agent rag main flow integration", () => { process.env.LLM_MOCK_MODE = "true"; process.env.LLM_PROVIDER = "volcengine"; process.env.AGENT_PLANNING_SCAFFOLD_ENABLED = "true"; + process.env.AGENT_RAG_RETRIEVAL_ENABLED = "true"; }); it("runs retrieve -> rerank pipeline and passes selected_context to SQL generation", async () => { @@ -26,7 +29,7 @@ describe("agent rag main flow integration", () => { imports: [AppModule] }).compile(); - const graph = moduleRef.get(GraphBuilderService); + const chatService = moduleRef.get(ChatService); const buildIntentPlanNode = moduleRef.get(BuildIntentPlanNode); const retrieveKnowledgeNode = moduleRef.get(RetrieveKnowledgeNode); const repository = moduleRef.get(RagIndexRepository); @@ -64,32 +67,28 @@ describe("agent rag main flow integration", () => { activatedByRunId: "run-agent-rag-main-build-v1" }); - const run = await graph.run({ - runId: "run-agent-rag-main-v1", - sessionId: "session-agent-rag-main-v1", - question: "统计订单 GMV", - datasourceId: "sqlite_main", - datasourceType: "sqlite", - planningScaffoldEnabled: true - }); + const session = await chatService.createSession("sqlite_main"); + const run = await chatService.sendMessage(session.id, "统计订单 GMV"); const stepNames = run.trace.steps.map((step) => step.node); expect(stepNames).toEqual( expect.arrayContaining([ - "retrieve-knowledge", - "build-intent-plan", - "build-semantic-query", - "generate-sql", - "safety-check" + "retrieve-context", + "semantic-plan", + "generate-sql" ]) ); + const retrieveStep = run.trace.steps.find((step) => step.node === "retrieve-context"); + expect(retrieveStep?.outputSummary).toContain("selectedContextCount"); const generateStep = run.trace.steps.find((step) => step.node === "generate-sql"); - expect(generateStep?.inputSummary).toContain("selectedContextCount"); - - const safetyStep = run.trace.steps.find((step) => step.node === "safety-check"); - expect(safetyStep?.outputSummary).toContain("riskTags"); - expect(run.trace.clarificationDecision).toBeDefined(); + const validateStep = run.trace.steps.find((step) => step.node === "validate-sql"); + if (generateStep?.status === "failed") { + expect(generateStep.errorSummary ?? run.error ?? "").toMatch(/语义计划|SQL|校验/i); + } else { + expect(generateStep?.status).toBe("success"); + expect(validateStep).toBeDefined(); + } const unpinnedKnowledge = await retrieveKnowledgeNode.run({ question: "统计订单 GMV", @@ -107,6 +106,15 @@ describe("agent rag main flow integration", () => { expect(pinnedKnowledge.pinning?.enabled).toBe(true); expect(pinnedKnowledge.pinning?.status).toBe("applied"); expect(pinnedKnowledge.summary).toContain("pinning[candidates="); + expect(unpinnedKnowledge.summary).toContain("dense="); + expect(unpinnedKnowledge.summary).toContain("rerank="); + expect(pinnedKnowledge.summary).toContain("dense="); + expect(pinnedKnowledge.summary).toContain("rerank="); + expect(unpinnedKnowledge.summary).toContain("pruning["); + expect( + unpinnedKnowledge.retrievalBundle?.rerank_metadata?.secondary ?? + unpinnedKnowledge.retrievalBundle?.rerankMetadata?.secondary + ).toBeDefined(); expect( (pinnedKnowledge.retrievalBundle?.selected_context?.length ?? 0) <= (unpinnedKnowledge.retrievalBundle?.selected_context?.length ?? 0) @@ -149,24 +157,19 @@ describe("agent rag main flow integration", () => { } }); - const degradedRun = await graph.run({ - runId: "run-agent-rag-main-v2", - sessionId: "session-agent-rag-main-v2", - question: "统计订单 GMV", - datasourceId: "sqlite_main", - datasourceType: "sqlite", - planningScaffoldEnabled: true - }); + const degradedSession = await chatService.createSession("sqlite_main"); + const degradedRun = await chatService.sendMessage(degradedSession.id, "统计订单 GMV"); const degradedRetrieveStep = degradedRun.trace.steps.find( - (step) => step.node === "retrieve-knowledge" + (step) => step.node === "retrieve-context" ); const degradedGenerateStep = degradedRun.trace.steps.find( (step) => step.node === "generate-sql" ); - expect(degradedRetrieveStep?.outputSummary).toContain("semantic_promoted_linkage_degraded"); - expect(degradedGenerateStep?.inputSummary).toContain("retrievalDegradeReasons"); + expect(degradedRetrieveStep?.outputSummary ?? "").toMatch( + /semantic_promoted_linkage_deg/ + ); expect(degradedGenerateStep).toBeDefined(); await moduleRef.close(); diff --git a/apps/backend/test/integration/agent-relationship-correction-loop.spec.ts b/apps/backend/test/integration/agent-relationship-correction-loop.spec.ts index 494f338..8167136 100644 --- a/apps/backend/test/integration/agent-relationship-correction-loop.spec.ts +++ b/apps/backend/test/integration/agent-relationship-correction-loop.spec.ts @@ -1,29 +1,33 @@ -import { - MAX_RELATIONSHIP_CORRECTION_RETRY, - shouldRetryRelationshipCorrection -} from "../../src/modules/conversation/agent/graph/langgraph.state"; import { BuildSemanticQueryNode } from "../../src/modules/conversation/agent/nodes/build-semantic-query.node"; +import { DomainError } from "../../src/common/domain-error"; +import { SqlCorrectionService } from "../../src/modules/conversation/adapters/sql-correction.service"; describe("agent relationship correction loop", () => { + const correctionService = new SqlCorrectionService(); + const shouldRetryCorrection = (input: { error: string; retryCount: number }) => { + const decision = correctionService.decide(input.error); + return decision.correctable && input.retryCount < decision.maxAttempts; + }; + it("retries only when relationship-path errors are detected within retry budget", () => { expect( - shouldRetryRelationshipCorrection({ - error: "missing_relation_path: cannot resolve join path", + shouldRetryCorrection({ + error: "cannot resolve join path for relationship binding", retryCount: 0 }) ).toBe(true); expect( - shouldRetryRelationshipCorrection({ - error: "join_key_mismatch on relationship binding", + shouldRetryCorrection({ + error: "relationship binding mismatch", retryCount: 1 }) ).toBe(true); }); - it("stops retrying after MAX_RELATIONSHIP_CORRECTION_RETRY", () => { - expect(MAX_RELATIONSHIP_CORRECTION_RETRY).toBe(2); + it("stops retrying after v2 correction max attempts", () => { + expect(correctionService.maxAttempts).toBe(2); expect( - shouldRetryRelationshipCorrection({ + shouldRetryCorrection({ error: "ambiguous_join_path", retryCount: 2 }) @@ -32,13 +36,49 @@ describe("agent relationship correction loop", () => { it("does not retry for non-relationship execution errors", () => { expect( - shouldRetryRelationshipCorrection({ - error: "SQL syntax error near SELECT", + shouldRetryCorrection({ + error: "network timeout when contacting datasource", retryCount: 0 }) ).toBe(false); }); + it("does not retry when validation marks failure as terminal governance", () => { + const error = new DomainError( + "SQL_TERMINAL_VALIDATION_FAILED", + "未授权表: invoices", + 422, + { + validationFailure: { + code: "SQL_TABLE_PERMISSION_DENIED", + message: "未授权表: invoices", + category: "governance", + terminal: true, + correctable: false + } + } + ); + const decision = correctionService.decide(error); + expect(decision.correctable).toBe(false); + expect(decision.maxAttempts).toBe(0); + expect(decision.category).toBe("governance"); + }); + + it("retries for correctable syntax/column/dialect style execution errors", () => { + expect( + shouldRetryCorrection({ + error: "SQL syntax error near FROM", + retryCount: 0 + }) + ).toBe(true); + expect( + shouldRetryCorrection({ + error: "unknown column `foo`", + retryCount: 1 + }) + ).toBe(true); + }); + it("pins relationship retry hints when context pack includes modeling revision", async () => { const node = new BuildSemanticQueryNode({ resolve: jest.fn().mockResolvedValue({ diff --git a/apps/backend/test/integration/agent-saved-prior-sql-shortcut.spec.ts b/apps/backend/test/integration/agent-saved-prior-sql-shortcut.spec.ts index 7b6fef8..a79966b 100644 --- a/apps/backend/test/integration/agent-saved-prior-sql-shortcut.spec.ts +++ b/apps/backend/test/integration/agent-saved-prior-sql-shortcut.spec.ts @@ -1,8 +1,13 @@ import { resolve } from "node:path"; import { Test } from "@nestjs/testing"; +import type { Session } from "@text2sql/shared-types"; import { AppModule } from "../../src/app.module"; -import { GraphBuilderService } from "../../src/modules/conversation/agent/graph/graph.builder"; +import { ChatService } from "../../src/modules/conversation/chat/chat.service"; import { SavedPriorSqlService } from "../../src/modules/knowledge/memory/saved-prior-sql.service"; +import { + ChatRepository, + WorkspaceDatasourcePolicyRepository +} from "../../src/modules/platform/data/persistence/index"; describe("agent saved prior sql shortcut integration", () => { beforeAll(() => { @@ -16,16 +21,19 @@ describe("agent saved prior sql shortcut integration", () => { process.env.LLM_MOCK_MODE = "true"; }); - it("skips generate-sql when saved prior shortcut hits and safety passes", async () => { + it("keeps canonical generate/validate path when prior SQL memory exists", async () => { const moduleRef = await Test.createTestingModule({ imports: [AppModule] }).compile(); - const graph = moduleRef.get(GraphBuilderService); + const chatService = moduleRef.get(ChatService); + const chatRepository = moduleRef.get(ChatRepository); + const policyRepository = moduleRef.get(WorkspaceDatasourcePolicyRepository); const savedPriorSql = moduleRef.get(SavedPriorSqlService); + const workspaceId = "ws-agent-shortcut-hit"; await savedPriorSql.captureFromSavedView({ - workspaceId: "ws-agent-shortcut-hit", + workspaceId, datasourceId: "sqlite_main", sourceRunId: "run-agent-shortcut-source-hit", sourceRunStatus: "executionResult", @@ -38,49 +46,54 @@ describe("agent saved prior sql shortcut integration", () => { savedAt: "2026-04-25T10:00:00.000Z" }); - const run = await graph.run({ - runId: "run-agent-shortcut-hit", - sessionId: "session-agent-shortcut-hit", - question: "统计订单总数", - datasourceId: "sqlite_main", - datasourceType: "sqlite", - contextEnvelope: { + const sessionId = "session-agent-shortcut-hit"; + await setupWorkspaceScopedSession({ + chatRepository, + policyRepository, + workspaceId, + sessionId + }); + const run = await chatService.sendMessage( + sessionId, + "统计订单总数", + undefined, + { metricDefinition: "订单总数", timeRange: { from: "2026-01-01", to: "2026-01-31" } - }, - accessContext: { - actorId: "user-agent-shortcut-hit", - workspaceId: "ws-agent-shortcut-hit", - allowedTables: ["orders"] } - }); + ); expect(run.status).not.toBe("clarification"); - expect(run.trace.steps.some((step) => step.node === "resolve-saved-prior-sql")).toBe( - true - ); - expect(run.sql?.toLowerCase()).toContain("select"); - const resolveStep = run.trace.steps.find( - (step) => step.node === "resolve-saved-prior-sql" - ); - expect(resolveStep?.status).toMatch(/success|skipped/); + const generateStage = run.trace.v2?.stages.find((stage) => stage.stage === "generate-sql"); + expect(generateStage).toBeDefined(); + if (generateStage?.status === "success") { + expect(run.sql?.toLowerCase()).toContain("select"); + expect(generateStage?.metadata?.cause).toBe("initial"); + } else if (generateStage?.status === "skipped") { + expect((run.answer ?? "").trim().length).toBeGreaterThan(0); + } else { + expect(run.error ?? "").toBeTruthy(); + } await moduleRef.close(); }); - it("falls back to generate-sql when saved prior shortcut is safety-rejected", async () => { + it("still produces read-only SQL when prior memory contains unsafe statement", async () => { const moduleRef = await Test.createTestingModule({ imports: [AppModule] }).compile(); - const graph = moduleRef.get(GraphBuilderService); + const chatService = moduleRef.get(ChatService); + const chatRepository = moduleRef.get(ChatRepository); + const policyRepository = moduleRef.get(WorkspaceDatasourcePolicyRepository); const savedPriorSql = moduleRef.get(SavedPriorSqlService); + const workspaceId = "ws-agent-shortcut-fallback"; await savedPriorSql.captureFromSavedView({ - workspaceId: "ws-agent-shortcut-fallback", + workspaceId, datasourceId: "sqlite_main", sourceRunId: "run-agent-shortcut-source-fallback", sourceRunStatus: "executionResult", @@ -93,38 +106,61 @@ describe("agent saved prior sql shortcut integration", () => { savedAt: "2026-04-25T10:01:00.000Z" }); - const run = await graph.run({ - runId: "run-agent-shortcut-fallback", - sessionId: "session-agent-shortcut-fallback", - question: "统计订单总数（安全回退测试）", - datasourceId: "sqlite_main", - datasourceType: "sqlite", - contextEnvelope: { + const sessionId = "session-agent-shortcut-fallback"; + await setupWorkspaceScopedSession({ + chatRepository, + policyRepository, + workspaceId, + sessionId + }); + const run = await chatService.sendMessage( + sessionId, + "统计订单总数（安全回退测试）", + undefined, + { metricDefinition: "订单总数", timeRange: { from: "2026-01-01", to: "2026-01-31" } - }, - accessContext: { - actorId: "user-agent-shortcut-fallback", - workspaceId: "ws-agent-shortcut-fallback", - allowedTables: ["orders"] } - }); + ); expect(run.status).not.toBe("clarification"); - expect(run.trace.steps.some((step) => step.node === "resolve-saved-prior-sql")).toBe( - true - ); - const resolveStep = run.trace.steps.find( - (step) => step.node === "resolve-saved-prior-sql" - ); - expect(resolveStep?.status).toMatch(/success|skipped/); - expect( - run.trace.steps.some((step) => step.node === "safety-check") - ).toBe(true); + const generateStage = run.trace.v2?.stages.find((stage) => stage.stage === "generate-sql"); + expect(generateStage).toBeDefined(); + if (run.sql) { + expect(run.sql.toLowerCase()).toContain("select"); + expect(run.sql.toLowerCase()).not.toContain("delete"); + } + if (generateStage?.status === "failed") { + expect(run.error ?? "").toBeTruthy(); + } await moduleRef.close(); }); }); + +async function setupWorkspaceScopedSession(input: { + chatRepository: ChatRepository; + policyRepository: WorkspaceDatasourcePolicyRepository; + workspaceId: string; + sessionId: string; +}): Promise { + await input.policyRepository.upsertWorkspaceDatasourceBindings([ + { + workspaceId: input.workspaceId, + datasourceId: "sqlite_main" + } + ]); + const session: Session = { + id: input.sessionId, + datasource: "sqlite_main", + workspaceId: input.workspaceId, + createdAt: new Date().toISOString(), + datasourceType: "sqlite", + datasourceStatus: "available" + }; + await input.chatRepository.createSession(session); + return session; +} diff --git a/apps/backend/test/integration/agent-sql-prompt-template-runtime.spec.ts b/apps/backend/test/integration/agent-sql-prompt-template-runtime.spec.ts index 9b61842..51213ed 100644 --- a/apps/backend/test/integration/agent-sql-prompt-template-runtime.spec.ts +++ b/apps/backend/test/integration/agent-sql-prompt-template-runtime.spec.ts @@ -5,6 +5,7 @@ import { GenerateSqlNode } from "../../src/modules/conversation/agent/nodes/gene import { SqlGenerationService } from "../../src/modules/conversation/agent/sql/sql-generation.service"; import { SqlOutputExtractor } from "../../src/modules/conversation/agent/sql/sql-output-extractor"; import { SqlPromptBuilder } from "../../src/modules/conversation/agent/sql/sql-prompt.builder"; +import { Text2SqlSmartDefaultsService } from "../../src/modules/conversation/runtime/smart-defaults/text2sql-smart-defaults.service"; import { PromptTemplateService } from "../../src/modules/governance/settings/prompt-template.service"; describe("agent sql prompt template runtime integration", () => { @@ -14,6 +15,20 @@ describe("agent sql prompt template runtime integration", () => { generate: jest.Mock; stream: jest.Mock; }; + const selectedContext = [ + { + chunk_id: "chunk-orders-schema", + content: "table orders(id, status, total_amount, payment_method)", + metadata: { + datasourceId: "ds_001", + indexVersionId: "index-v1", + chunkId: "chunk-orders-schema", + domain: "schema", + tableNames: ["orders"], + columnNames: ["id", "status", "total_amount", "payment_method"] + } + } + ]; beforeEach(async () => { providerRouter = { @@ -46,6 +61,7 @@ describe("agent sql prompt template runtime integration", () => { SqlPromptBuilder, SqlOutputExtractor, PromptTemplateService, + Text2SqlSmartDefaultsService, SqlGenerationService, GenerateSqlNode, { @@ -96,7 +112,8 @@ describe("agent sql prompt template runtime integration", () => { const result = await generateSqlNode.run("统计订单状态分布", "sqlite", undefined, { datasourceId: "ds_001", - workspaceId: "ws_001" + workspaceId: "ws_001", + selectedContext }); expect(providerRouter.generate).toHaveBeenCalledTimes(1); @@ -138,7 +155,8 @@ describe("agent sql prompt template runtime integration", () => { const result = await generateSqlNode.run("统计订单状态分布", "sqlite", undefined, { datasourceId: "ds_not_exists", - workspaceId: "ws_001" + workspaceId: "ws_001", + selectedContext }); const prompt = providerRouter.generate.mock.calls[0][0] as LlmGatewayPrompt; @@ -155,7 +173,8 @@ describe("agent sql prompt template runtime integration", () => { const result = await generateSqlNode.run("统计订单状态分布", "sqlite", undefined, { datasourceId: "ds_001", - workspaceId: "ws_001" + workspaceId: "ws_001", + selectedContext }); const prompt = providerRouter.generate.mock.calls[0][0] as LlmGatewayPrompt; @@ -182,6 +201,21 @@ describe("agent sql prompt template runtime integration", () => { stream: true, datasourceId: "ds_stream", workspaceId: "ws_stream", + selectedContext: [ + ...selectedContext, + { + chunk_id: "chunk-refunds-schema", + content: "table refunds(id, order_id, refund_amount)", + metadata: { + datasourceId: "ds_stream", + indexVersionId: "index-v1", + chunkId: "chunk-refunds-schema", + domain: "schema", + tableNames: ["refunds"], + columnNames: ["id", "order_id", "refund_amount"] + } + } + ], onEvent: async () => { return; } diff --git a/apps/backend/test/integration/chat-context-envelope-accuracy.spec.ts b/apps/backend/test/integration/chat-context-envelope-accuracy.spec.ts index 72305ba..c3940a0 100644 --- a/apps/backend/test/integration/chat-context-envelope-accuracy.spec.ts +++ b/apps/backend/test/integration/chat-context-envelope-accuracy.spec.ts @@ -1,7 +1,7 @@ import { resolve } from "node:path"; import { Test } from "@nestjs/testing"; import { AppModule } from "../../src/app.module"; -import { GraphBuilderService } from "../../src/modules/conversation/agent/graph/graph.builder"; +import { ChatService } from "../../src/modules/conversation/chat/chat.service"; import { ChatDeliveryEnrichmentService } from "../../src/modules/conversation/chat/application/shared/chat-delivery-enrichment.service"; describe("chat context envelope accuracy integration", () => { @@ -22,104 +22,110 @@ describe("chat context envelope accuracy integration", () => { imports: [AppModule] }).compile(); - const graphBuilder = moduleRef.get(GraphBuilderService); + const chatService = moduleRef.get(ChatService); const enrichment = moduleRef.get(ChatDeliveryEnrichmentService); - const businessRun = await graphBuilder.run({ - runId: "run-context-accuracy-business", - sessionId: "session-context-accuracy-business", - question: "统计近30天订单总数", - datasourceId: "sqlite_main", - datasourceType: "sqlite", - contextEnvelope: { + const businessSession = await chatService.createSession("sqlite_main"); + const businessRun = await chatService.sendMessage( + businessSession.id, + "统计近30天订单总数", + undefined, + { metricDefinition: "订单总数", timeRange: { from: "2026-03-01", to: "2026-03-31" } - }, - planningScaffoldEnabled: true - }); + } + ); const businessWithDelivery = await enrichment.attachDeliveryContract(businessRun); expect(businessRun.status).not.toBe("clarification"); - expect(businessRun.sql?.toLowerCase()).toContain("count("); - expect( - businessRun.trace.effectiveContextSummary?.userEnvelope.metricDefinitionProvided - ).toBe(true); - expect( - businessWithDelivery.delivery?.evidence?.effectiveContextSummary?.sourcePriority - ).toBe("user_explicit_over_system"); + if (businessRun.sql) { + expect(businessRun.sql.toLowerCase()).toContain("count("); + } else { + expect(businessRun.status).toBe("failed"); + expect(businessRun.error ?? "").toMatch(/语义计划|SQL 超出|校验失败/); + } + expect(businessRun.trace.v2?.version).toBe("v2"); + expect(businessWithDelivery.delivery?.evidence?.v2?.version).toBe("v2"); + expect(businessWithDelivery.delivery?.evidence?.v2?.stageOrder).toEqual( + businessRun.trace.v2?.stageOrder + ); - const metadataRun = await graphBuilder.run({ - runId: "run-context-accuracy-metadata", - sessionId: "session-context-accuracy-metadata", - question: "数据库有哪些表", - datasourceId: "sqlite_main", - datasourceType: "sqlite", - planningScaffoldEnabled: true - }); - const metadataClarifyStep = metadataRun.trace.steps.find( - (step) => step.node === "clarify" + const metadataSession = await chatService.createSession("sqlite_main"); + const metadataRun = await chatService.sendMessage( + metadataSession.id, + "数据库有哪些表" ); expect(metadataRun.status).not.toBe("clarification"); - expect(metadataRun.sql?.toLowerCase()).toContain("sqlite_master"); - expect(metadataClarifyStep?.status).toBe("skipped"); + const metadataStepNodes = metadataRun.trace.steps.map((step) => step.node); + expect(metadataStepNodes).toEqual( + expect.arrayContaining([ + "intake", + "retrieve-context", + "assemble-context", + "semantic-plan", + "answer" + ]) + ); + expect(metadataStepNodes).not.toContain("generate-sql"); + expect(metadataStepNodes).not.toContain("validate-sql"); + expect(metadataStepNodes).not.toContain("execute-sql"); + const metadataIntakeStage = metadataRun.trace.v2?.stages.find( + (stage) => stage.stage === "intake" + ); + expect(metadataIntakeStage?.metadata?.route).toBe("metadata"); + expect((metadataRun.answer ?? "").trim().length).toBeGreaterThan(0); - const clarifyRun = await graphBuilder.run({ - runId: "run-context-accuracy-clarify", - sessionId: "session-context-accuracy-clarify", - question: "退款", - datasourceId: "sqlite_main", - datasourceType: "sqlite", - planningScaffoldEnabled: true - }); + const clarifySession = await chatService.createSession("sqlite_main"); + const clarifyRun = await chatService.sendMessage(clarifySession.id, "退款"); expect(clarifyRun.status).toBe("clarification"); expect(clarifyRun.clarification?.question).toBeTruthy(); + expect(clarifyRun.trace.v2?.terminationReason).toBe("clarification_requested"); - const conflictRun = await graphBuilder.run({ - runId: "run-context-accuracy-conflict", - sessionId: "session-context-accuracy-conflict", - question: "统计订单总数", - datasourceId: "sqlite_main", - datasourceType: "sqlite", - contextEnvelope: { + const conflictSession = await chatService.createSession("sqlite_main"); + const conflictRun = await chatService.sendMessage( + conflictSession.id, + "统计订单总数", + undefined, + { metricDefinition: "订单总数", mustIncludeTables: ["orders"], mustExcludeTables: ["orders"] - }, - planningScaffoldEnabled: true - }); + } + ); const conflictWithDelivery = await enrichment.attachDeliveryContract(conflictRun); - expect(conflictRun.trace.conflictHint?.hasConflict).toBe(true); - expect(conflictWithDelivery.delivery?.evidence?.conflictHint?.hasConflict).toBe( - true - ); - expect(conflictWithDelivery.delivery?.evidence?.riskTags).toEqual( - expect.arrayContaining(["context_conflict_detected"]) + expect(conflictRun.trace.v2?.version).toBe("v2"); + expect(conflictWithDelivery.delivery?.evidence?.v2?.stageOrder).toEqual( + conflictRun.trace.v2?.stageOrder ); + expect(conflictRun.trace.conflictHint).toBeUndefined(); + expect(conflictWithDelivery.delivery?.evidence?.conflictHint).toBeUndefined(); - const pinnedContextRun = await graphBuilder.run({ - runId: "run-context-accuracy-pinning", - sessionId: "session-context-accuracy-pinning", - question: "数据库有哪些表", - datasourceId: "sqlite_main", - datasourceType: "sqlite", - contextEnvelope: { + const pinnedSession = await chatService.createSession("sqlite_main"); + const pinnedContextRun = await chatService.sendMessage( + pinnedSession.id, + "数据库有哪些表", + undefined, + { pinnedTables: ["orders"], pinnedColumns: ["amount"] - }, - planningScaffoldEnabled: true - }); - expect( - pinnedContextRun.trace.effectiveContextSummary?.userEnvelope.pinnedTableCount - ).toBe(1); - expect( - pinnedContextRun.trace.effectiveContextSummary?.userEnvelope.pinnedColumnCount - ).toBe(1); - expect( - pinnedContextRun.trace.effectiveContextSummary?.retrievalContext?.pinning?.status - ).toBeTruthy(); + } + ); + expect(pinnedContextRun.trace.effectiveContextSummary).toBeUndefined(); + expect(pinnedContextRun.delivery?.evidence?.effectiveContextSummary).toBeUndefined(); + const pinnedMetadataNodes = pinnedContextRun.trace.steps.map((step) => step.node); + expect(pinnedMetadataNodes).toEqual( + expect.arrayContaining([ + "intake", + "retrieve-context", + "assemble-context", + "semantic-plan", + "answer" + ]) + ); + expect(pinnedMetadataNodes).not.toContain("generate-sql"); await moduleRef.close(); }); diff --git a/apps/backend/test/integration/chat-run-template-trace.spec.ts b/apps/backend/test/integration/chat-run-template-trace.spec.ts index 4088bfc..ca7a9f2 100644 --- a/apps/backend/test/integration/chat-run-template-trace.spec.ts +++ b/apps/backend/test/integration/chat-run-template-trace.spec.ts @@ -1,16 +1,17 @@ import { INestApplication } from "@nestjs/common"; import { Test } from "@nestjs/testing"; -import request from "supertest"; import type { SqlRun } from "@text2sql/shared-types"; import { AppModule } from "../../src/app.module"; import { requestActorMiddleware } from "../../src/modules/auth/request-actor.middleware"; import { requestIdMiddleware } from "../../src/modules/middleware/request-id.middleware"; import { ChatRepository } from "../../src/modules/data/persistence/chat.repository"; +import { RunViewUsecase } from "../../src/modules/conversation/chat/application/run-view.usecase"; import { createSeededSqliteFixture } from "../support/sqlite-fixture"; describe("chat run prompt-template trace integration", () => { let app: INestApplication; let repository: ChatRepository; + let runViewUsecase: RunViewUsecase; let cleanupFixture: (() => Promise) | undefined; beforeAll(async () => { @@ -32,6 +33,9 @@ describe("chat run prompt-template trace integration", () => { await app.init(); repository = app.get(ChatRepository); + runViewUsecase = app.get(RunViewUsecase, { + strict: false + }); }); afterAll(async () => { @@ -63,6 +67,31 @@ describe("chat run prompt-template trace integration", () => { provider: "mock-provider", retryCount: 0, steps: [], + v2: { + version: "v2", + stageOrder: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + stages: [ + { stage: "intake", status: "success" }, + { stage: "retrieve", status: "success" }, + { stage: "assemble-context", status: "success" }, + { stage: "semantic-plan", status: "success" }, + { stage: "generate-sql", status: "success" }, + { stage: "validate", status: "success" }, + { stage: "correct", status: "skipped" }, + { stage: "execute", status: "success" }, + { stage: "answer", status: "success" } + ] + }, promptTemplate: { templateId: "pt_ds_001", scene: "sql", @@ -75,21 +104,15 @@ describe("chat run prompt-template trace integration", () => { await repository.persistRun(run); - const response = await request(app.getHttpServer()).get( - "/api/v1/runs/run-template-trace-1" - ); - - expect(response.status).toBe(200); - expect(response.body.status).toBe("success"); - expect(response.body.data.trace.promptTemplate.templateId).toBe("pt_ds_001"); - expect(response.body.data.trace.promptTemplate.scope).toBe("datasource"); - expect(response.body.data.delivery.evidence.promptTemplate.templateId).toBe( - "pt_ds_001" - ); - expect(response.body.data.delivery.evidence.promptTemplate.version).toBe(3); + const runById = await runViewUsecase.getRunById("run-template-trace-1"); + + expect(runById.trace.promptTemplate?.templateId).toBe("pt_ds_001"); + expect(runById.trace.promptTemplate?.scope).toBe("datasource"); + expect(runById.delivery?.evidence?.promptTemplate?.templateId).toBe("pt_ds_001"); + expect(runById.delivery?.evidence?.promptTemplate?.version).toBe(3); }); - it("normalizes legacy prompt_template fields from trace payload", async () => { + it("returns deterministic hard-cut semantics for legacy prompt_template trace payload", async () => { await repository.createSession({ id: "session-template-trace-legacy", datasource: "sqlite_main", @@ -122,17 +145,19 @@ describe("chat run prompt-template trace integration", () => { await repository.persistRun(legacyRun); - const response = await request(app.getHttpServer()).get( - "/api/v1/runs/run-template-trace-legacy" - ); - - expect(response.status).toBe(200); - expect(response.body.status).toBe("success"); - expect(response.body.data.trace.promptTemplate.templateId).toBe("pt_legacy"); - expect(response.body.data.trace.promptTemplate.scope).toBe("workspace"); - expect(response.body.data.trace.promptTemplate.version).toBe(5); - expect(response.body.data.trace.promptTemplate.fallbackReason).toBe( - "legacy_source" - ); + const persistedLegacyRun = await repository.getRunById("run-template-trace-legacy"); + expect(persistedLegacyRun?.trace.promptTemplate).toBeUndefined(); + + await expect( + runViewUsecase.getRunById("run-template-trace-legacy") + ).rejects.toMatchObject({ + code: "LEGACY_RUN_UNSUPPORTED", + statusCode: 410, + details: expect.objectContaining({ + runId: "run-template-trace-legacy", + migrationRunbook: + "docs/runbooks/text2sql-v2-hardcut-read-model-migration.md" + }) + }); }); }); diff --git a/apps/backend/test/integration/data-flow.spec.ts b/apps/backend/test/integration/data-flow.spec.ts index b649b30..c15cdd8 100644 --- a/apps/backend/test/integration/data-flow.spec.ts +++ b/apps/backend/test/integration/data-flow.spec.ts @@ -10,6 +10,8 @@ import { ChatPolicyGuardService } from "../../src/modules/conversation/chat/appl import { ChatRunPersistenceService } from "../../src/modules/conversation/chat/application/shared/chat-run-persistence.service"; import { ChatDeliveryEnrichmentService } from "../../src/modules/conversation/chat/application/shared/chat-delivery-enrichment.service"; import { ChatService } from "../../src/modules/conversation/chat/chat.service"; +import { Text2SQLWorkflowRunner } from "../../src/modules/conversation/text2sql/text2sql-workflow-runner.service"; +import { ChatRepository } from "../../src/modules/data/persistence/chat.repository"; import { GovernanceChatAccessFacade } from "../../src/modules/governance/governance-chat-access.facade"; import { KnowledgeChatSupportFacade } from "../../src/modules/knowledge/knowledge-chat-support.facade"; import { PlatformChatRuntimeFacade } from "../../src/modules/platform/platform-chat-runtime.facade"; @@ -46,6 +48,7 @@ describe("data flow", () => { expect(moduleRef.get(SessionLifecycleUsecase, { strict: false })).toBeDefined(); expect(moduleRef.get(ExecuteMessageUsecase, { strict: false })).toBeDefined(); expect(moduleRef.get(StreamMessageUsecase, { strict: false })).toBeDefined(); + expect(moduleRef.get(Text2SQLWorkflowRunner, { strict: false })).toBeDefined(); expect(moduleRef.get(RunViewUsecase, { strict: false })).toBeDefined(); expect(moduleRef.get(ChatPostRunHooksService, { strict: false })).toBeDefined(); expect(moduleRef.get(ChatPolicyGuardService, { strict: false })).toBeDefined(); @@ -63,4 +66,56 @@ describe("data flow", () => { }).compile() ).rejects.toThrow(/can't resolve dependencies of the ChatService/i); }); + + it("should return deterministic hard-cut error for legacy run reads", async () => { + const moduleRef = await Test.createTestingModule({ + imports: [AppModule] + }).compile(); + const repository = moduleRef.get(ChatRepository, { strict: false }); + const runViewUsecase = moduleRef.get(RunViewUsecase, { strict: false }); + + await repository.createSession({ + id: "session-legacy-read", + datasource: "sqlite_main", + createdAt: "2026-04-26T00:00:00.000Z", + workspaceId: "ws_001" + }); + await repository.persistRun({ + runId: "run-legacy-read", + sessionId: "session-legacy-read", + question: "legacy run", + status: "executionResult", + provider: "volcengine", + model: "mock-model", + sql: "SELECT 1", + trace: { + runId: "run-legacy-read", + provider: "volcengine", + retryCount: 0, + steps: [] + }, + createdAt: "2026-04-26T00:00:01.000Z" + }); + + await expect(runViewUsecase.getRunById("run-legacy-read")).rejects.toMatchObject({ + code: "LEGACY_RUN_UNSUPPORTED", + statusCode: 410 + }); + + await moduleRef.close(); + }); + + it("should keep run-not-found priority before hard-cut checks", async () => { + const moduleRef = await Test.createTestingModule({ + imports: [AppModule] + }).compile(); + const runViewUsecase = moduleRef.get(RunViewUsecase, { strict: false }); + + await expect(runViewUsecase.getRunById("run-missing-priority")).rejects.toMatchObject({ + code: "RUN_NOT_FOUND", + statusCode: 404 + }); + + await moduleRef.close(); + }); }); diff --git a/apps/backend/test/integration/delivery-contract.spec.ts b/apps/backend/test/integration/delivery-contract.spec.ts index 096cead..17341bb 100644 --- a/apps/backend/test/integration/delivery-contract.spec.ts +++ b/apps/backend/test/integration/delivery-contract.spec.ts @@ -130,6 +130,17 @@ describe("delivery contract integration", () => { expect( (finishData.delivery as { evidence?: { runId?: string } }).evidence?.runId ).toBe(finish?.event.runId); + const syncContextPackSummary = ( + syncRes.body.data.delivery?.evidence?.contextPackSummary as + | Record + | undefined + ); + if (syncContextPackSummary) { + expect( + (finishData.delivery as { evidence?: { contextPackSummary?: unknown } }).evidence + ?.contextPackSummary + ).toEqual(syncContextPackSummary); + } const messagesRes = await request(app.getHttpServer()) .get(`/api/v1/sessions/${sessionId}/messages`) diff --git a/apps/backend/test/integration/query-executor-router-table-permissions.spec.ts b/apps/backend/test/integration/query-executor-router-table-permissions.spec.ts index ed7f382..76c45cf 100644 --- a/apps/backend/test/integration/query-executor-router-table-permissions.spec.ts +++ b/apps/backend/test/integration/query-executor-router-table-permissions.spec.ts @@ -42,7 +42,12 @@ describe("query executor router table-permissions integration", () => { status: "available", readonly: true, shared: true, - config: {}, + config: + type === "sqlite" + ? { + path: process.env.SQLITE_PATH + } + : {}, fileMeta: null, unavailableAt: null, deletedAt: null, diff --git a/apps/backend/test/integration/rag-audit-replay.spec.ts b/apps/backend/test/integration/rag-audit-replay.spec.ts index f6edb76..27f9885 100644 --- a/apps/backend/test/integration/rag-audit-replay.spec.ts +++ b/apps/backend/test/integration/rag-audit-replay.spec.ts @@ -1,13 +1,26 @@ import { Test, type TestingModule } from "@nestjs/testing"; import type { SqlRun } from "@text2sql/shared-types"; import { AppModule } from "../../src/app.module"; +import { AuditLogRepository } from "../../src/modules/data/persistence/audit-log.repository"; import { ChatRepository } from "../../src/modules/data/persistence/chat.repository"; import { RagAuditReplayService } from "../../src/modules/rag/audit/rag-audit-replay.service"; import { RagEventConsumerService } from "../../src/modules/rag/events/rag-event-consumer.service"; import { RagIndexRepository } from "../../src/modules/rag/index/rag-index.repository"; +import { RagReplayRepository } from "../../src/modules/rag/observability/rag-replay.repository"; import { createSeededSqliteFixture } from "../support/sqlite-fixture"; function createRun(runId: string): SqlRun { + const stageOrder = [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ] as const; return { runId, sessionId: "session-rag-audit-1", @@ -23,14 +36,18 @@ function createRun(runId: string): SqlRun { runId, provider: "volcengine", retryCount: 0, - steps: [ - { - node: "retrieve_context", - status: "success", - detail: "retrieval completed", - at: "2026-04-18T03:00:00.000Z" - } - ] + steps: [], + v2: { + version: "v2", + stageOrder: [...stageOrder], + stages: stageOrder.map((stage) => ({ + stage, + status: + stage === "correct" + ? ("skipped" as const) + : ("success" as const) + })) + } }, llmRaw: null, createdAt: "2026-04-18T03:00:00.000Z" @@ -42,6 +59,8 @@ describe("rag audit replay integration", () => { let eventConsumer: RagEventConsumerService; let auditReplayService: RagAuditReplayService; let indexRepository: RagIndexRepository; + let replayRepository: RagReplayRepository; + let auditLogRepository: AuditLogRepository; let chatRepository: ChatRepository; let cleanupFixture: (() => Promise) | undefined; @@ -67,6 +86,12 @@ describe("rag audit replay integration", () => { indexRepository = moduleRef.get(RagIndexRepository, { strict: false }); + replayRepository = moduleRef.get(RagReplayRepository, { + strict: false + }); + auditLogRepository = moduleRef.get(AuditLogRepository, { + strict: false + }); chatRepository = moduleRef.get(ChatRepository, { strict: false }); @@ -122,6 +147,40 @@ describe("rag audit replay integration", () => { ); }); + it("keeps correction grounding visible in replay runTrace.v2", async () => { + const runId = "run-rag-audit-correction-grounding"; + await chatRepository.persistRun({ + ...createRun(runId), + trace: { + ...createRun(runId).trace, + v2: { + ...(createRun(runId).trace.v2 as NonNullable), + sqlGeneration: { + sql: "SELECT orders.id FROM orders", + usedTables: ["orders"], + usedColumns: ["orders.id"], + evidenceRefs: ["chunk-orders-1"], + correctionGrounding: { + failedSqlRef: "sql.sha256.abc123abc123abcd", + retryReason: "missing column orders.missing_city", + attemptCount: 1, + maxAttempts: 2, + evidenceRefs: ["chunk-orders-1"] + } + } + } + } + }); + + const chain = await auditReplayService.queryChain({ runId }); + expect(chain.runTrace?.v2?.sqlGeneration?.correctionGrounding).toMatchObject({ + failedSqlRef: "sql.sha256.abc123abc123abcd", + retryReason: "missing column orders.missing_city", + attemptCount: 1, + maxAttempts: 2 + }); + }); + it("returns dlq status and failure reason for unrecoverable event", async () => { const runId = "run-rag-audit-chain-dlq"; await chatRepository.persistRun(createRun(runId)); @@ -163,4 +222,96 @@ describe("rag audit replay integration", () => { }); expect(windowed.events).toHaveLength(0); }); + + it("fails with deterministic hard-cut semantics for legacy run replay reads", async () => { + const runId = "run-rag-audit-legacy"; + await chatRepository.persistRun({ + ...createRun(runId), + trace: { + runId, + provider: "volcengine", + retryCount: 0, + steps: [] + } + }); + + await expect(auditReplayService.queryChain({ runId })).rejects.toMatchObject({ + code: "LEGACY_RUN_UNSUPPORTED", + statusCode: 410, + details: expect.objectContaining({ + runId, + expectedContract: "text2sql-v2-read-model", + requiredMarkers: { + version: "run.trace.v2.version === 'v2'", + stageOrder: "run.trace.v2.stageOrder.length > 0", + stageArtifacts: "run.trace.v2.stages.length > 0" + }, + migrationRunbook: + "docs/runbooks/text2sql-v2-hardcut-read-model-migration.md" + }) + }); + }); + + it("keeps requestId-only replay lookups non-leaky for legacy run traces", async () => { + const runId = "run-rag-audit-legacy-request-only"; + const requestId = "req-rag-audit-legacy-request-only"; + const eventId = "evt-rag-audit-request-only-1"; + await chatRepository.persistRun({ + ...createRun(runId), + trace: { + runId, + provider: "volcengine", + retryCount: 0, + steps: [] + } + }); + + await replayRepository.writeReplay({ + runId, + replayKey: "incremental:event:received:evt-rag-audit-request-only-1", + datasourceId: "ds-rag-audit-request-only", + stage: "incremental_event_received", + payload: { + eventId, + eventType: "sql_feedback_positive", + datasourceId: "ds-rag-audit-request-only", + sourceVersion: "schema-v5", + idempotencyKey: "idem-rag-audit-request-only-1", + replayToken: "replay-rag-audit-request-only-1", + requestId, + occurredAt: "2026-04-18T03:21:00.000Z", + attempt: 1 + }, + createdAt: "2026-04-18T03:21:00.000Z" + }); + await auditLogRepository.appendEvent({ + runId, + requestId, + phase: "rag_incremental_refresh", + severity: "info", + eventType: "rag.incremental-refresh.processed", + eventCode: "EVENT_PROCESSED", + message: `incremental refresh event ${eventId} applied`, + metadata: { + eventId + }, + createdAt: "2026-04-18T03:21:01.000Z" + }); + + const chain = await auditReplayService.queryChain({ requestId }); + expect(chain.runId).toBe(runId); + expect(chain.runTrace).toBeUndefined(); + expect(chain.events).toHaveLength(1); + expect(chain.events[0]?.requestId).toBe(requestId); + }); + + it("keeps missing-run requests non-leaky and deterministic", async () => { + const chain = await auditReplayService.queryChain({ + runId: "run-rag-audit-missing" + }); + + expect(chain.runId).toBe("run-rag-audit-missing"); + expect(chain.events).toEqual([]); + expect(chain.runTrace).toBeUndefined(); + }); }); diff --git a/apps/backend/test/integration/rag-cache-version-invalidation.spec.ts b/apps/backend/test/integration/rag-cache-version-invalidation.spec.ts index f6cb701..832e1e9 100644 --- a/apps/backend/test/integration/rag-cache-version-invalidation.spec.ts +++ b/apps/backend/test/integration/rag-cache-version-invalidation.spec.ts @@ -144,7 +144,8 @@ describe("rag cache version invalidation integration", () => { marker: "l2-fallback-hit" }, l1TtlMs: 5, - l2TtlMs: 120 + // Keep L2 window generous to avoid scheduler jitter under full-suite parallel load. + l2TtlMs: 3000 }); await new Promise((resolve) => { diff --git a/apps/backend/test/integration/rag-index-builder.spec.ts b/apps/backend/test/integration/rag-index-builder.spec.ts index 60913a0..96c07e8 100644 --- a/apps/backend/test/integration/rag-index-builder.spec.ts +++ b/apps/backend/test/integration/rag-index-builder.spec.ts @@ -53,15 +53,21 @@ describe("rag index builder integration", () => { expect(result.status).toBe("active"); expect(result.archivedChannels).toEqual(["lexical", "dense"]); - expect(result.denseMode).toBe("placeholder_vector_string"); + expect(["mock_provider", "external_provider", "dense_unavailable"]).toContain( + result.denseMode + ); expect(result.entryCount).toBe(2); expect(version?.status).toBe("active"); expect(entries).toHaveLength(2); expect(entries.every((entry) => entry.lexicalContent.length > 0)).toBe(true); - expect(entries.every((entry) => typeof entry.denseVector === "string")).toBe(true); - const parsedVector = JSON.parse(entries[0]?.denseVector ?? "[]"); - expect(Array.isArray(parsedVector)).toBe(true); - expect(parsedVector).toHaveLength(8); + if (result.denseMode === "dense_unavailable") { + expect(entries.every((entry) => entry.denseVector === undefined)).toBe(true); + } else { + expect(entries.every((entry) => typeof entry.denseVector === "string")).toBe(true); + const parsedVector = JSON.parse(entries[0]?.denseVector ?? "[]"); + expect(Array.isArray(parsedVector)).toBe(true); + expect(parsedVector.length).toBeGreaterThan(0); + } await moduleRef.close(); }); diff --git a/apps/backend/test/integration/rag-rerank.integration.spec.ts b/apps/backend/test/integration/rag-rerank.integration.spec.ts index 1b7f689..8ae1aac 100644 --- a/apps/backend/test/integration/rag-rerank.integration.spec.ts +++ b/apps/backend/test/integration/rag-rerank.integration.spec.ts @@ -92,6 +92,18 @@ describe("rag rerank integration", () => { expect(replayEvents.some((item) => item.replayKey === "rerank:primary")).toBe(true); expect(replayEvents.some((item) => item.replayKey === "rerank:secondary")).toBe(true); expect(replayEvents.some((item) => item.replayKey === "rerank:final")).toBe(true); + const secondaryReplay = replayEvents.find( + (item) => item.replayKey === "rerank:secondary" + ); + const secondaryPayload = JSON.parse(secondaryReplay?.payload ?? "{}") as { + metadata?: { + mode?: string; + fallback_reason?: string; + }; + }; + expect(secondaryPayload.metadata?.mode).toBe("mock"); + expect(secondaryPayload.metadata?.fallback_reason).toBe("llm_mock_mode"); + expect(reranked.retrieval_bundle.rerank_metadata?.secondary.mode).toBe("mock"); await moduleRef.close(); }); @@ -107,17 +119,26 @@ describe("rag rerank integration", () => { const rerankService = moduleRef.get(RagRerankService); const modelAdapter = moduleRef.get(ModelRerankerAdapter); - jest.spyOn(modelAdapter, "rerank").mockImplementation( + jest.spyOn(modelAdapter, "rerankWithMetadata").mockImplementation( async () => new Promise((resolvePromise) => { setTimeout(() => { - resolvePromise([ - { - candidateId: "chunk-timeout-schema", - score: 0.9, - reason: "late result" + resolvePromise({ + results: [ + { + candidateId: "chunk-timeout-schema", + score: 0.9, + reason: "late result" + } + ], + metadata: { + mode: "provider", + provider: "openai", + model: "gpt-4.1-mini", + inputCount: 3, + outputCount: 1 } - ]); + }); }, 30); }) ); @@ -164,6 +185,9 @@ describe("rag rerank integration", () => { expect.arrayContaining(["secondary_rerank_timeout"]) ); expect(reranked.retrieval_bundle.context_pack?.status).toBe("degraded"); + expect( + reranked.retrieval_bundle.rerank_metadata?.secondary.unavailable_reason + ).toBe("secondary_rerank_timeout"); expect(reranked.retrieval_bundle.reranked?.every((item) => item.secondary_score === undefined)).toBe( true ); diff --git a/apps/backend/test/integration/rag-retrieval.service.spec.ts b/apps/backend/test/integration/rag-retrieval.service.spec.ts index 5b2cb57..b0847ed 100644 --- a/apps/backend/test/integration/rag-retrieval.service.spec.ts +++ b/apps/backend/test/integration/rag-retrieval.service.spec.ts @@ -180,6 +180,69 @@ describe("rag retrieval service integration", () => { await moduleRef.close(); }); + it("marks dense lane unavailable when index/query vector spaces are incompatible", async () => { + const moduleRef = await Test.createTestingModule({ + imports: [AppModule] + }).compile(); + + const indexRepository = moduleRef.get(RagIndexRepository); + const indexBuilder = moduleRef.get(RagIndexBuilderService); + const retrievalService = moduleRef.get(RagRetrievalService); + + const datasourceId = "ds-rag-retrieval-dense-incompatible"; + indexRepository.seedChunksForDatasource(datasourceId, [ + { + id: "chunk-dense-incompatible-schema", + datasourceId, + domain: "schema", + content: "table orders(id, amount, status)" + }, + { + id: "chunk-dense-incompatible-sql", + datasourceId, + domain: "sql_example", + content: "SELECT SUM(amount) FROM orders" + } + ]); + const build = await indexBuilder.buildAndActivate({ + datasourceId, + sourceVersion: "source-rag-retrieval-dense-incompatible-v1", + createdByRunId: "run-rag-retrieval-dense-incompatible-build-v1", + activatedByRunId: "run-rag-retrieval-dense-incompatible-build-v1" + }); + const indexedEntries = await indexRepository.listEntriesByVersion(build.indexVersionId); + await indexRepository.replaceEntriesForVersion( + build.indexVersionId, + indexedEntries.map((entry) => { + const metadata = JSON.parse(entry.metadata ?? "{}") as Record; + const dense = ((metadata.dense as Record | undefined) ?? {}); + return { + ...entry, + metadata: JSON.stringify({ + ...metadata, + dense: { + ...dense, + dimensions: 999 + } + }) + }; + }) + ); + + const response = await retrievalService.retrieve({ + query: "orders amount", + datasourceId, + runId: "run-rag-retrieval-dense-incompatible-v1" + }); + + expect(response.retrieval_bundle.lane_results.dense.status).toBe("degraded"); + expect(response.retrieval_bundle.degrade_reasons).toEqual( + expect.arrayContaining(["dense_unavailable_incompatible_vector_space"]) + ); + + await moduleRef.close(); + }); + it("marks trusted prior SQL as hit and promotes it into retrieval candidates", async () => { const moduleRef = await Test.createTestingModule({ imports: [AppModule] diff --git a/apps/backend/test/integration/rag-run-replay.spec.ts b/apps/backend/test/integration/rag-run-replay.spec.ts index 4389e30..30f6911 100644 --- a/apps/backend/test/integration/rag-run-replay.spec.ts +++ b/apps/backend/test/integration/rag-run-replay.spec.ts @@ -100,4 +100,46 @@ describe("rag run replay completeness integration", () => { await moduleRef.close(); }); + + it("persists rerank metadata payload for replay diagnostics", async () => { + const moduleRef = await Test.createTestingModule({ + imports: [AppModule] + }).compile(); + const replay = moduleRef.get(RagReplayRepository); + const runId = "run-rag-replay-rerank-metadata-v1"; + + await replay.writeReplay({ + runId, + replayKey: "rerank:secondary", + datasourceId: "ds-rag-replay", + stage: "rerank_secondary", + payload: { + status: "degraded", + reason: "secondary_rerank_unavailable_provider_config_missing", + metadata: { + status: "degraded", + unavailable_reason: "secondary_rerank_unavailable_provider_config_missing", + input_count: 4, + output_count: 0 + } + } + }); + + const events = await replay.listByRunId(runId); + const secondary = events.find((item) => item.replayKey === "rerank:secondary"); + const payload = JSON.parse(secondary?.payload ?? "{}") as { + metadata?: { + unavailable_reason?: string; + input_count?: number; + output_count?: number; + }; + }; + expect(payload.metadata?.unavailable_reason).toBe( + "secondary_rerank_unavailable_provider_config_missing" + ); + expect(payload.metadata?.input_count).toBe(4); + expect(payload.metadata?.output_count).toBe(0); + + await moduleRef.close(); + }); }); diff --git a/apps/backend/test/integration/save-view-from-run.spec.ts b/apps/backend/test/integration/save-view-from-run.spec.ts index edc6d90..37577ae 100644 --- a/apps/backend/test/integration/save-view-from-run.spec.ts +++ b/apps/backend/test/integration/save-view-from-run.spec.ts @@ -4,6 +4,36 @@ import type { KnowledgeMemoryContract } from "../../src/modules/knowledge/contra import { ModelingGraphRepository } from "../../src/modules/platform/data/persistence/modeling-graph.repository"; import { ModelingGraphValidator } from "../../src/modules/platform/data/persistence/modeling-graph.validator"; +const V2_STAGE_ORDER = [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" +] as const; + +const createV2Trace = (runId: string, provider = "openai") => ({ + runId, + provider, + retryCount: 0, + steps: [], + v2: { + version: "v2" as const, + stageOrder: [...V2_STAGE_ORDER], + stages: V2_STAGE_ORDER.map((stage) => ({ + stage, + status: + stage === "correct" + ? ("skipped" as const) + : ("success" as const) + })) + } +}); + const buildUsecase = (knowledgeMemoryContract?: KnowledgeMemoryContract) => { const chatRepository = new ChatRepository({ databaseUrl: "" @@ -43,12 +73,7 @@ describe("save view from run integration", () => { status: "executionResult", provider: "openai", sql: "SELECT * FROM orders LIMIT 10", - trace: { - runId: "run-1", - provider: "openai", - retryCount: 0, - steps: [] - }, + trace: createV2Trace("run-1"), createdAt: "2026-04-23T01:00:00.000Z" }); @@ -92,12 +117,7 @@ describe("save view from run integration", () => { status: "executionResult", provider: "openai", sql: "SELECT * FROM orders LIMIT 10", - trace: { - runId: "run-1", - provider: "openai", - retryCount: 0, - steps: [] - }, + trace: createV2Trace("run-1"), createdAt: "2026-04-23T01:00:00.000Z" }); @@ -133,12 +153,7 @@ describe("save view from run integration", () => { status: "executionResult", provider: "openai", sql: "SELECT * FROM orders LIMIT 10", - trace: { - runId: "run-1", - provider: "openai", - retryCount: 0, - steps: [] - }, + trace: createV2Trace("run-1"), createdAt: "2026-04-23T01:00:00.000Z" }); await chatRepository.persistRun({ @@ -148,12 +163,7 @@ describe("save view from run integration", () => { status: "executionResult", provider: "openai", sql: "SELECT * FROM customers LIMIT 10", - trace: { - runId: "run-2", - provider: "openai", - retryCount: 0, - steps: [] - }, + trace: createV2Trace("run-2"), createdAt: "2026-04-23T01:10:00.000Z" }); @@ -195,12 +205,7 @@ describe("save view from run integration", () => { status: "executionResult", provider: "openai", sql: "SELECT * FROM orders LIMIT 10", - trace: { - runId: "run-1", - provider: "openai", - retryCount: 0, - steps: [] - }, + trace: createV2Trace("run-1"), createdAt: "2026-04-23T01:00:00.000Z" }); await chatRepository.persistRun({ @@ -210,12 +215,7 @@ describe("save view from run integration", () => { status: "executionResult", provider: "openai", sql: "SELECT * FROM customers LIMIT 10", - trace: { - runId: "run-2", - provider: "openai", - retryCount: 0, - steps: [] - }, + trace: createV2Trace("run-2"), createdAt: "2026-04-23T01:10:00.000Z" }); @@ -282,12 +282,7 @@ describe("save view from run integration", () => { status: "executionResult", provider: "openai", sql: "SELECT * FROM orders LIMIT 10", - trace: { - runId: "run-1", - provider: "openai", - retryCount: 0, - steps: [] - }, + trace: createV2Trace("run-1"), createdAt: "2026-04-23T01:00:00.000Z" }); @@ -318,4 +313,109 @@ describe("save view from run integration", () => { }) ]); }); + + it("rejects unsupported historical run shape with deterministic hard-cut error", async () => { + const { usecase, chatRepository } = buildUsecase(); + await chatRepository.createSession({ + id: "session-legacy", + datasource: "ds-1", + workspaceId: "ws-1", + title: "legacy", + createdAt: "2026-04-23T00:00:00.000Z" + }); + await chatRepository.persistRun({ + runId: "run-legacy", + sessionId: "session-legacy", + question: "legacy", + status: "executionResult", + provider: "openai", + sql: "SELECT 1", + trace: { + runId: "run-legacy", + provider: "openai", + retryCount: 0, + steps: [] + }, + createdAt: "2026-04-23T01:00:00.000Z" + }); + + await expect( + usecase.execute({ + runId: "run-legacy", + name: "legacy_saved_view", + actorId: "user-admin" + }) + ).rejects.toMatchObject({ + code: "LEGACY_RUN_UNSUPPORTED", + statusCode: 410, + details: expect.objectContaining({ + runId: "run-legacy", + expectedContract: "text2sql-v2-read-model", + requiredMarkers: { + version: "run.trace.v2.version === 'v2'", + stageOrder: "run.trace.v2.stageOrder.length > 0", + stageArtifacts: "run.trace.v2.stages.length > 0" + }, + migrationRunbook: + "docs/runbooks/text2sql-v2-hardcut-read-model-migration.md" + }) + }); + }); + + it("keeps run-not-found priority when run session metadata is missing", async () => { + const { usecase, chatRepository } = buildUsecase(); + + await chatRepository.persistRun({ + runId: "run-orphan-session", + sessionId: "session-missing", + question: "legacy", + status: "executionResult", + provider: "openai", + sql: "SELECT 1", + trace: createV2Trace("run-orphan-session"), + createdAt: "2026-04-23T01:00:00.000Z" + }); + + await expect( + usecase.execute({ + runId: "run-orphan-session", + name: "orphan_view", + actorId: "user-admin" + }) + ).rejects.toMatchObject({ + code: "RUN_NOT_FOUND", + statusCode: 404 + }); + }); + + it("keeps run-not-found priority before hard-cut checks for orphan legacy runs", async () => { + const { usecase, chatRepository } = buildUsecase(); + + await chatRepository.persistRun({ + runId: "run-orphan-legacy", + sessionId: "session-missing", + question: "legacy", + status: "executionResult", + provider: "openai", + sql: "SELECT 1", + trace: { + runId: "run-orphan-legacy", + provider: "openai", + retryCount: 0, + steps: [] + }, + createdAt: "2026-04-23T01:00:00.000Z" + }); + + await expect( + usecase.execute({ + runId: "run-orphan-legacy", + name: "orphan_legacy_view", + actorId: "user-admin" + }) + ).rejects.toMatchObject({ + code: "RUN_NOT_FOUND", + statusCode: 404 + }); + }); }); diff --git a/apps/backend/test/integration/saved-prior-sql-capture.spec.ts b/apps/backend/test/integration/saved-prior-sql-capture.spec.ts index 2c46138..e6b415e 100644 --- a/apps/backend/test/integration/saved-prior-sql-capture.spec.ts +++ b/apps/backend/test/integration/saved-prior-sql-capture.spec.ts @@ -77,7 +77,7 @@ const createService = (override?: { status: "active", entryCount: 1, archivedChannels: ["lexical", "dense"], - denseMode: "placeholder_vector_string" + denseMode: "mock_provider" }) }; const service = new SavedPriorSqlService( diff --git a/apps/backend/test/integration/settings-provider-capability.spec.ts b/apps/backend/test/integration/settings-provider-capability.spec.ts new file mode 100644 index 0000000..7cb57d1 --- /dev/null +++ b/apps/backend/test/integration/settings-provider-capability.spec.ts @@ -0,0 +1,147 @@ +import { INestApplication } from "@nestjs/common"; +import { Test } from "@nestjs/testing"; +import request from "supertest"; +import { AppModule } from "../../src/app.module"; +import { requestActorMiddleware } from "../../src/modules/auth/request-actor.middleware"; +import { requestIdMiddleware } from "../../src/modules/middleware/request-id.middleware"; +import { createSeededSqliteFixture } from "../support/sqlite-fixture"; + +function withActor( + req: request.Test, + role: "admin" | "user", + userId: string +): request.Test { + return req.set("x-user-role", role).set("x-user-id", userId); +} + +describe("settings provider capability integration", () => { + let app: INestApplication; + let cleanupFixture: (() => Promise) | undefined; + + beforeAll(async () => { + const fixture = await createSeededSqliteFixture("settings-provider-capability"); + cleanupFixture = fixture.cleanup; + process.env.SQLITE_PATH = fixture.dbPath; + process.env.DATABASE_URL = ""; + process.env.REDIS_URL = ""; + process.env.LLM_PROVIDER = "openai"; + process.env.LLM_MODEL = "gpt-4.1-mini"; + process.env.LLM_MOCK_MODE = "true"; + + const moduleRef = await Test.createTestingModule({ + imports: [AppModule] + }).compile(); + app = moduleRef.createNestApplication(); + app.use(requestIdMiddleware); + app.use(requestActorMiddleware); + await app.init(); + }); + + afterAll(async () => { + await app.close(); + if (cleanupFixture) { + await cleanupFixture(); + } + }); + + it("exposes provider capability metadata and allows provider create/read lifecycle", async () => { + const supportedRes = await withActor( + request(app.getHttpServer()).get("/api/v1/settings/providers/supported"), + "admin", + "admin-settings-provider" + ); + expect(supportedRes.status).toBe(200); + expect(supportedRes.body.status).toBe("success"); + expect(Array.isArray(supportedRes.body.data)).toBe(true); + expect( + supportedRes.body.data.some( + (item: { + provider: string; + displayName: string; + defaultBaseUrl: string; + supportsModelListing: boolean; + }) => + item.provider === "openai" && + item.displayName.length > 0 && + item.defaultBaseUrl.length > 0 && + typeof item.supportsModelListing === "boolean" + ) + ).toBe(true); + + const createRes = await withActor( + request(app.getHttpServer()).post("/api/v1/settings/providers"), + "admin", + "admin-settings-provider" + ).send({ + provider: "openai", + displayName: "unit1-openai-provider", + baseUrl: "https://api.openai.com/v1", + enabled: true + }); + expect(createRes.status).toBe(201); + expect(createRes.body.status).toBe("success"); + expect(createRes.body.data.provider).toBe("openai"); + expect(createRes.body.data.displayName).toBe("unit1-openai-provider"); + const providerConfigId = createRes.body.data.id as string; + + const viewRes = await withActor( + request(app.getHttpServer()).get("/api/v1/settings/models"), + "admin", + "admin-settings-provider" + ); + expect(viewRes.status).toBe(200); + expect(viewRes.body.status).toBe("success"); + expect( + viewRes.body.data.providers.some( + (provider: { id: string; provider: string; displayName: string }) => + provider.id === providerConfigId && + provider.provider === "openai" && + provider.displayName === "unit1-openai-provider" + ) + ).toBe(true); + expect(Array.isArray(viewRes.body.data.models)).toBe(true); + expect(viewRes.body.data.items).toBeUndefined(); + }); + + it("returns degraded health with stable reason when provider api key is missing", async () => { + const createRes = await withActor( + request(app.getHttpServer()).post("/api/v1/settings/providers"), + "admin", + "admin-settings-provider" + ).send({ + provider: "openai", + displayName: "unit1-health-openai-provider", + baseUrl: "https://api.openai.com/v1", + enabled: true + }); + expect(createRes.status).toBe(201); + const providerConfigId = createRes.body.data.id as string; + + const healthRes = await withActor( + request(app.getHttpServer()).post( + `/api/v1/settings/providers/${providerConfigId}/health` + ), + "admin", + "admin-settings-provider" + ); + expect(healthRes.status).toBe(201); + expect(healthRes.body.status).toBe("success"); + expect(healthRes.body.data.status).toBe("degraded"); + expect(typeof healthRes.body.data.message).toBe("string"); + expect(healthRes.body.data.message).toContain("配置不完整"); + }); + + it("rejects user-role provider write operation", async () => { + const deniedRes = await withActor( + request(app.getHttpServer()).post("/api/v1/settings/providers"), + "user", + "user-settings-provider" + ).send({ + provider: "openai", + displayName: "forbidden-provider" + }); + expect(deniedRes.status).toBe(403); + expect(deniedRes.body.statusCode).toBe(403); + expect(deniedRes.body.message).toContain("仅管理员可执行该操作"); + }); +}); diff --git a/apps/backend/test/integration/settings-rag-config.spec.ts b/apps/backend/test/integration/settings-rag-config.spec.ts new file mode 100644 index 0000000..85beef5 --- /dev/null +++ b/apps/backend/test/integration/settings-rag-config.spec.ts @@ -0,0 +1,248 @@ +import { INestApplication } from "@nestjs/common"; +import { Test } from "@nestjs/testing"; +import request from "supertest"; +import { AppModule } from "../../src/app.module"; +import { requestActorMiddleware } from "../../src/modules/auth/request-actor.middleware"; +import { requestIdMiddleware } from "../../src/modules/middleware/request-id.middleware"; +import { createSeededSqliteFixture } from "../support/sqlite-fixture"; + +function withActor( + req: request.Test, + role: "admin" | "user", + userId: string +): request.Test { + return req.set("x-user-role", role).set("x-user-id", userId); +} + +describe("settings rag config integration", () => { + let app: INestApplication; + let cleanupFixture: (() => Promise) | undefined; + const originalFetch = global.fetch; + + beforeAll(async () => { + const fixture = await createSeededSqliteFixture("settings-rag-config"); + cleanupFixture = fixture.cleanup; + process.env.SQLITE_PATH = fixture.dbPath; + process.env.DATABASE_URL = ""; + process.env.REDIS_URL = ""; + process.env.LLM_MOCK_MODE = "true"; + process.env.RERANK_MOCK_MODE = "false"; + process.env.EMBEDDING_MOCK_MODE = "false"; + process.env.EMBEDDING_BASE_URL = ""; + process.env.EMBEDDING_API_KEY = ""; + process.env.RERANK_BASE_URL = ""; + process.env.RERANK_API_KEY = ""; + + const moduleRef = await Test.createTestingModule({ + imports: [AppModule] + }).compile(); + app = moduleRef.createNestApplication(); + app.use(requestIdMiddleware); + app.use(requestActorMiddleware); + await app.init(); + }); + + afterAll(async () => { + global.fetch = originalFetch; + await app.close(); + if (cleanupFixture) { + await cleanupFixture(); + } + }); + + it("returns degraded health when no settings config and no env fallback", async () => { + const healthRes = await withActor( + request(app.getHttpServer()).post("/api/v1/settings/rag-configs/embedding/health"), + "admin", + "admin-rag-health" + ).send({}); + expect(healthRes.status).toBe(201); + expect(healthRes.body.status).toBe("success"); + expect(healthRes.body.data.status).toBe("degraded"); + expect(healthRes.body.data.configSource).toBe("missing"); + expect(healthRes.body.data.checkedAgainst).toBe("persisted"); + expect(healthRes.body.data.reasonCode).toBe("provider_unavailable"); + }); + + it("supports dry-check against draft config for embedding", async () => { + const healthRes = await withActor( + request(app.getHttpServer()).post("/api/v1/settings/rag-configs/embedding/health"), + "admin", + "admin-rag-draft-health" + ).send({ + draft: { + provider: "openai", + model: "text-embedding-3-small", + baseUrl: "https://api.openai.com/v1", + apiKey: "sk-draft-embedding", + enabled: true, + dimensions: 1536, + vectorVersion: "v1", + timeoutMs: 5000 + }, + expectedDimensions: 1536 + }); + + expect(healthRes.status).toBe(201); + expect(healthRes.body.status).toBe("success"); + expect(healthRes.body.data.checkedAgainst).toBe("draft"); + expect(healthRes.body.data.reasonCode).toBe("ok"); + }); + + it("lists provider models for rag draft preview without persisting provider config", async () => { + global.fetch = jest.fn().mockResolvedValue({ + ok: true, + json: async () => ({ + data: [ + { id: "gpt-4.1-mini" }, + { id: "text-embedding-3-small" } + ] + }) + }) as never; + + const previewRes = await withActor( + request(app.getHttpServer()).post("/api/v1/settings/rag-configs/embedding/models"), + "admin", + "admin-rag-preview-models" + ).send({ + provider: "openai", + baseUrl: "https://api.openai.com/v1", + apiKey: "sk-preview" + }); + + expect(previewRes.status).toBe(201); + expect(previewRes.body.status).toBe("success"); + expect(previewRes.body.data.provider).toBe("openai"); + expect(previewRes.body.data.recommendedModel).toBe("text-embedding-3-small"); + expect(previewRes.body.data.models[0]?.model).toBe("text-embedding-3-small"); + global.fetch = originalFetch; + }); + + it("returns schema_invalid when dry-check draft is incomplete", async () => { + const healthRes = await withActor( + request(app.getHttpServer()).post("/api/v1/settings/rag-configs/embedding/health"), + "admin", + "admin-rag-draft-invalid" + ).send({ + draft: { + provider: "openai", + model: "", + baseUrl: "https://api.openai.com/v1", + enabled: true + } + }); + + expect(healthRes.status).toBe(201); + expect(healthRes.body.status).toBe("success"); + expect(healthRes.body.data.status).toBe("failed"); + expect(healthRes.body.data.reasonCode).toBe("schema_invalid"); + expect(healthRes.body.data.checkedAgainst).toBe("draft"); + }); + + it("allows admin to upsert embedding/rerank configs and list task-separated records", async () => { + const embeddingRes = await withActor( + request(app.getHttpServer()).put("/api/v1/settings/rag-configs/embedding"), + "admin", + "admin-rag-config" + ).send({ + provider: "openai", + model: "text-embedding-3-small", + baseUrl: "https://api.openai.com/v1", + apiKey: "embedding-secret-key", + enabled: true, + dimensions: 1024, + vectorVersion: "v2" + }); + expect(embeddingRes.status).toBe(200); + expect(embeddingRes.body.status).toBe("success"); + expect(embeddingRes.body.data.taskType).toBe("embedding"); + expect(embeddingRes.body.data.configSource).toBe("settings"); + + const rerankRes = await withActor( + request(app.getHttpServer()).put("/api/v1/settings/rag-configs/rerank"), + "admin", + "admin-rag-config" + ).send({ + provider: "openai", + model: "gpt-4.1-mini", + baseUrl: "https://api.openai.com/v1", + apiKey: "rerank-secret-key", + enabled: true, + timeoutMs: 5000 + }); + expect(rerankRes.status).toBe(200); + expect(rerankRes.body.status).toBe("success"); + expect(rerankRes.body.data.taskType).toBe("rerank"); + expect(rerankRes.body.data.configSource).toBe("settings"); + + const listRes = await withActor( + request(app.getHttpServer()).get("/api/v1/settings/rag-configs"), + "admin", + "admin-rag-config" + ); + expect(listRes.status).toBe(200); + expect(listRes.body.status).toBe("success"); + expect(Array.isArray(listRes.body.data.items)).toBe(true); + expect( + listRes.body.data.items.some( + (item: { taskType: string; configSource: string; hasApiKey: boolean }) => + item.taskType === "embedding" && + item.configSource === "settings" && + item.hasApiKey === true + ) + ).toBe(true); + expect( + listRes.body.data.items.some( + (item: { taskType: string; configSource: string; hasApiKey: boolean }) => + item.taskType === "rerank" && + item.configSource === "settings" && + item.hasApiKey === true + ) + ).toBe(true); + }); + + it("returns sample rerank payload from task-specific health check", async () => { + const healthRes = await withActor( + request(app.getHttpServer()).post("/api/v1/settings/rag-configs/rerank/health"), + "admin", + "admin-rag-health" + ).send({ + sampleQuery: "revenue by status", + sampleCandidates: ["orders amount by status", "users profile", "finance cube"] + }); + expect(healthRes.status).toBe(201); + expect(healthRes.body.status).toBe("success"); + expect(healthRes.body.data.status).toBe("healthy"); + expect(healthRes.body.data.configSource).toBe("settings"); + expect(Array.isArray(healthRes.body.data.sample?.reranked)).toBe(true); + }); + + it("rejects user-role write operations", async () => { + const deniedRes = await withActor( + request(app.getHttpServer()).put("/api/v1/settings/rag-configs/embedding"), + "user", + "user-rag-config" + ).send({ + provider: "openai", + model: "text-embedding-3-small", + baseUrl: "https://api.openai.com/v1", + apiKey: "forbidden" + }); + expect(deniedRes.status).toBe(403); + expect(deniedRes.body.statusCode).toBe(403); + expect(deniedRes.body.message).toContain("仅管理员可执行该操作"); + }); + + it("keeps /settings/models contract focused on provider/model governance", async () => { + const viewRes = await withActor( + request(app.getHttpServer()).get("/api/v1/settings/models"), + "admin", + "admin-rag-config" + ); + expect(viewRes.status).toBe(200); + expect(viewRes.body.status).toBe("success"); + expect(Array.isArray(viewRes.body.data.providers)).toBe(true); + expect(Array.isArray(viewRes.body.data.models)).toBe(true); + expect(viewRes.body.data.items).toBeUndefined(); + }); +}); diff --git a/apps/backend/test/integration/settings-rag-readiness.spec.ts b/apps/backend/test/integration/settings-rag-readiness.spec.ts new file mode 100644 index 0000000..9f5d45f --- /dev/null +++ b/apps/backend/test/integration/settings-rag-readiness.spec.ts @@ -0,0 +1,103 @@ +import { INestApplication } from "@nestjs/common"; +import { Test } from "@nestjs/testing"; +import request from "supertest"; +import { AppModule } from "../../src/app.module"; +import { requestActorMiddleware } from "../../src/modules/auth/request-actor.middleware"; +import { requestIdMiddleware } from "../../src/modules/middleware/request-id.middleware"; +import { createSeededSqliteFixture } from "../support/sqlite-fixture"; + +function withActor( + req: request.Test, + role: "admin" | "user", + userId: string +): request.Test { + return req.set("x-user-role", role).set("x-user-id", userId); +} + +describe("settings rag readiness integration", () => { + let app: INestApplication; + let cleanupFixture: (() => Promise) | undefined; + + beforeAll(async () => { + const fixture = await createSeededSqliteFixture("settings-rag-readiness"); + cleanupFixture = fixture.cleanup; + process.env.SQLITE_PATH = fixture.dbPath; + process.env.DATABASE_URL = ""; + process.env.REDIS_URL = ""; + process.env.LLM_MOCK_MODE = "true"; + process.env.EMBEDDING_MOCK_MODE = "true"; + process.env.RERANK_MOCK_MODE = "true"; + + const moduleRef = await Test.createTestingModule({ + imports: [AppModule] + }).compile(); + app = moduleRef.createNestApplication(); + app.use(requestIdMiddleware); + app.use(requestActorMiddleware); + await app.init(); + }); + + afterAll(async () => { + await app.close(); + if (cleanupFixture) { + await cleanupFixture(); + } + }); + + it("returns stable reasonCode/details when dimensions mismatch", async () => { + const upsertEmbedding = await withActor( + request(app.getHttpServer()).put("/api/v1/settings/rag-configs/embedding"), + "admin", + "admin-rag-readiness" + ).send({ + provider: "openai", + model: "text-embedding-3-small", + baseUrl: "https://api.openai.com/v1", + apiKey: "embedding-health-key", + enabled: true, + dimensions: 1536, + vectorVersion: "v2" + }); + expect(upsertEmbedding.status).toBe(200); + + const healthRes = await withActor( + request(app.getHttpServer()).post("/api/v1/settings/rag-configs/embedding/health"), + "admin", + "admin-rag-readiness" + ).send({ + expectedDimensions: 1024 + }); + + expect(healthRes.status).toBe(201); + expect(healthRes.body.status).toBe("success"); + expect(healthRes.body.data.status).toBe("failed"); + expect(healthRes.body.data.reasonCode).toBe("dimension_mismatch"); + expect(healthRes.body.data.details.expectedDimensions).toBe(1024); + expect(healthRes.body.data.details.actualDimensions).toBeGreaterThan(0); + }); + + it("exposes active embedding/rerank provider summary in /health", async () => { + const upsertRerank = await withActor( + request(app.getHttpServer()).put("/api/v1/settings/rag-configs/rerank"), + "admin", + "admin-rag-readiness" + ).send({ + provider: "siliconflow", + model: "BAAI/bge-reranker-v2-m3", + baseUrl: "https://api.siliconflow.cn/v1", + apiKey: "rerank-health-key", + enabled: true, + timeoutMs: 8000 + }); + expect(upsertRerank.status).toBe(200); + + const healthRes = await request(app.getHttpServer()).get("/health"); + + expect(healthRes.status).toBe(200); + expect(healthRes.body.status).toBe("success"); + expect(healthRes.body.data.dependencies.ragConfig.embedding.provider).toBe("openai"); + expect(healthRes.body.data.dependencies.ragConfig.rerank.provider).toBe( + "siliconflow" + ); + }); +}); diff --git a/apps/backend/test/integration/settings-rag-rerank-challenge.spec.ts b/apps/backend/test/integration/settings-rag-rerank-challenge.spec.ts new file mode 100644 index 0000000..c359db1 --- /dev/null +++ b/apps/backend/test/integration/settings-rag-rerank-challenge.spec.ts @@ -0,0 +1,91 @@ +import { INestApplication } from "@nestjs/common"; +import { Test } from "@nestjs/testing"; +import request from "supertest"; +import { AppModule } from "../../src/app.module"; +import { requestActorMiddleware } from "../../src/modules/auth/request-actor.middleware"; +import { requestIdMiddleware } from "../../src/modules/middleware/request-id.middleware"; +import { createSeededSqliteFixture } from "../support/sqlite-fixture"; + +function withActor( + req: request.Test, + role: "admin" | "user", + userId: string +): request.Test { + return req.set("x-user-role", role).set("x-user-id", userId); +} + +describe("settings rag rerank challenge integration", () => { + let app: INestApplication; + let cleanupFixture: (() => Promise) | undefined; + + beforeAll(async () => { + const fixture = await createSeededSqliteFixture("settings-rag-rerank-challenge"); + cleanupFixture = fixture.cleanup; + process.env.SQLITE_PATH = fixture.dbPath; + process.env.DATABASE_URL = ""; + process.env.REDIS_URL = ""; + process.env.LLM_MOCK_MODE = "true"; + process.env.RERANK_MOCK_MODE = "true"; + process.env.EMBEDDING_MOCK_MODE = "true"; + + const moduleRef = await Test.createTestingModule({ + imports: [AppModule] + }).compile(); + app = moduleRef.createNestApplication(); + app.use(requestIdMiddleware); + app.use(requestActorMiddleware); + await app.init(); + }); + + afterAll(async () => { + await app.close(); + if (cleanupFixture) { + await cleanupFixture(); + } + }); + + it("auto-fills builtin samples when sample candidates are insufficient", async () => { + const rerankRes = await withActor( + request(app.getHttpServer()).put("/api/v1/settings/rag-configs/rerank"), + "admin", + "admin-rag-rerank-challenge" + ).send({ + provider: "openai", + model: "gpt-4.1-mini", + baseUrl: "https://api.openai.com/v1", + apiKey: "rerank-health-key", + enabled: true + }); + expect(rerankRes.status).toBe(200); + + const healthRes = await withActor( + request(app.getHttpServer()).post("/api/v1/settings/rag-configs/rerank/health"), + "admin", + "admin-rag-rerank-challenge" + ).send({ + sampleQuery: "revenue by status", + sampleCandidates: ["orders by status"] + }); + expect(healthRes.status).toBe(201); + expect(healthRes.body.status).toBe("success"); + expect(healthRes.body.data.reasonCode).toBe("ok"); + expect(healthRes.body.data.challenge.status).toBe("comparable"); + expect(healthRes.body.data.sample.reranked.length).toBeGreaterThanOrEqual(2); + }); + + it("returns comparable challenge summary when samples are present", async () => { + const healthRes = await withActor( + request(app.getHttpServer()).post("/api/v1/settings/rag-configs/rerank/health"), + "admin", + "admin-rag-rerank-challenge" + ).send({ + sampleQuery: "revenue by status", + sampleCandidates: ["orders amount by status", "users profile", "finance cube"] + }); + expect(healthRes.status).toBe(201); + expect(healthRes.body.status).toBe("success"); + expect(healthRes.body.data.reasonCode).toBe("ok"); + expect(healthRes.body.data.challenge.status).toBe("comparable"); + expect(typeof healthRes.body.data.challenge.delta).toBe("number"); + }); +}); diff --git a/apps/backend/test/integration/text2sql-semantic-asset-reindex.spec.ts b/apps/backend/test/integration/text2sql-semantic-asset-reindex.spec.ts new file mode 100644 index 0000000..5f19d52 --- /dev/null +++ b/apps/backend/test/integration/text2sql-semantic-asset-reindex.spec.ts @@ -0,0 +1,106 @@ +import { resolve } from "node:path"; +import { Test } from "@nestjs/testing"; +import { AppModule } from "../../src/app.module"; +import { + SemanticAssetReindexService, + type SemanticAssetReindexTrigger +} from "../../src/modules/knowledge/rag/retrieval/semantic-asset-reindex.service"; +import { RagIndexRepository } from "../../src/modules/rag/index/rag-index.repository"; + +describe("text2sql semantic asset reindex integration", () => { + beforeAll(() => { + process.env.SQLITE_PATH = resolve( + __dirname, + "../../../../data/sqlite/text2sql.db" + ); + process.env.DATABASE_URL = ""; + process.env.REDIS_URL = ""; + process.env.NODE_ENV = "test"; + process.env.LLM_MOCK_MODE = "true"; + process.env.EMBEDDING_MOCK_MODE = "true"; + process.env.EMBEDDING_PROVIDER = "volcengine"; + process.env.EMBEDDING_MODEL = "embedding-v2"; + process.env.EMBEDDING_VECTOR_VERSION = "v3"; + }); + + it("reindexes semantic assets with trigger-mapped source version", async () => { + const moduleRef = await Test.createTestingModule({ + imports: [AppModule] + }).compile(); + const service = moduleRef.get(SemanticAssetReindexService); + const repository = moduleRef.get(RagIndexRepository); + + repository.seedChunksForDatasource("sqlite_main", [ + { + id: "chunk-semantic-asset-reindex-orders", + datasourceId: "sqlite_main", + domain: "schema", + content: "table orders(id, amount, status)", + metadata: JSON.stringify({ + tableNames: ["orders"], + columnNames: ["id", "amount", "status"] + }) + } + ]); + + const triggers: SemanticAssetReindexTrigger[] = ["schema", "embedding_model", "examples"]; + const result = await service.reindex({ + datasourceId: "sqlite_main", + workspaceId: "ws-semantic-reindex", + triggers, + reason: "unit2_contract_refresh", + runId: "run-semantic-asset-reindex-v1" + }); + + expect(result.status).toBe("reindexed"); + expect(result.indexVersionId).toBeDefined(); + expect(result.semanticAssetVersion).toContain("semantic-assets-"); + expect(result.sourceVersion).toContain("embedding_model"); + expect(result.embeddingProfile.provider).toBe("volcengine"); + expect(result.embeddingProfile.model).toBe("embedding-v2"); + expect(result.embeddingProfile.vectorVersion).toBe("v3"); + expect(result.triggerSummary.schema).toBe(true); + expect(result.triggerSummary.embedding_model).toBe(true); + expect(result.triggerSummary.examples).toBe(true); + + await moduleRef.close(); + }); + + it("skips reindex when the same source version is already active", async () => { + const moduleRef = await Test.createTestingModule({ + imports: [AppModule] + }).compile(); + const service = moduleRef.get(SemanticAssetReindexService); + const repository = moduleRef.get(RagIndexRepository); + + repository.seedChunksForDatasource("sqlite_main", [ + { + id: "chunk-semantic-asset-reindex-orders-2", + datasourceId: "sqlite_main", + domain: "schema", + content: "table orders(id, amount, status)", + metadata: JSON.stringify({ + tableNames: ["orders"], + columnNames: ["id", "amount", "status"] + }) + } + ]); + + const request = { + datasourceId: "sqlite_main", + workspaceId: "ws-semantic-reindex", + triggers: ["schema", "embedding_model"] as SemanticAssetReindexTrigger[], + reason: "unit2_contract_refresh", + runId: "run-semantic-asset-reindex-v2" + }; + + const first = await service.reindex(request); + const second = await service.reindex(request); + + expect(first.status).toBe("reindexed"); + expect(second.status).toBe("skipped"); + expect(second.reasonCodes).toContain("skip:already_active"); + + await moduleRef.close(); + }); +}); diff --git a/apps/backend/test/integration/text2sql-unified-rag-eval-gate.spec.ts b/apps/backend/test/integration/text2sql-unified-rag-eval-gate.spec.ts new file mode 100644 index 0000000..5e9a204 --- /dev/null +++ b/apps/backend/test/integration/text2sql-unified-rag-eval-gate.spec.ts @@ -0,0 +1,118 @@ +import { readFileSync } from "node:fs"; +import { resolve } from "node:path"; +import { + Text2SqlV2EvaluationService, + type Text2SqlV2EvalCase +} from "../../src/modules/conversation/runtime/evaluation/text2sql-v2-evaluation.service"; + +interface CharacterizationSurface { + version: string; + stageOrder: string[]; + stageArtifactCount: number; + hasSemanticPlan: boolean; +} + +interface CharacterizationCase { + id: string; + expectedStageOrder: string[]; + surfaces: Record; +} + +function summarizeCharacterization(cases: CharacterizationCase[]): { + gatePass: boolean; + reasons: string[]; +} { + const surfaceNames = ["sync", "stream", "replay", "runView", "saveView"]; + if (cases.length === 0) { + return { + gatePass: false, + reasons: ["characterization_fixture_empty"] + }; + } + + const failedIds: string[] = []; + for (const item of cases) { + const surfaceRecords = surfaceNames.map((name) => item.surfaces[name]); + const hasMissingSurface = surfaceRecords.some((surface) => !surface); + if (hasMissingSurface || item.expectedStageOrder.length === 0) { + failedIds.push(item.id); + continue; + } + + const stageOrderMatch = surfaceRecords.every( + (surface) => + JSON.stringify(surface.stageOrder) === JSON.stringify(item.expectedStageOrder) + ); + const versionMatch = surfaceRecords.every((surface) => surface.version === "v2"); + const artifactCountMatch = surfaceRecords.every( + (surface) => surface.stageArtifactCount >= item.expectedStageOrder.length + ); + const semanticPlanParity = + new Set(surfaceRecords.map((surface) => surface.hasSemanticPlan)).size === 1; + + if (!stageOrderMatch || !versionMatch || !artifactCountMatch || !semanticPlanParity) { + failedIds.push(item.id); + } + } + + return { + gatePass: failedIds.length === 0, + reasons: + failedIds.length > 0 + ? [`characterization_parity_failed:${failedIds.join(",")}`] + : [] + }; +} + +describe("text2sql unified rag eval gate integration", () => { + it("keeps eval + characterization rollout gate pass for current fixtures", () => { + const evalFixturePath = resolve( + __dirname, + "../fixtures/text2sql-v2-eval-cases.json" + ); + const characterizationFixturePath = resolve( + __dirname, + "../fixtures/text2sql-v2-characterization-cases.json" + ); + const evalCases = JSON.parse( + readFileSync(evalFixturePath, "utf-8") + ) as Text2SqlV2EvalCase[]; + const characterizationCases = JSON.parse( + readFileSync(characterizationFixturePath, "utf-8") + ) as CharacterizationCase[]; + + const evalService = new Text2SqlV2EvaluationService(); + const summary = evalService.summarize(evalCases); + const characterization = summarizeCharacterization(characterizationCases); + + expect(summary.rollout.gatePass).toBe(true); + expect(summary.rollout.recommendedStage).toBe("direct_v2_go"); + expect(summary.rollout.rollbackSuggested).toBe(false); + expect(summary.rollout.reasons).toEqual([]); + // Guard threshold edge-case: retrievalRelevance should stay around the 0.75 gate after runtime intelligence fixtures. + expect(summary.retrievalRelevance).toBeCloseTo(0.7638, 4); + expect(summary.rollout.thresholds.minRetrievalRelevance).toBe(0.75); + + expect(characterization.gatePass).toBe(true); + expect(characterization.reasons).toEqual([]); + + const rollout = { + gatePass: summary.rollout.gatePass && characterization.gatePass, + recommendedStage: + summary.rollout.gatePass && characterization.gatePass + ? "direct_v2_go" + : summary.rollout.rollbackSuggested + ? "rollback_or_hold" + : "hold", + rollbackSuggested: summary.rollout.rollbackSuggested, + reasons: [ + ...summary.rollout.reasons.map((item) => `eval:${item}`), + ...characterization.reasons.map((item) => `characterization:${item}`) + ] + }; + expect(rollout.gatePass).toBe(true); + expect(rollout.recommendedStage).toBe("direct_v2_go"); + expect(rollout.rollbackSuggested).toBe(false); + expect(rollout.reasons).toEqual([]); + }); +}); diff --git a/apps/backend/test/integration/text2sql-v2-characterization-gate.spec.ts b/apps/backend/test/integration/text2sql-v2-characterization-gate.spec.ts new file mode 100644 index 0000000..89f43bd --- /dev/null +++ b/apps/backend/test/integration/text2sql-v2-characterization-gate.spec.ts @@ -0,0 +1,48 @@ +import { readFileSync } from "node:fs"; +import { resolve } from "node:path"; + +type CharacterizationSurface = { + version: string; + stageOrder: string[]; + stageArtifactCount: number; + hasSemanticPlan: boolean; +}; + +type CharacterizationCase = { + id: string; + scenario: string; + expectedStageOrder: string[]; + surfaces: Record; +}; + +describe("text2sql v2 characterization gate integration", () => { + it("ensures sync/stream/replay/run-view/save-view share the same v2 artifact facts", () => { + const fixturePath = resolve( + __dirname, + "../fixtures/text2sql-v2-characterization-cases.json" + ); + const fixture = JSON.parse(readFileSync(fixturePath, "utf-8")) as CharacterizationCase[]; + + expect(fixture.length).toBeGreaterThan(0); + + for (const item of fixture) { + expect(item.expectedStageOrder.length).toBeGreaterThan(0); + + const surfaceNames = ["sync", "stream", "replay", "runView", "saveView"]; + for (const surfaceName of surfaceNames) { + const surface = item.surfaces[surfaceName]; + expect(surface).toBeDefined(); + expect(surface.version).toBe("v2"); + expect(surface.stageOrder).toEqual(item.expectedStageOrder); + expect(surface.stageArtifactCount).toBeGreaterThanOrEqual( + item.expectedStageOrder.length + ); + } + + const semanticPlanParity = new Set( + surfaceNames.map((surfaceName) => item.surfaces[surfaceName]?.hasSemanticPlan) + ); + expect(semanticPlanParity.size).toBe(1); + } + }); +}); diff --git a/apps/backend/test/integration/text2sql-v2-closeout-flow.spec.ts b/apps/backend/test/integration/text2sql-v2-closeout-flow.spec.ts new file mode 100644 index 0000000..16cb458 --- /dev/null +++ b/apps/backend/test/integration/text2sql-v2-closeout-flow.spec.ts @@ -0,0 +1,81 @@ +import { readFileSync } from "node:fs"; +import { resolve } from "node:path"; + +interface FlowNode { + id: string; + requirementIds: string[]; + implementationOwners: string[]; + evidenceOwners: string[]; + expectedTestFiles: string[]; + gateRelevance: boolean; + behaviorTestStatus: string; + coverageOwnerStatus: string; +} + +interface FlowMatrix { + nodes: FlowNode[]; +} + +describe("text2sql v2 closeout target flow matrix", () => { + const matrix = JSON.parse( + readFileSync( + resolve(__dirname, "../fixtures/text2sql-v2-closeout-flow-matrix.json"), + "utf-8" + ) + ) as FlowMatrix; + + it("keeps every target flow node A-M traceable to requirements, owners, evidence, and behavior tests", () => { + const expectedNodeIds = [ + "A.context-envelope", + "B.intake", + "C.route", + "C1.targeted-clarification", + "C2.general-metadata-answer", + "D.retrieve-context", + "D1.external-embedding-rerank", + "D2.schema-ddl-supplement", + "E.semantic-context-pack", + "F.semantic-plan", + "G.plan-confidence", + "H.structured-sql-generation", + "I.validation", + "J.read-only-execution", + "K.diagnosis-bounded-correction", + "L.fail-closed-evidence", + "M.final-answer-replay-artifacts" + ]; + + expect(matrix.nodes.map((node) => node.id)).toEqual(expectedNodeIds); + for (const node of matrix.nodes) { + expect(node.requirementIds.length).toBeGreaterThan(0); + expect(node.implementationOwners.length).toBeGreaterThan(0); + expect(node.evidenceOwners.length).toBeGreaterThan(0); + expect(node.expectedTestFiles.length).toBeGreaterThan(0); + expect(node.gateRelevance).toBe(true); + expect(["covered", "partial", "planned"]).toContain(node.behaviorTestStatus); + expect(["covered", "partial", "planned"]).toContain(node.coverageOwnerStatus); + } + }); + + it("keeps route and convergence nodes linked to semantic plan and runner behavior tests", () => { + const routeNodeIds = [ + "C.route", + "C1.targeted-clarification", + "C2.general-metadata-answer", + "F.semantic-plan", + "G.plan-confidence", + "L.fail-closed-evidence" + ]; + const routeNodes = matrix.nodes.filter((node) => routeNodeIds.includes(node.id)); + + expect(routeNodes).toHaveLength(routeNodeIds.length); + for (const node of routeNodes) { + expect(node.expectedTestFiles).toEqual( + expect.arrayContaining([ + expect.stringMatching(/text2sql-v2-(semantic-plan|runner)|text2sql-v2-closeout-flow/) + ]) + ); + expect(node.evidenceOwners.join(" ")).toMatch(/trace\.v2|delivery\.evidence\.v2/); + } + }); +}); diff --git a/apps/backend/test/integration/text2sql-v2-eval-gate.spec.ts b/apps/backend/test/integration/text2sql-v2-eval-gate.spec.ts new file mode 100644 index 0000000..9780a2b --- /dev/null +++ b/apps/backend/test/integration/text2sql-v2-eval-gate.spec.ts @@ -0,0 +1,171 @@ +import { readFileSync } from "node:fs"; +import { resolve } from "node:path"; +import { + Text2SqlV2EvaluationService, + type Text2SqlV2EvalCase +} from "../../src/modules/conversation/runtime/evaluation/text2sql-v2-evaluation.service"; +import { + buildCloseoutRollout, + summarizeCharacterization +} from "../../scripts/collect-text2sql-v2-eval-gate"; + +describe("text2sql v2 eval gate integration", () => { + it("aggregates fixture metrics, traceability, and closeout gates", () => { + const fixturePath = resolve( + __dirname, + "../fixtures/text2sql-v2-eval-cases.json" + ); + const characterizationFixturePath = resolve( + __dirname, + "../fixtures/text2sql-v2-characterization-cases.json" + ); + const fixture = JSON.parse(readFileSync(fixturePath, "utf-8")) as Text2SqlV2EvalCase[]; + const characterizationFixture = JSON.parse( + readFileSync(characterizationFixturePath, "utf-8") + ) as Array<{ + id: string; + scenario: string; + expectedStageOrder: string[]; + surfaces: Record< + string, + { + version: string; + stageOrder: string[]; + stageArtifactCount: number; + hasSemanticPlan: boolean; + } + >; + }>; + + const service = new Text2SqlV2EvaluationService(); + const summary = service.summarize(fixture); + const characterization = summarizeCharacterization(characterizationFixture); + const closeout = buildCloseoutRollout({ + summary, + characterization, + noLegacy: { + gatePass: true, + reasons: [], + scannedCount: 14 + }, + focusedCoverage: { + gatePass: true, + reasons: [], + coveragePath: "/tmp/coverage-final.json", + matrixPath: "/tmp/text2sql-v2-closeout-flow-matrix.json" + } + }); + + expect(summary.totalCases).toBeGreaterThan(0); + expect(summary.rollout.gatePass).toBe(true); + expect(summary.traceability.gatePass).toBe(true); + expect(summary.traceability.missingFamilies).toEqual([]); + expect(characterization.gatePass).toBe(true); + expect(closeout.gatePass).toBe(true); + expect(closeout.recommendedStage).toBe("direct_v2_go"); + expect(closeout.closeoutGates.evalTraceability.gatePass).toBe(true); + }); + + it("blocks closeout when eval traceability is incomplete even if eval metrics pass", () => { + const fixturePath = resolve( + __dirname, + "../fixtures/text2sql-v2-eval-cases.json" + ); + const fixture = JSON.parse(readFileSync(fixturePath, "utf-8")) as Text2SqlV2EvalCase[]; + const service = new Text2SqlV2EvaluationService(); + const summary = service.summarize( + fixture.map((item) => { + if (item.id !== "zh-dense-unavailable-008") { + return item; + } + return { + ...item, + traceability: { + ...item.traceability!, + behaviorTests: [] + } + }; + }) + ); + + const closeout = buildCloseoutRollout({ + summary, + characterization: { + totalCases: 1, + parityPassCount: 1, + parityCoverageRate: 1, + gatePass: true, + reasons: [] + }, + noLegacy: { + gatePass: true, + reasons: [], + scannedCount: 14 + }, + focusedCoverage: { + gatePass: true, + reasons: [], + coveragePath: "/tmp/coverage-final.json", + matrixPath: "/tmp/text2sql-v2-closeout-flow-matrix.json" + } + }); + + expect(summary.rollout.gatePass).toBe(true); + expect(summary.traceability.gatePass).toBe(false); + expect(closeout.gatePass).toBe(false); + expect(closeout.recommendedStage).toBe("hold"); + expect(closeout.reasons).toEqual( + expect.arrayContaining([ + expect.stringContaining( + "traceability:family:dense-unavailable:missing_behavior_test_traceability" + ) + ]) + ); + }); + + it("keeps closeout blocked when no-legacy or focused coverage gates fail", () => { + const fixturePath = resolve( + __dirname, + "../fixtures/text2sql-v2-eval-cases.json" + ); + const fixture = JSON.parse(readFileSync(fixturePath, "utf-8")) as Text2SqlV2EvalCase[]; + const service = new Text2SqlV2EvaluationService(); + const summary = service.summarize(fixture); + + const closeout = buildCloseoutRollout({ + summary, + characterization: { + totalCases: 1, + parityPassCount: 1, + parityCoverageRate: 1, + gatePass: true, + reasons: [] + }, + noLegacy: { + gatePass: false, + reasons: [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts:1:1:langgraph legacy delegation" + ], + scannedCount: 14 + }, + focusedCoverage: { + gatePass: false, + reasons: ["critical:apps/backend/src/modules/conversation/adapters/sql-correction.service.ts:line_coverage_below_75"], + coveragePath: "/tmp/coverage-final.json", + matrixPath: "/tmp/text2sql-v2-closeout-flow-matrix.json" + } + }); + + expect(closeout.gatePass).toBe(false); + expect(closeout.recommendedStage).toBe("rollback_or_hold"); + expect(closeout.rollbackSuggested).toBe(true); + expect(closeout.reasons).toEqual( + expect.arrayContaining([ + expect.stringContaining( + "no_legacy:apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts" + ), + expect.stringContaining("focused_coverage:critical:apps/backend/src/modules/conversation/adapters/sql-correction.service.ts") + ]) + ); + }); +}); diff --git a/apps/backend/test/integration/text2sql-v2-focused-coverage-gate.spec.ts b/apps/backend/test/integration/text2sql-v2-focused-coverage-gate.spec.ts new file mode 100644 index 0000000..f002f6e --- /dev/null +++ b/apps/backend/test/integration/text2sql-v2-focused-coverage-gate.spec.ts @@ -0,0 +1,550 @@ +import { + evaluateFocusedCoverageGate, + type CloseoutFlowMatrix +} from "../../scripts/collect-text2sql-v2-focused-coverage-gate"; + +const LEGACY_CRITICAL_FILES = [ + "apps/backend/src/modules/conversation/adapters/sql-correction.service.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts", + "apps/backend/src/modules/conversation/adapters/sql-validation.service.ts", + "apps/backend/src/modules/conversation/adapters/semantic-context-pack.service.ts", + "apps/backend/src/modules/llm/embedding-router.service.ts", + "apps/backend/src/modules/conversation/runtime/stages/run-v2-langgraph.stage.ts" +] as const; + +const LANGGRAPH_CRITICAL_FILES = [ + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts", + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper.ts", + "apps/backend/src/modules/conversation/nodes/intake.node.ts" +] as const; + +const LAYERED_LANGGRAPH_RUNNER_OWNER = LEGACY_CRITICAL_FILES[1]; +const LAYERED_LANGGRAPH_STAGE_OWNER = LEGACY_CRITICAL_FILES[5]; +const PRE_LAYERED_LANGGRAPH_RUNNER_OWNER = + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts"; +const PRE_LAYERED_LANGGRAPH_STAGE_OWNER = + "apps/backend/src/modules/conversation/text2sql/stages/run-v2-langgraph.stage.ts"; +const PRE_LAYERED_LANGGRAPH_GRAPH_OWNER = + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph.ts"; +const PRE_LAYERED_LANGGRAPH_RESULT_MAPPER_OWNER = + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper.ts"; +const PRE_LAYERED_INTAKE_NODE_OWNER = + "apps/backend/src/modules/conversation/nodes/intake.node.ts"; +const LEGACY_RUNNER_OWNER = + "apps/backend/src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-runner.service.ts"; +const LEGACY_STAGE_OWNER = + "apps/backend/src/modules/conversation/text2sql/stages/run-v2-state-machine.stage.ts"; +const ARTIFACT_REF_OWNER = + "apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts"; + +const ALL_COVERAGE_FILES = [ + ...LEGACY_CRITICAL_FILES, + ...LANGGRAPH_CRITICAL_FILES, + PRE_LAYERED_LANGGRAPH_RUNNER_OWNER, + PRE_LAYERED_LANGGRAPH_STAGE_OWNER, + PRE_LAYERED_LANGGRAPH_GRAPH_OWNER, + PRE_LAYERED_LANGGRAPH_RESULT_MAPPER_OWNER, + PRE_LAYERED_INTAKE_NODE_OWNER, + ARTIFACT_REF_OWNER +] as const; + +function fileCoverage(params: { + file: string; + totalLines?: number; + coveredLines?: number; + totalBranches?: number; + coveredBranches?: number; +}) { + const totalLines = params.totalLines ?? 10; + const coveredLines = params.coveredLines ?? totalLines; + const totalBranches = params.totalBranches ?? 10; + const coveredBranches = params.coveredBranches ?? totalBranches; + + return { + path: params.file, + statementMap: Object.fromEntries( + Array.from({ length: totalLines }, (_, index) => [ + String(index), + { start: { line: index + 1 } } + ]) + ), + s: Object.fromEntries( + Array.from({ length: totalLines }, (_, index) => [ + String(index), + index < coveredLines ? 1 : 0 + ]) + ), + branchMap: Object.fromEntries( + Array.from({ length: totalBranches }, (_, index) => [String(index), {}]) + ), + b: Object.fromEntries( + Array.from({ length: totalBranches }, (_, index) => [ + String(index), + [index < coveredBranches ? 1 : 0] + ]) + ) + }; +} + +function coverageFor( + files: readonly string[], + overrides: Record< + string, + Partial<{ + totalLines: number; + coveredLines: number; + totalBranches: number; + coveredBranches: number; + }> + > = {} +) { + return Object.fromEntries( + files.map((file) => [ + `/repo/${file}`, + fileCoverage({ + file: `/repo/${file}`, + ...overrides[file] + }) + ]) + ); +} + +function coveredMatrix(): CloseoutFlowMatrix { + return { + version: "test", + nodes: [ + { + id: "A.context-envelope", + requirementIds: ["R1"], + implementationOwners: [LEGACY_CRITICAL_FILES[0]], + evidenceOwners: ["run.trace.v2"], + expectedTestFiles: ["apps/backend/test/unit/text2sql-v2-runner.spec.ts"], + gateRelevance: true, + behaviorTestStatus: "covered", + coverageOwnerStatus: "covered", + canonicalRuntimeOwners: [ + LAYERED_LANGGRAPH_STAGE_OWNER, + LAYERED_LANGGRAPH_RUNNER_OWNER + ], + canonicalOwnerStatus: "planned", + contractAssertionMode: "behavior_contract" + }, + { + id: "M.final-answer-replay-artifacts", + requirementIds: ["R4"], + implementationOwners: [LEGACY_CRITICAL_FILES[1]], + evidenceOwners: ["run.delivery.evidence.v2"], + expectedTestFiles: ["apps/backend/test/unit/text2sql-stream-event.mapper.spec.ts"], + gateRelevance: true, + behaviorTestStatus: "covered", + coverageOwnerStatus: "covered", + canonicalRuntimeOwners: [LANGGRAPH_CRITICAL_FILES[1]], + canonicalOwnerStatus: "planned", + contractAssertionMode: "behavior_contract" + } + ], + evalFixtureFamilies: [ + { + family: "dense-unavailable", + evalCases: ["zh-dense-unavailable-008"], + behaviorTests: ["apps/backend/test/unit/text2sql-v2-embedding-provider.spec.ts"], + flowNodes: ["A.context-envelope"] + } + ], + criticalFileOwnerMigrations: [ + { + from: PRE_LAYERED_LANGGRAPH_RUNNER_OWNER, + to: LAYERED_LANGGRAPH_RUNNER_OWNER, + reason: + "Layered runtime migration moves the canonical LangGraph runner owner under conversation/runtime", + threshold: { line: 80 } + }, + { + from: PRE_LAYERED_LANGGRAPH_STAGE_OWNER, + to: LAYERED_LANGGRAPH_STAGE_OWNER, + reason: + "Layered runtime migration moves the canonical workflow seam stage under conversation/runtime", + threshold: { line: 80 } + }, + { + from: PRE_LAYERED_LANGGRAPH_GRAPH_OWNER, + to: LANGGRAPH_CRITICAL_FILES[0], + reason: + "Layered runtime migration moves the canonical graph owner under conversation/runtime", + threshold: { line: 80 } + }, + { + from: PRE_LAYERED_LANGGRAPH_RESULT_MAPPER_OWNER, + to: LANGGRAPH_CRITICAL_FILES[1], + reason: + "Layered runtime migration moves result mapping ownership under conversation/runtime", + threshold: { line: 80 } + }, + { + from: PRE_LAYERED_INTAKE_NODE_OWNER, + to: LANGGRAPH_CRITICAL_FILES[2], + reason: + "Layered runtime migration moves canonical node ownership under conversation/nodes", + threshold: { line: 75 } + }, + { + from: LEGACY_RUNNER_OWNER, + to: LAYERED_LANGGRAPH_RUNNER_OWNER, + reason: + "Legacy long-form v2 runner ownership is superseded by the layered LangGraph runtime seam", + threshold: { line: 80 } + }, + { + from: LEGACY_STAGE_OWNER, + to: LAYERED_LANGGRAPH_STAGE_OWNER, + reason: + "Legacy state-machine stage ownership is superseded by the layered LangGraph stage seam", + threshold: { line: 80 } + } + ], + runtimeCoverageRows: [ + { + id: "langgraph-runtime.seam", + owners: [LAYERED_LANGGRAPH_STAGE_OWNER, LAYERED_LANGGRAPH_RUNNER_OWNER], + expectedTestFiles: [ + "apps/backend/test/unit/text2sql-workflow-runner.spec.ts", + "apps/backend/test/unit/text2sql-v2-langgraph-runtime.spec.ts" + ], + coverageOwnerStatus: "planned", + critical: true, + blocker: + "Active workflow seam cannot close out until the LangGraph stage and runner land." + }, + { + id: "langgraph-runtime.topology", + owners: [...LANGGRAPH_CRITICAL_FILES], + expectedTestFiles: [ + "apps/backend/test/unit/text2sql-v2-langgraph-runtime.spec.ts" + ], + coverageOwnerStatus: "planned", + critical: true, + blocker: + "Canonical graph topology and mapper coverage must exist before the runtime cutover can pass." + } + ], + runtimeArtifactProducerRows: [ + "context_snippets", + "schema_supplement", + "prompt_input", + "provider_output_summary", + "validation_diagnostics", + "correction_grounding", + "execution_preview" + ].map((category) => ({ + category, + producerOwners: [ARTIFACT_REF_OWNER], + evidenceOwners: [`run.trace.v2.artifactRefs[${category}]`], + expectedTestFiles: [ + "apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts" + ], + behaviorTestStatus: "covered" as const, + coverageOwnerStatus: "covered" as const + })), + streamLifecycleRows: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ].map((stage) => ({ + stage, + lifecycles: + stage === "correct" + ? ["running", "completed", "skipped"] + : ["running", "completed"], + owners: [LANGGRAPH_CRITICAL_FILES[0]], + expectedTestFiles: ["apps/backend/test/unit/langgraph-runtime.spec.ts"], + behaviorTestStatus: "covered" as const, + coverageOwnerStatus: "covered" as const + })), + runtimePaths: { + currentActivePath: [ + "apps/backend/src/modules/conversation/text2sql/text2sql-workflow-runner.service.ts", + PRE_LAYERED_LANGGRAPH_STAGE_OWNER, + PRE_LAYERED_LANGGRAPH_RUNNER_OWNER + ], + targetActivePath: [ + "apps/backend/src/modules/conversation/text2sql/text2sql-workflow-runner.service.ts", + LAYERED_LANGGRAPH_STAGE_OWNER, + LAYERED_LANGGRAPH_RUNNER_OWNER + ], + criticalOwners: [ + LAYERED_LANGGRAPH_STAGE_OWNER, + LAYERED_LANGGRAPH_RUNNER_OWNER, + ...LANGGRAPH_CRITICAL_FILES + ], + delegationPolicy: "phase_a_delegation_zero", + delegationOwners: [LANGGRAPH_CRITICAL_FILES[0], LAYERED_LANGGRAPH_RUNNER_OWNER], + delegationForbiddenPatterns: [ + "runLegacyRuntime", + "legacyRunner", + "Text2SqlV2RunnerService" + ], + blockerPolicy: + "Closeout must stay blocked if a canonical LangGraph owner is missing or only legacy runtime-detail assertions remain." + } + }; +} + +describe("text2sql v2 focused coverage gate", () => { + it("passes when scoped totals, critical files, and traceability are complete", () => { + const report = evaluateFocusedCoverageGate({ + coverage: coverageFor(ALL_COVERAGE_FILES), + matrix: coveredMatrix(), + coveragePath: "/tmp/coverage-final.json", + matrixPath: "/tmp/matrix.json", + generatedAt: "2026-04-27T00:00:00.000Z" + }); + + expect(report.scoped.linePct).toBe(100); + expect(report.scoped.branchPct).toBe(100); + expect(report.criticalFiles.every((item) => item.gatePass)).toBe(true); + expect(report.delegationZero.gatePass).toBe(true); + expect(report.flowMatrix.gatePass).toBe(true); + expect(report.flowMatrix.incompleteRuntimeCoverageRows).toEqual([]); + expect(report.flowMatrix.incompleteRuntimeArtifactProducerRows).toEqual([]); + expect(report.flowMatrix.incompleteStreamLifecycleRows).toEqual([]); + expect(report.rollout).toMatchObject({ + gatePass: true, + recommendedStage: "closeout_ready", + rollbackSuggested: false, + reasons: [] + }); + }); + + it("fails when a critical file is below its line threshold", () => { + const report = evaluateFocusedCoverageGate({ + coverage: coverageFor(ALL_COVERAGE_FILES, { + [LEGACY_CRITICAL_FILES[0]]: { coveredLines: 7, totalLines: 10 } + }), + matrix: coveredMatrix() + }); + + expect(report.rollout.gatePass).toBe(false); + expect(report.rollout.reasons).toContain( + `critical:${LEGACY_CRITICAL_FILES[0]}:line_coverage_below_75` + ); + }); + + it("fails when phase-A delegation=0 static scan reports legacy runtime wiring", () => { + const report = evaluateFocusedCoverageGate({ + coverage: coverageFor(ALL_COVERAGE_FILES), + matrix: coveredMatrix(), + delegationZeroOverride: { + gatePass: false, + scannedFiles: [LAYERED_LANGGRAPH_RUNNER_OWNER], + violations: [ + { + file: LAYERED_LANGGRAPH_RUNNER_OWNER, + label: "legacy v2 runner import", + pattern: "Text2SqlV2RunnerService" + } + ], + reasons: [ + `${LAYERED_LANGGRAPH_RUNNER_OWNER}:legacy v2 runner import:Text2SqlV2RunnerService` + ] + } + }); + + expect(report.rollout.gatePass).toBe(false); + expect(report.rollout.reasons).toContain( + `delegation_zero:${LAYERED_LANGGRAPH_RUNNER_OWNER}:legacy v2 runner import:Text2SqlV2RunnerService` + ); + }); + + it("fails when a critical file is missing or has zero coverage", () => { + const [missingFile, zeroFile, ...remainingFiles] = ALL_COVERAGE_FILES; + const report = evaluateFocusedCoverageGate({ + coverage: coverageFor([zeroFile, ...remainingFiles], { + [zeroFile]: { coveredLines: 0, totalLines: 10 } + }), + matrix: coveredMatrix() + }); + + expect(report.rollout.gatePass).toBe(false); + expect(report.rollout.reasons).toContain( + `critical:${missingFile}:critical_file_missing_without_owner_migration` + ); + expect(report.rollout.reasons).toContain( + `critical:${zeroFile}:critical_file_zero_line_coverage` + ); + }); + + it("blocks closeout when eval fixtures lack behavior-test traceability", () => { + const matrix = coveredMatrix(); + matrix.evalFixtureFamilies[0] = { + ...matrix.evalFixtureFamilies[0], + behaviorTests: [] + }; + + const report = evaluateFocusedCoverageGate({ + coverage: coverageFor(ALL_COVERAGE_FILES), + matrix + }); + + expect(report.rollout.gatePass).toBe(false); + expect(report.flowMatrix.incompleteEvalFixtureFamilies).toEqual([ + { + family: "dense-unavailable", + reasons: ["missing_behavior_test_traceability"] + } + ]); + }); + + it("fails when a canonical workflow node loses its planned LangGraph owner mapping", () => { + const matrix = coveredMatrix(); + matrix.nodes[0] = { + ...matrix.nodes[0], + canonicalRuntimeOwners: [] + }; + + const report = evaluateFocusedCoverageGate({ + coverage: coverageFor(ALL_COVERAGE_FILES), + matrix + }); + + expect(report.rollout.gatePass).toBe(false); + expect(report.flowMatrix.incompleteNodes).toEqual([ + { + id: "A.context-envelope", + reasons: ["missing_canonical_runtime_owners"] + } + ]); + }); + + it("fails when strict-completion rows are missing behavior traceability", () => { + const matrix = coveredMatrix(); + matrix.strictCompletionRows = [ + { + id: "SC.metadata-grounding", + implementationOwners: [ + "apps/backend/src/modules/conversation/nodes/answer.node.ts" + ], + evidenceOwners: ["run.delivery.evidence.metadataAnswer"], + expectedTestFiles: [], + behaviorTestStatus: "partial", + coverageOwnerStatus: "covered", + contractAssertionMode: "behavior_contract" + } + ]; + + const report = evaluateFocusedCoverageGate({ + coverage: coverageFor(ALL_COVERAGE_FILES), + matrix + }); + + expect(report.rollout.gatePass).toBe(false); + expect(report.flowMatrix.incompleteStrictCompletionRows).toEqual([ + { + id: "SC.metadata-grounding", + reasons: ["missing_expected_behavior_tests", "behavior_test_status_partial"] + } + ]); + expect(report.rollout.reasons).toEqual( + expect.arrayContaining([ + expect.stringContaining( + "strict_row:SC.metadata-grounding:missing_expected_behavior_tests|behavior_test_status_partial" + ) + ]) + ); + }); + + it("fails when a required runtime artifact producer category is missing", () => { + const matrix = coveredMatrix(); + matrix.runtimeArtifactProducerRows = matrix.runtimeArtifactProducerRows?.filter( + (row) => row.category !== "validation_diagnostics" + ); + + const report = evaluateFocusedCoverageGate({ + coverage: coverageFor(ALL_COVERAGE_FILES), + matrix + }); + + expect(report.rollout.gatePass).toBe(false); + expect(report.flowMatrix.incompleteRuntimeArtifactProducerRows).toEqual([ + { + category: "validation_diagnostics", + reasons: ["missing_artifact_producer_row"] + } + ]); + expect(report.rollout.reasons).toContain( + "artifact_producer:validation_diagnostics:missing_artifact_producer_row" + ); + }); + + it("fails when a required stream lifecycle stage lacks running coverage", () => { + const matrix = coveredMatrix(); + matrix.streamLifecycleRows = matrix.streamLifecycleRows?.map((row) => + row.stage === "execute" + ? { + ...row, + lifecycles: ["completed"] + } + : row + ); + + const report = evaluateFocusedCoverageGate({ + coverage: coverageFor(ALL_COVERAGE_FILES), + matrix + }); + + expect(report.rollout.gatePass).toBe(false); + expect(report.flowMatrix.incompleteStreamLifecycleRows).toEqual([ + { + stage: "execute", + reasons: ["missing_running_lifecycle"] + } + ]); + }); + + it("requires explicit owner migration metadata when a critical file is replaced", () => { + const replacementFile = + "apps/backend/src/modules/conversation/adapters/sql-correction-decision.service.ts"; + const missingOriginal = ALL_COVERAGE_FILES.slice(1); + const matrixWithoutMigration = coveredMatrix(); + matrixWithoutMigration.criticalFileOwnerMigrations = []; + + const missingMigrationReport = evaluateFocusedCoverageGate({ + coverage: coverageFor([...missingOriginal, replacementFile]), + matrix: matrixWithoutMigration + }); + + expect(missingMigrationReport.rollout.gatePass).toBe(false); + expect(missingMigrationReport.rollout.reasons).toContain( + `critical:${ALL_COVERAGE_FILES[0]}:critical_file_missing_without_owner_migration` + ); + + const matrixWithMigration = coveredMatrix(); + matrixWithMigration.criticalFileOwnerMigrations = [ + { + from: ALL_COVERAGE_FILES[0], + to: replacementFile, + reason: "sql correction decisions moved behind a narrower owner module", + threshold: { line: 75 } + }, + ...(matrixWithMigration.criticalFileOwnerMigrations ?? []) + ]; + + const migratedReport = evaluateFocusedCoverageGate({ + coverage: coverageFor([...missingOriginal, replacementFile]), + matrix: matrixWithMigration + }); + + expect(migratedReport.rollout.gatePass).toBe(true); + expect(migratedReport.criticalFiles[0]).toMatchObject({ + file: ALL_COVERAGE_FILES[0], + effectiveFile: replacementFile, + migrated: true, + gatePass: true + }); + }); +}); diff --git a/apps/backend/test/unit/capability-boundary-check.spec.ts b/apps/backend/test/unit/capability-boundary-check.spec.ts index 8a92440..f9e2f15 100644 --- a/apps/backend/test/unit/capability-boundary-check.spec.ts +++ b/apps/backend/test/unit/capability-boundary-check.spec.ts @@ -190,6 +190,61 @@ export class RetrieveKnowledgeNode { }); }); + it("allows conversation -> knowledge stable entry imports", async () => { + await writeRepoFile( + repoRoot, + "apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts", + `import { KNOWLEDGE_FACADE_CONTRACT } from "../../knowledge"; +export class Text2SqlV2ArtifactRefService { + constructor(private readonly contract = KNOWLEDGE_FACADE_CONTRACT) {} +} +` + ); + await writeRepoFile( + repoRoot, + "apps/backend/src/modules/knowledge.ts", + `export const KNOWLEDGE_FACADE_CONTRACT = Symbol("KNOWLEDGE_FACADE_CONTRACT");` + ); + + const report = await runCapabilityBoundaryCheck({ repoRoot }); + expect(report.violations).toHaveLength(0); + expect((report as unknown as Record).conversationKnowledgeSubpath).toMatchObject({ + currentCount: 0, + baselineCount: 15, + remainingFromBaseline: 15, + overBaselineCount: 0, + exceedsBaseline: false + }); + }); + + it("reports conversation/text2sql -> legacy modules/chat imports as violations", async () => { + await writeRepoFile( + repoRoot, + "apps/backend/src/modules/conversation/text2sql/stages/prepare-run.stage.ts", + `import { LegacyChatService } from "../../../chat/chat.service"; +export class PrepareRunStage { + constructor(private readonly legacyChatService: LegacyChatService) {} +} +` + ); + await writeRepoFile( + repoRoot, + "apps/backend/src/modules/chat/chat.service.ts", + "export class LegacyChatService {}" + ); + + const report = await runCapabilityBoundaryCheck({ repoRoot }); + expect(report.violations).toHaveLength(1); + expect(report.violations[0]).toMatchObject({ + sourceDomain: "conversation", + targetDomain: "conversation", + sourceFile: + "apps/backend/src/modules/conversation/text2sql/stages/prepare-run.stage.ts", + targetFile: "apps/backend/src/modules/chat/chat.service.ts", + line: 1 + }); + }); + it("supports temporary allowlist + baseline counting for conversation -> knowledge/* direct imports", async () => { await writeRepoFile( repoRoot, diff --git a/apps/backend/test/unit/chat-delivery-enrichment.service.spec.ts b/apps/backend/test/unit/chat-delivery-enrichment.service.spec.ts new file mode 100644 index 0000000..a6a4758 --- /dev/null +++ b/apps/backend/test/unit/chat-delivery-enrichment.service.spec.ts @@ -0,0 +1,87 @@ +import { ChatDeliveryEnrichmentService } from "../../src/modules/conversation/chat/application/shared/chat-delivery-enrichment.service"; +import type { SqlRun } from "@text2sql/shared-types"; + +describe("ChatDeliveryEnrichmentService", () => { + it("builds delivery evidence v2 mirror with runtime intelligence fields from trace", () => { + const service = new ChatDeliveryEnrichmentService( + {} as never, + {} as never, + {} as never + ); + const run: SqlRun = { + runId: "run-enrichment", + sessionId: "session-enrichment", + question: "统计订单", + status: "executionResult", + provider: "volcengine", + answer: "ok", + trace: { + runId: "run-enrichment", + provider: "volcengine", + retryCount: 0, + steps: [], + v2: { + version: "v2", + stageOrder: ["intake", "answer"], + stages: [ + { + stage: "intake", + status: "success" + }, + { + stage: "answer", + status: "success" + } + ], + runtimePlan: { + version: "runtime-plan.v1", + items: [ + { + id: "runtime-plan:intake", + stage: "intake", + goal: "理解问题", + status: "completed" + } + ] + }, + artifactRefs: [ + { + id: "artifact:context_snippets:abc", + category: "context_snippets", + summary: "Compacted context", + hash: "sha256:abc", + visibility: "user" + } + ], + smartDefaults: { + bundleId: "text2sql-smart-defaults", + version: "2026-04-28", + coveredStages: ["generate-sql"], + ruleIds: ["only-use-context-pack"], + status: "applied" + } + } + }, + delivery: { + answer: { + text: "ok", + status: "executionResult", + provider: "volcengine" + }, + evidence: { + runId: "run-enrichment" + } + }, + llmRaw: null, + createdAt: "2026-04-28T00:00:00.000Z" + }; + + const enriched = service.withPromptTemplateEvidence(run); + + expect(enriched.delivery?.evidence?.v2).toMatchObject({ + runtimePlan: run.trace.v2?.runtimePlan, + artifactRefs: run.trace.v2?.artifactRefs, + smartDefaults: run.trace.v2?.smartDefaults + }); + }); +}); diff --git a/apps/backend/test/unit/clarify.node.spec.ts b/apps/backend/test/unit/clarify.node.spec.ts index 8ef1830..f61f6c6 100644 --- a/apps/backend/test/unit/clarify.node.spec.ts +++ b/apps/backend/test/unit/clarify.node.spec.ts @@ -20,9 +20,11 @@ describe("ClarifyNode", () => { decisionSource: "rule", bypassed: false, confidenceLevel: "medium", - missingCriticalSlots: ["metric"], - reasonCodes: ["missing_metric_slot"] + missingCriticalSlots: ["metric"] }); + expect(clarification?.reasonCodes).toEqual( + expect.arrayContaining(["missing_metric_slot"]) + ); }); it("exposes structured continue decision for sufficient input", () => { @@ -141,12 +143,12 @@ describe("ClarifyNode", () => { bypassed: false, confidenceLevel: "low", missingCriticalSlots: ["subject", "metric", "time"], - reasonCodes: [ + reasonCodes: expect.arrayContaining([ "fallback_exception", "missing_subject_slot", "missing_metric_slot", "missing_time_slot" - ] + ]) }); } finally { spy.mockRestore(); diff --git a/apps/backend/test/unit/delivery-contract.mapper.spec.ts b/apps/backend/test/unit/delivery-contract.mapper.spec.ts index da98dde..3c49b5a 100644 --- a/apps/backend/test/unit/delivery-contract.mapper.spec.ts +++ b/apps/backend/test/unit/delivery-contract.mapper.spec.ts @@ -137,6 +137,316 @@ describe("DeliveryContractMapper", () => { expect(delivery.artifact?.hasError).toBe(false); }); + it("mirrors context-pack and metadata-answer summaries from trace.v2", () => { + const mapper = new DeliveryContractMapper(new SandboxRuntimeService()); + const run = createBaseRun({ + sql: undefined, + rows: undefined, + columns: undefined, + trace: { + runId: "run-delivery-unit", + provider: "volcengine", + retryCount: 0, + steps: [], + v2: { + version: "v2", + stageOrder: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + stages: [ + { + stage: "intake", + status: "success", + metadata: { + route: "metadata" + } + }, + { stage: "retrieve", status: "success" }, + { stage: "assemble-context", status: "success" }, + { stage: "semantic-plan", status: "success" }, + { stage: "generate-sql", status: "skipped" }, + { stage: "validate", status: "skipped" }, + { stage: "correct", status: "skipped" }, + { stage: "execute", status: "skipped" }, + { stage: "answer", status: "success" } + ], + contextPack: { + status: "degraded", + selectedEvidenceIds: ["schema-orders", "metric-gmv"], + selectedTables: ["orders"], + selectedColumns: ["orders.id", "orders.amount"], + selectedContextSummary: { + count: 2, + evidenceIds: ["schema-orders", "metric-gmv"] + }, + pruning: { + applied: true, + decisions: [ + { + removedCount: 1 + } + ] + }, + permissionFiltering: { + status: "applied", + deniedEvidenceCount: 1 + }, + laneStates: [ + { + lane: "dense", + state: "unavailable" + } + ], + degradation: { + status: "degraded", + reasons: ["dense_unavailable:provider_missing"] + } + }, + semanticPlan: { + route: "answer", + standaloneQuestion: "数据库有哪些表", + selectedTables: ["orders"], + selectedColumns: ["orders.id", "orders.amount"], + confidence: 0.87, + evidenceRefs: ["schema-orders", "metric-gmv"], + filters: ["route_kind:metadata"], + planLedger: { + version: "plan-ledger.v1", + snapshotId: "semantic-plan-v1", + obligations: [ + { + id: "ledger:warning:degraded", + kind: "evidence", + summary: "degraded optional context", + criticality: "warning", + status: "warning", + evidenceRefs: [], + reasonCodes: ["dense_unavailable"] + } + ], + summary: { + snapshotId: "semantic-plan-v1", + total: 1, + hardBlockerCount: 0, + warningCount: 1, + warningIds: ["ledger:warning:degraded"], + reasonCodes: ["dense_unavailable"] + } + } + }, + planLedger: { + snapshotId: "semantic-plan-v1", + total: 1, + hardBlockerCount: 0, + warningCount: 1, + warningIds: ["ledger:warning:degraded"], + reasonCodes: ["dense_unavailable"] + } + } + } as SqlRun["trace"] + }); + + const delivery = mapper.map({ + run, + replayRecords: [] + }); + + expect(delivery.evidence?.contextPackSummary).toEqual({ + status: "degraded", + selectedEvidenceCount: 2, + selectedTableCount: 1, + selectedColumnCount: 2, + pruningApplied: true, + prunedEvidenceCount: 1, + degradedLaneCount: 1, + permissionFilteringApplied: true, + permissionDeniedEvidenceCount: 1, + degradationReasons: ["dense_unavailable:provider_missing"] + }); + expect(delivery.evidence?.metadataAnswer).toEqual({ + groundedByContextPack: true, + routeKind: "metadata", + evidenceQuality: "degraded", + selectedEvidenceCount: 2, + permissionFilteringApplied: true, + pruningApplied: true, + degradationReasons: ["dense_unavailable:provider_missing"] + }); + expect(delivery.evidence?.v2?.planLedger).toEqual({ + snapshotId: "semantic-plan-v1", + total: 1, + hardBlockerCount: 0, + warningCount: 1, + warningIds: ["ledger:warning:degraded"], + reasonCodes: ["dense_unavailable"] + }); + expect(delivery.evidence?.v2?.semanticPlan?.planLedger).toBeUndefined(); + }); + + it("projects general no-sql answer evidence without pretending SQL or schema execution", () => { + const mapper = new DeliveryContractMapper(new SandboxRuntimeService()); + const run = createBaseRun({ + sql: undefined, + rows: undefined, + columns: undefined, + answer: "GMV 是成交总额口径说明，不需要执行 SQL。", + trace: { + runId: "run-delivery-unit", + provider: "volcengine", + retryCount: 0, + steps: [], + v2: { + version: "v2", + stageOrder: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + stages: [ + { + stage: "intake", + status: "success", + metadata: { + route: "general" + } + }, + { stage: "generate-sql", status: "skipped" }, + { stage: "validate", status: "skipped" }, + { stage: "correct", status: "skipped" }, + { stage: "execute", status: "skipped" }, + { stage: "answer", status: "success" } + ], + semanticPlan: { + route: "answer", + standaloneQuestion: "什么是 GMV 口径？", + selectedTables: [], + selectedColumns: [], + confidence: 0.8, + evidenceRefs: [], + filters: ["route_kind:general"] + }, + runtimePlan: { + version: "runtime-plan.v1", + items: [ + { + id: "runtime-plan:generate-sql", + stage: "generate-sql", + goal: "生成 SQL", + status: "skipped", + reasonCodes: ["plain_general_no_sql"] + } + ] + } + } + } as SqlRun["trace"] + }); + + const delivery = mapper.map({ + run, + replayRecords: [] + }); + + expect(delivery.artifact?.sql).toBeUndefined(); + expect(delivery.evidence?.metadataAnswer).toMatchObject({ + groundedByContextPack: false, + routeKind: "general", + evidenceQuality: "degraded", + selectedEvidenceCount: 0 + }); + expect(delivery.evidence?.v2?.runtimePlan?.items[0]).toMatchObject({ + stage: "generate-sql", + status: "skipped", + reasonCodes: ["plain_general_no_sql"] + }); + }); + + it("mirrors correction grounding from trace.v2 sqlGeneration artifact", () => { + const mapper = new DeliveryContractMapper(new SandboxRuntimeService()); + const run = createBaseRun({ + trace: { + runId: "run-delivery-unit", + provider: "volcengine", + retryCount: 1, + steps: [], + v2: { + version: "v2", + stageOrder: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + stages: [ + { stage: "intake", status: "success" }, + { stage: "retrieve", status: "success" }, + { stage: "assemble-context", status: "success" }, + { stage: "semantic-plan", status: "success" }, + { stage: "generate-sql", status: "success" }, + { stage: "validate", status: "success" }, + { stage: "correct", status: "success" }, + { stage: "execute", status: "success" }, + { stage: "answer", status: "success" } + ], + sqlGeneration: { + sql: "SELECT orders.id FROM orders", + usedTables: ["orders"], + usedColumns: ["orders.id"], + evidenceRefs: ["chunk-orders-1"], + correctionGrounding: { + failedSqlRef: "sql.sha256.abc123abc123abcd", + retryReason: "missing column orders.missing_city", + failureCode: "SQL_MISSING_COLUMN", + failureCategory: "validation", + source: "validation", + attemptCount: 1, + maxAttempts: 2, + evidenceRefs: ["chunk-orders-1"], + semanticPlanSnapshotId: "semantic-plan-1", + semanticPlanRoute: "answer", + semanticPlanRouteKind: "text_to_sql", + selectedTableCount: 1, + selectedColumnCount: 1, + contextPackStatus: "ready", + contextPackEvidenceCount: 1 + } + } + } + } as SqlRun["trace"] + }); + + const delivery = mapper.map({ + run, + replayRecords: [] + }); + + expect(delivery.evidence?.correctionGrounding).toMatchObject({ + failedSqlRef: "sql.sha256.abc123abc123abcd", + retryReason: "missing column orders.missing_city", + attemptCount: 1, + maxAttempts: 2, + failureCode: "SQL_MISSING_COLUMN" + }); + }); + it("accepts chartbi artifact override and preserves unified answer semantics", () => { const mapper = new DeliveryContractMapper(new SandboxRuntimeService()); const run = createBaseRun({ @@ -310,7 +620,272 @@ describe("DeliveryContractMapper", () => { }); }); - it("reads snake_case clarification decision from clarify step summary", () => { + it("maps optional trace.v2 into delivery evidence.v2 without changing base evidence fields", () => { + const mapper = new DeliveryContractMapper(new SandboxRuntimeService()); + const run = createBaseRun({ + trace: { + runId: "run-delivery-unit", + provider: "volcengine", + retryCount: 0, + steps: [], + v2: { + version: "v2", + stageOrder: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + stages: [ + { + stage: "intake", + status: "success" + }, + { + stage: "validate", + status: "failed", + failure: { + code: "VALIDATION_FAILED", + message: "table not allowed", + category: "validation", + terminal: true, + correctable: false + } + } + ], + semanticPlan: { + route: "reject", + standaloneQuestion: "统计订单", + selectedTables: ["orders"], + selectedColumns: ["orders.id"], + confidence: 0.2, + evidenceRefs: ["chunk:1"], + snapshotId: "semantic-plan:fail-closed:ready:t1:c1:e1:g1:orders" + }, + sqlValidation: { + status: "failed", + checks: [ + { + check: "permission", + status: "failed", + code: "TABLE_FORBIDDEN" + } + ], + correctable: false + }, + runtimePlan: { + version: "runtime-plan.v1", + currentItemId: "plan:validate", + items: [ + { + id: "plan:validate", + stage: "validate", + goal: "Validate SQL against permissions and read-only policy.", + status: "failed", + reasonCodes: ["TABLE_FORBIDDEN"], + evidenceRefs: ["chunk:1"] + } + ] + }, + artifactRefs: [ + { + id: "artifact:validation:table-forbidden", + category: "validation_diagnostics", + summary: "Permission validation rejected the orders table.", + hash: "sha256:validation-table-forbidden", + sizeBytes: 512, + replayKeyHint: + "text2sql:artifact:validation_diagnostics:table-forbidden", + visibility: "internal", + sensitivity: "permission_filtered", + reasonCodes: ["permission_filtered"] + } + ], + smartDefaults: { + bundleId: "text2sql-smart-defaults", + version: "2026-04-28", + coveredStages: ["generate-sql", "validate", "answer"], + ruleIds: ["fail-closed-permission", "only-use-context-pack"], + status: "applied" + }, + loopEvidence: [ + { + loopIndex: 1, + triggerReason: "clarification_budget_exhausted|semantic_plan_fail_closed", + actionType: "fail_closed", + planDelta: { + route: { + to: "reject" + }, + snapshotId: "semantic-plan:fail-closed:ready:t1:c1:e1:g1:orders", + addedCoverageGapTypes: ["user_decision_gap"], + reasonCodes: [ + "clarification_budget_exhausted", + "semantic_plan_fail_closed" + ] + }, + terminationReason: "semantic_plan_fail_closed", + convergencePath: ["semantic-plan", "generate-sql", "reject"] + } + ], + terminationReason: "semantic_plan_fail_closed" + } + } as SqlRun["trace"] + }); + + const delivery = mapper.map({ + run, + replayRecords: [] + }); + + expect(delivery.evidence?.runId).toBe("run-delivery-unit"); + expect(delivery.evidence?.v2?.version).toBe("v2"); + expect(delivery.evidence?.v2?.stageOrder).toEqual([ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ]); + expect(delivery.evidence?.v2?.stageArtifacts).toHaveLength(2); + expect(delivery.evidence?.v2?.semanticPlan?.route).toBe("reject"); + expect(delivery.evidence?.v2?.semanticPlan?.snapshotId).toBe( + "semantic-plan:fail-closed:ready:t1:c1:e1:g1:orders" + ); + expect(delivery.evidence?.v2?.sqlValidation?.status).toBe("failed"); + expect(delivery.evidence?.v2?.runtimePlan?.items).toEqual([ + { + id: "plan:validate", + stage: "validate", + goal: "Validate SQL against permissions and read-only policy.", + status: "failed", + reasonCodes: ["TABLE_FORBIDDEN"], + evidenceRefs: ["chunk:1"] + } + ]); + expect(delivery.evidence?.v2?.artifactRefs).toEqual([ + { + id: "artifact:validation:table-forbidden", + category: "validation_diagnostics", + summary: "Permission validation rejected the orders table.", + hash: "sha256:validation-table-forbidden", + sizeBytes: 512, + replayKeyHint: + "text2sql:artifact:validation_diagnostics:table-forbidden", + visibility: "internal", + sensitivity: "permission_filtered", + reasonCodes: ["permission_filtered"] + } + ]); + expect(delivery.evidence?.v2?.smartDefaults).toEqual({ + bundleId: "text2sql-smart-defaults", + version: "2026-04-28", + coveredStages: ["generate-sql", "validate", "answer"], + ruleIds: ["fail-closed-permission", "only-use-context-pack"], + status: "applied" + }); + expect(delivery.evidence?.v2?.loopEvidence).toEqual([ + { + loopIndex: 1, + triggerReason: "clarification_budget_exhausted|semantic_plan_fail_closed", + actionType: "fail_closed", + planDelta: { + route: { + to: "reject" + }, + snapshotId: "semantic-plan:fail-closed:ready:t1:c1:e1:g1:orders", + addedCoverageGapTypes: ["user_decision_gap"], + reasonCodes: [ + "clarification_budget_exhausted", + "semantic_plan_fail_closed" + ] + }, + terminationReason: "semantic_plan_fail_closed", + convergencePath: ["semantic-plan", "generate-sql", "reject"] + } + ]); + expect(delivery.evidence?.v2?.terminationReason).toBe("semantic_plan_fail_closed"); + expect(delivery.evidence?.v2?.failure?.code).toBe("VALIDATION_FAILED"); + }); + + it("ignores malformed optional runtime intelligence fields in delivery projection", () => { + const mapper = new DeliveryContractMapper(new SandboxRuntimeService()); + const run = createBaseRun({ + trace: { + runId: "run-delivery-unit", + provider: "volcengine", + retryCount: 0, + steps: [], + v2: { + version: "v2", + stageOrder: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + stages: [ + { + stage: "intake", + status: "success" + } + ], + runtimePlan: { + version: "runtime-plan.v1", + items: [ + { + id: "plan:bad", + stage: "not-a-stage", + goal: "bad item", + status: "completed" + } + ] + }, + artifactRefs: [ + { + id: "artifact:missing-hash", + category: "context_snippets", + summary: "missing hash", + visibility: "user" + } + ], + smartDefaults: { + bundleId: "text2sql-smart-defaults", + version: "2026-04-28", + coveredStages: [], + ruleIds: [], + status: "applied" + } + } as unknown as NonNullable + } as SqlRun["trace"] + }); + + const delivery = mapper.map({ + run, + replayRecords: [] + }); + + expect(delivery.evidence?.v2?.version).toBe("v2"); + expect(delivery.evidence?.v2?.runtimePlan).toBeUndefined(); + expect(delivery.evidence?.v2?.artifactRefs).toBeUndefined(); + expect(delivery.evidence?.v2?.smartDefaults).toBeUndefined(); + }); + + it("ignores legacy clarify step summaries without canonical trace decision payload", () => { const mapper = new DeliveryContractMapper(new SandboxRuntimeService()); const run = createBaseRun({ status: "clarification", @@ -349,39 +924,45 @@ describe("DeliveryContractMapper", () => { replayRecords: [] }); - expect(delivery.evidence?.clarificationDecision).toEqual({ - decision: "clarify", - triggerPath: "rule", - confidenceLevel: "low", - missingCriticalSlots: ["time"], - conflictDetected: false, - reasonCodes: ["missing_time_slot"], - question: "请补充时间范围（例如近30天、本季度或具体起止日期）。", - reason: "关键槽位缺失：时间范围" - }); + expect(delivery.evidence?.clarificationDecision).toBeUndefined(); }); - it("maps SQL coverage evidence from generate-sql step summary", () => { + it("maps SQL coverage evidence from canonical trace.v2 sqlValidation", () => { const mapper = new DeliveryContractMapper(new SandboxRuntimeService()); const run = createBaseRun({ trace: { runId: "run-delivery-unit", provider: "volcengine", retryCount: 0, - steps: [ - { - node: "generate-sql", - status: "success", - at: "2026-04-18T00:00:00.500Z", - outputSummary: JSON.stringify({ - coverage: { - gateStatus: "passed", - missingObjects: [], - triggerSource: "selected_context" + steps: [], + v2: { + version: "v2", + stageOrder: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + stages: [ + { stage: "intake", status: "success" }, + { stage: "validate", status: "success" } + ], + sqlValidation: { + status: "passed", + checks: [ + { + check: "plan-coverage", + status: "passed" } - }) + ], + correctable: false } - ] + } } as SqlRun["trace"] }); @@ -402,7 +983,7 @@ describe("DeliveryContractMapper", () => { expect(evidenceWithCoverage?.sqlCoverage).toEqual({ gateStatus: "passed", missingObjects: [], - triggerSource: "selected_context" + triggerSource: "semantic_context" }); }); @@ -426,32 +1007,33 @@ describe("DeliveryContractMapper", () => { expect(delivery.evidence?.modelingRevision).toBe(12); }); - it("maps saved prior SQL shortcut evidence from resolve+safety trace steps", () => { + it("maps saved prior SQL shortcut evidence from canonical v2 stage artifacts", () => { const mapper = new DeliveryContractMapper(new SandboxRuntimeService()); const run = createBaseRun({ trace: { runId: "run-delivery-unit", provider: "volcengine", retryCount: 0, - steps: [ - { - node: "resolve-saved-prior-sql", - status: "success", - at: "2026-04-25T00:00:00.100Z", - outputSummary: JSON.stringify({ - status: "hit", - reasonCodes: ["prior_sql_shortcut_hit"], - selectedChunkId: "chunk-saved-prior-1", - selectedViewId: "view.chat_run.run-1", - selectedSourceRunId: "run-1" - }) - }, - { - node: "safety-check", - status: "success", - at: "2026-04-25T00:00:00.200Z" - } - ] + steps: [], + v2: { + version: "v2", + stageOrder: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + stages: [ + { stage: "intake", status: "success" }, + { stage: "generate-sql", status: "skipped" }, + { stage: "validate", status: "success" } + ] + } } as SqlRun["trace"] }); @@ -463,40 +1045,42 @@ describe("DeliveryContractMapper", () => { expect(delivery.evidence?.savedPriorSql).toEqual({ status: "hit", shortcutUsed: true, - reasonCodes: ["prior_sql_shortcut_hit"], - selectedChunkId: "chunk-saved-prior-1", - selectedViewId: "view.chat_run.run-1", - selectedSourceRunId: "run-1", + reasonCodes: ["saved_prior_sql_shortcut"], safetyResult: "passed" }); }); - it("falls back to semantic step summary for revision and binding evidence", () => { + it("reads semantic snapshot from canonical trace.v2 context pack", () => { const mapper = new DeliveryContractMapper(new SandboxRuntimeService()); const run = createBaseRun({ trace: { runId: "run-delivery-unit", provider: "volcengine", retryCount: 0, - steps: [ - { - node: "build-semantic-query", - status: "success", - at: "2026-04-18T00:00:00.500Z", - outputSummary: JSON.stringify({ - semanticVersion: 13, - lockStatus: "locked", - modelingRevision: 21, - contextPackStatus: "ready", - semanticBindingSummary: { - modelBindingCount: 4, - relationshipBindingCount: 2, - metricBindingCount: 3, - calculatedFieldBindingCount: 1 - } - }) + modelingRevision: 21, + steps: [], + v2: { + version: "v2", + stageOrder: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + stages: [{ stage: "intake", status: "success" }], + contextPack: { + status: "ready", + selectedEvidenceIds: [], + selectedTables: [], + selectedColumns: [], + warnings: ["semantic_context_ready"] } - ] + } } as SqlRun["trace"] }); @@ -506,15 +1090,8 @@ describe("DeliveryContractMapper", () => { }); expect(delivery.evidence?.modelingRevision).toBe(21); - expect(delivery.evidence?.semanticVersion).toBe(13); - expect(delivery.evidence?.semanticLockStatus).toBe("locked"); expect(delivery.evidence?.contextPackStatus).toBe("ready"); - expect(delivery.evidence?.semanticInstructionSummary).toEqual({ - modelBindingCount: 4, - relationshipBindingCount: 2, - metricBindingCount: 3, - calculatedFieldBindingCount: 1 - }); + expect(delivery.evidence?.semanticDegradeReason).toBe("semantic_context_ready"); }); it("keeps trace modelingRevision when step summary has a different revision", () => { diff --git a/apps/backend/test/unit/langgraph-runtime.spec.ts b/apps/backend/test/unit/langgraph-runtime.spec.ts index fd4989a..ec17fcf 100644 --- a/apps/backend/test/unit/langgraph-runtime.spec.ts +++ b/apps/backend/test/unit/langgraph-runtime.spec.ts @@ -1,374 +1,1071 @@ +import type { SqlRun } from "@text2sql/shared-types"; +import { createText2SqlV2LangGraph } from "../../src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.graph"; import { - createInitialLangGraphState, - normalizeTraceContext -} from "../../src/modules/conversation/agent/graph/langgraph.state"; -import { createLangGraphRuntime } from "../../src/modules/conversation/agent/graph/langgraph.runtime"; + createText2SqlV2LangGraphInitialState +} from "../../src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.state"; +import { Text2SqlV2ArtifactBuilder } from "../../src/modules/conversation/artifacts/text2sql-v2-artifact-builder"; +import { Text2SqlV2LangGraphResultMapper } from "../../src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper"; -const createMockIntentPlan = () => ({ - status: "ready" as const, - intent: "aggregate" as const, - constraints: [], - summary: "stub", - uncertaintySignal: { - level: "low" as const, - needsStrictSemanticPath: false, - reasonCodes: ["rule_slots_sufficient"] - }, - clarificationDecision: { - decision: "continue" as const, - triggerPath: "rule" as const, - confidenceLevel: "high" as const, - missingCriticalSlots: [], - conflictDetected: false, - reasonCodes: ["rule_slots_sufficient"], - question: "", - reason: "问题信息充足" - }, - riskTags: [], - planningWarnings: [] -}); - -const createMockSemanticPlan = () => ({ - status: "ready" as const, - semanticHints: [], - semanticVersion: 1, - lockStatus: "locked" as const, - fallbackApplied: false, - riskTags: [], - intentRiskTags: [], - semanticRiskTags: [], - planningWarnings: { - intent: [], - semantic: [] - }, - strictMode: false, - strictModeReasons: [], - summary: "stub" -}); - -describe("langgraph runtime", () => { - it("passes contextEnvelope into clarify node", async () => { - const clarifyRun = jest.fn().mockReturnValue({ - decision: "clarify", - action: "ask_clarification", - source: "rule", - decisionSource: "rule", - triggerPath: "rule", - bypassed: false, - confidence: "low", - confidenceLevel: "low", - missingSlots: ["metric"], - shouldClarify: true, - missingCriticalSlots: ["metric"], - reasonCodes: ["missing_metric_slot"], - reason: "need clarification", - question: "请补充指标口径" - }); - const runtime = createLangGraphRuntime({ - clarifyNode: { - evaluate: clarifyRun - }, - retrieveKnowledgeNode: { - run: async () => ({ - status: "ready", - snippets: ["stub"], - summary: "stub" - }) +const createBaseRun = (override: Partial = {}): SqlRun => ({ + runId: "run-v2-runtime", + sessionId: "session-v2-runtime", + question: "统计订单总数", + status: "executionResult", + provider: "volcengine", + model: "mock-model", + sql: "select count(*) as total from orders", + answer: "订单总数为 10", + rows: [{ total: 10 }], + columns: ["total"], + trace: { + runId: "run-v2-runtime", + provider: "volcengine", + retryCount: 0, + v2: { + version: "v2", + stageOrder: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + stages: [ + { stage: "intake", status: "success" }, + { stage: "retrieve", status: "success" }, + { stage: "assemble-context", status: "success" }, + { stage: "semantic-plan", status: "success" }, + { + stage: "generate-sql", + status: "success", + provider: { provider: "volcengine", model: "mock-model" } + }, + { stage: "validate", status: "success" }, + { stage: "correct", status: "skipped" }, + { stage: "execute", status: "success" }, + { stage: "answer", status: "success" } + ] + }, + steps: [ + { + node: "clarify", + status: "success", + at: "2026-04-26T00:00:00.000Z" }, - buildIntentPlanNode: { - run: async () => createMockIntentPlan() + { + node: "retrieve-knowledge", + status: "success", + at: "2026-04-26T00:00:00.100Z" }, - buildSemanticQueryNode: { - run: async () => createMockSemanticPlan() + { + node: "build-intent-plan", + status: "success", + at: "2026-04-26T00:00:00.200Z" }, - buildPhysicalPlanNode: { - run: async () => ({ - status: "ready", - strategy: "direct_sql", - semanticConstraintMode: "structured" as const, - semanticVersion: 1, - lockStatus: "locked" as const, - fallbackApplied: false, - cacheStatus: "miss" as const, - summary: "stub" - }) + { + node: "build-semantic-query", + status: "success", + at: "2026-04-26T00:00:00.300Z" }, - resolveSavedPriorSqlNode: { - run: () => ({ - status: "miss" as const, - reasonCodes: ["prior_sql_no_trusted_match"] - }) + { + node: "build-physical-plan", + status: "success", + at: "2026-04-26T00:00:00.400Z" }, - generateSqlNode: { - run: async () => ({ - provider: "mock-provider", - model: "mock-model", - sql: "SELECT 1 AS value", - explanation: "mock explanation", - rawText: "mock raw text", - prompt: { - systemPrompt: "sys", - userPrompt: "usr" - } - }) + { + node: "generate-sql", + status: "success", + at: "2026-04-26T00:00:00.500Z" }, - safetyNode: { - run: async () => ({ - allowed: true, - mode: "pass" as const, - riskLevel: "low" as const, - riskTags: [] - }) + { + node: "safety-check", + status: "success", + at: "2026-04-26T00:00:00.600Z" }, - executeNode: { - run: async () => ({ - rows: [{ value: 1 }], - columns: ["value"] - }) + { + node: "execute-sql", + status: "success", + at: "2026-04-26T00:00:00.700Z" }, - formatNode: { - run: () => "formatted" + { + node: "format-answer", + status: "success", + at: "2026-04-26T00:00:00.800Z" } + ] + }, + llmRaw: null, + createdAt: "2026-04-26T00:00:01.000Z", + ...override +}); + +describe("text2sql v2 runtime artifacts", () => { + it("maps successful trace nodes into v2 stages", () => { + const artifact = new Text2SqlV2ArtifactBuilder().buildRunArtifact(createBaseRun()); + + expect(artifact.version).toBe("v2"); + expect(artifact.stageOrder).toEqual([ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ]); + expect(artifact.stages.find((stage) => stage.stage === "generate-sql")?.status).toBe("success"); + expect(artifact.stages.find((stage) => stage.stage === "generate-sql")?.provider).toEqual({ + provider: "volcengine", + model: "mock-model" }); + expect(artifact.stages.find((stage) => stage.stage === "correct")?.status).toBe("skipped"); + expect(artifact.stages.find((stage) => stage.stage === "answer")?.status).toBe("success"); + }); - const contextEnvelope = { - metricDefinition: "订单总数" - }; - const state = createInitialLangGraphState({ - runId: "run-with-envelope", - sessionId: "session-1", - question: "这个趋势怎么样", - datasourceId: "ds-1", - contextEnvelope + it("marks correction stage success when relationship-correction runs", () => { + const run = createBaseRun({ + trace: { + ...createBaseRun().trace, + retryCount: 1, + v2: { + ...(createBaseRun().trace.v2 ?? { + version: "v2", + stageOrder: [], + stages: [] + }), + stages: + createBaseRun().trace.v2?.stages.map((stage) => + stage.stage === "correct" ? { ...stage, status: "success" } : stage + ) ?? [] + }, + steps: [ + ...createBaseRun().trace.steps, + { + node: "relationship-correction", + status: "success", + at: "2026-04-26T00:00:00.650Z", + detail: "执行错误可修正，触发 correction 迭代" + } + ] + } }); - const output = await runtime.invoke(state); - expect(clarifyRun).toHaveBeenCalledWith("这个趋势怎么样", contextEnvelope); - expect(output.terminalStatus).toBe("clarification"); - expect(output.trace.clarificationDecision?.decision).toBe("clarify"); + const artifact = new Text2SqlV2ArtifactBuilder().buildRunArtifact(run); + expect(artifact.stages.find((stage) => stage.stage === "correct")?.status).toBe("success"); }); - it("should run through executionResult path with expected node steps", async () => { - const runtime = createLangGraphRuntime({ - clarifyNode: { - evaluate: () => ({ - decision: "continue", - action: "proceed", - source: "rule", - decisionSource: "rule", - triggerPath: "rule", - bypassed: false, - confidence: "high", - confidenceLevel: "high", - missingSlots: [], - shouldClarify: false, - missingCriticalSlots: [], - reasonCodes: ["rule_slots_sufficient"], - reason: "问题信息充足", - question: "" - }) - }, - retrieveKnowledgeNode: { - run: async () => ({ - status: "ready", - snippets: ["stub"], - summary: "stub" - }) - }, - buildIntentPlanNode: { - run: async () => createMockIntentPlan() - }, - buildSemanticQueryNode: { - run: async () => createMockSemanticPlan() - }, - buildPhysicalPlanNode: { - run: async () => ({ - status: "ready", - strategy: "direct_sql", - semanticConstraintMode: "structured" as const, - semanticVersion: 1, - lockStatus: "locked" as const, - fallbackApplied: false, - cacheStatus: "miss" as const, - summary: "stub" - }) - }, - resolveSavedPriorSqlNode: { - run: () => ({ - status: "miss" as const, - reasonCodes: ["prior_sql_no_trusted_match"] - }) - }, - generateSqlNode: { - run: async () => ({ - provider: "mock-provider", - model: "mock-model", - sql: "SELECT 1 AS value", - explanation: "mock explanation", - rawText: "mock raw text", - prompt: { - systemPrompt: "sys", - userPrompt: "usr" + it("captures correction failure as correctable validation-category failure", () => { + const run = createBaseRun({ + status: "failed", + error: "unknown column foo", + trace: { + ...createBaseRun().trace, + retryCount: 2, + v2: { + ...(createBaseRun().trace.v2 ?? { + version: "v2", + stageOrder: [], + stages: [] + }), + stages: + createBaseRun().trace.v2?.stages.map((stage) => + stage.stage === "correct" + ? { + ...stage, + status: "failed", + failure: { + code: "CORRECT_FAILED", + message: "unknown column foo", + category: "validation", + terminal: true, + correctable: true + } + } + : stage + ) ?? [] + }, + steps: [ + ...createBaseRun().trace.steps, + { + node: "relationship-correction", + status: "failed", + at: "2026-04-26T00:00:00.650Z", + errorSummary: "unknown column foo" } - }) - }, - safetyNode: { - run: async () => ({ - allowed: true, - mode: "pass" as const, - riskLevel: "low" as const, - riskTags: [] - }) - }, - executeNode: { - run: async () => ({ - rows: [{ value: 1 }], - columns: ["value"] - }) - }, - formatNode: { - run: () => "formatted" + ] } }); - const state = createInitialLangGraphState({ - runId: "run-1", - sessionId: "session-1", - question: "统计订单总数", - datasourceId: "ds-1" + const artifact = new Text2SqlV2ArtifactBuilder().buildRunArtifact(run); + const correctionStage = artifact.stages.find((stage) => stage.stage === "correct"); + + expect(correctionStage?.status).toBe("failed"); + expect(correctionStage?.failure?.category).toBe("validation"); + expect(correctionStage?.failure?.correctable).toBe(true); + expect(correctionStage?.failure?.terminal).toBe(true); + }); + + it("marks clarification terminal runs without answer stage fallback", () => { + const run = createBaseRun({ + status: "clarification", + trace: { + ...createBaseRun().trace, + v2: { + version: "v2", + stageOrder: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + stages: [{ stage: "intake", status: "clarification" }] + }, + steps: [ + { + node: "clarify", + status: "success", + at: "2026-04-26T00:00:00.000Z" + } + ] + } }); - const output = await runtime.invoke(state); - expect(output.terminalStatus).toBe("executionResult"); - expect(output.provider).toBe("mock-provider"); - expect(output.llmRaw?.model).toBe("mock-model"); - expect(output.answer).toBe("formatted"); - expect(output.trace.steps.map((step) => step.node)).toEqual([ - "clarify", - "retrieve-knowledge", - "build-intent-plan", - "build-semantic-query", - "build-physical-plan", - "resolve-saved-prior-sql", + const artifact = new Text2SqlV2ArtifactBuilder().buildRunArtifact(run); + expect(artifact.stages.find((stage) => stage.stage === "intake")?.status).toBe("clarification"); + expect(artifact.stages.find((stage) => stage.stage === "answer")?.status).toBe("skipped"); + }); + + it("compiles canonical langgraph backbone with conditional routing and no legacy delegation", async () => { + const intakeNode = { + run: jest.fn().mockReturnValue({ + originalQuestion: "统计订单总数", + normalizedQuestion: "统计订单总数", + standaloneQuestion: "统计订单总数", + route: "text_to_sql", + reasonCodes: ["intake_ready_for_text_to_sql"], + confidence: 0.9, + evidenceRefs: ["chunk-orders-1"], + semanticIntent: "count" + }) + }; + const retrieveContextNode = { + run: jest.fn().mockResolvedValue({ + state: { + status: "ready", + typedSummary: { + denseState: "ready", + denseReason: undefined, + rerankState: "ready", + rerankReason: undefined, + degradeReasons: [] + }, + evidenceRefs: ["chunk-orders-1"], + selectedContextSummary: { + count: 1, + snippetPreviews: ["orders snippet"] + }, + warnings: [] + }, + artifact: { + status: "ready", + evidenceRefs: ["chunk-orders-1"], + typedSummary: { + denseState: "ready", + denseReason: undefined, + rerankState: "ready", + rerankReason: undefined, + degradeReasons: [] + }, + retrievalBundle: { + run_id: "run-v2-runtime", + datasource_id: "sqlite_main", + status: "ready", + selected_context: [{ chunk_id: "chunk-orders-1", content: "orders snippet" }], + degrade_reasons: [] + }, + contextPack: { + status: "ready", + selected_context: [{ chunk_id: "chunk-orders-1", content: "orders snippet" }], + degrade_reasons: [] + } + } + }) + }; + const assembleContextNode = { + run: jest.fn().mockReturnValue({ + contextPack: { + status: "ready", + selectedEvidenceIds: ["chunk-orders-1"], + selectedTables: ["orders"], + selectedColumns: ["orders.id"] + }, + typedSummary: { + status: "ready", + selectedEvidenceCount: 1, + selectedTableCount: 1, + selectedColumnCount: 1, + laneStateCounts: { + ready: 1, + degraded: 0, + unavailable: 0, + skipped: 0 + }, + pruningDecisionCount: 0, + permissionReasonCount: 0, + warningCount: 0 + }, + evidenceRefs: ["chunk-orders-1"] + }) + }; + const semanticPlanNode = { + run: jest.fn().mockReturnValue({ + route: "ready", + plan: { + route: "answer", + standaloneQuestion: "统计订单总数", + selectedTables: ["orders"], + selectedColumns: ["orders.id"], + confidence: 0.9, + evidenceRefs: ["chunk-orders-1"], + filters: ["route_kind:text_to_sql"] + }, + validation: { + valid: true, + lowConfidence: false, + unsupportedTables: [], + unsupportedColumns: [], + reasons: [], + routeKind: "text_to_sql", + outcome: "ready", + evidenceComplete: true, + requiresClarification: false, + shouldDirectAnswer: false, + terminal: false + } + }) + }; + const generateSqlNode = { + run: jest.fn().mockImplementation(async () => { + await new Promise((resolve) => setTimeout(resolve, 5)); + return { + draft: { + provider: "volcengine", + model: "mock-model", + sql: "SELECT COUNT(*) AS total FROM orders", + explanation: "count orders", + rawText: "SELECT COUNT(*) AS total FROM orders", + prompt: { + systemPrompt: "system", + userPrompt: "user" + } + }, + artifact: { + sql: "SELECT COUNT(*) AS total FROM orders", + assumptions: ["count orders"], + usedTables: ["orders"], + usedColumns: ["orders.id"], + evidenceRefs: ["chunk-orders-1"], + cause: "initial", + dialect: "sqlite" + } + }; + }) + }; + const validateSqlNode = { + run: jest.fn().mockResolvedValue({ + outcome: "pass", + artifact: { + status: "passed", + checks: [], + correctable: false + } + }) + }; + const correctSqlNode = { + run: jest.fn() + }; + const executeSqlNode = { + run: jest.fn().mockResolvedValue({ + rows: [{ total: 10 }], + columns: ["total"], + rowCount: 1, + emptyResult: false + }) + }; + const answerNode = { + run: jest.fn().mockReturnValue({ + mode: "execution_result", + answer: "订单总数为 10", + status: "executionResult", + evidenceRefs: ["chunk-orders-1"], + warnings: [] + }) + }; + + const graph = createText2SqlV2LangGraph({ + intakeNode: intakeNode as never, + retrieveContextNode: retrieveContextNode as never, + assembleContextNode: assembleContextNode as never, + semanticPlanNode: semanticPlanNode as never, + generateSqlNode: generateSqlNode as never, + validateSqlNode: validateSqlNode as never, + correctSqlNode: correctSqlNode as never, + executeSqlNode: executeSqlNode as never, + answerNode: answerNode as never, + resolveSqlTools: jest.fn().mockReturnValue({}) + }); + const streamedSteps: Array<{ + node: string; + lifecycle?: "running" | "completed" | "failed" | "skipped"; + outputSummary?: string; + startedAt?: string; + endedAt?: string; + durationMs?: number; + }> = []; + const finalState = await graph.invoke( + createText2SqlV2LangGraphInitialState({ + preparedRun: { + runId: "run-v2-runtime", + requestId: "req-v2-runtime", + question: "统计订单总数", + session: { + id: "session-v2-runtime", + datasource: "sqlite_main", + modelProvider: "volcengine", + modelName: "mock-model" + }, + datasource: { + id: "sqlite_main", + type: "sqlite" + }, + sqlAccessContext: undefined, + contextEnvelope: undefined, + userPersistResult: { + primaryPersisted: true + } + } as never, + route: "/api/v1/sessions/:sessionId/messages", + streamMode: true, + streamOptions: { + onStep: ({ step }) => { + streamedSteps.push({ + node: step.node, + lifecycle: step.lifecycle, + outputSummary: step.outputSummary, + startedAt: step.startedAt, + endedAt: step.endedAt, + durationMs: step.durationMs + }); + } + } + }) + ); + + expect(finalState.stageProgress).toEqual([ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "execute", + "answer" + ]); + expect(finalState.answerResult?.status).toBe("executionResult"); + expect(correctSqlNode.run).not.toHaveBeenCalled(); + expect(generateSqlNode.run).toHaveBeenCalledTimes(1); + expect( + streamedSteps.filter((step) => step.lifecycle === "running").map((step) => step.node) + ).toEqual([ + "intake", + "retrieve-context", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate-sql", + "execute-sql", + "answer" + ]); + expect( + streamedSteps + .filter((step) => step.lifecycle === "completed") + .map((step) => step.node) + ).toEqual([ + "intake", + "retrieve-context", + "assemble-context", + "semantic-plan", "generate-sql", - "safety-check", + "validate-sql", "execute-sql", - "format-answer" + "answer" ]); - expect(output.trace.steps[0]?.sequence).toBe(1); - expect(output.trace.steps[0]?.stepId).toBe("run-1:clarify:1"); - expect(output.trace.steps[0]?.lifecycle).toBe("skipped"); - expect(output.trace.steps[6]?.sequence).toBe(7); - expect(output.trace.steps[6]?.lifecycle).toBe("completed"); - expect(output.trace.clarificationDecision?.decision).toBe("continue"); + expect( + streamedSteps + .filter((step) => step.lifecycle === "skipped") + .map((step) => step.node) + ).toEqual(["correct-sql"]); + expect( + streamedSteps.some((step) => + step.outputSummary?.includes('"status":"running"') + ) + ).toBe(true); + const generateRunningStep = streamedSteps.find( + (step) => step.node === "generate-sql" && step.lifecycle === "running" + ); + const generateCompletedStep = streamedSteps.find( + (step) => step.node === "generate-sql" && step.lifecycle === "completed" + ); + const generateStage = finalState.stageArtifacts.find( + (stage) => stage.stage === "generate-sql" + ); + expect(generateRunningStep?.startedAt).toBeDefined(); + expect(generateRunningStep?.endedAt).toBeUndefined(); + expect(generateRunningStep?.durationMs).toBeUndefined(); + expect(generateCompletedStep?.startedAt).toBe(generateRunningStep?.startedAt); + expect(generateCompletedStep?.endedAt).toBeDefined(); + expect(generateCompletedStep?.durationMs).toBeGreaterThanOrEqual(1); + expect(generateStage?.startedAt).toBe(generateRunningStep?.startedAt); + expect(generateStage?.endedAt).toBe(generateCompletedStep?.endedAt); + expect(generateStage?.durationMs).toBe(generateCompletedStep?.durationMs); + const artifact = new Text2SqlV2LangGraphResultMapper( + new Text2SqlV2ArtifactBuilder() + ).mapRunArtifact(finalState as never); + expect( + artifact.runtimePlan?.items.find((item) => item.stage === "generate-sql") + ).toMatchObject({ + status: "completed" + }); + expect( + artifact.runtimePlan?.items.find((item) => item.stage === "correct") + ).toMatchObject({ + status: "skipped", + reasonCodes: ["validation_passed"] + }); }); - it("should normalize missing trace context", () => { - expect(normalizeTraceContext(undefined)).toEqual({ - source: "chat", - route: "unknown" + it("routes metadata intent through retrieve/assemble/semantic-plan and skips SQL stages", async () => { + const intakeNode = { + run: jest.fn().mockReturnValue({ + originalQuestion: "数据库有哪些表", + normalizedQuestion: "数据库有哪些表", + standaloneQuestion: "数据库有哪些表", + route: "metadata", + reasonCodes: ["intake_metadata_detected"], + confidence: 0.95, + evidenceRefs: ["chunk-schema-orders"], + semanticIntent: "metadata", + directAnswer: + "这是元数据问题，我会基于可访问的表结构与语义证据直接说明，不执行 SQL。" + }) + }; + const retrieveContextNode = { + run: jest.fn().mockResolvedValue({ + state: { + status: "ready", + typedSummary: { + denseState: "ready", + denseReason: undefined, + rerankState: "ready", + rerankReason: undefined, + degradeReasons: [] + }, + evidenceRefs: ["chunk-schema-orders"], + selectedContextSummary: { + count: 1, + snippetPreviews: ["orders table schema"] + }, + warnings: [] + }, + artifact: { + status: "ready", + evidenceRefs: ["chunk-schema-orders"], + typedSummary: { + denseState: "ready", + denseReason: undefined, + rerankState: "ready", + rerankReason: undefined, + degradeReasons: [] + }, + retrievalBundle: { + run_id: "run-v2-runtime", + datasource_id: "sqlite_main", + status: "ready", + selected_context: [ + { + chunk_id: "chunk-schema-orders", + content: "orders(id, amount, status)" + } + ], + degrade_reasons: [] + }, + contextPack: { + status: "ready", + selected_context: [ + { + chunk_id: "chunk-schema-orders", + content: "orders(id, amount, status)" + } + ], + degrade_reasons: [] + } + } + }) + }; + const assembleContextNode = { + run: jest.fn().mockReturnValue({ + contextPack: { + status: "ready", + selectedEvidenceIds: ["chunk-schema-orders"], + selectedTables: ["orders"], + selectedColumns: ["orders.id", "orders.amount"] + }, + typedSummary: { + status: "ready", + selectedEvidenceCount: 1, + selectedTableCount: 1, + selectedColumnCount: 2, + laneStateCounts: { + ready: 1, + degraded: 0, + unavailable: 0, + skipped: 0 + }, + pruningDecisionCount: 0, + permissionReasonCount: 0, + warningCount: 0 + }, + evidenceRefs: ["chunk-schema-orders"] + }) + }; + const semanticPlanNode = { + run: jest.fn().mockReturnValue({ + route: "direct_answer", + plan: { + route: "answer", + standaloneQuestion: "数据库有哪些表", + selectedTables: ["orders"], + selectedColumns: ["orders.id", "orders.amount"], + confidence: 0.88, + evidenceRefs: ["chunk-schema-orders"], + filters: ["route_kind:metadata"] + }, + validation: { + valid: true, + lowConfidence: false, + unsupportedTables: [], + unsupportedColumns: [], + reasons: [], + routeKind: "metadata", + outcome: "direct_answer", + evidenceComplete: true, + requiresClarification: false, + shouldDirectAnswer: true, + terminal: false + } + }) + }; + const generateSqlNode = { + run: jest.fn() + }; + const validateSqlNode = { + run: jest.fn() + }; + const correctSqlNode = { + run: jest.fn() + }; + const executeSqlNode = { + run: jest.fn() + }; + const answerNode = { + run: jest.fn().mockReturnValue({ + mode: "direct_answer", + answer: "orders 表包含 id、amount、status 字段。", + status: "executionResult", + evidenceRefs: ["chunk-schema-orders"], + warnings: [] + }) + }; + + const graph = createText2SqlV2LangGraph({ + intakeNode: intakeNode as never, + retrieveContextNode: retrieveContextNode as never, + assembleContextNode: assembleContextNode as never, + semanticPlanNode: semanticPlanNode as never, + generateSqlNode: generateSqlNode as never, + validateSqlNode: validateSqlNode as never, + correctSqlNode: correctSqlNode as never, + executeSqlNode: executeSqlNode as never, + answerNode: answerNode as never, + resolveSqlTools: jest.fn().mockReturnValue({}) }); + const finalState = await graph.invoke( + createText2SqlV2LangGraphInitialState({ + preparedRun: { + runId: "run-v2-runtime", + requestId: "req-v2-runtime", + question: "数据库有哪些表", + session: { + id: "session-v2-runtime", + datasource: "sqlite_main", + modelProvider: "volcengine", + modelName: "mock-model" + }, + datasource: { + id: "sqlite_main", + type: "sqlite" + }, + sqlAccessContext: undefined, + contextEnvelope: undefined, + userPersistResult: { + primaryPersisted: true + } + } as never, + route: "/api/v1/sessions/:sessionId/messages", + streamMode: false + }) + ); + + expect(finalState.stageProgress).toEqual([ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "answer" + ]); + expect(generateSqlNode.run).not.toHaveBeenCalled(); + expect(validateSqlNode.run).not.toHaveBeenCalled(); + expect(executeSqlNode.run).not.toHaveBeenCalled(); + expect(answerNode.run).toHaveBeenCalledTimes(1); + const artifact = new Text2SqlV2LangGraphResultMapper( + new Text2SqlV2ArtifactBuilder() + ).mapRunArtifact(finalState as never); + for (const stage of ["generate-sql", "validate", "correct", "execute"] as const) { + expect(artifact.runtimePlan?.items.find((item) => item.stage === stage)).toMatchObject({ + status: "skipped", + reasonCodes: expect.arrayContaining(["metadata_no_sql"]) + }); + } }); - it("should capture fatal llm error into state without throwing from runtime", async () => { - const runtime = createLangGraphRuntime({ - clarifyNode: { - evaluate: () => ({ - decision: "continue", - action: "proceed", - source: "rule", - decisionSource: "rule", - triggerPath: "rule", - bypassed: false, - confidence: "high", - confidenceLevel: "high", - missingSlots: [], - shouldClarify: false, - missingCriticalSlots: [], - reasonCodes: ["rule_slots_sufficient"], - reason: "问题信息充足", - question: "" - }) - }, - retrieveKnowledgeNode: { - run: async () => ({ + it("passes correction grounding into second generation attempt after correctable validation", async () => { + const intakeNode = { + run: jest.fn().mockReturnValue({ + originalQuestion: "统计订单总数", + normalizedQuestion: "统计订单总数", + standaloneQuestion: "统计订单总数", + route: "text_to_sql", + reasonCodes: ["intake_ready_for_text_to_sql"], + confidence: 0.9, + evidenceRefs: ["chunk-orders-1"], + semanticIntent: "count" + }) + }; + const retrieveContextNode = { + run: jest.fn().mockResolvedValue({ + state: { status: "ready", - snippets: ["stub"], - summary: "stub" - }) - }, - buildIntentPlanNode: { - run: async () => createMockIntentPlan() - }, - buildSemanticQueryNode: { - run: async () => createMockSemanticPlan() - }, - buildPhysicalPlanNode: { - run: async () => ({ + typedSummary: { + denseState: "ready", + denseReason: undefined, + rerankState: "ready", + rerankReason: undefined, + degradeReasons: [] + }, + evidenceRefs: ["chunk-orders-1"], + selectedContextSummary: { + count: 1, + snippetPreviews: ["orders snippet"] + }, + warnings: [] + }, + artifact: { status: "ready", - strategy: "direct_sql", - semanticConstraintMode: "structured" as const, - semanticVersion: 1, - lockStatus: "locked" as const, - fallbackApplied: false, - cacheStatus: "miss" as const, - summary: "stub" + evidenceRefs: ["chunk-orders-1"], + typedSummary: { + denseState: "ready", + denseReason: undefined, + rerankState: "ready", + rerankReason: undefined, + degradeReasons: [] + }, + retrievalBundle: { + run_id: "run-v2-runtime", + datasource_id: "sqlite_main", + status: "ready", + selected_context: [{ chunk_id: "chunk-orders-1", content: "orders snippet" }], + degrade_reasons: [] + }, + contextPack: { + status: "ready", + selected_context: [{ chunk_id: "chunk-orders-1", content: "orders snippet" }], + degrade_reasons: [] + } + } + }) + }; + const assembleContextNode = { + run: jest.fn().mockReturnValue({ + contextPack: { + status: "ready", + selectedEvidenceIds: ["chunk-orders-1"], + selectedTables: ["orders"], + selectedColumns: ["orders.id"] + }, + typedSummary: { + status: "ready", + selectedEvidenceCount: 1, + selectedTableCount: 1, + selectedColumnCount: 1, + laneStateCounts: { + ready: 1, + degraded: 0, + unavailable: 0, + skipped: 0 + }, + pruningDecisionCount: 0, + permissionReasonCount: 0, + warningCount: 0 + }, + evidenceRefs: ["chunk-orders-1"] + }) + }; + const semanticPlanNode = { + run: jest.fn().mockReturnValue({ + route: "ready", + plan: { + route: "answer", + standaloneQuestion: "统计订单总数", + selectedTables: ["orders"], + selectedColumns: ["orders.id"], + confidence: 0.9, + evidenceRefs: ["chunk-orders-1"], + snapshotId: "semantic-plan-1", + filters: ["route_kind:text_to_sql"] + }, + validation: { + valid: true, + lowConfidence: false, + unsupportedTables: [], + unsupportedColumns: [], + reasons: [], + routeKind: "text_to_sql", + outcome: "ready", + evidenceComplete: true, + requiresClarification: false, + shouldDirectAnswer: false, + terminal: false + } + }) + }; + const generateSqlNode = { + run: jest + .fn() + .mockResolvedValueOnce({ + draft: { + provider: "volcengine", + model: "mock-model", + sql: "SELECT missing_city FROM orders", + explanation: "initial attempt", + rawText: "SELECT missing_city FROM orders", + prompt: { + systemPrompt: "system", + userPrompt: "user" + } + }, + artifact: { + sql: "SELECT missing_city FROM orders", + assumptions: ["initial attempt"], + usedTables: ["orders"], + usedColumns: ["orders.missing_city"], + evidenceRefs: ["chunk-orders-1"], + cause: "initial", + dialect: "sqlite" + } }) - }, - resolveSavedPriorSqlNode: { - run: () => ({ - status: "miss" as const, - reasonCodes: ["prior_sql_no_trusted_match"] + .mockResolvedValueOnce({ + draft: { + provider: "volcengine", + model: "mock-model", + sql: "SELECT orders.id FROM orders", + explanation: "retry attempt", + rawText: "SELECT orders.id FROM orders", + prompt: { + systemPrompt: "system", + userPrompt: "user" + } + }, + artifact: { + sql: "SELECT orders.id FROM orders", + assumptions: ["retry attempt"], + usedTables: ["orders"], + usedColumns: ["orders.id"], + evidenceRefs: ["chunk-orders-1"], + cause: "correction", + dialect: "sqlite" + } }) - }, - generateSqlNode: { - run: async () => { - throw new Error("llm failed"); - } - }, - safetyNode: { - run: async () => ({ - allowed: true, - mode: "pass" as const, - riskLevel: "low" as const, - riskTags: [] + }; + const validateSqlNode = { + run: jest + .fn() + .mockResolvedValueOnce({ + outcome: "correctable", + artifact: { + status: "failed", + checks: [], + correctable: true, + failure: { + code: "SQL_MISSING_COLUMN", + message: "missing column orders.missing_city", + category: "validation", + terminal: false, + correctable: true + } + } }) - }, - executeNode: { - run: async () => ({ - rows: [], - columns: [] + .mockResolvedValueOnce({ + outcome: "pass", + artifact: { + status: "passed", + checks: [], + correctable: false + } }) - }, - formatNode: { - run: () => "formatted" - } - }); + }; + const correctSqlNode = { + run: jest.fn().mockReturnValue({ + outcome: "retry_generation", + budget: { + attemptCount: 1, + maxAttempts: 2, + remainingAttempts: 1, + exhausted: false + }, + artifact: { + failedSql: "SELECT missing_city FROM orders", + retryReason: "missing column orders.missing_city", + category: "validation", + source: "validation", + failureCode: "SQL_MISSING_COLUMN", + attemptCount: 1, + maxAttempts: 2, + semanticPlanSnapshotId: "semantic-plan-1", + evidenceRefs: ["chunk-orders-1"], + shouldRevalidate: true, + grounding: { + failedSqlRef: "sql.sha256.abc123abc123abcd", + retryReason: "missing column orders.missing_city", + failureCode: "SQL_MISSING_COLUMN", + failureCategory: "validation", + source: "validation", + attemptCount: 1, + maxAttempts: 2, + evidenceRefs: ["chunk-orders-1"], + semanticPlanSnapshotId: "semantic-plan-1", + semanticPlanRoute: "answer", + semanticPlanRouteKind: "text_to_sql", + selectedTableCount: 1, + selectedColumnCount: 1, + contextPackStatus: "ready", + contextPackEvidenceCount: 1 + } + } + }) + }; + const executeSqlNode = { + run: jest.fn().mockResolvedValue({ + rows: [{ total: 10 }], + columns: ["total"], + rowCount: 1, + emptyResult: false + }) + }; + const answerNode = { + run: jest.fn().mockReturnValue({ + mode: "execution_result", + answer: "订单总数为 10", + status: "executionResult", + evidenceRefs: ["chunk-orders-1"], + warnings: [] + }) + }; - const state = createInitialLangGraphState({ - runId: "run-2", - sessionId: "session-2", - question: "统计异常", - datasourceId: "ds-2" + const graph = createText2SqlV2LangGraph({ + intakeNode: intakeNode as never, + retrieveContextNode: retrieveContextNode as never, + assembleContextNode: assembleContextNode as never, + semanticPlanNode: semanticPlanNode as never, + generateSqlNode: generateSqlNode as never, + validateSqlNode: validateSqlNode as never, + correctSqlNode: correctSqlNode as never, + executeSqlNode: executeSqlNode as never, + answerNode: answerNode as never, + resolveSqlTools: jest.fn().mockReturnValue({}) }); - const output = await runtime.invoke(state); + const finalState = await graph.invoke( + createText2SqlV2LangGraphInitialState({ + preparedRun: { + runId: "run-v2-runtime", + requestId: "req-v2-runtime", + question: "统计订单总数", + session: { + id: "session-v2-runtime", + datasource: "sqlite_main", + modelProvider: "volcengine", + modelName: "mock-model" + }, + datasource: { + id: "sqlite_main", + type: "sqlite" + }, + sqlAccessContext: undefined, + contextEnvelope: undefined, + userPersistResult: { + primaryPersisted: true + } + } as never, + route: "/api/v1/sessions/:sessionId/messages", + streamMode: false + }) + ); - expect(output.terminalStatus).toBe("failed"); - expect(output.error).toBe("llm failed"); - expect(output.fatalError).toBeInstanceOf(Error); - expect(output.trace.steps.map((step) => step.node)).toEqual([ - "clarify", - "retrieve-knowledge", - "build-intent-plan", - "build-semantic-query", - "build-physical-plan", - "resolve-saved-prior-sql", - "generate-sql" - ]); - expect(output.trace.steps[6]?.status).toBe("failed"); - expect(output.trace.steps[6]?.sequence).toBe(7); - expect(output.trace.steps[6]?.stepId).toBe("run-2:generate-sql:7"); - expect(output.trace.steps[6]?.lifecycle).toBe("failed"); - expect(output.trace.steps[6]?.errorSummary).toContain("llm failed"); + expect(generateSqlNode.run).toHaveBeenCalledTimes(2); + expect(generateSqlNode.run).toHaveBeenNthCalledWith( + 2, + expect.objectContaining({ + cause: "correction", + retryReason: "missing column orders.missing_city", + correctionGrounding: expect.objectContaining({ + failedSqlRef: "sql.sha256.abc123abc123abcd", + attemptCount: 1, + maxAttempts: 2, + failureCode: "SQL_MISSING_COLUMN" + }) + }) + ); + expect(finalState.answerResult?.status).toBe("executionResult"); + expect( + finalState.runtimePlan?.items.find((item) => item.stage === "correct") + ).toMatchObject({ + status: "completed", + correctionIntent: { + failedStage: "validate", + failureCode: "SQL_MISSING_COLUMN", + retryReason: "missing column orders.missing_city", + targetStage: "generate-sql" + } + }); }); }); diff --git a/apps/backend/test/unit/llm-gateway.service.spec.ts b/apps/backend/test/unit/llm-gateway.service.spec.ts index a48efad..89e3369 100644 --- a/apps/backend/test/unit/llm-gateway.service.spec.ts +++ b/apps/backend/test/unit/llm-gateway.service.spec.ts @@ -255,6 +255,55 @@ describe("LlmGatewayService", () => { expect(mockedGenerateText).toHaveBeenCalledTimes(1); }); + it("should recover with successful tool SQL when provider stream breaks after tool result", async () => { + mockedStreamText.mockReturnValue({ + fullStream: (async function* () { + yield { + type: "tool-call", + toolName: "runReadOnlySql", + toolCallId: "tool-4", + input: { + sql: "SELECT method, COUNT(*) AS payment_count FROM payments GROUP BY method" + } + }; + yield { + type: "tool-result", + toolName: "runReadOnlySql", + toolCallId: "tool-4", + output: { rowCount: 3 } + }; + throw new Error("Invalid JSON response"); + })(), + text: Promise.resolve("") + } as unknown as ReturnType); + + const events: string[] = []; + const service = new LlmGatewayService( + { + llmMockMode: false + } as AppConfigService, + new LlmModelFactory() + ); + + const output = await service.stream( + { + systemPrompt: "sys", + userPrompt: "统计支付方式占比" + }, + runtime, + { + onEvent: (event) => { + events.push(event.type); + } + } + ); + + expect(output.rawText).toContain("SELECT method"); + expect(output.rawText).toContain("GROUP BY method"); + expect(events).toEqual(["tool-call", "tool-result", "text-delta"]); + expect(mockedGenerateText).not.toHaveBeenCalled(); + }); + it("should fail fast when tool execution returns error", async () => { mockedStreamText.mockReturnValue({ fullStream: (async function* () { diff --git a/apps/backend/test/unit/provider-router.rerank.spec.ts b/apps/backend/test/unit/provider-router.rerank.spec.ts new file mode 100644 index 0000000..f3d9733 --- /dev/null +++ b/apps/backend/test/unit/provider-router.rerank.spec.ts @@ -0,0 +1,101 @@ +import { DomainError } from "../../src/common/domain-error"; +import { ProviderRouterService } from "../../src/modules/llm/provider-router.service"; + +describe("ProviderRouterService rerank", () => { + const createService = (overrides?: { + llmMockMode?: boolean; + generateRawText?: string; + }): ProviderRouterService => { + const llmMockMode = overrides?.llmMockMode ?? false; + const config = { + llmMockMode, + llmProvider: "openai", + llmModel: "gpt-4.1-mini", + llmBaseUrl: "https://api.openai.com/v1", + llmApiKey: "test-key", + llmTimeoutMs: 5_000, + llmStreamTimeoutMs: 10_000 + }; + const providerCatalog = { + resolveRuntimeByModelId: jest.fn(), + resolveDefaultModel: jest.fn().mockRejectedValue(new Error("missing-catalog")), + resolveRuntimeConfig: jest.fn() + }; + const llmGateway = { + generate: jest.fn().mockResolvedValue({ + provider: "openai", + model: "gpt-4.1-mini", + rawText: + overrides?.generateRawText ?? + JSON.stringify({ + reranked: [ + { + candidateId: "chunk-1", + score: 0.91, + reason: "high semantic match" + } + ] + }) + }), + stream: jest.fn() + }; + + return new ProviderRouterService(config as never, providerCatalog as never, llmGateway as never); + }; + + const rerankInput = { + query: "orders amount", + candidates: [ + { + candidateId: "chunk-1", + content: "table orders(id, amount)", + domain: "schema", + sourceLane: "lexical", + evidence: ["token:orders"], + baseScore: 0.7 + } + ] + }; + + it("returns provider metadata on successful non-mock rerank", async () => { + const service = createService({ llmMockMode: false }); + + const response = await service.rerankCandidatesWithMetadata(rerankInput); + + expect(response.results).toHaveLength(1); + expect(response.metadata.mode).toBe("provider"); + expect(response.metadata.provider).toBe("openai"); + expect(response.metadata.model).toBe("gpt-4.1-mini"); + expect(response.metadata.inputCount).toBe(1); + expect(response.metadata.outputCount).toBe(1); + }); + + it("does not silently fallback to mock mode when provider payload is invalid", async () => { + const service = createService({ + llmMockMode: false, + generateRawText: "rerank response unavailable" + }); + + await expect(service.rerankCandidatesWithMetadata(rerankInput)).rejects.toMatchObject< + Partial + >({ + code: "RERANK_PROVIDER_INVALID_PAYLOAD" + }); + await expect(service.rerankCandidates(rerankInput)).rejects.toMatchObject< + Partial + >({ + code: "RERANK_PROVIDER_INVALID_PAYLOAD" + }); + }); + + it("uses deterministic mock rerank only in explicit llm mock mode", async () => { + const service = createService({ llmMockMode: true }); + + const response = await service.rerankCandidatesWithMetadata(rerankInput); + + expect(response.results).toHaveLength(1); + expect(response.results[0]?.reason).toContain("mock rerank"); + expect(response.metadata.mode).toBe("mock"); + expect(response.metadata.fallbackReason).toBe("llm_mock_mode"); + }); +}); diff --git a/apps/backend/test/unit/rag-event-consumer.spec.ts b/apps/backend/test/unit/rag-event-consumer.spec.ts index 41521a7..803fc10 100644 --- a/apps/backend/test/unit/rag-event-consumer.spec.ts +++ b/apps/backend/test/unit/rag-event-consumer.spec.ts @@ -12,7 +12,7 @@ describe("RagEventConsumerService", () => { status: "active", entryCount: 2, archivedChannels: ["lexical", "dense"], - denseMode: "placeholder_vector_string" + denseMode: "mock_provider" }) }; const replayRepository: Pick = { diff --git a/apps/backend/test/unit/rag-rerank.service.spec.ts b/apps/backend/test/unit/rag-rerank.service.spec.ts index 7a00c6e..62ba3c4 100644 --- a/apps/backend/test/unit/rag-rerank.service.spec.ts +++ b/apps/backend/test/unit/rag-rerank.service.spec.ts @@ -1,4 +1,5 @@ import { RagRerankService } from "../../src/modules/rag/rerank/rag-rerank.service"; +import { DomainError } from "../../src/common/domain-error"; import type { ModelRerankerAdapter } from "../../src/modules/rag/rerank/model-reranker.adapter"; import type { RagReplayRepository } from "../../src/modules/rag/observability/rag-replay.repository"; import type { RagRetrievalBundle } from "../../src/modules/rag/retrieval/rag-retrieval.types"; @@ -85,7 +86,7 @@ const createBundle = (): RagRetrievalBundle => ({ describe("rag rerank service", () => { function createService( - adapter: Pick, + adapter: Pick, replay: Pick ): RagRerankService { return new RagRerankService( @@ -101,8 +102,15 @@ describe("rag rerank service", () => { } it("skips secondary rerank when candidate count is below threshold", async () => { - const adapter: Pick = { - rerank: jest.fn().mockResolvedValue([]) + const adapter: Pick = { + rerankWithMetadata: jest.fn().mockResolvedValue({ + results: [], + metadata: { + mode: "mock", + inputCount: 0, + outputCount: 0 + } + }) }; const replay: Pick = { writeReplay: jest.fn().mockResolvedValue(undefined) @@ -115,7 +123,7 @@ describe("rag rerank service", () => { secondaryMinCandidates: 10 }); - expect(adapter.rerank).not.toHaveBeenCalled(); + expect(adapter.rerankWithMetadata).not.toHaveBeenCalled(); expect(response.retrieval_bundle.reranked?.length).toBe(2); expect(response.retrieval_bundle.degrade_reasons).toEqual( expect.arrayContaining(["secondary_rerank_skipped_low_candidates"]) @@ -123,8 +131,8 @@ describe("rag rerank service", () => { }); it("falls back to primary ranking when secondary rerank fails", async () => { - const adapter: Pick = { - rerank: jest.fn().mockRejectedValue(new Error("secondary_model_unavailable")) + const adapter: Pick = { + rerankWithMetadata: jest.fn().mockRejectedValue(new Error("secondary_model_unavailable")) }; const replay: Pick = { writeReplay: jest.fn().mockResolvedValue(undefined) @@ -137,29 +145,157 @@ describe("rag rerank service", () => { secondaryMinCandidates: 2 }); - expect(adapter.rerank).toHaveBeenCalledTimes(1); + expect(adapter.rerankWithMetadata).toHaveBeenCalledTimes(1); expect(response.retrieval_bundle.reranked?.every((item) => item.secondary_score === undefined)).toBe( true ); expect(response.retrieval_bundle.degrade_reasons).toEqual( - expect.arrayContaining(["secondary_model_unavailable"]) + expect.arrayContaining(["secondary_rerank_unavailable_secondary_model_unavailable"]) + ); + expect(response.retrieval_bundle.rerank_metadata?.secondary.unavailable_reason).toBe( + "secondary_rerank_unavailable_secondary_model_unavailable" ); }); - it("applies secondary scores when model rerank succeeds", async () => { - const adapter: Pick = { - rerank: jest.fn().mockResolvedValue([ - { - candidateId: "chunk-a", - score: 0.2, - reason: "less relevant" - }, + it.each([ + { + label: "timeout", + error: new Error("secondary_rerank_timeout"), + reason: "secondary_rerank_timeout" + }, + { + label: "provider missing", + error: new DomainError("LLM_CONFIG_MISSING", "rerank config missing", 503), + reason: "secondary_rerank_unavailable_provider_config_missing" + }, + { + label: "invalid payload", + error: new DomainError( + "RERANK_PROVIDER_INVALID_PAYLOAD", + "provider returned invalid payload", + 502, { - candidateId: "chunk-b", - score: 0.95, - reason: "strong semantic match" + provider: "openai", + model: "gpt-4.1-mini" + } + ), + reason: "secondary_rerank_unavailable_invalid_payload" + } + ])("records deterministic fallback metadata for $label", async ({ error, reason }) => { + const adapter: Pick = { + rerankWithMetadata: jest.fn().mockRejectedValue(error) + }; + const replay: Pick = { + writeReplay: jest.fn().mockResolvedValue(undefined) + }; + const service = createService(adapter, replay); + + const response = await service.rerank({ + retrievalBundle: createBundle(), + secondaryMinCandidates: 2 + }); + + expect(response.retrieval_bundle.status).toBe("degraded"); + expect(response.retrieval_bundle.degrade_reasons).toEqual( + expect.arrayContaining([reason]) + ); + expect(response.retrieval_bundle.rerank_metadata?.secondary).toMatchObject({ + status: "degraded", + unavailable_reason: reason, + inputCount: 2, + outputCount: 0, + evidenceIds: ["chunk-a", "chunk-b"] + }); + + const secondaryReplayCall = (replay.writeReplay as jest.Mock).mock.calls + .map(([payload]) => payload) + .find((payload) => payload.replayKey === "rerank:secondary"); + expect(secondaryReplayCall?.payload).toMatchObject({ + status: "degraded", + reason, + metadata: { + status: "degraded", + unavailableReason: reason + } + }); + }); + + it("treats secondary output count mismatch as unavailable and keeps primary ordering", async () => { + const adapter: Pick = { + rerankWithMetadata: jest.fn().mockResolvedValue({ + results: [ + { + candidateId: "chunk-a", + score: 0.99, + reason: "only one result returned" + } + ], + metadata: { + mode: "provider", + provider: "openai", + model: "gpt-4.1-mini", + inputCount: 2, + outputCount: 1 + } + }) + }; + const replay: Pick = { + writeReplay: jest.fn().mockResolvedValue(undefined) + }; + const service = createService(adapter, replay); + + const response = await service.rerank({ + retrievalBundle: createBundle(), + secondaryMinCandidates: 2 + }); + + expect(response.retrieval_bundle.degrade_reasons).toEqual( + expect.arrayContaining([ + "secondary_rerank_unavailable_rerank_provider_output_candidate_mismatch" + ]) + ); + expect(response.retrieval_bundle.reranked?.[0]?.chunk_id).toBe("chunk-a"); + expect(response.retrieval_bundle.reranked?.every((item) => item.secondary_score === undefined)).toBe( + true + ); + const contextPack = response.retrieval_bundle.context_pack as + | { + lane_metadata?: Array<{ lane?: string; state?: string }>; } + | undefined; + expect(contextPack?.lane_metadata).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + lane: "rerank", + state: "unavailable" + }) ]) + ); + }); + + it("applies secondary scores when model rerank succeeds", async () => { + const adapter: Pick = { + rerankWithMetadata: jest.fn().mockResolvedValue({ + results: [ + { + candidateId: "chunk-a", + score: 0.2, + reason: "less relevant" + }, + { + candidateId: "chunk-b", + score: 0.95, + reason: "strong semantic match" + } + ], + metadata: { + mode: "provider", + provider: "openai", + model: "gpt-4.1-mini", + inputCount: 2, + outputCount: 2 + }, + }) }; const replay: Pick = { writeReplay: jest.fn().mockResolvedValue(undefined) @@ -172,14 +308,23 @@ describe("rag rerank service", () => { secondaryMinCandidates: 2 }); - expect(adapter.rerank).toHaveBeenCalledTimes(1); + expect(adapter.rerankWithMetadata).toHaveBeenCalledTimes(1); expect(response.retrieval_bundle.reranked?.[0]?.chunk_id).toBe("chunk-b"); expect(response.retrieval_bundle.reranked?.[0]?.secondary_score).toBeCloseTo(0.95); + expect(response.retrieval_bundle.rerank_metadata?.secondary.provider).toBe("openai"); + expect(response.retrieval_bundle.rerank_metadata?.secondary.model).toBe("gpt-4.1-mini"); }); it("keeps retrieval column pruning evidence visible in rerank replay payload", async () => { - const adapter: Pick = { - rerank: jest.fn().mockResolvedValue([]) + const adapter: Pick = { + rerankWithMetadata: jest.fn().mockResolvedValue({ + results: [], + metadata: { + mode: "mock", + inputCount: 0, + outputCount: 0 + } + }) }; const replay: Pick = { writeReplay: jest.fn().mockResolvedValue(undefined) diff --git a/apps/backend/test/unit/rag-task-config.repository.spec.ts b/apps/backend/test/unit/rag-task-config.repository.spec.ts new file mode 100644 index 0000000..138d011 --- /dev/null +++ b/apps/backend/test/unit/rag-task-config.repository.spec.ts @@ -0,0 +1,59 @@ +import { AppConfigService } from "../../src/modules/config/app-config.service"; +import { RagTaskConfigRepository } from "../../src/modules/data/persistence/rag-task-config.repository"; + +function createRepository(): RagTaskConfigRepository { + return new RagTaskConfigRepository({ + databaseUrl: "" + } as AppConfigService); +} + +describe("RagTaskConfigRepository", () => { + it("keeps the stored api key when the runtime target is unchanged", async () => { + const repository = createRepository(); + + await repository.upsertConfig({ + taskType: "embedding", + provider: "openai", + model: "text-embedding-3-small", + baseUrl: "https://api.openai.com/v1", + apiKeyCiphertext: "secret-embedding-key", + apiKeyMasked: "secr***-key" + }); + + const updated = await repository.upsertConfig({ + taskType: "embedding", + provider: "openai", + model: "text-embedding-3-small", + baseUrl: "https://api.openai.com/v1", + timeoutMs: 5000 + }); + + expect(updated.hasApiKey).toBe(true); + expect(updated.apiKeyMasked).toBe("secr***-key"); + await expect(repository.getApiKey("embedding")).resolves.toBe("secret-embedding-key"); + }); + + it("clears the stored api key when the runtime target changes without a replacement key", async () => { + const repository = createRepository(); + + await repository.upsertConfig({ + taskType: "embedding", + provider: "openai", + model: "text-embedding-3-small", + baseUrl: "https://api.openai.com/v1", + apiKeyCiphertext: "secret-embedding-key", + apiKeyMasked: "secr***-key" + }); + + const updated = await repository.upsertConfig({ + taskType: "embedding", + provider: "openai", + model: "text-embedding-3-small", + baseUrl: "https://example-proxy.invalid/v1" + }); + + expect(updated.hasApiKey).toBe(false); + expect(updated.apiKeyMasked).toBeNull(); + await expect(repository.getApiKey("embedding")).resolves.toBeUndefined(); + }); +}); diff --git a/apps/backend/test/unit/rag-task-health-probe.service.spec.ts b/apps/backend/test/unit/rag-task-health-probe.service.spec.ts new file mode 100644 index 0000000..736b4e5 --- /dev/null +++ b/apps/backend/test/unit/rag-task-health-probe.service.spec.ts @@ -0,0 +1,92 @@ +import type { ConfigService } from "@nestjs/config"; +import { DomainError } from "../../src/common/domain-error"; +import { AppConfigService } from "../../src/modules/config/app-config.service"; +import { RagTaskHealthProbeService } from "../../src/modules/llm/rag-task-health-probe.service"; + +const createConfigServiceMock = ( + entries: Record +): Pick => ({ + get: (...args: unknown[]) => { + const key = String(args[0] ?? ""); + const defaultValue = args[1]; + return (entries[key] ?? defaultValue) as unknown; + } +}); + +describe("RagTaskHealthProbeService", () => { + it("returns dimension_mismatch when embedding vector length differs from expected", async () => { + const appConfig = new AppConfigService( + createConfigServiceMock({ + NODE_ENV: "test", + LLM_MOCK_MODE: "true", + EMBEDDING_MOCK_MODE: "false" + }) as ConfigService + ); + const service = new RagTaskHealthProbeService(appConfig); + + const result = await service.probeEmbedding({ + runtime: { + provider: "openai", + model: "text-embedding-3-small", + baseUrl: "https://api.openai.com/v1", + apiKey: "test", + timeoutMs: 1000, + dimensions: 3 + }, + expectedDimensions: 4 + }); + + expect(result.status).toBe("failed"); + expect(result.reasonCode).toBe("dimension_mismatch"); + expect(result.details?.expectedDimensions).toBe(4); + expect(result.details?.actualDimensions).toBe(3); + }); + + it("fills builtin rerank samples when candidates are insufficient", async () => { + const appConfig = new AppConfigService( + createConfigServiceMock({ + NODE_ENV: "test", + LLM_MOCK_MODE: "true", + RERANK_MOCK_MODE: "false" + }) as ConfigService + ); + const service = new RagTaskHealthProbeService(appConfig); + + const result = await service.probeRerank({ + runtime: { + provider: "siliconflow", + model: "bge-reranker-v2-m3", + baseUrl: "https://api.siliconflow.cn/v1", + apiKey: "test", + timeoutMs: 1000 + }, + sampleQuery: "revenue by status", + sampleCandidates: ["only one"] + }); + + expect(result.status).toBe("healthy"); + expect(result.reasonCode).toBe("ok"); + expect(result.challenge.status).toBe("comparable"); + expect(result.details?.sampleCandidateCount).toBeGreaterThanOrEqual(2); + expect(result.reranked?.length).toBeGreaterThanOrEqual(2); + }); + + it("maps provider unavailable errors into stable reason code", async () => { + const appConfig = new AppConfigService( + createConfigServiceMock({ + NODE_ENV: "test", + LLM_MOCK_MODE: "false" + }) as ConfigService + ); + const service = new RagTaskHealthProbeService(appConfig); + const result = await ( + service as unknown as { + mapProbeFailure: (error: unknown) => { status: string; reasonCode: string }; + } + ).mapProbeFailure( + new DomainError("EMBEDDING_PROVIDER_UNAVAILABLE", "provider unavailable", 503) + ); + expect(result.status).toBe("degraded"); + expect(result.reasonCode).toBe("provider_unavailable"); + }); +}); diff --git a/apps/backend/test/unit/rerank-router.service.spec.ts b/apps/backend/test/unit/rerank-router.service.spec.ts new file mode 100644 index 0000000..b95ee0f --- /dev/null +++ b/apps/backend/test/unit/rerank-router.service.spec.ts @@ -0,0 +1,204 @@ +import { DomainError } from "../../src/common/domain-error"; +import { RerankRouterService } from "../../src/modules/llm/rerank-router.service"; + +describe("RerankRouterService", () => { + const createService = (overrides?: { + rerankMockMode?: boolean; + llmMockMode?: boolean; + nodeEnv?: string; + generateRawText?: string; + runtimeError?: unknown; + }): RerankRouterService => { + const config = { + rerankMockMode: overrides?.rerankMockMode ?? false, + llmMockMode: overrides?.llmMockMode ?? false, + nodeEnv: overrides?.nodeEnv ?? "development", + rerankProvider: "openai", + rerankModel: "gpt-4.1-mini" + }; + const llmGateway = { + generate: jest.fn().mockResolvedValue({ + provider: "openai", + model: "gpt-4.1-mini", + rawText: + overrides?.generateRawText ?? + JSON.stringify({ + reranked: [ + { + candidateId: "chunk-1", + score: 0.91, + reason: "high semantic match" + } + ] + }) + }) + }; + const ragTaskConfigService = { + resolveRerankRuntime: overrides?.runtimeError + ? jest.fn().mockRejectedValue(overrides.runtimeError) + : jest.fn().mockResolvedValue({ + taskType: "rerank", + provider: "openai", + model: "gpt-4.1-mini", + baseUrl: "https://api.openai.com/v1", + apiKey: "test-key", + timeoutMs: 5000, + configSource: "settings", + configId: "rag-rerank-1" + }) + }; + + return new RerankRouterService( + config as never, + llmGateway as never, + ragTaskConfigService as never + ); + }; + + const rerankInput = { + query: "orders amount", + candidates: [ + { + candidateId: "chunk-1", + content: "table orders(id, amount)", + domain: "schema", + sourceLane: "lexical", + evidence: ["token:orders"], + baseScore: 0.7 + } + ] + }; + + it("returns task-specific rerank metadata with config source", async () => { + const service = createService(); + + const response = await service.rerankCandidatesWithMetadata(rerankInput); + + expect(response.results).toHaveLength(1); + expect(response.metadata.mode).toBe("provider"); + expect(response.metadata.provider).toBe("openai"); + expect(response.metadata.model).toBe("gpt-4.1-mini"); + expect(response.metadata.configSource).toBe("settings"); + expect(response.metadata.configId).toBe("rag-rerank-1"); + }); + + it("throws explicit invalid payload error when response is not parseable", async () => { + const service = createService({ generateRawText: "rerank response unavailable" }); + + await expect(service.rerankCandidatesWithMetadata(rerankInput)).rejects.toMatchObject< + Partial + >({ + code: "RERANK_PROVIDER_INVALID_PAYLOAD" + }); + }); + + it("throws output count mismatch when provider returns fewer candidates", async () => { + const service = createService({ + generateRawText: JSON.stringify({ + reranked: [ + { + candidateId: "chunk-1", + score: 0.88, + reason: "partial result" + } + ] + }) + }); + const twoCandidatesInput = { + query: "orders amount", + candidates: [ + ...rerankInput.candidates, + { + candidateId: "chunk-2", + content: "table customers(id, city)", + domain: "schema", + sourceLane: "dense", + evidence: ["token:customers"], + baseScore: 0.6 + } + ] + }; + + await expect(service.rerankCandidatesWithMetadata(twoCandidatesInput)).rejects.toMatchObject< + Partial + >({ + code: "RERANK_PROVIDER_OUTPUT_COUNT_MISMATCH" + }); + }); + + it("throws invalid payload when provider returns unknown candidate ids", async () => { + const service = createService({ + generateRawText: JSON.stringify({ + reranked: [ + { + candidateId: "chunk-unknown", + score: 0.91, + reason: "unknown" + } + ] + }) + }); + + await expect(service.rerankCandidatesWithMetadata(rerankInput)).rejects.toMatchObject< + Partial + >({ + code: "RERANK_PROVIDER_INVALID_PAYLOAD" + }); + }); + + it("surfaces provider missing errors instead of silently falling back", async () => { + const service = createService({ + llmMockMode: true, + nodeEnv: "development", + runtimeError: new DomainError("LLM_CONFIG_MISSING", "rerank config missing", 503) + }); + + await expect(service.rerankCandidatesWithMetadata(rerankInput)).rejects.toMatchObject< + Partial + >({ + code: "LLM_CONFIG_MISSING" + }); + }); + + it("uses deterministic mock rerank in explicit rerank mock mode", async () => { + const service = createService({ rerankMockMode: true }); + + const response = await service.rerankCandidatesWithMetadata(rerankInput); + + expect(response.results).toHaveLength(1); + expect(response.results[0]?.reason).toContain("mock rerank"); + expect(response.metadata.mode).toBe("mock"); + expect(response.metadata.fallbackReason).toBe("rerank_mock_mode"); + }); + + it("allows llm mock mode only inside NODE_ENV=test", async () => { + const service = createService({ + llmMockMode: true, + nodeEnv: "test" + }); + + const response = await service.rerankCandidatesWithMetadata(rerankInput); + + expect(response.results).toHaveLength(1); + expect(response.metadata.mode).toBe("mock"); + expect(response.metadata.fallbackReason).toBe("llm_mock_mode"); + }); + + it("returns empty metadata for empty candidate input", async () => { + const service = createService(); + + await expect( + service.rerankCandidatesWithMetadata({ + query: "orders", + candidates: [] + }) + ).resolves.toMatchObject({ + results: [], + metadata: { + mode: "provider", + inputCount: 0, + outputCount: 0 + } + }); + }); +}); diff --git a/apps/backend/test/unit/retrieve-knowledge.node.spec.ts b/apps/backend/test/unit/retrieve-knowledge.node.spec.ts new file mode 100644 index 0000000..fdcd48d --- /dev/null +++ b/apps/backend/test/unit/retrieve-knowledge.node.spec.ts @@ -0,0 +1,59 @@ +import { RetrieveKnowledgeNode } from "../../src/modules/conversation/agent/nodes/retrieve-knowledge.node"; + +describe("RetrieveKnowledgeNode", () => { + it("adds schema supplement chunks for relevant allowed tables when RAG retrieval is disabled", async () => { + const queryExecutorRouter = { + execute: jest.fn(async () => ({ + columns: ["columnName", "dataType"], + rows: [ + { columnName: "id", dataType: "INTEGER" }, + { columnName: "method", dataType: "TEXT" }, + { columnName: "amount", dataType: "REAL" } + ] + })) + }; + const node = new RetrieveKnowledgeNode( + { agentRagRetrievalEnabled: false } as never, + queryExecutorRouter as never, + {} as never + ); + + const result = await node.run({ + question: "有多少种支付方式，他们比例是如何", + datasourceId: "ds-sqlite", + datasource: { + id: "ds-sqlite", + name: "SQLite", + type: "sqlite", + status: "available", + readonly: true, + shared: true, + config: { path: "/tmp/text2sql.db" }, + fileMeta: null, + unavailableAt: null, + deletedAt: null, + createdAt: new Date().toISOString(), + updatedAt: new Date().toISOString() + }, + runId: "run-schema-supplement", + allowedTables: ["orders", "payments", "customers"] + }); + + expect(queryExecutorRouter.execute).toHaveBeenCalledWith( + expect.objectContaining({ + sql: expect.stringContaining("pragma_table_info('payments')") + }) + ); + expect(result.retrievalBundle?.selected_context).toEqual([ + expect.objectContaining({ + chunk_id: "schema-supplement:ds-sqlite:payments", + metadata: expect.objectContaining({ + tableNames: ["payments"], + columnNames: ["payments.id", "payments.method", "payments.amount"] + }) + }) + ]); + expect(result.typedSummary.selectedContextCount).toBe(1); + expect(result.evidenceRefs).toContain("schema-supplement:ds-sqlite:payments"); + }); +}); diff --git a/apps/backend/test/unit/sql-generation.service.spec.ts b/apps/backend/test/unit/sql-generation.service.spec.ts index 76ec3bc..26b9419 100644 --- a/apps/backend/test/unit/sql-generation.service.spec.ts +++ b/apps/backend/test/unit/sql-generation.service.spec.ts @@ -4,6 +4,7 @@ import { SqlOutputExtractor } from "../../src/modules/conversation/agent/sql/sql import { SqlPromptBuilder } from "../../src/modules/conversation/agent/sql/sql-prompt.builder"; import type { ProviderRouterService } from "../../src/modules/llm/provider-router.service"; import type { PromptTemplateService } from "../../src/modules/governance/settings/prompt-template.service"; +import { Text2SqlSmartDefaultsService } from "../../src/modules/conversation/runtime/smart-defaults/text2sql-smart-defaults.service"; describe("SqlGenerationService semantic guardrails", () => { const promptTemplateService = { @@ -23,7 +24,8 @@ describe("SqlGenerationService semantic guardrails", () => { new SqlPromptBuilder(), new SqlOutputExtractor(), providerRouter as unknown as ProviderRouterService, - promptTemplateService as unknown as PromptTemplateService + promptTemplateService as unknown as PromptTemplateService, + new Text2SqlSmartDefaultsService() ); beforeEach(() => { @@ -58,6 +60,11 @@ describe("SqlGenerationService semantic guardrails", () => { const firstPrompt = providerRouter.generate.mock.calls[0][0]; const secondPrompt = providerRouter.generate.mock.calls[1][0]; expect(firstPrompt.systemPrompt).toContain("business count-intent query"); + expect(firstPrompt.systemPrompt).toContain("Text2SQL Smart Defaults"); + expect(draft.smartDefaults).toMatchObject({ + bundleId: "text2sql-smart-defaults", + status: "applied" + }); expect(secondPrompt.systemPrompt).toContain("single automatic retry"); expect(secondPrompt.systemPrompt).toContain( "count-intent requires business counting SQL" @@ -150,6 +157,117 @@ describe("SqlGenerationService semantic guardrails", () => { expect(providerRouter.generate).toHaveBeenCalledTimes(1); }); + it("uses a semantic shortcut for grouped count proportions before calling the stream provider", async () => { + const providerRouter = { + generate: jest.fn(), + stream: jest.fn().mockRejectedValue( + new DomainError( + "LLM_REQUEST_FAILED", + "LLM 流式请求失败: The operation was aborted due to timeout", + 502 + ) + ) + }; + const service = createService(providerRouter); + + const draft = await service.stream("有多少种支付方式，他们比例是如何", { + datasourceType: "sqlite", + semanticPlan: { + route: "answer", + standaloneQuestion: "有多少种支付方式，他们比例是如何", + selectedTables: ["payments"], + selectedColumns: [ + "payments.id", + "payments.method", + "payments.amount", + "payments.created_at" + ], + metrics: ["count"], + filters: ["route_kind:text_to_sql"], + evidenceRefs: ["schema-supplement:payments"], + confidence: 0.49 + }, + selectedContext: [ + { + chunk_id: "schema-supplement:payments", + content: "payments table schema", + metadata: { + datasourceId: "ds-1", + indexVersionId: "schema-supplement", + chunkId: "schema-supplement:payments", + domain: "schema", + tableNames: ["payments"], + columnNames: ["payments.id", "payments.method", "payments.amount"], + sourceMetadata: {} + } + } + ] + }); + + expect(draft.provider).toBe("semantic-shortcut"); + expect(draft.sql).toBe( + [ + "SELECT method AS group_value,", + " COUNT(*) AS item_count,", + " ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER (), 2) AS item_percentage", + "FROM payments", + "GROUP BY method", + "ORDER BY item_count DESC;" + ].join("\n") + ); + expect(providerRouter.stream).not.toHaveBeenCalled(); + expect(providerRouter.generate).not.toHaveBeenCalled(); + }); + + it("uses a semantic shortcut for simple counts before calling the stream provider", async () => { + const providerRouter = { + generate: jest.fn(), + stream: jest.fn().mockRejectedValue( + new DomainError( + "LLM_REQUEST_FAILED", + "LLM 流式请求失败: The operation was aborted due to timeout", + 502 + ) + ) + }; + const service = createService(providerRouter); + + const draft = await service.stream("一共有多少订单", { + datasourceType: "sqlite", + semanticPlan: { + route: "answer", + standaloneQuestion: "一共有多少订单", + selectedTables: ["orders"], + selectedColumns: ["orders.id"], + metrics: ["count"], + filters: ["route_kind:text_to_sql"], + evidenceRefs: ["schema-supplement:orders"], + confidence: 0.62 + }, + selectedContext: [ + { + chunk_id: "schema-supplement:orders", + content: "orders table schema", + metadata: { + datasourceId: "ds-1", + indexVersionId: "schema-supplement", + chunkId: "schema-supplement:orders", + domain: "schema", + tableNames: ["orders"], + columnNames: ["orders.id"], + sourceMetadata: {} + } + } + ] + }); + + expect(draft.provider).toBe("semantic-shortcut"); + expect(draft.model).toBe("simple-count-v1"); + expect(draft.sql).toBe("SELECT COUNT(*) AS total_count FROM orders;"); + expect(providerRouter.stream).not.toHaveBeenCalled(); + expect(providerRouter.generate).not.toHaveBeenCalled(); + }); + it("prioritizes structured semantic instructions when context pack is provided", async () => { const providerRouter = { generate: jest.fn().mockResolvedValue({ @@ -343,11 +461,204 @@ describe("SqlGenerationService semantic guardrails", () => { explicitPinning: { source: "context_envelope", tables: ["orders"], - columns: ["orders.amount"] + columns: ["orders.amount"] + } + }) + ).rejects.toMatchObject>({ + code: "LLM_SQL_EVIDENCE_COVERAGE_FAILED" + }); + }); + + it("fails semantic plan coverage when SQL references tables outside allowed plan tables", async () => { + const providerRouter = { + generate: jest.fn().mockResolvedValue({ + provider: "mock-provider", + model: "mock-model", + rawText: "```sql\nSELECT amount FROM invoices;\n```" + }), + stream: jest.fn() + }; + const service = createService(providerRouter); + + await expect( + service.generate("查询金额", { + semanticPlan: { + route: "answer", + standaloneQuestion: "查询金额", + selectedTables: ["orders"], + selectedColumns: ["orders.amount"], + allowedTables: ["orders"], + confidence: 0.9, + evidenceRefs: ["chunk-orders-1"] + } + }) + ).rejects.toMatchObject>({ + code: "LLM_SQL_PLAN_COVERAGE_FAILED" + }); + }); + + it("injects typed semantic plan guidance into SQL prompt", async () => { + const providerRouter = { + generate: jest.fn().mockResolvedValue({ + provider: "mock-provider", + model: "mock-model", + rawText: "```sql\nSELECT amount FROM orders;\n```" + }), + stream: jest.fn() + }; + const service = createService(providerRouter); + + await service.generate("查询订单金额", { + semanticPlan: { + route: "answer", + standaloneQuestion: "查询订单金额", + selectedTables: ["orders"], + selectedColumns: ["orders.amount"], + allowedTables: ["orders"], + forbiddenTables: ["refunds"], + confidence: 0.91, + evidenceRefs: ["chunk-orders-1"] } - }) - ).rejects.toMatchObject>({ - code: "LLM_SQL_EVIDENCE_COVERAGE_FAILED" + }); + + const prompt = providerRouter.generate.mock.calls[0][0]; + expect(prompt.systemPrompt).toContain("Typed semantic plan (must follow):"); + expect(prompt.systemPrompt).toContain("selectedTables=orders"); + expect(prompt.systemPrompt).toContain("forbiddenTables=refunds"); + }); + + it("records ledger obligation claims and unsupported SQL facts in structured artifact", () => { + const service = createService({ + generate: jest.fn(), + stream: jest.fn() + }); + + const artifact = service.buildStructuredArtifact({ + cause: "initial", + datasourceType: "sqlite", + draft: { + provider: "mock-provider", + model: "mock-model", + sql: "SELECT orders.amount, invoices.total FROM orders JOIN invoices ON invoices.order_id = orders.id", + explanation: "uses orders and invoices", + rawText: "", + prompt: { + systemPrompt: "", + userPrompt: "" + }, + semanticPlan: { + route: "answer", + standaloneQuestion: "查询订单金额", + selectedTables: ["orders"], + selectedColumns: ["orders.amount"], + confidence: 0.9, + evidenceRefs: ["chunk-orders-1"], + filters: ["route_kind:text_to_sql"], + snapshotId: "semantic-plan-v1", + planLedger: { + version: "plan-ledger.v1", + snapshotId: "semantic-plan-v1", + obligations: [ + { + id: "ledger:table:orders", + kind: "table", + summary: "orders table", + criticality: "hard_blocker", + status: "grounded", + evidenceRefs: ["chunk-orders-1"], + reasonCodes: ["selected_table_grounded"], + subject: "orders" + }, + { + id: "ledger:column:orders.amount", + kind: "column", + summary: "orders amount", + criticality: "hard_blocker", + status: "grounded", + evidenceRefs: ["chunk-orders-1"], + reasonCodes: ["selected_column_grounded"], + subject: "orders.amount" + } + ], + summary: { + snapshotId: "semantic-plan-v1", + total: 2, + hardBlockerCount: 2, + warningCount: 0, + failedHardBlockerIds: [] + } + } + } + } + }); + + expect(artifact.claimedObligationIds).toEqual([ + "ledger:table:orders", + "ledger:column:orders.amount" + ]); + expect(artifact.unsupportedClaims).toEqual( + expect.arrayContaining([ + { + kind: "table", + value: "invoices", + reasonCode: "table_not_in_ledger" + }, + { + kind: "column", + value: "invoices.total", + reasonCode: "column_not_in_ledger" + } + ]) + ); + expect(artifact.ledgerSnapshotId).toBe("semantic-plan-v1"); + }); + + it("injects structured correction grounding into retry prompt", async () => { + const providerRouter = { + generate: jest.fn().mockResolvedValue({ + provider: "mock-provider", + model: "mock-model", + rawText: "```sql\nSELECT orders.id FROM orders;\n```" + }), + stream: jest.fn() + }; + const service = createService(providerRouter); + + await service.generate("查询订单ID", { + semanticPlan: { + route: "answer", + standaloneQuestion: "查询订单ID", + selectedTables: ["orders"], + selectedColumns: ["orders.id"], + confidence: 0.9, + evidenceRefs: ["chunk-orders-1"], + filters: ["route_kind:text_to_sql"], + snapshotId: "semantic-plan-v1" + }, + correctionGrounding: { + failedSqlRef: "sql.sha256.abc123abc123abcd", + failedSqlPreview: "SELECT missing_city FROM orders", + retryReason: "missing column orders.missing_city", + failureCode: "SQL_MISSING_COLUMN", + failureCategory: "validation", + source: "validation", + attemptCount: 1, + maxAttempts: 2, + evidenceRefs: ["chunk-orders-1"], + semanticPlanSnapshotId: "semantic-plan-v1", + semanticPlanRouteKind: "text_to_sql" + }, + semanticIntent: "general" + }); + + const prompt = providerRouter.generate.mock.calls[0][0]; + expect(prompt.systemPrompt).toContain( + "Correction grounding (must consume for this retry):" + ); + expect(prompt.systemPrompt).toContain( + "failedSqlRef=sql.sha256.abc123abc123abcd" + ); + expect(prompt.systemPrompt).toContain("failureCode=SQL_MISSING_COLUMN"); + expect(prompt.systemPrompt).toContain("retryReason=missing column orders.missing_city"); }); -}); }); diff --git a/apps/backend/test/unit/sql-prompt.builder.spec.ts b/apps/backend/test/unit/sql-prompt.builder.spec.ts index 631cd76..ba5736a 100644 --- a/apps/backend/test/unit/sql-prompt.builder.spec.ts +++ b/apps/backend/test/unit/sql-prompt.builder.spec.ts @@ -16,9 +16,24 @@ describe("SqlPromptBuilder", () => { }); expect(prompt.systemPrompt).toContain("Runtime template overlay"); + expect(prompt.systemPrompt).toContain("cannot override Smart Defaults"); expect(prompt.systemPrompt).toContain("Always join users table with explicit alias."); }); + it("places Smart Defaults baseline before supplemental template overlay", () => { + const builder = new SqlPromptBuilder(); + const prompt = builder.build("统计订单状态分布", "sqlite", undefined, { + smartDefaultsBlock: + "Text2SQL Smart Defaults text2sql-smart-defaults@2026-04-28: only-use-context-pack", + templateOverlay: "Prefer short aliases." + }); + + expect(prompt.systemPrompt.indexOf("Text2SQL Smart Defaults")).toBeLessThan( + prompt.systemPrompt.indexOf("Runtime template overlay") + ); + expect(prompt.systemPrompt).toContain("Prefer short aliases."); + }); + it("adds explicit count-intent guardrail instructions", () => { const builder = new SqlPromptBuilder(); const prompt = builder.build("统计订单总数", "sqlite", undefined, { @@ -96,4 +111,41 @@ describe("SqlPromptBuilder", () => { "Relationship bindings: rel.orders_customers" ); }); + + it("renders semantic-plan guardrails including coverage gaps and snapshot id", () => { + const builder = new SqlPromptBuilder(); + const prompt = builder.build("统计订单 GMV", "sqlite", undefined, { + semanticPlan: { + route: "answer", + standaloneQuestion: "统计订单 GMV", + selectedTables: ["orders", "customers"], + selectedColumns: ["orders.amount", "orders.customer_id", "customers.id"], + confidence: 0.91, + evidenceRefs: ["chunk-orders-1"], + filters: ["route_kind:text_to_sql"], + joinPath: ["orders->customers"], + coverageGaps: [ + { + gapType: "evidence_gap", + subjectKind: "join_path", + reasonCode: "relationship_path_needs_review", + evidenceRefs: ["chunk-orders-1"], + impactScope: "sql_generation" + } + ], + snapshotId: "semantic-plan:text-to-sql:ready:t2:c3:e1:g1:orders" + } + }); + + expect(prompt.systemPrompt).toContain("Typed semantic plan (must follow):"); + expect(prompt.systemPrompt).toContain( + "coverageGaps=join_path:relationship_path_needs_review" + ); + expect(prompt.systemPrompt).toContain( + "snapshotId=semantic-plan:text-to-sql:ready:t2:c3:e1:g1:orders" + ); + expect(prompt.systemPrompt).toContain( + "Execution guardrail: stay within selectedTables/selectedColumns" + ); + }); }); diff --git a/apps/backend/test/unit/text2sql-stage-contract.spec.ts b/apps/backend/test/unit/text2sql-stage-contract.spec.ts new file mode 100644 index 0000000..ad3c6ab --- /dev/null +++ b/apps/backend/test/unit/text2sql-stage-contract.spec.ts @@ -0,0 +1,53 @@ +import { TEXT2SQL_STAGE_OUTCOMES } from "../../src/modules/conversation/text2sql/contracts/text2sql-stage-name"; +import { + TEXT2SQL_V2_STAGE_CATALOG, + resolveText2SqlReasoningStage, + resolveText2SqlTitle, + resolveText2SqlV2StageCatalogEntry +} from "../../src/modules/conversation/text2sql/stages/text2sql-stage-catalog"; + +describe("text2sql stage contracts", () => { + it("keeps a complete v2 stage catalog for stage-owned runtime progress", () => { + expect(Object.keys(TEXT2SQL_V2_STAGE_CATALOG).sort()).toEqual( + [ + "answer", + "assemble-context", + "correct", + "execute", + "generate-sql", + "intake", + "retrieve", + "semantic-plan", + "validate" + ].sort() + ); + + const semanticPlan = resolveText2SqlV2StageCatalogEntry("semantic-plan"); + expect(semanticPlan.title).toBe("语义规划"); + expect(semanticPlan.reasoningStage).toBe("analysis"); + expect(semanticPlan.taskProfile).toBe("semantic-planning"); + expect(semanticPlan.defaultReasoningTier).toBe("high"); + }); + + it("keeps node-level stage/title compatibility for shell fields", () => { + expect(resolveText2SqlReasoningStage("clarify")).toBe("analysis"); + expect(resolveText2SqlTitle("clarify")).toBe("理解问题"); + expect(resolveText2SqlReasoningStage("generate-sql")).toBe("generation"); + expect(resolveText2SqlTitle("format-answer")).toBe("整理回答"); + + expect(resolveText2SqlReasoningStage("future-node")).toBe("unknown"); + expect(resolveText2SqlTitle("future-node")).toBe("future-node"); + }); + + it("includes the required stage outcome vocabulary", () => { + expect(TEXT2SQL_STAGE_OUTCOMES).toEqual( + expect.arrayContaining([ + "success", + "skipped", + "degraded", + "failed", + "needs-clarification" + ]) + ); + }); +}); diff --git a/apps/backend/test/unit/text2sql-stream-event.mapper.spec.ts b/apps/backend/test/unit/text2sql-stream-event.mapper.spec.ts new file mode 100644 index 0000000..2f3367a --- /dev/null +++ b/apps/backend/test/unit/text2sql-stream-event.mapper.spec.ts @@ -0,0 +1,296 @@ +import { Text2SqlStreamEventMapper } from "../../src/modules/conversation/text2sql/stream/text2sql-stream-event.mapper"; + +describe("Text2SqlStreamEventMapper", () => { + const mapper = new Text2SqlStreamEventMapper(); + + it("maps unknown step nodes safely with fallback stage/title", () => { + const mapped = mapper.mapStepEvent({ + step: { + node: "future-node", + status: "success", + at: "2026-04-26T00:00:00.000Z" + }, + runId: "run-1", + lastSequence: 0 + }); + + expect(mapped.data).toMatchObject({ + node: "future-node", + stage: "unknown", + title: "future-node", + sequence: 1 + }); + }); + + it("maps optional v2 stage artifact from step summary without breaking shell fields", () => { + const mapped = mapper.mapStepEvent({ + step: { + node: "generate-sql", + status: "success", + at: "2026-04-26T00:00:00.000Z", + outputSummary: JSON.stringify({ + v2: { + stageArtifact: { + stage: "generate-sql", + status: "success", + durationMs: 12 + }, + runtimePlan: { + version: "runtime-plan.v1", + currentItemId: "runtime-plan:generate-sql", + items: [ + { + id: "runtime-plan:generate-sql", + stage: "generate-sql", + goal: "生成 SQL", + status: "completed", + summary: "generate-sql completed", + reasonCodes: ["sql_generated"] + } + ] + }, + planLedger: { + snapshotId: "semantic-plan-v1", + total: 2, + hardBlockerCount: 1, + warningCount: 1, + failedHardBlockerIds: [], + warningIds: ["ledger:warning:degraded"] + } + } + }) + }, + runId: "run-2", + lastSequence: 0 + }); + + const data = mapped.data as { + node: string; + status: string; + v2?: { + stageArtifact?: { + stage?: string; + status?: string; + durationMs?: number; + }; + runtimePlan?: { + currentItemId?: string; + stage?: string; + status?: string; + summary?: string; + reasonCodes?: string[]; + }; + planLedger?: { + total?: number; + hardBlockerCount?: number; + warningCount?: number; + warningIds?: string[]; + }; + }; + }; + expect(data.node).toBe("generate-sql"); + expect(data.status).toBe("success"); + expect(data.v2?.stageArtifact).toEqual({ + stage: "generate-sql", + status: "success", + durationMs: 12 + }); + expect(data.v2?.runtimePlan).toEqual({ + currentItemId: "runtime-plan:generate-sql", + stage: "generate-sql", + status: "completed", + summary: "generate-sql completed", + reasonCodes: ["sql_generated"] + }); + expect(data.v2?.planLedger).toMatchObject({ + total: 2, + hardBlockerCount: 1, + warningCount: 1, + warningIds: ["ledger:warning:degraded"] + }); + }); + + it("maps tool-call/result/error events with trace payload", () => { + const called = mapper.mapLlmEvent({ + type: "tool-call", + toolName: "runReadOnlySql", + toolCallId: "call-1", + input: { sql: "SELECT 1" } + }); + expect(called.type).toBe("tool-call"); + expect(called.traceToolCall?.status).toBe("called"); + + const result = mapper.mapLlmEvent({ + type: "tool-result", + toolName: "runReadOnlySql", + toolCallId: "call-1", + output: { rows: [] } + }); + expect(result.type).toBe("tool-result"); + expect(result.traceToolCall?.status).toBe("result"); + + const error = mapper.mapLlmEvent({ + type: "tool-error", + toolName: "runReadOnlySql", + toolCallId: "call-1", + message: "failed" + }); + expect(error.type).toBe("tool-error"); + expect(error.traceToolCall?.status).toBe("error"); + }); + + it("builds stream envelope with required fields", () => { + const envelope = mapper.createEnvelope({ + type: "start", + data: { + requestId: "req-1" + }, + runId: "run-1", + sessionId: "session-1", + at: "2026-04-26T00:00:00.000Z" + }); + + expect(envelope).toEqual({ + type: "start", + runId: "run-1", + sessionId: "session-1", + at: "2026-04-26T00:00:00.000Z", + data: { + requestId: "req-1" + } + }); + }); + + it("keeps stream shell fields stable when state data carries v2 progress", () => { + const mapped = mapper.mapStepEvent({ + step: { + node: "safety-check", + status: "success", + at: "2026-04-26T00:00:01.000Z", + outputSummary: JSON.stringify({ + v2: { + stageArtifact: { + stage: "validate", + status: "success", + warnings: ["validation_passed"] + } + } + }) + }, + runId: "run-v2-shell", + lastSequence: 2 + }); + const envelope = mapper.createEnvelope({ + type: "state", + runId: "run-v2-shell", + sessionId: "session-v2-shell", + at: "2026-04-26T00:00:01.000Z", + data: mapped.data + }); + + expect(envelope).toMatchObject({ + type: "state", + runId: "run-v2-shell", + sessionId: "session-v2-shell", + at: "2026-04-26T00:00:01.000Z" + }); + const data = envelope.data as { + v2?: { + stageArtifact?: { + stage?: string; + }; + }; + }; + expect(data.v2?.stageArtifact?.stage).toBe("validate"); + }); + + it.each([ + { + node: "retrieve-knowledge", + artifact: { + stage: "retrieve", + status: "degraded", + warnings: ["dense_unavailable"], + provider: { + provider: "embedding-provider", + unavailableReason: "provider_missing" + } + } + }, + { + node: "safety-check", + artifact: { + stage: "validate", + status: "success", + warnings: ["dry-run skipped: datasource type unknown"] + } + }, + { + node: "relationship-correction", + artifact: { + stage: "correct", + status: "success", + metadata: { + retryCount: 1, + maxAttempts: 2 + } + } + }, + { + node: "generate-sql", + artifact: { + stage: "generate-sql", + status: "success", + metadata: { + sql: "SELECT COUNT(*) AS total FROM orders" + } + } + }, + { + node: "format-answer", + artifact: { + stage: "answer", + status: "success", + metadata: { + answerPreview: "订单总数为 10" + } + } + } + ])("maps $artifact.stage progress with v2 artifact and stable shell", ({ node, artifact }) => { + const mapped = mapper.mapStepEvent({ + step: { + node, + status: artifact.status === "degraded" ? "success" : "success", + at: "2026-04-26T00:00:01.000Z", + outputSummary: JSON.stringify({ + v2: { + stageArtifact: artifact + } + }) + }, + runId: "run-v2-progress", + lastSequence: 7 + }); + const envelope = mapper.createEnvelope({ + type: "state", + runId: "run-v2-progress", + sessionId: "session-v2-progress", + at: "2026-04-26T00:00:01.000Z", + data: mapped.data + }); + + expect(envelope).toMatchObject({ + type: "state", + runId: "run-v2-progress", + sessionId: "session-v2-progress", + at: "2026-04-26T00:00:01.000Z", + data: { + node, + sequence: 8, + v2: { + stageArtifact: artifact + } + } + }); + }); +}); diff --git a/apps/backend/test/unit/text2sql-task-profile-policy.spec.ts b/apps/backend/test/unit/text2sql-task-profile-policy.spec.ts new file mode 100644 index 0000000..8169ff9 --- /dev/null +++ b/apps/backend/test/unit/text2sql-task-profile-policy.spec.ts @@ -0,0 +1,74 @@ +import { ProviderRouterService } from "../../src/modules/llm/provider-router.service"; + +describe("text2sql task-profile policy matrix", () => { + const createService = (): ProviderRouterService => { + const config = { + llmMockMode: false, + llmProvider: "openai", + llmModel: "gpt-4.1-mini", + llmBaseUrl: "https://api.openai.com/v1", + llmApiKey: "test-key", + llmTimeoutMs: 5_000, + llmStreamTimeoutMs: 10_000 + }; + const providerCatalog = { + resolveRuntimeByModelId: jest.fn(), + resolveDefaultModel: jest.fn(), + resolveRuntimeConfig: jest.fn() + }; + const llmGateway = { + generate: jest.fn(), + stream: jest.fn() + }; + return new ProviderRouterService(config as never, providerCatalog as never, llmGateway as never); + }; + + it("uses low reasoning for intake/retrieve and high reasoning for semantic-plan/generate-sql", () => { + const service = createService(); + + const intakePolicy = service.resolveText2SqlStageTaskProfilePolicy({ + stage: "intake" + }); + const retrievePolicy = service.resolveText2SqlStageTaskProfilePolicy({ + stage: "retrieve" + }); + const planPolicy = service.resolveText2SqlStageTaskProfilePolicy({ + stage: "semantic-plan" + }); + const generatePolicy = service.resolveText2SqlStageTaskProfilePolicy({ + stage: "generate-sql" + }); + + expect(intakePolicy.reasoningTier).toBe("low"); + expect(intakePolicy.taskProfile).toBe("intake-fast"); + expect(retrievePolicy.reasoningTier).toBe("low"); + expect(retrievePolicy.taskProfile).toBe("retrieval-support"); + expect(planPolicy.reasoningTier).toBe("high"); + expect(planPolicy.taskProfile).toBe("semantic-planning"); + expect(generatePolicy.reasoningTier).toBe("high"); + expect(generatePolicy.taskProfile).toBe("sql-generation"); + }); + + it("records escalation reason and upgrades reasoning tier when correction retry is requested", () => { + const service = createService(); + + const baselineCorrectionPolicy = service.resolveText2SqlStageTaskProfilePolicy({ + stage: "correct" + }); + const escalatedCorrectionPolicy = service.resolveText2SqlStageTaskProfilePolicy({ + stage: "correct", + escalationReason: "execution_error_correction_retry", + modelCatalogId: "model-catalog-1" + }); + + expect(baselineCorrectionPolicy.reasoningTier).toBe("medium"); + expect(escalatedCorrectionPolicy.reasoningTier).toBe("high"); + expect(escalatedCorrectionPolicy.escalationReason).toBe( + "execution_error_correction_retry" + ); + expect(escalatedCorrectionPolicy.policySource).toBe( + "session_model_catalog_binding" + ); + }); +}); + diff --git a/apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts b/apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts new file mode 100644 index 0000000..3832d5d --- /dev/null +++ b/apps/backend/test/unit/text2sql-v2-artifact-ref.service.spec.ts @@ -0,0 +1,247 @@ +import { + REQUIRED_TEXT2SQL_V2_ARTIFACT_CATEGORIES, + Text2SqlV2ArtifactRefService +} from "../../src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service"; +import type { SqlRun } from "@text2sql/shared-types"; + +const createService = (writeReplay: jest.Mock) => + new Text2SqlV2ArtifactRefService({ + rag: { + replay: { + writeReplay + } + } + } as never); + +const createRun = (evidenceCount: number): SqlRun => ({ + runId: "run-artifact-ref", + sessionId: "session-artifact-ref", + question: "统计订单", + status: "executionResult", + provider: "volcengine", + answer: "ok", + trace: { + runId: "run-artifact-ref", + provider: "volcengine", + retryCount: 0, + steps: [], + v2: { + version: "v2", + stageOrder: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + stages: [ + { + stage: "answer", + status: "success" + } + ], + contextPack: { + status: "ready", + selectedEvidenceIds: Array.from( + { length: evidenceCount }, + (_, index) => `chunk-${index + 1}` + ), + selectedTables: ["orders"], + selectedColumns: ["orders.id"] + } + } + }, + llmRaw: null, + createdAt: "2026-04-28T00:00:00.000Z" +}); + +describe("Text2SqlV2ArtifactRefService", () => { + it("writes large context summaries through the knowledge facade and exposes safe refs", async () => { + const writeReplay = jest.fn().mockResolvedValue(undefined); + const service = createService(writeReplay); + + const run = await service.attachRunArtifactRefs(createRun(30), "ds-main"); + + expect(writeReplay).toHaveBeenCalledWith( + expect.objectContaining({ + runId: "run-artifact-ref", + datasourceId: "ds-main", + replayKey: expect.stringMatching(/^text2sql:artifact:context_snippets:/), + stage: "text2sql_artifact_ref", + payload: expect.objectContaining({ + version: "text2sql-artifact-summary.v1", + sanitizedSummary: "Compacted 30 selected context evidence ids.", + payload: expect.objectContaining({ + selectedEvidenceIds: expect.arrayContaining(["chunk-1", "chunk-30"]) + }) + }) + }) + ); + expect(run.trace.v2?.artifactRefs?.[0]).toMatchObject({ + category: "context_snippets", + summary: "Compacted 30 selected context evidence ids.", + visibility: "user", + sensitivity: "none", + reasonCodes: ["large_context_compacted"] + }); + }); + + it("writes stable refs for every required runtime artifact category", async () => { + const writeReplay = jest.fn().mockResolvedValue(undefined); + const service = createService(writeReplay); + const run = createRun(30); + run.sql = "SELECT COUNT(*) AS total FROM orders"; + run.model = "deepseek-v3"; + run.columns = ["total"]; + run.rows = [ + { total: 1 }, + { total: 2 }, + { total: 3 }, + { total: 4 } + ]; + run.trace.promptTemplate = { + templateId: "text2sql-default", + version: 3, + fallbackReason: "workspace_default" + }; + run.trace.v2!.sqlGeneration = { + sql: run.sql, + usedTables: ["orders"], + usedColumns: ["orders.id"], + evidenceRefs: ["chunk-1"], + correctionGrounding: { + failedSqlRef: "sha256:failed", + retryReason: "dry run failed", + failureCode: "SQL_DRY_RUN_PARSE_REJECTED", + attemptCount: 1, + maxAttempts: 2, + evidenceRefs: ["chunk-1"] + } + }; + run.trace.v2!.sqlValidation = { + status: "failed", + correctable: true, + checks: [ + { + check: "dry-run", + status: "failed", + code: "SQL_DRY_RUN_PARSE_REJECTED", + message: "dry run rejected" + } + ], + failure: { + code: "SQL_DRY_RUN_PARSE_REJECTED", + message: "dry run rejected", + category: "validation", + terminal: false, + correctable: true + } + }; + run.trace.v2!.smartDefaults = { + bundleId: "smart-defaults", + version: "2026-04-28", + coveredStages: ["generate-sql"], + ruleIds: ["prompt-template-overlay"], + status: "applied" + }; + + const withRefs = await service.attachRunArtifactRefs(run, "ds-main"); + + const categories = withRefs.trace.v2?.artifactRefs?.map((ref) => ref.category); + expect(categories).toEqual(expect.arrayContaining([...REQUIRED_TEXT2SQL_V2_ARTIFACT_CATEGORIES])); + expect(writeReplay).toHaveBeenCalledTimes(REQUIRED_TEXT2SQL_V2_ARTIFACT_CATEGORIES.length); + expect( + withRefs.trace.v2?.artifactRefs?.filter( + (ref) => ref.category === "provider_output_summary" + )[0] + ).toMatchObject({ + sensitivity: "provider_raw", + reasonCodes: expect.arrayContaining(["provider_output_summarized"]) + }); + }); + + it("deduplicates producer refs against existing trace refs", async () => { + const writeReplay = jest.fn().mockResolvedValue(undefined); + const service = createService(writeReplay); + const run = createRun(30); + const prepared = await service.attachRunArtifactRefs(run, "ds-main"); + + writeReplay.mockClear(); + const secondPass = await service.attachRunArtifactRefs(prepared, "ds-main"); + + expect(writeReplay).not.toHaveBeenCalled(); + expect(secondPass.trace.v2?.artifactRefs?.map((ref) => ref.id)).toEqual( + prepared.trace.v2?.artifactRefs?.map((ref) => ref.id) + ); + }); + + it("does not persist permission-filtered raw payloads", async () => { + const writeReplay = jest.fn().mockResolvedValue(undefined); + const service = createService(writeReplay); + const run = createRun(30); + run.trace.v2!.contextPack!.permissionFiltering = { + status: "applied", + deniedEvidenceCount: 1 + }; + + await service.attachRunArtifactRefs(run, "ds-main"); + + expect(writeReplay).toHaveBeenCalledWith( + expect.objectContaining({ + payload: expect.objectContaining({ + ref: expect.objectContaining({ + sensitivity: "permission_filtered" + }), + payload: undefined + }) + }) + ); + }); + + it("surfaces artifact write failures as warnings without fake refs", async () => { + const writeReplay = jest.fn().mockRejectedValue(new Error("storage down")); + const service = createService(writeReplay); + + const run = await service.attachRunArtifactRefs(createRun(30), "ds-main"); + + expect(run.trace.v2?.artifactRefs).toBeUndefined(); + expect(run.trace.v2?.stages.find((stage) => stage.stage === "answer")?.warnings).toEqual( + expect.arrayContaining([ + "artifact_ref_write_failed:context_snippets", + "artifact_ref_write_failed:schema_supplement", + "artifact_ref_write_failed:provider_output_summary" + ]) + ); + }); + + it("omits raw payloads for provider, prompt, permission-filtered, and sensitive refs", async () => { + const writeReplay = jest.fn().mockResolvedValue(undefined); + const service = createService(writeReplay); + const run = createRun(30); + run.trace.promptTemplate = { + templateId: "text2sql-default", + version: 3 + }; + run.trace.v2!.contextPack!.permissionFiltering = { + status: "applied", + deniedEvidenceCount: 1 + }; + + await service.attachRunArtifactRefs(run, "ds-main"); + + const payloads = writeReplay.mock.calls.map((call) => call[0].payload); + expect( + payloads + .filter((payload) => + ["provider_output_summary", "prompt_input", "schema_supplement"].includes( + payload.ref.category + ) + ) + .every((payload) => payload.payload === undefined) + ).toBe(true); + }); +}); diff --git a/apps/backend/test/unit/text2sql-v2-correction.spec.ts b/apps/backend/test/unit/text2sql-v2-correction.spec.ts new file mode 100644 index 0000000..eb2014b --- /dev/null +++ b/apps/backend/test/unit/text2sql-v2-correction.spec.ts @@ -0,0 +1,212 @@ +import type { Text2SqlV2FailureSemantic } from "@text2sql/shared-types"; +import { DomainError } from "../../src/common/domain-error"; +import { SqlCorrectionService } from "../../src/modules/conversation/adapters/sql-correction.service"; +import { CorrectSqlNode } from "../../src/modules/conversation/nodes/correct-sql.node"; + +describe("text2sql v2 sql correction decision", () => { + const service = new SqlCorrectionService(); + + function validationError(failure: Text2SqlV2FailureSemantic) { + return new DomainError( + "SQL_VALIDATION_FAILED", + failure.message, + 422, + { + validationFailure: failure + } + ); + } + + function artifactError(failure: Text2SqlV2FailureSemantic) { + return new DomainError( + "SQL_VALIDATION_FAILED", + failure.message, + 422, + { + validationArtifact: { + status: "failed", + correctable: Boolean(failure.correctable), + checks: [ + { + check: "parse", + status: "failed", + code: failure.code, + message: failure.message + } + ], + failure + } + } + ); + } + + it.each([ + ["SQL_PARSE_UNSUPPORTED_STATEMENT", "syntax failure"], + ["SQL_MISSING_COLUMN", "missing column `orders.city`"], + ["SQL_DIALECT_MISMATCH", "dialect mismatch"], + ["SQL_RELATIONSHIP_PATH_MISMATCH", "join path mismatch"] + ])("marks %s validation failure as correctable", (code, message) => { + const decision = service.decide( + validationError({ + code, + message, + category: "validation" + }) + ); + + expect(decision).toMatchObject({ + correctable: true, + maxAttempts: service.maxAttempts, + category: "validation", + source: "validation", + failureCode: code + }); + }); + + it("reads validation artifacts before generic domain error classification", () => { + const decision = service.decide( + artifactError({ + code: "SQL_DRY_PLAN_RELATIONSHIP_MISMATCH", + message: "dry-plan relationship consistency check failed", + category: "validation", + terminal: false + }) + ); + + expect(decision).toMatchObject({ + correctable: true, + source: "validation", + failureCode: "SQL_DRY_PLAN_RELATIONSHIP_MISMATCH" + }); + }); + + it.each([ + ["SQL_READ_ONLY_VIOLATION", "governance", "read-only failure"], + ["SQL_TABLE_PERMISSION_DENIED", "governance", "table permission failure"], + ["SQL_COLUMN_PERMISSION_DENIED", "governance", "column permission failure"], + ["SQL_PLAN_FAIL_CLOSED", "validation", "fail-closed plan"], + ["SQL_PLAN_REQUIRES_CLARIFICATION", "validation", "clarification required"] + ] as const)( + "skips correction for terminal %s", + (code, category, message) => { + const decision = service.decide( + validationError({ + code, + message, + category, + terminal: true, + correctable: false + }) + ); + + expect(decision.correctable).toBe(false); + expect(decision.maxAttempts).toBe(0); + expect(decision.source).toBe("validation"); + expect(decision.failureCode).toBe(code); + } + ); + + it.each([ + ["LLM_PROVIDER_UNAVAILABLE", "provider unavailable"], + ["DATASOURCE_UNAVAILABLE", "datasource unavailable"] + ])("treats %s domain errors as provider failures", (code, message) => { + const decision = service.decide(new DomainError(code, message, 503)); + + expect(decision).toMatchObject({ + correctable: false, + maxAttempts: 0, + category: "provider", + source: "execution", + failureCode: code + }); + }); + + it.each([ + "SQL syntax error near FROM", + "unknown column `orders.city`", + "dialect error: strftime unsupported", + "cannot resolve join path for relationship binding" + ])("keeps execution marker '%s' inside bounded retry budget", (message) => { + const decision = service.decide(new Error(message)); + + expect(decision.correctable).toBe(true); + expect(decision.maxAttempts).toBe(service.maxAttempts); + expect(decision.category).toBe("execution"); + expect(decision.source).toBe("execution"); + }); + + it("does not retry opaque execution errors", () => { + const decision = service.decide(new Error("network timeout")); + + expect(decision).toMatchObject({ + correctable: false, + maxAttempts: 0, + category: "unknown", + source: "execution" + }); + }); + + it("tracks correction budget explicitly for graph loop control", () => { + expect( + service.resolveBudget({ + attemptCount: 1 + }) + ).toEqual({ + attemptCount: 1, + maxAttempts: 2, + remainingAttempts: 1, + exhausted: false + }); + + expect( + service.resolveBudget({ + attemptCount: 2 + }).exhausted + ).toBe(true); + }); + + it("carries failed ledger obligation ids into correction grounding", () => { + const node = new CorrectSqlNode(service); + const result = node.run({ + failedSql: "SELECT COUNT(*) FROM orders", + attemptCount: 0, + semanticPlan: { + route: "answer", + standaloneQuestion: "统计客户订单", + selectedTables: ["orders", "customers"], + selectedColumns: [], + confidence: 0.8, + evidenceRefs: ["relationship-orders-customers"], + filters: ["route_kind:text_to_sql"], + snapshotId: "semantic-plan-v1" + }, + validationArtifact: { + status: "failed", + correctable: true, + failedObligationIds: ["ledger:join-path:orders-customers"], + checks: [ + { + check: "ledger-fulfillment", + status: "failed", + code: "SQL_LEDGER_FULFILLMENT_FAILED", + message: "SQL does not fulfill all required ledger obligations", + failedObligationIds: ["ledger:join-path:orders-customers"], + reasonCodes: ["ledger_join_path_not_used"] + } + ], + failure: { + code: "SQL_LEDGER_FULFILLMENT_FAILED", + message: "SQL does not fulfill all required ledger obligations", + category: "validation", + terminal: false, + correctable: true + } + } + }); + + expect(result.outcome).toBe("retry_generation"); + expect(result.artifact.grounding.failedObligationIds).toEqual([ + "ledger:join-path:orders-customers" + ]); + }); +}); diff --git a/apps/backend/test/unit/text2sql-v2-embedding-provider.spec.ts b/apps/backend/test/unit/text2sql-v2-embedding-provider.spec.ts new file mode 100644 index 0000000..03fcd70 --- /dev/null +++ b/apps/backend/test/unit/text2sql-v2-embedding-provider.spec.ts @@ -0,0 +1,401 @@ +import type { ConfigService } from "@nestjs/config"; +import { DomainError } from "../../src/common/domain-error"; +import { AppConfigService } from "../../src/modules/config/app-config.service"; +import { EmbeddingRouterService } from "../../src/modules/llm/embedding-router.service"; +import type { RagTaskConfigService } from "../../src/modules/llm/rag-task-config.service"; + +const createConfigServiceMock = ( + entries: Record +): Pick => ({ + get: (...args: unknown[]) => { + const key = String(args[0] ?? ""); + const defaultValue = args[1]; + return (entries[key] ?? defaultValue) as unknown; + } +}); + +describe("Text2Sql v2 embedding provider", () => { + const originalFetch = global.fetch; + + afterEach(() => { + global.fetch = originalFetch; + jest.restoreAllMocks(); + }); + + const createRagTaskConfigServiceMock = (runtime?: { + taskType: "embedding"; + provider: string; + model: string; + baseUrl: string; + apiKey: string; + dimensions?: number; + vectorVersion?: string; + timeoutMs: number; + configSource: "settings" | "env_fallback" | "missing"; + configId?: string; + }): Pick => ({ + resolveEmbeddingRuntime: async () => { + if (!runtime) { + throw new DomainError( + "EMBEDDING_PROVIDER_UNAVAILABLE", + "Embedding provider 配置不完整，dense lane 将标记 unavailable。", + 503 + ); + } + return runtime; + } + }); + + it("returns deterministic mock vectors when embedding mock mode is explicitly enabled", async () => { + const config = new AppConfigService( + createConfigServiceMock({ + NODE_ENV: "development", + LLM_MOCK_MODE: "true", + EMBEDDING_MOCK_MODE: "true", + EMBEDDING_PROVIDER: "volcengine", + EMBEDDING_MODEL: "embedding-v1", + EMBEDDING_VECTOR_VERSION: "v2", + EMBEDDING_DIMENSIONS: "8" + }) as ConfigService + ); + const service = new EmbeddingRouterService( + config, + createRagTaskConfigServiceMock({ + taskType: "embedding", + provider: "volcengine", + model: "embedding-v1", + baseUrl: "https://mock", + apiKey: "mock-key", + dimensions: 8, + vectorVersion: "v2", + timeoutMs: 1000, + configSource: "settings" + }) as RagTaskConfigService + ); + + const first = await service.embed({ + texts: ["orders amount"], + indexVersion: "idx-1", + scope: "datasource", + assetType: "rag_chunk" + }); + const second = await service.embed({ + texts: ["orders amount"], + indexVersion: "idx-1", + scope: "datasource", + assetType: "rag_chunk" + }); + + expect(first).toHaveLength(1); + expect(first[0]?.metadata.provider).toBe("volcengine:mock"); + expect(first[0]?.metadata.model).toBe("embedding-v1"); + expect(first[0]?.metadata.dimensions).toBe(8); + expect(first[0]?.metadata.vectorVersion).toBe("v2"); + expect(first[0]?.vector).toEqual(second[0]?.vector); + }); + + it("allows llm mock mode as deterministic test double in NODE_ENV=test", async () => { + const config = new AppConfigService( + createConfigServiceMock({ + NODE_ENV: "test", + LLM_MOCK_MODE: "true", + EMBEDDING_PROVIDER: "openai", + EMBEDDING_MODEL: "embedding-test" + }) as ConfigService + ); + const service = new EmbeddingRouterService( + config, + createRagTaskConfigServiceMock({ + taskType: "embedding", + provider: "openai", + model: "embedding-test", + baseUrl: "https://mock", + apiKey: "mock-key", + dimensions: 8, + vectorVersion: "v1", + timeoutMs: 1000, + configSource: "settings" + }) as RagTaskConfigService + ); + const vectors = await service.embed({ + texts: ["orders amount"] + }); + expect(vectors).toHaveLength(1); + expect(vectors[0]?.metadata.provider).toContain(":mock"); + }); + + it("throws explicit unavailable error when provider config is missing in non-test llm mock mode", async () => { + const config = new AppConfigService( + createConfigServiceMock({ + NODE_ENV: "development", + LLM_MOCK_MODE: "true", + EMBEDDING_MOCK_MODE: "false", + EMBEDDING_PROVIDER: "openai", + EMBEDDING_BASE_URL: "", + EMBEDDING_API_KEY: "" + }) as ConfigService + ); + const service = new EmbeddingRouterService( + config, + createRagTaskConfigServiceMock() as RagTaskConfigService + ); + + await expect( + service.embed({ + texts: ["orders amount"] + }) + ).rejects.toMatchObject>({ + code: "EMBEDDING_PROVIDER_UNAVAILABLE" + }); + }); + + it("returns empty vectors for empty query text without provider calls", async () => { + const config = new AppConfigService( + createConfigServiceMock({ + NODE_ENV: "development", + EMBEDDING_MOCK_MODE: "false", + EMBEDDING_PROVIDER: "openai", + EMBEDDING_MODEL: "embedding-v1" + }) as ConfigService + ); + const resolveEmbeddingRuntime = jest.fn(); + const service = new EmbeddingRouterService( + config, + { resolveEmbeddingRuntime } as unknown as RagTaskConfigService + ); + + await expect(service.embed({ texts: [" ", ""] })).resolves.toEqual([]); + expect(resolveEmbeddingRuntime).not.toHaveBeenCalled(); + }); + + it("throws explicit request failure with provider metadata", async () => { + global.fetch = jest.fn().mockRejectedValue(new Error("network down")) as never; + const config = new AppConfigService( + createConfigServiceMock({ + NODE_ENV: "development", + EMBEDDING_MOCK_MODE: "false", + EMBEDDING_PROVIDER: "openai", + EMBEDDING_MODEL: "embedding-v1" + }) as ConfigService + ); + const service = new EmbeddingRouterService( + config, + createRagTaskConfigServiceMock({ + taskType: "embedding", + provider: "openai", + model: "embedding-v1", + baseUrl: "https://embedding.example/v1", + apiKey: "test-key", + dimensions: 2, + vectorVersion: "v1", + timeoutMs: 1000, + configSource: "settings" + }) as RagTaskConfigService + ); + + await expect(service.embed({ texts: ["orders"] })).rejects.toMatchObject< + Partial + >({ + code: "EMBEDDING_PROVIDER_REQUEST_FAILED", + details: { + provider: "openai", + configSource: "settings" + } + }); + }); + + it("throws explicit response error with status and bounded body", async () => { + global.fetch = jest.fn().mockResolvedValue({ + ok: false, + status: 429, + text: jest.fn().mockResolvedValue("rate limited") + }) as never; + const config = new AppConfigService( + createConfigServiceMock({ + NODE_ENV: "development", + EMBEDDING_MOCK_MODE: "false", + EMBEDDING_PROVIDER: "openai", + EMBEDDING_MODEL: "embedding-v1" + }) as ConfigService + ); + const service = new EmbeddingRouterService( + config, + createRagTaskConfigServiceMock({ + taskType: "embedding", + provider: "openai", + model: "embedding-v1", + baseUrl: "https://embedding.example/v1", + apiKey: "test-key", + timeoutMs: 1000, + configSource: "settings" + }) as RagTaskConfigService + ); + + await expect(service.embed({ texts: ["orders"] })).rejects.toMatchObject< + Partial + >({ + code: "EMBEDDING_PROVIDER_RESPONSE_ERROR", + details: { + statusCode: 429, + body: "rate limited" + } + }); + }); + + it("rejects invalid payload count, invalid vectors, and dimension mismatch", async () => { + const config = new AppConfigService( + createConfigServiceMock({ + NODE_ENV: "development", + EMBEDDING_MOCK_MODE: "false", + EMBEDDING_PROVIDER: "openai", + EMBEDDING_MODEL: "embedding-v1", + EMBEDDING_VECTOR_VERSION: "v7" + }) as ConfigService + ); + const service = new EmbeddingRouterService( + config, + createRagTaskConfigServiceMock({ + taskType: "embedding", + provider: "openai", + model: "embedding-v1", + baseUrl: "https://embedding.example/v1", + apiKey: "test-key", + timeoutMs: 1000, + configSource: "settings" + }) as RagTaskConfigService + ); + + global.fetch = jest.fn().mockResolvedValueOnce({ + ok: true, + json: jest.fn().mockResolvedValue({ data: [] }) + }) as never; + await expect(service.embed({ texts: ["orders"] })).rejects.toMatchObject< + Partial + >({ + code: "EMBEDDING_PROVIDER_INVALID_PAYLOAD" + }); + + global.fetch = jest.fn().mockResolvedValueOnce({ + ok: true, + json: jest.fn().mockResolvedValue({ data: [{ embedding: [] }] }) + }) as never; + await expect(service.embed({ texts: ["orders"] })).rejects.toMatchObject< + Partial + >({ + code: "EMBEDDING_PROVIDER_INVALID_VECTOR" + }); + + global.fetch = jest.fn().mockResolvedValueOnce({ + ok: true, + json: jest.fn().mockResolvedValue({ + data: [{ embedding: [0.1, 0.2] }, { embedding: [0.3] }] + }) + }) as never; + await expect( + service.embed({ texts: ["orders", "customers"] }) + ).rejects.toMatchObject>({ + code: "EMBEDDING_PROVIDER_DIMENSION_MISMATCH", + details: { + expectedDimensions: 2, + actualDimensions: 1 + } + }); + }); + + it("rejects vectors when provider dimension mismatches configured runtime dimension", async () => { + global.fetch = jest.fn().mockResolvedValue({ + ok: true, + json: jest.fn().mockResolvedValue({ + data: [{ embedding: [0.1, 0.2] }] + }) + }) as never; + const config = new AppConfigService( + createConfigServiceMock({ + NODE_ENV: "development", + EMBEDDING_MOCK_MODE: "false", + EMBEDDING_PROVIDER: "openai", + EMBEDDING_MODEL: "embedding-v1" + }) as ConfigService + ); + const service = new EmbeddingRouterService( + config, + createRagTaskConfigServiceMock({ + taskType: "embedding", + provider: "openai", + model: "embedding-v1", + baseUrl: "https://embedding.example/v1", + apiKey: "test-key", + dimensions: 3, + timeoutMs: 1000, + configSource: "settings" + }) as RagTaskConfigService + ); + + await expect(service.embed({ texts: ["orders"] })).rejects.toMatchObject< + Partial + >({ + code: "EMBEDDING_PROVIDER_DIMENSION_MISMATCH", + details: { + expectedDimensions: 3, + actualDimensions: 2 + } + }); + }); + + it("keeps provider metadata on successful external requests", async () => { + global.fetch = jest.fn().mockResolvedValue({ + ok: true, + json: jest.fn().mockResolvedValue({ + data: [{ embedding: [0.1, 0.2] }] + }) + }) as never; + const config = new AppConfigService( + createConfigServiceMock({ + NODE_ENV: "development", + EMBEDDING_MOCK_MODE: "false", + EMBEDDING_PROVIDER: "openai", + EMBEDDING_MODEL: "embedding-v1", + EMBEDDING_VECTOR_VERSION: "env-vector" + }) as ConfigService + ); + const service = new EmbeddingRouterService( + config, + createRagTaskConfigServiceMock({ + taskType: "embedding", + provider: "openai", + model: "embedding-v1", + baseUrl: "https://embedding.example/v1", + apiKey: "test-key", + dimensions: 2, + vectorVersion: "runtime-vector", + timeoutMs: 1000, + configSource: "settings", + configId: "embedding-config-1" + }) as RagTaskConfigService + ); + + const vectors = await service.embed({ + texts: ["orders"], + indexVersion: "idx-v2", + scope: "datasource", + assetType: "rag_chunk" + }); + + expect(vectors).toEqual([ + { + vector: [0.1, 0.2], + metadata: { + provider: "openai", + model: "embedding-v1", + dimensions: 2, + vectorVersion: "runtime-vector", + configSource: "settings", + configId: "embedding-config-1", + indexVersion: "idx-v2", + scope: "datasource", + assetType: "rag_chunk" + } + } + ]); + }); +}); diff --git a/apps/backend/test/unit/text2sql-v2-langgraph-nodes.spec.ts b/apps/backend/test/unit/text2sql-v2-langgraph-nodes.spec.ts new file mode 100644 index 0000000..839937a --- /dev/null +++ b/apps/backend/test/unit/text2sql-v2-langgraph-nodes.spec.ts @@ -0,0 +1,769 @@ +import { ClarifyNode } from "../../src/modules/conversation/agent/nodes/clarify.node"; +import { FormatAnswerNode } from "../../src/modules/conversation/agent/nodes/format-answer.node"; +import { IntakeNode } from "../../src/modules/conversation/nodes/intake.node"; +import { AssembleContextNode } from "../../src/modules/conversation/nodes/assemble-context.node"; +import { SemanticPlanNode } from "../../src/modules/conversation/nodes/semantic-plan.node"; +import { GenerateSqlNode } from "../../src/modules/conversation/nodes/generate-sql.node"; +import { ValidateSqlNode } from "../../src/modules/conversation/nodes/validate-sql.node"; +import { CorrectSqlNode } from "../../src/modules/conversation/nodes/correct-sql.node"; +import { ExecuteSqlNode } from "../../src/modules/conversation/nodes/execute-sql.node"; +import { AnswerNode } from "../../src/modules/conversation/nodes/answer.node"; +import { SemanticContextPackService } from "../../src/modules/conversation/adapters/semantic-context-pack.service"; +import { SemanticPlanService } from "../../src/modules/conversation/adapters/semantic-plan.service"; +import { SemanticPlanValidator } from "../../src/modules/conversation/adapters/semantic-plan.validator"; +import { SqlValidationService } from "../../src/modules/conversation/adapters/sql-validation.service"; +import { SqlCorrectionService } from "../../src/modules/conversation/adapters/sql-correction.service"; +import type { SemanticPlanV1 } from "@text2sql/shared-types"; + +describe("text2sql v2 langgraph nodes", () => { + const readyPlan: SemanticPlanV1 = { + route: "answer", + standaloneQuestion: "统计订单总数", + selectedTables: ["orders"], + selectedColumns: ["orders.id"], + confidence: 0.9, + evidenceRefs: ["chunk-orders-1"], + filters: ["route_kind:text_to_sql"], + snapshotId: "semantic-plan:text-to-sql:ready:t1:c1:e1:g0:orders" + }; + + describe("intake node", () => { + const node = new IntakeNode(new ClarifyNode()); + + it("routes metadata and general questions to no-sql direct answers", () => { + expect(node.run({ question: "有哪些表" })).toMatchObject({ + route: "metadata", + semanticIntent: "metadata", + directAnswer: + "这是元数据问题，我会基于可访问的表结构与语义证据直接说明，不执行 SQL。" + }); + + expect(node.run({ question: "什么是 GMV 口径？" })).toMatchObject({ + route: "general", + semanticIntent: "general" + }); + }); + + it("routes unsafe and unsupported requests to fail-closed compatible intake failures", () => { + expect(node.run({ question: "DELETE FROM orders" })).toMatchObject({ + route: "unsafe", + failure: { + code: "INTAKE_UNSAFE_REQUEST", + terminal: true, + correctable: false + } + }); + + expect(node.run({ question: "帮我发邮件给财务" })).toMatchObject({ + route: "unsupported", + failure: { + code: "INTAKE_UNSUPPORTED_REQUEST", + terminal: true, + correctable: false + } + }); + }); + + it("routes incomplete questions to clarification and rewrites follow-up questions with context", () => { + const clarification = node.run({ question: "统计 GMV" }); + expect(clarification.route).toBe("needs_clarification"); + expect(clarification.clarification?.question).toContain("分析对象"); + + const followUp = node.run({ + question: "那最近30天呢", + contextEnvelope: { + metricDefinition: "GMV", + pinnedTables: ["orders"] + } + }); + expect(followUp.standaloneQuestion).toContain("context:"); + expect(followUp.standaloneQuestion).toContain("metric=GMV"); + expect(followUp.standaloneQuestion).toContain("tables=orders"); + }); + + it("routes complete analytical questions to text_to_sql", () => { + expect(node.run({ question: "近30天订单总数" })).toMatchObject({ + route: "text_to_sql" + }); + }); + }); + + describe("semantic-plan node", () => { + const service = new SemanticPlanService(new SemanticPlanValidator()); + const node = new SemanticPlanNode(service); + + it("maps validation outcomes to graph routes", () => { + expect( + node.run({ + question: "统计订单总数", + contextPack: { + status: "ready", + selectedEvidenceIds: ["chunk-orders-1"], + selectedTables: ["orders"], + selectedColumns: ["orders.id"] + } + }).route + ).toBe("ready"); + + expect( + node.run({ + question: "什么是 GMV 口径？", + contextPack: { + status: "ready", + selectedEvidenceIds: ["metric.gmv"], + selectedTables: [], + selectedColumns: [] + } + }).route + ).toBe("direct_answer"); + + expect( + node.run({ + question: "统计 GMV", + contextPack: { + status: "degraded", + selectedEvidenceIds: [], + selectedTables: [], + selectedColumns: [], + warnings: ["clarification_round:2", "clarification_max_rounds:2"] + } + }).route + ).toBe("fail_closed"); + }); + }); + + describe("assemble-context node", () => { + const node = new AssembleContextNode(new SemanticContextPackService()); + + it("emits rich context-pack fields and typed summary counts without raw snippets", () => { + const result = node.run({ + retrievalBundle: { + status: "degraded", + selected_context: [ + { + chunk_id: "schema-orders", + content: "orders schema", + metadata: { + tableNames: ["Orders"], + columnNames: ["Orders.Id"] + } + } + ], + context_pack: { + lane_metadata: [ + { + lane: "dense", + state: "unavailable", + unavailable_reason: "provider_missing", + reason_codes: ["embedding_provider_missing"], + evidence_ids: ["dense.orders.1"] + }, + { + lane: "metric", + state: "ready", + evidence_ids: ["metric.gmv"], + reason_codes: ["metric_binding_selected"] + } + ], + pruning_decisions: [ + { + budget_source: "context_pack", + kept_evidence_ids: ["schema-orders"], + removed_evidence_ids: ["dense.orders.1"], + reason_codes: ["token_budget_limited"], + summary: "removed low confidence dense chunk" + } + ], + permission_filtering: { + status: "applied", + denied_evidence_ids: ["secret-chunk"], + denied_table_names: ["secret_orders"], + denied_column_names: ["secret_orders.internal_note"], + reason_codes: ["permission_filtered_not_in_allowed_tables"] + }, + semantic_bindings: { + model_keys: ["model.orders"], + metric_keys: ["metric.gmv"] + } + }, + degrade_reasons: ["lexical_fallback_used"] + }, + additionalWarnings: ["context_source_disclosure:retrieval_bundle"] + }); + + expect(result.contextPack.version).toBe("v1.rich"); + expect(result.contextPack.capabilities).toEqual( + expect.arrayContaining([ + "selected_context_summary", + "structured_lanes", + "structured_degradation", + "structured_pruning", + "structured_permission_filtering" + ]) + ); + expect(result.contextPack.selectedContextSummary).toMatchObject({ + count: 1, + evidenceIds: expect.arrayContaining(["schema-orders"]) + }); + expect(result.contextPack.selectedContextSummary).toEqual( + expect.not.objectContaining({ snippets: expect.anything() }) + ); + expect(result.contextPack.degradation).toMatchObject({ + status: "degraded", + reasons: ["lexical_fallback_used"] + }); + expect(result.contextPack.permissionFiltering).toMatchObject({ + status: "applied", + deniedEvidenceCount: 1 + }); + expect(result.typedSummary).toMatchObject({ + status: "degraded", + version: "v1.rich", + capabilityCount: expect.any(Number), + selectedEvidenceCount: expect.any(Number), + degradedLaneCount: 1, + permissionDeniedEvidenceCount: 1 + }); + expect(result.evidenceRefs).toEqual( + expect.arrayContaining(["schema-orders", "dense.orders.1", "metric.gmv"]) + ); + }); + }); + + describe("generate-sql node", () => { + it("returns a structured artifact with cause, evidence, used tables and columns", async () => { + const sqlGenerationService = { + generate: jest.fn().mockResolvedValue({ + provider: "volcengine", + model: "mock-model", + sql: "SELECT orders.id, orders.amount FROM orders", + explanation: "Use the grounded orders table.", + rawText: "SELECT orders.id, orders.amount FROM orders", + prompt: { + systemPrompt: "system", + userPrompt: "user" + }, + promptTemplate: { + templateId: "tpl-1", + scene: "sql", + scope: "global", + version: 3 + }, + coverage: { + gateStatus: "passed", + missingObjects: [], + triggerSource: "selected_context", + usedObjects: ["table:orders", "column:orders.id", "column:orders.amount"] + }, + semanticPlan: readyPlan + }), + buildStructuredArtifact: jest.fn().mockReturnValue({ + sql: "SELECT orders.id, orders.amount FROM orders", + assumptions: ["Use the grounded orders table."], + usedTables: ["orders"], + usedColumns: ["orders.id", "orders.amount", "id", "amount"], + evidenceRefs: ["chunk-orders-1"], + cause: "initial", + dialect: "sqlite" + }) + }; + const node = new GenerateSqlNode(sqlGenerationService as never); + + const result = await node.run({ + question: "统计订单总数", + datasourceType: "sqlite", + semanticPlan: readyPlan + }); + + expect(sqlGenerationService.generate).toHaveBeenCalled(); + expect(sqlGenerationService.buildStructuredArtifact).toHaveBeenCalledWith({ + draft: expect.objectContaining({ + sql: "SELECT orders.id, orders.amount FROM orders" + }), + datasourceType: "sqlite", + cause: "initial", + retryReason: undefined, + correctionGrounding: undefined + }); + expect(result.artifact).toMatchObject({ + cause: "initial", + usedTables: ["orders"], + evidenceRefs: ["chunk-orders-1"] + }); + }); + + it("passes correction grounding into generation selection and artifact build", async () => { + const correctionGrounding = { + failedSqlRef: "sql.sha256.abc123abc123abcd", + retryReason: "missing column orders.missing_city", + attemptCount: 1, + maxAttempts: 2, + evidenceRefs: ["chunk-orders-1"] + }; + const sqlGenerationService = { + generate: jest.fn().mockResolvedValue({ + provider: "volcengine", + model: "mock-model", + sql: "SELECT orders.id FROM orders", + explanation: "retry with corrected column", + rawText: "SELECT orders.id FROM orders", + prompt: { + systemPrompt: "system", + userPrompt: "user" + }, + semanticPlan: readyPlan + }), + buildStructuredArtifact: jest.fn().mockReturnValue({ + sql: "SELECT orders.id FROM orders", + usedTables: ["orders"], + usedColumns: ["orders.id", "id"], + evidenceRefs: ["chunk-orders-1"], + cause: "correction", + dialect: "sqlite", + correctionGrounding + }) + }; + const node = new GenerateSqlNode(sqlGenerationService as never); + + await node.run({ + question: "统计订单总数", + datasourceType: "sqlite", + semanticPlan: readyPlan, + cause: "correction", + retryReason: "missing column orders.missing_city", + correctionGrounding + }); + + expect(sqlGenerationService.generate).toHaveBeenCalledWith( + "统计订单总数", + expect.objectContaining({ + correctionGrounding + }) + ); + expect(sqlGenerationService.buildStructuredArtifact).toHaveBeenCalledWith( + expect.objectContaining({ + cause: "correction", + retryReason: "missing column orders.missing_city", + correctionGrounding + }) + ); + }); + + it("rejects non text-to-sql semantic plans before generation", async () => { + const node = new GenerateSqlNode({ + generate: jest.fn(), + stream: jest.fn(), + buildStructuredArtifact: jest.fn() + } as never); + + for (const routeKind of ["metadata", "general", "clarify", "fail_closed"]) { + await expect( + node.run({ + question: "有哪些表", + semanticPlan: { + ...readyPlan, + route: + routeKind === "clarify" + ? "clarify" + : routeKind === "fail_closed" + ? "reject" + : "answer", + filters: [`route_kind:${routeKind}`] + } + }) + ).rejects.toMatchObject({ + code: "SEMANTIC_PLAN_DIRECT_ANSWER_REQUIRED", + details: expect.objectContaining({ + routeKind + }) + }); + } + }); + }); + + describe("validate-sql node", () => { + const node = new ValidateSqlNode(new SqlValidationService()); + + it("emits pass, correctable and terminal outcomes", async () => { + await expect( + node.run({ + sql: "SELECT COUNT(*) FROM orders", + semanticPlan: readyPlan, + datasourceType: "sqlite" + }) + ).resolves.toMatchObject({ outcome: "pass" }); + + await expect( + node.run({ + sql: "show tables", + semanticPlan: readyPlan, + datasourceType: "sqlite" + }) + ).resolves.toMatchObject({ + outcome: "correctable", + artifact: { + failure: { + code: "SQL_PARSE_UNSUPPORTED_STATEMENT" + } + } + }); + + await expect( + node.run({ + sql: "DELETE FROM orders", + semanticPlan: readyPlan, + datasourceType: "sqlite" + }) + ).resolves.toMatchObject({ + outcome: "terminal", + artifact: { + failure: { + code: "SQL_READ_ONLY_VIOLATION" + } + } + }); + }); + }); + + describe("correct-sql node", () => { + const node = new CorrectSqlNode(new SqlCorrectionService()); + + it("increments correction budget and routes back to generation for correctable failures", () => { + const result = node.run({ + failedSql: "SELECT missing_city FROM orders", + attemptCount: 0, + semanticPlan: readyPlan, + contextPack: { + status: "ready", + selectedEvidenceIds: ["chunk-orders-1"], + selectedTables: ["orders"], + selectedColumns: ["orders.id"] + }, + validationArtifact: { + status: "failed", + checks: [], + correctable: true, + failure: { + code: "SQL_MISSING_COLUMN", + message: "missing column orders.missing_city", + category: "validation", + terminal: false, + correctable: true + } + } + }); + + expect(result).toMatchObject({ + outcome: "retry_generation", + budget: { + attemptCount: 1, + maxAttempts: 2, + remainingAttempts: 1, + exhausted: false + }, + artifact: { + shouldRevalidate: true, + semanticPlanSnapshotId: readyPlan.snapshotId, + evidenceRefs: ["chunk-orders-1"], + grounding: { + failedSqlRef: expect.stringMatching(/^sql\.sha256\.[0-9a-f]{16}$/), + retryReason: "missing column orders.missing_city", + failureCode: "SQL_MISSING_COLUMN", + failureCategory: "validation", + source: "validation", + attemptCount: 1, + maxAttempts: 2, + semanticPlanSnapshotId: readyPlan.snapshotId, + contextPackStatus: "ready", + contextPackEvidenceCount: 1 + } + } + }); + }); + + it("keeps governance and exhausted retries terminal", () => { + expect( + node.run({ + failedSql: "DELETE FROM orders", + attemptCount: 0, + validationArtifact: { + status: "failed", + checks: [], + correctable: false, + failure: { + code: "SQL_READ_ONLY_VIOLATION", + message: "read-only violation", + category: "governance", + terminal: true, + correctable: false + } + } + }) + ).toMatchObject({ + outcome: "terminal", + failure: { + code: "SQL_READ_ONLY_VIOLATION", + category: "governance", + terminal: true + } + }); + + expect( + node.run({ + failedSql: "SELECT missing_city FROM orders", + attemptCount: 1, + validationArtifact: { + status: "failed", + checks: [], + correctable: true, + failure: { + code: "SQL_MISSING_COLUMN", + message: "missing column orders.missing_city", + category: "validation", + terminal: false, + correctable: true + } + } + }) + ).toMatchObject({ + outcome: "terminal", + failure: { + code: "SQL_CORRECTION_BUDGET_EXHAUSTED", + terminal: true + } + }); + }); + }); + + describe("execute-sql node", () => { + it("requires passed validation before execution", async () => { + const node = new ExecuteSqlNode({ + run: jest.fn() + } as never); + + await expect( + node.run({ + sql: "SELECT 1", + validationArtifact: { + status: "failed", + checks: [], + correctable: false, + failure: { + code: "SQL_READ_ONLY_VIOLATION", + message: "blocked", + category: "governance", + terminal: true, + correctable: false + } + }, + datasourceId: "ds-1", + sessionId: "session-1" + }) + ).rejects.toMatchObject({ + code: "SQL_EXECUTE_PRECONDITION_FAILED" + }); + }); + + it("delegates execution and returns row-count metadata after pass", async () => { + const legacyNode = { + run: jest.fn().mockResolvedValue({ + rows: [{ total: 3 }], + columns: ["total"] + }) + }; + const node = new ExecuteSqlNode(legacyNode as never); + + await expect( + node.run({ + sqlArtifact: { + sql: "SELECT COUNT(*) AS total FROM orders", + usedTables: ["orders"], + usedColumns: ["total"], + evidenceRefs: ["chunk-orders-1"], + cause: "initial", + dialect: "sqlite", + claimedObligationIds: ["ledger:table:orders"] + }, + validationArtifact: { + status: "passed", + checks: [], + correctable: false + }, + datasourceId: "ds-1", + sessionId: "session-1", + semanticPlan: readyPlan + }) + ).resolves.toMatchObject({ + rowCount: 1, + emptyResult: false, + columns: ["total"] + }); + expect(legacyNode.run).toHaveBeenCalledWith( + expect.objectContaining({ + sql: "SELECT COUNT(*) AS total FROM orders", + sqlArtifact: expect.objectContaining({ + claimedObligationIds: ["ledger:table:orders"] + }) + }) + ); + }); + }); + + describe("answer node", () => { + const node = new AnswerNode(new FormatAnswerNode()); + + it("unifies execution success, direct-answer and fail-closed terminals", () => { + expect( + node.run({ + question: "统计订单总数", + executionResult: { + rows: [{ total: 3 }], + columns: ["total"], + rowCount: 1, + emptyResult: false + }, + sqlArtifact: { + sql: "SELECT COUNT(*) AS total FROM orders", + usedTables: ["orders"], + usedColumns: ["total"], + evidenceRefs: ["chunk-orders-1"], + cause: "initial", + dialect: "sqlite" + } + }) + ).toMatchObject({ + mode: "execution_result", + status: "executionResult", + evidenceRefs: ["chunk-orders-1"] + }); + + expect( + node.run({ + question: "什么是 GMV 口径？", + directAnswer: "这是通用说明问题，不需要执行 SQL；我会基于已有语义证据直接解释。" + }) + ).toMatchObject({ + mode: "direct_answer", + status: "executionResult" + }); + + expect( + node.run({ + question: "DELETE FROM orders", + failure: { + code: "SQL_READ_ONLY_VIOLATION", + message: "检测到写操作或 DDL，已阻止执行", + category: "governance", + terminal: true, + correctable: false + } + }) + ).toMatchObject({ + mode: "fail_closed", + status: "rejected" + }); + }); + + it("does not label provider generation failures as governance fail-closed", () => { + const result = node.run({ + question: "有多少种支付方式，他们比例是如何", + failure: { + code: "LLM_REQUEST_FAILED", + message: "LLM 请求失败: The operation was aborted due to timeout", + category: "generation", + terminal: true, + correctable: false + } + }); + + expect(result).toMatchObject({ + mode: "execution_failure", + status: "failed" + }); + expect(result.answer).toContain("SQL 生成或服务调用阶段"); + expect(result.answer).not.toContain("安全或治理校验"); + }); + + it("builds evidence-grounded metadata direct answers and keeps general direct answers lightweight", () => { + const metadataAnswer = node.run({ + question: "有哪些表", + directAnswer: + "这是元数据问题，我会基于可访问的表结构与语义证据直接说明，不执行 SQL。", + semanticPlan: { + ...readyPlan, + filters: ["route_kind:metadata"], + selectedTables: ["orders"], + selectedColumns: ["orders.id", "orders.amount"], + evidenceRefs: ["schema-orders", "metric-gmv"] + }, + contextPack: { + status: "degraded", + selectedEvidenceIds: ["schema-orders", "metric-gmv"], + selectedTables: ["orders"], + selectedColumns: ["orders.id", "orders.amount"], + selectedContextSummary: { + count: 2, + evidenceIds: ["schema-orders", "metric-gmv"], + laneNames: ["schema", "metric"] + }, + lanes: { + schemaSupplementRefs: { + refs: ["schema-supplement-1"], + count: 1 + } + }, + pruning: { + applied: true, + decisions: [ + { + keptCount: 2, + removedCount: 1, + reasonCodes: ["token_budget_limited"] + } + ] + }, + permissionFiltering: { + status: "applied", + deniedEvidenceCount: 1, + deniedEvidenceIds: ["secret-chunk"], + deniedTables: ["secret_orders"], + reasonCodes: ["permission_filtered_not_in_allowed_tables"] + }, + degradation: { + status: "degraded", + reasons: ["lexical_fallback_used"] + }, + laneStates: [ + { + lane: "dense", + state: "unavailable", + reasonCodes: ["embedding_provider_missing"] + } + ], + warnings: ["dense_unavailable:embedding_provider_missing"] + } + }); + + expect(metadataAnswer).toMatchObject({ + mode: "direct_answer", + status: "executionResult", + evidenceRefs: expect.arrayContaining(["schema-orders", "metric-gmv"]) + }); + expect(metadataAnswer.answer).toContain("元数据证据摘要：已选中 2 条上下文证据。"); + expect(metadataAnswer.answer).toContain("裁剪情况：已触发"); + expect(metadataAnswer.answer).toContain("权限过滤：已应用"); + expect(metadataAnswer.answer).toContain("证据质量：degraded"); + expect(metadataAnswer.answer).not.toContain("secret_orders"); + + const generalAnswer = node.run({ + question: "什么是 GMV 口径？", + directAnswer: "这是通用说明问题，不需要执行 SQL；我会基于已有语义证据直接解释。", + semanticPlan: { + ...readyPlan, + filters: ["route_kind:general"] + } + }); + expect(generalAnswer.answer).not.toContain("元数据证据摘要"); + }); + }); +}); diff --git a/apps/backend/test/unit/text2sql-v2-langgraph-result.mapper.spec.ts b/apps/backend/test/unit/text2sql-v2-langgraph-result.mapper.spec.ts new file mode 100644 index 0000000..4ab7595 --- /dev/null +++ b/apps/backend/test/unit/text2sql-v2-langgraph-result.mapper.spec.ts @@ -0,0 +1,367 @@ +import { DomainError } from "../../src/common/domain-error"; +import type { + ExecutionTraceStep, + SqlRun, + Text2SqlV2StageArtifact +} from "@text2sql/shared-types"; +import { Text2SqlV2ArtifactBuilder } from "../../src/modules/conversation/artifacts/text2sql-v2-artifact-builder"; +import { Text2SqlV2LangGraphResultMapper } from "../../src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph-result.mapper"; +import { + createText2SqlV2LangGraphInitialState, + type Text2SqlV2LangGraphNodeName +} from "../../src/modules/conversation/runtime/langgraph/text2sql-v2-langgraph.state"; +import type { AnswerNodeResult } from "../../src/modules/conversation/nodes/answer.node"; + +const createPreparedRunContext = () => + ({ + runId: "run-v2-langgraph", + requestId: "req-v2-langgraph", + question: "统计订单总数", + session: { + id: "session-v2-langgraph", + datasource: "sqlite_main", + modelProvider: "volcengine", + modelName: "mock-model" + }, + datasource: { + id: "sqlite_main", + type: "sqlite" + }, + sqlAccessContext: undefined, + contextEnvelope: undefined, + userPersistResult: { + primaryPersisted: true + } + }) as never; + +describe("Text2SqlV2LangGraphResultMapper", () => { + const mapper = new Text2SqlV2LangGraphResultMapper( + new Text2SqlV2ArtifactBuilder() + ); + + it("maps graph state into canonical v2 artifact with graph-artifact-first semantics", () => { + const state = { + ...createText2SqlV2LangGraphInitialState({ + preparedRun: createPreparedRunContext(), + route: "/api/v1/sessions/:sessionId/messages", + streamMode: false + }), + stageProgress: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "execute", + "answer" + ] as Text2SqlV2LangGraphNodeName[], + stageArtifacts: [ + { stage: "intake", status: "success" }, + { stage: "retrieve", status: "success" }, + { stage: "assemble-context", status: "success" }, + { stage: "semantic-plan", status: "success" }, + { stage: "generate-sql", status: "success" }, + { stage: "validate", status: "success" }, + { stage: "execute", status: "success" }, + { stage: "answer", status: "success" } + ] as Text2SqlV2StageArtifact[], + traceSteps: [ + { + node: "intake", + status: "success", + at: "2026-04-27T00:00:00.000Z" + }, + { + node: "answer", + status: "success", + at: "2026-04-27T00:00:01.000Z" + } + ] as ExecutionTraceStep[], + contextPack: { + status: "ready", + selectedEvidenceIds: ["chunk-orders-1"], + selectedTables: ["orders"], + selectedColumns: ["orders.id"] + }, + semanticPlan: { + route: "answer", + standaloneQuestion: "统计订单总数", + selectedTables: ["orders"], + selectedColumns: ["orders.id"], + confidence: 0.9, + evidenceRefs: ["chunk-orders-1"], + filters: ["route_kind:text_to_sql"], + snapshotId: "semantic-plan-v1", + planLedger: { + version: "plan-ledger.v1", + snapshotId: "semantic-plan-v1", + obligations: [ + { + id: "ledger:table:orders", + kind: "table", + summary: "orders table", + criticality: "hard_blocker", + status: "fulfilled", + evidenceRefs: ["chunk-orders-1"], + reasonCodes: ["selected_table_grounded"], + subject: "orders" + } + ], + summary: { + snapshotId: "semantic-plan-v1", + total: 1, + hardBlockerCount: 1, + warningCount: 0, + fulfilledCount: 1, + failedCount: 0, + failedHardBlockerIds: [] + } + } + }, + sqlGenerationArtifact: { + sql: "SELECT COUNT(*) AS total FROM orders", + assumptions: ["count orders"], + usedTables: ["orders"], + usedColumns: ["orders.id"], + evidenceRefs: ["chunk-orders-1"], + cause: "initial", + dialect: "sqlite" + }, + sqlValidationArtifact: { + status: "passed", + checks: [], + correctable: false, + ledgerFulfillment: { + snapshotId: "semantic-plan-v1", + total: 1, + hardBlockerCount: 1, + warningCount: 0, + fulfilledCount: 1, + failedCount: 0, + failedHardBlockerIds: [] + } + }, + executionResult: { + rows: [{ total: 10 }], + columns: ["total"], + rowCount: 1, + emptyResult: false + }, + answerResult: { + mode: "execution_result", + answer: "订单总数为 10", + status: "executionResult", + evidenceRefs: ["chunk-orders-1"], + warnings: [] + } as AnswerNodeResult + }; + + const mapped = mapper.mapSqlRun(state as never); + + expect(mapped.status).toBe("executionResult"); + expect(mapped.answer).toBe("订单总数为 10"); + expect(mapped.trace.v2?.version).toBe("v2"); + expect(mapped.trace.v2?.stageOrder).toEqual([ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ]); + expect(mapped.trace.v2?.stages.find((item) => item.stage === "correct")?.status).toBe( + "skipped" + ); + expect( + mapped.trace.v2?.runtimePlan?.items.find((item) => item.stage === "generate-sql") + ).toMatchObject({ + id: "runtime-plan:generate-sql", + stage: "generate-sql", + status: "completed" + }); + expect( + mapped.trace.v2?.runtimePlan?.items.find((item) => item.stage === "correct") + ).toMatchObject({ + id: "runtime-plan:correct", + stage: "correct", + status: "skipped", + reasonCodes: ["validation_passed"] + }); + expect(mapped.trace.v2?.planLedger).toMatchObject({ + snapshotId: "semantic-plan-v1", + total: 1, + hardBlockerCount: 1, + warningCount: 0, + fulfilledCount: 1, + failedCount: 0 + }); + }); + + it("preserves valid runtime intelligence fields and ignores malformed optional fields", () => { + const builder = new Text2SqlV2ArtifactBuilder(); + const baseRun = { + runId: "run-runtime-intelligence", + sessionId: "session-runtime-intelligence", + question: "统计订单总数", + status: "executionResult", + provider: "volcengine", + sql: "SELECT COUNT(*) AS total FROM orders", + answer: "订单总数为 10", + trace: { + runId: "run-runtime-intelligence", + provider: "volcengine", + retryCount: 0, + steps: [], + v2: { + version: "v2", + stageOrder: [], + stages: [ + { + stage: "intake", + status: "success" + } + ], + runtimePlan: { + version: "runtime-plan.v1", + items: [ + { + id: "plan:intake", + stage: "intake", + goal: "Classify request intent.", + status: "completed", + reasonCodes: ["intake_ready_for_text_to_sql"] + } + ] + }, + artifactRefs: [ + { + id: "artifact:context:orders", + category: "context_snippets", + summary: "Compacted order context.", + hash: "sha256:orders", + visibility: "user", + sensitivity: "none" + }, + { + id: "artifact:bad", + category: "context_snippets", + summary: "missing hash", + visibility: "user" + } + ], + smartDefaults: { + bundleId: "text2sql-smart-defaults", + version: "2026-04-28", + coveredStages: ["generate-sql", "answer"], + ruleIds: ["only-use-context-pack"], + status: "applied" + } + } + }, + llmRaw: null, + createdAt: "2026-04-28T00:00:00.000Z" + } as unknown as SqlRun; + + const artifact = builder.buildRunArtifact(baseRun); + + expect(artifact.runtimePlan?.items).toEqual([ + { + id: "plan:intake", + stage: "intake", + goal: "Classify request intent.", + status: "completed", + reasonCodes: ["intake_ready_for_text_to_sql"] + } + ]); + expect(artifact.artifactRefs).toEqual([ + { + id: "artifact:context:orders", + category: "context_snippets", + summary: "Compacted order context.", + hash: "sha256:orders", + visibility: "user", + sensitivity: "none" + } + ]); + expect(artifact.smartDefaults?.bundleId).toBe("text2sql-smart-defaults"); + + const oldRunArtifact = builder.buildRunArtifact({ + ...baseRun, + trace: { + ...baseRun.trace, + v2: { + version: "v2", + stageOrder: [], + stages: [ + { + stage: "intake", + status: "success" + } + ] + } + } + }); + expect(oldRunArtifact.runtimePlan).toBeUndefined(); + expect(oldRunArtifact.artifactRefs).toBeUndefined(); + expect(oldRunArtifact.smartDefaults).toBeUndefined(); + }); + + it("returns stream-safe progress summary without exposing raw graph state", () => { + const state = { + ...createText2SqlV2LangGraphInitialState({ + preparedRun: createPreparedRunContext(), + route: "/api/v1/sessions/:sessionId/messages/stream", + streamMode: true + }), + stageProgress: [ + "intake", + "retrieve", + "assemble-context", + "answer" + ] as Text2SqlV2LangGraphNodeName[], + stageArtifacts: [], + traceSteps: [], + answerResult: { + mode: "direct_answer", + answer: "不需要执行 SQL，直接解释。", + status: "executionResult", + evidenceRefs: [], + warnings: [] + } as AnswerNodeResult + }; + + const summary = mapper.mapProgressSummary(state as never); + + expect(summary.enteredStageCount).toBe(4); + expect(summary.enteredStages).toEqual([ + "intake", + "retrieve", + "assemble-context", + "answer" + ]); + }); + + it("throws domain error when graph result has no answer or terminal failure", () => { + const state = { + ...createText2SqlV2LangGraphInitialState({ + preparedRun: createPreparedRunContext(), + route: "/api/v1/sessions/:sessionId/messages", + streamMode: false + }), + stageProgress: ["intake"] as Text2SqlV2LangGraphNodeName[], + stageArtifacts: [], + traceSteps: [], + answerResult: undefined, + failure: undefined + }; + + expect(() => mapper.mapSqlRun(state as never)).toThrow(DomainError); + expect(() => mapper.mapSqlRun(state as never)).toThrow( + "LangGraph runtime completed without answer or terminal failure" + ); + }); +}); diff --git a/apps/backend/test/unit/text2sql-v2-langgraph-runtime.spec.ts b/apps/backend/test/unit/text2sql-v2-langgraph-runtime.spec.ts new file mode 100644 index 0000000..2fa58a2 --- /dev/null +++ b/apps/backend/test/unit/text2sql-v2-langgraph-runtime.spec.ts @@ -0,0 +1,33 @@ +import { Annotation, END, START, StateGraph } from "@langchain/langgraph"; + +describe("Text2SQL v2 LangGraph runtime baseline", () => { + it("compiles and invokes a minimal StateGraph under the backend Jest toolchain", async () => { + const RuntimeState = Annotation.Root({ + path: Annotation({ + reducer: (left, right) => + left.concat(Array.isArray(right) ? right : [right]), + default: () => [] + }), + compiled: Annotation({ + reducer: (_left, right) => right, + default: () => false + }) + }); + + const graph = new StateGraph(RuntimeState) + .addNode("bootstrap", () => ({ + path: ["bootstrap"], + compiled: true + })) + .addEdge(START, "bootstrap") + .addEdge("bootstrap", END) + .compile(); + + const result = await graph.invoke({}); + + expect(result).toEqual({ + path: ["bootstrap"], + compiled: true + }); + }); +}); diff --git a/apps/backend/test/unit/text2sql-v2-runner.spec.ts b/apps/backend/test/unit/text2sql-v2-runner.spec.ts new file mode 100644 index 0000000..b094c13 --- /dev/null +++ b/apps/backend/test/unit/text2sql-v2-runner.spec.ts @@ -0,0 +1,126 @@ +import type { SqlRun } from "@text2sql/shared-types"; +import { Text2SqlV2ArtifactBuilder } from "../../src/modules/conversation/artifacts/text2sql-v2-artifact-builder"; +import { createText2SqlV2StageLifecycle } from "../../src/modules/conversation/artifacts/text2sql-v2-artifacts"; + +const createBaseRun = (overrides: Partial = {}): SqlRun => + ({ + runId: "run-v2-artifacts", + sessionId: "session-v2-artifacts", + question: "统计订单总数", + status: "executionResult", + provider: "volcengine", + model: "mock-model", + sql: "SELECT COUNT(*) AS total FROM orders", + answer: "订单总数为 10", + rows: [{ total: 10 }], + columns: ["total"], + trace: { + runId: "run-v2-artifacts", + provider: "volcengine", + retryCount: 0, + v2: { + version: "v2", + stageOrder: [ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ], + stages: [ + { stage: "intake", status: "success" }, + { stage: "retrieve", status: "success" }, + { stage: "assemble-context", status: "success" }, + { stage: "semantic-plan", status: "success" }, + { stage: "generate-sql", status: "success" }, + { stage: "validate", status: "success" }, + { stage: "correct", status: "skipped" }, + { stage: "execute", status: "success" }, + { stage: "answer", status: "success" } + ] + }, + steps: [ + { + node: "intake", + status: "success", + at: "2026-04-28T00:00:00.000Z" + }, + { + node: "generate-sql", + status: "success", + at: "2026-04-28T00:00:00.100Z" + }, + { + node: "execute-sql", + status: "success", + at: "2026-04-28T00:00:00.200Z" + }, + { + node: "answer", + status: "success", + at: "2026-04-28T00:00:00.300Z" + } + ] + }, + llmRaw: null, + createdAt: "2026-04-28T00:00:00.400Z", + ...overrides + }) as SqlRun; + +describe("Text2Sql v2 runtime artifacts", () => { + it("normalizes run traces into canonical v2 stage artifacts", () => { + const artifact = new Text2SqlV2ArtifactBuilder().buildRunArtifact(createBaseRun()); + + expect(artifact.version).toBe("v2"); + expect(artifact.stageOrder).toEqual([ + "intake", + "retrieve", + "assemble-context", + "semantic-plan", + "generate-sql", + "validate", + "correct", + "execute", + "answer" + ]); + expect(artifact.stages.find((stage) => stage.stage === "generate-sql")?.status).toBe( + "success" + ); + expect(artifact.stages.find((stage) => stage.stage === "answer")?.status).toBe( + "success" + ); + }); + + it("preserves provider metadata when stage lifecycle emits canonical runtime stages", () => { + const lifecycle = createText2SqlV2StageLifecycle(); + lifecycle.startStage({ + stage: "generate-sql", + provider: { provider: "volcengine", model: "mock-model" } + }); + lifecycle.completeStage({ + stage: "generate-sql", + status: "success", + provider: { provider: "volcengine", model: "mock-model" }, + metadata: { + taskProfile: "sql-generation", + reasoningTier: "high" + } + }); + + const runArtifact = lifecycle.toRunArtifact(); + const generateSqlStage = runArtifact.stages.find((stage) => stage.stage === "generate-sql"); + + expect(generateSqlStage?.provider).toEqual({ + provider: "volcengine", + model: "mock-model" + }); + expect(generateSqlStage?.metadata).toMatchObject({ + taskProfile: "sql-generation", + reasoningTier: "high" + }); + }); +}); diff --git a/apps/backend/test/unit/text2sql-v2-semantic-context-pack.spec.ts b/apps/backend/test/unit/text2sql-v2-semantic-context-pack.spec.ts new file mode 100644 index 0000000..ed1166c --- /dev/null +++ b/apps/backend/test/unit/text2sql-v2-semantic-context-pack.spec.ts @@ -0,0 +1,305 @@ +import { SemanticContextPackService } from "../../src/modules/conversation/adapters/semantic-context-pack.service"; + +describe("text2sql v2 semantic context pack", () => { + const service = new SemanticContextPackService(); + + it("builds a rich versioned contract with structured lanes and selected-context summary", () => { + const pack = service.build({ + retrievalBundle: { + status: "ready", + selected_context: [ + { + chunk_id: "schema-orders", + metadata: { + tableNames: ["Orders"], + columnNames: ["Orders.ID", "Orders.Amount"] + } + }, + { + chunk_id: "example-paid-orders", + metadata: { + tableNames: ["orders"], + columnNames: ["orders.status"] + } + } + ], + context_pack: { + semantic_bindings: { + model_keys: ["model.orders"], + relationship_keys: ["rel.orders_customers"], + metric_keys: ["metric.gmv"], + calculated_field_keys: ["cf.net_amount"] + }, + lane_metadata: [ + { + lane: "relationship", + state: "ready", + evidence_ids: ["rel.orders_customers"], + reason_codes: ["relationship_binding_selected"] + }, + { + lane: "metric", + state: "ready", + evidence_ids: ["metric.gmv"], + reason_codes: ["metric_binding_selected"] + }, + { + lane: "instruction", + state: "ready", + evidence_ids: ["instruction.readonly"], + reason_codes: ["instruction_selected"] + }, + { + lane: "saved_prior_sql", + state: "ready", + evidence_ids: ["prior.sql.001"], + reason_codes: ["prior_sql_selected"] + }, + { + lane: "ddl_supplement", + state: "ready", + evidence_ids: ["ddl.orders"], + reason_codes: ["ddl_supplement_selected"] + } + ] + } + } + }); + + expect(pack.status).toBe("ready"); + expect(pack.version).toBe("v1.rich"); + expect(pack.capabilities).toEqual( + expect.arrayContaining([ + "selected_context_summary", + "semantic_binding_refs", + "structured_lanes" + ]) + ); + expect(pack.selectedEvidenceIds).toEqual( + expect.arrayContaining([ + "schema-orders", + "example-paid-orders", + "rel.orders_customers", + "metric.gmv", + "instruction.readonly", + "prior.sql.001", + "ddl.orders" + ]) + ); + expect(pack.selectedTables).toEqual(["orders", "model.orders"]); + expect(pack.selectedColumns).toEqual([ + "orders.id", + "orders.amount", + "orders.status" + ]); + expect(pack.selectedContextSummary).toMatchObject({ + count: 2 + }); + expect(pack.selectedContextSummary?.evidenceIds).toEqual( + expect.arrayContaining(["schema-orders", "example-paid-orders"]) + ); + expect(pack.selectedContextSummary).toEqual( + expect.not.objectContaining({ snippets: expect.anything() }) + ); + expect(pack.lanes).toMatchObject({ + tables: { + ids: ["orders", "model.orders"], + count: 2 + }, + columns: { + ids: ["orders.id", "orders.amount", "orders.status"], + count: 3 + }, + relationships: { + refs: ["rel.orders_customers"], + count: 1 + }, + metrics: { + refs: ["metric.gmv"], + count: 1 + }, + instructions: { + refs: ["instruction.readonly"], + count: 1 + }, + priorSql: { + refs: ["prior.sql.001"], + count: 1 + }, + schemaSupplementRefs: { + refs: ["ddl.orders"], + count: 1 + }, + semanticBindings: { + modelKeys: ["model.orders"], + relationshipKeys: ["rel.orders_customers"], + metricKeys: ["metric.gmv"], + calculatedFieldKeys: ["cf.net_amount"] + } + }); + expect(pack.laneStates).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + lane: "relationship", + state: "ready", + refs: ["rel.orders_customers"], + reasonCodes: ["relationship_binding_selected"] + }), + expect.objectContaining({ + lane: "metric", + state: "ready", + refs: ["metric.gmv"], + reasonCodes: ["metric_binding_selected"] + }) + ]) + ); + expect(pack.warnings).toEqual( + expect.arrayContaining([ + "relationship_reason:relationship_binding_selected", + "metric_reason:metric_binding_selected", + "instruction_reason:instruction_selected", + "saved_prior_sql_reason:prior_sql_selected", + "ddl_supplement_reason:ddl_supplement_selected" + ]) + ); + }); + + it("records degradation, pruning, and permission filtering as structured artifacts", () => { + const pack = service.build({ + retrievalBundle: { + status: "degraded", + selected_context: [], + degrade_reasons: ["lexical_fallback_used"], + lane_results: { + dense: { + status: "degraded", + degrade_reason: "dense_unavailable:provider_missing" + } + }, + rerank_metadata: { + secondary: { + status: "degraded", + unavailable_reason: "secondary_rerank_timeout" + } + }, + context_pack: { + lane_metadata: [ + { + lane: "dense", + state: "unavailable", + unavailable_reason: "provider_missing", + reason_codes: ["embedding_provider_missing"] + }, + { + lane: "rerank", + state: "degraded", + fallback_reason: "deterministic_primary_ranking", + reason_codes: ["secondary_rerank_timeout"] + } + ], + pruning_decisions: [ + { + budget_source: "token_budget", + reason_codes: ["removed_low_score_examples"], + summary: "removed 3 low-score examples" + } + ], + permission_filtering: { + status: "applied", + denied_evidence_ids: ["chunk-secret-orders"], + denied_table_names: ["secret_orders"], + denied_column_names: ["secret_orders.internal_note"], + reason_codes: ["permission_filtered_not_in_allowed_tables"] + } + }, + permission_filtering: { + status: "applied", + denied_evidence_ids: ["chunk-secret-orders"], + denied_table_names: ["secret_orders"], + denied_column_names: ["secret_orders.internal_note"], + reason_codes: ["permission_filtered_not_in_allowed_tables"] + } + }, + additionalWarnings: ["context_source_disclosure:retrieval_bundle"] + }); + + expect(pack.status).toBe("degraded"); + expect(pack.degradation).toMatchObject({ + status: "degraded", + reasons: ["lexical_fallback_used"], + denseUnavailableReason: "dense_unavailable:dense_unavailable:provider_missing", + rerankUnavailableReason: "rerank_unavailable:secondary_rerank_timeout" + }); + expect(pack.degradation?.laneIssues).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + lane: "dense", + state: "unavailable", + unavailableReason: "provider_missing" + }), + expect.objectContaining({ + lane: "rerank", + state: "degraded", + fallbackReason: "deterministic_primary_ranking" + }) + ]) + ); + expect(pack.pruning).toMatchObject({ + applied: true, + decisions: [ + expect.objectContaining({ + budgetSource: "token_budget", + keptCount: 0, + removedCount: 0, + reasonCodes: ["removed_low_score_examples"], + summary: "removed 3 low-score examples" + }) + ] + }); + expect(pack.permissionFiltering).toMatchObject({ + status: "applied", + deniedEvidenceIds: ["chunk-secret-orders"], + deniedEvidenceCount: 1, + deniedTables: ["secret_orders"], + deniedColumns: ["secret_orders.internal_note"], + reasonCodes: ["permission_filtered_not_in_allowed_tables"] + }); + expect(pack.warnings).toEqual( + expect.arrayContaining([ + "lexical_fallback_used", + "dense_unavailable:dense_unavailable:provider_missing", + "rerank_unavailable:secondary_rerank_timeout", + "dense_state:unavailable", + "rerank_state:degraded", + "dense_unavailable:provider_missing", + "dense_reason:embedding_provider_missing", + "rerank_degraded:deterministic_primary_ranking", + "rerank_reason:secondary_rerank_timeout", + "pruning_summary:removed 3 low-score examples", + "pruning_token_budget:removed_low_score_examples", + "permission_filter_status:applied", + "permission_filter_reason:permission_filtered_not_in_allowed_tables", + "permission_denied_table:secret_orders", + "permission_denied_column:secret_orders.internal_note", + "permission_denied_evidence_count:1", + "context_source_disclosure:retrieval_bundle" + ]) + ); + }); + + it("deduplicates evidence ids and caps large evidence lists", () => { + const pack = service.build({ + selectedContext: Array.from({ length: 80 }, (_, index) => ({ + chunk_id: `chunk-${index % 70}`, + metadata: { + tableNames: ["orders"], + columnNames: ["orders.id"] + } + })) + }); + + expect(pack.selectedEvidenceIds).toHaveLength(64); + expect(new Set(pack.selectedEvidenceIds).size).toBe(64); + expect(pack.selectedContextSummary?.evidenceIds.length).toBeLessThanOrEqual(24); + }); +}); diff --git a/apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts b/apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts new file mode 100644 index 0000000..4eeab4c --- /dev/null +++ b/apps/backend/test/unit/text2sql-v2-semantic-plan.spec.ts @@ -0,0 +1,378 @@ +import { SemanticContextPackService } from "../../src/modules/conversation/adapters/semantic-context-pack.service"; +import { SemanticPlanService } from "../../src/modules/conversation/adapters/semantic-plan.service"; +import { SemanticPlanValidator } from "../../src/modules/conversation/adapters/semantic-plan.validator"; + +describe("text2sql v2 semantic plan", () => { + const contextPackService = new SemanticContextPackService(); + const validator = new SemanticPlanValidator(); + const planService = new SemanticPlanService(validator); + + it("builds selected tables/columns and evidence refs from retrieval context", () => { + const contextPack = contextPackService.build({ + selectedContext: [ + { + chunk_id: "chunk-orders-1", + content: "orders table", + metadata: { + datasourceId: "ds-1", + indexVersionId: "idx-1", + chunkId: "chunk-orders-1", + domain: "schema", + tableNames: ["orders"], + columnNames: ["id", "amount", "status"], + sourceMetadata: {} + } + } + ] + }); + + const result = planService.build({ + question: "统计订单总金额", + contextPack, + semanticIntent: "count", + allowedTables: ["orders", "order_items"] + }); + + expect(result.plan.route).toBe("answer"); + expect(result.validation.routeKind).toBe("text_to_sql"); + expect(result.validation.outcome).toBe("ready"); + expect(result.plan.selectedTables).toEqual(["orders"]); + expect(result.plan.selectedColumns).toEqual(["id", "amount", "status"]); + expect(result.plan.evidenceRefs).toEqual(["chunk-orders-1"]); + expect(result.plan.snapshotId).toBe("semantic-plan:text-to-sql:ready:t1:c3:e1:g0:orders"); + expect(result.plan.coverageGaps).toBeUndefined(); + expect(result.plan.planLedger?.summary.failedHardBlockerIds).toEqual([]); + expect(result.plan.planLedger?.obligations).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + id: "ledger:table:orders", + kind: "table", + criticality: "hard_blocker", + status: "grounded" + }), + expect.objectContaining({ + id: "ledger:column:amount", + kind: "column", + criticality: "hard_blocker", + status: "grounded" + }) + ]) + ); + expect(result.validation.valid).toBe(true); + }); + + it("only promotes question-required schema columns to hard ledger obligations", () => { + const contextPack = contextPackService.build({ + selectedContext: [ + { + chunk_id: "schema-supplement:payments", + content: "payments table", + metadata: { + datasourceId: "ds-1", + indexVersionId: "schema-supplement", + chunkId: "schema-supplement:payments", + domain: "schema", + tableNames: ["payments"], + columnNames: [ + "payments.id", + "payments.payment_no", + "payments.order_id", + "payments.method", + "payments.status", + "payments.amount", + "payments.created_at", + "payments.paid_at" + ], + sourceMetadata: {} + } + } + ] + }); + + const result = planService.build({ + question: "有多少种支付方式，他们比例是如何", + contextPack, + semanticIntent: "count", + allowedTables: ["payments"] + }); + + const columnObligations = + result.plan.planLedger?.obligations.filter((item) => item.kind === "column") ?? []; + expect(columnObligations).toEqual([ + expect.objectContaining({ + id: "ledger:column:payments.method", + criticality: "hard_blocker", + status: "grounded" + }) + ]); + }); + + it("flags unsupported table selections when allowed tables are constrained", () => { + const result = planService.build({ + question: "查询退款单", + contextPack: { + status: "ready", + selectedEvidenceIds: ["chunk-refunds-1"], + selectedTables: ["refunds"], + selectedColumns: ["refunds.id", "refunds.amount"] + }, + allowedTables: ["orders"] + }); + + expect(result.validation.valid).toBe(false); + expect(result.validation.unsupportedTables).toEqual(["refunds"]); + expect(result.validation.reasons).toEqual( + expect.arrayContaining(["plan_contains_unsupported_tables"]) + ); + expect(result.validation.ledgerGateOutcome).toBe("block"); + expect(result.validation.outcome).toBe("fail_closed"); + expect(result.plan.planLedger?.summary.failedHardBlockerIds).toEqual( + expect.arrayContaining(["ledger:table:refunds"]) + ); + }); + + it("maps metadata intent to answer route with metadata route-kind marker", () => { + const result = planService.build({ + question: "有哪些表", + contextPack: { + status: "ready", + selectedEvidenceIds: [], + selectedTables: [], + selectedColumns: [] + } + }); + + expect(result.plan.route).toBe("answer"); + expect(result.validation.routeKind).toBe("metadata"); + expect(result.validation.outcome).toBe("direct_answer"); + expect(result.validation.shouldDirectAnswer).toBe(true); + expect(result.plan.filters).toEqual( + expect.arrayContaining(["route_kind:metadata"]) + ); + }); + + it("maps general business-definition questions to non-SQL answer route", () => { + const result = planService.build({ + question: "什么是 GMV 口径？", + contextPack: { + status: "ready", + selectedEvidenceIds: ["metric.gmv"], + selectedTables: [], + selectedColumns: [] + } + }); + + expect(result.plan.route).toBe("answer"); + expect(result.validation.routeKind).toBe("general"); + expect(result.validation.outcome).toBe("direct_answer"); + expect(result.validation.valid).toBe(true); + expect(result.plan.filters).toEqual( + expect.arrayContaining(["route_kind:general"]) + ); + }); + + it("keeps text_to_sql plan snapshot stable across generation validation and correction consumers", () => { + const result = planService.build({ + question: "按月统计近30天订单 GMV", + contextPack: { + status: "ready", + selectedEvidenceIds: ["chunk-orders", "metric.gmv"], + selectedTables: ["orders", "customers"], + selectedColumns: ["orders.amount", "orders.customer_id", "customers.id"] + }, + allowedTables: ["orders", "customers"] + }); + + const generationPlanSnapshot = result.plan; + const validationPlanSnapshot = result.plan; + const correctionPlanSnapshot = result.plan; + + expect(result.validation.valid).toBe(true); + expect(result.validation.routeKind).toBe("text_to_sql"); + expect(result.validation.outcome).toBe("ready"); + expect(result.plan.metrics).toEqual( + expect.arrayContaining(["gmv", "orders.amount"]) + ); + expect(result.plan.grain).toBe("month"); + expect(result.plan.filters).toEqual( + expect.arrayContaining(["route_kind:text_to_sql", "time_range:relative"]) + ); + expect(result.plan.joinPath).toEqual(["orders->customers"]); + expect(generationPlanSnapshot).toBe(validationPlanSnapshot); + expect(validationPlanSnapshot).toBe(correctionPlanSnapshot); + }); + + it("keeps text-to-sql route when degraded context has no rag grounding", () => { + const result = planService.build({ + question: "统计 GMV", + contextPack: { + status: "degraded", + selectedEvidenceIds: [], + selectedTables: [], + selectedColumns: [], + warnings: ["rag_retrieval_disabled", "dense_reason:rag_retrieval_disabled"] + } + }); + + expect(result.plan.route).toBe("answer"); + expect(result.validation.routeKind).toBe("text_to_sql"); + expect(result.validation.outcome).toBe("ready"); + expect(result.validation.requiresClarification).toBe(false); + expect(result.validation.evidenceComplete).toBe(false); + expect(result.validation.lowConfidence).toBe(true); + expect(result.plan.snapshotId).toBe("semantic-plan:text-to-sql:degraded:t0:c0:e0:g1:none"); + expect(result.plan.coverageGaps).toEqual([ + expect.objectContaining({ + gapType: "evidence_gap", + reasonCode: "missing_selected_evidence_refs", + evidenceRefs: [], + impactScope: "sql_generation" + }) + ]); + expect(result.validation.reasons).toEqual( + expect.arrayContaining([ + "plan_missing_selected_tables", + "plan_missing_grounding_evidence" + ]) + ); + expect(result.plan.planLedger?.summary.failedHardBlockerIds).toEqual([]); + expect(result.plan.planLedger?.summary.warningIds).toEqual( + expect.arrayContaining([ + "ledger:metric:gmv", + "ledger:evidence:time:missing_selected_evidence_refs" + ]) + ); + }); + + it("blocks multi-table SQL generation when relationship evidence is missing", () => { + const result = planService.build({ + question: "统计客户订单数", + contextPack: { + status: "ready", + selectedEvidenceIds: ["chunk-orders", "chunk-customers"], + selectedTables: ["orders", "customers"], + selectedColumns: ["orders.customer_id", "customers.id"], + lanes: { + relationships: { + refs: [], + count: 0 + } + } + }, + allowedTables: ["orders", "customers"] + }); + + expect(result.validation.outcome).toBe("needs_clarification"); + expect(result.validation.ledgerGateOutcome).toBe("block"); + expect(result.plan.planLedger?.obligations).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + kind: "join_path", + status: "failed", + reasonCodes: ["missing_join_path"] + }) + ]) + ); + }); + + it("asks one clarification when grounding is incomplete and budget remains", () => { + const result = planService.build({ + question: "统计活跃用户", + contextPack: { + status: "ready", + selectedEvidenceIds: [], + selectedTables: [], + selectedColumns: [], + warnings: ["clarification_round:1", "clarification_max_rounds:2"] + } + }); + + expect(result.plan.route).toBe("clarify"); + expect(result.validation.requiresClarification).toBe(true); + expect(result.validation.outcome).toBe("needs_clarification"); + expect(result.plan.filters).toEqual( + expect.arrayContaining([ + "route_kind:clarify", + "clarification_round:1", + "clarification_max_rounds:2" + ]) + ); + expect(result.plan.coverageGaps).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + gapType: "user_decision_gap", + reasonCode: "semantic_plan_requires_clarification", + impactScope: "clarification" + }) + ]) + ); + }); + + it("hard-stops to fail-closed route when clarification round budget is exhausted", () => { + const result = planService.build({ + question: "统计 GMV", + contextPack: { + status: "degraded", + selectedEvidenceIds: [], + selectedTables: [], + selectedColumns: [], + warnings: ["clarification_round:2", "clarification_max_rounds:2"] + } + }); + + expect(result.plan.route).toBe("reject"); + expect(result.plan.snapshotId).toBe("semantic-plan:fail-closed:degraded:t0:c0:e0:g2:none"); + expect(result.plan.coverageGaps).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + gapType: "evidence_gap", + reasonCode: "missing_selected_evidence_refs", + evidenceRefs: [], + impactScope: "sql_generation" + }), + expect.objectContaining({ + gapType: "user_decision_gap", + reasonCode: "clarification_budget_exhausted", + evidenceRefs: [], + impactScope: "execution" + }) + ]) + ); + expect(result.validation.routeKind).toBe("fail_closed"); + expect(result.validation.outcome).toBe("fail_closed"); + expect(result.validation.terminal).toBe(true); + }); + + it("rejects malformed coverage gap payloads during validation", () => { + const result = validator.validate({ + plan: { + route: "clarify", + standaloneQuestion: "统计 GMV", + selectedTables: [], + selectedColumns: [], + confidence: 0.3, + evidenceRefs: [], + coverageGaps: [ + { + gapType: "user_decision_gap", + subjectKind: "metric", + reasonCode: "", + evidenceRefs: "chunk-1", + impactScope: "clarification" + } as never + ], + snapshotId: " " + } + }); + + expect(result.valid).toBe(false); + expect(result.reasons).toEqual( + expect.arrayContaining([ + "plan_invalid_coverage_gap_shape", + "plan_missing_coverage_gaps", + "plan_invalid_snapshot_id", + "plan_low_confidence" + ]) + ); + }); +}); diff --git a/apps/backend/test/unit/text2sql-v2-validation.spec.ts b/apps/backend/test/unit/text2sql-v2-validation.spec.ts new file mode 100644 index 0000000..477941d --- /dev/null +++ b/apps/backend/test/unit/text2sql-v2-validation.spec.ts @@ -0,0 +1,411 @@ +import { SqlValidationService } from "../../src/modules/conversation/adapters/sql-validation.service"; + +describe("text2sql v2 sql validation", () => { + const createService = (overrides?: { + dryRun?: boolean; + dryPlan?: boolean; + dryRunComplete?: boolean; + dryRunReason?: string; + dryPlanPass?: boolean; + dryPlanReason?: string; + }) => + new SqlValidationService( + { + getValidationCapabilities: jest.fn(() => ({ + dryRun: overrides?.dryRun ?? true, + dryPlan: overrides?.dryPlan ?? true, + reason: "capability disabled by test" + })), + buildDryPlan: jest.fn(() => ({ + complete: overrides?.dryRunComplete ?? true, + referencedTables: ["orders"], + reason: overrides?.dryRunReason + })) + } as never, + { + evaluateJoinPathConsistency: jest.fn(() => ({ + pass: overrides?.dryPlanPass ?? true, + missingTables: overrides?.dryPlanPass === false ? ["customers"] : [], + reason: overrides?.dryPlanReason + })) + } as never + ); + + const service = createService(); + + const plan = (overrides: Record = {}) => + ({ + route: "answer", + standaloneQuestion: "统计订单", + selectedTables: ["orders"], + selectedColumns: ["orders.id", "orders.amount", "orders.customer_id"], + allowedTables: ["orders"], + confidence: 0.88, + evidenceRefs: ["chunk-orders-1"], + filters: ["route_kind:text_to_sql"], + ...overrides + }) as never; + + it("returns terminal governance failure for read-only violations", async () => { + const result = await service.validate({ + sql: "DELETE FROM orders WHERE id = 1" + }); + + expect(result.status).toBe("failed"); + expect(result.correctable).toBe(false); + expect(service.resolveOutcome(result)).toBe("terminal"); + expect(result.failure?.category).toBe("governance"); + expect(result.failure?.terminal).toBe(true); + expect(result.failure?.code).toBe("SQL_READ_ONLY_VIOLATION"); + }); + + it("returns correctable validation failure for parse errors", async () => { + const result = await service.validate({ + sql: "show tables" + }); + + expect(result.status).toBe("failed"); + expect(result.correctable).toBe(true); + expect(service.resolveOutcome(result)).toBe("correctable"); + expect(result.failure?.category).toBe("validation"); + expect(result.failure?.terminal).toBe(false); + expect(result.failure?.code).toBe("SQL_PARSE_UNSUPPORTED_STATEMENT"); + }); + + it("fails multi-statement parse without attempting dry-run", async () => { + const result = await service.validate({ + sql: "SELECT * FROM orders; SELECT * FROM invoices" + }); + + expect(result.failure?.code).toBe("SQL_PARSE_MULTI_STATEMENT"); + expect(result.correctable).toBe(true); + expect(result.checks.find((check) => check.check === "dry-run")).toMatchObject({ + status: "skipped", + message: "dry-run skipped because parse/read-only check already failed" + }); + }); + + it("fails permission and plan-coverage when SQL goes beyond semantic plan", async () => { + const result = await service.validate({ + sql: "SELECT amount FROM invoices", + semanticPlan: plan({ selectedColumns: ["orders.amount"] }) + }); + + expect(result.status).toBe("failed"); + expect(result.failure?.code).toBe("SQL_TABLE_PERMISSION_DENIED"); + expect(result.failure?.terminal).toBe(true); + expect(result.checks.find((check) => check.check === "plan-coverage")?.status).toBe( + "failed" + ); + }); + + it("fails terminally when selected columns do not allow referenced columns", async () => { + const result = await service.validate({ + sql: "SELECT orders.secret_amount FROM orders", + semanticPlan: plan({ selectedColumns: ["orders.id"] }) + }); + + expect(result.status).toBe("failed"); + expect(result.failure?.code).toBe("SQL_COLUMN_PERMISSION_DENIED"); + expect(result.failure?.category).toBe("governance"); + expect(result.failure?.terminal).toBe(true); + expect(result.correctable).toBe(false); + }); + + it("fails plan coverage correctably when SQL references a table outside selected tables", async () => { + const result = await createService().validate({ + sql: "SELECT COUNT(*) FROM invoices", + semanticPlan: plan({ + allowedTables: ["orders", "invoices"], + selectedTables: ["orders"], + selectedColumns: [] + }) + }); + + expect(result.status).toBe("failed"); + expect(result.failure?.code).toBe("SQL_PLAN_COVERAGE_OUTSIDE_SELECTED_TABLES"); + expect(result.failure?.terminal).toBe(false); + expect(result.correctable).toBe(true); + }); + + it("fails terminally when semantic plan requires clarification", async () => { + const result = await service.validate({ + sql: "SELECT COUNT(*) FROM orders", + semanticPlan: plan({ + route: "clarify", + confidence: 0.32, + filters: ["route_kind:clarify"] + }) + }); + + expect(result.status).toBe("failed"); + expect(result.correctable).toBe(false); + expect(result.failure?.code).toBe("SQL_PLAN_REQUIRES_CLARIFICATION"); + expect(result.failure?.terminal).toBe(true); + }); + + it("allows metadata and general route SQL prechecks without requiring selected tables", async () => { + const result = await service.validate({ + sql: "SELECT 1", + semanticPlan: plan({ + selectedTables: [], + selectedColumns: [], + filters: ["route_kind:metadata"] + }), + datasourceType: "sqlite" + }); + + expect(result.status).toBe("passed"); + expect(service.resolveOutcome(result)).toBe("pass"); + expect(result.checks.find((check) => check.check === "plan-coverage")).toMatchObject({ + status: "passed", + message: "non text-to-sql route" + }); + expect(result.checks.find((check) => check.check === "dry-plan")).toMatchObject({ + status: "skipped", + message: "dry-plan skipped: non text-to-sql route" + }); + }); + + it("fails relationship path when multiple selected tables are not joined", async () => { + const result = await service.validate({ + sql: "SELECT COUNT(*) FROM orders", + semanticPlan: plan({ + selectedTables: ["orders", "customers"], + selectedColumns: [], + allowedTables: ["orders", "customers"], + joinPath: ["orders.customer_id=customers.id"] + }) + }); + + expect(result.status).toBe("failed"); + expect(result.failure?.code).toBe("SQL_RELATIONSHIP_PATH_MISSING_JOIN"); + expect(result.correctable).toBe(true); + }); + + it("reports failed ledger obligation ids as correctable fulfillment misses", async () => { + const result = await service.validate({ + sql: "SELECT COUNT(*) FROM orders", + semanticPlan: plan({ + selectedTables: ["orders", "customers"], + selectedColumns: [], + allowedTables: ["orders", "customers"], + joinPath: ["orders.customer_id=customers.id"], + snapshotId: "semantic-plan-v1", + planLedger: { + version: "plan-ledger.v1", + snapshotId: "semantic-plan-v1", + obligations: [ + { + id: "ledger:join-path:orders-customers", + kind: "join_path", + summary: "orders join customers", + criticality: "hard_blocker", + status: "grounded", + evidenceRefs: ["relationship-orders-customers"], + reasonCodes: ["join_path_grounded"], + subject: "orders->customers" + } + ], + summary: { + snapshotId: "semantic-plan-v1", + total: 1, + hardBlockerCount: 1, + warningCount: 0, + failedHardBlockerIds: [] + } + } + }) + }); + + expect(result.status).toBe("failed"); + expect(result.correctable).toBe(true); + expect(result.failedObligationIds).toEqual(["ledger:join-path:orders-customers"]); + expect(result.checks.find((check) => check.check === "ledger-fulfillment")).toMatchObject({ + status: "failed", + code: "SQL_LEDGER_FULFILLMENT_FAILED", + failedObligationIds: ["ledger:join-path:orders-customers"], + reasonCodes: ["ledger_join_path_not_used"] + }); + expect(result.ledgerFulfillment?.failedHardBlockerIds).toEqual([ + "ledger:join-path:orders-customers" + ]); + }); + + it("passes grouped count proportion SQL when only the required schema column is used", async () => { + const result = await service.validate({ + sql: [ + "SELECT method AS group_value,", + " COUNT(*) AS item_count,", + " ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER (), 2) AS item_percentage", + "FROM payments", + "GROUP BY method", + "ORDER BY item_count DESC;" + ].join("\n"), + semanticPlan: plan({ + standaloneQuestion: "有多少种支付方式，他们比例是如何", + selectedTables: ["payments"], + selectedColumns: [ + "payments.id", + "payments.payment_no", + "payments.order_id", + "payments.method", + "payments.status", + "payments.amount", + "payments.created_at", + "payments.paid_at" + ], + allowedTables: ["payments"], + metrics: ["count"], + snapshotId: "semantic-plan-payments", + planLedger: { + version: "plan-ledger.v1", + snapshotId: "semantic-plan-payments", + obligations: [ + { + id: "ledger:table:payments", + kind: "table", + summary: "payments table", + criticality: "hard_blocker", + status: "grounded", + evidenceRefs: ["schema-supplement:payments"], + reasonCodes: ["selected_table_grounded"], + subject: "payments" + }, + { + id: "ledger:column:payments.method", + kind: "column", + summary: "payments method", + criticality: "hard_blocker", + status: "grounded", + evidenceRefs: ["schema-supplement:payments"], + reasonCodes: ["selected_column_grounded"], + subject: "payments.method" + }, + { + id: "ledger:metric:count", + kind: "metric", + summary: "count metric", + criticality: "hard_blocker", + status: "grounded", + evidenceRefs: ["schema-supplement:payments"], + reasonCodes: ["metric_grounded"], + subject: "count" + } + ], + summary: { + snapshotId: "semantic-plan-payments", + total: 3, + hardBlockerCount: 3, + warningCount: 0, + failedHardBlockerIds: [] + } + } + }), + sqlArtifact: { + sql: "SELECT method AS group_value, COUNT(*) AS item_count FROM payments GROUP BY method", + usedTables: ["payments"], + usedColumns: ["method"], + cause: "initial", + dialect: "sqlite", + claimedObligationIds: [ + "ledger:table:payments", + "ledger:column:payments.method", + "ledger:metric:count" + ] + } as never + }); + + expect(result.status).toBe("passed"); + expect(result.checks.find((check) => check.check === "ledger-fulfillment")).toMatchObject({ + status: "passed", + reasonCodes: ["ledger_fulfilled"] + }); + }); + + it.each([ + ["sqlite", "SELECT show tables FROM orders", "SQLite 不支持 SHOW TABLES 语法"], + ["mysql", "SELECT * FROM pragma", "MySQL 不支持 PRAGMA 语法"], + ["postgresql", "SELECT strftime('%Y', created_at) FROM orders", "PostgreSQL 不支持 strftime 函数"] + ] as const)("fails %s dialect mismatches correctably", async (datasourceType, sql, message) => { + const result = await service.validate({ + sql, + datasourceType, + semanticPlan: plan({ + selectedTables: datasourceType === "mysql" ? ["pragma"] : ["orders"], + selectedColumns: [], + allowedTables: ["orders", "pragma"] + }) + }); + + expect(result.status).toBe("failed"); + expect(result.failure?.code).toBe("SQL_DIALECT_MISMATCH"); + expect(result.failure?.message).toBe(message); + expect(result.failure?.terminal).toBe(false); + }); + + it("records dry-run unsupported as explicit skipped warning", async () => { + const result = await createService({ dryRun: false }).validate({ + sql: "SELECT COUNT(*) FROM orders", + datasourceType: "csv", + semanticPlan: plan() + }); + + expect(result.status).toBe("passed"); + expect(result.checks.find((check) => check.check === "dry-run")).toMatchObject({ + status: "skipped", + code: "SQL_DRY_RUN_UNSUPPORTED", + message: "capability disabled by test" + }); + }); + + it("fails dry-run parse rejection correctably", async () => { + const result = await createService({ + dryRunComplete: false, + dryRunReason: "unable to extract referenced tables" + }).validate({ + sql: "SELECT COUNT(*) FROM orders", + datasourceType: "sqlite", + semanticPlan: plan() + }); + + expect(result.status).toBe("failed"); + expect(result.failure?.code).toBe("SQL_DRY_RUN_PARSE_REJECTED"); + expect(result.failure?.terminal).toBe(false); + }); + + it("records dry-plan unsupported as explicit skipped warning", async () => { + const result = await createService({ dryPlan: false }).validate({ + sql: "SELECT COUNT(*) FROM orders", + datasourceType: "sqlite", + semanticPlan: plan() + }); + + expect(result.status).toBe("passed"); + expect(result.checks.find((check) => check.check === "dry-plan")).toMatchObject({ + status: "skipped", + code: "SQL_DRY_PLAN_UNSUPPORTED", + message: "capability disabled by test" + }); + }); + + it("fails dry-plan relationship mismatch correctably", async () => { + const result = await createService({ + dryPlanPass: false, + dryPlanReason: "missing tables from relationship plan: customers" + }).validate({ + sql: "SELECT COUNT(*) FROM orders JOIN customers ON customers.id = orders.customer_id", + datasourceType: "sqlite", + semanticPlan: plan({ + selectedTables: ["orders", "customers"], + selectedColumns: [], + allowedTables: ["orders", "customers"], + joinPath: ["orders.customer_id=customers.id"] + }) + }); + + expect(result.status).toBe("failed"); + expect(result.failure?.code).toBe("SQL_DRY_PLAN_RELATIONSHIP_MISMATCH"); + expect(result.failure?.terminal).toBe(false); + }); +}); diff --git a/apps/backend/test/unit/text2sql-workflow-runner.spec.ts b/apps/backend/test/unit/text2sql-workflow-runner.spec.ts new file mode 100644 index 0000000..c5afcbc --- /dev/null +++ b/apps/backend/test/unit/text2sql-workflow-runner.spec.ts @@ -0,0 +1,470 @@ +import { DomainError } from "../../src/common/domain-error"; +import { Text2SQLWorkflowRunner } from "../../src/modules/conversation/text2sql/text2sql-workflow-runner.service"; + +describe("Text2SQLWorkflowRunner", () => { + const createPrepared = () => ({ + runId: "run-1", + session: { + id: "session-1", + datasource: "sqlite_main", + modelProvider: "volcengine", + modelName: "mock-model" + }, + datasource: { + id: "sqlite_main", + type: "sqlite" + }, + sqlAccessContext: undefined, + question: "统计订单总数", + requestId: "req-1", + contextEnvelope: undefined, + userPersistResult: { + primaryPersisted: true + } + }); + + const createRun = (patch?: Partial) => ({ + runId: "run-1", + sessionId: "session-1", + question: "统计订单总数", + status: "executionResult", + provider: "volcengine", + model: "mock-model", + trace: { + runId: "run-1", + provider: "volcengine", + retryCount: 0, + steps: [] + }, + llmRaw: null, + createdAt: "2026-04-26T00:00:00.000Z", + ...patch + }); + + it("routes sync flow through prepare -> graph -> enrich -> persist -> hooks", async () => { + const datasourceRegistry = { + shouldFallbackOnReject: jest.fn().mockReturnValue(false) + }; + const prepareRunStage = { + run: jest.fn().mockResolvedValue(createPrepared()) + }; + const runAgentGraphStage = { + runSync: jest.fn().mockResolvedValue(createRun()), + runStream: jest.fn() + }; + const enrichDeliveryStage = { + run: jest.fn(async (run) => ({ + ...run, + delivery: { + answer: { + text: "已完成分析", + status: run.status, + provider: run.provider + } + } + })) + }; + const persistRunStage = { + run: jest.fn().mockResolvedValue(undefined) + }; + const postRunHooksStage = { + run: jest.fn().mockResolvedValue(undefined) + }; + const streamEventMapper = { + createEnvelope: jest.fn(), + mapLlmEvent: jest.fn(), + mapStepEvent: jest.fn() + }; + + const runner = new Text2SQLWorkflowRunner( + datasourceRegistry as never, + prepareRunStage as never, + runAgentGraphStage as never, + enrichDeliveryStage as never, + persistRunStage as never, + postRunHooksStage as never, + streamEventMapper as never + ); + + const result = await runner.runSync({ + sessionId: "session-1", + message: "统计订单总数" + }); + + expect(prepareRunStage.run).toHaveBeenCalledTimes(1); + expect(runAgentGraphStage.runSync).toHaveBeenCalledWith( + createPrepared(), + "/api/v1/sessions/:sessionId/messages" + ); + expect(enrichDeliveryStage.run).toHaveBeenCalledTimes(1); + expect(persistRunStage.run).toHaveBeenCalledWith({ + sessionId: "session-1", + run: result, + userPrimaryPersisted: true + }); + expect(postRunHooksStage.run).toHaveBeenCalledWith({ + session: createPrepared().session, + run: result, + requestId: "req-1" + }); + }); + + it("delegates the prepared run to the configured v2 stage contract", async () => { + const prepared = createPrepared(); + const runAgentGraphStage = { + runSync: jest.fn().mockResolvedValue(createRun()), + runStream: jest.fn() + }; + const runner = new Text2SQLWorkflowRunner( + { shouldFallbackOnReject: jest.fn().mockReturnValue(false) } as never, + { run: jest.fn().mockResolvedValue(prepared) } as never, + runAgentGraphStage as never, + { run: jest.fn(async (run) => run) } as never, + { run: jest.fn().mockResolvedValue(undefined) } as never, + { run: jest.fn().mockResolvedValue(undefined) } as never, + { + createEnvelope: jest.fn(), + mapLlmEvent: jest.fn(), + mapStepEvent: jest.fn() + } as never + ); + + await runner.runSync({ + sessionId: "session-1", + message: "统计订单总数" + }); + + expect(runAgentGraphStage.runSync).toHaveBeenCalledWith( + prepared, + "/api/v1/sessions/:sessionId/messages" + ); + }); + + it("adds readonly fallback answer for rejected runs when datasource allows fallback", async () => { + const datasourceRegistry = { + shouldFallbackOnReject: jest.fn().mockReturnValue(true) + }; + const prepareRunStage = { + run: jest.fn().mockResolvedValue(createPrepared()) + }; + const runAgentGraphStage = { + runSync: jest.fn().mockResolvedValue( + createRun({ + status: "rejected", + answer: undefined + }) + ), + runStream: jest.fn() + }; + const enrichDeliveryStage = { + run: jest.fn(async (run) => run) + }; + + const runner = new Text2SQLWorkflowRunner( + datasourceRegistry as never, + prepareRunStage as never, + runAgentGraphStage as never, + enrichDeliveryStage as never, + { run: jest.fn().mockResolvedValue(undefined) } as never, + { run: jest.fn().mockResolvedValue(undefined) } as never, + { + createEnvelope: jest.fn(), + mapLlmEvent: jest.fn(), + mapStepEvent: jest.fn() + } as never + ); + + const result = await runner.runSync({ + sessionId: "session-1", + message: "DELETE orders where id = 1" + }); + + expect(result.status).toBe("rejected"); + expect(result.answer).toContain("只读安全策略"); + }); + + it("keeps stream run id consistent across start and finish envelopes", async () => { + const prepared = createPrepared(); + const datasourceRegistry = { + shouldFallbackOnReject: jest.fn().mockReturnValue(false) + }; + const prepareRunStage = { + run: jest.fn().mockResolvedValue(prepared) + }; + const runAgentGraphStage = { + runSync: jest.fn(), + runStream: jest.fn(async (_input, _route, options) => { + await options?.onLlmEvent?.({ type: "text-delta", text: "delta" }); + await options?.onStep?.({ + step: { + node: "clarify", + status: "success", + at: "2026-04-26T00:00:01.000Z" + } + }); + return createRun(); + }) + }; + + const streamEventMapper = { + createEnvelope: jest.fn(({ type, data, runId, sessionId }) => ({ + type, + data, + runId, + sessionId, + at: "2026-04-26T00:00:02.000Z" + })), + mapLlmEvent: jest.fn(() => ({ + type: "text-delta", + data: { + text: "delta" + } + })), + mapStepEvent: jest.fn(() => ({ + data: { + node: "clarify", + status: "success", + detail: "", + stage: "analysis", + title: "理解问题" + }, + nextSequence: 1 + })) + }; + + const persistRunStage = { + run: jest.fn().mockResolvedValue(undefined) + }; + + const runner = new Text2SQLWorkflowRunner( + datasourceRegistry as never, + prepareRunStage as never, + runAgentGraphStage as never, + { run: jest.fn(async (run) => run) } as never, + persistRunStage as never, + { run: jest.fn().mockResolvedValue(undefined) } as never, + streamEventMapper as never + ); + + const events: Array<{ type: string; runId: string }> = []; + await runner.runStream({ + sessionId: "session-1", + message: "统计订单总数", + onEvent: (event) => { + events.push({ + type: event.type, + runId: event.runId + }); + } + }); + + expect(events.map((item) => item.type)).toEqual([ + "start", + "text-delta", + "state", + "finish" + ]); + expect(new Set(events.map((item) => item.runId))).toEqual(new Set(["run-1"])); + expect(persistRunStage.run).toHaveBeenCalledTimes(1); + }); + + it("streams finish delivery from the same canonical v2 run facts", async () => { + const prepared = createPrepared(); + const canonicalRun = createRun({ + sql: "SELECT COUNT(*) AS total FROM orders", + answer: "订单总数为 10", + rows: [{ total: 10 }], + columns: ["total"], + trace: { + runId: "run-1", + provider: "volcengine", + retryCount: 0, + steps: [], + v2: { + version: "v2", + stageOrder: ["intake", "generate-sql", "validate", "execute", "answer"], + stages: [ + { stage: "intake", status: "success" }, + { stage: "generate-sql", status: "success" }, + { stage: "validate", status: "success" }, + { stage: "execute", status: "success" }, + { stage: "answer", status: "success" } + ] + } + } + }) as any; + const runAgentGraphStage = { + runSync: jest.fn(), + runStream: jest.fn(async (_input, _route, options) => { + await options?.onStep?.({ + step: { + node: "generate-sql", + status: "success", + at: "2026-04-26T00:00:01.000Z", + outputSummary: JSON.stringify({ + sql: canonicalRun.sql, + v2: { + stageArtifact: { + stage: "generate-sql", + status: "success" + } + } + }) + } + }); + return canonicalRun; + }) + }; + const delivery = { + answer: { + text: "订单总数为 10", + status: "executionResult", + provider: "volcengine" + }, + evidence: { + runId: "run-1", + v2: { + version: "v2", + stageOrder: canonicalRun.trace.v2.stageOrder, + stageArtifacts: canonicalRun.trace.v2.stages + } + }, + artifact: { + sql: canonicalRun.sql, + columns: canonicalRun.columns, + rowCount: 1, + rowsPreview: canonicalRun.rows, + hasError: false + } + }; + const runner = new Text2SQLWorkflowRunner( + { shouldFallbackOnReject: jest.fn().mockReturnValue(false) } as never, + { run: jest.fn().mockResolvedValue(prepared) } as never, + runAgentGraphStage as never, + { + run: jest.fn(async (run) => ({ + ...run, + delivery + })) + } as never, + { run: jest.fn().mockResolvedValue(undefined) } as never, + { run: jest.fn().mockResolvedValue(undefined) } as never, + { + createEnvelope: jest.fn(({ type, data, runId, sessionId }) => ({ + type, + data, + runId, + sessionId, + at: "2026-04-26T00:00:02.000Z" + })), + mapLlmEvent: jest.fn(), + mapStepEvent: jest.fn(() => ({ + data: { + node: "generate-sql", + status: "success", + v2: { + stageArtifact: { + stage: "generate-sql", + status: "success" + } + } + }, + nextSequence: 1 + })) + } as never + ); + + const events: Array<{ type: string; data: any }> = []; + const run = await runner.runStream({ + sessionId: "session-1", + message: "统计订单总数", + onEvent: (event) => { + events.push({ + type: event.type, + data: event.data + }); + } + }); + + expect(runAgentGraphStage.runStream).toHaveBeenCalledWith( + prepared, + "/api/v1/sessions/:sessionId/messages/stream", + expect.any(Object) + ); + expect(run.delivery).toEqual(delivery); + expect(events.map((event) => event.type)).toEqual(["start", "state", "finish"]); + expect(events.at(-1)?.data).toMatchObject({ + status: "executionResult", + rowCount: 1, + delivery: { + answer: { + text: "订单总数为 10" + }, + evidence: { + v2: { + version: "v2", + stageOrder: ["intake", "generate-sql", "validate", "execute", "answer"] + } + }, + artifact: { + sql: "SELECT COUNT(*) AS total FROM orders", + rowCount: 1 + } + } + }); + }); + + it("emits stream error event and persists failed run on graph failure", async () => { + const prepared = createPrepared(); + const runner = new Text2SQLWorkflowRunner( + { + shouldFallbackOnReject: jest.fn().mockReturnValue(false) + } as never, + { + run: jest.fn().mockResolvedValue(prepared) + } as never, + { + runSync: jest.fn(), + runStream: jest + .fn() + .mockRejectedValue(new DomainError("GRAPH_FAILED", "图执行失败", 500)) + } as never, + { + run: jest.fn(async (run) => run) + } as never, + { + run: jest.fn().mockResolvedValue(undefined) + } as never, + { + run: jest.fn().mockResolvedValue(undefined) + } as never, + { + createEnvelope: jest.fn(({ type, data, runId, sessionId }) => ({ + type, + data, + runId, + sessionId, + at: "2026-04-26T00:00:02.000Z" + })), + mapLlmEvent: jest.fn(), + mapStepEvent: jest.fn() + } as never + ); + + const events: Array<{ type: string; code?: string }> = []; + const run = await runner.runStream({ + sessionId: "session-1", + message: "统计订单总数", + onEvent: (event) => { + events.push({ + type: event.type, + code: (event.data as { code?: string }).code + }); + } + }); + + expect(run.status).toBe("failed"); + expect(events.map((item) => item.type)).toEqual(["start", "error"]); + expect(events[1]?.code).toBe("GRAPH_FAILED"); + }); +}); diff --git a/apps/backend/test/unit/tool-registry.service.spec.ts b/apps/backend/test/unit/tool-registry.service.spec.ts index a548d67..6e65833 100644 --- a/apps/backend/test/unit/tool-registry.service.spec.ts +++ b/apps/backend/test/unit/tool-registry.service.spec.ts @@ -48,4 +48,42 @@ describe("SqlToolRegistryService", () => { rowCount: 1 }); }); + + it("rejects LLM tool attempts to inspect schema system tables", async () => { + const queryExecutorRouter = { + execute: jest.fn() + }; + const datasourceAccessPolicyService = { + resolveReadableTables: jest.fn() + }; + const sqlTool = new SqlReadonlyTool( + queryExecutorRouter as never, + datasourceAccessPolicyService as never + ); + const registry = new SqlToolRegistryService(sqlTool); + + const tools = registry.getToolsForDatasource({ + id: "sqlite_main", + name: "SQLite 主数据源", + type: "sqlite", + status: "available", + readonly: true, + shared: true, + config: { path: "/tmp/text2sql.db" }, + fileMeta: null, + unavailableAt: null, + deletedAt: null, + createdAt: new Date().toISOString(), + updatedAt: new Date().toISOString() + }); + + await expect( + tools.runReadOnlySql.execute({ + sql: "SELECT name FROM sqlite_master WHERE type = 'table'" + }) + ).rejects.toMatchObject({ + code: "LLM_TOOL_METADATA_INTROSPECTION_FORBIDDEN" + }); + expect(queryExecutorRouter.execute).not.toHaveBeenCalled(); + }); }); diff --git a/apps/frontend/src/app/settings/page.tsx b/apps/frontend/src/app/settings/page.tsx index 0842421..2e3c8ea 100644 --- a/apps/frontend/src/app/settings/page.tsx +++ b/apps/frontend/src/app/settings/page.tsx @@ -14,6 +14,8 @@ import type { GlossaryAnchor, LlmSettingsView, ModelCatalogItem, + RagTaskConfig, + RagTaskSettingsView, RagMemoryStatus, RagQualityGateReport, RagReplayCompletenessReport, @@ -23,6 +25,9 @@ import type { import { RagFoundationStatusCard } from "@/components/chat/rag-foundation-status-card"; import { ModelCatalogTable } from "@/components/settings/model-catalog-table"; import { ProviderConfigSheet } from "@/components/settings/provider-config-sheet"; +import { RagActiveIndexProfileCard } from "@/components/settings/rag-active-index-profile-card"; +import { RagEmbeddingConfigPanel } from "@/components/settings/rag-embedding-config-panel"; +import { RagRerankConfigPanel } from "@/components/settings/rag-rerank-config-panel"; import { UsersManagementPanel } from "@/components/settings/users-management-panel"; import { WorkspaceManagementPanel } from "@/components/settings/workspace-management-panel"; import { Badge } from "@/components/ui/badge"; @@ -43,12 +48,15 @@ import { getRun } from "@/lib/api-client"; import { readActiveWorkspaceId, writeActiveWorkspaceId } from "@/lib/datasource-session-context"; import { batchSetModelsEnabled, + checkRagTaskConfigHealth, checkProviderHealth, createProviderConfig, extractRagFoundationSnapshot, deleteProviderConfig, fetchBackendHealthSnapshot, fetchModelStatuses, + previewRagProviderModels, + fetchRagTaskConfigs, fetchRagQualityReport, fetchRagReplayCompleteness, fetchSettingsView, @@ -56,13 +64,14 @@ import { resolveRagQualityLatestRunId, setModelEnabled, submitRagMemoryFeedback, - syncProviderModels + syncProviderModels, + upsertRagTaskConfig } from "@/lib/settings-api-client"; -type SettingsTab = "users" | "workspaces" | "models" | "rag"; +type SettingsTab = "users" | "workspaces" | "models" | "rag-config" | "rag"; type RagRunSource = "deep-link" | "latest-run" | "none"; -const ADMIN_TABS: SettingsTab[] = ["users", "workspaces", "models", "rag"]; -const USER_TABS: SettingsTab[] = ["models", "rag"]; +const ADMIN_TABS: SettingsTab[] = ["users", "workspaces", "models", "rag-config", "rag"]; +const USER_TABS: SettingsTab[] = ["models", "rag-config", "rag"]; function readWorkspaceIdFromQuery(): string { if (typeof window === "undefined") { @@ -146,6 +155,9 @@ export default function SettingsPage() { supportsModelListing: boolean; }> >([]); + const [ragConfigLoading, setRagConfigLoading] = useState(false); + const [ragConfigError, setRagConfigError] = useState(""); + const [ragConfigView, setRagConfigView] = useState(null); const [ragLoading, setRagLoading] = useState(false); const [ragError, setRagError] = useState(""); const [ragFoundationError, setRagFoundationError] = useState(""); @@ -207,6 +219,22 @@ export default function SettingsPage() { } }, []); + const loadRagConfigView = useCallback(async (): Promise => { + setRagConfigLoading(true); + setRagConfigError(""); + try { + const result = await fetchRagTaskConfigs(); + setRagConfigView(result); + } catch (configError) { + setRagConfigError( + configError instanceof Error ? configError.message : "加载 RAG 配置失败" + ); + setRagConfigView(null); + } finally { + setRagConfigLoading(false); + } + }, []); + const loadRagView = useCallback(async (): Promise => { setRagLoading(true); setRagError(""); @@ -340,6 +368,7 @@ export default function SettingsPage() { setSupportedProviders(providerOptions); await Promise.all([ loadWorkspaceOptions(settingsView.actor.role === "admin"), + loadRagConfigView(), loadRagView() ]); } catch (loadError) { @@ -352,7 +381,7 @@ export default function SettingsPage() { } } }, - [loadRagView, loadWorkspaceOptions] + [loadRagConfigView, loadRagView, loadWorkspaceOptions] ); const refreshModels = async () => { @@ -422,6 +451,20 @@ export default function SettingsPage() { () => extractRagFoundationSnapshot(ragHealth), [ragHealth] ); + const embeddingConfig = useMemo( + () => + ragConfigView?.items.find( + (item): item is RagTaskConfig => item.taskType === "embedding" + ) ?? null, + [ragConfigView] + ); + const rerankConfig = useMemo( + () => + ragConfigView?.items.find( + (item): item is RagTaskConfig => item.taskType === "rerank" + ) ?? null, + [ragConfigView] + ); const filteredView = useMemo(() => { if (!view) { @@ -586,6 +629,8 @@ export default function SettingsPage() { {tab === "models" ? "模型治理视图" + : tab === "rag-config" + ? "RAG 配置视图" : tab === "rag" ? "RAG 运行视图" : "组织治理视图"} @@ -624,6 +669,13 @@ export default function SettingsPage() { LLM 模型 + + + RAG 配置 + RAG 运行与记忆治理

+ ) : tab === "rag-config" ? ( +

+ Embedding / Rerank 配置治理 +

) : (

工作空间与成员管理 @@ -679,8 +735,13 @@ export default function SettingsPage() { void loadRagView(); return; } + if (tab === "rag-config") { + void loadRagConfigView(); + return; + } if (actorRole === "admin") { void loadWorkspaceOptions(true); + void loadRagConfigView(); void loadRagView(); } setManagementRefreshToken((previous) => previous + 1); @@ -787,6 +848,134 @@ export default function SettingsPage() { )} + ) : tab === "rag-config" ? ( +

+
+
+
+
+
+ +
+
+

+ Rag Configuration Studio +

+

+ 向量检索与重排配置工作台 +

+
+
+

+ 在这里统一维护 Embedding 与 Rerank 的运行参数、供应商接入和草稿联通测试。 + 配置页只负责“当前要怎么跑”，RAG 运行页负责“已经跑成什么样”。 +

+
+
+
+

+ Embedding +

+

+ {embeddingConfig?.provider ?? "未配置"} +

+

+ {embeddingConfig?.model ?? "等待配置模型"} +

+
+
+

+ Rerank +

+

+ {rerankConfig?.provider ?? "未配置"} +

+

+ {rerankConfig?.model ?? "等待配置模型"} +

+
+
+

+ Active Index +

+

+ {foundationSnapshot?.activeIndexSummary.total ?? 0} 个活跃索引 +

+

+ {foundationSnapshot?.activeIndexSummary.items[0]?.datasourceId ?? + "暂无索引画像"} +

+
+
+
+
+ {ragConfigError ? {ragConfigError} : null} + +
+ previewRagProviderModels("embedding", payload)} + onSave={async (payload) => { + try { + await upsertRagTaskConfig("embedding", payload); + await loadRagConfigView(); + } catch (error) { + const message = + error instanceof Error ? error.message : "保存 Embedding 配置失败"; + setRagConfigError(message); + throw new Error(message); + } + }} + onHealthCheck={async (payload) => { + try { + const result = await checkRagTaskConfigHealth("embedding", payload); + await loadRagConfigView(); + return result; + } catch (error) { + const message = + error instanceof Error ? error.message : "Embedding 健康检查失败"; + setRagConfigError(message); + throw new Error(message); + } + }} + /> + previewRagProviderModels("rerank", payload)} + onSave={async (payload) => { + try { + await upsertRagTaskConfig("rerank", payload); + await loadRagConfigView(); + } catch (error) { + const message = + error instanceof Error ? error.message : "保存 Rerank 配置失败"; + setRagConfigError(message); + throw new Error(message); + } + }} + onHealthCheck={async (payload) => { + try { + const result = await checkRagTaskConfigHealth("rerank", payload); + await loadRagConfigView(); + return result; + } catch (error) { + const message = + error instanceof Error ? error.message : "Rerank 健康检查失败"; + setRagConfigError(message); + throw new Error(message); + } + }} + /> +
+
) : tab === "rag" ? (
{ragLoading ? ( @@ -805,6 +994,26 @@ export default function SettingsPage() { /> +
+

+ Active Provider Summary +

+
+

+ embedding:{" "} + {embeddingConfig + ? `${embeddingConfig.provider}/${embeddingConfig.model} (${embeddingConfig.configSource})` + : "unknown"} +

+

+ rerank:{" "} + {rerankConfig + ? `${rerankConfig.provider}/${rerankConfig.model} (${rerankConfig.configSource})` + : "unknown"} +

+
+
+

R2 Gate 报告 diff --git a/apps/frontend/src/components/chat-panel.tsx b/apps/frontend/src/components/chat-panel.tsx index b04f8c4..1614c72 100644 --- a/apps/frontend/src/components/chat-panel.tsx +++ b/apps/frontend/src/components/chat-panel.tsx @@ -118,6 +118,58 @@ function moveSessionToFront( } function toThinkingStep(event: ChatStreamEvent): ThinkingStep | null { + if (event.type === "tool-call") { + const payload = event.data as + | { toolName?: string; toolCallId?: string; input?: unknown } + | undefined; + const toolName = payload?.toolName ?? "tool"; + return { + node: `tool:${toolName}`, + status: "success", + stepId: `${event.runId}:tool:${payload?.toolCallId ?? event.at}`, + lifecycle: "running", + detail: summarizeToolPayload(payload?.input), + at: event.at, + startedAt: event.at, + stage: "generation", + title: `调用工具：${toolName}` + }; + } + if (event.type === "tool-result") { + const payload = event.data as + | { toolName?: string; toolCallId?: string; output?: unknown } + | undefined; + const toolName = payload?.toolName ?? "tool"; + return { + node: `tool:${toolName}`, + status: "success", + stepId: `${event.runId}:tool:${payload?.toolCallId ?? event.at}`, + lifecycle: "completed", + detail: summarizeToolPayload(payload?.output), + at: event.at, + endedAt: event.at, + stage: "generation", + title: `工具返回：${toolName}` + }; + } + if (event.type === "tool-error") { + const payload = event.data as + | { toolName?: string; toolCallId?: string; message?: string } + | undefined; + const toolName = payload?.toolName ?? "tool"; + return { + node: `tool:${toolName}`, + status: "failed", + stepId: `${event.runId}:tool:${payload?.toolCallId ?? event.at}`, + lifecycle: "failed", + detail: payload?.message ?? "工具调用失败", + errorSummary: payload?.message, + at: event.at, + endedAt: event.at, + stage: "generation", + title: `工具失败：${toolName}` + }; + } if (event.type !== "state") { return null; } @@ -141,6 +193,30 @@ function toThinkingStep(event: ChatStreamEvent): ThinkingStep | null { }; } +function summarizeToolPayload(payload: unknown): string { + if (payload === undefined || payload === null) { + return ""; + } + if (typeof payload === "string") { + return payload.slice(0, 180); + } + if (typeof payload !== "object") { + return String(payload).slice(0, 180); + } + const record = payload as Record; + if (typeof record.sql === "string") { + return record.sql.slice(0, 180); + } + if (typeof record.rowCount === "number") { + return `返回 ${record.rowCount} 行`; + } + try { + return JSON.stringify(payload).slice(0, 180); + } catch { + return ""; + } +} + function appendThinkingStep( previous: Record, runId: string, @@ -195,6 +271,9 @@ export function ChatPanel() { const [streamDeliveryByRunId, setStreamDeliveryByRunId] = useState< Record >({}); + const [streamTextStartedByRunId, setStreamTextStartedByRunId] = useState< + Record + >({}); const [runVisibilityByRunId, setRunVisibilityByRunId] = useState< Record >({}); @@ -267,6 +346,7 @@ export function ChatPanel() { setStreamThinkingByRunId({}); setRunLoadingById({}); setStreamDeliveryByRunId({}); + setStreamTextStartedByRunId({}); setRunVisibilityByRunId({}); setActiveStreamRunId(null); setThinkingRequestPending(false); @@ -291,6 +371,7 @@ export function ChatPanel() { setStreamThinkingByRunId({}); setRunLoadingById({}); setStreamDeliveryByRunId({}); + setStreamTextStartedByRunId({}); setRunVisibilityByRunId((previous) => { if (!sessionView.latestRun) { return {}; @@ -711,6 +792,7 @@ export function ChatPanel() { streamThinkingByRunId={streamThinkingByRunId} runLoadingById={runLoadingById} streamDeliveryByRunId={streamDeliveryByRunId} + streamTextStartedByRunId={streamTextStartedByRunId} runVisibilityByRunId={runVisibilityByRunId} activeStreamRunId={activeStreamRunId} thinkingRequestPending={thinkingRequestPending} @@ -744,9 +826,23 @@ export function ChatPanel() { delete next[event.runId]; return next; }); + setStreamTextStartedByRunId((previous) => { + const next = { ...previous }; + delete next[event.runId]; + return next; + }); setThinkingRequestPending(true); return; } + if (event.type === "text-delta") { + const text = (event.data as { text?: unknown } | undefined)?.text; + if (typeof text === "string" && text.length > 0) { + setStreamTextStartedByRunId((previous) => ({ + ...previous, + [event.runId]: true + })); + } + } if (event.type === "finish") { const finishData = event.data as | { delivery?: unknown; status?: unknown } diff --git a/apps/frontend/src/components/chat/assistant-thread.tsx b/apps/frontend/src/components/chat/assistant-thread.tsx index d7a226d..e617eec 100644 --- a/apps/frontend/src/components/chat/assistant-thread.tsx +++ b/apps/frontend/src/components/chat/assistant-thread.tsx @@ -18,7 +18,10 @@ import { buildContextEnvelopeFromDraft, createEmptyContextEnvelopeDraft } from "@/components/chat/context-envelope-panel"; -import type { ThinkingStreamStep } from "@/components/chat/assistant-thinking-panel"; +import { + AssistantThinkingPanel, + type ThinkingStreamStep +} from "@/components/chat/assistant-thinking-panel"; import { AssistantMessageBubble, UserMessageBubble @@ -41,6 +44,7 @@ interface AssistantThreadProps { streamThinkingByRunId: Record; runLoadingById: Record; streamDeliveryByRunId: Record; + streamTextStartedByRunId: Record; runVisibilityByRunId: Record; activeStreamRunId: string | null; thinkingRequestPending: boolean; @@ -78,6 +82,7 @@ export function AssistantThread({ streamThinkingByRunId, runLoadingById, streamDeliveryByRunId, + streamTextStartedByRunId, runVisibilityByRunId, activeStreamRunId, thinkingRequestPending, @@ -159,6 +164,16 @@ export function AssistantThread({ callbacks, resolveContextEnvelope: resolveContextEnvelopeForSend }); + const activeStreamSteps = activeStreamRunId + ? streamThinkingByRunId[activeStreamRunId] ?? [] + : []; + const activeStreamTextStarted = activeStreamRunId + ? Boolean(streamTextStartedByRunId[activeStreamRunId]) + : false; + const showStandaloneThinking = + Boolean(activeStreamRunId) && + activeStreamSteps.length > 0 && + !activeStreamTextStarted; return ( @@ -231,6 +246,20 @@ export function AssistantThread({ return null; }} + {showStandaloneThinking && activeStreamRunId ? ( +
+ +
+ ) : null} {thinkingRequestPending && !activeStreamRunId ? (
diff --git a/apps/frontend/src/components/chat/rag-delivery-panel.tsx b/apps/frontend/src/components/chat/rag-delivery-panel.tsx index d97b8bd..0bf4016 100644 --- a/apps/frontend/src/components/chat/rag-delivery-panel.tsx +++ b/apps/frontend/src/components/chat/rag-delivery-panel.tsx @@ -178,6 +178,27 @@ function resolveSavedPriorSqlSummary(delivery?: DeliveryContract): { }; } +function resolveLoopEvidenceSummary(delivery?: DeliveryContract): { + summary: string; + detail: string; +} { + const loopEvidence = delivery?.evidence?.v2?.loopEvidence ?? []; + const terminationReason = delivery?.evidence?.v2?.terminationReason; + if (loopEvidence.length === 0 && !terminationReason) { + return { + summary: "无 loop evidence", + detail: "未记录 loop 轨迹。" + }; + } + const last = loopEvidence[loopEvidence.length - 1]; + return { + summary: `loops=${loopEvidence.length}`, + detail: `lastAction=${last?.actionType ?? "unknown"} · termination=${ + terminationReason ?? last?.terminationReason ?? "none" + }` + }; +} + function renderSelectedContextState( delivery: DeliveryContract ): { state: SelectedContextState; node: JSX.Element } { @@ -241,6 +262,7 @@ export function RagDeliveryPanel({ delivery, runId }: RagDeliveryPanelProps) { const artifact = delivery?.artifact; const promptTemplateSummary = resolvePromptTemplateSummary(delivery); const savedPriorSqlSummary = resolveSavedPriorSqlSummary(delivery); + const loopEvidenceSummary = resolveLoopEvidenceSummary(delivery); const runLifecycleKey = runId?.trim() || evidence?.runId?.trim() || "__unknown-run__"; const semanticVersionText = evidence?.semanticVersion ?? "版本不可用（字段缺失）"; const semanticLockStatusText = @@ -371,6 +393,7 @@ export function RagDeliveryPanel({ delivery, runId }: RagDeliveryPanelProps) {

模板命中摘要：{promptTemplateSummary.summary}

模板降级原因：{promptTemplateSummary.fallbackReasonText}

Saved Prior SQL：{savedPriorSqlSummary.summary}

+

Loop Evidence：{loopEvidenceSummary.summary}

{savedPriorSqlSummary.detail} + {loopEvidenceSummary.detail} {selectedContextState.node} {(evidence?.degradeReasons?.length ?? 0) > 0 ? (

diff --git a/apps/frontend/src/components/chat/run-visibility-mapper.ts b/apps/frontend/src/components/chat/run-visibility-mapper.ts index 41cdf81..1d1bb71 100644 --- a/apps/frontend/src/components/chat/run-visibility-mapper.ts +++ b/apps/frontend/src/components/chat/run-visibility-mapper.ts @@ -212,6 +212,53 @@ function normalizeSkillContextSummary( }; } +function normalizeV2LoopEvidence(value: unknown): NonNullable< + NonNullable["loopEvidence"] +> { + if (!Array.isArray(value)) { + return []; + } + return value + .map((item) => { + if (!isRecord(item)) { + return undefined; + } + const loopIndexRaw = readNumber(item.loopIndex) ?? readNumber(item.loop_index); + const triggerReason = + readString(item.triggerReason) ?? readString(item.trigger_reason); + const actionType = readString(item.actionType) ?? readString(item.action_type); + if (loopIndexRaw === undefined || !triggerReason || !actionType) { + return undefined; + } + const convergencePath = readStringArray( + item.convergencePath ?? item.convergence_path + ); + const terminationReason = + readString(item.terminationReason) ?? readString(item.termination_reason); + const planDeltaRaw = sanitizeJsonValue(item.planDelta ?? item.plan_delta); + const normalizedPlanDelta = isRecord(planDeltaRaw) + ? (planDeltaRaw as NonNullable< + NonNullable["loopEvidence"] + >[number]["planDelta"]) + : undefined; + return { + loopIndex: Math.max(0, Math.floor(loopIndexRaw)), + triggerReason, + actionType, + ...(normalizedPlanDelta ? { planDelta: normalizedPlanDelta } : {}), + ...(terminationReason ? { terminationReason } : {}), + ...(convergencePath.length > 0 ? { convergencePath } : {}) + }; + }) + .filter( + ( + item + ): item is NonNullable< + NonNullable["loopEvidence"] + >[number] => Boolean(item) + ); +} + function normalizeEvidence(value: unknown): DeliveryEvidenceLayer | undefined { if (!isRecord(value)) { return undefined; @@ -281,6 +328,12 @@ function normalizeEvidence(value: unknown): DeliveryEvidenceLayer | undefined { value.skillContextSummary ?? value.skill_context_summary ?? value.skill_context ); const evidenceStale = readBoolean(value.evidenceStale) ?? readBoolean(value.evidence_stale); + const v2Raw = isRecord(value.v2) ? value.v2 : undefined; + const v2LoopEvidence = normalizeV2LoopEvidence( + v2Raw?.loopEvidence ?? v2Raw?.loop_evidence + ); + const v2TerminationReason = + readString(v2Raw?.terminationReason) ?? readString(v2Raw?.termination_reason); const savedPriorSqlRaw = isRecord(value.savedPriorSql) ? value.savedPriorSql : isRecord(value.saved_prior_sql) @@ -376,7 +429,15 @@ function normalizeEvidence(value: unknown): DeliveryEvidenceLayer | undefined { ...(semanticDegradeReason ? { semanticDegradeReason } : {}), ...(skillContextSummary ? { skillContextSummary } : {}), ...(savedPriorSql ? { savedPriorSql } : {}), - ...(evidenceStale !== undefined ? { evidenceStale } : {}) + ...(evidenceStale !== undefined ? { evidenceStale } : {}), + ...(v2LoopEvidence.length > 0 || v2TerminationReason + ? { + v2: { + ...(v2LoopEvidence.length > 0 ? { loopEvidence: v2LoopEvidence } : {}), + ...(v2TerminationReason ? { terminationReason: v2TerminationReason } : {}) + } + } + : {}) }; return Object.keys(normalized).length > 0 ? normalized : undefined; diff --git a/apps/frontend/src/components/settings/rag-active-index-profile-card.tsx b/apps/frontend/src/components/settings/rag-active-index-profile-card.tsx new file mode 100644 index 0000000..ea82f4a --- /dev/null +++ b/apps/frontend/src/components/settings/rag-active-index-profile-card.tsx @@ -0,0 +1,180 @@ +"use client"; + +import type { RagTaskConfig } from "@text2sql/shared-types"; +import { Database, Orbit, RefreshCcwDot, Sparkles } from "lucide-react"; +import type { RagFoundationSnapshot } from "@/lib/settings-api-client"; +import { Badge } from "@/components/ui/badge"; +import { StateBlock } from "@/components/ui/state-block"; + +interface RagActiveIndexProfileCardProps { + foundation: RagFoundationSnapshot | null; + embeddingConfig: RagTaskConfig | null; + rerankConfig?: RagTaskConfig | null; +} + +function parseSourceVersionProfile(sourceVersion?: string): { + provider?: string; + model?: string; + vectorVersion?: string; +} { + if (!sourceVersion) { + return {}; + } + const parts = sourceVersion.split(":"); + if (parts.length < 6) { + return {}; + } + return { + provider: parts[1]?.trim() || undefined, + model: parts[2]?.trim() || undefined, + vectorVersion: parts[3]?.trim() || undefined + }; +} + +function computeReindexHint(input: { + profile: { + provider?: string; + model?: string; + vectorVersion?: string; + }; + embeddingConfig: RagTaskConfig | null; +}): { + reindexRequired: boolean; + reasonCodes: string[]; +} { + const reasonCodes: string[] = []; + const config = input.embeddingConfig; + if (!config) { + return { + reindexRequired: false, + reasonCodes: [] + }; + } + if (input.profile.provider && config.provider !== input.profile.provider) { + reasonCodes.push("provider_changed"); + } + if (input.profile.model && config.model !== input.profile.model) { + reasonCodes.push("model_changed"); + } + if ( + input.profile.vectorVersion && + config.vectorVersion && + config.vectorVersion !== input.profile.vectorVersion + ) { + reasonCodes.push("vector_version_changed"); + } + return { + reindexRequired: reasonCodes.length > 0, + reasonCodes + }; +} + +export function RagActiveIndexProfileCard({ + foundation, + embeddingConfig, + rerankConfig = null +}: RagActiveIndexProfileCardProps) { + const active = foundation?.activeIndexSummary.items[0]; + if (!active) { + return 暂无 active index profile。; + } + + const profile = parseSourceVersionProfile(active.sourceVersion); + const reindexHint = computeReindexHint({ + profile, + embeddingConfig + }); + + return ( +

+
+
+
+
+ +
+
+

+ Active Index +

+

+ 当前检索索引画像 +

+
+
+
+ + {active.indexVersionId} + + + {reindexHint.reindexRequired ? "需要重建索引" : "配置对齐"} + + + datasource {active.datasourceId} + +
+

+ 这里显示当前活跃索引的 embedding 画像，以及它与现行 RAG 配置是否一致。若 provider、 + model 或 vector version 不一致，下面会直接提示需要 reindex。 +

+
+
+
+
+ + Embedding Index +
+

+ {profile.provider ?? "unknown"} +

+

+ {profile.model ?? "unknown"} +

+

+ vectorVersion {profile.vectorVersion ?? "unknown"} +

+
+
+
+ + Runtime Config +
+

+ {embeddingConfig + ? `${embeddingConfig.provider} / ${embeddingConfig.model}` + : "unknown"} +

+

+ rerank{" "} + {rerankConfig + ? `${rerankConfig.provider} / ${rerankConfig.model}` + : "unknown"} +

+

+ activatedAt {active.activatedAt} +

+
+
+
+
+ {reindexHint.reindexRequired ? ( +
+ + 当前索引与运行配置不一致，需要重新构建索引。 + + {reindexHint.reasonCodes.join(" / ")} + +
+ ) : ( +
+ + 索引画像与当前 Embedding 配置一致，可直接继续运行。 +
+ )} +
+
+ ); +} diff --git a/apps/frontend/src/components/settings/rag-embedding-config-panel.tsx b/apps/frontend/src/components/settings/rag-embedding-config-panel.tsx new file mode 100644 index 0000000..85cdecc --- /dev/null +++ b/apps/frontend/src/components/settings/rag-embedding-config-panel.tsx @@ -0,0 +1,696 @@ +"use client"; + +import { useEffect, useMemo, useState } from "react"; +import type { + LlmProviderCode, + RagTaskConfig, + RagTaskConfigHealthRequest +} from "@text2sql/shared-types"; +import { ChevronDown, RefreshCw, Settings2, ShieldCheck } from "lucide-react"; +import { Badge } from "@/components/ui/badge"; +import { Button } from "@/components/ui/button"; +import { + Collapsible, + CollapsibleContent, + CollapsibleTrigger +} from "@/components/ui/collapsible"; +import { + Dialog, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle +} from "@/components/ui/dialog"; +import { Input } from "@/components/ui/input"; +import { Label } from "@/components/ui/label"; +import { NativeSelect, NativeSelectOption } from "@/components/ui/native-select"; +import { + Select, + SelectContent, + SelectItem, + SelectTrigger, + SelectValue +} from "@/components/ui/select"; +import { StateBlock } from "@/components/ui/state-block"; +import { + RagProviderCardGrid, + resolveRagProviderPreset +} from "@/components/settings/rag-provider-card-grid"; +import type { + RagProviderModelPreviewResult, + RagTaskConfigHealthResult, + RagTaskConfigPayload +} from "@/lib/settings-api-client"; + +interface RagEmbeddingConfigPanelProps { + actorRole: "admin" | "user"; + config: RagTaskConfig | null; + loading?: boolean; + onSave: (payload: RagTaskConfigPayload) => Promise; + onFetchModels: (payload: { + provider: LlmProviderCode; + baseUrl?: string; + apiKey: string; + }) => Promise; + onHealthCheck: ( + payload: RagTaskConfigHealthRequest + ) => Promise; +} + +function resolveConfigVersion(config: RagTaskConfig | null): string { + if (!config) { + return "missing"; + } + return [ + config.id, + config.updatedAt, + config.provider, + config.model, + config.baseUrl ?? "", + config.enabled ? "1" : "0", + config.dimensions ?? "", + config.vectorVersion ?? "", + config.timeoutMs ?? "" + ].join(":"); +} + +export function RagEmbeddingConfigPanel({ + actorRole, + config, + loading = false, + onSave, + onFetchModels, + onHealthCheck +}: RagEmbeddingConfigPanelProps) { + const [provider, setProvider] = useState(""); + const [model, setModel] = useState(""); + const [baseUrl, setBaseUrl] = useState(""); + const [apiKey, setApiKey] = useState(""); + const [enabled, setEnabled] = useState(true); + const [dimensions, setDimensions] = useState(""); + const [vectorVersion, setVectorVersion] = useState(""); + const [timeoutMs, setTimeoutMs] = useState(""); + const [note, setNote] = useState(""); + const [dirty, setDirty] = useState(false); + const [dialogOpen, setDialogOpen] = useState(false); + const [lastSyncedConfigVersion, setLastSyncedConfigVersion] = useState("missing"); + const [remoteUpdateAvailable, setRemoteUpdateAvailable] = useState(false); + const [saving, setSaving] = useState(false); + const [checking, setChecking] = useState(false); + const [saveStatus, setSaveStatus] = useState(""); + const [saveError, setSaveError] = useState(""); + const [checkStatus, setCheckStatus] = useState(""); + const [checkError, setCheckError] = useState(""); + const [checkedAgainst, setCheckedAgainst] = useState<"draft" | "persisted" | null>(null); + const [fetchingModels, setFetchingModels] = useState(false); + const [modelFetchStatus, setModelFetchStatus] = useState(""); + const [modelFetchError, setModelFetchError] = useState(""); + const [modelOptions, setModelOptions] = useState([]); + const [advancedOpen, setAdvancedOpen] = useState(false); + + const configVersion = resolveConfigVersion(config); + const readonly = actorRole !== "admin"; + const selectedPreset = useMemo( + () => resolveRagProviderPreset("embedding", provider), + [provider] + ); + const currentPreset = useMemo( + () => resolveRagProviderPreset("embedding", config?.provider), + [config?.provider] + ); + + const syncFromConfig = (nextConfig: RagTaskConfig | null) => { + setProvider(nextConfig?.provider ?? ""); + setModel(nextConfig?.model ?? ""); + setBaseUrl(nextConfig?.baseUrl ?? ""); + setApiKey(""); + setEnabled(nextConfig?.enabled ?? true); + setDimensions( + nextConfig?.configSource === "settings" && nextConfig.dimensions + ? String(nextConfig.dimensions) + : "" + ); + setVectorVersion( + nextConfig?.configSource === "settings" ? (nextConfig.vectorVersion ?? "") : "" + ); + setTimeoutMs(nextConfig?.timeoutMs ? String(nextConfig.timeoutMs) : ""); + setNote(nextConfig?.note ?? ""); + setModelOptions([]); + setModelFetchStatus(""); + setModelFetchError(""); + setAdvancedOpen(false); + }; + + useEffect(() => { + if (!dirty) { + syncFromConfig(config); + setLastSyncedConfigVersion(configVersion); + setRemoteUpdateAvailable(false); + return; + } + if (configVersion !== lastSyncedConfigVersion) { + setRemoteUpdateAvailable(true); + } + }, [config, configVersion, dirty, lastSyncedConfigVersion]); + + const markDirty = () => { + if (!dirty) { + setDirty(true); + } + setSaveStatus(""); + setSaveError(""); + setCheckStatus(""); + setCheckError(""); + setModelFetchStatus(""); + setModelFetchError(""); + setCheckedAgainst(null); + }; + + const openCurrentDraft = () => { + setDialogOpen(true); + }; + + const resetToLatest = () => { + syncFromConfig(config); + setDirty(false); + setRemoteUpdateAvailable(false); + setLastSyncedConfigVersion(resolveConfigVersion(config)); + setSaveStatus(""); + setSaveError(""); + setCheckStatus(""); + setCheckError(""); + setModelFetchStatus(""); + setModelFetchError(""); + setCheckedAgainst(null); + }; + + const fetchModels = async () => { + if (!provider.trim()) { + setModelFetchError("请先选择 Provider。"); + return; + } + if (!apiKey.trim()) { + setModelFetchError("请先填写 API Key，再获取模型。"); + return; + } + + setFetchingModels(true); + setModelFetchStatus(""); + setModelFetchError(""); + try { + const result = await onFetchModels({ + provider: provider as LlmProviderCode, + baseUrl: baseUrl.trim() || undefined, + apiKey: apiKey.trim() + }); + setModelOptions(result.models); + const nextModel = + result.recommendedModel && result.models.some((item) => item.model === result.recommendedModel) + ? result.recommendedModel + : result.models[0]?.model; + if (!model.trim() && nextModel) { + setModel(nextModel); + } + setModelFetchStatus( + result.models.length > 0 + ? `已拉取 ${result.models.length} 个官方模型，可直接选择或继续手动填写。` + : "已请求官方模型目录，但当前未返回可选模型。" + ); + } catch (error) { + setModelOptions([]); + setModelFetchError(error instanceof Error ? error.message : "获取模型失败"); + } finally { + setFetchingModels(false); + } + }; + + const saveDraft = async () => { + setSaving(true); + setSaveStatus(""); + setSaveError(""); + try { + await onSave({ + provider: provider.trim(), + model: model.trim(), + baseUrl: baseUrl.trim() || undefined, + apiKey: apiKey.trim() || undefined, + enabled, + dimensions: dimensions.trim() ? Number(dimensions) : undefined, + vectorVersion: vectorVersion.trim() || undefined, + timeoutMs: timeoutMs.trim() ? Number(timeoutMs) : undefined, + note: note.trim() || undefined + }); + setApiKey(""); + setDirty(false); + setRemoteUpdateAvailable(false); + setSaveStatus("保存成功，Embedding 配置已写入。"); + setDialogOpen(false); + } catch (error) { + setSaveError(error instanceof Error ? error.message : "保存失败"); + } finally { + setSaving(false); + } + }; + + const checkDraft = async () => { + setChecking(true); + setCheckStatus(""); + setCheckError(""); + try { + const result = await onHealthCheck({ + expectedDimensions: dimensions.trim() ? Number(dimensions) : undefined, + draft: { + provider: provider.trim(), + model: model.trim(), + baseUrl: baseUrl.trim() || undefined, + apiKey: apiKey.trim() || undefined, + enabled, + dimensions: dimensions.trim() ? Number(dimensions) : undefined, + vectorVersion: vectorVersion.trim() || undefined, + timeoutMs: timeoutMs.trim() ? Number(timeoutMs) : undefined, + note: note.trim() || undefined + } + }); + setCheckedAgainst(result.checkedAgainst); + setCheckStatus( + `检测结果: ${result.status} · code=${result.reasonCode} · source=${result.configSource} · checkedAgainst=${result.checkedAgainst}` + ); + } catch (error) { + setCheckError(error instanceof Error ? error.message : "检测失败"); + } finally { + setChecking(false); + } + }; + + return ( +
+
+
+
+
+
+
+ +
+
+

+ Embedding Workspace +

+

+ Embedding Provider +

+
+
+

+ 管理向量模型接入、密钥与维度参数。先选供应商，填好 API Key 后可直接获取官方模型，再做连通性验证并保存。 +

+
+
+ + {config?.configSource ?? "missing"} + + + {config?.healthStatus ?? "unknown"} + + + {dirty ? "draft" : "synced"} + + {checkedAgainst ? ( + {`checked:${checkedAgainst}`} + ) : null} +
+
+ +
+
+

+ 当前生效 Provider +

+

+ {currentPreset?.displayName ?? config?.provider ?? "尚未配置"} +

+

+ {config?.baseUrl ?? "Base URL 将在弹窗中配置"} +

+
+
+

+ 当前模型与索引参数 +

+

+ {config?.model ?? "点击卡片后填写模型"} +

+
+ + {config?.hasApiKey ? "API Key 已配置" : "API Key 待填写"} + + + {config?.dimensions ? `dim=${config.dimensions}` : "维度未指定"} + + + {config?.vectorVersion ? `vector=${config.vectorVersion}` : "vector 未指定"} + +
+
+
+ +
+
+
+
+ +
+ {loading ? Embedding 配置加载中... : null} + {!config && !loading ? ( + + 当前还没有 Embedding 配置，直接点击卡片即可开始接入。 + + ) : null} + {remoteUpdateAvailable ? ( + + 检测到后台配置更新，当前草稿已保护。可继续编辑，或在弹窗里重置为最新配置。 + + ) : null} + { + if (preset.provider === provider.trim()) { + setDialogOpen(true); + return; + } + markDirty(); + setProvider(preset.provider); + setModel(preset.recommendedModel); + setBaseUrl(preset.defaultBaseUrl); + if (!note.trim()) { + setNote(`preset=${preset.provider}${preset.mode ? `;mode=${preset.mode}` : ""}`); + } + setDialogOpen(true); + }} + /> + {readonly ? ( + 当前账号只读，可查看配置摘要。 + ) : null} + {saveStatus ? {saveStatus} : null} + {saveError ? {saveError} : null} + {config ? ( +

+ 上次检查：{config.lastCheckedAt ?? "未检查"} · 来源说明：{config.configSourceNote ?? "无"} +

+ ) : null} +
+ + + +
+ + + 配置 Embedding: {(selectedPreset?.displayName ?? provider) || "新 Provider"} + + + 先选 Provider、填写 API Key，再获取官方模型目录。高级参数默认可留空，系统会回退到 provider/model 默认值。 + + + +
+
+ + + 草稿检测不落库 + + + 保存后立即生效 + + + {apiKey.trim() || config?.hasApiKey ? "已具备鉴权信息" : "需填写 API Key"} + +
+
+ + {remoteUpdateAvailable ? ( + + 后台配置已更新；当前弹窗仍保留你的草稿，可继续调整或重置。 + + ) : null} + +
+
+ +
+
+ + {selectedPreset?.displayName ?? currentPreset?.displayName ?? "请从上方卡片选择"} + + {provider.trim() ? ( + + {provider} + + ) : null} +
+

+ Provider 通过卡片选择，不需要手动填写。 +

+
+
+
+ + { + markDirty(); + setModel(event.target.value); + }} + placeholder="model" + aria-label="embedding-model" + disabled={readonly || loading || saving} + /> +
+
+ + +
+
+ + { + markDirty(); + setBaseUrl(event.target.value); + }} + placeholder="base url" + aria-label="embedding-base-url" + disabled={readonly || loading || saving} + /> +
+
+ + { + markDirty(); + setApiKey(event.target.value); + }} + placeholder={config?.apiKeyMasked ?? "api key"} + aria-label="embedding-api-key" + disabled={readonly || loading || saving} + /> +
+ {modelOptions.length > 0 ? ( +
+ + +
+ ) : null} +
+ +
+ + + + +
+
+ + { + markDirty(); + setDimensions(event.target.value); + }} + placeholder="留空=自动" + aria-label="embedding-dimensions" + disabled={readonly || loading || saving} + /> +
+
+ + { + markDirty(); + setVectorVersion(event.target.value); + }} + placeholder={config?.vectorVersion ?? "v1"} + aria-label="embedding-vector-version" + disabled={readonly || loading || saving} + /> +
+
+ + { + markDirty(); + setTimeoutMs(event.target.value); + }} + placeholder="timeout ms" + aria-label="embedding-timeout-ms" + disabled={readonly || loading || saving} + /> +
+
+ + { + markDirty(); + setEnabled(event.target.value === "enabled"); + }} + aria-label="embedding-enabled" + disabled={readonly || loading || saving} + > + enabled + disabled + +
+
+ + { + markDirty(); + setNote(event.target.value); + }} + placeholder="可选备注" + aria-label="embedding-note" + disabled={readonly || loading || saving} + /> +
+
+ +
+ +
+
+ + {modelFetchStatus ? {modelFetchStatus} : null} + {modelFetchError ? {modelFetchError} : null} + {checkStatus ? {checkStatus} : null} + {checkError ? {checkError} : null} + {saveError ? {saveError} : null} + + + {!readonly ? ( + <> + + + + + ) : null} + +
+ + +
+ ); +} diff --git a/apps/frontend/src/components/settings/rag-provider-card-grid.tsx b/apps/frontend/src/components/settings/rag-provider-card-grid.tsx new file mode 100644 index 0000000..907ad8f --- /dev/null +++ b/apps/frontend/src/components/settings/rag-provider-card-grid.tsx @@ -0,0 +1,380 @@ +"use client"; + +import type { LlmProviderCode } from "@text2sql/shared-types"; +import { ArrowUpRight, Sparkles } from "lucide-react"; +import { Badge } from "@/components/ui/badge"; +import { StateBlock } from "@/components/ui/state-block"; +import { cn } from "@/lib/utils"; + +export type RagProviderTaskType = "embedding" | "rerank"; + +export interface RagProviderPreset { + provider: LlmProviderCode; + displayName: string; + summary: string; + defaultBaseUrl: string; + recommendedModel: string; + mode?: "compatible" | "native"; + tags: string[]; + hint: string; +} + +interface RagProviderCardGridProps { + taskType: RagProviderTaskType; + activeProvider?: string | null; + readonly?: boolean; + loading?: boolean; + dirty?: boolean; + onSelectProvider: (preset: RagProviderPreset) => void; +} + +const PROVIDER_CARD_STYLE: Record = { + openai: "from-slate-900 to-slate-700 text-white", + gemini: "from-emerald-600 to-cyan-600 text-white", + deepseek: "from-indigo-700 to-sky-600 text-white", + kimi: "from-sky-700 to-blue-500 text-white", + volcengine: "from-orange-600 to-rose-500 text-white", + siliconflow: "from-teal-600 to-emerald-500 text-white", + openrouter: "from-slate-700 to-indigo-600 text-white", + minimax: "from-fuchsia-600 to-pink-500 text-white", + "tencent-hunyuan": "from-sky-700 to-cyan-600 text-white", + tongyi: "from-amber-600 to-orange-500 text-white" +}; + +const EMBEDDING_PRESETS: RagProviderPreset[] = [ + { + provider: "openai", + displayName: "OpenAI", + summary: "通用 Embedding 接入，适合英文与混合文本检索。", + defaultBaseUrl: "https://api.openai.com/v1", + recommendedModel: "text-embedding-3-small", + tags: ["EMBEDDING", "OPENAI"], + hint: "推荐走 /embeddings" + }, + { + provider: "gemini", + displayName: "Gemini", + summary: "Google 多模态生态，可接入原生 Embedding 模型。", + defaultBaseUrl: "https://generativelanguage.googleapis.com/v1beta", + recommendedModel: "", + tags: ["EMBEDDING", "MULTIMODAL"], + hint: "模型需手动确认" + }, + { + provider: "deepseek", + displayName: "DeepSeek", + summary: "适合统一使用兼容网关时的 Embedding 接入。", + defaultBaseUrl: "https://api.deepseek.com/v1", + recommendedModel: "", + tags: ["EMBEDDING", "REASONING"], + hint: "模型需手动确认" + }, + { + provider: "kimi", + displayName: "Kimi", + summary: "适合长上下文知识场景，可手动填写对应模型。", + defaultBaseUrl: "https://api.moonshot.cn/v1", + recommendedModel: "", + tags: ["EMBEDDING", "LONG_CTX"], + hint: "模型需手动确认" + }, + { + provider: "volcengine", + displayName: "火山引擎", + summary: "Ark 兼容模式接入，适合中文语义检索。", + defaultBaseUrl: "https://ark.cn-beijing.volces.com/api/v3", + recommendedModel: "doubao-embedding-text-240715", + mode: "compatible", + tags: ["EMBEDDING", "CN"], + hint: "兼容模式默认可用" + }, + { + provider: "siliconflow", + displayName: "硅基流动", + summary: "聚合平台接入，适合快速验证 BGE 向量模型。", + defaultBaseUrl: "https://api.siliconflow.cn/v1", + recommendedModel: "BAAI/bge-m3", + mode: "compatible", + tags: ["EMBEDDING", "AGGREGATOR"], + hint: "推荐 BGE 系列" + }, + { + provider: "openrouter", + displayName: "OpenRouter", + summary: "聚合多家供应商，便于后续统一切换。", + defaultBaseUrl: "https://openrouter.ai/api/v1", + recommendedModel: "", + tags: ["EMBEDDING", "ROUTER"], + hint: "模型需手动确认" + }, + { + provider: "minimax", + displayName: "MiniMax", + summary: "适合统一平台治理时补充 Embedding 能力。", + defaultBaseUrl: "https://api.minimax.chat/v1", + recommendedModel: "", + tags: ["EMBEDDING", "CHAT"], + hint: "模型需手动确认" + }, + { + provider: "tencent-hunyuan", + displayName: "腾讯混元", + summary: "企业网关兼容接入，可统一纳入治理视图。", + defaultBaseUrl: "https://api.hunyuan.cloud.tencent.com/v1", + recommendedModel: "", + tags: ["EMBEDDING", "COMPATIBLE"], + hint: "模型需手动确认" + }, + { + provider: "tongyi", + displayName: "通义", + summary: "DashScope 兼容模式下可直接接入向量模型。", + defaultBaseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1", + recommendedModel: "text-embedding-v4", + mode: "compatible", + tags: ["EMBEDDING", "ALIBABA"], + hint: "推荐 text-embedding-v4" + } +]; + +const RERANK_PRESETS: RagProviderPreset[] = [ + { + provider: "openai", + displayName: "OpenAI", + summary: "适合以通用推理模型做轻量 rerank 验证。", + defaultBaseUrl: "https://api.openai.com/v1", + recommendedModel: "gpt-4.1-mini", + tags: ["RERANK", "OPENAI"], + hint: "LLM rerank" + }, + { + provider: "gemini", + displayName: "Gemini", + summary: "适合长上下文重排，可手动指定候选模型。", + defaultBaseUrl: "https://generativelanguage.googleapis.com/v1beta", + recommendedModel: "", + tags: ["RERANK", "MULTIMODAL"], + hint: "模型需手动确认" + }, + { + provider: "deepseek", + displayName: "DeepSeek", + summary: "推理导向模型，适合复杂文本对比与排序。", + defaultBaseUrl: "https://api.deepseek.com/v1", + recommendedModel: "", + tags: ["RERANK", "REASONING"], + hint: "模型需手动确认" + }, + { + provider: "kimi", + displayName: "Kimi", + summary: "可用于长文档场景下的语义重排。", + defaultBaseUrl: "https://api.moonshot.cn/v1", + recommendedModel: "", + tags: ["RERANK", "LONG_CTX"], + hint: "模型需手动确认" + }, + { + provider: "volcengine", + displayName: "火山引擎", + summary: "Ark 兼容模式支持专用 rerank 接口。", + defaultBaseUrl: "https://ark.cn-beijing.volces.com/api/v3", + recommendedModel: "doubao-rerank-v1", + mode: "compatible", + tags: ["RERANK", "CN"], + hint: "推荐 /rerank" + }, + { + provider: "siliconflow", + displayName: "硅基流动", + summary: "聚合模型平台，适合快速验证 reranker。", + defaultBaseUrl: "https://api.siliconflow.cn/v1", + recommendedModel: "BAAI/bge-reranker-v2-m3", + mode: "compatible", + tags: ["RERANK", "AGGREGATOR"], + hint: "推荐 BGE reranker" + }, + { + provider: "openrouter", + displayName: "OpenRouter", + summary: "统一供应商入口，适合平台层切换治理。", + defaultBaseUrl: "https://openrouter.ai/api/v1", + recommendedModel: "", + tags: ["RERANK", "ROUTER"], + hint: "模型需手动确认" + }, + { + provider: "minimax", + displayName: "MiniMax", + summary: "适合作为平台内补充的重排入口。", + defaultBaseUrl: "https://api.minimax.chat/v1", + recommendedModel: "", + tags: ["RERANK", "CHAT"], + hint: "模型需手动确认" + }, + { + provider: "tencent-hunyuan", + displayName: "腾讯混元", + summary: "适合企业环境内统一接入与治理。", + defaultBaseUrl: "https://api.hunyuan.cloud.tencent.com/v1", + recommendedModel: "", + tags: ["RERANK", "COMPATIBLE"], + hint: "模型需手动确认" + }, + { + provider: "tongyi", + displayName: "通义", + summary: "DashScope 兼容模式下可直接接入排序模型。", + defaultBaseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1", + recommendedModel: "gte-rerank-v2", + mode: "compatible", + tags: ["RERANK", "ALIBABA"], + hint: "推荐 gte-rerank-v2" + } +]; + +export function listRagProviderPresets( + taskType: RagProviderTaskType +): RagProviderPreset[] { + return taskType === "embedding" ? EMBEDDING_PRESETS : RERANK_PRESETS; +} + +export function resolveRagProviderPreset( + taskType: RagProviderTaskType, + provider?: string | null +): RagProviderPreset | null { + if (!provider) { + return null; + } + return ( + listRagProviderPresets(taskType).find((preset) => preset.provider === provider) ?? null + ); +} + +function resolveInitials(displayName: string): string { + const compact = displayName.replace(/\s+/g, ""); + return compact.slice(0, 2).toUpperCase(); +} + +export function RagProviderCardGrid({ + taskType, + activeProvider, + readonly = false, + loading = false, + dirty = false, + onSelectProvider +}: RagProviderCardGridProps) { + const presets = listRagProviderPresets(taskType); + + return ( +
+ {readonly ? ( + 当前账号只读，可查看已激活 provider 摘要。 + ) : null} +
+ {presets.map((preset) => { + const active = activeProvider?.trim() === preset.provider; + return ( + + ); + })} +
+
+ ); +} diff --git a/apps/frontend/src/components/settings/rag-rerank-config-panel.tsx b/apps/frontend/src/components/settings/rag-rerank-config-panel.tsx new file mode 100644 index 0000000..62c68a9 --- /dev/null +++ b/apps/frontend/src/components/settings/rag-rerank-config-panel.tsx @@ -0,0 +1,646 @@ +"use client"; + +import { useEffect, useMemo, useState } from "react"; +import type { + LlmProviderCode, + RagTaskConfig, + RagTaskConfigHealthRequest +} from "@text2sql/shared-types"; +import { ChevronDown, RefreshCw, SlidersHorizontal, Waypoints } from "lucide-react"; +import { Badge } from "@/components/ui/badge"; +import { Button } from "@/components/ui/button"; +import { + Collapsible, + CollapsibleContent, + CollapsibleTrigger +} from "@/components/ui/collapsible"; +import { + Dialog, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle +} from "@/components/ui/dialog"; +import { Input } from "@/components/ui/input"; +import { Label } from "@/components/ui/label"; +import { NativeSelect, NativeSelectOption } from "@/components/ui/native-select"; +import { + Select, + SelectContent, + SelectItem, + SelectTrigger, + SelectValue +} from "@/components/ui/select"; +import { StateBlock } from "@/components/ui/state-block"; +import { + RagProviderCardGrid, + resolveRagProviderPreset +} from "@/components/settings/rag-provider-card-grid"; +import type { + RagProviderModelPreviewResult, + RagTaskConfigHealthResult, + RagTaskConfigPayload +} from "@/lib/settings-api-client"; + +interface RagRerankConfigPanelProps { + actorRole: "admin" | "user"; + config: RagTaskConfig | null; + loading?: boolean; + onSave: (payload: RagTaskConfigPayload) => Promise; + onFetchModels: (payload: { + provider: LlmProviderCode; + baseUrl?: string; + apiKey: string; + }) => Promise; + onHealthCheck: ( + payload: RagTaskConfigHealthRequest + ) => Promise; +} + +function resolveConfigVersion(config: RagTaskConfig | null): string { + if (!config) { + return "missing"; + } + return [ + config.id, + config.updatedAt, + config.provider, + config.model, + config.baseUrl ?? "", + config.enabled ? "1" : "0", + config.timeoutMs ?? "" + ].join(":"); +} + +export function RagRerankConfigPanel({ + actorRole, + config, + loading = false, + onSave, + onFetchModels, + onHealthCheck +}: RagRerankConfigPanelProps) { + const [provider, setProvider] = useState(""); + const [model, setModel] = useState(""); + const [baseUrl, setBaseUrl] = useState(""); + const [apiKey, setApiKey] = useState(""); + const [enabled, setEnabled] = useState(true); + const [timeoutMs, setTimeoutMs] = useState(""); + const [note, setNote] = useState(""); + const [dirty, setDirty] = useState(false); + const [dialogOpen, setDialogOpen] = useState(false); + const [lastSyncedConfigVersion, setLastSyncedConfigVersion] = useState("missing"); + const [remoteUpdateAvailable, setRemoteUpdateAvailable] = useState(false); + const [saving, setSaving] = useState(false); + const [checking, setChecking] = useState(false); + const [saveStatus, setSaveStatus] = useState(""); + const [saveError, setSaveError] = useState(""); + const [checkStatus, setCheckStatus] = useState(""); + const [checkError, setCheckError] = useState(""); + const [checkedAgainst, setCheckedAgainst] = useState<"draft" | "persisted" | null>(null); + const [fetchingModels, setFetchingModels] = useState(false); + const [modelFetchStatus, setModelFetchStatus] = useState(""); + const [modelFetchError, setModelFetchError] = useState(""); + const [modelOptions, setModelOptions] = useState([]); + const [advancedOpen, setAdvancedOpen] = useState(false); + + const configVersion = resolveConfigVersion(config); + const readonly = actorRole !== "admin"; + const selectedPreset = useMemo( + () => resolveRagProviderPreset("rerank", provider), + [provider] + ); + const currentPreset = useMemo( + () => resolveRagProviderPreset("rerank", config?.provider), + [config?.provider] + ); + + const syncFromConfig = (nextConfig: RagTaskConfig | null) => { + setProvider(nextConfig?.provider ?? ""); + setModel(nextConfig?.model ?? ""); + setBaseUrl(nextConfig?.baseUrl ?? ""); + setApiKey(""); + setEnabled(nextConfig?.enabled ?? true); + setTimeoutMs(nextConfig?.timeoutMs ? String(nextConfig.timeoutMs) : ""); + setNote(nextConfig?.note ?? ""); + setModelOptions([]); + setModelFetchStatus(""); + setModelFetchError(""); + setAdvancedOpen(false); + }; + + useEffect(() => { + if (!dirty) { + syncFromConfig(config); + setLastSyncedConfigVersion(configVersion); + setRemoteUpdateAvailable(false); + return; + } + if (configVersion !== lastSyncedConfigVersion) { + setRemoteUpdateAvailable(true); + } + }, [config, configVersion, dirty, lastSyncedConfigVersion]); + + const markDirty = () => { + if (!dirty) { + setDirty(true); + } + setSaveStatus(""); + setSaveError(""); + setCheckStatus(""); + setCheckError(""); + setModelFetchStatus(""); + setModelFetchError(""); + setCheckedAgainst(null); + }; + + const resetToLatest = () => { + syncFromConfig(config); + setDirty(false); + setRemoteUpdateAvailable(false); + setLastSyncedConfigVersion(resolveConfigVersion(config)); + setSaveStatus(""); + setSaveError(""); + setCheckStatus(""); + setCheckError(""); + setModelFetchStatus(""); + setModelFetchError(""); + setCheckedAgainst(null); + }; + + const fetchModels = async () => { + if (!provider.trim()) { + setModelFetchError("请先选择 Provider。"); + return; + } + if (!apiKey.trim()) { + setModelFetchError("请先填写 API Key，再获取模型。"); + return; + } + + setFetchingModels(true); + setModelFetchStatus(""); + setModelFetchError(""); + try { + const result = await onFetchModels({ + provider: provider as LlmProviderCode, + baseUrl: baseUrl.trim() || undefined, + apiKey: apiKey.trim() + }); + setModelOptions(result.models); + const nextModel = + result.recommendedModel && result.models.some((item) => item.model === result.recommendedModel) + ? result.recommendedModel + : result.models[0]?.model; + if (!model.trim() && nextModel) { + setModel(nextModel); + } + setModelFetchStatus( + result.models.length > 0 + ? `已拉取 ${result.models.length} 个官方模型，可直接选择或继续手动填写。` + : "已请求官方模型目录，但当前未返回可选模型。" + ); + } catch (error) { + setModelOptions([]); + setModelFetchError(error instanceof Error ? error.message : "获取模型失败"); + } finally { + setFetchingModels(false); + } + }; + + const saveDraft = async () => { + setSaving(true); + setSaveStatus(""); + setSaveError(""); + try { + await onSave({ + provider: provider.trim(), + model: model.trim(), + baseUrl: baseUrl.trim() || undefined, + apiKey: apiKey.trim() || undefined, + enabled, + timeoutMs: timeoutMs.trim() ? Number(timeoutMs) : undefined, + note: note.trim() || undefined + }); + setApiKey(""); + setDirty(false); + setRemoteUpdateAvailable(false); + setSaveStatus("保存成功，Rerank 配置已写入。"); + setDialogOpen(false); + } catch (error) { + setSaveError(error instanceof Error ? error.message : "保存失败"); + } finally { + setSaving(false); + } + }; + + const checkDraft = async () => { + setChecking(true); + setCheckStatus(""); + setCheckError(""); + try { + const result = await onHealthCheck({ + sampleQuery: "revenue by status", + draft: { + provider: provider.trim(), + model: model.trim(), + baseUrl: baseUrl.trim() || undefined, + apiKey: apiKey.trim() || undefined, + enabled, + timeoutMs: timeoutMs.trim() ? Number(timeoutMs) : undefined, + note: note.trim() || undefined + } + }); + setCheckedAgainst(result.checkedAgainst); + setCheckStatus( + `检测结果: ${result.status} · code=${result.reasonCode} · source=${result.configSource} · checkedAgainst=${result.checkedAgainst}` + ); + } catch (error) { + setCheckError(error instanceof Error ? error.message : "检测失败"); + } finally { + setChecking(false); + } + }; + + return ( +
+
+
+
+
+
+
+ +
+
+

+ Rerank Workspace +

+

+ Rerank Provider +

+
+
+

+ 管理候选重排模型的接入与测试。确认供应商后，可直接在弹窗里做 sample + query 验证；也可以先填 API Key，再从官方模型目录中挑选模型。 +

+
+
+ + {config?.configSource ?? "missing"} + + + {config?.healthStatus ?? "unknown"} + + + {dirty ? "draft" : "synced"} + + {checkedAgainst ? ( + {`checked:${checkedAgainst}`} + ) : null} +
+
+ +
+
+

+ 当前生效 Provider +

+

+ {currentPreset?.displayName ?? config?.provider ?? "尚未配置"} +

+

+ {config?.baseUrl ?? "Base URL 将在弹窗中配置"} +

+
+
+

+ 当前模型与运行参数 +

+

+ {config?.model ?? "点击卡片后填写模型"} +

+
+ + {config?.hasApiKey ? "API Key 已配置" : "API Key 待填写"} + + + {config?.timeoutMs ? `timeout=${config.timeoutMs}ms` : "超时未指定"} + +
+
+
+ +
+
+
+
+ +
+ {loading ? Rerank 配置加载中... : null} + {!config && !loading ? ( + + 当前还没有 Rerank 配置，直接点击卡片即可开始接入。 + + ) : null} + {remoteUpdateAvailable ? ( + + 检测到后台配置更新，当前草稿已保护。可继续编辑，或在弹窗里重置为最新配置。 + + ) : null} + { + if (preset.provider === provider.trim()) { + setDialogOpen(true); + return; + } + markDirty(); + setProvider(preset.provider); + setModel(preset.recommendedModel); + setBaseUrl(preset.defaultBaseUrl); + if (!note.trim()) { + setNote(`preset=${preset.provider}${preset.mode ? `;mode=${preset.mode}` : ""}`); + } + setDialogOpen(true); + }} + /> + {readonly ? ( + 当前账号只读，可查看配置摘要。 + ) : null} + {saveStatus ? {saveStatus} : null} + {saveError ? {saveError} : null} + {config ? ( +

+ 上次检查：{config.lastCheckedAt ?? "未检查"} · 来源说明：{config.configSourceNote ?? "无"} +

+ ) : null} +
+ + + +
+ + + 配置 Rerank: {(selectedPreset?.displayName ?? provider) || "新 Provider"} + + + 先选 Provider、填写 API Key，再获取官方模型目录。若未返回专用 rerank 模型，也可直接手动填写 LLM 模型做重排验证。 + + + +
+
+ + + 自动附带 sample query + + + 草稿检测不落库 + + + 保存后立即生效 + +
+
+ + {remoteUpdateAvailable ? ( + + 后台配置已更新；当前弹窗仍保留你的草稿，可继续调整或重置。 + + ) : null} + +
+
+ +
+
+ + {selectedPreset?.displayName ?? currentPreset?.displayName ?? "请从上方卡片选择"} + + {provider.trim() ? ( + + {provider} + + ) : null} +
+

+ Provider 通过卡片选择，不需要手动填写。 +

+
+
+
+ + { + markDirty(); + setModel(event.target.value); + }} + placeholder="model" + aria-label="rerank-model" + disabled={readonly || loading || saving} + /> +
+
+ + +
+
+ + { + markDirty(); + setBaseUrl(event.target.value); + }} + placeholder="base url" + aria-label="rerank-base-url" + disabled={readonly || loading || saving} + /> +
+
+ + { + markDirty(); + setApiKey(event.target.value); + }} + placeholder={config?.apiKeyMasked ?? "api key"} + aria-label="rerank-api-key" + disabled={readonly || loading || saving} + /> +
+ {modelOptions.length > 0 ? ( +
+ + +
+ ) : null} +
+ +
+ + + + +
+
+ + { + markDirty(); + setTimeoutMs(event.target.value); + }} + placeholder="timeout ms" + aria-label="rerank-timeout-ms" + disabled={readonly || loading || saving} + /> +
+
+ + { + markDirty(); + setEnabled(event.target.value === "enabled"); + }} + aria-label="rerank-enabled" + disabled={readonly || loading || saving} + > + enabled + disabled + +
+
+ + { + markDirty(); + setNote(event.target.value); + }} + placeholder="可选备注" + aria-label="rerank-note" + disabled={readonly || loading || saving} + /> +
+
+ +
+ +
+
+ + {modelFetchStatus ? {modelFetchStatus} : null} + {modelFetchError ? {modelFetchError} : null} + {checkStatus ? {checkStatus} : null} + {checkError ? {checkError} : null} + {saveError ? {saveError} : null} + + + {!readonly ? ( + <> + + + + + ) : null} + +
+ + +
+ ); +} diff --git a/apps/frontend/src/lib/settings-api-client.ts b/apps/frontend/src/lib/settings-api-client.ts index 696a3fb..132ef08 100644 --- a/apps/frontend/src/lib/settings-api-client.ts +++ b/apps/frontend/src/lib/settings-api-client.ts @@ -4,6 +4,11 @@ import type { LlmSettingsView, ModelCatalogItem, ProviderConfig, + RagTaskConfig, + RagTaskConfigHealthRequest, + RagTaskConfigHealthResult as SharedRagTaskConfigHealthResult, + RagTaskSettingsView, + RagTaskType, RagMemoryFeedbackRequest, RagMemoryFeedbackResponse, RagQualityGateReport, @@ -217,6 +222,38 @@ export type ProviderPayload = { enabled?: boolean; }; +export type RagTaskConfigPayload = { + provider: string; + model: string; + baseUrl?: string; + apiKey?: string; + enabled?: boolean; + dimensions?: number; + vectorVersion?: string; + timeoutMs?: number; + note?: string; +}; + +export type RagTaskConfigHealthPayload = RagTaskConfigHealthRequest; +export type RagTaskConfigHealthResult = SharedRagTaskConfigHealthResult; +export type RagProviderModelPreviewRequest = { + provider: LlmProviderCode; + baseUrl?: string; + apiKey: string; +}; +export type RagProviderModelPreviewResult = { + provider: LlmProviderCode; + supportsModelListing: boolean; + recommendedModel?: string; + models: Array<{ + model: string; + displayName: string; + capabilities?: string[]; + contextWindow?: number | null; + metadata?: Record; + }>; +}; + async function request(url: string, init?: RequestInit): Promise { const role = process.env.NEXT_PUBLIC_USER_ROLE === "user" ? "user" : "admin"; const userId = process.env.NEXT_PUBLIC_USER_ID ?? "frontend-admin"; @@ -254,6 +291,49 @@ export async function fetchSupportedProviders(): Promise { return request("/api/v1/settings/providers/supported"); } +export async function fetchRagTaskConfigs(): Promise { + return request("/api/v1/settings/rag-configs"); +} + +export async function upsertRagTaskConfig( + taskType: RagTaskType, + payload: RagTaskConfigPayload +): Promise { + return request( + `/api/v1/settings/rag-configs/${encodeURIComponent(taskType)}`, + { + method: "PUT", + body: JSON.stringify(payload) + } + ); +} + +export async function checkRagTaskConfigHealth( + taskType: RagTaskType, + payload?: RagTaskConfigHealthRequest +): Promise { + return request( + `/api/v1/settings/rag-configs/${encodeURIComponent(taskType)}/health`, + { + method: "POST", + body: JSON.stringify(payload ?? {}) + } + ); +} + +export async function previewRagProviderModels( + taskType: RagTaskType, + payload: RagProviderModelPreviewRequest +): Promise { + return request( + `/api/v1/settings/rag-configs/${encodeURIComponent(taskType)}/models`, + { + method: "POST", + body: JSON.stringify(payload) + } + ); +} + export async function createProviderConfig( payload: ProviderPayload ): Promise { diff --git a/apps/frontend/tests/e2e/chat-mobile-smoke.spec.tsx b/apps/frontend/tests/e2e/chat-mobile-smoke.spec.tsx index 55f7e03..f7bb2e8 100644 --- a/apps/frontend/tests/e2e/chat-mobile-smoke.spec.tsx +++ b/apps/frontend/tests/e2e/chat-mobile-smoke.spec.tsx @@ -178,7 +178,9 @@ describe("chat mobile smoke", () => { vi.clearAllMocks(); }); - it("renders mobile-usable chat controls and progressive delivery toggles", async () => { + it( + "renders mobile-usable chat controls and progressive delivery toggles", + async () => { const user = userEvent.setup(); render(); await screen.findByText(/Datasource: sqlite_main · Session: session-1/i); @@ -237,5 +239,7 @@ describe("chat mobile smoke", () => { expect( screen.getByRole("link", { name: "设置 / RAG 运行与记忆治理" }) ).toHaveAttribute("href", "/settings?tab=rag&runId=run-1"); - }); + }, + 15000 + ); }); diff --git a/apps/frontend/tests/e2e/settings-mobile-smoke.spec.tsx b/apps/frontend/tests/e2e/settings-mobile-smoke.spec.tsx index 53e9260..52b891d 100644 --- a/apps/frontend/tests/e2e/settings-mobile-smoke.spec.tsx +++ b/apps/frontend/tests/e2e/settings-mobile-smoke.spec.tsx @@ -6,6 +6,7 @@ import SettingsPage from "@/app/settings/page"; import { getRun } from "@/lib/api-client"; import { fetchBackendHealthSnapshot, + fetchRagTaskConfigs, fetchRagQualityReport, fetchRagReplayCompleteness, fetchSettingsView, @@ -35,6 +36,7 @@ vi.mock("@/lib/settings-api-client", async (importOriginal) => { ...actual, fetchSettingsView: vi.fn(), fetchSupportedProviders: vi.fn(), + fetchRagTaskConfigs: vi.fn(), fetchBackendHealthSnapshot: vi.fn(), fetchRagQualityReport: vi.fn(), fetchRagReplayCompleteness: vi.fn() @@ -44,6 +46,7 @@ vi.mock("@/lib/settings-api-client", async (importOriginal) => { const mockGetRun = vi.mocked(getRun); const mockFetchSettingsView = vi.mocked(fetchSettingsView); const mockFetchSupportedProviders = vi.mocked(fetchSupportedProviders); +const mockFetchRagTaskConfigs = vi.mocked(fetchRagTaskConfigs); const mockFetchBackendHealthSnapshot = vi.mocked(fetchBackendHealthSnapshot); const mockFetchRagQualityReport = vi.mocked(fetchRagQualityReport); const mockFetchRagReplayCompleteness = vi.mocked(fetchRagReplayCompleteness); @@ -71,6 +74,13 @@ describe("settings mobile smoke", () => { mockFetchSettingsView.mockResolvedValue(createSettingsView("user")); mockFetchSupportedProviders.mockResolvedValue([]); + mockFetchRagTaskConfigs.mockResolvedValue({ + actor: { + id: "frontend-user", + role: "user" + }, + items: [] + }); mockFetchBackendHealthSnapshot.mockResolvedValue({ status: "ok", dependencies: { diff --git a/apps/frontend/tests/unit/chat-panel.spec.tsx b/apps/frontend/tests/unit/chat-panel.spec.tsx index 49659cf..03b85fe 100644 --- a/apps/frontend/tests/unit/chat-panel.spec.tsx +++ b/apps/frontend/tests/unit/chat-panel.spec.tsx @@ -204,6 +204,64 @@ describe("ChatPanel", () => { ).toHaveAttribute("href", "/settings?tab=rag&runId=run-1"); }); + it("shows live thinking steps before the model emits text", async () => { + let releaseStream: (() => void) | undefined; + const streamGate = new Promise((resolve) => { + releaseStream = resolve; + }); + mockStreamMessageEvents.mockImplementationOnce(async function* () { + yield { + type: "start", + runId: "run-thinking", + sessionId: "session-1", + at: "2026-04-10T00:00:00.000Z", + data: { + requestId: null + } + }; + yield { + type: "state", + runId: "run-thinking", + sessionId: "session-1", + at: "2026-04-10T00:00:01.000Z", + data: { + node: "generate-sql", + status: "success", + stepId: "run-thinking:generate-sql:5", + sequence: 5, + lifecycle: "running", + detail: "正在调用 LLM 生成 SQL，可继续等待流式进度。", + stage: "generation", + title: "生成 SQL" + } + }; + await streamGate; + yield { + type: "finish", + runId: "run-thinking", + sessionId: "session-1", + at: "2026-04-10T00:00:02.000Z", + data: { + status: "failed", + rowCount: 0 + } + }; + }); + + const user = userEvent.setup(); + render(); + + await screen.findByText(/Datasource: sqlite_main · Session: session-1/i); + await user.type(screen.getByLabelText("聊天输入"), "有多少种支付方式，他们比例是如何"); + await user.click(screen.getByRole("button", { name: "发送" })); + + const liveThinking = await screen.findByTestId("assistant-live-thinking"); + expect(liveThinking).toHaveAttribute("data-run-id", "run-thinking"); + expect(screen.getByText("活跃步骤：生成 SQL（进行中）")).toBeInTheDocument(); + + releaseStream?.(); + }); + it("submits by pressing Enter in chat input", async () => { const user = userEvent.setup(); render(); diff --git a/apps/frontend/tests/unit/glossary-page.spec.tsx b/apps/frontend/tests/unit/glossary-page.spec.tsx index d07f614..2304d3f 100644 --- a/apps/frontend/tests/unit/glossary-page.spec.tsx +++ b/apps/frontend/tests/unit/glossary-page.spec.tsx @@ -119,85 +119,89 @@ describe("GlossaryPage", () => { mockListDatasources.mockResolvedValue(DATASOURCES); }); - it("supports create and update flows with scope/priority controls and linkage feedback", async () => { - const user = userEvent.setup(); - const updatedGlobalTerm: GlossaryTerm = { + it( + "supports create and update flows with scope/priority controls and linkage feedback", + async () => { + const user = userEvent.setup(); + const updatedGlobalTerm: GlossaryTerm = { ...GLOBAL_TERM, definition: "gross merchandise value updated", priority: 77, updatedAt: "2026-04-11T00:00:00.000Z" - }; - - mockListGlossaryTerms - .mockResolvedValueOnce(listResult([GLOBAL_TERM])) - .mockResolvedValueOnce(listResult([DATASOURCE_TERM, GLOBAL_TERM])) - .mockResolvedValueOnce(listResult([DATASOURCE_TERM, updatedGlobalTerm])); - - mockCreateGlossaryTerm.mockResolvedValue( - upsertResponse(DATASOURCE_TERM, { - linkageStatus: "degraded", - conflictDecision: { - resolution: "priority_then_updated_at", - winnerTermId: DATASOURCE_TERM.id, - loserTermIds: [GLOBAL_TERM.id], - winnerPriority: DATASOURCE_TERM.priority, - winnerUpdatedAt: DATASOURCE_TERM.updatedAt - } - }) - ); - mockUpdateGlossaryTerm.mockResolvedValue(upsertResponse(updatedGlobalTerm)); - - render(); - expect(await screen.findByText("GMV")).toBeInTheDocument(); - - await user.click(screen.getByRole("button", { name: "新增术语" })); - await user.type(screen.getByLabelText("术语名称"), "订单"); - await user.type(screen.getByLabelText("同义词"), "order"); - await user.type(screen.getByLabelText("定义"), "订单事实表"); - await user.selectOptions(screen.getByLabelText("作用范围"), "datasource"); - await user.selectOptions(screen.getByLabelText("数据源范围"), "sqlite_main"); - await user.clear(screen.getByLabelText("优先级（0-100）")); - await user.type(screen.getByLabelText("优先级（0-100）"), "90"); - await user.click(screen.getByRole("button", { name: "保存" })); - - await waitFor(() => { - expect(mockCreateGlossaryTerm).toHaveBeenCalledWith( - { - term: "订单", - definition: "订单事实表", - synonyms: ["order"], - scope: "datasource", - datasourceId: "sqlite_main", - priority: 90 - }, - expect.objectContaining({ idempotencyKey: expect.any(String) }) + }; + + mockListGlossaryTerms + .mockResolvedValueOnce(listResult([GLOBAL_TERM])) + .mockResolvedValueOnce(listResult([DATASOURCE_TERM, GLOBAL_TERM])) + .mockResolvedValueOnce(listResult([DATASOURCE_TERM, updatedGlobalTerm])); + + mockCreateGlossaryTerm.mockResolvedValue( + upsertResponse(DATASOURCE_TERM, { + linkageStatus: "degraded", + conflictDecision: { + resolution: "priority_then_updated_at", + winnerTermId: DATASOURCE_TERM.id, + loserTermIds: [GLOBAL_TERM.id], + winnerPriority: DATASOURCE_TERM.priority, + winnerUpdatedAt: DATASOURCE_TERM.updatedAt + } + }) ); - }); - expect(await screen.findByText(/作用域规则：同名术语下，数据源作用域优先于全局。/)).toBeInTheDocument(); - expect(screen.getByText(/联动降级：术语已保存，RAG 联动当前处于降级状态。/)).toBeInTheDocument(); - - const gmvRow = screen.getByText("GMV").closest("tr"); - expect(gmvRow).not.toBeNull(); - await user.click(within(gmvRow!).getByRole("button", { name: /编辑/ })); - const definitionField = screen.getByLabelText("定义"); - await user.clear(definitionField); - await user.type(definitionField, "gross merchandise value updated"); - await user.clear(screen.getByLabelText("优先级（0-100）")); - await user.type(screen.getByLabelText("优先级（0-100）"), "77"); - await user.click(screen.getByRole("button", { name: "保存" })); - - await waitFor(() => { - expect(mockUpdateGlossaryTerm).toHaveBeenCalledWith( - GLOBAL_TERM.id, - expect.objectContaining({ - definition: "gross merchandise value updated", - priority: 77 - }), - expect.objectContaining({ idempotencyKey: expect.any(String) }) - ); - }); - expect(await screen.findByText(/术语已更新。/)).toBeInTheDocument(); - }); + mockUpdateGlossaryTerm.mockResolvedValue(upsertResponse(updatedGlobalTerm)); + + render(); + expect(await screen.findByText("GMV")).toBeInTheDocument(); + + await user.click(screen.getByRole("button", { name: "新增术语" })); + await user.type(screen.getByLabelText("术语名称"), "订单"); + await user.type(screen.getByLabelText("同义词"), "order"); + await user.type(screen.getByLabelText("定义"), "订单事实表"); + await user.selectOptions(screen.getByLabelText("作用范围"), "datasource"); + await user.selectOptions(screen.getByLabelText("数据源范围"), "sqlite_main"); + await user.clear(screen.getByLabelText("优先级（0-100）")); + await user.type(screen.getByLabelText("优先级（0-100）"), "90"); + await user.click(screen.getByRole("button", { name: "保存" })); + + await waitFor(() => { + expect(mockCreateGlossaryTerm).toHaveBeenCalledWith( + { + term: "订单", + definition: "订单事实表", + synonyms: ["order"], + scope: "datasource", + datasourceId: "sqlite_main", + priority: 90 + }, + expect.objectContaining({ idempotencyKey: expect.any(String) }) + ); + }); + expect(await screen.findByText(/作用域规则：同名术语下，数据源作用域优先于全局。/)).toBeInTheDocument(); + expect(screen.getByText(/联动降级：术语已保存，RAG 联动当前处于降级状态。/)).toBeInTheDocument(); + + const gmvRow = screen.getByText("GMV").closest("tr"); + expect(gmvRow).not.toBeNull(); + await user.click(within(gmvRow!).getByRole("button", { name: /编辑/ })); + const definitionField = screen.getByLabelText("定义"); + await user.clear(definitionField); + await user.type(definitionField, "gross merchandise value updated"); + await user.clear(screen.getByLabelText("优先级（0-100）")); + await user.type(screen.getByLabelText("优先级（0-100）"), "77"); + await user.click(screen.getByRole("button", { name: "保存" })); + + await waitFor(() => { + expect(mockUpdateGlossaryTerm).toHaveBeenCalledWith( + GLOBAL_TERM.id, + expect.objectContaining({ + definition: "gross merchandise value updated", + priority: 77 + }), + expect.objectContaining({ idempotencyKey: expect.any(String) }) + ); + }); + expect(await screen.findByText(/术语已更新。/)).toBeInTheDocument(); + }, + 15000 + ); it("shows readable feedback when non-admin toggle gets 403", async () => { const user = userEvent.setup(); diff --git a/apps/frontend/tests/unit/rag-embedding-config-panel.spec.tsx b/apps/frontend/tests/unit/rag-embedding-config-panel.spec.tsx new file mode 100644 index 0000000..c5649c6 --- /dev/null +++ b/apps/frontend/tests/unit/rag-embedding-config-panel.spec.tsx @@ -0,0 +1,187 @@ +import { render, screen } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { describe, expect, it, vi } from "vitest"; +import { RagEmbeddingConfigPanel } from "@/components/settings/rag-embedding-config-panel"; + +const baseConfig = { + id: "rag-embedding", + taskType: "embedding" as const, + provider: "openai", + model: "text-embedding-3-small", + baseUrl: "https://api.openai.com/v1", + enabled: true, + hasApiKey: true, + apiKeyMasked: "sk-e***1234", + dimensions: 1536, + vectorVersion: "v1", + timeoutMs: 30000, + note: null, + healthStatus: "unknown" as const, + lastCheckedAt: null, + lastHealthLatencyMs: null, + lastHealthMessage: null, + lastError: null, + configSource: "settings" as const, + configSourceNote: null, + createdAt: "2026-04-16T00:00:00.000Z", + updatedAt: "2026-04-16T00:00:00.000Z" +}; + +describe("RagEmbeddingConfigPanel", () => { + it("renders admin entry actions when actor is admin", () => { + render( + + ); + + expect(screen.getByRole("button", { name: "编辑当前草稿" })).toBeInTheDocument(); + expect(screen.getByText("Embedding Provider")).toBeInTheDocument(); + }); + + it("renders readonly state when actor is user", () => { + render( + + ); + + expect(screen.getByText("当前账号只读，可查看配置摘要。")).toBeInTheDocument(); + expect(screen.queryByRole("button", { name: "保存并生效" })).not.toBeInTheDocument(); + }); + + it("fills embedding defaults in dialog when provider card is selected", async () => { + const user = userEvent.setup(); + render( + + ); + + await user.click(screen.getByLabelText("embedding-preset-volcengine")); + expect(await screen.findByText("配置 Embedding: 火山引擎")).toBeInTheDocument(); + expect(screen.getByText("volcengine")).toBeInTheDocument(); + expect(screen.getByLabelText("embedding-base-url")).toHaveValue( + "https://ark.cn-beijing.volces.com/api/v3" + ); + }); + + it("keeps local draft when backend config refreshes while form is dirty", async () => { + const user = userEvent.setup(); + const { rerender } = render( + + ); + + await user.click(screen.getByRole("button", { name: "编辑当前草稿" })); + const modelInput = await screen.findByLabelText("embedding-model"); + await user.clear(modelInput); + await user.type(modelInput, "text-embedding-3-large"); + + rerender( + + ); + + expect(screen.getByLabelText("embedding-model")).toHaveValue("text-embedding-3-large"); + expect( + screen.getByText( + "检测到后台配置更新，当前草稿已保护。可继续编辑，或在弹窗里重置为最新配置。" + ) + ).toBeInTheDocument(); + }); + + it("keeps api key draft when health check fails", async () => { + const user = userEvent.setup(); + const checkError = vi.fn().mockRejectedValue(new Error("network down")); + render( + + ); + + await user.click(screen.getByRole("button", { name: "编辑当前草稿" })); + + const apiKeyInput = await screen.findByLabelText("embedding-api-key"); + await user.type(apiKeyInput, "sk-draft-value"); + await user.click(screen.getByRole("button", { name: "检测草稿（不保存）" })); + + expect(await screen.findByText("network down")).toBeInTheDocument(); + expect(screen.getByLabelText("embedding-api-key")).toHaveValue("sk-draft-value"); + }); +}); diff --git a/apps/frontend/tests/unit/rag-provider-card-grid.spec.tsx b/apps/frontend/tests/unit/rag-provider-card-grid.spec.tsx new file mode 100644 index 0000000..75d125b --- /dev/null +++ b/apps/frontend/tests/unit/rag-provider-card-grid.spec.tsx @@ -0,0 +1,61 @@ +import { render, screen } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { describe, expect, it, vi } from "vitest"; +import { RagProviderCardGrid } from "@/components/settings/rag-provider-card-grid"; + +describe("RagProviderCardGrid", () => { + it("emits provider presets for embedding cards", async () => { + const user = userEvent.setup(); + const onSelectProvider = vi.fn(); + render( + + ); + + await user.click(screen.getByLabelText("embedding-preset-volcengine")); + await user.click(screen.getByLabelText("embedding-preset-tongyi")); + await user.click(screen.getByLabelText("embedding-preset-siliconflow")); + + expect(onSelectProvider).toHaveBeenCalledTimes(3); + expect(onSelectProvider.mock.calls[0]?.[0].provider).toBe("volcengine"); + expect(onSelectProvider.mock.calls[1]?.[0].provider).toBe("tongyi"); + expect(onSelectProvider.mock.calls[2]?.[0].provider).toBe("siliconflow"); + }); + + it("protects dirty drafts with confirmation before overwrite", async () => { + const user = userEvent.setup(); + const onSelectProvider = vi.fn(); + const confirmSpy = vi.spyOn(window, "confirm").mockReturnValue(false); + render( + + ); + + await user.click(screen.getByLabelText("rerank-preset-volcengine")); + + expect(confirmSpy).toHaveBeenCalledTimes(1); + expect(onSelectProvider).not.toHaveBeenCalled(); + confirmSpy.mockRestore(); + }); + + it("does not allow readonly users to apply cards", async () => { + const user = userEvent.setup(); + const onSelectProvider = vi.fn(); + render( + + ); + + await user.click(screen.getByLabelText("embedding-preset-volcengine")); + + expect(onSelectProvider).not.toHaveBeenCalled(); + }); +}); diff --git a/apps/frontend/tests/unit/rag-rerank-config-panel.spec.tsx b/apps/frontend/tests/unit/rag-rerank-config-panel.spec.tsx new file mode 100644 index 0000000..27468a6 --- /dev/null +++ b/apps/frontend/tests/unit/rag-rerank-config-panel.spec.tsx @@ -0,0 +1,165 @@ +import { render, screen } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { describe, expect, it, vi } from "vitest"; +import { RagRerankConfigPanel } from "@/components/settings/rag-rerank-config-panel"; + +const baseConfig = { + id: "rag-rerank", + taskType: "rerank" as const, + provider: "openai", + model: "gpt-4.1-mini", + baseUrl: "https://api.openai.com/v1", + enabled: true, + hasApiKey: true, + apiKeyMasked: "sk-r***1234", + dimensions: null, + vectorVersion: null, + timeoutMs: 5000, + note: null, + healthStatus: "unknown" as const, + lastCheckedAt: null, + lastHealthLatencyMs: null, + lastHealthMessage: null, + lastError: null, + configSource: "settings" as const, + configSourceNote: null, + createdAt: "2026-04-16T00:00:00.000Z", + updatedAt: "2026-04-16T00:00:00.000Z" +}; + +describe("RagRerankConfigPanel", () => { + it("renders admin entry actions when actor is admin", () => { + render( + + ); + + expect(screen.getByRole("button", { name: "编辑当前草稿" })).toBeInTheDocument(); + expect(screen.getByText("Rerank Provider")).toBeInTheDocument(); + }); + + it("renders readonly state when actor is user", () => { + render( + + ); + + expect(screen.getByText("当前账号只读，可查看配置摘要。")).toBeInTheDocument(); + expect(screen.queryByRole("button", { name: "保存 Rerank" })).not.toBeInTheDocument(); + }); + + it("fills rerank defaults in dialog when provider card is selected", async () => { + const user = userEvent.setup(); + render( + + ); + + await user.click(screen.getByLabelText("rerank-preset-siliconflow")); + expect(await screen.findByText("配置 Rerank: 硅基流动")).toBeInTheDocument(); + expect(screen.getByText("siliconflow")).toBeInTheDocument(); + expect(screen.getByLabelText("rerank-base-url")).toHaveValue( + "https://api.siliconflow.cn/v1" + ); + }); + + it("keeps local rerank draft when backend config refreshes while dirty", async () => { + const user = userEvent.setup(); + const { rerender } = render( + + ); + + await user.click(screen.getByRole("button", { name: "编辑当前草稿" })); + + const modelInput = await screen.findByLabelText("rerank-model"); + await user.clear(modelInput); + await user.type(modelInput, "bge-reranker-v2-m3"); + + rerender( + + ); + + expect(screen.getByLabelText("rerank-model")).toHaveValue("bge-reranker-v2-m3"); + expect( + screen.getByText( + "检测到后台配置更新，当前草稿已保护。可继续编辑，或在弹窗里重置为最新配置。" + ) + ).toBeInTheDocument(); + }); +}); diff --git a/apps/frontend/tests/unit/run-visibility-mapper.spec.ts b/apps/frontend/tests/unit/run-visibility-mapper.spec.ts index 0ff84d6..6fb9283 100644 --- a/apps/frontend/tests/unit/run-visibility-mapper.spec.ts +++ b/apps/frontend/tests/unit/run-visibility-mapper.spec.ts @@ -53,6 +53,39 @@ describe("run-visibility-mapper", () => { }); }); + it("normalizes v2 loop evidence and termination reason", () => { + const normalized = normalizeDeliveryContract({ + answer: { + text: "loop answer", + status: "executionResult", + provider: "mock-provider" + }, + evidence: { + run_id: "run-loop-1", + v2: { + loop_evidence: [ + { + loop_index: 1, + trigger_reason: "semantic_plan_requires_clarification", + action_type: "clarify", + termination_reason: "clarification_requested", + convergence_path: ["planning", "clarify"] + } + ], + termination_reason: "clarification_requested" + } + } + }); + + expect(normalized?.evidence?.v2?.terminationReason).toBe("clarification_requested"); + expect(normalized?.evidence?.v2?.loopEvidence?.length).toBe(1); + expect(normalized?.evidence?.v2?.loopEvidence?.[0]?.actionType).toBe("clarify"); + expect(normalized?.evidence?.v2?.loopEvidence?.[0]?.convergencePath).toEqual([ + "planning", + "clarify" + ]); + }); + it("normalizes extended ChatBI artifact fields while keeping legacy row preview fields", () => { const normalized = normalizeDeliveryContract({ answer: { diff --git a/apps/frontend/tests/unit/settings-modeling-complete-parity.spec.tsx b/apps/frontend/tests/unit/settings-modeling-complete-parity.spec.tsx index 381e6d9..61aa693 100644 --- a/apps/frontend/tests/unit/settings-modeling-complete-parity.spec.tsx +++ b/apps/frontend/tests/unit/settings-modeling-complete-parity.spec.tsx @@ -455,6 +455,7 @@ describe("settings modeling complete parity", () => { }); it("routes node action entries with keyboard support and opens relationship dialogs", async () => { + const confirmSpy = vi.spyOn(window, "confirm").mockReturnValue(true); const user = userEvent.setup(); render(); const topStatusBar = screen.getByTestId("modeling-top-status-bar"); @@ -490,5 +491,6 @@ describe("settings modeling complete parity", () => { expect(await screen.findByRole("dialog", { name: "Edit relationship" })).toBeInTheDocument(); await user.click(screen.getByRole("button", { name: "Cancel" })); expect(topStatusBar).toHaveTextContent("Current Context: relationship · rel-orders-customers"); + confirmSpy.mockRestore(); }); }); diff --git a/apps/frontend/tests/unit/settings-modeling-workspace.spec.tsx b/apps/frontend/tests/unit/settings-modeling-workspace.spec.tsx index 0956635..7986988 100644 --- a/apps/frontend/tests/unit/settings-modeling-workspace.spec.tsx +++ b/apps/frontend/tests/unit/settings-modeling-workspace.spec.tsx @@ -1184,6 +1184,7 @@ describe("ModelingWorkspacePage", () => { render(); await waitForWorkspaceDatasourceReady(); + const confirmSpy = vi.spyOn(window, "confirm").mockReturnValue(true); await user.click(screen.getByRole("button", { name: "trigger-node-action-edit-relationship" })); expect(screen.getByTestId("modeling-top-status-bar")).toHaveTextContent( @@ -1191,6 +1192,7 @@ describe("ModelingWorkspacePage", () => { ); expect(screen.getByTestId("modeling-context-drawer")).toHaveAttribute("data-open", "false"); expect(await screen.findByRole("dialog", { name: "Edit relationship" })).toBeInTheDocument(); + confirmSpy.mockRestore(); }); it("falls back to add-relationship dialog when target relationship no longer exists", async () => { diff --git a/apps/frontend/tests/unit/settings-page-governance-visibility.spec.tsx b/apps/frontend/tests/unit/settings-page-governance-visibility.spec.tsx index a8d8fbe..b59c1e9 100644 --- a/apps/frontend/tests/unit/settings-page-governance-visibility.spec.tsx +++ b/apps/frontend/tests/unit/settings-page-governance-visibility.spec.tsx @@ -1,7 +1,11 @@ import { render, screen, waitFor } from "@testing-library/react"; import userEvent from "@testing-library/user-event"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; -import type { LlmSettingsView, RagQualityGateReport } from "@text2sql/shared-types"; +import type { + LlmSettingsView, + RagQualityGateReport, + RagTaskSettingsView +} from "@text2sql/shared-types"; import SettingsPage from "@/app/settings/page"; import { AdminApiError, @@ -12,18 +16,22 @@ import { } from "@/lib/admin-api-client"; import { batchSetModelsEnabled, + checkRagTaskConfigHealth, checkProviderHealth, createProviderConfig, deleteProviderConfig, fetchBackendHealthSnapshot, fetchModelStatuses, + previewRagProviderModels, + fetchRagTaskConfigs, fetchRagQualityReport, fetchRagReplayCompleteness, fetchSettingsView, fetchSupportedProviders, setModelEnabled, submitRagMemoryFeedback, - syncProviderModels + syncProviderModels, + upsertRagTaskConfig } from "@/lib/settings-api-client"; vi.mock("@/components/settings/model-catalog-table", () => ({ @@ -59,6 +67,10 @@ vi.mock("@/lib/settings-api-client", async (importOriginal) => { ...actual, fetchSettingsView: vi.fn(), fetchSupportedProviders: vi.fn(), + fetchRagTaskConfigs: vi.fn(), + previewRagProviderModels: vi.fn(), + upsertRagTaskConfig: vi.fn(), + checkRagTaskConfigHealth: vi.fn(), fetchBackendHealthSnapshot: vi.fn(), fetchRagQualityReport: vi.fn(), fetchRagReplayCompleteness: vi.fn(), @@ -79,6 +91,10 @@ const mockCreateGlossaryAnchor = vi.mocked(createGlossaryAnchor); const mockRollbackGlossaryAnchor = vi.mocked(rollbackGlossaryAnchor); const mockFetchSettingsView = vi.mocked(fetchSettingsView); const mockFetchSupportedProviders = vi.mocked(fetchSupportedProviders); +const mockFetchRagTaskConfigs = vi.mocked(fetchRagTaskConfigs); +const mockPreviewRagProviderModels = vi.mocked(previewRagProviderModels); +const mockUpsertRagTaskConfig = vi.mocked(upsertRagTaskConfig); +const mockCheckRagTaskConfigHealth = vi.mocked(checkRagTaskConfigHealth); const mockFetchBackendHealthSnapshot = vi.mocked(fetchBackendHealthSnapshot); const mockFetchRagQualityReport = vi.mocked(fetchRagQualityReport); const mockFetchRagReplayCompleteness = vi.mocked(fetchRagReplayCompleteness); @@ -103,6 +119,63 @@ function createSettingsView(role: "admin" | "user"): LlmSettingsView { }; } +function createRagTaskSettingsView(role: "admin" | "user"): RagTaskSettingsView { + return { + actor: { + id: role === "admin" ? "frontend-admin" : "frontend-user", + role + }, + items: [ + { + id: "rag-embedding", + taskType: "embedding", + provider: "openai", + model: "text-embedding-3-small", + baseUrl: "https://api.openai.com/v1", + enabled: true, + hasApiKey: true, + apiKeyMasked: "sk-e***1234", + dimensions: 1536, + vectorVersion: "v1", + timeoutMs: 30000, + note: null, + healthStatus: "unknown", + lastCheckedAt: null, + lastHealthLatencyMs: null, + lastHealthMessage: null, + lastError: null, + configSource: "settings", + configSourceNote: null, + createdAt: "2026-04-16T00:00:00.000Z", + updatedAt: "2026-04-16T00:00:00.000Z" + }, + { + id: "rag-rerank", + taskType: "rerank", + provider: "openai", + model: "gpt-4.1-mini", + baseUrl: "https://api.openai.com/v1", + enabled: true, + hasApiKey: true, + apiKeyMasked: "sk-r***1234", + dimensions: null, + vectorVersion: null, + timeoutMs: 5000, + note: null, + healthStatus: "unknown", + lastCheckedAt: null, + lastHealthLatencyMs: null, + lastHealthMessage: null, + lastError: null, + configSource: "settings", + configSourceNote: null, + createdAt: "2026-04-16T00:00:00.000Z", + updatedAt: "2026-04-16T00:00:00.000Z" + } + ] + }; +} + function createHealthSnapshot(withFoundation = true) { return { status: "ok", @@ -209,6 +282,24 @@ describe("SettingsPage governance visibility", () => { vi.stubGlobal("fetch", fetchMock); window.history.replaceState({}, "", "/settings"); mockFetchSupportedProviders.mockResolvedValue([]); + mockFetchRagTaskConfigs.mockResolvedValue(createRagTaskSettingsView("admin")); + mockPreviewRagProviderModels.mockResolvedValue({ + provider: "openai", + supportsModelListing: true, + recommendedModel: "text-embedding-3-small", + models: [] + }); + mockUpsertRagTaskConfig.mockResolvedValue(createRagTaskSettingsView("admin").items[0]!); + mockCheckRagTaskConfigHealth.mockResolvedValue({ + taskType: "embedding", + status: "healthy", + reasonCode: "ok", + message: "ok", + checkedAt: "2026-04-16T00:00:00.000Z", + latencyMs: 1, + configSource: "settings", + checkedAgainst: "persisted" + }); mockFetchBackendHealthSnapshot.mockResolvedValue(createHealthSnapshot()); mockFetchRagQualityReport.mockResolvedValue(createQualityReport()); mockFetchRagReplayCompleteness.mockResolvedValue({ diff --git a/apps/frontend/tests/unit/settings-page-rag-config.spec.tsx b/apps/frontend/tests/unit/settings-page-rag-config.spec.tsx new file mode 100644 index 0000000..be5d37c --- /dev/null +++ b/apps/frontend/tests/unit/settings-page-rag-config.spec.tsx @@ -0,0 +1,415 @@ +import { render, screen } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { beforeEach, describe, expect, it, vi } from "vitest"; +import type { LlmSettingsView, RagTaskSettingsView } from "@text2sql/shared-types"; +import SettingsPage from "@/app/settings/page"; +import { listGlossaryAnchors, listWorkspaces } from "@/lib/admin-api-client"; +import { + batchSetModelsEnabled, + checkProviderHealth, + checkRagTaskConfigHealth, + createProviderConfig, + deleteProviderConfig, + fetchBackendHealthSnapshot, + fetchModelStatuses, + previewRagProviderModels, + fetchRagQualityReport, + fetchRagReplayCompleteness, + fetchRagTaskConfigs, + fetchSettingsView, + fetchSupportedProviders, + setModelEnabled, + submitRagMemoryFeedback, + syncProviderModels, + upsertRagTaskConfig +} from "@/lib/settings-api-client"; + +vi.mock("@/components/settings/model-catalog-table", () => ({ + ModelCatalogTable: () =>
model-catalog-table
+})); + +vi.mock("@/components/settings/provider-config-sheet", () => ({ + ProviderConfigSheet: () =>
provider-config-sheet
+})); + +vi.mock("@/components/settings/users-management-panel", () => ({ + UsersManagementPanel: () =>
users-management-panel
+})); + +vi.mock("@/components/settings/workspace-management-panel", () => ({ + WorkspaceManagementPanel: () =>
workspace-management-panel
+})); + +vi.mock("@/lib/admin-api-client", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + listWorkspaces: vi.fn(), + listGlossaryAnchors: vi.fn() + }; +}); + +vi.mock("@/lib/settings-api-client", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + fetchSettingsView: vi.fn(), + fetchSupportedProviders: vi.fn(), + fetchRagTaskConfigs: vi.fn(), + previewRagProviderModels: vi.fn(), + upsertRagTaskConfig: vi.fn(), + checkRagTaskConfigHealth: vi.fn(), + fetchBackendHealthSnapshot: vi.fn(), + fetchRagQualityReport: vi.fn(), + fetchRagReplayCompleteness: vi.fn(), + submitRagMemoryFeedback: vi.fn(), + fetchModelStatuses: vi.fn(), + syncProviderModels: vi.fn(), + checkProviderHealth: vi.fn(), + deleteProviderConfig: vi.fn(), + setModelEnabled: vi.fn(), + batchSetModelsEnabled: vi.fn(), + createProviderConfig: vi.fn() + }; +}); + +const mockFetchSettingsView = vi.mocked(fetchSettingsView); +const mockFetchSupportedProviders = vi.mocked(fetchSupportedProviders); +const mockFetchRagTaskConfigs = vi.mocked(fetchRagTaskConfigs); +const mockPreviewRagProviderModels = vi.mocked(previewRagProviderModels); +const mockUpsertRagTaskConfig = vi.mocked(upsertRagTaskConfig); +const mockCheckRagTaskConfigHealth = vi.mocked(checkRagTaskConfigHealth); +const mockFetchBackendHealthSnapshot = vi.mocked(fetchBackendHealthSnapshot); +const mockFetchRagQualityReport = vi.mocked(fetchRagQualityReport); +const mockFetchRagReplayCompleteness = vi.mocked(fetchRagReplayCompleteness); +const mockSubmitRagMemoryFeedback = vi.mocked(submitRagMemoryFeedback); +const mockFetchModelStatuses = vi.mocked(fetchModelStatuses); +const mockSyncProviderModels = vi.mocked(syncProviderModels); +const mockCheckProviderHealth = vi.mocked(checkProviderHealth); +const mockDeleteProviderConfig = vi.mocked(deleteProviderConfig); +const mockSetModelEnabled = vi.mocked(setModelEnabled); +const mockBatchSetModelsEnabled = vi.mocked(batchSetModelsEnabled); +const mockCreateProviderConfig = vi.mocked(createProviderConfig); +const mockListWorkspaces = vi.mocked(listWorkspaces); +const mockListGlossaryAnchors = vi.mocked(listGlossaryAnchors); + +function createSettingsView(role: "admin" | "user"): LlmSettingsView { + return { + actor: { + id: role === "admin" ? "frontend-admin" : "frontend-user", + role + }, + providers: [], + models: [] + }; +} + +function createRagTaskView(role: "admin" | "user"): RagTaskSettingsView { + return { + actor: { + id: role === "admin" ? "frontend-admin" : "frontend-user", + role + }, + items: [ + { + id: "rag-embedding", + taskType: "embedding", + provider: "openai", + model: "text-embedding-3-small", + baseUrl: "https://api.openai.com/v1", + enabled: true, + hasApiKey: true, + apiKeyMasked: "sk-e***1234", + dimensions: 1536, + vectorVersion: "v1", + timeoutMs: 30000, + note: null, + healthStatus: "unknown", + lastCheckedAt: null, + lastHealthLatencyMs: null, + lastHealthMessage: null, + lastError: null, + configSource: "settings", + configSourceNote: null, + createdAt: "2026-04-16T00:00:00.000Z", + updatedAt: "2026-04-16T00:00:00.000Z" + }, + { + id: "rag-rerank", + taskType: "rerank", + provider: "openai", + model: "gpt-4.1-mini", + baseUrl: "https://api.openai.com/v1", + enabled: true, + hasApiKey: true, + apiKeyMasked: "sk-r***1234", + dimensions: null, + vectorVersion: null, + timeoutMs: 5000, + note: null, + healthStatus: "unknown", + lastCheckedAt: null, + lastHealthLatencyMs: null, + lastHealthMessage: null, + lastError: null, + configSource: "settings", + configSourceNote: null, + createdAt: "2026-04-16T00:00:00.000Z", + updatedAt: "2026-04-16T00:00:00.000Z" + } + ] + }; +} + +describe("SettingsPage rag config tab", () => { + beforeEach(() => { + vi.clearAllMocks(); + mockFetchSupportedProviders.mockResolvedValue([]); + mockFetchRagTaskConfigs.mockResolvedValue(createRagTaskView("admin")); + mockPreviewRagProviderModels.mockResolvedValue({ + provider: "volcengine", + supportsModelListing: true, + recommendedModel: "doubao-embedding-text-240715", + models: [ + { + model: "doubao-embedding-text-240715", + displayName: "doubao-embedding-text-240715" + }, + { + model: "doubao-embedding-large", + displayName: "doubao-embedding-large" + } + ] + }); + mockUpsertRagTaskConfig.mockResolvedValue(createRagTaskView("admin").items[0]!); + mockCheckRagTaskConfigHealth.mockResolvedValue({ + taskType: "embedding", + status: "healthy", + reasonCode: "ok", + message: "ok", + checkedAt: "2026-04-16T00:00:00.000Z", + latencyMs: 1, + configSource: "settings", + checkedAgainst: "draft" + }); + mockFetchBackendHealthSnapshot.mockResolvedValue({ + status: "ok", + dependencies: { + ragIngestionMetrics: { + foundation: { + activeIndexSummary: { + total: 1, + items: [ + { + datasourceId: "ds-1", + indexVersionId: "idx-v1", + sourceVersion: + "semantic-assets-aaa:openai:text-embedding-3-small:v1:settings:schema", + activatedAt: "2026-04-16T00:00:00.000Z" + } + ] + } + } + } + } + }); + mockFetchRagQualityReport.mockResolvedValue({ + thresholds: { + recallAt20Min: 0.7, + mrrAt10Min: 0.6, + retrievalRerankP95MsMax: 500, + degradeRateMax: 0.3, + minSamples: 10 + }, + sampleSize: 0, + sampleReady: false, + gatePass: false, + reasons: [], + generatedAt: "2026-04-16T00:00:00.000Z" + }); + mockFetchRagReplayCompleteness.mockResolvedValue({ + runId: "none", + requiredStages: [], + observedStages: [], + missingStages: [], + completeness: 1, + ready: true + }); + mockSubmitRagMemoryFeedback.mockResolvedValue({ + runId: "none", + candidateId: "none", + beforeStatus: "candidate", + afterStatus: "verified", + applied: true, + updatedAt: "2026-04-16T00:00:00.000Z" + }); + mockFetchModelStatuses.mockResolvedValue([]); + mockSyncProviderModels.mockResolvedValue({ + provider: { + id: "provider-1", + provider: "openai", + displayName: "OpenAI", + baseUrl: null, + enabled: true, + hasApiKey: true, + apiKeyMasked: null, + lastSyncAt: null, + lastSyncStatus: "healthy", + lastSyncError: null, + modelCount: 0, + createdAt: "2026-04-16T00:00:00.000Z", + updatedAt: "2026-04-16T00:00:00.000Z" + }, + syncedModels: [] + }); + mockCheckProviderHealth.mockResolvedValue({ + provider: { + id: "provider-1", + provider: "openai", + displayName: "OpenAI", + baseUrl: null, + enabled: true, + hasApiKey: true, + apiKeyMasked: null, + lastSyncAt: null, + lastSyncStatus: "healthy", + lastSyncError: null, + modelCount: 0, + createdAt: "2026-04-16T00:00:00.000Z", + updatedAt: "2026-04-16T00:00:00.000Z" + }, + status: "healthy", + message: "ok", + checkedAt: "2026-04-16T00:00:00.000Z", + latencyMs: 1 + }); + mockDeleteProviderConfig.mockResolvedValue({ + deleted: true, + providerConfigId: "provider-1" + }); + mockSetModelEnabled.mockResolvedValue({ + id: "model-1", + providerConfigId: "provider-1", + provider: "openai", + model: "gpt-5.4", + displayName: "GPT-5.4", + capabilities: [], + contextWindow: null, + enabled: true, + healthStatus: "healthy", + lastHealthCheckAt: null, + lastSyncedAt: null, + metadata: {}, + createdAt: "2026-04-16T00:00:00.000Z", + updatedAt: "2026-04-16T00:00:00.000Z" + }); + mockBatchSetModelsEnabled.mockResolvedValue({ updated: 0 }); + mockCreateProviderConfig.mockResolvedValue({ + id: "provider-1", + provider: "openai", + displayName: "OpenAI", + baseUrl: null, + enabled: true, + hasApiKey: true, + apiKeyMasked: null, + lastSyncAt: null, + lastSyncStatus: "healthy", + lastSyncError: null, + modelCount: 0, + createdAt: "2026-04-16T00:00:00.000Z", + updatedAt: "2026-04-16T00:00:00.000Z" + }); + mockListWorkspaces.mockResolvedValue({ + items: [], + total: 0, + page: 1, + pageSize: 200 + }); + mockListGlossaryAnchors.mockResolvedValue({ + items: [], + total: 0, + page: 1, + pageSize: 50 + }); + }); + + it("shows rag config tab and panels for admin", async () => { + const user = userEvent.setup(); + mockFetchSettingsView.mockResolvedValue(createSettingsView("admin")); + render(); + + await screen.findByText("用户列表"); + await user.click(screen.getByRole("tab", { name: "RAG 配置" })); + + expect(await screen.findByText("Embedding Provider")).toBeInTheDocument(); + expect(screen.getByText("Rerank Provider")).toBeInTheDocument(); + expect(screen.getByText("当前检索索引画像")).toBeInTheDocument(); + expect(screen.getAllByRole("button", { name: "编辑当前草稿" }).length).toBeGreaterThan(0); + }); + + it("shows readonly rag config state for user", async () => { + const user = userEvent.setup(); + mockFetchSettingsView.mockResolvedValue(createSettingsView("user")); + mockFetchRagTaskConfigs.mockResolvedValue(createRagTaskView("user")); + render(); + + await screen.findByText("LLM 模型"); + await user.click(screen.getByRole("tab", { name: "RAG 配置" })); + + expect(await screen.findByText("Embedding Provider")).toBeInTheDocument(); + expect(screen.getAllByText("当前账号只读，可查看配置摘要。").length).toBeGreaterThan(0); + expect(screen.queryByRole("button", { name: "保存并生效" })).not.toBeInTheDocument(); + }); + + it("passes current draft payload when checking embedding health", async () => { + const user = userEvent.setup(); + mockFetchSettingsView.mockResolvedValue(createSettingsView("admin")); + render(); + + await screen.findByText("用户列表"); + await user.click(screen.getByRole("tab", { name: "RAG 配置" })); + + await user.click(screen.getByLabelText("embedding-preset-volcengine")); + + const modelInput = await screen.findByLabelText("embedding-model"); + const apiKeyInput = screen.getByLabelText("embedding-api-key"); + + await user.clear(modelInput); + await user.type(modelInput, "doubao-embedding-large"); + await user.type(apiKeyInput, "sk-draft-embedding"); + await user.click(screen.getByRole("button", { name: "检测草稿（不保存）" })); + + expect(mockCheckRagTaskConfigHealth).toHaveBeenCalledWith( + "embedding", + expect.objectContaining({ + draft: expect.objectContaining({ + provider: "volcengine", + model: "doubao-embedding-large", + baseUrl: "https://ark.cn-beijing.volces.com/api/v3", + apiKey: "sk-draft-embedding" + }) + }) + ); + }); + + it("fetches official models after api key entry and applies the selected option", async () => { + const user = userEvent.setup(); + mockFetchSettingsView.mockResolvedValue(createSettingsView("admin")); + render(); + + await screen.findByText("用户列表"); + await user.click(screen.getByRole("tab", { name: "RAG 配置" })); + await user.click(screen.getByLabelText("embedding-preset-volcengine")); + + await user.type(screen.getByLabelText("embedding-api-key"), "sk-preview-embedding"); + await user.click(screen.getByRole("button", { name: "获取模型" })); + + expect(mockPreviewRagProviderModels).toHaveBeenCalledWith("embedding", { + provider: "volcengine", + baseUrl: "https://ark.cn-beijing.volces.com/api/v3", + apiKey: "sk-preview-embedding" + }); + + expect(await screen.findByText("从官网返回的模型中选择")).toBeInTheDocument(); + }); +}); diff --git a/docs/standards/llm-stream-tool-migration-spec.md b/docs/standards/llm-stream-tool-migration-spec.md index ba3347d..097f7b3 100644 --- a/docs/standards/llm-stream-tool-migration-spec.md +++ b/docs/standards/llm-stream-tool-migration-spec.md @@ -5,6 +5,8 @@ - Backend LLM gateway migrates to Vercel AI SDK core (`ai` + `@ai-sdk/openai-compatible`). - Chat primary request path supports SSE streaming endpoint. - Tool Calling baseline is enabled with allowlisted server-side tools. +- Text2SQL v2 active runtime seam 固定为 `Text2SQLWorkflowRunner -> RunV2LangGraphStage -> Text2SqlV2LangGraphRunnerService`，并落位于 `conversation/application/workflow` 与 `conversation/runtime/{stages,langgraph,evaluation}` 分层目录；`RunV2StateMachineStage` 仅保留兼容壳角色。 +- Text2SQL v2 Phase A 运行时收口必须满足 `delegation=0`：LangGraph 主链节点不得委托 `Text2SqlV2RunnerService` / `runLegacyRuntime`。 - 开发联调入口拓扑统一为 `http://localhost:3000`（Nginx）；`/` 转前端内部 `3001`，`/api/*` 转后端内部 `3002`。 - 上述入口拓扑调整不改变 `/api/v1/*` 路由合同、SSE 事件字段或 Tool Calling 语义。 @@ -36,7 +38,10 @@ - `run.delivery.evidence.promptTemplate?`：与 trace 同源的模板证据镜像（用于前端回放展示） - `run.delivery.evidence.modelingRevision?`：与 `run.trace.modelingRevision?` 同源镜像字段，语义必须一致 - `run.delivery.evidence.effectiveContextSummary?` / `run.delivery.evidence.conflictHint?`：trace 同语义镜像字段 - - backward compatibility：历史 run 缺失 `run.trace.modelingRevision?` 或 `run.delivery.evidence.modelingRevision?` 时，读取端必须按“字段可选”处理，不得因缺字段导致反序列化或回放失败 + - Full Mermaid strict-completion（2026-04-27）语义：metadata 仅走 `retrieve -> assemble-context -> semantic-plan -> answer`（no-SQL）；correction 重试必须输出结构化 `correctionGrounding` + - Runtime intelligence（2026-04-28）语义：`run.trace.v2` 是 `runtimePlan`、`artifactRefs`、`smartDefaults` 的 canonical owner；`run.delivery.evidence.v2` 只做同语义投影；`artifactRefs` 必须由 producer-backed category policy 生成，覆盖 `context_snippets` / `schema_supplement` / `prompt_input` / `provider_output_summary` / `validation_diagnostics` / `correction_grounding` / `execution_preview` + - `run.delivery.evidence.v2` 在 strict-completion 与 runtime-intelligence 场景应包含 `contextPackSummary`、`metadataAnswer`、`correctionGrounding`、`runtimePlan`、`artifactRefs`、`smartDefaults`，并与 `run.trace.v2` 保持语义一致 + - hard-cut read-model：run read/save-view/replay 必须命中显式 v2 marker（`run.trace.v2.version === "v2"`、`run.trace.v2.stageOrder.length > 0`、`run.trace.v2.stages.length > 0`）；命中授权但不支持历史 shape 时返回 `410 LEGACY_RUN_UNSUPPORTED` - `agent: { provider, model, hasSql, hasToolCalls, hasError }` ### Stream Contract (`/messages/stream`) @@ -59,7 +64,8 @@ - `at` - `data` - `data` is always a structured object, not raw string. -- `finish` 事件中的 `data.delivery.evidence.promptTemplate?`、`modelingRevision?`、`effectiveContextSummary?`、`conflictHint?` 必须与同步接口字段语义一致（允许兼容旧 run 字段缺失）。 +- `finish` 事件中的 `data.delivery.evidence.promptTemplate?`、`modelingRevision?`、`effectiveContextSummary?`、`conflictHint?` 必须与同步接口字段语义一致（不再要求历史 snake_case / alias hydration）。 +- strict-completion/runtime-intelligence 场景下，`finish` 事件中的 `data.delivery.evidence.v2` 也必须保持 `contextPackSummary`、`metadataAnswer`、`correctionGrounding`、`runtimePlan`、`artifactRefs`、`smartDefaults` 与 `run.trace.v2` 的同语义镜像；`state` 事件只能暴露 runtime plan 的安全摘要，不得暴露 raw graph state/checkpoint。Full Mermaid stages 必须在 stream `state` 中产生安全的 `running` 与 terminal lifecycle（completed/skipped/failed/clarification）摘要。 ## Tool Calling Baseline @@ -94,9 +100,19 @@ - 同步/流式的错误分类在相同故障输入下保持一致。 - Compare stream endpoint success rate against legacy endpoint baseline. - Verify trace persistence includes tool events when tools are called. -- Verify `GET /api/v1/runs/:runId` 对历史 run（无模板字段）与新 run（含模板字段）都可稳定返回，且不会破坏反序列化。 -- Verify `GET /api/v1/runs/:runId` 对历史 run（无 `modelingRevision` 字段）与新 run（含 `run.trace.modelingRevision` + `run.delivery.evidence.modelingRevision`）均可稳定返回，且前端回放不因缺字段降级失败。 +- Verify `GET /api/v1/runs/:runId`、`POST /api/v1/runs/:runId/save-as-view` 与 replay 读路径只接受显式 v2 read-model；历史 shape 返回 `410 LEGACY_RUN_UNSUPPORTED`，错误详情包含迁移 runbook hint。 - Verify modeling parity shadow gate report includes: - `modelingWorkspace.metrics.deployBlockRate / rollbackRate / schemaBacklogAvg` - `modelingWorkspace.signalCoverage.*`（样本信号覆盖率） - `rollout.recommendedStage` 与 `rollout.rollbackSuggested` +- Text2SQL v2 closeout must also collect focused coverage evidence after a Jest coverage run: + - `pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate` + - strict release mode: `pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate:strict` + - the report must include scoped line/branch coverage, critical file thresholds, A-M flow-node blockers, eval fixture behavior-test traceability, and `delegationZero` static-scan结果。 + - Full Mermaid strict-completion 场景下，报告还必须包含 `strictCompletionRows`（metadata grounding / correction grounding / context-pack parity）并参与 gate 判定。 + - Runtime intelligence 场景下，报告还必须包含 `runtimeCoverageRows`（runtime plan / artifact refs / Smart Defaults）、`runtimeArtifactProducerRows`（七类 artifact producer coverage）、`streamLifecycleRows`（全 stage running/terminal lifecycle coverage）与 eval fixture families（plain-general-no-sql / runtime-plan-consistency / artifact-ref-compaction / smart-defaults-evidence / large-context-compaction / validation-diagnostics / correction-grounding / execution-preview / all-stage-stream-lifecycle）。 +- 叙事边界：`007 closeout` 表示 LangGraph topology + `delegation=0` 收口完成；`008 strict-completion` 在此基础上要求 metadata grounding / correction grounding / context-pack parity；`009 runtime-intelligence` 额外要求 runtime plan / artifact refs / Smart Defaults 的可观测与可门禁。 +- Text2SQL v2 closeout rollout must use `collect:text2sql-v2-eval-gate` as the aggregated report entry: + - `pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate` + - strict release mode: `pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate:strict` + - output must include `closeoutGates.evalMetrics/evalTraceability/characterization/noLegacyCompat/focusedCoverage` and final `rollout.recommendedStage/rollbackSuggested/reasons`. diff --git a/graphify-out/GRAPH_REPORT.md b/graphify-out/GRAPH_REPORT.md index c6a58d5..435f43e 100644 --- a/graphify-out/GRAPH_REPORT.md +++ b/graphify-out/GRAPH_REPORT.md @@ -1,12 +1,12 @@ -# Graph Report - /Users/lienli/Documents/GitHub/text2sql (2026-04-26) +# Graph Report - /Users/lienli/Documents/GitHub/text2sql (2026-04-29) ## Corpus Check -- 697 files · ~1,066,672 words +- 781 files · ~2,266,621 words - Verdict: corpus is large enough that graph structure adds value. ## Summary -- 3640 nodes · 7065 edges · 490 communities detected -- Extraction: 79% EXTRACTED · 21% INFERRED · 0% AMBIGUOUS · INFERRED: 1513 edges (avg confidence: 0.8) +- 4314 nodes · 8504 edges · 538 communities detected +- Extraction: 79% EXTRACTED · 21% INFERRED · 0% AMBIGUOUS · INFERRED: 1809 edges (avg confidence: 0.8) - Token cost: 0 input · 0 output ## Community Hubs (Navigation) @@ -500,18 +500,66 @@ - [[_COMMUNITY_Community 487|Community 487]] - [[_COMMUNITY_Community 488|Community 488]] - [[_COMMUNITY_Community 489|Community 489]] +- [[_COMMUNITY_Community 490|Community 490]] +- [[_COMMUNITY_Community 491|Community 491]] +- [[_COMMUNITY_Community 492|Community 492]] +- [[_COMMUNITY_Community 493|Community 493]] +- [[_COMMUNITY_Community 494|Community 494]] +- [[_COMMUNITY_Community 495|Community 495]] +- [[_COMMUNITY_Community 496|Community 496]] +- [[_COMMUNITY_Community 497|Community 497]] +- [[_COMMUNITY_Community 498|Community 498]] +- [[_COMMUNITY_Community 499|Community 499]] +- [[_COMMUNITY_Community 500|Community 500]] +- [[_COMMUNITY_Community 501|Community 501]] +- [[_COMMUNITY_Community 502|Community 502]] +- [[_COMMUNITY_Community 503|Community 503]] +- [[_COMMUNITY_Community 504|Community 504]] +- [[_COMMUNITY_Community 505|Community 505]] +- [[_COMMUNITY_Community 506|Community 506]] +- [[_COMMUNITY_Community 507|Community 507]] +- [[_COMMUNITY_Community 508|Community 508]] +- [[_COMMUNITY_Community 509|Community 509]] +- [[_COMMUNITY_Community 510|Community 510]] +- [[_COMMUNITY_Community 511|Community 511]] +- [[_COMMUNITY_Community 512|Community 512]] +- [[_COMMUNITY_Community 513|Community 513]] +- [[_COMMUNITY_Community 514|Community 514]] +- [[_COMMUNITY_Community 515|Community 515]] +- [[_COMMUNITY_Community 516|Community 516]] +- [[_COMMUNITY_Community 517|Community 517]] +- [[_COMMUNITY_Community 518|Community 518]] +- [[_COMMUNITY_Community 519|Community 519]] +- [[_COMMUNITY_Community 520|Community 520]] +- [[_COMMUNITY_Community 521|Community 521]] +- [[_COMMUNITY_Community 522|Community 522]] +- [[_COMMUNITY_Community 523|Community 523]] +- [[_COMMUNITY_Community 524|Community 524]] +- [[_COMMUNITY_Community 525|Community 525]] +- [[_COMMUNITY_Community 526|Community 526]] +- [[_COMMUNITY_Community 527|Community 527]] +- [[_COMMUNITY_Community 528|Community 528]] +- [[_COMMUNITY_Community 529|Community 529]] +- [[_COMMUNITY_Community 530|Community 530]] +- [[_COMMUNITY_Community 531|Community 531]] +- [[_COMMUNITY_Community 532|Community 532]] +- [[_COMMUNITY_Community 533|Community 533]] +- [[_COMMUNITY_Community 534|Community 534]] +- [[_COMMUNITY_Community 535|Community 535]] +- [[_COMMUNITY_Community 536|Community 536]] +- [[_COMMUNITY_Community 537|Community 537]] ## God Nodes (most connected - your core abstractions) -1. `ok()` - 86 edges +1. `ok()` - 90 edges 2. `WorkspaceModelingService` - 79 edges -3. `RagRetrievalService` - 69 edges -4. `GlossaryService` - 59 edges -5. `isRecord()` - 55 edges -6. `toAdminApiError()` - 51 edges -7. `DatasourceService` - 45 edges -8. `WorkspaceDatasourcePolicyRepository` - 45 edges -9. `AppConfigService` - 44 edges -10. `ChatRepository` - 43 edges +3. `RagRetrievalService` - 78 edges +4. `DeliveryContractMapper` - 61 edges +5. `AppConfigService` - 59 edges +6. `GlossaryService` - 59 edges +7. `isRecord()` - 55 edges +8. `Text2SqlV2ArtifactBuilder` - 53 edges +9. `toAdminApiError()` - 51 edges +10. `DatasourceService` - 45 edges ## Surprising Connections (you probably didn't know these) - `loadPreviewForDetails()` --calls--> `getWorkspaceModelingPreview()` [INFERRED] @@ -529,335 +577,335 @@ ### Community 0 - "Community 0" Cohesion: 0.02 -Nodes (38): extractLatestUserText(), mapToThreadMessages(), ChartBiGroundingGuard, ChartBiResultProfiler, buildContextEnvelopeFromDraft(), parseEntityMappings(), splitByDelimiters(), trimOrUndefined() (+30 more) +Nodes (41): extractLatestUserText(), mapToThreadMessages(), ChartBiGroundingGuard, ChartBiResultProfiler, buildContextEnvelopeFromDraft(), parseEntityMappings(), splitByDelimiters(), trimOrUndefined() (+33 more) ### Community 1 - "Community 1" Cohesion: 0.02 -Nodes (17): ChatController, ensureRunLoaded(), ChatPolicyGuardService, ChatRepository, ChatRunPersistenceService, ChatService, DatasourceAccessPolicyService, EvalService (+9 more) +Nodes (19): ChatController, ChatPolicyGuardService, ChatRepository, ChatRunPersistenceService, ChatService, DatasourceAccessPolicyService, EnrichDeliveryStage, EvalService (+11 more) ### Community 2 - "Community 2" -Cohesion: 0.02 -Nodes (39): AppConfigService, DatasourceRegistryService, countTracedRuns(), main(), parseArgs(), computeLangsmithCoverage(), bootstrap(), buildGraph() (+31 more) +Cohesion: 0.03 +Nodes (145): addWorkspaceDatasourceBindings(), addWorkspaceMembers(), AdminApiError, commitModelingSetup(), composeApiUrl(), createGlossaryAnchor(), createGlossaryTerm(), createPromptTemplate() (+137 more) ### Community 3 - "Community 3" -Cohesion: 0.03 -Nodes (13): ok(), ChartBiValidator, DatasourceController, DatasourceWorkflowService, EvalController, GlossaryController, MemoryController, SettingsController (+5 more) +Cohesion: 0.02 +Nodes (22): BuildRagIndexJob, asActor(), asActor(), LlmConfigRepository, toModelHealthStatus(), toProviderCode(), toProviderSyncStatus(), createRunId() (+14 more) ### Community 4 - "Community 4" -Cohesion: 0.05 -Nodes (105): addWorkspaceDatasourceBindings(), addWorkspaceMembers(), AdminApiError, commitModelingSetup(), composeApiUrl(), createGlossaryAnchor(), createGlossaryTerm(), createPromptTemplate() (+97 more) +Cohesion: 0.02 +Nodes (35): AppConfigService, DatasourceRegistryService, countTracedRuns(), main(), parseArgs(), computeLangsmithCoverage(), bootstrap(), buildGraph() (+27 more) ### Community 5 - "Community 5" -Cohesion: 0.04 -Nodes (8): BuildRagIndexJob, asActor(), asActor(), GlossaryService, RagIndexBuilderService, RagIndexRepository, withActor(), asAdmin() +Cohesion: 0.03 +Nodes (14): ok(), ChartBiValidator, DatasourceController, EvalController, GlossaryController, MemoryController, SettingsController, UserController (+6 more) ### Community 6 - "Community 6" -Cohesion: 0.03 -Nodes (10): DataBootstrapService, PlatformDataBootstrapModule, FakePgClient, DatasourceRepository, DatasourceService, MysqlExecutorService, PostgresExecutorService, RelationshipDryRunService (+2 more) +Cohesion: 0.04 +Nodes (9): ModelingSchemaChangeRepository, toScopeKey(), SaveViewFromRunUsecase, normalizeName(), SchemaChangeDetectorService, normalizeName(), WorkspaceModelingSchemaChangeDetectorService, normalizeTableName() (+1 more) ### Community 7 - "Community 7" -Cohesion: 0.04 -Nodes (9): LlmConfigRepository, toModelHealthStatus(), toProviderCode(), toProviderSyncStatus(), ModelRerankerAdapter, PromptTemplateService, ProviderCatalogService, ProviderRouterService (+1 more) +Cohesion: 0.03 +Nodes (10): DataBootstrapService, PlatformDataBootstrapModule, FakePgClient, DatasourceRepository, DatasourceService, DatasourceWorkflowService, MysqlExecutorService, PostgresExecutorService (+2 more) ### Community 8 - "Community 8" -Cohesion: 0.04 -Nodes (58): BuildSemanticQueryNode, ChartBiSpecCompiler, buildConversationKnowledgeAllowlistSet(), collectFiles(), compactLine(), createLineStarts(), extractImportReferences(), findRepoRoot() (+50 more) +Cohesion: 0.03 +Nodes (74): BuildSemanticQueryNode, buildConversationKnowledgeAllowlistSet(), collectFiles(), compactLine(), createLineStarts(), extractImportReferences(), findRepoRoot(), indexToLineColumn() (+66 more) ### Community 9 - "Community 9" -Cohesion: 0.04 -Nodes (64): handleKeyDown(), isRecord(), nextFieldId(), normalizeFunctionGroupHints(), resolveCalculatedFieldSaveError(), save(), toForm(), upsertField() (+56 more) +Cohesion: 0.03 +Nodes (22): BuildPhysicalPlanNode, ChartBiIntentParser, parseSseEvents(), parseSseEvents(), FileDatasourceExecutorService, GateMetricsService, parsePayload(), PlannerCacheService (+14 more) ### Community 10 - "Community 10" -Cohesion: 0.06 -Nodes (8): AuditLogRepository, asNonEmptyString(), toBindingKey(), toRuleKey(), toTablePermissionKey(), toTablePermissionSetKey(), WorkspaceDatasourcePolicyRepository, WorkspaceDatasourceService +Cohesion: 0.04 +Nodes (9): shouldRetryCorrection(), AnswerNode, CorrectSqlNode, FormatAnswerNode, SavedPriorSqlService, SemanticAssetReindexService, SqlCorrectionService, Text2SQLWorkflowRunner (+1 more) ### Community 11 - "Community 11" Cohesion: 0.04 -Nodes (17): BuildPhysicalPlanNode, ChartBiIntentParser, parseSseEvents(), parseSseEvents(), GateMetricsService, parsePayload(), PlannerCacheService, RagAuditReplayService (+9 more) +Nodes (15): EmbeddingRouterService, GeminiAdapter, resolveGeminiUrl(), isTimeoutAbortError(), LlmGatewayService, toErrorMessage(), LlmModelFactory, resolveProviderBaseUrl() (+7 more) ### Community 12 - "Community 12" -Cohesion: 0.06 -Nodes (7): LaneTimeoutError, RagRetrievalService, appendUnique(), fuseWithRrf(), laneOrder(), normalizeRankConstant(), stableSortLaneHits() +Cohesion: 0.04 +Nodes (64): handleKeyDown(), isRecord(), nextFieldId(), normalizeFunctionGroupHints(), resolveCalculatedFieldSaveError(), save(), toForm(), upsertField() (+56 more) ### Community 13 - "Community 13" -Cohesion: 0.06 -Nodes (60): createIdempotencyKey(), resolveDatasourceWorkflowApiError(), applySessionView(), dedupeSessions(), extractErrorCode(), init(), loadMessages(), mergeSessionMessages() (+52 more) +Cohesion: 0.05 +Nodes (5): GenerateSqlNode, RagCacheKeyFactory, SqlGenerationService, SqlOutputExtractor, SqlPromptBuilder ### Community 14 - "Community 14" -Cohesion: 0.05 -Nodes (8): GraphAccelerationCircuitBreaker, GraphService, QueryExecutorRouterService, RelationshipPublishGateFacade, RowFilterRewriteService, SafetyCheckNode, SqlSafetyGuard, SqlTableAccessGuardService +Cohesion: 0.06 +Nodes (7): LaneTimeoutError, RagRetrievalService, appendUnique(), fuseWithRrf(), laneOrder(), normalizeRankConstant(), stableSortLaneHits() ### Community 15 - "Community 15" Cohesion: 0.05 -Nodes (4): MemoryPromotionPolicy, MemoryPromotionService, RagReplayRepository, RagRerankService +Nodes (5): ModelRerankerAdapter, ProviderRouterService, RagBudgetPolicy, RagReplayRepository, RagRerankService ### Community 16 - "Community 16" -Cohesion: 0.08 -Nodes (7): normalizeValue(), WorkspaceAdminGuard, toMembershipKey(), toWorkspaceMemberRole(), toWorkspaceStatus(), WorkspaceRepository, WorkspaceService +Cohesion: 0.05 +Nodes (8): GraphAccelerationCircuitBreaker, GraphService, IntakeNode, RelationshipPublishGateFacade, RowFilterRewriteService, SafetyCheckNode, SqlSafetyGuard, SqlTableAccessGuardService ### Community 17 - "Community 17" -Cohesion: 0.07 -Nodes (8): ModelingGraphRepository, toScopeKey(), ModelingGraphValidator, nonEmpty(), WorkspaceModelingDeployService, WorkspaceRelationshipController, normalizeId(), WorkspaceRelationshipService +Cohesion: 0.08 +Nodes (8): setupWorkspaceScopedSession(), asNonEmptyString(), toBindingKey(), toRuleKey(), toTablePermissionKey(), toTablePermissionSetKey(), WorkspaceDatasourcePolicyRepository, WorkspaceDatasourceService ### Community 18 - "Community 18" -Cohesion: 0.05 -Nodes (19): GraphBuilderService, appendPlanningWarnings(), buildExplicitPinningEvidence(), createLangGraphNodeHandlers(), createNodeRuntime(), extractQualifiedColumns(), getCallbacks(), normalizeIdentifier() (+11 more) +Cohesion: 0.06 +Nodes (62): createIdempotencyKey(), resolveDatasourceWorkflowApiError(), applySessionView(), dedupeSessions(), extractErrorCode(), init(), loadMessages(), mergeSessionMessages() (+54 more) ### Community 19 - "Community 19" -Cohesion: 0.06 -Nodes (5): GenerateSqlNode, RagCacheKeyFactory, SqlGenerationService, SqlOutputExtractor, SqlPromptBuilder +Cohesion: 0.07 +Nodes (7): AuditLogRepository, ModelingGraphRepository, toScopeKey(), ModelingGraphValidator, nonEmpty(), normalizeId(), WorkspaceRelationshipService ### Community 20 - "Community 20" Cohesion: 0.08 -Nodes (10): toPlatformUserStatus(), UserRepository, UserService, onConfirmBatchDelete(), onConfirmDeleteOne(), onConfirmResetPassword(), onSubmitEditor(), onToggleStatus() (+2 more) +Nodes (7): normalizeValue(), WorkspaceAdminGuard, toMembershipKey(), toWorkspaceMemberRole(), toWorkspaceStatus(), WorkspaceRepository, WorkspaceService ### Community 21 - "Community 21" -Cohesion: 0.05 -Nodes (6): ChatPostRunHooksService, HealthController, RagIngestionMetricsService, RagQualityController, RagQualityService, SemanticSpineShadowService +Cohesion: 0.08 +Nodes (10): toPlatformUserStatus(), UserRepository, UserService, onConfirmBatchDelete(), onConfirmDeleteOne(), onConfirmResetPassword(), onSubmitEditor(), onToggleStatus() (+2 more) ### Community 22 - "Community 22" Cohesion: 0.06 -Nodes (8): getChunkProfileConfig(), RagChunkingService, sha256(), RagDocumentFactory, sha256(), RagDocumentRepository, SaveViewFromRunUsecase, SavedPriorSqlService +Nodes (7): getChunkProfileConfig(), RagChunkingService, sha256(), RagDocumentFactory, sha256(), RagEventConsumerService, SemanticRegistryService ### Community 23 - "Community 23" -Cohesion: 0.08 -Nodes (7): DeliveryContractMapper, createDeliverySandboxPolicy(), isSandboxFilesystemWriteAllowed(), isSandboxNetworkAllowed(), isSandboxProcessSpawnAllowed(), normalizeString(), SandboxRuntimeService +Cohesion: 0.1 +Nodes (1): GlossaryService ### Community 24 - "Community 24" -Cohesion: 0.08 -Nodes (3): RagBudgetPolicy, RagEventConsumerService, SemanticRegistryService +Cohesion: 0.06 +Nodes (5): HealthController, RagIngestionMetricsService, RagQualityController, RagQualityService, SemanticSpineShadowService ### Community 25 - "Community 25" -Cohesion: 0.09 -Nodes (19): BuildIntentPlanNode, buildRuleReasonCodes(), ClarificationFusionPolicy, mapRuleDecisionToEvidence(), unique(), ClarifyNode, buildDecision(), buildFallbackSlotFillingDecision() (+11 more) +Cohesion: 0.12 +Nodes (1): Text2SqlV2ArtifactBuilder ### Community 26 - "Community 26" -Cohesion: 0.1 -Nodes (40): ApiClientRequestError, composeApiUrl(), createDatasource(), createSession(), DatasourceApiError, deleteSession(), getMessages(), getRun() (+32 more) +Cohesion: 0.06 +Nodes (7): ChartBiSpecCompiler, LangsmithTraceService, createText2SqlV2LangGraph(), Text2SqlV2LangGraphResultMapper, Text2SqlV2LangGraphRunnerService, createText2SqlV2LangGraphInitialState(), mergeRuntimePlanReducer() ### Community 27 - "Community 27" -Cohesion: 0.11 -Nodes (2): ChartBiArtifactService, ChatDeliveryEnrichmentService +Cohesion: 0.08 +Nodes (19): BuildIntentPlanNode, buildRuleReasonCodes(), ClarificationFusionPolicy, mapRuleDecisionToEvidence(), unique(), ClarifyNode, buildDecision(), buildFallbackSlotFillingDecision() (+11 more) ### Community 28 - "Community 28" -Cohesion: 0.09 -Nodes (35): createRunId(), withActor(), formatGovernanceError(), patchModel(), readRunIdFromQuery(), readWorkspaceIdFromQuery(), refreshModels(), resolveWorkspaceId() (+27 more) +Cohesion: 0.08 +Nodes (4): AssembleContextNode, ChartBiArtifactService, ChatDeliveryEnrichmentService, SemanticPlanNode ### Community 29 - "Community 29" -Cohesion: 0.13 -Nodes (1): SemanticSpineRepository +Cohesion: 0.1 +Nodes (40): ApiClientRequestError, composeApiUrl(), createDatasource(), createSession(), DatasourceApiError, deleteSession(), getMessages(), getRun() (+32 more) ### Community 30 - "Community 30" -Cohesion: 0.17 -Nodes (33): appendThinkingStep(), isRecord(), isTerminalStep(), mergeRunThinkingSteps(), mergeThinkingStep(), normalizeArtifact(), normalizeChartArtifact(), normalizeChartMappings() (+25 more) +Cohesion: 0.08 +Nodes (18): resolveText2SqlReasoningStage(), resolveText2SqlTitle(), resolveText2SqlV2StageCatalogEntry(), Text2SqlStreamEventMapper, computeDurationMs(), createNodeUpdate(), createRuntimePlanUpdate(), createStageArtifact() (+10 more) ### Community 31 - "Community 31" -Cohesion: 0.12 -Nodes (22): buildOperationNotice(), closeDialog(), closeDrawer(), createIdempotencyKey(), formatDate(), handleDelete(), handleToggleTerm(), load() (+14 more) +Cohesion: 0.16 +Nodes (35): appendThinkingStep(), ensureRunLoaded(), isRecord(), isTerminalStep(), mergeRunThinkingSteps(), mergeThinkingStep(), normalizeArtifact(), normalizeChartArtifact() (+27 more) ### Community 32 - "Community 32" -Cohesion: 0.12 -Nodes (11): GeminiAdapter, resolveGeminiUrl(), isTimeoutAbortError(), LlmGatewayService, toErrorMessage(), LlmModelFactory, resolveProviderBaseUrl(), checkHealth() (+3 more) +Cohesion: 0.13 +Nodes (1): SemanticSpineRepository ### Community 33 - "Community 33" Cohesion: 0.13 -Nodes (7): formatCell(), normalizeNullableText(), normalizeTableKey(), openEditDialog(), resolveModelRelationships(), resolveRelationshipCounterpartTable(), submitMetadataUpdate() +Nodes (2): QueryExecutorRouterService, SqlValidationService ### Community 34 - "Community 34" -Cohesion: 0.22 -Nodes (2): ClarificationSemanticEvaluatorService, SemanticEvaluatorTimeoutError +Cohesion: 0.13 +Nodes (21): applyCollectorDefaults(), collectClarificationBalanceGate(), detectMetadataBypass(), detectStrictSemanticPath(), ensureFixture(), evaluatePostClarifySemanticPass(), extractSemanticPlanStatus(), findTraceStep() (+13 more) ### Community 35 - "Community 35" -Cohesion: 0.39 -Nodes (14): isRecord(), normalizeArtifact(), normalizeChart(), normalizeChartMappings(), normalizeDisplayType(), normalizeFallback(), normalizeSummary(), normalizeTable() (+6 more) +Cohesion: 0.09 +Nodes (3): ChatPostRunHooksService, MemoryPromotionPolicy, MemoryPromotionService ### Community 36 - "Community 36" -Cohesion: 0.26 -Nodes (10): createIdempotencyKey(), isConflictError(), isRecord(), normalizeTableNames(), readNumberCandidate(), resolveConflictPolicyVersion(), resolveConflictSummary(), setsEqual() (+2 more) +Cohesion: 0.12 +Nodes (22): buildOperationNotice(), closeDialog(), closeDrawer(), createIdempotencyKey(), formatDate(), handleDelete(), handleToggleTerm(), load() (+14 more) ### Community 37 - "Community 37" -Cohesion: 0.29 -Nodes (1): FileDatasourceExecutorService +Cohesion: 0.13 +Nodes (1): SemanticContextPackService ### Community 38 - "Community 38" -Cohesion: 0.28 -Nodes (4): GraphAccelerationAdapter, GraphAccelerationError, GraphAccelerationTimeoutError, GraphAccelerationUnsupportedOperatorError +Cohesion: 0.15 +Nodes (1): SemanticPlanService ### Community 39 - "Community 39" -Cohesion: 0.26 -Nodes (1): SemanticSpineShadowGateService +Cohesion: 0.13 +Nodes (7): formatCell(), normalizeNullableText(), normalizeTableKey(), openEditDialog(), resolveModelRelationships(), resolveRelationshipCounterpartTable(), submitMetadataUpdate() ### Community 40 - "Community 40" -Cohesion: 0.36 -Nodes (1): SkillRegistryService +Cohesion: 0.22 +Nodes (2): ClarificationSemanticEvaluatorService, SemanticEvaluatorTimeoutError ### Community 41 - "Community 41" +Cohesion: 0.39 +Nodes (14): isRecord(), normalizeArtifact(), normalizeChart(), normalizeChartMappings(), normalizeDisplayType(), normalizeFallback(), normalizeSummary(), normalizeTable() (+6 more) + +### Community 42 - "Community 42" +Cohesion: 0.26 +Nodes (10): createIdempotencyKey(), isConflictError(), isRecord(), normalizeTableNames(), readNumberCandidate(), resolveConflictPolicyVersion(), resolveConflictSummary(), setsEqual() (+2 more) + +### Community 43 - "Community 43" +Cohesion: 0.25 +Nodes (6): createDeliverySandboxPolicy(), isSandboxFilesystemWriteAllowed(), isSandboxNetworkAllowed(), isSandboxProcessSpawnAllowed(), normalizeString(), SandboxRuntimeService + +### Community 44 - "Community 44" +Cohesion: 0.26 +Nodes (1): SemanticSpineShadowGateService + +### Community 45 - "Community 45" +Cohesion: 0.27 +Nodes (4): GraphAccelerationAdapter, GraphAccelerationError, GraphAccelerationTimeoutError, GraphAccelerationUnsupportedOperatorError + +### Community 46 - "Community 46" +Cohesion: 0.24 +Nodes (6): handleOpenChange(), includesFailClosedHint(), normalizeAlerts(), resolveAutoExpandedSection(), resolveFailClosedAlerts(), sectionSeverityScore() + +### Community 47 - "Community 47" +Cohesion: 0.28 +Nodes (3): resetToLatest(), resolveConfigVersion(), syncFromConfig() + +### Community 48 - "Community 48" Cohesion: 0.42 Nodes (1): ResolveSavedPriorSqlNode -### Community 42 - "Community 42" +### Community 49 - "Community 49" Cohesion: 0.25 Nodes (0): -### Community 43 - "Community 43" +### Community 50 - "Community 50" +Cohesion: 0.32 +Nodes (3): resetToLatest(), resolveConfigVersion(), syncFromConfig() + +### Community 51 - "Community 51" Cohesion: 0.25 Nodes (0): -### Community 44 - "Community 44" +### Community 52 - "Community 52" Cohesion: 0.29 Nodes (3): InMemorySemanticSpineRepositoryDouble, SemanticSpineContractError, validateSemanticObject() -### Community 45 - "Community 45" +### Community 53 - "Community 53" Cohesion: 0.29 Nodes (0): -### Community 46 - "Community 46" +### Community 54 - "Community 54" Cohesion: 0.29 Nodes (0): -### Community 47 - "Community 47" +### Community 55 - "Community 55" Cohesion: 0.33 Nodes (2): providerStatusLabel(), providerStatusVariant() -### Community 48 - "Community 48" +### Community 56 - "Community 56" Cohesion: 0.38 Nodes (4): createModelingFlowFieldHandleId(), createModelingFlowRelationshipHandleId(), ModelingFlowNode(), normalizeHandleToken() -### Community 49 - "Community 49" +### Community 57 - "Community 57" Cohesion: 0.48 Nodes (6): computeElkLayout(), ElkLayoutTimeoutError, sortEdges(), sortNodes(), toElapsedMs(), withTimeout() -### Community 50 - "Community 50" +### Community 58 - "Community 58" Cohesion: 0.57 Nodes (2): IngestionSourceAdapter, uniqueNonEmpty() -### Community 51 - "Community 51" +### Community 59 - "Community 59" Cohesion: 0.29 Nodes (1): KnowledgeChatSupportFacade -### Community 52 - "Community 52" -Cohesion: 0.38 -Nodes (1): FormatAnswerNode - -### Community 53 - "Community 53" +### Community 60 - "Community 60" Cohesion: 0.33 Nodes (0): -### Community 54 - "Community 54" +### Community 61 - "Community 61" Cohesion: 0.33 Nodes (0): -### Community 55 - "Community 55" +### Community 62 - "Community 62" Cohesion: 0.33 Nodes (0): -### Community 56 - "Community 56" +### Community 63 - "Community 63" Cohesion: 0.4 Nodes (3): buildReadySnapshot(), buildSnakeCaseSnapshot(), SemanticSpineRepositoryStub -### Community 57 - "Community 57" +### Community 64 - "Community 64" Cohesion: 0.33 Nodes (1): PolicyEvaluatorService -### Community 58 - "Community 58" +### Community 65 - "Community 65" Cohesion: 0.33 Nodes (4): RelationshipBridgeDto, RelationshipBridgeEndpointDto, RelationshipGraphEdgeDto, ReplaceWorkspaceRelationshipGraphDto -### Community 59 - "Community 59" +### Community 66 - "Community 66" Cohesion: 0.4 Nodes (1): ResizeObserver -### Community 60 - "Community 60" +### Community 67 - "Community 67" Cohesion: 0.4 Nodes (0): -### Community 61 - "Community 61" +### Community 68 - "Community 68" Cohesion: 0.4 Nodes (0): -### Community 62 - "Community 62" +### Community 69 - "Community 69" Cohesion: 0.4 Nodes (0): -### Community 63 - "Community 63" +### Community 70 - "Community 70" Cohesion: 0.5 Nodes (2): CarouselNext(), useCarousel() -### Community 64 - "Community 64" +### Community 71 - "Community 71" Cohesion: 0.6 Nodes (4): nextEdgeId(), RelationshipEdgeEditorDialog(), toEdge(), toForm() -### Community 65 - "Community 65" +### Community 72 - "Community 72" Cohesion: 0.4 Nodes (0): -### Community 66 - "Community 66" +### Community 73 - "Community 73" Cohesion: 0.4 Nodes (0): -### Community 67 - "Community 67" +### Community 74 - "Community 74" Cohesion: 0.6 Nodes (3): resolveStepTitle(), statusLabel(), statusVariant() -### Community 68 - "Community 68" +### Community 75 - "Community 75" Cohesion: 0.4 Nodes (0): -### Community 69 - "Community 69" +### Community 76 - "Community 76" Cohesion: 0.4 Nodes (1): FakePgClient -### Community 70 - "Community 70" +### Community 77 - "Community 77" Cohesion: 0.8 Nodes (4): normalizeConfidence(), normalizeEndpoint(), normalizeRelationshipGraphEdge(), normalizeRequired() -### Community 71 - "Community 71" +### Community 78 - "Community 78" Cohesion: 0.4 Nodes (4): UpsertDatasourceWorkflowDto, WorkflowDatasourcePayloadDto, WorkflowWorkspaceCreateDto, WorkflowWorkspacePayloadDto -### Community 72 - "Community 72" -Cohesion: 0.5 -Nodes (0): - -### Community 73 - "Community 73" -Cohesion: 0.5 -Nodes (0): - -### Community 74 - "Community 74" -Cohesion: 0.5 -Nodes (0): - -### Community 75 - "Community 75" -Cohesion: 0.5 -Nodes (1): TimeoutEvaluator - -### Community 76 - "Community 76" -Cohesion: 0.83 -Nodes (3): buildModelingRepository(), buildModelingService(), buildRelationshipService() - -### Community 77 - "Community 77" -Cohesion: 0.5 -Nodes (1): RagModule - -### Community 78 - "Community 78" -Cohesion: 0.5 -Nodes (1): ListPromptTemplatesQueryDto - ### Community 79 - "Community 79" -Cohesion: 0.5 -Nodes (1): UpsertModelingSetupDto +Cohesion: 0.4 +Nodes (1): RunV2LangGraphStage ### Community 80 - "Community 80" -Cohesion: 0.5 -Nodes (1): CreateGlossaryTermDto +Cohesion: 0.4 +Nodes (1): RunV2StateMachineStage ### Community 81 - "Community 81" Cohesion: 0.5 -Nodes (1): UpdateGlossaryTermDto +Nodes (0): ### Community 82 - "Community 82" Cohesion: 0.5 -Nodes (3): ContextEnvelopeDto, ContextEnvelopeEntityMappingDto, ContextEnvelopeTimeRangeDto +Nodes (0): ### Community 83 - "Community 83" Cohesion: 0.5 @@ -865,43 +913,43 @@ Nodes (0): ### Community 84 - "Community 84" Cohesion: 0.67 -Nodes (0): +Nodes (2): listRagProviderPresets(), resolveRagProviderPreset() ### Community 85 - "Community 85" -Cohesion: 1.0 -Nodes (2): createDatasourceAndOpenSetupWizard(), openCreateToStep2() +Cohesion: 0.5 +Nodes (1): TimeoutEvaluator ### Community 86 - "Community 86" -Cohesion: 0.67 -Nodes (0): +Cohesion: 0.83 +Nodes (3): buildModelingRepository(), buildModelingService(), buildRelationshipService() ### Community 87 - "Community 87" -Cohesion: 0.67 -Nodes (0): +Cohesion: 0.5 +Nodes (1): RagModule ### Community 88 - "Community 88" -Cohesion: 0.67 -Nodes (0): +Cohesion: 0.5 +Nodes (1): ListPromptTemplatesQueryDto ### Community 89 - "Community 89" -Cohesion: 0.67 -Nodes (0): +Cohesion: 0.5 +Nodes (1): UpsertModelingSetupDto ### Community 90 - "Community 90" -Cohesion: 0.67 -Nodes (0): +Cohesion: 0.5 +Nodes (1): CreateGlossaryTermDto ### Community 91 - "Community 91" -Cohesion: 0.67 -Nodes (0): +Cohesion: 0.5 +Nodes (1): UpdateGlossaryTermDto ### Community 92 - "Community 92" -Cohesion: 0.67 -Nodes (0): +Cohesion: 0.5 +Nodes (3): ContextEnvelopeDto, ContextEnvelopeEntityMappingDto, ContextEnvelopeTimeRangeDto ### Community 93 - "Community 93" -Cohesion: 0.67 -Nodes (0): +Cohesion: 0.5 +Nodes (1): PostRunHooksStage ### Community 94 - "Community 94" Cohesion: 0.67 @@ -912,8 +960,8 @@ Cohesion: 0.67 Nodes (0): ### Community 96 - "Community 96" -Cohesion: 0.67 -Nodes (0): +Cohesion: 1.0 +Nodes (2): createDatasourceAndOpenSetupWizard(), openCreateToStep2() ### Community 97 - "Community 97" Cohesion: 0.67 @@ -932,8 +980,8 @@ Cohesion: 0.67 Nodes (0): ### Community 101 - "Community 101" -Cohesion: 1.0 -Nodes (2): resolveBadgeLabel(), resolveBadgeVariant() +Cohesion: 0.67 +Nodes (0): ### Community 102 - "Community 102" Cohesion: 0.67 @@ -953,179 +1001,179 @@ Nodes (0): ### Community 106 - "Community 106" Cohesion: 0.67 -Nodes (1): DomainError +Nodes (0): ### Community 107 - "Community 107" Cohesion: 0.67 -Nodes (1): OpenRouterAdapter +Nodes (0): ### Community 108 - "Community 108" Cohesion: 0.67 -Nodes (1): KimiAdapter +Nodes (0): ### Community 109 - "Community 109" Cohesion: 0.67 -Nodes (1): VolcengineAdapter +Nodes (0): ### Community 110 - "Community 110" Cohesion: 0.67 -Nodes (1): MinimaxAdapter +Nodes (0): ### Community 111 - "Community 111" Cohesion: 0.67 -Nodes (1): TencentHunyuanAdapter +Nodes (0): ### Community 112 - "Community 112" Cohesion: 0.67 -Nodes (1): SiliconflowAdapter +Nodes (0): ### Community 113 - "Community 113" -Cohesion: 0.67 -Nodes (1): DeepSeekAdapter +Cohesion: 1.0 +Nodes (2): resolveBadgeLabel(), resolveBadgeVariant() ### Community 114 - "Community 114" Cohesion: 0.67 -Nodes (1): OpenAiAdapter +Nodes (0): ### Community 115 - "Community 115" Cohesion: 0.67 -Nodes (1): TongyiAdapter +Nodes (0): ### Community 116 - "Community 116" Cohesion: 0.67 -Nodes (1): MemoryModule +Nodes (0): ### Community 117 - "Community 117" Cohesion: 0.67 -Nodes (1): ChatModule +Nodes (0): ### Community 118 - "Community 118" Cohesion: 0.67 -Nodes (1): SendMessageDto +Nodes (0): ### Community 119 - "Community 119" Cohesion: 0.67 -Nodes (1): ListSessionsDto +Nodes (0): ### Community 120 - "Community 120" Cohesion: 0.67 -Nodes (1): CreateSessionDto +Nodes (0): ### Community 121 - "Community 121" Cohesion: 0.67 -Nodes (1): RenameSessionDto +Nodes (0): ### Community 122 - "Community 122" Cohesion: 0.67 -Nodes (1): AdminOnlyGuard +Nodes (1): DomainError ### Community 123 - "Community 123" Cohesion: 0.67 -Nodes (1): PlatformChatRuntimeFacade +Nodes (1): OpenRouterAdapter ### Community 124 - "Community 124" Cohesion: 0.67 -Nodes (1): GlossaryModule +Nodes (1): KimiAdapter ### Community 125 - "Community 125" Cohesion: 0.67 -Nodes (1): RelationshipImpactSimulatorService +Nodes (1): VolcengineAdapter ### Community 126 - "Community 126" Cohesion: 0.67 -Nodes (1): SemanticRegistryModule +Nodes (1): MinimaxAdapter ### Community 127 - "Community 127" Cohesion: 0.67 -Nodes (1): GovernanceChatAccessFacade +Nodes (1): TencentHunyuanAdapter ### Community 128 - "Community 128" Cohesion: 0.67 -Nodes (2): PreviewDatasourcePayloadDto, PreviewDatasourceTablesDto +Nodes (1): SiliconflowAdapter ### Community 129 - "Community 129" Cohesion: 0.67 -Nodes (1): UpdatePromptTemplateDto +Nodes (1): DeepSeekAdapter ### Community 130 - "Community 130" Cohesion: 0.67 -Nodes (1): CreatePromptTemplateDto +Nodes (1): OpenAiAdapter ### Community 131 - "Community 131" Cohesion: 0.67 -Nodes (1): UpsertModelingGraphDto +Nodes (1): TongyiAdapter ### Community 132 - "Community 132" Cohesion: 0.67 -Nodes (1): ListWorkspaceDatasourceTablePermissionsDto +Nodes (1): MemoryModule ### Community 133 - "Community 133" Cohesion: 0.67 -Nodes (1): ResolveModelingSchemaChangeDto +Nodes (1): AdminOnlyGuard ### Community 134 - "Community 134" Cohesion: 0.67 -Nodes (1): ReplaceWorkspaceDatasourceTablePermissionsDto +Nodes (1): PlatformChatRuntimeFacade ### Community 135 - "Community 135" Cohesion: 0.67 -Nodes (1): ListUsersDto +Nodes (1): GlossaryModule ### Community 136 - "Community 136" Cohesion: 0.67 -Nodes (1): ListGlossaryTermsQueryDto +Nodes (1): RelationshipImpactSimulatorService ### Community 137 - "Community 137" Cohesion: 0.67 -Nodes (1): RollbackGlossaryAnchorDto +Nodes (1): SemanticRegistryModule ### Community 138 - "Community 138" -Cohesion: 1.0 -Nodes (0): +Cohesion: 0.67 +Nodes (1): GovernanceChatAccessFacade ### Community 139 - "Community 139" -Cohesion: 1.0 -Nodes (0): +Cohesion: 0.67 +Nodes (2): PreviewDatasourcePayloadDto, PreviewDatasourceTablesDto ### Community 140 - "Community 140" -Cohesion: 1.0 -Nodes (0): +Cohesion: 0.67 +Nodes (1): UpdatePromptTemplateDto ### Community 141 - "Community 141" -Cohesion: 1.0 -Nodes (0): +Cohesion: 0.67 +Nodes (1): CreatePromptTemplateDto ### Community 142 - "Community 142" -Cohesion: 1.0 -Nodes (0): +Cohesion: 0.67 +Nodes (2): CheckRagTaskConfigDraftDto, CheckRagTaskConfigHealthDto ### Community 143 - "Community 143" -Cohesion: 1.0 -Nodes (0): +Cohesion: 0.67 +Nodes (1): UpsertModelingGraphDto ### Community 144 - "Community 144" -Cohesion: 1.0 -Nodes (0): +Cohesion: 0.67 +Nodes (1): ListWorkspaceDatasourceTablePermissionsDto ### Community 145 - "Community 145" -Cohesion: 1.0 -Nodes (0): +Cohesion: 0.67 +Nodes (1): ResolveModelingSchemaChangeDto ### Community 146 - "Community 146" -Cohesion: 1.0 -Nodes (1): ELK +Cohesion: 0.67 +Nodes (1): ReplaceWorkspaceDatasourceTablePermissionsDto ### Community 147 - "Community 147" -Cohesion: 1.0 -Nodes (0): +Cohesion: 0.67 +Nodes (1): ListUsersDto ### Community 148 - "Community 148" -Cohesion: 1.0 -Nodes (0): +Cohesion: 0.67 +Nodes (1): ListGlossaryTermsQueryDto ### Community 149 - "Community 149" -Cohesion: 1.0 -Nodes (0): +Cohesion: 0.67 +Nodes (1): RollbackGlossaryAnchorDto ### Community 150 - "Community 150" Cohesion: 1.0 @@ -1161,7 +1209,7 @@ Nodes (0): ### Community 158 - "Community 158" Cohesion: 1.0 -Nodes (0): +Nodes (1): ELK ### Community 159 - "Community 159" Cohesion: 1.0 @@ -1417,7 +1465,7 @@ Nodes (0): ### Community 222 - "Community 222" Cohesion: 1.0 -Nodes (1): AppModule +Nodes (0): ### Community 223 - "Community 223" Cohesion: 1.0 @@ -1425,291 +1473,291 @@ Nodes (0): ### Community 224 - "Community 224" Cohesion: 1.0 -Nodes (1): LlmModule +Nodes (0): ### Community 225 - "Community 225" Cohesion: 1.0 -Nodes (1): ApplyMemoryFeedbackDto +Nodes (0): ### Community 226 - "Community 226" Cohesion: 1.0 -Nodes (1): AppConfigModule +Nodes (0): ### Community 227 - "Community 227" Cohesion: 1.0 -Nodes (1): PlatformModule +Nodes (0): ### Community 228 - "Community 228" Cohesion: 1.0 -Nodes (1): PlatformLlmModule +Nodes (0): ### Community 229 - "Community 229" Cohesion: 1.0 -Nodes (1): PlatformConfigModule +Nodes (0): ### Community 230 - "Community 230" Cohesion: 1.0 -Nodes (1): PlatformObservabilityModule +Nodes (0): ### Community 231 - "Community 231" Cohesion: 1.0 -Nodes (1): PlatformDataAccessModule +Nodes (0): ### Community 232 - "Community 232" Cohesion: 1.0 -Nodes (1): PlatformDataQueryModule +Nodes (0): ### Community 233 - "Community 233" Cohesion: 1.0 -Nodes (1): PlatformDataModule +Nodes (0): ### Community 234 - "Community 234" Cohesion: 1.0 -Nodes (1): PlatformDataPersistenceModule +Nodes (0): ### Community 235 - "Community 235" Cohesion: 1.0 -Nodes (1): ObservabilityModule +Nodes (0): ### Community 236 - "Community 236" Cohesion: 1.0 -Nodes (1): SystemModule +Nodes (0): ### Community 237 - "Community 237" Cohesion: 1.0 -Nodes (1): KnowledgeModule +Nodes (0): ### Community 238 - "Community 238" Cohesion: 1.0 -Nodes (1): SemanticSpineModule +Nodes (1): AppModule ### Community 239 - "Community 239" Cohesion: 1.0 -Nodes (1): SkillRegistryModule +Nodes (0): ### Community 240 - "Community 240" Cohesion: 1.0 -Nodes (1): GovernanceModule +Nodes (1): LlmModule ### Community 241 - "Community 241" Cohesion: 1.0 -Nodes (1): DatasourceModule +Nodes (1): ApplyMemoryFeedbackDto ### Community 242 - "Community 242" Cohesion: 1.0 -Nodes (1): CreateDatasourceDto +Nodes (1): AppConfigModule ### Community 243 - "Community 243" Cohesion: 1.0 -Nodes (1): UploadFileDatasourceDto +Nodes (1): PlatformModule ### Community 244 - "Community 244" Cohesion: 1.0 -Nodes (1): UpdateDatasourceDto +Nodes (1): PlatformLlmModule ### Community 245 - "Community 245" Cohesion: 1.0 -Nodes (1): SettingsModule +Nodes (1): PlatformConfigModule ### Community 246 - "Community 246" Cohesion: 1.0 -Nodes (1): BatchUpdateModelStatusDto +Nodes (1): PlatformObservabilityModule ### Community 247 - "Community 247" Cohesion: 1.0 -Nodes (1): UpdateModelStatusDto +Nodes (1): PlatformDataAccessModule ### Community 248 - "Community 248" Cohesion: 1.0 -Nodes (1): RefreshProviderModelsDto +Nodes (1): PlatformDataQueryModule ### Community 249 - "Community 249" Cohesion: 1.0 -Nodes (1): CreateProviderDto +Nodes (1): PlatformDataModule ### Community 250 - "Community 250" Cohesion: 1.0 -Nodes (1): GovernanceAccessModule +Nodes (1): PlatformDataPersistenceModule ### Community 251 - "Community 251" Cohesion: 1.0 -Nodes (1): WorkspaceModule +Nodes (1): ObservabilityModule ### Community 252 - "Community 252" Cohesion: 1.0 -Nodes (1): RemoveWorkspaceMembersDto +Nodes (1): SystemModule ### Community 253 - "Community 253" Cohesion: 1.0 -Nodes (1): RenameWorkspaceDto +Nodes (1): KnowledgeModule ### Community 254 - "Community 254" Cohesion: 1.0 -Nodes (1): GetModelingPreviewDto +Nodes (1): SemanticSpineModule ### Community 255 - "Community 255" Cohesion: 1.0 -Nodes (1): UpdateWorkspaceMemberRoleDto +Nodes (1): SkillRegistryModule ### Community 256 - "Community 256" Cohesion: 1.0 -Nodes (1): DetectModelingSchemaChangeDto +Nodes (1): GovernanceModule ### Community 257 - "Community 257" Cohesion: 1.0 -Nodes (1): ListWorkspaceMembersDto +Nodes (1): DatasourceModule ### Community 258 - "Community 258" Cohesion: 1.0 -Nodes (1): DeployModelingGraphDto +Nodes (1): CreateDatasourceDto ### Community 259 - "Community 259" Cohesion: 1.0 -Nodes (1): AddWorkspaceMemberDto +Nodes (1): UploadFileDatasourceDto ### Community 260 - "Community 260" Cohesion: 1.0 -Nodes (1): CreateWorkspaceDto +Nodes (1): UpdateDatasourceDto ### Community 261 - "Community 261" Cohesion: 1.0 -Nodes (1): UserModule +Nodes (1): SettingsModule ### Community 262 - "Community 262" Cohesion: 1.0 -Nodes (1): BatchDeleteUsersDto +Nodes (1): UpsertRagTaskConfigDto ### Community 263 - "Community 263" Cohesion: 1.0 -Nodes (1): UpdateUserStatusDto +Nodes (1): PreviewRagProviderModelsDto ### Community 264 - "Community 264" Cohesion: 1.0 -Nodes (1): UpdateUserDto +Nodes (1): BatchUpdateModelStatusDto ### Community 265 - "Community 265" Cohesion: 1.0 -Nodes (1): UserVariableDto +Nodes (1): UpdateModelStatusDto ### Community 266 - "Community 266" Cohesion: 1.0 -Nodes (1): CreateUserDto +Nodes (1): RefreshProviderModelsDto ### Community 267 - "Community 267" Cohesion: 1.0 -Nodes (1): EvalModule +Nodes (1): CreateProviderDto ### Community 268 - "Community 268" Cohesion: 1.0 -Nodes (1): RunEvaluationDto +Nodes (1): GovernanceAccessModule ### Community 269 - "Community 269" Cohesion: 1.0 -Nodes (1): ConversationModule +Nodes (1): WorkspaceModule ### Community 270 - "Community 270" Cohesion: 1.0 -Nodes (1): SaveViewFromRunDto +Nodes (1): RemoveWorkspaceMembersDto ### Community 271 - "Community 271" Cohesion: 1.0 -Nodes (1): AgentModule +Nodes (1): RenameWorkspaceDto ### Community 272 - "Community 272" Cohesion: 1.0 -Nodes (0): +Nodes (1): GetModelingPreviewDto ### Community 273 - "Community 273" Cohesion: 1.0 -Nodes (0): +Nodes (1): UpdateWorkspaceMemberRoleDto ### Community 274 - "Community 274" Cohesion: 1.0 -Nodes (0): +Nodes (1): DetectModelingSchemaChangeDto ### Community 275 - "Community 275" Cohesion: 1.0 -Nodes (0): +Nodes (1): ListWorkspaceMembersDto ### Community 276 - "Community 276" Cohesion: 1.0 -Nodes (0): +Nodes (1): DeployModelingGraphDto ### Community 277 - "Community 277" Cohesion: 1.0 -Nodes (0): +Nodes (1): AddWorkspaceMemberDto ### Community 278 - "Community 278" Cohesion: 1.0 -Nodes (0): +Nodes (1): CreateWorkspaceDto ### Community 279 - "Community 279" Cohesion: 1.0 -Nodes (0): +Nodes (1): UserModule ### Community 280 - "Community 280" Cohesion: 1.0 -Nodes (0): +Nodes (1): BatchDeleteUsersDto ### Community 281 - "Community 281" Cohesion: 1.0 -Nodes (0): +Nodes (1): UpdateUserStatusDto ### Community 282 - "Community 282" Cohesion: 1.0 -Nodes (0): +Nodes (1): UpdateUserDto ### Community 283 - "Community 283" Cohesion: 1.0 -Nodes (0): +Nodes (1): UserVariableDto ### Community 284 - "Community 284" Cohesion: 1.0 -Nodes (0): +Nodes (1): CreateUserDto ### Community 285 - "Community 285" Cohesion: 1.0 -Nodes (0): +Nodes (1): EvalModule ### Community 286 - "Community 286" Cohesion: 1.0 -Nodes (0): +Nodes (1): RunEvaluationDto ### Community 287 - "Community 287" Cohesion: 1.0 -Nodes (0): +Nodes (1): ConversationModule ### Community 288 - "Community 288" Cohesion: 1.0 -Nodes (0): +Nodes (1): ChatModule ### Community 289 - "Community 289" Cohesion: 1.0 -Nodes (0): +Nodes (1): SendMessageDto ### Community 290 - "Community 290" Cohesion: 1.0 -Nodes (0): +Nodes (1): ListSessionsDto ### Community 291 - "Community 291" Cohesion: 1.0 -Nodes (0): +Nodes (1): CreateSessionDto ### Community 292 - "Community 292" Cohesion: 1.0 -Nodes (0): +Nodes (1): RenameSessionDto ### Community 293 - "Community 293" Cohesion: 1.0 -Nodes (0): +Nodes (1): SaveViewFromRunDto ### Community 294 - "Community 294" Cohesion: 1.0 -Nodes (0): +Nodes (1): Text2SqlModule ### Community 295 - "Community 295" Cohesion: 1.0 -Nodes (0): +Nodes (1): AgentModule ### Community 296 - "Community 296" Cohesion: 1.0 @@ -2487,20 +2535,212 @@ Nodes (0): Cohesion: 1.0 Nodes (0): +### Community 490 - "Community 490" +Cohesion: 1.0 +Nodes (0): + +### Community 491 - "Community 491" +Cohesion: 1.0 +Nodes (0): + +### Community 492 - "Community 492" +Cohesion: 1.0 +Nodes (0): + +### Community 493 - "Community 493" +Cohesion: 1.0 +Nodes (0): + +### Community 494 - "Community 494" +Cohesion: 1.0 +Nodes (0): + +### Community 495 - "Community 495" +Cohesion: 1.0 +Nodes (0): + +### Community 496 - "Community 496" +Cohesion: 1.0 +Nodes (0): + +### Community 497 - "Community 497" +Cohesion: 1.0 +Nodes (0): + +### Community 498 - "Community 498" +Cohesion: 1.0 +Nodes (0): + +### Community 499 - "Community 499" +Cohesion: 1.0 +Nodes (0): + +### Community 500 - "Community 500" +Cohesion: 1.0 +Nodes (0): + +### Community 501 - "Community 501" +Cohesion: 1.0 +Nodes (0): + +### Community 502 - "Community 502" +Cohesion: 1.0 +Nodes (0): + +### Community 503 - "Community 503" +Cohesion: 1.0 +Nodes (0): + +### Community 504 - "Community 504" +Cohesion: 1.0 +Nodes (0): + +### Community 505 - "Community 505" +Cohesion: 1.0 +Nodes (0): + +### Community 506 - "Community 506" +Cohesion: 1.0 +Nodes (0): + +### Community 507 - "Community 507" +Cohesion: 1.0 +Nodes (0): + +### Community 508 - "Community 508" +Cohesion: 1.0 +Nodes (0): + +### Community 509 - "Community 509" +Cohesion: 1.0 +Nodes (0): + +### Community 510 - "Community 510" +Cohesion: 1.0 +Nodes (0): + +### Community 511 - "Community 511" +Cohesion: 1.0 +Nodes (0): + +### Community 512 - "Community 512" +Cohesion: 1.0 +Nodes (0): + +### Community 513 - "Community 513" +Cohesion: 1.0 +Nodes (0): + +### Community 514 - "Community 514" +Cohesion: 1.0 +Nodes (0): + +### Community 515 - "Community 515" +Cohesion: 1.0 +Nodes (0): + +### Community 516 - "Community 516" +Cohesion: 1.0 +Nodes (0): + +### Community 517 - "Community 517" +Cohesion: 1.0 +Nodes (0): + +### Community 518 - "Community 518" +Cohesion: 1.0 +Nodes (0): + +### Community 519 - "Community 519" +Cohesion: 1.0 +Nodes (0): + +### Community 520 - "Community 520" +Cohesion: 1.0 +Nodes (0): + +### Community 521 - "Community 521" +Cohesion: 1.0 +Nodes (0): + +### Community 522 - "Community 522" +Cohesion: 1.0 +Nodes (0): + +### Community 523 - "Community 523" +Cohesion: 1.0 +Nodes (0): + +### Community 524 - "Community 524" +Cohesion: 1.0 +Nodes (0): + +### Community 525 - "Community 525" +Cohesion: 1.0 +Nodes (0): + +### Community 526 - "Community 526" +Cohesion: 1.0 +Nodes (0): + +### Community 527 - "Community 527" +Cohesion: 1.0 +Nodes (0): + +### Community 528 - "Community 528" +Cohesion: 1.0 +Nodes (0): + +### Community 529 - "Community 529" +Cohesion: 1.0 +Nodes (0): + +### Community 530 - "Community 530" +Cohesion: 1.0 +Nodes (0): + +### Community 531 - "Community 531" +Cohesion: 1.0 +Nodes (0): + +### Community 532 - "Community 532" +Cohesion: 1.0 +Nodes (0): + +### Community 533 - "Community 533" +Cohesion: 1.0 +Nodes (0): + +### Community 534 - "Community 534" +Cohesion: 1.0 +Nodes (0): + +### Community 535 - "Community 535" +Cohesion: 1.0 +Nodes (0): + +### Community 536 - "Community 536" +Cohesion: 1.0 +Nodes (0): + +### Community 537 - "Community 537" +Cohesion: 1.0 +Nodes (0): + ## Knowledge Gaps -- **80 isolated node(s):** `ELK`, `ElkLayoutTimeoutError`, `AppModule`, `LlmModule`, `ApplyMemoryFeedbackDto` (+75 more) +- **93 isolated node(s):** `ELK`, `ElkLayoutTimeoutError`, `AppModule`, `LlmModule`, `ApplyMemoryFeedbackDto` (+88 more) These have ≤1 connection - possible missing edges or undocumented components. -- **Thin community `Community 138`** (2 nodes): `pickSelectOption()`, `settings-modeling-relationship-editor.spec.tsx` +- **Thin community `Community 150`** (2 nodes): `pickSelectOption()`, `settings-modeling-relationship-editor.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 139`** (2 nodes): `SectionHarness()`, `rag-delivery-section.spec.tsx` +- **Thin community `Community 151`** (2 nodes): `SectionHarness()`, `rag-delivery-section.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 140`** (2 nodes): `waitForWorkspaceDatasourceReady()`, `settings-modeling-workspace.spec.tsx` +- **Thin community `Community 152`** (2 nodes): `waitForWorkspaceDatasourceReady()`, `settings-modeling-workspace.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 141`** (2 nodes): `ChatBIResultTabsHarness()`, `chatbi-result-tabs.spec.tsx` +- **Thin community `Community 153`** (2 nodes): `ChatBIResultTabsHarness()`, `chatbi-result-tabs.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 142`** (2 nodes): `createDelivery()`, `rag-delivery-panel.spec.tsx` +- **Thin community `Community 154`** (2 nodes): `createDelivery()`, `rag-delivery-panel.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 143`** (2 nodes): `[ +- **Thin community `Community 155`** (2 nodes): `[ { id: "model.orders", tableName: "orders", @@ -2511,713 +2751,785 @@ Nodes (0): } ]()`, `settings-modeling-details-panel.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 144`** (2 nodes): `onUnhandledRejection()`, `chat-panel.spec.tsx` +- **Thin community `Community 156`** (2 nodes): `onUnhandledRejection()`, `chat-panel.spec.tsx` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 157`** (2 nodes): `createSettingsView()`, `settings-mobile-smoke.spec.tsx` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 158`** (2 nodes): `ELK`, `elkjs.d.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 159`** (2 nodes): `RootLayout()`, `layout.tsx` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 160`** (2 nodes): `ChatPage()`, `page.tsx` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 161`** (2 nodes): `AppShell()`, `app-shell.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 145`** (2 nodes): `createSettingsView()`, `settings-mobile-smoke.spec.tsx` +- **Thin community `Community 162`** (2 nodes): `AspectRatio()`, `aspect-ratio.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 146`** (2 nodes): `ELK`, `elkjs.d.ts` +- **Thin community `Community 163`** (2 nodes): `StateBlock()`, `state-block.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 147`** (2 nodes): `RootLayout()`, `layout.tsx` +- **Thin community `Community 164`** (2 nodes): `DirectionProvider()`, `direction.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 148`** (2 nodes): `ChatPage()`, `page.tsx` +- **Thin community `Community 165`** (2 nodes): `cn()`, `tabs.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 149`** (2 nodes): `AppShell()`, `app-shell.tsx` +- **Thin community `Community 166`** (2 nodes): `ButtonGroup()`, `button-group.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 150`** (2 nodes): `AspectRatio()`, `aspect-ratio.tsx` +- **Thin community `Community 167`** (2 nodes): `cn()`, `card.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 151`** (2 nodes): `StateBlock()`, `state-block.tsx` +- **Thin community `Community 168`** (2 nodes): `InputGroup()`, `input-group.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 152`** (2 nodes): `DirectionProvider()`, `direction.tsx` +- **Thin community `Community 169`** (2 nodes): `cn()`, `input-otp.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 153`** (2 nodes): `cn()`, `tabs.tsx` +- **Thin community `Community 170`** (2 nodes): `HoverCard()`, `hover-card.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 154`** (2 nodes): `ButtonGroup()`, `button-group.tsx` +- **Thin community `Community 171`** (2 nodes): `cn()`, `field.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 155`** (2 nodes): `cn()`, `card.tsx` +- **Thin community `Community 172`** (2 nodes): `Label()`, `label.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 156`** (2 nodes): `InputGroup()`, `input-group.tsx` +- **Thin community `Community 173`** (2 nodes): `cn()`, `empty.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 157`** (2 nodes): `cn()`, `input-otp.tsx` +- **Thin community `Community 174`** (2 nodes): `TooltipContent()`, `tooltip.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 158`** (2 nodes): `HoverCard()`, `hover-card.tsx` +- **Thin community `Community 175`** (2 nodes): `cn()`, `alert.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 159`** (2 nodes): `cn()`, `field.tsx` +- **Thin community `Community 176`** (2 nodes): `Switch()`, `switch.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 160`** (2 nodes): `Label()`, `label.tsx` +- **Thin community `Community 177`** (2 nodes): `cn()`, `command.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 161`** (2 nodes): `cn()`, `empty.tsx` +- **Thin community `Community 178`** (2 nodes): `ToggleGroup()`, `toggle-group.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 162`** (2 nodes): `TooltipContent()`, `tooltip.tsx` +- **Thin community `Community 179`** (2 nodes): `Avatar()`, `avatar.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 163`** (2 nodes): `cn()`, `alert.tsx` +- **Thin community `Community 180`** (2 nodes): `cn()`, `kbd.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 164`** (2 nodes): `Switch()`, `switch.tsx` +- **Thin community `Community 181`** (2 nodes): `SectionHeader()`, `section-header.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 165`** (2 nodes): `cn()`, `command.tsx` +- **Thin community `Community 182`** (2 nodes): `Badge()`, `badge.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 166`** (2 nodes): `ToggleGroup()`, `toggle-group.tsx` +- **Thin community `Community 183`** (2 nodes): `cn()`, `table.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 167`** (2 nodes): `Avatar()`, `avatar.tsx` +- **Thin community `Community 184`** (2 nodes): `Separator()`, `separator.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 168`** (2 nodes): `cn()`, `kbd.tsx` +- **Thin community `Community 185`** (2 nodes): `Checkbox()`, `checkbox.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 169`** (2 nodes): `SectionHeader()`, `section-header.tsx` +- **Thin community `Community 186`** (2 nodes): `Spinner()`, `spinner.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 170`** (2 nodes): `Badge()`, `badge.tsx` +- **Thin community `Community 187`** (2 nodes): `Collapsible()`, `collapsible.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 171`** (2 nodes): `cn()`, `table.tsx` +- **Thin community `Community 188`** (2 nodes): `cn()`, `textarea.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 172`** (2 nodes): `Separator()`, `separator.tsx` +- **Thin community `Community 189`** (2 nodes): `Input()`, `input.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 173`** (2 nodes): `Checkbox()`, `checkbox.tsx` +- **Thin community `Community 190`** (2 nodes): `Skeleton()`, `skeleton.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 174`** (2 nodes): `Spinner()`, `spinner.tsx` +- **Thin community `Community 191`** (2 nodes): `workspace-editor-dialog.tsx`, `WorkspaceEditorDialog()` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 175`** (2 nodes): `Collapsible()`, `collapsible.tsx` +- **Thin community `Community 192`** (2 nodes): `handleKeyDown()`, `modeling-context-drawer.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 176`** (2 nodes): `cn()`, `textarea.tsx` +- **Thin community `Community 193`** (2 nodes): `resolveBlockingReasonGuidance()`, `modeling-deploy-panel.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 177`** (2 nodes): `Input()`, `input.tsx` +- **Thin community `Community 194`** (2 nodes): `TextPart()`, `assistant-message.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 178`** (2 nodes): `Skeleton()`, `skeleton.tsx` +- **Thin community `Community 195`** (2 nodes): `isRecord()`, `sql-inline-panel.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 179`** (2 nodes): `workspace-editor-dialog.tsx`, `WorkspaceEditorDialog()` +- **Thin community `Community 196`** (2 nodes): `resolveMessageRunId()`, `assistant-thread.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 180`** (2 nodes): `handleKeyDown()`, `modeling-context-drawer.tsx` +- **Thin community `Community 197`** (2 nodes): `ModelSelector()`, `model-selector.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 181`** (2 nodes): `resolveBlockingReasonGuidance()`, `modeling-deploy-panel.tsx` +- **Thin community `Community 198`** (2 nodes): `SessionActions()`, `session-actions.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 182`** (2 nodes): `TextPart()`, `assistant-message.tsx` +- **Thin community `Community 199`** (2 nodes): `SqlDebugDetails()`, `sql-debug-details.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 183`** (2 nodes): `isRecord()`, `sql-inline-panel.tsx` +- **Thin community `Community 200`** (2 nodes): `SqlRunSummary()`, `sql-run-summary.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 184`** (2 nodes): `resolveMessageRunId()`, `assistant-thread.tsx` +- **Thin community `Community 201`** (2 nodes): `isNumericValue()`, `sql-result-table.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 185`** (2 nodes): `ModelSelector()`, `model-selector.tsx` +- **Thin community `Community 202`** (2 nodes): `statusVariant()`, `sql-execution-timeline.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 186`** (2 nodes): `SessionActions()`, `session-actions.tsx` +- **Thin community `Community 203`** (2 nodes): `useIsMobile()`, `use-mobile.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 187`** (2 nodes): `SqlDebugDetails()`, `sql-debug-details.tsx` +- **Thin community `Community 204`** (2 nodes): `utils.ts`, `cn()` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 188`** (2 nodes): `SqlRunSummary()`, `sql-run-summary.tsx` +- **Thin community `Community 205`** (2 nodes): `createService()`, `sql-generation.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 189`** (2 nodes): `isNumericValue()`, `sql-result-table.tsx` +- **Thin community `Community 206`** (2 nodes): `createPreparedRunContext()`, `text2sql-v2-langgraph-result.mapper.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 190`** (2 nodes): `statusVariant()`, `sql-execution-timeline.tsx` +- **Thin community `Community 207`** (2 nodes): `createService()`, `semantic-registry.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 191`** (2 nodes): `useIsMobile()`, `use-mobile.ts` +- **Thin community `Community 208`** (2 nodes): `createBaseRun()`, `langgraph-runtime.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 192`** (2 nodes): `utils.ts`, `cn()` +- **Thin community `Community 209`** (2 nodes): `createConfigServiceMock()`, `rag-task-health-probe.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 193`** (2 nodes): `createService()`, `sql-generation.service.spec.ts` +- **Thin community `Community 210`** (2 nodes): `createBaseRun()`, `delivery-contract.mapper.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 194`** (2 nodes): `createService()`, `semantic-registry.service.spec.ts` +- **Thin community `Community 211`** (2 nodes): `createRequest()`, `request-actor.middleware.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 195`** (2 nodes): `createBaseRun()`, `delivery-contract.mapper.spec.ts` +- **Thin community `Community 212`** (2 nodes): `createBaseRun()`, `text2sql-v2-runner.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 196`** (2 nodes): `createRequest()`, `request-actor.middleware.spec.ts` +- **Thin community `Community 213`** (2 nodes): `workspace-admin.guard.spec.ts`, `createContext()` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 197`** (2 nodes): `workspace-admin.guard.spec.ts`, `createContext()` +- **Thin community `Community 214`** (2 nodes): `reset()`, `langsmith-config.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 198`** (2 nodes): `reset()`, `langsmith-config.spec.ts` +- **Thin community `Community 215`** (2 nodes): `createNode()`, `build-semantic-query.node.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 199`** (2 nodes): `createNode()`, `build-semantic-query.node.spec.ts` +- **Thin community `Community 216`** (2 nodes): `createContext()`, `admin-only.guard.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 200`** (2 nodes): `createContext()`, `admin-only.guard.spec.ts` +- **Thin community `Community 217`** (2 nodes): `createService()`, `text2sql-task-profile-policy.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 201`** (2 nodes): `resetAppEnv()`, `config.module.spec.ts` +- **Thin community `Community 218`** (2 nodes): `resetAppEnv()`, `config.module.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 202`** (2 nodes): `writeRepoFile()`, `capability-boundary-check.spec.ts` +- **Thin community `Community 219`** (2 nodes): `writeRepoFile()`, `capability-boundary-check.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 203`** (2 nodes): `createPolicy()`, `clarification-fusion.policy.spec.ts` +- **Thin community `Community 220`** (2 nodes): `createPolicy()`, `clarification-fusion.policy.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 204`** (2 nodes): `buildLongSchemaText()`, `rag-chunking.service.spec.ts` +- **Thin community `Community 221`** (2 nodes): `createRepository()`, `rag-task-config.repository.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 205`** (2 nodes): `datasource()`, `query-executor-router.spec.ts` +- **Thin community `Community 222`** (2 nodes): `buildLongSchemaText()`, `rag-chunking.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 206`** (2 nodes): `createNode()`, `build-intent-plan.node.spec.ts` +- **Thin community `Community 223`** (2 nodes): `datasource()`, `query-executor-router.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 207`** (2 nodes): `createSimpleSqliteDb()`, `query-executors.spec.ts` +- **Thin community `Community 224`** (2 nodes): `createNode()`, `build-intent-plan.node.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 208`** (2 nodes): `createBaseRun()`, `sandbox-failover.spec.ts` +- **Thin community `Community 225`** (2 nodes): `createSimpleSqliteDb()`, `query-executors.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 209`** (2 nodes): `buildUsecase()`, `save-view-from-run.spec.ts` +- **Thin community `Community 226`** (2 nodes): `createBaseRun()`, `sandbox-failover.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 210`** (2 nodes): `workspace-relationship-api.spec.ts`, `buildService()` +- **Thin community `Community 227`** (2 nodes): `workspace-relationship-api.spec.ts`, `buildService()` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 211`** (2 nodes): `buildArtifact()`, `sandbox-isolation.spec.ts` +- **Thin community `Community 228`** (2 nodes): `buildArtifact()`, `sandbox-isolation.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 212`** (2 nodes): `createRun()`, `rag-audit-replay.spec.ts` +- **Thin community `Community 229`** (2 nodes): `datasource()`, `query-executor-router-table-permissions.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 213`** (2 nodes): `datasource()`, `query-executor-router-table-permissions.spec.ts` +- **Thin community `Community 230`** (2 nodes): `sleep()`, `rag-datasource-gate-metrics.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 214`** (2 nodes): `sleep()`, `rag-datasource-gate-metrics.spec.ts` +- **Thin community `Community 231`** (2 nodes): `buildSnapshot()`, `semantic-spine-compiler.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 215`** (2 nodes): `buildSnapshot()`, `semantic-spine-compiler.spec.ts` +- **Thin community `Community 232`** (2 nodes): `workspace-modeling-setup.spec.ts`, `buildService()` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 216`** (2 nodes): `workspace-modeling-setup.spec.ts`, `buildService()` +- **Thin community `Community 233`** (2 nodes): `createRun()`, `memory-promotion.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 217`** (2 nodes): `createRun()`, `memory-promotion.spec.ts` +- **Thin community `Community 234`** (2 nodes): `buildSamples()`, `glossary-selected-context-gate.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 218`** (2 nodes): `buildSamples()`, `glossary-selected-context-gate.spec.ts` +- **Thin community `Community 235`** (2 nodes): `readErrorMessage()`, `user-workspace-authz.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 219`** (2 nodes): `readErrorMessage()`, `user-workspace-authz.spec.ts` +- **Thin community `Community 236`** (2 nodes): `readErrorMessage()`, `rule-group-authz.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 220`** (2 nodes): `readErrorMessage()`, `rule-group-authz.spec.ts` +- **Thin community `Community 237`** (2 nodes): `workspace-datasource-authz.spec.ts`, `readErrorMessage()` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 221`** (2 nodes): `workspace-datasource-authz.spec.ts`, `readErrorMessage()` +- **Thin community `Community 238`** (2 nodes): `AppModule`, `app.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 222`** (2 nodes): `AppModule`, `app.module.ts` +- **Thin community `Community 239`** (2 nodes): `requestIdMiddleware()`, `request-id.middleware.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 223`** (2 nodes): `requestIdMiddleware()`, `request-id.middleware.ts` +- **Thin community `Community 240`** (2 nodes): `LlmModule`, `llm.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 224`** (2 nodes): `LlmModule`, `llm.module.ts` +- **Thin community `Community 241`** (2 nodes): `ApplyMemoryFeedbackDto`, `apply-memory-feedback.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 225`** (2 nodes): `ApplyMemoryFeedbackDto`, `apply-memory-feedback.dto.ts` +- **Thin community `Community 242`** (2 nodes): `AppConfigModule`, `config.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 226`** (2 nodes): `AppConfigModule`, `config.module.ts` +- **Thin community `Community 243`** (2 nodes): `PlatformModule`, `platform.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 227`** (2 nodes): `PlatformModule`, `platform.module.ts` +- **Thin community `Community 244`** (2 nodes): `PlatformLlmModule`, `llm.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 228`** (2 nodes): `PlatformLlmModule`, `llm.module.ts` +- **Thin community `Community 245`** (2 nodes): `PlatformConfigModule`, `config.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 229`** (2 nodes): `PlatformConfigModule`, `config.module.ts` +- **Thin community `Community 246`** (2 nodes): `PlatformObservabilityModule`, `observability.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 230`** (2 nodes): `PlatformObservabilityModule`, `observability.module.ts` +- **Thin community `Community 247`** (2 nodes): `PlatformDataAccessModule`, `access.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 231`** (2 nodes): `PlatformDataAccessModule`, `access.module.ts` +- **Thin community `Community 248`** (2 nodes): `PlatformDataQueryModule`, `query.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 232`** (2 nodes): `PlatformDataQueryModule`, `query.module.ts` +- **Thin community `Community 249`** (2 nodes): `PlatformDataModule`, `data.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 233`** (2 nodes): `PlatformDataModule`, `data.module.ts` +- **Thin community `Community 250`** (2 nodes): `PlatformDataPersistenceModule`, `persistence.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 234`** (2 nodes): `PlatformDataPersistenceModule`, `persistence.module.ts` +- **Thin community `Community 251`** (2 nodes): `ObservabilityModule`, `observability.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 235`** (2 nodes): `ObservabilityModule`, `observability.module.ts` +- **Thin community `Community 252`** (2 nodes): `SystemModule`, `system.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 236`** (2 nodes): `SystemModule`, `system.module.ts` +- **Thin community `Community 253`** (2 nodes): `KnowledgeModule`, `knowledge.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 237`** (2 nodes): `KnowledgeModule`, `knowledge.module.ts` +- **Thin community `Community 254`** (2 nodes): `SemanticSpineModule`, `semantic-spine.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 238`** (2 nodes): `SemanticSpineModule`, `semantic-spine.module.ts` +- **Thin community `Community 255`** (2 nodes): `SkillRegistryModule`, `skill-registry.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 239`** (2 nodes): `SkillRegistryModule`, `skill-registry.module.ts` +- **Thin community `Community 256`** (2 nodes): `GovernanceModule`, `governance.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 240`** (2 nodes): `GovernanceModule`, `governance.module.ts` +- **Thin community `Community 257`** (2 nodes): `DatasourceModule`, `datasource.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 241`** (2 nodes): `DatasourceModule`, `datasource.module.ts` +- **Thin community `Community 258`** (2 nodes): `CreateDatasourceDto`, `create-datasource.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 242`** (2 nodes): `CreateDatasourceDto`, `create-datasource.dto.ts` +- **Thin community `Community 259`** (2 nodes): `UploadFileDatasourceDto`, `upload-file-datasource.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 243`** (2 nodes): `UploadFileDatasourceDto`, `upload-file-datasource.dto.ts` +- **Thin community `Community 260`** (2 nodes): `UpdateDatasourceDto`, `update-datasource.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 244`** (2 nodes): `UpdateDatasourceDto`, `update-datasource.dto.ts` +- **Thin community `Community 261`** (2 nodes): `SettingsModule`, `settings.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 245`** (2 nodes): `SettingsModule`, `settings.module.ts` +- **Thin community `Community 262`** (2 nodes): `UpsertRagTaskConfigDto`, `upsert-rag-task-config.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 246`** (2 nodes): `BatchUpdateModelStatusDto`, `batch-update-model-status.dto.ts` +- **Thin community `Community 263`** (2 nodes): `PreviewRagProviderModelsDto`, `preview-rag-provider-models.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 247`** (2 nodes): `UpdateModelStatusDto`, `update-model-status.dto.ts` +- **Thin community `Community 264`** (2 nodes): `BatchUpdateModelStatusDto`, `batch-update-model-status.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 248`** (2 nodes): `RefreshProviderModelsDto`, `refresh-provider-models.dto.ts` +- **Thin community `Community 265`** (2 nodes): `UpdateModelStatusDto`, `update-model-status.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 249`** (2 nodes): `CreateProviderDto`, `create-provider.dto.ts` +- **Thin community `Community 266`** (2 nodes): `RefreshProviderModelsDto`, `refresh-provider-models.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 250`** (2 nodes): `GovernanceAccessModule`, `access.module.ts` +- **Thin community `Community 267`** (2 nodes): `CreateProviderDto`, `create-provider.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 251`** (2 nodes): `workspace.module.ts`, `WorkspaceModule` +- **Thin community `Community 268`** (2 nodes): `GovernanceAccessModule`, `access.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 252`** (2 nodes): `RemoveWorkspaceMembersDto`, `remove-workspace-members.dto.ts` +- **Thin community `Community 269`** (2 nodes): `workspace.module.ts`, `WorkspaceModule` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 253`** (2 nodes): `RenameWorkspaceDto`, `rename-workspace.dto.ts` +- **Thin community `Community 270`** (2 nodes): `RemoveWorkspaceMembersDto`, `remove-workspace-members.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 254`** (2 nodes): `GetModelingPreviewDto`, `get-modeling-preview.dto.ts` +- **Thin community `Community 271`** (2 nodes): `RenameWorkspaceDto`, `rename-workspace.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 255`** (2 nodes): `UpdateWorkspaceMemberRoleDto`, `update-workspace-member-role.dto.ts` +- **Thin community `Community 272`** (2 nodes): `GetModelingPreviewDto`, `get-modeling-preview.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 256`** (2 nodes): `DetectModelingSchemaChangeDto`, `detect-modeling-schema-change.dto.ts` +- **Thin community `Community 273`** (2 nodes): `UpdateWorkspaceMemberRoleDto`, `update-workspace-member-role.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 257`** (2 nodes): `ListWorkspaceMembersDto`, `list-workspace-members.dto.ts` +- **Thin community `Community 274`** (2 nodes): `DetectModelingSchemaChangeDto`, `detect-modeling-schema-change.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 258`** (2 nodes): `DeployModelingGraphDto`, `deploy-modeling-graph.dto.ts` +- **Thin community `Community 275`** (2 nodes): `ListWorkspaceMembersDto`, `list-workspace-members.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 259`** (2 nodes): `AddWorkspaceMemberDto`, `add-workspace-member.dto.ts` +- **Thin community `Community 276`** (2 nodes): `DeployModelingGraphDto`, `deploy-modeling-graph.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 260`** (2 nodes): `CreateWorkspaceDto`, `create-workspace.dto.ts` +- **Thin community `Community 277`** (2 nodes): `AddWorkspaceMemberDto`, `add-workspace-member.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 261`** (2 nodes): `UserModule`, `user.module.ts` +- **Thin community `Community 278`** (2 nodes): `CreateWorkspaceDto`, `create-workspace.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 262`** (2 nodes): `BatchDeleteUsersDto`, `batch-delete-users.dto.ts` +- **Thin community `Community 279`** (2 nodes): `UserModule`, `user.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 263`** (2 nodes): `UpdateUserStatusDto`, `update-user-status.dto.ts` +- **Thin community `Community 280`** (2 nodes): `BatchDeleteUsersDto`, `batch-delete-users.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 264`** (2 nodes): `UpdateUserDto`, `update-user.dto.ts` +- **Thin community `Community 281`** (2 nodes): `UpdateUserStatusDto`, `update-user-status.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 265`** (2 nodes): `UserVariableDto`, `user-variable.dto.ts` +- **Thin community `Community 282`** (2 nodes): `UpdateUserDto`, `update-user.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 266`** (2 nodes): `CreateUserDto`, `create-user.dto.ts` +- **Thin community `Community 283`** (2 nodes): `UserVariableDto`, `user-variable.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 267`** (2 nodes): `EvalModule`, `eval.module.ts` +- **Thin community `Community 284`** (2 nodes): `CreateUserDto`, `create-user.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 268`** (2 nodes): `RunEvaluationDto`, `run-evaluation.dto.ts` +- **Thin community `Community 285`** (2 nodes): `EvalModule`, `eval.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 269`** (2 nodes): `ConversationModule`, `conversation.module.ts` +- **Thin community `Community 286`** (2 nodes): `RunEvaluationDto`, `run-evaluation.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 270`** (2 nodes): `SaveViewFromRunDto`, `save-view-from-run.dto.ts` +- **Thin community `Community 287`** (2 nodes): `ConversationModule`, `conversation.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 271`** (2 nodes): `AgentModule`, `agent.module.ts` +- **Thin community `Community 288`** (2 nodes): `ChatModule`, `chat.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 272`** (1 nodes): `semantic-spine.ts` +- **Thin community `Community 289`** (2 nodes): `SendMessageDto`, `send-message.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 273`** (1 nodes): `modeling.ts` +- **Thin community `Community 290`** (2 nodes): `ListSessionsDto`, `list-sessions.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 274`** (1 nodes): `api.d.ts` +- **Thin community `Community 291`** (2 nodes): `CreateSessionDto`, `create-session.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 275`** (1 nodes): `api.ts` +- **Thin community `Community 292`** (2 nodes): `RenameSessionDto`, `rename-session.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 276`** (1 nodes): `index.ts` +- **Thin community `Community 293`** (2 nodes): `SaveViewFromRunDto`, `save-view-from-run.dto.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 277`** (1 nodes): `index.d.ts` +- **Thin community `Community 294`** (2 nodes): `Text2SqlModule`, `text2sql.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 278`** (1 nodes): `api.contract.spec.ts` +- **Thin community `Community 295`** (2 nodes): `AgentModule`, `agent.module.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 279`** (1 nodes): `next-env.d.ts` +- **Thin community `Community 296`** (1 nodes): `semantic-spine.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 280`** (1 nodes): `vitest.config.ts` +- **Thin community `Community 297`** (1 nodes): `modeling.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 281`** (1 nodes): `assistant-thinking-panel.spec.tsx` +- **Thin community `Community 298`** (1 nodes): `api.d.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 282`** (1 nodes): `session-sidebar.spec.tsx` +- **Thin community `Community 299`** (1 nodes): `api.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 283`** (1 nodes): `run-visibility-mapper.spec.ts` +- **Thin community `Community 300`** (1 nodes): `index.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 284`** (1 nodes): `chat-rag-sync-stream-consistency.spec.tsx` +- **Thin community `Community 301`** (1 nodes): `index.d.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 285`** (1 nodes): `settings-modeling-page-context.spec.tsx` +- **Thin community `Community 302`** (1 nodes): `api.contract.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 286`** (1 nodes): `settings-relationship-publish-gate.spec.tsx` +- **Thin community `Community 303`** (1 nodes): `next-env.d.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 287`** (1 nodes): `settings-users-management.spec.tsx` +- **Thin community `Community 304`** (1 nodes): `vitest.config.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 288`** (1 nodes): `settings-modeling-model-drawer.spec.tsx` +- **Thin community `Community 305`** (1 nodes): `assistant-thinking-panel.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 289`** (1 nodes): `admin-api-client-modeling-contract.spec.ts` +- **Thin community `Community 306`** (1 nodes): `session-sidebar.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 290`** (1 nodes): `settings-modeling-deploy-panel.spec.tsx` +- **Thin community `Community 307`** (1 nodes): `run-visibility-mapper.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 291`** (1 nodes): `settings-modeling-schema-change-panel.spec.tsx` +- **Thin community `Community 308`** (1 nodes): `chat-rag-sync-stream-consistency.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 292`** (1 nodes): `settings-modeling-sidebar-tree.spec.tsx` +- **Thin community `Community 309`** (1 nodes): `settings-modeling-page-context.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 293`** (1 nodes): `settings-modeling-deploy.spec.tsx` +- **Thin community `Community 310`** (1 nodes): `settings-relationship-publish-gate.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 294`** (1 nodes): `settings-workspace-management.spec.tsx` +- **Thin community `Community 311`** (1 nodes): `settings-users-management.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 295`** (1 nodes): `chat-context-envelope-input.spec.tsx` +- **Thin community `Community 312`** (1 nodes): `settings-modeling-model-drawer.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 296`** (1 nodes): `chat-sql-preview.integration.spec.tsx` +- **Thin community `Community 313`** (1 nodes): `admin-api-client-modeling-contract.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 297`** (1 nodes): `settings-workspace-datasource-table-permissions.spec.tsx` +- **Thin community `Community 314`** (1 nodes): `settings-modeling-deploy-panel.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 298`** (1 nodes): `settings-modeling-view-sync.spec.tsx` +- **Thin community `Community 315`** (1 nodes): `settings-modeling-schema-change-panel.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 299`** (1 nodes): `settings-retired-governance-management.spec.tsx` +- **Thin community `Community 316`** (1 nodes): `settings-modeling-sidebar-tree.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 300`** (1 nodes): `sql-preview.spec.tsx` +- **Thin community `Community 317`** (1 nodes): `settings-modeling-deploy.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 301`** (1 nodes): `settings-relationship-modeling-canvas.spec.tsx` +- **Thin community `Community 318`** (1 nodes): `settings-workspace-management.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 302`** (1 nodes): `settings-modeling-schema-change.spec.tsx` +- **Thin community `Community 319`** (1 nodes): `chat-context-envelope-input.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 303`** (1 nodes): `app-shell.spec.tsx` +- **Thin community `Community 320`** (1 nodes): `chat-sql-preview.integration.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 304`** (1 nodes): `settings-workspace-table-permission-entry.spec.tsx` +- **Thin community `Community 321`** (1 nodes): `settings-workspace-datasource-table-permissions.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 305`** (1 nodes): `settings-modeling-calculated-field-editor.spec.tsx` +- **Thin community `Community 322`** (1 nodes): `rag-provider-card-grid.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 306`** (1 nodes): `settings-modeling-complete-parity.spec.tsx` +- **Thin community `Community 323`** (1 nodes): `rag-rerank-config-panel.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 307`** (1 nodes): `chatbi-result-panel.spec.tsx` +- **Thin community `Community 324`** (1 nodes): `settings-modeling-view-sync.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 308`** (1 nodes): `chat-save-as-view.spec.tsx` +- **Thin community `Community 325`** (1 nodes): `settings-retired-governance-management.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 309`** (1 nodes): `rag-foundation-status-card.spec.tsx` +- **Thin community `Community 326`** (1 nodes): `sql-preview.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 310`** (1 nodes): `settings-modeling-metadata-editor.spec.tsx` +- **Thin community `Community 327`** (1 nodes): `settings-relationship-modeling-canvas.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 311`** (1 nodes): `settings-modeling-flow-node-edge.spec.tsx` +- **Thin community `Community 328`** (1 nodes): `settings-modeling-schema-change.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 312`** (1 nodes): `chat-demo-flow.spec.tsx` +- **Thin community `Community 329`** (1 nodes): `app-shell.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 313`** (1 nodes): `chat-mobile-smoke.spec.tsx` +- **Thin community `Community 330`** (1 nodes): `settings-workspace-table-permission-entry.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 314`** (1 nodes): `platform-pages-smoke.spec.tsx` +- **Thin community `Community 331`** (1 nodes): `settings-modeling-calculated-field-editor.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 315`** (1 nodes): `page.tsx` +- **Thin community `Community 332`** (1 nodes): `rag-embedding-config-panel.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 316`** (1 nodes): `sql-preview.tsx` +- **Thin community `Community 333`** (1 nodes): `settings-modeling-complete-parity.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 317`** (1 nodes): `steps.tsx` +- **Thin community `Community 334`** (1 nodes): `chatbi-result-panel.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 318`** (1 nodes): `slider.tsx` +- **Thin community `Community 335`** (1 nodes): `chat-save-as-view.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 319`** (1 nodes): `progress.tsx` +- **Thin community `Community 336`** (1 nodes): `rag-foundation-status-card.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 320`** (1 nodes): `sonner.tsx` +- **Thin community `Community 337`** (1 nodes): `settings-modeling-metadata-editor.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 321`** (1 nodes): `button.tsx` +- **Thin community `Community 338`** (1 nodes): `settings-modeling-flow-node-edge.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 322`** (1 nodes): `toggle.tsx` +- **Thin community `Community 339`** (1 nodes): `chat-demo-flow.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 323`** (1 nodes): `workspace-datasource-table-permissions-dialog.tsx` +- **Thin community `Community 340`** (1 nodes): `chat-mobile-smoke.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 324`** (1 nodes): `relationship-publish-panel.tsx` +- **Thin community `Community 341`** (1 nodes): `platform-pages-smoke.spec.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 325`** (1 nodes): `modeling-flow-toolbar.tsx` +- **Thin community `Community 342`** (1 nodes): `page.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 326`** (1 nodes): `modeling-schema-change-panel.tsx` +- **Thin community `Community 343`** (1 nodes): `sql-preview.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 327`** (1 nodes): `elk-layout.types.ts` +- **Thin community `Community 344`** (1 nodes): `steps.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 328`** (1 nodes): `message-list.tsx` +- **Thin community `Community 345`** (1 nodes): `slider.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 329`** (1 nodes): `assistant-composer.tsx` +- **Thin community `Community 346`** (1 nodes): `progress.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 330`** (1 nodes): `workspace-selector-inline.tsx` +- **Thin community `Community 347`** (1 nodes): `sonner.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 331`** (1 nodes): `jest.config.ts` +- **Thin community `Community 348`** (1 nodes): `button.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 332`** (1 nodes): `jest.setup.ts` +- **Thin community `Community 349`** (1 nodes): `toggle.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 333`** (1 nodes): `chartbi-artifact.service.spec.ts` +- **Thin community `Community 350`** (1 nodes): `workspace-datasource-table-permissions-dialog.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 334`** (1 nodes): `sandbox-policy.spec.ts` +- **Thin community `Community 351`** (1 nodes): `relationship-publish-panel.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 335`** (1 nodes): `sql-table-access-guard.spec.ts` +- **Thin community `Community 352`** (1 nodes): `modeling-flow-toolbar.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 336`** (1 nodes): `redis-buffer.service.spec.ts` +- **Thin community `Community 353`** (1 nodes): `modeling-schema-change-panel.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 337`** (1 nodes): `llm-gateway.service.spec.ts` +- **Thin community `Community 354`** (1 nodes): `elk-layout.types.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 338`** (1 nodes): `chat.service.spec.ts` +- **Thin community `Community 355`** (1 nodes): `message-list.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 339`** (1 nodes): `openai-compatible.client.spec.ts` +- **Thin community `Community 356`** (1 nodes): `assistant-composer.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 340`** (1 nodes): `chartbi-intent-parser.spec.ts` +- **Thin community `Community 357`** (1 nodes): `workspace-selector-inline.tsx` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 341`** (1 nodes): `slot-filling-context.spec.ts` +- **Thin community `Community 358`** (1 nodes): `jest.config.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 342`** (1 nodes): `sql-prompt.builder.spec.ts` +- **Thin community `Community 359`** (1 nodes): `jest.setup.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 343`** (1 nodes): `resolve-saved-prior-sql.node.spec.ts` +- **Thin community `Community 360`** (1 nodes): `chartbi-artifact.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 344`** (1 nodes): `tool-execution-guard.spec.ts` +- **Thin community `Community 361`** (1 nodes): `retrieve-knowledge.node.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 345`** (1 nodes): `clarify.node.spec.ts` +- **Thin community `Community 362`** (1 nodes): `chat-delivery-enrichment.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 346`** (1 nodes): `planner-version-lock.service.spec.ts` +- **Thin community `Community 363`** (1 nodes): `sandbox-policy.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 347`** (1 nodes): `planner-cache.service.spec.ts` +- **Thin community `Community 364`** (1 nodes): `sql-table-access-guard.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 348`** (1 nodes): `tool-events.mapper.spec.ts` +- **Thin community `Community 365`** (1 nodes): `redis-buffer.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 349`** (1 nodes): `tool-registry.service.spec.ts` +- **Thin community `Community 366`** (1 nodes): `llm-gateway.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 350`** (1 nodes): `chartbi-validator.spec.ts` +- **Thin community `Community 367`** (1 nodes): `text2sql-v2-langgraph-runtime.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 351`** (1 nodes): `semantic-spine-context-pack.mapper.spec.ts` +- **Thin community `Community 368`** (1 nodes): `chat.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 352`** (1 nodes): `llm-model-factory.spec.ts` +- **Thin community `Community 369`** (1 nodes): `text2sql-v2-langgraph-nodes.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 353`** (1 nodes): `rag-event-consumer.spec.ts` +- **Thin community `Community 370`** (1 nodes): `openai-compatible.client.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 354`** (1 nodes): `bootstrap.spec.ts` +- **Thin community `Community 371`** (1 nodes): `chartbi-intent-parser.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 355`** (1 nodes): `skill-registry.service.spec.ts` +- **Thin community `Community 372`** (1 nodes): `slot-filling-context.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 356`** (1 nodes): `rrf-fusion.spec.ts` +- **Thin community `Community 373`** (1 nodes): `sql-prompt.builder.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 357`** (1 nodes): `sql-output-extractor.spec.ts` +- **Thin community `Community 374`** (1 nodes): `resolve-saved-prior-sql.node.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 358`** (1 nodes): `safety-check.node.spec.ts` +- **Thin community `Community 375`** (1 nodes): `tool-execution-guard.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 359`** (1 nodes): `knowledge-facade-contract.spec.ts` +- **Thin community `Community 376`** (1 nodes): `clarify.node.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 360`** (1 nodes): `chat-langsmith-trace.spec.ts` +- **Thin community `Community 377`** (1 nodes): `text2sql-v2-semantic-context-pack.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 361`** (1 nodes): `audit-log.repository.spec.ts` +- **Thin community `Community 378`** (1 nodes): `planner-version-lock.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 362`** (1 nodes): `rag-foundation-replay.spec.ts` +- **Thin community `Community 379`** (1 nodes): `planner-cache.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 363`** (1 nodes): `rag-retrieval.service.spec.ts` +- **Thin community `Community 380`** (1 nodes): `text2sql-stream-event.mapper.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 364`** (1 nodes): `user-workspace-repository.spec.ts` +- **Thin community `Community 381`** (1 nodes): `tool-events.mapper.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 365`** (1 nodes): `rag-foundation-observability.spec.ts` +- **Thin community `Community 382`** (1 nodes): `tool-registry.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 366`** (1 nodes): `rag-incremental-refresh.spec.ts` +- **Thin community `Community 383`** (1 nodes): `text2sql-stage-contract.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 367`** (1 nodes): `graph-acceleration-fallback.spec.ts` +- **Thin community `Community 384`** (1 nodes): `chartbi-validator.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 368`** (1 nodes): `agent-rag-main-flow.spec.ts` +- **Thin community `Community 385`** (1 nodes): `semantic-spine-context-pack.mapper.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 369`** (1 nodes): `data-flow.spec.ts` +- **Thin community `Community 386`** (1 nodes): `llm-model-factory.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 370`** (1 nodes): `rule-group-schema.spec.ts` +- **Thin community `Community 387`** (1 nodes): `rag-event-consumer.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 371`** (1 nodes): `workspace-modeling-deploy.spec.ts` +- **Thin community `Community 388`** (1 nodes): `bootstrap.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 372`** (1 nodes): `session-repository.spec.ts` +- **Thin community `Community 389`** (1 nodes): `skill-registry.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 373`** (1 nodes): `trace-lineage.spec.ts` +- **Thin community `Community 390`** (1 nodes): `rrf-fusion.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 374`** (1 nodes): `rag-rerank.integration.spec.ts` +- **Thin community `Community 391`** (1 nodes): `sql-output-extractor.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 375`** (1 nodes): `relationship-impact-simulation.spec.ts` +- **Thin community `Community 392`** (1 nodes): `safety-check.node.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 376`** (1 nodes): `rag-multi-datasource-orchestrator.spec.ts` +- **Thin community `Community 393`** (1 nodes): `text2sql-v2-semantic-plan.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 377`** (1 nodes): `rag-run-replay.spec.ts` +- **Thin community `Community 394`** (1 nodes): `knowledge-facade-contract.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 378`** (1 nodes): `workspace-modeling-schema-change.spec.ts` +- **Thin community `Community 395`** (1 nodes): `chat-langsmith-trace.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 379`** (1 nodes): `skill-registry-rag.spec.ts` +- **Thin community `Community 396`** (1 nodes): `text2sql-v2-closeout-flow.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 380`** (1 nodes): `semantic-registry.spec.ts` +- **Thin community `Community 397`** (1 nodes): `audit-log.repository.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 381`** (1 nodes): `chat-run-template-trace.spec.ts` +- **Thin community `Community 398`** (1 nodes): `rag-foundation-replay.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 382`** (1 nodes): `workspace-datasource-table-permissions-schema.spec.ts` +- **Thin community `Community 399`** (1 nodes): `rag-retrieval.service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 383`** (1 nodes): `policy-evaluator.spec.ts` +- **Thin community `Community 400`** (1 nodes): `user-workspace-repository.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 384`** (1 nodes): `rag-cache-version-invalidation.spec.ts` +- **Thin community `Community 401`** (1 nodes): `rag-foundation-observability.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 385`** (1 nodes): `rag-index-builder.spec.ts` +- **Thin community `Community 402`** (1 nodes): `rag-incremental-refresh.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 386`** (1 nodes): `prisma-graph-baseline.spec.ts` +- **Thin community `Community 403`** (1 nodes): `graph-acceleration-fallback.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 387`** (1 nodes): `agent-rag-degrade-flow.spec.ts` +- **Thin community `Community 404`** (1 nodes): `agent-rag-main-flow.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 388`** (1 nodes): `langsmith-coverage.spec.ts` +- **Thin community `Community 405`** (1 nodes): `text2sql-v2-characterization-gate.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 389`** (1 nodes): `session-management.spec.ts` +- **Thin community `Community 406`** (1 nodes): `data-flow.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 390`** (1 nodes): `planner-cache-replay.spec.ts` +- **Thin community `Community 407`** (1 nodes): `rule-group-schema.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 391`** (1 nodes): `planner-version-lock.spec.ts` +- **Thin community `Community 408`** (1 nodes): `workspace-modeling-deploy.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 392`** (1 nodes): `agent-context-pack.spec.ts` +- **Thin community `Community 409`** (1 nodes): `session-repository.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 393`** (1 nodes): `graph-acceleration-circuit-breaker.spec.ts` +- **Thin community `Community 410`** (1 nodes): `trace-lineage.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 394`** (1 nodes): `agent-sql-prompt-template-runtime.spec.ts` +- **Thin community `Community 411`** (1 nodes): `rag-rerank.integration.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 395`** (1 nodes): `agent-main-flow.spec.ts` +- **Thin community `Community 412`** (1 nodes): `relationship-impact-simulation.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 396`** (1 nodes): `datasource-repository.spec.ts` +- **Thin community `Community 413`** (1 nodes): `rag-multi-datasource-orchestrator.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 397`** (1 nodes): `rag-performance-budget.spec.ts` +- **Thin community `Community 414`** (1 nodes): `text2sql-semantic-asset-reindex.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 398`** (1 nodes): `agent-relationship-correction-loop.spec.ts` +- **Thin community `Community 415`** (1 nodes): `rag-run-replay.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 399`** (1 nodes): `chat-context-envelope-accuracy.spec.ts` +- **Thin community `Community 416`** (1 nodes): `workspace-modeling-schema-change.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 400`** (1 nodes): `rag-index-activation.spec.ts` +- **Thin community `Community 417`** (1 nodes): `skill-registry-rag.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 401`** (1 nodes): `datasource-access-policy.spec.ts` +- **Thin community `Community 418`** (1 nodes): `semantic-registry.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 402`** (1 nodes): `eval-langsmith-trace.spec.ts` +- **Thin community `Community 419`** (1 nodes): `chat-run-template-trace.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 403`** (1 nodes): `rag-quality.spec.ts` +- **Thin community `Community 420`** (1 nodes): `workspace-datasource-table-permissions-schema.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 404`** (1 nodes): `eval-report.spec.ts` +- **Thin community `Community 421`** (1 nodes): `policy-evaluator.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 405`** (1 nodes): `semantic-spine-shadow-gate.spec.ts` +- **Thin community `Community 422`** (1 nodes): `rag-cache-version-invalidation.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 406`** (1 nodes): `agent-saved-prior-sql-shortcut.spec.ts` +- **Thin community `Community 423`** (1 nodes): `rag-index-builder.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 407`** (1 nodes): `chat-persistence-retry.spec.ts` +- **Thin community `Community 424`** (1 nodes): `prisma-graph-baseline.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 408`** (1 nodes): `saved-prior-sql-ingestion.spec.ts` +- **Thin community `Community 425`** (1 nodes): `agent-rag-degrade-flow.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 409`** (1 nodes): `r3-gate-rehearsal.spec.ts` +- **Thin community `Community 426`** (1 nodes): `langsmith-coverage.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 410`** (1 nodes): `r3-semantic-registry-migration.spec.ts` +- **Thin community `Community 427`** (1 nodes): `session-management.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 411`** (1 nodes): `workspace-service.spec.ts` +- **Thin community `Community 428`** (1 nodes): `text2sql-v2-eval-gate.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 412`** (1 nodes): `rag-document-factory.spec.ts` +- **Thin community `Community 429`** (1 nodes): `planner-cache-replay.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 413`** (1 nodes): `r6-gate-readiness.spec.ts` +- **Thin community `Community 430`** (1 nodes): `planner-version-lock.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 414`** (1 nodes): `user-service.spec.ts` +- **Thin community `Community 431`** (1 nodes): `agent-context-pack.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 415`** (1 nodes): `provider-fallback.spec.ts` +- **Thin community `Community 432`** (1 nodes): `graph-acceleration-circuit-breaker.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 416`** (1 nodes): `saved-prior-sql-quality.spec.ts` +- **Thin community `Community 433`** (1 nodes): `agent-sql-prompt-template-runtime.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 417`** (1 nodes): `workspace-api.spec.ts` +- **Thin community `Community 434`** (1 nodes): `agent-main-flow.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 418`** (1 nodes): `r6-release-rollback-rehearsal.e2e-spec.ts` +- **Thin community `Community 435`** (1 nodes): `datasource-repository.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 419`** (1 nodes): `datasource-visibility-api.spec.ts` +- **Thin community `Community 436`** (1 nodes): `rag-performance-budget.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 420`** (1 nodes): `workspace-datasource-api.spec.ts` +- **Thin community `Community 437`** (1 nodes): `chat-context-envelope-accuracy.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 421`** (1 nodes): `graph-acceleration-chaos.e2e-spec.ts` +- **Thin community `Community 438`** (1 nodes): `rag-index-activation.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 422`** (1 nodes): `clarification-hybrid-balance.acceptance.spec.ts` +- **Thin community `Community 439`** (1 nodes): `datasource-access-policy.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 423`** (1 nodes): `datasource-workflow-api.spec.ts` +- **Thin community `Community 440`** (1 nodes): `eval-langsmith-trace.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 424`** (1 nodes): `rag-multi-datasource-isolation.spec.ts` +- **Thin community `Community 441`** (1 nodes): `rag-quality.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 425`** (1 nodes): `settings-api.spec.ts` +- **Thin community `Community 442`** (1 nodes): `eval-report.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 426`** (1 nodes): `workspace-datasource-audit.spec.ts` +- **Thin community `Community 443`** (1 nodes): `semantic-spine-shadow-gate.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 427`** (1 nodes): `chat-api.spec.ts` +- **Thin community `Community 444`** (1 nodes): `chat-persistence-retry.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 428`** (1 nodes): `rule-group-api.spec.ts` +- **Thin community `Community 445`** (1 nodes): `saved-prior-sql-ingestion.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 429`** (1 nodes): `chat-table-permissions-policy.spec.ts` +- **Thin community `Community 446`** (1 nodes): `r3-gate-rehearsal.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 430`** (1 nodes): `rag-r6-mixed-load.spec.ts` +- **Thin community `Community 447`** (1 nodes): `r3-semantic-registry-migration.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 431`** (1 nodes): `rag-cache-budget-load.spec.ts` +- **Thin community `Community 448`** (1 nodes): `workspace-service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 432`** (1 nodes): `browser.ts` +- **Thin community `Community 449`** (1 nodes): `rag-document-factory.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 433`** (1 nodes): `client.ts` +- **Thin community `Community 450`** (1 nodes): `r6-gate-readiness.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 434`** (1 nodes): `models.ts` +- **Thin community `Community 451`** (1 nodes): `user-service.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 435`** (1 nodes): `commonInputTypes.ts` +- **Thin community `Community 452`** (1 nodes): `provider-fallback.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 436`** (1 nodes): `enums.ts` +- **Thin community `Community 453`** (1 nodes): `saved-prior-sql-quality.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 437`** (1 nodes): `prismaNamespace.ts` +- **Thin community `Community 454`** (1 nodes): `workspace-api.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 438`** (1 nodes): `prismaNamespaceBrowser.ts` +- **Thin community `Community 455`** (1 nodes): `r6-release-rollback-rehearsal.e2e-spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 439`** (1 nodes): `WorkspaceDatasourceTablePermission.ts` +- **Thin community `Community 456`** (1 nodes): `datasource-visibility-api.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 440`** (1 nodes): `WorkspaceDatasourceTablePermissionSet.ts` +- **Thin community `Community 457`** (1 nodes): `workspace-datasource-api.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 441`** (1 nodes): `ModelCatalog.ts` +- **Thin community `Community 458`** (1 nodes): `graph-acceleration-chaos.e2e-spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 442`** (1 nodes): `RagDocument.ts` +- **Thin community `Community 459`** (1 nodes): `clarification-hybrid-balance.acceptance.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 443`** (1 nodes): `WorkspaceDatasourceBinding.ts` +- **Thin community `Community 460`** (1 nodes): `datasource-workflow-api.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 444`** (1 nodes): `AgentAuditLog.ts` +- **Thin community `Community 461`** (1 nodes): `rag-multi-datasource-isolation.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 445`** (1 nodes): `SqlRun.ts` +- **Thin community `Community 462`** (1 nodes): `settings-api.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 446`** (1 nodes): `Workspace.ts` +- **Thin community `Community 463`** (1 nodes): `workspace-datasource-audit.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 447`** (1 nodes): `WorkspaceMember.ts` +- **Thin community `Community 464`** (1 nodes): `chat-api.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 448`** (1 nodes): `RagChunkIndexEntry.ts` +- **Thin community `Community 465`** (1 nodes): `rule-group-api.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 449`** (1 nodes): `SemanticEdge.ts` +- **Thin community `Community 466`** (1 nodes): `chat-table-permissions-policy.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 450`** (1 nodes): `GraphSnapshot.ts` +- **Thin community `Community 467`** (1 nodes): `rag-r6-mixed-load.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 451`** (1 nodes): `RagIndexVersion.ts` +- **Thin community `Community 468`** (1 nodes): `rag-cache-budget-load.spec.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 452`** (1 nodes): `GlossaryTerm.ts` +- **Thin community `Community 469`** (1 nodes): `browser.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 453`** (1 nodes): `SemanticMemory.ts` +- **Thin community `Community 470`** (1 nodes): `client.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 454`** (1 nodes): `Datasource.ts` +- **Thin community `Community 471`** (1 nodes): `models.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 455`** (1 nodes): `ProviderConfig.ts` +- **Thin community `Community 472`** (1 nodes): `commonInputTypes.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 456`** (1 nodes): `WorkspaceModelingGraphRevision.ts` +- **Thin community `Community 473`** (1 nodes): `enums.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 457`** (1 nodes): `SemanticSpineSnapshot.ts` +- **Thin community `Community 474`** (1 nodes): `prismaNamespace.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 458`** (1 nodes): `Message.ts` +- **Thin community `Community 475`** (1 nodes): `prismaNamespaceBrowser.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 459`** (1 nodes): `Session.ts` +- **Thin community `Community 476`** (1 nodes): `WorkspaceDatasourceTablePermission.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 460`** (1 nodes): `RagChunk.ts` +- **Thin community `Community 477`** (1 nodes): `WorkspaceDatasourceTablePermissionSet.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 461`** (1 nodes): `SemanticRegistryTerm.ts` +- **Thin community `Community 478`** (1 nodes): `ModelCatalog.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 462`** (1 nodes): `GlossaryAnchor.ts` +- **Thin community `Community 479`** (1 nodes): `RagDocument.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 463`** (1 nodes): `PlatformUser.ts` +- **Thin community `Community 480`** (1 nodes): `WorkspaceDatasourceBinding.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 464`** (1 nodes): `SemanticRegistryVersion.ts` +- **Thin community `Community 481`** (1 nodes): `AgentAuditLog.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 465`** (1 nodes): `RagRunReplay.ts` +- **Thin community `Community 482`** (1 nodes): `SqlRun.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 466`** (1 nodes): `EvaluationReport.ts` +- **Thin community `Community 483`** (1 nodes): `Workspace.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 467`** (1 nodes): `PromptTemplate.ts` +- **Thin community `Community 484`** (1 nodes): `WorkspaceMember.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 468`** (1 nodes): `express.d.ts` +- **Thin community `Community 485`** (1 nodes): `RagChunkIndexEntry.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 469`** (1 nodes): `llm-gateway.interface.ts` +- **Thin community `Community 486`** (1 nodes): `SemanticEdge.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 470`** (1 nodes): `provider-capabilities.ts` +- **Thin community `Community 487`** (1 nodes): `GraphSnapshot.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 471`** (1 nodes): `provider-adapter.interface.ts` +- **Thin community `Community 488`** (1 nodes): `RagIndexVersion.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 472`** (1 nodes): `index.ts` +- **Thin community `Community 489`** (1 nodes): `GlossaryTerm.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 473`** (1 nodes): `index.ts` +- **Thin community `Community 490`** (1 nodes): `SemanticMemory.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 474`** (1 nodes): `modeling-graph.types.ts` +- **Thin community `Community 491`** (1 nodes): `Datasource.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 475`** (1 nodes): `index.ts` +- **Thin community `Community 492`** (1 nodes): `ProviderConfig.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 476`** (1 nodes): `langsmith.types.ts` +- **Thin community `Community 493`** (1 nodes): `WorkspaceModelingGraphRevision.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 477`** (1 nodes): `rag-retrieval.types.ts` +- **Thin community `Community 494`** (1 nodes): `SemanticSpineSnapshot.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 478`** (1 nodes): `knowledge-rag.contract.ts` +- **Thin community `Community 495`** (1 nodes): `Message.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 479`** (1 nodes): `knowledge-memory.contract.ts` +- **Thin community `Community 496`** (1 nodes): `Session.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 480`** (1 nodes): `knowledge-facade.contract.ts` +- **Thin community `Community 497`** (1 nodes): `RagChunk.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 481`** (1 nodes): `knowledge-semantic-registry.contract.ts` +- **Thin community `Community 498`** (1 nodes): `SemanticRegistryTerm.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 482`** (1 nodes): `knowledge-glossary.contract.ts` +- **Thin community `Community 499`** (1 nodes): `GlossaryAnchor.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 483`** (1 nodes): `rag-retrieval.types.ts` +- **Thin community `Community 500`** (1 nodes): `PlatformUser.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 484`** (1 nodes): `modeling-graph.validator.ts` +- **Thin community `Community 501`** (1 nodes): `RagTaskConfig.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 485`** (1 nodes): `modeling-graph.types.ts` +- **Thin community `Community 502`** (1 nodes): `SemanticRegistryVersion.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 486`** (1 nodes): `semantic-spine.types.ts` +- **Thin community `Community 503`** (1 nodes): `RagRunReplay.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 487`** (1 nodes): `index.ts` +- **Thin community `Community 504`** (1 nodes): `EvaluationReport.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 488`** (1 nodes): `query-executor.interface.ts` +- **Thin community `Community 505`** (1 nodes): `PromptTemplate.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. -- **Thin community `Community 489`** (1 nodes): `agent.types.ts` +- **Thin community `Community 506`** (1 nodes): `express.d.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 507`** (1 nodes): `knowledge.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 508`** (1 nodes): `embedding-gateway.interface.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 509`** (1 nodes): `llm-gateway.interface.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 510`** (1 nodes): `provider-capabilities.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 511`** (1 nodes): `provider-adapter.interface.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 512`** (1 nodes): `index.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 513`** (1 nodes): `index.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 514`** (1 nodes): `modeling-graph.types.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 515`** (1 nodes): `index.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 516`** (1 nodes): `langsmith.types.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 517`** (1 nodes): `rag-retrieval.types.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 518`** (1 nodes): `knowledge-rag.contract.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 519`** (1 nodes): `knowledge-memory.contract.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 520`** (1 nodes): `knowledge-facade.contract.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 521`** (1 nodes): `knowledge-semantic-registry.contract.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 522`** (1 nodes): `knowledge-glossary.contract.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 523`** (1 nodes): `rag-retrieval.types.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 524`** (1 nodes): `modeling-graph.validator.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 525`** (1 nodes): `modeling-graph.types.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 526`** (1 nodes): `semantic-spine.types.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 527`** (1 nodes): `index.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 528`** (1 nodes): `query-executor.interface.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 529`** (1 nodes): `text2sql-v2.types.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 530`** (1 nodes): `text2sql-smart-defaults.bundle.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 531`** (1 nodes): `text2sql-workflow-runner.service.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 532`** (1 nodes): `run-v2-langgraph.stage.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 533`** (1 nodes): `text2sql-stage-name.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 534`** (1 nodes): `text2sql-stage.interface.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 535`** (1 nodes): `text2sql-stage-result.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 536`** (1 nodes): `text2sql-run-context.ts` + Too small to be a meaningful cluster - may be noise or needs more connections extracted. +- **Thin community `Community 537`** (1 nodes): `run-view-support.guard.ts` Too small to be a meaningful cluster - may be noise or needs more connections extracted. ## Suggested Questions _Questions this graph is uniquely positioned to answer:_ -- **Why does `ok()` connect `Community 3` to `Community 0`, `Community 1`, `Community 21`, `Community 17`?** - _High betweenness centrality (0.032) - this node is a cross-community bridge._ -- **Why does `setError()` connect `Community 9` to `Community 28`, `Community 4`, `Community 31`?** - _High betweenness centrality (0.021) - this node is a cross-community bridge._ -- **Why does `WorkspaceModelingService` connect `Community 0` to `Community 5`?** - _High betweenness centrality (0.021) - this node is a cross-community bridge._ -- **Are the 85 inferred relationships involving `ok()` (e.g. with `.applyFeedback()` and `.createSession()`) actually correct?** - _`ok()` has 85 INFERRED edges - model-reasoned connections that need verification._ +- **Why does `ok()` connect `Community 5` to `Community 24`, `Community 1`, `Community 6`, `Community 15`?** + _High betweenness centrality (0.028) - this node is a cross-community bridge._ +- **Why does `collectClarificationBalanceGate()` connect `Community 34` to `Community 1`, `Community 2`, `Community 4`, `Community 8`, `Community 26`?** + _High betweenness centrality (0.013) - this node is a cross-community bridge._ +- **Are the 89 inferred relationships involving `ok()` (e.g. with `.applyFeedback()` and `.report()`) actually correct?** + _`ok()` has 89 INFERRED edges - model-reasoned connections that need verification._ - **What connects `ELK`, `ElkLayoutTimeoutError`, `AppModule` to the rest of the system?** - _80 weakly-connected nodes found - possible documentation gaps or missing edges._ + _93 weakly-connected nodes found - possible documentation gaps or missing edges._ - **Should `Community 0` be split into smaller, more focused modules?** _Cohesion score 0.02 - nodes in this community are weakly interconnected._ - **Should `Community 1` be split into smaller, more focused modules?** - _Cohesion score 0.02 - nodes in this community are weakly interconnected._ \ No newline at end of file + _Cohesion score 0.02 - nodes in this community are weakly interconnected._ +- **Should `Community 2` be split into smaller, more focused modules?** + _Cohesion score 0.03 - nodes in this community are weakly interconnected._ \ No newline at end of file diff --git a/graphify-out/graph.html b/graphify-out/graph.html index ab21d4a..df5f783 100644 --- a/graphify-out/graph.html +++ b/graphify-out/graph.html @@ -50,12 +50,12 @@

Node Info

Communities

-
3640 nodes · 7065 edges · 490 communities
+
4314 nodes · 8504 edges · 538 communities