From b957be509b218b0a3db4927f42f9add6fde2717c Mon Sep 17 00:00:00 2001 From: luoshuai990529 <58510855+luoshuai990529@users.noreply.github.com> Date: Sun, 25 Oct 2026 01:04:35 +0800 Subject: [PATCH 1/5] =?UTF-8?q?feat(search):=20=E6=8E=A5=E5=85=A5=20SAG2?= =?UTF-8?q?=20=E8=AF=81=E6=8D=AE=E6=A3=80=E7=B4=A2=E6=A8=A1=E5=BC=8F?= =?UTF-8?q?=EF=BC=8CJEV=20=E6=A8=A1=E5=BC=8F=E9=A1=BB=E9=85=8D=E7=BD=AE=20?= =?UTF-8?q?API=20Key?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 依赖与打包 - 新增 `zleap-sag2==0.1.0`(PyPI 正式版);中文分词由 `jieba-py` 改为 `jieba==0.42.1`,与 zleap-sag2 共用;桌面打包收集 `zleap-sag2`、`jieba` 元数据与 `pyuca` 排序词典 后端 - 新增 `sag/sag2_engine.py`:只读 zleap-sag2 引擎直接在 SAG 的 SQLite / PostgreSQL 关系库上检索(BM25 召回后由 JEV 服务多轮评分),一次请求覆盖 全部目标信源;按配置指纹惰性重建,内置并发上限、范围段落上限、整次超时 与异常翻译;引擎工作运行在专用线程的事件循环,不阻塞 API 循环 - 新增门面策略 `sag2`:保留引擎顺序与原始 JEV 分数,失败不回退 vector; 能力依赖 `jev` 与 `sag2_relational`(首期仅 SQLite / PostgreSQL) - JEV 为付费服务:`jev` 能力要求同时保存地址与 API Key(`jev_api_key_missing`), `multi_jev` 同步受约束;设置保存、Agent 人格、显式请求、连接测试均在缺 Key 时拒绝;改地址或 Key 导致连接不完整而默认策略仍为 JEV 模式时拒绝保存 - `sag2` 与 `multi_jev` 共用 JEV 错误文案与错误码;以 `JEV_SCORED_STRATEGIES` 统一各入口的 JEV 模式判断;新增 `SAG_SAG2_*` 调优参数 前端 - 检索模式列表新增 `sag2`,JEV 评分模式带付费标识;旧后端未声明支持时按 不可用处理;灰置项因缺配置或 Key 时提供「去设置」入口 - 知识库设置中 API Key 改为选择 JEV 模式时必填;检索状态栏显示 SAG2 的 本次 JEV 评分用量 文档 - README / README-CN 检索模式表新增 `sag2`,说明存储要求、PostgreSQL 辅助表 权限与付费 Key 要求;CHANGELOG Unreleased 记录 --- .env.example | 3 + CHANGELOG.md | 5 + README-CN.md | 11 +- README.md | 11 +- apps/api/.env.example | 14 + apps/api/packaging/sag-api.spec | 5 +- apps/api/pyproject.toml | 3 +- apps/api/sag_api/api/v1/dify.py | 5 +- apps/api/sag_api/api/v1/search.py | 3 +- apps/api/sag_api/core/config.py | 18 + apps/api/sag_api/enums.py | 9 +- apps/api/sag_api/mcp/server.py | 3 +- apps/api/sag_api/sag/engine_access.py | 3 + apps/api/sag_api/sag/engine_manager.py | 96 ++- apps/api/sag_api/sag/errors.py | 17 +- apps/api/sag_api/sag/jev_probe.py | 3 + apps/api/sag_api/sag/sag2_engine.py | 553 +++++++++++++++ apps/api/sag_api/sag/search_reader.py | 39 +- apps/api/sag_api/services/agent_domain.py | 10 +- apps/api/sag_api/services/agent_tooling.py | 10 + .../api/sag_api/services/retrieval_service.py | 8 +- apps/api/sag_api/services/settings_service.py | 19 +- apps/api/sag_api/tools/builtin.py | 13 +- apps/api/scripts/eval_retrieval.py | 2 +- apps/api/tests/test_agent_jev_capabilities.py | 18 +- apps/api/tests/test_agent_tools.py | 4 +- apps/api/tests/test_jev_config.py | 25 +- apps/api/tests/test_jev_error_scope.py | 2 + apps/api/tests/test_jev_retrieval.py | 10 + .../api/tests/test_sag2_engine_integration.py | 225 +++++++ apps/api/tests/test_sag2_retrieval.py | 630 ++++++++++++++++++ apps/api/uv.lock | 363 +++++----- apps/web/app/(app)/settings/page.tsx | 4 +- .../features/knowledge-config-form.test.tsx | 159 ++++- .../features/knowledge-config-form.tsx | 78 ++- .../features/retrieval-status.test.tsx | 36 +- .../components/features/retrieval-status.tsx | 36 +- .../features/search-strategy-control.test.tsx | 86 +++ .../features/search-strategy-control.tsx | 71 +- apps/web/lib/api-jev-timeouts.test.ts | 10 +- apps/web/lib/api.ts | 6 +- apps/web/lib/retrieval-config.test.ts | 50 +- apps/web/lib/retrieval-config.ts | 43 +- apps/web/messages/en-US.json | 19 +- apps/web/messages/zh-CN.json | 19 +- 45 files changed, 2427 insertions(+), 330 deletions(-) create mode 100644 apps/api/sag_api/sag/sag2_engine.py create mode 100644 apps/api/tests/test_sag2_engine_integration.py create mode 100644 apps/api/tests/test_sag2_retrieval.py create mode 100644 apps/web/components/features/search-strategy-control.test.tsx diff --git a/.env.example b/.env.example index d856d513..50b7a589 100644 --- a/.env.example +++ b/.env.example @@ -40,6 +40,9 @@ SAG_JEV_API_KEY= SAG_JEV_RANKING_TIMEOUT_SECONDS=30 # error:失败即报错;fallback_to_score:允许粗排结果并显示降级提示。 SAG_JEV_FAILURE_POLICY=error +# 可选 SAG2 证据检索(zleap-sag2,SAG_SEARCH_STRATEGY=sag2):共用上面的 JEV 连接(必须有 Key), +# 只读直搜 SQLite / PostgreSQL 关系库,不依赖向量库;失败不回退,SAG_JEV_FAILURE_POLICY 对其无效。 +# 调优参数见 apps/api/.env.example 的 SAG_SAG2_* 说明。 # 浏览器访问后端的地址(构建期内联;修改后需重建 web 镜像)。 NEXT_PUBLIC_API_BASE=http://localhost:8000 diff --git a/CHANGELOG.md b/CHANGELOG.md index 74bb0409..9e3c3a83 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,11 @@ ## Unreleased +- SAG2 只读引擎改在专用事件循环线程运行:大范围检索构建内存语料时不再阻塞 API 事件循环;整次超时会同步取消引擎侧工作。 +- 新增可选 SAG2 证据检索模式(`sag2`):接入 `zleap-sag2` 0.1.0,只读直搜 SQLite / PostgreSQL 关系库,BM25 召回后由 JEV 服务多轮评分,不依赖向量库,文档入库后即可检索;与 JEV 精排共用服务配置,失败不回退,首期不支持 MySQL / OceanBase。 +- JEV 为付费服务:选择 JEV 精排或 SAG2 证据检索前必须填写 API Key;仅保存服务地址不再足以启用模式,连接测试也要求 Key。探索页灰置项直接给出原因与设置入口,SAG2 结果显示本次评分用量。 +- 后端中文分词依赖由 `jieba-py` 改回 `jieba` 0.42.1,与 `zleap-sag2` 共用一份词典;分词结果不变。 + ## v1.9.2 · 2026-10-22 - 新增结构化输出模式设置和自动降级,兼容不支持严格结构化输出的模型;改善口语化提问的查询分析与语义结果保留(#248)。 diff --git a/README-CN.md b/README-CN.md index ca630588..ed5c662d 100644 --- a/README-CN.md +++ b/README-CN.md @@ -62,7 +62,7 @@ SAG 不是传统 RAG 与 GraphRAG 的融合,而是一套替代二者的原创 | 能力 | 解决的问题 | | --- | --- | | 知识导入 | 文件与网页信源、文档解析、分块、向量化、事件/实体抽取、后台处理 | -| 检索 | 跨信源或指定信源检索,支持快速(`vector` / `multi_es_fast`)、精确(`multi`)与可选 JEV 精排(`multi_jev`)模式 | +| 检索 | 跨信源或指定信源检索,支持快速(`vector` / `multi_es_fast`)、精确(`multi`)、可选 JEV 精排(`multi_jev`)与 SAG2 证据检索(`sag2`)模式 | | 原文溯源 | 每条检索结果和引用都能打开对应的原文块 | | 知识图谱 | 查看事件、实体及其可查询的关联关系 | | Agent 对话 | 基于指定信源进行多轮问答,并提供可点击引用 | @@ -566,12 +566,15 @@ config = EngineConfig.from_env() | 快速(multi_es-fast) | `multi_es_fast` | BM25 实体召回与事件多跳检索,跳过 LLM 精排 | | 精确 | `multi` | 结合实体关系与 LLM 精排,结果更完整 | | JEV 精排 | `multi_jev` | 召回与图扩展后,通过独立 JEV 服务为候选证据评分 | +| SAG2 证据检索 | `sag2` | 由 [zleap-sag2](https://pypi.org/project/zleap-sag2/) 只读直搜关系库:BM25 召回后用 JEV 服务多轮评分,不依赖向量库 | -这里列出的是应用/API 策略名称;应用将 `multi` 映射到 Python 引擎的 `full_expand`,将 `multi_es_fast` 映射到 `pruned_expand_rff`。可用性取决于存储能力:`multi_es_fast` 需要词法检索支持。 +这里列出的是应用/API 策略名称;应用将 `multi` 映射到 Python 引擎的 `full_expand`,将 `multi_es_fast` 映射到 `pruned_expand_rff`,`sag2` 由独立的 `zleap-sag2` 引擎执行。可用性取决于存储能力:`multi_es_fast` 与 `multi_jev` 需要词法检索支持,`sag2` 需要 SQLite 或 PostgreSQL 关系库。 -在“设置 → 知识库 → 检索”配置 302.AI、TypeSafe 官方或自定义 JEV 服务(默认 `jev-latest`,独立 API Key),再选择 **JEV 精排**。仅保存服务不会启用;默认限时 30 秒、失败报错,可选择粗排降级。 +在“设置 → 知识库 → 检索”配置 302.AI、TypeSafe 官方或自定义 JEV 服务(默认 `jev-latest`,独立 API Key),再选择 **JEV 精排** 或 **SAG2 证据检索**。JEV 是付费服务:仅保存服务不会启用,选择任一 JEV 模式前必须填写 API Key。JEV 精排默认限时 30 秒、失败报错,可选择粗排降级。 -支持 LanceDB、Elasticsearch,暂不支持 pgvector;PostgreSQL 作为关系库不受影响。未启用时沿用原检索策略,已有文档无需重新入库。效果与成本见[更新日志](CHANGELOG.md#jev-reranking)。 +**SAG2 证据检索**与 JEV 精排共用同一服务配置,但不经向量库:它直接只读 SAG 的 SQLite / PostgreSQL 关系库(首期不支持 MySQL / OceanBase),文档分块入库后即可检索,不要求事件抽取完成,pgvector 单库部署也可使用。每次检索会扫描所选信源的全部段落并多轮调用 JEV,用量高于 JEV 精排;失败直接报错,不支持粗排降级。候选数、超时、并发与范围上限等调优参数见 `apps/api/.env.example` 的 `SAG_SAG2_*`。使用 PostgreSQL 时,连接用户需能在目标 schema 创建并读写 `sag2_state`、`sag2_search_sessions` 两张辅助表,并对 `sag2_state` 执行 `LOCK TABLE`;SAG 的业务表保持只读。 + +JEV 精排支持 LanceDB、Elasticsearch,暂不支持 pgvector;PostgreSQL 作为关系库不受影响。未启用时沿用原检索策略,已有文档无需重新入库。效果与成本见[更新日志](CHANGELOG.md#jev-reranking)。 #### 存储后端 diff --git a/README.md b/README.md index 01dc29af..2165776e 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ Upload a document once. SAG parses it, splits it into chunks, embeds it, extract | Capability | What it gives you | | --- | --- | | Knowledge ingestion | File and web sources, document parsing, chunking, embedding, event/entity extraction, background processing | -| Search | Cross-source or source-scoped retrieval with Fast (`vector` / `multi_es_fast`), Precise (`multi`), and optional JEV reranking (`multi_jev`) modes | +| Search | Cross-source or source-scoped retrieval with Fast (`vector` / `multi_es_fast`), Precise (`multi`), optional JEV reranking (`multi_jev`), and SAG2 evidence retrieval (`sag2`) modes | | Source tracing | Open any result or citation back to the exact original chunk | | Knowledge graph | Inspect events, entities, and their queryable associations | | Agent chat | Multi-turn answers grounded in selected sources, with clickable citations | @@ -564,12 +564,15 @@ Pipeline request and result types are available from `zleap.sag.pipeline`: `Pars | Fast (multi_es-fast) | `multi_es_fast` | BM25 entity recall and event multi-hop retrieval, skipping LLM reranking | | Precise | `multi` | Combines entity relationships with LLM reranking for more complete results | | JEV reranking | `multi_jev` | Scores recalled and graph-expanded evidence through an independent JEV service | +| SAG2 evidence retrieval | `sag2` | Read-only search by [zleap-sag2](https://pypi.org/project/zleap-sag2/) over the relational store: BM25 recall scored over several JEV rounds, no vector store involved | -These are the application/API strategy names; the application maps `multi` to the Python engine's `full_expand` and `multi_es_fast` to `pruned_expand_rff`. Availability depends on storage capabilities: `multi_es_fast` requires lexical search support. +These are the application/API strategy names; the application maps `multi` to the Python engine's `full_expand` and `multi_es_fast` to `pruned_expand_rff`, while `sag2` runs on the separate `zleap-sag2` engine. Availability depends on storage capabilities: `multi_es_fast` and `multi_jev` require lexical search support; `sag2` requires a SQLite or PostgreSQL relational store. -Configure 302.AI, TypeSafe, or a custom JEV service in **Settings → Knowledge → Retrieval** (default model: `jev-latest`, separate API key), then select **JEV reranking**. Saving the service alone does not enable it. The default deadline is 30 seconds; failures return an error unless coarse fallback is enabled. +Configure 302.AI, TypeSafe, or a custom JEV service in **Settings → Knowledge → Retrieval** (default model: `jev-latest`, separate API key), then select **JEV reranking** or **SAG2 evidence retrieval**. JEV is a paid service: saving the service alone does not enable it, and an API key is required before either JEV mode can be selected. JEV reranking has a 30-second default deadline; failures return an error unless coarse fallback is enabled. -Supported on LanceDB and Elasticsearch; pgvector is currently unsupported. PostgreSQL relational storage can use JEV with a supported vector backend. Existing retrieval settings remain until JEV is selected; documents do not need reindexing. See the [benchmark results and cost estimates](CHANGELOG.md#jev-reranking). +**SAG2 evidence retrieval** shares the JEV service configuration but bypasses the vector store: it reads SAG's SQLite or PostgreSQL relational store directly (MySQL and OceanBase are not supported yet), documents become searchable as soon as they are chunked and stored, event extraction is not required, and pgvector single-database deployments can use it. Each search scans every passage of the selected sources and calls JEV over several rounds, so it costs more than JEV reranking; failures are reported as errors, with no coarse fallback. Tuning knobs for candidates, timeouts, concurrency and scope limits are documented as `SAG_SAG2_*` in `apps/api/.env.example`. On PostgreSQL the connecting role must be able to create and use the two auxiliary tables `sag2_state` and `sag2_search_sessions` in the target schema and to `LOCK TABLE` `sag2_state`; SAG's own tables stay read-only. + +JEV reranking is supported on LanceDB and Elasticsearch; pgvector is currently unsupported. PostgreSQL relational storage can use JEV with a supported vector backend. Existing retrieval settings remain until a JEV mode is selected; documents do not need reindexing. See the [benchmark results and cost estimates](CHANGELOG.md#jev-reranking). #### Storage backends diff --git a/apps/api/.env.example b/apps/api/.env.example index 4da32826..8349dd09 100644 --- a/apps/api/.env.example +++ b/apps/api/.env.example @@ -122,6 +122,20 @@ SAG_JEV_API_KEY= SAG_JEV_RANKING_TIMEOUT_SECONDS=30 SAG_JEV_FAILURE_POLICY=error +# 可选 SAG2 证据检索(zleap-sag2);选择 SAG_SEARCH_STRATEGY=sag2,或在设置页选择模式。 +# 共用上面的 JEV 服务地址、模型与 API Key(付费,选择任一 JEV 模式都必须填写 Key)。 +# 只读直搜 SQLite / PostgreSQL 关系库,不依赖向量库也不要求抽取完成;失败不回退, +# SAG_JEV_FAILURE_POLICY 对其无效。以下调优参数首期只经环境变量设置,默认值已控制用量。 +# SAG_SAG2_CANDIDATE_K=50 # BM25 候选数(zleap-sag2 默认 100) +# SAG_SAG2_SEED_K=10 # 每轮扩展种子数 +# SAG_SAG2_MAX_HOPS=2 # 扩展轮数 0–2 +# SAG_SAG2_EXPANSION_TERM_LIMIT=20 # 每轮扩展词数 +# SAG_SAG2_SEARCH_TIMEOUT_SECONDS=90 # 整次检索上限(含并发排队、扫描与全部评分轮次;设置发布期间的等待另计) +# SAG_SAG2_DECISION_TIMEOUT_SECONDS=60 # 单次决策请求超时 +# SAG_SAG2_DECISION_MAX_CONCURRENCY=20 # 决策请求并发 +# SAG_SAG2_MAX_CONCURRENT_SEARCHES=2 # 服务端同时执行的 SAG2 检索数 +# SAG_SAG2_MAX_SCOPE_CHUNKS=20000 # 所选信源实际加载分块上限(不含退役版本);选文档不缩小扫描,0 不限制 + # ── 知识宇宙镜头阈值与浏览器预算 ────────────────────── SAG_UNIVERSE_LOD_ORBIT_PX=72 SAG_UNIVERSE_LOD_NEAR_PX=180 diff --git a/apps/api/packaging/sag-api.spec b/apps/api/packaging/sag-api.spec index 7820565b..63c5f2a7 100644 --- a/apps/api/packaging/sag-api.spec +++ b/apps/api/packaging/sag-api.spec @@ -47,6 +47,8 @@ for package in ( # OpenAI, Anthropic, and Gemini, so freezing every LiteLLM module would pull # unrelated server/CLI dependencies into the desktop sidecar. datas += collect_data_files("litellm") +# zleap-sag2 的 Unicode 排序在运行时读取 pyuca 的 allkeys-*.txt,冻结包需显式收集。 +datas += collect_data_files("pyuca") datas += collect_data_files("certifi") for package in ( "litellm.litellm_core_utils", @@ -72,9 +74,10 @@ for package in ( hiddenimports += collect_submodules(package) for package in ( - "jieba-py", + "jieba", "sag-api", "zleap-sag", + "zleap-sag2", "lancedb", "litellm", "markitdown", diff --git a/apps/api/pyproject.toml b/apps/api/pyproject.toml index 8da93a4a..d9821944 100644 --- a/apps/api/pyproject.toml +++ b/apps/api/pyproject.toml @@ -23,6 +23,7 @@ dependencies = [ "litellm==1.103.0", "orjson>=3.11.6,<4", "zleap-sag==0.15.0", + "zleap-sag2==0.1.0", "alembic>=1.13", "trafilatura>=1.8", "markitdown[docx,pdf,pptx,xls,xlsx]>=0.1.6,<0.2", @@ -31,7 +32,7 @@ dependencies = [ "mcp>=1.28,<2", "octx[vectors]==0.1.6", "tzdata>=2024.1", - "jieba-py>=0.46.12,<0.47", + "jieba==0.42.1", ] [project.optional-dependencies] diff --git a/apps/api/sag_api/api/v1/dify.py b/apps/api/sag_api/api/v1/dify.py index 87eb0405..b29d9a7e 100644 --- a/apps/api/sag_api/api/v1/dify.py +++ b/apps/api/sag_api/api/v1/dify.py @@ -15,6 +15,7 @@ ServiceUnavailableError, ValidationError, ) +from sag_api.enums import JEV_SCORED_STRATEGIES from sag_api.sag import EngineManager from sag_api.schemas.dify import ( DifyRetrievalRecord, @@ -104,11 +105,11 @@ async def retrieval( **({ "score_source": section.metadata.get("score_source", "unknown"), "ranking_fallback_reason": (outcome.stats.get("ranking") or {}).get("fallback_reason"), - } if strategy == "multi_jev" else {}), + } if strategy in JEV_SCORED_STRATEGIES else {}), }, ) for section in outcome.sections if section.score >= body.retrieval_setting.score_threshold - and (strategy != "multi_jev" or fallback_used or section.metadata.get("score_source") == "jev") + and (strategy not in JEV_SCORED_STRATEGIES or fallback_used or section.metadata.get("score_source") == "jev") ] return DifyRetrievalResponse(records=records) diff --git a/apps/api/sag_api/api/v1/search.py b/apps/api/sag_api/api/v1/search.py index a771c8c7..78be5e6e 100644 --- a/apps/api/sag_api/api/v1/search.py +++ b/apps/api/sag_api/api/v1/search.py @@ -22,6 +22,7 @@ from sag_api.core.errors import ApiError, ValidationError from sag_api.core.logging import get_logger from sag_api.db.models import Source, User +from sag_api.enums import JEV_SCORED_STRATEGIES from sag_api.generation import LLMClient from sag_api.sag import EngineManager, RetrievedSection, SearchOutcome from sag_api.schemas.insight import EntityOut, GraphRelationOut @@ -178,7 +179,7 @@ async def _retrieve_search_evidence( top_k=body.top_k, include_ranked_candidates=body.include_ranked_candidates, ) - if strategy == "multi_jev": + if strategy in JEV_SCORED_STRATEGIES: outcome = await retrieval return outcome, event_scores_from_evidence(outcome.sections), True outcome, scores = await asyncio.gather( diff --git a/apps/api/sag_api/core/config.py b/apps/api/sag_api/core/config.py index c8972857..1ffc11a2 100644 --- a/apps/api/sag_api/core/config.py +++ b/apps/api/sag_api/core/config.py @@ -29,6 +29,7 @@ _DEFAULT_LLM_PROVIDER = get_model_provider("openai") MAX_JEV_RANKING_TIMEOUT_SECONDS = 120.0 +MAX_SAG2_SEARCH_TIMEOUT_SECONDS = 600.0 # zleap-sag 0.13.0 之前的默认向量维度:未显式配置时用它预建向量 schema, # 保持既有知识库的向量空间不变(存量 LanceDB 向量与该维度绑定)。 @@ -226,6 +227,23 @@ class Settings(BaseSettings): jev_ranking_timeout_seconds: float = Field(default=30.0, ge=0.1, le=MAX_JEV_RANKING_TIMEOUT_SECONDS) jev_failure_policy: Literal["error", "fallback_to_score"] = "error" + # SAG2 证据检索(zleap-sag2):共用上面的 JEV 连接,只读直搜 SAG 关系库;以下为其自有预算, + # 首期只经环境变量调整。候选数默认取包默认值的一半,控制付费评分用量。 + sag2_candidate_k: int = Field(default=50, ge=1, le=1000) + sag2_seed_k: int = Field(default=10, ge=1, le=100) + sag2_max_hops: int = Field(default=2, ge=0, le=2) + sag2_expansion_term_limit: int = Field(default=20, ge=1, le=100) + # 整次检索上限,含并发排队、范围扫描与最多三轮评分;超出报检索超时,不回退其他策略。 + # 等待设置发布完成的准入等待另按同一时长计,与 multi_jev 的准入语义一致。 + sag2_search_timeout_seconds: float = Field(default=90.0, ge=5, le=MAX_SAG2_SEARCH_TIMEOUT_SECONDS) + # 单次决策请求超时与并发,透传 zleap-sag2 的 JevConfig(包默认 180 秒对交互检索过长)。 + sag2_decision_timeout_seconds: float = Field(default=60.0, ge=1, le=600) + sag2_decision_max_concurrency: int = Field(default=20, ge=1, le=100) + # 服务端同时执行的 SAG2 检索数;排队等待计入整次超时。 + sag2_max_concurrent_searches: int = Field(default=2, ge=1, le=32) + # 所选信源段落行数上限;直读模式每次全量扫描,超出即拒绝。0 表示不限制。 + sag2_max_scope_chunks: int = Field(default=20_000, ge=0) + # Optional chatbot/query connections; extraction and indexing retain the original clients. chatbot_llm_enabled: bool = False chatbot_llm_provider: ModelProviderId = "openai" diff --git a/apps/api/sag_api/enums.py b/apps/api/sag_api/enums.py index c9a2ff92..cf1f8306 100644 --- a/apps/api/sag_api/enums.py +++ b/apps/api/sag_api/enums.py @@ -5,15 +5,20 @@ from enum import StrEnum from typing import Literal -SearchStrategy = Literal["vector", "multi", "multi_es_fast", "multi_jev"] -SEARCH_STRATEGIES = frozenset({"vector", "multi", "multi_es_fast", "multi_jev"}) +SearchStrategy = Literal["vector", "multi", "multi_es_fast", "multi_jev", "sag2"] +SEARCH_STRATEGIES = frozenset({"vector", "multi", "multi_es_fast", "multi_jev", "sag2"}) +# 由付费 JEV 决策服务评分的模式:选择前必须保存服务地址与 API Key,失败不回退 vector, +# 业务层保留引擎给出的证据顺序。 +JEV_SCORED_STRATEGIES = frozenset({"multi_jev", "sag2"}) # 策略对底层引擎能力的依赖。缺失能力的部署会在 UI 灰置该选项;后端调用则拒绝。 +# jev:已保存 JEV 服务地址与 API Key;sag2_relational:zleap-sag2 首期只读 SQLite / PostgreSQL 关系库。 SEARCH_STRATEGY_REQUIREMENTS: dict[str, frozenset[str]] = { "vector": frozenset(), "multi": frozenset(), "multi_es_fast": frozenset({"lexical_search"}), "multi_jev": frozenset({"lexical_search", "jev"}), + "sag2": frozenset({"jev", "sag2_relational"}), } diff --git a/apps/api/sag_api/mcp/server.py b/apps/api/sag_api/mcp/server.py index 41903830..3c921f77 100644 --- a/apps/api/sag_api/mcp/server.py +++ b/apps/api/sag_api/mcp/server.py @@ -19,6 +19,7 @@ from mcp.types import ToolAnnotations from pydantic import Field +from sag_api.enums import JEV_SCORED_STRATEGIES from sag_api.services.insight_service import find_entity_context from sag_api.services.outline_service import build_outline, render_outline_text from sag_api.services.retrieval_service import get_published_chunk, grep_published_chunks, retrieve_relevant_sections @@ -227,7 +228,7 @@ async def search( top_k=max(1, min(top_k, 50)), ) text = _sections_to_text(outcome.sections, selected) - if outcome.stats.get("requested_strategy") == "multi_jev" and outcome.stats.get("fallback_used"): + if outcome.stats.get("requested_strategy") in JEV_SCORED_STRATEGIES and outcome.stats.get("fallback_used"): text = "(JEV 精排未完成,本次返回粗排结果)\n" + text return text diff --git a/apps/api/sag_api/sag/engine_access.py b/apps/api/sag_api/sag/engine_access.py index fa01e85c..66c6e2fd 100644 --- a/apps/api/sag_api/sag/engine_access.py +++ b/apps/api/sag_api/sag/engine_access.py @@ -96,6 +96,9 @@ async def search_raw(self, *args: Any, **kwargs: Any) -> Any: async def search_chunk_vectors(self, *args: Any, **kwargs: Any) -> Any: return await self._manager._search_chunk_vectors(*args, **kwargs) + async def sag2_search(self, *args: Any, **kwargs: Any) -> Any: + return await self._manager._sag2_search(*args, **kwargs) + async def universe_entity_event_counts(self, *args: Any, **kwargs: Any) -> Any: return await self._manager._universe_entity_event_counts(*args, **kwargs) diff --git a/apps/api/sag_api/sag/engine_manager.py b/apps/api/sag_api/sag/engine_manager.py index 14fdde11..cd40017d 100644 --- a/apps/api/sag_api/sag/engine_manager.py +++ b/apps/api/sag_api/sag/engine_manager.py @@ -24,6 +24,7 @@ from sag_api.core.errors import ConfigurationError, ServiceUnavailableError from sag_api.core.logging import get_logger from sag_api.enums import ( + JEV_SCORED_STRATEGIES, SEARCH_STRATEGIES, SEARCH_STRATEGY_REQUIREMENTS, normalize_search_strategy, @@ -42,7 +43,14 @@ from sag_api.sag.engine_access import EngineAccess from sag_api.sag.errors import map_sag_errors from sag_api.sag.incremental_processor import IncrementalDocumentProcessor, ProgressCallback -from sag_api.sag.search_reader import SearchReader, search_source_timeout_seconds +from sag_api.sag.sag2_engine import ( + Sag2EngineHolder, + jev_connection_issue, + jev_connection_ready, + sag2_relational_issue, + sag2_relational_supported, +) +from sag_api.sag.search_reader import SearchReader, search_admission_timeout_seconds from sag_api.sag.universe_cursor import ( decode_universe_cursor, encode_universe_cursor, @@ -184,6 +192,8 @@ def __init__(self, settings: Settings): self._universe = UniverseReader(self._access) self._content = ContentReader(self._access) self._search = SearchReader(self._access) + # SAG2 证据检索:一个只读 zleap-sag2 引擎覆盖全部信源,随配置发布重建。 + self._sag2 = Sag2EngineHolder(settings) async def _relational_session_factory(self, source_config_id: str, source: Source | None = None) -> Any: """0.8.2 起 zleap 无全局会话工厂;经引擎注入的 RelationalStore 访问关系库。""" @@ -327,26 +337,35 @@ def create_missing(sync_connection) -> None: # noqa: ANN001 def _vector_provider_supports_lexical(self) -> bool: return self._VECTOR_PROVIDER_LEXICAL_SUPPORT.get(self._settings.sag_vector_provider, False) - def _strategy_missing_capabilities(self, strategy: str) -> tuple[str, ...]: + # 缺失能力的报告顺序:存储层能力先于服务配置,前端只展示第一个原因。 + _CAPABILITY_ORDER: tuple[str, ...] = ("lexical_search", "sag2_relational", "jev") + + @classmethod + def _missing_capabilities(cls, settings: Settings, strategy: str) -> tuple[str, ...]: requirements = SEARCH_STRATEGY_REQUIREMENTS.get(strategy, frozenset()) + supports_lexical = cls._VECTOR_PROVIDER_LEXICAL_SUPPORT.get(settings.sag_vector_provider, False) missing: list[str] = [] - for capability in requirements: - if capability == "lexical_search" and not self._vector_provider_supports_lexical(): + for capability in sorted(requirements, key=cls._CAPABILITY_ORDER.index): + if capability == "lexical_search" and not supports_lexical: + missing.append(capability) + elif capability == "jev" and not jev_connection_ready(settings): missing.append(capability) - elif capability == "jev" and not self._settings.jev_endpoint: + elif capability == "sag2_relational" and not sag2_relational_supported(settings): missing.append(capability) return tuple(missing) + def _strategy_missing_capabilities(self, strategy: str) -> tuple[str, ...]: + return self._missing_capabilities(self._settings, strategy) + def _effective_search_strategy(self, requested: str | None) -> str: """校验请求的门面策略。未识别或能力不满足时按配置策略回退,再兜底 vector。""" raw = requested or self._settings.search_strategy strategy = normalize_search_strategy(raw) - if strategy == "multi_jev": + if strategy in JEV_SCORED_STRATEGIES: missing = self._strategy_missing_capabilities(strategy) if missing: # Explicit/default JEV selection must never silently change mode. - capability = "lexical_search" if "lexical_search" in missing else "jev" - reason, message = self._capability_disabled_reason(capability, self._settings.sag_vector_provider) + reason, message = self._capability_disabled_reason(missing[0], self._settings) raise ConfigurationError(message, code=reason, stage=ErrorStage.RETRIEVE) return strategy if strategy in SEARCH_STRATEGIES: @@ -373,15 +392,17 @@ def _zleap_engine_strategy(self, facade_strategy: str) -> str: return self._FACADE_TO_ZLEAP_STRATEGY.get(facade_strategy, facade_strategy) @classmethod - def _capability_disabled_reason(cls, capability: str, provider: str) -> tuple[str, str] | None: - """给定缺失的能力名 + 当前 provider,产出 (reason_code, 用户可读文案)。""" + def _capability_disabled_reason(cls, capability: str, settings: Settings) -> tuple[str, str] | None: + """给定缺失的能力名 + 当前配置,产出 (reason_code, 用户可读文案)。""" if capability == "lexical_search": return ( "vector_provider_lacks_lexical", - f"当前向量存储 ({provider}) 不支持 BM25 词法检索,无法启用该检索模式。", + f"当前向量存储 ({settings.sag_vector_provider}) 不支持 BM25 词法检索,无法启用该检索模式。", ) if capability == "jev": - return ("jev_not_configured", "尚未配置 JEV 精排服务,请先保存服务地址。") + return jev_connection_issue(settings) + if capability == "sag2_relational": + return sag2_relational_issue(settings) return None @classmethod @@ -390,33 +411,23 @@ def strategies_capability_report(cls, settings: Settings) -> dict[str, Any]: 无需持有 EngineManager 实例——所有判据只来自 settings。 """ - provider = settings.sag_vector_provider - supports_lexical = cls._VECTOR_PROVIDER_LEXICAL_SUPPORT.get(provider, False) enabled: list[str] = [] disabled: dict[str, dict[str, str]] = {} for strategy in sorted(SEARCH_STRATEGIES): - requirements = SEARCH_STRATEGY_REQUIREMENTS.get(strategy, frozenset()) - missing: list[tuple[str, str]] = [] - for capability in sorted(requirements, key=lambda value: value != "lexical_search"): - if ( - capability == "lexical_search" and not supports_lexical - or capability == "jev" and not settings.jev_endpoint - ): - reason = cls._capability_disabled_reason(capability, provider) - if reason is not None: - missing.append(reason) - if missing: + missing = cls._missing_capabilities(settings, strategy) + reason = cls._capability_disabled_reason(missing[0], settings) if missing else None + if reason is not None: # 只呈现第一个原因即可满足 UI 灰置 + tooltip 展示。 - reason_code, message = missing[0] + reason_code, message = reason disabled[strategy] = {"reason": reason_code, "message": message} else: enabled.append(strategy) return {"enabled": enabled, "disabled": disabled} @classmethod - def require_jev_capabilities(cls, settings: Settings) -> None: - """Reject explicit JEV activation before publishing incompatible settings.""" - unavailable = cls.strategies_capability_report(settings)["disabled"].get("multi_jev") + def require_jev_capabilities(cls, settings: Settings, strategy: str = "multi_jev") -> None: + """Reject explicit JEV-scored mode activation before publishing incompatible settings.""" + unavailable = cls.strategies_capability_report(settings)["disabled"].get(strategy) if unavailable is not None: raise ConfigurationError(unavailable["message"], code=unavailable["reason"]) @@ -890,10 +901,7 @@ async def search_many( source_ids_by_config: dict[str, tuple[str, ...]] | None = None, include_ranked_candidates: bool = False, ) -> SearchOutcome: - admission_timeout = ( - search_source_timeout_seconds(self._settings, strategy) - if (strategy or self._settings.search_strategy) == "multi_jev" else None - ) + admission_timeout = search_admission_timeout_seconds(self._settings, strategy) try: async with self._search_configuration_gate.read(timeout=admission_timeout): return await self._search.search_many( @@ -911,6 +919,25 @@ async def search_many( ) from error raise + async def _sag2_search( + self, + targets: list[tuple[str, Source | None]], + query: str, + *, + top_k: int, + requested_sources: int, + source_limit_applied: bool, + source_ids_by_config: dict[str, tuple[str, ...]] | None, + ) -> SearchOutcome: + return await self._sag2.search( + targets, + query, + top_k=top_k, + requested_sources=requested_sources, + source_limit_applied=source_limit_applied, + source_ids_by_config=source_ids_by_config, + ) + async def _search_chunk_vectors( self, targets: list[tuple[str, Source | None]], @@ -1180,6 +1207,7 @@ async def aclose_all(self) -> None: async with self._create_lock: async with self._lifecycle_gate.write(): await self._close_all_slots() + await self._sag2.aclose() async def apply_settings(self, settings: Any, *, reset_engines: bool) -> None: """Publish runtime settings and reset slots in the same admission barrier.""" @@ -1190,6 +1218,8 @@ async def apply_settings(self, settings: Any, *, reset_engines: bool) -> None: setattr(self._settings, field_name, getattr(settings, field_name)) if reset_engines: await self._close_all_slots() + # 只读 SAG2 引擎按自身指纹判断是否重建,与槽重置解耦。 + await self._sag2.refresh(self._settings) async def _close_all_slots(self) -> None: # Caller owns the create lock and lifecycle writer; don't acquire them twice. diff --git a/apps/api/sag_api/sag/errors.py b/apps/api/sag_api/sag/errors.py index b833851d..9d9588ca 100644 --- a/apps/api/sag_api/sag/errors.py +++ b/apps/api/sag_api/sag/errors.py @@ -31,6 +31,11 @@ ValidationError, ) +# JEV 评分服务的错误文案,`multi_jev`(zleap-sag)与 `sag2`(zleap-sag2)两条路径共用。 +JEV_AUTH_FAILED_MESSAGE = "JEV 鉴权失败,请检查服务地址和 API Key" +JEV_UNAVAILABLE_MESSAGE = "JEV 精排服务暂不可用,请稍后重试" +JEV_REQUEST_REJECTED_MESSAGE = "JEV 精排请求被拒绝,请检查模型和候选内容限制" + try: # jsonschema 是 zleap-sag structured-output 校验的传递依赖 from jsonschema.exceptions import ValidationError as JsonSchemaValidationError except Exception: # noqa: BLE001 - 依赖缺失时退化为不可能匹配的哨兵 @@ -67,17 +72,11 @@ def map_sag_errors(*, stage: ErrorStage = ErrorStage.UNKNOWN, search_strategy: s timed_out = timed_out or isinstance(cause, TimeoutError) if getattr(cause, "provider", None) == "jev": if isinstance(cause, AIAuthError): - raise ConfigurationError( - "JEV 鉴权失败,请检查服务地址和 API Key", layer=ErrorLayer.ENGINE, stage=stage, - ) from e + raise ConfigurationError(JEV_AUTH_FAILED_MESSAGE, layer=ErrorLayer.ENGINE, stage=stage) from e if isinstance(cause, AITransientError): - raise ServiceUnavailableError( - "JEV 精排服务暂不可用,请稍后重试", layer=ErrorLayer.ENGINE, stage=stage, - ) from e + raise ServiceUnavailableError(JEV_UNAVAILABLE_MESSAGE, layer=ErrorLayer.ENGINE, stage=stage) from e if isinstance(cause, (AIInvalidRequestError, LLMContextLengthError)): - raise ValidationError( - "JEV 精排请求被拒绝,请检查模型和候选内容限制", layer=ErrorLayer.ENGINE, stage=stage, - ) from e + raise ValidationError(JEV_REQUEST_REJECTED_MESSAGE, layer=ErrorLayer.ENGINE, stage=stage) from e if isinstance(cause, AIError): raise UpstreamError("JEV 精排返回无效结果", layer=ErrorLayer.ENGINE, stage=stage) from e cause = cause.__cause__ diff --git a/apps/api/sag_api/sag/jev_probe.py b/apps/api/sag_api/sag/jev_probe.py index f2f8bfc3..4e14a18a 100644 --- a/apps/api/sag_api/sag/jev_probe.py +++ b/apps/api/sag_api/sag/jev_probe.py @@ -20,6 +20,9 @@ async def probe_jev_connection(configuration: Settings) -> JevConnectionTestResu """Score synthetic evidence without persisting settings or exposing provider errors.""" if not configuration.jev_endpoint: return JevConnectionTestResult(ok=False, message="尚未配置 JEV 完整服务地址") + if not configuration.jev_api_key: + # JEV 是付费服务;没有 Key 的探测既不会成功也不应发出请求。 + return JevConnectionTestResult(ok=False, message="JEV 为付费服务,请先填写 API Key") client = JevClient( endpoint=configuration.jev_endpoint, model=configuration.jev_model, diff --git a/apps/api/sag_api/sag/sag2_engine.py b/apps/api/sag_api/sag/sag2_engine.py new file mode 100644 index 00000000..370ba414 --- /dev/null +++ b/apps/api/sag_api/sag/sag2_engine.py @@ -0,0 +1,553 @@ +"""zleap-sag2 只读直搜:共用 JEV 连接,在 SAG 关系库上做 BM25 召回与多轮证据评分。 + +与 ``multi_jev`` 不同,SAG2 不经过每信源的 zleap-sag ``DataEngine``:一个未绑定数据源的 +``zleap.sag2.DataEngine`` 连接同一关系库,识别 ``source_chunk`` 后以只读方式检索, +一次请求覆盖全部目标信源并由引擎给出最终顺序。写入、删除仍由 zleap-sag 管理。 + +首期只支持 SQLite 与 PostgreSQL;直读模式每次检索会扫描所选信源的全部可见段落, +因此这里同时限制并发检索数与信源内实际加载的段落数,排队与扫描都计入整次超时。 + +对 zleap-sag2 内部结构的依赖集中在 ``_sag_schema_present`` 与 ``_count_scope`` 两个 +函数里(``engine.store.engine`` 是其关系库连接);升级 ``zleap-sag2`` 版本时需复核这两处。 + +zleap-sag2 0.1.0 在构建内存语料时会在事件循环线程上同步分词、建倒排表,范围越大阻塞越久。 +为此只读引擎及其全部协程都运行在一个专用线程的事件循环里(``_EngineLoop``), +API 事件循环只负责排队、超时与取消,不被扫描阻塞。 +""" + +from __future__ import annotations + +import asyncio +import threading +import time +from collections.abc import Callable, Coroutine +from pathlib import Path +from typing import TYPE_CHECKING, Any + +from sag_api.core.error_taxonomy import ErrorLayer, ErrorStage +from sag_api.core.errors import ( + ConfigurationError, + ServiceUnavailableError, + UpstreamError, + ValidationError, +) +from sag_api.core.logging import get_logger +from sag_api.sag.dto import RetrievedSection, SearchOutcome +from sag_api.sag.errors import ( + JEV_AUTH_FAILED_MESSAGE, + JEV_REQUEST_REJECTED_MESSAGE, + JEV_UNAVAILABLE_MESSAGE, +) + +if TYPE_CHECKING: + from sag_api.core.config import Settings + from sag_api.db.models import Source + +log = get_logger("sag.sag2") + +SAG2_RELATIONAL_PROVIDERS = frozenset({"sqlite", "postgres"}) +SAG2_STRATEGY = "sag2" +SAG_CHUNK_TABLE = "source_chunk" + + +def relational_provider(settings: Settings) -> str: + return settings.sag_relational_provider or "sqlite" + + +def jev_connection_issue(settings: Settings) -> tuple[str, str] | None: + """JEV 为付费服务:地址与 API Key 都保存后,才允许选择任何 JEV 评分模式。 + + 返回 ``(reason_code, 用户可读文案)``;连接完整时返回 ``None``。 + """ + if not settings.jev_endpoint: + return ("jev_not_configured", "尚未配置 JEV 精排服务,请先保存服务地址。") + if not settings.jev_api_key: + return ("jev_api_key_missing", "JEV 为付费服务,请先在设置中填写 API Key。") + return None + + +def sag2_relational_issue(settings: Settings) -> tuple[str, str] | None: + """SAG2 首期只读 SQLite / PostgreSQL;其他关系库返回不可用原因。""" + provider = relational_provider(settings) + if provider in SAG2_RELATIONAL_PROVIDERS: + return None + return ( + "sag2_relational_unsupported", + f"SAG2 证据检索首期仅支持 SQLite 与 PostgreSQL 关系库,当前为 {provider}。", + ) + + +def jev_connection_ready(settings: Settings) -> bool: + return jev_connection_issue(settings) is None + + +def sag2_relational_supported(settings: Settings) -> bool: + return sag2_relational_issue(settings) is None + + +def _fingerprint(settings: Settings) -> tuple[Any, ...]: + """决定是否需要重建只读引擎的配置子集;检索参数在每次请求时读取,不在此列。""" + return ( + settings.jev_endpoint, + settings.jev_model, + settings.jev_api_key, + relational_provider(settings), + settings.data_dir, + settings.sag_pg_host, + settings.sag_pg_port, + settings.sag_pg_user, + settings.sag_pg_password, + settings.sag_pg_database, + settings.sag2_decision_timeout_seconds, + settings.sag2_decision_max_concurrency, + ) + + +def build_sag2_config(settings: Settings): + """由 SAG 运行时配置装配 zleap-sag2 的 ``EngineConfig``(同一关系库 + 共用 JEV 连接)。""" + from zleap.sag2 import EngineConfig, JevConfig, RelationalConfig + + for issue in (sag2_relational_issue(settings), jev_connection_issue(settings)): + if issue is not None: + code, message = issue + raise ConfigurationError(message, code=code, stage=ErrorStage.RETRIEVE) + if relational_provider(settings) == "sqlite": + # zleap-sag 在 data_dir 下派生同名 SQLite 文件;运行时已把 data_dir 替换为活动目录。 + relational = RelationalConfig(provider="sqlite", path=str(Path(settings.data_dir) / "sag.db")) + else: + relational = RelationalConfig( + provider="postgres", + host=settings.sag_pg_host, + port=settings.sag_pg_port, + user=settings.sag_pg_user, + password=settings.sag_pg_password, + database=settings.sag_pg_database, + ) + jev = JevConfig( + endpoint=settings.jev_endpoint, + model=settings.jev_model, + api_key=settings.jev_api_key, + timeout_seconds=settings.sag2_decision_timeout_seconds, + max_concurrency=settings.sag2_decision_max_concurrency, + ) + return EngineConfig(relational=relational, jev=jev) + + +def _base_stats(*, sources: int, requested_sources: int, source_limit_applied: bool, candidates: int) -> dict[str, Any]: + """所有 SAG2 结果共有的 stats 字段;SAG2 没有粗排降级,``fallback_used`` 恒为 False。""" + return { + "sources": sources, + "sources_requested": requested_sources, + "source_limit_applied": source_limit_applied, + "candidates": candidates, + "requested_strategy": SAG2_STRATEGY, + "effective_strategy": SAG2_STRATEGY, + "fallback_used": False, + "ranking": {"method": "jev", "fallback_reason": None}, + } + + +def outcome_from_result( + result: Any, + *, + query: str, + data_source_ids: list[str], + requested_sources: int, + source_limit_applied: bool, + scope_chunks: int, +) -> SearchOutcome: + """把 zleap-sag2 的 ``SearchResult`` 映射为业务 DTO,保留引擎顺序与原始 JEV 分数。""" + sections = [ + RetrievedSection( + chunk_id=hit.chunk_id or hit.id, + heading=(hit.heading or hit.title or "").strip(), + content=(hit.content or "").strip(), + score=float(hit.score or 0.0), + rank=index, + source_id=hit.source_id, + source_config_id=hit.data_source_id, + metadata={"score_source": "jev", "hop": int(hit.hop or 0)}, + ) + for index, hit in enumerate(result.chunks) + ] + usage = dict(getattr(result, "usage", None) or {}) + trace = getattr(result, "trace", None) or () + stats = _base_stats( + sources=len(data_source_ids), + requested_sources=requested_sources, + source_limit_applied=source_limit_applied, + candidates=len(sections), + ) + stats["jev_usage"] = { + "requests": usage.get("requests"), + "judgments": usage.get("judgments"), + "input_tokens": usage.get("input_tokens"), + "output_tokens": usage.get("output_tokens"), + } + stats["sag2"] = { + "elapsed_ms": round(float(getattr(result, "elapsed_ms", 0.0) or 0.0), 2), + "local_ms": round(float(getattr(result, "local_ms", 0.0) or 0.0), 2), + "jev_ms": round(float(getattr(result, "jev_ms", 0.0) or 0.0), 2), + "snapshot_revision": getattr(result, "snapshot_revision", None), + "scope_chunks": scope_chunks, + "hops": [ + {"stage": item.get("stage"), "hop": item.get("hop"), "count": item.get("count")} + for item in trace + if isinstance(item, dict) + ], + } + return SearchOutcome(query=getattr(result, "query", None) or query, sections=sections, stats=stats) + + +class _AdmissionGate: + """可在线调整上限的并发闸门:在途检索继续持有名额,新检索按当前上限排队。""" + + def __init__(self, limit: int) -> None: + self._limit = max(1, limit) + self._active = 0 + self._condition = asyncio.Condition() + + @property + def active(self) -> int: + return self._active + + async def set_limit(self, limit: int) -> None: + async with self._condition: + self._limit = max(1, limit) + self._condition.notify_all() + + async def __aenter__(self) -> None: + async with self._condition: + await self._condition.wait_for(lambda: self._active < self._limit) + self._active += 1 + + async def __aexit__(self, *_exc: object) -> None: + async with self._condition: + self._active -= 1 + self._condition.notify_all() + + async def drain(self) -> None: + async with self._condition: + await self._condition.wait_for(lambda: self._active == 0) + + +class _EngineLoop: + """专用线程上的事件循环:承载只读引擎的连接、扫描与评分,不占用 API 循环。 + + ``run`` 从 API 循环提交协程并等待结果;等待方被取消(如整次超时)时同步取消 + 专用循环里的协程,避免遗留仍在扫描的工作。 + """ + + def __init__(self, name: str = "sag2-engine") -> None: + self._loop = asyncio.new_event_loop() + self._thread = threading.Thread(target=self._serve, name=name, daemon=True) + self._thread.start() + + def _serve(self) -> None: + asyncio.set_event_loop(self._loop) + try: + self._loop.run_forever() + finally: + self._loop.close() + + @property + def alive(self) -> bool: + return self._thread.is_alive() + + async def run(self, coroutine: Coroutine[Any, Any, Any]) -> Any: + future = asyncio.run_coroutine_threadsafe(coroutine, self._loop) + try: + return await asyncio.wrap_future(future) + except asyncio.CancelledError: + future.cancel() + raise + + def stop(self, timeout: float = 5.0) -> None: + if not self._thread.is_alive(): + return + self._loop.call_soon_threadsafe(self._loop.stop) + self._thread.join(timeout=timeout) + + +class Sag2EngineHolder: + """按配置指纹懒建、复用、重建一个只读 zleap-sag2 引擎,并限制并发检索数。 + + 引擎只在专用线程的事件循环里创建和使用;``_gate`` 与整次超时留在 API 循环。 + ``scorer_factory`` 仅供测试注入离线评分器;缺省由引擎按 ``JevConfig`` 创建真实客户端。 + """ + + def __init__(self, settings: Settings, *, scorer_factory: Callable[[Any], Any] | None = None) -> None: + self._settings = settings + self._scorer_factory = scorer_factory + self._engine: Any | None = None + self._fingerprint: tuple[Any, ...] | None = None + self._lock = asyncio.Lock() + self._gate = _AdmissionGate(settings.sag2_max_concurrent_searches) + self._loop: _EngineLoop | None = None + + def _engine_loop(self) -> _EngineLoop: + if self._loop is None or not self._loop.alive: + self._loop = _EngineLoop() + return self._loop + + @property + def started(self) -> bool: + return self._engine is not None + + @property + def stale(self) -> bool: + """当前引擎是否已不匹配配置;下次检索会按新配置重建。""" + return self._engine is not None and self._fingerprint != _fingerprint(self._settings) + + async def refresh(self, settings: Settings) -> None: + """配置发布后调用:新的并发上限立即生效;连接或存储变化后由下次检索惰性重建。 + + 在途检索持有旧引擎的本地引用,不在这里关闭它,避免打断正在进行的评分。 + """ + self._settings = settings + await self._gate.set_limit(settings.sag2_max_concurrent_searches) + + async def aclose(self) -> None: + """等待在途检索结束后关闭引擎并停掉专用循环;与 ``_close_all_slots`` 等待空闲的语义一致。""" + await self._gate.drain() + loop, self._loop = self._loop, None + if loop is not None and loop.alive: + try: + await loop.run(self._locked_close()) + finally: + await asyncio.to_thread(loop.stop) + else: + await self._locked_close() + + async def _locked_close(self) -> None: + async with self._lock: + await self._close() + + async def _close(self) -> None: + engine, self._engine, self._fingerprint = self._engine, None, None + if engine is None: + return + try: + await engine.aclose() + except Exception as error: # noqa: BLE001 - best-effort shutdown + log.warning("关闭 SAG2 只读引擎失败:%s", error) + + async def engine(self) -> Any: + async with self._lock: + fingerprint = _fingerprint(self._settings) + if self._engine is not None and self._fingerprint == fingerprint: + return self._engine + await self._close() + self._engine = await self._start(self._settings) + self._fingerprint = fingerprint + return self._engine + + async def _start(self, settings: Settings) -> Any: + from zleap.sag2 import DataEngine + + config = build_sag2_config(settings) + not_ready = ConfigurationError( + "知识库尚未初始化,暂无可检索的段落", code="sag2_storage_not_ready", stage=ErrorStage.RETRIEVE, + ) + if relational_provider(settings) == "sqlite" and not Path(settings.data_dir, "sag.db").is_file(): + raise not_ready + scorer = self._scorer_factory(config) if self._scorer_factory is not None else None + engine = DataEngine(config, scorer=scorer, health_check=False) + try: + # 空库会让 zleap-sag2 建立自己的业务表;只在已有 SAG 段落表时才启动只读模式。 + if not await self._sag_schema_present(engine): + raise not_ready + await engine.start() + except BaseException: + await engine.aclose() + raise + log.info("SAG2 只读引擎已启动 provider=%s", relational_provider(settings)) + return engine + + async def search( + self, + targets: list[tuple[str, Source | None]], + query: str, + *, + top_k: int, + requested_sources: int, + source_limit_applied: bool, + source_ids_by_config: dict[str, tuple[str, ...]] | None, + ) -> SearchOutcome: + """一次只读检索覆盖全部目标信源;失败直接上抛,不回退其他策略。""" + data_source_ids = [scid for scid, _ in targets] + if source_ids_by_config is not None: + data_source_ids = [scid for scid in data_source_ids if source_ids_by_config.get(scid)] + if not data_source_ids: + return SearchOutcome(query=query, sections=[], stats=_base_stats( + sources=0, requested_sources=requested_sources, source_limit_applied=source_limit_applied, candidates=0, + )) + source_ids = ( + None + if source_ids_by_config is None + else tuple(sorted({sid for scid in data_source_ids for sid in source_ids_by_config[scid]})) + ) + timeout = max(1.0, float(self._settings.sag2_search_timeout_seconds)) + try: + result, scope_chunks = await asyncio.wait_for( + self._run(query, data_source_ids, source_ids, top_k), timeout, + ) + except TimeoutError as error: + raise ServiceUnavailableError( + "SAG2 检索超时,请缩小信源范围或稍后重试", layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE, + ) from error + return outcome_from_result( + result, + query=query, + data_source_ids=data_source_ids, + requested_sources=requested_sources, + source_limit_applied=source_limit_applied, + scope_chunks=scope_chunks, + ) + + async def _run( + self, + query: str, + data_source_ids: list[str], + source_ids: tuple[str, ...] | None, + top_k: int, + ) -> tuple[Any, int]: + async with self._gate: + # 排队在 API 循环完成;引擎工作整体交给专用循环,扫描不阻塞其他请求。 + return await self._engine_loop().run(self._execute(query, data_source_ids, source_ids, top_k)) + + async def _execute( + self, + query: str, + data_source_ids: list[str], + source_ids: tuple[str, ...] | None, + top_k: int, + ) -> tuple[Any, int]: + """在专用循环里运行:取引擎、范围护栏、构造请求、检索与异常翻译。""" + from zleap.sag2 import SearchOptions, SearchRequest, SearchScope + + engine = await self.engine() + settings = self._settings + scope_chunks = await self._count_scope(engine, data_source_ids) + limit = int(settings.sag2_max_scope_chunks) + if limit and scope_chunks > limit: + raise ValidationError( + f"信源扫描范围过大:包含 {scope_chunks:,} 个段落,超过 SAG2 证据检索上限 {limit:,}。" + "本版引擎先扫描整个信源,选择单篇文档不会减少扫描量;请减少信源,或联系管理员调整扫描上限。", + layer=ErrorLayer.ENGINE, + stage=ErrorStage.RETRIEVE, + ) + scope_values: dict[str, Any] = {"data_source_ids": tuple(data_source_ids)} + if source_ids is not None: + scope_values["source_ids"] = source_ids + request = SearchRequest( + query=query, + scope=SearchScope(**scope_values), + options=SearchOptions( + candidate_k=settings.sag2_candidate_k, + seed_k=settings.sag2_seed_k, + max_hops=settings.sag2_max_hops, + expansion_term_limit=settings.sag2_expansion_term_limit, + top_k=max(1, min(int(top_k), 1000)), + ), + ) + started = time.perf_counter() + try: + result = await engine.search(request) + except Exception as error: # noqa: BLE001 - translated below + raise self._translate(error) from error + log.info( + "SAG2 检索完成 sources=%d scope_chunks=%d hits=%d elapsed=%.0fms", + len(data_source_ids), scope_chunks, len(result.chunks), (time.perf_counter() - started) * 1000, + ) + return result, scope_chunks + + @staticmethod + async def _sag_schema_present(engine: Any) -> bool: + """SAG 的段落表是否存在;zleap-sag2 据此决定进入只读直搜模式。""" + from sqlalchemy import inspect + + async with engine.store.engine.connect() as connection: + return bool(await connection.run_sync(lambda sync: inspect(sync).has_table(SAG_CHUNK_TABLE))) + + @staticmethod + async def _count_scope(engine: Any, data_source_ids: list[str]) -> int: + """匹配 SDK 0.1.0 Sag1Reader._rows 的分块 SQL,避免历史代际虚增。 + + SDK 先按信源加载、后按文档过滤,因此仍须统计整个信源的加载成本。 + 复用 SDK 检测到的表以兼容无 manifest 的旧库;不读取分块正文。 + """ + from sqlalchemy import and_, exists, func, or_, select + + tables = engine.store.sag1_reader.tables + chunks = tables[SAG_CHUNK_TABLE] + statement = select(func.count()).select_from(chunks).where(chunks.c.data_source_id.in_(data_source_ids)) + if "generation_id" in chunks.c: + unmanaged = chunks.c.generation_id.is_(None) + manifest = tables.get("sag_source_manifest") + if manifest is None: + statement = statement.where(unmanaged) + else: + same_source = and_( + manifest.c.data_source_id == chunks.c.data_source_id, + manifest.c.source_id == chunks.c.source_id, + ) + statement = statement.where(or_( + exists(select(1).select_from(manifest).where( + same_source, manifest.c.status == "ready", + manifest.c.active_generation_id == chunks.c.generation_id, + )), + and_(unmanaged, ~exists(select(1).select_from(manifest).where(same_source))), + )) + namespace = tables.get("sag_data_source_manifest") + if namespace is not None: + statement = statement.where(~exists(select(1).select_from(namespace).where( + namespace.c.data_source_id == chunks.c.data_source_id, namespace.c.active.is_not(True), + ))) + async with engine.store.engine.connect() as connection: + return int(await connection.scalar(statement) or 0) + + @staticmethod + def _translate(error: Exception) -> Exception: + """把 zleap-sag2 的异常翻译为带 layer/stage 的领域错误,文案与 ``multi_jev`` 一致;凭据与响应体不进消息。""" + from zleap.sag2 import JevError, SagError + from zleap.sag2.exceptions import ConfigError as Sag2ConfigError + + if isinstance(error, (ConfigurationError, ServiceUnavailableError, ValidationError, UpstreamError)): + return error + if isinstance(error, JevError): + status = error.details.get("status") if isinstance(error.details, dict) else None + if status in (401, 403): + return ConfigurationError(JEV_AUTH_FAILED_MESSAGE, layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE) + # 408/429 与 5xx 由 zleap-sag2 自行重试,耗尽后以“重试用尽”上抛;其余 4xx 是请求本身被拒绝。 + if isinstance(status, int) and 400 <= status < 500 and status not in (408, 429): + return ValidationError(JEV_REQUEST_REJECTED_MESSAGE, layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE) + return ServiceUnavailableError(JEV_UNAVAILABLE_MESSAGE, layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE) + if isinstance(error, Sag2ConfigError): + return ConfigurationError( + "SAG2 证据检索配置无效,请检查 JEV 服务与关系库设置", code=str(error.code), + layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE, + ) + if isinstance(error, SagError): + return UpstreamError( + "SAG2 检索失败,请稍后重试", code=str(error.code), layer=ErrorLayer.ENGINE, + stage=ErrorStage.RETRIEVE, retryable=bool(error.retryable), + ) + if isinstance(error, TimeoutError): + return ServiceUnavailableError( + "SAG2 检索超时,请缩小信源范围或稍后重试", layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE, + ) + return UpstreamError("SAG2 检索失败,请稍后重试", layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE) + + +__all__ = [ + "SAG2_RELATIONAL_PROVIDERS", + "SAG2_STRATEGY", + "Sag2EngineHolder", + "build_sag2_config", + "jev_connection_issue", + "jev_connection_ready", + "outcome_from_result", + "sag2_relational_issue", + "sag2_relational_supported", +] diff --git a/apps/api/sag_api/sag/search_reader.py b/apps/api/sag_api/sag/search_reader.py index 7e9465e8..1b31f754 100644 --- a/apps/api/sag_api/sag/search_reader.py +++ b/apps/api/sag_api/sag/search_reader.py @@ -18,6 +18,7 @@ from sag_api.core.error_taxonomy import ErrorLayer, ErrorStage from sag_api.core.errors import ServiceUnavailableError from sag_api.core.logging import get_logger +from sag_api.enums import JEV_SCORED_STRATEGIES, normalize_search_strategy from sag_api.sag._timings_probe import capture_scope as _timings_capture_scope from sag_api.sag._timings_probe import release_scope as _timings_release_scope from sag_api.sag.dto import RetrievedSection, SearchOutcome @@ -40,6 +41,20 @@ def search_source_timeout_seconds(settings: Settings, strategy: str | None) -> f return timeout +def search_admission_timeout_seconds(settings: Settings, strategy: str | None) -> float | None: + """How long a JEV-scored search may wait for a settings publication before failing. + + ``multi_jev`` reuses its per-source budget; ``sag2`` uses its whole-search budget. + Other modes wait without a deadline, as before. + """ + requested = normalize_search_strategy(strategy or settings.search_strategy) + if requested == "multi_jev": + return search_source_timeout_seconds(settings, strategy) + if requested == "sag2": + return max(1.0, float(settings.sag2_search_timeout_seconds)) + return None + + def _jev_sort_key(section: RetrievedSection) -> tuple[int, float]: """Only compare scores within a scoring channel; JEV evidence comes first.""" channel = section.metadata.get("score_source") @@ -162,6 +177,16 @@ async def search( requested_strategy = strategy or self._access.settings.search_strategy strategy = self._access.effective_search_strategy(strategy) top_k = top_k or self._access.settings.search_top_k + if strategy == "sag2": + # SAG2 不经每源 zleap-sag 引擎;同一只读引擎按范围检索,失败不回退。 + return await self._access.sag2_search( + [(source_config_id, source)], + query, + top_k=top_k, + requested_sources=1, + source_limit_applied=False, + source_ids_by_config=None if source_ids is None else {source_config_id: tuple(source_ids)}, + ) search_options: dict[str, Any] = { "source": source, "top_k": top_k, @@ -253,9 +278,21 @@ async def search_many( per_source_k = max(top_k, 4) requested_sources = len(targets) targets = targets[: self._access.settings.search_source_candidate_limit] + source_limit_applied = requested_sources > len(targets) if source_ids_by_config is not None: targets = [(scid, source) for scid, source in targets if source_ids_by_config.get(scid)] + if strategy == "sag2": + # 一次只读检索覆盖全部目标信源,由 zleap-sag2 给出跨源顺序;任何失败整次报错。 + return await self._access.sag2_search( + targets, + query, + top_k=top_k, + requested_sources=requested_sources, + source_limit_applied=source_limit_applied, + source_ids_by_config=source_ids_by_config, + ) + if strategy == "vector" and not include_ranked_candidates and targets: try: return await self._access.search_chunk_vectors( @@ -299,7 +336,7 @@ async def _one(scid: str, source: Source | None): outcome = await self._access.search(scid, query, **options) return scid, outcome except Exception as e: # noqa: BLE001 - if strategy == "multi_jev": + if strategy in JEV_SCORED_STRATEGIES: raise log.warning("fan-out 检索失败 %s:%s", scid, getattr(e, "message", None) or e) return None diff --git a/apps/api/sag_api/services/agent_domain.py b/apps/api/sag_api/services/agent_domain.py index d2ca35a6..f209c9a8 100644 --- a/apps/api/sag_api/services/agent_domain.py +++ b/apps/api/sag_api/services/agent_domain.py @@ -21,7 +21,7 @@ from sag_api.core.error_taxonomy import ErrorCode from sag_api.core.errors import ConflictError, NotFoundError, ValidationError from sag_api.db.models import Agent, AgentBinding, Message, Source, Thread -from sag_api.enums import BindingTargetType, MessageRole, MessageStatus +from sag_api.enums import JEV_SCORED_STRATEGIES, BindingTargetType, MessageRole, MessageStatus from sag_api.generation import build_agent_messages, build_prompt_preview from sag_api.generation.prompt import estimate_tokens from sag_api.sag import EngineManager @@ -148,8 +148,8 @@ async def create_agent(session: AsyncSession, *, name: str, avatar: str = "", pe name = name.strip() if not name: raise ValidationError("Agent 名称不能为空") - if persona is not None and persona.get("search_strategy") == "multi_jev": - EngineManager.require_jev_capabilities(settings) + if persona is not None and persona.get("search_strategy") in JEV_SCORED_STRATEGIES: + EngineManager.require_jev_capabilities(settings, persona["search_strategy"]) agent = Agent(name=name, avatar=avatar or name[:1], persona=persona or {}) session.add(agent) await session.commit() @@ -166,8 +166,8 @@ async def update_agent( persona: dict | None = None, ) -> Agent: agent = await get_agent(session, agent_id) - if persona is not None and persona.get("search_strategy") == "multi_jev": - EngineManager.require_jev_capabilities(settings) + if persona is not None and persona.get("search_strategy") in JEV_SCORED_STRATEGIES: + EngineManager.require_jev_capabilities(settings, persona["search_strategy"]) if name is not None: agent.name = name if avatar is not None: diff --git a/apps/api/sag_api/services/agent_tooling.py b/apps/api/sag_api/services/agent_tooling.py index d70aca5a..e1706ef4 100644 --- a/apps/api/sag_api/services/agent_tooling.py +++ b/apps/api/sag_api/services/agent_tooling.py @@ -361,6 +361,16 @@ def _adapt_tool(host_tool, host_context: HostToolContext, citations: list[dict]) configuration.agent_tool_timeout_seconds, (waves + 1) * (recall_timeout + MAX_JEV_RANKING_TIMEOUT_SECONDS) + recall_timeout, ) + elif strategy == "sag2": + from sag_api.sag.search_reader import search_admission_timeout_seconds + + # One read-only request covers every source. Its whole-search budget is + # also the settings-publication wait, so allow one of each plus recall. + whole_search = search_admission_timeout_seconds(configuration, strategy) or 0.0 + timeout_seconds = max( + configuration.agent_tool_timeout_seconds, + 2 * whole_search + max(1.0, configuration.search_source_timeout), + ) async def execute( arguments: Mapping[str, Any], diff --git a/apps/api/sag_api/services/retrieval_service.py b/apps/api/sag_api/services/retrieval_service.py index 0aefabe7..a28bb7c8 100644 --- a/apps/api/sag_api/services/retrieval_service.py +++ b/apps/api/sag_api/services/retrieval_service.py @@ -11,7 +11,7 @@ from sag_api.core.config import settings from sag_api.core.logging import get_logger -from sag_api.enums import normalize_search_strategy +from sag_api.enums import JEV_SCORED_STRATEGIES, normalize_search_strategy from sag_api.sag import RetrievedSection, SearchOutcome from sag_api.services.query_analysis import ( QueryAnalysis, @@ -326,9 +326,9 @@ async def retrieve_relevant_sections( configuration = getattr(engine_manager, "_settings", settings) requested_strategy = strategy or configuration.search_strategy mode = normalize_search_strategy(requested_strategy) - if mode == "multi_jev": - # The profile owns recall and final scoring. Adding application lexical - # hits afterwards would mix unscored evidence into the ranked list. + if mode in JEV_SCORED_STRATEGIES: + # The JEV-scored profile owns recall and final scoring. Adding application + # lexical hits afterwards would mix unscored evidence into the ranked list. requested_limit = max(1, min(int(top_k or configuration.search_top_k), 50)) published = await published_document_inputs(sources) visible_sources = [source for source in sources if published.get(source.sag_source_config_id)] diff --git a/apps/api/sag_api/services/settings_service.py b/apps/api/sag_api/services/settings_service.py index f15bdc3a..6e57d9df 100644 --- a/apps/api/sag_api/services/settings_service.py +++ b/apps/api/sag_api/services/settings_service.py @@ -22,7 +22,7 @@ from sag_api.core.logging import get_logger from sag_api.core.model_providers import get_model_provider from sag_api.db.models import Document, Setting -from sag_api.enums import SEARCH_STRATEGIES, normalize_search_strategy +from sag_api.enums import JEV_SCORED_STRATEGIES, SEARCH_STRATEGIES, normalize_search_strategy from sag_api.schemas.system import ModelConfigUpdate _SCOPE = "global" @@ -494,10 +494,10 @@ async def _save_model_config_locked(session: AsyncSession, patch: dict) -> dict: raise ConfigurationError( "Invalid Responses configuration; check endpoint, API version and reasoning options" ) from None - if patch.get("search_strategy") == "multi_jev": + if patch.get("search_strategy") in JEV_SCORED_STRATEGIES: from sag_api.sag.engine_manager import EngineManager - EngineManager.require_jev_capabilities(_settings.model_copy(update=candidate)) + EngineManager.require_jev_capabilities(_settings.model_copy(update=candidate), patch["search_strategy"]) # Credentials belong to their scoring endpoint; a new destination must not # inherit the old secret, including an environment-supplied secret. if str(patch.get("jev_api_key") or "").strip(): @@ -506,6 +506,19 @@ async def _save_model_config_locked(session: AsyncSession, patch: dict) -> dict: stored["jev_endpoint"] = candidate["jev_endpoint"] elif "jev_endpoint" in patch and candidate["jev_endpoint"] != raw.get("jev_endpoint", _settings.jev_endpoint): stored["jev_api_key"] = None + if patch.keys() & {"jev_endpoint", "jev_api_key"}: + # Changing the scoring connection must not leave a paid JEV mode as the default + # without a usable key; the caller either switches mode or supplies the key. + from sag_api.sag.sag2_engine import jev_connection_issue + + final = {**candidate, **{key: stored[key] for key in ("jev_endpoint", "jev_api_key") if key in stored}} + if normalize_search_strategy(str(final["search_strategy"])) in JEV_SCORED_STRATEGIES: + issue = jev_connection_issue(_settings.model_copy(update=final)) + if issue is not None: + code, message = issue + raise ConfigurationError( + f"{message} 当前默认检索模式为 JEV 模式;请先改为其他模式,或补填该服务的 API Key。", code=code, + ) identity = ("llm_provider", "llm_responses_provider", "llm_responses_endpoint") if ( not _settings.lock_llm_config diff --git a/apps/api/sag_api/tools/builtin.py b/apps/api/sag_api/tools/builtin.py index 9bf080bc..86bd35a3 100644 --- a/apps/api/sag_api/tools/builtin.py +++ b/apps/api/sag_api/tools/builtin.py @@ -19,7 +19,7 @@ from sag_api.connectors.web import extract_web_markdown, extract_web_title from sag_api.core.config import settings from sag_api.core.logging import get_logger -from sag_api.enums import SEARCH_STRATEGIES, normalize_search_strategy +from sag_api.enums import JEV_SCORED_STRATEGIES, SEARCH_STRATEGIES, normalize_search_strategy from sag_api.generation import build_citations from sag_api.sag import RetrievedSection from sag_api.services.retrieval_service import ( @@ -80,10 +80,11 @@ def _events_by_section(events: list | None) -> dict[tuple[str, str], list]: def knowledge_search_strategy(persona: dict[str, Any], configuration: Any = settings) -> str: - """Keep the legacy vector default unless the user explicitly enables JEV.""" - default = "multi_jev" if configuration.search_strategy == "multi_jev" else "vector" + """Keep the legacy vector default unless the user explicitly enables a JEV-scored mode.""" + configured = normalize_search_strategy(configuration.search_strategy) + default = configured if configured in JEV_SCORED_STRATEGIES else "vector" value = persona.get("search_strategy") or default - if default == "multi_jev" and ( + if default in JEV_SCORED_STRATEGIES and ( not isinstance(value, str) or normalize_search_strategy(value) not in SEARCH_STRATEGIES ): # The engine falls back to global JEV for unknown modes. Resolve that @@ -260,7 +261,7 @@ async def invoke(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult: strategy=strategy, top_k=limit, ) - is_jev = strategy == "multi_jev" + is_jev = strategy in JEV_SCORED_STRATEGIES if is_jev: outcome = await retrieval event_scores: dict[tuple[str, str], float] = {} @@ -324,7 +325,7 @@ async def invoke(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult: for c in citations: c["n"] = c["n"] + offset content = _format_sections(sections, offset, list(graph.events) if graph is not None else None) - if strategy == "multi_jev" and outcome.stats.get("fallback_used"): + if is_jev and outcome.stats.get("fallback_used"): content = "(JEV 精排未完成,本次返回粗排结果)\n" + content return ToolResult( content=content, diff --git a/apps/api/scripts/eval_retrieval.py b/apps/api/scripts/eval_retrieval.py index 69b054c6..ec6132de 100644 --- a/apps/api/scripts/eval_retrieval.py +++ b/apps/api/scripts/eval_retrieval.py @@ -3,7 +3,7 @@ 用法示例: uv run python scripts/eval_retrieval.py \\ --fixture tests/fixtures/golden_queries.yaml \\ - --strategies vector,multi_es_fast \\ + --strategies vector,multi_es_fast,multi_jev,sag2 \\ --mode both \\ --judge on \\ --out /tmp/eval_report.json diff --git a/apps/api/tests/test_agent_jev_capabilities.py b/apps/api/tests/test_agent_jev_capabilities.py index 93451928..6e806dea 100644 --- a/apps/api/tests/test_agent_jev_capabilities.py +++ b/apps/api/tests/test_agent_jev_capabilities.py @@ -28,21 +28,24 @@ async def skip_unrelated_mcp(_factory, _app): @pytest.mark.parametrize( - ("vector_provider", "endpoint", "expected_code"), + ("vector_provider", "endpoint", "api_key", "expected_code"), [ - ("pgvector", "https://jev.example/score", "vector_provider_lacks_lexical"), - ("pgvector", None, "vector_provider_lacks_lexical"), - ("lancedb", None, "jev_not_configured"), - ("es", None, "jev_not_configured"), + ("pgvector", "https://jev.example/score", "synthetic-jev-key", "vector_provider_lacks_lexical"), + ("pgvector", None, None, "vector_provider_lacks_lexical"), + ("lancedb", None, None, "jev_not_configured"), + ("es", None, None, "jev_not_configured"), + # Paid service: an endpoint without a key is not enough to enable JEV. + ("lancedb", "https://jev.example/score", None, "jev_api_key_missing"), ], ) async def test_unavailable_jev_agent_creation_leaves_no_row( - agent_config_client, monkeypatch, vector_provider, endpoint, expected_code, + agent_config_client, monkeypatch, vector_provider, endpoint, api_key, expected_code, ): client = agent_config_client monkeypatch.setattr(settings, "sag_relational_provider", "postgres") monkeypatch.setattr(settings, "sag_vector_provider", vector_provider) monkeypatch.setattr(settings, "jev_endpoint", endpoint) + monkeypatch.setattr(settings, "jev_api_key", api_key) before = (await client.get("/api/v1/agents")).json() response = await client.post( @@ -67,6 +70,7 @@ async def test_pgvector_rejects_jev_agent_update_without_changing_other_fields(a monkeypatch.setattr(settings, "sag_relational_provider", "postgres") monkeypatch.setattr(settings, "sag_vector_provider", "pgvector") monkeypatch.setattr(settings, "jev_endpoint", "https://jev.example/score") + monkeypatch.setattr(settings, "jev_api_key", "synthetic-jev-key") response = await client.patch( path, json={"name": "Must not persist", "avatar": "X", "persona": {"search_strategy": "multi_jev"}}, @@ -88,6 +92,7 @@ async def test_lexical_backends_allow_creating_and_updating_jev_agents( monkeypatch.setattr(settings, "sag_relational_provider", relational_provider) monkeypatch.setattr(settings, "sag_vector_provider", vector_provider) monkeypatch.setattr(settings, "jev_endpoint", "https://jev.example/score") + monkeypatch.setattr(settings, "jev_api_key", "synthetic-jev-key") created = await client.post( "/api/v1/agents", json={"name": "JEV assistant", "persona": {"search_strategy": "multi_jev"}}, @@ -132,6 +137,7 @@ async def test_pgvector_can_edit_other_fields_and_repair_a_previously_saved_jev_ client = agent_config_client monkeypatch.setattr(settings, "sag_vector_provider", "lancedb") monkeypatch.setattr(settings, "jev_endpoint", "https://jev.example/score") + monkeypatch.setattr(settings, "jev_api_key", "synthetic-jev-key") created = await client.post( "/api/v1/agents", json={"name": "Existing JEV assistant", "persona": {"search_strategy": "multi_jev"}}, ) diff --git a/apps/api/tests/test_agent_tools.py b/apps/api/tests/test_agent_tools.py index f67b9092..e99d7b4b 100644 --- a/apps/api/tests/test_agent_tools.py +++ b/apps/api/tests/test_agent_tools.py @@ -156,7 +156,7 @@ async def test_search_tool_preserves_old_modes_and_only_adds_opted_in_jev( engine = EngineManager(Settings( _env_file=None, search_strategy=global_strategy, sag_vector_provider="lancedb", - jev_endpoint="https://jev.invalid/score", + jev_endpoint="https://jev.invalid/score", jev_api_key="synthetic-jev-key", )) source = await publication_source("compatibility", "config-compatibility", "document-compatibility") selected = [] @@ -187,7 +187,7 @@ def test_unknown_legacy_strategy_gets_jev_budget_after_explicit_global_jev_selec engine = EngineManager(Settings( _env_file=None, search_strategy="multi_jev", sag_vector_provider="lancedb", - jev_endpoint="https://jev.invalid/score", agent_tool_timeout_seconds=5, + jev_endpoint="https://jev.invalid/score", jev_api_key="synthetic-jev-key", agent_tool_timeout_seconds=5, )) adapted = _adapt_tool( SearchContextTool(), diff --git a/apps/api/tests/test_jev_config.py b/apps/api/tests/test_jev_config.py index 6fc56635..ccc5b82f 100644 --- a/apps/api/tests/test_jev_config.py +++ b/apps/api/tests/test_jev_config.py @@ -291,10 +291,22 @@ async def test_lexical_backends_can_enable_jev_and_save_its_endpoint_in_the_same settings.jev_endpoint = None settings.llm_model = "existing-model" settings.llm_api_key = "existing-key" - response = await client.put( + # JEV is a paid service: enabling the mode with an endpoint but no key rejects the whole save. + rejected = await client.put( "/api/v1/system/model-config", headers=headers, json={"search_strategy": "multi_jev", "jev_endpoint": "https://jev.example/score"}, ) + assert rejected.status_code == 400, rejected.text + assert rejected.json()["error"]["code"] == "jev_api_key_missing" + assert settings.search_strategy == "vector" and settings.jev_endpoint is None + + response = await client.put( + "/api/v1/system/model-config", headers=headers, + json={ + "search_strategy": "multi_jev", "jev_endpoint": "https://jev.example/score", + "jev_api_key": "synthetic-jev-key", + }, + ) assert response.status_code == 200, response.text assert response.json()["config"]["search_strategy"] == "multi_jev" @@ -304,7 +316,8 @@ async def test_lexical_backends_can_enable_jev_and_save_its_endpoint_in_the_same async with SessionLocal() as session: row = await session.scalar(select(Setting).where(Setting.scope == "global", Setting.key == "model_config")) assert row.value == { - "search_strategy": "multi_jev", "jev_endpoint": "https://jev.example/score", "jev_api_key": None, + "search_strategy": "multi_jev", "jev_endpoint": "https://jev.example/score", + "jev_api_key": "synthetic-jev-key", } @@ -505,13 +518,15 @@ async def test_jev_draft_checks_protocol_without_mutating_saved_configuration(je assert all(question["type"] == "noul" for question in payload["questions"].values()) assert "synthetic-saved-key" not in response.text + call_count = len(transport.calls) response = await client.post( "/api/v1/system/model-config/jev/test", headers=headers, json={"jev_endpoint": "https://draft.example/score", "jev_api_key": ""}, ) - assert response.json()["ok"] is True # An unauthenticated gateway is supported. - assert transport.calls[-1][0] == "https://draft.example/score" - assert transport.calls[-1][1]["Authorization"] == "Bearer " + # JEV is a paid service: a new endpoint without its own key is rejected before any request. + assert response.json()["ok"] is False + assert "API Key" in response.json()["message"] + assert len(transport.calls) == call_count assert settings.model_dump() == before assert app.state.knowledge_runtime._settings.model_dump() == runtime_before assert len(resets) == reset_count diff --git a/apps/api/tests/test_jev_error_scope.py b/apps/api/tests/test_jev_error_scope.py index 56571698..385e4b61 100644 --- a/apps/api/tests/test_jev_error_scope.py +++ b/apps/api/tests/test_jev_error_scope.py @@ -45,6 +45,7 @@ async def test_reader_classifies_wrapped_timeout_by_actual_request_strategy(monk # The configured default deliberately differs from non-JEV request overrides. manager = EngineManager(Settings(_env_file=None).model_copy(update={ "search_strategy": "multi_jev", "jev_endpoint": "https://jev.invalid/score", + "jev_api_key": "synthetic-jev-key", })) @asynccontextmanager @@ -101,6 +102,7 @@ def test_jev_provider_classification_takes_priority_over_nested_timeout(provider async def test_non_jev_timeout_still_uses_existing_vector_fallback(monkeypatch, strategy): manager = EngineManager(Settings(_env_file=None).model_copy(update={ "search_strategy": "multi_jev", "jev_endpoint": "https://jev.invalid/score", "search_fallback_vector": True, + "jev_api_key": "synthetic-jev-key", })) @asynccontextmanager diff --git a/apps/api/tests/test_jev_retrieval.py b/apps/api/tests/test_jev_retrieval.py index e1d6aa4d..1056cf01 100644 --- a/apps/api/tests/test_jev_retrieval.py +++ b/apps/api/tests/test_jev_retrieval.py @@ -14,6 +14,7 @@ def jev_settings(**changes): return Settings(_env_file=None).model_copy(update={ "jev_endpoint": "https://jev.invalid/score", + "jev_api_key": "synthetic-jev-key", "jev_ranking_timeout_seconds": 30.0, "jev_failure_policy": "error", "sag_vector_provider": "lancedb", @@ -38,6 +39,15 @@ def test_jev_mode_requires_both_connection_and_lexical_capability(): report = manager.strategies_capability_report(manager._settings) assert report["disabled"]["multi_jev"]["reason"] == "jev_not_configured" + # JEV is a paid service: a saved endpoint without a key must not enable any JEV-scored mode. + manager = EngineManager(jev_settings(jev_api_key=None)) + with pytest.raises(ConfigurationError) as error: + manager._effective_search_strategy("multi_jev") + assert error.value.code == "jev_api_key_missing" + report = manager.strategies_capability_report(manager._settings) + assert report["disabled"]["multi_jev"]["reason"] == "jev_api_key_missing" + assert report["disabled"]["sag2"]["reason"] == "jev_api_key_missing" + manager = EngineManager(jev_settings(sag_vector_provider="pgvector")) with pytest.raises(ConfigurationError) as error: manager._effective_search_strategy("multi_jev") diff --git a/apps/api/tests/test_sag2_engine_integration.py b/apps/api/tests/test_sag2_engine_integration.py new file mode 100644 index 00000000..8fcaf900 --- /dev/null +++ b/apps/api/tests/test_sag2_engine_integration.py @@ -0,0 +1,225 @@ +"""Run zleap-sag2 read-only against a real zleap-sag SQLite store with an offline scorer.""" + +import sqlite3 +from types import SimpleNamespace + +import pytest + +from sag_api.core.config import Settings +from sag_api.core.errors import ConfigurationError, ValidationError +from sag_api.sag.sag2_engine import Sag2EngineHolder + +QUERY = "Alice 出生在哪里?" + + +class OverlapScorer: + """Mimic zleap-sag2's ``JevScoring.score`` contract with query-term overlap; no network.""" + + def __init__(self) -> None: + self.calls = 0 + + async def score(self, query, candidates, evidence): + self.calls += 1 + terms = [term for term in ("Alice", "出生", "北京") if term in query] + scored = [] + for candidate in candidates: + text = f"{candidate.get('title', '')} {candidate.get('heading', '')} {candidate.get('content', '')}" + overlap = sum(term in text for term in terms) + scored.append({**candidate, "jev_score": round(min(1.0, 0.1 + 0.3 * overlap), 4)}) + usage = { + "requests": 1, "judgments": len(candidates), "input_tokens": 100 * len(candidates), + "output_tokens": 0, "batches": [{"judgments": len(candidates)}], + } + return scored, usage + + +async def seed_sag_store(data_dir) -> None: + """Create the zleap-sag schema and publish one managed document, one retired generation, one legacy source.""" + from zleap.sag import DataEngine + from zleap.sag.db import models as m + + from sag_api.sag.config_builder import build_engine_config + + config = build_engine_config(Settings(_env_file=None), overrides={"data_dir": str(data_dir)}) + engine = DataEngine(config, data_source_id="cfg-1", health_check=False) + await engine.init_schema() + await engine.start() + try: + factory = engine.resources.relational.session_factory() + async with factory() as session: + session.add(m.DataSource(id="cfg-1", name="demo")) + session.add(m.SAGDataSourceManifest(data_source_id="cfg-1", revision=1, active=True)) + session.add(m.Article( + id="doc1", data_source_id="cfg-1", title="Alice 的生平", + extra_data={"sag_pipeline": {"generation_id": "gen1", "source_type": "article"}}, + )) + session.add(m.SAGSourceManifest( + data_source_id="cfg-1", source_id="doc1", source_type="article", active_generation_id="gen1", + operation_id="op1", fence_scope="cfg-1", fence_token=1, status="ready", + chunk_count=3, event_count=0, revision=1, + )) + rows = [ + ("c1", "gen1", "出生", "Alice 出生在北京,1990 年随家人移居上海。", 0), + ("c2", "gen1", "教育", "Alice 在复旦大学学习计算机科学。", 1), + ("c3", "gen1", "工作", "Bob 是 Alice 的同事。", 2), + ("c0-stale", "gen0", "旧版本", "Alice 出生在广州(已退役版本)。", 0), + ] + for chunk_id, generation, heading, content, rank in rows: + session.add(m.SourceChunk( + id=chunk_id, data_source_id="cfg-1", source_type="article", source_id="doc1", + generation_id=generation, article_id="doc1", content=content, heading=heading, rank=rank, + chunk_length=len(content), references=[], + extra_data={"title": "Alice 的生平", "chunk_type": "TEXT"}, + )) + session.add(m.Article(id="legacy1", data_source_id="cfg-1", title="旧文档")) + session.add(m.SourceChunk( + id="l1", data_source_id="cfg-1", source_type="article", source_id="legacy1", generation_id=None, + article_id="legacy1", content="没有 manifest 的旧来源段落,提到 Alice 喜欢咖啡。", heading="", + rank=0, chunk_length=24, extra_data={}, references=[], + )) + await session.commit() + finally: + await engine.aclose() + + +def sag2_settings(data_dir, **changes) -> Settings: + return Settings(_env_file=None).model_copy(update={ + "data_dir": str(data_dir), + "jev_endpoint": "https://jev.invalid/score", + "jev_api_key": "synthetic-jev-key", + "search_strategy": "sag2", + "sag2_candidate_k": 20, + **changes, + }) + + +async def run_search(holder: Sag2EngineHolder, source_ids_by_config): + return await holder.search( + [("cfg-1", None)], QUERY, top_k=5, requested_sources=1, source_limit_applied=False, + source_ids_by_config=source_ids_by_config, + ) + + +@pytest.mark.asyncio +async def test_sag2_reads_published_sag_chunks_in_place(tmp_path): + await seed_sag_store(tmp_path) + scorer = OverlapScorer() + holder = Sag2EngineHolder(sag2_settings(tmp_path), scorer_factory=lambda _config: scorer) + try: + outcome = await run_search(holder, {"cfg-1": ("doc1", "legacy1")}) + ids = [section.chunk_id for section in outcome.sections] + assert ids[0] == "c1" + assert "c0-stale" not in ids # retired generation stays invisible + assert "l1" in ids # legacy source without a manifest remains searchable + first = outcome.sections[0] + assert (first.source_config_id, first.source_id, first.heading) == ("cfg-1", "doc1", "出生") + assert all(section.metadata["score_source"] == "jev" for section in outcome.sections) + assert outcome.stats["effective_strategy"] == "sag2" + assert outcome.stats["jev_usage"]["judgments"] >= 4 + assert outcome.stats["sag2"]["scope_chunks"] == 4 + assert scorer.calls >= 1 + + # Publication pointers scope the request before scoring. + scoped = await run_search(holder, {"cfg-1": ("doc1",)}) + assert "l1" not in [section.chunk_id for section in scoped.sections] + assert [section.chunk_id for section in scoped.sections][0] == "c1" + + # Read-only attach: only the two auxiliary tables are added to the SAG database. + connection = sqlite3.connect(tmp_path / "sag.db") + try: + names = { + row[0] for row in connection.execute( + "select name from sqlite_master where type='table' and name like 'sag2%'", + ) + } + finally: + connection.close() + assert names == {"sag2_state", "sag2_search_sessions"} + assert holder.started + finally: + await holder.aclose() + assert not holder.started + + +@pytest.mark.asyncio +async def test_sag2_refuses_to_start_on_an_uninitialised_workspace(tmp_path): + holder = Sag2EngineHolder(sag2_settings(tmp_path / "missing")) + with pytest.raises(ConfigurationError) as error: + await run_search(holder, None) + assert error.value.code == "sag2_storage_not_ready" + assert not (tmp_path / "missing" / "sag.db").exists() + + +@pytest.mark.asyncio +async def test_scope_guard_ignores_retired_rows_but_keeps_whole_source_scan_limit(tmp_path): + await seed_sag_store(tmp_path) + with sqlite3.connect(tmp_path / "sag.db") as connection: + # Reprocessing can leave many retired generations awaiting cleanup. + connection.executemany( + "INSERT INTO source_chunk (id, data_source_id, source_id, source_type, generation_id, " + "article_id, content, rank, chunk_length) VALUES (?, 'cfg-1', 'doc1', 'article', " + "'retired', 'doc1', 'retired evidence', 0, 16)", + [(f"retired-{i}",) for i in range(20_001)], + ) + scorer = OverlapScorer() + holder = Sag2EngineHolder(sag2_settings(tmp_path), scorer_factory=lambda _config: scorer) + try: + outcome = await run_search(holder, {"cfg-1": ("doc1",)}) + assert outcome.sections[0].chunk_id == "c1" + assert outcome.stats["sag2"]["scope_chunks"] == 4 + # Selecting one document does not narrow SDK 0.1.0's namespace scan. + holder._settings.sag2_max_scope_chunks = 3 + calls = scorer.calls + with pytest.raises(ValidationError, match="信源扫描范围"): + await run_search(holder, {"cfg-1": ("legacy1",)}) + assert scorer.calls == calls + finally: + await holder.aclose() + + +@pytest.mark.asyncio +@pytest.mark.parametrize("managed", [False, True]) +async def test_scope_count_matches_sdk_loaded_rows_including_legacy_schemas(tmp_path, managed): + from sqlalchemy import create_engine + from sqlalchemy.ext.asyncio import create_async_engine + from zleap.sag2._sag1 import Sag1Reader + + path = tmp_path / "scope.db" + with sqlite3.connect(path) as connection: + connection.execute( + "CREATE TABLE source_chunk (id TEXT, data_source_id TEXT, source_id TEXT, source_type TEXT, " + "content TEXT, rank INTEGER" + (", generation_id TEXT" if managed else "") + ")", + ) + if managed: + connection.execute( + "CREATE TABLE sag_source_manifest (data_source_id TEXT, source_id TEXT, " + "status TEXT, active_generation_id TEXT)", + ) + connection.execute("INSERT INTO sag_source_manifest VALUES ('A', 'doc', 'ready', 'current')") + connection.execute("CREATE TABLE sag_data_source_manifest (data_source_id TEXT, active BOOLEAN)") + connection.execute("INSERT INTO sag_data_source_manifest VALUES ('inactive', 0)") + rows = [("current", "A", "doc", "article", "text", 0), + ("legacy", "A", "legacy", "article", "text", 0), + ("other", "B", "doc", "article", "text", 0)] + if managed: + rows = [(*row, "current" if row[0] == "current" else None) for row in rows] + rows += [("retired", "A", "doc", "article", "text", 0, "old"), + ("staging", "A", "new", "article", "text", 0, "unpublished"), + ("inactive", "inactive", "doc", "article", "text", 0, None)] + connection.executemany("INSERT INTO source_chunk VALUES (" + ",".join("?" * len(rows[0])) + ")", rows) + sync_engine = create_engine(f"sqlite:///{path}") + try: + with sync_engine.connect() as connection: + reader = Sag1Reader.detect(connection) + finally: + sync_engine.dispose() + engine = create_async_engine(f"sqlite+aiosqlite:///{path}") + holder_engine = SimpleNamespace(store=SimpleNamespace(engine=engine, sag1_reader=reader)) + try: + for sources, expected in [(["A"], 2), (["B"], 1), (["inactive"], 0), (["A", "inactive"], 2), ([], 0)]: + async with engine.connect() as connection: + loaded = await reader._rows(connection, "source_chunk", sources) + assert len(loaded) == expected + assert await Sag2EngineHolder._count_scope(holder_engine, sources) == expected + finally: + await engine.dispose() diff --git a/apps/api/tests/test_sag2_retrieval.py b/apps/api/tests/test_sag2_retrieval.py new file mode 100644 index 00000000..45c67b69 --- /dev/null +++ b/apps/api/tests/test_sag2_retrieval.py @@ -0,0 +1,630 @@ +"""Offline contracts for the SAG2 evidence strategy (zleap-sag2 read-only search).""" + +import asyncio +import threading +import time + +import pytest + +from sag_api.core.config import Settings, settings +from sag_api.core.errors import ConfigurationError, ServiceUnavailableError, ValidationError +from sag_api.sag import RetrievedSection, SearchOutcome, SourceGraphInfo +from sag_api.sag.engine_manager import EngineManager +from sag_api.sag.sag2_engine import Sag2EngineHolder, _fingerprint +from tests.test_jev_config import jev_config_client # noqa: F401 - shared settings/API fixture + + +def sag2_settings(**changes): + return Settings(_env_file=None).model_copy(update={ + "jev_endpoint": "https://jev.invalid/score", + "jev_api_key": "synthetic-jev-key", + "sag_vector_provider": "lancedb", + "search_source_timeout": 12.0, + **changes, + }) + + +def hit(chunk, score, *, config="cfg-1", document="document-1"): + return RetrievedSection( + chunk_id=chunk, heading=chunk, content=f"evidence {chunk}", score=score, + source_config_id=config, source_id=document, metadata={"score_source": "jev", "hop": 0}, + ) + + +class _NativeStore: + """A store without the SAG reader: scope counting is skipped.""" + + sag1_reader = None + + +@pytest.mark.parametrize(("changes", "expected"), [ + ({"jev_endpoint": None}, "jev_not_configured"), + ({"jev_api_key": None}, "jev_api_key_missing"), + ({"sag_relational_provider": "mysql"}, "sag2_relational_unsupported"), + ({"sag_relational_provider": "oceanbase"}, "sag2_relational_unsupported"), +]) +def test_sag2_requires_paid_jev_connection_and_supported_relational_store(changes, expected): + manager = EngineManager(sag2_settings(**changes)) + with pytest.raises(ConfigurationError) as error: + manager._effective_search_strategy("sag2") + assert error.value.code == expected + report = manager.strategies_capability_report(manager._settings) + assert report["disabled"]["sag2"]["reason"] == expected + assert "sag2" not in report["enabled"] + + +@pytest.mark.parametrize("relational_provider", [None, "sqlite", "postgres"]) +def test_sag2_is_available_on_sqlite_and_postgres_without_lexical_vectors(relational_provider): + manager = EngineManager(sag2_settings(sag_relational_provider=relational_provider, sag_vector_provider="pgvector")) + assert manager._effective_search_strategy("sag2") == "sag2" + report = manager.strategies_capability_report(manager._settings) + assert "sag2" in report["enabled"] + # The vector store still gates multi_jev; sag2 reads the relational store directly. + assert report["disabled"]["multi_jev"]["reason"] == "vector_provider_lacks_lexical" + + +@pytest.mark.asyncio +async def test_sag2_fanout_is_one_read_only_request_over_published_sources(monkeypatch): + manager = EngineManager(sag2_settings(search_source_candidate_limit=2)) + calls = [] + + async def sag2_search(targets, query, **kwargs): + calls.append((targets, query, kwargs)) + return SearchOutcome(query=query, sections=[hit("a", 0.9), hit("b", 0.8, config="cfg-3")], stats={ + "requested_strategy": "sag2", "effective_strategy": "sag2", "fallback_used": False, + }) + + async def raw(*_args, **_kwargs): + pytest.fail("SAG2 must not run per-source zleap-sag searches") + + monkeypatch.setattr(manager, "_sag2_search", sag2_search) + monkeypatch.setattr(manager, "_search_raw", raw) + result = await manager.search_many( + [("cfg-1", None), ("cfg-2", None), ("cfg-3", None)], "q", strategy="sag2", top_k=5, + source_ids_by_config={"cfg-1": ("d1",), "cfg-2": (), "cfg-3": ("d3",)}, + ) + assert len(calls) == 1 + targets, _query, kwargs = calls[0] + # The candidate limit keeps cfg-1 and cfg-2; cfg-2 has no published input left to search. + assert [scid for scid, _ in targets] == ["cfg-1"] + assert kwargs == { + "top_k": 5, "requested_sources": 3, "source_limit_applied": True, + "source_ids_by_config": {"cfg-1": ("d1",), "cfg-2": (), "cfg-3": ("d3",)}, + } + assert [section.chunk_id for section in result.sections] == ["a", "b"] + assert result.stats["effective_strategy"] == "sag2" + + +@pytest.mark.asyncio +async def test_sag2_single_source_search_never_falls_back_to_vector(monkeypatch): + manager = EngineManager(sag2_settings(search_fallback_vector=True)) + calls = [] + + async def sag2_search(targets, query, **kwargs): + calls.append((targets, kwargs)) + raise RuntimeError("scorer unavailable") + + async def raw(*_args, **_kwargs): + pytest.fail("SAG2 has no vector fallback") + + monkeypatch.setattr(manager, "_sag2_search", sag2_search) + monkeypatch.setattr(manager, "_search_raw", raw) + with pytest.raises(RuntimeError, match="scorer unavailable"): + await manager.search("cfg-1", "q", strategy="sag2", source_ids=("d1",)) + assert calls == [([("cfg-1", None)], { + "top_k": settings.search_top_k, "requested_sources": 1, "source_limit_applied": False, + "source_ids_by_config": {"cfg-1": ("d1",)}, + })] + + +@pytest.mark.asyncio +async def test_holder_builds_scope_and_options_and_preserves_engine_order(monkeypatch): + from zleap.sag2 import SearchHit, SearchResult + + holder = Sag2EngineHolder(sag2_settings( + sag2_candidate_k=40, sag2_seed_k=5, sag2_max_hops=1, sag2_expansion_term_limit=7, + )) + captured = [] + + class Engine: + store = _NativeStore() + + async def search(self, request): + captured.append(request) + return SearchResult( + query=request.query, original_query=request.query, snapshot_revision=7, + chunks=( + SearchHit(id="c-low", chunk_id="c-low", data_source_id="cfg-2", source_id="d3", + title="Title", heading="Heading", content="low", score=0.2, hop=1), + SearchHit(id="c-high", chunk_id="c-high", data_source_id="cfg-1", source_id="d1", + title="Title", heading="", content="high", score=0.9, hop=0), + ), + trace=({"stage": "bm25", "hop": 0, "count": 2}, {"stage": "jev", "hop": 0, "count": 2}), + usage={"requests": 2, "judgments": 4, "input_tokens": 1234, "output_tokens": None, "batches": []}, + elapsed_ms=12.5, local_ms=2.5, jev_ms=10.0, + ) + + async def engine(): + return Engine() + + async def count(_engine, data_source_ids): + return 3 * len(data_source_ids) + + monkeypatch.setattr(holder, "engine", engine) + monkeypatch.setattr(holder, "_count_scope", count) + outcome = await holder.search( + [("cfg-1", None), ("cfg-2", None)], "q", top_k=5, requested_sources=2, source_limit_applied=False, + source_ids_by_config={"cfg-1": ("d2", "d1"), "cfg-2": ("d3",)}, + ) + request = captured[0] + assert request.scope.data_source_ids == ("cfg-1", "cfg-2") + assert request.scope.source_ids == ("d1", "d2", "d3") + option_fields = {"candidate_k", "seed_k", "max_hops", "expansion_term_limit", "top_k"} + assert request.options.model_dump(include=option_fields) == { + "candidate_k": 40, "seed_k": 5, "max_hops": 1, "expansion_term_limit": 7, "top_k": 5, + } + # The engine order wins over raw score order; scores stay the raw JEV values. + assert [(s.chunk_id, s.score, s.rank, s.source_config_id, s.source_id) for s in outcome.sections] == [ + ("c-low", 0.2, 0, "cfg-2", "d3"), ("c-high", 0.9, 1, "cfg-1", "d1"), + ] + assert [s.metadata for s in outcome.sections] == [ + {"score_source": "jev", "hop": 1}, {"score_source": "jev", "hop": 0}, + ] + assert outcome.sections[1].heading == "Title" + assert outcome.stats["requested_strategy"] == outcome.stats["effective_strategy"] == "sag2" + assert outcome.stats["fallback_used"] is False + assert outcome.stats["ranking"] == {"method": "jev", "fallback_reason": None} + assert outcome.stats["jev_usage"] == {"requests": 2, "judgments": 4, "input_tokens": 1234, "output_tokens": None} + assert outcome.stats["sag2"]["snapshot_revision"] == 7 + assert outcome.stats["sag2"]["scope_chunks"] == 6 + assert outcome.stats["sag2"]["hops"] == [ + {"stage": "bm25", "hop": 0, "count": 2}, {"stage": "jev", "hop": 0, "count": 2}, + ] + assert outcome.stats["sources"] == 2 and outcome.stats["candidates"] == 2 + + unscoped = await holder.search( + [("cfg-1", None)], "q", top_k=3, requested_sources=1, source_limit_applied=False, source_ids_by_config=None, + ) + assert captured[1].scope.source_ids is None + assert len(unscoped.sections) == 2 + + empty = await holder.search( + [("cfg-1", None)], "q", top_k=3, requested_sources=1, source_limit_applied=False, + source_ids_by_config={"cfg-1": ()}, + ) + assert empty.sections == [] and empty.stats["candidates"] == 0 and len(captured) == 2 + + +@pytest.mark.asyncio +async def test_holder_rejects_scopes_above_chunk_limit_before_scoring(monkeypatch): + holder = Sag2EngineHolder(sag2_settings(sag2_max_scope_chunks=100)) + + class Engine: + store = _NativeStore() + + async def search(self, request): + pytest.fail("An oversized scope must not reach the paid scorer") + + async def engine(): + return Engine() + + async def count(_engine, _data_source_ids): + return 101 + + monkeypatch.setattr(holder, "engine", engine) + monkeypatch.setattr(holder, "_count_scope", count) + with pytest.raises(ValidationError, match="SAG2"): + await holder.search( + [("cfg-1", None)], "q", top_k=3, requested_sources=1, source_limit_applied=False, source_ids_by_config=None, + ) + + +@pytest.mark.asyncio +async def test_holder_timeout_is_a_retryable_service_error(monkeypatch): + configuration = sag2_settings() + configuration.sag2_search_timeout_seconds = 0.05 + holder = Sag2EngineHolder(configuration) + + async def run(*_args, **_kwargs): + await asyncio.sleep(1) + + monkeypatch.setattr(holder, "_run", run) + with pytest.raises(ServiceUnavailableError) as error: + await holder.search( + [("cfg-1", None)], "q", top_k=3, requested_sources=1, source_limit_applied=False, source_ids_by_config=None, + ) + assert error.value.retryable is True + + +@pytest.mark.asyncio +async def test_holder_limits_concurrent_paid_searches(monkeypatch): + from zleap.sag2 import SearchResult + + holder = Sag2EngineHolder(sag2_settings(sag2_max_concurrent_searches=1)) + active = peak = 0 + + class Engine: + store = _NativeStore() + + async def search(self, request): + nonlocal active, peak + active += 1 + peak = max(peak, active) + await asyncio.sleep(0.01) + active -= 1 + return SearchResult(query=request.query, original_query=request.query) + + async def engine(): + return Engine() + + async def count(_engine, _data_source_ids): + return 1 + + monkeypatch.setattr(holder, "engine", engine) + monkeypatch.setattr(holder, "_count_scope", count) + await asyncio.gather(*( + holder.search([("cfg-1", None)], "q", top_k=3, requested_sources=1, source_limit_applied=False, + source_ids_by_config=None) + for _ in range(3) + )) + assert peak == 1 + + +@pytest.mark.asyncio +async def test_refresh_rebuilds_lazily_only_when_connection_or_storage_changes(monkeypatch): + configuration = sag2_settings() + holder = Sag2EngineHolder(configuration) + closed, started = [], [] + + class Engine: + def __init__(self, name): + self.name = name + + async def aclose(self): + closed.append(self.name) + + async def start(settings): + started.append(settings.jev_api_key) + return Engine(settings.jev_api_key) + + monkeypatch.setattr(holder, "_start", start) + holder._engine, holder._fingerprint = Engine("synthetic-jev-key"), _fingerprint(configuration) + await holder.refresh(configuration.model_copy(update={"search_top_k": 20, "sag2_candidate_k": 30})) + assert holder.started and not holder.stale and not closed + assert (await holder.engine()).name == "synthetic-jev-key" and started == [] + + # A connection change keeps the running engine for in-flight searches and rebuilds on the next call. + await holder.refresh(configuration.model_copy(update={"jev_api_key": "rotated-key"})) + assert holder.started and holder.stale and closed == [] + rebuilt = await holder.engine() + assert rebuilt.name == "rotated-key" and started == ["rotated-key"] and closed == ["synthetic-jev-key"] + assert not holder.stale + + await holder.aclose() + assert closed == ["synthetic-jev-key", "rotated-key"] and not holder.started + + +@pytest.mark.asyncio +async def test_refresh_applies_new_concurrency_limit_without_dropping_inflight_searches(monkeypatch): + from zleap.sag2 import SearchResult + + configuration = sag2_settings(sag2_max_concurrent_searches=1) + holder = Sag2EngineHolder(configuration) + # The engine runs on the holder's dedicated loop thread, so signal across threads. + release, first_running = threading.Event(), threading.Event() + active = peak = 0 + + class Engine: + async def search(self, request): + nonlocal active, peak + active += 1 + peak = max(peak, active) + first_running.set() + await asyncio.to_thread(release.wait, 5) + active -= 1 + return SearchResult(query=request.query, original_query=request.query) + + async def engine(): + return Engine() + + async def count(_engine, _data_source_ids): + return 1 + + monkeypatch.setattr(holder, "engine", engine) + monkeypatch.setattr(holder, "_count_scope", count) + + def run(): + return asyncio.create_task(holder.search( + [("cfg-1", None)], "q", top_k=3, requested_sources=1, source_limit_applied=False, source_ids_by_config=None, + )) + + first, second = run(), run() + assert await asyncio.to_thread(first_running.wait, 1) + await asyncio.sleep(0.05) + assert active == 1 # the second search queues behind the limit of 1 + await holder.refresh(configuration.model_copy(update={"sag2_max_concurrent_searches": 2})) + await asyncio.sleep(0.05) + assert active == 2 # the raised limit admits the queued search; the first keeps running + release.set() + await asyncio.gather(first, second) + assert peak == 2 + await holder.aclose() + + +@pytest.mark.asyncio +async def test_engine_work_runs_off_the_api_loop_and_timeouts_cancel_it(monkeypatch): + from zleap.sag2 import SearchResult + + holder = Sag2EngineHolder(sag2_settings()) + cancelled = threading.Event() + + class Engine: + async def search(self, request): + if request.query == "block": + time.sleep(0.3) # synchronous corpus build: must not stall the API loop + return SearchResult(query=request.query, original_query=request.query) + try: + await asyncio.sleep(5) + except asyncio.CancelledError: + cancelled.set() + raise + return SearchResult(query=request.query, original_query=request.query) + + async def engine(): + return Engine() + + async def count(_engine, _data_source_ids): + return 1 + + monkeypatch.setattr(holder, "engine", engine) + monkeypatch.setattr(holder, "_count_scope", count) + + def run(query): + return holder.search( + [("cfg-1", None)], query, top_k=3, requested_sources=1, source_limit_applied=False, + source_ids_by_config=None, + ) + + # While the engine blocks its own thread, the API loop keeps ticking. + ticks = 0 + + async def ticker(): + nonlocal ticks + for _ in range(10): + await asyncio.sleep(0.02) + ticks += 1 + + await asyncio.gather(run("block"), ticker()) + assert ticks == 10 + assert threading.current_thread() is threading.main_thread() + + # The whole-search timeout cancels the coroutine inside the dedicated loop. + holder._settings.sag2_search_timeout_seconds = 1.0 + with pytest.raises(ServiceUnavailableError): + await run("hang") + assert cancelled.wait(1) + assert holder._gate.active == 0 + await holder.aclose() + assert holder._loop is None + + +@pytest.mark.parametrize(("status", "expected_type", "expected_message"), [ + (401, ConfigurationError, "JEV 鉴权失败,请检查服务地址和 API Key"), + (403, ConfigurationError, "JEV 鉴权失败,请检查服务地址和 API Key"), + (422, ValidationError, "JEV 精排请求被拒绝,请检查模型和候选内容限制"), + (429, ServiceUnavailableError, "JEV 精排服务暂不可用,请稍后重试"), + (None, ServiceUnavailableError, "JEV 精排服务暂不可用,请稍后重试"), +]) +def test_sag2_jev_errors_translate_like_multi_jev(status, expected_type, expected_message): + from zleap.sag2 import JevError + + from sag_api.core.errors import ApiError + + error = JevError("JEV rejected the request", details={} if status is None else {"status": status}) + translated = Sag2EngineHolder._translate(error) + assert isinstance(translated, expected_type) + assert translated.message == expected_message + assert translated.code == expected_type.code # no sag2-specific codes for shared JEV failures + assert translated.layer.value == "engine" and translated.stage.value == "retrieve" + assert isinstance(translated, ApiError) + + +@pytest.mark.asyncio +async def test_sag2_configuration_admission_times_out_without_starting_or_leaking_reader(monkeypatch): + manager = EngineManager(sag2_settings().model_copy(update={"sag2_search_timeout_seconds": 0.05})) + started = [] + + async def sag2_search(targets, query, **kwargs): + started.append([scid for scid, _ in targets]) + return SearchOutcome(query=query, sections=[hit("ranked", 0.9)], stats={"effective_strategy": "sag2"}) + + monkeypatch.setattr(manager, "_sag2_search", sag2_search) + async with manager._search_configuration_gate.write(): + with pytest.raises(ServiceUnavailableError) as error: + await asyncio.wait_for(manager.search_many([("blocked", None)], "q", strategy="sag2"), timeout=1.5) + assert error.value.retryable is True + assert error.value.layer.value == "engine" and error.value.stage.value == "retrieve" + assert started == [] + + result = await asyncio.wait_for(manager.search_many([("after-release", None)], "q", strategy="sag2"), timeout=1) + assert result.sections[0].chunk_id == "ranked" + assert started == [["after-release"]] + # A leaked admission reader would prevent a later settings write forever. + await asyncio.wait_for(manager.apply_settings(sag2_settings(), reset_engines=False), timeout=1) + + +@pytest.mark.asyncio +async def test_settings_wait_for_whole_sag2_search_before_publishing(monkeypatch): + manager = EngineManager(sag2_settings(sag2_candidate_k=50)) + updated = sag2_settings(jev_endpoint="https://new-jev.invalid/score", sag2_candidate_k=70) + search_started, release_search, update_started = asyncio.Event(), asyncio.Event(), asyncio.Event() + observed = [] + + async def sag2_search(targets, query, **kwargs): + observed.append((manager._settings.jev_endpoint, manager._settings.sag2_candidate_k)) + search_started.set() + await release_search.wait() + return SearchOutcome(query=query, sections=[hit("ranked", 0.9)], stats={"effective_strategy": "sag2"}) + + async def save(): + update_started.set() + await manager.apply_settings(updated, reset_engines=True) + + monkeypatch.setattr(manager, "_sag2_search", sag2_search) + query_task = asyncio.create_task(manager.search_many([("cfg-1", None), ("cfg-2", None)], "q", strategy="sag2")) + await asyncio.wait_for(search_started.wait(), timeout=1) + save_task = asyncio.create_task(save()) + try: + await asyncio.wait_for(update_started.wait(), timeout=1) + await asyncio.sleep(0.05) + assert not save_task.done(), "settings must wait for the whole SAG2 search" + release_search.set() + await asyncio.wait_for(query_task, timeout=1) + await asyncio.wait_for(save_task, timeout=1) + await manager.search_many([("cfg-3", None)], "q", strategy="sag2") + finally: + release_search.set() + for task in (query_task, save_task): + if not task.done(): + task.cancel() + await asyncio.gather(query_task, save_task, return_exceptions=True) + assert observed == [("https://jev.invalid/score", 50), ("https://new-jev.invalid/score", 70)] + + +@pytest.mark.asyncio +async def test_sag2_business_path_preserves_engine_order_limit_and_publication(publication_source): + from sag_api.services import retrieval_service + + source = await publication_source("sag2-business", "cfg-1", "document-1") + + class Engine: + _settings = sag2_settings(search_strategy="sag2") + + async def search_many(self, targets, query, **kwargs): + assert kwargs["strategy"] == "sag2" + assert kwargs["source_ids_by_config"] == {"cfg-1": ("document-1",)} + return SearchOutcome(query=query, sections=[ + hit("unpublished", 1.0, document="hidden"), hit("first", 0.21), hit("second", 0.2), hit("third", 0.19), + ], stats={"effective_strategy": "sag2", "ranking": {"method": "jev", "fallback_reason": None}}) + + async def grep_chunks(self, *args, **kwargs): + pytest.fail("SAG2 must not add unranked application lexical candidates") + + result = await retrieval_service.retrieve_relevant_sections(Engine(), [source], "q", top_k=2) + assert [section.chunk_id for section in result.sections] == ["first", "second"] + assert [section.score for section in result.sections] == [0.21, 0.2] + assert result.stats["requested_strategy"] == "sag2" + assert result.stats["publication_filtered"] == 1 + assert result.stats["lexical_candidates"] == 0 + + +@pytest.mark.asyncio +async def test_agent_follows_global_sag2_and_gets_whole_search_budget(monkeypatch, publication_source): + from sag_api.services.agent_tooling import _adapt_tool + from sag_api.tools import builtin + from sag_api.tools.base import ToolContext + + source = await publication_source("sag2-agent", "cfg-1", "document-1") + engine = EngineManager(sag2_settings( + search_strategy="sag2", agent_tool_timeout_seconds=5, sag2_search_timeout_seconds=90, + )) + calls = [] + + async def retrieve(manager, sources, query, *, strategy, top_k): + calls.append(strategy) + assert manager._effective_search_strategy(strategy) == "sag2" + return SearchOutcome(query=query, sections=[hit("first", 0.2), hit("second", 0.1)], stats={ + "effective_strategy": "sag2", "ranking": {"method": "jev", "fallback_reason": None}, + }) + + async def graph(sections, _sources, **kwargs): + assert sections == [] + return SourceGraphInfo(events=[]) + + async def events(*args, **kwargs): + pytest.fail("Independent event recall must not change SAG2 evidence") + + async def reorder(*args, **kwargs): + pytest.fail("SAG2 evidence must retain its engine order") + + engine.graph_for_sections = graph + monkeypatch.setattr(builtin, "retrieve_relevant_sections", retrieve) + monkeypatch.setattr(builtin, "recall_event_scores", events) + monkeypatch.setattr(builtin, "_prioritize_event_evidence", reorder) + result = await builtin.SearchContextTool().invoke( + {"query": "q"}, ToolContext(engine_manager=engine, sources=[source], persona={}), + ) + assert calls == ["sag2"] + assert [section.chunk_id for section in result.data["sections"]] == ["first", "second"] + assert result.data["retrieval_stats"]["effective_strategy"] == "sag2" + + adapted = _adapt_tool(builtin.SearchContextTool(), ToolContext(engine_manager=engine, persona={}), []) + assert adapted.spec.timeout_seconds is not None + assert adapted.spec.timeout_seconds >= 90 + 12 + + +async def test_saving_sag2_default_requires_key_and_supported_relational_store(jev_config_client): # noqa: F811 + client, headers, _resets = jev_config_client + settings.sag_relational_provider = None + settings.sag_vector_provider = "pgvector" + settings.search_strategy = "vector" + settings.jev_endpoint = None + settings.jev_api_key = None + + rejected = await client.put( + "/api/v1/system/model-config", headers=headers, + json={"search_strategy": "sag2", "jev_endpoint": "https://jev.example/score"}, + ) + assert rejected.status_code == 400, rejected.text + assert rejected.json()["error"]["code"] == "jev_api_key_missing" + assert settings.search_strategy == "vector" and settings.jev_endpoint is None + + accepted = await client.put( + "/api/v1/system/model-config", headers=headers, + json={ + "search_strategy": "sag2", "jev_endpoint": "https://jev.example/score", + "jev_api_key": "synthetic-jev-key", + }, + ) + assert accepted.status_code == 200, accepted.text + body = accepted.json() + assert body["config"]["search_strategy"] == "sag2" + assert body["config"]["jev_api_key_set"] is True + assert "sag2" in body["capabilities"]["search_strategies"] + assert body["capabilities"]["search_strategies_disabled"]["multi_jev"]["reason"] == "vector_provider_lacks_lexical" + + settings.sag_relational_provider = "mysql" + unsupported = await client.put( + "/api/v1/system/model-config", headers=headers, json={"search_strategy": "sag2"}, + ) + assert unsupported.status_code == 400, unsupported.text + assert unsupported.json()["error"]["code"] == "sag2_relational_unsupported" + settings.sag_relational_provider = None + + # Changing the endpoint clears its key; with sag2 still the default that must be rejected. + cleared = await client.put( + "/api/v1/system/model-config", headers=headers, json={"jev_endpoint": "https://other.example/score"}, + ) + assert cleared.status_code == 400, cleared.text + assert cleared.json()["error"]["code"] == "jev_api_key_missing" + assert settings.jev_endpoint == "https://jev.example/score" and settings.jev_api_key == "synthetic-jev-key" + assert settings.search_strategy == "sag2" + + # Supplying the new endpoint's key in the same save keeps the paid default usable. + rotated = await client.put( + "/api/v1/system/model-config", headers=headers, + json={"jev_endpoint": "https://other.example/score", "jev_api_key": "other-key"}, + ) + assert rotated.status_code == 200, rotated.text + assert settings.jev_endpoint == "https://other.example/score" and settings.jev_api_key == "other-key" + + # With a non-JEV default the endpoint may change freely and its key is cleared. + assert (await client.put( + "/api/v1/system/model-config", headers=headers, json={"search_strategy": "vector"}, + )).status_code == 200 + freed = await client.put( + "/api/v1/system/model-config", headers=headers, json={"jev_endpoint": "https://third.example/score"}, + ) + assert freed.status_code == 200, freed.text + assert freed.json()["config"]["jev_api_key_set"] is False + assert freed.json()["capabilities"]["search_strategies_disabled"]["sag2"]["reason"] == "jev_api_key_missing" diff --git a/apps/api/uv.lock b/apps/api/uv.lock index c270c62d..5d8b9016 100644 --- a/apps/api/uv.lock +++ b/apps/api/uv.lock @@ -1,5 +1,5 @@ version = 1 -revision = 5 +revision = 3 requires-python = ">=3.11" resolution-markers = [ "python_full_version >= '3.14' and sys_platform == 'win32'", @@ -1266,13 +1266,10 @@ wheels = [ ] [[package]] -name = "jieba-py" -version = "0.46.12" +name = "jieba" +version = "0.42.1" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/6a/03/f940a9f8fc2441ef1175369c01726add656dc55fea9edf1421733467050d/jieba_py-0.46.12.tar.gz", hash = "sha256:c74a4ecf7e579c00915feeefd40e54450c1616ddfa18497cb0d42563f7e4eb97", size = 5310676, upload-time = "2026-04-20T23:27:27.077Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/f3/26/b7bbcedc1bfa49fe44d71233819deb95026f13ed10936a175c6b2f8a0f05/jieba_py-0.46.12-py3-none-any.whl", hash = "sha256:a4f616b571cbb2f3668608973bcd882a04e2faa94b95338acbbddf3cbe111930", size = 5403721, upload-time = "2026-04-20T23:27:18.386Z" }, -] +sdist = { url = "https://files.pythonhosted.org/packages/c6/cb/18eeb235f833b726522d7ebed54f2278ce28ba9438e3135ab0278d9792a2/jieba-0.42.1.tar.gz", hash = "sha256:055ca12f62674fafed09427f176506079bc135638a14e23e25be909131928db2", size = 19214172, upload-time = "2020-01-20T14:27:23.5Z" } [[package]] name = "jinja2" @@ -1633,7 +1630,7 @@ name = "macholib" version = "1.16.4" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "altgraph" }, + { name = "altgraph", marker = "sys_platform != 'win32'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/10/2f/97589876ea967487978071c9042518d28b958d87b17dceb7cdc1d881f963/macholib-1.16.4.tar.gz", hash = "sha256:f408c93ab2e995cd2c46e34fe328b130404be143469e41bc366c807448979362", size = 59427, upload-time = "2025-11-22T08:28:38.373Z" } wheels = [ @@ -3006,6 +3003,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/ec/dd/96da98f892250475bdf2328112d7468abdd4acc7b902b6af23f4ed958ea0/pytz-2026.2-py2.py3-none-any.whl", hash = "sha256:04156e608bee23d3792fd45c94ae47fae1036688e75032eea2e3bf0323d1f126", size = 510141, upload-time = "2026-05-04T01:35:27.408Z" }, ] +[[package]] +name = "pyuca" +version = "1.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/30/32/95beca7e3308581c6da4735c7102b0c0cbb30a6b863cc1a8e44e6d2f5c3c/pyuca-1.2.tar.gz", hash = "sha256:8a382fe74627f08c0d18908c0713ca4a20aad5385f077579e56208beea2893b2", size = 1398641, upload-time = "2017-09-25T23:12:12.163Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/98/88/aeeee34d88f841aca712a8c18fbd62a33eaad8f2dbe535e87f3c829b02f9/pyuca-1.2-py2.py3-none-any.whl", hash = "sha256:abaa12e1bd2c7c68ca8396ff8383bc0654a739cef3ae68fd7af58bf29af0a91e", size = 1464896, upload-time = "2017-09-25T23:12:15.67Z" }, +] + [[package]] name = "pywin32" version = "312" @@ -3108,106 +3114,122 @@ wheels = [ [[package]] name = "regex" -version = "2026.7.10" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/7b/37/451aaddbf50922f34d744ad5ca919ae1fcfac112123885d9728f52a484b3/regex-2026.7.10.tar.gz", hash = "sha256:1050fedf0a8a92e843971120c2f57c3a99bea86c0dfa1d63a9fac053fe54b135", size = 416282, upload-time = "2026-07-10T19:49:46.267Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/3d/16/bfd13770be1acd1c05506b93fc6be15c759d6417595d1ba334d355efbf26/regex-2026.7.10-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:66d2c35587cd601c95965d5c0415058ba5cfd6ffbab7624ce198bd967102b341", size = 494639, upload-time = "2026-07-10T19:46:52.207Z" }, - { url = "https://files.pythonhosted.org/packages/e6/b4/0086215709f0f705661f13ba81516287538886ef0d589c545c12b0484669/regex-2026.7.10-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:28a0973eeffff4292f5a7ee498ab65d5e94ee8cc9cea364239251eb4a260a0f1", size = 295920, upload-time = "2026-07-10T19:46:53.63Z" }, - { url = "https://files.pythonhosted.org/packages/8e/9e/8e07d0eea46d2cf36bf4d3794634bb0a820f016d31bc349dfef008d96b02/regex-2026.7.10-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:8331484450b3894298bef8abecce532171ff6ac60b71f999eed10f2c01941a8a", size = 290673, upload-time = "2026-07-10T19:46:54.863Z" }, - { url = "https://files.pythonhosted.org/packages/b7/56/d83c446de21c70ff49d2f1b2ff2196ac79a4ac6373d2cfe496011a250600/regex-2026.7.10-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0639b2488b775a0109f55a5a2172deebdedb4b6c5ab0d48c90b43cbf5de58d17", size = 792378, upload-time = "2026-07-10T19:46:56.116Z" }, - { url = "https://files.pythonhosted.org/packages/dc/0e/d265e0cc6da47aea97e90eb896be2d2e8f92d16add13bac04fa46a0fd972/regex-2026.7.10-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:be4223af640d0aa04c05db81d5d96ada3ead9c09187d892fd37f4f97829480be", size = 861790, upload-time = "2026-07-10T19:46:57.611Z" }, - { url = "https://files.pythonhosted.org/packages/b4/a5/62655f6208d1170a3e9188d6a45d4af0a5ae3b9da8b87d474818ac5ff016/regex-2026.7.10-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d3c75d57a00109255e60bc9c623b6ececaf7905eaab845c79f036670ed4750a2", size = 906530, upload-time = "2026-07-10T19:46:59.142Z" }, - { url = "https://files.pythonhosted.org/packages/86/b7/d65aa2e9ffb18677cd0afbcf5990da8519a4e50778deb1bca49f043c5174/regex-2026.7.10-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:724ee9379568658ec06362cf24325c5315cc5a67f61dfe585bfeff58300a355b", size = 799912, upload-time = "2026-07-10T19:47:00.534Z" }, - { url = "https://files.pythonhosted.org/packages/8f/19/3a5ce23ea2eb1fe36306aef49c79746ce297e4b434aeb981b525c661413a/regex-2026.7.10-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:732c19e5828eb287d01edb83b2eb87f283ba8e5fc3441c732709d3e8cbd14aaa", size = 773675, upload-time = "2026-07-10T19:47:01.999Z" }, - { url = "https://files.pythonhosted.org/packages/fe/76/3c0eaa426700dd2ba14f2335f2b700a4e1484202254192ae440b83b8352a/regex-2026.7.10-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:982d07727c809b42a3968785354f11c3728414e4e90af0754345b431b2c32561", size = 781711, upload-time = "2026-07-10T19:47:03.425Z" }, - { url = "https://files.pythonhosted.org/packages/a4/a8/a5a3fad84f9a7f897619f0f8e0a2c64946e9709044a186a8f869fb5c332f/regex-2026.7.10-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:4574feca202f8c470bf678aed8b5d89df04aaf8dc677f3b83d92825051301c0f", size = 854539, upload-time = "2026-07-10T19:47:04.999Z" }, - { url = "https://files.pythonhosted.org/packages/f8/c7/47e9b8c8ee77723b9eda74f517b6b25d2f555cf276c063a9eeea35bd86d5/regex-2026.7.10-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:80151ca5bfc6c4524186b3e08b499e97319b2001fc265ed2d4fc12c0d5692cdf", size = 763378, upload-time = "2026-07-10T19:47:06.845Z" }, - { url = "https://files.pythonhosted.org/packages/36/09/e27e42d9d42edf71205c7e6f5b2902bc874ea03c557c80da03b8ed16c9bf/regex-2026.7.10-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:bb52e10e453b5493afe1f7702a2973bc10f4dd8901c0f2ed869ffaa3f8319296", size = 844663, upload-time = "2026-07-10T19:47:08.923Z" }, - { url = "https://files.pythonhosted.org/packages/a1/b5/2423acb98362184ad9c8eebabafa15188d6a177daab919add8f2120fc6cd/regex-2026.7.10-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:e37aba1994d73b4944053ab65a15f313bd5c28c885dd7f0d494a11749d89db6e", size = 789236, upload-time = "2026-07-10T19:47:10.303Z" }, - { url = "https://files.pythonhosted.org/packages/60/ed/b387e84c8a3d6aa115dfb56865437a3fbaf28f4a6fb3b76cc6cce38ced70/regex-2026.7.10-cp311-cp311-win32.whl", hash = "sha256:6cbedeb5112f59dbd169385459b9943310bdd241c6966c19c5f6e2295055c93a", size = 266774, upload-time = "2026-07-10T19:47:11.904Z" }, - { url = "https://files.pythonhosted.org/packages/c4/64/f30a163a65ed1f07ad12c53af00a6bd2a7251a5329fba5a08adc6f9e81a3/regex-2026.7.10-cp311-cp311-win_amd64.whl", hash = "sha256:b1963ec5ba4d52788fb0eac6aca6eb8040e8e318c7e47ebbdfc09440c802919c", size = 277959, upload-time = "2026-07-10T19:47:13.231Z" }, - { url = "https://files.pythonhosted.org/packages/2b/de/61c8174171134cebb834ca9f8fe2ff8f49d8a3dd43453b48b537d0fbb49b/regex-2026.7.10-cp311-cp311-win_arm64.whl", hash = "sha256:3750c42d47712e362158a04d0fd80131f73a55e8c715b2885442a0ff6f9fc3fc", size = 276918, upload-time = "2026-07-10T19:47:14.693Z" }, - { url = "https://files.pythonhosted.org/packages/b3/9c/2503d4ccf3452dc323f8baa3cf3ee10406037d52735c76cfced81423f183/regex-2026.7.10-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:7252b48b0c60100095088fbeb281fca9a4fcf678a4e04b1c520c3f8613c952c4", size = 497114, upload-time = "2026-07-10T19:47:16.22Z" }, - { url = "https://files.pythonhosted.org/packages/91/eb/04534f4263a4f658cd20a511e9d6124350044f2214eb24fee2db96acf318/regex-2026.7.10-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:da6ef4cb8d457aab0482b50120136ae94238aaa421863eaa7d599759742c72d6", size = 297422, upload-time = "2026-07-10T19:47:17.794Z" }, - { url = "https://files.pythonhosted.org/packages/ca/2d/35809de392ab66ba439b58c3187ae3b8b53c883233f284b59961e5725c99/regex-2026.7.10-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:fe7ff456c22725c9d9017f7a2a7df2b51af6df77314176760b22e2d05278e181", size = 292110, upload-time = "2026-07-10T19:47:19.188Z" }, - { url = "https://files.pythonhosted.org/packages/ad/1e/5ce0fbe9aab071893ce2b7df020d0f561f7b411ec334124302468d587884/regex-2026.7.10-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f3463a5f26be513a49e4d497debcf1b252a2db7b92c77d89621aa90b83d2dd38", size = 796800, upload-time = "2026-07-10T19:47:20.639Z" }, - { url = "https://files.pythonhosted.org/packages/d4/67/c1ccbada395c10e334763b583e1039b1660b142303ebb941d4269130b22f/regex-2026.7.10-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:948dfc62683a6947b9b486c4598d8f6e3ecc542478b6767b87d52be68aeb55c6", size = 865509, upload-time = "2026-07-10T19:47:22.135Z" }, - { url = "https://files.pythonhosted.org/packages/0e/06/f0b31afc16c1208f945b66290eb2a9936ab8becdfb23bbcedb91cc5f9d9b/regex-2026.7.10-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:c2cbd385d82f63bb35edb60b09b08abad3619bd0a4a492ae59e55afaf98e1b9d", size = 912395, upload-time = "2026-07-10T19:47:24.128Z" }, - { url = "https://files.pythonhosted.org/packages/0b/1c/8687de3a6c3220f4f872a9bf4bcd8dc249f2a96e7dddfa93de8bd4d16399/regex-2026.7.10-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f6222cafe00e072bb2b8f14142cd969637411fbc4dd3b1d73a90a3b817fa046f", size = 801308, upload-time = "2026-07-10T19:47:25.696Z" }, - { url = "https://files.pythonhosted.org/packages/5f/e3/60a40ec02a2315d826414a125640aceb6f30450574c530c8f352110ece0e/regex-2026.7.10-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:65ee5d1ac3cd541325f5ac92625b1c1505f4d171520dd931bda7952895c5321a", size = 777120, upload-time = "2026-07-10T19:47:27.158Z" }, - { url = "https://files.pythonhosted.org/packages/6a/9a/ec579b4f840ac59bc7c192b56e66abd4cbf385615300d59f7c94bf6863ae/regex-2026.7.10-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:aa34473fbcc108fea403074f3f45091461b18b2047d136f16ffaa4c65ad46a68", size = 785164, upload-time = "2026-07-10T19:47:28.732Z" }, - { url = "https://files.pythonhosted.org/packages/ad/1c/60d88afd5f98d4b0fb1f8b8969270628140dc01c7ff93a939f2aa83f31a6/regex-2026.7.10-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:9d028d189d8f38d7ff292f22187c0df37f2317f554d2ed9a2908ada330af57c0", size = 860161, upload-time = "2026-07-10T19:47:30.605Z" }, - { url = "https://files.pythonhosted.org/packages/2a/40/08ae3ba45fe79e48c9a888a3389a7ee7e2d8c580d2d996da5ece02dfdcb9/regex-2026.7.10-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:396ea70e4ea1f19571940add3bad9fd3eb6a19dc610d0d01f692bc1ba0c10cb4", size = 765829, upload-time = "2026-07-10T19:47:32.06Z" }, - { url = "https://files.pythonhosted.org/packages/12/e6/e613c6755d19aca9d977cdc3418a1991ffc8f386779752dd8fdfa888ea89/regex-2026.7.10-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:ebbf0d83ed5271991d666e54bb6c90ac2c55fb2ef3a88740c6af85dc85de2402", size = 852170, upload-time = "2026-07-10T19:47:33.567Z" }, - { url = "https://files.pythonhosted.org/packages/03/33/89072f2060e6b844b4916d5bc40ef01e973640c703025707869264ec75ab/regex-2026.7.10-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:58a4571b2a093f6f6ee4fd281faa8ebf645abcf575f758173ea2605c7a1e1ecb", size = 789550, upload-time = "2026-07-10T19:47:35.395Z" }, - { url = "https://files.pythonhosted.org/packages/e3/3c/4bc8be9a155035e63780ccac1da101f36194946fdc3f6fce90c7179fc6df/regex-2026.7.10-cp312-cp312-win32.whl", hash = "sha256:eac1207936555aa691ce32df1432b478f2729d54e6d93a1f4db9215bcd8eb47d", size = 267151, upload-time = "2026-07-10T19:47:37.047Z" }, - { url = "https://files.pythonhosted.org/packages/35/73/9f5aade65bb98cc6e99c336e45a49a658300720c16721f3e687f8d754fec/regex-2026.7.10-cp312-cp312-win_amd64.whl", hash = "sha256:ecae626449d00db8c08f8f1fc00047a32d6d7eb5402b3976f5c3fda2b80a7a4f", size = 277751, upload-time = "2026-07-10T19:47:38.488Z" }, - { url = "https://files.pythonhosted.org/packages/36/6f/d069dd12872ea1d50e17319d342f89e2072cae4b62f4245009a1108c74d8/regex-2026.7.10-cp312-cp312-win_arm64.whl", hash = "sha256:87794549a3f5c1c2bdfba2380c1bf87b931e375f4133d929da44f95e396bf5fe", size = 277063, upload-time = "2026-07-10T19:47:40.023Z" }, - { url = "https://files.pythonhosted.org/packages/e0/88/0c977b9f3ba9b08645516eca236388c340f56f7a87054d41a187a04e134c/regex-2026.7.10-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:4db009b4fc533d79af3e841d6c8538730423f82ea8508e353a3713725de7901c", size = 496868, upload-time = "2026-07-10T19:47:41.675Z" }, - { url = "https://files.pythonhosted.org/packages/f6/51/600882cd5d9a3cf083fd66a4064f5b7f243ba2a7de2437d42823e286edaf/regex-2026.7.10-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:b96341cb29a3faa5db05aff29c77d141d827414f145330e5d8846892119351c1", size = 297306, upload-time = "2026-07-10T19:47:43.521Z" }, - { url = "https://files.pythonhosted.org/packages/52/6f/48a912054ffcb756e374207bb8f4430c5c3e0ffa9627b3c7b6661844b30a/regex-2026.7.10-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:14d27f6bd04beb01f6a25a1153d73e58c290fd45d92ba56af1bb44199fd1010d", size = 291950, upload-time = "2026-07-10T19:47:45.267Z" }, - { url = "https://files.pythonhosted.org/packages/1a/c8/8e1c3c86ebcee7effccbd1f7fc54fe3af22aa0e9204503e2baea4a6ff001/regex-2026.7.10-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e6b6a11bf898cca3ce7bfaa17b646901107f3975677fbd5097f36e5eb5641983", size = 796817, upload-time = "2026-07-10T19:47:48.054Z" }, - { url = "https://files.pythonhosted.org/packages/65/39/3e49d9ff0e0737eb8180a00569b47aabb59b84611f48392eba4d998d91a0/regex-2026.7.10-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:234f8e0d65cf1df9becadae98648f74030ee85a8f12edcb5eb0f60a22a602197", size = 865513, upload-time = "2026-07-10T19:47:49.855Z" }, - { url = "https://files.pythonhosted.org/packages/70/57/6511ad809bb3122c65bbeeffa5b750652bb03d273d29f3acb0754109b183/regex-2026.7.10-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:91b916d495db3e1b473c7c8e68733beec4dce8e487442db61764fff94f59740e", size = 912391, upload-time = "2026-07-10T19:47:51.776Z" }, - { url = "https://files.pythonhosted.org/packages/cc/29/a1b0c109c9e878cb04b931bfe4c54332d692b93c322e127b5ae9f25b0d9e/regex-2026.7.10-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1f0d4ccf70b1d13711242de0ba78967db5c35d12ac408378c70e06295c3f6644", size = 801338, upload-time = "2026-07-10T19:47:53.38Z" }, - { url = "https://files.pythonhosted.org/packages/33/be/171c3dad4d77000e1befeff2883ca88734696dfd97b2951e5e074f32e4dd/regex-2026.7.10-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c622f4c638a725c39abcb2e680b1bd592663c83b672a4ed350a17f806d75618e", size = 777149, upload-time = "2026-07-10T19:47:54.944Z" }, - { url = "https://files.pythonhosted.org/packages/33/61/41ab0de0e4574da1071c151f67d1eb9db3d92c43e31d64d2e6863c3d89bf/regex-2026.7.10-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:41a47c2b28d9421e2509a4583a22510dc31d83212fcf38e1508a7013140f71a8", size = 785216, upload-time = "2026-07-10T19:47:56.56Z" }, - { url = "https://files.pythonhosted.org/packages/66/28/372859ea693736f07cf7023247c7eca8f221d9c6df8697ff9f93371cca08/regex-2026.7.10-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:13fba679fe035037e9d5286620f88bbfd105df4d5fcd975942edd282ab986775", size = 860229, upload-time = "2026-07-10T19:47:58.278Z" }, - { url = "https://files.pythonhosted.org/packages/50/b1/e1d32cd944b599534ae655d35e8640d0ec790c0fa12e1fb29bf434d50f55/regex-2026.7.10-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:8e26a075fa9945b9e44a3d02cc83d776c3b76bb1ff4b133bbfa620d5650131da", size = 765797, upload-time = "2026-07-10T19:48:00.291Z" }, - { url = "https://files.pythonhosted.org/packages/0c/62/79a2cd9556a3329351e370929743ef4f0ccc0aaff6b3dc414ae5fa4a1302/regex-2026.7.10-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:d0834c84ae8750ae1c4cede59b0afd4d2f775be958e11b18a3eea24ed9d0d9f1", size = 852130, upload-time = "2026-07-10T19:48:01.972Z" }, - { url = "https://files.pythonhosted.org/packages/66/58/76fec29898cf5d359ab63face50f9d4f7135cc2eca3477139227b1d09952/regex-2026.7.10-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:64722a5031aeace7f6c8d5ea9a9b22d9368af0d6e8fa532585da8158549ea963", size = 789644, upload-time = "2026-07-10T19:48:03.748Z" }, - { url = "https://files.pythonhosted.org/packages/f6/06/3c7cec7817bda293e13c8f88aed227bbcf8b37e5990936ff6442a8fdf11a/regex-2026.7.10-cp313-cp313-win32.whl", hash = "sha256:74ae61d8573ecd51b5eeee7be2218e4c56e99c14fa8fcf97cf7519611d4be92e", size = 267130, upload-time = "2026-07-10T19:48:05.677Z" }, - { url = "https://files.pythonhosted.org/packages/88/6c/e2a6f9a6a905f923cfc912298a5949737e9504b1ca24f29eda8d04d05ece/regex-2026.7.10-cp313-cp313-win_amd64.whl", hash = "sha256:5e792367e5f9b4ffb8cad93f1beaa91837056b94da98aa5c65a0db0c1b474927", size = 277722, upload-time = "2026-07-10T19:48:07.318Z" }, - { url = "https://files.pythonhosted.org/packages/00/a6/9d8935aaa940c388496aa1a0c82669cc4b5d06291c2712d595e3f0cf16d3/regex-2026.7.10-cp313-cp313-win_arm64.whl", hash = "sha256:82ab8330e7e2e416c2d42fcec67f02c242393b8681014750d4b70b3f158e1f08", size = 277059, upload-time = "2026-07-10T19:48:08.977Z" }, - { url = "https://files.pythonhosted.org/packages/7d/e9/26decfd3e85c09e42ff7b0d23a6f51085ca4c268db15f084928ca33459c6/regex-2026.7.10-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:2b93eafd92c4128bab2f93500e8912cc9ecb3d3765f6685b902c6820d0909b6b", size = 501508, upload-time = "2026-07-10T19:48:10.668Z" }, - { url = "https://files.pythonhosted.org/packages/38/a5/5b167cebde101945690219bf34361481c9f07e858a4f46d9996b80ec1490/regex-2026.7.10-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:3f03b92fb6ec739df042e45b06423fc717ecf0063e07ffe2897f7b2d5735e1e8", size = 299705, upload-time = "2026-07-10T19:48:12.544Z" }, - { url = "https://files.pythonhosted.org/packages/f6/20/7909be4b9f449f8c282c14b6762d59aa722aeaeebe7ee4f9bb623eeaa5e0/regex-2026.7.10-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:bb5aab464a0c5e03a97abad5bdf54517061ebbf72340d576e99ff661a42575cc", size = 294605, upload-time = "2026-07-10T19:48:14.495Z" }, - { url = "https://files.pythonhosted.org/packages/82/88/e52550185d6fda68f549b01239698697de47320fd599f5e880b1986b7673/regex-2026.7.10-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fadb07dbe36a541283ff454b1a268afd54b077d917043f2e1e5615372cb5f200", size = 811747, upload-time = "2026-07-10T19:48:16.197Z" }, - { url = "https://files.pythonhosted.org/packages/06/98/16c255c909714de1ee04da6ae30f3ee04170f300cdc0dcf57a314ee4816a/regex-2026.7.10-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:21150500b970b12202879dfd82e7fd809d8e853140fff84d08e57a90cf1e154e", size = 871203, upload-time = "2026-07-10T19:48:18.12Z" }, - { url = "https://files.pythonhosted.org/packages/3b/32/423ed27c9bae2092a453e853da2b6628a658d08bb5a6117db8d591183d85/regex-2026.7.10-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a68b637451d64ba30ed8ae125c973fa834cc2d37dfa7f154c2b479015d477ba8", size = 917334, upload-time = "2026-07-10T19:48:19.952Z" }, - { url = "https://files.pythonhosted.org/packages/73/87/74dac8efb500db31cb000fda6bae2be45fc2fbf1fa9412f445fbb8acbe37/regex-2026.7.10-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:3e23458d8903e33e7d27196d7a311523dc4e2f4137a5f34e4dbd30c8d37ff33e", size = 816379, upload-time = "2026-07-10T19:48:21.616Z" }, - { url = "https://files.pythonhosted.org/packages/a8/9f/1859403654e3e030b288f06d49233c6a4f889d62b84c4ef3f3a28653173d/regex-2026.7.10-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:cae27622c094558e519abf3242cf4272db961d12c5c9a9ffb7a1b44b2627d5c6", size = 785563, upload-time = "2026-07-10T19:48:23.643Z" }, - { url = "https://files.pythonhosted.org/packages/6d/d8/35d30d6bdf1ef6a5430e8982607b3a6db4df1ddedbe001e43435585d88ba/regex-2026.7.10-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:ee877b6d78f9dff1da94fef51ae8cf9cce0967e043fdcc864c40b85cf293c192", size = 801415, upload-time = "2026-07-10T19:48:25.499Z" }, - { url = "https://files.pythonhosted.org/packages/f7/22/630f31f5ea4826167b2b064d9cac2093a5b3222af380aa432cfe1a5dabcd/regex-2026.7.10-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:2c66a8a1969cfd506d1e203c0005fd0fc3fe6efc83c945606566b6f9611d4851", size = 866560, upload-time = "2026-07-10T19:48:27.789Z" }, - { url = "https://files.pythonhosted.org/packages/8d/14/f5914a6d9c5bc63b9bed8c9a1169fb0be35dbe05cdc460e17d953031a366/regex-2026.7.10-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:2bc350e1c5fa250f30ab0c3e38e5cfdffcd82cb8af224df69955cab4e3003812", size = 772877, upload-time = "2026-07-10T19:48:29.563Z" }, - { url = "https://files.pythonhosted.org/packages/c1/0f/7c13999eef3e4186f7c79d4950fa56f041bf4de107682fb82c80db605ff9/regex-2026.7.10-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:53f54993b462f3f91fea0f2076b46deb6619a5f45d70dbd1f543f789d8b900ef", size = 856648, upload-time = "2026-07-10T19:48:31.282Z" }, - { url = "https://files.pythonhosted.org/packages/a4/71/a48e43909b6450fb48fa94e783bef2d9a37179258bc32ef2283955df7be7/regex-2026.7.10-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:cfcec18f7da682c4e2d82112829ce906569cb8d69fa6c26f3a50dfbed5ceb682", size = 803520, upload-time = "2026-07-10T19:48:33.275Z" }, - { url = "https://files.pythonhosted.org/packages/e0/b8/f037d1bf2c133cb24ceb6e7d81d08417080390eddab6ddfd701aa7091874/regex-2026.7.10-cp313-cp313t-win32.whl", hash = "sha256:a2d6d30be35ddd70ce0f8ee259a4c25f24d6d689a45a5ac440f03e6bcc5a21d1", size = 269168, upload-time = "2026-07-10T19:48:35.353Z" }, - { url = "https://files.pythonhosted.org/packages/b6/9c/eaac34f8452a838956e7e89852ad049678cdc1af5d14f72d3b3b658b1ea5/regex-2026.7.10-cp313-cp313t-win_amd64.whl", hash = "sha256:c57b6ad3f7a1bdd101b2966f29dc161adf49727b1e8d3e1e89db2eda8a75c344", size = 280004, upload-time = "2026-07-10T19:48:37.106Z" }, - { url = "https://files.pythonhosted.org/packages/cd/a9/e22e997587bc1d588b0b2cd0572027d39dd3a006216e40bbf0361688c51c/regex-2026.7.10-cp313-cp313t-win_arm64.whl", hash = "sha256:3d8ef9df02c8083c7b4b855e3cb87c8e0ebbcfea088d98c7a886aaefdf88d837", size = 279308, upload-time = "2026-07-10T19:48:38.907Z" }, - { url = "https://files.pythonhosted.org/packages/6a/4a/a7fa3ada9bd2d2ce20d56dfceec6b2a51afeed9bf3d8286355ceec5f0628/regex-2026.7.10-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:39f81d1fdf594446495f2f4edd8e62d8eda0f7a802c77ac596dc8448ad4cc5ca", size = 497087, upload-time = "2026-07-10T19:48:40.543Z" }, - { url = "https://files.pythonhosted.org/packages/0f/7e/ca0b1a87192e5828dbc16f16ae6caca9b67f25bf729a3348468a5ff52755/regex-2026.7.10-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:441edc66a54063f8269d1494fc8474d06605e71e8a918f4bcfd079ebda4ce042", size = 297307, upload-time = "2026-07-10T19:48:42.213Z" }, - { url = "https://files.pythonhosted.org/packages/b2/6c/fb40bb34275d3cd4d7a376d5fb2ea1f0f4a96fd884fa83c0c4ae869001bf/regex-2026.7.10-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:cfeb11990f59e59a0df26c648f0adfcbf27be77241250636f5769eb08db662be", size = 292163, upload-time = "2026-07-10T19:48:43.929Z" }, - { url = "https://files.pythonhosted.org/packages/18/0b/34cbea16c8fea9a18475a7e8f5837c70af451e738bfeb4eb5b029b7dc07a/regex-2026.7.10-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:460176b2db044a292baaee6891106566739657877af89a251cded228689015a6", size = 797064, upload-time = "2026-07-10T19:48:45.623Z" }, - { url = "https://files.pythonhosted.org/packages/87/77/f6805d97f15f5a710bdfd56a768f3468c978239daf9e1b15efd8935e1967/regex-2026.7.10-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:9dc55698737aca028848bde418d6c51d74f2a5fd44872d3c8b56b626729adb89", size = 866155, upload-time = "2026-07-10T19:48:47.589Z" }, - { url = "https://files.pythonhosted.org/packages/a2/e3/a2a905807bba3bcd90d6ebbb67d27af2adf7d41708175cbc6b956a0c75f1/regex-2026.7.10-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d3e10779f60c000213a5b53f518824bd07b3dc119333b26d70c6be1c27b5c794", size = 911596, upload-time = "2026-07-10T19:48:49.473Z" }, - { url = "https://files.pythonhosted.org/packages/a2/ca/a3126888b2c6f33c7e29144fedf85f6d5a52a400024fa045ad8fc0550ef1/regex-2026.7.10-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:38a5926601aaccf379512746b86eb0ac1d29121f6c776dac6ac5b31077432f2c", size = 800713, upload-time = "2026-07-10T19:48:51.452Z" }, - { url = "https://files.pythonhosted.org/packages/66/19/9d252fd969f726c8b56b4bacf910811cc70495a110907b3a7ccb96cd9cad/regex-2026.7.10-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:a72ecf5bfd3fc8d57927f7e3ded2487e144472f39010c3acaec3f6f3ff53f361", size = 777286, upload-time = "2026-07-10T19:48:53.443Z" }, - { url = "https://files.pythonhosted.org/packages/40/7a/5f1bf433fa446ecb3aab87bb402603dc9e171ef8052c1bb8690bb4e255a3/regex-2026.7.10-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:d50714405845c1010c871098558cfe5718fe39d2a2fab5f95c8863caeb7a82b3", size = 785826, upload-time = "2026-07-10T19:48:55.381Z" }, - { url = "https://files.pythonhosted.org/packages/99/ca/69f3a7281d86f1b592338007f3e535cc219d771448e2b61c0b56e4f9d05b/regex-2026.7.10-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:ec1c44cf9bd22079aac37a07cb49a29ced9050ab5bddf24e50aba298f1e34d90", size = 860957, upload-time = "2026-07-10T19:48:57.962Z" }, - { url = "https://files.pythonhosted.org/packages/bc/11/487ff55c8d515ec9dd60d7ba3c129eeaa9e527358ed9e8a054a9e9430f81/regex-2026.7.10-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:9e9aaef25a40d1f1e1bbb1d0eb0190c4a64a7a1750f7eb67b8399bed6f4fd2a6", size = 765959, upload-time = "2026-07-10T19:49:00.27Z" }, - { url = "https://files.pythonhosted.org/packages/73/e1/fa034e6fa8896a09bd0d5e19c81fdc024411ab37980950a0401dccee8f6d/regex-2026.7.10-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:e54e088dc64dd2766014e7cfe5f8bc45399400fd486816e494f93e3f0f55da06", size = 851447, upload-time = "2026-07-10T19:49:02.128Z" }, - { url = "https://files.pythonhosted.org/packages/ee/a5/b9427ed53b0e14c540dc436d56aaf57a19fb9183c6e7abd66f4b4368fbad/regex-2026.7.10-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:834271b1ff2cfa1f67fcd65a48bf11d11e9ab837e21bf79ce554efb648599ae8", size = 789418, upload-time = "2026-07-10T19:49:03.949Z" }, - { url = "https://files.pythonhosted.org/packages/ba/52/aab92420c8aa845c7bcbe68dc65023d4a9e9ea785abf0beb2198f0de5ba1/regex-2026.7.10-cp314-cp314-win32.whl", hash = "sha256:f988a1cec68058f71a38471813fba9e87dffe855582682e8a10e40ece12567a2", size = 272538, upload-time = "2026-07-10T19:49:05.833Z" }, - { url = "https://files.pythonhosted.org/packages/99/16/5c7050e0ef7dd8889441924ff0a2c33b7f0587c0ccb0953fe7ca997d673b/regex-2026.7.10-cp314-cp314-win_amd64.whl", hash = "sha256:2129e4a5e86f26926982d883dff815056f2e98220fdf630e59f961b578a26c43", size = 280796, upload-time = "2026-07-10T19:49:07.593Z" }, - { url = "https://files.pythonhosted.org/packages/e8/1a/4f6099d2ba271502fdb97e697bae2ed0213c0d87f2273fe7d21e2e401d12/regex-2026.7.10-cp314-cp314-win_arm64.whl", hash = "sha256:9cd5b6805396157b4cf993a6940cbb8663161f29b4df2458c1c9991f099299c5", size = 281017, upload-time = "2026-07-10T19:49:09.767Z" }, - { url = "https://files.pythonhosted.org/packages/19/02/4061fc71f64703e0df61e782c2894c3fbc089d277767eff6e16099581c73/regex-2026.7.10-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:103e8f3acc3dcede88c0331c8612766bdcfc47c9250c5477f0e10e0550b9da49", size = 501467, upload-time = "2026-07-10T19:49:11.952Z" }, - { url = "https://files.pythonhosted.org/packages/73/a5/8d42b2f3fd672908a05582effd0f88438bf9bb4e8e02d69a62c723e23601/regex-2026.7.10-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:538ddb143f5ca085e372def17ef3ed9d74b50ad7fc431bd85dc50a9af1a7076f", size = 299700, upload-time = "2026-07-10T19:49:14.067Z" }, - { url = "https://files.pythonhosted.org/packages/65/70/36fa4b46f73d268c0dbe77c40e62da2cd4833ee206d3b2e438c2034e1f36/regex-2026.7.10-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:6e3448e86b05ce87d4eb50f9c680860830f3b32493660b39f43957d6263e2eba", size = 294590, upload-time = "2026-07-10T19:49:15.883Z" }, - { url = "https://files.pythonhosted.org/packages/e0/a7/b6db1823f3a233c2a46f854fdc986f4fd424a84ed557b7751f2998efb266/regex-2026.7.10-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5eab9d3f981c423afd1a61db055cfe83553c3f6455949e334db04722469dd0a2", size = 811925, upload-time = "2026-07-10T19:49:17.97Z" }, - { url = "https://files.pythonhosted.org/packages/b6/7d/f8bee4c210c42c7e8b952bb9fb7099dd7fb2f4bd0f33d0d65a8ab08aafc0/regex-2026.7.10-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:177f930af3ad72e1045f8877540e0c43a38f7d328cf05f31963d0bd5f7ecf067", size = 871257, upload-time = "2026-07-10T19:49:19.943Z" }, - { url = "https://files.pythonhosted.org/packages/5d/78/22adf72e614ba0216b996e9aaef5712c23699e360ea127bb3d5ee1a7666f/regex-2026.7.10-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:dd3b6d97beb39afb412f2c79522b9e099463c31f4c49ab8347c5a2ca3531c478", size = 917551, upload-time = "2026-07-10T19:49:22.069Z" }, - { url = "https://files.pythonhosted.org/packages/03/f7/ebc15a39e81e6b58da5f913b91fc293a25c6700d353c14d5cd25fc85712a/regex-2026.7.10-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8679f0652a183d93da646fcec8da8228db0be40d1595da37e6d74c2dc8c4713c", size = 816436, upload-time = "2026-07-10T19:49:24.131Z" }, - { url = "https://files.pythonhosted.org/packages/5c/33/20bc2bdd57f7e0fcc51be37e4c4d1bca7f0b4af8dc0a148c23220e689da8/regex-2026.7.10-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:494b19a5805438aeb582de99f9d97603d8fd48e6f4cc74d0088bb292b4da3b70", size = 785935, upload-time = "2026-07-10T19:49:26.265Z" }, - { url = "https://files.pythonhosted.org/packages/b4/51/87ff99c849b56309c40214a72b54b0eef320d0516a8a516970cc8be1b725/regex-2026.7.10-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:0911e34151a5429d0325dae538ba9851ec0b62426bdfd613060cda8f1c36ec7f", size = 801494, upload-time = "2026-07-10T19:49:28.493Z" }, - { url = "https://files.pythonhosted.org/packages/16/11/fde67d49083fef489b7e0f841e2e5736516795b166c9867f05956c1e494b/regex-2026.7.10-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:b862572b7a5f5ed47d2ba5921e63bf8d9e3b682f859d8f11e0e5ca46f7e82173", size = 866549, upload-time = "2026-07-10T19:49:30.592Z" }, - { url = "https://files.pythonhosted.org/packages/e6/b5/31a156c36acf10181d88f55a66c688d5454a344e53ccc03d49f4a48a2297/regex-2026.7.10-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:3f361215e000d68a4aff375106637b83c80be36091d83ee5107ad3b32bd73f48", size = 773089, upload-time = "2026-07-10T19:49:32.661Z" }, - { url = "https://files.pythonhosted.org/packages/27/bb/734e978c904726664df47ae36ce5eca5065de5141185ae46efec063476a2/regex-2026.7.10-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:4533af6099543db32ef26abc2b2f824781d4eebb309ab9296150fd1a0c7eb07d", size = 856710, upload-time = "2026-07-10T19:49:35.289Z" }, - { url = "https://files.pythonhosted.org/packages/6d/e5/dc35cea074dbdcb9776c4b0542a3bc326ff08454af0768ef35f3fc66e7fa/regex-2026.7.10-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:668ab85105361d0200e3545bec198a1acfc6b0aeb5fff8897647a826e5a171be", size = 803621, upload-time = "2026-07-10T19:49:37.704Z" }, - { url = "https://files.pythonhosted.org/packages/a6/b2/124564af46bc0b592785610b3985315610af0a07f4cf21fa36e06c2398dd/regex-2026.7.10-cp314-cp314t-win32.whl", hash = "sha256:dd7715817a187edd7e2a2390908757f7ba42148e59cad755fb8ee1160c628eca", size = 274558, upload-time = "2026-07-10T19:49:39.926Z" }, - { url = "https://files.pythonhosted.org/packages/4e/9c/cd813ce9f3404c0443915175c1e339c5afd8fcda04310102eaf233015eef/regex-2026.7.10-cp314-cp314t-win_amd64.whl", hash = "sha256:78712d4954234df5ca24fdadb65a2ab034213f0cdfde376c272f9fc5e09866bb", size = 283687, upload-time = "2026-07-10T19:49:41.872Z" }, - { url = "https://files.pythonhosted.org/packages/1b/d3/3dae6a6ce46144940e64425e32b8573a393a009aeaf75fa6752a35399056/regex-2026.7.10-cp314-cp314t-win_arm64.whl", hash = "sha256:749b92640e1970e881fdf22a411d74bf9d049b154f4ef7232eeb9a90dd8be7f3", size = 283377, upload-time = "2026-07-10T19:49:43.985Z" }, +version = "2026.9.29" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/fc/f2/af1da9d3ceed77bfcdce40427d49ba0be94e4fe84245e3bfef68c10e75b6/regex-2026.9.29.tar.gz", hash = "sha256:8b5fcc4771732191b2b7d1dd68d8f0353f47f8d90b6150f6dce58bf1112442cb", size = 419199, upload-time = "2026-09-29T00:49:58.298Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e8/6b/6dea87689c3a06a6e79d254bf824e6f3e3d724b5ba027c6112559aa6cd2c/regex-2026.9.29-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:6abb75ab16bc3281714a5b99548a2225db70dba1f995f6d7f7419b76eb5a8fbe", size = 495413, upload-time = "2026-09-29T00:46:14.51Z" }, + { url = "https://files.pythonhosted.org/packages/3a/a5/0c791a0e83ad1013d262c13247c4c77e0f4a8d05bdc167df96aba6681c0d/regex-2026.9.29-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:b7b893976e7fe42053da64f2aa27239c24252fd2ec6df471e1be197c0addc3b1", size = 295145, upload-time = "2026-09-29T00:46:16.292Z" }, + { url = "https://files.pythonhosted.org/packages/b1/07/9bf3607d8d13a12e436ab9d63f9791e10706827d535695b23964ad79fd79/regex-2026.9.29-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:066d0e3dbfdd739bce2bf8c2a41dd16f73e3d8adc2eb06dd803a36a307f56075", size = 292123, upload-time = "2026-09-29T00:46:17.646Z" }, + { url = "https://files.pythonhosted.org/packages/64/6b/32c2e6fc617e1d3f247e250fea31a9a35b1265bd32f585968aa13b9999b9/regex-2026.9.29-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7020ed44df30b3aa492c00ee3b52d0548c1f30c2c6c5bb13ae897680900d3413", size = 799537, upload-time = "2026-09-29T00:46:18.976Z" }, + { url = "https://files.pythonhosted.org/packages/bf/72/f041177f3c7a4606f7c81a95fe7eea03e2a0c4e8bff9e439a01432cbc9f2/regex-2026.9.29-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ae4613d7d9dda60fcba95f846cc6f808017f1843f392cf9daad14a6534493d71", size = 873255, upload-time = "2026-09-29T00:46:20.684Z" }, + { url = "https://files.pythonhosted.org/packages/d0/4e/a78948e11dd715e0e46716c2e0f3404b3fe6a44e2a2e9abdc7d965cab2b3/regex-2026.9.29-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:bec37990e3d6121f29ecfb594bd8f1bf009e9f7926daba2e50e3b27d3892a783", size = 914570, upload-time = "2026-09-29T00:46:22.599Z" }, + { url = "https://files.pythonhosted.org/packages/8a/70/aa08d1d2b294894b365e5f8ba5380fe3f8546acdb81f10639dfd74209c37/regex-2026.9.29-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:612b709381c0355b70d89cdb51b7f670591ed5cbbc0e3b5337488019dc667b65", size = 804978, upload-time = "2026-09-29T00:46:23.981Z" }, + { url = "https://files.pythonhosted.org/packages/21/32/1b03534c4715aca3b564416d28d518083ed4dab3bc913267600d2256140d/regex-2026.9.29-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:a760da040b47767b4b873adfb7c3b691e9ba2fc60f113f9d0b88f1a62f323e85", size = 779297, upload-time = "2026-09-29T00:46:25.318Z" }, + { url = "https://files.pythonhosted.org/packages/76/a7/378f6f558d9e4444af315a307c5953565a511d1e3666f1bb7bdc82012b6b/regex-2026.9.29-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:49ee178ca31c94621294bf9b8b676a92a2e6bba8af0529591753719e57edb621", size = 786961, upload-time = "2026-09-29T00:46:26.963Z" }, + { url = "https://files.pythonhosted.org/packages/59/13/79f0b1846f5f342f92ddbd4b27b18bcb86da96d902c1a0be26520bde98d7/regex-2026.9.29-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:5eeb8edc6110d9194a4d0d54610f64c37a31c605b5dbb7e407fc6ec7fa34a4a1", size = 863234, upload-time = "2026-09-29T00:46:28.58Z" }, + { url = "https://files.pythonhosted.org/packages/97/19/05af70dec9f2eed6ba34e08d2dcc6a48e7ae5e307659d5fe4201a5d7bbee/regex-2026.9.29-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:ccb64d887a9db1cd76dbc0f92051a1a478a2a67e7f56c62d915cb881d7734704", size = 766487, upload-time = "2026-09-29T00:46:29.941Z" }, + { url = "https://files.pythonhosted.org/packages/01/e1/9c7486d4afe8fdd1fe0ad60139f8aa91427381f409af6a29b609d8fdcb3a/regex-2026.9.29-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:9e4482589065c8ecd761cff522dcd85f2d39e62f551e37e025d1c7d54772def3", size = 854792, upload-time = "2026-09-29T00:46:31.358Z" }, + { url = "https://files.pythonhosted.org/packages/26/c7/49d008ff5f741d9a9799d7315556f3a12b983ff0fcd2cdfb62904bedafbf/regex-2026.9.29-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:d60030baaa7bfbb02d650c126cdcddcb6e33dbff14d819434c8fa2fdcaeeeba5", size = 793050, upload-time = "2026-09-29T00:46:32.775Z" }, + { url = "https://files.pythonhosted.org/packages/cb/a1/46ba549e65562ca04608b24179b8a7bb6f146ae0e7c6d7f5e70f3339c8ba/regex-2026.9.29-cp311-cp311-win32.whl", hash = "sha256:18ae8eed4526e35bdb754d61562b90bf5c00a67fdcf3cc1380dd59597486631b", size = 268940, upload-time = "2026-09-29T00:46:34.179Z" }, + { url = "https://files.pythonhosted.org/packages/4d/4a/aab232183c70fdcf77bcf0c51819da02ec522e393e6a0bf00bcf2142e21f/regex-2026.9.29-cp311-cp311-win_amd64.whl", hash = "sha256:1043aedf5917caa861bcb25a9c11460049656bdf0017a90a309fa8f255467725", size = 280641, upload-time = "2026-09-29T00:46:35.484Z" }, + { url = "https://files.pythonhosted.org/packages/33/b1/7c05954af0f51de376df2ba97f7f78a8b79334c7e5b3d2d9f2aead1f4d3d/regex-2026.9.29-cp311-cp311-win_arm64.whl", hash = "sha256:352cf115a810b357caa35193ab656ecf5ef41056855e82f292c99e8514f8d954", size = 279411, upload-time = "2026-09-29T00:46:37.193Z" }, + { url = "https://files.pythonhosted.org/packages/84/48/3fdcde9a0baa84d7d25571223265d6e434e114763b438601d54a8028bf3e/regex-2026.9.29-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:dc79d36d0618752265f0d575915bdc5c5130ecb9c9f6b3bcefeae32e4bdfafcf", size = 497903, upload-time = "2026-09-29T00:46:38.938Z" }, + { url = "https://files.pythonhosted.org/packages/2e/1c/4ee3e97c76f53940488dfe7a7e18705e78daac8cd7fb161d246b9e328449/regex-2026.9.29-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:3a21a9509d0ee88e7a70e1ad228cd2f0e0fd1e187458db132e8a8d18c97daf9d", size = 296416, upload-time = "2026-09-29T00:46:40.406Z" }, + { url = "https://files.pythonhosted.org/packages/37/14/f3f0ba083d2094392d5eabf56db5ea6ba469fd6e927afd187042054ea68a/regex-2026.9.29-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:f57dc6b8fef170f105d2cf5cdce254f47b137d7755086cf7050f47e16582abba", size = 293633, upload-time = "2026-09-29T00:46:41.959Z" }, + { url = "https://files.pythonhosted.org/packages/c9/72/67e7a8ce17f1aea49df215564048efb49cc8c2b31a0e0fc30f36838f8516/regex-2026.9.29-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f93bc1c3486ef3747e07c9d7c1d0a147b8fbaab975f80e348aed6f71309dfaca", size = 805885, upload-time = "2026-09-29T00:46:43.373Z" }, + { url = "https://files.pythonhosted.org/packages/f6/78/25436bcfd4d2260b4b4090094d55d7ab53ec8a1ab4865a0b8bcb33c7d5c0/regex-2026.9.29-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:9e1d3a4cb7993b708f0ada8d0c84590efd853f169e7147d2202c9da503180242", size = 878344, upload-time = "2026-09-29T00:46:45.328Z" }, + { url = "https://files.pythonhosted.org/packages/97/e6/a09ec3a23ae41d6179880e67f0aace9284b2d95f2d7b326eff203f8eec5e/regex-2026.9.29-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:dabee8f4935e731fb46b2a3091bdda0d3d94b3bbfb907d2b4f12eefce4009619", size = 919181, upload-time = "2026-09-29T00:46:47.041Z" }, + { url = "https://files.pythonhosted.org/packages/26/83/d2fbd2e4e3afb1167daa825187d196f313cbaa1a4768f311fb041bb0e3d2/regex-2026.9.29-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:39ab5894d971f9ac68baa6eca5c50387db579cfcacf36ae8df3feceb1815e6d0", size = 807783, upload-time = "2026-09-29T00:46:48.894Z" }, + { url = "https://files.pythonhosted.org/packages/46/0b/eb429a7016610d44fc89a597163f8c9127505f0d7dc724dc9effbb6a3ac0/regex-2026.9.29-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c1a9a6651197fbed6f0212591418b9def774fc3f8324f78d1bf0e6a63e5f8aa1", size = 783465, upload-time = "2026-09-29T00:46:50.64Z" }, + { url = "https://files.pythonhosted.org/packages/1b/07/58a3c0153c7476898430f6a7cf3d9062a1d17fbea4f43399ecaf411c7b4c/regex-2026.9.29-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:87fb80cbe3557e27e7b28b995c2b2eedf689b8886f941ab93e0e288f0976518a", size = 793519, upload-time = "2026-09-29T00:46:52.396Z" }, + { url = "https://files.pythonhosted.org/packages/2a/e8/161b94d39164520e21a7befe0245569bf7fda4c7cf1fc4e2df2b5def49da/regex-2026.9.29-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:3c5c2ef13797466aa64170cbb66ad98a32351dd4127694cea7199f80f213750d", size = 869293, upload-time = "2026-09-29T00:46:54.128Z" }, + { url = "https://files.pythonhosted.org/packages/8f/07/3b02ed829aa2decdc1955d222bd1e2f99d1c8bb4873bbb9a66b2f0a36bff/regex-2026.9.29-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:59b49507f47479e299a9e1bc41b5cb83a7afda0540625f1dbae886615978acbf", size = 770239, upload-time = "2026-09-29T00:46:56.106Z" }, + { url = "https://files.pythonhosted.org/packages/42/5b/ba61f6fe062eb8562e742367d177bb75370434138ef6c9d2a27114f8d613/regex-2026.9.29-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:0dd8af32e9f7b56b7f95cc1fd79b23054c3bdc172392ae560acc24d57b7ffe71", size = 861973, upload-time = "2026-09-29T00:46:57.665Z" }, + { url = "https://files.pythonhosted.org/packages/cc/27/767259b20e8a842948990f5e99138d6c077248fd42f8b5468b1d9ca4b814/regex-2026.9.29-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:db5e82ba15c142425b8406690032df89e39cca4a2e8afbbb9a3d84edc2373ac3", size = 796470, upload-time = "2026-09-29T00:46:59.236Z" }, + { url = "https://files.pythonhosted.org/packages/a0/05/2566c4ba849b68a8ab81a6bf428fa79d20aae7ddee83979103c0381df254/regex-2026.9.29-cp312-cp312-win32.whl", hash = "sha256:d0c3082bf79bcd6a614d55916590ad4b8f93200e10b97f463ea5d9d07c9b5f23", size = 269327, upload-time = "2026-09-29T00:47:01.135Z" }, + { url = "https://files.pythonhosted.org/packages/93/19/489bc8db91196381c935752df01ba3f607140daece33b78d88573f028e64/regex-2026.9.29-cp312-cp312-win_amd64.whl", hash = "sha256:fdd88ed5e20b1bcdd234421e454962c971aa44b653bdb7f1ea9ef683e90fb649", size = 280334, upload-time = "2026-09-29T00:47:04.436Z" }, + { url = "https://files.pythonhosted.org/packages/0b/47/fb88ba779d0e5e7d4b0ec1aceeb13845948a2cb876bd572a2d1dfdba090b/regex-2026.9.29-cp312-cp312-win_arm64.whl", hash = "sha256:4fe97894d1b306c919b4e50def1e6f6c522f4d03a7283811f4d108f1ce5d3ac2", size = 279614, upload-time = "2026-09-29T00:47:06.541Z" }, + { url = "https://files.pythonhosted.org/packages/79/d5/6080f7d1a6e7e36aa720f806ac93c035ba39c209ae6cc510e8ef4c0279c6/regex-2026.9.29-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:f1a0d5117230dd46b399a30a38afa44f79c99f3168988fdc4f425c3f928b39df", size = 497622, upload-time = "2026-09-29T00:47:08.251Z" }, + { url = "https://files.pythonhosted.org/packages/00/71/c87fc7a2e21a42f9d57489db32951c37eef56d153840459a80d464f0321d/regex-2026.9.29-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:f0fe9834e5aeccaf19a0d8feb296d66a24be1a7c9922002f842a682cd5abb787", size = 296281, upload-time = "2026-09-29T00:47:09.764Z" }, + { url = "https://files.pythonhosted.org/packages/11/9e/aa0f4cde3bc4688c1d58b0cd8415edd708339bc0bc401a195b0b1e8c8f0c/regex-2026.9.29-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:c90fcf7804ea0a54b896ce0f2b9565350220b8d4890fd0db461a476a4c687963", size = 293472, upload-time = "2026-09-29T00:47:11.723Z" }, + { url = "https://files.pythonhosted.org/packages/90/d4/e835c487850ed922a8d6074f953b888c8ea99775c76b9ed5f8a4d72eab92/regex-2026.9.29-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e11edba5bc344a32b029a7af9d4b3173982dd79eeafa0b9dbd787364414b0509", size = 805966, upload-time = "2026-09-29T00:47:13.235Z" }, + { url = "https://files.pythonhosted.org/packages/2c/57/ba8809847fbae8d2cbc71367c6ded510a7ec88bf52493c65efc1acf4effb/regex-2026.9.29-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:bb90e7177944b6684738c1fc36aabd2dd00d1de3be7dbe09f91e196f1bc0dc81", size = 878346, upload-time = "2026-09-29T00:47:14.877Z" }, + { url = "https://files.pythonhosted.org/packages/1a/52/e3da19fc3cc15ef67ab67e121e87887c3bccfdb683a7a9ec557c460ca5b7/regex-2026.9.29-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d06fcdecc10fc7954d7c8f27a03c96055fe525274dc84a7b0dbdc3d6b9e03dab", size = 919250, upload-time = "2026-09-29T00:47:16.622Z" }, + { url = "https://files.pythonhosted.org/packages/9a/8e/c1ed81f55f992f6aa0b699a592a50c1ce9e6d44ff1aee2c14c0537dcef9c/regex-2026.9.29-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d49c18f1ea294cf4adde2e5ac256e98c82ea9d708462ce4bf799dffa7cfe8a2c", size = 807902, upload-time = "2026-09-29T00:47:18.268Z" }, + { url = "https://files.pythonhosted.org/packages/ad/bc/5a6886eb470e41040e21e05b75024a18b6ebfe7ea400b72094a60f949101/regex-2026.9.29-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3e778bfccd63075167709136afbc251c1f683758d5bf49c803c60ac3f894ce6b", size = 783514, upload-time = "2026-09-29T00:47:19.921Z" }, + { url = "https://files.pythonhosted.org/packages/cb/52/6d951d453b023c6edb880f1ba474291b53b8ce1cc438b96a9db6d791d991/regex-2026.9.29-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:686ac5350fceae63830bb98805fcb8039325bf4c06d9f6f048ff65229d5bffa5", size = 793466, upload-time = "2026-09-29T00:47:21.552Z" }, + { url = "https://files.pythonhosted.org/packages/99/b9/d5a41adc08360f5eee0dc4846c578f002366947211fc8af5a69a64ee7b9f/regex-2026.9.29-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:26ec4ccce55aa533fbd603d08911b01101a8fcfec987845ac3ae2c7087b2bde3", size = 869464, upload-time = "2026-09-29T00:47:23.276Z" }, + { url = "https://files.pythonhosted.org/packages/4b/32/d76c9d91f5d798e2e9e67f6f85ec4ae35445ac425f7454797311cecb80ca/regex-2026.9.29-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:a655d34b2a6943af32401f3d94f72e9d731f6ad16285815550bf2b4ee69d420a", size = 770278, upload-time = "2026-09-29T00:47:25.193Z" }, + { url = "https://files.pythonhosted.org/packages/24/00/aeebdb540c620a0f7317f6d6fad80a47729ecf0599a24b5c34ec155351f5/regex-2026.9.29-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:0c992c19cd45058a4b92f68f139c93db168b48fb1f322c9a7cd620806afb6b51", size = 861949, upload-time = "2026-09-29T00:47:27.005Z" }, + { url = "https://files.pythonhosted.org/packages/12/62/d0314bcedfd3586197e4596931fa220260eb2385bf53184e5b9ae67db24b/regex-2026.9.29-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:ebb8912f565b8cdbbf27debfe00df04202c20e2f651b9e32767930c5eace3621", size = 796602, upload-time = "2026-09-29T00:47:29.233Z" }, + { url = "https://files.pythonhosted.org/packages/ae/c7/d5a8c13a613facb03e0fb55c1ebaaf7bb35d8e2c1abe8bef8dca809fc1d9/regex-2026.9.29-cp313-cp313-win32.whl", hash = "sha256:4d7d93613b01b0199961330e49cfc52d479b3d5776c56c691db31130c0a07d91", size = 269306, upload-time = "2026-09-29T00:47:31.14Z" }, + { url = "https://files.pythonhosted.org/packages/80/a7/bf93a3a6afa5f7bc16b7afb94ae581b01cae620b8ad56bd8f9572a985959/regex-2026.9.29-cp313-cp313-win_amd64.whl", hash = "sha256:61956f074ecd123f55adca68ee3eab46e6a07ad3f8e64e6db95dfacb444f55c4", size = 280307, upload-time = "2026-09-29T00:47:32.709Z" }, + { url = "https://files.pythonhosted.org/packages/b2/7d/388274e53605a86297f433a08102a7bbdcf9379d47683d307ccaefd88e2c/regex-2026.9.29-cp313-cp313-win_arm64.whl", hash = "sha256:bfc71e6d970419c1309b3640305298643e2a734cad3f7cfb6d2ddee4175ab53d", size = 279599, upload-time = "2026-09-29T00:47:34.674Z" }, + { url = "https://files.pythonhosted.org/packages/93/1f/d9dc6f02f569625faf67a4daec926cd5023472dcd69bb44286dccd5a5ab3/regex-2026.9.29-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:957bb708e8057ab1649ba566456429d691ec9b90d1c9ad1af1ba7ffbbeaf05f2", size = 497598, upload-time = "2026-09-29T00:47:36.541Z" }, + { url = "https://files.pythonhosted.org/packages/9c/83/9b693a3fd1451381e812031a8961ec5b3b8f0c8cc6871f14c5223642804d/regex-2026.9.29-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:c9b602fae1e00b7c035d661ce85575365719192a7b46784bd71cf64c68053aa0", size = 296250, upload-time = "2026-09-29T00:47:38.233Z" }, + { url = "https://files.pythonhosted.org/packages/dd/5f/52bc2abc3fef040cd9de76ab29c918d6a717a454ae2b9dd7938b0c95656d/regex-2026.9.29-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:0166844493626c5015c6088ee15c9ca2fd060ca15b7641d1657da6a58432ae33", size = 293518, upload-time = "2026-09-29T00:47:39.957Z" }, + { url = "https://files.pythonhosted.org/packages/dc/fc/cf50671215ee0057046980b4571ef8646a005819bb67f0957e779ed107a5/regex-2026.9.29-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b97a38fb4c732b6832db6bf108963adbcd82ef1268ba2025dce390f45af75efa", size = 806037, upload-time = "2026-09-29T00:47:41.676Z" }, + { url = "https://files.pythonhosted.org/packages/14/4b/dddef8fc15c63e4347cc9efb138d0cd306f30e6c98acbcc81a8f780083b9/regex-2026.9.29-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a540abfab208e1b7ef2df231c40ef3b6cbb30a0aad6204e9b6a81c10a6794628", size = 878881, upload-time = "2026-09-29T00:47:43.755Z" }, + { url = "https://files.pythonhosted.org/packages/9f/cb/38daabed32d28f7e58a06e9344ce00dc67952e9996bc578ed6a29fe1240e/regex-2026.9.29-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:ddfa987262763c3c22a8367d2a49c244b018a74c3a8e3ab1a864119ad45c5633", size = 918684, upload-time = "2026-09-29T00:47:45.594Z" }, + { url = "https://files.pythonhosted.org/packages/a9/4d/041d9458a645fee4fce4d642a89d27271a3cfcd91095104f6dde44da70bf/regex-2026.9.29-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:2f7f7aa47b229f2b39a2ae2596d2ad5625d77b5eb9856fac2dab3eb506cdd0a0", size = 807176, upload-time = "2026-09-29T00:47:47.372Z" }, + { url = "https://files.pythonhosted.org/packages/bf/c4/4383eed7aa5aef67616cb1b3f3ad06b7c624c4e6cced48630cd5ce133d85/regex-2026.9.29-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:d9b77b25b4f395f92de6099ab08e8ae2bc7e51dfe157f22900902243a5cc90c7", size = 784315, upload-time = "2026-09-29T00:47:49.518Z" }, + { url = "https://files.pythonhosted.org/packages/5c/a6/0086ad31cebb183c637d3198547075aa493afde308e1ff61fccccb29ba6e/regex-2026.9.29-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:34b6925af9853bf461950e6508910f179fd6e9b1a7ec8548e069606b7e51a26b", size = 793748, upload-time = "2026-09-29T00:47:51.279Z" }, + { url = "https://files.pythonhosted.org/packages/d5/a0/f9005cba3f629a859573fc5d1224ea4e1f97919ec8581d018e03a351a604/regex-2026.9.29-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:addd736a0547d553283adaf4e05d7104e7f2c7b0b092e9b4d28756825f14531f", size = 870302, upload-time = "2026-09-29T00:47:53.368Z" }, + { url = "https://files.pythonhosted.org/packages/01/4f/e1a3e46bb5315a4e18b01a990e7a28e2a16595609d50c442baf2815a3c65/regex-2026.9.29-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:fe3fa1dd453ed5c7f5ea23a26218329790ed7197a99b90e94330e313959a7f52", size = 770299, upload-time = "2026-09-29T00:47:55.606Z" }, + { url = "https://files.pythonhosted.org/packages/2c/fe/f303b4acfda44e1ff1379368748c1ef2dad04a6a8e9c0ecbc970b19d97ca/regex-2026.9.29-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:0cc63b5e47c12a48d90c7e9d7de6a035dd14f62868aaedbb4e0ff8ba2b8bfe7b", size = 861570, upload-time = "2026-09-29T00:47:57.617Z" }, + { url = "https://files.pythonhosted.org/packages/60/b6/b4f7e99249f596017c60ccad5faf9310fc8e3e59bb2244940a90a1b0bdff/regex-2026.9.29-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:724184b4aafed865e4f13ca313fdcb43024300c028ec67319cfa16847d84685e", size = 795967, upload-time = "2026-09-29T00:47:59.922Z" }, + { url = "https://files.pythonhosted.org/packages/fb/d3/fc865a4638d9f6762192b6bab5b7aa1f33a90e9e99578c2e111e2a63c8c3/regex-2026.9.29-cp314-cp314-win32.whl", hash = "sha256:c6c8fabf1dafc1f1ddcbb67896d3f93efb092e8c4b6322d7389b944e76a484e5", size = 274758, upload-time = "2026-09-29T00:48:01.8Z" }, + { url = "https://files.pythonhosted.org/packages/31/e2/c2b466924ccbeb874862968ca638051b15a8fd29d994a0e99004a5cbf78e/regex-2026.9.29-cp314-cp314-win_amd64.whl", hash = "sha256:1c2a0026062abcc321a53db4a185ceba0b59a66b5d37b0808917a88b55a5257f", size = 283817, upload-time = "2026-09-29T00:48:03.614Z" }, + { url = "https://files.pythonhosted.org/packages/c6/42/ea0f8dbaa924fa75c6338935eaee2f44dab369b27f02db1e03d74344b049/regex-2026.9.29-cp314-cp314-win_arm64.whl", hash = "sha256:121a76a0985db80ceae9e171c337f8c927868e37d01b54e3ce87bc87f9c6a208", size = 283663, upload-time = "2026-09-29T00:48:05.624Z" }, + { url = "https://files.pythonhosted.org/packages/44/48/d58e5081119f5c223bbb37d2340acde3d069e1df8e8cd166c37502eee4da/regex-2026.9.29-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:e31f72490b7c12f7790e1e25c3afffd20503ee1bfb43461d7838b871ff244b19", size = 501393, upload-time = "2026-09-29T00:48:07.833Z" }, + { url = "https://files.pythonhosted.org/packages/72/3c/c49945287d4f9efee7d41f98072f8ad880efb8f430595a612fbdea996a4e/regex-2026.9.29-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:80ea96f5c1a30bf09007d48466521d9c294bebe197c708c3359096e3e3691632", size = 298237, upload-time = "2026-09-29T00:48:09.684Z" }, + { url = "https://files.pythonhosted.org/packages/f9/1f/688cb61c3d4cf7bcc1ed444b5cc49399eba3e51c469ae285cf87fea3022e/regex-2026.9.29-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:554bffadcbcb6d5f4e5fb10a61cc52084b9a63d1dab5f10bcd2c4343972e8e2c", size = 295936, upload-time = "2026-09-29T00:48:11.454Z" }, + { url = "https://files.pythonhosted.org/packages/26/a3/de43ac6b877b7d09c19a3a426b1bd5acdd209eaaf68f406466f80439ccf6/regex-2026.9.29-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:864e9b87ac33c3fb9fb4ad48166d4fdb579c351d5c77deb0d34bccb36a775cd9", size = 816905, upload-time = "2026-09-29T00:48:13.321Z" }, + { url = "https://files.pythonhosted.org/packages/62/14/9940763201c51d537786304984c67d0fc3d2ed18837ffb6f09a869f6b6c9/regex-2026.9.29-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:044265d77d94f5e3cb2fd72c76723807c429cb8c533e9d4672d0334a6f14f588", size = 881527, upload-time = "2026-09-29T00:48:15.313Z" }, + { url = "https://files.pythonhosted.org/packages/d3/e1/c842d8df0b23245ebf202f8ab9c39fd48e2db39959454ec39a41c8c72082/regex-2026.9.29-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:2089fe39c406784d90101c726755ffa1497bb74638fd434300d2b88006186de8", size = 923115, upload-time = "2026-09-29T00:48:17.328Z" }, + { url = "https://files.pythonhosted.org/packages/d8/c1/98622479e3c354a446a75232e522d747d2b3df23092dcd8a5309380a2020/regex-2026.9.29-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0def9fb6abac55492d6d51cddb7225d07d6f279e774e0adc08569a54a5fc8d46", size = 820674, upload-time = "2026-09-29T00:48:19.32Z" }, + { url = "https://files.pythonhosted.org/packages/6c/d0/5808c95f9c79ed27b5eedaafc3df6239ec56a49f2e23ea8f831b18427c82/regex-2026.9.29-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:888d60953908dcf761aa320c3e390ab8556efbdb551ace63921de90f6ae0848d", size = 793306, upload-time = "2026-09-29T00:48:21.615Z" }, + { url = "https://files.pythonhosted.org/packages/bf/d3/021ca2638671ad20603bcd9b4d5bfa35d2610cd216a043ea7f0b44ea39f6/regex-2026.9.29-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:ed511a0708e2297e1d6431e7fb217e3402791e491e02da800658ace4973df1bb", size = 803103, upload-time = "2026-09-29T00:48:23.871Z" }, + { url = "https://files.pythonhosted.org/packages/6b/2d/755c6d13ef9c657378013676c391c7a402166b3f419a464a3e058dcbe533/regex-2026.9.29-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:e1172147d28d8fbcf8cb8d26c41506169f5ad8fe9ec969cb116835a19d4d8eca", size = 872175, upload-time = "2026-09-29T00:48:26.255Z" }, + { url = "https://files.pythonhosted.org/packages/6c/fc/e1cab183b9dafe8597f58c1c766da9bf96204d3b2f232bcf3eeb75ff7b6c/regex-2026.9.29-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:92f05c9c42bde5785dc48770bc2194d9f7442544156f951e19cd31b096cec562", size = 777362, upload-time = "2026-09-29T00:48:28.389Z" }, + { url = "https://files.pythonhosted.org/packages/06/7c/e10ea17fba31fb4a1f9d13ed53a2d2a9066a2aea58d7557e263f6d99e7b0/regex-2026.9.29-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:f37964e4a5e993d2fd45147741e9dff7f34a2d8c00ab94c4ea0514a4677f959e", size = 865606, upload-time = "2026-09-29T00:48:30.4Z" }, + { url = "https://files.pythonhosted.org/packages/8e/6e/69824d9aee1fd41c54ea7264654a47c8d9d84d8a228e11c2bcf4c201ed81/regex-2026.9.29-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:951733b1bbdb71e377cec567b409f1a7881b47cfcad84121aa74cb575fa425ea", size = 807945, upload-time = "2026-09-29T00:48:32.375Z" }, + { url = "https://files.pythonhosted.org/packages/89/22/857050a86e21ce60193e02a8ef662521f2e263a645c8b1b905fc136b61a7/regex-2026.9.29-cp314-cp314t-win32.whl", hash = "sha256:65b408d8fcb273e3499e7ef2ce796810da1becd208c7fb4373692a242d79d461", size = 276758, upload-time = "2026-09-29T00:48:34.72Z" }, + { url = "https://files.pythonhosted.org/packages/4d/96/56808fe029553d7d4c703414f2a527faad2ea2bfa9ca094a2e7f8762b530/regex-2026.9.29-cp314-cp314t-win_amd64.whl", hash = "sha256:bf48516e35cf848390ea68850aba53e7c333720d2945b4d2c25b69fc5171723f", size = 286527, upload-time = "2026-09-29T00:48:36.864Z" }, + { url = "https://files.pythonhosted.org/packages/01/aa/074e2cfb3d8101a6a764aba5f7c5d1e21de087483e35bdc0c4ce2eb60364/regex-2026.9.29-cp314-cp314t-win_arm64.whl", hash = "sha256:9173db3be74a35cb6731701094b98120f7ee4876a287882a59cdea1fa7da342f", size = 285954, upload-time = "2026-09-29T00:48:38.901Z" }, + { url = "https://files.pythonhosted.org/packages/a7/dc/d84990386c9dfdf8c377f00f371b241fdc9a2c8aea0e3d66941b2e51be0b/regex-2026.9.29-cp315-cp315-macosx_10_15_universal2.whl", hash = "sha256:c3589f40749acce747510bf5d589d54e376cb0930ea58b35effac97e5312b0c1", size = 497836, upload-time = "2026-09-29T00:48:40.858Z" }, + { url = "https://files.pythonhosted.org/packages/c2/ab/a569ebde875fa12ff8c6c9a30e07503620f195e4be4d54c3d3ee8eecc283/regex-2026.9.29-cp315-cp315-macosx_10_15_x86_64.whl", hash = "sha256:32ab11df9677ca80bcbb5fe4eb1da9109a5019239a054836efc6fa1c64e683cf", size = 296244, upload-time = "2026-09-29T00:48:42.952Z" }, + { url = "https://files.pythonhosted.org/packages/f3/3e/7d548e82a108e7c8b2d5246650e397a2f8db599f9b2e975466939c5b4e70/regex-2026.9.29-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:7c03031610e3e6ed1768a2b7a8fc84637c1257b50c5eacaf094c6e17a84fc563", size = 293748, upload-time = "2026-09-29T00:48:44.985Z" }, + { url = "https://files.pythonhosted.org/packages/40/34/a8e19a52f452bbb07b32a2bef70dcdf90c2737049749f74cc12d7486fb4f/regex-2026.9.29-cp315-cp315-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:42e82e578c904445d4c8a35b8f28052cf567593215fa5db06266fbc6f77aaa2e", size = 807840, upload-time = "2026-09-29T00:48:46.948Z" }, + { url = "https://files.pythonhosted.org/packages/88/7b/11fbd4640b3bb82b72822a63c20ade4013d562d291703a9debeedc24e682/regex-2026.9.29-cp315-cp315-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:0b65c72739f981377c9c22e0c5c3cd7f42da7bd8a3c9209330fac772c7d893ed", size = 879330, upload-time = "2026-09-29T00:48:49.168Z" }, + { url = "https://files.pythonhosted.org/packages/f3/55/de58c74f1f4e31586d83eb39c56872d686c4e0d0966d151884c833b94ced/regex-2026.9.29-cp315-cp315-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:4408b2b27a95ca8cc48b7411945753773353b5c93b307754781086c99d3a576f", size = 919251, upload-time = "2026-09-29T00:48:51.322Z" }, + { url = "https://files.pythonhosted.org/packages/81/42/a8c480f6dd5ac59fa28ddae79afd9d7ac7e596fdb61813adc65bb6e674b8/regex-2026.9.29-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a714befaacbd10092ffe4cea0d3c5f008fb9efe9bc322c715bcdfdee414b9a3d", size = 808808, upload-time = "2026-09-29T00:48:53.529Z" }, + { url = "https://files.pythonhosted.org/packages/68/60/0bc0d1ec8b37ad64be6fa30e035251f11de9667a0fac9e82ee74517d81be/regex-2026.9.29-cp315-cp315-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:33026515aebc0e70d1c89978e53e8d695d35d9e472f8d5b34465ba3c74028650", size = 789907, upload-time = "2026-09-29T00:48:56.036Z" }, + { url = "https://files.pythonhosted.org/packages/da/84/116a3ef19b3acfe81077f0bf2cbc7714a5e94bc8935b7243ab61cb0f1c3c/regex-2026.9.29-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:31b003f9a070335e2a8233ee9b14a3ca8e6d792012ae011f741bf0aaf11744c5", size = 795770, upload-time = "2026-09-29T00:48:58.284Z" }, + { url = "https://files.pythonhosted.org/packages/96/ba/e38c3f203e7e7e18c957d48e6cb6dbf96c11e95a44efa4a480522afc5d6d/regex-2026.9.29-cp315-cp315-musllinux_1_2_ppc64le.whl", hash = "sha256:c03c6eb6ece86dfdcbb34799efaa339b093132e1aceed491ba5e08fe06cdf699", size = 870671, upload-time = "2026-09-29T00:49:00.506Z" }, + { url = "https://files.pythonhosted.org/packages/2f/0f/9ee0b0cb76c55f63684bd7fff554978e8773b4fc86e2bcb2d50772dc1086/regex-2026.9.29-cp315-cp315-musllinux_1_2_riscv64.whl", hash = "sha256:a5300757f8a68f5b6cc33f57338d72a0e3589c5cc9ad5f8504ea06f028be582a", size = 778631, upload-time = "2026-09-29T00:49:02.984Z" }, + { url = "https://files.pythonhosted.org/packages/b6/19/e6e3eeb226af5872c4958002f6edef4e4f40ea4cc5f5665023f2019eb045/regex-2026.9.29-cp315-cp315-musllinux_1_2_s390x.whl", hash = "sha256:80c7cadd3fd2bfde5df8aa0787e315812cad0c313a753095d02f4c2b6c01677b", size = 862187, upload-time = "2026-09-29T00:49:05.264Z" }, + { url = "https://files.pythonhosted.org/packages/5b/62/823c102e106bb2711d6b7dfe5981552fe4467b2969c46a20c5c383cf498c/regex-2026.9.29-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:3f1e6cb402a89457582cd696f982559217d13484a193202c394015297968c86d", size = 798423, upload-time = "2026-09-29T00:49:07.644Z" }, + { url = "https://files.pythonhosted.org/packages/37/e0/e927776258fa70b2f6feffc3be584ffc85ba4c1e20a320f0aee9a632fc7d/regex-2026.9.29-cp315-cp315-win32.whl", hash = "sha256:a64b85a4760337cfefdb27d42da6ed8b58e8cde3f2d57b6ef43e76ef6ea9ef47", size = 274757, upload-time = "2026-09-29T00:49:10.513Z" }, + { url = "https://files.pythonhosted.org/packages/77/04/358de85d1860238e1b4fa98fc2c80c990124a25d2e14739e28cc02c25562/regex-2026.9.29-cp315-cp315-win_amd64.whl", hash = "sha256:b3e445b66c80b4eb4234e855ce94d9adc183eedbd632816228d89930b91b2c5b", size = 283824, upload-time = "2026-09-29T00:49:12.849Z" }, + { url = "https://files.pythonhosted.org/packages/92/d3/d5c5b264784a5ab2b0f8cf620c1eeb4dbf3440d306761905e7d99345bef5/regex-2026.9.29-cp315-cp315-win_arm64.whl", hash = "sha256:8f39588af4731c8923c26810eb3b33f76f17633985e40f59c3cd45a33805a895", size = 283664, upload-time = "2026-09-29T00:49:15.331Z" }, + { url = "https://files.pythonhosted.org/packages/02/dc/f63ec2c201445ce1150fe780f5c56f16a10124d9a9da3a93161dbb0d8892/regex-2026.9.29-cp315-cp315t-macosx_10_15_universal2.whl", hash = "sha256:fb99cc9d45f48895d9d67f6a0b8a57f08d39c174d9f25ad97a313e0470267b1c", size = 501549, upload-time = "2026-09-29T00:49:17.705Z" }, + { url = "https://files.pythonhosted.org/packages/9a/5c/d2a698dc6bfc11fbce03f1cb0249c13284e93b79ed11f893edf6fac431c9/regex-2026.9.29-cp315-cp315t-macosx_10_15_x86_64.whl", hash = "sha256:720537c7ea6f80dc61913184edb0ce2497a306b39ef19f28505b322553d52bdb", size = 298187, upload-time = "2026-09-29T00:49:20.171Z" }, + { url = "https://files.pythonhosted.org/packages/85/b7/88dcdb38cd3935d4ee9e9ce9b8e56cb3b3518d1f020acfa7dd62ad289bf8/regex-2026.9.29-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:0fd2c901cc307a745ad4bc87f20060d7a0825a3371d1e93488af22e7a387f78f", size = 296157, upload-time = "2026-09-29T00:49:22.342Z" }, + { url = "https://files.pythonhosted.org/packages/d3/8e/ba6c01dde33a69fc294b38b43f6677baaa5735a6248f39708031a738158a/regex-2026.9.29-cp315-cp315t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b11b589e00095ec69cf79841a76360f9b079e95b0368a25b5ebb951ab0c157ff", size = 818468, upload-time = "2026-09-29T00:49:24.612Z" }, + { url = "https://files.pythonhosted.org/packages/2a/f1/2586693e3a2d6b1247852593d37a6c17b42a92ee44f7cdcb9a0c1494e64a/regex-2026.9.29-cp315-cp315t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:d7cab119d0df0b9413f106b4d7fc34f2872d3574ed3806fb48959c830b1537da", size = 882825, upload-time = "2026-09-29T00:49:26.996Z" }, + { url = "https://files.pythonhosted.org/packages/30/51/084f3e7bdcd0e9c33665c938cf5d134dc3548cbb4a75f0197ec7bfd754b1/regex-2026.9.29-cp315-cp315t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b89efc38431793d28b7cd91227e2f952ad7c48df19132b17f43a5fec3c14143b", size = 923314, upload-time = "2026-09-29T00:49:29.822Z" }, + { url = "https://files.pythonhosted.org/packages/5a/f1/066c6fc23b7dc229789c21c880b5ba5ad689fb95fed12e078266f55a1f9b/regex-2026.9.29-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:80a5ea3b4fd9d6a5b9a44f7976a9acaaab35aa3c1f6b29e5bd857dfabaded223", size = 822222, upload-time = "2026-09-29T00:49:32.404Z" }, + { url = "https://files.pythonhosted.org/packages/0a/56/592cd46fdb8f2f8682a1d7fd1310e4d0bcb93fbd0e6bbe4141ac28240227/regex-2026.9.29-cp315-cp315t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:19959129885356df0e97556856f77eb2888380dac18bed075a7c05c5128c618d", size = 794882, upload-time = "2026-09-29T00:49:35.076Z" }, + { url = "https://files.pythonhosted.org/packages/ee/4d/d65384bb071c864b01aa8314e3a6a687845ebd57588390976edc960c218b/regex-2026.9.29-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:6a1a824fbed817e0a891103886b68f063b1e83cc51bc97192a90a60195a9291f", size = 805887, upload-time = "2026-09-29T00:49:37.395Z" }, + { url = "https://files.pythonhosted.org/packages/65/b6/358de0d8f40d5178e4f7e7e121cfd5b961c812b77a055d11f5079e3f8fd7/regex-2026.9.29-cp315-cp315t-musllinux_1_2_ppc64le.whl", hash = "sha256:1ba8c6a416569ce0d37e83e28a254a61dc99a419084dfb6476cea02d997f74fa", size = 872901, upload-time = "2026-09-29T00:49:39.927Z" }, + { url = "https://files.pythonhosted.org/packages/00/06/6bfded72d043240c6b52bbb5e16f639d81affbf7484b4fe2ec45f3d4afc9/regex-2026.9.29-cp315-cp315t-musllinux_1_2_riscv64.whl", hash = "sha256:446654b29bfaa30500d80947eda42cef1449dc8a87f4e3cf061cc8485d3a1f0b", size = 782970, upload-time = "2026-09-29T00:49:42.581Z" }, + { url = "https://files.pythonhosted.org/packages/5a/20/9f418a50baa78b3ed8308fcb0cc49e472dd000b7ef935a7295af202ea744/regex-2026.9.29-cp315-cp315t-musllinux_1_2_s390x.whl", hash = "sha256:bf3c49863c23a1ad6da9c30351aed6cff8d5ddbeb63c5c8420ae54e98c7d0138", size = 865441, upload-time = "2026-09-29T00:49:45.238Z" }, + { url = "https://files.pythonhosted.org/packages/2c/29/817c7eacdeaf8463123e949bd394c39ad024eea1ec38ddf5ad141da2f3bd/regex-2026.9.29-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:01000ddf0e3ffef97f2413ceb514f6313040106b6d18a03ee00a4fe35c1eb1db", size = 809431, upload-time = "2026-09-29T00:49:47.878Z" }, + { url = "https://files.pythonhosted.org/packages/63/0b/83aab3b5b739947f744135a7a3a446e25433ebc92b05e01aae197ccbfdda/regex-2026.9.29-cp315-cp315t-win32.whl", hash = "sha256:c4e38dd8f39c43a91d2410ad2b85610701b0979342c3df1d69eaf8e838c757d8", size = 276964, upload-time = "2026-09-29T00:49:50.524Z" }, + { url = "https://files.pythonhosted.org/packages/72/f2/6314b5fc68789b5dcc38885bc6e3d6986b34fb3372b7231088ee5cecaa05/regex-2026.9.29-cp315-cp315t-win_amd64.whl", hash = "sha256:e2c89e9b762c57f59d5e99ee8b20202adb892e35f8d3485741340999ca55058e", size = 286487, upload-time = "2026-09-29T00:49:53.224Z" }, + { url = "https://files.pythonhosted.org/packages/56/bc/97b2245c8c7b2dd01f2db74f2bea003cd33c15009b4996a2447f46b5325c/regex-2026.9.29-cp315-cp315t-win_arm64.whl", hash = "sha256:e8c65ef3862a8ad6e86492b6ed9327805dd66904c012bd3649dc67d822ed6c34", size = 285955, upload-time = "2026-09-29T00:49:55.655Z" }, ] [[package]] @@ -3408,7 +3430,7 @@ dependencies = [ { name = "filelock" }, { name = "firecrawl-anydoc" }, { name = "httpx" }, - { name = "jieba-py" }, + { name = "jieba" }, { name = "litellm" }, { name = "markitdown", extra = ["docx", "pdf", "pptx", "xls", "xlsx"] }, { name = "mcp" }, @@ -3424,6 +3446,7 @@ dependencies = [ { name = "tzdata" }, { name = "uvicorn", extra = ["standard"] }, { name = "zleap-sag" }, + { name = "zleap-sag2" }, ] [package.optional-dependencies] @@ -3456,7 +3479,7 @@ requires-dist = [ { name = "filelock", specifier = ">=3.16,<4" }, { name = "firecrawl-anydoc", specifier = "==0.2.4" }, { name = "httpx", specifier = ">=0.27" }, - { name = "jieba-py", specifier = ">=0.46.12,<0.47" }, + { name = "jieba", specifier = "==0.42.1" }, { name = "litellm", specifier = "==1.103.0" }, { name = "markitdown", extras = ["docx", "pdf", "pptx", "xls", "xlsx"], specifier = ">=0.1.6,<0.2" }, { name = "mcp", specifier = ">=1.28,<2" }, @@ -3477,6 +3500,7 @@ requires-dist = [ { name = "uvicorn", extras = ["standard"], specifier = ">=0.30" }, { name = "zleap-sag", specifier = "==0.15.0" }, { name = "zleap-sag", extras = ["postgres"], marker = "extra == 'postgres'", specifier = "==0.15.0" }, + { name = "zleap-sag2", specifier = "==0.1.0" }, ] provides-extras = ["postgres", "dev", "desktop"] @@ -3609,56 +3633,63 @@ wheels = [ [[package]] name = "tiktoken" -version = "0.13.0" +version = "0.14.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "regex" }, { name = "requests" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/e4/e5/5f3cb2159769d0f4324c0e9e87f9de3c4b1cd45848a96b2eb3566ad5ca77/tiktoken-0.13.0.tar.gz", hash = "sha256:c9435714c3a84c2319499de9a300c0e604449dd0799ff246458b3bb6a7f433c1", size = 38986, upload-time = "2026-05-15T04:51:27.153Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/1a/4c/1bc81f4cd53e827c4ee67ca951b5935724716049452d8dfa09b8b82372bb/tiktoken-0.13.0-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:7bfe1849caa65d1e1d9871817170ec497bbb7984e182012e1bdce72f66608cdb", size = 1036353, upload-time = "2026-05-15T04:50:21.757Z" }, - { url = "https://files.pythonhosted.org/packages/75/91/10b9c7076bc02c246c853201fdbbe300a4b8c5ed7b84c25f7403f4e32655/tiktoken-0.13.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:91c180fe255bd5a86d8316210d2833a1d4d33d026cd86a67812f4773743c8d26", size = 984644, upload-time = "2026-05-15T04:50:23.256Z" }, - { url = "https://files.pythonhosted.org/packages/4e/e4/fceae98015fab47fcd49b8bd7f46145bcd187a47e0add1e5378ed67ef980/tiktoken-0.13.0-cp311-cp311-manylinux_2_28_aarch64.whl", hash = "sha256:059c8ecf554eb5b41e6e054ba467b871b03277d267dee7244380aca4359747d4", size = 1119261, upload-time = "2026-05-15T04:50:24.348Z" }, - { url = "https://files.pythonhosted.org/packages/f9/39/fe42ad00de01a8c4a49ad8649a2c8a316835a9cad5961b11d21eac0020a5/tiktoken-0.13.0-cp311-cp311-manylinux_2_28_x86_64.whl", hash = "sha256:36217497eaffc158607a3b26f065300db2aefd43b115263f3b9688ce38146173", size = 1138253, upload-time = "2026-05-15T04:50:25.505Z" }, - { url = "https://files.pythonhosted.org/packages/03/c4/ccee1ecccca107e9a16efcecdeeb964c325305038554d466ece65b42338f/tiktoken-0.13.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:303f7d91b4fce3baddbcde05c139091d4caa5026ac7214c1dc7ff7a71ee429ff", size = 1185747, upload-time = "2026-05-15T04:50:27.02Z" }, - { url = "https://files.pythonhosted.org/packages/9d/03/cd0cba295522b91eb55c6b2704f1df895f8226cfe60ab10d4d51d0cc9e69/tiktoken-0.13.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:5d48843bee149630eb735a99e1f4a85b47308d21868ea63163f6e87768d3cfed", size = 1241265, upload-time = "2026-05-15T04:50:28.815Z" }, - { url = "https://files.pythonhosted.org/packages/7e/25/a10efd564402d82c2ff50d12057353ace447aa8007deceaa48641f63d35c/tiktoken-0.13.0-cp311-cp311-win_amd64.whl", hash = "sha256:fc1c44cd37b43fc46bae593129164f4f281e82ea116b57a85aa81bda57eafc94", size = 876509, upload-time = "2026-05-15T04:50:30.026Z" }, - { url = "https://files.pythonhosted.org/packages/85/8e/144bde4e01df66b34bb865557c7cd754ed08b036217ebd79c9db5e9048a9/tiktoken-0.13.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:32ac870a806cfb260a02d0cb70426aef02e038297f8ad50df5040bb5af360791", size = 1034888, upload-time = "2026-05-15T04:50:31.579Z" }, - { url = "https://files.pythonhosted.org/packages/36/18/d4ac9d20956cdebca04841316660ed584c2fecdc2b81722a28bc7ad3b1e4/tiktoken-0.13.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:4d9980f11429ed2d737c463bb1fb78cf330caa026adf002f714aced7849a687b", size = 982970, upload-time = "2026-05-15T04:50:32.961Z" }, - { url = "https://files.pythonhosted.org/packages/74/ed/6bb8d05b9f731f749fee5c6f5ca63e981143c826a5985877330507bd13b7/tiktoken-0.13.0-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:3f277ebea5edd7b8bf03c6f9431e1d67d517530115572b2dc1d465326e8f88c7", size = 1115741, upload-time = "2026-05-15T04:50:34.475Z" }, - { url = "https://files.pythonhosted.org/packages/34/de/2ca96b07a82d972b74fe4b46de055b79c904e45c7eab699354a0bfa697dc/tiktoken-0.13.0-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:a116178fa7e1b4065bff05214360373a65cac22f965be7b3f73d00a0dbfe7649", size = 1136523, upload-time = "2026-05-15T04:50:35.782Z" }, - { url = "https://files.pythonhosted.org/packages/ee/dc/9dafec002c2d4424378563cf4cf5c7fb93631d2a55013c8b87554ee4012c/tiktoken-0.13.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:2c397ddda233208345b01bd30f2fca79ff730e55731d0108a603f9bc57f6af3b", size = 1181954, upload-time = "2026-05-15T04:50:36.99Z" }, - { url = "https://files.pythonhosted.org/packages/a1/d0/1f8578c45b2f24759b46f0b50d31878c63c73e6bf0f2227e10ec5c5408dc/tiktoken-0.13.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:95097e4f89b06403976e498abf61a0ee73a7497e73fb599cb211d8197a054d91", size = 1240069, upload-time = "2026-05-15T04:50:38.221Z" }, - { url = "https://files.pythonhosted.org/packages/aa/90/28d7f154888610aa9237e541986beb62b479df29d193a5a0617dbb1514d0/tiktoken-0.13.0-cp312-cp312-win_amd64.whl", hash = "sha256:8f2d16e7a7c783ad81f36e457d046d1f1c8af70b22aec8a13238efe531977c41", size = 874748, upload-time = "2026-05-15T04:50:39.587Z" }, - { url = "https://files.pythonhosted.org/packages/9c/83/b096c859c2a47c11731bf2f5885f4028b809dfe2396582883eed9cae372f/tiktoken-0.13.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:5df5d1507bd245f1ccad4a074698240021239e455eb0bb4ced4e3d7181872154", size = 1034228, upload-time = "2026-05-15T04:50:40.988Z" }, - { url = "https://files.pythonhosted.org/packages/53/61/c68e123b6d753e3fc2751e9b18e732c9d8bf1e1926762e736eee935d931c/tiktoken-0.13.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:8fe806a50664e83a6ffd56cbd1e4f5dcc6cd32a3e7538f70dc38b1a271384545", size = 982978, upload-time = "2026-05-15T04:50:42.195Z" }, - { url = "https://files.pythonhosted.org/packages/ef/8b/96cc178cc584e65d363134500f297790b06cd48cdeb1e8fcf7bbe60f4715/tiktoken-0.13.0-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:125bc05005e747f993a83dc67934249932d6e4209854452cd4c0b1d53fba3ba2", size = 1116355, upload-time = "2026-05-15T04:50:43.564Z" }, - { url = "https://files.pythonhosted.org/packages/86/f5/bab735d2c72ea55404b295d02d092644eb5f7cc6205e34d35eb9abfb9ab2/tiktoken-0.13.0-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:5e6358911cab4adee6712da27d65573496a4f68cf8a2b5fca6a4ad10fc5748cf", size = 1135772, upload-time = "2026-05-15T04:50:44.782Z" }, - { url = "https://files.pythonhosted.org/packages/4e/b9/6de04ebdf904edfaad87788011b3735087a0c9ea671b9027e1e4e965e8c8/tiktoken-0.13.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:975cbd78d085d75d26b59660e262736dcaed1e35f8f142cd6291025c01d25486", size = 1182415, upload-time = "2026-05-15T04:50:46.422Z" }, - { url = "https://files.pythonhosted.org/packages/0d/9c/470a05f3b1caf038f44880e334d47ab674e0c80d514c66b375d14d5afa10/tiktoken-0.13.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:75ab9bc99fa020a4c283424590ecd7f3afd70c1c281cb3fa3192a6c3af9f9615", size = 1239879, upload-time = "2026-05-15T04:50:48.052Z" }, - { url = "https://files.pythonhosted.org/packages/42/a6/c1936d16055436cb32e6c6128d68629622e00f4768562f55653752d34768/tiktoken-0.13.0-cp313-cp313-win_amd64.whl", hash = "sha256:6b1615f0ff71953d19729ceb18865429c185b0a23c5353f1bbca34a394bf60f7", size = 874829, upload-time = "2026-05-15T04:50:49.202Z" }, - { url = "https://files.pythonhosted.org/packages/d6/07/acb5992c3772b5a36284f742cfb7a5895aa4471d1848ac31464ad50d7fdf/tiktoken-0.13.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:6eb4a5bfbc6426938026b1a334e898ac53541360d62d8c689870160cc80abd67", size = 1033600, upload-time = "2026-05-15T04:50:50.4Z" }, - { url = "https://files.pythonhosted.org/packages/14/e9/742e9aec30f59b9f161f7ff7cd072e02ea836c9e1c0854a8076dfcd40d5c/tiktoken-0.13.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:43cee3e5400573b2046fbf092cc7a5bc30164f9e4c95ce20714da929df48737a", size = 982516, upload-time = "2026-05-15T04:50:52.03Z" }, - { url = "https://files.pythonhosted.org/packages/72/74/ca1541b053e7648254d2e4b42a253e1bb4359f2c91a0a8d49228c794e1a0/tiktoken-0.13.0-cp313-cp313t-manylinux_2_28_aarch64.whl", hash = "sha256:7de52e3f566d19b3b11bd37eea552c6c305ad74081f736882bd44d148ed4c48d", size = 1115518, upload-time = "2026-05-15T04:50:53.543Z" }, - { url = "https://files.pythonhosted.org/packages/46/e3/93825eaf5a4a504795b787e5d5dea07fbeb3dabf97aa7b450be8bde59c89/tiktoken-0.13.0-cp313-cp313t-manylinux_2_28_x86_64.whl", hash = "sha256:51384448aa508e4df84c0f7c1dc3211c7f7b8096325660ee5fc82f3e11b381ce", size = 1136867, upload-time = "2026-05-15T04:50:55.191Z" }, - { url = "https://files.pythonhosted.org/packages/8c/46/002b68de6827091d5ae90b048f326e8aad8d953520950e5ce1508879414f/tiktoken-0.13.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:e28157350f7ebf35008dd8e9e0fdb621f976e4230c881099c85e8cf07eaa50e2", size = 1181826, upload-time = "2026-05-15T04:50:56.296Z" }, - { url = "https://files.pythonhosted.org/packages/db/c6/d393e3185a276505182f7abd93fe714f3c444a2be9180798fa052347504e/tiktoken-0.13.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:165cf1820ea4a354985c2490a5205d4cc74661c934aca79dd0368232fff94e0f", size = 1239489, upload-time = "2026-05-15T04:50:57.918Z" }, - { url = "https://files.pythonhosted.org/packages/b7/4d/bc07d1f1635d4897a202acc0ae11c2886eaa7325c359ba4741b47bf8e225/tiktoken-0.13.0-cp313-cp313t-win_amd64.whl", hash = "sha256:6c43a675ca14f6f2749ba7f12075d37456015a24b859f2517b9beb4ef30807ec", size = 873820, upload-time = "2026-05-15T04:50:59.528Z" }, - { url = "https://files.pythonhosted.org/packages/8c/93/0dd6adca026a616c3a92974566b43381eea4b475ce1f36c062b8271a9ac5/tiktoken-0.13.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:eaaaef47c2406277181d2086484c317bf7fc433e2d5d03ff94f56b0dcec87471", size = 1034977, upload-time = "2026-05-15T04:51:00.957Z" }, - { url = "https://files.pythonhosted.org/packages/d9/77/5ec6e6bc5b30bed6d93f7f2162d8f6b32437b3ba27cb527cfe004f6109c9/tiktoken-0.13.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:ca8b310bd93b3772cb1b7922d915446864860f562bdfe4825c63a0aed3fb28cd", size = 983635, upload-time = "2026-05-15T04:51:02.629Z" }, - { url = "https://files.pythonhosted.org/packages/94/b0/c8ae9aff00d625c50659b4513e707a0462c4bf5d4d6cc1b802103225c02e/tiktoken-0.13.0-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:32e0c12305105002c047b3bb1070b0dd9a73b0cb3b2856a8972b810e7a4f5881", size = 1116036, upload-time = "2026-05-15T04:51:04.082Z" }, - { url = "https://files.pythonhosted.org/packages/1b/ac/6a5dddd1d0a6018ecb389bd0353e6b4a515eb4d2286611bd0ace1937b9e1/tiktoken-0.13.0-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:5ba5fd62507a932d1241346179e3b39bc7bf7408f03c272652d93b3bedf5db24", size = 1135544, upload-time = "2026-05-15T04:51:05.229Z" }, - { url = "https://files.pythonhosted.org/packages/f4/b8/585032b4384b2f7dcdaddcb52865c83a701a420d09e3c2b4a2be1c450c57/tiktoken-0.13.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:d108bc2d470fc53c8ecd24f2c0fd2b5f98c33e87cdb6aa2e9b8c5dced703d273", size = 1182217, upload-time = "2026-05-15T04:51:06.517Z" }, - { url = "https://files.pythonhosted.org/packages/cd/b6/993ff1ded3958215fd341a847b8e5ffeb5de473f435296870d314fc91ac4/tiktoken-0.13.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:cb99cb5127449f58d0a2d5f5ccfb390d8dbdfd919c221246caaee29d8725ed51", size = 1239404, upload-time = "2026-05-15T04:51:07.843Z" }, - { url = "https://files.pythonhosted.org/packages/dd/3d/fef7e06e3b33e7538db0ced734cf9fe23b6832d2ac4990c119c377aec55e/tiktoken-0.13.0-cp314-cp314-win_amd64.whl", hash = "sha256:115c4f26ffa11caac8b54eea35c2ad38c612c20a48d35dd15d70a02ac6f51f58", size = 918686, upload-time = "2026-05-15T04:51:08.925Z" }, - { url = "https://files.pythonhosted.org/packages/c1/82/a7fc44582bc32ab00de988a2299bf77c077f59068b233109e34b7d6ca7e6/tiktoken-0.13.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:472527e9132952f2fbf77cd290658bacf003d4d5a3fabc18e5fbd407cbae4d9b", size = 1034454, upload-time = "2026-05-15T04:51:10.035Z" }, - { url = "https://files.pythonhosted.org/packages/37/d0/24d8a890c14f432a05cea669c17bebeaa99f96a7c79523b590f564246411/tiktoken-0.13.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:4e2f67d27c9626cdd25fe33d9313c5cdb3d8d82da646b68d6eb8e7e9c20e6448", size = 982976, upload-time = "2026-05-15T04:51:11.23Z" }, - { url = "https://files.pythonhosted.org/packages/49/b7/2ab43f62788a9266187a9bfc1d3af99ad83e5eaa25fbef168a69cd5ad14f/tiktoken-0.13.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:2b920b35805cd64585a37c3dc7ce65fba4d2d36016be01e1d7942482ca29093a", size = 1115526, upload-time = "2026-05-15T04:51:12.608Z" }, - { url = "https://files.pythonhosted.org/packages/64/39/1494321ed323ce7a14d88e3cd6cb9058625977df1c6961ddc492bd10a9f3/tiktoken-0.13.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:493af3aa28a4aaf2e3d2600a2ee717252c9bf5ab38fff94eb5a02db5ab77e5ad", size = 1136466, upload-time = "2026-05-15T04:51:13.926Z" }, - { url = "https://files.pythonhosted.org/packages/96/d9/dfd086aa2d918c563a140720e0ce296cada1634efd2783d5cf51e05f984e/tiktoken-0.13.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:6644c9c2b5cf3916f5a3641d7d12fdb3f006a7b3d9ff6acdaec44e29ab1ff91e", size = 1181863, upload-time = "2026-05-15T04:51:15.025Z" }, - { url = "https://files.pythonhosted.org/packages/2f/68/a18b4f307086954fdae32714cb4f85562e34f9d34ab206e61f1816aa6018/tiktoken-0.13.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:5cb65b60b9408563676d874a3a4ee573370066f0dc4e29d84e82e989c6517424", size = 1239218, upload-time = "2026-05-15T04:51:16.103Z" }, - { url = "https://files.pythonhosted.org/packages/16/5b/f2aa703a4fc5d2dff73460a7d46cc2f3f44aa0f3dd8eeb20d2a0ecf68862/tiktoken-0.13.0-cp314-cp314t-win_amd64.whl", hash = "sha256:85b78cc3a2c3d48723ca751fa981f1fedccd54194ca0471b957364353a898b07", size = 918110, upload-time = "2026-05-15T04:51:17.237Z" }, +sdist = { url = "https://files.pythonhosted.org/packages/66/62/167a842aa0429d45f5e797354fd4343a96f6043d67d0513c675c7b8d36e6/tiktoken-0.14.0.tar.gz", hash = "sha256:231dec90efcdccf1b565a1416107736f1e09b1a08fe736ef9d6363e626d03874", size = 38898, upload-time = "2026-08-17T19:49:49.514Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/8f/c5/9d848b7f408241171e1f843deb8bfa626086452bc9c78beee500829583e3/tiktoken-0.14.0-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:c2edf09b381fafbc014ae8e018ed25087abb9a3dafa8465a0ea63c6558c47a79", size = 1094971, upload-time = "2026-08-17T19:48:40.347Z" }, + { url = "https://files.pythonhosted.org/packages/2d/a9/d94302340304328961d6f0c35ca4e60617fbb57a5cf667e2ed1692cb9e57/tiktoken-0.14.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:cd8ca1305c1c902fe42c486165f2e4808d9997625c98ffb05b9e0366d99d3948", size = 1042916, upload-time = "2026-08-17T19:48:41.541Z" }, + { url = "https://files.pythonhosted.org/packages/c8/b6/31da98ee871383509cae2ba96a9ddef1965e3c4f8cb6dc7bcda3379398db/tiktoken-0.14.0-cp311-cp311-manylinux_2_28_aarch64.whl", hash = "sha256:1f83081065ee5833d35b49e9180f3d8d15622a603dd1c435da0da6cc12b3662f", size = 1188650, upload-time = "2026-08-17T19:48:42.729Z" }, + { url = "https://files.pythonhosted.org/packages/24/65/8c5dddd7cb67f6571d154a58d7c6e2f07da54bf84c49b6a1839965b7c35e/tiktoken-0.14.0-cp311-cp311-manylinux_2_28_x86_64.whl", hash = "sha256:f5e7665f6624e052e5e7f6a36919ab69279decdc976d7b16b4fa15e1897d0513", size = 1206378, upload-time = "2026-08-17T19:48:44.013Z" }, + { url = "https://files.pythonhosted.org/packages/d1/04/522ec59d30dd9a2f3ab837011cd4fc5d1178dc4a2fa07c9fa4b90af6ba9d/tiktoken-0.14.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:144a3fc369f92b7d548995217c5d6e84038d3572157a0f6f34080d65291d0f78", size = 1253694, upload-time = "2026-08-17T19:48:45.597Z" }, + { url = "https://files.pythonhosted.org/packages/69/84/9019e272bad188a1c61ecf44f25a9ba2368744644e3ac1f3d6516f3c9e80/tiktoken-0.14.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:151d37a150c8f3dfc5f4345597b10e101876bd1bd13494e0185af6b508758d2e", size = 1317873, upload-time = "2026-08-17T19:48:46.792Z" }, + { url = "https://files.pythonhosted.org/packages/24/7f/fff1217240343c0c11b5938b98aeae0e3a266cacfac25f86f91cdcd748f0/tiktoken-0.14.0-cp311-cp311-win_amd64.whl", hash = "sha256:c77d4a3e1deb2707819df92046b89aad1ac81d27e07616b797cbff3f62c037da", size = 944395, upload-time = "2026-08-17T19:48:48.028Z" }, + { url = "https://files.pythonhosted.org/packages/8c/da/e273746b9d24a63c776bc60fba914351573ad9c575b52601eb5e60632564/tiktoken-0.14.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:8e947aefe98ef74cce94923f90e48c98fe34eb1ec0a6bfdfadfc5a96359bfc36", size = 1094408, upload-time = "2026-08-17T19:48:49.269Z" }, + { url = "https://files.pythonhosted.org/packages/69/9f/fe6b1aca23331aa5271df5a4bd07bf68a7059254d47faee1b8272592a777/tiktoken-0.14.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:d6cebe67765569df3dafac8474e4eccf5c19d24140492567a5e58a11445732a4", size = 1038499, upload-time = "2026-08-17T19:48:50.666Z" }, + { url = "https://files.pythonhosted.org/packages/0b/35/e9f47647c9e163bd1de30fe1a491669b7248cfc67b7404c35c009a701e1a/tiktoken-0.14.0-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:7db45b98e94adf4173a5cd7422b150999a7ee11ff847783a14f6e1b80cc38cb6", size = 1186355, upload-time = "2026-08-17T19:48:51.93Z" }, + { url = "https://files.pythonhosted.org/packages/51/11/9976ad86980a00cdef05e730a0127a2578a1bc6d11644d8d47246de2eb26/tiktoken-0.14.0-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:7896eea257fe497a2b7134474d909156c6744ce8da35bce88011a960e008aa0d", size = 1204197, upload-time = "2026-08-17T19:48:53.18Z" }, + { url = "https://files.pythonhosted.org/packages/d4/9c/7035b0bcfaa68d1ee4803fc5be5214ad865669b05bd20e7105ae8a18afc6/tiktoken-0.14.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:b950248272f1b303dc32986396e2dccfa10cf6d1e83ec8f0bba1776660305482", size = 1250635, upload-time = "2026-08-17T19:48:54.392Z" }, + { url = "https://files.pythonhosted.org/packages/bc/1d/69cabf18bed7f4366da076735816abce0d4db3fae491ae338a6612128777/tiktoken-0.14.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:3de75343041a1c57333b1e707ac8a9769738241d7d6a55d39e12cf84548337c6", size = 1316085, upload-time = "2026-08-17T19:48:55.525Z" }, + { url = "https://files.pythonhosted.org/packages/bd/bd/a2e884fb1402cba5be08836590320012b2d8ada0e2eef9911a64df4bcd2d/tiktoken-0.14.0-cp312-cp312-win_amd64.whl", hash = "sha256:087538c080e5ff421abd3a0785ed63c5111d06af98e6cd0d374dbe5969147ca3", size = 941208, upload-time = "2026-08-17T19:48:56.938Z" }, + { url = "https://files.pythonhosted.org/packages/50/53/ee1453623bf65f019328721ccb6587846d2c5b7b82f34e73ca09101f072e/tiktoken-0.14.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e9c5fe393aab56469f04e432ff851216d3def3436cf5f07e442a240164bf500f", size = 1094198, upload-time = "2026-08-17T19:48:57.955Z" }, + { url = "https://files.pythonhosted.org/packages/ad/5f/6448cfe278c3664ba9ec5b5ac08344341f7dc3d42888476e215a14eda2be/tiktoken-0.14.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:cbe2cc3bba939bcdaf103e03df9d5039d33887080b315624be28ec69059e5f94", size = 1038820, upload-time = "2026-08-17T19:48:59.015Z" }, + { url = "https://files.pythonhosted.org/packages/69/3b/d67eac1bcce9dee3abe23aff5e3ded3116bbebaf67b80a0811c06d3806fc/tiktoken-0.14.0-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:2157f52e4b4d7ac5ecc7457b3716834706e7ef9a46f5144029bfeb7cf71f4e06", size = 1186175, upload-time = "2026-08-17T19:49:00.068Z" }, + { url = "https://files.pythonhosted.org/packages/37/62/cae690d9783146b0f81f564ada0f8f611de68178c0c9c7e1e969f0516b48/tiktoken-0.14.0-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:26e60f6a956ee171ab728b37b8439905d7ea1db435c30f9822f291e9861c861d", size = 1203884, upload-time = "2026-08-17T19:49:01.163Z" }, + { url = "https://files.pythonhosted.org/packages/b9/1e/633e30237b94e383cf814145499079f3bb9cdd4aeafc1bc42e01b0f810a6/tiktoken-0.14.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:380873f330b741c4435574f37edb20813d04603ace2d53e0a63560e1fec83010", size = 1250980, upload-time = "2026-08-17T19:49:02.274Z" }, + { url = "https://files.pythonhosted.org/packages/cb/56/4c12f07b812f84206f38d723eb1ebfdd34bad9309b5dbc0bee6bbcff4cbf/tiktoken-0.14.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:3fd7c14b1cb45b486c39fc9b3443bb341f3e2fc7e6f31247f3435a5836651632", size = 1315434, upload-time = "2026-08-17T19:49:03.434Z" }, + { url = "https://files.pythonhosted.org/packages/c9/e0/c65603f0c44811def666d3fbf611bf2af3b5e1ef613e06c19411419830b3/tiktoken-0.14.0-cp313-cp313-win_amd64.whl", hash = "sha256:90a762670c7f968184723769a06ed51f5cf5ce5dcd1e30164f25c72d85c2d1f1", size = 940883, upload-time = "2026-08-17T19:49:04.583Z" }, + { url = "https://files.pythonhosted.org/packages/59/b0/1cf129f4af8fc513931f931023def596b7c4bfc77026513cd9d851da9e88/tiktoken-0.14.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:e067f4cbcc5d036e8aff7fe7a6b530a8f4de2e4616ad9005a24a1879e24e6450", size = 1096273, upload-time = "2026-08-17T19:49:05.807Z" }, + { url = "https://files.pythonhosted.org/packages/62/85/2ae74575e321148484147e10b53c3b1717c59ebaa9edb4fe18b1f5c055f8/tiktoken-0.14.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:f2af4a336ea56d6c14f27741a0e1d8294a35dd0b038bcf990d232ebb54eb994b", size = 1040269, upload-time = "2026-08-17T19:49:06.943Z" }, + { url = "https://files.pythonhosted.org/packages/89/29/92a1120a12e4bcf2d5464350d1a91b68a433d63ce656bb7f806c27aec09c/tiktoken-0.14.0-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:f702e0aeeb6506e57687e881c59e844ebe8f0a6a097ddafe20e3ab25f387be4e", size = 1186101, upload-time = "2026-08-17T19:49:08.102Z" }, + { url = "https://files.pythonhosted.org/packages/5b/7d/144af98dc5ad68108451a82e2f5a17f80e2663f5115058b8dfd215c1ad02/tiktoken-0.14.0-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:e3442bbb2f0c588cec876061e37ae67b455b9df9978b003c8fe30e45f2ef5b42", size = 1204457, upload-time = "2026-08-17T19:49:09.28Z" }, + { url = "https://files.pythonhosted.org/packages/e6/1f/be7cb06ab2108f612f3e92e7b76cf391e192db0db37a984616f0cc32aafc/tiktoken-0.14.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:979c1524f753b662b0f3cd261b135afe6659cce33caaa7a5ea00dd1756b3055c", size = 1251716, upload-time = "2026-08-17T19:49:10.509Z" }, + { url = "https://files.pythonhosted.org/packages/ab/6b/81f158d0f90adb826cd704069c2129a046cb784a2a09861009519fc41cf4/tiktoken-0.14.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:2cc19ac87b41c9493c9778ff5847f0c8bbcf5bd0ec6b87ce06c1c802adc8a771", size = 1315432, upload-time = "2026-08-17T19:49:11.844Z" }, + { url = "https://files.pythonhosted.org/packages/fc/ec/f5fa35ec13f07279fdcaf3cc9c04bbb154ea591d23978651f2b672593e8a/tiktoken-0.14.0-cp314-cp314-win_amd64.whl", hash = "sha256:eceeff0c62419bc78d4b6e70a4762a4d25df3ae8f2d5946e3853ce93e7a57098", size = 988046, upload-time = "2026-08-17T19:49:13.282Z" }, + { url = "https://files.pythonhosted.org/packages/68/c9/7756717408d3d0dfea3f046c9466144b28afde39ff69d5808f2475dcd7f5/tiktoken-0.14.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:6eb94895c45f26bb8f5546e5fd8a069efcf6e3f108ea9d5cbe3bf6f7f3983438", size = 1096261, upload-time = "2026-08-17T19:49:14.351Z" }, + { url = "https://files.pythonhosted.org/packages/79/29/46ad8061f57bd9f8b2ea0aa82bf574e0f2aa040b0857a1582adba9957899/tiktoken-0.14.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:86951a971c53979ec857bd8c4a32dc227ab0fd33f6c12a3bd62d3fbf5f0bfcaa", size = 1040183, upload-time = "2026-08-17T19:49:15.707Z" }, + { url = "https://files.pythonhosted.org/packages/5a/7c/3184d17b868456f17b60b1a75f5ec0405618a43aa753336df341d8f11781/tiktoken-0.14.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:e2eca764c53490f8930dbce329e0769f11108d87d908282a80c5c130e26e7037", size = 1186719, upload-time = "2026-08-17T19:49:16.84Z" }, + { url = "https://files.pythonhosted.org/packages/0b/e8/46de4400d5bf859f640feee85bd7e32235f68ddf25db53c63be78e581e3a/tiktoken-0.14.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:26cc4b4840fa0e9f4b72ed489883e12f57e00d1021ca794720e3c29a12f0edef", size = 1204660, upload-time = "2026-08-17T19:49:17.987Z" }, + { url = "https://files.pythonhosted.org/packages/29/ce/af8964c38bc8226dd8950305b7a255fa33345d5572f78af7275a313d28e0/tiktoken-0.14.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:2fc834fbe3f6a0736905c36ab709537e6840dbd63b982dc9e0216ae7d305ba1a", size = 1250932, upload-time = "2026-08-17T19:49:19.28Z" }, + { url = "https://files.pythonhosted.org/packages/1d/4b/323631116fc986d9cc5bbeb2b8223c7c85e61a8bb94ea5ab4951023b149b/tiktoken-0.14.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:ca4db6ff5c5bf600f9b7761a0070ed44dfe5797a76bd432fb978bc480ef40c58", size = 1315190, upload-time = "2026-08-17T19:49:20.467Z" }, + { url = "https://files.pythonhosted.org/packages/18/8b/ba48a73729c9270989b36f37ab2ed5525e52690d715097c9fa791aaa5d05/tiktoken-0.14.0-cp314-cp314t-win_amd64.whl", hash = "sha256:7aab286a020660a039097912a088236b985d18a3090d73f136c4413d29d37ca0", size = 987717, upload-time = "2026-08-17T19:49:21.704Z" }, + { url = "https://files.pythonhosted.org/packages/1d/10/b73b7e319179e0f60b32475f783b044f9cece872c53b6662664e9084b0d0/tiktoken-0.14.0-cp315-cp315-macosx_10_15_x86_64.whl", hash = "sha256:14b47e3674f2624803a8acc8fb367b7e24fc53055f9df3296482fe9a3a34a232", size = 1096280, upload-time = "2026-08-17T19:49:22.779Z" }, + { url = "https://files.pythonhosted.org/packages/c2/6b/09999a9bf1d559670d1680e8f8e419ac0e2c5f6aac82e9bfdf70f260b30a/tiktoken-0.14.0-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:19d643d701fdaa70e5b9c7f8f96abcaffe77ca5e482a3a1a7dde46feb4284695", size = 1040433, upload-time = "2026-08-17T19:49:23.998Z" }, + { url = "https://files.pythonhosted.org/packages/cd/7b/8537be0836f3df99b2a636b44399bfa43cd757f2b8b4097dacb794cf24a7/tiktoken-0.14.0-cp315-cp315-manylinux_2_28_aarch64.whl", hash = "sha256:e4ddf863b59347deaa92302dcd90e5eb003cdc9be06ec2b692c38d1bdd9efd49", size = 1186989, upload-time = "2026-08-17T19:49:25.021Z" }, + { url = "https://files.pythonhosted.org/packages/7c/9d/f9c56d7a943a4468abf9ef37661bb9b8e0cd3aa8aa87368c7146cc3f3222/tiktoken-0.14.0-cp315-cp315-manylinux_2_28_x86_64.whl", hash = "sha256:60c47ca69ddda0dea8256fffd12e1b86f4b59734a20e4a70c61f63cc5f021df4", size = 1204615, upload-time = "2026-08-17T19:49:26.37Z" }, + { url = "https://files.pythonhosted.org/packages/4b/d2/98a38579db25c4a8a84e31dd95d9072ec5f21f7e70de591da0412e29b25b/tiktoken-0.14.0-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:728303a072163130c5b477b1f20d6211895569c1d5302c24ffc93a3009160871", size = 1251828, upload-time = "2026-08-17T19:49:27.423Z" }, + { url = "https://files.pythonhosted.org/packages/0c/83/467be424746c039c5493c0f4102feab16b9b48eb6f5c089b2a2438e3cde2/tiktoken-0.14.0-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:3c5349c9f916283bba32bec8af69b763e4faa304dc004d0eaaea66a3cf004c1f", size = 1316260, upload-time = "2026-08-17T19:49:29.101Z" }, + { url = "https://files.pythonhosted.org/packages/02/ee/ddf46ca78e371f5890e96b6e7d089a85b3536432be219851eb0481786ca8/tiktoken-0.14.0-cp315-cp315-win_amd64.whl", hash = "sha256:1b6e4adcfd285c44502aed51df98aaaca4f0fea028165dbf8a9e857b9f98d8ea", size = 988230, upload-time = "2026-08-17T19:49:30.246Z" }, + { url = "https://files.pythonhosted.org/packages/2a/00/5162e90c851a28da18ed382d34898b79a8022548e5619a64e14c03ce7c3d/tiktoken-0.14.0-cp315-cp315t-macosx_10_15_x86_64.whl", hash = "sha256:11d8211b290855d2721334ff17dd9b3a17bfb26872be01f25d73612ef7ece890", size = 1096186, upload-time = "2026-08-17T19:49:31.656Z" }, + { url = "https://files.pythonhosted.org/packages/65/97/a5a7bfccf25b1bb65e82bae8edff11ac3c9c041c374b7b4a823d60c38133/tiktoken-0.14.0-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:d0781223705199b289faa59601bb9c2441712d4c600dd13c43d8fd6a33d22cd5", size = 1039947, upload-time = "2026-08-17T19:49:32.848Z" }, + { url = "https://files.pythonhosted.org/packages/fb/ba/ef427fc638f1439181c5e12dd26b70e881861f89c007aa7e5b36300f8342/tiktoken-0.14.0-cp315-cp315t-manylinux_2_28_aarch64.whl", hash = "sha256:2ea70afba6b9eddbf22c165142e5f0a2ad7aa36a452873c48b57bb2aeb8492ae", size = 1186997, upload-time = "2026-08-17T19:49:34.121Z" }, + { url = "https://files.pythonhosted.org/packages/3e/88/2f3f85a968cdc514152129af0a060ebcccb067005a2f29b0d5ef3c838514/tiktoken-0.14.0-cp315-cp315t-manylinux_2_28_x86_64.whl", hash = "sha256:78571efc311c30b73f31eb949a921d6dac39a5d9dc42d1cfa8f8db157b3447b1", size = 1205211, upload-time = "2026-08-17T19:49:35.284Z" }, + { url = "https://files.pythonhosted.org/packages/4e/f6/80760e98a08e6649d2d68afb6035af713121dfb615acce8c4f73810ec438/tiktoken-0.14.0-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:86f66c85e796f5d05d5c4a60ec1d40cbfebc47a32464053528c797163fa9ab89", size = 1251479, upload-time = "2026-08-17T19:49:36.419Z" }, + { url = "https://files.pythonhosted.org/packages/c5/84/50966fb6918a0fb9b32721277e5342bf729a2d74350074d662fbedf9772e/tiktoken-0.14.0-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:149d97453c4c98c04b081d64a85e635921269b532710d6faf81e9e82b790e7d3", size = 1316673, upload-time = "2026-08-17T19:49:37.756Z" }, + { url = "https://files.pythonhosted.org/packages/35/5e/9b01afd037bfa22a0033963fa091e0f75b6fb15cd85bffb42ff86e697323/tiktoken-0.14.0-cp315-cp315t-win_amd64.whl", hash = "sha256:561e7580f84a79859af1ef6f676968e9030fcc3fe195700b15235bca64f009c9", size = 987929, upload-time = "2026-08-17T19:49:38.947Z" }, ] [[package]] @@ -4209,3 +4240,25 @@ postgres = [ { name = "asyncpg" }, { name = "psycopg2-binary" }, ] + +[[package]] +name = "zleap-sag2" +version = "0.1.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "aiohttp" }, + { name = "aiosqlite" }, + { name = "jieba" }, + { name = "pydantic" }, + { name = "pydantic-settings" }, + { name = "pyuca" }, + { name = "regex" }, + { name = "sqlalchemy", extra = ["asyncio"] }, + { name = "tiktoken" }, + { name = "tokenizers" }, + { name = "tzdata" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/66/6b/104d933ec83342d390521fb64dff789a895403001073d930188eafa7145e/zleap_sag2-0.1.0.tar.gz", hash = "sha256:c11bb47fb240c599202dbae514ad11897d7eac165a4a01274c0ce20e8ba8f1bd", size = 3939314, upload-time = "2026-10-22T09:32:46.885Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a1/c1/e311691682a099a88ceee586e5718d917100dc1d7c31ef628ef73db2a7b2/zleap_sag2-0.1.0-py3-none-any.whl", hash = "sha256:dd8b3ab600c6345b1b5e66f295cb9be068af498747785259d09bf1cfde7a4244", size = 3977601, upload-time = "2026-10-22T09:32:44.822Z" }, +] diff --git a/apps/web/app/(app)/settings/page.tsx b/apps/web/app/(app)/settings/page.tsx index a49907fa..6504b9ac 100644 --- a/apps/web/app/(app)/settings/page.tsx +++ b/apps/web/app/(app)/settings/page.tsx @@ -60,7 +60,9 @@ function SettingsPageContent() { ? '[data-settings-section="assistant-appearance"]' : activeTab === "knowledge" && section === "document-processing" ? '[data-settings-section="document-processing"]' - : null; + : activeTab === "knowledge" && section === "jev" + ? '[data-settings-section="jev"]' + : null; if (!selector) return; let secondFrame = 0; const firstFrame = window.requestAnimationFrame(() => { diff --git a/apps/web/components/features/knowledge-config-form.test.tsx b/apps/web/components/features/knowledge-config-form.test.tsx index 95169ab3..03717daf 100644 --- a/apps/web/components/features/knowledge-config-form.test.tsx +++ b/apps/web/components/features/knowledge-config-form.test.tsx @@ -22,6 +22,9 @@ const config = { }; const provider302Endpoint = "https://api.302.ai/typesafeai/v1/systemone"; const officialEndpoint = "https://api.typesafe.ai/v1/systemone"; +/** A key already saved for the prefilled 302.AI endpoint satisfies the key requirement without typing. */ +const keyedConfig = { ...config, jev_endpoint: provider302Endpoint, jev_api_key_set: true }; +const keyMissing = { reason: "jev_api_key_missing", message: "Add a JEV API key" }; let root: Root; let container: HTMLDivElement; let saved: Record | undefined; @@ -66,11 +69,17 @@ function pointerEvent(type: string) { Object.defineProperties(event, { pointerId: { value: 1 }, pointerType: { value: "mouse" } }); return event; } -async function select(id: string, label: string) { +async function openSelect(id: string) { const trigger = container.querySelector(id); expect(trigger, `missing selector ${id}`).not.toBeNull(); await act(async () => trigger!.dispatchEvent(pointerEvent("pointerdown"))); - const option = [...document.body.querySelectorAll('[role="option"]')].find(item => item.textContent?.includes(label))!; + return [...document.body.querySelectorAll('[role="option"]')]; +} +async function closeSelect() { + await act(async () => document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }))); +} +async function select(id: string, label: string) { + const option = (await openSelect(id)).find(item => item.textContent?.includes(label))!; expect(option).toBeDefined(); expect(option.getAttribute("aria-disabled")).not.toBe("true"); await act(async () => { @@ -78,6 +87,12 @@ async function select(id: string, label: string) { option.dispatchEvent(pointerEvent("pointerup")); }); } +async function expectStrategyDisabled(label: string, disabled: boolean) { + const option = (await openSelect("#kb-search-strategy")).find(item => item.textContent?.includes(label))!; + expect(option, `missing option ${label}`).toBeDefined(); + expect(option.getAttribute("aria-disabled") === "true").toBe(disabled); + await closeSelect(); +} describe("JEV knowledge settings", () => { it("prefills 302.AI and the stable latest model without saving or changing the selected strategy", async () => { @@ -95,6 +110,10 @@ describe("JEV knowledge settings", () => { expect(container.textContent).toContain("Documents are not translated"); expect(container.textContent).toContain("does not change JEV's scoring language"); expect(container.textContent).toContain("latest stable JEV release"); + expect(container.textContent).toContain("API key (required for JEV modes)"); + expect(container.textContent).toContain("JEV is a paid service shared by JEV reranking and SAG2 evidence retrieval"); + expect(container.textContent).toContain("The failure policy applies to JEV reranking only"); + expect(container.querySelector('[data-settings-section="jev"]')).not.toBeNull(); }); it.each(["", " "])("prefills the latest alias when the stored model is blank (%j)", async model => { vi.mocked(api.getModelConfig).mockResolvedValue({ ...config, jev_model: model } as never); @@ -125,16 +144,29 @@ describe("JEV knowledge settings", () => { { label: "unconfigured", jev_endpoint: null, search_strategy: "vector" }, { label: "configured but inactive", jev_endpoint: officialEndpoint, search_strategy: "vector" }, { label: "already enabled", jev_endpoint: officialEndpoint, search_strategy: "multi_jev" }, + { label: "already running SAG2", jev_endpoint: officialEndpoint, search_strategy: "sag2" }, ])("saves document settings without changing $label JEV configuration", async stored => { vi.mocked(api.getModelConfig).mockResolvedValue({ ...config, ...stored } as never); await mount(); + expect(container.querySelector('[role="alert"]')).toBeNull(); await edit("#kb-extract-concurrency", "12"); await act(async () => button("Save and apply").click()); expect(saved).toMatchObject({ document_extract_concurrency: 12 }); expect(saved).not.toHaveProperty("search_strategy"); expect(Object.keys(saved!).filter(key => key.startsWith("jev_"))).toEqual([]); }); + it("keeps JEV modes disabled until an API key is entered, then saves the key with the mode", async () => { + await mount(); + await expectStrategyDisabled("JEV reranking", true); + expect(container.querySelector('[role="alert"]')).toBeNull(); + expect(button("Save and apply").disabled).toBe(false); + await edit("#kb-jev-api-key", "synthetic-302-key"); + await select("#kb-search-strategy", "JEV"); + await act(async () => button("Save and apply").click()); + expect(saved).toMatchObject({ jev_endpoint: provider302Endpoint, jev_model: "jev-latest", jev_api_key: "synthetic-302-key", search_strategy: "multi_jev", jev_ranking_timeout_seconds: 30, jev_failure_policy: "error" }); + }); it("saves untouched provider defaults only when the user enables JEV", async () => { + vi.mocked(api.getModelConfig).mockResolvedValue(keyedConfig as never); await mount(); await select("#kb-search-strategy", "JEV"); await act(async () => button("Save and apply").click()); @@ -142,6 +174,7 @@ describe("JEV knowledge settings", () => { expect(saved).not.toHaveProperty("jev_api_key"); }); it("does not persist provider defaults after the user cancels enabling JEV", async () => { + vi.mocked(api.getModelConfig).mockResolvedValue(keyedConfig as never); await mount(); await select("#kb-search-strategy", "JEV"); await select("#kb-search-strategy", "Fast (vector)"); @@ -150,9 +183,11 @@ describe("JEV knowledge settings", () => { expect(Object.keys(saved!).filter(key => key.startsWith("jev_"))).toEqual([]); }); it("does not persist a tested but unedited default JEV draft", async () => { + vi.mocked(api.getModelConfig).mockResolvedValue(keyedConfig as never); await mount(); await act(async () => button("Test JEV connection").click()); expect(tested).toMatchObject({ jev_endpoint: provider302Endpoint, jev_model: "jev-latest" }); + expect(tested).not.toHaveProperty("jev_api_key"); await edit("#kb-extract-concurrency", "12"); await act(async () => button("Save and apply").click()); expect(Object.keys(saved!).filter(key => key.startsWith("jev_"))).toEqual([]); @@ -175,9 +210,11 @@ describe("JEV knowledge settings", () => { expect(container.querySelector("#kb-jev-model")!.value).toBe("jev-latest"); expect(container.querySelector("#kb-jev-api-key")!.value).toBe(""); expect(container.textContent).not.toContain("Draft connected"); + // The new destination needs its own key before it can be tested. + expect(button("Test JEV connection").disabled).toBe(true); + await edit("#kb-jev-api-key", "synthetic-official-key"); await act(async () => button("Test JEV connection").click()); - expect(tested).toMatchObject({ jev_endpoint: officialEndpoint, jev_model: "jev-latest" }); - expect(tested).not.toHaveProperty("jev_api_key"); + expect(tested).toMatchObject({ jev_endpoint: officialEndpoint, jev_model: "jev-latest", jev_api_key: "synthetic-official-key" }); expect(tested).not.toHaveProperty("llm_api_key"); await select("#kb-jev-provider", "302.AI"); await act(async () => button("Save and apply").click()); @@ -186,14 +223,18 @@ describe("JEV knowledge settings", () => { expect(saved).not.toHaveProperty("jev_api_key"); expect(saved).not.toHaveProperty("jev_provider"); }); - it("allows a custom full URL and custom model while keeping a blank independent key", async () => { + it("requires a key before testing a custom full URL and custom model", async () => { await mount(); await select("#kb-jev-provider", "Custom"); await edit("#kb-jev-endpoint", "https://gateway.invalid/custom/score"); await edit("#kb-jev-model", "gateway-jev"); + expect(container.querySelector("#kb-jev-api-key")!.placeholder).toBe("Enter the API key for your JEV service"); + expect(button("Test JEV connection").disabled).toBe(true); + expect(container.querySelector('[role="alert"]')).toBeNull(); + await edit("#kb-jev-api-key", "synthetic-gateway-key"); + expect(button("Test JEV connection").disabled).toBe(false); await act(async () => button("Test JEV connection").click()); - expect(tested).toMatchObject({ jev_endpoint: "https://gateway.invalid/custom/score", jev_model: "gateway-jev" }); - expect(tested).not.toHaveProperty("jev_api_key"); + expect(tested).toMatchObject({ jev_endpoint: "https://gateway.invalid/custom/score", jev_model: "gateway-jev", jev_api_key: "synthetic-gateway-key" }); }); it("clears a draft key and test result when a custom destination changes", async () => { await mount(); @@ -206,15 +247,16 @@ describe("JEV knowledge settings", () => { expect(container.querySelector("#kb-jev-api-key")!.value).toBe(""); expect(container.textContent).not.toContain("Draft connected"); }); - it("saves a service draft and JEV mode together while leaving a blank key untouched", async () => { + it("saves a service draft, its key and JEV mode together", async () => { await mount(); await select("#kb-jev-provider", "Custom"); await edit("#kb-jev-endpoint", "https://jev.invalid/score"); await edit("#kb-jev-model", "gateway-model"); + await expectStrategyDisabled("JEV reranking", true); + await edit("#kb-jev-api-key", "synthetic-gateway-key"); await select("#kb-search-strategy", "JEV"); await act(async () => button("Save and apply").click()); - expect(saved).toMatchObject({ jev_endpoint: "https://jev.invalid/score", jev_model: "gateway-model", search_strategy: "multi_jev", jev_ranking_timeout_seconds: 30, jev_failure_policy: "error" }); - expect(saved).not.toHaveProperty("jev_api_key"); + expect(saved).toMatchObject({ jev_endpoint: "https://jev.invalid/score", jev_model: "gateway-model", jev_api_key: "synthetic-gateway-key", search_strategy: "multi_jev", jev_ranking_timeout_seconds: 30, jev_failure_policy: "error" }); expect(state.refreshCapabilities).toHaveBeenCalled(); }); it.each([ @@ -241,8 +283,10 @@ describe("JEV knowledge settings", () => { }); it("starts clean after saving JEV and switching away from it", async () => { await mount(); + await edit("#kb-jev-api-key", "synthetic-302-key"); await select("#kb-search-strategy", "JEV"); await act(async () => button("Save and apply").click()); + expect(saved).toMatchObject({ search_strategy: "multi_jev", jev_api_key: "synthetic-302-key" }); await act(async () => button("Save and apply").click()); expect(saved).not.toHaveProperty("search_strategy"); expect(Object.keys(saved!).filter(key => key.startsWith("jev_"))).toEqual([]); @@ -272,6 +316,23 @@ describe("JEV knowledge settings", () => { expect(saved).toBeUndefined(); expect(tested).toBeUndefined(); }); + it("blocks saving a JEV mode whose key was cleared by changing the destination", async () => { + state.capabilities = { vector_provider: "lancedb", search_strategies: ["vector", "multi", "multi_es_fast", "multi_jev", "sag2"] }; + vi.mocked(api.getModelConfig).mockResolvedValue({ ...config, jev_endpoint: officialEndpoint, search_strategy: "sag2" } as never); + await mount(); + expect(container.querySelector('[role="alert"]')).toBeNull(); + await select("#kb-jev-provider", "302.AI"); + expect(container.querySelector('[role="alert"]')?.textContent).toContain("Enter the JEV API key before selecting JEV reranking or SAG2 evidence retrieval"); + expect(container.querySelector("#kb-jev-api-key")?.getAttribute("aria-invalid")).toBe("true"); + expect(button("Save and apply").disabled).toBe(true); + expect(button("Test JEV connection").disabled).toBe(true); + await edit("#kb-jev-api-key", "synthetic-302-key"); + expect(container.querySelector('[role="alert"]')).toBeNull(); + expect(button("Save and apply").disabled).toBe(false); + await act(async () => button("Save and apply").click()); + expect(saved).toMatchObject({ jev_endpoint: provider302Endpoint, jev_api_key: "synthetic-302-key" }); + expect(saved).not.toHaveProperty("search_strategy"); + }); it.each([ ["pgvector", "PostgreSQL (pgvector)"], ["oceanbase", "OceanBase"], @@ -319,8 +380,76 @@ describe("JEV knowledge settings", () => { expect(saved).toMatchObject({ search_strategy: "vector" }); expect(Object.keys(saved!).filter(key => key.startsWith("jev_"))).toEqual([]); }); + it("hides the JEV service form when storage rules out both JEV modes", async () => { + state.capabilities = { + vector_provider: "oceanbase", search_strategies: ["vector", "multi"], + search_strategies_disabled: { + multi_jev: { reason: "vector_provider_lacks_lexical", message: "Lexical search required" }, + sag2: { reason: "sag2_relational_unsupported", message: "SQLite or PostgreSQL required" }, + }, + }; + vi.mocked(api.getModelConfig).mockResolvedValue({ ...config, search_strategy: "sag2", jev_endpoint: officialEndpoint } as never); + await mount(); + expect(container.querySelector("#kb-jev-provider")).toBeNull(); + expect(container.textContent).toContain("SAG2 evidence retrieval currently supports only SQLite and PostgreSQL"); + expect(container.textContent).toContain("Choose Fast (vector) or Precise above and save"); + expect(container.querySelector('[role="alert"]')).toBeNull(); + expect(button("Save and apply").disabled).toBe(false); + }); + it("keeps the JEV service form for SAG2 on PostgreSQL when only JEV reranking lacks lexical search", async () => { + state.capabilities = { + vector_provider: "pgvector", search_strategies: ["vector", "multi", "sag2"], + search_strategies_disabled: { + multi_jev: { reason: "vector_provider_lacks_lexical", message: "Lexical search required" }, + multi_es_fast: { reason: "vector_provider_lacks_lexical", message: "Lexical search required" }, + }, + }; + vi.mocked(api.getModelConfig).mockResolvedValue(keyedConfig as never); + await mount(); + expect(container.querySelector("#kb-jev-provider")).not.toBeNull(); + expect(container.textContent).toContain("requires lexical search"); + expect(container.textContent).not.toContain("Your existing retrieval settings remain unchanged"); + expect(button("Test JEV connection").disabled).toBe(false); + await expectStrategyDisabled("JEV reranking", true); + await select("#kb-search-strategy", "SAG2"); + await act(async () => button("Save and apply").click()); + expect(saved).toMatchObject({ search_strategy: "sag2", jev_endpoint: provider302Endpoint, jev_model: "jev-latest" }); + expect(saved).not.toHaveProperty("jev_api_key"); + }); + it("explains the SAG2 relational limitation while keeping JEV reranking configurable", async () => { + state.capabilities = { + vector_provider: "lancedb", search_strategies: ["vector", "multi", "multi_es_fast", "multi_jev"], + search_strategies_disabled: { sag2: { reason: "sag2_relational_unsupported", message: "SQLite or PostgreSQL required" } }, + }; + vi.mocked(api.getModelConfig).mockResolvedValue(keyedConfig as never); + await mount(); + expect(container.querySelector("#kb-jev-provider")).not.toBeNull(); + expect(container.textContent).toContain("SAG2 evidence retrieval currently supports only SQLite and PostgreSQL"); + expect(container.querySelector('[role="alert"]')).toBeNull(); + await expectStrategyDisabled("SAG2", true); + await select("#kb-search-strategy", "JEV"); + await act(async () => button("Save and apply").click()); + expect(saved).toMatchObject({ search_strategy: "multi_jev" }); + }); + it("lifts a missing-key reason for both JEV modes only once a key is typed", async () => { + state.capabilities = { + vector_provider: "lancedb", search_strategies: ["vector", "multi", "multi_es_fast"], + search_strategies_disabled: { multi_jev: keyMissing, sag2: keyMissing }, + }; + vi.mocked(api.getModelConfig).mockResolvedValue({ ...config, jev_endpoint: provider302Endpoint, jev_api_key_set: false } as never); + await mount(); + await expectStrategyDisabled("JEV reranking", true); + await expectStrategyDisabled("SAG2", true); + expect(container.querySelector('[role="alert"]')).toBeNull(); + await edit("#kb-jev-api-key", "synthetic-302-key"); + await expectStrategyDisabled("JEV reranking", false); + await select("#kb-search-strategy", "SAG2"); + await act(async () => button("Save and apply").click()); + expect(saved).toMatchObject({ search_strategy: "sag2", jev_endpoint: provider302Endpoint, jev_api_key: "synthetic-302-key" }); + }); it("disables the JEV option and rejects a draft enable when storage capabilities change", async () => { await mount(); + await edit("#kb-jev-api-key", "synthetic-302-key"); await select("#kb-search-strategy", "JEV"); state.capabilities = { vector_provider: "pgvector", search_strategies: ["vector", "multi"], @@ -328,9 +457,7 @@ describe("JEV knowledge settings", () => { }; await mount(); expect(button("Save and apply").disabled).toBe(true); - const trigger = container.querySelector("#kb-search-strategy")!; - await act(async () => trigger.dispatchEvent(pointerEvent("pointerdown"))); - const jevOption = [...document.body.querySelectorAll('[role="option"]')].find(item => item.textContent?.includes("JEV"))!; + const jevOption = (await openSelect("#kb-search-strategy")).find(item => item.textContent?.includes("JEV"))!; expect(jevOption.getAttribute("aria-disabled")).toBe("true"); expect(saved).toBeUndefined(); }); @@ -341,16 +468,18 @@ describe("JEV knowledge settings", () => { expect(container.textContent).toContain(displayName); expect(container.textContent).not.toContain("Currently using vector retrieval"); expect(container.querySelector("#kb-jev-provider")).not.toBeNull(); + expect(button("Test JEV connection").disabled).toBe(true); + await edit("#kb-jev-api-key", "synthetic-302-key"); expect(button("Test JEV connection").disabled).toBe(false); await select("#kb-search-strategy", "JEV"); await act(async () => button("Save and apply").click()); - expect(saved).toMatchObject({ search_strategy: "multi_jev", jev_endpoint: provider302Endpoint }); + expect(saved).toMatchObject({ search_strategy: "multi_jev", jev_endpoint: provider302Endpoint, jev_api_key: "synthetic-302-key" }); }); it("keeps ordinary settings editable against an older API without JEV capability", async () => { state.capabilities = { search_strategies: ["vector", "multi"] }; vi.mocked(api.getModelConfig).mockResolvedValue({ ...config, jev_endpoint: "invalid" } as never); await mount(); - expect(container.textContent).toContain("This server does not advertise JEV support"); + expect(container.textContent).toContain("This server does not advertise support for this JEV-scored mode"); expect(button("Test JEV connection").disabled).toBe(true); expect(button("Save and apply").disabled).toBe(false); await act(async () => button("Save and apply").click()); diff --git a/apps/web/components/features/knowledge-config-form.tsx b/apps/web/components/features/knowledge-config-form.tsx index 83ff0fd4..6d06adc9 100644 --- a/apps/web/components/features/knowledge-config-form.tsx +++ b/apps/web/components/features/knowledge-config-form.tsx @@ -22,7 +22,14 @@ import { Skeleton } from "@/components/ui/skeleton"; import { Slider } from "@/components/ui/slider"; import { Spinner } from "@/components/ui/spinner"; import { api, ApiError } from "@/lib/api"; -import { getSearchStrategiesDisabled, SEARCH_STRATEGIES } from "@/lib/retrieval-config"; +import { + getSearchStrategiesDisabled, + isJevConfigDisabledReason, + isJevScoredStrategy, + JEV_SCORED_STRATEGIES, + SEARCH_STRATEGIES, + type JevScoredStrategy, +} from "@/lib/retrieval-config"; import type { ModelConfig, ModelConfigPatch } from "@/lib/types"; import { Tooltip, @@ -82,10 +89,26 @@ export function KnowledgeConfigForm() { const url = new URL(jevEndpoint.trim()); validEndpoint = ["http:", "https:"].includes(url.protocol) && !url.username && !url.password; } catch { /* An empty or incomplete draft cannot enable JEV. */ } - const jevDraftReady = validEndpoint && Boolean(jevModel.trim()); + // A saved key only applies to the endpoint it was saved for. + const savedKeyApplies = jevKeySet && jevEndpoint.trim() === savedJevEndpoint; + // JEV is a paid service: a key saved for this exact endpoint or typed into the draft is required. + const jevKeyReady = savedKeyApplies || Boolean(jevKey.trim()); + const jevServiceDraftValid = validEndpoint && Boolean(jevModel.trim()); + const jevDraftReady = jevServiceDraftValid && jevKeyReady; const disabledStrategies = getSearchStrategiesDisabled(capabilities, strategies("unsupportedBackend"), jevDraftReady); const jevStorageUnsupported = disabledStrategies.multi_jev?.reason === "vector_provider_lacks_lexical"; - const jevUnsupported = jevStorageUnsupported || disabledStrategies.multi_jev?.reason === "unsupported_backend"; + const sag2StorageUnsupported = disabledStrategies.sag2?.reason === "sag2_relational_unsupported"; + // A JEV mode is serviceable when only its (shared) service configuration stands in the way. + const jevServiceable = (mode: JevScoredStrategy) => { + const reason = disabledStrategies[mode]?.reason; + return reason === undefined || isJevConfigDisabledReason(reason); + }; + const jevUnsupported = !JEV_SCORED_STRATEGIES.some(jevServiceable); + // Only hide the service form when storage rules out every JEV mode; PostgreSQL + // still runs SAG2 even though JEV reranking lacks lexical search there. + const jevFormHidden = jevStorageUnsupported && !jevServiceable("sag2"); + const savedJevModeBlocked = savedJevDraft !== null && isJevScoredStrategy(savedJevDraft.strategy) + && Boolean(disabledStrategies[savedJevDraft.strategy]) && !jevServiceable(savedJevDraft.strategy); const strategyChanged = savedJevDraft !== null && strategy !== savedJevDraft.strategy; const legacyVectorFallback = !strategyChanged && strategy === "multi_es_fast" && disabledStrategies.multi_es_fast?.reason === "vector_provider_lacks_lexical"; @@ -93,12 +116,13 @@ export function KnowledgeConfigForm() { const storageName = vectorProvider ? ({ lancedb: "LanceDB", es: "Elasticsearch", pgvector: "PostgreSQL (pgvector)", oceanbase: "OceanBase", }[vectorProvider] ?? vectorProvider) : null; - const invalidJevDraft = !jevUnsupported && ( - (Boolean(jevEndpoint.trim()) && !jevDraftReady) + const jevTimeoutValid = Number.isFinite(jevTimeout) && jevTimeout >= 0.1 && jevTimeout <= 120; + const jevDraftFieldsInvalid = (Boolean(jevEndpoint.trim()) && !jevServiceDraftValid) || !jevModel.trim() - || !Number.isFinite(jevTimeout) || jevTimeout < 0.1 || jevTimeout > 120 - || (strategy === "multi_jev" && !jevDraftReady) - ); + || !jevTimeoutValid; + const jevModeSelected = isJevScoredStrategy(strategy); + const jevKeyMissing = jevModeSelected && !jevKeyReady; + const invalidJevDraft = !jevUnsupported && (jevDraftFieldsInvalid || (jevModeSelected && !jevDraftReady)); const hydrate = React.useCallback((config: ModelConfig) => { const endpoint = config.jev_endpoint?.trim() || JEV_ENDPOINTS["302"]; @@ -179,7 +203,8 @@ export function KnowledgeConfigForm() { || jevTimeout !== savedJevDraft.timeout || jevFailurePolicy !== savedJevDraft.failurePolicy || Boolean(jevKey.trim()) - || (strategy === "multi_jev" && savedJevDraft.strategy !== "multi_jev") + // Enabling either JEV-scored mode persists the (possibly untouched) service draft with it. + || (isJevScoredStrategy(strategy) && strategy !== savedJevDraft.strategy) ); const patch: ModelConfigPatch = { document_chunk_max_tokens: chunkMaxTokens, @@ -371,6 +396,11 @@ export function KnowledgeConfigForm() { {strategies(labelKey)} + {isJevScoredStrategy(value) && ( + + {strategies("paid")} + + )} {info && ( {strategies("disabledSuffix")} @@ -409,15 +439,27 @@ export function KnowledgeConfigForm() { - + - {jevStorageUnsupported ? ( + : <> + {t("jevDescription")} + {t("jevSharedNotice")} + }> + {jevFormHidden ? (
-

{t(savedJevDraft?.strategy === "multi_jev" ? "jevStorageSelectCompatible" : "jevStorageUnchanged")}

+

{t(savedJevModeBlocked ? "jevStorageSelectCompatible" : "jevStorageUnchanged")}

+ {sag2StorageUnsupported &&

{t("sag2StorageUnavailable")}

}

{t("jevStorageNoChanges")}

) : <> + {(jevStorageUnsupported || sag2StorageUnsupported || savedJevModeBlocked) && ( +
+ {jevStorageUnsupported &&

{t("jevStorageUnavailable", { provider: storageName ?? vectorProvider ?? "" })}

} + {sag2StorageUnsupported &&

{t("sag2StorageUnavailable")}

} + {savedJevModeBlocked &&

{t("jevStorageSelectCompatible")}

} +
+ )}
{t("jevProvider")} @@ -447,8 +489,9 @@ export function KnowledgeConfigForm() { {t("jevKey")} { setJevKey(event.target.value); setJevTestResult(null); }} /> {jevProvider !== "custom" && {t("jevKeyProviderDescription", { provider: jevProvider === "302" ? "302.AI" : "TypeSafe" })}} @@ -474,10 +517,10 @@ export function KnowledgeConfigForm() {
{jevUnsupported &&

{strategies("unsupportedBackend")}

} - {invalidJevDraft &&

{t("jevInvalidDraft")}

} + {invalidJevDraft &&

{t(jevDraftFieldsInvalid ? "jevInvalidDraft" : "jevKeyRequired")}

}
@@ -486,6 +529,7 @@ export function KnowledgeConfigForm() {
}
+
diff --git a/apps/web/components/features/retrieval-status.test.tsx b/apps/web/components/features/retrieval-status.test.tsx index 4e26019e..1b4a1231 100644 --- a/apps/web/components/features/retrieval-status.test.tsx +++ b/apps/web/components/features/retrieval-status.test.tsx @@ -5,13 +5,14 @@ import { createRoot } from "react-dom/client"; import { NextIntlClientProvider } from "next-intl"; import { describe, expect, it } from "vitest"; import messages from "@/messages/en-US.json"; +import type { SearchStrategy } from "@/lib/retrieval-config"; import { RetrievalStatus } from "./retrieval-status"; -async function render(stats: Record) { +async function render(stats: Record, requestedStrategy: SearchStrategy = "multi_jev") { (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; const container = document.createElement("div"); const root = createRoot(container); - await act(async () => root.render()); + await act(async () => root.render()); const text = container.textContent; await act(async () => root.unmount()); return text; @@ -37,3 +38,34 @@ describe("retrieval execution status", () => { expect(text).toContain("Partial results"); }); }); + +describe("SAG2 execution status", () => { + const success = { + requested_strategy: "sag2", effective_strategy: "sag2", fallback_used: false, + ranking: { method: "jev", fallback_reason: null }, + sag2: { local_ms: 12, jev_ms: 480, snapshot_revision: 3, scope_chunks: 40, hops: [] }, + }; + it("renders JEV usage for a successful run without an execution warning", async () => { + const text = await render({ ...success, jev_usage: { requests: 3, judgments: 1200, input_tokens: 45678, output_tokens: 90 } }, "sag2"); + expect(text).toBe("JEV scoring this run: 3 requests · 1,200 judgments · 45,678 input tokens"); + }); + it("omits token counts the service did not report", async () => { + const text = await render({ ...success, jev_usage: { requests: 1, judgments: 8, input_tokens: null, output_tokens: null } }, "sag2"); + expect(text).toBe("JEV scoring this run: 1 requests · 8 judgments"); + }); + it("stays silent without usage data", async () => { + expect(await render(success, "sag2")).toBe(""); + }); + it("treats a SAG2 coarse fallback like any JEV fallback", async () => { + const text = await render({ ...success, fallback_used: true, ranking: { method: "jev", fallback_reason: "timeout" } }, "sag2"); + expect(text).toContain("Requested: SAG2 evidence retrieval"); + expect(text).toContain("Actual: Coarse ranking"); + expect(text).toContain("JEV reranking did not complete"); + }); + it("shows the actual mode when SAG2 was executed as another strategy", async () => { + const text = await render({ requested_strategy: "sag2", effective_strategy: "vector", jev_usage: { requests: 0, judgments: 0, input_tokens: null, output_tokens: null } }, "sag2"); + expect(text).toContain("Requested: SAG2 evidence retrieval"); + expect(text).toContain("Actual: Fast (vector)"); + expect(text).toContain("0 requests · 0 judgments"); + }); +}); diff --git a/apps/web/components/features/retrieval-status.tsx b/apps/web/components/features/retrieval-status.tsx index 50cffc7b..12585ca2 100644 --- a/apps/web/components/features/retrieval-status.tsx +++ b/apps/web/components/features/retrieval-status.tsx @@ -1,7 +1,12 @@ "use client"; -import { useTranslations } from "next-intl"; -import { getSearchStrategy, isSearchStrategy, type SearchStrategy } from "@/lib/retrieval-config"; +import { useLocale, useTranslations } from "next-intl"; +import { + getSearchStrategy, + isJevScoredStrategy, + isSearchStrategy, + type SearchStrategy, +} from "@/lib/retrieval-config"; function record(value: unknown): Record { return value !== null && typeof value === "object" && !Array.isArray(value) @@ -12,6 +17,10 @@ function usedFallback(stats: Record): boolean { return stats.fallback_used === true || Boolean(record(stats.ranking).fallback_reason); } +function finiteNumber(value: unknown): number | null { + return typeof value === "number" && Number.isFinite(value) ? value : null; +} + /** Explain execution changes without treating same-profile coarse ranking as JEV success. */ export function RetrievalStatus({ stats, requestedStrategy }: { stats: Record; @@ -19,19 +28,36 @@ export function RetrievalStatus({ stats, requestedStrategy }: { }) { const t = useTranslations("RetrievalStatus"); const strategies = useTranslations("SearchStrategies"); + const locale = useLocale(); const requested = isSearchStrategy(stats.requested_strategy) ? stats.requested_strategy : requestedStrategy; const effective = typeof stats.effective_strategy === "string" ? stats.effective_strategy : requested; const fallback = usedFallback(stats) || Object.values(record(stats.source_stats)).some(value => usedFallback(record(value))); - const jevFallback = (requested === "multi_jev" || effective === "multi_jev") && fallback; + const jevFallback = (isJevScoredStrategy(requested) || isJevScoredStrategy(effective)) && fallback; const partial = stats.partial === true; const changed = requested && effective && requested !== effective; - if (!jevFallback && !partial && !changed) return null; + // Paid JEV calls are reported per run so users can see what a query cost. + const usage = record(stats.jev_usage); + const usageRequests = finiteNumber(usage.requests); + const usageJudgments = finiteNumber(usage.judgments); + const usageInputTokens = finiteNumber(usage.input_tokens); + const format = (value: number) => value.toLocaleString(locale); + // Only report usage the backend actually measured; never fabricate a zero. + const usageText = usageRequests !== null && usageJudgments !== null + ? t("jevUsage", { + requests: format(usageRequests), + judgments: format(usageJudgments), + tokens: usageInputTokens === null ? "" : t("jevUsageTokens", { tokens: format(usageInputTokens) }), + }) + : null; + const executionChanged = jevFallback || partial || changed; + if (!executionChanged && usageText === null) return null; function label(mode: string) { return isSearchStrategy(mode) ? strategies(getSearchStrategy(mode).labelKey) : mode; } return
- {requested &&

{t("requested", { mode: label(requested) })}{" · "}{t("actual", { mode: jevFallback ? t("coarse") : label(effective ?? requested) })}

} + {executionChanged && requested &&

{t("requested", { mode: label(requested) })}{" · "}{t("actual", { mode: jevFallback ? t("coarse") : label(effective ?? requested) })}

} {jevFallback &&

{t("jevFallback")}

} {partial &&

{t("partial")}

} + {usageText !== null &&

{usageText}

}
; } diff --git a/apps/web/components/features/search-strategy-control.test.tsx b/apps/web/components/features/search-strategy-control.test.tsx new file mode 100644 index 00000000..0f903311 --- /dev/null +++ b/apps/web/components/features/search-strategy-control.test.tsx @@ -0,0 +1,86 @@ +/** @vitest-environment jsdom */ +import * as React from "react"; +import { act } from "react"; +import { createRoot, type Root } from "react-dom/client"; +import { NextIntlClientProvider } from "next-intl"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import messages from "@/messages/en-US.json"; +import type { SearchStrategy, SearchStrategyDisabledMap } from "@/lib/retrieval-config"; +import { SearchStrategyControl } from "./search-strategy-control"; + +vi.mock("next/link", () => ({ + default: React.forwardRef>( + function Link({ children, href, ...props }, ref) { return {children}; }, + ), +})); + +let root: Root; +let container: HTMLDivElement; +const onValueChange = vi.fn<(value: SearchStrategy) => void>(); + +beforeEach(() => { + (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + onValueChange.mockClear(); + Object.defineProperties(HTMLElement.prototype, { + hasPointerCapture: { configurable: true, value: () => false }, releasePointerCapture: { configurable: true, value: () => undefined }, + setPointerCapture: { configurable: true, value: () => undefined }, scrollIntoView: { configurable: true, value: () => undefined }, + }); + vi.stubGlobal("ResizeObserver", class { observe() {} unobserve() {} disconnect() {} }); + container = document.createElement("div"); document.body.append(container); root = createRoot(container); +}); +afterEach(async () => { await act(async () => root.unmount()); container.remove(); vi.unstubAllGlobals(); }); + +function pointerEvent(type: string) { + const event = new MouseEvent(type, { bubbles: true, button: 0 }); + Object.defineProperties(event, { pointerId: { value: 1 }, pointerType: { value: "mouse" } }); + return event; +} +async function open(disabledMap?: SearchStrategyDisabledMap, value: SearchStrategy = "vector") { + await act(async () => root.render( + + + , + )); + const trigger = container.querySelector('[data-testid="search-strategy"]')!; + await act(async () => trigger.dispatchEvent(pointerEvent("pointerdown"))); + return [...document.body.querySelectorAll('[role="menuitem"]')]; +} +function item(items: HTMLElement[], label: string) { + return items.find(candidate => candidate.textContent?.includes(label))!; +} + +describe("search strategy dropdown", () => { + it("lists SAG2 after JEV reranking and marks both as paid", async () => { + const items = await open(); + const labels = items.map(candidate => candidate.textContent ?? ""); + expect(labels.findIndex(text => text.includes("JEV reranking"))).toBeLessThan(labels.findIndex(text => text.includes("SAG2 evidence retrieval"))); + expect(document.body.querySelector('[data-testid="search-strategy-sag2-paid"]')?.textContent).toBe("Paid"); + expect(document.body.querySelector('[data-testid="search-strategy-multi_jev-paid"]')?.textContent).toBe("Paid"); + expect(item(items, "Fast (vector)").textContent).not.toContain("Paid"); + expect(item(items, "SAG2 evidence retrieval").textContent).toContain("BM25 recall scored over several JEV rounds"); + expect(document.body.querySelector('[data-testid$="-settings"]')).toBeNull(); + }); + it("selects SAG2 when it is enabled", async () => { + const items = await open(); + const sag2 = item(items, "SAG2 evidence retrieval"); + expect(sag2.getAttribute("aria-disabled")).not.toBe("true"); + await act(async () => { sag2.dispatchEvent(pointerEvent("pointermove")); sag2.dispatchEvent(pointerEvent("pointerup")); sag2.click(); }); + expect(onValueChange).toHaveBeenCalledWith("sag2"); + }); + it.each(["jev_not_configured", "jev_api_key_missing"])("offers the settings page when a JEV mode is disabled for %s", async reason => { + const items = await open({ sag2: { reason, message: "Add a JEV API key" }, multi_jev: { reason, message: "Add a JEV API key" } }); + const sag2 = item(items, "SAG2 evidence retrieval"); + expect(sag2.getAttribute("aria-disabled")).toBe("true"); + expect(sag2.textContent).toContain("Add a JEV API key"); + const link = document.body.querySelector('[data-testid="search-strategy-sag2-settings"]')!; + expect(link.getAttribute("href")).toBe("/settings?tab=knowledge§ion=jev"); + expect(link.textContent).toContain("Open settings"); + expect(document.body.querySelector('[data-testid="search-strategy-multi_jev-settings"]')).not.toBeNull(); + expect(onValueChange).not.toHaveBeenCalled(); + }); + it.each(["unsupported_backend", "sag2_relational_unsupported", "vector_provider_lacks_lexical"])("does not link to settings for %s", async reason => { + const items = await open({ sag2: { reason, message: "Not available here" }, multi_jev: { reason, message: "Not available here" } }); + expect(item(items, "SAG2 evidence retrieval").getAttribute("aria-disabled")).toBe("true"); + expect(document.body.querySelector('[data-testid$="-settings"]')).toBeNull(); + }); +}); diff --git a/apps/web/components/features/search-strategy-control.tsx b/apps/web/components/features/search-strategy-control.tsx index ce99c9c9..60b4a445 100644 --- a/apps/web/components/features/search-strategy-control.tsx +++ b/apps/web/components/features/search-strategy-control.tsx @@ -1,8 +1,17 @@ "use client"; -import { Check, ChevronDown, ShieldQuestion, Sparkles, Zap } from "lucide-react"; +import { + Check, + ChevronDown, + ScanSearch, + Settings2, + ShieldQuestion, + Sparkles, + Zap, +} from "lucide-react"; import { useTranslations } from "next-intl"; -import type { ComponentType } from "react"; +import Link from "next/link"; +import { Fragment, type ComponentType } from "react"; import { DropdownMenu, @@ -20,18 +29,28 @@ import { import { cn } from "@/lib/utils"; import { getSearchStrategy, + isJevConfigDisabledReason, + isJevScoredStrategy, SEARCH_STRATEGIES, type SearchStrategy, type SearchStrategyDisabledMap, } from "@/lib/retrieval-config"; +import { settingsTabHref } from "@/lib/settings-config"; const STRATEGY_ICONS: Record> = { vector: Zap, multi_es_fast: ShieldQuestion, multi: Sparkles, multi_jev: Sparkles, + sag2: ScanSearch, }; +/** The shared JEV service section inside the knowledge settings tab. */ +const JEV_SETTINGS_HREF = settingsTabHref("knowledge", "jev"); + +const badgeClassName = + "rounded bg-muted px-1 py-0.5 text-[10px] font-normal leading-none text-muted-foreground"; + export function SearchStrategyControl({ value, defaultValue, @@ -74,10 +93,13 @@ export function SearchStrategyControl({ const Icon = STRATEGY_ICONS[strategy.value]; const selected = strategy.value === value; const isDefault = strategy.value === defaultValue; + const paid = isJevScoredStrategy(strategy.value); const disabledInfo = disabledMap?.[strategy.value]; + // A disabled Radix item ignores pointer events, so the settings + // shortcut lives in its own selectable row right below the item. + const needsJevSettings = paid && isJevConfigDisabledReason(disabledInfo?.reason); const item = ( { if (disabledInfo) { @@ -95,18 +117,15 @@ export function SearchStrategyControl({ > - + {t(strategy.labelKey)} - {isDefault && ( - - {t("default")} - - )} - {disabledInfo && ( - - {t("disabledSuffix")} + {isDefault && {t("default")}} + {paid && ( + + {t("paid")} )} + {disabledInfo && {t("disabledSuffix")}} {disabledInfo?.message ?? t(strategy.descriptionKey)} @@ -120,14 +139,28 @@ export function SearchStrategyControl({ /> ); - if (!disabledInfo) return item; return ( - - {item} - - {disabledInfo.message} - - + + {disabledInfo ? ( + + {item} + + {disabledInfo.message} + + + ) : item} + {needsJevSettings && ( + + + + {t("openSettings")} + + + )} + ); })} diff --git a/apps/web/lib/api-jev-timeouts.test.ts b/apps/web/lib/api-jev-timeouts.test.ts index c7a2a9bc..fea1898f 100644 --- a/apps/web/lib/api-jev-timeouts.test.ts +++ b/apps/web/lib/api-jev-timeouts.test.ts @@ -71,9 +71,9 @@ describe("JEV request deadlines", () => { expect(await result).toEqual({ value: { ok: true, message: "Connected" }, error: undefined }); }); - it("allows a 35-second synchronous JEV search", async () => { + it.each(["multi_jev", "sag2"] as const)("allows a 35-second synchronous %s search", async strategy => { slowFetch(35_000, searchResult); - const result = outcome(api.globalSearch({ query: "slow query", strategy: "multi_jev" })); + const result = outcome(api.globalSearch({ query: "slow query", strategy })); await vi.advanceTimersByTimeAsync(35_000); expect(await result).toEqual({ value: searchResult, error: undefined }); }); @@ -112,10 +112,10 @@ describe("JEV request deadlines", () => { expect((await result).error).toMatchObject({ code: "timeout" }); }); - it("lets a comparison containing JEV finish after 35 seconds", async () => { + it.each(["multi_jev", "sag2"] as const)("lets a comparison containing %s finish after 35 seconds", async strategy => { const comparison = { query: "slow query", results: [], judges: [], judge_enabled: false, judge_reason: null }; slowFetch(35_000, comparison); - const result = outcome(api.evalCompare({ query: "slow query", strategies: ["vector", "multi_jev"] })); + const result = outcome(api.evalCompare({ query: "slow query", strategies: ["vector", strategy] })); await vi.advanceTimersByTimeAsync(35_000); expect(await result).toEqual({ value: comparison, error: undefined }); }); @@ -157,7 +157,7 @@ function delayedSearchStream(firstResultMs: number, { complete = true, pings = f const handlers = () => ({ onResult: vi.fn(), onSummaryDelta: vi.fn(), onCompleted: vi.fn() }); describe("JEV search stream deadlines", () => { - it.each(["multi_jev", undefined] as const)("waits 35 seconds for a first result with mode %s", async strategy => { + it.each(["multi_jev", "sag2", undefined] as const)("waits 35 seconds for a first result with mode %s", async strategy => { delayedSearchStream(35_000, { pings: true }); const result = outcome(api.streamGlobalSearch({ query: "slow query", strategy }, handlers())); await vi.advanceTimersByTimeAsync(35_000); diff --git a/apps/web/lib/api.ts b/apps/web/lib/api.ts index c6974d13..e556093d 100644 --- a/apps/web/lib/api.ts +++ b/apps/web/lib/api.ts @@ -4,7 +4,7 @@ import { getDiagnosticsStore } from "./diagnostics"; import { generateUuidV4 } from "./uuid"; import { readClientLocale } from "../i18n/client"; import { clientErrorMessage, serverErrorMessage } from "../i18n/client-errors"; -import type { SearchStrategy } from "./retrieval-config"; +import { isJevScoredStrategy, type SearchStrategy } from "./retrieval-config"; import type { ActivityItem, ClientAccessInfo, @@ -153,7 +153,7 @@ const SEARCH_STREAM_IDLE_TIMEOUT_MS = 45_000; function usesServerSearchDeadline(strategy?: SearchStrategy): boolean { // An omitted strategy may inherit JEV from the global configuration. - return strategy === undefined || strategy === "multi_jev"; + return strategy === undefined || isJevScoredStrategy(strategy); } function isSearchResponse(value: unknown): value is SearchResponse { @@ -1020,7 +1020,7 @@ export const api = { method: "POST", body: JSON.stringify(b), signal, - timeoutMs: b.strategies.includes("multi_jev") ? null : undefined, + timeoutMs: b.strategies.some(isJevScoredStrategy) ? null : undefined, }), // 知识宇宙:统计轮廓 + 原子时间线与显式探索 diff --git a/apps/web/lib/retrieval-config.test.ts b/apps/web/lib/retrieval-config.test.ts index 24a0aea1..a2839801 100644 --- a/apps/web/lib/retrieval-config.test.ts +++ b/apps/web/lib/retrieval-config.test.ts @@ -1,5 +1,13 @@ import { describe, expect, it } from "vitest"; -import { isSearchStrategy, getSearchStrategiesDisabled } from "./retrieval-config"; +import { + getSearchStrategiesDisabled, + isJevConfigDisabledReason, + isJevScoredStrategy, + isSearchStrategy, + JEV_SCORED_STRATEGIES, + SEARCH_STRATEGIES, + SEARCH_STRATEGY_REQUIREMENTS, +} from "./retrieval-config"; describe("JEV strategy availability", () => { it("accepts JEV as a request strategy", () => { @@ -19,4 +27,44 @@ describe("JEV strategy availability", () => { const storage = { reason: "vector_provider_lacks_lexical", message: "Lexical search required" }; expect(getSearchStrategiesDisabled({ search_strategies_disabled: { multi_jev: storage } }, "Upgrade", true).multi_jev).toEqual(storage); }); + it("lifts a missing API key only when the draft is complete", () => { + const keyMissing = { reason: "jev_api_key_missing", message: "Add a JEV API key" }; + const capabilities = { search_strategies: ["vector"], search_strategies_disabled: { multi_jev: keyMissing, sag2: keyMissing } }; + expect(getSearchStrategiesDisabled(capabilities, "Upgrade").multi_jev).toEqual(keyMissing); + expect(getSearchStrategiesDisabled(capabilities, "Upgrade").sag2).toEqual(keyMissing); + expect(getSearchStrategiesDisabled(capabilities, "Upgrade", true).multi_jev).toBeUndefined(); + expect(getSearchStrategiesDisabled(capabilities, "Upgrade", true).sag2).toBeUndefined(); + }); +}); + +describe("SAG2 strategy availability", () => { + it("lists SAG2 after JEV reranking and marks both as JEV-scored", () => { + expect(SEARCH_STRATEGIES.map(strategy => strategy.value)).toEqual(["vector", "multi_es_fast", "multi", "multi_jev", "sag2"]); + expect(isSearchStrategy("sag2")).toBe(true); + expect(JEV_SCORED_STRATEGIES).toEqual(["multi_jev", "sag2"]); + expect(isJevScoredStrategy("sag2")).toBe(true); + expect(isJevScoredStrategy("multi_jev")).toBe(true); + expect(isJevScoredStrategy("multi")).toBe(false); + expect(SEARCH_STRATEGY_REQUIREMENTS.sag2).toEqual(["jev", "sag2_relational"]); + }); + it("marks SAG2 unsupported on an older backend that still supports JEV reranking", () => { + const disabled = getSearchStrategiesDisabled({ search_strategies: ["vector", "multi_jev"] }, "Upgrade required", true); + expect(disabled.multi_jev).toBeUndefined(); + expect(disabled.sag2).toEqual({ reason: "unsupported_backend", message: "Upgrade required" }); + expect(getSearchStrategiesDisabled(undefined, "Upgrade required").sag2?.reason).toBe("unsupported_backend"); + }); + it("enables SAG2 when the backend advertises it", () => { + expect(getSearchStrategiesDisabled({ search_strategies: ["vector", "multi_jev", "sag2"] }, "Upgrade").sag2).toBeUndefined(); + }); + it("never lifts storage or relational reasons with a ready draft", () => { + const relational = { reason: "sag2_relational_unsupported", message: "SQLite or PostgreSQL required" }; + const storage = { reason: "vector_provider_lacks_lexical", message: "Lexical search required" }; + const disabled = getSearchStrategiesDisabled({ search_strategies_disabled: { sag2: relational, multi_jev: storage } }, "Upgrade", true); + expect(disabled.sag2).toEqual(relational); + expect(disabled.multi_jev).toEqual(storage); + expect(isJevConfigDisabledReason("sag2_relational_unsupported")).toBe(false); + expect(isJevConfigDisabledReason("vector_provider_lacks_lexical")).toBe(false); + expect(isJevConfigDisabledReason("jev_api_key_missing")).toBe(true); + expect(isJevConfigDisabledReason("jev_not_configured")).toBe(true); + }); }); diff --git a/apps/web/lib/retrieval-config.ts b/apps/web/lib/retrieval-config.ts index b4bb41f2..09429ca0 100644 --- a/apps/web/lib/retrieval-config.ts +++ b/apps/web/lib/retrieval-config.ts @@ -19,6 +19,11 @@ export const SEARCH_STRATEGIES = [ labelKey: "multiJevLabel", descriptionKey: "multiJevDescription", }, + { + value: "sag2", + labelKey: "sag2Label", + descriptionKey: "sag2Description", + }, ] as const; export type SearchStrategy = (typeof SEARCH_STRATEGIES)[number]["value"]; @@ -35,8 +40,32 @@ export const SEARCH_STRATEGY_REQUIREMENTS = { multi: [] as const, multi_es_fast: ["lexical_search"] as const, multi_jev: ["lexical_search", "jev"] as const, + sag2: ["jev", "sag2_relational"] as const, } as const; +/** + * Strategies whose relevance scores come from the paid JEV service. + * They share one service configuration and all need an API key. + */ +export const JEV_SCORED_STRATEGIES = ["multi_jev", "sag2"] as const satisfies readonly SearchStrategy[]; + +export type JevScoredStrategy = (typeof JEV_SCORED_STRATEGIES)[number]; + +export function isJevScoredStrategy(value: unknown): value is JevScoredStrategy { + return JEV_SCORED_STRATEGIES.some((strategy) => strategy === value); +} + +/** + * Disabled reasons that only describe an incomplete JEV service configuration. + * A complete local draft (endpoint + model + key) can lift them; storage and + * backend-version reasons are never lifted client-side. + */ +export const JEV_CONFIG_DISABLED_REASONS = ["jev_not_configured", "jev_api_key_missing"] as const; + +export function isJevConfigDisabledReason(reason: unknown): boolean { + return JEV_CONFIG_DISABLED_REASONS.some((candidate) => candidate === reason); +} + export function isSearchStrategy(value: unknown): value is SearchStrategy { return ( typeof value === "string" && @@ -70,12 +99,14 @@ export function getSearchStrategiesDisabled( jevDraftReady = false, ): SearchStrategyDisabledMap { const disabled = { ...capabilities?.search_strategies_disabled }; - const supportsJev = capabilities?.search_strategies?.includes("multi_jev") - || Object.hasOwn(disabled, "multi_jev"); - if (!supportsJev) { - disabled.multi_jev = { reason: "unsupported_backend", message: unsupportedMessage }; - } else if (jevDraftReady && disabled.multi_jev?.reason === "jev_not_configured") { - delete disabled.multi_jev; + for (const strategy of JEV_SCORED_STRATEGIES) { + const supported = capabilities?.search_strategies?.includes(strategy) + || Object.hasOwn(disabled, strategy); + if (!supported) { + disabled[strategy] = { reason: "unsupported_backend", message: unsupportedMessage }; + } else if (jevDraftReady && isJevConfigDisabledReason(disabled[strategy]?.reason)) { + delete disabled[strategy]; + } } return disabled; } diff --git a/apps/web/messages/en-US.json b/apps/web/messages/en-US.json index ef95ade4..11b51e39 100644 --- a/apps/web/messages/en-US.json +++ b/apps/web/messages/en-US.json @@ -613,7 +613,11 @@ "disabledSuffix": "(unavailable)", "multiJevLabel": "JEV reranking", "multiJevDescription": "Expand related evidence, then score relevance with your configured JEV service.", - "unsupportedBackend": "This server does not advertise JEV support. Upgrade the server to use this mode." + "sag2Label": "SAG2 evidence retrieval", + "sag2Description": "BM25 recall scored over several JEV rounds; no vector store needed; paid service.", + "paid": "Paid", + "openSettings": "Open settings", + "unsupportedBackend": "This server does not advertise support for this JEV-scored mode. Upgrade the server to use it." }, "RetrievalTest": { "failed": "Retrieval failed", @@ -680,8 +684,10 @@ "jevStorageUnchanged": "Your existing retrieval settings remain unchanged. Document uploads, search, and chat continue to use the current compatible retrieval behavior.", "jevStorageSelectCompatible": "The saved JEV mode cannot run with this storage. Choose Fast (vector) or Precise above and save to resume retrieval. Your models and document data are kept.", "jevStorageNoChanges": "No database or model changes are needed to continue using your knowledge base. You can still adjust document processing and retrieval settings above.", + "sag2StorageUnavailable": "SAG2 evidence retrieval currently supports only SQLite and PostgreSQL relational stores; it is unavailable with the current storage.", "jevTitle": "JEV reranking service", - "jevDescription": "Selecting JEV mode sends the question and candidate evidence to this service for relevance scoring. Saving the service alone does not enable this mode.", + "jevDescription": "Selecting JEV reranking or SAG2 evidence retrieval sends the question and candidate evidence to this service for relevance scoring; an API key is required. Saving the service alone does not enable these modes.", + "jevSharedNotice": "JEV is a paid service shared by JEV reranking and SAG2 evidence retrieval and is only called while one of them is selected. The failure policy applies to JEV reranking only.", "jevProvider": "Service provider", "jevProviderOfficial": "TypeSafe official", "jevProviderCustom": "Custom", @@ -690,12 +696,13 @@ "jevEndpointDescription": "Use the complete HTTP(S) scoring URL supplied by your service. No path is added automatically.", "jevModel": "Model", "jevModelDescription": "jev-latest follows the latest stable JEV release. You can enter a specific model identifier supported by your service.", - "jevKey": "API key (optional)", + "jevKey": "API key (required for JEV modes)", "jevKeyConfigured": "Configured; leave blank to keep it", - "jevKeyOptional": "Leave blank for a service without authentication", + "jevKeyRequiredPlaceholder": "Enter the API key for your JEV service", "jevKeyProviderPlaceholder": "Enter your {provider} API key", "jevKeyProviderDescription": "{provider} requires its own API key. Leave blank only to reuse a key already saved for this address.", "jevKeyDescription": "This key is separate from your generation model key. Changing the service address clears the saved key; enter a new one if required.", + "jevKeyRequired": "Enter the JEV API key before selecting JEV reranking or SAG2 evidence retrieval.", "jevTimeout": "Reranking time limit (seconds)", "jevTimeoutDescription": "Total scoring and retry time, from 0.1 to 120 seconds.", "jevFailurePolicy": "When reranking fails", @@ -704,7 +711,7 @@ "jevTest": "Test JEV connection", "jevTesting": "Testing…", "jevTestFailed": "JEV connection test failed", - "jevInvalidDraft": "Enter a valid full HTTP(S) URL, a model name, and a time limit between 0.1 and 120 seconds." + "jevInvalidDraft": "Enter a valid full HTTP(S) URL, a model name, and a time limit between 0.1 and 120 seconds. JEV modes also require an API key." }, "ChatbotConfig": { "retry": "Retry", @@ -1767,6 +1774,8 @@ "actual": "Actual: {mode}", "coarse": "Coarse ranking", "jevFallback": "JEV reranking did not complete; these results include coarse ranking.", + "jevUsage": "JEV scoring this run: {requests} requests · {judgments} judgments{tokens}", + "jevUsageTokens": " · {tokens} input tokens", "partial": "Partial results: some sources did not complete." }, "ClientAccess": { diff --git a/apps/web/messages/zh-CN.json b/apps/web/messages/zh-CN.json index 633aa268..8be0c7fc 100644 --- a/apps/web/messages/zh-CN.json +++ b/apps/web/messages/zh-CN.json @@ -613,7 +613,11 @@ "disabledSuffix": "(不可用)", "multiJevLabel": "JEV 精排", "multiJevDescription": "扩展关联证据后,使用配置的 JEV 服务评分相关性。", - "unsupportedBackend": "当前服务端未声明支持 JEV,请升级服务端后使用此模式。" + "sag2Label": "SAG2 证据检索", + "sag2Description": "BM25 召回后由 JEV 服务多轮评分,不依赖向量库;付费服务。", + "paid": "付费", + "openSettings": "去设置", + "unsupportedBackend": "当前服务端未声明支持此 JEV 评分模式,请升级服务端后使用。" }, "RetrievalTest": { "failed": "检索失败", @@ -680,8 +684,10 @@ "jevStorageUnchanged": "现有检索设置保持不变。文档上传、检索和问答继续沿用当前兼容的检索行为。", "jevStorageSelectCompatible": "已保存的 JEV 模式无法在此存储下运行。请在上方选择“快速(向量)”或“精准”并保存,以恢复检索;模型和文档数据保持不变。", "jevStorageNoChanges": "继续使用知识库无需更换数据库或模型。仍可调整上方的文档处理和检索参数。", + "sag2StorageUnavailable": "SAG2 证据检索首期仅支持 SQLite 与 PostgreSQL 关系库,当前存储不可用。", "jevTitle": "JEV 精排服务", - "jevDescription": "选择 JEV 模式时,会将问题与候选证据发送至此服务进行相关性评分。仅保存服务配置不会开启此模式。", + "jevDescription": "选择 JEV 精排或 SAG2 证据检索时,会将问题与候选证据发送至此服务进行相关性评分,需填写 API Key。仅保存服务配置不会开启这些模式。", + "jevSharedNotice": "JEV 为付费服务,由「JEV 精排」与「SAG2 证据检索」共用,仅在选择其中一种模式时才会调用;「精排失败时」策略仅对 JEV 精排生效。", "jevProvider": "服务商", "jevProviderOfficial": "TypeSafe 官方", "jevProviderCustom": "自定义", @@ -690,12 +696,13 @@ "jevEndpointDescription": "填写服务商提供的完整 HTTP(S) 评分地址,系统不会自动追加路径。", "jevModel": "模型", "jevModelDescription": "jev-latest 跟随 JEV 最新稳定版,也可填写服务商支持的指定模型标识。", - "jevKey": "API Key(可选)", + "jevKey": "API Key(选择 JEV 模式时必填)", "jevKeyConfigured": "已配置,留空保持不变", - "jevKeyOptional": "免密服务可留空", + "jevKeyRequiredPlaceholder": "填写 JEV 服务的 API Key", "jevKeyProviderPlaceholder": "填写 {provider} API Key", "jevKeyProviderDescription": "{provider} 需要独立的 API Key;仅在此地址已保存密钥时,才可留空复用。", "jevKeyDescription": "此密钥独立于生成模型密钥。更改服务地址后会清除原密钥,如需鉴权请重新填写。", + "jevKeyRequired": "选择 JEV 精排或 SAG2 证据检索前,请填写 JEV API Key。", "jevTimeout": "精排总时限(秒)", "jevTimeoutDescription": "包含评分与重试,总时限为 0.1 至 120 秒。", "jevFailurePolicy": "精排失败时", @@ -704,7 +711,7 @@ "jevTest": "测试 JEV 连接", "jevTesting": "测试中…", "jevTestFailed": "JEV 连接测试失败", - "jevInvalidDraft": "请填写有效的完整 HTTP(S) URL、模型名,以及 0.1 至 120 秒的总时限。" + "jevInvalidDraft": "请填写有效的完整 HTTP(S) URL、模型名,以及 0.1 至 120 秒的总时限;选择 JEV 模式时还需填写 API Key。" }, "ChatbotConfig": { "retry": "重试", @@ -1767,6 +1774,8 @@ "actual": "实际模式:{mode}", "coarse": "粗排", "jevFallback": "本次未完成 JEV 精排,已返回粗排结果。", + "jevUsage": "本次 JEV 评分:{requests} 次请求 · {judgments} 次判定{tokens}", + "jevUsageTokens": " · {tokens} 输入 token", "partial": "部分结果:部分信源未完成检索。" }, "ClientAccess": { From 9662cce6902d9124612ce000c1eb23a06ebaad37 Mon Sep 17 00:00:00 2001 From: luoshuai990529 <58510855+luoshuai990529@users.noreply.github.com> Date: Sun, 25 Oct 2026 01:05:43 +0800 Subject: [PATCH 2/5] =?UTF-8?q?feat(sources):=20=E4=BF=A1=E6=BA=90?= =?UTF-8?q?=E5=8F=AF=E8=AE=BE=E7=BD=AE=E9=BB=98=E8=AE=A4=E6=A3=80=E7=B4=A2?= =?UTF-8?q?=E6=A8=A1=E5=BC=8F=EF=BC=8C=E5=88=9B=E5=BB=BA=E6=97=B6=E5=8F=AF?= =?UTF-8?q?=E5=B0=B1=E5=9C=B0=E9=85=8D=E7=BD=AE=20JEV?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 后端 - `Source` 新增 `default_search_strategy`(可空,跟随全局默认),创建 / 更新 接口接受并返回;取值须为当前部署可用的模式,JEV 付费模式还需已保存 API Key,拒绝时沿用能力原因码 - 新增 `resolve_search_strategy`:显式请求 → Agent 人格 → 范围内信源的共同 默认 → 全局默认;检索服务、搜索接口、Agent 工具统一走该解析,结果 `stats.strategy_origin` 标明来源 前端 - 创建 / 编辑信源对话框新增「默认检索模式」选择器:首项「跟随全局默认」, 各模式附通俗说明、适用场景与付费标识;不可用的模式灰置并说明原因 - 选择 JEV 模式但缺少服务或 Key 时就地展开 JEV 配置(预设服务商、Key、 测试连接),保存后再创建或更新;缺 Key 时无法提交 - 信源卡片与详情头部显示默认模式标签;搜索页在范围内信源默认一致且用户 未手动选择时自动采用并标注「信源默认」 --- CHANGELOG.md | 1 + README-CN.md | 4 +- README.md | 4 +- apps/api/sag_api/api/v1/search.py | 7 +- apps/api/sag_api/core/db.py | 1 + apps/api/sag_api/db/models/source.py | 3 + apps/api/sag_api/sag/engine_manager.py | 9 +- apps/api/sag_api/schemas/source.py | 7 +- apps/api/sag_api/services/agent_tooling.py | 2 +- .../api/sag_api/services/retrieval_service.py | 46 ++- apps/api/sag_api/services/settings_service.py | 25 +- apps/api/sag_api/services/source_service.py | 22 ++ apps/api/sag_api/tools/builtin.py | 9 +- apps/api/tests/chatbot/test_model_cards.py | 3 +- apps/api/tests/test_jev_config.py | 81 +++++ .../api/tests/test_source_default_strategy.py | 219 +++++++++++++ apps/web/app/(app)/knowledge/[id]/page.tsx | 12 +- .../features/create-source-dialog.tsx | 2 +- .../features/document-deletion.test.tsx | 2 +- .../document-processing-progress.test.tsx | 2 +- .../document-restart-confirmation.test.tsx | 2 +- .../features/dsh-service-settings.test.tsx | 1 + .../features/edit-source-dialog.test.tsx | 114 +++++++ .../features/edit-source-dialog.tsx | 77 ++++- .../components/features/jev-quick-setup.tsx | 290 ++++++++++++++++++ .../features/knowledge-config-form.tsx | 18 +- .../features/knowledge-workspace.test.tsx | 1 + .../features/retrieval-mode-picker.test.tsx | 148 +++++++++ .../features/retrieval-mode-picker.tsx | 157 ++++++++++ .../features/retrieval-mode-pill.tsx | 51 +++ .../features/search-strategy-control.test.tsx | 12 +- .../features/search-strategy-control.tsx | 36 +-- .../features/search/search-panel.tsx | 6 +- .../features/search/search-provider.tsx | 52 +++- .../search/search-scope-default.test.tsx | 126 ++++++++ .../components/features/source-card.test.tsx | 43 ++- apps/web/components/features/source-card.tsx | 7 +- .../features/source-create-form.test.tsx | 156 ++++++++++ .../features/source-create-form.tsx | 78 ++++- .../features/source-deletion.test.tsx | 2 +- apps/web/lib/api.ts | 7 +- apps/web/lib/jev-config.ts | 37 +++ apps/web/lib/retrieval-config.test.ts | 35 +++ apps/web/lib/retrieval-config.ts | 49 +++ apps/web/lib/types.ts | 6 + apps/web/messages/en-US.json | 44 ++- apps/web/messages/zh-CN.json | 44 ++- 47 files changed, 1960 insertions(+), 100 deletions(-) create mode 100644 apps/api/tests/test_source_default_strategy.py create mode 100644 apps/web/components/features/edit-source-dialog.test.tsx create mode 100644 apps/web/components/features/jev-quick-setup.tsx create mode 100644 apps/web/components/features/retrieval-mode-picker.test.tsx create mode 100644 apps/web/components/features/retrieval-mode-picker.tsx create mode 100644 apps/web/components/features/retrieval-mode-pill.tsx create mode 100644 apps/web/components/features/search/search-scope-default.test.tsx create mode 100644 apps/web/components/features/source-create-form.test.tsx create mode 100644 apps/web/lib/jev-config.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e3c3a83..3b2a3e73 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ ## Unreleased +- 信源可设置「默认检索模式」:创建或编辑信源时选择快速、精确、JEV 精排或 SAG2 证据检索,并以通俗说明与付费提示帮助选择;JEV 模式缺少 API Key 时可在对话框内直接配置。搜索与问答在所选范围内信源一致时自动采用该默认(显式选择与 Agent 人格优先),结果 `stats.strategy_origin` 标明来源。不改变文档入库流程。 - SAG2 只读引擎改在专用事件循环线程运行:大范围检索构建内存语料时不再阻塞 API 事件循环;整次超时会同步取消引擎侧工作。 - 新增可选 SAG2 证据检索模式(`sag2`):接入 `zleap-sag2` 0.1.0,只读直搜 SQLite / PostgreSQL 关系库,BM25 召回后由 JEV 服务多轮评分,不依赖向量库,文档入库后即可检索;与 JEV 精排共用服务配置,失败不回退,首期不支持 MySQL / OceanBase。 - JEV 为付费服务:选择 JEV 精排或 SAG2 证据检索前必须填写 API Key;仅保存服务地址不再足以启用模式,连接测试也要求 Key。探索页灰置项直接给出原因与设置入口,SAG2 结果显示本次评分用量。 diff --git a/README-CN.md b/README-CN.md index ed5c662d..4ab80206 100644 --- a/README-CN.md +++ b/README-CN.md @@ -570,7 +570,9 @@ config = EngineConfig.from_env() 这里列出的是应用/API 策略名称;应用将 `multi` 映射到 Python 引擎的 `full_expand`,将 `multi_es_fast` 映射到 `pruned_expand_rff`,`sag2` 由独立的 `zleap-sag2` 引擎执行。可用性取决于存储能力:`multi_es_fast` 与 `multi_jev` 需要词法检索支持,`sag2` 需要 SQLite 或 PostgreSQL 关系库。 -在“设置 → 知识库 → 检索”配置 302.AI、TypeSafe 官方或自定义 JEV 服务(默认 `jev-latest`,独立 API Key),再选择 **JEV 精排** 或 **SAG2 证据检索**。JEV 是付费服务:仅保存服务不会启用,选择任一 JEV 模式前必须填写 API Key。JEV 精排默认限时 30 秒、失败报错,可选择粗排降级。 +每个信源可在创建或编辑时设置**默认检索模式**;未设置则跟随全局默认。搜索与问答按“本次显式选择 → Agent 人格 → 范围内信源的共同默认 → 全局默认”解析模式,范围内信源默认不一致时按全局默认处理;结果 `stats.strategy_origin` 标明来源。该设置只影响检索,不改变文档入库流程。 + +在“设置 → 知识库 → 检索”配置 302.AI、TypeSafe 官方或自定义 JEV 服务(默认 `jev-latest`,独立 API Key),再选择 **JEV 精排** 或 **SAG2 证据检索**;创建信源时选择 JEV 模式也可在对话框内直接完成该配置。JEV 是付费服务:仅保存服务不会启用,选择任一 JEV 模式前必须填写 API Key。JEV 精排默认限时 30 秒、失败报错,可选择粗排降级。 **SAG2 证据检索**与 JEV 精排共用同一服务配置,但不经向量库:它直接只读 SAG 的 SQLite / PostgreSQL 关系库(首期不支持 MySQL / OceanBase),文档分块入库后即可检索,不要求事件抽取完成,pgvector 单库部署也可使用。每次检索会扫描所选信源的全部段落并多轮调用 JEV,用量高于 JEV 精排;失败直接报错,不支持粗排降级。候选数、超时、并发与范围上限等调优参数见 `apps/api/.env.example` 的 `SAG_SAG2_*`。使用 PostgreSQL 时,连接用户需能在目标 schema 创建并读写 `sag2_state`、`sag2_search_sessions` 两张辅助表,并对 `sag2_state` 执行 `LOCK TABLE`;SAG 的业务表保持只读。 diff --git a/README.md b/README.md index 2165776e..af9e3e9b 100644 --- a/README.md +++ b/README.md @@ -568,7 +568,9 @@ Pipeline request and result types are available from `zleap.sag.pipeline`: `Pars These are the application/API strategy names; the application maps `multi` to the Python engine's `full_expand` and `multi_es_fast` to `pruned_expand_rff`, while `sag2` runs on the separate `zleap-sag2` engine. Availability depends on storage capabilities: `multi_es_fast` and `multi_jev` require lexical search support; `sag2` requires a SQLite or PostgreSQL relational store. -Configure 302.AI, TypeSafe, or a custom JEV service in **Settings → Knowledge → Retrieval** (default model: `jev-latest`, separate API key), then select **JEV reranking** or **SAG2 evidence retrieval**. JEV is a paid service: saving the service alone does not enable it, and an API key is required before either JEV mode can be selected. JEV reranking has a 30-second default deadline; failures return an error unless coarse fallback is enabled. +Each source can carry a **default retrieval mode**, chosen when the source is created or edited; unset means follow the global default. Search and chat resolve the mode as explicit request → agent persona → the shared default of every source in scope → global default, falling back to the global default when sources in scope disagree; `stats.strategy_origin` reports which one applied. The setting only affects retrieval and never changes document ingestion. + +Configure 302.AI, TypeSafe, or a custom JEV service in **Settings → Knowledge → Retrieval** (default model: `jev-latest`, separate API key), then select **JEV reranking** or **SAG2 evidence retrieval**; choosing a JEV mode while creating a source offers the same configuration inline. JEV is a paid service: saving the service alone does not enable it, and an API key is required before either JEV mode can be selected. JEV reranking has a 30-second default deadline; failures return an error unless coarse fallback is enabled. **SAG2 evidence retrieval** shares the JEV service configuration but bypasses the vector store: it reads SAG's SQLite or PostgreSQL relational store directly (MySQL and OceanBase are not supported yet), documents become searchable as soon as they are chunked and stored, event extraction is not required, and pgvector single-database deployments can use it. Each search scans every passage of the selected sources and calls JEV over several rounds, so it costs more than JEV reranking; failures are reported as errors, with no coarse fallback. Tuning knobs for candidates, timeouts, concurrency and scope limits are documented as `SAG_SAG2_*` in `apps/api/.env.example`. On PostgreSQL the connecting role must be able to create and use the two auxiliary tables `sag2_state` and `sag2_search_sessions` in the target schema and to `LOCK TABLE` `sag2_state`; SAG's own tables stay read-only. diff --git a/apps/api/sag_api/api/v1/search.py b/apps/api/sag_api/api/v1/search.py index 78be5e6e..ee479421 100644 --- a/apps/api/sag_api/api/v1/search.py +++ b/apps/api/sag_api/api/v1/search.py @@ -44,6 +44,7 @@ event_scores_from_evidence, published_document_inputs, recall_event_scores, + resolve_search_strategy, retrieve_relevant_sections, stream_synthesize_search_answer, synthesize_search_answer, @@ -170,12 +171,14 @@ async def _retrieve_search_evidence( body: SearchRequest | GlobalSearchRequest, ) -> tuple[SearchOutcome, EventScoreMap, bool]: configuration = getattr(engine_manager, "_settings", settings) - strategy = body.strategy or configuration.search_strategy + # Resolve once for the evidence-shape decision below; the retrieval service + # resolves the same inputs again and records where the mode came from. + strategy = resolve_search_strategy(requested=body.strategy, sources=sources, configuration=configuration).strategy retrieval = retrieve_relevant_sections( engine_manager, sources, body.query, - strategy=strategy, + strategy=body.strategy, top_k=body.top_k, include_ranked_candidates=body.include_ranked_candidates, ) diff --git a/apps/api/sag_api/core/db.py b/apps/api/sag_api/core/db.py index d89c8f9c..7afedcf6 100644 --- a/apps/api/sag_api/core/db.py +++ b/apps/api/sag_api/core/db.py @@ -60,6 +60,7 @@ async def get_session() -> AsyncIterator[AsyncSession]: # create_all 只建新表、不改旧表,故对演进列做幂等 ADD COLUMN。 _COLUMN_UPGRADES: dict[str, dict[str, str]] = { "agents": {"is_default": "BOOLEAN NOT NULL DEFAULT FALSE"}, + "sources": {"default_search_strategy": "VARCHAR(32)"}, "documents": { "progress": "INTEGER NOT NULL DEFAULT 0", "processing_stage": "VARCHAR(32)", diff --git a/apps/api/sag_api/db/models/source.py b/apps/api/sag_api/db/models/source.py index d917c91b..beecd7b2 100644 --- a/apps/api/sag_api/db/models/source.py +++ b/apps/api/sag_api/db/models/source.py @@ -33,6 +33,9 @@ class Source(IDMixin, TimestampMixin, Base): document_count: Mapped[int] = mapped_column(Integer, default=0) chunk_count: Mapped[int] = mapped_column(Integer, default=0) event_count: Mapped[int] = mapped_column(Integer, default=0) + # 该信源的默认检索模式;None 表示跟随全局默认。搜索与问答在范围内信源一致时采用, + # 不改变文档入库流程。 + default_search_strategy: Mapped[str | None] = mapped_column(String(32), nullable=True) @hybrid_property def is_deleting(self) -> bool: diff --git a/apps/api/sag_api/sag/engine_manager.py b/apps/api/sag_api/sag/engine_manager.py index cd40017d..8c612b21 100644 --- a/apps/api/sag_api/sag/engine_manager.py +++ b/apps/api/sag_api/sag/engine_manager.py @@ -425,12 +425,17 @@ def strategies_capability_report(cls, settings: Settings) -> dict[str, Any]: return {"enabled": enabled, "disabled": disabled} @classmethod - def require_jev_capabilities(cls, settings: Settings, strategy: str = "multi_jev") -> None: - """Reject explicit JEV-scored mode activation before publishing incompatible settings.""" + def require_strategy_available(cls, settings: Settings, strategy: str) -> None: + """Reject selecting a mode the current deployment cannot serve, with its capability reason.""" unavailable = cls.strategies_capability_report(settings)["disabled"].get(strategy) if unavailable is not None: raise ConfigurationError(unavailable["message"], code=unavailable["reason"]) + @classmethod + def require_jev_capabilities(cls, settings: Settings, strategy: str = "multi_jev") -> None: + """Reject explicit JEV-scored mode activation before publishing incompatible settings.""" + cls.require_strategy_available(settings, strategy) + def _config_for(self, source: Source | None) -> Any: overrides = None if source is not None and source.config: diff --git a/apps/api/sag_api/schemas/source.py b/apps/api/sag_api/schemas/source.py index 7bcc11dc..cd45d139 100644 --- a/apps/api/sag_api/schemas/source.py +++ b/apps/api/sag_api/schemas/source.py @@ -5,7 +5,7 @@ from pydantic import BaseModel, ConfigDict, Field -from sag_api.enums import ConnectorKind, SourceStatus, SourceType +from sag_api.enums import ConnectorKind, SearchStrategy, SourceStatus, SourceType from sag_api.schemas.job import JobOut @@ -22,12 +22,16 @@ class SourceCreate(BaseModel): description: str = "" connector_kind: ConnectorKind = ConnectorKind.FILE_UPLOAD config: dict[str, Any] = Field(default_factory=dict) + # 默认检索模式;None 表示跟随全局默认。 + default_search_strategy: SearchStrategy | None = None class SourceUpdate(BaseModel): name: str | None = Field(default=None, max_length=200) description: str | None = None status: SourceStatus | None = None + # 显式传 null 表示改回跟随全局默认;未出现则保持不变。 + default_search_strategy: SearchStrategy | None = None class SourceOut(BaseModel): @@ -42,6 +46,7 @@ class SourceOut(BaseModel): document_count: int chunk_count: int event_count: int + default_search_strategy: SearchStrategy | None = None created_at: datetime updated_at: datetime deletion_job: JobOut | None = None diff --git a/apps/api/sag_api/services/agent_tooling.py b/apps/api/sag_api/services/agent_tooling.py index e1706ef4..0e6fdb22 100644 --- a/apps/api/sag_api/services/agent_tooling.py +++ b/apps/api/sag_api/services/agent_tooling.py @@ -348,7 +348,7 @@ def _adapt_tool(host_tool, host_context: HostToolContext, citations: list[dict]) from sag_api.tools.builtin import knowledge_search_strategy configuration = getattr(host_context.engine_manager, "_settings", settings) - strategy = knowledge_search_strategy(host_context.persona, configuration) + strategy = knowledge_search_strategy(host_context.persona, configuration, host_context.sources) # Keep this run's mode stable while the model prepares the tool call. host_context = replace(host_context, persona={**host_context.persona, "search_strategy": strategy}) if strategy == "multi_jev": diff --git a/apps/api/sag_api/services/retrieval_service.py b/apps/api/sag_api/services/retrieval_service.py index a28bb7c8..dcd2a9e5 100644 --- a/apps/api/sag_api/services/retrieval_service.py +++ b/apps/api/sag_api/services/retrieval_service.py @@ -30,6 +30,47 @@ class SearchSource(Protocol): EventScoreMap = dict[tuple[str, str], float] DocumentSourceScope = dict[str, tuple[str, ...]] +StrategyOrigin = Literal["request", "persona", "source_default", "global"] + + +@dataclass(frozen=True, slots=True) +class ResolvedSearchStrategy: + """The mode a retrieval will run with and where that choice came from.""" + + strategy: str + origin: StrategyOrigin + + +def common_source_default_strategy(sources) -> str | None: + """范围内每个信源都设置了同一默认模式时返回它;有信源未设置或不一致则返回 None。 + + 混合范围不猜测:一个信源的偏好不应改变其他信源的检索方式。 + """ + defaults: set[str] = set() + for source in sources: + value = getattr(source, "default_search_strategy", None) + if not value: + return None + defaults.add(normalize_search_strategy(str(value))) + return next(iter(defaults)) if len(defaults) == 1 else None + + +def resolve_search_strategy( + *, + requested: str | None = None, + persona_strategy: str | None = None, + sources=(), + configuration: Any = settings, +) -> ResolvedSearchStrategy: + """显式请求 → Agent 人格 → 范围内信源的共同默认 → 全局默认。""" + if requested: + return ResolvedSearchStrategy(requested, "request") + if persona_strategy: + return ResolvedSearchStrategy(persona_strategy, "persona") + common = common_source_default_strategy(sources) + if common: + return ResolvedSearchStrategy(common, "source_default") + return ResolvedSearchStrategy(configuration.search_strategy, "global") def event_scores_from_evidence(sections: list[RetrievedSection]) -> EventScoreMap: @@ -324,7 +365,8 @@ async def retrieve_relevant_sections( total_start = time.perf_counter() configuration = getattr(engine_manager, "_settings", settings) - requested_strategy = strategy or configuration.search_strategy + resolved = resolve_search_strategy(requested=strategy, sources=sources, configuration=configuration) + requested_strategy = resolved.strategy mode = normalize_search_strategy(requested_strategy) if mode in JEV_SCORED_STRATEGIES: # The JEV-scored profile owns recall and final scoring. Adding application @@ -351,6 +393,7 @@ async def retrieve_relevant_sections( return SearchOutcome(query=outcome.query or query, sections=visible_sections[:requested_limit], stats={ **outcome.stats, "requested_strategy": requested_strategy, + "strategy_origin": resolved.origin, "requested_top_k": requested_limit, "candidate_top_k": requested_limit, "candidates": len(outcome.sections), @@ -416,6 +459,7 @@ def visible(section: RetrievedSection) -> bool: stats = { **outcome.stats, "requested_strategy": requested_strategy, + "strategy_origin": resolved.origin, "requested_top_k": requested_limit, "candidate_top_k": candidate_limit, "candidates": reranked.candidate_count, diff --git a/apps/api/sag_api/services/settings_service.py b/apps/api/sag_api/services/settings_service.py index 6e57d9df..2ff7b533 100644 --- a/apps/api/sag_api/services/settings_service.py +++ b/apps/api/sag_api/services/settings_service.py @@ -21,7 +21,7 @@ from sag_api.core.errors import ConfigurationError, ConflictError from sag_api.core.logging import get_logger from sag_api.core.model_providers import get_model_provider -from sag_api.db.models import Document, Setting +from sag_api.db.models import Document, Setting, Source from sag_api.enums import JEV_SCORED_STRATEGIES, SEARCH_STRATEGIES, normalize_search_strategy from sag_api.schemas.system import ModelConfigUpdate @@ -507,18 +507,29 @@ async def _save_model_config_locked(session: AsyncSession, patch: dict) -> dict: elif "jev_endpoint" in patch and candidate["jev_endpoint"] != raw.get("jev_endpoint", _settings.jev_endpoint): stored["jev_api_key"] = None if patch.keys() & {"jev_endpoint", "jev_api_key"}: - # Changing the scoring connection must not leave a paid JEV mode as the default - # without a usable key; the caller either switches mode or supplies the key. + # Connection changes must preserve both global and source-level defaults. + # Reject atomically rather than silently changing a saved retrieval mode. from sag_api.sag.sag2_engine import jev_connection_issue final = {**candidate, **{key: stored[key] for key in ("jev_endpoint", "jev_api_key") if key in stored}} - if normalize_search_strategy(str(final["search_strategy"])) in JEV_SCORED_STRATEGIES: - issue = jev_connection_issue(_settings.model_copy(update=final)) - if issue is not None: - code, message = issue + issue = jev_connection_issue(_settings.model_copy(update=final)) + if issue is not None: + code, message = issue + if normalize_search_strategy(str(final["search_strategy"])) in JEV_SCORED_STRATEGIES: raise ConfigurationError( f"{message} 当前默认检索模式为 JEV 模式;请先改为其他模式,或补填该服务的 API Key。", code=code, ) + source_default = await session.scalar( + select(Source.id).where( + Source.is_deleting.is_(False), + Source.default_search_strategy.in_(JEV_SCORED_STRATEGIES), + ).limit(1) + ) + if source_default is not None: + raise ConfigurationError( + f"{message} 已有信源默认使用 JEV 模式;请先修改信源默认模式,或补填该服务的 API Key。", + code=code, + ) identity = ("llm_provider", "llm_responses_provider", "llm_responses_endpoint") if ( not _settings.lock_llm_config diff --git a/apps/api/sag_api/services/source_service.py b/apps/api/sag_api/services/source_service.py index 3cfc5828..5e642ca7 100644 --- a/apps/api/sag_api/services/source_service.py +++ b/apps/api/sag_api/services/source_service.py @@ -19,12 +19,14 @@ from sag_api.db.models import Document, Job, OctxInstallation, OctxTransfer, Source from sag_api.enums import ( CONNECTOR_SOURCE_TYPE, + SEARCH_STRATEGIES, DocumentStatus, JobStatus, JobType, OctxTransferStatus, SourceStatus, SourceType, + normalize_search_strategy, ) from sag_api.jobs import JobQueue from sag_api.jobs.scheduling import DELETE_PRIORITY, set_scheduler @@ -97,12 +99,28 @@ async def get_source(session: AsyncSession, source_id: str) -> Source: return source +def validated_default_search_strategy(value: str | None, configuration=settings) -> str | None: + """信源默认检索模式必须是当前部署可用的模式;JEV 付费模式还要求已保存 API Key。 + + 与设置页、Agent 人格使用同一能力报告,拒绝时带相同原因码供前端提示。 + """ + if value is None: + return None + strategy = normalize_search_strategy(str(value)) + if strategy not in SEARCH_STRATEGIES: + raise ValidationError(f"不支持的检索模式:{value}") + EngineManager.require_strategy_available(configuration, strategy) + return strategy + + async def create_source( session: AsyncSession, data: SourceCreate, *, engine_manager: EngineManager ) -> Source: connector = registry.get(data.connector_kind) connector.validate_config(data.config) source_type = CONNECTOR_SOURCE_TYPE.get(data.connector_kind, SourceType.DOCUMENT) + # 与设置页、Agent 人格一致,按全局配置单例判断模式可用性。 + default_strategy = validated_default_search_strategy(data.default_search_strategy) source = Source( name=data.name, @@ -111,6 +129,7 @@ async def create_source( connector_kind=data.connector_kind, sag_source_config_id=f"src_{new_id()[:16]}", config=initialize_vector_identity_state(data.config or {}), + default_search_strategy=default_strategy, ) session.add(source) await session.commit() @@ -146,6 +165,9 @@ async def update_source( source.description = data.description if data.status is not None: source.status = data.status + if "default_search_strategy" in data.model_fields_set: + # 显式 null 表示改回跟随全局默认;只影响后续检索,不触发文档重处理。 + source.default_search_strategy = validated_default_search_strategy(data.default_search_strategy) await session.commit() await session.refresh(source) from sag_api.services.universe_service import schedule_universe_refresh diff --git a/apps/api/sag_api/tools/builtin.py b/apps/api/sag_api/tools/builtin.py index 86bd35a3..cf10c280 100644 --- a/apps/api/sag_api/tools/builtin.py +++ b/apps/api/sag_api/tools/builtin.py @@ -23,6 +23,7 @@ from sag_api.generation import build_citations from sag_api.sag import RetrievedSection from sag_api.services.retrieval_service import ( + common_source_default_strategy, event_scores_from_evidence, published_document_inputs, recall_event_scores, @@ -79,11 +80,11 @@ def _events_by_section(events: list | None) -> dict[tuple[str, str], list]: return grouped -def knowledge_search_strategy(persona: dict[str, Any], configuration: Any = settings) -> str: - """Keep the legacy vector default unless the user explicitly enables a JEV-scored mode.""" +def knowledge_search_strategy(persona: dict[str, Any], configuration: Any = settings, sources=()) -> str: + """Persona choice → shared source default → legacy default (vector unless a JEV mode is global).""" configured = normalize_search_strategy(configuration.search_strategy) default = configured if configured in JEV_SCORED_STRATEGIES else "vector" - value = persona.get("search_strategy") or default + value = persona.get("search_strategy") or common_source_default_strategy(sources) or default if default in JEV_SCORED_STRATEGIES and ( not isinstance(value, str) or normalize_search_strategy(value) not in SEARCH_STRATEGIES ): @@ -249,7 +250,7 @@ async def invoke(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult: if not query or not ctx.sources: return ToolResult(content="(无相关资料)", citations=[], data={"section_count": 0}) persona = ctx.persona or {} - strategy = knowledge_search_strategy(persona, getattr(ctx.engine_manager, "_settings", settings)) + strategy = knowledge_search_strategy(persona, getattr(ctx.engine_manager, "_settings", settings), ctx.sources) top_k = args.get("top_k") or persona.get("top_k") limit = max(1, min(int(top_k or 8), 50)) source_refs = {s.sag_source_config_id: {"id": s.id, "name": s.name} for s in ctx.sources} diff --git a/apps/api/tests/chatbot/test_model_cards.py b/apps/api/tests/chatbot/test_model_cards.py index 76f49f6a..a56aad62 100644 --- a/apps/api/tests/chatbot/test_model_cards.py +++ b/apps/api/tests/chatbot/test_model_cards.py @@ -13,7 +13,7 @@ from sag_api.core.db import get_session from sag_api.core.deps import get_current_user from sag_api.core.errors import ApiError -from sag_api.db.models import Document, Setting +from sag_api.db.models import Document, Setting, Source from sag_api.services import settings_service @@ -26,6 +26,7 @@ async def card_client(isolate, database, monkeypatch): async with database() as session: connection = await session.connection() await connection.run_sync(lambda sync: Document.__table__.create(sync)) + await connection.run_sync(lambda sync: Source.__table__.create(sync)) await session.commit() class Runtime: diff --git a/apps/api/tests/test_jev_config.py b/apps/api/tests/test_jev_config.py index ccc5b82f..2406d2e1 100644 --- a/apps/api/tests/test_jev_config.py +++ b/apps/api/tests/test_jev_config.py @@ -221,6 +221,87 @@ async def test_jev_service_rejects_invalid_explicit_fields_before_persisting(jev assert resets == [] +@pytest.mark.parametrize("strategy", ["multi_jev", "sag2"]) +@pytest.mark.parametrize("endpoint", [None, "https://replacement.example/score"]) +async def test_jev_connection_change_preserves_source_defaults_atomically(jev_config_client, strategy, endpoint): + from sag_api.core.db import SessionLocal + from sag_api.db.models import Setting, Source + + client, headers, resets = jev_config_client + initial = await client.put( + "/api/v1/system/model-config", headers=headers, + json={"search_strategy": "vector", "jev_endpoint": "https://saved.example/score", + "jev_api_key": "synthetic-saved-key"}, + ) + assert initial.status_code == 200, initial.text + source_id = uuid4().hex + async with SessionLocal() as session: + session.add(Source(id=source_id, name="Protected source", sag_source_config_id=source_id, + default_search_strategy=strategy)) + await session.commit() + row = await session.scalar(select(Setting).where(Setting.scope == "global", Setting.key == "model_config")) + stored_before = dict(row.value) + settings_before = settings.model_dump() + reset_count = len(resets) + try: + rejected = await client.put( + "/api/v1/system/model-config", headers=headers, json={"jev_endpoint": endpoint}, + ) + assert rejected.status_code == 400, rejected.text + assert rejected.json()["error"]["code"] in {"jev_not_configured", "jev_api_key_missing"} + assert "信源" in rejected.json()["error"]["message"] + assert settings.model_dump() == settings_before + assert len(resets) == reset_count + async with SessionLocal() as session: + row = await session.scalar(select(Setting).where(Setting.scope == "global", Setting.key == "model_config")) + assert row.value == stored_before + assert (await session.get(Source, source_id)).default_search_strategy == strategy + + # Supplying a key for the new destination keeps the saved source usable. + replaced = await client.put( + "/api/v1/system/model-config", headers=headers, + json={"jev_endpoint": "https://replacement.example/score", "jev_api_key": "synthetic-new-key"}, + ) + assert replaced.status_code == 200, replaced.text + finally: + async with SessionLocal() as session: + await session.execute(delete(Source).where(Source.id == source_id)) + await session.commit() + + +async def test_stale_source_default_does_not_block_unrelated_settings_or_deleted_sources(jev_config_client): + from sag_api.core.db import SessionLocal + from sag_api.db.models import Source + from sag_api.enums import SourceStatus + + client, headers, _resets = jev_config_client + settings.search_strategy = "vector" + settings.jev_endpoint = None + settings.jev_api_key = None + source_id = uuid4().hex + async with SessionLocal() as session: + session.add(Source(id=source_id, name="Stale source", sag_source_config_id=source_id, + default_search_strategy="sag2")) + await session.commit() + try: + unrelated = await client.put( + "/api/v1/system/model-config", headers=headers, json={"search_top_k": 9}, + ) + assert unrelated.status_code == 200, unrelated.text + async with SessionLocal() as session: + (await session.get(Source, source_id)).status = SourceStatus.DELETING + await session.commit() + draft = await client.put( + "/api/v1/system/model-config", headers=headers, + json={"jev_endpoint": "https://draft.example/score"}, + ) + assert draft.status_code == 200, draft.text + finally: + async with SessionLocal() as session: + await session.execute(delete(Source).where(Source.id == source_id)) + await session.commit() + + @pytest.mark.parametrize( ("relational_provider", "vector_provider", "endpoint", "expected_code"), [ diff --git a/apps/api/tests/test_source_default_strategy.py b/apps/api/tests/test_source_default_strategy.py new file mode 100644 index 00000000..19276d47 --- /dev/null +++ b/apps/api/tests/test_source_default_strategy.py @@ -0,0 +1,219 @@ +"""Per-source default retrieval mode: validation, persistence and resolution order.""" + +from types import SimpleNamespace +from uuid import uuid4 + +import httpx +import pytest + +from sag_api.core.config import Settings, settings +from sag_api.sag import RetrievedSection, SearchOutcome +from sag_api.sag.engine_manager import EngineManager +from sag_api.services.retrieval_service import ( + common_source_default_strategy, + resolve_search_strategy, + retrieve_relevant_sections, +) +from sag_api.tools.builtin import knowledge_search_strategy + + +def configured(**changes) -> Settings: + return Settings(_env_file=None).model_copy(update={ + "jev_endpoint": "https://jev.invalid/score", + "jev_api_key": "synthetic-jev-key", + "sag_vector_provider": "lancedb", + "search_strategy": "multi_es_fast", + **changes, + }) + + +def source(default: str | None, config_id: str = "cfg-1"): + return SimpleNamespace( + id=config_id, name=config_id, sag_source_config_id=config_id, default_search_strategy=default, + ) + + +@pytest.fixture +async def source_client(monkeypatch): + from sag_api.main import app + + async def skip_unrelated_mcp(_factory, _app): + return None + + async def skip_unrelated_universe_refresh(*_args, **_kwargs): + return None + + monkeypatch.setattr("sag_api.runtime._RuntimeFactory.start_mcp", skip_unrelated_mcp) + # Source updates schedule a universe projection job. It keeps writing SQLite + # after the app lifespan ends and races the shared teardown cleanup. + monkeypatch.setattr( + "sag_api.services.universe_service.schedule_universe_refresh", skip_unrelated_universe_refresh, + ) + snapshot = settings.model_dump() + try: + async with app.router.lifespan_context(app): + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://t") as client: + registration = await client.post( + "/api/v1/auth/register", + json={"email": f"source-mode-{uuid4().hex}@t.com", "password": "password123"}, + ) + assert registration.status_code == 201 + client.headers["Authorization"] = f"Bearer {registration.json()['access_token']}" + yield client + finally: + for key, value in snapshot.items(): + setattr(settings, key, value) + + +def test_common_default_requires_every_source_to_agree(): + assert common_source_default_strategy([]) is None + assert common_source_default_strategy([source("sag2"), source("sag2", "cfg-2")]) == "sag2" + assert common_source_default_strategy([source("sag2"), source(None, "cfg-2")]) is None + assert common_source_default_strategy([source("sag2"), source("vector", "cfg-2")]) is None + # Legacy aliases normalize before comparison. + assert common_source_default_strategy([source("atomic"), source("multi", "cfg-2")]) == "multi" + + +def test_resolution_order_request_persona_source_global(): + configuration = configured(search_strategy="vector") + scoped = [source("sag2"), source("sag2", "cfg-2")] + + def resolved(**kwargs): + result = resolve_search_strategy(configuration=configuration, **kwargs) + return result.strategy, result.origin + + assert resolved(requested="multi", persona_strategy="multi_jev", sources=scoped) == ("multi", "request") + assert resolved(persona_strategy="multi_jev", sources=scoped) == ("multi_jev", "persona") + assert resolved(sources=scoped) == ("sag2", "source_default") + assert resolved(sources=[source("sag2"), source(None, "cfg-2")]) == ("vector", "global") + assert resolved() == ("vector", "global") + + +def test_agent_tool_follows_source_default_before_legacy_vector(): + configuration = configured(search_strategy="multi_es_fast") + assert knowledge_search_strategy({}, configuration, [source("sag2")]) == "sag2" + assert knowledge_search_strategy({"search_strategy": "vector"}, configuration, [source("sag2")]) == "vector" + assert knowledge_search_strategy({}, configuration, [source("sag2"), source(None, "cfg-2")]) == "vector" + # A global JEV default still wins over an unknown legacy persona value, as before. + assert knowledge_search_strategy({"search_strategy": "retired"}, configured(search_strategy="sag2"), []) == "sag2" + + +@pytest.mark.asyncio +async def test_retrieval_reports_source_default_origin(monkeypatch): + from sag_api.services import retrieval_service + + captured = [] + + class Engine: + _settings = configured(search_strategy="vector") + + async def search_many(self, targets, query, **kwargs): + captured.append(kwargs["strategy"]) + return SearchOutcome(query=query, sections=[RetrievedSection( + chunk_id="c1", heading="h", content="evidence", score=0.9, source_config_id="cfg-1", source_id="d1", + metadata={"score_source": "jev"}, + )], stats={"effective_strategy": "sag2"}) + + async def published(sources, **_kwargs): + return {s.sag_source_config_id: ("d1",) for s in sources} + + monkeypatch.setattr(retrieval_service, "published_document_inputs", published) + outcome = await retrieve_relevant_sections(Engine(), [source("sag2")], "q", top_k=3) + assert captured == ["sag2"] + assert outcome.stats["requested_strategy"] == "sag2" + assert outcome.stats["strategy_origin"] == "source_default" + + outcome = await retrieve_relevant_sections(Engine(), [source("sag2")], "q", strategy="multi_jev", top_k=3) + assert captured[-1] == "multi_jev" + assert outcome.stats["strategy_origin"] == "request" + + +async def test_source_default_mode_is_validated_persisted_and_clearable(source_client, monkeypatch): + client = source_client + monkeypatch.setattr(settings, "sag_vector_provider", "lancedb") + monkeypatch.setattr(settings, "jev_endpoint", "https://jev.example/score") + monkeypatch.setattr(settings, "jev_api_key", None) + before = {item["id"] for item in (await client.get("/api/v1/sources")).json()} + + # Paid mode without a key is rejected before any row is written. + rejected = await client.post("/api/v1/sources", json={"name": "SAG2 库", "default_search_strategy": "sag2"}) + assert rejected.status_code == 400, rejected.text + assert rejected.json()["error"]["code"] == "jev_api_key_missing" + assert {item["id"] for item in (await client.get("/api/v1/sources")).json()} == before + + unknown = await client.post("/api/v1/sources", json={"name": "x", "default_search_strategy": "nope"}) + assert unknown.status_code == 422 + + monkeypatch.setattr(settings, "jev_api_key", "synthetic-jev-key") + created = await client.post("/api/v1/sources", json={"name": "SAG2 库", "default_search_strategy": "sag2"}) + assert created.status_code == 201, created.text + body = created.json() + assert body["default_search_strategy"] == "sag2" + source_id = body["id"] + assert (await client.get(f"/api/v1/sources/{source_id}")).json()["default_search_strategy"] == "sag2" + + # Follow-global is the default when the field is omitted. + plain = await client.post("/api/v1/sources", json={"name": "普通库"}) + assert plain.status_code == 201 and plain.json()["default_search_strategy"] is None + + # Updates: a mode the storage cannot serve is rejected; null clears back to global. + monkeypatch.setattr(settings, "sag_vector_provider", "pgvector") + blocked = await client.patch(f"/api/v1/sources/{source_id}", json={"default_search_strategy": "multi_jev"}) + assert blocked.status_code == 400 and blocked.json()["error"]["code"] == "vector_provider_lacks_lexical" + assert (await client.get(f"/api/v1/sources/{source_id}")).json()["default_search_strategy"] == "sag2" + renamed = await client.patch(f"/api/v1/sources/{source_id}", json={"name": "改名"}) + assert renamed.status_code == 200 and renamed.json()["default_search_strategy"] == "sag2" + cleared = await client.patch(f"/api/v1/sources/{source_id}", json={"default_search_strategy": None}) + assert cleared.status_code == 200, cleared.text + assert cleared.json()["default_search_strategy"] is None + assert cleared.json()["name"] == "改名" + # Sources are left in place: deleting would queue background work that + # races the shared teardown cleanup for the SQLite lock. + + +async def test_global_search_uses_shared_source_default(source_client, monkeypatch): + from sag_api.core.deps import get_engine_manager + from sag_api.main import app + + client = source_client + monkeypatch.setattr(settings, "sag_vector_provider", "lancedb") + monkeypatch.setattr(settings, "search_strategy", "vector") + monkeypatch.setattr(settings, "jev_endpoint", "https://jev.example/score") + monkeypatch.setattr(settings, "jev_api_key", "synthetic-jev-key") + created = await client.post("/api/v1/sources", json={"name": "SAG2 库", "default_search_strategy": "sag2"}) + assert created.status_code == 201, created.text + source_id = created.json()["id"] + seen = [] + + class StubEngine: + _settings = settings + + async def search_many(self, targets, query, **kwargs): + seen.append(kwargs.get("strategy")) + return SearchOutcome(query=query, sections=[], stats={"effective_strategy": kwargs.get("strategy")}) + + async def grep_chunks(self, *args, **kwargs): + return [] + + app.dependency_overrides[get_engine_manager] = lambda: StubEngine() + try: + scoped = await client.post("/api/v1/search", json={"query": "q", "source_ids": [source_id]}) + assert scoped.status_code == 200, scoped.text + assert seen[-1] == "sag2" + assert scoped.json()["stats"]["strategy_origin"] == "source_default" + + explicit = await client.post( + "/api/v1/search", json={"query": "q", "source_ids": [source_id], "strategy": "vector"}, + ) + assert explicit.status_code == 200, explicit.text + assert seen[-1] == "vector" + assert explicit.json()["stats"]["strategy_origin"] == "request" + finally: + app.dependency_overrides.pop(get_engine_manager, None) + + +def test_require_strategy_available_matches_capability_report(): + assert EngineManager.require_strategy_available(configured(), "sag2") is None + with pytest.raises(Exception) as error: + EngineManager.require_strategy_available(configured(sag_relational_provider="mysql"), "sag2") + assert getattr(error.value, "code", None) == "sag2_relational_unsupported" diff --git a/apps/web/app/(app)/knowledge/[id]/page.tsx b/apps/web/app/(app)/knowledge/[id]/page.tsx index 0f8aba83..c52962bd 100644 --- a/apps/web/app/(app)/knowledge/[id]/page.tsx +++ b/apps/web/app/(app)/knowledge/[id]/page.tsx @@ -26,6 +26,7 @@ import { FolderImportDialog, type FolderImportDialogHandle, } from "@/components/features/folder-import-dialog"; +import { RetrievalModePill } from "@/components/features/retrieval-mode-pill"; import { RetrievalTestDialog } from "@/components/features/retrieval-test-dialog"; import { SourceIdCopy } from "@/components/features/source-id-copy"; import { SourceGraph } from "@/components/features/source-graph"; @@ -123,9 +124,14 @@ export default function SourceDetailPage() { {source ? ( <> -

- {source.name} -

+
+

+ {source.name} +

+ {source.default_search_strategy && ( + + )} +

{t("sourceStats", { documents: source.document_count, diff --git a/apps/web/components/features/create-source-dialog.tsx b/apps/web/components/features/create-source-dialog.tsx index 4efb3162..9c866b5d 100644 --- a/apps/web/components/features/create-source-dialog.tsx +++ b/apps/web/components/features/create-source-dialog.tsx @@ -36,7 +36,7 @@ export function CreateSourceDialog({ )} - + {t("new")} {t("dialogDescription")} diff --git a/apps/web/components/features/document-deletion.test.tsx b/apps/web/components/features/document-deletion.test.tsx index e2bc21fb..1f83be79 100644 --- a/apps/web/components/features/document-deletion.test.tsx +++ b/apps/web/components/features/document-deletion.test.tsx @@ -12,7 +12,7 @@ import { OctxExportProvider } from "./octx-export-provider"; const source: Source = { id: "source-1", name: "Reports", description: "", source_type: "document", connector_kind: "file_upload", - status: "active", document_count: 0, chunk_count: 0, event_count: 0, + status: "active", default_search_strategy: null, document_count: 0, chunk_count: 0, event_count: 0, created_at: "2026-10-09T00:00:00Z", updated_at: "2026-10-09T00:00:00Z", }; const cleanup: BackgroundJob = { diff --git a/apps/web/components/features/document-processing-progress.test.tsx b/apps/web/components/features/document-processing-progress.test.tsx index a2864b33..f8ca74c6 100644 --- a/apps/web/components/features/document-processing-progress.test.tsx +++ b/apps/web/components/features/document-processing-progress.test.tsx @@ -238,7 +238,7 @@ describe("live document details", () => { let current: Doc = { ...base, status: "paused" }; const source: Source = { id: "source-1", name: "Reports", description: "", source_type: "document", - connector_kind: "file_upload", status: "active", document_count: 1, + connector_kind: "file_upload", status: "active", default_search_strategy: null, document_count: 1, chunk_count: 20, event_count: 0, created_at: base.created_at, updated_at: base.updated_at, }; vi.spyOn(api, "getSource").mockResolvedValue(source); diff --git a/apps/web/components/features/document-restart-confirmation.test.tsx b/apps/web/components/features/document-restart-confirmation.test.tsx index 6ddcb718..223ccfa9 100644 --- a/apps/web/components/features/document-restart-confirmation.test.tsx +++ b/apps/web/components/features/document-restart-confirmation.test.tsx @@ -21,7 +21,7 @@ const paused: Doc = { }; const source: Source = { id: "source-1", name: "Reports", description: "", source_type: "document", connector_kind: "file_upload", - status: "active", document_count: 1, chunk_count: 20, event_count: 4, + status: "active", default_search_strategy: null, document_count: 1, chunk_count: 20, event_count: 4, created_at: paused.created_at, updated_at: paused.updated_at, }; diff --git a/apps/web/components/features/dsh-service-settings.test.tsx b/apps/web/components/features/dsh-service-settings.test.tsx index eefc203b..0aa53ddd 100644 --- a/apps/web/components/features/dsh-service-settings.test.tsx +++ b/apps/web/components/features/dsh-service-settings.test.tsx @@ -42,6 +42,7 @@ const sources: Source[] = [ source_type: "document", connector_kind: "local", status: "active", + default_search_strategy: null, document_count: 0, chunk_count: 0, event_count: 0, diff --git a/apps/web/components/features/edit-source-dialog.test.tsx b/apps/web/components/features/edit-source-dialog.test.tsx new file mode 100644 index 00000000..6cedcea2 --- /dev/null +++ b/apps/web/components/features/edit-source-dialog.test.tsx @@ -0,0 +1,114 @@ +/** @vitest-environment jsdom */ +import * as React from "react"; +import { act } from "react"; +import { createRoot, type Root } from "react-dom/client"; +import { NextIntlClientProvider } from "next-intl"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +import messages from "@/messages/en-US.json"; +import { api } from "@/lib/api"; +import type { Capabilities, Source } from "@/lib/types"; +import { TooltipProvider } from "@/components/ui/tooltip"; +import { EditSourceDialog } from "./edit-source-dialog"; + +const state = vi.hoisted(() => ({ + capabilities: {} as Partial, + refreshCapabilities: vi.fn(async () => {}), +})); +vi.mock("@/components/features/app-shell", () => ({ useApp: () => state })); +vi.mock("sonner", () => ({ toast: { success: vi.fn(), error: vi.fn() } })); +vi.mock("next/link", () => ({ + default: React.forwardRef>( + function Link({ children, href, ...props }, ref) { return {children}; }, + ), +})); + +const source: Source = { + id: "source-1", name: "Manuals", description: "Specs", source_type: "document", connector_kind: "file_upload", + status: "active", default_search_strategy: "multi", document_count: 0, chunk_count: 0, event_count: 0, + created_at: "2026-10-24T00:00:00Z", updated_at: "2026-10-24T00:00:00Z", +}; + +let root: Root; +let container: HTMLDivElement; +let onUpdated: ReturnType void>>; + +beforeEach(() => { + (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + state.capabilities = { search_strategy: "vector", search_strategies: ["vector", "multi_es_fast", "multi", "multi_jev", "sag2"] }; + onUpdated = vi.fn(); + vi.spyOn(api, "updateSource").mockImplementation(async (_id, body) => ({ ...source, ...body }) as Source); + vi.spyOn(api, "getModelConfig").mockResolvedValue({ jev_endpoint: null, jev_model: "jev-latest" } as never); + Object.defineProperties(HTMLElement.prototype, { + hasPointerCapture: { configurable: true, value: () => false }, releasePointerCapture: { configurable: true, value: () => undefined }, + setPointerCapture: { configurable: true, value: () => undefined }, scrollIntoView: { configurable: true, value: () => undefined }, + }); + vi.stubGlobal("ResizeObserver", class { observe() {} unobserve() {} disconnect() {} }); + container = document.createElement("div"); document.body.append(container); root = createRoot(container); +}); +afterEach(async () => { await act(async () => root.unmount()); container.remove(); vi.restoreAllMocks(); vi.unstubAllGlobals(); }); + +function pointerEvent(type: string) { + const event = new MouseEvent(type, { bubbles: true, button: 0 }); + Object.defineProperties(event, { pointerId: { value: 1 }, pointerType: { value: "mouse" } }); + return event; +} +async function openDialog(currentSource: Source = source) { + await act(async () => root.render( + + + , + )); + await act(async () => container.querySelector("button")!.click()); + const dialog = document.body.querySelector('[role="dialog"]')!; + expect(dialog).not.toBeNull(); + return dialog; +} +async function pickMode(testId: string) { + const trigger = document.body.querySelector('[data-testid="retrieval-mode-picker"]')!; + await act(async () => trigger.dispatchEvent(pointerEvent("pointerdown"))); + const option = document.body.querySelector(`[data-testid="${testId}"]`)!; + expect(option, `option ${testId}`).not.toBeNull(); + await act(async () => { option.dispatchEvent(pointerEvent("pointerdown")); option.dispatchEvent(pointerEvent("pointerup")); }); +} + +describe("edit source dialog", () => { + it("preselects the saved default mode without resubmitting it", async () => { + const dialog = await openDialog(); + expect(dialog.textContent).toContain("name, description and default retrieval mode"); + expect(dialog.querySelector('[data-testid="retrieval-mode-picker"]')?.textContent).toContain("Precise"); + await act(async () => dialog.querySelector("form")!.requestSubmit()); + expect(api.updateSource).toHaveBeenCalledWith("source-1", { name: "Manuals", description: "Specs" }); + expect(onUpdated).toHaveBeenCalledWith(expect.objectContaining({ default_search_strategy: "multi" })); + }); + it.each(["sag2", "multi_jev"] as const)("allows metadata edits with an unchanged stale %s default", async (mode) => { + state.capabilities = { + ...state.capabilities, + search_strategies_disabled: { [mode]: { reason: "jev_api_key_missing", message: "Configure JEV" } }, + }; + const currentSource = { ...source, default_search_strategy: mode }; + vi.mocked(api.updateSource).mockImplementation(async (_id, body) => ({ ...currentSource, ...body }) as Source); + const dialog = await openDialog(currentSource); + expect(dialog.querySelector('button[type="submit"]')!.disabled).toBe(false); + await act(async () => dialog.querySelector("form")!.requestSubmit()); + expect(api.updateSource).toHaveBeenCalledWith("source-1", { name: "Manuals", description: "Specs" }); + expect(onUpdated).toHaveBeenCalledWith(expect.objectContaining({ default_search_strategy: mode })); + }); + it("sends null when switching back to the global default", async () => { + const dialog = await openDialog(); + await pickMode("retrieval-mode-global"); + await act(async () => dialog.querySelector("form")!.requestSubmit()); + expect(api.updateSource).toHaveBeenCalledWith("source-1", { name: "Manuals", description: "Specs", default_search_strategy: null }); + }); + it("blocks saving a JEV mode until the key is entered", async () => { + state.capabilities = { + ...state.capabilities, + search_strategies_disabled: { sag2: { reason: "jev_not_configured", message: "Configure JEV" } }, + }; + const dialog = await openDialog(); + await pickMode("retrieval-mode-sag2"); + expect(dialog.querySelector('[data-testid="jev-quick-setup"]')).not.toBeNull(); + expect(dialog.querySelector('button[type="submit"]')!.disabled).toBe(true); + expect(dialog.querySelector('[data-testid="source-form-blocked"]')).not.toBeNull(); + }); +}); diff --git a/apps/web/components/features/edit-source-dialog.tsx b/apps/web/components/features/edit-source-dialog.tsx index 5c8ba6ca..7f3e55ff 100644 --- a/apps/web/components/features/edit-source-dialog.tsx +++ b/apps/web/components/features/edit-source-dialog.tsx @@ -5,7 +5,17 @@ import { Pencil } from "lucide-react"; import { useTranslations } from "next-intl"; import { toast } from "sonner"; +import { useApp } from "@/components/features/app-shell"; +import { useJevQuickSetup } from "@/components/features/jev-quick-setup"; +import { RetrievalModePicker } from "@/components/features/retrieval-mode-picker"; import { api, ApiError } from "@/lib/api"; +import { + DEFAULT_SEARCH_STRATEGY, + getSearchStrategiesDisabled, + isSearchStrategy, + needsJevQuickSetup, + type SearchStrategy, +} from "@/lib/retrieval-config"; import type { Source } from "@/lib/types"; import { cn } from "@/lib/utils"; import { Button } from "@/components/ui/button"; @@ -35,32 +45,66 @@ export function EditSourceDialog({ tooltipSide?: React.ComponentProps["side"]; }) { const t = useTranslations("SourceForm"); + const strategies = useTranslations("SearchStrategies"); + const modes = useTranslations("RetrievalModes"); + const { capabilities } = useApp(); const [open, setOpen] = React.useState(false); const [name, setName] = React.useState(source.name); const [description, setDescription] = React.useState(source.description ?? ""); + const [mode, setMode] = React.useState( + source.default_search_strategy ?? null, + ); const [loading, setLoading] = React.useState(false); + const [error, setError] = React.useState(null); + + const globalStrategy = isSearchStrategy(capabilities?.search_strategy) + ? capabilities.search_strategy + : DEFAULT_SEARCH_STRATEGY; + const unsupportedMessage = strategies("unsupportedBackend"); + const disabledMap = React.useMemo( + () => getSearchStrategiesDisabled(capabilities, unsupportedMessage), + [capabilities, unsupportedMessage], + ); + const modeChanged = mode !== (source.default_search_strategy ?? null); + const jevSetupNeeded = open && modeChanged && needsJevQuickSetup(mode, disabledMap); + const jevSetup = useJevQuickSetup({ enabled: jevSetupNeeded }); + const jevKeyMissing = jevSetupNeeded && !jevSetup.ready; React.useEffect(() => { if (!open) return; setName(source.name); setDescription(source.description ?? ""); + setMode(source.default_search_strategy ?? null); + setError(null); }, [open, source]); async function submit(e: React.FormEvent) { e.preventDefault(); const cleanName = name.trim(); - if (!cleanName) return; + if (!cleanName || jevKeyMissing) return; setLoading(true); + setError(null); try { + if (jevSetupNeeded) { + try { + await jevSetup.save(); + } catch { + // The quick setup shows the failure next to its fields. + return; + } + } const updated = await api.updateSource(source.id, { name: cleanName, description: description.trim(), + ...(modeChanged ? { default_search_strategy: mode } : {}), }); toast.success(t("updated")); onUpdated?.(updated); setOpen(false); } catch (err) { - toast.error(err instanceof ApiError ? err.message : t("updateFailed")); + const message = err instanceof ApiError ? err.message : t("updateFailed"); + setError(message); + toast.error(message); } finally { setLoading(false); } @@ -85,7 +129,7 @@ export function EditSourceDialog({ {t("edit")} - + {t("edit")} {t("editDescription")} @@ -114,9 +158,32 @@ export function EditSourceDialog({ rows={2} /> + { + setMode(next); + setError(null); + }} + globalStrategy={globalStrategy} + disabledMap={disabledMap} + disabled={loading} + jevSetup={modeChanged ? jevSetup : undefined} + /> + + {error && ( +

+ {error} +

+ )} - - diff --git a/apps/web/components/features/jev-quick-setup.tsx b/apps/web/components/features/jev-quick-setup.tsx new file mode 100644 index 00000000..9b17cd0a --- /dev/null +++ b/apps/web/components/features/jev-quick-setup.tsx @@ -0,0 +1,290 @@ +"use client"; + +import * as React from "react"; +import { FlaskConical, Settings2 } from "lucide-react"; +import Link from "next/link"; +import { useTranslations } from "next-intl"; + +import { useApp } from "@/components/features/app-shell"; +import { Button } from "@/components/ui/button"; +import { Field, FieldLabel } from "@/components/ui/field"; +import { Input } from "@/components/ui/input"; +import { + Select, + SelectContent, + SelectItem, + SelectTrigger, + SelectValue, +} from "@/components/ui/select"; +import { Spinner } from "@/components/ui/spinner"; +import { api, ApiError } from "@/lib/api"; +import { + isValidJevEndpoint, + JEV_DEFAULT_MODEL, + JEV_ENDPOINTS, + JEV_PROVIDER_NAMES, + providerForEndpoint, + type JevProvider, +} from "@/lib/jev-config"; +import { settingsTabHref } from "@/lib/settings-config"; +import type { ModelConfigPatch } from "@/lib/types"; +import { cn } from "@/lib/utils"; + +/** The shared JEV service section inside the knowledge settings tab. */ +export const JEV_SETTINGS_HREF = settingsTabHref("knowledge", "jev"); + +export interface JevQuickSetupState { + provider: JevProvider; + endpoint: string; + apiKey: string; + endpointValid: boolean; + /** Endpoint and key are both usable, so `save()` may run. */ + ready: boolean; + testing: boolean; + saving: boolean; + testResult: { ok: boolean; message: string } | null; + /** Last save failure, shown inline next to the fields. */ + error: string | null; + setProvider: (provider: JevProvider) => void; + setEndpoint: (endpoint: string) => void; + setApiKey: (apiKey: string) => void; + test: () => Promise; + /** + * Persists the shared JEV service (endpoint, model, key) and refreshes + * capabilities so JEV modes stop being reported as disabled. Records the + * failure in `error` and rethrows so the caller can stop its own submit. + */ + save: () => Promise; +} + +/** + * Draft state for configuring the paid JEV service without leaving a source + * dialog. `enabled` is true while a JEV mode is selected but blocked only by a + * missing configuration; the first time that happens a saved endpoint and + * model are read back so a custom deployment is not silently replaced by the + * 302.AI preset. + */ +export function useJevQuickSetup({ enabled }: { enabled: boolean }): JevQuickSetupState { + const t = useTranslations("RetrievalModes"); + const { refreshCapabilities } = useApp(); + const [provider, setProviderState] = React.useState("302"); + const [endpoint, setEndpointState] = React.useState(JEV_ENDPOINTS["302"]); + const [model, setModel] = React.useState(JEV_DEFAULT_MODEL); + const [apiKey, setApiKeyState] = React.useState(""); + const [testing, setTesting] = React.useState(false); + const [saving, setSaving] = React.useState(false); + const [testResult, setTestResult] = React.useState(null); + const [error, setError] = React.useState(null); + const prefilledRef = React.useRef(false); + const dirtyRef = React.useRef(false); + + React.useEffect(() => { + if (!enabled || prefilledRef.current) return; + prefilledRef.current = true; + api.getModelConfig().then((config) => { + if (dirtyRef.current) return; + const savedEndpoint = config.jev_endpoint?.trim(); + if (savedEndpoint) { + setEndpointState(savedEndpoint); + setProviderState(providerForEndpoint(savedEndpoint)); + } + const savedModel = config.jev_model?.trim(); + if (savedModel) setModel(savedModel); + }).catch(() => { + /* The 302.AI preset stays in place when the saved config cannot be read. */ + }); + }, [enabled]); + + const endpointValid = isValidJevEndpoint(endpoint); + const ready = endpointValid && Boolean(apiKey.trim()); + + const patch = React.useCallback((): ModelConfigPatch => ({ + jev_endpoint: endpoint.trim(), + jev_model: model.trim() || JEV_DEFAULT_MODEL, + jev_api_key: apiKey.trim(), + }), [apiKey, endpoint, model]); + + const setProvider = React.useCallback((next: JevProvider) => { + dirtyRef.current = true; + setTestResult(null); + setError(null); + setProviderState(next); + if (next === "custom") return; + setEndpointState(JEV_ENDPOINTS[next]); + setModel(JEV_DEFAULT_MODEL); + }, []); + + const setEndpoint = React.useCallback((next: string) => { + dirtyRef.current = true; + setTestResult(null); + setError(null); + setEndpointState(next); + }, []); + + const setApiKey = React.useCallback((next: string) => { + dirtyRef.current = true; + setTestResult(null); + setError(null); + setApiKeyState(next); + }, []); + + const test = React.useCallback(async () => { + setTesting(true); + setTestResult(null); + try { + setTestResult(await api.testJevModelConfig(patch())); + } catch (cause) { + setTestResult({ + ok: false, + message: cause instanceof ApiError ? cause.message : t("jevTestFailed"), + }); + } finally { + setTesting(false); + } + }, [patch, t]); + + const save = React.useCallback(async () => { + setSaving(true); + setError(null); + try { + await api.saveModelConfig(patch()); + await refreshCapabilities(); + } catch (cause) { + setError(cause instanceof ApiError ? cause.message : t("jevSaveFailed")); + throw cause; + } finally { + setSaving(false); + } + }, [patch, refreshCapabilities, t]); + + return { + provider, + endpoint, + apiKey, + endpointValid, + ready, + testing, + saving, + testResult, + error, + setProvider, + setEndpoint, + setApiKey, + test, + save, + }; +} + +export function JevQuickSetup({ + setup, + idPrefix, + disabled = false, + className, +}: { + setup: JevQuickSetupState; + idPrefix: string; + disabled?: boolean; + className?: string; +}) { + const t = useTranslations("RetrievalModes"); + const providerName = setup.provider === "custom" ? null : JEV_PROVIDER_NAMES[setup.provider]; + const endpointInvalid = !setup.endpointValid; + + return ( +
+
+

{t("jevSetupTitle")}

+

{t("jevSetupDescription")}

+
+
+ + {t("jevProvider")} + + + + {t("jevEndpoint")} + setup.setEndpoint(event.target.value)} + /> + {endpointInvalid && ( +

{t("jevEndpointInvalid")}

+ )} +
+ + {t("jevApiKey")} +
+ setup.setApiKey(event.target.value)} + /> + +
+
+
+ {setup.testResult && ( +

+ {setup.testResult.message} +

+ )} + {setup.error && ( +

+ {setup.error} +

+ )} +

+ {t("jevSharedNote")}{" "} + + + {t("jevOpenSettings")} + +

+
+ ); +} diff --git a/apps/web/components/features/knowledge-config-form.tsx b/apps/web/components/features/knowledge-config-form.tsx index 6d06adc9..809d4fa3 100644 --- a/apps/web/components/features/knowledge-config-form.tsx +++ b/apps/web/components/features/knowledge-config-form.tsx @@ -30,6 +30,12 @@ import { SEARCH_STRATEGIES, type JevScoredStrategy, } from "@/lib/retrieval-config"; +import { + JEV_DEFAULT_MODEL, + JEV_ENDPOINTS, + providerForEndpoint, + type JevProvider, +} from "@/lib/jev-config"; import type { ModelConfig, ModelConfigPatch } from "@/lib/types"; import { Tooltip, @@ -38,12 +44,6 @@ import { TooltipTrigger, } from "@/components/ui/tooltip"; -const JEV_DEFAULT_MODEL = "jev-latest"; -const JEV_ENDPOINTS = { - "302": "https://api.302.ai/typesafeai/v1/systemone", - official: "https://api.typesafe.ai/v1/systemone", -} as const; -type JevProvider = keyof typeof JEV_ENDPOINTS | "custom"; type SavedJevDraft = { endpoint: string; model: string; @@ -52,12 +52,6 @@ type SavedJevDraft = { strategy: ModelConfig["search_strategy"]; }; -function providerForEndpoint(endpoint: string): JevProvider { - if (!endpoint.trim() || endpoint.trim() === JEV_ENDPOINTS["302"]) return "302"; - if (endpoint.trim() === JEV_ENDPOINTS.official) return "official"; - return "custom"; -} - export function KnowledgeConfigForm() { const t = useTranslations("KnowledgeConfig"); const strategies = useTranslations("SearchStrategies"); diff --git a/apps/web/components/features/knowledge-workspace.test.tsx b/apps/web/components/features/knowledge-workspace.test.tsx index 04ec1a16..e47b003a 100644 --- a/apps/web/components/features/knowledge-workspace.test.tsx +++ b/apps/web/components/features/knowledge-workspace.test.tsx @@ -14,6 +14,7 @@ const source: Source = { source_type: "document", connector_kind: "file_upload", status: "active", + default_search_strategy: null, document_count: 2, chunk_count: 2, event_count: 4, diff --git a/apps/web/components/features/retrieval-mode-picker.test.tsx b/apps/web/components/features/retrieval-mode-picker.test.tsx new file mode 100644 index 00000000..e39eddf0 --- /dev/null +++ b/apps/web/components/features/retrieval-mode-picker.test.tsx @@ -0,0 +1,148 @@ +/** @vitest-environment jsdom */ +import * as React from "react"; +import { act } from "react"; +import { createRoot, type Root } from "react-dom/client"; +import { NextIntlClientProvider } from "next-intl"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +import messages from "@/messages/en-US.json"; +import { api } from "@/lib/api"; +import { needsJevQuickSetup, type SearchStrategy, type SearchStrategyDisabledMap } from "@/lib/retrieval-config"; +import { useJevQuickSetup } from "./jev-quick-setup"; +import { RetrievalModePicker } from "./retrieval-mode-picker"; + +vi.mock("next/link", () => ({ + default: React.forwardRef>( + function Link({ children, href, ...props }, ref) { return {children}; }, + ), +})); +vi.mock("@/components/features/app-shell", () => ({ useApp: () => ({ refreshCapabilities: vi.fn() }) })); + +let root: Root; +let container: HTMLDivElement; +const onValueChange = vi.fn<(value: SearchStrategy | null) => void>(); + +beforeEach(() => { + (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + onValueChange.mockClear(); + vi.spyOn(api, "getModelConfig").mockResolvedValue({ jev_endpoint: null, jev_model: "jev-latest" } as never); + Object.defineProperties(HTMLElement.prototype, { + hasPointerCapture: { configurable: true, value: () => false }, releasePointerCapture: { configurable: true, value: () => undefined }, + setPointerCapture: { configurable: true, value: () => undefined }, scrollIntoView: { configurable: true, value: () => undefined }, + }); + vi.stubGlobal("ResizeObserver", class { observe() {} unobserve() {} disconnect() {} }); + container = document.createElement("div"); document.body.append(container); root = createRoot(container); +}); +afterEach(async () => { await act(async () => root.unmount()); container.remove(); vi.restoreAllMocks(); vi.unstubAllGlobals(); }); + +function pointerEvent(type: string) { + const event = new MouseEvent(type, { bubbles: true, button: 0 }); + Object.defineProperties(event, { pointerId: { value: 1 }, pointerType: { value: "mouse" } }); + return event; +} + +function Harness({ value, disabledMap, withJevSetup = false }: { + value: SearchStrategy | null; disabledMap?: SearchStrategyDisabledMap; withJevSetup?: boolean; +}) { + const jevSetup = useJevQuickSetup({ enabled: needsJevQuickSetup(value, disabledMap) }); + return ( + + ); +} + +async function mount(props: React.ComponentProps) { + await act(async () => root.render( + , + )); +} +async function openOptions() { + const trigger = container.querySelector('[data-testid="retrieval-mode-picker"]')!; + await act(async () => trigger.dispatchEvent(pointerEvent("pointerdown"))); + return [...document.body.querySelectorAll('[role="option"]')]; +} +const description = () => container.querySelector('[data-testid="retrieval-mode-description"]')!.textContent ?? ""; + +describe("retrieval mode picker", () => { + it("lists follow-global first with the current default, then every mode with paid badges", async () => { + await mount({ value: null }); + expect(container.querySelector('[data-testid="retrieval-mode-picker"]')?.textContent).toContain("Follow the global default (currently: Fast (vector))"); + const options = await openOptions(); + expect(options.map(option => option.getAttribute("data-testid"))).toEqual([ + "retrieval-mode-global", "retrieval-mode-vector", "retrieval-mode-multi_es_fast", + "retrieval-mode-multi", "retrieval-mode-multi_jev", "retrieval-mode-sag2", + ]); + expect(document.body.querySelector('[data-testid="retrieval-mode-sag2-paid"]')?.textContent).toBe("Paid"); + expect(document.body.querySelector('[data-testid="retrieval-mode-multi_jev-paid"]')?.textContent).toBe("Paid"); + expect(document.body.querySelector('[data-testid="retrieval-mode-vector-paid"]')).toBeNull(); + const sag2 = options.find(option => option.getAttribute("data-testid") === "retrieval-mode-sag2")!; + await act(async () => { sag2.dispatchEvent(pointerEvent("pointerdown")); sag2.dispatchEvent(pointerEvent("pointerup")); }); + expect(onValueChange).toHaveBeenCalledWith("sag2"); + }); + it("reports follow-global as null and describes the global mode", async () => { + await mount({ value: "multi" }); + const global = (await openOptions()).find(option => option.getAttribute("data-testid") === "retrieval-mode-global")!; + await act(async () => { global.dispatchEvent(pointerEvent("pointerdown")); global.dispatchEvent(pointerEvent("pointerup")); }); + expect(onValueChange).toHaveBeenCalledWith(null); + await mount({ value: null }); + expect(description()).toContain("uses whatever default is chosen in Settings"); + expect(description()).toContain("Current global default: Fast (vector)"); + expect(description()).toContain("Finds the passages closest in meaning"); + }); + it("shows a plain-language summary, when to use it and the paid note for the selected mode", async () => { + await mount({ value: "sag2" }); + expect(description()).toContain("searches the original text over several rounds"); + expect(description()).toContain("Higher usage per search, billed by volume"); + expect(container.querySelector('[data-testid="retrieval-mode-paid-note"]')?.textContent).toBe("Paid service · needs a JEV API key"); + await mount({ value: "vector" }); + expect(description()).toContain("Fastest and cheapest"); + expect(container.querySelector('[data-testid="retrieval-mode-paid-note"]')).toBeNull(); + }); + it("disables modes the deployment cannot serve and shows the reason, but keeps key-only blockers selectable", async () => { + await mount({ + value: null, + disabledMap: { + multi_jev: { reason: "vector_provider_lacks_lexical", message: "Needs lexical search" }, + sag2: { reason: "jev_api_key_missing", message: "Add a JEV API key" }, + }, + }); + const options = await openOptions(); + const multiJev = options.find(option => option.getAttribute("data-testid") === "retrieval-mode-multi_jev")!; + const sag2 = options.find(option => option.getAttribute("data-testid") === "retrieval-mode-sag2")!; + expect(multiJev.getAttribute("aria-disabled")).toBe("true"); + expect(multiJev.textContent).toContain("Unavailable"); + expect(multiJev.textContent).toContain("Needs lexical search"); + expect(sag2.getAttribute("aria-disabled")).not.toBe("true"); + expect(sag2.textContent).toContain("Key needed"); + expect(sag2.textContent).not.toContain("Add a JEV API key"); + }); + it.each(["jev_not_configured", "jev_api_key_missing"])("renders the inline JEV setup for %s", async reason => { + await mount({ value: "sag2", withJevSetup: true, disabledMap: { sag2: { reason, message: "Add a JEV API key" } } }); + const setup = container.querySelector('[data-testid="jev-quick-setup"]')!; + expect(setup).not.toBeNull(); + expect(setup.textContent).toContain("Set up the JEV service first"); + expect(setup.textContent).toContain("Settings → Knowledge → JEV reranking service"); + expect(container.querySelector("#mode-jev-endpoint")!.value).toBe("https://api.302.ai/typesafeai/v1/systemone"); + expect(container.querySelector("#mode-jev-endpoint")!.readOnly).toBe(true); + expect(container.querySelector("#mode-jev-api-key")!.type).toBe("password"); + expect(container.querySelector('[data-testid="jev-quick-setup-settings"]')!.getAttribute("href")).toBe("/settings?tab=knowledge§ion=jev"); + expect(container.querySelector('[data-testid="jev-quick-setup-test"]')!.disabled).toBe(true); + }); + it.each([ + ["sag2" as const, "sag2_relational_unsupported"], + ["multi_jev" as const, "vector_provider_lacks_lexical"], + ["sag2" as const, "unsupported_backend"], + ])("hides the inline setup for %s blocked by %s", async (value, reason) => { + await mount({ value, withJevSetup: true, disabledMap: { [value]: { reason, message: "Not here" } } }); + expect(container.querySelector('[data-testid="jev-quick-setup"]')).toBeNull(); + expect(description()).toContain("Not here"); + }); + it("hides the inline setup for non-JEV modes and when the service is already configured", async () => { + await mount({ value: "multi", withJevSetup: true, disabledMap: { sag2: { reason: "jev_api_key_missing", message: "Add a key" } } }); + expect(container.querySelector('[data-testid="jev-quick-setup"]')).toBeNull(); + await mount({ value: "sag2", withJevSetup: true }); + expect(container.querySelector('[data-testid="jev-quick-setup"]')).toBeNull(); + }); +}); diff --git a/apps/web/components/features/retrieval-mode-picker.tsx b/apps/web/components/features/retrieval-mode-picker.tsx new file mode 100644 index 00000000..277cb678 --- /dev/null +++ b/apps/web/components/features/retrieval-mode-picker.tsx @@ -0,0 +1,157 @@ +"use client"; + +import * as React from "react"; +import { useTranslations } from "next-intl"; + +import { JevQuickSetup, type JevQuickSetupState } from "@/components/features/jev-quick-setup"; +import { Field, FieldLabel } from "@/components/ui/field"; +import { + Select, + SelectContent, + SelectItem, + SelectSeparator, + SelectTrigger, + SelectValue, +} from "@/components/ui/select"; +import { + getSearchStrategy, + isJevConfigDisabledReason, + isJevScoredStrategy, + needsJevQuickSetup, + SEARCH_STRATEGIES, + SEARCH_STRATEGY_ICONS, + type SearchStrategy, + type SearchStrategyDisabledMap, +} from "@/lib/retrieval-config"; +import { cn } from "@/lib/utils"; + +/** Select value standing in for "no source default; follow the global setting". */ +export const FOLLOW_GLOBAL_VALUE = "__global__"; + +const MODE_COPY = { + vector: { summary: "vectorSummary", whenToUse: "vectorWhenToUse" }, + multi_es_fast: { summary: "multiEsFastSummary", whenToUse: "multiEsFastWhenToUse" }, + multi: { summary: "multiSummary", whenToUse: "multiWhenToUse" }, + multi_jev: { summary: "multiJevSummary", whenToUse: "multiJevWhenToUse" }, + sag2: { summary: "sag2Summary", whenToUse: "sag2WhenToUse" }, +} as const satisfies Record; + +const badgeClassName = + "rounded bg-muted px-1 py-0.5 text-[10px] font-normal leading-none text-muted-foreground"; + +export function RetrievalModePicker({ + id, + value, + onValueChange, + globalStrategy, + disabledMap, + disabled = false, + jevSetup, +}: { + id: string; + /** `null` follows the global default. */ + value: SearchStrategy | null; + onValueChange: (value: SearchStrategy | null) => void; + globalStrategy: SearchStrategy; + /** `capabilities.search_strategies_disabled`, normalised by `getSearchStrategiesDisabled`. */ + disabledMap?: SearchStrategyDisabledMap; + disabled?: boolean; + /** + * Inline JEV service setup. Rendered under the description only while the + * selected mode is JEV-scored and blocked solely by a missing configuration. + */ + jevSetup?: JevQuickSetupState; +}) { + const t = useTranslations("RetrievalModes"); + const strategies = useTranslations("SearchStrategies"); + const globalMode = getSearchStrategy(globalStrategy); + const globalLabel = strategies(globalMode.labelKey); + const selected = value ? getSearchStrategy(value) : null; + const selectedInfo = selected ? disabledMap?.[selected.value] : undefined; + const selectedUnavailable = Boolean(selectedInfo) && !isJevConfigDisabledReason(selectedInfo?.reason); + const showJevSetup = jevSetup !== undefined && needsJevQuickSetup(value, disabledMap); + const describedMode = selected ?? globalMode; + + return ( + + {t("label")} + + +
+ {!selected && ( + <> +

{t("followGlobalDescription")}

+

{t("globalModeLead", { label: globalLabel })}

+ + )} +

{t(MODE_COPY[describedMode.value].summary)}

+

{t(MODE_COPY[describedMode.value].whenToUse)}

+ {isJevScoredStrategy(describedMode.value) && ( +

+ {t("paidNeedsKey")} +

+ )} + {selectedUnavailable && selectedInfo && ( +

{selectedInfo.message}

+ )} +
+ + {showJevSetup && jevSetup && ( + + )} +
+ ); +} diff --git a/apps/web/components/features/retrieval-mode-pill.tsx b/apps/web/components/features/retrieval-mode-pill.tsx new file mode 100644 index 00000000..994156d8 --- /dev/null +++ b/apps/web/components/features/retrieval-mode-pill.tsx @@ -0,0 +1,51 @@ +"use client"; + +import { useTranslations } from "next-intl"; + +import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"; +import { + getSearchStrategy, + SEARCH_STRATEGY_ICONS, + type SearchStrategy, +} from "@/lib/retrieval-config"; +import { cn } from "@/lib/utils"; + +/** Compact "default retrieval mode" marker shown next to a source's name. */ +export function RetrievalModePill({ + strategy, + className, + tooltipSide = "bottom", +}: { + strategy: SearchStrategy; + className?: string; + tooltipSide?: React.ComponentProps["side"]; +}) { + const t = useTranslations("RetrievalModes"); + const strategies = useTranslations("SearchStrategies"); + const mode = getSearchStrategy(strategy); + const Icon = SEARCH_STRATEGY_ICONS[mode.value]; + const label = strategies(mode.labelKey); + const tooltip = t("pillTooltip", { label }); + + return ( + + + + + {label} + + + + {tooltip} + + + ); +} diff --git a/apps/web/components/features/search-strategy-control.test.tsx b/apps/web/components/features/search-strategy-control.test.tsx index 0f903311..960ddd12 100644 --- a/apps/web/components/features/search-strategy-control.test.tsx +++ b/apps/web/components/features/search-strategy-control.test.tsx @@ -35,10 +35,10 @@ function pointerEvent(type: string) { Object.defineProperties(event, { pointerId: { value: 1 }, pointerType: { value: "mouse" } }); return event; } -async function open(disabledMap?: SearchStrategyDisabledMap, value: SearchStrategy = "vector") { +async function open(disabledMap?: SearchStrategyDisabledMap, value: SearchStrategy = "vector", hint?: string) { await act(async () => root.render( - + , )); const trigger = container.querySelector('[data-testid="search-strategy"]')!; @@ -60,6 +60,14 @@ describe("search strategy dropdown", () => { expect(item(items, "SAG2 evidence retrieval").textContent).toContain("BM25 recall scored over several JEV rounds"); expect(document.body.querySelector('[data-testid$="-settings"]')).toBeNull(); }); + it("shows where the current mode came from when a hint is given", async () => { + await open(undefined, "sag2", "Source default"); + const hint = container.querySelector('[data-testid="search-strategy-hint"]'); + expect(hint?.textContent).toContain("Source default"); + expect(document.body.querySelector('[role="menu"]')?.textContent).toContain("Source default"); + await open(undefined, "sag2"); + expect(container.querySelector('[data-testid="search-strategy-hint"]')).toBeNull(); + }); it("selects SAG2 when it is enabled", async () => { const items = await open(); const sag2 = item(items, "SAG2 evidence retrieval"); diff --git a/apps/web/components/features/search-strategy-control.tsx b/apps/web/components/features/search-strategy-control.tsx index 60b4a445..6d08a0d6 100644 --- a/apps/web/components/features/search-strategy-control.tsx +++ b/apps/web/components/features/search-strategy-control.tsx @@ -1,17 +1,9 @@ "use client"; -import { - Check, - ChevronDown, - ScanSearch, - Settings2, - ShieldQuestion, - Sparkles, - Zap, -} from "lucide-react"; +import { Check, ChevronDown, Settings2 } from "lucide-react"; import { useTranslations } from "next-intl"; import Link from "next/link"; -import { Fragment, type ComponentType } from "react"; +import { Fragment } from "react"; import { DropdownMenu, @@ -32,19 +24,12 @@ import { isJevConfigDisabledReason, isJevScoredStrategy, SEARCH_STRATEGIES, + SEARCH_STRATEGY_ICONS, type SearchStrategy, type SearchStrategyDisabledMap, } from "@/lib/retrieval-config"; import { settingsTabHref } from "@/lib/settings-config"; -const STRATEGY_ICONS: Record> = { - vector: Zap, - multi_es_fast: ShieldQuestion, - multi: Sparkles, - multi_jev: Sparkles, - sag2: ScanSearch, -}; - /** The shared JEV service section inside the knowledge settings tab. */ const JEV_SETTINGS_HREF = settingsTabHref("knowledge", "jev"); @@ -56,6 +41,7 @@ export function SearchStrategyControl({ defaultValue, onValueChange, disabledMap, + hint, }: { value: SearchStrategy; defaultValue: SearchStrategy; @@ -65,10 +51,12 @@ export function SearchStrategyControl({ * key 缺失即启用,存在即灰置 + Tooltip 展示 message。 */ disabledMap?: SearchStrategyDisabledMap; + /** Short muted note on where the current value came from (e.g. the scoped source's default). */ + hint?: string; }) { const t = useTranslations("SearchStrategies"); const currentStrategy = getSearchStrategy(value); - const CurrentIcon = STRATEGY_ICONS[currentStrategy.value]; + const CurrentIcon = SEARCH_STRATEGY_ICONS[currentStrategy.value]; return ( @@ -82,15 +70,21 @@ export function SearchStrategyControl({ > {t(currentStrategy.labelKey)} + {hint && ( + + · {hint} + + )} - + {t("mode")} + {hint && {hint}} {SEARCH_STRATEGIES.map((strategy) => { - const Icon = STRATEGY_ICONS[strategy.value]; + const Icon = SEARCH_STRATEGY_ICONS[strategy.value]; const selected = strategy.value === value; const isDefault = strategy.value === defaultValue; const paid = isJevScoredStrategy(strategy.value); diff --git a/apps/web/components/features/search/search-panel.tsx b/apps/web/components/features/search/search-panel.tsx index 4983783d..decd1834 100644 --- a/apps/web/components/features/search/search-panel.tsx +++ b/apps/web/components/features/search/search-panel.tsx @@ -120,6 +120,7 @@ export function SearchPanel({ }: SearchPanelProps) { const t = useTranslations("Search"); const searchStrategies = useTranslations("SearchStrategies"); + const retrievalModes = useTranslations("RetrievalModes"); const search = useSearchWorkspace(); const { capabilities } = useApp(); const ensureSources = search.ensureSources; @@ -269,8 +270,10 @@ export function SearchPanel({ }, [search]); function changeStrategy(value: SearchStrategy) { - if (value === search.strategy) return; + const changed = value !== search.strategy; + // Pin even an unchanged pick so a later scope change no longer overrides it. search.setStrategy(value); + if (!changed) return; const activeQuery = search.query.trim() || search.lastQuery; if ((search.result !== null || search.busy) && activeQuery) { void executeSearch({ @@ -440,6 +443,7 @@ export function SearchPanel({ defaultValue={search.defaultStrategy} onValueChange={changeStrategy} disabledMap={getSearchStrategiesDisabled(capabilities, searchStrategies("unsupportedBackend"))} + hint={search.strategyOrigin === "scope" ? retrievalModes("scopeDefaultHint") : undefined} />
{mentionOpen && ( diff --git a/apps/web/components/features/search/search-provider.tsx b/apps/web/components/features/search/search-provider.tsx index 365ab2ec..eac7f28f 100644 --- a/apps/web/components/features/search/search-provider.tsx +++ b/apps/web/components/features/search/search-provider.tsx @@ -5,7 +5,7 @@ import { useTranslations } from "next-intl"; import { api, ApiError } from "@/lib/api"; import { isSourceDeleting } from "@/lib/source-activity"; -import type { SearchStrategy } from "@/lib/retrieval-config"; +import { getScopeDefaultStrategy, type SearchStrategy } from "@/lib/retrieval-config"; import type { ActivityItem, SearchResponse, Source } from "@/lib/types"; import { activationFromSearch, @@ -31,8 +31,13 @@ export type { SearchPhase, SearchRunIntent } from "@/components/features/search/ export interface SearchScope { id: string; name: string; + /** Carried over from the full source when known, so the scope default resolves before the source list loads. */ + default_search_strategy?: SearchStrategy | null; } +/** Where the strategy shown in the search control came from. */ +export type SearchStrategyOrigin = "pinned" | "scope" | "global"; + export interface SearchRunOptions { query?: string; topK?: number; @@ -49,7 +54,10 @@ interface SearchWorkspaceState extends SearchLifecycleState { query: string; scoped: SearchScope[]; sources: Source[]; + /** The user's explicit pick while `strategyPinned`; otherwise mirrors the global default. */ strategy: SearchStrategy; + /** True once the user picked a strategy in this session; scope defaults no longer override it. */ + strategyPinned: boolean; activity: ActivityItem[] | null; history: string[]; contentView: SearchContentView; @@ -58,6 +66,9 @@ interface SearchWorkspaceState extends SearchLifecycleState { interface SearchWorkspaceContextValue extends SearchWorkspaceState { defaultStrategy: SearchStrategy; + /** Common non-null default of every scoped source, or null when they disagree or nothing is scoped. */ + scopeDefaultStrategy: SearchStrategy | null; + strategyOrigin: SearchStrategyOrigin; canLoadMore: boolean; setQuery: (query: string) => void; setStrategy: (strategy: SearchStrategy) => void; @@ -186,6 +197,7 @@ export function SearchProvider({ committedSearchKey: "", lastQuery: "", strategy: defaultStrategy, + strategyPinned: false, lastStrategy: defaultStrategy, topK: DEFAULT_SEARCH_TOP_K, hasMore: false, @@ -232,11 +244,29 @@ export function SearchProvider({ setState((current) => ({ ...current, strategy: defaultStrategy, + strategyPinned: false, lastStrategy: defaultStrategy, })); } }, [defaultStrategy]); + // Sources scoped through the picker carry their own default; scopes restored + // from a URL only have an id, so fall back to the loaded source list. + const scopeDefaultStrategy = React.useMemo(() => getScopeDefaultStrategy( + state.scoped.map((scope) => state.sources.find((source) => source.id === scope.id) ?? scope), + disabledMap, + ), [disabledMap, state.scoped, state.sources]); + const effectiveStrategy = state.strategyPinned + ? state.strategy + : (scopeDefaultStrategy ?? defaultStrategy); + const strategyOrigin: SearchStrategyOrigin = state.strategyPinned + ? "pinned" + : scopeDefaultStrategy + ? "scope" + : "global"; + const effectiveStrategyRef = React.useRef(effectiveStrategy); + effectiveStrategyRef.current = effectiveStrategy; + const cancel = React.useCallback(() => { const activeRequest = activeRequestRef.current; requestIdRef.current += 1; @@ -346,7 +376,7 @@ export function SearchProvider({ return null; } - const strategy = options.strategy ?? snapshot.strategy; + const strategy = options.strategy ?? effectiveStrategyRef.current; const sourceIds = options.sourceIds ?? (snapshot.scoped.length ? snapshot.scoped.map((source) => source.id) : undefined); const requestedKey = createSearchKey({ query, strategy, sourceIds }); @@ -495,7 +525,7 @@ export function SearchProvider({ }, [clear, t]); const setStrategy = React.useCallback((strategy: SearchStrategy) => { - setState((current) => ({ ...current, strategy })); + setState((current) => ({ ...current, strategy, strategyPinned: true })); }, []); // capabilities 变化后,如果当前选中的策略已被后端标记为不可用, @@ -505,7 +535,7 @@ export function SearchProvider({ setState((current) => { if (!disabledMap[current.strategy]) return current; if (current.strategy === defaultStrategy) return current; - return { ...current, strategy: defaultStrategy }; + return { ...current, strategy: defaultStrategy, strategyPinned: false }; }); }, [disabledMap, defaultStrategy]); @@ -518,7 +548,11 @@ export function SearchProvider({ ...current, scoped: current.scoped.some((item) => item.id === source.id) ? current.scoped.filter((item) => item.id !== source.id) - : [...current.scoped, { id: source.id, name: source.name }], + : [...current.scoped, { + id: source.id, + name: source.name, + default_search_strategy: source.default_search_strategy ?? null, + }], })); }, []); @@ -562,7 +596,7 @@ export function SearchProvider({ const draftSearchKey = createSearchKey({ query: state.query, - strategy: state.strategy, + strategy: effectiveStrategy, sourceIds: state.scoped.map((source) => source.id), }); const canLoadMore = canLoadMoreSearch({ @@ -577,7 +611,10 @@ export function SearchProvider({ const value = React.useMemo( () => ({ ...state, + strategy: effectiveStrategy, defaultStrategy, + scopeDefaultStrategy, + strategyOrigin, canLoadMore, setQuery, setStrategy, @@ -599,6 +636,9 @@ export function SearchProvider({ canLoadMore, clear, defaultStrategy, + effectiveStrategy, + scopeDefaultStrategy, + strategyOrigin, ensureActivity, ensureSources, clearHistory, diff --git a/apps/web/components/features/search/search-scope-default.test.tsx b/apps/web/components/features/search/search-scope-default.test.tsx new file mode 100644 index 00000000..fa1ba28a --- /dev/null +++ b/apps/web/components/features/search/search-scope-default.test.tsx @@ -0,0 +1,126 @@ +/** @vitest-environment jsdom */ +import * as React from "react"; +import { act } from "react"; +import { createRoot } from "react-dom/client"; +import { NextIntlClientProvider } from "next-intl"; +import { afterEach, describe, expect, it, vi } from "vitest"; + +import messages from "@/messages/zh-CN.json"; +import type { SearchStrategy, SearchStrategyDisabledMap } from "@/lib/retrieval-config"; +import type { Source } from "@/lib/types"; +import { SearchProvider, useSearchWorkspace, type SearchScope } from "./search-provider"; + +afterEach(() => { vi.unstubAllGlobals(); }); + +function source(id: string, defaultStrategy: SearchStrategy | null): Source { + return { + id, name: id, description: "", source_type: "document", connector_kind: "file_upload", status: "active", + default_search_strategy: defaultStrategy, document_count: 0, chunk_count: 0, event_count: 0, + created_at: "2026-10-24T00:00:00Z", updated_at: "2026-10-24T00:00:00Z", + }; +} +const sources = [source("a", "sag2"), source("b", "sag2"), source("c", "multi"), source("d", null)]; +const scope = (...ids: string[]): SearchScope[] => ids.map((id) => ({ id, name: id })); + +function Controls({ onReady }: { onReady: (workspace: ReturnType) => void }) { + const workspace = useSearchWorkspace(); + onReady(workspace); + return <> +
{workspace.strategy}
+
{workspace.strategyOrigin}
+
{workspace.scopeDefaultStrategy ?? "none"}
+ ; +} + +async function harness(disabledMap?: SearchStrategyDisabledMap) { + (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + const requests: Array> = []; + vi.stubGlobal("fetch", async (url: RequestInfo | URL, options?: RequestInit) => { + if (String(url).endsWith("/sources")) return Response.json(sources); + requests.push(JSON.parse(String(options?.body))); + return Response.json({ error: { code: "boom", message: "stopped" } }, { status: 500 }); + }); + let workspace!: ReturnType; + const container = document.createElement("div"); + document.body.append(container); + const root = createRoot(container); + await act(async () => root.render( + + { workspace = value; }} /> + + )); + const read = (id: string) => container.querySelector(`#${id}`)?.textContent; + return { + requests, + read, + get workspace() { return workspace; }, + act: (callback: () => unknown) => act(async () => { await callback(); }), + cleanup: async () => { await act(async () => root.unmount()); container.remove(); }, + }; +} + +describe("search scope default strategy", () => { + it("follows the shared default of the scoped sources once they are loaded", async () => { + const h = await harness(); + try { + expect(h.read("strategy")).toBe("vector"); + expect(h.read("origin")).toBe("global"); + await h.act(() => h.workspace.setScope(scope("a", "b"))); + // Scopes restored by id alone resolve only after the source list arrives. + expect(h.read("origin")).toBe("global"); + await h.act(() => h.workspace.ensureSources()); + expect(h.read("strategy")).toBe("sag2"); + expect(h.read("origin")).toBe("scope"); + expect(h.read("scope-default")).toBe("sag2"); + await h.act(() => h.workspace.setScope(scope("a", "c"))); + expect(h.read("strategy")).toBe("vector"); + expect(h.read("origin")).toBe("global"); + await h.act(() => h.workspace.setScope(scope("a", "d"))); + expect(h.read("origin")).toBe("global"); + await h.act(() => h.workspace.setScope([])); + expect(h.read("origin")).toBe("global"); + } finally { await h.cleanup(); } + }); + it("uses the default carried by a toggled source before the list loads", async () => { + const h = await harness(); + try { + await h.act(() => h.workspace.toggleSource(sources[2])); + expect(h.read("strategy")).toBe("multi"); + expect(h.read("origin")).toBe("scope"); + } finally { await h.cleanup(); } + }); + it("ignores a scope default the deployment can no longer serve", async () => { + const h = await harness({ sag2: { reason: "jev_api_key_missing", message: "Add a key" } }); + try { + await h.act(() => h.workspace.toggleSource(sources[0])); + expect(h.read("strategy")).toBe("vector"); + expect(h.read("origin")).toBe("global"); + } finally { await h.cleanup(); } + }); + it("keeps an explicit pick across scope changes and sends it with the request", async () => { + const h = await harness(); + try { + await h.act(() => h.workspace.ensureSources()); + await h.act(() => h.workspace.setScope(scope("a", "b"))); + expect(h.read("strategy")).toBe("sag2"); + await h.act(() => h.workspace.setStrategy("multi_es_fast")); + expect(h.read("strategy")).toBe("multi_es_fast"); + expect(h.read("origin")).toBe("pinned"); + await h.act(() => h.workspace.setScope(scope("a"))); + expect(h.read("strategy")).toBe("multi_es_fast"); + expect(h.read("origin")).toBe("pinned"); + await h.act(() => h.workspace.run({ query: "question" }).catch(() => {})); + expect(h.requests).toEqual([expect.objectContaining({ strategy: "multi_es_fast", source_ids: ["a"] })]); + } finally { await h.cleanup(); } + }); + it("runs with the scope default when nothing is pinned", async () => { + const h = await harness(); + try { + await h.act(() => h.workspace.ensureSources()); + await h.act(() => h.workspace.setScope(scope("b"))); + await h.act(() => h.workspace.run({ query: "question" }).catch(() => {})); + expect(h.requests).toEqual([expect.objectContaining({ strategy: "sag2", source_ids: ["b"] })]); + expect(h.read("origin")).toBe("scope"); + } finally { await h.cleanup(); } + }); +}); diff --git a/apps/web/components/features/source-card.test.tsx b/apps/web/components/features/source-card.test.tsx index 4c5e423c..cab5328b 100644 --- a/apps/web/components/features/source-card.test.tsx +++ b/apps/web/components/features/source-card.test.tsx @@ -16,6 +16,7 @@ const source: Source = { source_type: "document", connector_kind: "file_upload", status: "active", + default_search_strategy: null, document_count: 2, chunk_count: 2, event_count: 4, @@ -23,21 +24,25 @@ const source: Source = { updated_at: "2026-07-27T12:00:00Z", }; +function render(value: Source) { + return renderToStaticMarkup( + + + + + + + , + ); +} + describe("source card", () => { it("exposes an always-visible source id control outside its navigation link", () => { - const html = renderToStaticMarkup( - - - - - - - , - ); + const html = render(source); const navigationEnd = html.indexOf(""); const copyButton = html.indexOf('aria-label="复制信源 ID"'); @@ -49,4 +54,16 @@ describe("source card", () => { expect(navigationEnd).toBeGreaterThanOrEqual(0); expect(copyButton).toBeGreaterThan(navigationEnd); }); + + it("shows a default retrieval mode pill only when the source sets one", () => { + expect(render(source)).not.toContain('data-testid="source-default-mode"'); + expect(render({ ...source, default_search_strategy: undefined } as unknown as Source)) + .not.toContain('data-testid="source-default-mode"'); + + const html = render({ ...source, default_search_strategy: "sag2" }); + expect(html).toContain('data-testid="source-default-mode"'); + expect(html).toContain('data-strategy="sag2"'); + expect(html).toContain("SAG2 证据检索"); + expect(html).toContain('aria-label="默认检索模式:SAG2 证据检索;搜索和问答时仍可临时切换"'); + }); }); diff --git a/apps/web/components/features/source-card.tsx b/apps/web/components/features/source-card.tsx index 5f5b1a7c..3767e84a 100644 --- a/apps/web/components/features/source-card.tsx +++ b/apps/web/components/features/source-card.tsx @@ -11,6 +11,7 @@ import { relativeTime } from "@/lib/format"; import { Button } from "@/components/ui/button"; import { ConfirmDialog } from "@/components/ui/confirm-dialog"; import { EditSourceDialog } from "@/components/features/edit-source-dialog"; +import { RetrievalModePill } from "@/components/features/retrieval-mode-pill"; import { useOctxExports } from "@/components/features/octx-export-provider"; import { useApp } from "@/components/features/app-shell"; import { SourceIdCopy } from "@/components/features/source-id-copy"; @@ -27,6 +28,7 @@ export function SourceCard({ source, onChanged }: { source: Source; onChanged?: const { startExport, isSourceExporting } = useOctxExports(); const exportRunning = isSourceExporting(source.id); + const defaultMode = source.default_search_strategy ?? null; const handleExport = React.useCallback( (event: React.MouseEvent) => { @@ -50,10 +52,13 @@ export function SourceCard({ source, onChanged }: { source: Source; onChanged?: }
-
+

{source.name}

+ {defaultMode && ( + + )}

{source.description || t("noDescription")} diff --git a/apps/web/components/features/source-create-form.test.tsx b/apps/web/components/features/source-create-form.test.tsx new file mode 100644 index 00000000..895e85d1 --- /dev/null +++ b/apps/web/components/features/source-create-form.test.tsx @@ -0,0 +1,156 @@ +/** @vitest-environment jsdom */ +import * as React from "react"; +import { act } from "react"; +import { createRoot, type Root } from "react-dom/client"; +import { NextIntlClientProvider } from "next-intl"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +import messages from "@/messages/en-US.json"; +import { api, ApiError } from "@/lib/api"; +import type { Capabilities, Source } from "@/lib/types"; +import { SourceCreateForm } from "./source-create-form"; + +const state = vi.hoisted(() => ({ + capabilities: {} as Partial, + refreshCapabilities: vi.fn(async () => {}), +})); +vi.mock("@/components/features/app-shell", () => ({ useApp: () => state })); +vi.mock("sonner", () => ({ toast: { success: vi.fn(), error: vi.fn() } })); +vi.mock("next/link", () => ({ + default: React.forwardRef>( + function Link({ children, href, ...props }, ref) { return {children}; }, + ), +})); + +const created: Source = { + id: "source-1", name: "Manuals", description: "", source_type: "document", connector_kind: "file_upload", + status: "active", default_search_strategy: null, document_count: 0, chunk_count: 0, event_count: 0, + created_at: "2026-10-24T00:00:00Z", updated_at: "2026-10-24T00:00:00Z", +}; +const keyMissing = { reason: "jev_api_key_missing", message: "Add a JEV API key" }; + +let root: Root; +let container: HTMLDivElement; +let onCreated: ReturnType void>>; + +beforeEach(() => { + (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + state.capabilities = { + search_strategy: "vector", search_strategies: ["vector", "multi_es_fast", "multi", "multi_jev", "sag2"], + search_strategies_disabled: { multi_jev: keyMissing, sag2: keyMissing }, + }; + state.refreshCapabilities.mockClear(); + onCreated = vi.fn(); + vi.spyOn(api, "createSource").mockImplementation(async body => ({ ...created, ...body }) as Source); + vi.spyOn(api, "saveModelConfig").mockResolvedValue({} as never); + vi.spyOn(api, "getModelConfig").mockResolvedValue({ jev_endpoint: null, jev_model: "jev-latest" } as never); + Object.defineProperties(HTMLElement.prototype, { + hasPointerCapture: { configurable: true, value: () => false }, releasePointerCapture: { configurable: true, value: () => undefined }, + setPointerCapture: { configurable: true, value: () => undefined }, scrollIntoView: { configurable: true, value: () => undefined }, + }); + vi.stubGlobal("ResizeObserver", class { observe() {} unobserve() {} disconnect() {} }); + container = document.createElement("div"); document.body.append(container); root = createRoot(container); +}); +afterEach(async () => { await act(async () => root.unmount()); container.remove(); vi.restoreAllMocks(); vi.unstubAllGlobals(); }); + +async function mount() { + await act(async () => root.render( + , + )); +} +function pointerEvent(type: string) { + const event = new MouseEvent(type, { bubbles: true, button: 0 }); + Object.defineProperties(event, { pointerId: { value: 1 }, pointerType: { value: "mouse" } }); + return event; +} +async function type(input: HTMLInputElement | HTMLTextAreaElement, value: string) { + await act(async () => { + Object.getOwnPropertyDescriptor(Object.getPrototypeOf(input), "value")!.set!.call(input, value); + input.dispatchEvent(new Event("input", { bubbles: true })); + }); +} +async function pickMode(testId: string) { + const trigger = container.querySelector('[data-testid="retrieval-mode-picker"]')!; + await act(async () => trigger.dispatchEvent(pointerEvent("pointerdown"))); + const option = document.body.querySelector(`[data-testid="${testId}"]`)!; + expect(option, `option ${testId}`).not.toBeNull(); + await act(async () => { option.dispatchEvent(pointerEvent("pointerdown")); option.dispatchEvent(pointerEvent("pointerup")); }); +} +const nameInput = () => container.querySelector('input[maxlength="200"]')!; +const submitButton = () => container.querySelector('button[type="submit"]')!; +async function submit() { + await act(async () => container.querySelector("form")!.requestSubmit()); +} + +describe("source create form", () => { + it("creates a source that follows the global default without sending a strategy", async () => { + await mount(); + await type(nameInput(), "Manuals"); + expect(container.querySelector('[data-testid="jev-quick-setup"]')).toBeNull(); + await submit(); + expect(api.createSource).toHaveBeenCalledWith({ name: "Manuals", description: "" }); + expect(api.saveModelConfig).not.toHaveBeenCalled(); + expect(onCreated).toHaveBeenCalledWith(expect.objectContaining({ id: "source-1" })); + }); + it("sends the chosen default retrieval mode", async () => { + await mount(); + await type(nameInput(), "Manuals"); + await pickMode("retrieval-mode-multi"); + await submit(); + expect(api.createSource).toHaveBeenCalledWith({ name: "Manuals", description: "", default_search_strategy: "multi" }); + expect(api.saveModelConfig).not.toHaveBeenCalled(); + }); + it("blocks creation until a JEV key is entered, then saves the service before creating", async () => { + await mount(); + await type(nameInput(), "Manuals"); + await pickMode("retrieval-mode-sag2"); + expect(container.querySelector('[data-testid="jev-quick-setup"]')).not.toBeNull(); + expect(submitButton().disabled).toBe(true); + expect(container.querySelector('[data-testid="source-form-blocked"]')?.textContent).toBe("Enter a JEV API key to save this default mode."); + + await type(container.querySelector('input[type="password"]')!, "jev-secret"); + expect(submitButton().disabled).toBe(false); + expect(container.querySelector('[data-testid="source-form-blocked"]')).toBeNull(); + + await submit(); + expect(api.saveModelConfig).toHaveBeenCalledWith({ + jev_endpoint: "https://api.302.ai/typesafeai/v1/systemone", jev_model: "jev-latest", jev_api_key: "jev-secret", + }); + expect(state.refreshCapabilities).toHaveBeenCalledTimes(1); + expect(api.createSource).toHaveBeenCalledWith({ name: "Manuals", description: "", default_search_strategy: "sag2" }); + expect(vi.mocked(api.saveModelConfig).mock.invocationCallOrder[0]).toBeLessThan(vi.mocked(api.createSource).mock.invocationCallOrder[0]); + }); + it("keeps a saved custom endpoint instead of replacing it with the preset", async () => { + vi.mocked(api.getModelConfig).mockResolvedValue({ jev_endpoint: "https://jev.internal/score", jev_model: "jev-pinned" } as never); + await mount(); + await type(nameInput(), "Manuals"); + await pickMode("retrieval-mode-multi_jev"); + const endpoint = container.querySelector('input[type="url"]')!; + expect(endpoint.value).toBe("https://jev.internal/score"); + expect(endpoint.readOnly).toBe(false); + await type(container.querySelector('input[type="password"]')!, "k"); + await submit(); + expect(api.saveModelConfig).toHaveBeenCalledWith({ jev_endpoint: "https://jev.internal/score", jev_model: "jev-pinned", jev_api_key: "k" }); + }); + it("shows a JEV save failure inline and does not create the source", async () => { + vi.mocked(api.saveModelConfig).mockRejectedValue(new ApiError(400, "jev_invalid", "JEV rejected the key")); + await mount(); + await type(nameInput(), "Manuals"); + await pickMode("retrieval-mode-sag2"); + await type(container.querySelector('input[type="password"]')!, "bad"); + await submit(); + expect(container.querySelector('[data-testid="jev-quick-setup-error"]')?.textContent).toBe("JEV rejected the key"); + expect(api.createSource).not.toHaveBeenCalled(); + expect(onCreated).not.toHaveBeenCalled(); + expect(submitButton().disabled).toBe(false); + }); + it("shows a backend rejection of the default mode inline", async () => { + vi.mocked(api.createSource).mockRejectedValue(new ApiError(400, "vector_provider_lacks_lexical", "Lexical search is required")); + await mount(); + await type(nameInput(), "Manuals"); + await pickMode("retrieval-mode-multi"); + await submit(); + expect(container.querySelector('[data-testid="source-form-error"]')?.textContent).toBe("Lexical search is required"); + expect(onCreated).not.toHaveBeenCalled(); + }); +}); diff --git a/apps/web/components/features/source-create-form.tsx b/apps/web/components/features/source-create-form.tsx index 4c4123dc..41b73f23 100644 --- a/apps/web/components/features/source-create-form.tsx +++ b/apps/web/components/features/source-create-form.tsx @@ -4,7 +4,17 @@ import * as React from "react"; import { useTranslations } from "next-intl"; import { toast } from "sonner"; +import { useApp } from "@/components/features/app-shell"; +import { useJevQuickSetup } from "@/components/features/jev-quick-setup"; +import { RetrievalModePicker } from "@/components/features/retrieval-mode-picker"; import { api, ApiError } from "@/lib/api"; +import { + DEFAULT_SEARCH_STRATEGY, + getSearchStrategiesDisabled, + isSearchStrategy, + needsJevQuickSetup, + type SearchStrategy, +} from "@/lib/retrieval-config"; import type { Source } from "@/lib/types"; import { cn } from "@/lib/utils"; import { Button } from "@/components/ui/button"; @@ -22,23 +32,58 @@ export function SourceCreateForm({ compact?: boolean; }) { const t = useTranslations("SourceForm"); + const strategies = useTranslations("SearchStrategies"); + const modes = useTranslations("RetrievalModes"); + const { capabilities } = useApp(); const [name, setName] = React.useState(""); const [description, setDescription] = React.useState(""); + const [mode, setMode] = React.useState(null); const [loading, setLoading] = React.useState(false); + const [error, setError] = React.useState(null); const nameId = React.useId(); const descriptionId = React.useId(); + const modeId = React.useId(); + + const globalStrategy = isSearchStrategy(capabilities?.search_strategy) + ? capabilities.search_strategy + : DEFAULT_SEARCH_STRATEGY; + const unsupportedMessage = strategies("unsupportedBackend"); + const disabledMap = React.useMemo( + () => getSearchStrategiesDisabled(capabilities, unsupportedMessage), + [capabilities, unsupportedMessage], + ); + const jevSetupNeeded = needsJevQuickSetup(mode, disabledMap); + const jevSetup = useJevQuickSetup({ enabled: jevSetupNeeded }); + const jevKeyMissing = jevSetupNeeded && !jevSetup.ready; async function submit(event: React.FormEvent) { event.preventDefault(); + if (jevKeyMissing) return; setLoading(true); + setError(null); try { - const source = await api.createSource({ name: name.trim(), description: description.trim() }); + if (jevSetupNeeded) { + try { + await jevSetup.save(); + } catch { + // The quick setup shows the failure next to its fields. + return; + } + } + const source = await api.createSource({ + name: name.trim(), + description: description.trim(), + ...(mode ? { default_search_strategy: mode } : {}), + }); toast.success(t("created")); onCreated(source); setName(""); setDescription(""); - } catch (error) { - toast.error(error instanceof ApiError ? error.message : t("createFailed")); + setMode(null); + } catch (cause) { + const message = cause instanceof ApiError ? cause.message : t("createFailed"); + setError(message); + toast.error(message); } finally { setLoading(false); } @@ -71,14 +116,37 @@ export function SourceCreateForm({ rows={compact ? 3 : 2} /> + { + setMode(next); + setError(null); + }} + globalStrategy={globalStrategy} + disabledMap={disabledMap} + disabled={loading} + jevSetup={jevSetup} + /> -

+ {error && ( +

+ {error} +

+ )} + +
+ {jevKeyMissing && ( + + {modes("keyRequiredToSubmit")} + + )} {onCancel && ( )} -
diff --git a/apps/web/components/features/source-deletion.test.tsx b/apps/web/components/features/source-deletion.test.tsx index 31c15da4..541194bf 100644 --- a/apps/web/components/features/source-deletion.test.tsx +++ b/apps/web/components/features/source-deletion.test.tsx @@ -18,7 +18,7 @@ import { KnowledgeWorkspace, SourceRow } from "./knowledge-workspace"; const source: Source = { id: "source-1", name: "Reports", description: "", source_type: "document", connector_kind: "file_upload", - status: "active", document_count: 2, chunk_count: 4, event_count: 5, + status: "active", default_search_strategy: null, document_count: 2, chunk_count: 4, event_count: 5, created_at: "2026-10-09T00:00:00Z", updated_at: "2026-10-09T00:00:00Z", }; const deletion: BackgroundJob = { diff --git a/apps/web/lib/api.ts b/apps/web/lib/api.ts index e556093d..0fafb70a 100644 --- a/apps/web/lib/api.ts +++ b/apps/web/lib/api.ts @@ -786,7 +786,12 @@ export const api = { // 信源 listSources: () => request("/api/v1/sources"), getSource: (id: string) => request(`/api/v1/sources/${id}`), - createSource: (b: { name: string; description?: string }) => + createSource: (b: { + name: string; + description?: string; + /** Omit (or send null) to follow the global default retrieval mode. */ + default_search_strategy?: SearchStrategy | null; + }) => request("/api/v1/sources", { method: "POST", body: JSON.stringify(b), diff --git a/apps/web/lib/jev-config.ts b/apps/web/lib/jev-config.ts new file mode 100644 index 00000000..5145fb38 --- /dev/null +++ b/apps/web/lib/jev-config.ts @@ -0,0 +1,37 @@ +/** + * Shared JEV scoring-service presets. The knowledge settings page and the + * inline quick setup inside the source dialogs write the same three fields + * (`jev_endpoint`, `jev_model`, `jev_api_key`), so they must agree on these. + */ +export const JEV_DEFAULT_MODEL = "jev-latest"; + +export const JEV_ENDPOINTS = { + "302": "https://api.302.ai/typesafeai/v1/systemone", + official: "https://api.typesafe.ai/v1/systemone", +} as const; + +export type JevPresetProvider = keyof typeof JEV_ENDPOINTS; +export type JevProvider = JevPresetProvider | "custom"; + +/** Human-readable provider names shown next to the API key field. */ +export const JEV_PROVIDER_NAMES: Record = { + "302": "302.AI", + official: "TypeSafe", +}; + +export function providerForEndpoint(endpoint: string): JevProvider { + const trimmed = endpoint.trim(); + if (!trimmed || trimmed === JEV_ENDPOINTS["302"]) return "302"; + if (trimmed === JEV_ENDPOINTS.official) return "official"; + return "custom"; +} + +/** A complete HTTP(S) URL without embedded credentials, matching the settings form. */ +export function isValidJevEndpoint(endpoint: string): boolean { + try { + const url = new URL(endpoint.trim()); + return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password; + } catch { + return false; + } +} diff --git a/apps/web/lib/retrieval-config.test.ts b/apps/web/lib/retrieval-config.test.ts index a2839801..5a5bcccc 100644 --- a/apps/web/lib/retrieval-config.test.ts +++ b/apps/web/lib/retrieval-config.test.ts @@ -1,11 +1,14 @@ import { describe, expect, it } from "vitest"; import { + getScopeDefaultStrategy, getSearchStrategiesDisabled, isJevConfigDisabledReason, isJevScoredStrategy, isSearchStrategy, JEV_SCORED_STRATEGIES, + needsJevQuickSetup, SEARCH_STRATEGIES, + SEARCH_STRATEGY_ICONS, SEARCH_STRATEGY_REQUIREMENTS, } from "./retrieval-config"; @@ -68,3 +71,35 @@ describe("SAG2 strategy availability", () => { expect(isJevConfigDisabledReason("jev_not_configured")).toBe(true); }); }); + +describe("source default strategy", () => { + it("resolves a scope default only when every scoped source shares the same non-null value", () => { + expect(getScopeDefaultStrategy([])).toBeNull(); + expect(getScopeDefaultStrategy([{ default_search_strategy: "sag2" }])).toBe("sag2"); + expect(getScopeDefaultStrategy([{ default_search_strategy: "sag2" }, { default_search_strategy: "sag2" }])).toBe("sag2"); + expect(getScopeDefaultStrategy([{ default_search_strategy: "sag2" }, { default_search_strategy: "multi" }])).toBeNull(); + expect(getScopeDefaultStrategy([{ default_search_strategy: "sag2" }, { default_search_strategy: null }])).toBeNull(); + expect(getScopeDefaultStrategy([{ default_search_strategy: "multi" }, {}])).toBeNull(); + expect(getScopeDefaultStrategy([{ default_search_strategy: null }, {}])).toBeNull(); + }); + it("ignores a scope default the deployment currently cannot serve", () => { + const blocked = { sag2: { reason: "jev_api_key_missing", message: "Add a key" } }; + expect(getScopeDefaultStrategy([{ default_search_strategy: "sag2" }], blocked)).toBeNull(); + expect(getScopeDefaultStrategy([{ default_search_strategy: "multi" }], blocked)).toBe("multi"); + }); + it("offers the inline JEV setup only for JEV modes blocked by a missing configuration", () => { + const disabled = { + multi_jev: { reason: "vector_provider_lacks_lexical", message: "Lexical" }, + sag2: { reason: "jev_api_key_missing", message: "Key" }, + }; + expect(needsJevQuickSetup("sag2", disabled)).toBe(true); + expect(needsJevQuickSetup("sag2", { sag2: { reason: "jev_not_configured", message: "Configure" } })).toBe(true); + expect(needsJevQuickSetup("multi_jev", disabled)).toBe(false); + expect(needsJevQuickSetup("multi", { multi: { reason: "jev_api_key_missing", message: "Key" } })).toBe(false); + expect(needsJevQuickSetup("sag2", {})).toBe(false); + expect(needsJevQuickSetup(null, disabled)).toBe(false); + }); + it("has an icon for every mode", () => { + for (const strategy of SEARCH_STRATEGIES) expect(SEARCH_STRATEGY_ICONS[strategy.value]).toBeTypeOf("object"); + }); +}); diff --git a/apps/web/lib/retrieval-config.ts b/apps/web/lib/retrieval-config.ts index 09429ca0..e545cafb 100644 --- a/apps/web/lib/retrieval-config.ts +++ b/apps/web/lib/retrieval-config.ts @@ -1,3 +1,11 @@ +import { + ScanSearch, + ShieldQuestion, + Sparkles, + Zap, + type LucideIcon, +} from "lucide-react"; + export const SEARCH_STRATEGIES = [ { value: "vector", @@ -30,6 +38,15 @@ export type SearchStrategy = (typeof SEARCH_STRATEGIES)[number]["value"]; export const DEFAULT_SEARCH_STRATEGY: SearchStrategy = "vector"; +/** One icon per mode, shared by the search control, the source pill and the picker. */ +export const SEARCH_STRATEGY_ICONS: Record = { + vector: Zap, + multi_es_fast: ShieldQuestion, + multi: Sparkles, + multi_jev: Sparkles, + sag2: ScanSearch, +}; + /** * Capability keys a strategy needs from the current vector provider. * 后端 apps/api/sag_api/enums.py::SEARCH_STRATEGY_REQUIREMENTS 是权威来源; @@ -110,3 +127,35 @@ export function getSearchStrategiesDisabled( } return disabled; } + +/** + * True when a JEV-scored mode is only blocked by an incomplete JEV service + * configuration, i.e. the user can unblock it by entering an API key. + */ +export function needsJevQuickSetup( + strategy: SearchStrategy | null | undefined, + disabledMap: SearchStrategyDisabledMap | null | undefined, +): boolean { + return isJevScoredStrategy(strategy) + && isJevConfigDisabledReason(disabledMap?.[strategy]?.reason); +} + +/** + * The default mode shared by every source in a search scope. The backend only + * honours a source default when all scoped sources agree on the same non-null + * value, so the client mirrors that rule. A scope default the deployment can + * no longer serve (present in `disabledMap`) is ignored as well. + */ +export function getScopeDefaultStrategy( + sources: ReadonlyArray<{ default_search_strategy?: SearchStrategy | null }>, + disabledMap?: SearchStrategyDisabledMap | null, +): SearchStrategy | null { + if (sources.length === 0) return null; + const first = sources[0].default_search_strategy ?? null; + if (!first) return null; + for (const source of sources) { + if ((source.default_search_strategy ?? null) !== first) return null; + } + if (disabledMap?.[first]) return null; + return first; +} diff --git a/apps/web/lib/types.ts b/apps/web/lib/types.ts index 801d4d0a..c1c3946e 100644 --- a/apps/web/lib/types.ts +++ b/apps/web/lib/types.ts @@ -71,6 +71,12 @@ export interface Source { connector_kind: string; status: SourceStatus; deletion_job?: BackgroundJob | null; + /** + * Default retrieval mode for search and chat scoped to this source. + * `null` follows the global default; older backends omit the field, which + * callers must treat the same way (`source.default_search_strategy ?? null`). + */ + default_search_strategy: SearchStrategy | null; document_count: number; chunk_count: number; event_count: number; diff --git a/apps/web/messages/en-US.json b/apps/web/messages/en-US.json index 11b51e39..7aa1e6d4 100644 --- a/apps/web/messages/en-US.json +++ b/apps/web/messages/en-US.json @@ -285,11 +285,11 @@ "creating": "Creating…", "create": "Create source", "new": "New source", - "dialogDescription": "Sources hold content. After creation, upload documents and SAG will parse, chunk, and extract events automatically.", + "dialogDescription": "Sources hold content. Name it, pick a default retrieval mode, then upload documents to search and chat.", "updated": "Source updated", "updateFailed": "Failed to update source", "edit": "Edit source", - "editDescription": "Change this source’s name and description.", + "editDescription": "Change this source’s name, description and default retrieval mode.", "saving": "Saving…", "saveChanges": "Save changes" }, @@ -619,6 +619,46 @@ "openSettings": "Open settings", "unsupportedBackend": "This server does not advertise support for this JEV-scored mode. Upgrade the server to use it." }, + "RetrievalModes": { + "label": "Default retrieval mode", + "followGlobal": "Follow the global default (currently: {label})", + "followGlobalDescription": "No separate setting: this source uses whatever default is chosen in Settings and changes along with it.", + "globalModeLead": "Current global default: {label}", + "vectorSummary": "Finds the passages closest in meaning to your question.", + "vectorWhenToUse": "Fastest and cheapest; good for clear material and direct questions.", + "multiEsFastSummary": "Keyword and entity recall plus event hops, with no LLM reranking.", + "multiEsFastWhenToUse": "Balanced speed and quality; good for material full of specific terms, model numbers or names.", + "multiSummary": "Combines entity relationships with LLM reranking.", + "multiWhenToUse": "Most complete results, but slower and uses your generation model; good for complex questions and survey-style material.", + "multiJevSummary": "After recall and graph expansion, the JEV service scores each piece of evidence.", + "multiJevWhenToUse": "Fast and accurate, billed per call; needs a JEV API key and a vector store with lexical search.", + "sag2Summary": "The SAG2 algorithm searches the original text over several rounds, scored by the JEV service; no vector store needed and strong on multi-hop follow-ups.", + "sag2WhenToUse": "Higher usage per search, billed by volume; needs a JEV API key. Document ingestion is unchanged.", + "paid": "Paid", + "paidNeedsKey": "Paid service · needs a JEV API key", + "needsKeyBadge": "Key needed", + "unavailable": "Unavailable", + "switchHint": "You can still switch modes per search or chat.", + "pillTooltip": "Default retrieval mode: {label}. You can still switch modes per search or chat.", + "scopeDefaultHint": "Source default", + "keyRequiredToSubmit": "Enter a JEV API key to save this default mode.", + "jevSetupTitle": "Set up the JEV service first", + "jevSetupDescription": "This mode sends your question and candidate evidence to the JEV service for scoring, which needs an API key.", + "jevProvider": "Provider", + "jevProviderOfficial": "TypeSafe official", + "jevProviderCustom": "Custom", + "jevEndpoint": "Service URL", + "jevEndpointInvalid": "Enter a complete HTTP(S) URL.", + "jevApiKey": "API key", + "jevApiKeyPlaceholder": "Enter your {provider} API key", + "jevApiKeyCustomPlaceholder": "Enter the API key for your JEV service", + "jevTest": "Test connection", + "jevTesting": "Testing…", + "jevTestFailed": "Connection test failed", + "jevSaveFailed": "Failed to save the JEV service", + "jevSharedNote": "Saved once for every JEV mode; change it later under Settings → Knowledge → JEV reranking service.", + "jevOpenSettings": "Open settings" + }, "RetrievalTest": { "failed": "Retrieval failed", "title": "Test retrieval · {source}", diff --git a/apps/web/messages/zh-CN.json b/apps/web/messages/zh-CN.json index 8be0c7fc..e4fbd1b9 100644 --- a/apps/web/messages/zh-CN.json +++ b/apps/web/messages/zh-CN.json @@ -285,11 +285,11 @@ "creating": "创建中…", "create": "创建信源", "new": "新建信源", - "dialogDescription": "信源用来装内容。创建后上传文档,SAG 会自动解析、分块并抽取事件。", + "dialogDescription": "信源用来装内容。起个名字、选好默认检索模式,创建后上传文档即可搜索和问答。", "updated": "信源已更新", "updateFailed": "更新失败", "edit": "修改信源", - "editDescription": "调整这个信息源的名称和描述。", + "editDescription": "调整这个信源的名称、描述和默认检索模式。", "saving": "保存中…", "saveChanges": "保存修改" }, @@ -619,6 +619,46 @@ "openSettings": "去设置", "unsupportedBackend": "当前服务端未声明支持此 JEV 评分模式,请升级服务端后使用。" }, + "RetrievalModes": { + "label": "默认检索模式", + "followGlobal": "跟随全局默认(当前:{label})", + "followGlobalDescription": "不单独设置,和系统设置里的默认模式保持一致;全局默认变化时,这个信源会跟着变。", + "globalModeLead": "当前全局默认:{label}", + "vectorSummary": "按语义相似度直接找最接近的段落。", + "vectorWhenToUse": "响应最快、成本最低;适合资料清晰、问题直接的知识库。", + "multiEsFastSummary": "关键词与实体召回加事件多跳,不调用大模型精排。", + "multiEsFastWhenToUse": "速度与效果均衡;适合有明确名词、型号、人名的资料。", + "multiSummary": "结合实体关系并由大模型精排。", + "multiWhenToUse": "结果最完整但更慢、消耗生成模型;适合复杂问题与综述型资料。", + "multiJevSummary": "召回与图扩展后,由 JEV 服务给每条证据打相关性分。", + "multiJevWhenToUse": "速度快、准确率高,按次计费;需要 JEV API Key 且向量库支持词法检索。", + "sag2Summary": "由 SAG2 算法在原文上多轮检索并由 JEV 服务评分,不依赖向量库,擅长多跳追问。", + "sag2WhenToUse": "每次检索用量较高、按量计费;需要 JEV API Key。文档入库流程不变。", + "paid": "付费", + "paidNeedsKey": "付费服务 · 需要 JEV API Key", + "needsKeyBadge": "待填 Key", + "unavailable": "不可用", + "switchHint": "搜索和问答时仍可临时切换。", + "pillTooltip": "默认检索模式:{label};搜索和问答时仍可临时切换", + "scopeDefaultHint": "信源默认", + "keyRequiredToSubmit": "填写 JEV API Key 后才能保存这个默认模式。", + "jevSetupTitle": "先配置 JEV 服务", + "jevSetupDescription": "这个模式会把问题和候选证据发给 JEV 服务打分,需要一个 API Key。", + "jevProvider": "服务商", + "jevProviderOfficial": "TypeSafe 官方", + "jevProviderCustom": "自定义", + "jevEndpoint": "服务地址", + "jevEndpointInvalid": "请填写完整的 HTTP(S) 地址。", + "jevApiKey": "API Key", + "jevApiKeyPlaceholder": "填写 {provider} API Key", + "jevApiKeyCustomPlaceholder": "填写 JEV 服务的 API Key", + "jevTest": "测试连接", + "jevTesting": "测试中…", + "jevTestFailed": "连接测试失败", + "jevSaveFailed": "JEV 服务保存失败", + "jevSharedNote": "保存后用于全部 JEV 模式,可在 设置 → 知识库 → JEV 精排服务 中修改。", + "jevOpenSettings": "打开设置" + }, "RetrievalTest": { "failed": "检索失败", "title": "检索测试 · {source}", From b71c81c5e61ce6661ce3380f01207fed283ea432 Mon Sep 17 00:00:00 2001 From: luoshuai990529 <58510855+luoshuai990529@users.noreply.github.com> Date: Sun, 25 Oct 2026 01:05:44 +0800 Subject: [PATCH 3/5] =?UTF-8?q?feat(chat):=20=E9=97=AE=E7=AD=94=E5=8F=AF?= =?UTF-8?q?=E4=B8=BA=E5=BD=93=E5=89=8D=E8=BD=AE=E6=AC=A1=E9=80=89=E6=8B=A9?= =?UTF-8?q?=E6=A3=80=E7=B4=A2=E6=A8=A1=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 后端 - `AskRequest` 新增可选 `strategy`,经 `AskPlan` 与工具上下文传入 `search_context`,优先于 Agent 人格与信源默认 - `/ask` 在开始流式生成前校验该模式可用,付费 JEV 模式缺 Key 时返回 400, 不落库用户消息;工具结果 `retrieval_stats.strategy_origin` 标明来源 前端 - 输入框工具栏在「联网」旁加入与探索页一致的模式控件,默认显示将实际 使用的模式并标注来源(人格默认 / 信源默认),生成中禁用 - 用户选择后仅对本面板后续轮次生效;模式不可用被拒绝时在输入框上方 内联提示并提供设置入口;活动时间线显示本轮模式来源 --- CHANGELOG.md | 1 + README-CN.md | 2 +- README.md | 2 +- apps/api/sag_api/api/v1/agents.py | 5 + apps/api/sag_api/schemas/agent.py | 4 +- apps/api/sag_api/services/agent_domain.py | 3 + apps/api/sag_api/services/agent_service.py | 1 + apps/api/sag_api/services/agent_tooling.py | 13 +- apps/api/sag_api/tools/base.py | 4 + apps/api/sag_api/tools/builtin.py | 32 +- .../test_document_operation_restart.py | 6 +- apps/api/tests/test_chat_turn_strategy.py | 170 ++++++++++ apps/api/tests/test_client_access_standard.py | 2 + apps/api/tests/test_jev_transports.py | 5 +- apps/web/components/features/app-shell.tsx | 4 + .../features/chat/conversation-panel.test.tsx | 311 ++++++++++++++++-- .../features/chat/conversation-panel.tsx | 141 +++++++- .../features/retrieval-status.test.tsx | 19 ++ .../components/features/retrieval-status.tsx | 22 +- .../features/search-strategy-control.tsx | 8 +- apps/web/lib/conversation-runtime.test.ts | 19 +- apps/web/lib/conversation-runtime.ts | 6 + apps/web/lib/retrieval-config.test.ts | 8 + apps/web/lib/retrieval-config.ts | 15 + apps/web/lib/sse.test.ts | 13 + apps/web/lib/sse.ts | 3 + apps/web/lib/types.ts | 2 + apps/web/messages/en-US.json | 9 +- apps/web/messages/zh-CN.json | 9 +- 29 files changed, 785 insertions(+), 54 deletions(-) create mode 100644 apps/api/tests/test_chat_turn_strategy.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 3b2a3e73..c17da7ad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ ## Unreleased +- 问答页可为当前轮次选择检索模式:输入框工具栏新增与探索页一致的模式控件,默认显示将实际使用的模式及其来源(人格默认 / 信源默认 / 全局),用户选择后对后续轮次生效;付费 JEV 模式缺少 API Key 时在开始生成前拒绝并给出设置入口。回答的活动时间线显示本轮实际模式与来源。 - 信源可设置「默认检索模式」:创建或编辑信源时选择快速、精确、JEV 精排或 SAG2 证据检索,并以通俗说明与付费提示帮助选择;JEV 模式缺少 API Key 时可在对话框内直接配置。搜索与问答在所选范围内信源一致时自动采用该默认(显式选择与 Agent 人格优先),结果 `stats.strategy_origin` 标明来源。不改变文档入库流程。 - SAG2 只读引擎改在专用事件循环线程运行:大范围检索构建内存语料时不再阻塞 API 事件循环;整次超时会同步取消引擎侧工作。 - 新增可选 SAG2 证据检索模式(`sag2`):接入 `zleap-sag2` 0.1.0,只读直搜 SQLite / PostgreSQL 关系库,BM25 召回后由 JEV 服务多轮评分,不依赖向量库,文档入库后即可检索;与 JEV 精排共用服务配置,失败不回退,首期不支持 MySQL / OceanBase。 diff --git a/README-CN.md b/README-CN.md index 4ab80206..b5fcbc8c 100644 --- a/README-CN.md +++ b/README-CN.md @@ -570,7 +570,7 @@ config = EngineConfig.from_env() 这里列出的是应用/API 策略名称;应用将 `multi` 映射到 Python 引擎的 `full_expand`,将 `multi_es_fast` 映射到 `pruned_expand_rff`,`sag2` 由独立的 `zleap-sag2` 引擎执行。可用性取决于存储能力:`multi_es_fast` 与 `multi_jev` 需要词法检索支持,`sag2` 需要 SQLite 或 PostgreSQL 关系库。 -每个信源可在创建或编辑时设置**默认检索模式**;未设置则跟随全局默认。搜索与问答按“本次显式选择 → Agent 人格 → 范围内信源的共同默认 → 全局默认”解析模式,范围内信源默认不一致时按全局默认处理;结果 `stats.strategy_origin` 标明来源。该设置只影响检索,不改变文档入库流程。 +每个信源可在创建或编辑时设置**默认检索模式**;未设置则跟随全局默认。探索页与问答页的输入框都提供模式控件,可为当前查询或当前轮次临时切换。搜索与问答按“本次显式选择 → Agent 人格 → 范围内信源的共同默认 → 全局默认”解析模式,范围内信源默认不一致时按全局默认处理;结果 `stats.strategy_origin` 标明来源。该设置只影响检索,不改变文档入库流程。 在“设置 → 知识库 → 检索”配置 302.AI、TypeSafe 官方或自定义 JEV 服务(默认 `jev-latest`,独立 API Key),再选择 **JEV 精排** 或 **SAG2 证据检索**;创建信源时选择 JEV 模式也可在对话框内直接完成该配置。JEV 是付费服务:仅保存服务不会启用,选择任一 JEV 模式前必须填写 API Key。JEV 精排默认限时 30 秒、失败报错,可选择粗排降级。 diff --git a/README.md b/README.md index af9e3e9b..30765e46 100644 --- a/README.md +++ b/README.md @@ -568,7 +568,7 @@ Pipeline request and result types are available from `zleap.sag.pipeline`: `Pars These are the application/API strategy names; the application maps `multi` to the Python engine's `full_expand` and `multi_es_fast` to `pruned_expand_rff`, while `sag2` runs on the separate `zleap-sag2` engine. Availability depends on storage capabilities: `multi_es_fast` and `multi_jev` require lexical search support; `sag2` requires a SQLite or PostgreSQL relational store. -Each source can carry a **default retrieval mode**, chosen when the source is created or edited; unset means follow the global default. Search and chat resolve the mode as explicit request → agent persona → the shared default of every source in scope → global default, falling back to the global default when sources in scope disagree; `stats.strategy_origin` reports which one applied. The setting only affects retrieval and never changes document ingestion. +Each source can carry a **default retrieval mode**, chosen when the source is created or edited; unset means follow the global default. Both the explore page and the chat composer offer a mode control for a one-off switch on the current query or turn. Search and chat resolve the mode as explicit request → agent persona → the shared default of every source in scope → global default, falling back to the global default when sources in scope disagree; `stats.strategy_origin` reports which one applied. The setting only affects retrieval and never changes document ingestion. Configure 302.AI, TypeSafe, or a custom JEV service in **Settings → Knowledge → Retrieval** (default model: `jev-latest`, separate API key), then select **JEV reranking** or **SAG2 evidence retrieval**; choosing a JEV mode while creating a source offers the same configuration inline. JEV is a paid service: saving the service alone does not enable it, and an API key is required before either JEV mode can be selected. JEV reranking has a 30-second default deadline; failures return an error unless coarse fallback is enabled. diff --git a/apps/api/sag_api/api/v1/agents.py b/apps/api/sag_api/api/v1/agents.py index f7df15a5..4adebd8d 100644 --- a/apps/api/sag_api/api/v1/agents.py +++ b/apps/api/sag_api/api/v1/agents.py @@ -8,6 +8,7 @@ from sse_starlette.sse import EventSourceResponse from sag_agent import AgentRuntime, EventType, RunHandle +from sag_api.core.config import settings from sag_api.core.db import SessionLocal, get_session from sag_api.core.deps import ( get_agent_runtime, @@ -351,6 +352,9 @@ async def ask( thread = await svc.get_thread(session, agent.id, thread_id) if not llm.configured: raise ConfigurationError("尚未配置 LLM,无法生成回答") + if body.strategy is not None: + # 本轮显式选择的模式必须可用(付费 JEV 模式需已配置 Key);在流开始前就拒绝。 + EngineManager.require_strategy_available(settings, body.strategy) plan = await svc.prepare_ask( session, agent=agent, @@ -359,6 +363,7 @@ async def ask( attachments=body.attachments, source_ids=body.source_ids, llm=llm, + strategy=body.strategy, ) web_enabled = body.effective_web_enabled diff --git a/apps/api/sag_api/schemas/agent.py b/apps/api/sag_api/schemas/agent.py index 6a2d186e..2da3c693 100644 --- a/apps/api/sag_api/schemas/agent.py +++ b/apps/api/sag_api/schemas/agent.py @@ -5,7 +5,7 @@ from pydantic import BaseModel, ConfigDict, Field, model_validator -from sag_api.enums import BindingTargetType, MessageRole, MessageStatus +from sag_api.enums import BindingTargetType, MessageRole, MessageStatus, SearchStrategy class AgentCreate(BaseModel): @@ -99,6 +99,8 @@ class MessagePageOut(BaseModel): class AskRequest(BaseModel): query: str = Field(default="", max_length=4000) + # 本轮检索模式;未传时按 Agent 人格 → 范围内信源共同默认 → 全局默认解析。 + strategy: SearchStrategy | None = None # 图片附件 id 列表(≤4,经 POST /attachments 上传) attachments: list[str] = Field(default_factory=list, max_length=4) # @知识库 范围限定:仅在这些信源内检索(空=默认全部) diff --git a/apps/api/sag_api/services/agent_domain.py b/apps/api/sag_api/services/agent_domain.py index f209c9a8..4194bb4f 100644 --- a/apps/api/sag_api/services/agent_domain.py +++ b/apps/api/sag_api/services/agent_domain.py @@ -472,6 +472,7 @@ class AskPlan: source_ids: list[str] | None = None # @范围:限定循环内检索工具可见的信源 source_scope: list[dict[str, str]] | None = None user_message_id: str | None = None + strategy: str | None = None # 本轮显式选择的检索模式 def build_ask_context( @@ -510,6 +511,7 @@ async def prepare_ask( attachments: list[str] | None = None, source_ids: list[str] | None = None, llm=None, + strategy: str | None = None, ) -> AskPlan: """落库用户消息(含图片附件 meta)、解析历史(超上下文阈值时主动压缩),组装计划。""" resolved: list[dict] = [] @@ -554,6 +556,7 @@ async def prepare_ask( ) plan.user_message_id = user_msg.id plan.source_scope = source_scope + plan.strategy = strategy return plan diff --git a/apps/api/sag_api/services/agent_service.py b/apps/api/sag_api/services/agent_service.py index 66dbc305..f9517871 100644 --- a/apps/api/sag_api/services/agent_service.py +++ b/apps/api/sag_api/services/agent_service.py @@ -75,6 +75,7 @@ async def generate_stream( sources=sources, persona=agent.persona or {}, agent=agent, + requested_strategy=plan.strategy, ) try: diff --git a/apps/api/sag_api/services/agent_tooling.py b/apps/api/sag_api/services/agent_tooling.py index 0e6fdb22..8b0c22cb 100644 --- a/apps/api/sag_api/services/agent_tooling.py +++ b/apps/api/sag_api/services/agent_tooling.py @@ -345,12 +345,17 @@ def _adapt_tool(host_tool, host_context: HostToolContext, citations: list[dict]) timeout_seconds = None if name == "search_context": from sag_api.core.config import MAX_JEV_RANKING_TIMEOUT_SECONDS, settings - from sag_api.tools.builtin import knowledge_search_strategy + from sag_api.tools.builtin import knowledge_search_strategy, knowledge_search_strategy_origin configuration = getattr(host_context.engine_manager, "_settings", settings) - strategy = knowledge_search_strategy(host_context.persona, configuration, host_context.sources) - # Keep this run's mode stable while the model prepares the tool call. - host_context = replace(host_context, persona={**host_context.persona, "search_strategy": strategy}) + strategy = knowledge_search_strategy( + host_context.persona, configuration, host_context.sources, host_context.requested_strategy, + ) + # Freeze execution and provenance together without rewriting the persona. + origin = knowledge_search_strategy_origin( + host_context.persona, host_context.sources, host_context.requested_strategy, + ) + host_context = replace(host_context, search_strategy_snapshot=(strategy, origin)) if strategy == "multi_jev": source_count = min(len(host_context.sources), configuration.search_source_candidate_limit) waves = max(1, ceil(source_count / configuration.search_source_concurrency)) diff --git a/apps/api/sag_api/tools/base.py b/apps/api/sag_api/tools/base.py index ecb0651f..52e44b14 100644 --- a/apps/api/sag_api/tools/base.py +++ b/apps/api/sag_api/tools/base.py @@ -44,8 +44,12 @@ class ToolContext: sources: list[Source] = field(default_factory=list) persona: dict[str, Any] = field(default_factory=dict) agent: Agent | None = None + # 本轮显式选择的检索模式;优先于人格与信源默认。 + requested_strategy: str | None = None # 全局证据编号偏移:循环在每次派发前设置,保证 [n] 跨轮递增不重号 citation_offset: int = 0 + # 工具准备时固定的模式与来源,不修改用户的人格配置。 + search_strategy_snapshot: tuple[str, str] | None = None @dataclass diff --git a/apps/api/sag_api/tools/builtin.py b/apps/api/sag_api/tools/builtin.py index cf10c280..27d03420 100644 --- a/apps/api/sag_api/tools/builtin.py +++ b/apps/api/sag_api/tools/builtin.py @@ -80,8 +80,12 @@ def _events_by_section(events: list | None) -> dict[tuple[str, str], list]: return grouped -def knowledge_search_strategy(persona: dict[str, Any], configuration: Any = settings, sources=()) -> str: - """Persona choice → shared source default → legacy default (vector unless a JEV mode is global).""" +def knowledge_search_strategy( + persona: dict[str, Any], configuration: Any = settings, sources=(), requested: str | None = None, +) -> str: + """Explicit turn choice → persona → shared source default → legacy default (vector unless a JEV mode is global).""" + if requested: + return requested configured = normalize_search_strategy(configuration.search_strategy) default = configured if configured in JEV_SCORED_STRATEGIES else "vector" value = persona.get("search_strategy") or common_source_default_strategy(sources) or default @@ -96,6 +100,19 @@ def knowledge_search_strategy(persona: dict[str, Any], configuration: Any = sett return value +def knowledge_search_strategy_origin( + persona: dict[str, Any], sources=(), requested: str | None = None, +) -> str: + """Which input decided ``knowledge_search_strategy``; reported to the UI as ``strategy_origin``.""" + if requested: + return "request" + if persona.get("search_strategy"): + return "persona" + if common_source_default_strategy(sources): + return "source_default" + return "global" + + def _format_sections(sections: list, offset: int = 0, events: list | None = None) -> str: if not sections: return "(无相关资料)" @@ -250,7 +267,13 @@ async def invoke(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult: if not query or not ctx.sources: return ToolResult(content="(无相关资料)", citations=[], data={"section_count": 0}) persona = ctx.persona or {} - strategy = knowledge_search_strategy(persona, getattr(ctx.engine_manager, "_settings", settings), ctx.sources) + if ctx.search_strategy_snapshot is not None: + strategy, strategy_origin = ctx.search_strategy_snapshot + else: + strategy = knowledge_search_strategy( + persona, getattr(ctx.engine_manager, "_settings", settings), ctx.sources, ctx.requested_strategy, + ) + strategy_origin = knowledge_search_strategy_origin(persona, ctx.sources, ctx.requested_strategy) top_k = args.get("top_k") or persona.get("top_k") limit = max(1, min(int(top_k or 8), 50)) source_refs = {s.sag_source_config_id: {"id": s.id, "name": s.name} for s in ctx.sources} @@ -339,7 +362,8 @@ async def invoke(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult: "candidate_count": int(outcome.stats.get("candidates") or len(sections)), "event_count": len(graph.events) if graph is not None else 0, "event_candidates": len(event_scores), - "retrieval_stats": outcome.stats, + # The tool passes an explicit strategy to retrieval, so restate where it came from. + "retrieval_stats": {**outcome.stats, "strategy_origin": strategy_origin}, "_graph": graph, }, ) diff --git a/apps/api/tests/integration/test_document_operation_restart.py b/apps/api/tests/integration/test_document_operation_restart.py index 3ec8428d..f76e3820 100644 --- a/apps/api/tests/integration/test_document_operation_restart.py +++ b/apps/api/tests/integration/test_document_operation_restart.py @@ -349,10 +349,14 @@ async def wait_file(name, child, timeout=30): async with sessions() as session: bound = (await session.get(Job, identities["jobs"][0])).payload.get("process_request") receipt = await sdk.get_operation_status(bound["context"]["operation_id"]) if bound else None + # The marker can appear after this iteration read an older receipt. reached = ( models.blocked.is_set() and receipt is not None and receipt.extraction_progress["chunk_succeeded"] == 1 - if kill_at == "successful_chunk" else (root / "prepared.json").exists() + if kill_at == "successful_chunk" else ( + (root / "prepared.json").exists() and receipt is not None + and receipt.checkpoint == "extract_prepared" + ) ) if reached: break diff --git a/apps/api/tests/test_chat_turn_strategy.py b/apps/api/tests/test_chat_turn_strategy.py new file mode 100644 index 00000000..e50188da --- /dev/null +++ b/apps/api/tests/test_chat_turn_strategy.py @@ -0,0 +1,170 @@ +"""Per-turn retrieval mode in chat: explicit choice wins, is gated before streaming, and reports its origin.""" + +from types import SimpleNamespace +from uuid import uuid4 + +import httpx +import pytest + +from sag_api.core.config import Settings, settings +from sag_api.sag import RetrievedSection, SearchOutcome, SourceGraphInfo +from sag_api.sag.engine_manager import EngineManager +from sag_api.schemas.agent import AskRequest +from sag_api.tools.builtin import knowledge_search_strategy, knowledge_search_strategy_origin + + +def configured(**changes) -> Settings: + return Settings(_env_file=None).model_copy(update={ + "jev_endpoint": "https://jev.invalid/score", + "jev_api_key": "synthetic-jev-key", + "sag_vector_provider": "lancedb", + "search_strategy": "multi_es_fast", + **changes, + }) + + +def source(default: str | None, config_id: str = "cfg-1"): + return SimpleNamespace( + id=config_id, name=config_id, sag_source_config_id=config_id, default_search_strategy=default, + ) + + +def test_ask_request_accepts_optional_strategy(): + assert AskRequest(query="q").strategy is None + assert AskRequest(query="q", strategy="sag2").strategy == "sag2" + with pytest.raises(ValueError): + AskRequest(query="q", strategy="nope") + + +def test_turn_choice_precedes_persona_source_default_and_global(): + configuration = configured(search_strategy="vector") + persona = {"search_strategy": "multi"} + scoped = [source("sag2")] + assert knowledge_search_strategy(persona, configuration, scoped, "multi_jev") == "multi_jev" + assert knowledge_search_strategy_origin(persona, scoped, "multi_jev") == "request" + assert knowledge_search_strategy(persona, configuration, scoped) == "multi" + assert knowledge_search_strategy_origin(persona, scoped) == "persona" + assert knowledge_search_strategy({}, configuration, scoped) == "sag2" + assert knowledge_search_strategy_origin({}, scoped) == "source_default" + assert knowledge_search_strategy({}, configuration, []) == "vector" + assert knowledge_search_strategy_origin({}, []) == "global" + + +@pytest.mark.asyncio +async def test_search_tool_uses_turn_choice_and_reports_origin(monkeypatch, publication_source): + from sag_api.services.agent_tooling import _adapt_tool + from sag_api.tools import builtin + from sag_api.tools.base import ToolContext + + scoped = await publication_source("turn-choice", "cfg-1", "document-1") + scoped.default_search_strategy = "sag2" + engine = EngineManager(configured(search_strategy="multi_es_fast")) + calls = [] + + async def retrieve(manager, sources, query, *, strategy, top_k): + calls.append(strategy) + return SearchOutcome(query=query, sections=[RetrievedSection( + chunk_id="c1", heading="h", content="evidence", score=0.5, source_config_id="cfg-1", + source_id="document-1", metadata={"score_source": "jev"}, + )], stats={"requested_strategy": strategy, "effective_strategy": strategy, "strategy_origin": "request"}) + + async def events(*_args, **_kwargs): + return {} + + async def graph(*_args, **_kwargs): + return SourceGraphInfo(events=[]) + + engine.graph_for_sections = graph + monkeypatch.setattr(builtin, "retrieve_relevant_sections", retrieve) + monkeypatch.setattr(builtin, "recall_event_scores", events) + tool = builtin.SearchContextTool() + + # The explicit turn choice overrides the persona and the source default. + result = await tool.invoke({"query": "q"}, ToolContext( + engine_manager=engine, sources=[scoped], persona={"search_strategy": "multi"}, requested_strategy="vector", + )) + assert calls[-1] == "vector" + assert result.data["retrieval_stats"]["strategy_origin"] == "request" + + # Without a turn choice the persona wins, then the source default. + result = await tool.invoke({"query": "q"}, ToolContext( + engine_manager=engine, sources=[scoped], persona={"search_strategy": "multi"}, + )) + assert calls[-1] == "multi" and result.data["retrieval_stats"]["strategy_origin"] == "persona" + result = await tool.invoke({"query": "q"}, ToolContext(engine_manager=engine, sources=[scoped], persona={})) + assert calls[-1] == "sag2" and result.data["retrieval_stats"]["strategy_origin"] == "source_default" + + # The adapted tool's budget follows the turn choice as well. + adapted = _adapt_tool(tool, ToolContext( + engine_manager=engine, sources=[scoped], persona={}, requested_strategy="vector", + ), []) + assert adapted.spec.timeout_seconds is None + + captured = [] + original_invoke = tool.invoke + + async def capture(arguments, context): + result = await original_invoke(arguments, context) + captured.append(result.data["retrieval_stats"]) + return result + + monkeypatch.setattr(tool, "invoke", capture) + for source_default, expected_origin in [("sag2", "source_default"), (None, "global")]: + scoped.default_search_strategy = source_default + persona = {} + adapted = _adapt_tool(tool, ToolContext(engine_manager=engine, sources=[scoped], persona=persona), []) + await adapted.execute({"query": "q"}, SimpleNamespace( + cancellation=SimpleNamespace(raise_if_cancelled=lambda: None), + )) + assert captured[-1]["strategy_origin"] == expected_origin + assert persona == {} + + +@pytest.fixture +async def chat_client(monkeypatch): + from sag_api.main import app + + async def skip_unrelated_mcp(_factory, _app): + return None + + monkeypatch.setattr("sag_api.runtime._RuntimeFactory.start_mcp", skip_unrelated_mcp) + snapshot = settings.model_dump() + try: + async with app.router.lifespan_context(app): + app.state.llm = SimpleNamespace(configured=True) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://t") as client: + registration = await client.post( + "/api/v1/auth/register", + json={"email": f"chat-mode-{uuid4().hex}@t.com", "password": "password123"}, + ) + assert registration.status_code == 201 + client.headers["Authorization"] = f"Bearer {registration.json()['access_token']}" + yield client + finally: + for key, value in snapshot.items(): + setattr(settings, key, value) + + +async def test_ask_rejects_unavailable_turn_strategy_before_streaming(chat_client, monkeypatch): + client = chat_client + monkeypatch.setattr(settings, "sag_vector_provider", "lancedb") + monkeypatch.setattr(settings, "jev_endpoint", "https://jev.example/score") + monkeypatch.setattr(settings, "jev_api_key", None) + agent = (await client.post("/api/v1/agents", json={"name": "模式助手"})).json() + thread = (await client.post(f"/api/v1/agents/{agent['id']}/threads", json={})).json() + endpoint = f"/api/v1/agents/{agent['id']}/threads/{thread['id']}/ask" + + rejected = await client.post(endpoint, json={"query": "问题", "strategy": "sag2"}) + assert rejected.status_code == 400, rejected.text + assert rejected.json()["error"]["code"] == "jev_api_key_missing" + # Nothing was persisted for the rejected turn. + messages = await client.get(f"/api/v1/agents/{agent['id']}/threads/{thread['id']}/messages") + assert messages.status_code == 200 and messages.json()["items"] == [] + + unknown = await client.post(endpoint, json={"query": "问题", "strategy": "nope"}) + assert unknown.status_code == 422 + + monkeypatch.setattr(settings, "sag_relational_provider", "mysql") + monkeypatch.setattr(settings, "jev_api_key", "synthetic-jev-key") + storage = await client.post(endpoint, json={"query": "问题", "strategy": "sag2"}) + assert storage.status_code == 400 and storage.json()["error"]["code"] == "sag2_relational_unsupported" diff --git a/apps/api/tests/test_client_access_standard.py b/apps/api/tests/test_client_access_standard.py index 11629595..abf8463e 100644 --- a/apps/api/tests/test_client_access_standard.py +++ b/apps/api/tests/test_client_access_standard.py @@ -218,6 +218,8 @@ async def test_real_source_writes_have_recoverable_subject_scoped_operations(sta break await asyncio.sleep(0.05) assert job.json()["status"] == "succeeded", job.text + # A completed delete response can precede the worker's final DB cleanup. + await asyncio.wait_for(app.state.job_queue._queue.join(), timeout=30) async def test_disabled_user_loses_business_and_refresh_access(standard_client): diff --git a/apps/api/tests/test_jev_transports.py b/apps/api/tests/test_jev_transports.py index 86e4f076..97658952 100644 --- a/apps/api/tests/test_jev_transports.py +++ b/apps/api/tests/test_jev_transports.py @@ -63,13 +63,14 @@ async def test_agent_tool_keeps_the_strategy_selected_when_the_run_was_prepared( class RecordingSearchTool(SearchTool): async def invoke(self, _arguments, context): - used.append(context.persona.get("search_strategy")) + used.append(context.search_strategy_snapshot) + assert context.persona == {} # Freezing a run must not rewrite the persona. return ToolResult(content="evidence") adapted = _adapt_tool(RecordingSearchTool(), ToolContext(engine_manager=object()), []) active.search_strategy = "multi_jev" await adapted.execute({}, SimpleNamespace(cancellation=SimpleNamespace(raise_if_cancelled=lambda: None))) - assert used == ["vector"] + assert used == [("vector", "global")] @pytest.mark.asyncio diff --git a/apps/web/components/features/app-shell.tsx b/apps/web/components/features/app-shell.tsx index e3722547..da9d9f24 100644 --- a/apps/web/components/features/app-shell.tsx +++ b/apps/web/components/features/app-shell.tsx @@ -133,6 +133,7 @@ const CONVERSATION_TRANSPORT: ConversationTransport = { sourceIds, knowledgeOnly, webEnabled, + strategy, onEvent, signal, }) => { @@ -145,6 +146,7 @@ const CONVERSATION_TRANSPORT: ConversationTransport = { attachment_count: attachmentIds?.length ?? 0, source_ids: sourceIds, web_enabled: webEnabled, + strategy, }); const promise = streamAgentAsk( agentId, @@ -155,6 +157,8 @@ const CONVERSATION_TRANSPORT: ConversationTransport = { source_ids: sourceIds, knowledge_only: knowledgeOnly === true || !webEnabled, web_enabled: webEnabled, + // Only an explicit per-turn pick travels; otherwise the backend resolves the mode. + ...(strategy ? { strategy } : {}), }, (event) => { // 只记录关键事件,跳过高频 message.delta diff --git a/apps/web/components/features/chat/conversation-panel.test.tsx b/apps/web/components/features/chat/conversation-panel.test.tsx index 2be334eb..2cf90735 100644 --- a/apps/web/components/features/chat/conversation-panel.test.tsx +++ b/apps/web/components/features/chat/conversation-panel.test.tsx @@ -6,35 +6,50 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import english from "@/messages/en-US.json"; import type { ConversationMessage, ConversationSessionSnapshot } from "@/lib/conversation-runtime"; -import type { MessageSourceScope, Source } from "@/lib/types"; +import { AgentHttpError } from "@/lib/sse"; +import type { Agent, Capabilities, MessageSourceScope, Source } from "@/lib/types"; import { ConversationPanel } from "./conversation-panel"; const state = vi.hoisted(() => ({ snapshot: null as ConversationSessionSnapshot | null, send: vi.fn(), activate: vi.fn(), ensureHistory: vi.fn(), setInput: vi.fn(), + toastError: vi.fn(), setImages: vi.fn(), uploadAttachment: vi.fn(), + runtimeRun: {} as object | null, + input: "Unsent draft", images: [] as { file: File; url: string }[], sources: [] as Source[], + scoped: [{ id: "composer-source", name: "Composer selection" }], + capabilities: { llm_configured: true } as Partial, + agent: null as Agent | null, })); +const catalog = english as unknown as Record>; vi.mock("next-intl", () => ({ useLocale: () => "en-US", - useTranslations: () => (key: keyof typeof english.Conversation) => english.Conversation[key] ?? key, + useTranslations: (namespace: string) => (key: string, values?: Record) => + (catalog[namespace]?.[key] ?? key).replace(/\{(\w+)\}/g, (_, name: string) => String(values?.[name] ?? "")), })); +vi.mock("next/link", () => ({ + default: React.forwardRef>( + function Link({ children, href, ...props }, ref) { return {children}; }, + ), +})); +vi.mock("sonner", () => ({ toast: { error: state.toastError, success: vi.fn() } })); vi.mock("@/components/features/app-shell", () => ({ - useApp: () => ({ capabilities: { llm_configured: true }, timezone: "UTC" }), + useApp: () => ({ capabilities: state.capabilities, agent: state.agent, timezone: "UTC" }), })); vi.mock("./conversation-provider", () => ({ useConversationSession: () => state.snapshot, useConversationRuntime: () => ({ activate: state.activate, ensureHistory: state.ensureHistory, send: state.send, getIndexSnapshot: () => ({ activeRunSessionId: null }), - getSessionSnapshot: () => ({ run: {} }), + getSessionSnapshot: () => ({ run: state.runtimeRun }), }), useConversationComposer: () => ({ - input: "Unsent draft", scoped: [{ id: "composer-source", name: "Composer selection" }], - images: [], webEnabled: false, setInput: state.setInput, - setImages: vi.fn(), setScoped: vi.fn(), setWebEnabled: vi.fn(), + input: state.input, scoped: state.scoped, + images: state.images, webEnabled: false, setInput: state.setInput, + setImages: state.setImages, setScoped: vi.fn(), setWebEnabled: vi.fn(), }), })); -vi.mock("@/lib/api", () => ({ api: { listSources: async () => state.sources } })); +vi.mock("@/lib/api", () => ({ api: { listSources: async () => state.sources, uploadAttachment: state.uploadAttachment } })); vi.mock("@/components/features/detail-panel", () => ({ useDetailPanel: () => ({ open: vi.fn() }) })); vi.mock("@/components/features/markdown-content", () => ({ MarkdownContent: ({ content }: { content: string }) =>
{content}
, @@ -42,16 +57,55 @@ vi.mock("@/components/features/markdown-content", () => ({ vi.mock("./prompt-preview", () => ({ PromptPreview: () => null })); vi.mock("./agent-activity-timeline", () => ({ AgentActivityTimeline: () => null })); +const ALL_STRATEGIES = ["vector", "multi_es_fast", "multi", "multi_jev", "sag2"] as const; +const emptySession: ConversationSessionSnapshot = { + sessionId: "session-1", agentId: "agent-1", threadId: "thread-1", error: null, run: null, + history: { status: "ready", requestId: 0, hasMore: false, nextCursor: null, error: null }, messages: [], +}; +function source(id: string, defaultStrategy: Source["default_search_strategy"] = null, status = "active"): Source { + return { + id, name: id, description: "", source_type: "document", connector_kind: "file_upload", + status, default_search_strategy: defaultStrategy, document_count: 0, chunk_count: 0, event_count: 0, + created_at: "2026-10-09T00:00:00Z", updated_at: "2026-10-09T00:00:00Z", + } as Source; +} +function agent(searchStrategy?: string): Agent { + return { + id: "agent-1", name: "Agent", avatar: "", created_at: "2026-10-09T00:00:00Z", updated_at: "2026-10-09T00:00:00Z", + persona: { greeting: "Hi", ...(searchStrategy ? { search_strategy: searchStrategy as Agent["persona"]["search_strategy"] } : {}) }, + }; +} +function pointerEvent(type: string) { + const event = new MouseEvent(type, { bubbles: true, button: 0 }); + Object.defineProperties(event, { pointerId: { value: 1 }, pointerType: { value: "mouse" } }); + return event; +} + let container: HTMLDivElement; let root: Root; const originalScrollIntoView = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "scrollIntoView"); beforeEach(() => { vi.clearAllMocks(); + state.runtimeRun = {}; + state.input = "Unsent draft"; + state.images = []; + state.setInput.mockImplementation((next) => { state.input = typeof next === "function" ? next(state.input) : next; }); + state.setImages.mockImplementation((next) => { state.images = typeof next === "function" ? next(state.images) : next; }); + state.uploadAttachment.mockResolvedValue({ id: "attachment-1" }); state.sources = []; + state.scoped = [{ id: "composer-source", name: "Composer selection" }]; + state.capabilities = { llm_configured: true }; + state.agent = null; + state.snapshot = emptySession; state.send.mockResolvedValue({}); (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; vi.stubGlobal("ResizeObserver", class { observe() {} unobserve() {} disconnect() {} }); - Object.defineProperty(HTMLElement.prototype, "scrollIntoView", { configurable: true, value: vi.fn() }); + Object.defineProperties(HTMLElement.prototype, { + scrollIntoView: { configurable: true, value: vi.fn() }, + hasPointerCapture: { configurable: true, value: () => false }, + releasePointerCapture: { configurable: true, value: () => undefined }, + setPointerCapture: { configurable: true, value: () => undefined }, + }); container = document.createElement("div"); document.body.append(container); root = createRoot(container); @@ -65,20 +119,25 @@ afterEach(async () => { else delete (HTMLElement.prototype as Partial).scrollIntoView; }); +async function renderPanel() { + await act(async () => root.render()); +} +const trigger = () => container.querySelector('[data-testid="search-strategy"]')!; +const hint = () => container.querySelector('[data-testid="search-strategy-hint"]')?.textContent ?? null; +const sendButton = () => container.querySelector(`button[title="${english.Conversation.send}"]`)!; +async function pick(label: string) { + await act(async () => trigger().dispatchEvent(pointerEvent("pointerdown"))); + const item = [...document.body.querySelectorAll('[role="menuitem"]')] + .find((candidate) => candidate.textContent?.includes(label))!; + await act(async () => { item.dispatchEvent(pointerEvent("pointermove")); item.dispatchEvent(pointerEvent("pointerup")); item.click(); }); +} + describe("retry source scope", () => { it("excludes deleting sources from mentions while keeping the composer selection", async () => { - state.sources = ["active", "paused", "error", "deleting", "delete_failed"].map((status) => ({ - id: status, name: status, description: "", source_type: "document", connector_kind: "file_upload", - status, document_count: 0, chunk_count: 0, event_count: 0, - created_at: "2026-10-09T00:00:00Z", updated_at: "2026-10-09T00:00:00Z", - } as Source)); - state.snapshot = { - sessionId: "session-1", agentId: "agent-1", threadId: "thread-1", error: null, run: null, - history: { status: "ready", requestId: 0, hasMore: false, nextCursor: null, error: null }, messages: [], - }; - await act(async () => root.render()); + state.sources = ["active", "paused", "error", "deleting", "delete_failed"].map((status) => source(status, null, status)); + await renderPanel(); const textarea = container.querySelector("textarea")!; await act(async () => { Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value")!.set!.call(textarea, "@"); @@ -100,13 +159,10 @@ describe("retry source scope", () => { sourceScope: saved as MessageSourceScope[] | null, }; state.snapshot = { - sessionId: "session-1", agentId: "agent-1", threadId: "thread-1", error: null, run: null, - history: { status: "ready", requestId: 0, hasMore: false, nextCursor: null, error: null }, + ...emptySession, messages: [base, { ...base, id: "answer", role: "assistant", content: "Original answer", sourceScope: null }], }; - await act(async () => root.render()); + await renderPanel(); const retry = container.querySelector('button[aria-label="Generate answer again"]')!; expect(retry).toBeTruthy(); await act(async () => retry.click()); @@ -115,3 +171,206 @@ describe("retry source scope", () => { })); }); }); + +describe("composer retrieval mode", () => { + it("shows the global default without a hint when nothing else applies", async () => { + state.capabilities = { llm_configured: true, search_strategy: "multi_es_fast" }; + await renderPanel(); + // The legacy Agent default is vector for non-JEV global modes. + expect(trigger().textContent).toContain("Fast (vector)"); + expect(hint()).toBeNull(); + expect(trigger().disabled).toBe(false); + }); + + it("prefers the agent persona mode and says so", async () => { + state.capabilities = { llm_configured: true, search_strategy: "vector", search_strategies: [...ALL_STRATEGIES] }; + state.agent = agent("sag2"); + state.sources = [source("composer-source", "multi")]; + await renderPanel(); + expect(trigger().textContent).toContain("SAG2 evidence retrieval"); + expect(hint()).toContain("Persona default"); + }); + + it("falls back to the shared source default when the persona mode cannot be served", async () => { + // Without an advertised search_strategies list the JEV modes are unsupported. + state.capabilities = { llm_configured: true, search_strategy: "vector" }; + state.agent = agent("sag2"); + state.sources = [source("composer-source", "multi")]; + await renderPanel(); + expect(trigger().textContent).toContain("Precise"); + expect(hint()).toContain("Source default"); + }); + + it("ignores source defaults that the scoped sources do not share", async () => { + state.scoped = [{ id: "a", name: "a" }, { id: "b", name: "b" }]; + state.sources = [source("a", "multi"), source("b", "multi_es_fast")]; + await renderPanel(); + expect(trigger().textContent).toContain("Fast (vector)"); + expect(hint()).toBeNull(); + }); + + it("omits the mode from the request when nothing is pinned", async () => { + state.agent = agent("multi"); + await renderPanel(); + await act(async () => sendButton().click()); + expect(state.send).toHaveBeenCalledTimes(1); + expect(state.send.mock.calls[0][1]).not.toHaveProperty("strategy"); + }); + + it("sends the pinned mode and drops the origin hint", async () => { + state.agent = agent("multi"); + await renderPanel(); + expect(hint()).toContain("Persona default"); + await pick("Fast (multi_es-fast)"); + expect(trigger().textContent).toContain("Fast (multi_es-fast)"); + expect(hint()).toBeNull(); + await act(async () => sendButton().click()); + expect(state.send).toHaveBeenCalledWith("session-1", expect.objectContaining({ strategy: "multi_es_fast" })); + }); + + it("locks the control while a run is in flight", async () => { + state.snapshot = { + ...emptySession, + run: { requestId: "r", runId: "run-1", lifecycle: "running", startedAt: 0, assistantMessageId: "a", steps: [], pendingApproval: null }, + }; + await renderPanel(); + expect(trigger().disabled).toBe(true); + }); + + it("keeps a pre-stream mode rejection above the composer with a settings link", async () => { + state.send.mockRejectedValue(new AgentHttpError("Add a JEV API key first", "jev_api_key_missing", 400)); + await renderPanel(); + await act(async () => sendButton().click()); + const notice = container.querySelector('[data-testid="strategy-notice"]')!; + expect(notice.textContent).toContain("Add a JEV API key first"); + expect(notice.getAttribute("data-code")).toBe("jev_api_key_missing"); + expect(container.querySelector('[data-testid="strategy-notice-settings"]')?.getAttribute("href")) + .toBe("/settings?tab=knowledge§ion=jev"); + expect(state.toastError).not.toHaveBeenCalled(); + await pick("Precise"); + expect(container.querySelector('[data-testid="strategy-notice"]')).toBeNull(); + }); + + it("blocks an unavailable pinned mode before uploading or clearing the draft", async () => { + state.capabilities = { llm_configured: true, search_strategies: [...ALL_STRATEGIES] }; + await renderPanel(); + await pick("SAG2 evidence retrieval"); + state.images = [{ file: new File(["image"], "draft.png"), url: "blob:draft" }]; + state.capabilities = { + ...state.capabilities, + search_strategies_disabled: { sag2: { reason: "jev_api_key_missing", message: "Add a JEV API key first" } }, + }; + await renderPanel(); + expect(container.querySelector('[data-testid="strategy-notice"]')?.textContent).toContain("Add a JEV API key first"); + await act(async () => sendButton().click()); + expect(state.send).not.toHaveBeenCalled(); + expect(state.uploadAttachment).not.toHaveBeenCalled(); + expect(state.input).toBe("Unsent draft"); + expect(state.images).toHaveLength(1); + expect(trigger().textContent).toContain("SAG2 evidence retrieval"); + expect(sendButton().disabled).toBe(true); + await pick("Precise"); + await act(async () => sendButton().click()); + expect(state.send).toHaveBeenCalledWith("session-1", expect.objectContaining({ strategy: "multi" })); + }); + + it("restores text and image previews when a stale capability is rejected before streaming", async () => { + const revoke = vi.fn(); + vi.stubGlobal("URL", class extends URL { static revokeObjectURL = revoke; }); + const image = { file: new File(["image"], "draft.png"), url: "blob:draft" }; + state.images = [image]; + state.capabilities = { llm_configured: true, search_strategies: [...ALL_STRATEGIES] }; + let reject!: (reason: Error) => void; + state.send.mockImplementation(() => new Promise((_resolve, fail) => { reject = fail; })); + await renderPanel(); + await pick("SAG2 evidence retrieval"); + await act(async () => sendButton().click()); + expect(state.input).toBe(""); + expect(state.images).toEqual([]); + await act(async () => reject(new AgentHttpError("Add a JEV API key first", "jev_api_key_missing", 400))); + expect(state.input).toBe("Unsent draft"); + expect(state.images).toEqual([image]); + expect(revoke).not.toHaveBeenCalled(); + state.send.mockResolvedValue({}); + await renderPanel(); + await pick("Precise"); + await act(async () => sendButton().click()); + expect(state.send).toHaveBeenLastCalledWith("session-1", expect.objectContaining({ + query: "Unsent draft", attachmentIds: ["attachment-1"], strategy: "multi", + })); + expect(revoke).toHaveBeenCalledWith("blob:draft"); + }); + + it("allows the same pinned mode once its configuration is restored", async () => { + state.capabilities = { llm_configured: true, search_strategies: [...ALL_STRATEGIES] }; + await renderPanel(); + await pick("SAG2 evidence retrieval"); + state.capabilities = { ...state.capabilities, search_strategies_disabled: { + sag2: { reason: "jev_api_key_missing", message: "Add a JEV API key first" }, + } }; + await renderPanel(); + expect(sendButton().disabled).toBe(true); + state.capabilities = { ...state.capabilities, search_strategies_disabled: {} }; + await renderPanel(); + expect(container.querySelector('[data-testid="strategy-notice"]')).toBeNull(); + expect(sendButton().disabled).toBe(false); + await act(async () => sendButton().click()); + expect(state.send).toHaveBeenCalledWith("session-1", expect.objectContaining({ strategy: "sag2" })); + }); + + it("does not accept pasted images while uploading or awaiting a rejected turn", async () => { + const create = vi.fn((file: File) => `blob:${file.name}`); + vi.stubGlobal("URL", class extends URL { static createObjectURL = create; }); + const originalImages = Array.from({ length: 4 }, (_, index) => ({ + file: new File(["image"], `original-${index}.png`, { type: "image/png" }), url: `blob:original-${index}`, + })); + state.images = originalImages; + let finishUpload!: (value: { id: string }) => void; + const upload = new Promise<{ id: string }>((resolve) => { finishUpload = resolve; }); + state.uploadAttachment.mockReturnValue(upload); + let reject!: (reason: Error) => void; + state.send.mockImplementation(() => new Promise((_resolve, fail) => { reject = fail; })); + await renderPanel(); + const paste = () => { + const event = new Event("paste", { bubbles: true, cancelable: true }); + Object.defineProperty(event, "clipboardData", { value: { files: Array.from({ length: 4 }, (_, index) => + new File(["new image"], `new-${index}.png`, { type: "image/png" })) } }); + container.querySelector("textarea")!.dispatchEvent(event); + }; + // Same tick: uploadingRef guards the paste before React renders the busy state. + await act(async () => { sendButton().click(); paste(); }); + expect(create).not.toHaveBeenCalled(); + expect(state.setImages).not.toHaveBeenCalled(); + await act(async () => finishUpload({ id: "attachment-1" })); + expect(state.images).toEqual([]); + await act(async () => paste()); + expect(create).not.toHaveBeenCalled(); + await act(async () => reject(new AgentHttpError("Add a JEV API key first", "jev_api_key_missing", 400))); + expect(state.images).toEqual(originalImages); + expect(state.images).toHaveLength(4); + state.runtimeRun = null; + state.images = []; + await renderPanel(); + await act(async () => paste()); + expect(create).toHaveBeenCalledTimes(4); + expect(state.images).toHaveLength(4); + }); + + it("does not overwrite a newer draft when restoring a rejected question", async () => { + let reject!: (reason: Error) => void; + state.send.mockImplementation(() => new Promise((_resolve, fail) => { reject = fail; })); + await renderPanel(); + await act(async () => sendButton().click()); + state.input = "A newer draft"; + await act(async () => reject(new AgentHttpError("Add a JEV API key first", "jev_api_key_missing", 400))); + expect(state.input).toBe("A newer draft"); + }); + + it("still toasts errors that are not about the retrieval mode", async () => { + state.send.mockRejectedValue(new AgentHttpError("Server exploded", "internal_error", 500)); + await renderPanel(); + await act(async () => sendButton().click()); + expect(container.querySelector('[data-testid="strategy-notice"]')).toBeNull(); + expect(state.toastError).toHaveBeenCalledWith("Server exploded"); + }); +}); diff --git a/apps/web/components/features/chat/conversation-panel.tsx b/apps/web/components/features/chat/conversation-panel.tsx index ea24092c..37e5e9bc 100644 --- a/apps/web/components/features/chat/conversation-panel.tsx +++ b/apps/web/components/features/chat/conversation-panel.tsx @@ -3,6 +3,7 @@ import * as React from "react"; import { ArrowUp, Check, Copy, FileUp, Globe2, ImagePlus, Library, Plus, RotateCcw, Square, Trash2, X } from "lucide-react"; import { useLocale, useTranslations } from "next-intl"; +import Link from "next/link"; import { toast } from "sonner"; import { toolArgumentsPreview } from "@/lib/agent-run-activity"; @@ -15,6 +16,16 @@ import { isComposerCompositionKeyEvent, shouldSubmitAfterEnter, } from "@/lib/composer-keyboard"; +import { + getScopeDefaultStrategy, + getSearchStrategiesDisabled, + isSearchStrategy, + isJevScoredStrategy, + isSearchStrategyRejectionCode, + type SearchStrategy, +} from "@/lib/retrieval-config"; +import { settingsTabHref } from "@/lib/settings-config"; +import { AgentHttpError } from "@/lib/sse"; import type { Citation, MessageSourceScope, Source } from "@/lib/types"; import { cn } from "@/lib/utils"; import { copyText } from "@/lib/clipboard"; @@ -35,6 +46,7 @@ import { type ConversationMessageRenderContext, } from "@/components/features/chat/conversation-transcript"; import { PromptPreview } from "@/components/features/chat/prompt-preview"; +import { SearchStrategyControl } from "@/components/features/search-strategy-control"; import { AuthImage } from "@/components/features/auth-image"; import { Button } from "@/components/ui/button"; import { @@ -60,6 +72,18 @@ import { DropdownMenuTrigger, } from "@/components/ui/dropdown-menu"; +/** Where a rejected JEV mode gets fixed; the same section the mode menu links to. */ +const JEV_SETTINGS_HREF = settingsTabHref("knowledge", "jev"); + +/** Who decided the mode shown in the composer when nothing is pinned. */ +type ChatStrategyOrigin = "pinned" | "persona" | "source_default" | "global"; + +/** A pre-stream rejection of the chosen retrieval mode, shown above the composer. */ +interface StrategyNotice { + code: string; + message: string; +} + function MessageActions({ content, citations, @@ -186,9 +210,11 @@ export function ConversationPanel({ onToolMatchClick, }: ConversationPanelProps) { const t = useTranslations("Conversation"); + const searchStrategies = useTranslations("SearchStrategies"); + const retrievalModes = useTranslations("RetrievalModes"); const locale = useLocale(); const resolvedPlaceholder = placeholder ?? t("defaultPlaceholder"); - const { capabilities } = useApp(); + const { capabilities, agent } = useApp(); const runtime = useConversationRuntime(); const session = useConversationSession(sessionId); const detailPanel = useDetailPanel(); @@ -205,6 +231,9 @@ export function ConversationPanel({ useConversationComposer(sessionId); const imagesRef = React.useRef(images); const [sources, setSources] = React.useState([]); + // An explicit pick lives with this panel only; it is sent as `strategy` until the panel unmounts. + const [pinnedStrategy, setPinnedStrategy] = React.useState(null); + const [strategyNotice, setStrategyNotice] = React.useState(null); const [mentionOpen, setMentionOpen] = React.useState(false); const [mentionIdx, setMentionIdx] = React.useState(0); const [uploading, setUploading] = React.useState(false); @@ -267,6 +296,52 @@ export function ConversationPanel({ return q ? sources.filter((s) => s.name.toLowerCase().includes(q)) : sources; }, [sources, mentionQuery]); React.useEffect(() => setMentionIdx(0), [mentionQuery]); + + // Mirror the backend's resolution order so the composer shows the mode a turn will actually use: + // pinned pick → agent persona → shared default of the scoped sources → global default. + const unsupportedStrategyMessage = searchStrategies("unsupportedBackend"); + const strategyDisabledMap = React.useMemo( + () => getSearchStrategiesDisabled(capabilities, unsupportedStrategyMessage), + [capabilities, unsupportedStrategyMessage], + ); + const personaStrategy = React.useMemo(() => { + const value = agent?.persona?.search_strategy; + return isSearchStrategy(value) && !strategyDisabledMap[value] ? value : null; + }, [agent?.persona?.search_strategy, strategyDisabledMap]); + // Scopes only carry id + name; the loaded source list supplies each one's default. + // A scope whose source is not loaded yet counts as "no default", like the backend treats null. + const scopeDefaultStrategy = React.useMemo(() => getScopeDefaultStrategy( + scoped.map((scope) => ({ + default_search_strategy: sources.find((source) => source.id === scope.id)?.default_search_strategy ?? null, + })), + strategyDisabledMap, + ), [scoped, sources, strategyDisabledMap]); + // Match the Agent's legacy non-JEV default; an explicit pick still overrides it. + const globalStrategy = isJevScoredStrategy(capabilities?.search_strategy) + ? capabilities.search_strategy + : "vector"; + const resolvedStrategy = personaStrategy ?? scopeDefaultStrategy ?? globalStrategy; + // Keep an explicit choice visible, but never submit it after its configuration expires. + const pinnedStrategyIssue = pinnedStrategy ? strategyDisabledMap[pinnedStrategy] : undefined; + const displayedStrategyNotice = pinnedStrategyIssue + ? { code: pinnedStrategyIssue.reason, message: pinnedStrategyIssue.message } + : strategyNotice; + const strategyOrigin: ChatStrategyOrigin = pinnedStrategy + ? "pinned" + : personaStrategy + ? "persona" + : scopeDefaultStrategy + ? "source_default" + : "global"; + const strategyHint = strategyOrigin === "persona" + ? retrievalModes("personaDefaultHint") + : strategyOrigin === "source_default" + ? retrievalModes("scopeDefaultHint") + : undefined; + const pinStrategy = React.useCallback((value: SearchStrategy) => { + setPinnedStrategy(value); + setStrategyNotice(null); + }, []); React.useEffect(() => { mentionListRef.current ?.querySelector(`[data-idx="${mentionIdx}"]`) @@ -493,7 +568,9 @@ export function ConversationPanel({ const MAX_IMAGES = 4; function addImages(files: FileList | File[] | null) { - if (!files) return; + // Match the disabled attachment button, including paste/file-picker events + // before a busy-state render. A rejected turn may need all four images back. + if (!files || uploadingRef.current || streaming || runtime.getSessionSnapshot(sessionId).run) return; const incoming = Array.from(files).filter((f) => f.type.startsWith("image/")); if (!incoming.length) return; setImages((prev) => { @@ -518,10 +595,12 @@ export function ConversationPanel({ } async function send(text?: string, sourceScope?: MessageSourceScope[] | null) { + const draftInput = input; const query = (text ?? input).trim(); const pendingImages = images; const selectedScope = (sourceScope ?? scoped).map((source) => ({ ...source })); if ((!query && pendingImages.length === 0) || uploadingRef.current) return; + if (pinnedStrategyIssue) return; if (!capabilities?.llm_configured) { toast.error(t("modelNotConfigured")); getDiagnosticsStore().record("error", { @@ -537,6 +616,7 @@ export function ConversationPanel({ uploadingRef.current = true; setUploading(true); + setStrategyNotice(null); try { const uploaded = pendingImages.length ? await Promise.all(pendingImages.map((item) => api.uploadAttachment(item.file))) @@ -547,6 +627,8 @@ export function ConversationPanel({ attachmentIds: uploaded.map((item) => item.id), sourceScope: selectedScope, webEnabled, + // Omitted unless pinned so the backend applies persona / source / global defaults itself. + ...(pinnedStrategy ? { strategy: pinnedStrategy } : {}), }); // send 在首次 await 前就登记 run;未登记表示被全局并发边界拒绝,保留草稿。 @@ -558,12 +640,26 @@ export function ConversationPanel({ setInput(""); imagesRef.current = []; setImages([]); - pendingImages.forEach((image) => URL.revokeObjectURL(image.url)); setStepsCollapsed(false); followOutputRef.current = true; - void request.catch((error) => { - toast.error(error instanceof Error ? error.message : t("connectionInterrupted")); + const releaseImagePreviews = () => pendingImages.forEach((image) => URL.revokeObjectURL(image.url)); + void request.then(releaseImagePreviews, (error) => { + // A mode this deployment cannot serve is rejected before streaming; keep that + // explanation next to the mode control instead of letting it vanish with a toast. + if (error instanceof AgentHttpError && isSearchStrategyRejectionCode(error.code)) { + setStrategyNotice({ code: error.code, message: error.message }); + // Capabilities can be stale (e.g. settings changed in another window). The + // server rejected this turn before streaming, so preserve its unsent draft. + setInput((current) => current || (text === undefined ? draftInput : query)); + setImages((current) => [ + ...pendingImages, + ...current.filter((image) => !pendingImages.some((pending) => pending.url === image.url)), + ]); + } else { + releaseImagePreviews(); + toast.error(error instanceof Error ? error.message : t("connectionInterrupted")); + } getDiagnosticsStore().record("qa.error", { context: "conversation.send", error_message: error instanceof Error ? error.message.slice(0, 500) : String(error).slice(0, 500), @@ -737,6 +833,31 @@ export function ConversationPanel({
+ {displayedStrategyNotice && ( +
+ {displayedStrategyNotice.message} + + {searchStrategies("openSettings")} + + {!pinnedStrategyIssue && } +
+ )}
{images.length > 0 && (
@@ -945,6 +1066,14 @@ export function ConversationPanel({ : t("webDisabledDescription")} + @@ -1013,7 +1142,7 @@ export function ConversationPanel({ + ); +} + +/** Compact latency / candidate summary for one strategy run. */ +export function StatsPill({ stats }: { stats: Record }) { + const latency = pickNumber(stats, "latency_total_ms"); + const engineLatency = pickNumber(stats, "latency_engine_ms"); + const candidates = pickNumber(stats, "candidates"); + const relevant = pickNumber(stats, "relevant"); + const parts: string[] = []; + if (latency != null) parts.push(`${latency.toFixed(0)}ms`); + else if (engineLatency != null) parts.push(`${engineLatency.toFixed(0)}ms`); + if (candidates != null) parts.push(`cand=${candidates}`); + if (relevant != null) parts.push(`rel=${relevant}`); + const engineTimings = pickTimings(stats, "engine_timings"); + const topSteps = engineTimings + .filter(([key]) => !/\.total$/.test(key)) // total 已经在 pill 里 + .sort((a, b) => b[1] - a[1]) + .slice(0, 3); + if (parts.length === 0 && topSteps.length === 0) return null; + return ( +
+ {parts.length > 0 && {parts.join(" · ")}} + {topSteps.length > 0 && ( + `${k}=${v.toFixed(0)}ms`).join("\n")}> + {topSteps.map(([k, v]) => `${shortStep(k)}=${v.toFixed(0)}ms`).join(" · ")} + + )} +
+ ); +} + +/** One strategy's column as shown in the per-source retrieval test dialog. */ +export function ColumnResult({ + result, + label, + sectionLabel, + emptyLabel, +}: { + result: EvalStrategyResult | undefined; + label: string; + sectionLabel: string; + emptyLabel: string; +}) { + if (!result) return null; + return ( +
+ +
+ {label} + +
+
+ {result.error ? ( +

+ {result.error} +

+ ) : result.sections.length === 0 ? ( +

+ {emptyLabel} +

+ ) : ( + result.sections.map((section, i) => ( + + )) + )} +
+
+ ); +} + +/** Pairwise LLM verdicts, or the reason none were produced. */ +export function JudgeVerdicts({ + judges, + judgeReason, + missingLabel, + tieLabel = "tie", + strategyLabelFor, + className, +}: { + judges: EvalJudge[]; + judgeReason: string | null; + missingLabel: string; + tieLabel?: string; + strategyLabelFor: (value: SearchStrategy) => string; + className?: string; +}) { + return ( +
+ {judges.length === 0 ? ( +

{judgeReason || missingLabel}

+ ) : ( +
    + {judges.map((verdict, i) => { + const winner = + verdict.winner === "A" + ? strategyLabelFor(verdict.a_strategy) + : verdict.winner === "B" + ? strategyLabelFor(verdict.b_strategy) + : tieLabel; + return ( +
  • + + + {winner} + + + {verdict.reason} + +
  • + ); + })} +
+ )} +
+ ); +} diff --git a/apps/web/components/features/retrieval-test-dialog.test.tsx b/apps/web/components/features/retrieval-test-dialog.test.tsx new file mode 100644 index 00000000..900ab6f4 --- /dev/null +++ b/apps/web/components/features/retrieval-test-dialog.test.tsx @@ -0,0 +1,89 @@ +/** @vitest-environment jsdom */ +import * as React from "react"; +import { act } from "react"; +import { createRoot, type Root } from "react-dom/client"; +import { NextIntlClientProvider } from "next-intl"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +import messages from "@/messages/en-US.json"; +import { api, type EvalCompareResponse } from "@/lib/api"; +import type { Capabilities, Section } from "@/lib/types"; +import { RetrievalTestDialog } from "./retrieval-test-dialog"; + +const state = vi.hoisted(() => ({ capabilities: {} as Partial })); +vi.mock("@/components/features/app-shell", () => ({ useApp: () => state })); +vi.mock("sonner", () => ({ toast: { success: vi.fn(), error: vi.fn() } })); + +function section(chunk: string, score: number): Section { + return { chunk_id: chunk, heading: `Heading ${chunk}`, content: `Body ${chunk}`, score, rank: 1, source_id: "s1", source_name: "Manuals" }; +} +const compareResponse: EvalCompareResponse = { + query: "question", + results: [ + { strategy: "vector", sections: [section("c1", 0.8)], stats: { latency_total_ms: 300, candidates: 20, relevant: 5 }, error: null }, + { strategy: "multi_es_fast", sections: [], stats: {}, error: "lexical search unavailable" }, + ], + judges: [{ a_strategy: "vector", b_strategy: "multi_es_fast", winner: "A", reason: "Only A retrieved anything" }], + judge_enabled: true, + judge_reason: null, +}; + +let root: Root; +let container: HTMLDivElement; + +beforeEach(() => { + (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + state.capabilities = { search_strategy: "vector", search_strategies: ["vector", "multi_es_fast", "multi", "multi_jev", "sag2"] }; + Object.defineProperties(HTMLElement.prototype, { + hasPointerCapture: { configurable: true, value: () => false }, releasePointerCapture: { configurable: true, value: () => undefined }, + setPointerCapture: { configurable: true, value: () => undefined }, scrollIntoView: { configurable: true, value: () => undefined }, + }); + vi.stubGlobal("ResizeObserver", class { observe() {} unobserve() {} disconnect() {} }); + container = document.createElement("div"); document.body.append(container); root = createRoot(container); +}); +afterEach(async () => { await act(async () => root.unmount()); container.remove(); vi.restoreAllMocks(); vi.unstubAllGlobals(); }); + +async function openDialog() { + await act(async () => root.render( + + {}} /> + , + )); + const dialog = document.body.querySelector('[role="dialog"]')!; + expect(dialog).not.toBeNull(); + return dialog; +} +async function typeQuery(dialog: HTMLElement, value: string) { + const input = dialog.querySelector("#rt-q")!; + const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!; + await act(async () => { + setter.call(input, value); + input.dispatchEvent(new Event("input", { bubbles: true })); + }); +} + +describe("retrieval test dialog", () => { + it("still renders the single-mode form", async () => { + const dialog = await openDialog(); + expect(dialog.textContent).toContain("Test retrieval · Manuals"); + expect(dialog.querySelector("#rt-q")).not.toBeNull(); + expect(dialog.querySelector("#rt-a-select")).toBeNull(); + }); + it("compares two strategies with the shared columns and verdict list", async () => { + const evalCompare = vi.spyOn(api, "evalCompare").mockResolvedValue(compareResponse); + const dialog = await openDialog(); + await act(async () => dialog.querySelector("#rt-compare")!.click()); + expect(dialog.querySelector("#rt-a-select")).not.toBeNull(); + expect(dialog.querySelector("#rt-b-select")).not.toBeNull(); + await typeQuery(dialog, "question"); + await act(async () => dialog.querySelector("form")!.requestSubmit()); + expect(evalCompare).toHaveBeenCalledWith({ + query: "question", source_ids: ["s1"], top_k: 8, strategies: ["vector", "multi_es_fast"], judge: true, + }); + expect(dialog.textContent).toContain("Fast (vector)"); + expect(dialog.textContent).toContain("Heading c1"); + expect(dialog.textContent).toContain("300ms · cand=20 · rel=5"); + expect(dialog.textContent).toContain("lexical search unavailable"); + expect(dialog.querySelector('[data-testid="compare-judges"]')?.textContent).toContain("Only A retrieved anything"); + }); +}); diff --git a/apps/web/components/features/retrieval-test-dialog.tsx b/apps/web/components/features/retrieval-test-dialog.tsx index d8782321..cdac7506 100644 --- a/apps/web/components/features/retrieval-test-dialog.tsx +++ b/apps/web/components/features/retrieval-test-dialog.tsx @@ -6,12 +6,7 @@ import { useTranslations } from "next-intl"; import { toast } from "sonner"; import { useApp } from "@/components/features/app-shell"; -import { - api, - ApiError, - type EvalCompareResponse, - type EvalStrategyResult, -} from "@/lib/api"; +import { api, ApiError, type EvalCompareResponse } from "@/lib/api"; import { DEFAULT_SEARCH_STRATEGY, getSearchStrategiesDisabled, @@ -19,6 +14,11 @@ import { type SearchStrategy, } from "@/lib/retrieval-config"; import type { Section } from "@/lib/types"; +import { + ColumnResult, + JudgeVerdicts, + SectionRow, +} from "@/components/features/retrieval-compare-parts"; import { RetrievalStatus } from "@/components/features/retrieval-status"; import { Button } from "@/components/ui/button"; import { Spinner } from "@/components/ui/spinner"; @@ -379,164 +379,12 @@ function CompareColumns({ />
-
- {data.judges.length === 0 ? ( -

- {data.judge_reason || judgeMissingLabel} -

- ) : ( -
    - {data.judges.map((verdict, i) => { - const winner = - verdict.winner === "A" - ? strategyLabelFor(verdict.a_strategy) - : verdict.winner === "B" - ? strategyLabelFor(verdict.b_strategy) - : "tie"; - return ( -
  • - - - {winner} - - - {verdict.reason} - -
  • - ); - })} -
- )} -
-
- ); -} - -function ColumnResult({ - result, - label, - sectionLabel, - emptyLabel, -}: { - result: EvalStrategyResult | undefined; - label: string; - sectionLabel: string; - emptyLabel: string; -}) { - if (!result) return null; - return ( -
- -
- {label} - -
-
- {result.error ? ( -

- {result.error} -

- ) : result.sections.length === 0 ? ( -

- {emptyLabel} -

- ) : ( - result.sections.map((section, i) => ( - - )) - )} -
-
- ); -} - -function StatsPill({ stats }: { stats: Record }) { - const latency = pickNumber(stats, "latency_total_ms"); - const engineLatency = pickNumber(stats, "latency_engine_ms"); - const candidates = pickNumber(stats, "candidates"); - const relevant = pickNumber(stats, "relevant"); - const parts: string[] = []; - if (latency != null) parts.push(`${latency.toFixed(0)}ms`); - else if (engineLatency != null) parts.push(`${engineLatency.toFixed(0)}ms`); - if (candidates != null) parts.push(`cand=${candidates}`); - if (relevant != null) parts.push(`rel=${relevant}`); - const engineTimings = pickTimings(stats, "engine_timings"); - const topSteps = engineTimings - .filter(([key]) => !/\.total$/.test(key)) // total 已经在 pill 里 - .sort((a, b) => b[1] - a[1]) - .slice(0, 3); - if (parts.length === 0 && topSteps.length === 0) return null; - return ( -
- {parts.length > 0 && {parts.join(" · ")}} - {topSteps.length > 0 && ( - `${k}=${v.toFixed(0)}ms`).join("\n")}> - {topSteps.map(([k, v]) => `${shortStep(k)}=${v.toFixed(0)}ms`).join(" · ")} - - )} -
- ); -} - -function pickNumber(stats: Record, key: string): number | null { - const value = stats[key]; - return typeof value === "number" && Number.isFinite(value) ? value : null; -} - -function pickTimings(stats: Record, key: string): [string, number][] { - const value = stats[key]; - if (!value || typeof value !== "object") return []; - const entries: [string, number][] = []; - for (const [k, v] of Object.entries(value as Record)) { - if (typeof v === "number" && Number.isFinite(v)) entries.push([k, v]); - } - return entries; -} - -function shortStep(key: string): string { - // "multi_es.step5_fast_expand" → "step5_fast_expand";vector.embedding → embedding - const idx = key.indexOf("."); - return idx >= 0 ? key.slice(idx + 1) : key; -} - -function SectionRow({ - index, - section, - sectionLabel, -}: { - index: number; - section: Section; - sectionLabel: string; -}) { - return ( -
-
- - {index + 1} - - - {section.heading || sectionLabel} - - - {section.score.toFixed(4)} - -
-
-
-
-

- {section.content} -

+
); } diff --git a/apps/web/components/features/search/search-compare-results.test.tsx b/apps/web/components/features/search/search-compare-results.test.tsx new file mode 100644 index 00000000..3164e568 --- /dev/null +++ b/apps/web/components/features/search/search-compare-results.test.tsx @@ -0,0 +1,142 @@ +/** @vitest-environment jsdom */ +import * as React from "react"; +import { act } from "react"; +import { createRoot, type Root } from "react-dom/client"; +import { NextIntlClientProvider } from "next-intl"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +import messages from "@/messages/en-US.json"; +import type { EvalCompareResponse, EvalStrategyResult } from "@/lib/api"; +import type { Section } from "@/lib/types"; +import { + countChunkColumns, + SearchCompareResults, + type SearchCompareResultsProps, +} from "./search-compare-results"; + +function section(chunk: string, score: number): Section { + return { + chunk_id: chunk, heading: `Heading ${chunk}`, content: `Body ${chunk}`, score, rank: 1, + source_id: "src", source_name: "Manuals", + }; +} + +const vector: EvalStrategyResult = { + strategy: "vector", + sections: [section("c1", 0.9), section("c2", 0.8)], + stats: { latency_total_ms: 1234, requested_strategy: "vector", effective_strategy: "vector" }, + error: null, +}; +const sag2: EvalStrategyResult = { + strategy: "sag2", + sections: [section("c1", 0.95), section("c3", 0.7)], + stats: { + latency_total_ms: 2500, requested_strategy: "sag2", effective_strategy: "sag2", + jev_usage: { requests: 3, judgments: 12, input_tokens: 4096, output_tokens: null }, + sag2: { jev_ms: 1800, local_ms: 700, scope_chunks: 40, hops: 2 }, + }, + error: null, +}; +const failed: EvalStrategyResult = { strategy: "multi", sections: [], stats: {}, error: "boom" }; + +const data: EvalCompareResponse = { + query: "question", + results: [vector, sag2, failed], + judges: [{ a_strategy: "vector", b_strategy: "sag2", winner: "B", reason: "More complete" }], + judge_enabled: true, + judge_reason: null, +}; + +let root: Root; +let container: HTMLDivElement; +const onAdopt = vi.fn(); +const onOpenSection = vi.fn(); +const onRetry = vi.fn(); + +beforeEach(() => { + (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + onAdopt.mockClear(); onOpenSection.mockClear(); onRetry.mockClear(); + container = document.createElement("div"); document.body.append(container); root = createRoot(container); +}); +afterEach(async () => { await act(async () => root.unmount()); container.remove(); }); + +async function render(props: Partial = {}) { + await act(async () => root.render( + + + , + )); + return container; +} +const column = (strategy: string) => container.querySelector(`[data-testid="compare-column-${strategy}"]`)!; +const metrics = (strategy: string) => column(strategy).querySelector('[data-testid="compare-metrics"]')?.textContent ?? ""; + +describe("search compare results", () => { + it("renders one column per mode with a readable metrics strip", async () => { + await render(); + expect(metrics("vector")).toBe("1.2 s·2 hits"); + expect(metrics("sag2")).toBe("2.5 s·2 hits·JEV 3 requests · 12 judgments · 4,096 input tokens"); + expect(column("sag2").textContent).toContain("SAG2 evidence retrieval"); + expect(column("sag2").textContent).toContain("Paid"); + expect(column("vector").textContent).not.toContain("Paid"); + }); + it("shows a failed mode as a muted alert and does not offer to adopt it", async () => { + await render(); + expect(column("multi").querySelector('[role="alert"]')?.textContent).toBe("boom"); + expect(column("multi").querySelector('[data-testid="compare-adopt-multi"]')?.disabled).toBe(true); + expect(metrics("multi")).toBe("0 hits"); + }); + it("marks passages that two or more modes retrieved", async () => { + await render(); + const markers = [...container.querySelectorAll('[data-testid="compare-common-hit"]')]; + expect(markers).toHaveLength(2); + expect(column("vector").querySelectorAll('[data-testid="compare-common-hit"]')).toHaveLength(1); + expect(column("sag2").querySelectorAll('[data-testid="compare-common-hit"]')).toHaveLength(1); + expect(countChunkColumns(data.results).get("c1")).toBe(2); + expect(countChunkColumns(data.results).get("c2")).toBe(1); + }); + it("adopts a mode and opens a passage through the callbacks", async () => { + await render(); + await act(async () => column("vector").querySelector('[data-testid="compare-adopt-vector"]')!.click()); + expect(onAdopt).toHaveBeenCalledWith("vector"); + const rows = column("sag2").querySelectorAll("button"); + const passage = [...rows].find((button) => button.textContent?.includes("Heading c3"))!; + await act(async () => passage.click()); + expect(onOpenSection).toHaveBeenCalledWith(sag2.sections[1], 1, sag2); + }); + it("lists the pairwise verdicts, or the reason the judge did not run", async () => { + await render(); + const judges = container.querySelector('[data-testid="compare-judges"]')!; + expect(judges.textContent).toContain("SAG2 evidence retrieval"); + expect(judges.textContent).toContain("More complete"); + await render({ data: { ...data, judges: [], judge_enabled: false, judge_reason: "LLM not configured" } }); + expect(container.querySelector('[data-testid="compare-judges"]')?.textContent).toBe("LLM not configured"); + await render({ data: { ...data, judges: [], judge_reason: null } }); + expect(container.querySelector('[data-testid="compare-judges"]')?.textContent).toBe("No judge verdict was produced"); + }); + it("explains a changed execution under the column header", async () => { + const fallback: EvalStrategyResult = { + ...sag2, + stats: { ...sag2.stats, effective_strategy: "vector", fallback_used: true }, + }; + await render({ data: { ...data, results: [vector, fallback] } }); + expect(column("sag2").textContent).toContain("Requested: SAG2 evidence retrieval"); + expect(column("sag2").textContent).toContain("Actual: Coarse ranking"); + expect(column("vector").querySelector('[role="status"]')).toBeNull(); + }); + it("draws a busy column per pending mode and a retry when the whole request failed", async () => { + await render({ data: null, busy: true, pendingStrategies: ["vector", "sag2"] }); + expect(container.querySelectorAll('[aria-busy="true"]')).toHaveLength(2); + expect(column("sag2").textContent).toContain("SAG2 evidence retrieval"); + await render({ data: null, error: "service down" }); + expect(container.textContent).toContain("Comparison failed"); + expect(container.textContent).toContain("service down"); + const retry = [...container.querySelectorAll("button")].find((button) => button.textContent === "Retry")!; + await act(async () => retry.click()); + expect(onRetry).toHaveBeenCalledTimes(1); + }); +}); diff --git a/apps/web/components/features/search/search-compare-results.tsx b/apps/web/components/features/search/search-compare-results.tsx new file mode 100644 index 00000000..69732dec --- /dev/null +++ b/apps/web/components/features/search/search-compare-results.tsx @@ -0,0 +1,299 @@ +"use client"; + +import * as React from "react"; +import { useLocale, useTranslations } from "next-intl"; +import { Search as SearchIcon, Trophy } from "lucide-react"; + +import type { EvalCompareResponse, EvalStrategyResult } from "@/lib/api"; +import { + getSearchStrategy, + isJevScoredStrategy, + SEARCH_STRATEGY_ICONS, + type SearchStrategy, +} from "@/lib/retrieval-config"; +import type { Section } from "@/lib/types"; +import { cn } from "@/lib/utils"; +import { EmptyState } from "@/components/features/empty-state"; +import { + JudgeVerdicts, + pickNumber, + SectionRow, + strategyBadgeClassName, +} from "@/components/features/retrieval-compare-parts"; +import { RetrievalStatus } from "@/components/features/retrieval-status"; +import { Button } from "@/components/ui/button"; +import { Skeleton } from "@/components/ui/skeleton"; + +function record(value: unknown): Record { + return value !== null && typeof value === "object" && !Array.isArray(value) + ? value as Record + : {}; +} + +/** True when the server ran something other than the requested mode. */ +function executionChanged(result: EvalStrategyResult): boolean { + const { stats } = result; + if (stats.fallback_used === true || Boolean(record(stats.ranking).fallback_reason)) return true; + const requested = typeof stats.requested_strategy === "string" ? stats.requested_strategy : result.strategy; + const effective = typeof stats.effective_strategy === "string" ? stats.effective_strategy : requested; + return requested !== effective; +} + +/** Count how many columns retrieved each chunk so shared hits can be marked. */ +export function countChunkColumns(results: ReadonlyArray): Map { + const counts = new Map(); + for (const column of results) { + const seen = new Set(); + for (const section of column.sections) { + if (section.chunk_id) seen.add(section.chunk_id); + } + for (const chunkId of seen) counts.set(chunkId, (counts.get(chunkId) ?? 0) + 1); + } + return counts; +} + +function gridClassName(count: number, compact: boolean): string { + if (compact || count <= 1) return "grid-cols-1"; + return count >= 3 ? "grid-cols-1 md:grid-cols-3" : "grid-cols-1 md:grid-cols-2"; +} + +function ColumnHeading({ strategy }: { strategy: SearchStrategy }) { + const strategies = useTranslations("SearchStrategies"); + const entry = getSearchStrategy(strategy); + const Icon = SEARCH_STRATEGY_ICONS[entry.value]; + return ( + + + {strategies(entry.labelKey)} + {isJevScoredStrategy(entry.value) && ( + {strategies("paid")} + )} + + ); +} + +function MetricsStrip({ result }: { result: EvalStrategyResult }) { + const t = useTranslations("Search"); + const locale = useLocale(); + const format = (value: number) => value.toLocaleString(locale); + const latency = pickNumber(result.stats, "latency_total_ms") ?? pickNumber(result.stats, "latency_engine_ms"); + const usage = record(result.stats.jev_usage); + const requests = pickNumber(usage, "requests"); + const judgments = pickNumber(usage, "judgments"); + const inputTokens = pickNumber(usage, "input_tokens"); + const parts: string[] = []; + if (latency !== null) parts.push(t("compareLatency", { seconds: (latency / 1000).toFixed(1) })); + parts.push(t("compareHits", { count: result.sections.length })); + if (requests !== null && judgments !== null) { + parts.push(t("compareUsage", { + requests: format(requests), + judgments: format(judgments), + tokens: inputTokens === null ? "" : t("compareUsageTokens", { tokens: format(inputTokens) }), + })); + } + return ( +

+ {parts.map((part, index) => ( + + {index > 0 && } + {part} + + ))} +

+ ); +} + +function CompareColumn({ + result, + chunkColumns, + onAdopt, + onOpenSection, +}: { + result: EvalStrategyResult; + chunkColumns: Map; + onAdopt: (strategy: SearchStrategy) => void; + onOpenSection: (section: Section, index: number, column: EvalStrategyResult) => void; +}) { + const t = useTranslations("Search"); + // The strip already reports JEV usage; keep the status box for execution changes only. + const statusStats = React.useMemo(() => { + const { jev_usage: _usage, ...rest } = result.stats; + void _usage; + return rest; + }, [result.stats]); + return ( +
+
+
+ + +
+ +
+ {!result.error && executionChanged(result) && ( + + )} + {result.error ? ( +

+ {result.error} +

+ ) : result.sections.length === 0 ? ( +

{t("compareEmpty")}

+ ) : ( +
+ {result.sections.map((section, index) => ( + = 2 ? ( + + {t("commonHit")} + + ) : undefined} + onClick={() => onOpenSection(section, index, result)} + /> + ))} +
+ )} +
+ ); +} + +function BusyColumn({ strategy }: { strategy: SearchStrategy }) { + return ( +
+ + + {Array.from({ length: 4 }).map((_, index) => ( + + ))} +
+ ); +} + +export interface SearchCompareResultsProps { + data: EvalCompareResponse | null; + busy: boolean; + /** Modes in flight, used for the skeleton columns while busy. */ + pendingStrategies: ReadonlyArray; + /** Whole-request failure (as opposed to one mode's `error`). */ + error: string | null; + compact: boolean; + onAdopt: (strategy: SearchStrategy) => void; + onOpenSection: (section: Section, index: number, column: EvalStrategyResult) => void; + onRetry: () => void; +} + +/** Side-by-side columns for 2–3 retrieval modes plus the pairwise LLM verdicts. */ +export function SearchCompareResults({ + data, + busy, + pendingStrategies, + error, + compact, + onAdopt, + onOpenSection, + onRetry, +}: SearchCompareResultsProps) { + const t = useTranslations("Search"); + const strategies = useTranslations("SearchStrategies"); + const strategyLabelFor = React.useCallback( + (value: SearchStrategy) => strategies(getSearchStrategy(value).labelKey), + [strategies], + ); + const chunkColumns = React.useMemo( + () => countChunkColumns(data?.results ?? []), + [data], + ); + + if (busy) { + return ( +
+ {pendingStrategies.map((strategy) => ( + + ))} +
+ ); + } + + if (error) { + return ( + + {t("retry")} + + )} + /> + ); + } + + if (!data) return null; + + return ( +
+
+ {data.results.map((result) => ( + + ))} +
+
+

+ + {t("judgeToggle")} +

+ +
+
+ ); +} diff --git a/apps/web/components/features/search/search-panel-compare.test.tsx b/apps/web/components/features/search/search-panel-compare.test.tsx new file mode 100644 index 00000000..16fca9d4 --- /dev/null +++ b/apps/web/components/features/search/search-panel-compare.test.tsx @@ -0,0 +1,219 @@ +/** @vitest-environment jsdom */ +import * as React from "react"; +import { act } from "react"; +import { createRoot, type Root } from "react-dom/client"; +import { NextIntlClientProvider } from "next-intl"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +import messages from "@/messages/en-US.json"; +import type { EvalCompareResponse } from "@/lib/api"; +import type { Capabilities, Section } from "@/lib/types"; +import { TooltipProvider } from "@/components/ui/tooltip"; +import { SearchPanel } from "./search-panel"; +import { SearchProvider, useSearchWorkspace } from "./search-provider"; + +const state = vi.hoisted(() => ({ capabilities: {} as Partial })); +const detail = vi.hoisted(() => ({ open: vi.fn() })); +vi.mock("@/components/features/app-shell", () => ({ useApp: () => state })); +vi.mock("@/components/features/detail-panel", () => ({ useDetailPanel: () => detail })); +vi.mock("next/dynamic", () => ({ default: () => () => null })); +vi.mock("sonner", () => ({ toast: { success: vi.fn(), error: vi.fn() } })); +vi.mock("next/link", () => ({ + default: React.forwardRef>( + function Link({ children, href, ...props }, ref) { return {children}; }, + ), +})); + +function section(chunk: string, score: number): Section { + return { chunk_id: chunk, heading: `Heading ${chunk}`, content: `Body ${chunk}`, score, rank: 1, source_id: "src", source_name: "Manuals" }; +} +const compareResponse: EvalCompareResponse = { + query: "question", + results: [ + { strategy: "multi", sections: [section("c1", 0.8)], stats: { latency_total_ms: 900 }, error: null }, + { strategy: "sag2", sections: [section("c1", 0.9), section("c2", 0.7)], stats: { latency_total_ms: 2100 }, error: null }, + ], + judges: [], + judge_enabled: true, + judge_reason: null, +}; + +let root: Root; +let container: HTMLDivElement; +let compareRequests: Array>; +let searchRequests: Array>; +let workspace: ReturnType; + +function Capture() { + workspace = useSearchWorkspace(); + return null; +} + +beforeEach(() => { + (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + state.capabilities = { + llm_configured: true, search_strategy: "vector", + search_strategies: ["vector", "multi_es_fast", "multi", "multi_jev", "sag2"], + }; + detail.open.mockClear(); + compareRequests = []; searchRequests = []; + vi.stubGlobal("fetch", async (url: RequestInfo | URL, options?: RequestInit) => { + const target = String(url); + if (target.includes("/sources")) return Response.json([]); + if (target.includes("/activity")) return Response.json([]); + if (target.includes("/search/eval-compare")) { + compareRequests.push(JSON.parse(String(options?.body))); + return Response.json(compareResponse); + } + if (target.includes("/search")) { + searchRequests.push(JSON.parse(String(options?.body))); + return Response.json({ error: { code: "boom", message: "stopped" } }, { status: 500 }); + } + return Response.json({}); + }); + vi.stubGlobal("ResizeObserver", class { observe() {} unobserve() {} disconnect() {} }); + container = document.createElement("div"); document.body.append(container); root = createRoot(container); +}); +afterEach(async () => { await act(async () => root.unmount()); container.remove(); vi.unstubAllGlobals(); }); + +async function render() { + await act(async () => root.render( + + + + + + + + , + )); +} +const byTestId = (id: string) => container.querySelector(`[data-testid="${id}"]`); +const chip = (strategy: string) => byTestId(`search-compare-chip-${strategy}`) as HTMLButtonElement | null; +const chipState = (strategy: string) => chip(strategy)?.getAttribute("data-state"); +async function click(element: HTMLElement | null) { + expect(element).not.toBeNull(); + await act(async () => element!.click()); +} +async function typeQuery(value: string) { + const input = container.querySelector('input[type="text"]')!; + const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!; + await act(async () => { + setter.call(input, value); + input.dispatchEvent(new Event("input", { bubbles: true })); + }); +} +async function submit() { + await act(async () => container.querySelector("form")!.requestSubmit()); +} + +describe("search compare mode", () => { + it("replaces the mode control with 2–3 chips seeded from the current mode", async () => { + await render(); + expect(byTestId("search-strategy")).not.toBeNull(); + expect(byTestId("search-compare-config")).toBeNull(); + await click(byTestId("search-compare-toggle")); + expect(byTestId("search-strategy")).toBeNull(); + expect(container.querySelectorAll('[data-testid^="search-compare-chip-"]')).toHaveLength(5); + expect(chipState("vector")).toBe("on"); + expect(chipState("sag2")).toBe("on"); + expect(chipState("multi")).toBe("off"); + expect(chip("sag2")?.textContent).toContain("Paid"); + expect(chip("vector")?.textContent).not.toContain("Paid"); + expect(byTestId("search-compare-hint")?.textContent).toBe("Pick 2–3 modes to compare side by side with the same question"); + + await click(chip("multi")); + expect(chipState("multi")).toBe("on"); + expect(chip("multi_jev")?.disabled).toBe(true); + expect(chip("multi_es_fast")?.disabled).toBe(true); + await click(chip("vector")); + expect(chipState("vector")).toBe("off"); + expect(chip("multi_jev")?.disabled).toBe(false); + // Two is the floor: deselecting one of the remaining pair is ignored. + await click(chip("sag2")); + expect(chipState("sag2")).toBe("on"); + expect(chipState("multi")).toBe("on"); + }); + + it("omits modes the deployment cannot serve", async () => { + state.capabilities = { + ...state.capabilities, + search_strategies_disabled: { sag2: { reason: "jev_api_key_missing", message: "Add a key" } }, + }; + await render(); + await click(byTestId("search-compare-toggle")); + expect(chip("sag2")).toBeNull(); + expect(chipState("vector")).toBe("on"); + expect(chipState("multi_jev")).toBe("on"); + }); + + it("runs eval-compare with the query, chips, scope and judge, then adopts a mode", async () => { + await render(); + await act(async () => workspace.setScope([{ id: "a", name: "Alpha" }])); + await click(byTestId("search-compare-toggle")); + await click(chip("multi")); + await click(chip("vector")); + // The scope chips move under the mode chips while comparing. + expect(byTestId("search-compare-config")?.textContent).toContain("Alpha"); + expect(byTestId("search-compare-judge")?.getAttribute("data-state")).toBe("checked"); + await typeQuery("question"); + await submit(); + expect(compareRequests).toEqual([ + { query: "question", strategies: ["multi", "sag2"], source_ids: ["a"], top_k: 12, judge: true }, + ]); + expect(searchRequests).toEqual([]); + const results = byTestId("search-compare-results")!; + expect(results.querySelector('[data-testid="compare-column-multi"]')).not.toBeNull(); + expect(results.querySelector('[data-testid="compare-column-sag2"]')).not.toBeNull(); + expect(results.querySelectorAll('[data-testid="compare-common-hit"]')).toHaveLength(2); + + await click(byTestId("compare-adopt-sag2")); + expect(byTestId("search-compare-config")).toBeNull(); + expect(workspace.strategy).toBe("sag2"); + expect(workspace.strategyOrigin).toBe("pinned"); + expect(searchRequests).toEqual([ + expect.objectContaining({ query: "question", strategy: "sag2", source_ids: ["a"] }), + ]); + expect(byTestId("search-strategy")?.textContent).toContain("SAG2 evidence retrieval"); + }); + + it("hides the judge switch without an LLM and sends judge=false", async () => { + state.capabilities = { ...state.capabilities, llm_configured: false }; + await render(); + await click(byTestId("search-compare-toggle")); + expect(byTestId("search-compare-judge")).toBeNull(); + expect(byTestId("search-compare-config")?.textContent).toContain("Scope: all knowledge"); + await typeQuery("question"); + await submit(); + expect(compareRequests).toEqual([ + { query: "question", strategies: ["vector", "sag2"], top_k: 12, judge: false }, + ]); + }); + + it("keeps the last normal result while compare is on and restores it when off", async () => { + await render(); + await typeQuery("question"); + await submit(); + expect(searchRequests).toHaveLength(1); + expect(container.textContent).toContain("Search did not complete"); + await click(byTestId("search-compare-toggle")); + expect(container.textContent).not.toContain("Search did not complete"); + expect(container.textContent).toContain("Enter a question and press Enter to compare"); + await click(byTestId("search-compare-toggle")); + expect(container.textContent).toContain("Search did not complete"); + expect(searchRequests).toHaveLength(1); + }); + + it("opens a compared passage through the detail panel", async () => { + await render(); + await click(byTestId("search-compare-toggle")); + await typeQuery("question"); + await submit(); + const passage = [...container.querySelectorAll('[data-testid="compare-column-sag2"] button')] + .find((button) => button.textContent?.includes("Heading c2"))!; + await click(passage); + expect(detail.open).toHaveBeenCalledWith({ + kind: "chunk", sourceId: "src", chunkId: "c2", heading: "Heading c2", sourceName: "Manuals", + }); + }); +}); diff --git a/apps/web/components/features/search/search-panel.tsx b/apps/web/components/features/search/search-panel.tsx index decd1834..1a8db4d1 100644 --- a/apps/web/components/features/search/search-panel.tsx +++ b/apps/web/components/features/search/search-panel.tsx @@ -5,19 +5,25 @@ import dynamic from "next/dynamic"; import { useTranslations } from "next-intl"; import { Clock, + Columns2, History, Library, List, Search as SearchIcon, Sparkles, + Trophy, Waypoints, X, } from "lucide-react"; import { toast } from "sonner"; +import type { EvalStrategyResult } from "@/lib/api"; import { getSearchStrategy, getSearchStrategiesDisabled, + isJevScoredStrategy, + SEARCH_STRATEGIES, + SEARCH_STRATEGY_ICONS, type SearchStrategy, } from "@/lib/retrieval-config"; import type { SearchResultSort } from "@/lib/search-result-sort"; @@ -28,6 +34,7 @@ import type { Citation, SearchEvent, SearchResponse, + Section, Source, } from "@/lib/types"; import { useApp } from "@/components/features/app-shell"; @@ -45,9 +52,17 @@ import { SearchSummaryCard, sectionCitation, } from "@/components/features/search/search-panel-sections"; +import { SearchCompareResults } from "@/components/features/search/search-compare-results"; +import { + COMPARE_MAX_STRATEGIES, + COMPARE_MIN_STRATEGIES, + useSearchCompare, +} from "@/components/features/search/use-search-compare"; import { SearchStrategyControl } from "@/components/features/search-strategy-control"; +import { strategyBadgeClassName } from "@/components/features/retrieval-compare-parts"; import { EmptyState } from "@/components/features/empty-state"; import { Skeleton } from "@/components/ui/skeleton"; +import { Switch } from "@/components/ui/switch"; import { Toggle } from "@/components/ui/toggle"; import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"; import { @@ -135,6 +150,18 @@ export function SearchPanel({ const hydrationKeyRef = React.useRef(""); const contentView = search.contentView; const changeContentView = search.setContentView; + const disabledMap = React.useMemo( + () => getSearchStrategiesDisabled(capabilities, searchStrategies("unsupportedBackend")), + [capabilities, searchStrategies], + ); + const enabledStrategies = React.useMemo( + () => SEARCH_STRATEGIES.map((item) => item.value).filter((value) => !disabledMap[value]), + [disabledMap], + ); + const compare = useSearchCompare({ + enabledStrategies, + judgeAvailable: Boolean(capabilities?.llm_configured), + }); const executeSearch = React.useCallback( async (options: { @@ -167,6 +194,62 @@ export function SearchPanel({ [changeContentView, onSearchComplete, onSearchError, onSearchStart, search, t], ); + const compareRun = compare.run; + const runCompare = React.useCallback(async (query?: string) => { + const text = (query ?? search.query).trim(); + if (!text) return null; + setMentionOpen(false); + changeContentView("results"); + // Same scope resolution as the normal search: no scope means every source. + return compareRun({ + query: text, + sourceIds: search.scoped.length ? search.scoped.map((source) => source.id) : undefined, + topK: search.topK, + }); + }, [changeContentView, compareRun, search.query, search.scoped, search.topK]); + + function toggleCompare(on: boolean) { + if (on) compare.enable(search.strategy); + else compare.disable(); + } + + /** Pin the compared mode and land in the regular results with the same question. */ + function adoptStrategy(strategy: SearchStrategy) { + const query = (compare.result?.query || compare.lastQuery || search.query).trim(); + search.setStrategy(strategy); + compare.disable(); + if (!query) return; + search.setQuery(query); + void executeSearch({ query, strategy, saveExploration: false }); + } + + /** A compared passage opens through the same detail flow as the normal list. */ + function openCompareSection(section: Section, index: number, column: EvalStrategyResult) { + const citation = sectionCitation(section, index); + if (onCitationClick) { + onCitationClick(citation, { + query: compare.result?.query ?? compare.lastQuery, + sections: column.sections, + events: [], + entities: [], + relations: [], + source_hits: [], + summary: "", + exploration_id: null, + stats: column.stats, + }); + return; + } + if (!section.chunk_id || !section.source_id) return; + open({ + kind: "chunk", + sourceId: section.source_id, + chunkId: section.chunk_id, + heading: section.heading, + sourceName: section.source_name ?? undefined, + }); + } + const activitySourceIds = React.useMemo( () => search.scoped.map((source) => source.id).sort(), [search.scoped], @@ -286,6 +369,10 @@ export function SearchPanel({ async function run(e?: React.FormEvent) { e?.preventDefault(); + if (compare.enabled) { + await runCompare(); + return; + } await executeSearch({ saveExploration: false, }); @@ -301,7 +388,7 @@ export function SearchPanel({ } const activeView = showGraphView ? view : "list"; - const graphViewActive = activeView === "graph" && Boolean(search.result?.events.length); + const graphViewActive = !compare.enabled && activeView === "graph" && Boolean(search.result?.events.length); const citations = React.useMemo( () => search.result?.sections.map(sectionCitation) ?? [], [search.result], @@ -328,6 +415,24 @@ export function SearchPanel({ current: currentViewLabel, next: nextViewLabel, }); + // In compare mode the scope chips move under the mode chips so the input keeps its room. + const scopeChips = search.scoped.map((sc) => ( + + + {sc.name} + + + )); return (
- {search.scoped.map((sc) => ( - - - {sc.name} - - - ))} + {!compare.enabled && scopeChips} { const cancelledSearch = search.busy; search.clear(); + compare.reset(); if (cancelledSearch) onSearchCancel?.(); setMentionOpen(false); inputRef.current?.focus(); @@ -438,13 +529,26 @@ export function SearchPanel({ )} - + + + {t("compare")} + + {!compare.enabled && ( + + )}
{mentionOpen && (
@@ -490,6 +594,7 @@ export function SearchPanel({ type="button" onClick={() => { search.cancel(); + compare.cancel(); onSearchCancel?.(); onCancel?.(); }} @@ -499,6 +604,63 @@ export function SearchPanel({ )}
+ {compare.enabled && ( +
+
+ + {enabledStrategies.map((value) => { + const Icon = SEARCH_STRATEGY_ICONS[value]; + const on = compare.strategies.includes(value); + return ( + = COMPARE_MAX_STRATEGIES} + data-testid={`search-compare-chip-${value}`} + className="h-7 min-w-0 gap-1.5 rounded-full border border-border bg-transparent px-2.5 text-xs font-normal text-muted-foreground hover:text-foreground data-[state=on]:border-primary/40 data-[state=on]:bg-primary/10 data-[state=on]:text-primary [&_svg]:size-3.5" + > + + {searchStrategies(getSearchStrategy(value).labelKey)} + {isJevScoredStrategy(value) && ( + {searchStrategies("paid")} + )} + + ); + })} + + + {compare.strategies.length < COMPARE_MIN_STRATEGIES ? t("compareMin") : t("compareHint")} + +
+
+ {compare.judgeAvailable && ( + + )} +
+ {search.scoped.length ? scopeChips : {t("compareScopeAll")}} +
+
+
+ )} {showRecentActivity && showContentSwitcher && ( @@ -516,7 +678,7 @@ export function SearchPanel({ {t("history")} @@ -524,7 +686,7 @@ export function SearchPanel({ {t("recentActivity")} @@ -533,7 +695,44 @@ export function SearchPanel({
)} - {contentView === "results" && search.busy && search.result === null ? ( + {compare.enabled && contentView === "results" ? ( +
+ {compare.busy || compare.result || compare.error ? ( + <> +
+

+ {t("results")} + + + {t("compare")} + +

+ {!compact && compare.lastQuery && ( + {compare.lastQuery} + )} +
+ void runCompare(compare.lastQuery)} + /> + + ) : ( +
+
+ +

{t("compareStartTitle")}

+

{t("compareHint")}

+
+
+ )} +
+ ) : contentView === "results" && search.busy && search.result === null ? (
diff --git a/apps/web/components/features/search/use-search-compare.test.ts b/apps/web/components/features/search/use-search-compare.test.ts new file mode 100644 index 00000000..c72f4227 --- /dev/null +++ b/apps/web/components/features/search/use-search-compare.test.ts @@ -0,0 +1,58 @@ +import { describe, expect, it } from "vitest"; + +import type { SearchStrategy } from "@/lib/retrieval-config"; +import { + COMPARE_MAX_STRATEGIES, + COMPARE_MIN_STRATEGIES, + defaultCompareStrategies, + selectCompareStrategies, + sortCompareStrategies, +} from "./use-search-compare"; + +const all: SearchStrategy[] = ["vector", "multi_es_fast", "multi", "multi_jev", "sag2"]; + +describe("default compare selection", () => { + it("pairs the current mode with sag2 when it is enabled", () => { + expect(defaultCompareStrategies("vector", all)).toEqual(["vector", "sag2"]); + expect(defaultCompareStrategies("multi", all)).toEqual(["multi", "sag2"]); + }); + it("falls back to multi_jev, then multi, when sag2 is unavailable", () => { + expect(defaultCompareStrategies("vector", ["vector", "multi", "multi_jev"])).toEqual(["vector", "multi_jev"]); + expect(defaultCompareStrategies("vector", ["vector", "multi_es_fast", "multi"])).toEqual(["vector", "multi"]); + }); + it("never pairs a mode with itself", () => { + expect(defaultCompareStrategies("sag2", all)).toEqual(["multi_jev", "sag2"]); + expect(defaultCompareStrategies("multi", ["vector", "multi"])).toEqual(["vector", "multi"]); + }); + it("uses any other enabled mode when no preferred alternative exists", () => { + expect(defaultCompareStrategies("vector", ["vector", "multi_es_fast"])).toEqual(["vector", "multi_es_fast"]); + }); + it("leaves a single pick when nothing else can be served", () => { + expect(defaultCompareStrategies("vector", ["vector"])).toEqual(["vector"]); + expect(defaultCompareStrategies("sag2", ["vector"])).toEqual(["vector"]); + }); +}); + +describe("compare selection bounds", () => { + it("accepts two or three enabled modes in catalog order", () => { + expect(selectCompareStrategies(["vector", "sag2"], ["sag2", "multi", "vector"], all)).toEqual(["vector", "multi", "sag2"]); + expect(selectCompareStrategies(["vector", "multi", "sag2"], ["multi", "sag2"], all)).toEqual(["multi", "sag2"]); + }); + it("keeps the previous picks when the change would leave fewer than two", () => { + expect(selectCompareStrategies(["vector", "sag2"], ["sag2"], all)).toEqual(["vector", "sag2"]); + expect(selectCompareStrategies(["vector", "sag2"], [], all)).toEqual(["vector", "sag2"]); + }); + it("keeps the previous picks when the change would exceed three", () => { + expect(selectCompareStrategies(["vector", "multi", "sag2"], ["vector", "multi", "multi_jev", "sag2"], all)) + .toEqual(["vector", "multi", "sag2"]); + }); + it("drops unknown and disabled values before applying the bounds", () => { + expect(selectCompareStrategies(["vector", "multi"], ["vector", "multi", "bogus", "sag2"], ["vector", "multi"])) + .toEqual(["vector", "multi"]); + }); + it("exposes the 2–3 bounds used by the chips", () => { + expect(COMPARE_MIN_STRATEGIES).toBe(2); + expect(COMPARE_MAX_STRATEGIES).toBe(3); + expect(sortCompareStrategies(["sag2", "vector"])).toEqual(["vector", "sag2"]); + }); +}); diff --git a/apps/web/components/features/search/use-search-compare.ts b/apps/web/components/features/search/use-search-compare.ts new file mode 100644 index 00000000..94bde25e --- /dev/null +++ b/apps/web/components/features/search/use-search-compare.ts @@ -0,0 +1,212 @@ +"use client"; + +import * as React from "react"; +import { useTranslations } from "next-intl"; + +import { api, ApiError, type EvalCompareResponse } from "@/lib/api"; +import { + isSearchStrategy, + SEARCH_STRATEGIES, + type SearchStrategy, +} from "@/lib/retrieval-config"; + +export const COMPARE_MIN_STRATEGIES = 2; +export const COMPARE_MAX_STRATEGIES = 3; + +/** The alternative that differs most from a typical pick, in order of preference. */ +const PREFERRED_ALTERNATIVES: readonly SearchStrategy[] = ["sag2", "multi_jev", "multi"]; + +/** Keep chips and columns in catalog order regardless of click order. */ +export function sortCompareStrategies( + values: ReadonlyArray, +): SearchStrategy[] { + const picked = new Set(values); + return SEARCH_STRATEGIES.map((item) => item.value).filter((value) => picked.has(value)); +} + +/** + * Seed the compare selection: the mode the user already has, plus the enabled + * mode that behaves most differently from it (sag2 → multi_jev → multi). + */ +export function defaultCompareStrategies( + current: SearchStrategy, + enabled: ReadonlyArray, +): SearchStrategy[] { + const picks: SearchStrategy[] = enabled.includes(current) ? [current] : []; + const alternative = PREFERRED_ALTERNATIVES.find( + (value) => value !== current && enabled.includes(value), + ) ?? enabled.find((value) => value !== current); + if (alternative) picks.push(alternative); + return sortCompareStrategies(picks); +} + +/** + * Apply a toggle-group change while enforcing 2–3 picks: a change that would + * leave the group outside that range is ignored and the previous picks stay. + */ +export function selectCompareStrategies( + current: ReadonlyArray, + next: ReadonlyArray, + enabled: ReadonlyArray, +): SearchStrategy[] { + const valid = sortCompareStrategies( + next.filter((value): value is SearchStrategy => isSearchStrategy(value) && enabled.includes(value)), + ); + if (valid.length < COMPARE_MIN_STRATEGIES || valid.length > COMPARE_MAX_STRATEGIES) { + return sortCompareStrategies(current); + } + return valid; +} + +export interface SearchCompareRunOptions { + query: string; + sourceIds?: string[]; + topK?: number; +} + +export interface SearchCompareState { + /** Compare mode is on: the search box runs eval-compare instead of a normal search. */ + enabled: boolean; + /** Selected modes, filtered to what the deployment can serve. */ + strategies: SearchStrategy[]; + /** Whether an LLM judge can run at all on this deployment. */ + judgeAvailable: boolean; + /** Effective judge flag sent with the request. */ + judge: boolean; + busy: boolean; + /** Modes of the request in flight, so busy columns can be drawn. */ + pendingStrategies: SearchStrategy[]; + result: EvalCompareResponse | null; + error: string | null; + lastQuery: string; + canRun: boolean; + enable: (current: SearchStrategy) => void; + disable: () => void; + selectStrategies: (values: ReadonlyArray) => void; + setJudge: (judge: boolean) => void; + run: (options: SearchCompareRunOptions) => Promise; + cancel: () => void; + reset: () => void; +} + +/** + * Local state for the side-by-side compare on the search page. It never + * touches the normal search lifecycle in SearchProvider, so toggling compare + * off brings the previous normal result straight back. + */ +export function useSearchCompare({ + enabledStrategies, + judgeAvailable, +}: { + enabledStrategies: ReadonlyArray; + judgeAvailable: boolean; +}): SearchCompareState { + const t = useTranslations("Search"); + const [enabled, setEnabled] = React.useState(false); + const [selected, setSelected] = React.useState([]); + const [judgeChoice, setJudgeChoice] = React.useState(true); + const [busy, setBusy] = React.useState(false); + const [pendingStrategies, setPendingStrategies] = React.useState([]); + const [result, setResult] = React.useState(null); + const [error, setError] = React.useState(null); + const [lastQuery, setLastQuery] = React.useState(""); + const abortRef = React.useRef(null); + + const enabledKey = enabledStrategies.join("\u0000"); + const strategies = React.useMemo( + () => selected.filter((value) => enabledStrategies.includes(value)), + // eslint-disable-next-line react-hooks/exhaustive-deps + [selected, enabledKey], + ); + const judge = judgeAvailable && judgeChoice; + + const cancel = React.useCallback(() => { + abortRef.current?.abort(); + abortRef.current = null; + setBusy(false); + }, []); + + React.useEffect(() => () => { + abortRef.current?.abort(); + }, []); + + const enable = React.useCallback((current: SearchStrategy) => { + setSelected(defaultCompareStrategies(current, enabledStrategies)); + setEnabled(true); + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [enabledKey]); + + const disable = React.useCallback(() => { + cancel(); + setEnabled(false); + }, [cancel]); + + const selectStrategies = React.useCallback((values: ReadonlyArray) => { + setSelected((current) => selectCompareStrategies(current, values, enabledStrategies)); + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [enabledKey]); + + const reset = React.useCallback(() => { + cancel(); + setResult(null); + setError(null); + setLastQuery(""); + setPendingStrategies([]); + }, [cancel]); + + const run = React.useCallback(async ({ query, sourceIds, topK }: SearchCompareRunOptions) => { + const text = query.trim(); + if (!text || strategies.length < COMPARE_MIN_STRATEGIES) return null; + abortRef.current?.abort(); + const controller = new AbortController(); + abortRef.current = controller; + setBusy(true); + setError(null); + setResult(null); + setLastQuery(text); + setPendingStrategies(strategies); + try { + const response = await api.evalCompare({ + query: text, + strategies, + source_ids: sourceIds, + top_k: topK, + judge, + }, controller.signal); + if (abortRef.current !== controller) return null; + setResult(response); + return response; + } catch (caught) { + if (abortRef.current !== controller) return null; + if (!(caught instanceof ApiError && caught.code === "aborted")) { + setError(caught instanceof ApiError ? caught.message : t("compareFailed")); + } + return null; + } finally { + if (abortRef.current === controller) { + abortRef.current = null; + setBusy(false); + } + } + }, [judge, strategies, t]); + + return { + enabled, + strategies, + judgeAvailable, + judge, + busy, + pendingStrategies, + result, + error, + lastQuery, + canRun: !busy && strategies.length >= COMPARE_MIN_STRATEGIES, + enable, + disable, + selectStrategies, + setJudge: setJudgeChoice, + run, + cancel, + reset, + }; +} diff --git a/apps/web/messages/en-US.json b/apps/web/messages/en-US.json index 694ff202..38266835 100644 --- a/apps/web/messages/en-US.json +++ b/apps/web/messages/en-US.json @@ -1303,7 +1303,26 @@ "startTitle": "Enter a question to start searching", "startDescription": "Answers use only relevance-ranked evidence and preserve clickable references.", "emptyGraph": "No event–entity relationships to display", - "emptyGraphDescription": "The matching events are not linked to entities yet. Switch to the list to view event summaries." + "emptyGraphDescription": "The matching events are not linked to entities yet. Switch to the list to view event summaries.", + "compare": "Compare", + "compareAria": "Compare retrieval modes side by side", + "compareModesAria": "Modes to compare", + "compareHint": "Pick 2–3 modes to compare side by side with the same question", + "compareMin": "Pick at least 2 modes to compare", + "compareScopeAll": "Scope: all knowledge", + "compareStartTitle": "Enter a question and press Enter to compare", + "compareRunning": "Running the modes side by side…", + "compareEmpty": "Nothing was retrieved", + "compareFailed": "Comparison failed", + "compareLatency": "{seconds} s", + "compareHits": "{count, plural, one {# hit} other {# hits}}", + "compareUsage": "JEV {requests} requests · {judgments} judgments{tokens}", + "compareUsageTokens": " · {tokens} input tokens", + "judgeToggle": "LLM judge", + "judgeMissing": "No judge verdict was produced", + "judgeTie": "Tie", + "adoptMode": "Search with this mode", + "commonHit": "Shared hit" }, "Graph": { "layout": "Graph layout", diff --git a/apps/web/messages/zh-CN.json b/apps/web/messages/zh-CN.json index 82ea6899..1f241476 100644 --- a/apps/web/messages/zh-CN.json +++ b/apps/web/messages/zh-CN.json @@ -1303,7 +1303,26 @@ "startTitle": "输入问题开始搜索", "startDescription": "回答只会使用经过相关性重排的证据,并保留可点击引用。", "emptyGraph": "没有可展示的事件—实体关系", - "emptyGraphDescription": "当前命中的事件尚未关联实体,可切回列表查看事件摘要。" + "emptyGraphDescription": "当前命中的事件尚未关联实体,可切回列表查看事件摘要。", + "compare": "对比", + "compareAria": "并排对比多种检索模式", + "compareModesAria": "参与对比的检索模式", + "compareHint": "选择 2–3 种模式,用同一问题并排对比", + "compareMin": "至少选择 2 种模式才能对比", + "compareScopeAll": "范围:全部知识库", + "compareStartTitle": "输入问题,回车开始对比", + "compareRunning": "正在并排检索…", + "compareEmpty": "没有召回任何内容", + "compareFailed": "对比检索失败", + "compareLatency": "耗时 {seconds} s", + "compareHits": "召回 {count, number} 条", + "compareUsage": "JEV {requests} 次请求 · {judgments} 次判定{tokens}", + "compareUsageTokens": " · {tokens} token", + "judgeToggle": "LLM 评审", + "judgeMissing": "本次未生成评审结果", + "judgeTie": "平局", + "adoptMode": "按此模式检索", + "commonHit": "共同命中" }, "Graph": { "layout": "图谱布局", From 86c6c0abe494adda8c65509ad44fd0f4795f1804 Mon Sep 17 00:00:00 2001 From: luoshuai990529 <58510855+luoshuai990529@users.noreply.github.com> Date: Sun, 1 Nov 2026 22:03:56 +0800 Subject: [PATCH 5/5] =?UTF-8?q?feat(knowledge):=20=E5=9B=BA=E5=AE=9A?= =?UTF-8?q?=E4=BF=A1=E6=BA=90=E7=AE=97=E6=B3=95=E5=B9=B6=E8=B4=AF=E9=80=9A?= =?UTF-8?q?=20SAG2=20=E5=8E=9F=E7=94=9F=E5=85=A5=E5=BA=93=E4=B8=8E?= =?UTF-8?q?=E6=B7=B7=E5=90=88=E6=A3=80=E7=B4=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 9 +- README-CN.md | 10 +- README.md | 10 +- apps/api/.env.example | 8 +- apps/api/sag_api/api/v1/search.py | 5 +- apps/api/sag_api/core/db.py | 5 +- apps/api/sag_api/db/models/source.py | 3 + apps/api/sag_api/enums.py | 5 +- apps/api/sag_api/jobs/tasks.py | 5 +- apps/api/sag_api/sag/document_identity.py | 14 +- apps/api/sag_api/sag/engine_access.py | 2 +- apps/api/sag_api/sag/engine_manager.py | 76 ++++- apps/api/sag_api/sag/incremental_processor.py | 4 +- apps/api/sag_api/sag/sag2_engine.py | 2 +- apps/api/sag_api/sag/sag2_native_search.py | 70 +++++ apps/api/sag_api/sag/sag2_source_engine.py | 253 ++++++++++++++++ apps/api/sag_api/sag/search_reader.py | 8 +- apps/api/sag_api/schemas/source.py | 10 +- apps/api/sag_api/services/agent_tooling.py | 12 +- apps/api/sag_api/services/engine_routing.py | 102 +++++++ .../sag_api/services/knowledge_algorithms.py | 8 + .../sag_api/services/octx_conflict_service.py | 2 + apps/api/sag_api/services/octx_export.py | 4 + .../sag_api/services/octx_transfer_common.py | 5 +- .../api/sag_api/services/retrieval_service.py | 55 ++-- apps/api/sag_api/services/settings_service.py | 13 +- apps/api/sag_api/services/source_service.py | 23 +- apps/api/sag_api/tools/builtin.py | 32 +-- apps/api/tests/test_agent_tools.py | 18 +- apps/api/tests/test_chat_turn_strategy.py | 10 +- apps/api/tests/test_engine_routing.py | 89 ++++++ apps/api/tests/test_jev_config.py | 23 +- apps/api/tests/test_jev_retrieval.py | 5 +- apps/api/tests/test_jev_transports.py | 2 +- apps/api/tests/test_retrieval_relevance.py | 7 +- apps/api/tests/test_sag2_native_engine.py | 269 ++++++++++++++++++ apps/api/tests/test_sag2_octx_policy.py | 16 ++ apps/api/tests/test_sag2_retrieval.py | 14 +- apps/api/tests/test_search_strategy.py | 4 +- .../api/tests/test_source_default_strategy.py | 171 ++--------- apps/api/tests/test_source_engine_binding.py | 33 +++ apps/web/app/(app)/knowledge/[id]/page.tsx | 22 +- apps/web/components/features/app-shell.tsx | 8 +- .../features/chat/conversation-panel.test.tsx | 14 +- .../features/chat/conversation-panel.tsx | 14 +- .../web/components/features/document-list.tsx | 6 +- .../features/edit-source-dialog.test.tsx | 56 +--- .../features/edit-source-dialog.tsx | 81 +----- .../features/jev-mode-setup-dialog.test.tsx | 55 ++++ .../features/jev-mode-setup-dialog.tsx | 28 ++ .../features/knowledge-config-form.test.tsx | 28 +- .../features/knowledge-config-form.tsx | 11 +- .../features/knowledge-engine-pill.tsx | 14 + .../features/knowledge-source-workspace.tsx | 4 +- .../features/retrieval-mode-picker.test.tsx | 148 ---------- .../features/retrieval-mode-picker.tsx | 157 ---------- .../features/retrieval-mode-pill.tsx | 51 ---- .../features/retrieval-status.test.tsx | 8 + .../components/features/retrieval-status.tsx | 9 +- .../features/retrieval-test-dialog.tsx | 4 +- .../features/search-strategy-control.test.tsx | 2 +- .../features/search-strategy-control.tsx | 14 +- .../search/search-mixed-evidence.test.tsx | 26 ++ .../features/search/search-panel-sections.tsx | 2 +- .../features/search/search-panel.tsx | 2 +- .../features/search/search-provider.tsx | 11 +- .../search/search-scope-default.test.tsx | 24 +- .../components/features/source-card.test.tsx | 18 +- apps/web/components/features/source-card.tsx | 14 +- .../features/source-create-form.test.tsx | 85 +----- .../features/source-create-form.tsx | 91 ++---- .../features/source-engine-binding.test.tsx | 28 ++ apps/web/components/features/upload-zone.tsx | 6 +- apps/web/lib/api.ts | 1 + apps/web/lib/retrieval-config.test.ts | 19 +- apps/web/lib/retrieval-config.ts | 25 +- apps/web/lib/types.ts | 2 + apps/web/messages/en-US.json | 30 +- apps/web/messages/zh-CN.json | 40 ++- 79 files changed, 1491 insertions(+), 1083 deletions(-) create mode 100644 apps/api/sag_api/sag/sag2_native_search.py create mode 100644 apps/api/sag_api/sag/sag2_source_engine.py create mode 100644 apps/api/sag_api/services/engine_routing.py create mode 100644 apps/api/sag_api/services/knowledge_algorithms.py create mode 100644 apps/api/tests/test_engine_routing.py create mode 100644 apps/api/tests/test_sag2_native_engine.py create mode 100644 apps/api/tests/test_sag2_octx_policy.py create mode 100644 apps/api/tests/test_source_engine_binding.py create mode 100644 apps/web/components/features/jev-mode-setup-dialog.test.tsx create mode 100644 apps/web/components/features/jev-mode-setup-dialog.tsx create mode 100644 apps/web/components/features/knowledge-engine-pill.tsx delete mode 100644 apps/web/components/features/retrieval-mode-picker.test.tsx delete mode 100644 apps/web/components/features/retrieval-mode-picker.tsx delete mode 100644 apps/web/components/features/retrieval-mode-pill.tsx create mode 100644 apps/web/components/features/search/search-mixed-evidence.test.tsx create mode 100644 apps/web/components/features/source-engine-binding.test.tsx diff --git a/CHANGELOG.md b/CHANGELOG.md index 8bde45f2..3d51d317 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,11 +5,10 @@ ## Unreleased - 探索页新增「对比」:同一问题在 2–3 种检索模式下并排检索,显示耗时、召回数、SAG2 的 JEV 用量与共同命中的片段,可选 LLM 评审,并可一键按某一模式正式检索。 -- 问答页可为当前轮次选择检索模式:输入框工具栏新增与探索页一致的模式控件,默认显示将实际使用的模式及其来源(人格默认 / 信源默认 / 全局),用户选择后对后续轮次生效;付费 JEV 模式缺少 API Key 时在开始生成前拒绝并给出设置入口。回答的活动时间线显示本轮实际模式与来源。 -- 信源可设置「默认检索模式」:创建或编辑信源时选择快速、精确、JEV 精排或 SAG2 证据检索,并以通俗说明与付费提示帮助选择;JEV 模式缺少 API Key 时可在对话框内直接配置。搜索与问答在所选范围内信源一致时自动采用该默认(显式选择与 Agent 人格优先),结果 `stats.strategy_origin` 标明来源。不改变文档入库流程。 -- SAG2 只读引擎改在专用事件循环线程运行:大范围检索构建内存语料时不再阻塞 API 事件循环;整次超时会同步取消引擎侧工作。 -- 新增可选 SAG2 证据检索模式(`sag2`):接入 `zleap-sag2` 0.1.0,只读直搜 SQLite / PostgreSQL 关系库,BM25 召回后由 JEV 服务多轮评分,不依赖向量库,文档入库后即可检索;与 JEV 精排共用服务配置,失败不回退,首期不支持 MySQL / OceanBase。 -- JEV 为付费服务:选择 JEV 精排或 SAG2 证据检索前必须填写 API Key;仅保存服务地址不再足以启用模式,连接测试也要求 Key。探索页灰置项直接给出原因与设置入口,SAG2 结果显示本次评分用量。 +- 信源创建时固定选择「事件检索(SAG1)」或「证据检索(SAG2)」,创建后不可切换;已有信源保留 SAG1。SAG1 上传保留实体/事项抽取,SAG2 上传只解析、分块、建立原生索引。 +- 搜索与问答默认按各知识库算法自动召回,混合范围合并去重,部分失败明确提示;显式具体模式只检索同算法的信源。问答工具栏仍支持按轮选择,探索页支持模式对比。 +- 搜索/问答选择未配置的付费 JEV 模式时打开配置弹窗,保存成功后才切换;取消保留原模式与输入。创建 SAG2 信源和上传不需要 JEV Key。 +- SAG2 原生持久化索引支持 SQLite / PostgreSQL,检索在专用线程执行,只扫描所选已发布文档;SQLite 使用独立 sag2.db,PostgreSQL 使用独立 sag2 schema,不修改 SAG1 表。OCTX 当前仅支持 SAG1,SAG2 导出与导入覆盖均禁用。 - 后端中文分词依赖由 `jieba-py` 改回 `jieba` 0.42.1,与 `zleap-sag2` 共用一份词典;分词结果不变。 ## v1.9.2 · 2026-10-22 diff --git a/README-CN.md b/README-CN.md index 94dd302f..9ec38bb3 100644 --- a/README-CN.md +++ b/README-CN.md @@ -566,15 +566,17 @@ config = EngineConfig.from_env() | 快速(multi_es-fast) | `multi_es_fast` | BM25 实体召回与事件多跳检索,跳过 LLM 精排 | | 精确 | `multi` | 结合实体关系与 LLM 精排,结果更完整 | | JEV 精排 | `multi_jev` | 召回与图扩展后,通过独立 JEV 服务为候选证据评分 | -| SAG2 证据检索 | `sag2` | 由 [zleap-sag2](https://pypi.org/project/zleap-sag2/) 只读直搜关系库:BM25 召回后用 JEV 服务多轮评分,不依赖向量库 | +| SAG2 证据检索 | `sag2` | 由 [zleap-sag2](https://pypi.org/project/zleap-sag2/) 原生索引检索:BM25 召回后用 JEV 服务多轮评分,不依赖向量库 | 这里列出的是应用/API 策略名称;应用将 `multi` 映射到 Python 引擎的 `full_expand`,将 `multi_es_fast` 映射到 `pruned_expand_rff`,`sag2` 由独立的 `zleap-sag2` 引擎执行。可用性取决于存储能力:`multi_es_fast` 与 `multi_jev` 需要词法检索支持,`sag2` 需要 SQLite 或 PostgreSQL 关系库。 -每个信源可在创建或编辑时设置**默认检索模式**;未设置则跟随全局默认。探索页与问答页的输入框都提供模式控件,可为当前查询或当前轮次临时切换;探索页还可开启「对比」,用同一问题并排比较 2–3 种模式的耗时、召回与用量,并一键采用其中一种。搜索与问答按“本次显式选择 → Agent 人格 → 范围内信源的共同默认 → 全局默认”解析模式,范围内信源默认不一致时按全局默认处理;结果 `stats.strategy_origin` 标明来源。该设置只影响检索,不改变文档入库流程。 +创建信源时只选择两种固定算法:**事件检索(SAG1)**(默认)或 **证据检索(SAG2)**,创建后不可编辑切换。SAG1 后续上传沿用原有解析、分块、向量化和实体/事项提取;SAG2 后续上传只解析、分块并建立原文索引,不调用抽取或向量模型。已有信源统一保留 SAG1,既有数据无需重建。OCTX 导入/导出目前仅支持 SAG1,SAG2 不允许导出或被 OCTX 覆盖。 -在“设置 → 知识库 → 检索”配置 302.AI、TypeSafe 官方或自定义 JEV 服务(默认 `jev-latest`,独立 API Key),再选择 **JEV 精排** 或 **SAG2 证据检索**;创建信源时选择 JEV 模式也可在对话框内直接完成该配置。JEV 是付费服务:仅保存服务不会启用,选择任一 JEV 模式前必须填写 API Key。JEV 精排默认限时 30 秒、失败报错,可选择粗排降级。 +搜索和问答默认使用**自动(按知识库算法)**:SAG1 按设置页的 SAG1 检索策略召回,SAG2 按证据检索召回,混合范围合并、去重后回答;某一算法失败会明确提示结果不完整。显式选择 SAG1 子模式只检索 SAG1 信源,选择 SAG2 只检索 SAG2 信源;Agent 人格中的显式策略也遵循此限制。探索页仍可并排对比 2–3 种具体模式。 -**SAG2 证据检索**与 JEV 精排共用同一服务配置,但不经向量库:它直接只读 SAG 的 SQLite / PostgreSQL 关系库(首期不支持 MySQL / OceanBase),文档分块入库后即可检索,不要求事件抽取完成,pgvector 单库部署也可使用。每次检索会扫描所选信源的全部段落并多轮调用 JEV,用量高于 JEV 精排;失败直接报错,不支持粗排降级。候选数、超时、并发与范围上限等调优参数见 `apps/api/.env.example` 的 `SAG_SAG2_*`。使用 PostgreSQL 时,连接用户需能在目标 schema 创建并读写 `sag2_state`、`sag2_search_sessions` 两张辅助表,并对 `sag2_state` 执行 `LOCK TABLE`;SAG 的业务表保持只读。 +在“设置 → 知识库 → 检索”配置 302.AI、TypeSafe 官方或自定义 JEV 服务(默认 `jev-latest`,独立 API Key)。JEV 精排和 SAG2 检索共用此服务:搜索/问答选择缺少配置的付费模式时打开配置弹窗,保存成功后才切换,取消保留当前模式和输入。创建 SAG2 信源及上传建索引不要求 JEV Key。JEV 精排默认限时 30 秒、失败报错,可选择粗排降级;SAG2 失败不降级。 + +**SAG2** 使用独立的 `zleap-sag2` 原生持久化索引,支持 SQLite / PostgreSQL(首期不支持 MySQL / OceanBase),BM25 召回后多轮调用 JEV 评分,不依赖向量库。仅已发布的所选文档进入检索范围和扫描计数。SQLite 数据位于引擎目录的 `sag2.db`;PostgreSQL 使用原数据库的独立 `sag2` schema,连接用户需有创建 schema 和其中表的权限。SAG1 数据表保持原样。候选数、超时、并发与范围上限等参数见 `apps/api/.env.example` 的 `SAG_SAG2_*`。 JEV 精排支持 LanceDB、Elasticsearch,暂不支持 pgvector;PostgreSQL 作为关系库不受影响。未启用时沿用原检索策略,已有文档无需重新入库。效果与成本见[更新日志](CHANGELOG.md#jev-reranking)。 diff --git a/README.md b/README.md index 64c29321..4cc752c9 100644 --- a/README.md +++ b/README.md @@ -564,15 +564,17 @@ Pipeline request and result types are available from `zleap.sag.pipeline`: `Pars | Fast (multi_es-fast) | `multi_es_fast` | BM25 entity recall and event multi-hop retrieval, skipping LLM reranking | | Precise | `multi` | Combines entity relationships with LLM reranking for more complete results | | JEV reranking | `multi_jev` | Scores recalled and graph-expanded evidence through an independent JEV service | -| SAG2 evidence retrieval | `sag2` | Read-only search by [zleap-sag2](https://pypi.org/project/zleap-sag2/) over the relational store: BM25 recall scored over several JEV rounds, no vector store involved | +| SAG2 evidence retrieval | `sag2` | Native-index search by [zleap-sag2](https://pypi.org/project/zleap-sag2/) over the relational store: BM25 recall scored over several JEV rounds, no vector store involved | These are the application/API strategy names; the application maps `multi` to the Python engine's `full_expand` and `multi_es_fast` to `pruned_expand_rff`, while `sag2` runs on the separate `zleap-sag2` engine. Availability depends on storage capabilities: `multi_es_fast` and `multi_jev` require lexical search support; `sag2` requires a SQLite or PostgreSQL relational store. -Each source can carry a **default retrieval mode**, chosen when the source is created or edited; unset means follow the global default. Both the explore page and the chat composer offer a mode control for a one-off switch on the current query or turn; the explore page can also run a side-by-side comparison of two or three modes for the same question (latency, hits, usage) and adopt one with a click. Search and chat resolve the mode as explicit request → agent persona → the shared default of every source in scope → global default, falling back to the global default when sources in scope disagree; `stats.strategy_origin` reports which one applied. The setting only affects retrieval and never changes document ingestion. +Create each source with one immutable algorithm: **Event retrieval (SAG1)** (default) or **Evidence retrieval (SAG2)**. SAG1 uploads retain parsing, chunking, embeddings and entity/event extraction. SAG2 uploads only parse, chunk and build native text indexes, without extraction or embeddings. Existing sources stay on SAG1 without rebuilding. OCTX import/export remains SAG1-only; SAG2 export and OCTX overwrite are rejected. -Configure 302.AI, TypeSafe, or a custom JEV service in **Settings → Knowledge → Retrieval** (default model: `jev-latest`, separate API key), then select **JEV reranking** or **SAG2 evidence retrieval**; choosing a JEV mode while creating a source offers the same configuration inline. JEV is a paid service: saving the service alone does not enable it, and an API key is required before either JEV mode can be selected. JEV reranking has a 30-second default deadline; failures return an error unless coarse fallback is enabled. +Search and chat default to **Automatic (by knowledge-base algorithm)**: SAG1 uses the SAG1 retrieval profile from Settings, SAG2 uses evidence retrieval, and mixed scopes merge and deduplicate both groups before answering. Partial failures explicitly identify the missing algorithm. Selecting a concrete SAG1 profile restricts retrieval to SAG1 sources; selecting SAG2 restricts it to SAG2 sources. Explicit agent-persona strategies follow the same scope rule. Explore still compares two or three concrete modes side by side. -**SAG2 evidence retrieval** shares the JEV service configuration but bypasses the vector store: it reads SAG's SQLite or PostgreSQL relational store directly (MySQL and OceanBase are not supported yet), documents become searchable as soon as they are chunked and stored, event extraction is not required, and pgvector single-database deployments can use it. Each search scans every passage of the selected sources and calls JEV over several rounds, so it costs more than JEV reranking; failures are reported as errors, with no coarse fallback. Tuning knobs for candidates, timeouts, concurrency and scope limits are documented as `SAG_SAG2_*` in `apps/api/.env.example`. On PostgreSQL the connecting role must be able to create and use the two auxiliary tables `sag2_state` and `sag2_search_sessions` in the target schema and to `LOCK TABLE` `sag2_state`; SAG's own tables stay read-only. +Configure 302.AI, TypeSafe, or a custom JEV service in **Settings → Knowledge → Retrieval** (default model: `jev-latest`, separate API key). JEV reranking and SAG2 retrieval share this paid service. Selecting an unconfigured paid mode in search/chat opens a configuration dialog; only a successful save activates the mode. Cancel preserves the current mode and input. Creating or indexing a SAG2 source needs no JEV key. JEV reranking has a 30-second default deadline and optional coarse fallback; SAG2 never falls back. + +**SAG2** uses separate durable native `zleap-sag2` indexes on SQLite or PostgreSQL (MySQL and OceanBase are not supported), BM25 recall and multiple JEV scoring rounds, without a vector store. Retrieval and scope counting include only selected, published inputs. SQLite uses `sag2.db` in the engine data directory; PostgreSQL uses a separate `sag2` schema in the configured database, requiring permission to create the schema and its tables. SAG1 tables remain unchanged. Tuning parameters are documented as `SAG_SAG2_*` in `apps/api/.env.example`. JEV reranking is supported on LanceDB and Elasticsearch; pgvector is currently unsupported. PostgreSQL relational storage can use JEV with a supported vector backend. Existing retrieval settings remain until a JEV mode is selected; documents do not need reindexing. See the [benchmark results and cost estimates](CHANGELOG.md#jev-reranking). diff --git a/apps/api/.env.example b/apps/api/.env.example index 8349dd09..ad7acec9 100644 --- a/apps/api/.env.example +++ b/apps/api/.env.example @@ -122,9 +122,9 @@ SAG_JEV_API_KEY= SAG_JEV_RANKING_TIMEOUT_SECONDS=30 SAG_JEV_FAILURE_POLICY=error -# 可选 SAG2 证据检索(zleap-sag2);选择 SAG_SEARCH_STRATEGY=sag2,或在设置页选择模式。 -# 共用上面的 JEV 服务地址、模型与 API Key(付费,选择任一 JEV 模式都必须填写 Key)。 -# 只读直搜 SQLite / PostgreSQL 关系库,不依赖向量库也不要求抽取完成;失败不回退, +# 创建信源时可选 SAG2 证据检索(zleap-sag2),创建后算法不可更改;搜索/问答默认按算法自动召回。 +# 检索共用上面的 JEV 服务地址、模型与 API Key(付费);创建和上传建索引无需 JEV Key。 +# 原生索引使用独立 SQLite sag2.db / PostgreSQL sag2 schema,不向量化或抽取实体事项;检索失败不回退, # SAG_JEV_FAILURE_POLICY 对其无效。以下调优参数首期只经环境变量设置,默认值已控制用量。 # SAG_SAG2_CANDIDATE_K=50 # BM25 候选数(zleap-sag2 默认 100) # SAG_SAG2_SEED_K=10 # 每轮扩展种子数 @@ -134,7 +134,7 @@ SAG_JEV_FAILURE_POLICY=error # SAG_SAG2_DECISION_TIMEOUT_SECONDS=60 # 单次决策请求超时 # SAG_SAG2_DECISION_MAX_CONCURRENCY=20 # 决策请求并发 # SAG_SAG2_MAX_CONCURRENT_SEARCHES=2 # 服务端同时执行的 SAG2 检索数 -# SAG_SAG2_MAX_SCOPE_CHUNKS=20000 # 所选信源实际加载分块上限(不含退役版本);选文档不缩小扫描,0 不限制 +# SAG_SAG2_MAX_SCOPE_CHUNKS=20000 # 所选已发布文档分块上限(不含退役版本或未发布输入),0 不限制 # ── 知识宇宙镜头阈值与浏览器预算 ────────────────────── SAG_UNIVERSE_LOD_ORBIT_PX=72 diff --git a/apps/api/sag_api/api/v1/search.py b/apps/api/sag_api/api/v1/search.py index ee479421..627a030a 100644 --- a/apps/api/sag_api/api/v1/search.py +++ b/apps/api/sag_api/api/v1/search.py @@ -182,7 +182,10 @@ async def _retrieve_search_evidence( top_k=body.top_k, include_ranked_candidates=body.include_ranked_candidates, ) - if strategy in JEV_SCORED_STRATEGIES: + if strategy in JEV_SCORED_STRATEGIES or (strategy == "auto" and ( + configuration.search_strategy == "multi_jev" + or any(getattr(source, "engine_kind", "sag1") == "sag2" for source in sources) + )): outcome = await retrieval return outcome, event_scores_from_evidence(outcome.sections), True outcome, scores = await asyncio.gather( diff --git a/apps/api/sag_api/core/db.py b/apps/api/sag_api/core/db.py index 7afedcf6..c0e0dcfb 100644 --- a/apps/api/sag_api/core/db.py +++ b/apps/api/sag_api/core/db.py @@ -60,7 +60,10 @@ async def get_session() -> AsyncIterator[AsyncSession]: # create_all 只建新表、不改旧表,故对演进列做幂等 ADD COLUMN。 _COLUMN_UPGRADES: dict[str, dict[str, str]] = { "agents": {"is_default": "BOOLEAN NOT NULL DEFAULT FALSE"}, - "sources": {"default_search_strategy": "VARCHAR(32)"}, + "sources": { + "default_search_strategy": "VARCHAR(32)", + "engine_kind": "VARCHAR(16) NOT NULL DEFAULT 'sag1'", + }, "documents": { "progress": "INTEGER NOT NULL DEFAULT 0", "processing_stage": "VARCHAR(32)", diff --git a/apps/api/sag_api/db/models/source.py b/apps/api/sag_api/db/models/source.py index beecd7b2..a15a16d2 100644 --- a/apps/api/sag_api/db/models/source.py +++ b/apps/api/sag_api/db/models/source.py @@ -14,6 +14,9 @@ class Source(IDMixin, TimestampMixin, Base): __tablename__ = "sources" + # Immutable ingestion/retrieval engine; historical sources are always SAG1. + engine_kind: Mapped[str] = mapped_column(String(16), default="sag1", server_default="sag1") + name: Mapped[str] = mapped_column(String(200)) description: Mapped[str] = mapped_column(Text, default="") source_type: Mapped[SourceType] = mapped_column( diff --git a/apps/api/sag_api/enums.py b/apps/api/sag_api/enums.py index cf1f8306..ef22d6b5 100644 --- a/apps/api/sag_api/enums.py +++ b/apps/api/sag_api/enums.py @@ -5,8 +5,8 @@ from enum import StrEnum from typing import Literal -SearchStrategy = Literal["vector", "multi", "multi_es_fast", "multi_jev", "sag2"] -SEARCH_STRATEGIES = frozenset({"vector", "multi", "multi_es_fast", "multi_jev", "sag2"}) +SearchStrategy = Literal["auto", "vector", "multi", "multi_es_fast", "multi_jev", "sag2"] +SEARCH_STRATEGIES = frozenset({"auto", "vector", "multi", "multi_es_fast", "multi_jev", "sag2"}) # 由付费 JEV 决策服务评分的模式:选择前必须保存服务地址与 API Key,失败不回退 vector, # 业务层保留引擎给出的证据顺序。 JEV_SCORED_STRATEGIES = frozenset({"multi_jev", "sag2"}) @@ -14,6 +14,7 @@ # 策略对底层引擎能力的依赖。缺失能力的部署会在 UI 灰置该选项;后端调用则拒绝。 # jev:已保存 JEV 服务地址与 API Key;sag2_relational:zleap-sag2 首期只读 SQLite / PostgreSQL 关系库。 SEARCH_STRATEGY_REQUIREMENTS: dict[str, frozenset[str]] = { + "auto": frozenset(), "vector": frozenset(), "multi": frozenset(), "multi_es_fast": frozenset({"lexical_search"}), diff --git a/apps/api/sag_api/jobs/tasks.py b/apps/api/sag_api/jobs/tasks.py index 3eee5539..6141d304 100644 --- a/apps/api/sag_api/jobs/tasks.py +++ b/apps/api/sag_api/jobs/tasks.py @@ -545,6 +545,7 @@ async def bind_request(processor, config, runtime_settings) -> ProcessSourceRequ runtime_settings, source.sag_source_config_id, input_path, + **({"engine_kind": "sag2"} if getattr(source, "engine_kind", "sag1") == "sag2" else {}), ) except OSError: raise DocumentRestartRequiredError("resume_input_unavailable") from None @@ -632,6 +633,7 @@ async def bind_request(processor, config, runtime_settings) -> ProcessSourceRequ runtime_settings, source.sag_source_config_id, input_path, + **({"engine_kind": "sag2"} if getattr(source, "engine_kind", "sag1") == "sag2" else {}), ) reason = processing_identity_restart_reason(identity, current) if reason or candidate.source.original_sha256 != identity["original_sha256"]: @@ -664,7 +666,8 @@ async def bind_request(processor, config, runtime_settings) -> ProcessSourceRequ "process_request": candidate.model_dump(mode="json"), "processing_identity": identity, "control_revision": control_revision, - "vector_identity": configured_embedding_identity(runtime_settings), + "vector_identity": (None if getattr(source, "engine_kind", "sag1") == "sag2" + else configured_embedding_identity(runtime_settings)), } ) .execution_options(synchronize_session=False) diff --git a/apps/api/sag_api/sag/document_identity.py b/apps/api/sag_api/sag/document_identity.py index f801e5d9..c7d119e9 100644 --- a/apps/api/sag_api/sag/document_identity.py +++ b/apps/api/sag_api/sag/document_identity.py @@ -120,9 +120,21 @@ def _responses_identity(settings: Settings) -> dict | None: async def document_processing_identity( - config: EngineConfig, settings: Settings, source_config_id: str, path: str, + config: EngineConfig, settings: Settings, source_config_id: str, path: str, *, engine_kind: str = "sag1", ) -> dict[str, str]: raw = await asyncio.to_thread(_input_identity, path) + if engine_kind == "sag2": + return { + "configuration_digest": _digest({ + "engine_kind": "sag2", "parser": document_parser_identity(path, settings), + "chunking": {"strategy": "standard", "max_tokens": settings.document_chunk_max_tokens}, + "storage": {"data_dir": str(Path(settings.data_dir).resolve()), + "relational_provider": settings.sag_relational_provider, + "pg_host": settings.sag_pg_host, "pg_port": settings.sag_pg_port, + "pg_database": settings.sag_pg_database, "pg_user": settings.sag_pg_user}, + }), + "input_digest": _digest(raw), "original_sha256": raw["sha256"], + } entity_contract = await _entity_contract(config, source_config_id) return { "configuration_digest": _digest({ diff --git a/apps/api/sag_api/sag/engine_access.py b/apps/api/sag_api/sag/engine_access.py index 66c6e2fd..8c5d1cbb 100644 --- a/apps/api/sag_api/sag/engine_access.py +++ b/apps/api/sag_api/sag/engine_access.py @@ -40,7 +40,7 @@ def _shared_slot(self, source_config_id: str, source: Any = None) -> Any: return None wanted = manager._config_for(source) for slot in manager._slots.values(): - if slot.closing: + if slot.closing or not hasattr(slot.engine, "_config"): continue actual = slot.engine._config if (actual.relational, actual.vector, actual.embedding) == ( diff --git a/apps/api/sag_api/sag/engine_manager.py b/apps/api/sag_api/sag/engine_manager.py index 8c612b21..1235c16f 100644 --- a/apps/api/sag_api/sag/engine_manager.py +++ b/apps/api/sag_api/sag/engine_manager.py @@ -13,7 +13,7 @@ from collections.abc import Awaitable, Callable from contextlib import asynccontextmanager from dataclasses import dataclass, field -from datetime import datetime +from datetime import UTC, datetime from typing import TYPE_CHECKING, Any from zleap.sag import DataEngine, EngineConfig @@ -44,12 +44,13 @@ from sag_api.sag.errors import map_sag_errors from sag_api.sag.incremental_processor import IncrementalDocumentProcessor, ProgressCallback from sag_api.sag.sag2_engine import ( - Sag2EngineHolder, jev_connection_issue, jev_connection_ready, sag2_relational_issue, sag2_relational_supported, ) +from sag_api.sag.sag2_native_search import Sag2NativeSearchHolder +from sag_api.sag.sag2_source_engine import Sag2SourceEngine from sag_api.sag.search_reader import SearchReader, search_admission_timeout_seconds from sag_api.sag.universe_cursor import ( decode_universe_cursor, @@ -193,7 +194,7 @@ def __init__(self, settings: Settings): self._content = ContentReader(self._access) self._search = SearchReader(self._access) # SAG2 证据检索:一个只读 zleap-sag2 引擎覆盖全部信源,随配置发布重建。 - self._sag2 = Sag2EngineHolder(settings) + self._sag2 = Sag2NativeSearchHolder(settings) async def _relational_session_factory(self, source_config_id: str, source: Source | None = None) -> Any: """0.8.2 起 zleap 无全局会话工厂;经引擎注入的 RelationalStore 访问关系库。""" @@ -456,7 +457,10 @@ async def document_processing_identity( overrides = (source.config or {}).get("engine") if source is not None else None with map_sag_errors(stage=ErrorStage.CONFIG): config = build_engine_config(settings, overrides=overrides) - return await document_processing_identity(config, settings, source_config_id, path) + return await document_processing_identity( + config, settings, source_config_id, path, + **({"engine_kind": "sag2"} if getattr(source, "engine_kind", "sag1") == "sag2" else {}), + ) async def _ensure_engine_schema(self, engine: DataEngine) -> None: if self._schema_ready: @@ -553,6 +557,13 @@ async def _slot(self, source_config_id: str, source: Source | None = None) -> _S async with self._lifecycle_gate.write(): log.info("构造引擎 source_config_id=%s", source_config_id) config = self._config_for(source) + if getattr(source, "engine_kind", "sag1") == "sag2": + engine = Sag2SourceEngine(self._settings, source_config_id) + await engine.start() + slot = _Slot(engine=engine, config=config) + self._slots[source_config_id] = slot + await self._evict_lru(keep=source_config_id) + return slot engine = DataEngine( config, data_source_id=source_config_id, @@ -837,6 +848,7 @@ async def never_pause() -> bool: engine, source_config_id, max_concurrency=frozen.document_extract_concurrency, + language=frozen.sag_language if isinstance(engine, Sag2SourceEngine) else None, chunk_max_tokens=frozen.document_chunk_max_tokens, chunk_mode=frozen.document_chunk_mode, document_title=document_title, @@ -968,6 +980,10 @@ async def search_event_scores( limit: int | None = None, source_ids_by_config: dict[str, tuple[str, ...]] | None = None, ) -> dict[tuple[str, str], float]: + sources_by_config = {key: source for key, source in sources_by_config.items() + if getattr(source, "engine_kind", "sag1") != "sag2"} + if not sources_by_config: + return {} return await self._search.search_event_scores( query, sources_by_config, limit=limit, source_ids_by_config=source_ids_by_config ) @@ -981,6 +997,8 @@ async def universe_overview_stats( bucket_count: int = 8, category_limit: int = 8, ) -> UniverseSourceStatsInfo: + if getattr(source, "engine_kind", "sag1") == "sag2": + return UniverseSourceStatsInfo() return await self._universe.universe_overview_stats( source_config_id, source_ids=source_ids, @@ -1029,6 +1047,8 @@ async def universe_timeline( cursor: str | None = None, snapshot_id: str | None = None, ) -> UniverseTimelineInfo: + if getattr(source, "engine_kind", "sag1") == "sag2": + return UniverseTimelineInfo(snapshot_id=source_revision, direction=direction, as_of=datetime.now(UTC)) return await self._universe.universe_timeline( source_config_id, source_ids=source_ids, @@ -1056,6 +1076,8 @@ async def universe_expand( after: datetime | None = None, before: datetime | None = None, ) -> UniverseExpansionInfo | None: + if getattr(source, "engine_kind", "sag1") == "sag2": + return None return await self._universe.universe_expand( source_config_id, node_kind, @@ -1079,6 +1101,8 @@ async def universe_node_detail( source_ids: tuple[str, ...], source: Source | None = None, ) -> dict[str, Any] | None: + if getattr(source, "engine_kind", "sag1") == "sag2": + return None return await self._universe.universe_node_detail( source_config_id, node_kind, node_id, source_ids=source_ids, source=source ) @@ -1094,6 +1118,10 @@ async def graph_for_sections( edge_limit: int = 96, event_scores: dict[tuple[str, str], float] | None = None, ) -> SourceGraphInfo: + sections = [section for section in sections + if getattr(sources_by_config.get(section.source_config_id), "engine_kind", "sag1") != "sag2"] + if not sections and not event_scores: + return SourceGraphInfo() return await self._content.graph_for_sections( sections, sources_by_config, @@ -1113,6 +1141,8 @@ async def list_entities( types: list[str] | None = None, limit: int = 100, ) -> list[EntityInfo]: + if getattr(source, "engine_kind", "sag1") == "sag2": + return [] return await self._content.list_entities( source_config_id, source_ids=source_ids, source=source, types=types, limit=limit ) @@ -1127,6 +1157,8 @@ async def source_graph( entity_limit: int = 1_000, expected_event_count: int | None = None, ) -> SourceGraphInfo: + if getattr(source, "engine_kind", "sag1") == "sag2": + return SourceGraphInfo() return await self._content.source_graph( source_config_id, source_ids, @@ -1157,6 +1189,11 @@ async def list_chunk_headings( doc_sag_id: str | None = None, limit: int = 300, ) -> list[dict]: + if getattr(source, "engine_kind", "sag1") == "sag2": + slot = await self._slot(source_config_id, source) + rows = await slot.engine.rows((doc_sag_id,) if doc_sag_id else ()) + return [{"chunk_id": row["chunk_id"], "heading": row.get("heading") or "", + "rank": int(row.get("_rank") or 0)} for row in rows[:limit]] return await self._content.list_chunk_headings( source_config_id, source=source, doc_sag_id=doc_sag_id, limit=limit ) @@ -1168,6 +1205,14 @@ async def get_document_markdown( *, source: Source | None = None, ) -> str | None: + if getattr(source, "engine_kind", "sag1") == "sag2": + slot = await self._slot(source_config_id, source) + rows = await slot.engine.rows((article_id,)) + if not rows: + return None + return rows[0].get("metadata", {}).get("original_text") or "\n\n".join( + str(row.get("content") or "") for row in rows + ) return await self._content.get_document_markdown(source_config_id, article_id, source=source) async def grep_chunks( @@ -1179,6 +1224,21 @@ async def grep_chunks( limit: int = 20, source_ids: tuple[str, ...] | None = None, ) -> list[dict]: + if getattr(source, "engine_kind", "sag1") == "sag2": + slot = await self._slot(source_config_id, source) + rows = await slot.engine.rows(source_ids or ()) + needle = pattern.casefold() + result = [] + for row in rows: + content = str(row.get("content") or "") + position = content.casefold().find(needle) + if position < 0: + continue + result.append({"chunk_id": row["chunk_id"], "heading": row.get("heading") or "", + "source_id": row["source_id"], "snippet": content[max(0, position - 80):position + 700]}) + if len(result) >= limit: + break + return result return await self._content.grep_chunks( source_config_id, pattern, source=source, limit=limit, source_ids=source_ids ) @@ -1191,6 +1251,14 @@ async def get_chunk( source_ids: tuple[str, ...] | None = None, source: Source | None = None, ): + if getattr(source, "engine_kind", "sag1") == "sag2": + from sag_api.sag.dto import ChunkInfo + slot = await self._slot(source_config_id, source) + for input_id in source_ids or (): + row = await slot.engine.read_chunk(input_id, chunk_id, data_source_id=source_config_id) + if row is not None: + return ChunkInfo(chunk_id=chunk_id, heading=row.heading or "", content=row.content, rank=0) + return None return await self._content.get_chunk(source_config_id, chunk_id, source_ids=source_ids, source=source) async def release(self, source_config_id: str) -> None: diff --git a/apps/api/sag_api/sag/incremental_processor.py b/apps/api/sag_api/sag/incremental_processor.py index 9b46b85f..3e89692b 100644 --- a/apps/api/sag_api/sag/incremental_processor.py +++ b/apps/api/sag_api/sag/incremental_processor.py @@ -116,8 +116,10 @@ def __init__( chunk_mode: str = "standard", document_title: str | None = None, max_entities_per_event: int = 20, + language: str | None = None, ) -> None: self._engine = engine + self._language = language self._source_config_id = source_config_id self._max_concurrency = max(1, min(100, max_concurrency)) self._chunk_max_tokens = chunk_max_tokens @@ -138,7 +140,7 @@ async def build_request( content_bytes = await asyncio.to_thread(markdown.read_bytes) original = Path(original_path) if original_path is not None else markdown original_bytes = content_bytes if original == markdown else await asyncio.to_thread(original.read_bytes) - language = self._engine.resources.prompts.language + language = self._language or self._engine.resources.prompts.language return ProcessSourceRequest( context=context.model_copy( update={ diff --git a/apps/api/sag_api/sag/sag2_engine.py b/apps/api/sag_api/sag/sag2_engine.py index 370ba414..d56570a7 100644 --- a/apps/api/sag_api/sag/sag2_engine.py +++ b/apps/api/sag_api/sag/sag2_engine.py @@ -433,7 +433,7 @@ async def _execute( if limit and scope_chunks > limit: raise ValidationError( f"信源扫描范围过大:包含 {scope_chunks:,} 个段落,超过 SAG2 证据检索上限 {limit:,}。" - "本版引擎先扫描整个信源,选择单篇文档不会减少扫描量;请减少信源,或联系管理员调整扫描上限。", + "请缩小所选文档或信源范围,或联系管理员调整扫描上限。", layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE, ) diff --git a/apps/api/sag_api/sag/sag2_native_search.py b/apps/api/sag_api/sag/sag2_native_search.py new file mode 100644 index 00000000..1f04da7f --- /dev/null +++ b/apps/api/sag_api/sag/sag2_native_search.py @@ -0,0 +1,70 @@ +"""SAG2 retrieval over native, published document inputs only.""" + +from __future__ import annotations + +import asyncio + +from sqlalchemy import select + +from sag_api.core.errors import ConfigurationError +from sag_api.sag.sag2_engine import Sag2EngineHolder, jev_connection_issue +from sag_api.sag.sag2_source_engine import _BINDINGS, Sag2SourceEngine, native_config, native_namespace + + +class Sag2NativeSearchHolder(Sag2EngineHolder): + async def _start(self, settings): + issue = jev_connection_issue(settings) + if issue: + code, message = issue + raise ConfigurationError(message, code=code) + scorer = self._scorer_factory(native_config(settings)) if self._scorer_factory else None + adapter = Sag2SourceEngine(settings, "search", scorer=scorer) + await adapter.start() + return adapter.native + + async def _count_scope(self, engine, data_source_ids): + # source_state counts indexed chunks without loading text/token streams. + gate = asyncio.Semaphore(16) + + async with engine.store.engine.connect() as connection: + pairs = ( + await connection.execute( + select(_BINDINGS.c.namespace, _BINDINGS.c.input_id).where( + _BINDINGS.c.namespace.in_(data_source_ids), + ) + ) + ).all() + + async def count(namespace, input_id): + async with gate: + state = await engine.source_state(input_id, data_source_id=namespace) + return int(state.chunk_count) if state is not None else 0 + + return sum(await asyncio.gather(*(count(namespace, input_id) for namespace, input_id in pairs))) + + async def search(self, targets, query, *, top_k, requested_sources, source_limit_applied, source_ids_by_config): + if source_ids_by_config is None: + raise ConfigurationError("SAG2 检索必须限定已发布文档范围") + mapping = { + native_namespace(config_id, input_id): config_id + for config_id, _ in targets + for input_id in source_ids_by_config.get(config_id, ()) + } + scopes = { + native_namespace(config_id, input_id): (input_id,) + for config_id, _ in targets + for input_id in source_ids_by_config.get(config_id, ()) + } + outcome = await super().search( + [(namespace, None) for namespace in mapping], + query, + top_k=top_k, + requested_sources=requested_sources, + source_limit_applied=source_limit_applied, + source_ids_by_config=scopes, + ) + for section in outcome.sections: + section.source_config_id = mapping[section.source_config_id] + section.metadata["engine_kind"] = "sag2" + outcome.stats["sources"] = len(targets) + return outcome diff --git a/apps/api/sag_api/sag/sag2_source_engine.py b/apps/api/sag_api/sag/sag2_source_engine.py new file mode 100644 index 00000000..79aee32e --- /dev/null +++ b/apps/api/sag_api/sag/sag2_source_engine.py @@ -0,0 +1,253 @@ +"""Native SAG2 storage with the application's durable document-operation contract. + +The application persists the same request envelope for both engines. This adapter +removes extraction options before calling SAG2 and maps its zero-event result back +to the shared publication DTO; no SAG1 engine or model clients are constructed. +""" + +from __future__ import annotations + +from datetime import UTC, datetime +from hashlib import sha256 +from pathlib import Path +from uuid import NAMESPACE_URL, uuid5 + +from sqlalchemy import Column, MetaData, String, Table, delete, event, select, text +from zleap.sag.operations import OperationResult +from zleap.sag.pipeline import ChunkSetRef, EventSetRef +from zleap.sag2 import DataEngine, EngineConfig, JevConfig, RelationalConfig +from zleap.sag2.operations import ( + DeleteDataSourceRequest, + DeleteSourceRequest, + ProcessSourceRequest, +) +from zleap.sag2.pipeline.errors import PipelineCancelledError +from zleap.sag2.pipeline.options import IndexOptions + +from sag_api.core.config import Settings +from sag_api.core.errors import ConfigurationError + +_BINDINGS_METADATA = MetaData() +_BINDINGS = Table( + "sag_app_sag2_inputs", + _BINDINGS_METADATA, + Column("namespace", String(256), primary_key=True), + Column("source_config_id", String(64), nullable=False, index=True), + Column("input_id", String(64), nullable=False), +) + + +def native_namespace(source_config_id: str, input_id: str) -> str: + return uuid5(NAMESPACE_URL, f"sag:source:{source_config_id}:input:{input_id}").hex + + + +def native_config(settings: Settings) -> EngineConfig: + provider = settings.sag_relational_provider or "sqlite" + if provider == "sqlite": + relational = RelationalConfig(provider="sqlite", path=str(Path(settings.data_dir) / "sag2.db")) + elif provider == "postgres": + relational = RelationalConfig( + provider="postgres", + host=settings.sag_pg_host, + port=settings.sag_pg_port, + user=settings.sag_pg_user, + password=settings.sag_pg_password, + database=settings.sag_pg_database, + ) + else: + raise ConfigurationError("SAG2 仅支持 SQLite 与 PostgreSQL 关系库") + jev = None + if settings.jev_endpoint and settings.jev_api_key: + jev = JevConfig( + endpoint=settings.jev_endpoint, + api_key=settings.jev_api_key, + model=settings.jev_model, + timeout_seconds=settings.sag2_decision_timeout_seconds, + max_concurrency=settings.sag2_decision_max_concurrency, + ) + return EngineConfig(relational=relational, jev=jev) + + +class Sag2SourceEngine: + """One namespace in native SAG2 storage, independent of SAG1's tables.""" + + def __init__(self, settings: Settings, source_config_id: str, *, scorer=None): + self.source_config_id = source_config_id + self.native = DataEngine(native_config(settings), health_check=False, scorer=scorer) + + async def start(self): + if self.native.config.relational.provider == "postgres": + sql_engine = self.native.store.engine + async with sql_engine.begin() as connection: + await connection.execute(text("CREATE SCHEMA IF NOT EXISTS sag2")) + await sql_engine.dispose() + + @event.listens_for(sql_engine.sync_engine, "connect") + def set_namespace(connection, _record): + previous = connection.autocommit + connection.autocommit = True + try: + cursor = connection.cursor() + cursor.execute("SET SESSION search_path TO sag2") + cursor.close() + finally: + connection.autocommit = previous + + await self.native.start() + async with self.native.store.engine.begin() as connection: + await connection.run_sync(_BINDINGS_METADATA.create_all) + + async def aclose(self): + await self.native.aclose() + + def _result(self, result): + if result is None: + return None + data = result.model_dump(mode="json") + if data.get("failure_code") == "pipeline_cancelled": + data["failure_code"] = "cancelled" + data["data_source_id"] = self.source_config_id + data["fence_scope"] = self.source_config_id + payload = dict(data.get("result") or {}) + if data["operation_type"] == "process_source" and data["status"] == "succeeded": + raw = {**payload, "data_source_id": self.source_config_id} + chunks = ChunkSetRef.model_validate( + { + **{key: value for key, value in raw.items() if key in ChunkSetRef.model_fields}, + "vector_status": "skipped_by_policy", + } + ) + events = EventSetRef( + data_source_id=chunks.data_source_id, + source_type=chunks.source_type, + source_id=chunks.source_id, + source_version=chunks.source_version, + chunk_version=chunks.chunk_version, + extract_version="sag2:no-extraction", + generation_id=chunks.generation_id, + chunk_ids=chunks.chunk_ids, + event_ids=(), + relation_status="skipped_by_policy", + vector_status="skipped_by_policy", + ) + payload.update(chunk_ref=chunks.model_dump(mode="json"), event_ref=events.model_dump(mode="json")) + if data["operation_type"] in {"delete_source", "delete_data_source"} and data["status"] == "succeeded": + payload["target"] = "source" if data["operation_type"] == "delete_source" else "data_source" + data["result"] = payload + return OperationResult.model_validate(data) + + async def process_source(self, request, *, observer=None, cancellation=None): + data = request.model_dump(mode="json", exclude={"extraction_options"}) + # SAG1's input-isolation flag is an app publication policy; SAG2 always + # stores immutable generations and the app filters by the published input. + data["context"].pop("isolation", None) + input_id = data["source"]["descriptor"]["source_id"] + namespace = native_namespace(self.source_config_id, input_id) + data["source"]["descriptor"]["data_source_id"] = namespace + data["context"]["fence_scope"] = namespace + # Each app input is immutable and has its own fence, so processing or + # resuming another document cannot invalidate this operation. + async with self.native.store.engine.begin() as connection: + from sqlalchemy.dialects.postgresql import insert as pg_insert + from sqlalchemy.dialects.sqlite import insert as sqlite_insert + + insert = pg_insert if connection.dialect.name == "postgresql" else sqlite_insert + await connection.execute( + insert(_BINDINGS) + .values( + namespace=namespace, + source_config_id=self.source_config_id, + input_id=input_id, + ) + .on_conflict_do_nothing() + ) + data["index_options"] = { + key: value for key, value in data.get("index_options", {}).items() if key in IndexOptions.model_fields + } + native_request = ProcessSourceRequest.model_validate(data) + try: + result = await self.native.process_source(native_request, observer=observer, cancellation=cancellation) + except PipelineCancelledError: + result = await self.native.get_operation_status(request.context.operation_id) + return self._result(result) + + async def get_operation_status(self, operation_id): + return self._result(await self.native.get_operation_status(operation_id)) + + async def delete_source(self, request): + data = request.model_dump(mode="json") + data["context"].pop("isolation", None) + namespace = native_namespace(self.source_config_id, request.source_id) + data["data_source_id"] = namespace + data["context"]["fence_scope"] = namespace + data["context"]["fence_token"] = max(2, data["context"]["fence_token"]) + result = self._result(await self.native.delete_source(DeleteSourceRequest.model_validate(data))) + return result.model_copy(update={ + "fence_token": request.context.fence_token, "fence_scope": request.context.fence_scope, + }) + + async def delete_data_source(self, request): + async with self.native.store.engine.connect() as connection: + namespaces = ( + ( + await connection.execute( + select(_BINDINGS.c.namespace).where( + _BINDINGS.c.source_config_id == self.source_config_id, + ) + ) + ) + .scalars() + .all() + ) + removed = 0 + for namespace in namespaces: + data = request.model_dump(mode="json") + data["context"].pop("isolation", None) + data["context"].update( + operation_id=request.context.operation_id + ":" + sha256(namespace.encode()).hexdigest()[:16], + idempotency_key=request.context.idempotency_key + ":" + sha256(namespace.encode()).hexdigest()[:16], + fence_scope=namespace, + fence_token=max(3, request.context.fence_token), + ) + data["data_source_id"] = namespace + result = await self.native.delete_data_source(DeleteDataSourceRequest.model_validate(data)) + if result.status != "succeeded": + return self._aggregate_delete_result(request, result=result) + removed += int((result.result or {}).get("deleted_chunks", 0)) + async with self.native.store.engine.begin() as connection: + await connection.execute(delete(_BINDINGS).where(_BINDINGS.c.source_config_id == self.source_config_id)) + return self._aggregate_delete_result(request, removed=removed) + + def _aggregate_delete_result(self, request, *, removed=0, result=None): + now = datetime.now(UTC) + return OperationResult( + operation_id=request.context.operation_id, + idempotency_key=request.context.idempotency_key, + request_digest=request.context.request_digest, + operation_type="delete_data_source", + data_source_id=self.source_config_id, + status=result.status if result is not None else "succeeded", + checkpoint=result.checkpoint if result is not None else "ready", + fence_scope=request.context.fence_scope, + fence_token=request.context.fence_token, + created_at=now, updated_at=now, + failure_code=result.failure_code if result is not None else None, + failure_message=result.failure_message if result is not None else None, + retryable=result.retryable if result is not None else False, + result={"target": "data_source", "deleted_chunks": removed}, + ) + + async def read_chunk(self, source_id, chunk_id, *, data_source_id): + return await self.native.read_chunk( + source_id, chunk_id, data_source_id=native_namespace(data_source_id, source_id) + ) + + async def rows(self, input_ids): + from zleap.sag2 import SearchScope + + if not input_ids: + return [] + scope = SearchScope(data_source_ids=tuple(native_namespace(self.source_config_id, item) for item in input_ids)) + snapshot = await self.native.store.snapshot(scope) + return list(snapshot.rows.values()) diff --git a/apps/api/sag_api/sag/search_reader.py b/apps/api/sag_api/sag/search_reader.py index 1b31f754..bb4fb4a4 100644 --- a/apps/api/sag_api/sag/search_reader.py +++ b/apps/api/sag_api/sag/search_reader.py @@ -315,12 +315,15 @@ async def search_many( "source_limit_applied": requested_sources > len(targets), "candidates": 0, "chunk_recall": "batch-vector-timeout", + "source_failures": [{"source_config_id": scid, "message": "块向量召回超时"} + for scid, _ in targets], }, ) except Exception as error: # noqa: BLE001 - use the same scope in per-range fallback log.warning("批量块向量召回失败,回退逐范围检索:%s", error) semaphore = asyncio.Semaphore(self._access.settings.search_source_concurrency) + source_failures = [] async def _one(scid: str, source: Source | None): async with semaphore: @@ -338,7 +341,9 @@ async def _one(scid: str, source: Source | None): except Exception as e: # noqa: BLE001 if strategy in JEV_SCORED_STRATEGIES: raise - log.warning("fan-out 检索失败 %s:%s", scid, getattr(e, "message", None) or e) + message = getattr(e, "message", None) or str(e) + log.warning("fan-out 检索失败 %s:%s", scid, message) + source_failures.append({"source_config_id": scid, "message": message}) return None tasks = [asyncio.create_task(_one(scid, src)) for scid, src in targets] @@ -387,6 +392,7 @@ async def _one(scid: str, source: Source | None): candidate.setdefault("source_config_id", scid) ranked_candidates.append(candidate) stats: dict[str, Any] = { + **({"source_failures": source_failures} if source_failures else {}), "sources": len(targets), "sources_requested": requested_sources, "source_limit_applied": requested_sources > len(targets), diff --git a/apps/api/sag_api/schemas/source.py b/apps/api/sag_api/schemas/source.py index cd45d139..d574479c 100644 --- a/apps/api/sag_api/schemas/source.py +++ b/apps/api/sag_api/schemas/source.py @@ -1,7 +1,7 @@ from __future__ import annotations from datetime import datetime -from typing import Any +from typing import Any, Literal from pydantic import BaseModel, ConfigDict, Field @@ -18,26 +18,26 @@ class ConnectorOut(BaseModel): class SourceCreate(BaseModel): + model_config = ConfigDict(extra="forbid") + engine_kind: Literal["sag1", "sag2"] = "sag1" name: str = Field(min_length=1, max_length=200) description: str = "" connector_kind: ConnectorKind = ConnectorKind.FILE_UPLOAD config: dict[str, Any] = Field(default_factory=dict) - # 默认检索模式;None 表示跟随全局默认。 - default_search_strategy: SearchStrategy | None = None class SourceUpdate(BaseModel): + model_config = ConfigDict(extra="forbid") name: str | None = Field(default=None, max_length=200) description: str | None = None status: SourceStatus | None = None - # 显式传 null 表示改回跟随全局默认;未出现则保持不变。 - default_search_strategy: SearchStrategy | None = None class SourceOut(BaseModel): model_config = ConfigDict(from_attributes=True) id: str + engine_kind: Literal["sag1", "sag2"] = "sag1" name: str description: str source_type: SourceType diff --git a/apps/api/sag_api/services/agent_tooling.py b/apps/api/sag_api/services/agent_tooling.py index 8b0c22cb..3fdfc9d1 100644 --- a/apps/api/sag_api/services/agent_tooling.py +++ b/apps/api/sag_api/services/agent_tooling.py @@ -356,7 +356,9 @@ def _adapt_tool(host_tool, host_context: HostToolContext, citations: list[dict]) host_context.persona, host_context.sources, host_context.requested_strategy, ) host_context = replace(host_context, search_strategy_snapshot=(strategy, origin)) - if strategy == "multi_jev": + effective = (host_context.engine_manager._effective_search_strategy(strategy) + if hasattr(host_context.engine_manager, "_effective_search_strategy") else strategy) + if effective == "multi_jev" or (effective == "auto" and configuration.search_strategy == "multi_jev"): source_count = min(len(host_context.sources), configuration.search_source_candidate_limit) waves = max(1, ceil(source_count / configuration.search_source_concurrency)) recall_timeout = max(1.0, configuration.search_source_timeout) @@ -366,14 +368,16 @@ def _adapt_tool(host_tool, host_context: HostToolContext, citations: list[dict]) configuration.agent_tool_timeout_seconds, (waves + 1) * (recall_timeout + MAX_JEV_RANKING_TIMEOUT_SECONDS) + recall_timeout, ) - elif strategy == "sag2": + if strategy == "sag2" or (strategy == "auto" and any( + getattr(source, "engine_kind", "sag1") == "sag2" for source in host_context.sources + )): from sag_api.sag.search_reader import search_admission_timeout_seconds # One read-only request covers every source. Its whole-search budget is # also the settings-publication wait, so allow one of each plus recall. - whole_search = search_admission_timeout_seconds(configuration, strategy) or 0.0 + whole_search = search_admission_timeout_seconds(configuration, "sag2") or 0.0 timeout_seconds = max( - configuration.agent_tool_timeout_seconds, + timeout_seconds or 0, configuration.agent_tool_timeout_seconds, 2 * whole_search + max(1.0, configuration.search_source_timeout), ) diff --git a/apps/api/sag_api/services/engine_routing.py b/apps/api/sag_api/services/engine_routing.py new file mode 100644 index 00000000..3b0e885f --- /dev/null +++ b/apps/api/sag_api/services/engine_routing.py @@ -0,0 +1,102 @@ +"""Route automatic retrieval by immutable knowledge algorithm and fuse ranks.""" + +from __future__ import annotations + +import asyncio + +from sag_api.sag.dto import SearchOutcome + + +async def retrieve_automatic(sources, query, *, sag1_strategy, top_k, retrieve): + groups = { + kind: [source for source in sources if getattr(source, "engine_kind", "sag1") == kind] + for kind in ("sag1", "sag2") + } + kinds = [kind for kind, group in groups.items() if group] + results = await asyncio.gather( + *(retrieve(groups[kind], "sag2" if kind == "sag2" else sag1_strategy) for kind in kinds), return_exceptions=True + ) + if (len(kinds) == 1 and not isinstance(results[0], BaseException) + and not results[0].stats.get("source_failures")): + outcome = results[0] + for section in outcome.sections: + section.metadata["engine_kind"] = kinds[0] + return outcome.model_copy( + update={ + "stats": { + **outcome.stats, + "requested_strategy": "auto", + "effective_strategy": "auto", + "engine_kind": kinds[0], + "jev_fallback_used": sag1_strategy == "multi_jev" and bool(outcome.stats.get("fallback_used")), + } + } + ) + failures = [] + candidates = {} + usage = {} + engine_stats = {} + source_stats = {} + fallback_used = False + jev_fallback_used = False + succeeded = 0 + for kind, result in zip(kinds, results, strict=True): + if isinstance(result, BaseException): + if not isinstance(result, Exception): + raise result + failures.append({"engine_kind": kind, "message": getattr(result, "message", None) or str(result)}) + continue + succeeded += 1 + engine_stats[kind] = result.stats + source_stats.update(result.stats.get("source_stats") or {}) + fallback_used |= bool(result.stats.get("fallback_used")) + jev_fallback_used |= kind == "sag1" and sag1_strategy == "multi_jev" and bool(result.stats.get("fallback_used")) + if result.stats.get("source_failures"): + messages = list(dict.fromkeys(item["message"] for item in result.stats["source_failures"])) + failures.append({"engine_kind": kind, "message": "; ".join(messages)}) + for key, value in (result.stats.get("jev_usage") or {}).items(): + if isinstance(value, (int, float)): + usage[key] = usage.get(key, 0) + value + for rank, section in enumerate(result.sections): + key = (section.source_config_id, section.chunk_id or section.content) + contribution = 1.0 / (60 + rank + 1) + if key not in candidates: + candidates[key] = [section, 0.0, len(candidates), kind] + candidates[key][1] += contribution + if kinds and not succeeded: + raise next(result for result in results if isinstance(result, Exception)) + ranked = sorted(candidates.values(), key=lambda item: (-item[1], item[2]))[:top_k] + sections = [ + section.model_copy( + update={ + "score": score, + "rank": rank, + "metadata": { + **section.metadata, + "engine_kind": kind, + "original_score": section.score, + "score_source": "rrf", + }, + } + ) + for rank, (section, score, _, kind) in enumerate(ranked) + ] + return SearchOutcome( + query=query, + sections=sections, + stats={ + "requested_strategy": "auto", + "effective_strategy": "auto", + "strategy_origin": "global", + "sources": len(sources), + "relevant": len(sections), + "fusion": "rrf", + "partial_results": bool(failures), + "engine_failures": failures, + "engine_stats": engine_stats, + "source_stats": source_stats, + "fallback_used": fallback_used, + "jev_fallback_used": jev_fallback_used, + **({"jev_usage": usage} if usage else {}), + }, + ) diff --git a/apps/api/sag_api/services/knowledge_algorithms.py b/apps/api/sag_api/services/knowledge_algorithms.py new file mode 100644 index 00000000..4643f231 --- /dev/null +++ b/apps/api/sag_api/services/knowledge_algorithms.py @@ -0,0 +1,8 @@ +"""Business policy for immutable knowledge algorithms.""" + +from sag_api.core.errors import ValidationError + + +def require_sag1_octx(source) -> None: + if getattr(source, "engine_kind", "sag1") == "sag2": + raise ValidationError("证据检索(SAG2)知识库暂不支持 OCTX 导入覆盖或导出;OCTX 目前仅支持事件检索(SAG1)。") diff --git a/apps/api/sag_api/services/octx_conflict_service.py b/apps/api/sag_api/services/octx_conflict_service.py index d201d3e1..14a00423 100644 --- a/apps/api/sag_api/services/octx_conflict_service.py +++ b/apps/api/sag_api/services/octx_conflict_service.py @@ -14,6 +14,7 @@ from sag_api.db.models.octx import transition_transfer from sag_api.enums import OctxImportAction, OctxTransferStatus from sag_api.octx.decision_token import DecisionTokenError, verify_decision_token +from sag_api.services.knowledge_algorithms import require_sag1_octx @dataclass(frozen=True, slots=True) @@ -211,6 +212,7 @@ async def confirm_import_decision( target_source_id = decision.target_source_id if target_source_id is None or target_source_id not in claims.source_revisions: raise ValidationError("update target is not present in OCTX decision token") + require_sag1_octx(await session.get(Source, target_source_id)) binding = await session.get(OctxSourceBinding, target_source_id) if binding is None or binding.asset_id != claims.asset_id: transition_transfer(transfer, OctxTransferStatus.VALIDATING) diff --git a/apps/api/sag_api/services/octx_export.py b/apps/api/sag_api/services/octx_export.py index 2e267407..e9a90aeb 100644 --- a/apps/api/sag_api/services/octx_export.py +++ b/apps/api/sag_api/services/octx_export.py @@ -54,6 +54,7 @@ from sag_api.octx.semver import bump_semver_patch, parse_semver, validate_semver from sag_api.octx.storage import OctxStorage from sag_api.sag.octx_snapshot import export_snapshot +from sag_api.services.knowledge_algorithms import require_sag1_octx from sag_api.services.octx_checkpoint import merge_checkpoint from sag_api.services.octx_diagnostics_service import append_octx_trace @@ -127,6 +128,7 @@ async def create_export_transfer( source = await session.get(Source, source_id) if source is None: raise NotFoundError("source not found") + require_sag1_octx(source) documents = ( ( await session.execute( @@ -327,6 +329,7 @@ async def create_document_export_transfer( source = await session.get(Source, source_id) if source is None: raise NotFoundError("source not found") + require_sag1_octx(source) document = await session.get(Document, document_id) if document is None or document.source_id != source_id or not document.is_active: raise NotFoundError("document not found") @@ -530,6 +533,7 @@ async def execute_export( source = await session.get(Source, transfer.target_source_id) if source is None: raise NotFoundError("source not found") + require_sag1_octx(source) checkpoint = dict(transfer.checkpoint or {}) selected_document_ids = tuple(checkpoint.get("selected_document_ids") or ()) selected_article_ids = tuple(checkpoint.get("selected_article_ids") or ()) diff --git a/apps/api/sag_api/services/octx_transfer_common.py b/apps/api/sag_api/services/octx_transfer_common.py index 6440dee2..a3b4ad8a 100644 --- a/apps/api/sag_api/services/octx_transfer_common.py +++ b/apps/api/sag_api/services/octx_transfer_common.py @@ -37,6 +37,7 @@ OctxTransferStatus, ) from sag_api.octx.storage import FileSignature, OctxStorage, StoredUpload +from sag_api.services.knowledge_algorithms import require_sag1_octx from sag_api.services.octx_checkpoint import merge_checkpoint logger = logging.getLogger(__name__) @@ -234,7 +235,9 @@ async def _claim_import_target(session: AsyncSession, transfer: OctxTransfer) -> if claimed.rowcount != 1: raise ConflictError("OCTX target is being deleted", code=ErrorCode.OCTX_TRANSFER_CANCELLED, retryable=False) await _ensure_transfer_active(session, transfer, stage="atomic_switch") - return await session.get(Source, target_id, populate_existing=True) + source = await session.get(Source, target_id, populate_existing=True) + require_sag1_octx(source) + return source def _export_document_state(documents: list[Document]) -> tuple[list[dict], list[dict]]: diff --git a/apps/api/sag_api/services/retrieval_service.py b/apps/api/sag_api/services/retrieval_service.py index dcd2a9e5..328ed4a9 100644 --- a/apps/api/sag_api/services/retrieval_service.py +++ b/apps/api/sag_api/services/retrieval_service.py @@ -41,20 +41,6 @@ class ResolvedSearchStrategy: origin: StrategyOrigin -def common_source_default_strategy(sources) -> str | None: - """范围内每个信源都设置了同一默认模式时返回它;有信源未设置或不一致则返回 None。 - - 混合范围不猜测:一个信源的偏好不应改变其他信源的检索方式。 - """ - defaults: set[str] = set() - for source in sources: - value = getattr(source, "default_search_strategy", None) - if not value: - return None - defaults.add(normalize_search_strategy(str(value))) - return next(iter(defaults)) if len(defaults) == 1 else None - - def resolve_search_strategy( *, requested: str | None = None, @@ -62,15 +48,12 @@ def resolve_search_strategy( sources=(), configuration: Any = settings, ) -> ResolvedSearchStrategy: - """显式请求 → Agent 人格 → 范围内信源的共同默认 → 全局默认。""" + """显式请求 → Agent 人格 → 按信源固定算法自动检索。""" if requested: return ResolvedSearchStrategy(requested, "request") if persona_strategy: return ResolvedSearchStrategy(persona_strategy, "persona") - common = common_source_default_strategy(sources) - if common: - return ResolvedSearchStrategy(common, "source_default") - return ResolvedSearchStrategy(configuration.search_strategy, "global") + return ResolvedSearchStrategy("auto", "global") def event_scores_from_evidence(sections: list[RetrievedSection]) -> EventScoreMap: @@ -305,6 +288,7 @@ async def _lexical_sections( *, analysis: QueryAnalysis, source_ids_by_config: DocumentSourceScope, + failures: list[dict] | None = None, ) -> tuple[list[RetrievedSection], set[tuple[str, str]]]: grep_chunks = getattr(engine_manager, "grep_chunks", None) terms = analysis.lookup_terms @@ -330,7 +314,12 @@ async def one( term, **options, ) - except Exception: # noqa: BLE001 + except Exception as error: # noqa: BLE001 + if failures is not None and not any( + item["source_config_id"] == source.sag_source_config_id for item in failures + ): + failures.append({"source_config_id": source.sag_source_config_id, + "message": getattr(error, "message", None) or str(error)}) return [], False sections = [ RetrievedSection( @@ -368,6 +357,29 @@ async def retrieve_relevant_sections( resolved = resolve_search_strategy(requested=strategy, sources=sources, configuration=configuration) requested_strategy = resolved.strategy mode = normalize_search_strategy(requested_strategy) + if mode == "auto": + from sag_api.services.engine_routing import retrieve_automatic + sag1_strategy = configuration.search_strategy + if sag1_strategy not in {"vector", "multi", "multi_es_fast", "multi_jev"}: + sag1_strategy = "vector" + async def retrieve(group, mode): + return await retrieve_relevant_sections( + engine_manager, group, query, strategy=mode, top_k=top_k, + include_ranked_candidates=include_ranked_candidates, + ) + outcome = await retrieve_automatic( + sources, query, sag1_strategy=sag1_strategy, + top_k=max(1, min(int(top_k or configuration.search_top_k), 50)), retrieve=retrieve, + ) + outcome.stats["latency_total_ms"] = round((time.perf_counter() - total_start) * 1000, 2) + outcome.stats["strategy_origin"] = resolved.origin + return outcome + expected_engine = "sag2" if mode == "sag2" else "sag1" + sources = [source for source in sources if getattr(source, "engine_kind", "sag1") == expected_engine] + if not sources: + return SearchOutcome(query=query, sections=[], stats={ + "requested_strategy": requested_strategy, "effective_strategy": mode, "sources": 0, + }) if mode in JEV_SCORED_STRATEGIES: # The JEV-scored profile owns recall and final scoring. Adding application # lexical hits afterwards would mix unscored evidence into the ranked list. @@ -424,6 +436,7 @@ async def retrieve_relevant_sections( if include_ranked_candidates: search_options["include_ranked_candidates"] = True search_options["source_ids_by_config"] = published + lexical_failures: list[dict] = [] outcome, lexical_recall = await asyncio.gather( engine_manager.search_many(targets, query, **search_options), _lexical_sections( @@ -431,6 +444,7 @@ async def retrieve_relevant_sections( sources, analysis=analysis, source_ids_by_config=published, + failures=lexical_failures, ), ) lexical, exact_lexical_keys = lexical_recall @@ -458,6 +472,7 @@ def visible(section: RetrievedSection) -> bool: total_latency_ms = round((time.perf_counter() - total_start) * 1000, 2) stats = { **outcome.stats, + "source_failures": [*(outcome.stats.get("source_failures") or []), *lexical_failures], "requested_strategy": requested_strategy, "strategy_origin": resolved.origin, "requested_top_k": requested_limit, diff --git a/apps/api/sag_api/services/settings_service.py b/apps/api/sag_api/services/settings_service.py index 2ff7b533..e80a4703 100644 --- a/apps/api/sag_api/services/settings_service.py +++ b/apps/api/sag_api/services/settings_service.py @@ -21,7 +21,7 @@ from sag_api.core.errors import ConfigurationError, ConflictError from sag_api.core.logging import get_logger from sag_api.core.model_providers import get_model_provider -from sag_api.db.models import Document, Setting, Source +from sag_api.db.models import Document, Setting from sag_api.enums import JEV_SCORED_STRATEGIES, SEARCH_STRATEGIES, normalize_search_strategy from sag_api.schemas.system import ModelConfigUpdate @@ -519,17 +519,6 @@ async def _save_model_config_locked(session: AsyncSession, patch: dict) -> dict: raise ConfigurationError( f"{message} 当前默认检索模式为 JEV 模式;请先改为其他模式,或补填该服务的 API Key。", code=code, ) - source_default = await session.scalar( - select(Source.id).where( - Source.is_deleting.is_(False), - Source.default_search_strategy.in_(JEV_SCORED_STRATEGIES), - ).limit(1) - ) - if source_default is not None: - raise ConfigurationError( - f"{message} 已有信源默认使用 JEV 模式;请先修改信源默认模式,或补填该服务的 API Key。", - code=code, - ) identity = ("llm_provider", "llm_responses_provider", "llm_responses_endpoint") if ( not _settings.lock_llm_config diff --git a/apps/api/sag_api/services/source_service.py b/apps/api/sag_api/services/source_service.py index 5e642ca7..3f5b3942 100644 --- a/apps/api/sag_api/services/source_service.py +++ b/apps/api/sag_api/services/source_service.py @@ -19,14 +19,12 @@ from sag_api.db.models import Document, Job, OctxInstallation, OctxTransfer, Source from sag_api.enums import ( CONNECTOR_SOURCE_TYPE, - SEARCH_STRATEGIES, DocumentStatus, JobStatus, JobType, OctxTransferStatus, SourceStatus, SourceType, - normalize_search_strategy, ) from sag_api.jobs import JobQueue from sag_api.jobs.scheduling import DELETE_PRIORITY, set_scheduler @@ -99,37 +97,21 @@ async def get_source(session: AsyncSession, source_id: str) -> Source: return source -def validated_default_search_strategy(value: str | None, configuration=settings) -> str | None: - """信源默认检索模式必须是当前部署可用的模式;JEV 付费模式还要求已保存 API Key。 - - 与设置页、Agent 人格使用同一能力报告,拒绝时带相同原因码供前端提示。 - """ - if value is None: - return None - strategy = normalize_search_strategy(str(value)) - if strategy not in SEARCH_STRATEGIES: - raise ValidationError(f"不支持的检索模式:{value}") - EngineManager.require_strategy_available(configuration, strategy) - return strategy - - async def create_source( session: AsyncSession, data: SourceCreate, *, engine_manager: EngineManager ) -> Source: connector = registry.get(data.connector_kind) connector.validate_config(data.config) source_type = CONNECTOR_SOURCE_TYPE.get(data.connector_kind, SourceType.DOCUMENT) - # 与设置页、Agent 人格一致,按全局配置单例判断模式可用性。 - default_strategy = validated_default_search_strategy(data.default_search_strategy) source = Source( name=data.name, + engine_kind=data.engine_kind, description=data.description, source_type=source_type, connector_kind=data.connector_kind, sag_source_config_id=f"src_{new_id()[:16]}", config=initialize_vector_identity_state(data.config or {}), - default_search_strategy=default_strategy, ) session.add(source) await session.commit() @@ -165,9 +147,6 @@ async def update_source( source.description = data.description if data.status is not None: source.status = data.status - if "default_search_strategy" in data.model_fields_set: - # 显式 null 表示改回跟随全局默认;只影响后续检索,不触发文档重处理。 - source.default_search_strategy = validated_default_search_strategy(data.default_search_strategy) await session.commit() await session.refresh(source) from sag_api.services.universe_service import schedule_universe_refresh diff --git a/apps/api/sag_api/tools/builtin.py b/apps/api/sag_api/tools/builtin.py index 27d03420..75bc2e4f 100644 --- a/apps/api/sag_api/tools/builtin.py +++ b/apps/api/sag_api/tools/builtin.py @@ -19,11 +19,10 @@ from sag_api.connectors.web import extract_web_markdown, extract_web_title from sag_api.core.config import settings from sag_api.core.logging import get_logger -from sag_api.enums import JEV_SCORED_STRATEGIES, SEARCH_STRATEGIES, normalize_search_strategy +from sag_api.enums import JEV_SCORED_STRATEGIES from sag_api.generation import build_citations from sag_api.sag import RetrievedSection from sag_api.services.retrieval_service import ( - common_source_default_strategy, event_scores_from_evidence, published_document_inputs, recall_event_scores, @@ -83,21 +82,10 @@ def _events_by_section(events: list | None) -> dict[tuple[str, str], list]: def knowledge_search_strategy( persona: dict[str, Any], configuration: Any = settings, sources=(), requested: str | None = None, ) -> str: - """Explicit turn choice → persona → shared source default → legacy default (vector unless a JEV mode is global).""" + """Explicit turn choice → persona → automatic per-source engine routing.""" if requested: return requested - configured = normalize_search_strategy(configuration.search_strategy) - default = configured if configured in JEV_SCORED_STRATEGIES else "vector" - value = persona.get("search_strategy") or common_source_default_strategy(sources) or default - if default in JEV_SCORED_STRATEGIES and ( - not isinstance(value, str) or normalize_search_strategy(value) not in SEARCH_STRATEGIES - ): - # The engine falls back to global JEV for unknown modes. Resolve that - # here too so the tool's budget and evidence handling use the same mode. - return default - # Existing persona values, including legacy aliases, retain the engine's - # resolution rules; preparing an unused tool must not add validation gates. - return value + return persona.get("search_strategy") or "auto" def knowledge_search_strategy_origin( @@ -108,8 +96,6 @@ def knowledge_search_strategy_origin( return "request" if persona.get("search_strategy"): return "persona" - if common_source_default_strategy(sources): - return "source_default" return "global" @@ -285,7 +271,12 @@ async def invoke(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult: strategy=strategy, top_k=limit, ) - is_jev = strategy in JEV_SCORED_STRATEGIES + effective = (ctx.engine_manager._effective_search_strategy(strategy) + if hasattr(ctx.engine_manager, "_effective_search_strategy") else strategy) + is_jev = effective in JEV_SCORED_STRATEGIES or (effective == "auto" and ( + getattr(ctx.engine_manager, "_settings", settings).search_strategy == "multi_jev" + or any(getattr(source, "engine_kind", "sag1") == "sag2" for source in ctx.sources) + )) if is_jev: outcome = await retrieval event_scores: dict[tuple[str, str], float] = {} @@ -349,6 +340,11 @@ async def invoke(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult: for c in citations: c["n"] = c["n"] + offset content = _format_sections(sections, offset, list(graph.events) if graph is not None else None) + if outcome.stats.get("engine_failures"): + warnings = ";".join( + f"{item['engine_kind']}:{item['message']}" for item in outcome.stats["engine_failures"] + ) + content = f"注意:本次检索结果不完整,以下算法检索失败或不完整:{warnings}。回答须说明此限制。\n\n{content}" if is_jev and outcome.stats.get("fallback_used"): content = "(JEV 精排未完成,本次返回粗排结果)\n" + content return ToolResult( diff --git a/apps/api/tests/test_agent_tools.py b/apps/api/tests/test_agent_tools.py index e99d7b4b..908e80f7 100644 --- a/apps/api/tests/test_agent_tools.py +++ b/apps/api/tests/test_agent_tools.py @@ -90,15 +90,15 @@ async def invoke(self, args, ctx): @pytest.mark.parametrize("persona", [ {}, {"search_strategy": ""}, {"search_strategy": False}, {"search_strategy": None}, ]) -def test_existing_assistant_default_stays_vector_until_jev_is_selected(strategy, persona): - assert knowledge_search_strategy(persona, SimpleNamespace(search_strategy=strategy)) == "vector" +def test_unset_assistant_uses_automatic_routing(strategy, persona): + assert knowledge_search_strategy(persona, SimpleNamespace(search_strategy=strategy)) == "auto" @pytest.mark.parametrize("persona", [ {}, {"search_strategy": ""}, {"search_strategy": False}, {"search_strategy": None}, ]) def test_unset_assistant_strategy_follows_explicit_global_jev_selection(persona): - assert knowledge_search_strategy(persona, SimpleNamespace(search_strategy="multi_jev")) == "multi_jev" + assert knowledge_search_strategy(persona, SimpleNamespace(search_strategy="multi_jev")) == "auto" @pytest.mark.parametrize("strategy", ["vector", "multi", "multi_es_fast", "atomic", "multi_jev", "typo"]) @@ -137,11 +137,11 @@ async def test_legacy_persona_does_not_block_tool_preparation_or_chat_without_so @pytest.mark.asyncio @pytest.mark.parametrize(("global_strategy", "persona", "expected"), [ - ("multi", {}, "vector"), - ("multi_es_fast", {"search_strategy": ""}, "vector"), - ("multi", {"search_strategy": False}, "vector"), - ("multi", {"search_strategy": None}, "vector"), - ("multi_jev", {}, "multi_jev"), + ("multi", {}, "auto"), + ("multi_es_fast", {"search_strategy": ""}, "auto"), + ("multi", {"search_strategy": False}, "auto"), + ("multi", {"search_strategy": None}, "auto"), + ("multi_jev", {}, "auto"), ("multi_jev", {"search_strategy": "vector"}, "vector"), ("vector", {"search_strategy": "multi_jev"}, "multi_jev"), ("multi", {"search_strategy": "atomic"}, "multi"), @@ -177,7 +177,7 @@ async def events(*_args, **_kwargs): {"query": "查询旧资料"}, ToolContext(engine_manager=engine, sources=[source], persona=persona), ) assert selected == [expected] - assert bool(event_calls) is (expected != "multi_jev") + assert bool(event_calls) is not (expected == "multi_jev" or (expected == "auto" and global_strategy == "multi_jev")) assert result.data["section_count"] == 0 diff --git a/apps/api/tests/test_chat_turn_strategy.py b/apps/api/tests/test_chat_turn_strategy.py index e50188da..7f224004 100644 --- a/apps/api/tests/test_chat_turn_strategy.py +++ b/apps/api/tests/test_chat_turn_strategy.py @@ -44,9 +44,9 @@ def test_turn_choice_precedes_persona_source_default_and_global(): assert knowledge_search_strategy_origin(persona, scoped, "multi_jev") == "request" assert knowledge_search_strategy(persona, configuration, scoped) == "multi" assert knowledge_search_strategy_origin(persona, scoped) == "persona" - assert knowledge_search_strategy({}, configuration, scoped) == "sag2" - assert knowledge_search_strategy_origin({}, scoped) == "source_default" - assert knowledge_search_strategy({}, configuration, []) == "vector" + assert knowledge_search_strategy({}, configuration, scoped) == "auto" + assert knowledge_search_strategy_origin({}, scoped) == "global" + assert knowledge_search_strategy({}, configuration, []) == "auto" assert knowledge_search_strategy_origin({}, []) == "global" @@ -92,7 +92,7 @@ async def graph(*_args, **_kwargs): )) assert calls[-1] == "multi" and result.data["retrieval_stats"]["strategy_origin"] == "persona" result = await tool.invoke({"query": "q"}, ToolContext(engine_manager=engine, sources=[scoped], persona={})) - assert calls[-1] == "sag2" and result.data["retrieval_stats"]["strategy_origin"] == "source_default" + assert calls[-1] == "auto" and result.data["retrieval_stats"]["strategy_origin"] == "global" # The adapted tool's budget follows the turn choice as well. adapted = _adapt_tool(tool, ToolContext( @@ -109,7 +109,7 @@ async def capture(arguments, context): return result monkeypatch.setattr(tool, "invoke", capture) - for source_default, expected_origin in [("sag2", "source_default"), (None, "global")]: + for source_default, expected_origin in [("sag2", "global"), (None, "global")]: scoped.default_search_strategy = source_default persona = {} adapted = _adapt_tool(tool, ToolContext(engine_manager=engine, sources=[scoped], persona=persona), []) diff --git a/apps/api/tests/test_engine_routing.py b/apps/api/tests/test_engine_routing.py new file mode 100644 index 00000000..e60e8ecb --- /dev/null +++ b/apps/api/tests/test_engine_routing.py @@ -0,0 +1,89 @@ +from types import SimpleNamespace + +import pytest + +from sag_api.sag.dto import RetrievedSection, SearchOutcome +from sag_api.services.engine_routing import retrieve_automatic + + +@pytest.mark.asyncio +async def test_auto_routes_bound_engines_and_interleaves_without_comparing_scores(): + sources = [SimpleNamespace(engine_kind="sag1", id="one"), SimpleNamespace(engine_kind="sag2", id="two")] + calls = [] + + async def retrieve(group, strategy): + calls.append((group[0].id, strategy)) + return SearchOutcome( + query="q", + sections=[ + RetrievedSection( + chunk_id=strategy, + source_config_id=group[0].id, + content=strategy, + score=100 if strategy == "vector" else 0.9, + ) + ], + ) + + result = await retrieve_automatic(sources, "q", sag1_strategy="vector", top_k=8, retrieve=retrieve) + assert set(calls) == {("one", "vector"), ("two", "sag2")} + assert {s.metadata["engine_kind"] for s in result.sections} == {"sag1", "sag2"} + assert result.stats["effective_strategy"] == "auto" + + +@pytest.mark.asyncio +async def test_partial_failure_is_reported_instead_of_appearing_complete(): + sources = [SimpleNamespace(engine_kind="sag1"), SimpleNamespace(engine_kind="sag2")] + + async def retrieve(group, strategy): + if strategy == "sag2": + raise RuntimeError("JEV unavailable") + return SearchOutcome(query="q", sections=[RetrievedSection(content="evidence", chunk_id="one")]) + + result = await retrieve_automatic(sources, "q", sag1_strategy="vector", top_k=8, retrieve=retrieve) + assert result.stats["partial_results"] is True + assert result.stats["engine_failures"][0]["engine_kind"] == "sag2" + assert len(result.sections) == 1 + + +@pytest.mark.asyncio +async def test_sag1_fanout_failure_is_not_hidden_by_successful_native_group(): + from sag_api.core.config import Settings + from sag_api.sag.search_reader import SearchReader + + async def broken(*args, **kwargs): + raise RuntimeError("legacy storage offline") + + reader = SearchReader(SimpleNamespace( + settings=Settings(_env_file=None), effective_search_strategy=lambda value: value, search=broken, + )) + async def retrieve(group, strategy): + if strategy == "multi": + return await reader.search_many([("legacy", None)], "q", strategy=strategy) + return SearchOutcome(query="q", sections=[RetrievedSection(content="native evidence")]) + + result = await retrieve_automatic( + [SimpleNamespace(engine_kind="sag1"), SimpleNamespace(engine_kind="sag2")], "q", + sag1_strategy="multi", top_k=8, retrieve=retrieve, + ) + assert result.stats["partial_results"] is True + assert result.stats["engine_failures"][0]["engine_kind"] == "sag1" + assert "legacy storage offline" in result.stats["engine_failures"][0]["message"] + + +@pytest.mark.asyncio +async def test_mixed_results_preserve_jev_fallback_provenance(): + async def retrieve(group, strategy): + return SearchOutcome(query="q", sections=[], stats={ + "fallback_used": strategy == "multi_jev", + "ranking": {"method": "jev", "fallback_reason": "deadline" if strategy == "multi_jev" else None}, + "source_stats": {strategy: {"fallback_used": strategy == "multi_jev"}}, + }) + result = await retrieve_automatic( + [SimpleNamespace(engine_kind="sag1"), SimpleNamespace(engine_kind="sag2")], "q", + sag1_strategy="multi_jev", top_k=8, retrieve=retrieve, + ) + assert result.stats["fallback_used"] is True + assert result.stats["jev_fallback_used"] is True + assert result.stats["engine_stats"]["sag1"]["ranking"]["fallback_reason"] == "deadline" + assert result.stats["source_stats"]["multi_jev"]["fallback_used"] is True diff --git a/apps/api/tests/test_jev_config.py b/apps/api/tests/test_jev_config.py index 2406d2e1..e87dddaf 100644 --- a/apps/api/tests/test_jev_config.py +++ b/apps/api/tests/test_jev_config.py @@ -223,9 +223,9 @@ async def test_jev_service_rejects_invalid_explicit_fields_before_persisting(jev @pytest.mark.parametrize("strategy", ["multi_jev", "sag2"]) @pytest.mark.parametrize("endpoint", [None, "https://replacement.example/score"]) -async def test_jev_connection_change_preserves_source_defaults_atomically(jev_config_client, strategy, endpoint): +async def test_retired_source_preferences_do_not_block_jev_connection_changes(jev_config_client, strategy, endpoint): from sag_api.core.db import SessionLocal - from sag_api.db.models import Setting, Source + from sag_api.db.models import Source client, headers, resets = jev_config_client initial = await client.put( @@ -239,23 +239,16 @@ async def test_jev_connection_change_preserves_source_defaults_atomically(jev_co session.add(Source(id=source_id, name="Protected source", sag_source_config_id=source_id, default_search_strategy=strategy)) await session.commit() - row = await session.scalar(select(Setting).where(Setting.scope == "global", Setting.key == "model_config")) - stored_before = dict(row.value) - settings_before = settings.model_dump() - reset_count = len(resets) try: - rejected = await client.put( + changed = await client.put( "/api/v1/system/model-config", headers=headers, json={"jev_endpoint": endpoint}, ) - assert rejected.status_code == 400, rejected.text - assert rejected.json()["error"]["code"] in {"jev_not_configured", "jev_api_key_missing"} - assert "信源" in rejected.json()["error"]["message"] - assert settings.model_dump() == settings_before - assert len(resets) == reset_count + assert changed.status_code == 200, changed.text + assert changed.json()["config"]["jev_api_key_set"] is False async with SessionLocal() as session: - row = await session.scalar(select(Setting).where(Setting.scope == "global", Setting.key == "model_config")) - assert row.value == stored_before - assert (await session.get(Source, source_id)).default_search_strategy == strategy + legacy = await session.get(Source, source_id) + assert legacy.default_search_strategy == strategy + assert legacy.engine_kind == "sag1" # Supplying a key for the new destination keeps the saved source usable. replaced = await client.put( diff --git a/apps/api/tests/test_jev_retrieval.py b/apps/api/tests/test_jev_retrieval.py index 1056cf01..d4ad7f5e 100644 --- a/apps/api/tests/test_jev_retrieval.py +++ b/apps/api/tests/test_jev_retrieval.py @@ -227,7 +227,8 @@ async def test_agent_uses_global_jev_and_preserves_order_and_stats(monkeypatch, async def retrieve(manager, sources, query, *, strategy, top_k): calls.append(strategy) - assert manager._effective_search_strategy(strategy) == "multi_jev" + expected = "multi_jev" if persona.get("search_strategy") else "auto" + assert manager._effective_search_strategy(strategy) == expected return SearchOutcome(query=query, sections=[hit("first", 0.2), hit("second", 0.1)], stats={"ranking": {"method": "jev", "fallback_reason": None}}) @@ -252,7 +253,7 @@ async def reorder(*args, **kwargs): result = await builtin.SearchContextTool().invoke( {"query": "q"}, ToolContext(engine_manager=engine, sources=[source], persona=persona), ) - assert calls == ["multi_jev"] + assert calls == ["retired_custom_mode" if persona.get("search_strategy") else "auto"] assert [section.chunk_id for section in result.data["sections"]] == ["first", "second"] assert result.data["retrieval_stats"]["ranking"]["method"] == "jev" diff --git a/apps/api/tests/test_jev_transports.py b/apps/api/tests/test_jev_transports.py index 97658952..83d09fec 100644 --- a/apps/api/tests/test_jev_transports.py +++ b/apps/api/tests/test_jev_transports.py @@ -70,7 +70,7 @@ async def invoke(self, _arguments, context): adapted = _adapt_tool(RecordingSearchTool(), ToolContext(engine_manager=object()), []) active.search_strategy = "multi_jev" await adapted.execute({}, SimpleNamespace(cancellation=SimpleNamespace(raise_if_cancelled=lambda: None))) - assert used == [("vector", "global")] + assert used == [("auto", "global")] @pytest.mark.asyncio diff --git a/apps/api/tests/test_retrieval_relevance.py b/apps/api/tests/test_retrieval_relevance.py index 83267238..d07c2c73 100644 --- a/apps/api/tests/test_retrieval_relevance.py +++ b/apps/api/tests/test_retrieval_relevance.py @@ -335,7 +335,7 @@ async def grep_chunks(self, source_config_id, term, **_kwargs): @pytest.mark.asyncio -async def test_total_latency_includes_query_analysis(monkeypatch): +async def test_total_latency_includes_query_analysis(monkeypatch, publication_source): from types import SimpleNamespace from sag_api.core.db import init_db @@ -360,10 +360,11 @@ async def search_many(self, _targets, query, **_kwargs): ) await init_db() + source = await publication_source("latency", "cfg-latency", "doc-latency") outcome = await retrieval_service.retrieve_relevant_sections( EmptyEngine(), - [], - "肉类清汤", + [source], + "肉类清汤", strategy="vector", ) assert outcome.stats["latency_total_ms"] == 250.0 diff --git a/apps/api/tests/test_sag2_native_engine.py b/apps/api/tests/test_sag2_native_engine.py new file mode 100644 index 00000000..ac355319 --- /dev/null +++ b/apps/api/tests/test_sag2_native_engine.py @@ -0,0 +1,269 @@ +"""Real SQLite lifecycle tests: no LLM, embedding, or JEV needed for native indexing.""" + +import os +from pathlib import Path + +import pytest +from zleap.sag.operations import DeleteSourceRequest, OperationContext +from zleap.sag.operations import OperationContext as Sag2Context + +from sag_api.core.config import Settings +from sag_api.sag.incremental_processor import IncrementalDocumentProcessor +from sag_api.sag.sag2_source_engine import Sag2SourceEngine + + +@pytest.mark.asyncio +@pytest.mark.parametrize("provider", ["sqlite", "postgres"]) +async def test_native_index_replay_read_and_delete_without_models(tmp_path, provider): + if provider == "postgres" and not os.getenv("SAG_NATIVE_POSTGRES_PORT"): + pytest.skip("requires dedicated native PostgreSQL test container") + settings = Settings( + _env_file=None, data_dir=str(tmp_path), jev_endpoint=None, jev_api_key=None, + sag_relational_provider=provider, sag_pg_host="127.0.0.1", + sag_pg_port=int(os.getenv("SAG_NATIVE_POSTGRES_PORT", "5432")), + sag_pg_user="postgres", sag_pg_password="pr253-disposable", sag_pg_database="sag_native", + ) + engine = Sag2SourceEngine(settings, "src_native") + await engine.start() + try: + path = tmp_path / "manual.md" + path.write_text("# 星港设备维护\nZX-253 每隔14天校准,负责人林澈。") + processor = IncrementalDocumentProcessor(engine, "src_native", max_concurrency=1, language="zh") + request = await processor.build_request( + path, + context=OperationContext( + operation_id="op-native", + idempotency_key="op-native", + request_digest="0" * 64, + fence_scope="src_native", + fence_token=1, + owner_id="test", + isolation="input", + ), + input_id="doc-native", + ) + result = await engine.process_source(request) + assert result.status == "succeeded", result.failure_message + assert result.result["event_ref"]["event_ids"] == [] + assert result.result["event_ref"]["entity_ids"] == [] + chunk = result.result["chunk_ref"] + assert chunk["chunk_ids"] + assert (await engine.get_operation_status("op-native")).operation_id == result.operation_id + replay = await engine.process_source(request) + assert replay.result == result.result + stored = await engine.read_chunk("doc-native", chunk["chunk_ids"][0], data_source_id="src_native") + assert "ZX-253" in stored.content + await engine.delete_source( + DeleteSourceRequest( + context=Sag2Context( + operation_id="del-native", + idempotency_key="del-native", + request_digest="0" * 64, + fence_scope="src_native", + fence_token=1, + owner_id="test", + ), + data_source_id="src_native", + source_id="doc-native", + ) + ) + assert await engine.read_chunk("doc-native", chunk["chunk_ids"][0], data_source_id="src_native") is None + assert not (Path(settings.data_dir) / "sag.db").exists() + finally: + await engine.aclose() + + +@pytest.mark.asyncio +async def test_manager_provisions_native_engine_without_sag1_store(tmp_path): + from types import SimpleNamespace + + from sag_api.sag.engine_manager import EngineManager + + settings = Settings(_env_file=None, data_dir=str(tmp_path), jev_endpoint=None, jev_api_key=None) + manager = EngineManager(settings) + source = SimpleNamespace(engine_kind="sag2", config={}, name="native", description="") + try: + await manager.provision("src_manager", source) + assert isinstance(manager._slots["src_manager"].engine, Sag2SourceEngine) + timeline = await manager.universe_timeline( + "src_manager", source_ids=(), source_revision="native-revision", source=source, + ) + assert timeline.total_events == 0 + assert timeline.bundles == [] + assert not (tmp_path / "sag.db").exists() + finally: + await manager.release("src_manager") + + +from tests.test_source_default_strategy import source_client # noqa: E402,F401 + + +@pytest.mark.asyncio +async def test_sag2_upload_job_publishes_zero_events_without_model_keys(source_client): # noqa: F811 + import asyncio + + from sag_api.main import app + + created = await source_client.post("/api/v1/sources", json={"name": "Native job", "engine_kind": "sag2"}) + assert created.status_code == 201, created.text + source = created.json() + uploaded = await source_client.post( + f"/api/v1/sources/{source['id']}/documents", + files={"file": ("manual.md", b"# Native\nZX-253 calibrates every 14 days.", "text/markdown")}, + ) + assert uploaded.status_code == 201, uploaded.text + await asyncio.wait_for(app.state.job_queue._queue.join(), 20) + document = (await source_client.get(f"/api/v1/sources/{source['id']}/documents/{uploaded.json()['id']}")).json() + assert document["status"] == "ready", document + assert document["event_count"] == 0 + assert document["chunk_count"] > 0 + base = f"/api/v1/sources/{source['id']}" + doc = f"{base}/documents/{uploaded.json()['id']}" + for endpoint in [f"{base}/octx-exports", f"{doc}/octx-exports"]: + blocked = await source_client.post(endpoint, json={}) + assert blocked.status_code == 422, blocked.text + assert "SAG2" in blocked.text + outline = await source_client.get(f"{base}/outline", params={"document_id": uploaded.json()["id"]}) + assert outline.status_code == 200, outline.text + reprocess = await source_client.post(f"{doc}/reprocess") + assert reprocess.status_code == 200, reprocess.text + await asyncio.wait_for(app.state.job_queue._queue.join(), 20) + republished = (await source_client.get(doc)).json() + assert republished["status"] == "ready", republished + assert republished["event_count"] == 0 + deleted = await source_client.delete(doc) + assert deleted.status_code == 202, deleted.text + await asyncio.wait_for(app.state.job_queue._queue.join(), 20) + assert (await source_client.get(doc)).status_code == 404 + async def completed_job(response): + async with asyncio.timeout(20): + while True: + current = (await source_client.get(f"/api/v1/jobs/{response.json()['id']}")).json() + if current["status"] in {"succeeded", "failed"}: + return current + await asyncio.sleep(0.02) + deletion = await completed_job(deleted) + assert deletion["status"] == "succeeded", deletion + whole = await source_client.delete(base) + assert whole.status_code == 202, whole.text + await asyncio.wait_for(app.state.job_queue._queue.join(), 20) + source_deletion = await completed_job(whole) + assert source_deletion["status"] == "succeeded", source_deletion + from sag_api.core.db import SessionLocal + from sag_api.db.models import Source + async with SessionLocal() as session: + assert await session.get(Source, source["id"]) is None + + +@pytest.mark.asyncio +async def test_native_search_only_uses_published_inputs_and_maps_business_source(tmp_path): + from sag_api.sag.sag2_native_search import Sag2NativeSearchHolder + from tests.test_sag2_engine_integration import OverlapScorer + + settings = Settings( + _env_file=None, data_dir=str(tmp_path), jev_endpoint="https://jev.invalid/score", jev_api_key="test" + ) + engine = Sag2SourceEngine(settings, "cfg-native") + await engine.start() + refs = {} + try: + for input_id in ["published", "candidate"]: + path = tmp_path / f"{input_id}.md" + path.write_text(f"# {input_id}\nAlice 出生在北京,1990年移居上海。") + processor = IncrementalDocumentProcessor(engine, "cfg-native", max_concurrency=1, language="zh") + req = await processor.build_request( + path, + context=OperationContext( + operation_id=input_id, + idempotency_key=input_id, + request_digest="0" * 64, + fence_scope="cfg-native", + fence_token=1, + owner_id="test", + isolation="input", + ), + input_id=input_id, + ) + result = await engine.process_source(req) + assert result.status == "succeeded", result.failure_message + refs[input_id] = result.result["chunk_ref"]["chunk_ids"] + holder = Sag2NativeSearchHolder(settings, scorer_factory=lambda _cfg: OverlapScorer()) + try: + outcome = await holder.search( + [("cfg-native", None)], + "Alice 出生在哪?", + top_k=5, + requested_sources=1, + source_limit_applied=False, + source_ids_by_config={"cfg-native": ("published",)}, + ) + assert outcome.sections + assert all(section.source_id == "published" for section in outcome.sections) + assert all(section.source_config_id == "cfg-native" for section in outcome.sections) + assert refs["candidate"][0] not in {section.chunk_id for section in outcome.sections} + finally: + await holder.aclose() + finally: + await engine.aclose() + + +@pytest.mark.asyncio +async def test_native_cancel_is_retryable_and_resume_is_not_invalidated_by_another_input(tmp_path): + from zleap.sag.pipeline import CancellationToken + settings = Settings(_env_file=None, data_dir=str(tmp_path), jev_endpoint=None, jev_api_key=None) + engine = Sag2SourceEngine(settings, "cancel-source") + await engine.start() + try: + path = tmp_path / "pause.md" + path.write_text("# Native pause\nEvidence for document resume.") + processor = IncrementalDocumentProcessor(engine, "cancel-source", max_concurrency=1, language="zh") + async def request(identifier): + return await processor.build_request(path, context=OperationContext( + operation_id=identifier, idempotency_key=identifier, request_digest="0"*64, + fence_scope="cancel-source", fence_token=1, owner_id="test", isolation="input", + ), input_id=identifier) + cancellation = CancellationToken() + async def observer(event): + if event.stage == "chunk": + cancellation.cancel() + first = await request("paused-input") + paused = await engine.process_source(first, observer=observer, cancellation=cancellation) + assert paused.retryable is True + assert paused.failure_code == "cancelled" + assert (await engine.process_source(await request("other-input"))).status == "succeeded" + resumed = await engine.process_source(first) + assert resumed.status == "succeeded", resumed.failure_message + finally: + await engine.aclose() + + +@pytest.mark.asyncio +@pytest.mark.parametrize("kind", ["document", "source"]) +async def test_native_deletion_receipts_authorize_application_cleanup(tmp_path, kind): + from zleap.sag.operations import DeleteDataSourceRequest + + from sag_api.jobs.tasks import _require_delete_completion + + engine = Sag2SourceEngine(Settings(_env_file=None, data_dir=str(tmp_path)), "delete-source") + await engine.start() + try: + document_request = DeleteSourceRequest( + context=OperationContext( + operation_id="delete-undispatched", idempotency_key="delete-undispatched", + request_digest="0" * 64, fence_scope="delete-source", fence_token=1, owner_id="test", + ), data_source_id="delete-source", source_id="never-dispatched", + ) + if kind == "document": + document_receipt = await engine.delete_source(document_request) + _require_delete_completion(document_request, document_receipt) + return + request = DeleteDataSourceRequest( + context=OperationContext( + operation_id="delete-all", idempotency_key="delete-all", request_digest="0" * 64, + fence_scope="delete-source", fence_token=1, owner_id="test", + ), data_source_id="delete-source", + ) + receipt = await engine.delete_data_source(request) + _require_delete_completion(request, receipt) + finally: + await engine.aclose() diff --git a/apps/api/tests/test_sag2_octx_policy.py b/apps/api/tests/test_sag2_octx_policy.py new file mode 100644 index 00000000..f3b3155e --- /dev/null +++ b/apps/api/tests/test_sag2_octx_policy.py @@ -0,0 +1,16 @@ +from types import SimpleNamespace + +import pytest + +from sag_api.core.errors import ValidationError +from sag_api.services.knowledge_algorithms import require_sag1_octx + + +def test_legacy_sources_keep_octx_support(): + require_sag1_octx(SimpleNamespace()) + require_sag1_octx(SimpleNamespace(engine_kind="sag1")) + + +def test_sag2_rejects_octx_operations(): + with pytest.raises(ValidationError, match="SAG2"): + require_sag1_octx(SimpleNamespace(engine_kind="sag2")) diff --git a/apps/api/tests/test_sag2_retrieval.py b/apps/api/tests/test_sag2_retrieval.py index 45c67b69..76814d0d 100644 --- a/apps/api/tests/test_sag2_retrieval.py +++ b/apps/api/tests/test_sag2_retrieval.py @@ -496,6 +496,7 @@ async def test_sag2_business_path_preserves_engine_order_limit_and_publication(p from sag_api.services import retrieval_service source = await publication_source("sag2-business", "cfg-1", "document-1") + source.engine_kind = "sag2" class Engine: _settings = sag2_settings(search_strategy="sag2") @@ -513,18 +514,19 @@ async def grep_chunks(self, *args, **kwargs): result = await retrieval_service.retrieve_relevant_sections(Engine(), [source], "q", top_k=2) assert [section.chunk_id for section in result.sections] == ["first", "second"] assert [section.score for section in result.sections] == [0.21, 0.2] - assert result.stats["requested_strategy"] == "sag2" + assert result.stats["requested_strategy"] == "auto" assert result.stats["publication_filtered"] == 1 assert result.stats["lexical_candidates"] == 0 @pytest.mark.asyncio -async def test_agent_follows_global_sag2_and_gets_whole_search_budget(monkeypatch, publication_source): +async def test_agent_auto_routes_native_and_gets_whole_search_budget(monkeypatch, publication_source): from sag_api.services.agent_tooling import _adapt_tool from sag_api.tools import builtin from sag_api.tools.base import ToolContext source = await publication_source("sag2-agent", "cfg-1", "document-1") + source.engine_kind = "sag2" engine = EngineManager(sag2_settings( search_strategy="sag2", agent_tool_timeout_seconds=5, sag2_search_timeout_seconds=90, )) @@ -532,7 +534,7 @@ async def test_agent_follows_global_sag2_and_gets_whole_search_budget(monkeypatc async def retrieve(manager, sources, query, *, strategy, top_k): calls.append(strategy) - assert manager._effective_search_strategy(strategy) == "sag2" + assert strategy == "auto" return SearchOutcome(query=query, sections=[hit("first", 0.2), hit("second", 0.1)], stats={ "effective_strategy": "sag2", "ranking": {"method": "jev", "fallback_reason": None}, }) @@ -554,11 +556,13 @@ async def reorder(*args, **kwargs): result = await builtin.SearchContextTool().invoke( {"query": "q"}, ToolContext(engine_manager=engine, sources=[source], persona={}), ) - assert calls == ["sag2"] + assert calls == ["auto"] assert [section.chunk_id for section in result.data["sections"]] == ["first", "second"] assert result.data["retrieval_stats"]["effective_strategy"] == "sag2" - adapted = _adapt_tool(builtin.SearchContextTool(), ToolContext(engine_manager=engine, persona={}), []) + adapted = _adapt_tool( + builtin.SearchContextTool(), ToolContext(engine_manager=engine, sources=[source], persona={}), [] + ) assert adapted.spec.timeout_seconds is not None assert adapted.spec.timeout_seconds >= 90 + 12 diff --git a/apps/api/tests/test_search_strategy.py b/apps/api/tests/test_search_strategy.py index e259f27c..816fe40b 100644 --- a/apps/api/tests/test_search_strategy.py +++ b/apps/api/tests/test_search_strategy.py @@ -548,7 +548,7 @@ def test_strategies_capability_report_marks_multi_es_disabled_on_pgvector(monkey monkeypatch.setattr(settings, "sag_vector_provider", "pgvector") report = EngineManager.strategies_capability_report(settings) - assert set(report["enabled"]) == {"vector", "multi"} + assert set(report["enabled"]) == {"auto", "vector", "multi"} assert "multi_es_fast" in report["disabled"] disabled_entry = report["disabled"]["multi_es_fast"] assert disabled_entry["reason"] == "vector_provider_lacks_lexical" @@ -556,7 +556,7 @@ def test_strategies_capability_report_marks_multi_es_disabled_on_pgvector(monkey monkeypatch.setattr(settings, "sag_vector_provider", "lancedb") ok_report = EngineManager.strategies_capability_report(settings) - assert set(ok_report["enabled"]) == {"vector", "multi", "multi_es_fast"} + assert set(ok_report["enabled"]) == {"auto", "vector", "multi", "multi_es_fast"} assert ok_report["disabled"]["multi_jev"]["reason"] == "jev_not_configured" diff --git a/apps/api/tests/test_source_default_strategy.py b/apps/api/tests/test_source_default_strategy.py index 19276d47..1a52508a 100644 --- a/apps/api/tests/test_source_default_strategy.py +++ b/apps/api/tests/test_source_default_strategy.py @@ -7,12 +7,8 @@ import pytest from sag_api.core.config import Settings, settings -from sag_api.sag import RetrievedSection, SearchOutcome -from sag_api.sag.engine_manager import EngineManager from sag_api.services.retrieval_service import ( - common_source_default_strategy, resolve_search_strategy, - retrieve_relevant_sections, ) from sag_api.tools.builtin import knowledge_search_strategy @@ -65,155 +61,36 @@ async def skip_unrelated_universe_refresh(*_args, **_kwargs): setattr(settings, key, value) -def test_common_default_requires_every_source_to_agree(): - assert common_source_default_strategy([]) is None - assert common_source_default_strategy([source("sag2"), source("sag2", "cfg-2")]) == "sag2" - assert common_source_default_strategy([source("sag2"), source(None, "cfg-2")]) is None - assert common_source_default_strategy([source("sag2"), source("vector", "cfg-2")]) is None - # Legacy aliases normalize before comparison. - assert common_source_default_strategy([source("atomic"), source("multi", "cfg-2")]) == "multi" - - -def test_resolution_order_request_persona_source_global(): +def test_default_resolution_ignores_retired_per_source_preferences(): configuration = configured(search_strategy="vector") scoped = [source("sag2"), source("sag2", "cfg-2")] - - def resolved(**kwargs): - result = resolve_search_strategy(configuration=configuration, **kwargs) - return result.strategy, result.origin - - assert resolved(requested="multi", persona_strategy="multi_jev", sources=scoped) == ("multi", "request") - assert resolved(persona_strategy="multi_jev", sources=scoped) == ("multi_jev", "persona") - assert resolved(sources=scoped) == ("sag2", "source_default") - assert resolved(sources=[source("sag2"), source(None, "cfg-2")]) == ("vector", "global") - assert resolved() == ("vector", "global") - - -def test_agent_tool_follows_source_default_before_legacy_vector(): - configuration = configured(search_strategy="multi_es_fast") - assert knowledge_search_strategy({}, configuration, [source("sag2")]) == "sag2" - assert knowledge_search_strategy({"search_strategy": "vector"}, configuration, [source("sag2")]) == "vector" - assert knowledge_search_strategy({}, configuration, [source("sag2"), source(None, "cfg-2")]) == "vector" - # A global JEV default still wins over an unknown legacy persona value, as before. - assert knowledge_search_strategy({"search_strategy": "retired"}, configured(search_strategy="sag2"), []) == "sag2" + assert resolve_search_strategy(configuration=configuration, sources=scoped).strategy == "auto" + assert knowledge_search_strategy({}, configuration, scoped) == "auto" + assert resolve_search_strategy(requested="multi", configuration=configuration, sources=scoped).strategy == "multi" @pytest.mark.asyncio -async def test_retrieval_reports_source_default_origin(monkeypatch): - from sag_api.services import retrieval_service - - captured = [] - - class Engine: - _settings = configured(search_strategy="vector") - - async def search_many(self, targets, query, **kwargs): - captured.append(kwargs["strategy"]) - return SearchOutcome(query=query, sections=[RetrievedSection( - chunk_id="c1", heading="h", content="evidence", score=0.9, source_config_id="cfg-1", source_id="d1", - metadata={"score_source": "jev"}, - )], stats={"effective_strategy": "sag2"}) - - async def published(sources, **_kwargs): - return {s.sag_source_config_id: ("d1",) for s in sources} - - monkeypatch.setattr(retrieval_service, "published_document_inputs", published) - outcome = await retrieve_relevant_sections(Engine(), [source("sag2")], "q", top_k=3) - assert captured == ["sag2"] - assert outcome.stats["requested_strategy"] == "sag2" - assert outcome.stats["strategy_origin"] == "source_default" - - outcome = await retrieve_relevant_sections(Engine(), [source("sag2")], "q", strategy="multi_jev", top_k=3) - assert captured[-1] == "multi_jev" - assert outcome.stats["strategy_origin"] == "request" - - -async def test_source_default_mode_is_validated_persisted_and_clearable(source_client, monkeypatch): - client = source_client - monkeypatch.setattr(settings, "sag_vector_provider", "lancedb") - monkeypatch.setattr(settings, "jev_endpoint", "https://jev.example/score") - monkeypatch.setattr(settings, "jev_api_key", None) - before = {item["id"] for item in (await client.get("/api/v1/sources")).json()} - - # Paid mode without a key is rejected before any row is written. - rejected = await client.post("/api/v1/sources", json={"name": "SAG2 库", "default_search_strategy": "sag2"}) - assert rejected.status_code == 400, rejected.text - assert rejected.json()["error"]["code"] == "jev_api_key_missing" - assert {item["id"] for item in (await client.get("/api/v1/sources")).json()} == before - - unknown = await client.post("/api/v1/sources", json={"name": "x", "default_search_strategy": "nope"}) - assert unknown.status_code == 422 - - monkeypatch.setattr(settings, "jev_api_key", "synthetic-jev-key") - created = await client.post("/api/v1/sources", json={"name": "SAG2 库", "default_search_strategy": "sag2"}) - assert created.status_code == 201, created.text - body = created.json() - assert body["default_search_strategy"] == "sag2" - source_id = body["id"] - assert (await client.get(f"/api/v1/sources/{source_id}")).json()["default_search_strategy"] == "sag2" - - # Follow-global is the default when the field is omitted. - plain = await client.post("/api/v1/sources", json={"name": "普通库"}) - assert plain.status_code == 201 and plain.json()["default_search_strategy"] is None - - # Updates: a mode the storage cannot serve is rejected; null clears back to global. - monkeypatch.setattr(settings, "sag_vector_provider", "pgvector") - blocked = await client.patch(f"/api/v1/sources/{source_id}", json={"default_search_strategy": "multi_jev"}) - assert blocked.status_code == 400 and blocked.json()["error"]["code"] == "vector_provider_lacks_lexical" - assert (await client.get(f"/api/v1/sources/{source_id}")).json()["default_search_strategy"] == "sag2" - renamed = await client.patch(f"/api/v1/sources/{source_id}", json={"name": "改名"}) - assert renamed.status_code == 200 and renamed.json()["default_search_strategy"] == "sag2" - cleared = await client.patch(f"/api/v1/sources/{source_id}", json={"default_search_strategy": None}) - assert cleared.status_code == 200, cleared.text - assert cleared.json()["default_search_strategy"] is None - assert cleared.json()["name"] == "改名" - # Sources are left in place: deleting would queue background work that - # races the shared teardown cleanup for the SQLite lock. - - -async def test_global_search_uses_shared_source_default(source_client, monkeypatch): - from sag_api.core.deps import get_engine_manager - from sag_api.main import app - - client = source_client - monkeypatch.setattr(settings, "sag_vector_provider", "lancedb") - monkeypatch.setattr(settings, "search_strategy", "vector") - monkeypatch.setattr(settings, "jev_endpoint", "https://jev.example/score") - monkeypatch.setattr(settings, "jev_api_key", "synthetic-jev-key") - created = await client.post("/api/v1/sources", json={"name": "SAG2 库", "default_search_strategy": "sag2"}) +@pytest.mark.parametrize("engine_kind", ["sag1", "sag2"]) +async def test_source_algorithm_is_fixed_but_metadata_remains_editable(source_client, engine_kind): + created = await source_client.post("/api/v1/sources", json={"name": "Engine binding", "engine_kind": engine_kind}) assert created.status_code == 201, created.text source_id = created.json()["id"] - seen = [] - - class StubEngine: - _settings = settings + assert created.json()["engine_kind"] == engine_kind + changed = await source_client.patch(f"/api/v1/sources/{source_id}", json={"name": "Renamed"}) + assert changed.status_code == 200 + assert changed.json()["engine_kind"] == engine_kind + for replacement in ["sag1", "sag2"]: + rejected = await source_client.patch(f"/api/v1/sources/{source_id}", json={"engine_kind": replacement}) + assert rejected.status_code == 422 + assert (await source_client.get(f"/api/v1/sources/{source_id}")).json()["engine_kind"] == engine_kind - async def search_many(self, targets, query, **kwargs): - seen.append(kwargs.get("strategy")) - return SearchOutcome(query=query, sections=[], stats={"effective_strategy": kwargs.get("strategy")}) - async def grep_chunks(self, *args, **kwargs): - return [] - - app.dependency_overrides[get_engine_manager] = lambda: StubEngine() - try: - scoped = await client.post("/api/v1/search", json={"query": "q", "source_ids": [source_id]}) - assert scoped.status_code == 200, scoped.text - assert seen[-1] == "sag2" - assert scoped.json()["stats"]["strategy_origin"] == "source_default" - - explicit = await client.post( - "/api/v1/search", json={"query": "q", "source_ids": [source_id], "strategy": "vector"}, - ) - assert explicit.status_code == 200, explicit.text - assert seen[-1] == "vector" - assert explicit.json()["stats"]["strategy_origin"] == "request" - finally: - app.dependency_overrides.pop(get_engine_manager, None) - - -def test_require_strategy_available_matches_capability_report(): - assert EngineManager.require_strategy_available(configured(), "sag2") is None - with pytest.raises(Exception) as error: - EngineManager.require_strategy_available(configured(sag_relational_provider="mysql"), "sag2") - assert getattr(error.value, "code", None) == "sag2_relational_unsupported" +@pytest.mark.asyncio +async def test_retired_source_default_mode_is_not_an_editable_setting(source_client): + created = await source_client.post("/api/v1/sources", json={"name": "Default SAG1"}) + assert created.status_code == 201 + assert created.json()["engine_kind"] == "sag1" + rejected = await source_client.patch( + f"/api/v1/sources/{created.json()['id']}", json={"default_search_strategy": "sag2"} + ) + assert rejected.status_code == 422 diff --git a/apps/api/tests/test_source_engine_binding.py b/apps/api/tests/test_source_engine_binding.py new file mode 100644 index 00000000..f6bcddf1 --- /dev/null +++ b/apps/api/tests/test_source_engine_binding.py @@ -0,0 +1,33 @@ +"""Knowledge algorithms are chosen once, independently of retrieval preferences.""" + +import pytest +from pydantic import ValidationError + +from sag_api.core.db import _COLUMN_UPGRADES +from sag_api.db.models import Source +from sag_api.schemas.source import SourceCreate, SourceUpdate + + +def test_source_creation_defaults_to_sag1(): + assert SourceCreate(name="legacy compatible").engine_kind == "sag1" + + +@pytest.mark.parametrize("kind", ["sag1", "sag2"]) +def test_source_creation_accepts_two_algorithms(kind): + assert SourceCreate(name="test", engine_kind=kind).engine_kind == kind + + +@pytest.mark.parametrize("kind", ["vector", "multi", "multi_jev", "invalid"]) +def test_source_creation_rejects_retrieval_strategy_as_algorithm(kind): + with pytest.raises(ValidationError): + SourceCreate(name="test", engine_kind=kind) + + +def test_edit_cannot_change_algorithm(): + with pytest.raises(ValidationError): + SourceUpdate(engine_kind="sag1") + + +def test_legacy_source_migration_does_not_infer_sag2_from_preference(): + assert _COLUMN_UPGRADES["sources"]["engine_kind"] == "VARCHAR(16) NOT NULL DEFAULT 'sag1'" + assert str(Source.__table__.c.engine_kind.server_default.arg) == "sag1" diff --git a/apps/web/app/(app)/knowledge/[id]/page.tsx b/apps/web/app/(app)/knowledge/[id]/page.tsx index c52962bd..94e79085 100644 --- a/apps/web/app/(app)/knowledge/[id]/page.tsx +++ b/apps/web/app/(app)/knowledge/[id]/page.tsx @@ -26,7 +26,7 @@ import { FolderImportDialog, type FolderImportDialogHandle, } from "@/components/features/folder-import-dialog"; -import { RetrievalModePill } from "@/components/features/retrieval-mode-pill"; +import { KnowledgeEnginePill } from "@/components/features/knowledge-engine-pill"; import { RetrievalTestDialog } from "@/components/features/retrieval-test-dialog"; import { SourceIdCopy } from "@/components/features/source-id-copy"; import { SourceGraph } from "@/components/features/source-graph"; @@ -128,9 +128,7 @@ export default function SourceDetailPage() {

{source.name}

- {source.default_search_strategy && ( - - )} +

{t("sourceStats", { @@ -192,9 +190,9 @@ export default function SourceDetailPage() { variant="outline" size="icon" onClick={handleExport} - disabled={!source || exportRunning} + disabled={!source || exportRunning || source.engine_kind === "sag2"} aria-label={tCard("export")} - title={tCard("export")} + title={source?.engine_kind === "sag2" ? tCard("sag2OctxUnsupported") : tCard("export")} > {exportRunning ? ( @@ -203,7 +201,7 @@ export default function SourceDetailPage() { )} - {tCard("export")} + {source?.engine_kind === "sag2" ? tCard("sag2OctxUnsupported") : tCard("export")} @@ -285,6 +283,7 @@ export default function SourceDetailPage() { @@ -294,6 +293,7 @@ export default function SourceDetailPage() { @@ -309,7 +309,7 @@ export default function SourceDetailPage() { ))}

- ) : graphViewActive ? ( + ) : graphViewActive && source.engine_kind !== "sag2" ? (
) : ( {isFileSource - ? t("addDialogDescription") + ? t(source?.engine_kind === "sag2" ? "sag2UploadDescription" : "addDialogDescription") : t("syncDialogDescription")} @@ -363,6 +364,7 @@ export default function SourceDetailPage() { (source.connector_kind === "file_upload" ? (
{ dismissFolderImportDialog( diff --git a/apps/web/components/features/app-shell.tsx b/apps/web/components/features/app-shell.tsx index da9d9f24..d3e0ec48 100644 --- a/apps/web/components/features/app-shell.tsx +++ b/apps/web/components/features/app-shell.tsx @@ -34,9 +34,7 @@ import { import { DEFAULT_TIME_ZONE } from "@/lib/format"; import { PetAgent } from "@/lib/pet-agent"; import { - DEFAULT_SEARCH_STRATEGY, getSearchStrategiesDisabled, - isSearchStrategy, } from "@/lib/retrieval-config"; import { SIDEBAR_THREADS_PAGE_SIZE, @@ -827,11 +825,7 @@ export function AppShell({ children }: { children: React.ReactNode }) { > diff --git a/apps/web/components/features/chat/conversation-panel.test.tsx b/apps/web/components/features/chat/conversation-panel.test.tsx index 2cf90735..75e2dd50 100644 --- a/apps/web/components/features/chat/conversation-panel.test.tsx +++ b/apps/web/components/features/chat/conversation-panel.test.tsx @@ -57,7 +57,7 @@ vi.mock("@/components/features/markdown-content", () => ({ vi.mock("./prompt-preview", () => ({ PromptPreview: () => null })); vi.mock("./agent-activity-timeline", () => ({ AgentActivityTimeline: () => null })); -const ALL_STRATEGIES = ["vector", "multi_es_fast", "multi", "multi_jev", "sag2"] as const; +const ALL_STRATEGIES = ["auto", "vector", "multi_es_fast", "multi", "multi_jev", "sag2"] as const; const emptySession: ConversationSessionSnapshot = { sessionId: "session-1", agentId: "agent-1", threadId: "thread-1", error: null, run: null, history: { status: "ready", requestId: 0, hasMore: false, nextCursor: null, error: null }, messages: [], @@ -173,11 +173,11 @@ describe("retry source scope", () => { }); describe("composer retrieval mode", () => { - it("shows the global default without a hint when nothing else applies", async () => { + it("shows automatic algorithm routing without a hint when nothing is pinned", async () => { state.capabilities = { llm_configured: true, search_strategy: "multi_es_fast" }; await renderPanel(); // The legacy Agent default is vector for non-JEV global modes. - expect(trigger().textContent).toContain("Fast (vector)"); + expect(trigger().textContent).toContain("Auto (knowledge algorithms)"); expect(hint()).toBeNull(); expect(trigger().disabled).toBe(false); }); @@ -191,21 +191,21 @@ describe("composer retrieval mode", () => { expect(hint()).toContain("Persona default"); }); - it("falls back to the shared source default when the persona mode cannot be served", async () => { + it("falls back to automatic routing when the persona mode cannot be served", async () => { // Without an advertised search_strategies list the JEV modes are unsupported. state.capabilities = { llm_configured: true, search_strategy: "vector" }; state.agent = agent("sag2"); state.sources = [source("composer-source", "multi")]; await renderPanel(); - expect(trigger().textContent).toContain("Precise"); - expect(hint()).toContain("Source default"); + expect(trigger().textContent).toContain("Auto (knowledge algorithms)"); + expect(hint()).toBeNull(); }); it("ignores source defaults that the scoped sources do not share", async () => { state.scoped = [{ id: "a", name: "a" }, { id: "b", name: "b" }]; state.sources = [source("a", "multi"), source("b", "multi_es_fast")]; await renderPanel(); - expect(trigger().textContent).toContain("Fast (vector)"); + expect(trigger().textContent).toContain("Auto (knowledge algorithms)"); expect(hint()).toBeNull(); }); diff --git a/apps/web/components/features/chat/conversation-panel.tsx b/apps/web/components/features/chat/conversation-panel.tsx index 37e5e9bc..26e50a00 100644 --- a/apps/web/components/features/chat/conversation-panel.tsx +++ b/apps/web/components/features/chat/conversation-panel.tsx @@ -17,10 +17,8 @@ import { shouldSubmitAfterEnter, } from "@/lib/composer-keyboard"; import { - getScopeDefaultStrategy, getSearchStrategiesDisabled, isSearchStrategy, - isJevScoredStrategy, isSearchStrategyRejectionCode, type SearchStrategy, } from "@/lib/retrieval-config"; @@ -310,16 +308,8 @@ export function ConversationPanel({ }, [agent?.persona?.search_strategy, strategyDisabledMap]); // Scopes only carry id + name; the loaded source list supplies each one's default. // A scope whose source is not loaded yet counts as "no default", like the backend treats null. - const scopeDefaultStrategy = React.useMemo(() => getScopeDefaultStrategy( - scoped.map((scope) => ({ - default_search_strategy: sources.find((source) => source.id === scope.id)?.default_search_strategy ?? null, - })), - strategyDisabledMap, - ), [scoped, sources, strategyDisabledMap]); - // Match the Agent's legacy non-JEV default; an explicit pick still overrides it. - const globalStrategy = isJevScoredStrategy(capabilities?.search_strategy) - ? capabilities.search_strategy - : "vector"; + const scopeDefaultStrategy = null; + const globalStrategy: SearchStrategy = "auto"; const resolvedStrategy = personaStrategy ?? scopeDefaultStrategy ?? globalStrategy; // Keep an explicit choice visible, but never submit it after its configuration expires. const pinnedStrategyIssue = pinnedStrategy ? strategyDisabledMap[pinnedStrategy] : undefined; diff --git a/apps/web/components/features/document-list.tsx b/apps/web/components/features/document-list.tsx index 938f9abc..9ed35cbd 100644 --- a/apps/web/components/features/document-list.tsx +++ b/apps/web/components/features/document-list.tsx @@ -25,6 +25,7 @@ import { useOctxExports } from "@/components/features/octx-export-provider"; export function DocumentList({ sourceId, + engineKind = "sag1", sourceName, documents, activities, @@ -33,6 +34,7 @@ export function DocumentList({ onOpenDocument, }: { sourceId: string; + engineKind?: "sag1" | "sag2"; sourceName: string; documents: Doc[]; activities: Record; @@ -103,7 +105,7 @@ export function DocumentList({ const buttonClass = compact ? "size-7" : undefined; return (
- {document.has_publication && ( + {document.has_publication && engineKind !== "sag2" && ( diff --git a/apps/web/components/features/jev-mode-setup-dialog.test.tsx b/apps/web/components/features/jev-mode-setup-dialog.test.tsx new file mode 100644 index 00000000..d2003355 --- /dev/null +++ b/apps/web/components/features/jev-mode-setup-dialog.test.tsx @@ -0,0 +1,55 @@ +/** @vitest-environment jsdom */ +import * as React from "react"; +import { act } from "react"; +import { createRoot } from "react-dom/client"; +import { NextIntlClientProvider } from "next-intl"; +import { afterEach, expect, it, vi } from "vitest"; +import messages from "@/messages/en-US.json"; +import { api } from "@/lib/api"; +import { SearchStrategyControl } from "./search-strategy-control"; + +vi.mock("@/components/features/app-shell", () => ({ useApp: () => ({ refreshCapabilities: vi.fn(async () => {}) }) })); +vi.mock("next/link", () => ({ default: (props: React.AnchorHTMLAttributes) => })); +let cleanup: (() => Promise) | undefined; +afterEach(async () => { await cleanup?.(); vi.restoreAllMocks(); }); +it("opens JEV setup for an unconfigured paid mode without changing the current mode", async () => { + (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + vi.spyOn(api, "getModelConfig").mockResolvedValue({ jev_endpoint: null, jev_model: "jev-latest" } as never); + Object.defineProperties(HTMLElement.prototype, { + hasPointerCapture: { configurable: true, value: () => false }, releasePointerCapture: { configurable: true, value: () => {} }, + setPointerCapture: { configurable: true, value: () => {} }, scrollIntoView: { configurable: true, value: () => {} }, + }); + const container = document.createElement("div"); document.body.append(container); + const root = createRoot(container); const change = vi.fn(); + cleanup = async () => { await act(async () => root.unmount()); container.remove(); }; + await act(async () => root.render( + + )); + function pointer(type: string) { + const event = new MouseEvent(type, { bubbles: true, button: 0 }); + Object.defineProperties(event, { pointerId: { value: 1 }, pointerType: { value: "mouse" } }); return event; + } + await act(async () => container.querySelector("button")!.dispatchEvent(pointer("pointerdown"))); + const option = document.querySelector('[data-testid="search-strategy-sag2-paid"]')!.closest('[role="menuitem"]')!; + expect(option.getAttribute("aria-disabled")).not.toBe("true"); + await act(async () => option.click()); + expect(document.querySelector('[role="dialog"]')).not.toBeNull(); + expect(document.querySelector('input[type="password"]')).not.toBeNull(); + expect(change).not.toHaveBeenCalled(); + const input = document.querySelector('input[type="password"]')!; + await act(async () => { + Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!.call(input, "synthetic-key"); + input.dispatchEvent(new Event("input", { bubbles: true })); + }); + const save = [...document.querySelectorAll("button")].find(button => button.textContent?.includes("Save and use"))!; + expect(save.disabled).toBe(false); + const request = vi.spyOn(api, "saveModelConfig").mockRejectedValueOnce(new Error("Save rejected")); + await act(async () => save.click()); + expect(change).not.toHaveBeenCalled(); + expect(document.querySelector('[role="dialog"]')).not.toBeNull(); + request.mockResolvedValueOnce({ config: {}, capabilities: {} } as never); + await act(async () => save.click()); + expect(change).toHaveBeenCalledWith("sag2"); + expect(document.querySelector('[role="dialog"]')).toBeNull(); +}); diff --git a/apps/web/components/features/jev-mode-setup-dialog.tsx b/apps/web/components/features/jev-mode-setup-dialog.tsx new file mode 100644 index 00000000..ba013999 --- /dev/null +++ b/apps/web/components/features/jev-mode-setup-dialog.tsx @@ -0,0 +1,28 @@ +"use client"; +import { useTranslations } from "next-intl"; +import { Button } from "@/components/ui/button"; +import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "@/components/ui/dialog"; +import { JevQuickSetup, useJevQuickSetup } from "./jev-quick-setup"; + +export function JevModeSetupDialog({ onConfigured, onClose }: { + onConfigured: () => void; onClose: () => void; +}) { + const t = useTranslations("RetrievalModes"); + const form = useJevQuickSetup({ enabled: true }); + async function save() { + try { await form.save(); onConfigured(); } catch { /* The form shows the failure inline. */ } + } + return { if (!open && !form.saving) onClose(); }}> + + {t("jevSetupTitle")} + {t("jevSetupDescription")} + + + + + + + ; +} diff --git a/apps/web/components/features/knowledge-config-form.test.tsx b/apps/web/components/features/knowledge-config-form.test.tsx index 03717daf..3c882b9e 100644 --- a/apps/web/components/features/knowledge-config-form.test.tsx +++ b/apps/web/components/features/knowledge-config-form.test.tsx @@ -157,7 +157,7 @@ describe("JEV knowledge settings", () => { }); it("keeps JEV modes disabled until an API key is entered, then saves the key with the mode", async () => { await mount(); - await expectStrategyDisabled("JEV reranking", true); + await expectStrategyDisabled("JEV reranking", false); expect(container.querySelector('[role="alert"]')).toBeNull(); expect(button("Save and apply").disabled).toBe(false); await edit("#kb-jev-api-key", "synthetic-302-key"); @@ -252,7 +252,7 @@ describe("JEV knowledge settings", () => { await select("#kb-jev-provider", "Custom"); await edit("#kb-jev-endpoint", "https://jev.invalid/score"); await edit("#kb-jev-model", "gateway-model"); - await expectStrategyDisabled("JEV reranking", true); + await expectStrategyDisabled("JEV reranking", false); await edit("#kb-jev-api-key", "synthetic-gateway-key"); await select("#kb-search-strategy", "JEV"); await act(async () => button("Save and apply").click()); @@ -318,7 +318,7 @@ describe("JEV knowledge settings", () => { }); it("blocks saving a JEV mode whose key was cleared by changing the destination", async () => { state.capabilities = { vector_provider: "lancedb", search_strategies: ["vector", "multi", "multi_es_fast", "multi_jev", "sag2"] }; - vi.mocked(api.getModelConfig).mockResolvedValue({ ...config, jev_endpoint: officialEndpoint, search_strategy: "sag2" } as never); + vi.mocked(api.getModelConfig).mockResolvedValue({ ...config, jev_endpoint: officialEndpoint, search_strategy: "multi_jev" } as never); await mount(); expect(container.querySelector('[role="alert"]')).toBeNull(); await select("#kb-jev-provider", "302.AI"); @@ -392,7 +392,7 @@ describe("JEV knowledge settings", () => { await mount(); expect(container.querySelector("#kb-jev-provider")).toBeNull(); expect(container.textContent).toContain("SAG2 evidence retrieval currently supports only SQLite and PostgreSQL"); - expect(container.textContent).toContain("Choose Fast (vector) or Precise above and save"); + expect(container.querySelector("#kb-search-strategy")?.textContent).toContain("Fast (vector)"); expect(container.querySelector('[role="alert"]')).toBeNull(); expect(button("Save and apply").disabled).toBe(false); }); @@ -411,9 +411,11 @@ describe("JEV knowledge settings", () => { expect(container.textContent).not.toContain("Your existing retrieval settings remain unchanged"); expect(button("Test JEV connection").disabled).toBe(false); await expectStrategyDisabled("JEV reranking", true); - await select("#kb-search-strategy", "SAG2"); + const options = await openSelect("#kb-search-strategy"); + expect(options.some(option => option.textContent?.includes("SAG2"))).toBe(false); + await closeSelect(); await act(async () => button("Save and apply").click()); - expect(saved).toMatchObject({ search_strategy: "sag2", jev_endpoint: provider302Endpoint, jev_model: "jev-latest" }); + expect(saved).not.toHaveProperty("search_strategy"); expect(saved).not.toHaveProperty("jev_api_key"); }); it("explains the SAG2 relational limitation while keeping JEV reranking configurable", async () => { @@ -426,7 +428,9 @@ describe("JEV knowledge settings", () => { expect(container.querySelector("#kb-jev-provider")).not.toBeNull(); expect(container.textContent).toContain("SAG2 evidence retrieval currently supports only SQLite and PostgreSQL"); expect(container.querySelector('[role="alert"]')).toBeNull(); - await expectStrategyDisabled("SAG2", true); + const options = await openSelect("#kb-search-strategy"); + expect(options.some(option => option.textContent?.includes("SAG2"))).toBe(false); + await closeSelect(); await select("#kb-search-strategy", "JEV"); await act(async () => button("Save and apply").click()); expect(saved).toMatchObject({ search_strategy: "multi_jev" }); @@ -438,14 +442,16 @@ describe("JEV knowledge settings", () => { }; vi.mocked(api.getModelConfig).mockResolvedValue({ ...config, jev_endpoint: provider302Endpoint, jev_api_key_set: false } as never); await mount(); - await expectStrategyDisabled("JEV reranking", true); - await expectStrategyDisabled("SAG2", true); + await expectStrategyDisabled("JEV reranking", false); + const options = await openSelect("#kb-search-strategy"); + expect(options.some(option => option.textContent?.includes("SAG2"))).toBe(false); + await closeSelect(); expect(container.querySelector('[role="alert"]')).toBeNull(); await edit("#kb-jev-api-key", "synthetic-302-key"); await expectStrategyDisabled("JEV reranking", false); - await select("#kb-search-strategy", "SAG2"); + await select("#kb-search-strategy", "JEV"); await act(async () => button("Save and apply").click()); - expect(saved).toMatchObject({ search_strategy: "sag2", jev_endpoint: provider302Endpoint, jev_api_key: "synthetic-302-key" }); + expect(saved).toMatchObject({ search_strategy: "multi_jev", jev_endpoint: provider302Endpoint, jev_api_key: "synthetic-302-key" }); }); it("disables the JEV option and rejects a draft enable when storage capabilities change", async () => { await mount(); diff --git a/apps/web/components/features/knowledge-config-form.tsx b/apps/web/components/features/knowledge-config-form.tsx index 809d4fa3..2805d99f 100644 --- a/apps/web/components/features/knowledge-config-form.tsx +++ b/apps/web/components/features/knowledge-config-form.tsx @@ -126,7 +126,7 @@ export function KnowledgeConfigForm() { setChunkMaxTokens(config.document_chunk_max_tokens ?? 1_000); setChunkMode(config.document_chunk_mode ?? "standard"); setExtractConcurrency(config.document_extract_concurrency ?? 30); - setStrategy(config.search_strategy); + setStrategy(config.search_strategy === "sag2" || config.search_strategy === "auto" ? "vector" : config.search_strategy); setTopK(config.search_top_k); setLanguage(config.sag_language); setJevProvider(providerForEndpoint(config.jev_endpoint ?? "")); @@ -138,7 +138,7 @@ export function KnowledgeConfigForm() { setJevTimeout(timeout); setJevFailurePolicy(failurePolicy); // Display defaults are a preview; only edits or explicitly enabling JEV save them. - setSavedJevDraft({ endpoint, model, timeout, failurePolicy, strategy: config.search_strategy }); + setSavedJevDraft({ endpoint, model, timeout, failurePolicy, strategy: config.search_strategy === "sag2" || config.search_strategy === "auto" ? "vector" : config.search_strategy }); setJevTestResult(null); setLoaded(true); }, []); @@ -372,7 +372,8 @@ export function KnowledgeConfigForm() { onValueChange( - next === FOLLOW_GLOBAL_VALUE ? null : (next as SearchStrategy), - )} - > - - - - - - {t("followGlobal", { label: globalLabel })} - - - {SEARCH_STRATEGIES.map((strategy) => { - const info = disabledMap?.[strategy.value]; - const needsKeyOnly = Boolean(info) && isJevConfigDisabledReason(info?.reason); - const unavailable = Boolean(info) && !needsKeyOnly; - const paid = isJevScoredStrategy(strategy.value); - const Icon = SEARCH_STRATEGY_ICONS[strategy.value]; - return ( - - - - - {strategies(strategy.labelKey)} - {paid && ( - - {t("paid")} - - )} - {needsKeyOnly && {t("needsKeyBadge")}} - {unavailable && {t("unavailable")}} - - {unavailable && info && ( - - {info.message} - - )} - - - ); - })} - - - -
- {!selected && ( - <> -

{t("followGlobalDescription")}

-

{t("globalModeLead", { label: globalLabel })}

- - )} -

{t(MODE_COPY[describedMode.value].summary)}

-

{t(MODE_COPY[describedMode.value].whenToUse)}

- {isJevScoredStrategy(describedMode.value) && ( -

- {t("paidNeedsKey")} -

- )} - {selectedUnavailable && selectedInfo && ( -

{selectedInfo.message}

- )} -
- - {showJevSetup && jevSetup && ( - - )} - - ); -} diff --git a/apps/web/components/features/retrieval-mode-pill.tsx b/apps/web/components/features/retrieval-mode-pill.tsx deleted file mode 100644 index 994156d8..00000000 --- a/apps/web/components/features/retrieval-mode-pill.tsx +++ /dev/null @@ -1,51 +0,0 @@ -"use client"; - -import { useTranslations } from "next-intl"; - -import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"; -import { - getSearchStrategy, - SEARCH_STRATEGY_ICONS, - type SearchStrategy, -} from "@/lib/retrieval-config"; -import { cn } from "@/lib/utils"; - -/** Compact "default retrieval mode" marker shown next to a source's name. */ -export function RetrievalModePill({ - strategy, - className, - tooltipSide = "bottom", -}: { - strategy: SearchStrategy; - className?: string; - tooltipSide?: React.ComponentProps["side"]; -}) { - const t = useTranslations("RetrievalModes"); - const strategies = useTranslations("SearchStrategies"); - const mode = getSearchStrategy(strategy); - const Icon = SEARCH_STRATEGY_ICONS[mode.value]; - const label = strategies(mode.labelKey); - const tooltip = t("pillTooltip", { label }); - - return ( - - - - - {label} - - - - {tooltip} - - - ); -} diff --git a/apps/web/components/features/retrieval-status.test.tsx b/apps/web/components/features/retrieval-status.test.tsx index fa96ac0f..cb48e20b 100644 --- a/apps/web/components/features/retrieval-status.test.tsx +++ b/apps/web/components/features/retrieval-status.test.tsx @@ -88,3 +88,11 @@ describe("SAG2 execution status", () => { expect(text).toContain("0 requests · 0 judgments"); }); }); + + +it("shows JEV degradation inside automatic mixed retrieval", async () => { + const text = await render({ requested_strategy: "auto", effective_strategy: "auto", jev_fallback_used: true, + fallback_used: true, engine_failures: [{ engine_kind: "sag1", message: "legacy storage offline" }] }, "auto"); + expect(text).toContain("JEV reranking did not complete"); + expect(text).toContain("sag1 retrieval failed or is incomplete: legacy storage offline"); +}); diff --git a/apps/web/components/features/retrieval-status.tsx b/apps/web/components/features/retrieval-status.tsx index 4d4b8bbb..466f2a72 100644 --- a/apps/web/components/features/retrieval-status.tsx +++ b/apps/web/components/features/retrieval-status.tsx @@ -48,7 +48,8 @@ export function RetrievalStatus({ stats, requestedStrategy }: { const requested = isSearchStrategy(stats.requested_strategy) ? stats.requested_strategy : requestedStrategy; const effective = typeof stats.effective_strategy === "string" ? stats.effective_strategy : requested; const fallback = usedFallback(stats) || Object.values(record(stats.source_stats)).some(value => usedFallback(record(value))); - const jevFallback = (isJevScoredStrategy(requested) || isJevScoredStrategy(effective)) && fallback; + const jevFallback = stats.jev_fallback_used === true + || (isJevScoredStrategy(requested) || isJevScoredStrategy(effective)) && fallback; const partial = stats.partial === true; const changed = requested && effective && requested !== effective; // Paid JEV calls are reported per run so users can see what a query cost. @@ -65,11 +66,12 @@ export function RetrievalStatus({ stats, requestedStrategy }: { tokens: usageInputTokens === null ? "" : t("jevUsageTokens", { tokens: format(usageInputTokens) }), }) : null; + const engineFailures = Array.isArray(stats.engine_failures) ? stats.engine_failures : []; const executionChanged = jevFallback || partial || changed; const origin = explainedOrigin(stats.strategy_origin); // The origin describes the resolved (requested) mode; a changed execution is reported separately. const originMode = requested ?? effective; - if (!executionChanged && usageText === null && !(origin && originMode)) return null; + if (!executionChanged && usageText === null && !(origin && originMode) && !engineFailures.length) return null; function label(mode: string) { return isSearchStrategy(mode) ? strategies(getSearchStrategy(mode).labelKey) : mode; } @@ -79,5 +81,8 @@ export function RetrievalStatus({ stats, requestedStrategy }: { {jevFallback &&

{t("jevFallback")}

} {partial &&

{t("partial")}

} {usageText !== null &&

{usageText}

} + {engineFailures.map((failure, index) => { const info = record(failure); return

+ {t("engineFailure", { engine: String(info.engine_kind ?? ""), message: String(info.message ?? "") })} +

; })}
; } diff --git a/apps/web/components/features/retrieval-test-dialog.tsx b/apps/web/components/features/retrieval-test-dialog.tsx index cdac7506..4cb05500 100644 --- a/apps/web/components/features/retrieval-test-dialog.tsx +++ b/apps/web/components/features/retrieval-test-dialog.tsx @@ -58,7 +58,7 @@ export function RetrievalTestDialog({ const disabledMap = getSearchStrategiesDisabled(capabilities, strategies("unsupportedBackend")); const enabledStrategies = SEARCH_STRATEGIES.filter( - (item) => !disabledMap[item.value], + (item) => item.value !== "auto" && !disabledMap[item.value], ).map((item) => item.value); const fallbackA: SearchStrategy = enabledStrategies[0] ?? DEFAULT_SEARCH_STRATEGY; @@ -282,7 +282,7 @@ function StrategyPicker({ - {SEARCH_STRATEGIES.map(({ value: strategy, labelKey }) => { + {SEARCH_STRATEGIES.filter(item => item.value !== "auto").map(({ value: strategy, labelKey }) => { const info = disabledMap[strategy]; const sameAsOther = strategy === otherValue; return ( diff --git a/apps/web/components/features/search-strategy-control.test.tsx b/apps/web/components/features/search-strategy-control.test.tsx index 960ddd12..75ffd301 100644 --- a/apps/web/components/features/search-strategy-control.test.tsx +++ b/apps/web/components/features/search-strategy-control.test.tsx @@ -78,7 +78,7 @@ describe("search strategy dropdown", () => { it.each(["jev_not_configured", "jev_api_key_missing"])("offers the settings page when a JEV mode is disabled for %s", async reason => { const items = await open({ sag2: { reason, message: "Add a JEV API key" }, multi_jev: { reason, message: "Add a JEV API key" } }); const sag2 = item(items, "SAG2 evidence retrieval"); - expect(sag2.getAttribute("aria-disabled")).toBe("true"); + expect(sag2.getAttribute("aria-disabled")).not.toBe("true"); expect(sag2.textContent).toContain("Add a JEV API key"); const link = document.body.querySelector('[data-testid="search-strategy-sag2-settings"]')!; expect(link.getAttribute("href")).toBe("/settings?tab=knowledge§ion=jev"); diff --git a/apps/web/components/features/search-strategy-control.tsx b/apps/web/components/features/search-strategy-control.tsx index ca5453e3..664a74b4 100644 --- a/apps/web/components/features/search-strategy-control.tsx +++ b/apps/web/components/features/search-strategy-control.tsx @@ -3,7 +3,8 @@ import { Check, ChevronDown, Settings2 } from "lucide-react"; import { useTranslations } from "next-intl"; import Link from "next/link"; -import { Fragment } from "react"; +import { Fragment, useState } from "react"; +import { JevModeSetupDialog } from "./jev-mode-setup-dialog"; import { DropdownMenu, @@ -58,6 +59,7 @@ export function SearchStrategyControl({ disabled?: boolean; }) { const t = useTranslations("SearchStrategies"); + const [pending, setPending] = useState(null); const currentStrategy = getSearchStrategy(value); const CurrentIcon = SEARCH_STRATEGY_ICONS[currentStrategy.value]; @@ -98,8 +100,12 @@ export function SearchStrategyControl({ const needsJevSettings = paid && isJevConfigDisabledReason(disabledInfo?.reason); const item = ( { + if (needsJevSettings) { + setPending(strategy.value); + return; + } if (disabledInfo) { // Radix 默认会关闭菜单;这里阻断以便 Tooltip 保持可见, // 且不触发无意义的 onValueChange。 @@ -163,6 +169,10 @@ export function SearchStrategyControl({ })} + {pending && setPending(null)} + onConfigured={() => { onValueChange(pending); setPending(null); }} + />} ); } diff --git a/apps/web/components/features/search/search-mixed-evidence.test.tsx b/apps/web/components/features/search/search-mixed-evidence.test.tsx new file mode 100644 index 00000000..a9a24a06 --- /dev/null +++ b/apps/web/components/features/search/search-mixed-evidence.test.tsx @@ -0,0 +1,26 @@ +/** @vitest-environment jsdom */ +import * as React from "react"; +import { act } from "react"; +import { createRoot } from "react-dom/client"; +import { NextIntlClientProvider } from "next-intl"; +import { expect, it, vi } from "vitest"; +import messages from "@/messages/zh-CN.json"; +import type { SearchResponse } from "@/lib/types"; +import { ResultList } from "./search-panel-sections"; +vi.mock("@/components/features/detail-panel", () => ({ useDetailPanel: () => ({ open: vi.fn() }) })); +it("keeps native evidence visible when SAG1 graph events are also present", async () => { + (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + const result: SearchResponse = { + query: "q", entities: [], relations: [], source_hits: [], summary: "", exploration_id: null, stats: {}, + events: [{ id: "event", title: "SAG1 event", summary: "legacy", score: 0.8, source_id: "legacy", document_id: null, category: "", rank: 0, parent_id: null, chunk_id: null, start_time: null }], + sections: [{ source_id: "native", chunk_id: "c", heading: "Native evidence", content: "NATIVE-253", score: 0.2, rank: 0, + metadata: { engine_kind: "sag2" } }], + }; + const container = document.createElement("div"); document.body.append(container); const root = createRoot(container); + try { + await act(async () => root.render( + + )); + expect(container.textContent).toContain("NATIVE-253"); + } finally { await act(async () => root.unmount()); container.remove(); } +}); diff --git a/apps/web/components/features/search/search-panel-sections.tsx b/apps/web/components/features/search/search-panel-sections.tsx index f64fdb87..fe520638 100644 --- a/apps/web/components/features/search/search-panel-sections.tsx +++ b/apps/web/components/features/search/search-panel-sections.tsx @@ -404,7 +404,7 @@ export function ResultList({ /> ); } - if (result.events.length === 0) { + if (result.events.length === 0 || result.sections.some(section => section.metadata?.engine_kind === "sag2")) { return (
{result.sections.map((section, index) => { diff --git a/apps/web/components/features/search/search-panel.tsx b/apps/web/components/features/search/search-panel.tsx index 1a8db4d1..7bcc29e6 100644 --- a/apps/web/components/features/search/search-panel.tsx +++ b/apps/web/components/features/search/search-panel.tsx @@ -155,7 +155,7 @@ export function SearchPanel({ [capabilities, searchStrategies], ); const enabledStrategies = React.useMemo( - () => SEARCH_STRATEGIES.map((item) => item.value).filter((value) => !disabledMap[value]), + () => SEARCH_STRATEGIES.map((item) => item.value).filter((value) => value !== "auto" && !disabledMap[value]), [disabledMap], ); const compare = useSearchCompare({ diff --git a/apps/web/components/features/search/search-provider.tsx b/apps/web/components/features/search/search-provider.tsx index eac7f28f..d21a5862 100644 --- a/apps/web/components/features/search/search-provider.tsx +++ b/apps/web/components/features/search/search-provider.tsx @@ -5,7 +5,7 @@ import { useTranslations } from "next-intl"; import { api, ApiError } from "@/lib/api"; import { isSourceDeleting } from "@/lib/source-activity"; -import { getScopeDefaultStrategy, type SearchStrategy } from "@/lib/retrieval-config"; +import { type SearchStrategy } from "@/lib/retrieval-config"; import type { ActivityItem, SearchResponse, Source } from "@/lib/types"; import { activationFromSearch, @@ -252,13 +252,8 @@ export function SearchProvider({ // Sources scoped through the picker carry their own default; scopes restored // from a URL only have an id, so fall back to the loaded source list. - const scopeDefaultStrategy = React.useMemo(() => getScopeDefaultStrategy( - state.scoped.map((scope) => state.sources.find((source) => source.id === scope.id) ?? scope), - disabledMap, - ), [disabledMap, state.scoped, state.sources]); - const effectiveStrategy = state.strategyPinned - ? state.strategy - : (scopeDefaultStrategy ?? defaultStrategy); + const scopeDefaultStrategy = null; + const effectiveStrategy = state.strategyPinned ? state.strategy : defaultStrategy; const strategyOrigin: SearchStrategyOrigin = state.strategyPinned ? "pinned" : scopeDefaultStrategy diff --git a/apps/web/components/features/search/search-scope-default.test.tsx b/apps/web/components/features/search/search-scope-default.test.tsx index fa1ba28a..3c2702d7 100644 --- a/apps/web/components/features/search/search-scope-default.test.tsx +++ b/apps/web/components/features/search/search-scope-default.test.tsx @@ -59,8 +59,8 @@ async function harness(disabledMap?: SearchStrategyDisabledMap) { }; } -describe("search scope default strategy", () => { - it("follows the shared default of the scoped sources once they are loaded", async () => { +describe("search defaults ignore retired per-source mode preferences", () => { + it("retains the application default after scoped sources load", async () => { const h = await harness(); try { expect(h.read("strategy")).toBe("vector"); @@ -69,9 +69,9 @@ describe("search scope default strategy", () => { // Scopes restored by id alone resolve only after the source list arrives. expect(h.read("origin")).toBe("global"); await h.act(() => h.workspace.ensureSources()); - expect(h.read("strategy")).toBe("sag2"); - expect(h.read("origin")).toBe("scope"); - expect(h.read("scope-default")).toBe("sag2"); + expect(h.read("strategy")).toBe("vector"); + expect(h.read("origin")).toBe("global"); + expect(h.read("scope-default")).toBe("none"); await h.act(() => h.workspace.setScope(scope("a", "c"))); expect(h.read("strategy")).toBe("vector"); expect(h.read("origin")).toBe("global"); @@ -81,12 +81,12 @@ describe("search scope default strategy", () => { expect(h.read("origin")).toBe("global"); } finally { await h.cleanup(); } }); - it("uses the default carried by a toggled source before the list loads", async () => { + it("ignores retired mode preferences on a toggled source", async () => { const h = await harness(); try { await h.act(() => h.workspace.toggleSource(sources[2])); - expect(h.read("strategy")).toBe("multi"); - expect(h.read("origin")).toBe("scope"); + expect(h.read("strategy")).toBe("vector"); + expect(h.read("origin")).toBe("global"); } finally { await h.cleanup(); } }); it("ignores a scope default the deployment can no longer serve", async () => { @@ -102,7 +102,7 @@ describe("search scope default strategy", () => { try { await h.act(() => h.workspace.ensureSources()); await h.act(() => h.workspace.setScope(scope("a", "b"))); - expect(h.read("strategy")).toBe("sag2"); + expect(h.read("strategy")).toBe("vector"); await h.act(() => h.workspace.setStrategy("multi_es_fast")); expect(h.read("strategy")).toBe("multi_es_fast"); expect(h.read("origin")).toBe("pinned"); @@ -113,14 +113,14 @@ describe("search scope default strategy", () => { expect(h.requests).toEqual([expect.objectContaining({ strategy: "multi_es_fast", source_ids: ["a"] })]); } finally { await h.cleanup(); } }); - it("runs with the scope default when nothing is pinned", async () => { + it("runs with the application default when nothing is pinned", async () => { const h = await harness(); try { await h.act(() => h.workspace.ensureSources()); await h.act(() => h.workspace.setScope(scope("b"))); await h.act(() => h.workspace.run({ query: "question" }).catch(() => {})); - expect(h.requests).toEqual([expect.objectContaining({ strategy: "sag2", source_ids: ["b"] })]); - expect(h.read("origin")).toBe("scope"); + expect(h.requests).toEqual([expect.objectContaining({ strategy: "vector", source_ids: ["b"] })]); + expect(h.read("origin")).toBe("global"); } finally { await h.cleanup(); } }); }); diff --git a/apps/web/components/features/source-card.test.tsx b/apps/web/components/features/source-card.test.tsx index cab5328b..409ccce0 100644 --- a/apps/web/components/features/source-card.test.tsx +++ b/apps/web/components/features/source-card.test.tsx @@ -55,15 +55,13 @@ describe("source card", () => { expect(copyButton).toBeGreaterThan(navigationEnd); }); - it("shows a default retrieval mode pill only when the source sets one", () => { - expect(render(source)).not.toContain('data-testid="source-default-mode"'); - expect(render({ ...source, default_search_strategy: undefined } as unknown as Source)) - .not.toContain('data-testid="source-default-mode"'); - - const html = render({ ...source, default_search_strategy: "sag2" }); - expect(html).toContain('data-testid="source-default-mode"'); - expect(html).toContain('data-strategy="sag2"'); - expect(html).toContain("SAG2 证据检索"); - expect(html).toContain('aria-label="默认检索模式:SAG2 证据检索;搜索和问答时仍可临时切换"'); + it("shows the immutable algorithm, defaulting legacy sources to SAG1", () => { + expect(render(source)).toContain('data-engine-kind="sag1"'); + const html = render({ ...source, engine_kind: "sag2" }); + expect(html).toContain('data-testid="source-engine-kind"'); + expect(html).toContain('data-engine-kind="sag2"'); + expect(html).toContain("证据检索(SAG2)"); + expect(html).toContain("SAG2 暂不支持 OCTX 导出"); + expect(html).not.toContain('data-testid="source-default-mode"'); }); }); diff --git a/apps/web/components/features/source-card.tsx b/apps/web/components/features/source-card.tsx index 3767e84a..66a059d1 100644 --- a/apps/web/components/features/source-card.tsx +++ b/apps/web/components/features/source-card.tsx @@ -11,7 +11,7 @@ import { relativeTime } from "@/lib/format"; import { Button } from "@/components/ui/button"; import { ConfirmDialog } from "@/components/ui/confirm-dialog"; import { EditSourceDialog } from "@/components/features/edit-source-dialog"; -import { RetrievalModePill } from "@/components/features/retrieval-mode-pill"; +import { KnowledgeEnginePill } from "@/components/features/knowledge-engine-pill"; import { useOctxExports } from "@/components/features/octx-export-provider"; import { useApp } from "@/components/features/app-shell"; import { SourceIdCopy } from "@/components/features/source-id-copy"; @@ -28,7 +28,7 @@ export function SourceCard({ source, onChanged }: { source: Source; onChanged?: const { startExport, isSourceExporting } = useOctxExports(); const exportRunning = isSourceExporting(source.id); - const defaultMode = source.default_search_strategy ?? null; + const sag2 = source.engine_kind === "sag2"; const handleExport = React.useCallback( (event: React.MouseEvent) => { @@ -56,8 +56,8 @@ export function SourceCard({ source, onChanged }: { source: Source; onChanged?:

{source.name}

- {defaultMode && ( - + {( + )}

@@ -95,15 +95,15 @@ export function SourceCard({ source, onChanged }: { source: Source; onChanged?: variant="ghost" size="icon" aria-label={t("export")} - title={t("export")} + title={sag2 ? t("sag2OctxUnsupported") : t("export")} onClick={handleExport} - disabled={exportRunning || deletion.active} + disabled={exportRunning || deletion.active || sag2} className="bg-background/95 text-muted-foreground shadow-soft backdrop-blur-sm hover:text-foreground" > {exportRunning ? : } - {t("export")} + {sag2 ? t("sag2OctxUnsupported") : t("export")} {!deletion.active && , )); } -function pointerEvent(type: string) { - const event = new MouseEvent(type, { bubbles: true, button: 0 }); - Object.defineProperties(event, { pointerId: { value: 1 }, pointerType: { value: "mouse" } }); - return event; -} async function type(input: HTMLInputElement | HTMLTextAreaElement, value: string) { await act(async () => { Object.getOwnPropertyDescriptor(Object.getPrototypeOf(input), "value")!.set!.call(input, value); input.dispatchEvent(new Event("input", { bubbles: true })); }); } -async function pickMode(testId: string) { - const trigger = container.querySelector('[data-testid="retrieval-mode-picker"]')!; - await act(async () => trigger.dispatchEvent(pointerEvent("pointerdown"))); - const option = document.body.querySelector(`[data-testid="${testId}"]`)!; - expect(option, `option ${testId}`).not.toBeNull(); - await act(async () => { option.dispatchEvent(pointerEvent("pointerdown")); option.dispatchEvent(pointerEvent("pointerup")); }); -} const nameInput = () => container.querySelector('input[maxlength="200"]')!; const submitButton = () => container.querySelector('button[type="submit"]')!; async function submit() { @@ -83,74 +71,25 @@ async function submit() { } describe("source create form", () => { - it("creates a source that follows the global default without sending a strategy", async () => { - await mount(); - await type(nameInput(), "Manuals"); - expect(container.querySelector('[data-testid="jev-quick-setup"]')).toBeNull(); - await submit(); - expect(api.createSource).toHaveBeenCalledWith({ name: "Manuals", description: "" }); + it("creates a SAG1 source by default without changing model settings", async () => { + await mount(); await type(nameInput(), "Manuals"); await submit(); + expect(api.createSource).toHaveBeenCalledWith({ name: "Manuals", description: "", engine_kind: "sag1" }); expect(api.saveModelConfig).not.toHaveBeenCalled(); expect(onCreated).toHaveBeenCalledWith(expect.objectContaining({ id: "source-1" })); }); - it("sends the chosen default retrieval mode", async () => { - await mount(); - await type(nameInput(), "Manuals"); - await pickMode("retrieval-mode-multi"); - await submit(); - expect(api.createSource).toHaveBeenCalledWith({ name: "Manuals", description: "", default_search_strategy: "multi" }); - expect(api.saveModelConfig).not.toHaveBeenCalled(); - }); - it("blocks creation until a JEV key is entered, then saves the service before creating", async () => { - await mount(); - await type(nameInput(), "Manuals"); - await pickMode("retrieval-mode-sag2"); - expect(container.querySelector('[data-testid="jev-quick-setup"]')).not.toBeNull(); - expect(submitButton().disabled).toBe(true); - expect(container.querySelector('[data-testid="source-form-blocked"]')?.textContent).toBe("Enter a JEV API key to save this default mode."); - - await type(container.querySelector('input[type="password"]')!, "jev-secret"); + it("can create a SAG2 source without a JEV key because indexing does not use JEV", async () => { + await mount(); await type(nameInput(), "Evidence"); + await act(async () => container.querySelector('input[value="sag2"]')!.click()); expect(submitButton().disabled).toBe(false); - expect(container.querySelector('[data-testid="source-form-blocked"]')).toBeNull(); - await submit(); - expect(api.saveModelConfig).toHaveBeenCalledWith({ - jev_endpoint: "https://api.302.ai/typesafeai/v1/systemone", jev_model: "jev-latest", jev_api_key: "jev-secret", - }); - expect(state.refreshCapabilities).toHaveBeenCalledTimes(1); - expect(api.createSource).toHaveBeenCalledWith({ name: "Manuals", description: "", default_search_strategy: "sag2" }); - expect(vi.mocked(api.saveModelConfig).mock.invocationCallOrder[0]).toBeLessThan(vi.mocked(api.createSource).mock.invocationCallOrder[0]); - }); - it("keeps a saved custom endpoint instead of replacing it with the preset", async () => { - vi.mocked(api.getModelConfig).mockResolvedValue({ jev_endpoint: "https://jev.internal/score", jev_model: "jev-pinned" } as never); - await mount(); - await type(nameInput(), "Manuals"); - await pickMode("retrieval-mode-multi_jev"); - const endpoint = container.querySelector('input[type="url"]')!; - expect(endpoint.value).toBe("https://jev.internal/score"); - expect(endpoint.readOnly).toBe(false); - await type(container.querySelector('input[type="password"]')!, "k"); - await submit(); - expect(api.saveModelConfig).toHaveBeenCalledWith({ jev_endpoint: "https://jev.internal/score", jev_model: "jev-pinned", jev_api_key: "k" }); + expect(api.createSource).toHaveBeenCalledWith({ name: "Evidence", description: "", engine_kind: "sag2" }); + expect(api.saveModelConfig).not.toHaveBeenCalled(); + expect(container.querySelector('[data-testid="jev-quick-setup"]')).toBeNull(); }); - it("shows a JEV save failure inline and does not create the source", async () => { - vi.mocked(api.saveModelConfig).mockRejectedValue(new ApiError(400, "jev_invalid", "JEV rejected the key")); - await mount(); - await type(nameInput(), "Manuals"); - await pickMode("retrieval-mode-sag2"); - await type(container.querySelector('input[type="password"]')!, "bad"); - await submit(); - expect(container.querySelector('[data-testid="jev-quick-setup-error"]')?.textContent).toBe("JEV rejected the key"); - expect(api.createSource).not.toHaveBeenCalled(); + it("does not report creation success after an API failure", async () => { + vi.mocked(api.createSource).mockRejectedValue(new ApiError(400, "invalid_source", "Source rejected")); + await mount(); await type(nameInput(), "Manuals"); await submit(); expect(onCreated).not.toHaveBeenCalled(); expect(submitButton().disabled).toBe(false); }); - it("shows a backend rejection of the default mode inline", async () => { - vi.mocked(api.createSource).mockRejectedValue(new ApiError(400, "vector_provider_lacks_lexical", "Lexical search is required")); - await mount(); - await type(nameInput(), "Manuals"); - await pickMode("retrieval-mode-multi"); - await submit(); - expect(container.querySelector('[data-testid="source-form-error"]')?.textContent).toBe("Lexical search is required"); - expect(onCreated).not.toHaveBeenCalled(); - }); }); diff --git a/apps/web/components/features/source-create-form.tsx b/apps/web/components/features/source-create-form.tsx index 41b73f23..38df46b2 100644 --- a/apps/web/components/features/source-create-form.tsx +++ b/apps/web/components/features/source-create-form.tsx @@ -4,17 +4,7 @@ import * as React from "react"; import { useTranslations } from "next-intl"; import { toast } from "sonner"; -import { useApp } from "@/components/features/app-shell"; -import { useJevQuickSetup } from "@/components/features/jev-quick-setup"; -import { RetrievalModePicker } from "@/components/features/retrieval-mode-picker"; import { api, ApiError } from "@/lib/api"; -import { - DEFAULT_SEARCH_STRATEGY, - getSearchStrategiesDisabled, - isSearchStrategy, - needsJevQuickSetup, - type SearchStrategy, -} from "@/lib/retrieval-config"; import type { Source } from "@/lib/types"; import { cn } from "@/lib/utils"; import { Button } from "@/components/ui/button"; @@ -32,58 +22,24 @@ export function SourceCreateForm({ compact?: boolean; }) { const t = useTranslations("SourceForm"); - const strategies = useTranslations("SearchStrategies"); - const modes = useTranslations("RetrievalModes"); - const { capabilities } = useApp(); const [name, setName] = React.useState(""); const [description, setDescription] = React.useState(""); - const [mode, setMode] = React.useState(null); + const [engineKind, setEngineKind] = React.useState<"sag1" | "sag2">("sag1"); const [loading, setLoading] = React.useState(false); - const [error, setError] = React.useState(null); const nameId = React.useId(); const descriptionId = React.useId(); - const modeId = React.useId(); - - const globalStrategy = isSearchStrategy(capabilities?.search_strategy) - ? capabilities.search_strategy - : DEFAULT_SEARCH_STRATEGY; - const unsupportedMessage = strategies("unsupportedBackend"); - const disabledMap = React.useMemo( - () => getSearchStrategiesDisabled(capabilities, unsupportedMessage), - [capabilities, unsupportedMessage], - ); - const jevSetupNeeded = needsJevQuickSetup(mode, disabledMap); - const jevSetup = useJevQuickSetup({ enabled: jevSetupNeeded }); - const jevKeyMissing = jevSetupNeeded && !jevSetup.ready; async function submit(event: React.FormEvent) { event.preventDefault(); - if (jevKeyMissing) return; setLoading(true); - setError(null); try { - if (jevSetupNeeded) { - try { - await jevSetup.save(); - } catch { - // The quick setup shows the failure next to its fields. - return; - } - } - const source = await api.createSource({ - name: name.trim(), - description: description.trim(), - ...(mode ? { default_search_strategy: mode } : {}), - }); + const source = await api.createSource({ name: name.trim(), description: description.trim(), engine_kind: engineKind }); toast.success(t("created")); onCreated(source); setName(""); setDescription(""); - setMode(null); - } catch (cause) { - const message = cause instanceof ApiError ? cause.message : t("createFailed"); - setError(message); - toast.error(message); + } catch (error) { + toast.error(error instanceof ApiError ? error.message : t("createFailed")); } finally { setLoading(false); } @@ -116,37 +72,26 @@ export function SourceCreateForm({ rows={compact ? 3 : 2} /> - { - setMode(next); - setError(null); - }} - globalStrategy={globalStrategy} - disabledMap={disabledMap} - disabled={loading} - jevSetup={jevSetup} - /> - {error && ( -

- {error} -

- )} - -
- {jevKeyMissing && ( - - {modes("keyRequiredToSubmit")} - - )} +
+ {t("algorithm")} + {(["sag1", "sag2"] as const).map(kind => ( + + ))} +

{t("algorithmImmutable")}

+
+
{onCancel && ( )} -
diff --git a/apps/web/components/features/source-engine-binding.test.tsx b/apps/web/components/features/source-engine-binding.test.tsx new file mode 100644 index 00000000..4d117f1a --- /dev/null +++ b/apps/web/components/features/source-engine-binding.test.tsx @@ -0,0 +1,28 @@ +/** @vitest-environment jsdom */ +import * as React from "react"; +import { act } from "react"; +import { createRoot } from "react-dom/client"; +import { NextIntlClientProvider } from "next-intl"; +import { afterEach, expect, it, vi } from "vitest"; +import messages from "@/messages/zh-CN.json"; +import { SourceCreateForm } from "./source-create-form"; + +vi.mock("@/components/features/app-shell", () => ({ useApp: () => ({ capabilities: {} }) })); +vi.mock("sonner", () => ({ toast: { success: vi.fn(), error: vi.fn() } })); +let cleanup: (() => Promise) | undefined; +afterEach(async () => { await cleanup?.(); }); +it("offers only two immutable ingestion algorithms and defaults to SAG1", async () => { + (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + const container = document.createElement("div"); document.body.append(container); + const root = createRoot(container); + cleanup = async () => { await act(async () => root.unmount()); container.remove(); }; + await act(async () => root.render( + + )); + expect(container.textContent).toContain("事件检索(SAG1)"); + expect(container.textContent).toContain("证据检索(SAG2)"); + const radios = [...container.querySelectorAll('input[type="radio"]')]; + expect(radios.map(r => r.value)).toEqual(["sag1", "sag2"]); + expect(radios[0].checked).toBe(true); + expect(container.textContent).not.toContain("默认检索模式"); +}); diff --git a/apps/web/components/features/upload-zone.tsx b/apps/web/components/features/upload-zone.tsx index 1f3b4ddd..cb822a51 100644 --- a/apps/web/components/features/upload-zone.tsx +++ b/apps/web/components/features/upload-zone.tsx @@ -15,12 +15,14 @@ import { Spinner } from "@/components/ui/spinner"; export function UploadZone({ sourceId, + engineKind = "sag1", onUploaded, maxMb = 25, allowedExts, compact = false, }: { sourceId: string; + engineKind?: "sag1" | "sag2"; onUploaded: () => void; maxMb?: number; allowedExts?: string[]; @@ -161,7 +163,7 @@ export function UploadZone({
)}
-

+ {engineKind === "sag1" &&

{t("concurrencyHint")}{" "} {t("concurrencyAction")} -

+

}
); } diff --git a/apps/web/lib/api.ts b/apps/web/lib/api.ts index 0fafb70a..154609e4 100644 --- a/apps/web/lib/api.ts +++ b/apps/web/lib/api.ts @@ -787,6 +787,7 @@ export const api = { listSources: () => request("/api/v1/sources"), getSource: (id: string) => request(`/api/v1/sources/${id}`), createSource: (b: { + engine_kind?: "sag1" | "sag2"; name: string; description?: string; /** Omit (or send null) to follow the global default retrieval mode. */ diff --git a/apps/web/lib/retrieval-config.test.ts b/apps/web/lib/retrieval-config.test.ts index e81d9e71..580296c9 100644 --- a/apps/web/lib/retrieval-config.test.ts +++ b/apps/web/lib/retrieval-config.test.ts @@ -1,6 +1,5 @@ import { describe, expect, it } from "vitest"; import { - getScopeDefaultStrategy, getSearchStrategiesDisabled, isJevConfigDisabledReason, isJevScoredStrategy, @@ -43,7 +42,7 @@ describe("JEV strategy availability", () => { describe("SAG2 strategy availability", () => { it("lists SAG2 after JEV reranking and marks both as JEV-scored", () => { - expect(SEARCH_STRATEGIES.map(strategy => strategy.value)).toEqual(["vector", "multi_es_fast", "multi", "multi_jev", "sag2"]); + expect(SEARCH_STRATEGIES.map(strategy => strategy.value)).toEqual(["auto", "vector", "multi_es_fast", "multi", "multi_jev", "sag2"]); expect(isSearchStrategy("sag2")).toBe(true); expect(JEV_SCORED_STRATEGIES).toEqual(["multi_jev", "sag2"]); expect(isJevScoredStrategy("sag2")).toBe(true); @@ -73,21 +72,7 @@ describe("SAG2 strategy availability", () => { }); }); -describe("source default strategy", () => { - it("resolves a scope default only when every scoped source shares the same non-null value", () => { - expect(getScopeDefaultStrategy([])).toBeNull(); - expect(getScopeDefaultStrategy([{ default_search_strategy: "sag2" }])).toBe("sag2"); - expect(getScopeDefaultStrategy([{ default_search_strategy: "sag2" }, { default_search_strategy: "sag2" }])).toBe("sag2"); - expect(getScopeDefaultStrategy([{ default_search_strategy: "sag2" }, { default_search_strategy: "multi" }])).toBeNull(); - expect(getScopeDefaultStrategy([{ default_search_strategy: "sag2" }, { default_search_strategy: null }])).toBeNull(); - expect(getScopeDefaultStrategy([{ default_search_strategy: "multi" }, {}])).toBeNull(); - expect(getScopeDefaultStrategy([{ default_search_strategy: null }, {}])).toBeNull(); - }); - it("ignores a scope default the deployment currently cannot serve", () => { - const blocked = { sag2: { reason: "jev_api_key_missing", message: "Add a key" } }; - expect(getScopeDefaultStrategy([{ default_search_strategy: "sag2" }], blocked)).toBeNull(); - expect(getScopeDefaultStrategy([{ default_search_strategy: "multi" }], blocked)).toBe("multi"); - }); +describe("paid mode setup", () => { it("offers the inline JEV setup only for JEV modes blocked by a missing configuration", () => { const disabled = { multi_jev: { reason: "vector_provider_lacks_lexical", message: "Lexical" }, diff --git a/apps/web/lib/retrieval-config.ts b/apps/web/lib/retrieval-config.ts index af5b2bdf..14d243cd 100644 --- a/apps/web/lib/retrieval-config.ts +++ b/apps/web/lib/retrieval-config.ts @@ -7,6 +7,7 @@ import { } from "lucide-react"; export const SEARCH_STRATEGIES = [ + { value: "auto", labelKey: "autoLabel", descriptionKey: "autoDescription" }, { value: "vector", labelKey: "vectorLabel", @@ -36,10 +37,11 @@ export const SEARCH_STRATEGIES = [ export type SearchStrategy = (typeof SEARCH_STRATEGIES)[number]["value"]; -export const DEFAULT_SEARCH_STRATEGY: SearchStrategy = "vector"; +export const DEFAULT_SEARCH_STRATEGY: SearchStrategy = "auto"; /** One icon per mode, shared by the search control, the source pill and the picker. */ export const SEARCH_STRATEGY_ICONS: Record = { + auto: ScanSearch, vector: Zap, multi_es_fast: ShieldQuestion, multi: Sparkles, @@ -53,6 +55,7 @@ export const SEARCH_STRATEGY_ICONS: Record = { * 前端只用来在拿不到 disabled map 时兜底渲染,避免用户点了才发现打不通。 */ export const SEARCH_STRATEGY_REQUIREMENTS = { + auto: [] as const, vector: [] as const, multi: [] as const, multi_es_fast: ["lexical_search"] as const, @@ -154,23 +157,3 @@ export function needsJevQuickSetup( return isJevScoredStrategy(strategy) && isJevConfigDisabledReason(disabledMap?.[strategy]?.reason); } - -/** - * The default mode shared by every source in a search scope. The backend only - * honours a source default when all scoped sources agree on the same non-null - * value, so the client mirrors that rule. A scope default the deployment can - * no longer serve (present in `disabledMap`) is ignored as well. - */ -export function getScopeDefaultStrategy( - sources: ReadonlyArray<{ default_search_strategy?: SearchStrategy | null }>, - disabledMap?: SearchStrategyDisabledMap | null, -): SearchStrategy | null { - if (sources.length === 0) return null; - const first = sources[0].default_search_strategy ?? null; - if (!first) return null; - for (const source of sources) { - if ((source.default_search_strategy ?? null) !== first) return null; - } - if (disabledMap?.[first]) return null; - return first; -} diff --git a/apps/web/lib/types.ts b/apps/web/lib/types.ts index cd8b36f6..a317942b 100644 --- a/apps/web/lib/types.ts +++ b/apps/web/lib/types.ts @@ -64,6 +64,7 @@ export type ParserStatus = | "fallback" | "failed"; export interface Source { + engine_kind?: "sag1" | "sag2"; id: string; name: string; description: string; @@ -525,6 +526,7 @@ export interface SourceGraphResponse { } export interface Section { + metadata?: Record; chunk_id: string | null; heading: string; content: string; diff --git a/apps/web/messages/en-US.json b/apps/web/messages/en-US.json index 38266835..a560e464 100644 --- a/apps/web/messages/en-US.json +++ b/apps/web/messages/en-US.json @@ -285,13 +285,19 @@ "creating": "Creating…", "create": "Create source", "new": "New source", - "dialogDescription": "Sources hold content. Name it, pick a default retrieval mode, then upload documents to search and chat.", + "dialogDescription": "Choose a knowledge algorithm, create the source, then upload documents.", "updated": "Source updated", "updateFailed": "Failed to update source", "edit": "Edit source", - "editDescription": "Change this source’s name, description and default retrieval mode.", + "editDescription": "Edit the name and description. The knowledge algorithm cannot be changed.", "saving": "Saving…", - "saveChanges": "Save changes" + "saveChanges": "Save changes", + "algorithm": "Knowledge algorithm", + "sag1": "Event retrieval (SAG1)", + "sag2": "Evidence retrieval (SAG2)", + "sag1Description": "Parse, chunk, embed, and extract entities and events.", + "sag2Description": "Parse, chunk and index evidence without entity or event extraction. Retrieval requires a JEV API key.", + "algorithmImmutable": "The algorithm is fixed at creation and applies to all future uploads." }, "SourceCard": { "deleteSubmitted": "Deletion request submitted", @@ -347,7 +353,8 @@ "complete": "Export complete", "failed": "Export failed", "cancelled": "Cancelled" - } + }, + "sag2OctxUnsupported": "OCTX export is not supported for SAG2 yet" }, "UploadZone": { "unsupportedType": "{name}: Unsupported file type", @@ -524,6 +531,7 @@ "list": "List", "graph2dView": "2D graph view", "graph3dView": "3D graph view", + "sag2UploadDescription": "Uploads are parsed, chunked and indexed as source text, without entity or event extraction.", "emptyDocumentsDescription": "Add a document from the upper-right. SAG will parse, chunk, vectorize, and extract events and entities automatically.", "addDialogDescription": "The document will be parsed, chunked, and processed for events and entities automatically.", "syncDialogDescription": "Fetch the latest connector content and update this source.", @@ -617,7 +625,9 @@ "sag2Description": "BM25 recall scored over several JEV rounds; no vector store needed; paid service.", "paid": "Paid", "openSettings": "Open settings", - "unsupportedBackend": "This server does not advertise support for this JEV-scored mode. Upgrade the server to use it." + "unsupportedBackend": "This server does not advertise support for this JEV-scored mode. Upgrade the server to use it.", + "autoLabel": "Auto (knowledge algorithms)", + "autoDescription": "Retrieve with each knowledge source’s bound SAG1 or SAG2 algorithm and merge the evidence." }, "RetrievalModes": { "label": "Default retrieval mode", @@ -658,7 +668,10 @@ "jevTestFailed": "Connection test failed", "jevSaveFailed": "Failed to save the JEV service", "jevSharedNote": "Saved once for every JEV mode; change it later under Settings → Knowledge → JEV reranking service.", - "jevOpenSettings": "Open settings" + "jevOpenSettings": "Open settings", + "cancelSetup": "Cancel", + "savingSetup": "Saving…", + "saveAndUse": "Save and use this mode" }, "RetrievalTest": { "failed": "Retrieval failed", @@ -712,7 +725,7 @@ "retrievalDescription": "Control knowledge retrieval and reranking services.", "retrievalRules": "Retrieval rules", "retrievalRulesDescription": "Set the retrieval strategy and result count.", - "retrievalStrategy": "Retrieval strategy", + "retrievalStrategy": "SAG1 retrieval strategy", "chinese": "中文", "english": "English", "topK": "Results · {count, number}", @@ -1840,7 +1853,8 @@ "partial": "Partial results: some sources did not complete.", "origin": "Using {mode} ({origin})", "originPersona": "persona default", - "originSourceDefault": "source default" + "originSourceDefault": "source default", + "engineFailure": "{engine} retrieval failed or is incomplete: {message}" }, "ClientAccess": { "title": "CLI and automation", diff --git a/apps/web/messages/zh-CN.json b/apps/web/messages/zh-CN.json index 1f241476..a6130e25 100644 --- a/apps/web/messages/zh-CN.json +++ b/apps/web/messages/zh-CN.json @@ -285,13 +285,19 @@ "creating": "创建中…", "create": "创建信源", "new": "新建信源", - "dialogDescription": "信源用来装内容。起个名字、选好默认检索模式,创建后上传文档即可搜索和问答。", + "dialogDescription": "选择知识库算法并创建信源,之后即可上传文档。", "updated": "信源已更新", "updateFailed": "更新失败", "edit": "修改信源", - "editDescription": "调整这个信源的名称、描述和默认检索模式。", + "editDescription": "修改名称和描述;知识库算法创建后不可更改。", "saving": "保存中…", - "saveChanges": "保存修改" + "saveChanges": "保存修改", + "algorithm": "知识库算法", + "sag1": "事件检索(SAG1)", + "sag2": "证据检索(SAG2)", + "sag1Description": "解析、分块、向量化,并提取实体和事项。", + "sag2Description": "解析、分块并建立原文索引,不提取实体和事项;检索需要 JEV API Key。", + "algorithmImmutable": "创建后不可更改算法,后续上传始终沿用此算法。" }, "SourceCard": { "deleteSubmitted": "删除请求已提交", @@ -347,7 +353,8 @@ "complete": "导出完成", "failed": "导出失败", "cancelled": "已取消" - } + }, + "sag2OctxUnsupported": "SAG2 暂不支持 OCTX 导出" }, "UploadZone": { "unsupportedType": "{name}:不支持的文件类型", @@ -524,6 +531,7 @@ "list": "列表", "graph2dView": "2D 图谱视图", "graph3dView": "3D 图谱视图", + "sag2UploadDescription": "上传文档后自动解析、分块并建立原文索引,不提取实体和事项。", "emptyDocumentsDescription": "点击右上角添加文档,SAG 会自动解析、分块、向量化并抽取事件与实体。", "addDialogDescription": "添加后会自动解析、分块并抽取事件与实体。", "syncDialogDescription": "抓取连接器中的最新内容并更新信息源。", @@ -601,23 +609,25 @@ "exportOctx": "导出为 .octx" }, "SearchStrategies": { - "vectorLabel": "快速(vector)", + "vectorLabel": "事件检索(SAG1)· 快速", "vectorDescription": "基于向量语义相似度直接召回,响应更快。", - "multiEsFastLabel": "快速(multi_es-fast)", + "multiEsFastLabel": "事件检索(SAG1)· 均衡", "multiEsFastDescription": "基于 BM25 实体召回与事件多跳的快速检索,跳过 LLM 精排。", - "multiLabel": "精确", + "multiLabel": "事件检索(SAG1)· 精确", "multiDescription": "结合实体关系与 LLM 精排,结果更完整。", "mode": "检索模式", "modeAria": "检索模式:{strategy}", "default": "默认", "disabledSuffix": "(不可用)", - "multiJevLabel": "JEV 精排", + "multiJevLabel": "事件检索(SAG1)· JEV 精排", "multiJevDescription": "扩展关联证据后,使用配置的 JEV 服务评分相关性。", - "sag2Label": "SAG2 证据检索", + "sag2Label": "证据检索(SAG2)", "sag2Description": "BM25 召回后由 JEV 服务多轮评分,不依赖向量库;付费服务。", "paid": "付费", "openSettings": "去设置", - "unsupportedBackend": "当前服务端未声明支持此 JEV 评分模式,请升级服务端后使用。" + "unsupportedBackend": "当前服务端未声明支持此 JEV 评分模式,请升级服务端后使用。", + "autoLabel": "自动(按知识库算法)", + "autoDescription": "按知识库创建时绑定的 SAG1 / SAG2 分别检索,再合并证据。" }, "RetrievalModes": { "label": "默认检索模式", @@ -658,7 +668,10 @@ "jevTestFailed": "连接测试失败", "jevSaveFailed": "JEV 服务保存失败", "jevSharedNote": "保存后用于全部 JEV 模式,可在 设置 → 知识库 → JEV 精排服务 中修改。", - "jevOpenSettings": "打开设置" + "jevOpenSettings": "打开设置", + "cancelSetup": "取消", + "savingSetup": "保存中…", + "saveAndUse": "保存并使用此模式" }, "RetrievalTest": { "failed": "检索失败", @@ -712,7 +725,7 @@ "retrievalDescription": "控制知识召回方式与精排服务。", "retrievalRules": "检索规则", "retrievalRulesDescription": "调整检索策略和召回条数。", - "retrievalStrategy": "检索策略", + "retrievalStrategy": "SAG1 检索策略", "chinese": "中文", "english": "English", "topK": "召回条数 · {count, number}", @@ -1840,7 +1853,8 @@ "partial": "部分结果:部分信源未完成检索。", "origin": "按{origin}使用 {mode}", "originPersona": "人格默认", - "originSourceDefault": "信源默认" + "originSourceDefault": "信源默认", + "engineFailure": "{engine} 检索失败或不完整:{message}" }, "ClientAccess": { "title": "CLI 与自动化",