feat(phase9 #96 D10.d): search primitives split + omnibus deprecation (#1713)

Phase 9 D10.d (#96) per docs/modularization/d10-design-pack.md §B.

Adds 4 split search MCP tools (vector_search / graph_search /
fulltext_search / web_search) under aperag/mcp/tools/, marks the
omnibus search_collection and search_chat_files as DEPRECATED with a
docstring banner, and relocates the existing web_search implementation
from server.py into the new tools subpackage so all D10 search tools
live in one place.

Forbidden boundaries (§G D10.d) are honored: search_collection /
search_chat_files implementation bodies are intentionally untouched
(deletion is D10.h territory), no read primitive tool surface is
modified (D10.c territory), no aperag/service/search_service.py
compat layer is created (would require [D10 spec amendment] thread).

The §B canonical SearchResult / SearchResultItem shape with chunk_id
/ section_path / heading_anchor surfacing is intentionally deferred
to a D10.d follow-up PR — current backend does not expose chunk_id in
the public response shape and the propagation question warrants a
[D10 spec amendment] thread before implementation.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: earayu

aperag/mcp/server.py

@@ -22,7 +22,7 @@
 
 # Import view models for type safety
 from aperag.domains.retrieval.schemas import SearchResult
-from aperag.domains.web_access.schemas import WebReadResponse, WebSearchResponse
+from aperag.domains.web_access.schemas import WebReadResponse
 from aperag.mcp.tools import (
     ByteRange,
 )
@@ -236,7 +236,15 @@ async def search_collection(
     topk: int = 5,
     query_keywords: list[str] = None,
 ) -> Dict[str, Any]:
-    """Search a persistent knowledge base for evidence relevant to the current request.
+    """[DEPRECATED] Search a persistent knowledge base for evidence relevant to the current request.
+
+    [DEPRECATED] Phase 9 D10.d (#96, ``docs/modularization/d10-design-pack.md``
+    §B.5 / §H.1): use the discrete split tools instead —
+    ``vector_search`` / ``graph_search`` / ``fulltext_search``. This
+    omnibus tool is preserved as a deprecated alias for backward
+    compatibility during the D10 migration window and will be removed in
+    D11 once telemetry confirms no remaining external callers (D10.h
+    cutover lane). Implementation is intentionally untouched.
 
     Use this when:
     - You already know which collection should be searched.
@@ -397,7 +405,14 @@ async def search_chat_files(
     rerank: bool = True,
     topk: int = 5,
 ) -> Dict[str, Any]:
-    """Search files uploaded in the current chat for evidence relevant to this turn.
+    """[DEPRECATED] Search files uploaded in the current chat for evidence relevant to this turn.
+
+    [DEPRECATED] Phase 9 D10.d (#96, ``docs/modularization/d10-design-pack.md``
+    §H.2): chat-scoped omnibus search shares the deprecation timeline of
+    ``search_collection``. The split tool surface (``vector_search`` /
+    ``graph_search`` / ``fulltext_search``) is collection-scoped today;
+    a chat-scoped equivalent will be sequenced in the D10.h cutover
+    lane. Implementation is intentionally untouched.
 
     Use this when:
     - The user refers to files shared in this chat session.
@@ -499,116 +514,12 @@ async def search_chat_files(
         return {"error": str(e)}
 
 
-@mcp_server.tool
-async def web_search(
-    query: str = "",
-    max_results: int = 5,
-    timeout: int = 30,
-    locale: str = "en-US",
-    source: str = "",
-) -> Dict[str, Any]:
-    """Search the web for current or missing information.
-
-    Use this when:
-    - The current turn allows web access.
-    - You need current information, external verification, or gap-filling beyond ApeRAG collections.
-
-    Do not use this when:
-    - The current turn disables web access.
-    - Collection or chat-file evidence is already sufficient for the requested step.
-
-    What success means:
-    - You received candidate web results with titles, snippets, and URLs.
-
-    What an empty result means:
-    - No strong web results were found for this query and scope.
-    - Use `meta.search_status` to distinguish a genuine empty result from `unavailable` or `disabled`.
-
-    What failure may mean:
-    - network / timeout: external search could not complete.
-    - upstream search provider issue: the search backend could not return usable results.
-
-    How to explain this step to the user:
-    - While running: "Searching the web for current or missing information."
-    - After completion: "Checked web sources for supporting information."
-
-    Args:
-        query: Search query for web search. Optional when using source-only site browsing.
-        max_results: Maximum number of results to return (default: 5)
-        timeout: Request timeout in seconds (default: 30)
-        locale: Browser locale (default: en-US)
-        source: Optional domain or URL for site-specific filtering. When provided with query,
-                limits search results to this domain (e.g., 'site:vercel.com query').
-
-    Returns:
-        Web search results with URLs, titles, snippets, and metadata
-
-    Note:
-        Uses JINA first when configured, otherwise falls back to DuckDuckGo.
-        Search failures are soft-failed into empty result sets with lightweight `meta` diagnostics so
-        downstream workflows stay stable while still distinguishing `ok`, `empty`, `unavailable`, and `disabled`.
-    """
-    try:
-        api_key = get_api_key()
-        logger.info(
-            "MCP web_search request query=%s source=%s max_results=%s timeout=%s locale=%s",
-            query.strip() if query else "",
-            source.strip() if source else "",
-            max_results,
-            timeout,
-            locale,
-        )
-
-        # Build search request
-        search_data = {
-            "max_results": max_results,
-            "timeout": timeout,
-            "locale": locale,
-        }
-
-        # Only include non-empty optional parameters
-        if query and query.strip():
-            search_data["query"] = query.strip()
-
-        if source and source.strip():
-            search_data["source"] = source.strip()
-
-        # Use longer timeout for web search operations
-        async with httpx.AsyncClient(timeout=90.0) as client:
-            response = await client.post(
-                f"{API_BASE_URL}/api/v2/web/search",
-                headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
-                json=search_data,
-            )
-            if response.status_code == 200:
-                try:
-                    # Parse response using view model for type safety
-                    search_response = WebSearchResponse.model_validate(response.json())
-                    logger.info(
-                        "MCP web_search completed query=%s source=%s status=%s results=%s providers=%s backends=%s fallback=%s",
-                        query.strip() if query else "",
-                        source.strip() if source else "",
-                        search_response.meta.search_status if search_response.meta else "unknown",
-                        len(search_response.results),
-                        search_response.meta.provider_used if search_response.meta else [],
-                        search_response.meta.backend_used if search_response.meta else [],
-                        search_response.meta.fallback_used if search_response.meta else False,
-                    )
-                    return search_response.model_dump()
-                except Exception as e:
-                    logger.error(f"Failed to parse web search response: {e}")
-                    return {"error": "Failed to parse web search response", "details": str(e)}
-            else:
-                logger.warning(
-                    "MCP web_search failed status=%s query=%s source=%s body=%s",
-                    response.status_code,
-                    query.strip() if query else "",
-                    source.strip() if source else "",
-                    response.text,
-                )
-                return {"error": f"Web search failed: {response.status_code}", "details": response.text}
-    except ValueError as e:
-        return {"error": str(e)}
+# NOTE(D10.d #96 §B.4): the ``web_search`` tool implementation moved to
+# ``aperag.mcp.tools.search_web`` so all D10 search tools live in the
+# ``aperag/mcp/tools/`` subpackage. Wire signature is preserved (no
+# breaking change for external MCP callers); §B.4 spec parameter
+# canonicalization (``top_k`` / kw-only / ``source: str | None``) is
+# deferred to the D10.h cutover lane.
 
 
 @mcp_server.tool
@@ -976,5 +887,23 @@ def get_api_key() -> str:
     )
 
 
+# Phase 9 D10.d (#96, ``docs/modularization/d10-design-pack.md`` §B):
+# import the split search tool functions so their ``@mcp_server.tool``
+# decorators register the new surface (``vector_search`` /
+# ``graph_search`` / ``fulltext_search`` / ``web_search``). The imports
+# happen at the bottom of this module — after ``mcp_server``,
+# ``API_BASE_URL``, and ``get_api_key`` are defined — to break the
+# circular import cycle (``aperag.mcp.tools.search_*`` import from
+# ``aperag.mcp.server``).
+#
+# Re-exporting the function symbols at module level preserves the
+# existing ``aperag.mcp.server.web_search`` access path for backward
+# compatibility with callers (e.g. ``tests/unit_test/test_mcp_server.py``)
+# that read attributes off the server module directly.
+from aperag.mcp.tools.search_fulltext import fulltext_search  # noqa: E402, F401
+from aperag.mcp.tools.search_graph import graph_search  # noqa: E402, F401
+from aperag.mcp.tools.search_vector import vector_search  # noqa: E402, F401
+from aperag.mcp.tools.search_web import web_search  # noqa: E402, F401
+
 # Export the server instance
 __all__ = ["mcp_server"]

aperag/mcp/tools/__init__.py

@@ -49,6 +49,22 @@
     OutlineHeading,
 )
 
+# NOTE(D10.d #96): the D10.d split search tool modules
+# (``aperag.mcp.tools.search_{vector,graph,fulltext,web}``) are
+# intentionally **not** re-exported from this package's ``__init__``
+# because they ``from aperag.mcp.server import mcp_server, ...`` at
+# module load time. After D10.c implementation (#1714 / #95) added
+# top-level ``from aperag.mcp.tools import ...`` to ``aperag/mcp/server.py``,
+# importing the search modules from here would create a partial-load
+# cycle: server.py top imports trigger this ``__init__`` → search_*
+# modules try to import from ``aperag.mcp.server`` → server.py is still
+# in mid-execution and ``mcp_server`` / ``API_BASE_URL`` /
+# ``get_api_key`` are not yet defined. Registration therefore happens
+# only via the bottom-of-server.py import block (after the symbols
+# exist). Consumers that need the function symbols can import directly
+# from the per-tool module path or via the ``aperag.mcp.server`` module
+# attribute (which re-exports them at module level for backward compat).
+
 __all__ = [
     # Stable handle types (LOCKED per §A.9)
     "ChunkId",

aperag/mcp/tools/search_fulltext.py

@@ -0,0 +1,126 @@
+# Copyright 2025 ApeCloud, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Phase 9 D10.d (#96) — fulltext_search split MCP tool (§B.3).
+
+Replaces ``search_collection use_fulltext_index=True`` with a discrete
+tool per ``docs/modularization/d10-design-pack.md`` §B.3 (Lock #5
+split). ``search_collection`` itself remains as a deprecated alias
+(§B.5 / §H.1) until the D10.h cutover.
+
+Wire shape: returns the existing ``SearchResult`` dict shape with
+``recall_type = "fulltext_search"`` for produced items. §B canonical
+shape follow-up gated on the chunk_id propagation amendment thread —
+see ``search_vector.py`` module docstring.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict
+
+import httpx
+
+from aperag.domains.retrieval.schemas import SearchResult
+from aperag.mcp.server import API_BASE_URL, get_api_key, mcp_server
+
+logger = logging.getLogger(__name__)
+
+
+@mcp_server.tool
+async def fulltext_search(
+    collection_id: str,
+    query: str,
+    top_k: int = 5,
+    keywords: list[str] | None = None,
+) -> Dict[str, Any]:
+    """Full-text keyword search within a collection (§B.3).
+
+    Use this when:
+    - You need exact keyword / phrase matches.
+    - The query has identifiable proper nouns or domain-specific terms
+      that benefit from inverted-index lookup over similarity.
+
+    Do not use this when:
+    - You need semantic similarity; use ``vector_search``.
+    - You need entity / relation traversal; use ``graph_search``.
+
+    What success means:
+    - You retrieved candidate evidence ranked by full-text relevance
+      (Elasticsearch / PostgreSQL FTS depending on collection backend).
+
+    What an empty result means:
+    - No documents matched the keywords.
+    - Consider relaxing keyword constraints, or trying ``vector_search``
+      for fuzzier semantic match.
+
+    What failure may mean:
+    - auth / permission: the current user cannot access this collection.
+    - network / timeout: the full-text path did not complete.
+    - bad request: the collection ID is invalid or full-text index missing.
+
+    Args:
+        collection_id: The ID of the collection to search.
+        query: The natural-language search query.
+        top_k: Maximum number of results to return (default: 5).
+        keywords: Optional explicit keyword list overriding the
+            auto-extracted keywords from the query.
+
+    Returns:
+        Search results with ``items`` carrying ``recall_type =
+        "fulltext_search"``. Highlight snippets / matched terms are
+        surfaced via ``items[*].metadata``.
+    """
+    try:
+        api_key = get_api_key()
+
+        fulltext_payload: Dict[str, Any] = {"topk": top_k}
+        if keywords is not None:
+            fulltext_payload["keywords"] = keywords
+
+        search_data: Dict[str, Any] = {
+            "query": query,
+            "fulltext_search": fulltext_payload,
+        }
+
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            response = await client.post(
+                f"{API_BASE_URL}/api/v2/collections/{collection_id}/searches",
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "Content-Type": "application/json",
+                },
+                json=search_data,
+            )
+            if response.status_code in (200, 201):
+                try:
+                    search_result = SearchResult.model_validate(response.json())
+                    if search_result.items and len(search_result.items) > top_k:
+                        search_result.items = search_result.items[:top_k]
+                        for i, item in enumerate(search_result.items):
+                            if item.rank is not None:
+                                item.rank = i + 1
+                    return search_result.model_dump()
+                except Exception as exc:
+                    logger.error("Failed to parse fulltext_search response: %s", exc)
+                    return {
+                        "error": "Failed to parse fulltext_search response",
+                        "details": str(exc),
+                    }
+            return {
+                "error": f"fulltext_search failed: {response.status_code}",
+                "details": response.text,
+            }
+    except ValueError as exc:
+        return {"error": str(exc)}