lean-explore 0.2.2__py3-none-any.whl → 1.0.0__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,124 +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.
-"""
-
-from typing import List, Optional
+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.
+class ApiClient:
+    """Async client for the remote Lean Explore API.
 
-    This client handles making HTTP requests to the production API base URL,
-    authenticating with an API key, and parsing responses into Pydantic models.
-
-    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 search(
-        self, query: str, package_filters: Optional[List[str]] = None
-    ) -> APISearchResponse:
-        """Performs a search for statement groups via the API.
+        self,
+        query: str,
+        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:
             query: The search query string.
-            package_filters: An optional list of package names to filter the
-                search by.
+            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 containing the search results and
-            associated metadata.
+            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.
         """
+        del rerank_top  # Unused - server handles reranking
         endpoint = f"{self.base_url}/search"
-        params = {"q": query}
-        if package_filters:
-            params["pkg"] = package_filters
+        params: dict[str, str | int] = {"q": query, "limit": limit}
+        if packages:
+            params["packages"] = ",".join(packages)
 
         async with httpx.AsyncClient(timeout=self.timeout) as client:
             response = await client.get(endpoint, params=params, headers=self._headers)
             response.raise_for_status()
-            return APISearchResponse(**response.json())
+            data = response.json()
 
-    async def get_by_id(self, group_id: int) -> Optional[APISearchResultItem]:
-        """Retrieves a specific statement group by its unique ID via the API.
+            # Parse API response into our types
+            results = [SearchResult(**item) for item in data.get("results", [])]
 
-        Args:
-            group_id: The unique identifier of the statement group.
+            return SearchResponse(
+                query=query,
+                results=results,
+                count=len(results),
+                processing_time_ms=data.get("processing_time_ms"),
+            )
 
-        Returns:
-            An APISearchResultItem object if the statement group is found,
-            otherwise None if a 404 error is received.
-
-        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.
-        """
-        endpoint = f"{self.base_url}/statement_groups/{group_id}"
-        async with httpx.AsyncClient(timeout=self.timeout) as client:
-            response = await client.get(endpoint, headers=self._headers)
-            if response.status_code == 404:
-                return None
-            response.raise_for_status()
-            return APISearchResultItem(**response.json())
-
-    async def get_dependencies(self, group_id: int) -> Optional[APICitationsResponse]:
-        """Retrieves the dependencies (citations) for a specific statement group.
-
-        This method fetches the statement groups that the specified 'group_id'
-        depends on (i.e., cites).
+    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 for which
-                to fetch dependencies.
+            declaration_id: The declaration ID.
 
         Returns:
-            An APICitationsResponse object containing the list of dependencies
-            (cited items) if the source statement group is found. Returns None
-            if the source statement group itself is not found (receives a 404).
+            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.
         """
-        endpoint = f"{self.base_url}/statement_groups/{group_id}/dependencies"
+        endpoint = f"{self.base_url}/declarations/{declaration_id}"
+
         async with httpx.AsyncClient(timeout=self.timeout) as client:
             response = await client.get(endpoint, headers=self._headers)
+
             if response.status_code == 404:
                 return None
+
             response.raise_for_status()
-            return APICitationsResponse(**response.json())
+            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.
+"""