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

lean_explore/__init__.py

@@ -1 +1,14 @@
-"""Local package for lean explore."""
+"""Lean Explore - Search and explore Lean mathematical libraries.
+
+This package provides tools for searching Lean declarations using hybrid
+semantic and lexical search, with support for both local and remote backends.
+
+Subpackages:
+    api: Remote API client for the Lean Explore cloud service.
+    cli: Command-line interface for search and data management.
+    extract: Data extraction pipeline from doc-gen4 output.
+    mcp: Model Context Protocol server for AI assistant integration.
+    models: Data models for declarations and search results.
+    search: Local search engine with BM25 and semantic search.
+    util: Shared utilities for embeddings, reranking, and logging.
+"""

lean_explore/api/__init__.py

@@ -1 +1,12 @@
-"""Local package for lean explore."""
+"""Remote API client package for Lean Explore.
+
+This package provides an async HTTP client for connecting to the remote
+Lean Explore API service as an alternative to local search.
+
+Modules:
+    client: ApiClient class for search and declaration retrieval via HTTP.
+"""
+
+from lean_explore.api.client import ApiClient
+
+__all__ = ["ApiClient"]

lean_explore/api/client.py

@@ -1,216 +1,104 @@
-# src/lean_explore/api/client.py
+"""Client for interacting with the remote Lean Explore API."""
 
-"""Provides a client for interacting with the remote Lean Explore API.
-
-This module contains the Client class, which facilitates
-communication with the backend Lean Explore search engine API for
-performing searches and retrieving detailed information.
-"""
-
-import asyncio
-from typing import List, Optional, Union, overload
+import os
 
 import httpx
 
-from lean_explore.shared.models.api import (
-    APICitationsResponse,
-    APISearchResponse,
-    APISearchResultItem,
-)
-
-_DEFAULT_API_BASE_URL = "https://www.leanexplore.com/api/v1"
-
+from lean_explore.config import Config
+from lean_explore.models import SearchResponse, SearchResult
 
-class Client:
-    """An asynchronous client for the Lean Explore backend API.
 
-    This client handles making HTTP requests to the production API base URL,
-    authenticating with an API key, and parsing responses into Pydantic models.
+class ApiClient:
+    """Async client for the remote Lean Explore API.
 
-    Attributes:
-        api_key: The API key used for authenticating requests.
-        timeout: The timeout for HTTP requests in seconds.
-        base_url: The hardcoded base URL for the API.
+    This client handles making HTTP requests to the API, authenticating
+    with an API key, and parsing responses into SearchResult objects.
     """
 
-    def __init__(self, api_key: str, timeout: float = 10.0):
-        """Initializes the API Client.
+    def __init__(self, api_key: str | None = None, timeout: float = 10.0):
+        """Initialize the API client.
 
         Args:
-            api_key: The API key for authentication.
+            api_key: The API key for authentication. If None, reads from
+                LEANEXPLORE_API_KEY environment variable.
             timeout: Default timeout for HTTP requests in seconds.
+
+        Raises:
+            ValueError: If no API key is provided and LEANEXPLORE_API_KEY is not set.
         """
-        self.base_url: str = _DEFAULT_API_BASE_URL
-        self.api_key: str = api_key
+        self.base_url: str = Config.API_BASE_URL
+        self.api_key: str = api_key or os.getenv("LEANEXPLORE_API_KEY", "")
+        if not self.api_key:
+            raise ValueError(
+                "API key required. Pass api_key parameter or set LEANEXPLORE_API_KEY "
+                "environment variable."
+            )
         self.timeout: float = timeout
-        self._headers: dict = {"Authorization": f"Bearer {self.api_key}"}
+        self._headers: dict[str, str] = {"Authorization": f"Bearer {self.api_key}"}
 
-    async def _fetch_one_search(
+    async def search(
         self,
-        client: httpx.AsyncClient,
         query: str,
-        package_filters: Optional[List[str]],
-    ) -> APISearchResponse:
-        """Coroutine to fetch a single search result.
+        limit: int = 20,
+        rerank_top: int | None = None,  # Ignored for API (server handles reranking)
+        packages: list[str] | None = None,
+    ) -> SearchResponse:
+        """Search for Lean declarations via the API.
 
         Args:
-            client: An active httpx.AsyncClient instance.
             query: The search query string.
-            package_filters: An optional list of package names.
-
-        Returns:
-            An APISearchResponse object.
-        """
-        endpoint = f"{self.base_url}/search"
-        params = {"q": query}
-        if package_filters:
-            params["pkg"] = package_filters
-
-        response = await client.get(endpoint, params=params, headers=self._headers)
-        response.raise_for_status()
-        return APISearchResponse(**response.json())
-
-    @overload
-    async def search(
-        self, query: str, package_filters: Optional[List[str]] = None
-    ) -> APISearchResponse: ...
-
-    @overload
-    async def search(
-        self, query: List[str], package_filters: Optional[List[str]] = None
-    ) -> List[APISearchResponse]: ...
-
-    async def search(
-        self,
-        query: Union[str, List[str]],
-        package_filters: Optional[List[str]] = None,
-    ) -> Union[APISearchResponse, List[APISearchResponse]]:
-        """Performs a search for statement groups via the API.
-
-        This method can handle a single query string or a list of query strings.
-        When a list is provided, requests are sent concurrently.
-
-        Args:
-            query: The search query string or a list of query strings.
-            package_filters: An optional list of package names to filter the
-                search by. This filter is applied to all queries.
+            limit: Maximum number of results to return.
+            rerank_top: Ignored for API backend (included for interface consistency).
+            packages: Filter results to specific packages (e.g., ["Mathlib"]).
 
         Returns:
-            An APISearchResponse object if a single query was provided, or a
-            list of APISearchResponse objects if a list of queries was provided.
+            SearchResponse containing results and metadata.
 
         Raises:
-            httpx.HTTPStatusError: If the API returns an HTTP error status (4xx or 5xx).
-            httpx.RequestError: For network-related issues or other request errors.
+            httpx.HTTPStatusError: If the API returns an HTTP error status.
+            httpx.RequestError: For network-related issues.
         """
-        was_single_query = isinstance(query, str)
-        queries = [query] if was_single_query else query
+        del rerank_top  # Unused - server handles reranking
+        endpoint = f"{self.base_url}/search"
+        params: dict[str, str | int] = {"q": query, "limit": limit}
+        if packages:
+            params["packages"] = ",".join(packages)
 
         async with httpx.AsyncClient(timeout=self.timeout) as client:
-            tasks = [
-                self._fetch_one_search(client, q, package_filters) for q in queries
-            ]
-            results = await asyncio.gather(*tasks)
-
-        if was_single_query:
-            return results[0]
-        return results
-
-    async def _fetch_one_by_id(
-        self, client: httpx.AsyncClient, group_id: int
-    ) -> Optional[APISearchResultItem]:
-        endpoint = f"{self.base_url}/statement_groups/{group_id}"
-        response = await client.get(endpoint, headers=self._headers)
-        if response.status_code == 404:
-            return None
-        response.raise_for_status()
-        return APISearchResultItem(**response.json())
-
-    @overload
-    async def get_by_id(self, group_id: int) -> Optional[APISearchResultItem]: ...
-
-    @overload
-    async def get_by_id(
-        self, group_id: List[int]
-    ) -> List[Optional[APISearchResultItem]]: ...
-
-    async def get_by_id(
-        self, group_id: Union[int, List[int]]
-    ) -> Union[Optional[APISearchResultItem], List[Optional[APISearchResultItem]]]:
-        """Retrieves a specific statement group by its unique ID via the API.
+            response = await client.get(endpoint, params=params, headers=self._headers)
+            response.raise_for_status()
+            data = response.json()
 
-        Args:
-            group_id: The unique identifier of the statement group, or a list of IDs.
+            # Parse API response into our types
+            results = [SearchResult(**item) for item in data.get("results", [])]
 
-        Returns:
-            An APISearchResultItem object if a single ID was found, None if it was
-            not found. A list of Optional[APISearchResultItem] if a list of
-            IDs was provided.
+            return SearchResponse(
+                query=query,
+                results=results,
+                count=len(results),
+                processing_time_ms=data.get("processing_time_ms"),
+            )
 
-        Raises:
-            httpx.HTTPStatusError: If the API returns an HTTP error status
-                                other than 404 (e.g., 401, 403, 5xx).
-            httpx.RequestError: For network-related issues or other request errors.
-        """
-        was_single_id = isinstance(group_id, int)
-        group_ids = [group_id] if was_single_id else group_id
-
-        async with httpx.AsyncClient(timeout=self.timeout) as client:
-            tasks = [self._fetch_one_by_id(client, g_id) for g_id in group_ids]
-            results = await asyncio.gather(*tasks)
-
-        if was_single_id:
-            return results[0]
-        return results
-
-    async def _fetch_one_dependencies(
-        self, client: httpx.AsyncClient, group_id: int
-    ) -> Optional[APICitationsResponse]:
-        endpoint = f"{self.base_url}/statement_groups/{group_id}/dependencies"
-        response = await client.get(endpoint, headers=self._headers)
-        if response.status_code == 404:
-            return None
-        response.raise_for_status()
-        return APICitationsResponse(**response.json())
-
-    @overload
-    async def get_dependencies(
-        self, group_id: int
-    ) -> Optional[APICitationsResponse]: ...
-
-    @overload
-    async def get_dependencies(
-        self, group_id: List[int]
-    ) -> List[Optional[APICitationsResponse]]: ...
-
-    async def get_dependencies(
-        self, group_id: Union[int, List[int]]
-    ) -> Union[Optional[APICitationsResponse], List[Optional[APICitationsResponse]]]:
-        """Retrieves the dependencies (citations) for a specific statement group.
-
-        This method fetches the statement groups that the specified 'group_id'(s)
-        depend on (i.e., cite).
+    async def get_by_id(self, declaration_id: int) -> SearchResult | None:
+        """Retrieve a declaration by ID via the API.
 
         Args:
-            group_id: The unique identifier of the statement group, or a list of IDs.
+            declaration_id: The declaration ID.
 
         Returns:
-            An APICitationsResponse object if a single ID was provided. A list
-            of Optional[APICitationsResponse] if a list of IDs was provided.
-            None is returned for IDs that are not found.
+            SearchResult if found, None otherwise.
 
         Raises:
-            httpx.HTTPStatusError: If the API returns an HTTP error status
-                                other than 404 (e.g., 401, 403, 5xx).
-            httpx.RequestError: For network-related issues or other request errors.
+            httpx.HTTPStatusError: If the API returns an error (except 404).
+            httpx.RequestError: For network-related issues.
         """
-        was_single_id = isinstance(group_id, int)
-        group_ids = [group_id] if was_single_id else group_id
+        endpoint = f"{self.base_url}/declarations/{declaration_id}"
 
         async with httpx.AsyncClient(timeout=self.timeout) as client:
-            tasks = [self._fetch_one_dependencies(client, g_id) for g_id in group_ids]
-            results = await asyncio.gather(*tasks)
+            response = await client.get(endpoint, headers=self._headers)
+
+            if response.status_code == 404:
+                return None
 
-        if was_single_id:
-            return results[0]
-        return results
+            response.raise_for_status()
+            return SearchResult(**response.json())

lean_explore/cli/__init__.py

@@ -1 +1,10 @@
-"""Local package for lean explore."""
+"""Command-line interface package for Lean Explore.
+
+This package provides CLI commands to search for Lean declarations via the
+remote API, manage MCP servers, and download/manage local data toolchains.
+
+Modules:
+    main: Core CLI application and top-level commands.
+    data_commands: Subcommands for managing local data toolchains.
+    display: Formatting and display utilities for search results.
+"""