lean-explore 1.0.1__py3-none-any.whl → 1.1.0__py3-none-any.whl

lean_explore/mcp/tools.py

@@ -8,10 +8,32 @@ from mcp.server.fastmcp import Context as MCPContext
 
 from lean_explore.mcp.app import AppContext, BackendServiceType, mcp_app
 from lean_explore.models import SearchResponse, SearchResult
+from lean_explore.models.search_types import (
+    SearchResultSummary,
+    SearchSummaryResponse,
+    extract_bold_description,
+)
+
+
+class SearchResultSummaryDict(TypedDict, total=False):
+    """Serialized SearchResultSummary for slim MCP search responses."""
+
+    id: int
+    name: str
+    description: str | None
+
+
+class SearchSummaryResponseDict(TypedDict, total=False):
+    """Serialized SearchSummaryResponse for slim MCP search responses."""
+
+    query: str
+    results: list[SearchResultSummaryDict]
+    count: int
+    processing_time_ms: int | None
 
 
 class SearchResultDict(TypedDict, total=False):
-    """Serialized SearchResult for MCP tool responses."""
+    """Serialized SearchResult for verbose MCP tool responses."""
 
     id: int
     name: str
@@ -24,7 +46,7 @@ class SearchResultDict(TypedDict, total=False):
 
 
 class SearchResponseDict(TypedDict, total=False):
-    """Serialized SearchResponse for MCP tool responses."""
+    """Serialized SearchResponse for verbose MCP tool responses."""
 
     query: str
     results: list[SearchResultDict]
@@ -55,6 +77,41 @@ async def _get_backend_from_context(ctx: MCPContext) -> BackendServiceType:
     return backend
 
 
+async def _execute_backend_search(
+    backend: BackendServiceType,
+    query: str,
+    limit: int,
+    rerank_top: int | None,
+    packages: list[str] | None,
+) -> SearchResponse:
+    """Execute a search on the backend, handling both async and sync backends.
+
+    Args:
+        backend: The backend service (ApiClient or Service).
+        query: The search query string.
+        limit: Maximum number of results.
+        rerank_top: Number of candidates to rerank with cross-encoder.
+        packages: Optional package filter.
+
+    Returns:
+        The search response from the backend.
+
+    Raises:
+        RuntimeError: If the backend does not support search.
+    """
+    if not hasattr(backend, "search"):
+        logger.error("Backend service does not have a 'search' method.")
+        raise RuntimeError("Search functionality not available on configured backend.")
+
+    if asyncio.iscoroutinefunction(backend.search):
+        return await backend.search(
+            query=query, limit=limit, rerank_top=rerank_top, packages=packages
+        )
+    return backend.search(
+        query=query, limit=limit, rerank_top=rerank_top, packages=packages
+    )
+
+
 @mcp_app.tool()
 async def search(
     ctx: MCPContext,
@@ -62,8 +119,12 @@ async def search(
     limit: int = 10,
     rerank_top: int | None = 50,
     packages: list[str] | None = None,
-) -> SearchResponseDict:
-    """Searches Lean declarations by a query string.
+) -> SearchSummaryResponseDict:
+    """Searches Lean declarations and returns concise results.
+
+    Returns slim results (id, name, short description) to minimize token usage.
+    Use get_by_id to retrieve full details for specific declarations, or
+    search_verbose to get all fields upfront.
 
     Args:
         ctx: The MCP context, providing access to the backend service.
@@ -75,7 +136,7 @@ async def search(
             Defaults to None (all packages).
 
     Returns:
-        A dictionary containing the search response with results.
+        A dictionary containing slim search results with id, name, and description.
     """
     backend = await _get_backend_from_context(ctx)
     logger.info(
@@ -83,21 +144,65 @@ async def search(
         f"rerank_top: {rerank_top}, packages: {packages}"
     )
 
-    if not hasattr(backend, "search"):
-        logger.error("Backend service does not have a 'search' method.")
-        raise RuntimeError("Search functionality not available on configured backend.")
+    response = await _execute_backend_search(
+        backend, query, limit, rerank_top, packages
+    )
 
-    # Call backend search (handle both async and sync)
-    if asyncio.iscoroutinefunction(backend.search):
-        response: SearchResponse = await backend.search(
-            query=query, limit=limit, rerank_top=rerank_top, packages=packages
-        )
-    else:
-        response: SearchResponse = backend.search(
-            query=query, limit=limit, rerank_top=rerank_top, packages=packages
+    # Convert full results to slim summaries
+    summary_results = [
+        SearchResultSummary(
+            id=result.id,
+            name=result.name,
+            description=extract_bold_description(result.informalization),
         )
+        for result in response.results
+    ]
+    summary_response = SearchSummaryResponse(
+        query=response.query,
+        results=summary_results,
+        count=response.count,
+        processing_time_ms=response.processing_time_ms,
+    )
+
+    return summary_response.model_dump(exclude_none=True)
+
+
+@mcp_app.tool()
+async def search_verbose(
+    ctx: MCPContext,
+    query: str,
+    limit: int = 10,
+    rerank_top: int | None = 50,
+    packages: list[str] | None = None,
+) -> SearchResponseDict:
+    """Searches Lean declarations and returns full results with all fields.
+
+    Returns complete results including source code, dependencies, module info,
+    and full informalization. Use this when you need all details upfront. For
+    a more concise overview, use search instead.
+
+    Args:
+        ctx: The MCP context, providing access to the backend service.
+        query: A search query string, e.g., "continuous function".
+        limit: The maximum number of search results to return. Defaults to 10.
+        rerank_top: Number of candidates to rerank with cross-encoder. Set to 0 or
+            None to skip reranking. Defaults to 50. Only used with local backend.
+        packages: Filter results to specific packages (e.g., ["Mathlib", "Std"]).
+            Defaults to None (all packages).
+
+    Returns:
+        A dictionary containing the full search response with all fields.
+    """
+    backend = await _get_backend_from_context(ctx)
+    logger.info(
+        f"MCP Tool 'search_verbose' called with query: '{query}', limit: {limit}, "
+        f"rerank_top: {rerank_top}, packages: {packages}"
+    )
+
+    response = await _execute_backend_search(
+        backend, query, limit, rerank_top, packages
+    )
 
-    # Return as dict for MCP
     return response.model_dump(exclude_none=True)
 
 
@@ -108,6 +213,9 @@ async def get_by_id(
 ) -> SearchResultDict | None:
     """Retrieves a specific declaration by its unique identifier.
 
+    Returns the full declaration including source code, dependencies, module
+    info, and informalization. Use this to expand results from the search tool.
+
     Args:
         ctx: The MCP context, providing access to the backend service.
         declaration_id: The unique integer identifier of the declaration.

lean_explore/models/__init__.py

@@ -4,6 +4,20 @@ This package contains database models and type definitions for search results.
 """
 
 from lean_explore.models.search_db import Base, Declaration
-from lean_explore.models.search_types import SearchResponse, SearchResult
+from lean_explore.models.search_types import (
+    SearchResponse,
+    SearchResult,
+    SearchResultSummary,
+    SearchSummaryResponse,
+    extract_bold_description,
+)
 
-__all__ = ["Base", "Declaration", "SearchResult", "SearchResponse"]
+__all__ = [
+    "Base",
+    "Declaration",
+    "SearchResult",
+    "SearchResponse",
+    "SearchResultSummary",
+    "SearchSummaryResponse",
+    "extract_bold_description",
+]

lean_explore/models/search_types.py

@@ -1,8 +1,62 @@
 """Type definitions for search results and related data structures."""
 
+import re
+
 from pydantic import BaseModel, ConfigDict
 
 
+def extract_bold_description(informalization: str | None) -> str | None:
+    """Extract the bold header text from an informalization string.
+
+    Informalizations follow the pattern: **Bold Title.** Rest of description...
+    This function extracts just the bold title portion.
+
+    Args:
+        informalization: The full informalization text, or None.
+
+    Returns:
+        The bold header text (without ** markers), or None if no bold
+        header is found or input is None.
+    """
+    if not informalization:
+        return None
+    match = re.match(r"\*\*(.+?)\*\*", informalization)
+    return match.group(1) if match else None
+
+
+class SearchResultSummary(BaseModel):
+    """A slim search result containing only identification and description.
+
+    Used by the MCP search tool to return concise results that minimize
+    token usage. Consumers can use the id to fetch full details via get_by_id.
+    """
+
+    id: int
+    """Primary key identifier."""
+
+    name: str
+    """Fully qualified Lean name (e.g., 'Nat.add')."""
+
+    description: str | None
+    """Short description extracted from the informalization bold header."""
+
+
+class SearchSummaryResponse(BaseModel):
+    """Response from a slim search operation containing summary results."""
+
+    query: str
+    """The original search query string."""
+
+    results: list[SearchResultSummary]
+    """List of slim search results."""
+
+    count: int
+    """Number of results returned."""
+
+    processing_time_ms: int | None = None
+    """Processing time in milliseconds, if available."""
+
+
 class SearchResult(BaseModel):
     """A search result representing a Lean declaration.
 

lean_explore/search/engine.py

@@ -59,7 +59,7 @@ class SearchEngine:
         reranker_model_name: str = "Qwen/Qwen3-Reranker-0.6B",
         faiss_index_path: Path | None = None,
         faiss_ids_map_path: Path | None = None,
-        use_local_data: bool = True,
+        use_local_data: bool = False,
     ):
         """Initialize the search engine.
 
@@ -71,8 +71,9 @@ class SearchEngine:
             reranker_model_name: Name of the reranker model to use.
             faiss_index_path: Path to FAISS index. Defaults to config path.
             faiss_ids_map_path: Path to FAISS ID mapping. Defaults to config path.
-            use_local_data: If True, use DATA_DIRECTORY paths. If False, use
-                CACHE_DIRECTORY paths (for downloaded remote data).
+            use_local_data: If True, use DATA_DIRECTORY paths (for locally
+                generated data). If False, use CACHE_DIRECTORY paths (for
+                data downloaded via 'lean-explore data fetch').
         """
         self._embedding_client = embedding_client
         self._embedding_model_name = embedding_model_name

{lean_explore-1.0.1.dist-info → lean_explore-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-explore
-Version: 1.0.1
+Version: 1.1.0
 Summary: A search engine for Lean 4 declarations.
 Author-email: Justin Asher <justinchadwickasher@gmail.com>
 License:                                  Apache License

{lean_explore-1.0.1.dist-info → lean_explore-1.1.0.dist-info}/RECORD

@@ -21,12 +21,12 @@ lean_explore/extract/types.py,sha256=Sp6sYuioTE_Gs0Z0lbq4h7OMyAnaZafdLV8UGtKn-zs
 lean_explore/mcp/__init__.py,sha256=YO0RM466ik2jQk8YMDITzkm3AHPtjEhn7Wm7rOusUXo,462
 lean_explore/mcp/app.py,sha256=PJ2HwX6VyTqKejuI1G8Ld4aO9XWp9hT5H8loaA5g0Lc,2173
 lean_explore/mcp/server.py,sha256=Lf3SCn8ghPNkZ3BybHh3VCXn91F-yX6RSRke1rvC7Pk,8234
-lean_explore/mcp/tools.py,sha256=iOpJkezDDIBGfAKU5xfqVjrGQEP0MLGHHdkqHEnLPDE,4515
-lean_explore/models/__init__.py,sha256=G2Xeld_DADq-hhxm1K1CrEPeAM3ylHU2ckCh42Ogxro,321
+lean_explore/mcp/tools.py,sha256=ehCUEKu6HXzK07aAgpLUDdg4UnVDH_kbvz9aXbOIfbs,8075
+lean_explore/models/__init__.py,sha256=k4tDULTDIp61iLuP-CBXLJzjCaEBgNVgO_x9JpdrjgY,523
 lean_explore/models/search_db.py,sha256=_a6B6FpqUevyHvW4KmNLeziiznIuxftpMUy0AtSDBJE,2673
-lean_explore/models/search_types.py,sha256=VcFGrK5Z12Cg9f2R-Y6GXGlh2SunyBAJaZ5I4DG0AUw,1442
+lean_explore/models/search_types.py,sha256=3r0eql--zoTGRtwosbvZpTMK7tdBdPSfWPBFTU_pupE,3001
 lean_explore/search/__init__.py,sha256=0k_iHe5xrurepznk7NzMYz10QFbK10ydMlpFlsuyFSc,1216
-lean_explore/search/engine.py,sha256=e4F_wOChfY6aBWQbYXDpsE_gIENXzd-Vj08aRK5qrls,23591
+lean_explore/search/engine.py,sha256=oAsqiltBEXsbur0t77-zG8ATgcZ-8vKX8vvdoPNZsv0,23660
 lean_explore/search/scoring.py,sha256=VkH-kpGheX14_tf8uJYBOp0nrG05_JJLmv7_0QdfAQk,4168
 lean_explore/search/service.py,sha256=6CWN-U5jxv7cTzc7ffitgzNMn3k59LfirpteC4xsvSE,1915
 lean_explore/search/tokenization.py,sha256=1EHd3dbJLwnmrj2SmdU1W8WoyCUnzhJB5gzmZLpWifs,1831
@@ -35,9 +35,9 @@ lean_explore/util/embedding_client.py,sha256=6XJGJrGTXAiefDr-E1j_SPHTTZMIJYi62Pw
 lean_explore/util/logging.py,sha256=hF8YPi-1I6DdC1B_yROXA6u5GG14IIhD0Nym2FfqgRA,649
 lean_explore/util/openrouter_client.py,sha256=C_0HLO5o1seYjGl2zn6897i2onK7CdI6XxtE3cWb3Os,1926
 lean_explore/util/reranker_client.py,sha256=kLCTGPMQuphjwAj0PPi9KXpSzDP7o9JRQJpTbmWGiMs,6074
-lean_explore-1.0.1.dist-info/licenses/LICENSE,sha256=l4QLw1kIvEOjUktmmKm4dycK1E249Qs2s2AQTYbMXpY,11354
-lean_explore-1.0.1.dist-info/METADATA,sha256=Cuj-elh89YOPKaM_bf7jxvsumb1nQpm_sytbB8bF0ak,17084
-lean_explore-1.0.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-lean_explore-1.0.1.dist-info/entry_points.txt,sha256=FuKSRE7GmI9B_kM-xoiWEJj2dQ4upqhHnw8qH1vcjW8,59
-lean_explore-1.0.1.dist-info/top_level.txt,sha256=h51BKWrFvB7iym-IlaNAAHX5MZfA8Gmg-aDuXGo0fQ8,13
-lean_explore-1.0.1.dist-info/RECORD,,
+lean_explore-1.1.0.dist-info/licenses/LICENSE,sha256=l4QLw1kIvEOjUktmmKm4dycK1E249Qs2s2AQTYbMXpY,11354
+lean_explore-1.1.0.dist-info/METADATA,sha256=i1cn36xApYYYwA3K2GxiVzoQ-UeJ-yPhkoHTexnJbGI,17084
+lean_explore-1.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+lean_explore-1.1.0.dist-info/entry_points.txt,sha256=FuKSRE7GmI9B_kM-xoiWEJj2dQ4upqhHnw8qH1vcjW8,59
+lean_explore-1.1.0.dist-info/top_level.txt,sha256=h51BKWrFvB7iym-IlaNAAHX5MZfA8Gmg-aDuXGo0fQ8,13
+lean_explore-1.1.0.dist-info/RECORD,,