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..3d51d317 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,13 @@ ## Unreleased +- 探索页新增「对比」:同一问题在 2–3 种检索模式下并排检索,显示耗时、召回数、SAG2 的 JEV 用量与共同命中的片段,可选 LLM 评审,并可一键按某一模式正式检索。 +- 信源创建时固定选择「事件检索(SAG1)」或「证据检索(SAG2)」,创建后不可切换;已有信源保留 SAG1。SAG1 上传保留实体/事项抽取,SAG2 上传只解析、分块、建立原生索引。 +- 搜索与问答默认按各知识库算法自动召回,混合范围合并去重,部分失败明确提示;显式具体模式只检索同算法的信源。问答工具栏仍支持按轮选择,探索页支持模式对比。 +- 搜索/问答选择未配置的付费 JEV 模式时打开配置弹窗,保存成功后才切换;取消保留原模式与输入。创建 SAG2 信源和上传不需要 JEV Key。 +- SAG2 原生持久化索引支持 SQLite / PostgreSQL,检索在专用线程执行,只扫描所选已发布文档;SQLite 使用独立 sag2.db,PostgreSQL 使用独立 sag2 schema,不修改 SAG1 表。OCTX 当前仅支持 SAG1,SAG2 导出与导入覆盖均禁用。 +- 后端中文分词依赖由 `jieba-py` 改回 `jieba` 0.42.1,与 `zleap-sag2` 共用一份词典;分词结果不变。 + ## v1.9.2 · 2026-10-22 - 新增结构化输出模式设置和自动降级,兼容不支持严格结构化输出的模型;改善口语化提问的查询分析与语义结果保留(#248)。 diff --git a/README-CN.md b/README-CN.md index ca630588..9ec38bb3 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,19 @@ 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 秒、失败报错,可选择粗排降级。 +创建信源时只选择两种固定算法:**事件检索(SAG1)**(默认)或 **证据检索(SAG2)**,创建后不可编辑切换。SAG1 后续上传沿用原有解析、分块、向量化和实体/事项提取;SAG2 后续上传只解析、分块并建立原文索引,不调用抽取或向量模型。已有信源统一保留 SAG1,既有数据无需重建。OCTX 导入/导出目前仅支持 SAG1,SAG2 不允许导出或被 OCTX 覆盖。 -支持 LanceDB、Elasticsearch,暂不支持 pgvector;PostgreSQL 作为关系库不受影响。未启用时沿用原检索策略,已有文档无需重新入库。效果与成本见[更新日志](CHANGELOG.md#jev-reranking)。 +搜索和问答默认使用**自动(按知识库算法)**:SAG1 按设置页的 SAG1 检索策略召回,SAG2 按证据检索召回,混合范围合并、去重后回答;某一算法失败会明确提示结果不完整。显式选择 SAG1 子模式只检索 SAG1 信源,选择 SAG2 只检索 SAG2 信源;Agent 人格中的显式策略也遵循此限制。探索页仍可并排对比 2–3 种具体模式。 + +在“设置 → 知识库 → 检索”配置 302.AI、TypeSafe 官方或自定义 JEV 服务(默认 `jev-latest`,独立 API Key)。JEV 精排和 SAG2 检索共用此服务:搜索/问答选择缺少配置的付费模式时打开配置弹窗,保存成功后才切换,取消保留当前模式和输入。创建 SAG2 信源及上传建索引不要求 JEV Key。JEV 精排默认限时 30 秒、失败报错,可选择粗排降级;SAG2 失败不降级。 + +**SAG2** 使用独立的 `zleap-sag2` 原生持久化索引,支持 SQLite / PostgreSQL(首期不支持 MySQL / OceanBase),BM25 召回后多轮调用 JEV 评分,不依赖向量库。仅已发布的所选文档进入检索范围和扫描计数。SQLite 数据位于引擎目录的 `sag2.db`;PostgreSQL 使用原数据库的独立 `sag2` schema,连接用户需有创建 schema 和其中表的权限。SAG1 数据表保持原样。候选数、超时、并发与范围上限等参数见 `apps/api/.env.example` 的 `SAG_SAG2_*`。 + +JEV 精排支持 LanceDB、Elasticsearch,暂不支持 pgvector;PostgreSQL 作为关系库不受影响。未启用时沿用原检索策略,已有文档无需重新入库。效果与成本见[更新日志](CHANGELOG.md#jev-reranking)。 #### 存储后端 diff --git a/README.md b/README.md index 01dc29af..4cc752c9 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,19 @@ 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` | Native-index search by [zleap-sag2](https://pypi.org/project/zleap-sag2/) over the relational store: BM25 recall scored over several JEV rounds, no vector store involved | -These are the application/API strategy names; the application maps `multi` to the Python engine's `full_expand` and `multi_es_fast` to `pruned_expand_rff`. 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. +Create each source with one immutable algorithm: **Event retrieval (SAG1)** (default) or **Evidence retrieval (SAG2)**. SAG1 uploads retain parsing, chunking, embeddings and entity/event extraction. SAG2 uploads only parse, chunk and build native text indexes, without extraction or embeddings. Existing sources stay on SAG1 without rebuilding. OCTX import/export remains SAG1-only; SAG2 export and OCTX overwrite are rejected. -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). +Search and chat default to **Automatic (by knowledge-base algorithm)**: SAG1 uses the SAG1 retrieval profile from Settings, SAG2 uses evidence retrieval, and mixed scopes merge and deduplicate both groups before answering. Partial failures explicitly identify the missing algorithm. Selecting a concrete SAG1 profile restricts retrieval to SAG1 sources; selecting SAG2 restricts it to SAG2 sources. Explicit agent-persona strategies follow the same scope rule. Explore still compares two or three concrete modes side by side. + +Configure 302.AI, TypeSafe, or a custom JEV service in **Settings → Knowledge → Retrieval** (default model: `jev-latest`, separate API key). JEV reranking and SAG2 retrieval share this paid service. Selecting an unconfigured paid mode in search/chat opens a configuration dialog; only a successful save activates the mode. Cancel preserves the current mode and input. Creating or indexing a SAG2 source needs no JEV key. JEV reranking has a 30-second default deadline and optional coarse fallback; SAG2 never falls back. + +**SAG2** uses separate durable native `zleap-sag2` indexes on SQLite or PostgreSQL (MySQL and OceanBase are not supported), BM25 recall and multiple JEV scoring rounds, without a vector store. Retrieval and scope counting include only selected, published inputs. SQLite uses `sag2.db` in the engine data directory; PostgreSQL uses a separate `sag2` schema in the configured database, requiring permission to create the schema and its tables. SAG1 tables remain unchanged. Tuning parameters are documented as `SAG_SAG2_*` in `apps/api/.env.example`. + +JEV reranking is supported on LanceDB and Elasticsearch; pgvector is currently unsupported. PostgreSQL relational storage can use JEV with a supported vector backend. Existing retrieval settings remain until a JEV mode is selected; documents do not need reindexing. See the [benchmark results and cost estimates](CHANGELOG.md#jev-reranking). #### Storage backends diff --git a/apps/api/.env.example b/apps/api/.env.example index 4da32826..ad7acec9 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),创建后算法不可更改;搜索/问答默认按算法自动召回。 +# 检索共用上面的 JEV 服务地址、模型与 API Key(付费);创建和上传建索引无需 JEV Key。 +# 原生索引使用独立 SQLite sag2.db / PostgreSQL sag2 schema,不向量化或抽取实体事项;检索失败不回退, +# SAG_JEV_FAILURE_POLICY 对其无效。以下调优参数首期只经环境变量设置,默认值已控制用量。 +# SAG_SAG2_CANDIDATE_K=50 # BM25 候选数(zleap-sag2 默认 100) +# SAG_SAG2_SEED_K=10 # 每轮扩展种子数 +# 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..627a030a 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,21 @@ 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 or (strategy == "auto" and ( + configuration.search_strategy == "multi_jev" + or any(getattr(source, "engine_kind", "sag1") == "sag2" for source in sources) + )): outcome = await retrieval return outcome, event_scores_from_evidence(outcome.sections), True outcome, scores = await asyncio.gather( diff --git a/apps/api/sag_api/core/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..c0e0dcfb 100644 --- a/apps/api/sag_api/core/db.py +++ b/apps/api/sag_api/core/db.py @@ -60,6 +60,10 @@ async def get_session() -> AsyncIterator[AsyncSession]: # create_all 只建新表、不改旧表,故对演进列做幂等 ADD COLUMN。 _COLUMN_UPGRADES: dict[str, dict[str, str]] = { "agents": {"is_default": "BOOLEAN NOT NULL DEFAULT FALSE"}, + "sources": { + "default_search_strategy": "VARCHAR(32)", + "engine_kind": "VARCHAR(16) NOT NULL DEFAULT 'sag1'", + }, "documents": { "progress": "INTEGER NOT NULL DEFAULT 0", "processing_stage": "VARCHAR(32)", diff --git a/apps/api/sag_api/db/models/source.py b/apps/api/sag_api/db/models/source.py index d917c91b..a15a16d2 100644 --- a/apps/api/sag_api/db/models/source.py +++ b/apps/api/sag_api/db/models/source.py @@ -14,6 +14,9 @@ class Source(IDMixin, TimestampMixin, Base): __tablename__ = "sources" + # Immutable ingestion/retrieval engine; historical sources are always SAG1. + engine_kind: Mapped[str] = mapped_column(String(16), default="sag1", server_default="sag1") + name: Mapped[str] = mapped_column(String(200)) description: Mapped[str] = mapped_column(Text, default="") source_type: Mapped[SourceType] = mapped_column( @@ -33,6 +36,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..ef22d6b5 100644 --- a/apps/api/sag_api/enums.py +++ b/apps/api/sag_api/enums.py @@ -5,15 +5,21 @@ 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["auto", "vector", "multi", "multi_es_fast", "multi_jev", "sag2"] +SEARCH_STRATEGIES = frozenset({"auto", "vector", "multi", "multi_es_fast", "multi_jev", "sag2"}) +# 由付费 JEV 决策服务评分的模式:选择前必须保存服务地址与 API Key,失败不回退 vector, +# 业务层保留引擎给出的证据顺序。 +JEV_SCORED_STRATEGIES = frozenset({"multi_jev", "sag2"}) # 策略对底层引擎能力的依赖。缺失能力的部署会在 UI 灰置该选项;后端调用则拒绝。 +# jev:已保存 JEV 服务地址与 API Key;sag2_relational:zleap-sag2 首期只读 SQLite / PostgreSQL 关系库。 SEARCH_STRATEGY_REQUIREMENTS: dict[str, frozenset[str]] = { + "auto": frozenset(), "vector": frozenset(), "multi": frozenset(), "multi_es_fast": frozenset({"lexical_search"}), "multi_jev": frozenset({"lexical_search", "jev"}), + "sag2": frozenset({"jev", "sag2_relational"}), } diff --git a/apps/api/sag_api/jobs/tasks.py b/apps/api/sag_api/jobs/tasks.py index 3eee5539..6141d304 100644 --- a/apps/api/sag_api/jobs/tasks.py +++ b/apps/api/sag_api/jobs/tasks.py @@ -545,6 +545,7 @@ async def bind_request(processor, config, runtime_settings) -> ProcessSourceRequ runtime_settings, source.sag_source_config_id, input_path, + **({"engine_kind": "sag2"} if getattr(source, "engine_kind", "sag1") == "sag2" else {}), ) except OSError: raise DocumentRestartRequiredError("resume_input_unavailable") from None @@ -632,6 +633,7 @@ async def bind_request(processor, config, runtime_settings) -> ProcessSourceRequ runtime_settings, source.sag_source_config_id, input_path, + **({"engine_kind": "sag2"} if getattr(source, "engine_kind", "sag1") == "sag2" else {}), ) reason = processing_identity_restart_reason(identity, current) if reason or candidate.source.original_sha256 != identity["original_sha256"]: @@ -664,7 +666,8 @@ async def bind_request(processor, config, runtime_settings) -> ProcessSourceRequ "process_request": candidate.model_dump(mode="json"), "processing_identity": identity, "control_revision": control_revision, - "vector_identity": configured_embedding_identity(runtime_settings), + "vector_identity": (None if getattr(source, "engine_kind", "sag1") == "sag2" + else configured_embedding_identity(runtime_settings)), } ) .execution_options(synchronize_session=False) diff --git a/apps/api/sag_api/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/document_identity.py b/apps/api/sag_api/sag/document_identity.py index f801e5d9..c7d119e9 100644 --- a/apps/api/sag_api/sag/document_identity.py +++ b/apps/api/sag_api/sag/document_identity.py @@ -120,9 +120,21 @@ def _responses_identity(settings: Settings) -> dict | None: async def document_processing_identity( - config: EngineConfig, settings: Settings, source_config_id: str, path: str, + config: EngineConfig, settings: Settings, source_config_id: str, path: str, *, engine_kind: str = "sag1", ) -> dict[str, str]: raw = await asyncio.to_thread(_input_identity, path) + if engine_kind == "sag2": + return { + "configuration_digest": _digest({ + "engine_kind": "sag2", "parser": document_parser_identity(path, settings), + "chunking": {"strategy": "standard", "max_tokens": settings.document_chunk_max_tokens}, + "storage": {"data_dir": str(Path(settings.data_dir).resolve()), + "relational_provider": settings.sag_relational_provider, + "pg_host": settings.sag_pg_host, "pg_port": settings.sag_pg_port, + "pg_database": settings.sag_pg_database, "pg_user": settings.sag_pg_user}, + }), + "input_digest": _digest(raw), "original_sha256": raw["sha256"], + } entity_contract = await _entity_contract(config, source_config_id) return { "configuration_digest": _digest({ diff --git a/apps/api/sag_api/sag/engine_access.py b/apps/api/sag_api/sag/engine_access.py index fa01e85c..8c5d1cbb 100644 --- a/apps/api/sag_api/sag/engine_access.py +++ b/apps/api/sag_api/sag/engine_access.py @@ -40,7 +40,7 @@ def _shared_slot(self, source_config_id: str, source: Any = None) -> Any: return None wanted = manager._config_for(source) for slot in manager._slots.values(): - if slot.closing: + if slot.closing or not hasattr(slot.engine, "_config"): continue actual = slot.engine._config if (actual.relational, actual.vector, actual.embedding) == ( @@ -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..1235c16f 100644 --- a/apps/api/sag_api/sag/engine_manager.py +++ b/apps/api/sag_api/sag/engine_manager.py @@ -13,7 +13,7 @@ from collections.abc import Awaitable, Callable from contextlib import asynccontextmanager from dataclasses import dataclass, field -from datetime import datetime +from datetime import UTC, datetime from typing import TYPE_CHECKING, Any from zleap.sag import DataEngine, EngineConfig @@ -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,15 @@ 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 ( + jev_connection_issue, + jev_connection_ready, + sag2_relational_issue, + sag2_relational_supported, +) +from sag_api.sag.sag2_native_search import Sag2NativeSearchHolder +from sag_api.sag.sag2_source_engine import Sag2SourceEngine +from sag_api.sag.search_reader import SearchReader, search_admission_timeout_seconds from sag_api.sag.universe_cursor import ( decode_universe_cursor, encode_universe_cursor, @@ -184,6 +193,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 = Sag2NativeSearchHolder(settings) async def _relational_session_factory(self, source_config_id: str, source: Source | None = None) -> Any: """0.8.2 起 zleap 无全局会话工厂;经引擎注入的 RelationalStore 访问关系库。""" @@ -327,26 +338,35 @@ def create_missing(sync_connection) -> None: # noqa: ANN001 def _vector_provider_supports_lexical(self) -> bool: return self._VECTOR_PROVIDER_LEXICAL_SUPPORT.get(self._settings.sag_vector_provider, False) - def _strategy_missing_capabilities(self, strategy: str) -> tuple[str, ...]: + # 缺失能力的报告顺序:存储层能力先于服务配置,前端只展示第一个原因。 + _CAPABILITY_ORDER: tuple[str, ...] = ("lexical_search", "sag2_relational", "jev") + + @classmethod + def _missing_capabilities(cls, settings: Settings, strategy: str) -> tuple[str, ...]: requirements = SEARCH_STRATEGY_REQUIREMENTS.get(strategy, frozenset()) + supports_lexical = cls._VECTOR_PROVIDER_LEXICAL_SUPPORT.get(settings.sag_vector_provider, False) missing: list[str] = [] - for capability in requirements: - if capability == "lexical_search" and not self._vector_provider_supports_lexical(): + for capability in sorted(requirements, key=cls._CAPABILITY_ORDER.index): + if capability == "lexical_search" and not supports_lexical: + missing.append(capability) + elif capability == "jev" and not jev_connection_ready(settings): missing.append(capability) - elif capability == "jev" and not self._settings.jev_endpoint: + elif capability == "sag2_relational" and not sag2_relational_supported(settings): missing.append(capability) return tuple(missing) + def _strategy_missing_capabilities(self, strategy: str) -> tuple[str, ...]: + return self._missing_capabilities(self._settings, strategy) + def _effective_search_strategy(self, requested: str | None) -> str: """校验请求的门面策略。未识别或能力不满足时按配置策略回退,再兜底 vector。""" raw = requested or self._settings.search_strategy strategy = normalize_search_strategy(raw) - if strategy == "multi_jev": + if strategy in JEV_SCORED_STRATEGIES: missing = self._strategy_missing_capabilities(strategy) if missing: # Explicit/default JEV selection must never silently change mode. - capability = "lexical_search" if "lexical_search" in missing else "jev" - reason, message = self._capability_disabled_reason(capability, self._settings.sag_vector_provider) + reason, message = self._capability_disabled_reason(missing[0], self._settings) raise ConfigurationError(message, code=reason, stage=ErrorStage.RETRIEVE) return strategy if strategy in SEARCH_STRATEGIES: @@ -373,15 +393,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 +412,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: @@ -440,7 +457,10 @@ async def document_processing_identity( overrides = (source.config or {}).get("engine") if source is not None else None with map_sag_errors(stage=ErrorStage.CONFIG): config = build_engine_config(settings, overrides=overrides) - return await document_processing_identity(config, settings, source_config_id, path) + return await document_processing_identity( + config, settings, source_config_id, path, + **({"engine_kind": "sag2"} if getattr(source, "engine_kind", "sag1") == "sag2" else {}), + ) async def _ensure_engine_schema(self, engine: DataEngine) -> None: if self._schema_ready: @@ -537,6 +557,13 @@ async def _slot(self, source_config_id: str, source: Source | None = None) -> _S async with self._lifecycle_gate.write(): log.info("构造引擎 source_config_id=%s", source_config_id) config = self._config_for(source) + if getattr(source, "engine_kind", "sag1") == "sag2": + engine = Sag2SourceEngine(self._settings, source_config_id) + await engine.start() + slot = _Slot(engine=engine, config=config) + self._slots[source_config_id] = slot + await self._evict_lru(keep=source_config_id) + return slot engine = DataEngine( config, data_source_id=source_config_id, @@ -821,6 +848,7 @@ async def never_pause() -> bool: engine, source_config_id, max_concurrency=frozen.document_extract_concurrency, + language=frozen.sag_language if isinstance(engine, Sag2SourceEngine) else None, chunk_max_tokens=frozen.document_chunk_max_tokens, chunk_mode=frozen.document_chunk_mode, document_title=document_title, @@ -890,10 +918,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 +936,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]], @@ -936,6 +980,10 @@ async def search_event_scores( limit: int | None = None, source_ids_by_config: dict[str, tuple[str, ...]] | None = None, ) -> dict[tuple[str, str], float]: + sources_by_config = {key: source for key, source in sources_by_config.items() + if getattr(source, "engine_kind", "sag1") != "sag2"} + if not sources_by_config: + return {} return await self._search.search_event_scores( query, sources_by_config, limit=limit, source_ids_by_config=source_ids_by_config ) @@ -949,6 +997,8 @@ async def universe_overview_stats( bucket_count: int = 8, category_limit: int = 8, ) -> UniverseSourceStatsInfo: + if getattr(source, "engine_kind", "sag1") == "sag2": + return UniverseSourceStatsInfo() return await self._universe.universe_overview_stats( source_config_id, source_ids=source_ids, @@ -997,6 +1047,8 @@ async def universe_timeline( cursor: str | None = None, snapshot_id: str | None = None, ) -> UniverseTimelineInfo: + if getattr(source, "engine_kind", "sag1") == "sag2": + return UniverseTimelineInfo(snapshot_id=source_revision, direction=direction, as_of=datetime.now(UTC)) return await self._universe.universe_timeline( source_config_id, source_ids=source_ids, @@ -1024,6 +1076,8 @@ async def universe_expand( after: datetime | None = None, before: datetime | None = None, ) -> UniverseExpansionInfo | None: + if getattr(source, "engine_kind", "sag1") == "sag2": + return None return await self._universe.universe_expand( source_config_id, node_kind, @@ -1047,6 +1101,8 @@ async def universe_node_detail( source_ids: tuple[str, ...], source: Source | None = None, ) -> dict[str, Any] | None: + if getattr(source, "engine_kind", "sag1") == "sag2": + return None return await self._universe.universe_node_detail( source_config_id, node_kind, node_id, source_ids=source_ids, source=source ) @@ -1062,6 +1118,10 @@ async def graph_for_sections( edge_limit: int = 96, event_scores: dict[tuple[str, str], float] | None = None, ) -> SourceGraphInfo: + sections = [section for section in sections + if getattr(sources_by_config.get(section.source_config_id), "engine_kind", "sag1") != "sag2"] + if not sections and not event_scores: + return SourceGraphInfo() return await self._content.graph_for_sections( sections, sources_by_config, @@ -1081,6 +1141,8 @@ async def list_entities( types: list[str] | None = None, limit: int = 100, ) -> list[EntityInfo]: + if getattr(source, "engine_kind", "sag1") == "sag2": + return [] return await self._content.list_entities( source_config_id, source_ids=source_ids, source=source, types=types, limit=limit ) @@ -1095,6 +1157,8 @@ async def source_graph( entity_limit: int = 1_000, expected_event_count: int | None = None, ) -> SourceGraphInfo: + if getattr(source, "engine_kind", "sag1") == "sag2": + return SourceGraphInfo() return await self._content.source_graph( source_config_id, source_ids, @@ -1125,6 +1189,11 @@ async def list_chunk_headings( doc_sag_id: str | None = None, limit: int = 300, ) -> list[dict]: + if getattr(source, "engine_kind", "sag1") == "sag2": + slot = await self._slot(source_config_id, source) + rows = await slot.engine.rows((doc_sag_id,) if doc_sag_id else ()) + return [{"chunk_id": row["chunk_id"], "heading": row.get("heading") or "", + "rank": int(row.get("_rank") or 0)} for row in rows[:limit]] return await self._content.list_chunk_headings( source_config_id, source=source, doc_sag_id=doc_sag_id, limit=limit ) @@ -1136,6 +1205,14 @@ async def get_document_markdown( *, source: Source | None = None, ) -> str | None: + if getattr(source, "engine_kind", "sag1") == "sag2": + slot = await self._slot(source_config_id, source) + rows = await slot.engine.rows((article_id,)) + if not rows: + return None + return rows[0].get("metadata", {}).get("original_text") or "\n\n".join( + str(row.get("content") or "") for row in rows + ) return await self._content.get_document_markdown(source_config_id, article_id, source=source) async def grep_chunks( @@ -1147,6 +1224,21 @@ async def grep_chunks( limit: int = 20, source_ids: tuple[str, ...] | None = None, ) -> list[dict]: + if getattr(source, "engine_kind", "sag1") == "sag2": + slot = await self._slot(source_config_id, source) + rows = await slot.engine.rows(source_ids or ()) + needle = pattern.casefold() + result = [] + for row in rows: + content = str(row.get("content") or "") + position = content.casefold().find(needle) + if position < 0: + continue + result.append({"chunk_id": row["chunk_id"], "heading": row.get("heading") or "", + "source_id": row["source_id"], "snippet": content[max(0, position - 80):position + 700]}) + if len(result) >= limit: + break + return result return await self._content.grep_chunks( source_config_id, pattern, source=source, limit=limit, source_ids=source_ids ) @@ -1159,6 +1251,14 @@ async def get_chunk( source_ids: tuple[str, ...] | None = None, source: Source | None = None, ): + if getattr(source, "engine_kind", "sag1") == "sag2": + from sag_api.sag.dto import ChunkInfo + slot = await self._slot(source_config_id, source) + for input_id in source_ids or (): + row = await slot.engine.read_chunk(input_id, chunk_id, data_source_id=source_config_id) + if row is not None: + return ChunkInfo(chunk_id=chunk_id, heading=row.heading or "", content=row.content, rank=0) + return None return await self._content.get_chunk(source_config_id, chunk_id, source_ids=source_ids, source=source) async def release(self, source_config_id: str) -> None: @@ -1180,6 +1280,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 +1291,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/incremental_processor.py b/apps/api/sag_api/sag/incremental_processor.py index 9b46b85f..3e89692b 100644 --- a/apps/api/sag_api/sag/incremental_processor.py +++ b/apps/api/sag_api/sag/incremental_processor.py @@ -116,8 +116,10 @@ def __init__( chunk_mode: str = "standard", document_title: str | None = None, max_entities_per_event: int = 20, + language: str | None = None, ) -> None: self._engine = engine + self._language = language self._source_config_id = source_config_id self._max_concurrency = max(1, min(100, max_concurrency)) self._chunk_max_tokens = chunk_max_tokens @@ -138,7 +140,7 @@ async def build_request( content_bytes = await asyncio.to_thread(markdown.read_bytes) original = Path(original_path) if original_path is not None else markdown original_bytes = content_bytes if original == markdown else await asyncio.to_thread(original.read_bytes) - language = self._engine.resources.prompts.language + language = self._language or self._engine.resources.prompts.language return ProcessSourceRequest( context=context.model_copy( update={ diff --git a/apps/api/sag_api/sag/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..d56570a7 --- /dev/null +++ b/apps/api/sag_api/sag/sag2_engine.py @@ -0,0 +1,553 @@ +"""zleap-sag2 只读直搜:共用 JEV 连接,在 SAG 关系库上做 BM25 召回与多轮证据评分。 + +与 ``multi_jev`` 不同,SAG2 不经过每信源的 zleap-sag ``DataEngine``:一个未绑定数据源的 +``zleap.sag2.DataEngine`` 连接同一关系库,识别 ``source_chunk`` 后以只读方式检索, +一次请求覆盖全部目标信源并由引擎给出最终顺序。写入、删除仍由 zleap-sag 管理。 + +首期只支持 SQLite 与 PostgreSQL;直读模式每次检索会扫描所选信源的全部可见段落, +因此这里同时限制并发检索数与信源内实际加载的段落数,排队与扫描都计入整次超时。 + +对 zleap-sag2 内部结构的依赖集中在 ``_sag_schema_present`` 与 ``_count_scope`` 两个 +函数里(``engine.store.engine`` 是其关系库连接);升级 ``zleap-sag2`` 版本时需复核这两处。 + +zleap-sag2 0.1.0 在构建内存语料时会在事件循环线程上同步分词、建倒排表,范围越大阻塞越久。 +为此只读引擎及其全部协程都运行在一个专用线程的事件循环里(``_EngineLoop``), +API 事件循环只负责排队、超时与取消,不被扫描阻塞。 +""" + +from __future__ import annotations + +import asyncio +import threading +import time +from collections.abc import Callable, Coroutine +from pathlib import Path +from typing import TYPE_CHECKING, Any + +from sag_api.core.error_taxonomy import ErrorLayer, ErrorStage +from sag_api.core.errors import ( + ConfigurationError, + ServiceUnavailableError, + UpstreamError, + ValidationError, +) +from sag_api.core.logging import get_logger +from sag_api.sag.dto import RetrievedSection, SearchOutcome +from sag_api.sag.errors import ( + JEV_AUTH_FAILED_MESSAGE, + JEV_REQUEST_REJECTED_MESSAGE, + JEV_UNAVAILABLE_MESSAGE, +) + +if TYPE_CHECKING: + from sag_api.core.config import Settings + from sag_api.db.models import Source + +log = get_logger("sag.sag2") + +SAG2_RELATIONAL_PROVIDERS = frozenset({"sqlite", "postgres"}) +SAG2_STRATEGY = "sag2" +SAG_CHUNK_TABLE = "source_chunk" + + +def relational_provider(settings: Settings) -> str: + return settings.sag_relational_provider or "sqlite" + + +def jev_connection_issue(settings: Settings) -> tuple[str, str] | None: + """JEV 为付费服务:地址与 API Key 都保存后,才允许选择任何 JEV 评分模式。 + + 返回 ``(reason_code, 用户可读文案)``;连接完整时返回 ``None``。 + """ + if not settings.jev_endpoint: + return ("jev_not_configured", "尚未配置 JEV 精排服务,请先保存服务地址。") + if not settings.jev_api_key: + return ("jev_api_key_missing", "JEV 为付费服务,请先在设置中填写 API Key。") + return None + + +def sag2_relational_issue(settings: Settings) -> tuple[str, str] | None: + """SAG2 首期只读 SQLite / PostgreSQL;其他关系库返回不可用原因。""" + provider = relational_provider(settings) + if provider in SAG2_RELATIONAL_PROVIDERS: + return None + return ( + "sag2_relational_unsupported", + f"SAG2 证据检索首期仅支持 SQLite 与 PostgreSQL 关系库,当前为 {provider}。", + ) + + +def jev_connection_ready(settings: Settings) -> bool: + return jev_connection_issue(settings) is None + + +def sag2_relational_supported(settings: Settings) -> bool: + return sag2_relational_issue(settings) is None + + +def _fingerprint(settings: Settings) -> tuple[Any, ...]: + """决定是否需要重建只读引擎的配置子集;检索参数在每次请求时读取,不在此列。""" + return ( + settings.jev_endpoint, + settings.jev_model, + settings.jev_api_key, + relational_provider(settings), + settings.data_dir, + settings.sag_pg_host, + settings.sag_pg_port, + settings.sag_pg_user, + settings.sag_pg_password, + settings.sag_pg_database, + settings.sag2_decision_timeout_seconds, + settings.sag2_decision_max_concurrency, + ) + + +def build_sag2_config(settings: Settings): + """由 SAG 运行时配置装配 zleap-sag2 的 ``EngineConfig``(同一关系库 + 共用 JEV 连接)。""" + from zleap.sag2 import EngineConfig, JevConfig, RelationalConfig + + for issue in (sag2_relational_issue(settings), jev_connection_issue(settings)): + if issue is not None: + code, message = issue + raise ConfigurationError(message, code=code, stage=ErrorStage.RETRIEVE) + if relational_provider(settings) == "sqlite": + # zleap-sag 在 data_dir 下派生同名 SQLite 文件;运行时已把 data_dir 替换为活动目录。 + relational = RelationalConfig(provider="sqlite", path=str(Path(settings.data_dir) / "sag.db")) + else: + relational = RelationalConfig( + provider="postgres", + host=settings.sag_pg_host, + port=settings.sag_pg_port, + user=settings.sag_pg_user, + password=settings.sag_pg_password, + database=settings.sag_pg_database, + ) + jev = JevConfig( + endpoint=settings.jev_endpoint, + model=settings.jev_model, + api_key=settings.jev_api_key, + timeout_seconds=settings.sag2_decision_timeout_seconds, + max_concurrency=settings.sag2_decision_max_concurrency, + ) + return EngineConfig(relational=relational, jev=jev) + + +def _base_stats(*, sources: int, requested_sources: int, source_limit_applied: bool, candidates: int) -> dict[str, Any]: + """所有 SAG2 结果共有的 stats 字段;SAG2 没有粗排降级,``fallback_used`` 恒为 False。""" + return { + "sources": sources, + "sources_requested": requested_sources, + "source_limit_applied": source_limit_applied, + "candidates": candidates, + "requested_strategy": SAG2_STRATEGY, + "effective_strategy": SAG2_STRATEGY, + "fallback_used": False, + "ranking": {"method": "jev", "fallback_reason": None}, + } + + +def outcome_from_result( + result: Any, + *, + query: str, + data_source_ids: list[str], + requested_sources: int, + source_limit_applied: bool, + scope_chunks: int, +) -> SearchOutcome: + """把 zleap-sag2 的 ``SearchResult`` 映射为业务 DTO,保留引擎顺序与原始 JEV 分数。""" + sections = [ + RetrievedSection( + chunk_id=hit.chunk_id or hit.id, + heading=(hit.heading or hit.title or "").strip(), + content=(hit.content or "").strip(), + score=float(hit.score or 0.0), + rank=index, + source_id=hit.source_id, + source_config_id=hit.data_source_id, + metadata={"score_source": "jev", "hop": int(hit.hop or 0)}, + ) + for index, hit in enumerate(result.chunks) + ] + usage = dict(getattr(result, "usage", None) or {}) + trace = getattr(result, "trace", None) or () + stats = _base_stats( + sources=len(data_source_ids), + requested_sources=requested_sources, + source_limit_applied=source_limit_applied, + candidates=len(sections), + ) + stats["jev_usage"] = { + "requests": usage.get("requests"), + "judgments": usage.get("judgments"), + "input_tokens": usage.get("input_tokens"), + "output_tokens": usage.get("output_tokens"), + } + stats["sag2"] = { + "elapsed_ms": round(float(getattr(result, "elapsed_ms", 0.0) or 0.0), 2), + "local_ms": round(float(getattr(result, "local_ms", 0.0) or 0.0), 2), + "jev_ms": round(float(getattr(result, "jev_ms", 0.0) or 0.0), 2), + "snapshot_revision": getattr(result, "snapshot_revision", None), + "scope_chunks": scope_chunks, + "hops": [ + {"stage": item.get("stage"), "hop": item.get("hop"), "count": item.get("count")} + for item in trace + if isinstance(item, dict) + ], + } + return SearchOutcome(query=getattr(result, "query", None) or query, sections=sections, stats=stats) + + +class _AdmissionGate: + """可在线调整上限的并发闸门:在途检索继续持有名额,新检索按当前上限排队。""" + + def __init__(self, limit: int) -> None: + self._limit = max(1, limit) + self._active = 0 + self._condition = asyncio.Condition() + + @property + def active(self) -> int: + return self._active + + async def set_limit(self, limit: int) -> None: + async with self._condition: + self._limit = max(1, limit) + self._condition.notify_all() + + async def __aenter__(self) -> None: + async with self._condition: + await self._condition.wait_for(lambda: self._active < self._limit) + self._active += 1 + + async def __aexit__(self, *_exc: object) -> None: + async with self._condition: + self._active -= 1 + self._condition.notify_all() + + async def drain(self) -> None: + async with self._condition: + await self._condition.wait_for(lambda: self._active == 0) + + +class _EngineLoop: + """专用线程上的事件循环:承载只读引擎的连接、扫描与评分,不占用 API 循环。 + + ``run`` 从 API 循环提交协程并等待结果;等待方被取消(如整次超时)时同步取消 + 专用循环里的协程,避免遗留仍在扫描的工作。 + """ + + def __init__(self, name: str = "sag2-engine") -> None: + self._loop = asyncio.new_event_loop() + self._thread = threading.Thread(target=self._serve, name=name, daemon=True) + self._thread.start() + + def _serve(self) -> None: + asyncio.set_event_loop(self._loop) + try: + self._loop.run_forever() + finally: + self._loop.close() + + @property + def alive(self) -> bool: + return self._thread.is_alive() + + async def run(self, coroutine: Coroutine[Any, Any, Any]) -> Any: + future = asyncio.run_coroutine_threadsafe(coroutine, self._loop) + try: + return await asyncio.wrap_future(future) + except asyncio.CancelledError: + future.cancel() + raise + + def stop(self, timeout: float = 5.0) -> None: + if not self._thread.is_alive(): + return + self._loop.call_soon_threadsafe(self._loop.stop) + self._thread.join(timeout=timeout) + + +class Sag2EngineHolder: + """按配置指纹懒建、复用、重建一个只读 zleap-sag2 引擎,并限制并发检索数。 + + 引擎只在专用线程的事件循环里创建和使用;``_gate`` 与整次超时留在 API 循环。 + ``scorer_factory`` 仅供测试注入离线评分器;缺省由引擎按 ``JevConfig`` 创建真实客户端。 + """ + + def __init__(self, settings: Settings, *, scorer_factory: Callable[[Any], Any] | None = None) -> None: + self._settings = settings + self._scorer_factory = scorer_factory + self._engine: Any | None = None + self._fingerprint: tuple[Any, ...] | None = None + self._lock = asyncio.Lock() + self._gate = _AdmissionGate(settings.sag2_max_concurrent_searches) + self._loop: _EngineLoop | None = None + + def _engine_loop(self) -> _EngineLoop: + if self._loop is None or not self._loop.alive: + self._loop = _EngineLoop() + return self._loop + + @property + def started(self) -> bool: + return self._engine is not None + + @property + def stale(self) -> bool: + """当前引擎是否已不匹配配置;下次检索会按新配置重建。""" + return self._engine is not None and self._fingerprint != _fingerprint(self._settings) + + async def refresh(self, settings: Settings) -> None: + """配置发布后调用:新的并发上限立即生效;连接或存储变化后由下次检索惰性重建。 + + 在途检索持有旧引擎的本地引用,不在这里关闭它,避免打断正在进行的评分。 + """ + self._settings = settings + await self._gate.set_limit(settings.sag2_max_concurrent_searches) + + async def aclose(self) -> None: + """等待在途检索结束后关闭引擎并停掉专用循环;与 ``_close_all_slots`` 等待空闲的语义一致。""" + await self._gate.drain() + loop, self._loop = self._loop, None + if loop is not None and loop.alive: + try: + await loop.run(self._locked_close()) + finally: + await asyncio.to_thread(loop.stop) + else: + await self._locked_close() + + async def _locked_close(self) -> None: + async with self._lock: + await self._close() + + async def _close(self) -> None: + engine, self._engine, self._fingerprint = self._engine, None, None + if engine is None: + return + try: + await engine.aclose() + except Exception as error: # noqa: BLE001 - best-effort shutdown + log.warning("关闭 SAG2 只读引擎失败:%s", error) + + async def engine(self) -> Any: + async with self._lock: + fingerprint = _fingerprint(self._settings) + if self._engine is not None and self._fingerprint == fingerprint: + return self._engine + await self._close() + self._engine = await self._start(self._settings) + self._fingerprint = fingerprint + return self._engine + + async def _start(self, settings: Settings) -> Any: + from zleap.sag2 import DataEngine + + config = build_sag2_config(settings) + not_ready = ConfigurationError( + "知识库尚未初始化,暂无可检索的段落", code="sag2_storage_not_ready", stage=ErrorStage.RETRIEVE, + ) + if relational_provider(settings) == "sqlite" and not Path(settings.data_dir, "sag.db").is_file(): + raise not_ready + scorer = self._scorer_factory(config) if self._scorer_factory is not None else None + engine = DataEngine(config, scorer=scorer, health_check=False) + try: + # 空库会让 zleap-sag2 建立自己的业务表;只在已有 SAG 段落表时才启动只读模式。 + if not await self._sag_schema_present(engine): + raise not_ready + await engine.start() + except BaseException: + await engine.aclose() + raise + log.info("SAG2 只读引擎已启动 provider=%s", relational_provider(settings)) + return engine + + async def search( + self, + targets: list[tuple[str, Source | None]], + query: str, + *, + top_k: int, + requested_sources: int, + source_limit_applied: bool, + source_ids_by_config: dict[str, tuple[str, ...]] | None, + ) -> SearchOutcome: + """一次只读检索覆盖全部目标信源;失败直接上抛,不回退其他策略。""" + data_source_ids = [scid for scid, _ in targets] + if source_ids_by_config is not None: + data_source_ids = [scid for scid in data_source_ids if source_ids_by_config.get(scid)] + if not data_source_ids: + return SearchOutcome(query=query, sections=[], stats=_base_stats( + sources=0, requested_sources=requested_sources, source_limit_applied=source_limit_applied, candidates=0, + )) + source_ids = ( + None + if source_ids_by_config is None + else tuple(sorted({sid for scid in data_source_ids for sid in source_ids_by_config[scid]})) + ) + timeout = max(1.0, float(self._settings.sag2_search_timeout_seconds)) + try: + result, scope_chunks = await asyncio.wait_for( + self._run(query, data_source_ids, source_ids, top_k), timeout, + ) + except TimeoutError as error: + raise ServiceUnavailableError( + "SAG2 检索超时,请缩小信源范围或稍后重试", layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE, + ) from error + return outcome_from_result( + result, + query=query, + data_source_ids=data_source_ids, + requested_sources=requested_sources, + source_limit_applied=source_limit_applied, + scope_chunks=scope_chunks, + ) + + async def _run( + self, + query: str, + data_source_ids: list[str], + source_ids: tuple[str, ...] | None, + top_k: int, + ) -> tuple[Any, int]: + async with self._gate: + # 排队在 API 循环完成;引擎工作整体交给专用循环,扫描不阻塞其他请求。 + return await self._engine_loop().run(self._execute(query, data_source_ids, source_ids, top_k)) + + async def _execute( + self, + query: str, + data_source_ids: list[str], + source_ids: tuple[str, ...] | None, + top_k: int, + ) -> tuple[Any, int]: + """在专用循环里运行:取引擎、范围护栏、构造请求、检索与异常翻译。""" + from zleap.sag2 import SearchOptions, SearchRequest, SearchScope + + engine = await self.engine() + settings = self._settings + scope_chunks = await self._count_scope(engine, data_source_ids) + limit = int(settings.sag2_max_scope_chunks) + if limit and scope_chunks > limit: + raise ValidationError( + f"信源扫描范围过大:包含 {scope_chunks:,} 个段落,超过 SAG2 证据检索上限 {limit:,}。" + "请缩小所选文档或信源范围,或联系管理员调整扫描上限。", + layer=ErrorLayer.ENGINE, + stage=ErrorStage.RETRIEVE, + ) + scope_values: dict[str, Any] = {"data_source_ids": tuple(data_source_ids)} + if source_ids is not None: + scope_values["source_ids"] = source_ids + request = SearchRequest( + query=query, + scope=SearchScope(**scope_values), + options=SearchOptions( + candidate_k=settings.sag2_candidate_k, + seed_k=settings.sag2_seed_k, + max_hops=settings.sag2_max_hops, + expansion_term_limit=settings.sag2_expansion_term_limit, + top_k=max(1, min(int(top_k), 1000)), + ), + ) + started = time.perf_counter() + try: + result = await engine.search(request) + except Exception as error: # noqa: BLE001 - translated below + raise self._translate(error) from error + log.info( + "SAG2 检索完成 sources=%d scope_chunks=%d hits=%d elapsed=%.0fms", + len(data_source_ids), scope_chunks, len(result.chunks), (time.perf_counter() - started) * 1000, + ) + return result, scope_chunks + + @staticmethod + async def _sag_schema_present(engine: Any) -> bool: + """SAG 的段落表是否存在;zleap-sag2 据此决定进入只读直搜模式。""" + from sqlalchemy import inspect + + async with engine.store.engine.connect() as connection: + return bool(await connection.run_sync(lambda sync: inspect(sync).has_table(SAG_CHUNK_TABLE))) + + @staticmethod + async def _count_scope(engine: Any, data_source_ids: list[str]) -> int: + """匹配 SDK 0.1.0 Sag1Reader._rows 的分块 SQL,避免历史代际虚增。 + + SDK 先按信源加载、后按文档过滤,因此仍须统计整个信源的加载成本。 + 复用 SDK 检测到的表以兼容无 manifest 的旧库;不读取分块正文。 + """ + from sqlalchemy import and_, exists, func, or_, select + + tables = engine.store.sag1_reader.tables + chunks = tables[SAG_CHUNK_TABLE] + statement = select(func.count()).select_from(chunks).where(chunks.c.data_source_id.in_(data_source_ids)) + if "generation_id" in chunks.c: + unmanaged = chunks.c.generation_id.is_(None) + manifest = tables.get("sag_source_manifest") + if manifest is None: + statement = statement.where(unmanaged) + else: + same_source = and_( + manifest.c.data_source_id == chunks.c.data_source_id, + manifest.c.source_id == chunks.c.source_id, + ) + statement = statement.where(or_( + exists(select(1).select_from(manifest).where( + same_source, manifest.c.status == "ready", + manifest.c.active_generation_id == chunks.c.generation_id, + )), + and_(unmanaged, ~exists(select(1).select_from(manifest).where(same_source))), + )) + namespace = tables.get("sag_data_source_manifest") + if namespace is not None: + statement = statement.where(~exists(select(1).select_from(namespace).where( + namespace.c.data_source_id == chunks.c.data_source_id, namespace.c.active.is_not(True), + ))) + async with engine.store.engine.connect() as connection: + return int(await connection.scalar(statement) or 0) + + @staticmethod + def _translate(error: Exception) -> Exception: + """把 zleap-sag2 的异常翻译为带 layer/stage 的领域错误,文案与 ``multi_jev`` 一致;凭据与响应体不进消息。""" + from zleap.sag2 import JevError, SagError + from zleap.sag2.exceptions import ConfigError as Sag2ConfigError + + if isinstance(error, (ConfigurationError, ServiceUnavailableError, ValidationError, UpstreamError)): + return error + if isinstance(error, JevError): + status = error.details.get("status") if isinstance(error.details, dict) else None + if status in (401, 403): + return ConfigurationError(JEV_AUTH_FAILED_MESSAGE, layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE) + # 408/429 与 5xx 由 zleap-sag2 自行重试,耗尽后以“重试用尽”上抛;其余 4xx 是请求本身被拒绝。 + if isinstance(status, int) and 400 <= status < 500 and status not in (408, 429): + return ValidationError(JEV_REQUEST_REJECTED_MESSAGE, layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE) + return ServiceUnavailableError(JEV_UNAVAILABLE_MESSAGE, layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE) + if isinstance(error, Sag2ConfigError): + return ConfigurationError( + "SAG2 证据检索配置无效,请检查 JEV 服务与关系库设置", code=str(error.code), + layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE, + ) + if isinstance(error, SagError): + return UpstreamError( + "SAG2 检索失败,请稍后重试", code=str(error.code), layer=ErrorLayer.ENGINE, + stage=ErrorStage.RETRIEVE, retryable=bool(error.retryable), + ) + if isinstance(error, TimeoutError): + return ServiceUnavailableError( + "SAG2 检索超时,请缩小信源范围或稍后重试", layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE, + ) + return UpstreamError("SAG2 检索失败,请稍后重试", layer=ErrorLayer.ENGINE, stage=ErrorStage.RETRIEVE) + + +__all__ = [ + "SAG2_RELATIONAL_PROVIDERS", + "SAG2_STRATEGY", + "Sag2EngineHolder", + "build_sag2_config", + "jev_connection_issue", + "jev_connection_ready", + "outcome_from_result", + "sag2_relational_issue", + "sag2_relational_supported", +] diff --git a/apps/api/sag_api/sag/sag2_native_search.py b/apps/api/sag_api/sag/sag2_native_search.py new file mode 100644 index 00000000..1f04da7f --- /dev/null +++ b/apps/api/sag_api/sag/sag2_native_search.py @@ -0,0 +1,70 @@ +"""SAG2 retrieval over native, published document inputs only.""" + +from __future__ import annotations + +import asyncio + +from sqlalchemy import select + +from sag_api.core.errors import ConfigurationError +from sag_api.sag.sag2_engine import Sag2EngineHolder, jev_connection_issue +from sag_api.sag.sag2_source_engine import _BINDINGS, Sag2SourceEngine, native_config, native_namespace + + +class Sag2NativeSearchHolder(Sag2EngineHolder): + async def _start(self, settings): + issue = jev_connection_issue(settings) + if issue: + code, message = issue + raise ConfigurationError(message, code=code) + scorer = self._scorer_factory(native_config(settings)) if self._scorer_factory else None + adapter = Sag2SourceEngine(settings, "search", scorer=scorer) + await adapter.start() + return adapter.native + + async def _count_scope(self, engine, data_source_ids): + # source_state counts indexed chunks without loading text/token streams. + gate = asyncio.Semaphore(16) + + async with engine.store.engine.connect() as connection: + pairs = ( + await connection.execute( + select(_BINDINGS.c.namespace, _BINDINGS.c.input_id).where( + _BINDINGS.c.namespace.in_(data_source_ids), + ) + ) + ).all() + + async def count(namespace, input_id): + async with gate: + state = await engine.source_state(input_id, data_source_id=namespace) + return int(state.chunk_count) if state is not None else 0 + + return sum(await asyncio.gather(*(count(namespace, input_id) for namespace, input_id in pairs))) + + async def search(self, targets, query, *, top_k, requested_sources, source_limit_applied, source_ids_by_config): + if source_ids_by_config is None: + raise ConfigurationError("SAG2 检索必须限定已发布文档范围") + mapping = { + native_namespace(config_id, input_id): config_id + for config_id, _ in targets + for input_id in source_ids_by_config.get(config_id, ()) + } + scopes = { + native_namespace(config_id, input_id): (input_id,) + for config_id, _ in targets + for input_id in source_ids_by_config.get(config_id, ()) + } + outcome = await super().search( + [(namespace, None) for namespace in mapping], + query, + top_k=top_k, + requested_sources=requested_sources, + source_limit_applied=source_limit_applied, + source_ids_by_config=scopes, + ) + for section in outcome.sections: + section.source_config_id = mapping[section.source_config_id] + section.metadata["engine_kind"] = "sag2" + outcome.stats["sources"] = len(targets) + return outcome diff --git a/apps/api/sag_api/sag/sag2_source_engine.py b/apps/api/sag_api/sag/sag2_source_engine.py new file mode 100644 index 00000000..79aee32e --- /dev/null +++ b/apps/api/sag_api/sag/sag2_source_engine.py @@ -0,0 +1,253 @@ +"""Native SAG2 storage with the application's durable document-operation contract. + +The application persists the same request envelope for both engines. This adapter +removes extraction options before calling SAG2 and maps its zero-event result back +to the shared publication DTO; no SAG1 engine or model clients are constructed. +""" + +from __future__ import annotations + +from datetime import UTC, datetime +from hashlib import sha256 +from pathlib import Path +from uuid import NAMESPACE_URL, uuid5 + +from sqlalchemy import Column, MetaData, String, Table, delete, event, select, text +from zleap.sag.operations import OperationResult +from zleap.sag.pipeline import ChunkSetRef, EventSetRef +from zleap.sag2 import DataEngine, EngineConfig, JevConfig, RelationalConfig +from zleap.sag2.operations import ( + DeleteDataSourceRequest, + DeleteSourceRequest, + ProcessSourceRequest, +) +from zleap.sag2.pipeline.errors import PipelineCancelledError +from zleap.sag2.pipeline.options import IndexOptions + +from sag_api.core.config import Settings +from sag_api.core.errors import ConfigurationError + +_BINDINGS_METADATA = MetaData() +_BINDINGS = Table( + "sag_app_sag2_inputs", + _BINDINGS_METADATA, + Column("namespace", String(256), primary_key=True), + Column("source_config_id", String(64), nullable=False, index=True), + Column("input_id", String(64), nullable=False), +) + + +def native_namespace(source_config_id: str, input_id: str) -> str: + return uuid5(NAMESPACE_URL, f"sag:source:{source_config_id}:input:{input_id}").hex + + + +def native_config(settings: Settings) -> EngineConfig: + provider = settings.sag_relational_provider or "sqlite" + if provider == "sqlite": + relational = RelationalConfig(provider="sqlite", path=str(Path(settings.data_dir) / "sag2.db")) + elif provider == "postgres": + relational = RelationalConfig( + provider="postgres", + host=settings.sag_pg_host, + port=settings.sag_pg_port, + user=settings.sag_pg_user, + password=settings.sag_pg_password, + database=settings.sag_pg_database, + ) + else: + raise ConfigurationError("SAG2 仅支持 SQLite 与 PostgreSQL 关系库") + jev = None + if settings.jev_endpoint and settings.jev_api_key: + jev = JevConfig( + endpoint=settings.jev_endpoint, + api_key=settings.jev_api_key, + model=settings.jev_model, + timeout_seconds=settings.sag2_decision_timeout_seconds, + max_concurrency=settings.sag2_decision_max_concurrency, + ) + return EngineConfig(relational=relational, jev=jev) + + +class Sag2SourceEngine: + """One namespace in native SAG2 storage, independent of SAG1's tables.""" + + def __init__(self, settings: Settings, source_config_id: str, *, scorer=None): + self.source_config_id = source_config_id + self.native = DataEngine(native_config(settings), health_check=False, scorer=scorer) + + async def start(self): + if self.native.config.relational.provider == "postgres": + sql_engine = self.native.store.engine + async with sql_engine.begin() as connection: + await connection.execute(text("CREATE SCHEMA IF NOT EXISTS sag2")) + await sql_engine.dispose() + + @event.listens_for(sql_engine.sync_engine, "connect") + def set_namespace(connection, _record): + previous = connection.autocommit + connection.autocommit = True + try: + cursor = connection.cursor() + cursor.execute("SET SESSION search_path TO sag2") + cursor.close() + finally: + connection.autocommit = previous + + await self.native.start() + async with self.native.store.engine.begin() as connection: + await connection.run_sync(_BINDINGS_METADATA.create_all) + + async def aclose(self): + await self.native.aclose() + + def _result(self, result): + if result is None: + return None + data = result.model_dump(mode="json") + if data.get("failure_code") == "pipeline_cancelled": + data["failure_code"] = "cancelled" + data["data_source_id"] = self.source_config_id + data["fence_scope"] = self.source_config_id + payload = dict(data.get("result") or {}) + if data["operation_type"] == "process_source" and data["status"] == "succeeded": + raw = {**payload, "data_source_id": self.source_config_id} + chunks = ChunkSetRef.model_validate( + { + **{key: value for key, value in raw.items() if key in ChunkSetRef.model_fields}, + "vector_status": "skipped_by_policy", + } + ) + events = EventSetRef( + data_source_id=chunks.data_source_id, + source_type=chunks.source_type, + source_id=chunks.source_id, + source_version=chunks.source_version, + chunk_version=chunks.chunk_version, + extract_version="sag2:no-extraction", + generation_id=chunks.generation_id, + chunk_ids=chunks.chunk_ids, + event_ids=(), + relation_status="skipped_by_policy", + vector_status="skipped_by_policy", + ) + payload.update(chunk_ref=chunks.model_dump(mode="json"), event_ref=events.model_dump(mode="json")) + if data["operation_type"] in {"delete_source", "delete_data_source"} and data["status"] == "succeeded": + payload["target"] = "source" if data["operation_type"] == "delete_source" else "data_source" + data["result"] = payload + return OperationResult.model_validate(data) + + async def process_source(self, request, *, observer=None, cancellation=None): + data = request.model_dump(mode="json", exclude={"extraction_options"}) + # SAG1's input-isolation flag is an app publication policy; SAG2 always + # stores immutable generations and the app filters by the published input. + data["context"].pop("isolation", None) + input_id = data["source"]["descriptor"]["source_id"] + namespace = native_namespace(self.source_config_id, input_id) + data["source"]["descriptor"]["data_source_id"] = namespace + data["context"]["fence_scope"] = namespace + # Each app input is immutable and has its own fence, so processing or + # resuming another document cannot invalidate this operation. + async with self.native.store.engine.begin() as connection: + from sqlalchemy.dialects.postgresql import insert as pg_insert + from sqlalchemy.dialects.sqlite import insert as sqlite_insert + + insert = pg_insert if connection.dialect.name == "postgresql" else sqlite_insert + await connection.execute( + insert(_BINDINGS) + .values( + namespace=namespace, + source_config_id=self.source_config_id, + input_id=input_id, + ) + .on_conflict_do_nothing() + ) + data["index_options"] = { + key: value for key, value in data.get("index_options", {}).items() if key in IndexOptions.model_fields + } + native_request = ProcessSourceRequest.model_validate(data) + try: + result = await self.native.process_source(native_request, observer=observer, cancellation=cancellation) + except PipelineCancelledError: + result = await self.native.get_operation_status(request.context.operation_id) + return self._result(result) + + async def get_operation_status(self, operation_id): + return self._result(await self.native.get_operation_status(operation_id)) + + async def delete_source(self, request): + data = request.model_dump(mode="json") + data["context"].pop("isolation", None) + namespace = native_namespace(self.source_config_id, request.source_id) + data["data_source_id"] = namespace + data["context"]["fence_scope"] = namespace + data["context"]["fence_token"] = max(2, data["context"]["fence_token"]) + result = self._result(await self.native.delete_source(DeleteSourceRequest.model_validate(data))) + return result.model_copy(update={ + "fence_token": request.context.fence_token, "fence_scope": request.context.fence_scope, + }) + + async def delete_data_source(self, request): + async with self.native.store.engine.connect() as connection: + namespaces = ( + ( + await connection.execute( + select(_BINDINGS.c.namespace).where( + _BINDINGS.c.source_config_id == self.source_config_id, + ) + ) + ) + .scalars() + .all() + ) + removed = 0 + for namespace in namespaces: + data = request.model_dump(mode="json") + data["context"].pop("isolation", None) + data["context"].update( + operation_id=request.context.operation_id + ":" + sha256(namespace.encode()).hexdigest()[:16], + idempotency_key=request.context.idempotency_key + ":" + sha256(namespace.encode()).hexdigest()[:16], + fence_scope=namespace, + fence_token=max(3, request.context.fence_token), + ) + data["data_source_id"] = namespace + result = await self.native.delete_data_source(DeleteDataSourceRequest.model_validate(data)) + if result.status != "succeeded": + return self._aggregate_delete_result(request, result=result) + removed += int((result.result or {}).get("deleted_chunks", 0)) + async with self.native.store.engine.begin() as connection: + await connection.execute(delete(_BINDINGS).where(_BINDINGS.c.source_config_id == self.source_config_id)) + return self._aggregate_delete_result(request, removed=removed) + + def _aggregate_delete_result(self, request, *, removed=0, result=None): + now = datetime.now(UTC) + return OperationResult( + operation_id=request.context.operation_id, + idempotency_key=request.context.idempotency_key, + request_digest=request.context.request_digest, + operation_type="delete_data_source", + data_source_id=self.source_config_id, + status=result.status if result is not None else "succeeded", + checkpoint=result.checkpoint if result is not None else "ready", + fence_scope=request.context.fence_scope, + fence_token=request.context.fence_token, + created_at=now, updated_at=now, + failure_code=result.failure_code if result is not None else None, + failure_message=result.failure_message if result is not None else None, + retryable=result.retryable if result is not None else False, + result={"target": "data_source", "deleted_chunks": removed}, + ) + + async def read_chunk(self, source_id, chunk_id, *, data_source_id): + return await self.native.read_chunk( + source_id, chunk_id, data_source_id=native_namespace(data_source_id, source_id) + ) + + async def rows(self, input_ids): + from zleap.sag2 import SearchScope + + if not input_ids: + return [] + scope = SearchScope(data_source_ids=tuple(native_namespace(self.source_config_id, item) for item in input_ids)) + snapshot = await self.native.store.snapshot(scope) + return list(snapshot.rows.values()) diff --git a/apps/api/sag_api/sag/search_reader.py b/apps/api/sag_api/sag/search_reader.py index 7e9465e8..bb4fb4a4 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( @@ -278,12 +315,15 @@ async def search_many( "source_limit_applied": requested_sources > len(targets), "candidates": 0, "chunk_recall": "batch-vector-timeout", + "source_failures": [{"source_config_id": scid, "message": "块向量召回超时"} + for scid, _ in targets], }, ) except Exception as error: # noqa: BLE001 - use the same scope in per-range fallback log.warning("批量块向量召回失败,回退逐范围检索:%s", error) semaphore = asyncio.Semaphore(self._access.settings.search_source_concurrency) + source_failures = [] async def _one(scid: str, source: Source | None): async with semaphore: @@ -299,9 +339,11 @@ 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) + message = getattr(e, "message", None) or str(e) + log.warning("fan-out 检索失败 %s:%s", scid, message) + source_failures.append({"source_config_id": scid, "message": message}) return None tasks = [asyncio.create_task(_one(scid, src)) for scid, src in targets] @@ -350,6 +392,7 @@ async def _one(scid: str, source: Source | None): candidate.setdefault("source_config_id", scid) ranked_candidates.append(candidate) stats: dict[str, Any] = { + **({"source_failures": source_failures} if source_failures else {}), "sources": len(targets), "sources_requested": requested_sources, "source_limit_applied": requested_sources > len(targets), diff --git a/apps/api/sag_api/schemas/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..d574479c 100644 --- a/apps/api/sag_api/schemas/source.py +++ b/apps/api/sag_api/schemas/source.py @@ -1,11 +1,11 @@ from __future__ import annotations from datetime import datetime -from typing import Any +from typing import Any, Literal 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 @@ -18,6 +18,8 @@ class ConnectorOut(BaseModel): class SourceCreate(BaseModel): + model_config = ConfigDict(extra="forbid") + engine_kind: Literal["sag1", "sag2"] = "sag1" name: str = Field(min_length=1, max_length=200) description: str = "" connector_kind: ConnectorKind = ConnectorKind.FILE_UPLOAD @@ -25,6 +27,7 @@ class SourceCreate(BaseModel): class SourceUpdate(BaseModel): + model_config = ConfigDict(extra="forbid") name: str | None = Field(default=None, max_length=200) description: str | None = None status: SourceStatus | None = None @@ -34,6 +37,7 @@ class SourceOut(BaseModel): model_config = ConfigDict(from_attributes=True) id: str + engine_kind: Literal["sag1", "sag2"] = "sag1" name: str description: str source_type: SourceType @@ -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..3fdfc9d1 100644 --- a/apps/api/sag_api/services/agent_tooling.py +++ b/apps/api/sag_api/services/agent_tooling.py @@ -345,13 +345,20 @@ def _adapt_tool(host_tool, host_context: HostToolContext, citations: list[dict]) timeout_seconds = None if name == "search_context": from sag_api.core.config import MAX_JEV_RANKING_TIMEOUT_SECONDS, settings - from sag_api.tools.builtin import knowledge_search_strategy + from sag_api.tools.builtin import knowledge_search_strategy, knowledge_search_strategy_origin configuration = getattr(host_context.engine_manager, "_settings", settings) - strategy = knowledge_search_strategy(host_context.persona, configuration) - # Keep this run's mode stable while the model prepares the tool call. - host_context = replace(host_context, persona={**host_context.persona, "search_strategy": strategy}) - if strategy == "multi_jev": + strategy = knowledge_search_strategy( + host_context.persona, configuration, host_context.sources, host_context.requested_strategy, + ) + # Freeze execution and provenance together without rewriting the persona. + origin = knowledge_search_strategy_origin( + host_context.persona, host_context.sources, host_context.requested_strategy, + ) + host_context = replace(host_context, search_strategy_snapshot=(strategy, origin)) + effective = (host_context.engine_manager._effective_search_strategy(strategy) + if hasattr(host_context.engine_manager, "_effective_search_strategy") else strategy) + if effective == "multi_jev" or (effective == "auto" and configuration.search_strategy == "multi_jev"): source_count = min(len(host_context.sources), configuration.search_source_candidate_limit) waves = max(1, ceil(source_count / configuration.search_source_concurrency)) recall_timeout = max(1.0, configuration.search_source_timeout) @@ -361,6 +368,18 @@ 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, ) + if strategy == "sag2" or (strategy == "auto" and any( + getattr(source, "engine_kind", "sag1") == "sag2" for source in host_context.sources + )): + from sag_api.sag.search_reader import search_admission_timeout_seconds + + # One read-only request covers every source. Its whole-search budget is + # also the settings-publication wait, so allow one of each plus recall. + whole_search = search_admission_timeout_seconds(configuration, "sag2") or 0.0 + timeout_seconds = max( + timeout_seconds or 0, 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/engine_routing.py b/apps/api/sag_api/services/engine_routing.py new file mode 100644 index 00000000..3b0e885f --- /dev/null +++ b/apps/api/sag_api/services/engine_routing.py @@ -0,0 +1,102 @@ +"""Route automatic retrieval by immutable knowledge algorithm and fuse ranks.""" + +from __future__ import annotations + +import asyncio + +from sag_api.sag.dto import SearchOutcome + + +async def retrieve_automatic(sources, query, *, sag1_strategy, top_k, retrieve): + groups = { + kind: [source for source in sources if getattr(source, "engine_kind", "sag1") == kind] + for kind in ("sag1", "sag2") + } + kinds = [kind for kind, group in groups.items() if group] + results = await asyncio.gather( + *(retrieve(groups[kind], "sag2" if kind == "sag2" else sag1_strategy) for kind in kinds), return_exceptions=True + ) + if (len(kinds) == 1 and not isinstance(results[0], BaseException) + and not results[0].stats.get("source_failures")): + outcome = results[0] + for section in outcome.sections: + section.metadata["engine_kind"] = kinds[0] + return outcome.model_copy( + update={ + "stats": { + **outcome.stats, + "requested_strategy": "auto", + "effective_strategy": "auto", + "engine_kind": kinds[0], + "jev_fallback_used": sag1_strategy == "multi_jev" and bool(outcome.stats.get("fallback_used")), + } + } + ) + failures = [] + candidates = {} + usage = {} + engine_stats = {} + source_stats = {} + fallback_used = False + jev_fallback_used = False + succeeded = 0 + for kind, result in zip(kinds, results, strict=True): + if isinstance(result, BaseException): + if not isinstance(result, Exception): + raise result + failures.append({"engine_kind": kind, "message": getattr(result, "message", None) or str(result)}) + continue + succeeded += 1 + engine_stats[kind] = result.stats + source_stats.update(result.stats.get("source_stats") or {}) + fallback_used |= bool(result.stats.get("fallback_used")) + jev_fallback_used |= kind == "sag1" and sag1_strategy == "multi_jev" and bool(result.stats.get("fallback_used")) + if result.stats.get("source_failures"): + messages = list(dict.fromkeys(item["message"] for item in result.stats["source_failures"])) + failures.append({"engine_kind": kind, "message": "; ".join(messages)}) + for key, value in (result.stats.get("jev_usage") or {}).items(): + if isinstance(value, (int, float)): + usage[key] = usage.get(key, 0) + value + for rank, section in enumerate(result.sections): + key = (section.source_config_id, section.chunk_id or section.content) + contribution = 1.0 / (60 + rank + 1) + if key not in candidates: + candidates[key] = [section, 0.0, len(candidates), kind] + candidates[key][1] += contribution + if kinds and not succeeded: + raise next(result for result in results if isinstance(result, Exception)) + ranked = sorted(candidates.values(), key=lambda item: (-item[1], item[2]))[:top_k] + sections = [ + section.model_copy( + update={ + "score": score, + "rank": rank, + "metadata": { + **section.metadata, + "engine_kind": kind, + "original_score": section.score, + "score_source": "rrf", + }, + } + ) + for rank, (section, score, _, kind) in enumerate(ranked) + ] + return SearchOutcome( + query=query, + sections=sections, + stats={ + "requested_strategy": "auto", + "effective_strategy": "auto", + "strategy_origin": "global", + "sources": len(sources), + "relevant": len(sections), + "fusion": "rrf", + "partial_results": bool(failures), + "engine_failures": failures, + "engine_stats": engine_stats, + "source_stats": source_stats, + "fallback_used": fallback_used, + "jev_fallback_used": jev_fallback_used, + **({"jev_usage": usage} if usage else {}), + }, + ) diff --git a/apps/api/sag_api/services/knowledge_algorithms.py b/apps/api/sag_api/services/knowledge_algorithms.py new file mode 100644 index 00000000..4643f231 --- /dev/null +++ b/apps/api/sag_api/services/knowledge_algorithms.py @@ -0,0 +1,8 @@ +"""Business policy for immutable knowledge algorithms.""" + +from sag_api.core.errors import ValidationError + + +def require_sag1_octx(source) -> None: + if getattr(source, "engine_kind", "sag1") == "sag2": + raise ValidationError("证据检索(SAG2)知识库暂不支持 OCTX 导入覆盖或导出;OCTX 目前仅支持事件检索(SAG1)。") diff --git a/apps/api/sag_api/services/octx_conflict_service.py b/apps/api/sag_api/services/octx_conflict_service.py index d201d3e1..14a00423 100644 --- a/apps/api/sag_api/services/octx_conflict_service.py +++ b/apps/api/sag_api/services/octx_conflict_service.py @@ -14,6 +14,7 @@ from sag_api.db.models.octx import transition_transfer from sag_api.enums import OctxImportAction, OctxTransferStatus from sag_api.octx.decision_token import DecisionTokenError, verify_decision_token +from sag_api.services.knowledge_algorithms import require_sag1_octx @dataclass(frozen=True, slots=True) @@ -211,6 +212,7 @@ async def confirm_import_decision( target_source_id = decision.target_source_id if target_source_id is None or target_source_id not in claims.source_revisions: raise ValidationError("update target is not present in OCTX decision token") + require_sag1_octx(await session.get(Source, target_source_id)) binding = await session.get(OctxSourceBinding, target_source_id) if binding is None or binding.asset_id != claims.asset_id: transition_transfer(transfer, OctxTransferStatus.VALIDATING) diff --git a/apps/api/sag_api/services/octx_export.py b/apps/api/sag_api/services/octx_export.py index 2e267407..e9a90aeb 100644 --- a/apps/api/sag_api/services/octx_export.py +++ b/apps/api/sag_api/services/octx_export.py @@ -54,6 +54,7 @@ from sag_api.octx.semver import bump_semver_patch, parse_semver, validate_semver from sag_api.octx.storage import OctxStorage from sag_api.sag.octx_snapshot import export_snapshot +from sag_api.services.knowledge_algorithms import require_sag1_octx from sag_api.services.octx_checkpoint import merge_checkpoint from sag_api.services.octx_diagnostics_service import append_octx_trace @@ -127,6 +128,7 @@ async def create_export_transfer( source = await session.get(Source, source_id) if source is None: raise NotFoundError("source not found") + require_sag1_octx(source) documents = ( ( await session.execute( @@ -327,6 +329,7 @@ async def create_document_export_transfer( source = await session.get(Source, source_id) if source is None: raise NotFoundError("source not found") + require_sag1_octx(source) document = await session.get(Document, document_id) if document is None or document.source_id != source_id or not document.is_active: raise NotFoundError("document not found") @@ -530,6 +533,7 @@ async def execute_export( source = await session.get(Source, transfer.target_source_id) if source is None: raise NotFoundError("source not found") + require_sag1_octx(source) checkpoint = dict(transfer.checkpoint or {}) selected_document_ids = tuple(checkpoint.get("selected_document_ids") or ()) selected_article_ids = tuple(checkpoint.get("selected_article_ids") or ()) diff --git a/apps/api/sag_api/services/octx_transfer_common.py b/apps/api/sag_api/services/octx_transfer_common.py index 6440dee2..a3b4ad8a 100644 --- a/apps/api/sag_api/services/octx_transfer_common.py +++ b/apps/api/sag_api/services/octx_transfer_common.py @@ -37,6 +37,7 @@ OctxTransferStatus, ) from sag_api.octx.storage import FileSignature, OctxStorage, StoredUpload +from sag_api.services.knowledge_algorithms import require_sag1_octx from sag_api.services.octx_checkpoint import merge_checkpoint logger = logging.getLogger(__name__) @@ -234,7 +235,9 @@ async def _claim_import_target(session: AsyncSession, transfer: OctxTransfer) -> if claimed.rowcount != 1: raise ConflictError("OCTX target is being deleted", code=ErrorCode.OCTX_TRANSFER_CANCELLED, retryable=False) await _ensure_transfer_active(session, transfer, stage="atomic_switch") - return await session.get(Source, target_id, populate_existing=True) + source = await session.get(Source, target_id, populate_existing=True) + require_sag1_octx(source) + return source def _export_document_state(documents: list[Document]) -> tuple[list[dict], list[dict]]: diff --git a/apps/api/sag_api/services/retrieval_service.py b/apps/api/sag_api/services/retrieval_service.py index 0aefabe7..328ed4a9 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,30 @@ 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 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") + return ResolvedSearchStrategy("auto", "global") def event_scores_from_evidence(sections: list[RetrievedSection]) -> EventScoreMap: @@ -264,6 +288,7 @@ async def _lexical_sections( *, analysis: QueryAnalysis, source_ids_by_config: DocumentSourceScope, + failures: list[dict] | None = None, ) -> tuple[list[RetrievedSection], set[tuple[str, str]]]: grep_chunks = getattr(engine_manager, "grep_chunks", None) terms = analysis.lookup_terms @@ -289,7 +314,12 @@ async def one( term, **options, ) - except Exception: # noqa: BLE001 + except Exception as error: # noqa: BLE001 + if failures is not None and not any( + item["source_config_id"] == source.sag_source_config_id for item in failures + ): + failures.append({"source_config_id": source.sag_source_config_id, + "message": getattr(error, "message", None) or str(error)}) return [], False sections = [ RetrievedSection( @@ -324,11 +354,35 @@ 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 == "auto": + from sag_api.services.engine_routing import retrieve_automatic + sag1_strategy = configuration.search_strategy + if sag1_strategy not in {"vector", "multi", "multi_es_fast", "multi_jev"}: + sag1_strategy = "vector" + async def retrieve(group, mode): + return await retrieve_relevant_sections( + engine_manager, group, query, strategy=mode, top_k=top_k, + include_ranked_candidates=include_ranked_candidates, + ) + outcome = await retrieve_automatic( + sources, query, sag1_strategy=sag1_strategy, + top_k=max(1, min(int(top_k or configuration.search_top_k), 50)), retrieve=retrieve, + ) + outcome.stats["latency_total_ms"] = round((time.perf_counter() - total_start) * 1000, 2) + outcome.stats["strategy_origin"] = resolved.origin + return outcome + expected_engine = "sag2" if mode == "sag2" else "sag1" + sources = [source for source in sources if getattr(source, "engine_kind", "sag1") == expected_engine] + if not sources: + return SearchOutcome(query=query, sections=[], stats={ + "requested_strategy": requested_strategy, "effective_strategy": mode, "sources": 0, + }) + if mode in JEV_SCORED_STRATEGIES: + # The JEV-scored profile owns recall and final scoring. Adding application + # lexical hits afterwards would mix unscored evidence into the ranked list. 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 +405,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), @@ -381,6 +436,7 @@ async def retrieve_relevant_sections( if include_ranked_candidates: search_options["include_ranked_candidates"] = True search_options["source_ids_by_config"] = published + lexical_failures: list[dict] = [] outcome, lexical_recall = await asyncio.gather( engine_manager.search_many(targets, query, **search_options), _lexical_sections( @@ -388,6 +444,7 @@ async def retrieve_relevant_sections( sources, analysis=analysis, source_ids_by_config=published, + failures=lexical_failures, ), ) lexical, exact_lexical_keys = lexical_recall @@ -415,7 +472,9 @@ def visible(section: RetrievedSection) -> bool: total_latency_ms = round((time.perf_counter() - total_start) * 1000, 2) stats = { **outcome.stats, + "source_failures": [*(outcome.stats.get("source_failures") or []), *lexical_failures], "requested_strategy": requested_strategy, + "strategy_origin": resolved.origin, "requested_top_k": requested_limit, "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..e80a4703 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"}: + # Connection changes must preserve both global and source-level defaults. + # Reject atomically rather than silently changing a saved retrieval mode. + from sag_api.sag.sag2_engine import jev_connection_issue + + final = {**candidate, **{key: stored[key] for key in ("jev_endpoint", "jev_api_key") if key in stored}} + issue = jev_connection_issue(_settings.model_copy(update=final)) + if issue is not None: + code, message = issue + if normalize_search_strategy(str(final["search_strategy"])) in JEV_SCORED_STRATEGIES: + raise ConfigurationError( + f"{message} 当前默认检索模式为 JEV 模式;请先改为其他模式,或补填该服务的 API Key。", code=code, + ) 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..3f5b3942 100644 --- a/apps/api/sag_api/services/source_service.py +++ b/apps/api/sag_api/services/source_service.py @@ -106,6 +106,7 @@ async def create_source( source = Source( name=data.name, + engine_kind=data.engine_kind, description=data.description, source_type=source_type, connector_kind=data.connector_kind, diff --git a/apps/api/sag_api/tools/base.py b/apps/api/sag_api/tools/base.py index ecb0651f..52e44b14 100644 --- a/apps/api/sag_api/tools/base.py +++ b/apps/api/sag_api/tools/base.py @@ -44,8 +44,12 @@ class ToolContext: sources: list[Source] = field(default_factory=list) persona: dict[str, Any] = field(default_factory=dict) agent: Agent | None = None + # 本轮显式选择的检索模式;优先于人格与信源默认。 + requested_strategy: str | None = None # 全局证据编号偏移:循环在每次派发前设置,保证 [n] 跨轮递增不重号 citation_offset: int = 0 + # 工具准备时固定的模式与来源,不修改用户的人格配置。 + search_strategy_snapshot: tuple[str, str] | None = None @dataclass diff --git a/apps/api/sag_api/tools/builtin.py b/apps/api/sag_api/tools/builtin.py index 9bf080bc..75bc2e4f 100644 --- a/apps/api/sag_api/tools/builtin.py +++ b/apps/api/sag_api/tools/builtin.py @@ -19,7 +19,7 @@ from sag_api.connectors.web import extract_web_markdown, extract_web_title from sag_api.core.config import settings from sag_api.core.logging import get_logger -from sag_api.enums import SEARCH_STRATEGIES, normalize_search_strategy +from sag_api.enums import JEV_SCORED_STRATEGIES from sag_api.generation import build_citations from sag_api.sag import RetrievedSection from sag_api.services.retrieval_service import ( @@ -79,19 +79,24 @@ 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 ( - not isinstance(value, str) or normalize_search_strategy(value) not in SEARCH_STRATEGIES - ): - # The engine falls back to global JEV for unknown modes. Resolve that - # here too so the tool's budget and evidence handling use the same mode. - return default - # Existing persona values, including legacy aliases, retain the engine's - # resolution rules; preparing an unused tool must not add validation gates. - return value +def knowledge_search_strategy( + persona: dict[str, Any], configuration: Any = settings, sources=(), requested: str | None = None, +) -> str: + """Explicit turn choice → persona → automatic per-source engine routing.""" + if requested: + return requested + return persona.get("search_strategy") or "auto" + + +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" + return "global" def _format_sections(sections: list, offset: int = 0, events: list | None = None) -> str: @@ -248,7 +253,13 @@ async def invoke(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult: if not query or not ctx.sources: return ToolResult(content="(无相关资料)", citations=[], data={"section_count": 0}) persona = ctx.persona or {} - strategy = knowledge_search_strategy(persona, getattr(ctx.engine_manager, "_settings", settings)) + if ctx.search_strategy_snapshot is not None: + strategy, strategy_origin = ctx.search_strategy_snapshot + else: + strategy = knowledge_search_strategy( + persona, getattr(ctx.engine_manager, "_settings", settings), ctx.sources, ctx.requested_strategy, + ) + strategy_origin = knowledge_search_strategy_origin(persona, ctx.sources, ctx.requested_strategy) top_k = args.get("top_k") or persona.get("top_k") limit = max(1, min(int(top_k or 8), 50)) source_refs = {s.sag_source_config_id: {"id": s.id, "name": s.name} for s in ctx.sources} @@ -260,7 +271,12 @@ async def invoke(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult: strategy=strategy, top_k=limit, ) - is_jev = strategy == "multi_jev" + effective = (ctx.engine_manager._effective_search_strategy(strategy) + if hasattr(ctx.engine_manager, "_effective_search_strategy") else strategy) + is_jev = effective in JEV_SCORED_STRATEGIES or (effective == "auto" and ( + getattr(ctx.engine_manager, "_settings", settings).search_strategy == "multi_jev" + or any(getattr(source, "engine_kind", "sag1") == "sag2" for source in ctx.sources) + )) if is_jev: outcome = await retrieval event_scores: dict[tuple[str, str], float] = {} @@ -324,7 +340,12 @@ 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 outcome.stats.get("engine_failures"): + warnings = ";".join( + f"{item['engine_kind']}:{item['message']}" for item in outcome.stats["engine_failures"] + ) + content = f"注意:本次检索结果不完整,以下算法检索失败或不完整:{warnings}。回答须说明此限制。\n\n{content}" + if is_jev and outcome.stats.get("fallback_used"): content = "(JEV 精排未完成,本次返回粗排结果)\n" + content return ToolResult( content=content, @@ -337,7 +358,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/chatbot/test_model_cards.py b/apps/api/tests/chatbot/test_model_cards.py index 76f49f6a..a56aad62 100644 --- a/apps/api/tests/chatbot/test_model_cards.py +++ b/apps/api/tests/chatbot/test_model_cards.py @@ -13,7 +13,7 @@ from sag_api.core.db import get_session from sag_api.core.deps import get_current_user from sag_api.core.errors import ApiError -from sag_api.db.models import Document, Setting +from sag_api.db.models import Document, Setting, Source from sag_api.services import settings_service @@ -26,6 +26,7 @@ async def card_client(isolate, database, monkeypatch): async with database() as session: connection = await session.connection() await connection.run_sync(lambda sync: Document.__table__.create(sync)) + await connection.run_sync(lambda sync: Source.__table__.create(sync)) await session.commit() class Runtime: diff --git a/apps/api/tests/integration/test_document_operation_restart.py b/apps/api/tests/integration/test_document_operation_restart.py index 3ec8428d..f76e3820 100644 --- a/apps/api/tests/integration/test_document_operation_restart.py +++ b/apps/api/tests/integration/test_document_operation_restart.py @@ -349,10 +349,14 @@ async def wait_file(name, child, timeout=30): async with sessions() as session: bound = (await session.get(Job, identities["jobs"][0])).payload.get("process_request") receipt = await sdk.get_operation_status(bound["context"]["operation_id"]) if bound else None + # The marker can appear after this iteration read an older receipt. reached = ( models.blocked.is_set() and receipt is not None and receipt.extraction_progress["chunk_succeeded"] == 1 - if kill_at == "successful_chunk" else (root / "prepared.json").exists() + if kill_at == "successful_chunk" else ( + (root / "prepared.json").exists() and receipt is not None + and receipt.checkpoint == "extract_prepared" + ) ) if reached: break diff --git a/apps/api/tests/test_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..908e80f7 100644 --- a/apps/api/tests/test_agent_tools.py +++ b/apps/api/tests/test_agent_tools.py @@ -90,15 +90,15 @@ async def invoke(self, args, ctx): @pytest.mark.parametrize("persona", [ {}, {"search_strategy": ""}, {"search_strategy": False}, {"search_strategy": None}, ]) -def test_existing_assistant_default_stays_vector_until_jev_is_selected(strategy, persona): - assert knowledge_search_strategy(persona, SimpleNamespace(search_strategy=strategy)) == "vector" +def test_unset_assistant_uses_automatic_routing(strategy, persona): + assert knowledge_search_strategy(persona, SimpleNamespace(search_strategy=strategy)) == "auto" @pytest.mark.parametrize("persona", [ {}, {"search_strategy": ""}, {"search_strategy": False}, {"search_strategy": None}, ]) def test_unset_assistant_strategy_follows_explicit_global_jev_selection(persona): - assert knowledge_search_strategy(persona, SimpleNamespace(search_strategy="multi_jev")) == "multi_jev" + assert knowledge_search_strategy(persona, SimpleNamespace(search_strategy="multi_jev")) == "auto" @pytest.mark.parametrize("strategy", ["vector", "multi", "multi_es_fast", "atomic", "multi_jev", "typo"]) @@ -137,11 +137,11 @@ async def test_legacy_persona_does_not_block_tool_preparation_or_chat_without_so @pytest.mark.asyncio @pytest.mark.parametrize(("global_strategy", "persona", "expected"), [ - ("multi", {}, "vector"), - ("multi_es_fast", {"search_strategy": ""}, "vector"), - ("multi", {"search_strategy": False}, "vector"), - ("multi", {"search_strategy": None}, "vector"), - ("multi_jev", {}, "multi_jev"), + ("multi", {}, "auto"), + ("multi_es_fast", {"search_strategy": ""}, "auto"), + ("multi", {"search_strategy": False}, "auto"), + ("multi", {"search_strategy": None}, "auto"), + ("multi_jev", {}, "auto"), ("multi_jev", {"search_strategy": "vector"}, "vector"), ("vector", {"search_strategy": "multi_jev"}, "multi_jev"), ("multi", {"search_strategy": "atomic"}, "multi"), @@ -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 = [] @@ -177,7 +177,7 @@ async def events(*_args, **_kwargs): {"query": "查询旧资料"}, ToolContext(engine_manager=engine, sources=[source], persona=persona), ) assert selected == [expected] - assert bool(event_calls) is (expected != "multi_jev") + assert bool(event_calls) is not (expected == "multi_jev" or (expected == "auto" and global_strategy == "multi_jev")) assert result.data["section_count"] == 0 @@ -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..7f224004 --- /dev/null +++ b/apps/api/tests/test_chat_turn_strategy.py @@ -0,0 +1,170 @@ +"""Per-turn retrieval mode in chat: explicit choice wins, is gated before streaming, and reports its origin.""" + +from types import SimpleNamespace +from uuid import uuid4 + +import httpx +import pytest + +from sag_api.core.config import Settings, settings +from sag_api.sag import RetrievedSection, SearchOutcome, SourceGraphInfo +from sag_api.sag.engine_manager import EngineManager +from sag_api.schemas.agent import AskRequest +from sag_api.tools.builtin import knowledge_search_strategy, knowledge_search_strategy_origin + + +def configured(**changes) -> Settings: + return Settings(_env_file=None).model_copy(update={ + "jev_endpoint": "https://jev.invalid/score", + "jev_api_key": "synthetic-jev-key", + "sag_vector_provider": "lancedb", + "search_strategy": "multi_es_fast", + **changes, + }) + + +def source(default: str | None, config_id: str = "cfg-1"): + return SimpleNamespace( + id=config_id, name=config_id, sag_source_config_id=config_id, default_search_strategy=default, + ) + + +def test_ask_request_accepts_optional_strategy(): + assert AskRequest(query="q").strategy is None + assert AskRequest(query="q", strategy="sag2").strategy == "sag2" + with pytest.raises(ValueError): + AskRequest(query="q", strategy="nope") + + +def test_turn_choice_precedes_persona_source_default_and_global(): + configuration = configured(search_strategy="vector") + persona = {"search_strategy": "multi"} + scoped = [source("sag2")] + assert knowledge_search_strategy(persona, configuration, scoped, "multi_jev") == "multi_jev" + assert knowledge_search_strategy_origin(persona, scoped, "multi_jev") == "request" + assert knowledge_search_strategy(persona, configuration, scoped) == "multi" + assert knowledge_search_strategy_origin(persona, scoped) == "persona" + assert knowledge_search_strategy({}, configuration, scoped) == "auto" + assert knowledge_search_strategy_origin({}, scoped) == "global" + assert knowledge_search_strategy({}, configuration, []) == "auto" + 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] == "auto" and result.data["retrieval_stats"]["strategy_origin"] == "global" + + # The adapted tool's budget follows the turn choice as well. + adapted = _adapt_tool(tool, ToolContext( + engine_manager=engine, sources=[scoped], persona={}, requested_strategy="vector", + ), []) + assert adapted.spec.timeout_seconds is None + + captured = [] + original_invoke = tool.invoke + + async def capture(arguments, context): + result = await original_invoke(arguments, context) + captured.append(result.data["retrieval_stats"]) + return result + + monkeypatch.setattr(tool, "invoke", capture) + for source_default, expected_origin in [("sag2", "global"), (None, "global")]: + scoped.default_search_strategy = source_default + persona = {} + adapted = _adapt_tool(tool, ToolContext(engine_manager=engine, sources=[scoped], persona=persona), []) + await adapted.execute({"query": "q"}, SimpleNamespace( + cancellation=SimpleNamespace(raise_if_cancelled=lambda: None), + )) + assert captured[-1]["strategy_origin"] == expected_origin + assert persona == {} + + +@pytest.fixture +async def chat_client(monkeypatch): + from sag_api.main import app + + async def skip_unrelated_mcp(_factory, _app): + return None + + monkeypatch.setattr("sag_api.runtime._RuntimeFactory.start_mcp", skip_unrelated_mcp) + snapshot = settings.model_dump() + try: + async with app.router.lifespan_context(app): + app.state.llm = SimpleNamespace(configured=True) + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://t") as client: + registration = await client.post( + "/api/v1/auth/register", + json={"email": f"chat-mode-{uuid4().hex}@t.com", "password": "password123"}, + ) + assert registration.status_code == 201 + client.headers["Authorization"] = f"Bearer {registration.json()['access_token']}" + yield client + finally: + for key, value in snapshot.items(): + setattr(settings, key, value) + + +async def test_ask_rejects_unavailable_turn_strategy_before_streaming(chat_client, monkeypatch): + client = chat_client + monkeypatch.setattr(settings, "sag_vector_provider", "lancedb") + monkeypatch.setattr(settings, "jev_endpoint", "https://jev.example/score") + monkeypatch.setattr(settings, "jev_api_key", None) + agent = (await client.post("/api/v1/agents", json={"name": "模式助手"})).json() + thread = (await client.post(f"/api/v1/agents/{agent['id']}/threads", json={})).json() + endpoint = f"/api/v1/agents/{agent['id']}/threads/{thread['id']}/ask" + + rejected = await client.post(endpoint, json={"query": "问题", "strategy": "sag2"}) + assert rejected.status_code == 400, rejected.text + assert rejected.json()["error"]["code"] == "jev_api_key_missing" + # Nothing was persisted for the rejected turn. + messages = await client.get(f"/api/v1/agents/{agent['id']}/threads/{thread['id']}/messages") + assert messages.status_code == 200 and messages.json()["items"] == [] + + unknown = await client.post(endpoint, json={"query": "问题", "strategy": "nope"}) + assert unknown.status_code == 422 + + monkeypatch.setattr(settings, "sag_relational_provider", "mysql") + monkeypatch.setattr(settings, "jev_api_key", "synthetic-jev-key") + storage = await client.post(endpoint, json={"query": "问题", "strategy": "sag2"}) + assert storage.status_code == 400 and storage.json()["error"]["code"] == "sag2_relational_unsupported" diff --git a/apps/api/tests/test_client_access_standard.py b/apps/api/tests/test_client_access_standard.py index 11629595..abf8463e 100644 --- a/apps/api/tests/test_client_access_standard.py +++ b/apps/api/tests/test_client_access_standard.py @@ -218,6 +218,8 @@ async def test_real_source_writes_have_recoverable_subject_scoped_operations(sta break await asyncio.sleep(0.05) assert job.json()["status"] == "succeeded", job.text + # A completed delete response can precede the worker's final DB cleanup. + await asyncio.wait_for(app.state.job_queue._queue.join(), timeout=30) async def test_disabled_user_loses_business_and_refresh_access(standard_client): diff --git a/apps/api/tests/test_engine_routing.py b/apps/api/tests/test_engine_routing.py new file mode 100644 index 00000000..e60e8ecb --- /dev/null +++ b/apps/api/tests/test_engine_routing.py @@ -0,0 +1,89 @@ +from types import SimpleNamespace + +import pytest + +from sag_api.sag.dto import RetrievedSection, SearchOutcome +from sag_api.services.engine_routing import retrieve_automatic + + +@pytest.mark.asyncio +async def test_auto_routes_bound_engines_and_interleaves_without_comparing_scores(): + sources = [SimpleNamespace(engine_kind="sag1", id="one"), SimpleNamespace(engine_kind="sag2", id="two")] + calls = [] + + async def retrieve(group, strategy): + calls.append((group[0].id, strategy)) + return SearchOutcome( + query="q", + sections=[ + RetrievedSection( + chunk_id=strategy, + source_config_id=group[0].id, + content=strategy, + score=100 if strategy == "vector" else 0.9, + ) + ], + ) + + result = await retrieve_automatic(sources, "q", sag1_strategy="vector", top_k=8, retrieve=retrieve) + assert set(calls) == {("one", "vector"), ("two", "sag2")} + assert {s.metadata["engine_kind"] for s in result.sections} == {"sag1", "sag2"} + assert result.stats["effective_strategy"] == "auto" + + +@pytest.mark.asyncio +async def test_partial_failure_is_reported_instead_of_appearing_complete(): + sources = [SimpleNamespace(engine_kind="sag1"), SimpleNamespace(engine_kind="sag2")] + + async def retrieve(group, strategy): + if strategy == "sag2": + raise RuntimeError("JEV unavailable") + return SearchOutcome(query="q", sections=[RetrievedSection(content="evidence", chunk_id="one")]) + + result = await retrieve_automatic(sources, "q", sag1_strategy="vector", top_k=8, retrieve=retrieve) + assert result.stats["partial_results"] is True + assert result.stats["engine_failures"][0]["engine_kind"] == "sag2" + assert len(result.sections) == 1 + + +@pytest.mark.asyncio +async def test_sag1_fanout_failure_is_not_hidden_by_successful_native_group(): + from sag_api.core.config import Settings + from sag_api.sag.search_reader import SearchReader + + async def broken(*args, **kwargs): + raise RuntimeError("legacy storage offline") + + reader = SearchReader(SimpleNamespace( + settings=Settings(_env_file=None), effective_search_strategy=lambda value: value, search=broken, + )) + async def retrieve(group, strategy): + if strategy == "multi": + return await reader.search_many([("legacy", None)], "q", strategy=strategy) + return SearchOutcome(query="q", sections=[RetrievedSection(content="native evidence")]) + + result = await retrieve_automatic( + [SimpleNamespace(engine_kind="sag1"), SimpleNamespace(engine_kind="sag2")], "q", + sag1_strategy="multi", top_k=8, retrieve=retrieve, + ) + assert result.stats["partial_results"] is True + assert result.stats["engine_failures"][0]["engine_kind"] == "sag1" + assert "legacy storage offline" in result.stats["engine_failures"][0]["message"] + + +@pytest.mark.asyncio +async def test_mixed_results_preserve_jev_fallback_provenance(): + async def retrieve(group, strategy): + return SearchOutcome(query="q", sections=[], stats={ + "fallback_used": strategy == "multi_jev", + "ranking": {"method": "jev", "fallback_reason": "deadline" if strategy == "multi_jev" else None}, + "source_stats": {strategy: {"fallback_used": strategy == "multi_jev"}}, + }) + result = await retrieve_automatic( + [SimpleNamespace(engine_kind="sag1"), SimpleNamespace(engine_kind="sag2")], "q", + sag1_strategy="multi_jev", top_k=8, retrieve=retrieve, + ) + assert result.stats["fallback_used"] is True + assert result.stats["jev_fallback_used"] is True + assert result.stats["engine_stats"]["sag1"]["ranking"]["fallback_reason"] == "deadline" + assert result.stats["source_stats"]["multi_jev"]["fallback_used"] is True diff --git a/apps/api/tests/test_jev_config.py b/apps/api/tests/test_jev_config.py index 6fc56635..e87dddaf 100644 --- a/apps/api/tests/test_jev_config.py +++ b/apps/api/tests/test_jev_config.py @@ -221,6 +221,80 @@ async def test_jev_service_rejects_invalid_explicit_fields_before_persisting(jev assert resets == [] +@pytest.mark.parametrize("strategy", ["multi_jev", "sag2"]) +@pytest.mark.parametrize("endpoint", [None, "https://replacement.example/score"]) +async def test_retired_source_preferences_do_not_block_jev_connection_changes(jev_config_client, strategy, endpoint): + from sag_api.core.db import SessionLocal + from sag_api.db.models import Source + + client, headers, resets = jev_config_client + initial = await client.put( + "/api/v1/system/model-config", headers=headers, + json={"search_strategy": "vector", "jev_endpoint": "https://saved.example/score", + "jev_api_key": "synthetic-saved-key"}, + ) + assert initial.status_code == 200, initial.text + source_id = uuid4().hex + async with SessionLocal() as session: + session.add(Source(id=source_id, name="Protected source", sag_source_config_id=source_id, + default_search_strategy=strategy)) + await session.commit() + try: + changed = await client.put( + "/api/v1/system/model-config", headers=headers, json={"jev_endpoint": endpoint}, + ) + assert changed.status_code == 200, changed.text + assert changed.json()["config"]["jev_api_key_set"] is False + async with SessionLocal() as session: + legacy = await session.get(Source, source_id) + assert legacy.default_search_strategy == strategy + assert legacy.engine_kind == "sag1" + + # Supplying a key for the new destination keeps the saved source usable. + replaced = await client.put( + "/api/v1/system/model-config", headers=headers, + json={"jev_endpoint": "https://replacement.example/score", "jev_api_key": "synthetic-new-key"}, + ) + assert replaced.status_code == 200, replaced.text + finally: + async with SessionLocal() as session: + await session.execute(delete(Source).where(Source.id == source_id)) + await session.commit() + + +async def test_stale_source_default_does_not_block_unrelated_settings_or_deleted_sources(jev_config_client): + from sag_api.core.db import SessionLocal + from sag_api.db.models import Source + from sag_api.enums import SourceStatus + + client, headers, _resets = jev_config_client + settings.search_strategy = "vector" + settings.jev_endpoint = None + settings.jev_api_key = None + source_id = uuid4().hex + async with SessionLocal() as session: + session.add(Source(id=source_id, name="Stale source", sag_source_config_id=source_id, + default_search_strategy="sag2")) + await session.commit() + try: + unrelated = await client.put( + "/api/v1/system/model-config", headers=headers, json={"search_top_k": 9}, + ) + assert unrelated.status_code == 200, unrelated.text + async with SessionLocal() as session: + (await session.get(Source, source_id)).status = SourceStatus.DELETING + await session.commit() + draft = await client.put( + "/api/v1/system/model-config", headers=headers, + json={"jev_endpoint": "https://draft.example/score"}, + ) + assert draft.status_code == 200, draft.text + finally: + async with SessionLocal() as session: + await session.execute(delete(Source).where(Source.id == source_id)) + await session.commit() + + @pytest.mark.parametrize( ("relational_provider", "vector_provider", "endpoint", "expected_code"), [ @@ -291,10 +365,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 +390,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 +592,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..d4ad7f5e 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") @@ -217,7 +227,8 @@ async def test_agent_uses_global_jev_and_preserves_order_and_stats(monkeypatch, async def retrieve(manager, sources, query, *, strategy, top_k): calls.append(strategy) - assert manager._effective_search_strategy(strategy) == "multi_jev" + expected = "multi_jev" if persona.get("search_strategy") else "auto" + assert manager._effective_search_strategy(strategy) == expected return SearchOutcome(query=query, sections=[hit("first", 0.2), hit("second", 0.1)], stats={"ranking": {"method": "jev", "fallback_reason": None}}) @@ -242,7 +253,7 @@ async def reorder(*args, **kwargs): result = await builtin.SearchContextTool().invoke( {"query": "q"}, ToolContext(engine_manager=engine, sources=[source], persona=persona), ) - assert calls == ["multi_jev"] + assert calls == ["retired_custom_mode" if persona.get("search_strategy") else "auto"] assert [section.chunk_id for section in result.data["sections"]] == ["first", "second"] assert result.data["retrieval_stats"]["ranking"]["method"] == "jev" diff --git a/apps/api/tests/test_jev_transports.py b/apps/api/tests/test_jev_transports.py index 86e4f076..83d09fec 100644 --- a/apps/api/tests/test_jev_transports.py +++ b/apps/api/tests/test_jev_transports.py @@ -63,13 +63,14 @@ async def test_agent_tool_keeps_the_strategy_selected_when_the_run_was_prepared( class RecordingSearchTool(SearchTool): async def invoke(self, _arguments, context): - used.append(context.persona.get("search_strategy")) + used.append(context.search_strategy_snapshot) + assert context.persona == {} # Freezing a run must not rewrite the persona. return ToolResult(content="evidence") adapted = _adapt_tool(RecordingSearchTool(), ToolContext(engine_manager=object()), []) active.search_strategy = "multi_jev" await adapted.execute({}, SimpleNamespace(cancellation=SimpleNamespace(raise_if_cancelled=lambda: None))) - assert used == ["vector"] + assert used == [("auto", "global")] @pytest.mark.asyncio diff --git a/apps/api/tests/test_retrieval_relevance.py b/apps/api/tests/test_retrieval_relevance.py index 83267238..d07c2c73 100644 --- a/apps/api/tests/test_retrieval_relevance.py +++ b/apps/api/tests/test_retrieval_relevance.py @@ -335,7 +335,7 @@ async def grep_chunks(self, source_config_id, term, **_kwargs): @pytest.mark.asyncio -async def test_total_latency_includes_query_analysis(monkeypatch): +async def test_total_latency_includes_query_analysis(monkeypatch, publication_source): from types import SimpleNamespace from sag_api.core.db import init_db @@ -360,10 +360,11 @@ async def search_many(self, _targets, query, **_kwargs): ) await init_db() + source = await publication_source("latency", "cfg-latency", "doc-latency") outcome = await retrieval_service.retrieve_relevant_sections( EmptyEngine(), - [], - "肉类清汤", + [source], + "肉类清汤", strategy="vector", ) assert outcome.stats["latency_total_ms"] == 250.0 diff --git a/apps/api/tests/test_sag2_engine_integration.py b/apps/api/tests/test_sag2_engine_integration.py new file mode 100644 index 00000000..8fcaf900 --- /dev/null +++ b/apps/api/tests/test_sag2_engine_integration.py @@ -0,0 +1,225 @@ +"""Run zleap-sag2 read-only against a real zleap-sag SQLite store with an offline scorer.""" + +import sqlite3 +from types import SimpleNamespace + +import pytest + +from sag_api.core.config import Settings +from sag_api.core.errors import ConfigurationError, ValidationError +from sag_api.sag.sag2_engine import Sag2EngineHolder + +QUERY = "Alice 出生在哪里?" + + +class OverlapScorer: + """Mimic zleap-sag2's ``JevScoring.score`` contract with query-term overlap; no network.""" + + def __init__(self) -> None: + self.calls = 0 + + async def score(self, query, candidates, evidence): + self.calls += 1 + terms = [term for term in ("Alice", "出生", "北京") if term in query] + scored = [] + for candidate in candidates: + text = f"{candidate.get('title', '')} {candidate.get('heading', '')} {candidate.get('content', '')}" + overlap = sum(term in text for term in terms) + scored.append({**candidate, "jev_score": round(min(1.0, 0.1 + 0.3 * overlap), 4)}) + usage = { + "requests": 1, "judgments": len(candidates), "input_tokens": 100 * len(candidates), + "output_tokens": 0, "batches": [{"judgments": len(candidates)}], + } + return scored, usage + + +async def seed_sag_store(data_dir) -> None: + """Create the zleap-sag schema and publish one managed document, one retired generation, one legacy source.""" + from zleap.sag import DataEngine + from zleap.sag.db import models as m + + from sag_api.sag.config_builder import build_engine_config + + config = build_engine_config(Settings(_env_file=None), overrides={"data_dir": str(data_dir)}) + engine = DataEngine(config, data_source_id="cfg-1", health_check=False) + await engine.init_schema() + await engine.start() + try: + factory = engine.resources.relational.session_factory() + async with factory() as session: + session.add(m.DataSource(id="cfg-1", name="demo")) + session.add(m.SAGDataSourceManifest(data_source_id="cfg-1", revision=1, active=True)) + session.add(m.Article( + id="doc1", data_source_id="cfg-1", title="Alice 的生平", + extra_data={"sag_pipeline": {"generation_id": "gen1", "source_type": "article"}}, + )) + session.add(m.SAGSourceManifest( + data_source_id="cfg-1", source_id="doc1", source_type="article", active_generation_id="gen1", + operation_id="op1", fence_scope="cfg-1", fence_token=1, status="ready", + chunk_count=3, event_count=0, revision=1, + )) + rows = [ + ("c1", "gen1", "出生", "Alice 出生在北京,1990 年随家人移居上海。", 0), + ("c2", "gen1", "教育", "Alice 在复旦大学学习计算机科学。", 1), + ("c3", "gen1", "工作", "Bob 是 Alice 的同事。", 2), + ("c0-stale", "gen0", "旧版本", "Alice 出生在广州(已退役版本)。", 0), + ] + for chunk_id, generation, heading, content, rank in rows: + session.add(m.SourceChunk( + id=chunk_id, data_source_id="cfg-1", source_type="article", source_id="doc1", + generation_id=generation, article_id="doc1", content=content, heading=heading, rank=rank, + chunk_length=len(content), references=[], + extra_data={"title": "Alice 的生平", "chunk_type": "TEXT"}, + )) + session.add(m.Article(id="legacy1", data_source_id="cfg-1", title="旧文档")) + session.add(m.SourceChunk( + id="l1", data_source_id="cfg-1", source_type="article", source_id="legacy1", generation_id=None, + article_id="legacy1", content="没有 manifest 的旧来源段落,提到 Alice 喜欢咖啡。", heading="", + rank=0, chunk_length=24, extra_data={}, references=[], + )) + await session.commit() + finally: + await engine.aclose() + + +def sag2_settings(data_dir, **changes) -> Settings: + return Settings(_env_file=None).model_copy(update={ + "data_dir": str(data_dir), + "jev_endpoint": "https://jev.invalid/score", + "jev_api_key": "synthetic-jev-key", + "search_strategy": "sag2", + "sag2_candidate_k": 20, + **changes, + }) + + +async def run_search(holder: Sag2EngineHolder, source_ids_by_config): + return await holder.search( + [("cfg-1", None)], QUERY, top_k=5, requested_sources=1, source_limit_applied=False, + source_ids_by_config=source_ids_by_config, + ) + + +@pytest.mark.asyncio +async def test_sag2_reads_published_sag_chunks_in_place(tmp_path): + await seed_sag_store(tmp_path) + scorer = OverlapScorer() + holder = Sag2EngineHolder(sag2_settings(tmp_path), scorer_factory=lambda _config: scorer) + try: + outcome = await run_search(holder, {"cfg-1": ("doc1", "legacy1")}) + ids = [section.chunk_id for section in outcome.sections] + assert ids[0] == "c1" + assert "c0-stale" not in ids # retired generation stays invisible + assert "l1" in ids # legacy source without a manifest remains searchable + first = outcome.sections[0] + assert (first.source_config_id, first.source_id, first.heading) == ("cfg-1", "doc1", "出生") + assert all(section.metadata["score_source"] == "jev" for section in outcome.sections) + assert outcome.stats["effective_strategy"] == "sag2" + assert outcome.stats["jev_usage"]["judgments"] >= 4 + assert outcome.stats["sag2"]["scope_chunks"] == 4 + assert scorer.calls >= 1 + + # Publication pointers scope the request before scoring. + scoped = await run_search(holder, {"cfg-1": ("doc1",)}) + assert "l1" not in [section.chunk_id for section in scoped.sections] + assert [section.chunk_id for section in scoped.sections][0] == "c1" + + # Read-only attach: only the two auxiliary tables are added to the SAG database. + connection = sqlite3.connect(tmp_path / "sag.db") + try: + names = { + row[0] for row in connection.execute( + "select name from sqlite_master where type='table' and name like 'sag2%'", + ) + } + finally: + connection.close() + assert names == {"sag2_state", "sag2_search_sessions"} + assert holder.started + finally: + await holder.aclose() + assert not holder.started + + +@pytest.mark.asyncio +async def test_sag2_refuses_to_start_on_an_uninitialised_workspace(tmp_path): + holder = Sag2EngineHolder(sag2_settings(tmp_path / "missing")) + with pytest.raises(ConfigurationError) as error: + await run_search(holder, None) + assert error.value.code == "sag2_storage_not_ready" + assert not (tmp_path / "missing" / "sag.db").exists() + + +@pytest.mark.asyncio +async def test_scope_guard_ignores_retired_rows_but_keeps_whole_source_scan_limit(tmp_path): + await seed_sag_store(tmp_path) + with sqlite3.connect(tmp_path / "sag.db") as connection: + # Reprocessing can leave many retired generations awaiting cleanup. + connection.executemany( + "INSERT INTO source_chunk (id, data_source_id, source_id, source_type, generation_id, " + "article_id, content, rank, chunk_length) VALUES (?, 'cfg-1', 'doc1', 'article', " + "'retired', 'doc1', 'retired evidence', 0, 16)", + [(f"retired-{i}",) for i in range(20_001)], + ) + scorer = OverlapScorer() + holder = Sag2EngineHolder(sag2_settings(tmp_path), scorer_factory=lambda _config: scorer) + try: + outcome = await run_search(holder, {"cfg-1": ("doc1",)}) + assert outcome.sections[0].chunk_id == "c1" + assert outcome.stats["sag2"]["scope_chunks"] == 4 + # Selecting one document does not narrow SDK 0.1.0's namespace scan. + holder._settings.sag2_max_scope_chunks = 3 + calls = scorer.calls + with pytest.raises(ValidationError, match="信源扫描范围"): + await run_search(holder, {"cfg-1": ("legacy1",)}) + assert scorer.calls == calls + finally: + await holder.aclose() + + +@pytest.mark.asyncio +@pytest.mark.parametrize("managed", [False, True]) +async def test_scope_count_matches_sdk_loaded_rows_including_legacy_schemas(tmp_path, managed): + from sqlalchemy import create_engine + from sqlalchemy.ext.asyncio import create_async_engine + from zleap.sag2._sag1 import Sag1Reader + + path = tmp_path / "scope.db" + with sqlite3.connect(path) as connection: + connection.execute( + "CREATE TABLE source_chunk (id TEXT, data_source_id TEXT, source_id TEXT, source_type TEXT, " + "content TEXT, rank INTEGER" + (", generation_id TEXT" if managed else "") + ")", + ) + if managed: + connection.execute( + "CREATE TABLE sag_source_manifest (data_source_id TEXT, source_id TEXT, " + "status TEXT, active_generation_id TEXT)", + ) + connection.execute("INSERT INTO sag_source_manifest VALUES ('A', 'doc', 'ready', 'current')") + connection.execute("CREATE TABLE sag_data_source_manifest (data_source_id TEXT, active BOOLEAN)") + connection.execute("INSERT INTO sag_data_source_manifest VALUES ('inactive', 0)") + rows = [("current", "A", "doc", "article", "text", 0), + ("legacy", "A", "legacy", "article", "text", 0), + ("other", "B", "doc", "article", "text", 0)] + if managed: + rows = [(*row, "current" if row[0] == "current" else None) for row in rows] + rows += [("retired", "A", "doc", "article", "text", 0, "old"), + ("staging", "A", "new", "article", "text", 0, "unpublished"), + ("inactive", "inactive", "doc", "article", "text", 0, None)] + connection.executemany("INSERT INTO source_chunk VALUES (" + ",".join("?" * len(rows[0])) + ")", rows) + sync_engine = create_engine(f"sqlite:///{path}") + try: + with sync_engine.connect() as connection: + reader = Sag1Reader.detect(connection) + finally: + sync_engine.dispose() + engine = create_async_engine(f"sqlite+aiosqlite:///{path}") + holder_engine = SimpleNamespace(store=SimpleNamespace(engine=engine, sag1_reader=reader)) + try: + for sources, expected in [(["A"], 2), (["B"], 1), (["inactive"], 0), (["A", "inactive"], 2), ([], 0)]: + async with engine.connect() as connection: + loaded = await reader._rows(connection, "source_chunk", sources) + assert len(loaded) == expected + assert await Sag2EngineHolder._count_scope(holder_engine, sources) == expected + finally: + await engine.dispose() diff --git a/apps/api/tests/test_sag2_native_engine.py b/apps/api/tests/test_sag2_native_engine.py new file mode 100644 index 00000000..ac355319 --- /dev/null +++ b/apps/api/tests/test_sag2_native_engine.py @@ -0,0 +1,269 @@ +"""Real SQLite lifecycle tests: no LLM, embedding, or JEV needed for native indexing.""" + +import os +from pathlib import Path + +import pytest +from zleap.sag.operations import DeleteSourceRequest, OperationContext +from zleap.sag.operations import OperationContext as Sag2Context + +from sag_api.core.config import Settings +from sag_api.sag.incremental_processor import IncrementalDocumentProcessor +from sag_api.sag.sag2_source_engine import Sag2SourceEngine + + +@pytest.mark.asyncio +@pytest.mark.parametrize("provider", ["sqlite", "postgres"]) +async def test_native_index_replay_read_and_delete_without_models(tmp_path, provider): + if provider == "postgres" and not os.getenv("SAG_NATIVE_POSTGRES_PORT"): + pytest.skip("requires dedicated native PostgreSQL test container") + settings = Settings( + _env_file=None, data_dir=str(tmp_path), jev_endpoint=None, jev_api_key=None, + sag_relational_provider=provider, sag_pg_host="127.0.0.1", + sag_pg_port=int(os.getenv("SAG_NATIVE_POSTGRES_PORT", "5432")), + sag_pg_user="postgres", sag_pg_password="pr253-disposable", sag_pg_database="sag_native", + ) + engine = Sag2SourceEngine(settings, "src_native") + await engine.start() + try: + path = tmp_path / "manual.md" + path.write_text("# 星港设备维护\nZX-253 每隔14天校准,负责人林澈。") + processor = IncrementalDocumentProcessor(engine, "src_native", max_concurrency=1, language="zh") + request = await processor.build_request( + path, + context=OperationContext( + operation_id="op-native", + idempotency_key="op-native", + request_digest="0" * 64, + fence_scope="src_native", + fence_token=1, + owner_id="test", + isolation="input", + ), + input_id="doc-native", + ) + result = await engine.process_source(request) + assert result.status == "succeeded", result.failure_message + assert result.result["event_ref"]["event_ids"] == [] + assert result.result["event_ref"]["entity_ids"] == [] + chunk = result.result["chunk_ref"] + assert chunk["chunk_ids"] + assert (await engine.get_operation_status("op-native")).operation_id == result.operation_id + replay = await engine.process_source(request) + assert replay.result == result.result + stored = await engine.read_chunk("doc-native", chunk["chunk_ids"][0], data_source_id="src_native") + assert "ZX-253" in stored.content + await engine.delete_source( + DeleteSourceRequest( + context=Sag2Context( + operation_id="del-native", + idempotency_key="del-native", + request_digest="0" * 64, + fence_scope="src_native", + fence_token=1, + owner_id="test", + ), + data_source_id="src_native", + source_id="doc-native", + ) + ) + assert await engine.read_chunk("doc-native", chunk["chunk_ids"][0], data_source_id="src_native") is None + assert not (Path(settings.data_dir) / "sag.db").exists() + finally: + await engine.aclose() + + +@pytest.mark.asyncio +async def test_manager_provisions_native_engine_without_sag1_store(tmp_path): + from types import SimpleNamespace + + from sag_api.sag.engine_manager import EngineManager + + settings = Settings(_env_file=None, data_dir=str(tmp_path), jev_endpoint=None, jev_api_key=None) + manager = EngineManager(settings) + source = SimpleNamespace(engine_kind="sag2", config={}, name="native", description="") + try: + await manager.provision("src_manager", source) + assert isinstance(manager._slots["src_manager"].engine, Sag2SourceEngine) + timeline = await manager.universe_timeline( + "src_manager", source_ids=(), source_revision="native-revision", source=source, + ) + assert timeline.total_events == 0 + assert timeline.bundles == [] + assert not (tmp_path / "sag.db").exists() + finally: + await manager.release("src_manager") + + +from tests.test_source_default_strategy import source_client # noqa: E402,F401 + + +@pytest.mark.asyncio +async def test_sag2_upload_job_publishes_zero_events_without_model_keys(source_client): # noqa: F811 + import asyncio + + from sag_api.main import app + + created = await source_client.post("/api/v1/sources", json={"name": "Native job", "engine_kind": "sag2"}) + assert created.status_code == 201, created.text + source = created.json() + uploaded = await source_client.post( + f"/api/v1/sources/{source['id']}/documents", + files={"file": ("manual.md", b"# Native\nZX-253 calibrates every 14 days.", "text/markdown")}, + ) + assert uploaded.status_code == 201, uploaded.text + await asyncio.wait_for(app.state.job_queue._queue.join(), 20) + document = (await source_client.get(f"/api/v1/sources/{source['id']}/documents/{uploaded.json()['id']}")).json() + assert document["status"] == "ready", document + assert document["event_count"] == 0 + assert document["chunk_count"] > 0 + base = f"/api/v1/sources/{source['id']}" + doc = f"{base}/documents/{uploaded.json()['id']}" + for endpoint in [f"{base}/octx-exports", f"{doc}/octx-exports"]: + blocked = await source_client.post(endpoint, json={}) + assert blocked.status_code == 422, blocked.text + assert "SAG2" in blocked.text + outline = await source_client.get(f"{base}/outline", params={"document_id": uploaded.json()["id"]}) + assert outline.status_code == 200, outline.text + reprocess = await source_client.post(f"{doc}/reprocess") + assert reprocess.status_code == 200, reprocess.text + await asyncio.wait_for(app.state.job_queue._queue.join(), 20) + republished = (await source_client.get(doc)).json() + assert republished["status"] == "ready", republished + assert republished["event_count"] == 0 + deleted = await source_client.delete(doc) + assert deleted.status_code == 202, deleted.text + await asyncio.wait_for(app.state.job_queue._queue.join(), 20) + assert (await source_client.get(doc)).status_code == 404 + async def completed_job(response): + async with asyncio.timeout(20): + while True: + current = (await source_client.get(f"/api/v1/jobs/{response.json()['id']}")).json() + if current["status"] in {"succeeded", "failed"}: + return current + await asyncio.sleep(0.02) + deletion = await completed_job(deleted) + assert deletion["status"] == "succeeded", deletion + whole = await source_client.delete(base) + assert whole.status_code == 202, whole.text + await asyncio.wait_for(app.state.job_queue._queue.join(), 20) + source_deletion = await completed_job(whole) + assert source_deletion["status"] == "succeeded", source_deletion + from sag_api.core.db import SessionLocal + from sag_api.db.models import Source + async with SessionLocal() as session: + assert await session.get(Source, source["id"]) is None + + +@pytest.mark.asyncio +async def test_native_search_only_uses_published_inputs_and_maps_business_source(tmp_path): + from sag_api.sag.sag2_native_search import Sag2NativeSearchHolder + from tests.test_sag2_engine_integration import OverlapScorer + + settings = Settings( + _env_file=None, data_dir=str(tmp_path), jev_endpoint="https://jev.invalid/score", jev_api_key="test" + ) + engine = Sag2SourceEngine(settings, "cfg-native") + await engine.start() + refs = {} + try: + for input_id in ["published", "candidate"]: + path = tmp_path / f"{input_id}.md" + path.write_text(f"# {input_id}\nAlice 出生在北京,1990年移居上海。") + processor = IncrementalDocumentProcessor(engine, "cfg-native", max_concurrency=1, language="zh") + req = await processor.build_request( + path, + context=OperationContext( + operation_id=input_id, + idempotency_key=input_id, + request_digest="0" * 64, + fence_scope="cfg-native", + fence_token=1, + owner_id="test", + isolation="input", + ), + input_id=input_id, + ) + result = await engine.process_source(req) + assert result.status == "succeeded", result.failure_message + refs[input_id] = result.result["chunk_ref"]["chunk_ids"] + holder = Sag2NativeSearchHolder(settings, scorer_factory=lambda _cfg: OverlapScorer()) + try: + outcome = await holder.search( + [("cfg-native", None)], + "Alice 出生在哪?", + top_k=5, + requested_sources=1, + source_limit_applied=False, + source_ids_by_config={"cfg-native": ("published",)}, + ) + assert outcome.sections + assert all(section.source_id == "published" for section in outcome.sections) + assert all(section.source_config_id == "cfg-native" for section in outcome.sections) + assert refs["candidate"][0] not in {section.chunk_id for section in outcome.sections} + finally: + await holder.aclose() + finally: + await engine.aclose() + + +@pytest.mark.asyncio +async def test_native_cancel_is_retryable_and_resume_is_not_invalidated_by_another_input(tmp_path): + from zleap.sag.pipeline import CancellationToken + settings = Settings(_env_file=None, data_dir=str(tmp_path), jev_endpoint=None, jev_api_key=None) + engine = Sag2SourceEngine(settings, "cancel-source") + await engine.start() + try: + path = tmp_path / "pause.md" + path.write_text("# Native pause\nEvidence for document resume.") + processor = IncrementalDocumentProcessor(engine, "cancel-source", max_concurrency=1, language="zh") + async def request(identifier): + return await processor.build_request(path, context=OperationContext( + operation_id=identifier, idempotency_key=identifier, request_digest="0"*64, + fence_scope="cancel-source", fence_token=1, owner_id="test", isolation="input", + ), input_id=identifier) + cancellation = CancellationToken() + async def observer(event): + if event.stage == "chunk": + cancellation.cancel() + first = await request("paused-input") + paused = await engine.process_source(first, observer=observer, cancellation=cancellation) + assert paused.retryable is True + assert paused.failure_code == "cancelled" + assert (await engine.process_source(await request("other-input"))).status == "succeeded" + resumed = await engine.process_source(first) + assert resumed.status == "succeeded", resumed.failure_message + finally: + await engine.aclose() + + +@pytest.mark.asyncio +@pytest.mark.parametrize("kind", ["document", "source"]) +async def test_native_deletion_receipts_authorize_application_cleanup(tmp_path, kind): + from zleap.sag.operations import DeleteDataSourceRequest + + from sag_api.jobs.tasks import _require_delete_completion + + engine = Sag2SourceEngine(Settings(_env_file=None, data_dir=str(tmp_path)), "delete-source") + await engine.start() + try: + document_request = DeleteSourceRequest( + context=OperationContext( + operation_id="delete-undispatched", idempotency_key="delete-undispatched", + request_digest="0" * 64, fence_scope="delete-source", fence_token=1, owner_id="test", + ), data_source_id="delete-source", source_id="never-dispatched", + ) + if kind == "document": + document_receipt = await engine.delete_source(document_request) + _require_delete_completion(document_request, document_receipt) + return + request = DeleteDataSourceRequest( + context=OperationContext( + operation_id="delete-all", idempotency_key="delete-all", request_digest="0" * 64, + fence_scope="delete-source", fence_token=1, owner_id="test", + ), data_source_id="delete-source", + ) + receipt = await engine.delete_data_source(request) + _require_delete_completion(request, receipt) + finally: + await engine.aclose() diff --git a/apps/api/tests/test_sag2_octx_policy.py b/apps/api/tests/test_sag2_octx_policy.py new file mode 100644 index 00000000..f3b3155e --- /dev/null +++ b/apps/api/tests/test_sag2_octx_policy.py @@ -0,0 +1,16 @@ +from types import SimpleNamespace + +import pytest + +from sag_api.core.errors import ValidationError +from sag_api.services.knowledge_algorithms import require_sag1_octx + + +def test_legacy_sources_keep_octx_support(): + require_sag1_octx(SimpleNamespace()) + require_sag1_octx(SimpleNamespace(engine_kind="sag1")) + + +def test_sag2_rejects_octx_operations(): + with pytest.raises(ValidationError, match="SAG2"): + require_sag1_octx(SimpleNamespace(engine_kind="sag2")) diff --git a/apps/api/tests/test_sag2_retrieval.py b/apps/api/tests/test_sag2_retrieval.py new file mode 100644 index 00000000..76814d0d --- /dev/null +++ b/apps/api/tests/test_sag2_retrieval.py @@ -0,0 +1,634 @@ +"""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") + source.engine_kind = "sag2" + + 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"] == "auto" + assert result.stats["publication_filtered"] == 1 + assert result.stats["lexical_candidates"] == 0 + + +@pytest.mark.asyncio +async def test_agent_auto_routes_native_and_gets_whole_search_budget(monkeypatch, publication_source): + from sag_api.services.agent_tooling import _adapt_tool + from sag_api.tools import builtin + from sag_api.tools.base import ToolContext + + source = await publication_source("sag2-agent", "cfg-1", "document-1") + source.engine_kind = "sag2" + engine = EngineManager(sag2_settings( + search_strategy="sag2", agent_tool_timeout_seconds=5, sag2_search_timeout_seconds=90, + )) + calls = [] + + async def retrieve(manager, sources, query, *, strategy, top_k): + calls.append(strategy) + assert strategy == "auto" + return SearchOutcome(query=query, sections=[hit("first", 0.2), hit("second", 0.1)], stats={ + "effective_strategy": "sag2", "ranking": {"method": "jev", "fallback_reason": None}, + }) + + 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 == ["auto"] + assert [section.chunk_id for section in result.data["sections"]] == ["first", "second"] + assert result.data["retrieval_stats"]["effective_strategy"] == "sag2" + + adapted = _adapt_tool( + builtin.SearchContextTool(), ToolContext(engine_manager=engine, sources=[source], 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_search_strategy.py b/apps/api/tests/test_search_strategy.py index e259f27c..816fe40b 100644 --- a/apps/api/tests/test_search_strategy.py +++ b/apps/api/tests/test_search_strategy.py @@ -548,7 +548,7 @@ def test_strategies_capability_report_marks_multi_es_disabled_on_pgvector(monkey monkeypatch.setattr(settings, "sag_vector_provider", "pgvector") report = EngineManager.strategies_capability_report(settings) - assert set(report["enabled"]) == {"vector", "multi"} + assert set(report["enabled"]) == {"auto", "vector", "multi"} assert "multi_es_fast" in report["disabled"] disabled_entry = report["disabled"]["multi_es_fast"] assert disabled_entry["reason"] == "vector_provider_lacks_lexical" @@ -556,7 +556,7 @@ def test_strategies_capability_report_marks_multi_es_disabled_on_pgvector(monkey monkeypatch.setattr(settings, "sag_vector_provider", "lancedb") ok_report = EngineManager.strategies_capability_report(settings) - assert set(ok_report["enabled"]) == {"vector", "multi", "multi_es_fast"} + assert set(ok_report["enabled"]) == {"auto", "vector", "multi", "multi_es_fast"} assert ok_report["disabled"]["multi_jev"]["reason"] == "jev_not_configured" diff --git a/apps/api/tests/test_source_default_strategy.py b/apps/api/tests/test_source_default_strategy.py new file mode 100644 index 00000000..1a52508a --- /dev/null +++ b/apps/api/tests/test_source_default_strategy.py @@ -0,0 +1,96 @@ +"""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.services.retrieval_service import ( + resolve_search_strategy, +) +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_default_resolution_ignores_retired_per_source_preferences(): + configuration = configured(search_strategy="vector") + scoped = [source("sag2"), source("sag2", "cfg-2")] + assert resolve_search_strategy(configuration=configuration, sources=scoped).strategy == "auto" + assert knowledge_search_strategy({}, configuration, scoped) == "auto" + assert resolve_search_strategy(requested="multi", configuration=configuration, sources=scoped).strategy == "multi" + + +@pytest.mark.asyncio +@pytest.mark.parametrize("engine_kind", ["sag1", "sag2"]) +async def test_source_algorithm_is_fixed_but_metadata_remains_editable(source_client, engine_kind): + created = await source_client.post("/api/v1/sources", json={"name": "Engine binding", "engine_kind": engine_kind}) + assert created.status_code == 201, created.text + source_id = created.json()["id"] + assert created.json()["engine_kind"] == engine_kind + changed = await source_client.patch(f"/api/v1/sources/{source_id}", json={"name": "Renamed"}) + assert changed.status_code == 200 + assert changed.json()["engine_kind"] == engine_kind + for replacement in ["sag1", "sag2"]: + rejected = await source_client.patch(f"/api/v1/sources/{source_id}", json={"engine_kind": replacement}) + assert rejected.status_code == 422 + assert (await source_client.get(f"/api/v1/sources/{source_id}")).json()["engine_kind"] == engine_kind + + +@pytest.mark.asyncio +async def test_retired_source_default_mode_is_not_an_editable_setting(source_client): + created = await source_client.post("/api/v1/sources", json={"name": "Default SAG1"}) + assert created.status_code == 201 + assert created.json()["engine_kind"] == "sag1" + rejected = await source_client.patch( + f"/api/v1/sources/{created.json()['id']}", json={"default_search_strategy": "sag2"} + ) + assert rejected.status_code == 422 diff --git a/apps/api/tests/test_source_engine_binding.py b/apps/api/tests/test_source_engine_binding.py new file mode 100644 index 00000000..f6bcddf1 --- /dev/null +++ b/apps/api/tests/test_source_engine_binding.py @@ -0,0 +1,33 @@ +"""Knowledge algorithms are chosen once, independently of retrieval preferences.""" + +import pytest +from pydantic import ValidationError + +from sag_api.core.db import _COLUMN_UPGRADES +from sag_api.db.models import Source +from sag_api.schemas.source import SourceCreate, SourceUpdate + + +def test_source_creation_defaults_to_sag1(): + assert SourceCreate(name="legacy compatible").engine_kind == "sag1" + + +@pytest.mark.parametrize("kind", ["sag1", "sag2"]) +def test_source_creation_accepts_two_algorithms(kind): + assert SourceCreate(name="test", engine_kind=kind).engine_kind == kind + + +@pytest.mark.parametrize("kind", ["vector", "multi", "multi_jev", "invalid"]) +def test_source_creation_rejects_retrieval_strategy_as_algorithm(kind): + with pytest.raises(ValidationError): + SourceCreate(name="test", engine_kind=kind) + + +def test_edit_cannot_change_algorithm(): + with pytest.raises(ValidationError): + SourceUpdate(engine_kind="sag1") + + +def test_legacy_source_migration_does_not_infer_sag2_from_preference(): + assert _COLUMN_UPGRADES["sources"]["engine_kind"] == "VARCHAR(16) NOT NULL DEFAULT 'sag1'" + assert str(Source.__table__.c.engine_kind.server_default.arg) == "sag1" diff --git a/apps/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..94e79085 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 { KnowledgeEnginePill } from "@/components/features/knowledge-engine-pill"; import { RetrievalTestDialog } from "@/components/features/retrieval-test-dialog"; import { SourceIdCopy } from "@/components/features/source-id-copy"; import { SourceGraph } from "@/components/features/source-graph"; @@ -123,9 +124,12 @@ export default function SourceDetailPage() { {source ? ( <> -

- {source.name} -

+
+

+ {source.name} +

+ +

{t("sourceStats", { documents: source.document_count, @@ -186,9 +190,9 @@ export default function SourceDetailPage() { variant="outline" size="icon" onClick={handleExport} - disabled={!source || exportRunning} + disabled={!source || exportRunning || source.engine_kind === "sag2"} aria-label={tCard("export")} - title={tCard("export")} + title={source?.engine_kind === "sag2" ? tCard("sag2OctxUnsupported") : tCard("export")} > {exportRunning ? ( @@ -197,7 +201,7 @@ export default function SourceDetailPage() { )} - {tCard("export")} + {source?.engine_kind === "sag2" ? tCard("sag2OctxUnsupported") : tCard("export")} @@ -279,6 +283,7 @@ export default function SourceDetailPage() { @@ -288,6 +293,7 @@ export default function SourceDetailPage() { @@ -303,7 +309,7 @@ export default function SourceDetailPage() { ))} - ) : graphViewActive ? ( + ) : graphViewActive && source.engine_kind !== "sag2" ? (

) : ( {isFileSource - ? t("addDialogDescription") + ? t(source?.engine_kind === "sag2" ? "sag2UploadDescription" : "addDialogDescription") : t("syncDialogDescription")} @@ -357,6 +364,7 @@ export default function SourceDetailPage() { (source.connector_kind === "file_upload" ? (
{ dismissFolderImportDialog( 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..d3e0ec48 100644 --- a/apps/web/components/features/app-shell.tsx +++ b/apps/web/components/features/app-shell.tsx @@ -34,9 +34,7 @@ import { import { DEFAULT_TIME_ZONE } from "@/lib/format"; import { PetAgent } from "@/lib/pet-agent"; import { - DEFAULT_SEARCH_STRATEGY, getSearchStrategiesDisabled, - isSearchStrategy, } from "@/lib/retrieval-config"; import { SIDEBAR_THREADS_PAGE_SIZE, @@ -133,6 +131,7 @@ const CONVERSATION_TRANSPORT: ConversationTransport = { sourceIds, knowledgeOnly, webEnabled, + strategy, onEvent, signal, }) => { @@ -145,6 +144,7 @@ const CONVERSATION_TRANSPORT: ConversationTransport = { attachment_count: attachmentIds?.length ?? 0, source_ids: sourceIds, web_enabled: webEnabled, + strategy, }); const promise = streamAgentAsk( agentId, @@ -155,6 +155,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 @@ -823,11 +825,7 @@ export function AppShell({ children }: { children: React.ReactNode }) { > diff --git a/apps/web/components/features/chat/conversation-panel.test.tsx b/apps/web/components/features/chat/conversation-panel.test.tsx index 2be334eb..75e2dd50 100644 --- a/apps/web/components/features/chat/conversation-panel.test.tsx +++ b/apps/web/components/features/chat/conversation-panel.test.tsx @@ -6,35 +6,50 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import english from "@/messages/en-US.json"; import type { ConversationMessage, ConversationSessionSnapshot } from "@/lib/conversation-runtime"; -import type { MessageSourceScope, Source } from "@/lib/types"; +import { AgentHttpError } from "@/lib/sse"; +import type { Agent, Capabilities, MessageSourceScope, Source } from "@/lib/types"; import { ConversationPanel } from "./conversation-panel"; const state = vi.hoisted(() => ({ snapshot: null as ConversationSessionSnapshot | null, send: vi.fn(), activate: vi.fn(), ensureHistory: vi.fn(), setInput: vi.fn(), + toastError: vi.fn(), setImages: vi.fn(), uploadAttachment: vi.fn(), + runtimeRun: {} as object | null, + input: "Unsent draft", images: [] as { file: File; url: string }[], sources: [] as Source[], + scoped: [{ id: "composer-source", name: "Composer selection" }], + capabilities: { llm_configured: true } as Partial, + agent: null as Agent | null, })); +const catalog = english as unknown as Record>; vi.mock("next-intl", () => ({ useLocale: () => "en-US", - useTranslations: () => (key: keyof typeof english.Conversation) => english.Conversation[key] ?? key, + useTranslations: (namespace: string) => (key: string, values?: Record) => + (catalog[namespace]?.[key] ?? key).replace(/\{(\w+)\}/g, (_, name: string) => String(values?.[name] ?? "")), })); +vi.mock("next/link", () => ({ + default: React.forwardRef>( + function Link({ children, href, ...props }, ref) { return {children}; }, + ), +})); +vi.mock("sonner", () => ({ toast: { error: state.toastError, success: vi.fn() } })); vi.mock("@/components/features/app-shell", () => ({ - useApp: () => ({ capabilities: { llm_configured: true }, timezone: "UTC" }), + useApp: () => ({ capabilities: state.capabilities, agent: state.agent, timezone: "UTC" }), })); vi.mock("./conversation-provider", () => ({ useConversationSession: () => state.snapshot, useConversationRuntime: () => ({ activate: state.activate, ensureHistory: state.ensureHistory, send: state.send, getIndexSnapshot: () => ({ activeRunSessionId: null }), - getSessionSnapshot: () => ({ run: {} }), + getSessionSnapshot: () => ({ run: state.runtimeRun }), }), useConversationComposer: () => ({ - input: "Unsent draft", scoped: [{ id: "composer-source", name: "Composer selection" }], - images: [], webEnabled: false, setInput: state.setInput, - setImages: vi.fn(), setScoped: vi.fn(), setWebEnabled: vi.fn(), + input: state.input, scoped: state.scoped, + images: state.images, webEnabled: false, setInput: state.setInput, + setImages: state.setImages, setScoped: vi.fn(), setWebEnabled: vi.fn(), }), })); -vi.mock("@/lib/api", () => ({ api: { listSources: async () => state.sources } })); +vi.mock("@/lib/api", () => ({ api: { listSources: async () => state.sources, uploadAttachment: state.uploadAttachment } })); vi.mock("@/components/features/detail-panel", () => ({ useDetailPanel: () => ({ open: vi.fn() }) })); vi.mock("@/components/features/markdown-content", () => ({ MarkdownContent: ({ content }: { content: string }) =>
{content}
, @@ -42,16 +57,55 @@ vi.mock("@/components/features/markdown-content", () => ({ vi.mock("./prompt-preview", () => ({ PromptPreview: () => null })); vi.mock("./agent-activity-timeline", () => ({ AgentActivityTimeline: () => null })); +const ALL_STRATEGIES = ["auto", "vector", "multi_es_fast", "multi", "multi_jev", "sag2"] as const; +const emptySession: ConversationSessionSnapshot = { + sessionId: "session-1", agentId: "agent-1", threadId: "thread-1", error: null, run: null, + history: { status: "ready", requestId: 0, hasMore: false, nextCursor: null, error: null }, messages: [], +}; +function source(id: string, defaultStrategy: Source["default_search_strategy"] = null, status = "active"): Source { + return { + id, name: id, description: "", source_type: "document", connector_kind: "file_upload", + status, default_search_strategy: defaultStrategy, document_count: 0, chunk_count: 0, event_count: 0, + created_at: "2026-10-09T00:00:00Z", updated_at: "2026-10-09T00:00:00Z", + } as Source; +} +function agent(searchStrategy?: string): Agent { + return { + id: "agent-1", name: "Agent", avatar: "", created_at: "2026-10-09T00:00:00Z", updated_at: "2026-10-09T00:00:00Z", + persona: { greeting: "Hi", ...(searchStrategy ? { search_strategy: searchStrategy as Agent["persona"]["search_strategy"] } : {}) }, + }; +} +function pointerEvent(type: string) { + const event = new MouseEvent(type, { bubbles: true, button: 0 }); + Object.defineProperties(event, { pointerId: { value: 1 }, pointerType: { value: "mouse" } }); + return event; +} + let container: HTMLDivElement; let root: Root; const originalScrollIntoView = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "scrollIntoView"); beforeEach(() => { vi.clearAllMocks(); + state.runtimeRun = {}; + state.input = "Unsent draft"; + state.images = []; + state.setInput.mockImplementation((next) => { state.input = typeof next === "function" ? next(state.input) : next; }); + state.setImages.mockImplementation((next) => { state.images = typeof next === "function" ? next(state.images) : next; }); + state.uploadAttachment.mockResolvedValue({ id: "attachment-1" }); state.sources = []; + state.scoped = [{ id: "composer-source", name: "Composer selection" }]; + state.capabilities = { llm_configured: true }; + state.agent = null; + state.snapshot = emptySession; state.send.mockResolvedValue({}); (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; vi.stubGlobal("ResizeObserver", class { observe() {} unobserve() {} disconnect() {} }); - Object.defineProperty(HTMLElement.prototype, "scrollIntoView", { configurable: true, value: vi.fn() }); + Object.defineProperties(HTMLElement.prototype, { + scrollIntoView: { configurable: true, value: vi.fn() }, + hasPointerCapture: { configurable: true, value: () => false }, + releasePointerCapture: { configurable: true, value: () => undefined }, + setPointerCapture: { configurable: true, value: () => undefined }, + }); container = document.createElement("div"); document.body.append(container); root = createRoot(container); @@ -65,20 +119,25 @@ afterEach(async () => { else delete (HTMLElement.prototype as Partial).scrollIntoView; }); +async function renderPanel() { + await act(async () => root.render()); +} +const trigger = () => container.querySelector('[data-testid="search-strategy"]')!; +const hint = () => container.querySelector('[data-testid="search-strategy-hint"]')?.textContent ?? null; +const sendButton = () => container.querySelector(`button[title="${english.Conversation.send}"]`)!; +async function pick(label: string) { + await act(async () => trigger().dispatchEvent(pointerEvent("pointerdown"))); + const item = [...document.body.querySelectorAll('[role="menuitem"]')] + .find((candidate) => candidate.textContent?.includes(label))!; + await act(async () => { item.dispatchEvent(pointerEvent("pointermove")); item.dispatchEvent(pointerEvent("pointerup")); item.click(); }); +} + describe("retry source scope", () => { it("excludes deleting sources from mentions while keeping the composer selection", async () => { - state.sources = ["active", "paused", "error", "deleting", "delete_failed"].map((status) => ({ - id: status, name: status, description: "", source_type: "document", connector_kind: "file_upload", - status, document_count: 0, chunk_count: 0, event_count: 0, - created_at: "2026-10-09T00:00:00Z", updated_at: "2026-10-09T00:00:00Z", - } as Source)); - state.snapshot = { - sessionId: "session-1", agentId: "agent-1", threadId: "thread-1", error: null, run: null, - history: { status: "ready", requestId: 0, hasMore: false, nextCursor: null, error: null }, messages: [], - }; - await act(async () => root.render()); + state.sources = ["active", "paused", "error", "deleting", "delete_failed"].map((status) => source(status, null, status)); + await renderPanel(); const textarea = container.querySelector("textarea")!; await act(async () => { Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value")!.set!.call(textarea, "@"); @@ -100,13 +159,10 @@ describe("retry source scope", () => { sourceScope: saved as MessageSourceScope[] | null, }; state.snapshot = { - sessionId: "session-1", agentId: "agent-1", threadId: "thread-1", error: null, run: null, - history: { status: "ready", requestId: 0, hasMore: false, nextCursor: null, error: null }, + ...emptySession, messages: [base, { ...base, id: "answer", role: "assistant", content: "Original answer", sourceScope: null }], }; - await act(async () => root.render()); + await renderPanel(); const retry = container.querySelector('button[aria-label="Generate answer again"]')!; expect(retry).toBeTruthy(); await act(async () => retry.click()); @@ -115,3 +171,206 @@ describe("retry source scope", () => { })); }); }); + +describe("composer retrieval mode", () => { + it("shows automatic algorithm routing without a hint when nothing is pinned", async () => { + state.capabilities = { llm_configured: true, search_strategy: "multi_es_fast" }; + await renderPanel(); + // The legacy Agent default is vector for non-JEV global modes. + expect(trigger().textContent).toContain("Auto (knowledge algorithms)"); + 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 automatic routing when the persona mode cannot be served", async () => { + // Without an advertised search_strategies list the JEV modes are unsupported. + state.capabilities = { llm_configured: true, search_strategy: "vector" }; + state.agent = agent("sag2"); + state.sources = [source("composer-source", "multi")]; + await renderPanel(); + expect(trigger().textContent).toContain("Auto (knowledge algorithms)"); + expect(hint()).toBeNull(); + }); + + it("ignores source defaults that the scoped sources do not share", async () => { + state.scoped = [{ id: "a", name: "a" }, { id: "b", name: "b" }]; + state.sources = [source("a", "multi"), source("b", "multi_es_fast")]; + await renderPanel(); + expect(trigger().textContent).toContain("Auto (knowledge algorithms)"); + expect(hint()).toBeNull(); + }); + + it("omits the mode from the request when nothing is pinned", async () => { + state.agent = agent("multi"); + await renderPanel(); + await act(async () => sendButton().click()); + expect(state.send).toHaveBeenCalledTimes(1); + expect(state.send.mock.calls[0][1]).not.toHaveProperty("strategy"); + }); + + it("sends the pinned mode and drops the origin hint", async () => { + state.agent = agent("multi"); + await renderPanel(); + expect(hint()).toContain("Persona default"); + await pick("Fast (multi_es-fast)"); + expect(trigger().textContent).toContain("Fast (multi_es-fast)"); + expect(hint()).toBeNull(); + await act(async () => sendButton().click()); + expect(state.send).toHaveBeenCalledWith("session-1", expect.objectContaining({ strategy: "multi_es_fast" })); + }); + + it("locks the control while a run is in flight", async () => { + state.snapshot = { + ...emptySession, + run: { requestId: "r", runId: "run-1", lifecycle: "running", startedAt: 0, assistantMessageId: "a", steps: [], pendingApproval: null }, + }; + await renderPanel(); + expect(trigger().disabled).toBe(true); + }); + + it("keeps a pre-stream mode rejection above the composer with a settings link", async () => { + state.send.mockRejectedValue(new AgentHttpError("Add a JEV API key first", "jev_api_key_missing", 400)); + await renderPanel(); + await act(async () => sendButton().click()); + const notice = container.querySelector('[data-testid="strategy-notice"]')!; + expect(notice.textContent).toContain("Add a JEV API key first"); + expect(notice.getAttribute("data-code")).toBe("jev_api_key_missing"); + expect(container.querySelector('[data-testid="strategy-notice-settings"]')?.getAttribute("href")) + .toBe("/settings?tab=knowledge§ion=jev"); + expect(state.toastError).not.toHaveBeenCalled(); + await pick("Precise"); + expect(container.querySelector('[data-testid="strategy-notice"]')).toBeNull(); + }); + + it("blocks an unavailable pinned mode before uploading or clearing the draft", async () => { + state.capabilities = { llm_configured: true, search_strategies: [...ALL_STRATEGIES] }; + await renderPanel(); + await pick("SAG2 evidence retrieval"); + state.images = [{ file: new File(["image"], "draft.png"), url: "blob:draft" }]; + state.capabilities = { + ...state.capabilities, + search_strategies_disabled: { sag2: { reason: "jev_api_key_missing", message: "Add a JEV API key first" } }, + }; + await renderPanel(); + expect(container.querySelector('[data-testid="strategy-notice"]')?.textContent).toContain("Add a JEV API key first"); + await act(async () => sendButton().click()); + expect(state.send).not.toHaveBeenCalled(); + expect(state.uploadAttachment).not.toHaveBeenCalled(); + expect(state.input).toBe("Unsent draft"); + expect(state.images).toHaveLength(1); + expect(trigger().textContent).toContain("SAG2 evidence retrieval"); + expect(sendButton().disabled).toBe(true); + await pick("Precise"); + await act(async () => sendButton().click()); + expect(state.send).toHaveBeenCalledWith("session-1", expect.objectContaining({ strategy: "multi" })); + }); + + it("restores text and image previews when a stale capability is rejected before streaming", async () => { + const revoke = vi.fn(); + vi.stubGlobal("URL", class extends URL { static revokeObjectURL = revoke; }); + const image = { file: new File(["image"], "draft.png"), url: "blob:draft" }; + state.images = [image]; + state.capabilities = { llm_configured: true, search_strategies: [...ALL_STRATEGIES] }; + let reject!: (reason: Error) => void; + state.send.mockImplementation(() => new Promise((_resolve, fail) => { reject = fail; })); + await renderPanel(); + await pick("SAG2 evidence retrieval"); + await act(async () => sendButton().click()); + expect(state.input).toBe(""); + expect(state.images).toEqual([]); + await act(async () => reject(new AgentHttpError("Add a JEV API key first", "jev_api_key_missing", 400))); + expect(state.input).toBe("Unsent draft"); + expect(state.images).toEqual([image]); + expect(revoke).not.toHaveBeenCalled(); + state.send.mockResolvedValue({}); + await renderPanel(); + await pick("Precise"); + await act(async () => sendButton().click()); + expect(state.send).toHaveBeenLastCalledWith("session-1", expect.objectContaining({ + query: "Unsent draft", attachmentIds: ["attachment-1"], strategy: "multi", + })); + expect(revoke).toHaveBeenCalledWith("blob:draft"); + }); + + it("allows the same pinned mode once its configuration is restored", async () => { + state.capabilities = { llm_configured: true, search_strategies: [...ALL_STRATEGIES] }; + await renderPanel(); + await pick("SAG2 evidence retrieval"); + state.capabilities = { ...state.capabilities, search_strategies_disabled: { + sag2: { reason: "jev_api_key_missing", message: "Add a JEV API key first" }, + } }; + await renderPanel(); + expect(sendButton().disabled).toBe(true); + state.capabilities = { ...state.capabilities, search_strategies_disabled: {} }; + await renderPanel(); + expect(container.querySelector('[data-testid="strategy-notice"]')).toBeNull(); + expect(sendButton().disabled).toBe(false); + await act(async () => sendButton().click()); + expect(state.send).toHaveBeenCalledWith("session-1", expect.objectContaining({ strategy: "sag2" })); + }); + + it("does not accept pasted images while uploading or awaiting a rejected turn", async () => { + const create = vi.fn((file: File) => `blob:${file.name}`); + vi.stubGlobal("URL", class extends URL { static createObjectURL = create; }); + const originalImages = Array.from({ length: 4 }, (_, index) => ({ + file: new File(["image"], `original-${index}.png`, { type: "image/png" }), url: `blob:original-${index}`, + })); + state.images = originalImages; + let finishUpload!: (value: { id: string }) => void; + const upload = new Promise<{ id: string }>((resolve) => { finishUpload = resolve; }); + state.uploadAttachment.mockReturnValue(upload); + let reject!: (reason: Error) => void; + state.send.mockImplementation(() => new Promise((_resolve, fail) => { reject = fail; })); + await renderPanel(); + const paste = () => { + const event = new Event("paste", { bubbles: true, cancelable: true }); + Object.defineProperty(event, "clipboardData", { value: { files: Array.from({ length: 4 }, (_, index) => + new File(["new image"], `new-${index}.png`, { type: "image/png" })) } }); + container.querySelector("textarea")!.dispatchEvent(event); + }; + // Same tick: uploadingRef guards the paste before React renders the busy state. + await act(async () => { sendButton().click(); paste(); }); + expect(create).not.toHaveBeenCalled(); + expect(state.setImages).not.toHaveBeenCalled(); + await act(async () => finishUpload({ id: "attachment-1" })); + expect(state.images).toEqual([]); + await act(async () => paste()); + expect(create).not.toHaveBeenCalled(); + await act(async () => reject(new AgentHttpError("Add a JEV API key first", "jev_api_key_missing", 400))); + expect(state.images).toEqual(originalImages); + expect(state.images).toHaveLength(4); + state.runtimeRun = null; + state.images = []; + await renderPanel(); + await act(async () => paste()); + expect(create).toHaveBeenCalledTimes(4); + expect(state.images).toHaveLength(4); + }); + + it("does not overwrite a newer draft when restoring a rejected question", async () => { + let reject!: (reason: Error) => void; + state.send.mockImplementation(() => new Promise((_resolve, fail) => { reject = fail; })); + await renderPanel(); + await act(async () => sendButton().click()); + state.input = "A newer draft"; + await act(async () => reject(new AgentHttpError("Add a JEV API key first", "jev_api_key_missing", 400))); + expect(state.input).toBe("A newer draft"); + }); + + it("still toasts errors that are not about the retrieval mode", async () => { + state.send.mockRejectedValue(new AgentHttpError("Server exploded", "internal_error", 500)); + await renderPanel(); + await act(async () => sendButton().click()); + expect(container.querySelector('[data-testid="strategy-notice"]')).toBeNull(); + expect(state.toastError).toHaveBeenCalledWith("Server exploded"); + }); +}); diff --git a/apps/web/components/features/chat/conversation-panel.tsx b/apps/web/components/features/chat/conversation-panel.tsx index ea24092c..26e50a00 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,14 @@ import { isComposerCompositionKeyEvent, shouldSubmitAfterEnter, } from "@/lib/composer-keyboard"; +import { + 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 +44,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 +70,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 +208,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 +229,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 +294,44 @@ 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 = null; + const globalStrategy: SearchStrategy = "auto"; + const resolvedStrategy = personaStrategy ?? scopeDefaultStrategy ?? globalStrategy; + // Keep an explicit choice visible, but never submit it after its configuration expires. + const pinnedStrategyIssue = pinnedStrategy ? strategyDisabledMap[pinnedStrategy] : undefined; + const displayedStrategyNotice = pinnedStrategyIssue + ? { code: pinnedStrategyIssue.reason, message: pinnedStrategyIssue.message } + : strategyNotice; + const strategyOrigin: ChatStrategyOrigin = pinnedStrategy + ? "pinned" + : personaStrategy + ? "persona" + : scopeDefaultStrategy + ? "source_default" + : "global"; + const strategyHint = strategyOrigin === "persona" + ? retrievalModes("personaDefaultHint") + : strategyOrigin === "source_default" + ? retrievalModes("scopeDefaultHint") + : undefined; + const pinStrategy = React.useCallback((value: SearchStrategy) => { + setPinnedStrategy(value); + setStrategyNotice(null); + }, []); React.useEffect(() => { mentionListRef.current ?.querySelector(`[data-idx="${mentionIdx}"]`) @@ -493,7 +558,9 @@ export function ConversationPanel({ const MAX_IMAGES = 4; function addImages(files: FileList | File[] | null) { - if (!files) return; + // Match the disabled attachment button, including paste/file-picker events + // before a busy-state render. A rejected turn may need all four images back. + if (!files || uploadingRef.current || streaming || runtime.getSessionSnapshot(sessionId).run) return; const incoming = Array.from(files).filter((f) => f.type.startsWith("image/")); if (!incoming.length) return; setImages((prev) => { @@ -518,10 +585,12 @@ export function ConversationPanel({ } async function send(text?: string, sourceScope?: MessageSourceScope[] | null) { + const draftInput = input; const query = (text ?? input).trim(); const pendingImages = images; const selectedScope = (sourceScope ?? scoped).map((source) => ({ ...source })); if ((!query && pendingImages.length === 0) || uploadingRef.current) return; + if (pinnedStrategyIssue) return; if (!capabilities?.llm_configured) { toast.error(t("modelNotConfigured")); getDiagnosticsStore().record("error", { @@ -537,6 +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;未登记表示被全局并发边界拒绝,保留草稿。 @@ -558,12 +630,26 @@ export function ConversationPanel({ setInput(""); imagesRef.current = []; setImages([]); - pendingImages.forEach((image) => URL.revokeObjectURL(image.url)); setStepsCollapsed(false); followOutputRef.current = true; - void request.catch((error) => { - toast.error(error instanceof Error ? error.message : t("connectionInterrupted")); + const releaseImagePreviews = () => pendingImages.forEach((image) => URL.revokeObjectURL(image.url)); + void request.then(releaseImagePreviews, (error) => { + // A mode this deployment cannot serve is rejected before streaming; keep that + // explanation next to the mode control instead of letting it vanish with a toast. + if (error instanceof AgentHttpError && isSearchStrategyRejectionCode(error.code)) { + setStrategyNotice({ code: error.code, message: error.message }); + // Capabilities can be stale (e.g. settings changed in another window). The + // server rejected this turn before streaming, so preserve its unsent draft. + setInput((current) => current || (text === undefined ? draftInput : query)); + setImages((current) => [ + ...pendingImages, + ...current.filter((image) => !pendingImages.some((pending) => pending.url === image.url)), + ]); + } else { + releaseImagePreviews(); + toast.error(error instanceof Error ? error.message : t("connectionInterrupted")); + } getDiagnosticsStore().record("qa.error", { context: "conversation.send", error_message: error instanceof Error ? error.message.slice(0, 500) : String(error).slice(0, 500), @@ -737,6 +823,31 @@ export function ConversationPanel({
+ {displayedStrategyNotice && ( +
+ {displayedStrategyNotice.message} + + {searchStrategies("openSettings")} + + {!pinnedStrategyIssue && } +
+ )}
{images.length > 0 && (
@@ -945,6 +1056,14 @@ export function ConversationPanel({ : t("webDisabledDescription")} + @@ -1013,7 +1132,7 @@ export function ConversationPanel({ )} - + {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-list.tsx b/apps/web/components/features/document-list.tsx index 938f9abc..9ed35cbd 100644 --- a/apps/web/components/features/document-list.tsx +++ b/apps/web/components/features/document-list.tsx @@ -25,6 +25,7 @@ import { useOctxExports } from "@/components/features/octx-export-provider"; export function DocumentList({ sourceId, + engineKind = "sag1", sourceName, documents, activities, @@ -33,6 +34,7 @@ export function DocumentList({ onOpenDocument, }: { sourceId: string; + engineKind?: "sag1" | "sag2"; sourceName: string; documents: Doc[]; activities: Record; @@ -103,7 +105,7 @@ export function DocumentList({ const buttonClass = compact ? "size-7" : undefined; return (
- {document.has_publication && ( + {document.has_publication && engineKind !== "sag2" && ( + + + + ; +} diff --git a/apps/web/components/features/jev-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..3c882b9e 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", false); + 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", false); + 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: "multi_jev" } 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,82 @@ 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.querySelector("#kb-search-strategy")?.textContent).toContain("Fast (vector)"); + 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); + const options = await openSelect("#kb-search-strategy"); + expect(options.some(option => option.textContent?.includes("SAG2"))).toBe(false); + await closeSelect(); + await act(async () => button("Save and apply").click()); + expect(saved).not.toHaveProperty("search_strategy"); + 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(); + const options = await openSelect("#kb-search-strategy"); + expect(options.some(option => option.textContent?.includes("SAG2"))).toBe(false); + await closeSelect(); + await select("#kb-search-strategy", "JEV"); + await act(async () => button("Save and apply").click()); + expect(saved).toMatchObject({ search_strategy: "multi_jev" }); + }); + 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", false); + const options = await openSelect("#kb-search-strategy"); + expect(options.some(option => option.textContent?.includes("SAG2"))).toBe(false); + await closeSelect(); + expect(container.querySelector('[role="alert"]')).toBeNull(); + await edit("#kb-jev-api-key", "synthetic-302-key"); + await expectStrategyDisabled("JEV reranking", false); + await select("#kb-search-strategy", "JEV"); + await act(async () => button("Save and apply").click()); + expect(saved).toMatchObject({ search_strategy: "multi_jev", jev_endpoint: provider302Endpoint, jev_api_key: "synthetic-302-key" }); + }); it("disables the JEV option and rejects a draft enable when storage capabilities change", async () => { await mount(); + 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 +463,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 +474,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..2805d99f 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"]; @@ -108,7 +126,7 @@ export function KnowledgeConfigForm() { setChunkMaxTokens(config.document_chunk_max_tokens ?? 1_000); setChunkMode(config.document_chunk_mode ?? "standard"); setExtractConcurrency(config.document_extract_concurrency ?? 30); - setStrategy(config.search_strategy); + setStrategy(config.search_strategy === "sag2" || config.search_strategy === "auto" ? "vector" : config.search_strategy); setTopK(config.search_top_k); setLanguage(config.sag_language); setJevProvider(providerForEndpoint(config.jev_endpoint ?? "")); @@ -120,7 +138,7 @@ export function KnowledgeConfigForm() { setJevTimeout(timeout); setJevFailurePolicy(failurePolicy); // Display defaults are a preview; only edits or explicitly enabling JEV save them. - setSavedJevDraft({ endpoint, model, timeout, failurePolicy, strategy: config.search_strategy }); + setSavedJevDraft({ endpoint, model, timeout, failurePolicy, strategy: config.search_strategy === "sag2" || config.search_strategy === "auto" ? "vector" : config.search_strategy }); setJevTestResult(null); setLoaded(true); }, []); @@ -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, @@ -353,7 +372,8 @@ export function KnowledgeConfigForm() { { setJevKey(event.target.value); setJevTestResult(null); }} /> {jevProvider !== "custom" && {t("jevKeyProviderDescription", { provider: jevProvider === "302" ? "302.AI" : "TypeSafe" })}} @@ -474,10 +512,10 @@ export function KnowledgeConfigForm() { {jevUnsupported &&

{strategies("unsupportedBackend")}

} - {invalidJevDraft &&

{t("jevInvalidDraft")}

} + {invalidJevDraft &&

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

}
@@ -486,6 +524,7 @@ export function KnowledgeConfigForm() {
} +
diff --git a/apps/web/components/features/knowledge-engine-pill.tsx b/apps/web/components/features/knowledge-engine-pill.tsx new file mode 100644 index 00000000..f602e465 --- /dev/null +++ b/apps/web/components/features/knowledge-engine-pill.tsx @@ -0,0 +1,14 @@ +"use client"; +import { useTranslations } from "next-intl"; +import { cn } from "@/lib/utils"; + +export function KnowledgeEnginePill({ kind = "sag1", className }: { + kind?: "sag1" | "sag2"; className?: string; +}) { + const t = useTranslations("SourceForm"); + return + {t(kind)} + ; +} diff --git a/apps/web/components/features/knowledge-source-workspace.tsx b/apps/web/components/features/knowledge-source-workspace.tsx index 3daf1660..c3e9db0a 100644 --- a/apps/web/components/features/knowledge-source-workspace.tsx +++ b/apps/web/components/features/knowledge-source-workspace.tsx @@ -167,12 +167,13 @@ export function KnowledgeSourceWorkspace({ >

{isFileSource - ? t("uploadDescription") + ? t(source?.engine_kind === "sag2" ? "sag2UploadDescription" : "uploadDescription") : t("syncDescription")}

{source && (isFileSource ? ( void finishMutation()} maxMb={capabilities?.max_upload_mb ?? 25} @@ -236,6 +237,7 @@ export function KnowledgeSourceWorkspace({ , 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-status.test.tsx b/apps/web/components/features/retrieval-status.test.tsx index 4e26019e..cb48e20b 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,61 @@ 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"); + }); +}); + + +it("shows JEV degradation inside automatic mixed retrieval", async () => { + const text = await render({ requested_strategy: "auto", effective_strategy: "auto", jev_fallback_used: true, + fallback_used: true, engine_failures: [{ engine_kind: "sag1", message: "legacy storage offline" }] }, "auto"); + expect(text).toContain("JEV reranking did not complete"); + expect(text).toContain("sag1 retrieval failed or is incomplete: legacy storage offline"); +}); diff --git a/apps/web/components/features/retrieval-status.tsx b/apps/web/components/features/retrieval-status.tsx index 50cffc7b..466f2a72 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,45 @@ 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 = stats.jev_fallback_used === true + || (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 engineFailures = Array.isArray(stats.engine_failures) ? stats.engine_failures : []; + const executionChanged = jevFallback || partial || changed; + const origin = explainedOrigin(stats.strategy_origin); + // The origin describes the resolved (requested) mode; a changed execution is reported separately. + const originMode = requested ?? effective; + if (!executionChanged && usageText === null && !(origin && originMode) && !engineFailures.length) 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}

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

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

; })}
; } diff --git a/apps/web/components/features/retrieval-test-dialog.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..4cb05500 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"; @@ -58,7 +58,7 @@ export function RetrievalTestDialog({ const disabledMap = getSearchStrategiesDisabled(capabilities, strategies("unsupportedBackend")); const enabledStrategies = SEARCH_STRATEGIES.filter( - (item) => !disabledMap[item.value], + (item) => item.value !== "auto" && !disabledMap[item.value], ).map((item) => item.value); const fallbackA: SearchStrategy = enabledStrategies[0] ?? DEFAULT_SEARCH_STRATEGY; @@ -282,7 +282,7 @@ function StrategyPicker({ - {SEARCH_STRATEGIES.map(({ value: strategy, labelKey }) => { + {SEARCH_STRATEGIES.filter(item => item.value !== "auto").map(({ value: strategy, labelKey }) => { const info = disabledMap[strategy]; const sameAsOther = strategy === otherValue; return ( @@ -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..75ffd301 --- /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")).not.toBe("true"); + expect(sag2.textContent).toContain("Add a JEV API key"); + const link = document.body.querySelector('[data-testid="search-strategy-sag2-settings"]')!; + expect(link.getAttribute("href")).toBe("/settings?tab=knowledge§ion=jev"); + 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..664a74b4 100644 --- a/apps/web/components/features/search-strategy-control.tsx +++ b/apps/web/components/features/search-strategy-control.tsx @@ -1,8 +1,10 @@ "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, useState } from "react"; +import { JevModeSetupDialog } from "./jev-mode-setup-dialog"; import { DropdownMenu, @@ -20,23 +22,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,40 +53,59 @@ 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 [pending, setPending] = useState(null); 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 (needsJevSettings) { + setPending(strategy.value); + return; + } if (disabledInfo) { // Radix 默认会关闭菜单;这里阻断以便 Tooltip 保持可见, // 且不触发无意义的 onValueChange。 @@ -95,18 +121,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,18 +143,36 @@ export function SearchStrategyControl({ /> ); - if (!disabledInfo) return item; return ( - - {item} - - {disabledInfo.message} - - + + {disabledInfo ? ( + + {item} + + {disabledInfo.message} + + + ) : item} + {needsJevSettings && ( + + + + {t("openSettings")} + + + )} + ); })} + {pending && setPending(null)} + onConfigured={() => { onValueChange(pending); setPending(null); }} + />} ); } 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-mixed-evidence.test.tsx b/apps/web/components/features/search/search-mixed-evidence.test.tsx new file mode 100644 index 00000000..a9a24a06 --- /dev/null +++ b/apps/web/components/features/search/search-mixed-evidence.test.tsx @@ -0,0 +1,26 @@ +/** @vitest-environment jsdom */ +import * as React from "react"; +import { act } from "react"; +import { createRoot } from "react-dom/client"; +import { NextIntlClientProvider } from "next-intl"; +import { expect, it, vi } from "vitest"; +import messages from "@/messages/zh-CN.json"; +import type { SearchResponse } from "@/lib/types"; +import { ResultList } from "./search-panel-sections"; +vi.mock("@/components/features/detail-panel", () => ({ useDetailPanel: () => ({ open: vi.fn() }) })); +it("keeps native evidence visible when SAG1 graph events are also present", async () => { + (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + const result: SearchResponse = { + query: "q", entities: [], relations: [], source_hits: [], summary: "", exploration_id: null, stats: {}, + events: [{ id: "event", title: "SAG1 event", summary: "legacy", score: 0.8, source_id: "legacy", document_id: null, category: "", rank: 0, parent_id: null, chunk_id: null, start_time: null }], + sections: [{ source_id: "native", chunk_id: "c", heading: "Native evidence", content: "NATIVE-253", score: 0.2, rank: 0, + metadata: { engine_kind: "sag2" } }], + }; + const container = document.createElement("div"); document.body.append(container); const root = createRoot(container); + try { + await act(async () => root.render( + + )); + expect(container.textContent).toContain("NATIVE-253"); + } finally { await act(async () => root.unmount()); container.remove(); } +}); diff --git a/apps/web/components/features/search/search-panel-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-sections.tsx b/apps/web/components/features/search/search-panel-sections.tsx index f64fdb87..fe520638 100644 --- a/apps/web/components/features/search/search-panel-sections.tsx +++ b/apps/web/components/features/search/search-panel-sections.tsx @@ -404,7 +404,7 @@ export function ResultList({ /> ); } - if (result.events.length === 0) { + if (result.events.length === 0 || result.sections.some(section => section.metadata?.engine_kind === "sag2")) { return (
{result.sections.map((section, index) => { diff --git a/apps/web/components/features/search/search-panel.tsx b/apps/web/components/features/search/search-panel.tsx index 4983783d..7bcc29e6 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) => value !== "auto" && !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..d21a5862 100644 --- a/apps/web/components/features/search/search-provider.tsx +++ b/apps/web/components/features/search/search-provider.tsx @@ -5,7 +5,7 @@ import { useTranslations } from "next-intl"; import { api, ApiError } from "@/lib/api"; import { isSourceDeleting } from "@/lib/source-activity"; -import type { SearchStrategy } from "@/lib/retrieval-config"; +import { 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,24 @@ 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 = null; + const effectiveStrategy = state.strategyPinned ? state.strategy : 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 +371,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 +520,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 +530,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 +543,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 +591,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 +606,10 @@ export function SearchProvider({ const value = React.useMemo( () => ({ ...state, + strategy: effectiveStrategy, defaultStrategy, + scopeDefaultStrategy, + strategyOrigin, canLoadMore, setQuery, setStrategy, @@ -599,6 +631,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..3c2702d7 --- /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 defaults ignore retired per-source mode preferences", () => { + it("retains the application default after scoped sources load", async () => { + const h = await harness(); + try { + expect(h.read("strategy")).toBe("vector"); + 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("vector"); + expect(h.read("origin")).toBe("global"); + expect(h.read("scope-default")).toBe("none"); + await h.act(() => h.workspace.setScope(scope("a", "c"))); + expect(h.read("strategy")).toBe("vector"); + expect(h.read("origin")).toBe("global"); + 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("ignores retired mode preferences on a toggled source", async () => { + const h = await harness(); + try { + await h.act(() => h.workspace.toggleSource(sources[2])); + expect(h.read("strategy")).toBe("vector"); + expect(h.read("origin")).toBe("global"); + } 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("vector"); + 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 application default when nothing is pinned", async () => { + const h = await harness(); + try { + await h.act(() => h.workspace.ensureSources()); + await h.act(() => h.workspace.setScope(scope("b"))); + await h.act(() => h.workspace.run({ query: "question" }).catch(() => {})); + expect(h.requests).toEqual([expect.objectContaining({ strategy: "vector", source_ids: ["b"] })]); + expect(h.read("origin")).toBe("global"); + } 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..409ccce0 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,14 @@ describe("source card", () => { expect(navigationEnd).toBeGreaterThanOrEqual(0); expect(copyButton).toBeGreaterThan(navigationEnd); }); + + it("shows the immutable algorithm, defaulting legacy sources to SAG1", () => { + expect(render(source)).toContain('data-engine-kind="sag1"'); + const html = render({ ...source, engine_kind: "sag2" }); + expect(html).toContain('data-testid="source-engine-kind"'); + expect(html).toContain('data-engine-kind="sag2"'); + expect(html).toContain("证据检索(SAG2)"); + expect(html).toContain("SAG2 暂不支持 OCTX 导出"); + expect(html).not.toContain('data-testid="source-default-mode"'); + }); }); diff --git a/apps/web/components/features/source-card.tsx b/apps/web/components/features/source-card.tsx index 5f5b1a7c..66a059d1 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 { KnowledgeEnginePill } from "@/components/features/knowledge-engine-pill"; import { useOctxExports } from "@/components/features/octx-export-provider"; import { useApp } from "@/components/features/app-shell"; import { SourceIdCopy } from "@/components/features/source-id-copy"; @@ -27,6 +28,7 @@ export function SourceCard({ source, onChanged }: { source: Source; onChanged?: const { startExport, isSourceExporting } = useOctxExports(); const exportRunning = isSourceExporting(source.id); + const sag2 = source.engine_kind === "sag2"; const handleExport = React.useCallback( (event: React.MouseEvent) => { @@ -50,10 +52,13 @@ export function SourceCard({ source, onChanged }: { source: Source; onChanged?: }
-
+

{source.name}

+ {( + + )}

{source.description || t("noDescription")} @@ -90,15 +95,15 @@ export function SourceCard({ source, onChanged }: { source: Source; onChanged?: variant="ghost" size="icon" aria-label={t("export")} - title={t("export")} + title={sag2 ? t("sag2OctxUnsupported") : t("export")} onClick={handleExport} - disabled={exportRunning || deletion.active} + disabled={exportRunning || deletion.active || sag2} className="bg-background/95 text-muted-foreground shadow-soft backdrop-blur-sm hover:text-foreground" > {exportRunning ? : } - {t("export")} + {sag2 ? t("sag2OctxUnsupported") : t("export")} {!deletion.active && ({ + 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( + , + )); +} +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 })); + }); +} +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 SAG1 source by default without changing model settings", async () => { + await mount(); await type(nameInput(), "Manuals"); await submit(); + expect(api.createSource).toHaveBeenCalledWith({ name: "Manuals", description: "", engine_kind: "sag1" }); + expect(api.saveModelConfig).not.toHaveBeenCalled(); + expect(onCreated).toHaveBeenCalledWith(expect.objectContaining({ id: "source-1" })); + }); + it("can create a SAG2 source without a JEV key because indexing does not use JEV", async () => { + await mount(); await type(nameInput(), "Evidence"); + await act(async () => container.querySelector('input[value="sag2"]')!.click()); + expect(submitButton().disabled).toBe(false); + await submit(); + expect(api.createSource).toHaveBeenCalledWith({ name: "Evidence", description: "", engine_kind: "sag2" }); + expect(api.saveModelConfig).not.toHaveBeenCalled(); + expect(container.querySelector('[data-testid="jev-quick-setup"]')).toBeNull(); + }); + it("does not report creation success after an API failure", async () => { + vi.mocked(api.createSource).mockRejectedValue(new ApiError(400, "invalid_source", "Source rejected")); + await mount(); await type(nameInput(), "Manuals"); await submit(); + expect(onCreated).not.toHaveBeenCalled(); + expect(submitButton().disabled).toBe(false); + }); +}); diff --git a/apps/web/components/features/source-create-form.tsx b/apps/web/components/features/source-create-form.tsx index 4c4123dc..38df46b2 100644 --- a/apps/web/components/features/source-create-form.tsx +++ b/apps/web/components/features/source-create-form.tsx @@ -24,6 +24,7 @@ export function SourceCreateForm({ const t = useTranslations("SourceForm"); const [name, setName] = React.useState(""); const [description, setDescription] = React.useState(""); + const [engineKind, setEngineKind] = React.useState<"sag1" | "sag2">("sag1"); const [loading, setLoading] = React.useState(false); const nameId = React.useId(); const descriptionId = React.useId(); @@ -32,7 +33,7 @@ export function SourceCreateForm({ event.preventDefault(); setLoading(true); try { - const source = await api.createSource({ name: name.trim(), description: description.trim() }); + const source = await api.createSource({ name: name.trim(), description: description.trim(), engine_kind: engineKind }); toast.success(t("created")); onCreated(source); setName(""); @@ -72,6 +73,18 @@ export function SourceCreateForm({ /> +

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

{t("algorithmImmutable")}

+
{onCancel && (
)}
-

+ {engineKind === "sag1" &&

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

+

}
); } 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..154609e4 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,13 @@ export const api = { // 信源 listSources: () => request("/api/v1/sources"), getSource: (id: string) => request(`/api/v1/sources/${id}`), - createSource: (b: { name: string; description?: string }) => + createSource: (b: { + engine_kind?: "sag1" | "sag2"; + 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 +1026,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..580296c9 100644 --- a/apps/web/lib/retrieval-config.test.ts +++ b/apps/web/lib/retrieval-config.test.ts @@ -1,5 +1,16 @@ import { describe, expect, it } from "vitest"; -import { isSearchStrategy, getSearchStrategiesDisabled } from "./retrieval-config"; +import { + 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 +30,69 @@ 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(["auto", "vector", "multi_es_fast", "multi", "multi_jev", "sag2"]); + expect(isSearchStrategy("sag2")).toBe(true); + expect(JEV_SCORED_STRATEGIES).toEqual(["multi_jev", "sag2"]); + expect(isJevScoredStrategy("sag2")).toBe(true); + 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("paid mode setup", () => { + it("offers the inline JEV setup only for JEV modes blocked by a missing configuration", () => { + const disabled = { + multi_jev: { reason: "vector_provider_lacks_lexical", message: "Lexical" }, + 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..14d243cd 100644 --- a/apps/web/lib/retrieval-config.ts +++ b/apps/web/lib/retrieval-config.ts @@ -1,4 +1,13 @@ +import { + ScanSearch, + ShieldQuestion, + Sparkles, + Zap, + type LucideIcon, +} from "lucide-react"; + export const SEARCH_STRATEGIES = [ + { value: "auto", labelKey: "autoLabel", descriptionKey: "autoDescription" }, { value: "vector", labelKey: "vectorLabel", @@ -19,11 +28,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"; +export const DEFAULT_SEARCH_STRATEGY: SearchStrategy = "auto"; + +/** One icon per mode, shared by the search control, the source pill and the picker. */ +export const SEARCH_STRATEGY_ICONS: Record = { + auto: ScanSearch, + vector: Zap, + multi_es_fast: ShieldQuestion, + multi: Sparkles, + multi_jev: Sparkles, + sag2: ScanSearch, +}; /** * Capability keys a strategy needs from the current vector provider. @@ -31,12 +55,52 @@ export const DEFAULT_SEARCH_STRATEGY: SearchStrategy = "vector"; * 前端只用来在拿不到 disabled map 时兜底渲染,避免用户点了才发现打不通。 */ export const SEARCH_STRATEGY_REQUIREMENTS = { + auto: [] as const, vector: [] as const, 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 +134,26 @@ 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); +} 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..a317942b 100644 --- a/apps/web/lib/types.ts +++ b/apps/web/lib/types.ts @@ -64,6 +64,7 @@ export type ParserStatus = | "fallback" | "failed"; export interface Source { + engine_kind?: "sag1" | "sag2"; id: string; name: string; description: string; @@ -71,6 +72,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 +181,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 { @@ -517,6 +526,7 @@ export interface SourceGraphResponse { } export interface Section { + metadata?: Record; chunk_id: string | null; heading: string; content: string; diff --git a/apps/web/messages/en-US.json b/apps/web/messages/en-US.json index ef95ade4..a560e464 100644 --- a/apps/web/messages/en-US.json +++ b/apps/web/messages/en-US.json @@ -285,13 +285,19 @@ "creating": "Creating…", "create": "Create source", "new": "New source", - "dialogDescription": "Sources hold content. After creation, upload documents and SAG will parse, chunk, and extract events automatically.", + "dialogDescription": "Choose a knowledge algorithm, create the source, then upload documents.", "updated": "Source updated", "updateFailed": "Failed to update source", "edit": "Edit source", - "editDescription": "Change this source’s name and description.", + "editDescription": "Edit the name and description. The knowledge algorithm cannot be changed.", "saving": "Saving…", - "saveChanges": "Save changes" + "saveChanges": "Save changes", + "algorithm": "Knowledge algorithm", + "sag1": "Event retrieval (SAG1)", + "sag2": "Evidence retrieval (SAG2)", + "sag1Description": "Parse, chunk, embed, and extract entities and events.", + "sag2Description": "Parse, chunk and index evidence without entity or event extraction. Retrieval requires a JEV API key.", + "algorithmImmutable": "The algorithm is fixed at creation and applies to all future uploads." }, "SourceCard": { "deleteSubmitted": "Deletion request submitted", @@ -347,7 +353,8 @@ "complete": "Export complete", "failed": "Export failed", "cancelled": "Cancelled" - } + }, + "sag2OctxUnsupported": "OCTX export is not supported for SAG2 yet" }, "UploadZone": { "unsupportedType": "{name}: Unsupported file type", @@ -524,6 +531,7 @@ "list": "List", "graph2dView": "2D graph view", "graph3dView": "3D graph view", + "sag2UploadDescription": "Uploads are parsed, chunked and indexed as source text, without entity or event extraction.", "emptyDocumentsDescription": "Add a document from the upper-right. SAG will parse, chunk, vectorize, and extract events and entities automatically.", "addDialogDescription": "The document will be parsed, chunked, and processed for events and entities automatically.", "syncDialogDescription": "Fetch the latest connector content and update this source.", @@ -613,7 +621,57 @@ "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.", + "autoLabel": "Auto (knowledge algorithms)", + "autoDescription": "Retrieve with each knowledge source’s bound SAG1 or SAG2 algorithm and merge the evidence." + }, + "RetrievalModes": { + "label": "Default retrieval mode", + "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", + "cancelSetup": "Cancel", + "savingSetup": "Saving…", + "saveAndUse": "Save and use this mode" }, "RetrievalTest": { "failed": "Retrieval failed", @@ -667,7 +725,7 @@ "retrievalDescription": "Control knowledge retrieval and reranking services.", "retrievalRules": "Retrieval rules", "retrievalRulesDescription": "Set the retrieval strategy and result count.", - "retrievalStrategy": "Retrieval strategy", + "retrievalStrategy": "SAG1 retrieval strategy", "chinese": "中文", "english": "English", "topK": "Results · {count, number}", @@ -680,8 +738,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 +750,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 +765,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 +1185,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 +1316,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 +1848,13 @@ "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", + "engineFailure": "{engine} retrieval failed or is incomplete: {message}" }, "ClientAccess": { "title": "CLI and automation", diff --git a/apps/web/messages/zh-CN.json b/apps/web/messages/zh-CN.json index 633aa268..a6130e25 100644 --- a/apps/web/messages/zh-CN.json +++ b/apps/web/messages/zh-CN.json @@ -285,13 +285,19 @@ "creating": "创建中…", "create": "创建信源", "new": "新建信源", - "dialogDescription": "信源用来装内容。创建后上传文档,SAG 会自动解析、分块并抽取事件。", + "dialogDescription": "选择知识库算法并创建信源,之后即可上传文档。", "updated": "信源已更新", "updateFailed": "更新失败", "edit": "修改信源", - "editDescription": "调整这个信息源的名称和描述。", + "editDescription": "修改名称和描述;知识库算法创建后不可更改。", "saving": "保存中…", - "saveChanges": "保存修改" + "saveChanges": "保存修改", + "algorithm": "知识库算法", + "sag1": "事件检索(SAG1)", + "sag2": "证据检索(SAG2)", + "sag1Description": "解析、分块、向量化,并提取实体和事项。", + "sag2Description": "解析、分块并建立原文索引,不提取实体和事项;检索需要 JEV API Key。", + "algorithmImmutable": "创建后不可更改算法,后续上传始终沿用此算法。" }, "SourceCard": { "deleteSubmitted": "删除请求已提交", @@ -347,7 +353,8 @@ "complete": "导出完成", "failed": "导出失败", "cancelled": "已取消" - } + }, + "sag2OctxUnsupported": "SAG2 暂不支持 OCTX 导出" }, "UploadZone": { "unsupportedType": "{name}:不支持的文件类型", @@ -524,6 +531,7 @@ "list": "列表", "graph2dView": "2D 图谱视图", "graph3dView": "3D 图谱视图", + "sag2UploadDescription": "上传文档后自动解析、分块并建立原文索引,不提取实体和事项。", "emptyDocumentsDescription": "点击右上角添加文档,SAG 会自动解析、分块、向量化并抽取事件与实体。", "addDialogDescription": "添加后会自动解析、分块并抽取事件与实体。", "syncDialogDescription": "抓取连接器中的最新内容并更新信息源。", @@ -601,19 +609,69 @@ "exportOctx": "导出为 .octx" }, "SearchStrategies": { - "vectorLabel": "快速(vector)", + "vectorLabel": "事件检索(SAG1)· 快速", "vectorDescription": "基于向量语义相似度直接召回,响应更快。", - "multiEsFastLabel": "快速(multi_es-fast)", + "multiEsFastLabel": "事件检索(SAG1)· 均衡", "multiEsFastDescription": "基于 BM25 实体召回与事件多跳的快速检索,跳过 LLM 精排。", - "multiLabel": "精确", + "multiLabel": "事件检索(SAG1)· 精确", "multiDescription": "结合实体关系与 LLM 精排,结果更完整。", "mode": "检索模式", "modeAria": "检索模式:{strategy}", "default": "默认", "disabledSuffix": "(不可用)", - "multiJevLabel": "JEV 精排", + "multiJevLabel": "事件检索(SAG1)· JEV 精排", "multiJevDescription": "扩展关联证据后,使用配置的 JEV 服务评分相关性。", - "unsupportedBackend": "当前服务端未声明支持 JEV,请升级服务端后使用此模式。" + "sag2Label": "证据检索(SAG2)", + "sag2Description": "BM25 召回后由 JEV 服务多轮评分,不依赖向量库;付费服务。", + "paid": "付费", + "openSettings": "去设置", + "unsupportedBackend": "当前服务端未声明支持此 JEV 评分模式,请升级服务端后使用。", + "autoLabel": "自动(按知识库算法)", + "autoDescription": "按知识库创建时绑定的 SAG1 / SAG2 分别检索,再合并证据。" + }, + "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": "打开设置", + "cancelSetup": "取消", + "savingSetup": "保存中…", + "saveAndUse": "保存并使用此模式" }, "RetrievalTest": { "failed": "检索失败", @@ -667,7 +725,7 @@ "retrievalDescription": "控制知识召回方式与精排服务。", "retrievalRules": "检索规则", "retrievalRulesDescription": "调整检索策略和召回条数。", - "retrievalStrategy": "检索策略", + "retrievalStrategy": "SAG1 检索策略", "chinese": "中文", "english": "English", "topK": "召回条数 · {count, number}", @@ -680,8 +738,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 +750,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 +765,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 +1185,8 @@ "reject": "拒绝", "allowOnce": "允许一次", "thinking": "正在思考…", - "sessionMissing": "对话运行实例不存在:{id}" + "sessionMissing": "对话运行实例不存在:{id}", + "dismissNotice": "关闭提示" }, "Citations": { "visitExternal": "访问外部来源:{title}", @@ -1254,7 +1316,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 +1848,13 @@ "actual": "实际模式:{mode}", "coarse": "粗排", "jevFallback": "本次未完成 JEV 精排,已返回粗排结果。", - "partial": "部分结果:部分信源未完成检索。" + "jevUsage": "本次 JEV 评分:{requests} 次请求 · {judgments} 次判定{tokens}", + "jevUsageTokens": " · {tokens} 输入 token", + "partial": "部分结果:部分信源未完成检索。", + "origin": "按{origin}使用 {mode}", + "originPersona": "人格默认", + "originSourceDefault": "信源默认", + "engineFailure": "{engine} 检索失败或不完整:{message}" }, "ClientAccess": { "title": "CLI 与自动化",