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..3ea07645 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,14 @@ ## Unreleased +- 探索页新增「对比」:同一问题在 2–3 种检索模式下并排检索,显示耗时、召回数、SAG2 的 JEV 用量与共同命中的片段,可选 LLM 评审,并可一键按某一模式正式检索。 +- SAG2 只读引擎改在专用事件循环线程运行:大范围检索构建内存语料时不再阻塞 API 事件循环;整次超时会同步取消引擎侧工作。 +- 问答页可为当前轮次选择检索模式:输入框工具栏新增与探索页一致的模式控件,默认显示将实际使用的模式及其来源(人格默认 / 信源默认 / 全局),用户选择后对后续轮次生效;付费 JEV 模式缺少 API Key 时在开始生成前拒绝并给出设置入口。回答的活动时间线显示本轮实际模式与来源。 +- 信源可设置「默认检索模式」:创建或编辑信源时选择快速、精确、JEV 精排或 SAG2 证据检索,并以通俗说明与付费提示帮助选择;JEV 模式缺少 API Key 时可在对话框内直接配置。搜索与问答在所选范围内信源一致时自动采用该默认(显式选择与 Agent 人格优先),结果 `stats.strategy_origin` 标明来源。不改变文档入库流程。 +- 新增可选 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..94dd302f 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,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 服务多轮评分,不依赖向量库 | -这里列出的是应用/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 秒、失败报错,可选择粗排降级。 +每个信源可在创建或编辑时设置**默认检索模式**;未设置则跟随全局默认。探索页与问答页的输入框都提供模式控件,可为当前查询或当前轮次临时切换;探索页还可开启「对比」,用同一问题并排比较 2–3 种模式的耗时、召回与用量,并一键采用其中一种。搜索与问答按“本次显式选择 → Agent 人格 → 范围内信源的共同默认 → 全局默认”解析模式,范围内信源默认不一致时按全局默认处理;结果 `stats.strategy_origin` 标明来源。该设置只影响检索,不改变文档入库流程。 -支持 LanceDB、Elasticsearch,暂不支持 pgvector;PostgreSQL 作为关系库不受影响。未启用时沿用原检索策略,已有文档无需重新入库。效果与成本见[更新日志](CHANGELOG.md#jev-reranking)。 +在“设置 → 知识库 → 检索”配置 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 的业务表保持只读。 + +JEV 精排支持 LanceDB、Elasticsearch,暂不支持 pgvector;PostgreSQL 作为关系库不受影响。未启用时沿用原检索策略,已有文档无需重新入库。效果与成本见[更新日志](CHANGELOG.md#jev-reranking)。 #### 存储后端 diff --git a/README.md b/README.md index 01dc29af..64c29321 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,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 | -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. +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. -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). +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. + +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..8f013373 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/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/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..ee479421 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 @@ -43,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, @@ -169,16 +171,18 @@ 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, ) - 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/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/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..8c612b21 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 self._settings.jev_endpoint: + elif capability == "jev" and not jev_connection_ready(settings): + missing.append(capability) + 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,36 +411,31 @@ 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_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: @@ -890,10 +906,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 +924,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 +1212,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 +1223,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..292e2d2e --- /dev/null +++ b/apps/api/sag_api/sag/sag2_engine.py @@ -0,0 +1,525 @@ +"""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: + """范围内段落行数(含待清理的历史版本),用于扫描成本护栏。""" + from sqlalchemy import column, func, select, table + + chunks = table(SAG_CHUNK_TABLE, column("data_source_id")) + statement = select(func.count()).select_from(chunks).where(chunks.c.data_source_id.in_(data_source_ids)) + 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/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/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_domain.py b/apps/api/sag_api/services/agent_domain.py index d2ca35a6..4194bb4f 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: @@ -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 d70aca5a..89bb68a5 100644 --- a/apps/api/sag_api/services/agent_tooling.py +++ b/apps/api/sag_api/services/agent_tooling.py @@ -348,8 +348,11 @@ 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) - # Keep this run's mode stable while the model prepares the tool call. + strategy = knowledge_search_strategy( + host_context.persona, configuration, host_context.sources, host_context.requested_strategy, + ) + # Keep this run's mode stable while the model prepares the tool call; the + # explicit turn choice stays in requested_strategy so its origin is reported. host_context = replace(host_context, persona={**host_context.persona, "search_strategy": strategy}) if strategy == "multi_jev": source_count = min(len(host_context.sources), configuration.search_source_candidate_limit) @@ -361,6 +364,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..dcd2a9e5 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, @@ -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,11 +365,12 @@ 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 == "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)] @@ -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 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/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/base.py b/apps/api/sag_api/tools/base.py index ecb0651f..b70c47ba 100644 --- a/apps/api/sag_api/tools/base.py +++ b/apps/api/sag_api/tools/base.py @@ -44,6 +44,8 @@ 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 diff --git a/apps/api/sag_api/tools/builtin.py b/apps/api/sag_api/tools/builtin.py index 9bf080bc..d9317a79 100644 --- a/apps/api/sag_api/tools/builtin.py +++ b/apps/api/sag_api/tools/builtin.py @@ -19,10 +19,11 @@ 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 ( + common_source_default_strategy, event_scores_from_evidence, published_document_inputs, recall_event_scores, @@ -79,11 +80,16 @@ 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 JEV.""" - default = "multi_jev" if configuration.search_strategy == "multi_jev" else "vector" - value = persona.get("search_strategy") or default - if default == "multi_jev" and ( +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 + 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 @@ -94,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 "(无相关资料)" @@ -248,7 +267,10 @@ 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, 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} @@ -260,7 +282,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 +346,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, @@ -337,7 +359,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/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_chat_turn_strategy.py b/apps/api/tests/test_chat_turn_strategy.py new file mode 100644 index 00000000..c33e10cf --- /dev/null +++ b/apps/api/tests/test_chat_turn_strategy.py @@ -0,0 +1,151 @@ +"""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 + + +@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_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..c77e8d66 --- /dev/null +++ b/apps/api/tests/test_sag2_engine_integration.py @@ -0,0 +1,149 @@ +"""Run zleap-sag2 read-only against a real zleap-sag SQLite store with an offline scorer.""" + +import sqlite3 + +import pytest + +from sag_api.core.config import Settings +from sag_api.core.errors import ConfigurationError +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"] == 5 + 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() 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/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/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)/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/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/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..4c256fdb 100644 --- a/apps/web/components/features/chat/conversation-panel.test.tsx +++ b/apps/web/components/features/chat/conversation-panel.test.tsx @@ -6,20 +6,33 @@ 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(), 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, @@ -29,7 +42,7 @@ vi.mock("./conversation-provider", () => ({ getSessionSnapshot: () => ({ run: {} }), }), useConversationComposer: () => ({ - input: "Unsent draft", scoped: [{ id: "composer-source", name: "Composer selection" }], + input: "Unsent draft", scoped: state.scoped, images: [], webEnabled: false, setInput: state.setInput, setImages: vi.fn(), setScoped: vi.fn(), setWebEnabled: vi.fn(), }), @@ -42,16 +55,49 @@ 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.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 +111,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 +151,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 +163,90 @@ 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(); + expect(trigger().textContent).toContain("Fast (multi_es-fast)"); + 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("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..9947c1b0 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 { + DEFAULT_SEARCH_STRATEGY, + getScopeDefaultStrategy, + getSearchStrategiesDisabled, + isSearchStrategy, + 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,46 @@ 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]); + const globalStrategy = isSearchStrategy(capabilities?.search_strategy) + ? capabilities.search_strategy + : DEFAULT_SEARCH_STRATEGY; + const resolvedStrategy = personaStrategy ?? scopeDefaultStrategy ?? globalStrategy; + 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}"]`) @@ -537,6 +606,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 +617,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;未登记表示被全局并发边界拒绝,保留草稿。 @@ -563,7 +635,13 @@ export function ConversationPanel({ followOutputRef.current = true; void request.catch((error) => { - toast.error(error instanceof Error ? error.message : t("connectionInterrupted")); + // 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 }); + } else { + 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 +815,31 @@ export function ConversationPanel({

+ {strategyNotice && ( +
+ {strategyNotice.message} + + {searchStrategies("openSettings")} + + +
+ )}
{images.length > 0 && (
@@ -945,6 +1048,14 @@ export function ConversationPanel({ : t("webDisabledDescription")} + 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..2a03c187 --- /dev/null +++ b/apps/web/components/features/edit-source-dialog.test.tsx @@ -0,0 +1,101 @@ +/** @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() { + 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 and sends it unchanged", 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", default_search_strategy: "multi" }); + expect(onUpdated).toHaveBeenCalledWith(expect.objectContaining({ default_search_strategy: "multi" })); + }); + 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..5c2baf80 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,65 @@ 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 jevSetupNeeded = open && 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(), + 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 +128,7 @@ export function EditSourceDialog({ {t("edit")} - + {t("edit")} {t("editDescription")} @@ -114,9 +157,32 @@ export function EditSourceDialog({ rows={2} /> + { + setMode(next); + setError(null); + }} + globalStrategy={globalStrategy} + disabledMap={disabledMap} + disabled={loading} + jevSetup={jevSetup} + /> + + {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.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..809d4fa3 100644 --- a/apps/web/components/features/knowledge-config-form.tsx +++ b/apps/web/components/features/knowledge-config-form.tsx @@ -22,7 +22,20 @@ 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 { + JEV_DEFAULT_MODEL, + JEV_ENDPOINTS, + providerForEndpoint, + type JevProvider, +} from "@/lib/jev-config"; import type { ModelConfig, ModelConfigPatch } from "@/lib/types"; import { Tooltip, @@ -31,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; @@ -45,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"); @@ -82,10 +83,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 +110,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 +197,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 +390,11 @@ export function KnowledgeConfigForm() { {strategies(labelKey)} + {isJevScoredStrategy(value) && ( + + {strategies("paid")} + + )} {info && ( {strategies("disabledSuffix")} @@ -409,15 +433,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 +483,9 @@ export function KnowledgeConfigForm() { {t("jevKey")} { setJevKey(event.target.value); setJevTestResult(null); }} /> {jevProvider !== "custom" && {t("jevKeyProviderDescription", { provider: jevProvider === "302" ? "302.AI" : "TypeSafe" })}} @@ -474,10 +511,10 @@ export function KnowledgeConfigForm() {
{jevUnsupported &&

{strategies("unsupportedBackend")}

} - {invalidJevDraft &&

{t("jevInvalidDraft")}

} + {invalidJevDraft &&

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

}
@@ -486,6 +523,7 @@ export function KnowledgeConfigForm() {
}
+
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-compare-parts.tsx b/apps/web/components/features/retrieval-compare-parts.tsx new file mode 100644 index 00000000..f93c4679 --- /dev/null +++ b/apps/web/components/features/retrieval-compare-parts.tsx @@ -0,0 +1,213 @@ +"use client"; + +import * as React from "react"; +import { Trophy } from "lucide-react"; + +import type { EvalJudge, EvalStrategyResult } from "@/lib/api"; +import type { SearchStrategy } from "@/lib/retrieval-config"; +import type { Section } from "@/lib/types"; +import { RetrievalStatus } from "@/components/features/retrieval-status"; +import { cn } from "@/lib/utils"; + +/** Small muted badge used next to a mode label (paid / default markers). */ +export const strategyBadgeClassName = + "rounded bg-muted px-1 py-0.5 text-[10px] font-normal leading-none text-muted-foreground"; + +export 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; +} + +/** One retrieved passage: rank, heading, score bar and a two-line excerpt. */ +export function SectionRow({ + index, + section, + sectionLabel, + marker, + onClick, +}: { + index: number; + section: Section; + sectionLabel: string; + /** Optional inline marker rendered after the heading (e.g. a shared-hit tag). */ + marker?: React.ReactNode; + /** When provided the row becomes a button that opens the passage. */ + onClick?: () => void; +}) { + const body = ( + <> +
+ + {index + 1} + + + {section.heading || sectionLabel} + + {marker} + + {section.score.toFixed(4)} + +
+
+
+
+

+ {section.content} +

+ + ); + if (!onClick) { + return
{body}
; + } + return ( + + ); +} + +/** 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-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/retrieval-status.test.tsx b/apps/web/components/features/retrieval-status.test.tsx index 4e26019e..fa96ac0f 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,53 @@ describe("retrieval execution status", () => { expect(text).toContain("Partial results"); }); }); + +describe("retrieval mode origin", () => { + const ran = { requested_strategy: "sag2", effective_strategy: "sag2", ranking: { method: "jev", fallback_reason: null } }; + it("says the mode came from the agent persona", async () => { + expect(await render({ ...ran, strategy_origin: "persona" }, "sag2")).toBe("Using SAG2 evidence retrieval (persona default)"); + }); + it("says the mode came from the scoped sources", async () => { + expect(await render({ ...ran, strategy_origin: "source_default" }, "sag2")).toBe("Using SAG2 evidence retrieval (source default)"); + }); + it.each(["request", "global", "unexpected"])("stays silent for a %s origin when the execution is unchanged", async (origin) => { + expect(await render({ ...ran, strategy_origin: origin }, "sag2")).toBe(""); + }); + it("keeps the origin next to a changed execution", async () => { + const text = await render({ requested_strategy: "sag2", effective_strategy: "vector", strategy_origin: "source_default" }, "sag2"); + expect(text).toContain("Using SAG2 evidence retrieval (source default)"); + expect(text).toContain("Requested: SAG2 evidence retrieval"); + expect(text).toContain("Actual: Fast (vector)"); + }); +}); + +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..4d4b8bbb 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,26 @@ 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; +} + +/** + * Origins worth a line of their own: the user did not pick the mode and it is + * not simply the global default, so say where it came from. "request" and + * "global" stay silent unless the execution changed. + */ +const EXPLAINED_ORIGINS = { + persona: "originPersona", + source_default: "originSourceDefault", +} as const; + +function explainedOrigin(value: unknown): keyof typeof EXPLAINED_ORIGINS | null { + return typeof value === "string" && Object.hasOwn(EXPLAINED_ORIGINS, value) + ? value as keyof typeof EXPLAINED_ORIGINS + : null; +} + /** Explain execution changes without treating same-profile coarse ranking as JEV success. */ export function RetrievalStatus({ stats, requestedStrategy }: { stats: Record; @@ -19,19 +44,40 @@ 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; + 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; 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) })}

} + {origin && originMode &&

{t("origin", { mode: label(originMode), origin: t(EXPLAINED_ORIGINS[origin]) })}

} + {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/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-strategy-control.test.tsx b/apps/web/components/features/search-strategy-control.test.tsx new file mode 100644 index 00000000..960ddd12 --- /dev/null +++ b/apps/web/components/features/search-strategy-control.test.tsx @@ -0,0 +1,94 @@ +/** @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", hint?: string) { + 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("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"); + 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..ca5453e3 100644 --- a/apps/web/components/features/search-strategy-control.tsx +++ b/apps/web/components/features/search-strategy-control.tsx @@ -1,8 +1,9 @@ "use client"; -import { Check, ChevronDown, ShieldQuestion, Sparkles, Zap } from "lucide-react"; +import { Check, ChevronDown, Settings2 } from "lucide-react"; import { useTranslations } from "next-intl"; -import type { ComponentType } from "react"; +import Link from "next/link"; +import { Fragment } from "react"; import { DropdownMenu, @@ -20,23 +21,28 @@ import { import { cn } from "@/lib/utils"; import { getSearchStrategy, + 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, -}; +/** 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, onValueChange, disabledMap, + hint, + disabled, }: { value: SearchStrategy; defaultValue: SearchStrategy; @@ -46,38 +52,52 @@ 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; + /** Lock the control while a request is in flight, like the toolbar toggles around it. */ + disabled?: boolean; }) { const t = useTranslations("SearchStrategies"); const currentStrategy = getSearchStrategy(value); - const CurrentIcon = STRATEGY_ICONS[currentStrategy.value]; + const CurrentIcon = SEARCH_STRATEGY_ICONS[currentStrategy.value]; return ( - + - + {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); 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 +115,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 +137,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/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 4983783d..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 { @@ -120,6 +135,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; @@ -134,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: { @@ -166,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], @@ -269,8 +353,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({ @@ -283,6 +369,10 @@ export function SearchPanel({ async function run(e?: React.FormEvent) { e?.preventDefault(); + if (compare.enabled) { + await runCompare(); + return; + } await executeSearch({ saveExploration: false, }); @@ -298,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], @@ -325,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(); @@ -435,12 +529,26 @@ export function SearchPanel({ )} - + + + {t("compare")} + + {!compare.enabled && ( + + )}
{mentionOpen && (
@@ -486,6 +594,7 @@ export function SearchPanel({ type="button" onClick={() => { search.cancel(); + compare.cancel(); onSearchCancel?.(); onCancel?.(); }} @@ -495,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 && ( @@ -512,7 +678,7 @@ export function SearchPanel({ {t("history")} @@ -520,7 +686,7 @@ export function SearchPanel({ {t("recentActivity")} @@ -529,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/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/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/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-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..0fafb70a 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 { @@ -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), @@ -1020,7 +1025,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/conversation-runtime.test.ts b/apps/web/lib/conversation-runtime.test.ts index 7e4ac9d3..6564229a 100644 --- a/apps/web/lib/conversation-runtime.test.ts +++ b/apps/web/lib/conversation-runtime.test.ts @@ -122,7 +122,7 @@ class FakeTransport implements ConversationTransport { readonly deleteCalls: string[] = []; readonly historyPages: MessagePage[] = []; readonly historyCursors: Array = []; - readonly streamCalls: Array<{ webEnabled: boolean; knowledgeOnly?: boolean; sourceIds?: string[] }> = []; + readonly streamCalls: Array<{ webEnabled: boolean; knowledgeOnly?: boolean; sourceIds?: string[]; strategy?: string }> = []; approvalResult: Promise | null = null; onEvent: ((event: AgentEvent) => void) | null = null; streamSignal: AbortSignal | null = null; @@ -143,6 +143,7 @@ class FakeTransport implements ConversationTransport { webEnabled: input.webEnabled, knowledgeOnly: input.knowledgeOnly, sourceIds: input.sourceIds, + strategy: input.strategy, }); this.onEvent = input.onEvent; this.streamSignal = input.signal; @@ -190,6 +191,7 @@ class SequentialTransport extends FakeTransport { webEnabled: input.webEnabled, knowledgeOnly: input.knowledgeOnly, sourceIds: input.sourceIds, + strategy: input.strategy, }); this.onEvent = input.onEvent; this.streamSignal = input.signal; @@ -569,6 +571,21 @@ describe("conversation runtime", () => { ]); }); + it("forwards a pinned retrieval mode and omits it when nothing is pinned", async () => { + const transport = new FakeTransport(); + const conversations = runtime(transport); + const sessionId = conversations.forThread("thread-1", { activate: true }); + + const first = conversations.send(sessionId, { query: "按 SAG2 检索", strategy: "sag2" }); + expect(transport.streamCalls[0].strategy).toBe("sag2"); + transport.streamResult.resolve({ status: "completed", runId: "run-1" }); + await first; + + await conversations.send(sessionId, { query: "跟随默认模式" }); + expect(transport.streamCalls[1]).not.toHaveProperty("strategy", expect.anything()); + expect(transport.streamCalls[1].strategy).toBeUndefined(); + }); + it("replaces buffered stream text with the canonical terminal answer and citations", async () => { vi.useFakeTimers(); const transport = new FakeTransport(); diff --git a/apps/web/lib/conversation-runtime.ts b/apps/web/lib/conversation-runtime.ts index dcbf7ca4..3285a1a5 100644 --- a/apps/web/lib/conversation-runtime.ts +++ b/apps/web/lib/conversation-runtime.ts @@ -6,6 +6,7 @@ import { settleActiveSteps, type LiveStep, } from "./agent-run-activity"; +import type { SearchStrategy } from "./retrieval-config"; import type { AgentEvent, AgentRunOutcome } from "./sse"; import { clientErrorMessage } from "../i18n/client-errors"; import type { @@ -41,6 +42,8 @@ export interface ConversationTransport { sourceIds?: string[]; knowledgeOnly?: boolean; webEnabled: boolean; + /** Explicit per-turn retrieval mode; omitted when the backend should resolve it. */ + strategy?: SearchStrategy; onEvent: (event: AgentEvent) => void; signal: AbortSignal; }): Promise; @@ -148,6 +151,8 @@ export interface ConversationSendInput { sourceScope?: MessageSourceScope[]; knowledgeOnly?: boolean; webEnabled?: boolean; + /** Retrieval mode pinned by the user for this turn; leave undefined to let the backend resolve it. */ + strategy?: SearchStrategy; title?: string; } @@ -657,6 +662,7 @@ export class ConversationRuntime { sourceIds: sourceScope.length ? sourceScope.map((source) => source.id) : undefined, knowledgeOnly: input.knowledgeOnly, webEnabled: input.webEnabled === true, + strategy: input.strategy, onEvent: (event) => this.handleEvent(operation, event), signal: controller.signal, }); 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 24a0aea1..e81d9e71 100644 --- a/apps/web/lib/retrieval-config.test.ts +++ b/apps/web/lib/retrieval-config.test.ts @@ -1,5 +1,17 @@ import { describe, expect, it } from "vitest"; -import { isSearchStrategy, getSearchStrategiesDisabled } from "./retrieval-config"; +import { + getScopeDefaultStrategy, + getSearchStrategiesDisabled, + isJevConfigDisabledReason, + isJevScoredStrategy, + isSearchStrategy, + isSearchStrategyRejectionCode, + JEV_SCORED_STRATEGIES, + needsJevQuickSetup, + SEARCH_STRATEGIES, + SEARCH_STRATEGY_ICONS, + SEARCH_STRATEGY_REQUIREMENTS, +} from "./retrieval-config"; describe("JEV strategy availability", () => { it("accepts JEV as a request strategy", () => { @@ -19,4 +31,83 @@ 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); + }); +}); + +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("recognises the ask rejections that mean the chosen mode cannot be served", () => { + for (const code of ["jev_not_configured", "jev_api_key_missing", "vector_provider_lacks_lexical", "sag2_relational_unsupported"]) { + expect(isSearchStrategyRejectionCode(code)).toBe(true); + } + expect(isSearchStrategyRejectionCode("stream_error")).toBe(false); + expect(isSearchStrategyRejectionCode(undefined)).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 b4bb41f2..af5b2bdf 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", @@ -19,12 +27,26 @@ export const SEARCH_STRATEGIES = [ labelKey: "multiJevLabel", descriptionKey: "multiJevDescription", }, + { + value: "sag2", + labelKey: "sag2Label", + descriptionKey: "sag2Description", + }, ] as const; 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 是权威来源; @@ -35,8 +57,47 @@ 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); +} + +/** + * Error codes the ask endpoint returns (HTTP 400, before streaming) when the + * requested mode cannot be served by this deployment. They mirror the reasons + * in `search_strategies_disabled`, so the UI treats them the same way. + */ +export const SEARCH_STRATEGY_REJECTION_CODES = [ + ...JEV_CONFIG_DISABLED_REASONS, + "vector_provider_lacks_lexical", + "sag2_relational_unsupported", +] as const; + +export function isSearchStrategyRejectionCode(code: unknown): boolean { + return SEARCH_STRATEGY_REJECTION_CODES.some((candidate) => candidate === code); +} + export function isSearchStrategy(value: unknown): value is SearchStrategy { return ( typeof value === "string" && @@ -70,12 +131,46 @@ 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; } + +/** + * 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/sse.test.ts b/apps/web/lib/sse.test.ts index 059482e5..94d6811a 100644 --- a/apps/web/lib/sse.test.ts +++ b/apps/web/lib/sse.test.ts @@ -40,4 +40,17 @@ describe("agent ask transport", () => { web_enabled: webEnabled, }); }); + + it("sends the retrieval mode only when the caller pinned one", async () => { + const fetchMock = vi.fn().mockResolvedValue(completedResponse()); + vi.stubGlobal("fetch", fetchMock); + + await streamAgentAsk("agent-1", "thread-1", { query: "问", web_enabled: false, strategy: "sag2" }, vi.fn()); + fetchMock.mockResolvedValue(completedResponse()); + await streamAgentAsk("agent-1", "thread-1", { query: "问", web_enabled: false }, vi.fn()); + + const bodies = fetchMock.mock.calls.map((call) => JSON.parse(String((call[1] as RequestInit).body))); + expect(bodies[0]).toMatchObject({ strategy: "sag2" }); + expect(bodies[1]).not.toHaveProperty("strategy"); + }); }); diff --git a/apps/web/lib/sse.ts b/apps/web/lib/sse.ts index aec19bde..c011411f 100644 --- a/apps/web/lib/sse.ts +++ b/apps/web/lib/sse.ts @@ -1,6 +1,7 @@ import { API_BASE } from "./api"; import { getToken } from "./auth"; import { getDiagnosticsStore } from "./diagnostics"; +import type { SearchStrategy } from "./retrieval-config"; import { readClientLocale } from "../i18n/client"; import { clientErrorMessage, serverErrorMessage } from "../i18n/client-errors"; @@ -240,6 +241,8 @@ export function streamAgentAsk( source_ids?: string[]; knowledge_only?: boolean; web_enabled: boolean; + /** Only present when the user explicitly picked a mode for this turn. */ + strategy?: SearchStrategy; }, onEvent: (event: AgentEvent) => void, signal?: AbortSignal, diff --git a/apps/web/lib/types.ts b/apps/web/lib/types.ts index 801d4d0a..cd8b36f6 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; @@ -174,6 +180,8 @@ export interface Persona { system_prompt?: string; greeting?: string; tools?: string[]; + /** Retrieval mode this agent asks with unless the user picks one per turn. */ + search_strategy?: SearchStrategy; } export interface ActivityItem { diff --git a/apps/web/messages/en-US.json b/apps/web/messages/en-US.json index ef95ade4..38266835 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" }, @@ -613,7 +613,52 @@ "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." + }, + "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", + "personaDefaultHint": "Persona 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", @@ -680,8 +725,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 +737,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 +752,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", @@ -1124,7 +1172,8 @@ "reject": "Reject", "allowOnce": "Allow once", "thinking": "Thinking…", - "sessionMissing": "Conversation runtime session not found: {id}" + "sessionMissing": "Conversation runtime session not found: {id}", + "dismissNotice": "Dismiss notice" }, "Citations": { "visitExternal": "Visit external source: {title}", @@ -1254,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", @@ -1767,7 +1835,12 @@ "actual": "Actual: {mode}", "coarse": "Coarse ranking", "jevFallback": "JEV reranking did not complete; these results include coarse ranking.", - "partial": "Partial results: some sources did not complete." + "jevUsage": "JEV scoring this run: {requests} requests · {judgments} judgments{tokens}", + "jevUsageTokens": " · {tokens} input tokens", + "partial": "Partial results: some sources did not complete.", + "origin": "Using {mode} ({origin})", + "originPersona": "persona default", + "originSourceDefault": "source default" }, "ClientAccess": { "title": "CLI and automation", diff --git a/apps/web/messages/zh-CN.json b/apps/web/messages/zh-CN.json index 633aa268..1f241476 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": "保存修改" }, @@ -613,7 +613,52 @@ "disabledSuffix": "(不可用)", "multiJevLabel": "JEV 精排", "multiJevDescription": "扩展关联证据后,使用配置的 JEV 服务评分相关性。", - "unsupportedBackend": "当前服务端未声明支持 JEV,请升级服务端后使用此模式。" + "sag2Label": "SAG2 证据检索", + "sag2Description": "BM25 召回后由 JEV 服务多轮评分,不依赖向量库;付费服务。", + "paid": "付费", + "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": "信源默认", + "personaDefaultHint": "人格默认", + "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": "检索失败", @@ -680,8 +725,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 +737,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 +752,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": "重试", @@ -1124,7 +1172,8 @@ "reject": "拒绝", "allowOnce": "允许一次", "thinking": "正在思考…", - "sessionMissing": "对话运行实例不存在:{id}" + "sessionMissing": "对话运行实例不存在:{id}", + "dismissNotice": "关闭提示" }, "Citations": { "visitExternal": "访问外部来源:{title}", @@ -1254,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": "图谱布局", @@ -1767,7 +1835,12 @@ "actual": "实际模式:{mode}", "coarse": "粗排", "jevFallback": "本次未完成 JEV 精排,已返回粗排结果。", - "partial": "部分结果:部分信源未完成检索。" + "jevUsage": "本次 JEV 评分:{requests} 次请求 · {judgments} 次判定{tokens}", + "jevUsageTokens": " · {tokens} 输入 token", + "partial": "部分结果:部分信源未完成检索。", + "origin": "按{origin}使用 {mode}", + "originPersona": "人格默认", + "originSourceDefault": "信源默认" }, "ClientAccess": { "title": "CLI 与自动化",