lean-explore 0.2.2__tar.gz → 0.3.0__tar.gz

{lean_explore-0.2.2 → lean_explore-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: lean-explore
-Version: 0.2.2
-Summary: A project to explore and rank Lean mathematical declarations.
+Version: 0.3.0
+Summary: A search engine for Lean 4 declarations.
 Author-email: Justin Asher <justinchadwickasher@gmail.com>
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -239,7 +239,28 @@ Requires-Dist: tqdm>=4.60
 Requires-Dist: requests>=2.25.0
 Dynamic: license-file
 
-# LeanExplore
+<h1 align="center">
+  LeanExplore
+</h1>
+
+<h3 align="center">
+  A search engine for Lean 4 declarations
+</h3>
+
+<p align="center">
+  <a href="https://pypi.org/project/lean-explore/">
+    <img src="https://img.shields.io/pypi/v/lean-explore.svg" alt="PyPI version" />
+  </a>
+  <a href="https://github.com/justincasher/lean-explore/blob/main/LeanExplore.pdf">
+    <img src="https://img.shields.io/badge/Paper-PDF-blue.svg" alt="Read the Paper" />
+  </a>
+  <a href="https://github.com/justincasher/lean-explore/commits/main">
+    <img src="https://img.shields.io/github/last-commit/justincasher/lean-explore" alt="last update" />
+  </a>
+  <a href="https://github.com/justincasher/lean-explore/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/justincasher/lean-explore.svg" alt="license" />
+  </a>
+</p>
 
 A search engine for Lean 4 declarations. This project provides tools and resources for exploring the Lean 4 ecosystem.
 
@@ -249,6 +270,7 @@ The current indexed projects include:
 
 * Batteries
 * Lean
+* Init
 * Mathlib
 * PhysLean
 * Std

{lean_explore-0.2.2 → lean_explore-0.3.0}/README.md

@@ -1,4 +1,25 @@
-# LeanExplore
+<h1 align="center">
+  LeanExplore
+</h1>
+
+<h3 align="center">
+  A search engine for Lean 4 declarations
+</h3>
+
+<p align="center">
+  <a href="https://pypi.org/project/lean-explore/">
+    <img src="https://img.shields.io/pypi/v/lean-explore.svg" alt="PyPI version" />
+  </a>
+  <a href="https://github.com/justincasher/lean-explore/blob/main/LeanExplore.pdf">
+    <img src="https://img.shields.io/badge/Paper-PDF-blue.svg" alt="Read the Paper" />
+  </a>
+  <a href="https://github.com/justincasher/lean-explore/commits/main">
+    <img src="https://img.shields.io/github/last-commit/justincasher/lean-explore" alt="last update" />
+  </a>
+  <a href="https://github.com/justincasher/lean-explore/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/justincasher/lean-explore.svg" alt="license" />
+  </a>
+</p>
 
 A search engine for Lean 4 declarations. This project provides tools and resources for exploring the Lean 4 ecosystem.
 
@@ -8,6 +29,7 @@ The current indexed projects include:
 
 * Batteries
 * Lean
+* Init
 * Mathlib
 * PhysLean
 * Std

{lean_explore-0.2.2 → lean_explore-0.3.0}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lean-explore"
-version = "0.2.2"
+version = "0.3.0"
 authors = [
     { name = "Justin Asher", email = "justinchadwickasher@gmail.com" },
 ]
-description = "A project to explore and rank Lean mathematical declarations."
+description = "A search engine for Lean 4 declarations."
 readme = "README.md"
 requires-python = ">=3.10"
 license = { file = "LICENSE" }

lean_explore-0.3.0/src/lean_explore/api/client.py

@@ -0,0 +1,216 @@
+# src/lean_explore/api/client.py
+
+"""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 httpx
+
+from lean_explore.shared.models.api import (
+    APICitationsResponse,
+    APISearchResponse,
+    APISearchResultItem,
+)
+
+_DEFAULT_API_BASE_URL = "https://www.leanexplore.com/api/v1"
+
+
+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.
+
+    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.
+    """
+
+    def __init__(self, api_key: str, timeout: float = 10.0):
+        """Initializes the API Client.
+
+        Args:
+            api_key: The API key for authentication.
+            timeout: Default timeout for HTTP requests in seconds.
+        """
+        self.base_url: str = _DEFAULT_API_BASE_URL
+        self.api_key: str = api_key
+        self.timeout: float = timeout
+        self._headers: dict = {"Authorization": f"Bearer {self.api_key}"}
+
+    async def _fetch_one_search(
+        self,
+        client: httpx.AsyncClient,
+        query: str,
+        package_filters: Optional[List[str]],
+    ) -> APISearchResponse:
+        """Coroutine to fetch a single search result.
+
+        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.
+
+        Returns:
+            An APISearchResponse object if a single query was provided, or a
+            list of APISearchResponse objects if a list of queries was provided.
+
+        Raises:
+            httpx.HTTPStatusError: If the API returns an HTTP error status (4xx or 5xx).
+            httpx.RequestError: For network-related issues or other request errors.
+        """
+        was_single_query = isinstance(query, str)
+        queries = [query] if was_single_query else query
+
+        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.
+
+        Args:
+            group_id: The unique identifier of the statement group, or a list of IDs.
+
+        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.
+
+        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).
+
+        Args:
+            group_id: The unique identifier of the statement group, or a list of IDs.
+
+        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.
+
+        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_dependencies(client, g_id) for g_id in group_ids]
+            results = await asyncio.gather(*tasks)
+
+        if was_single_id:
+            return results[0]
+        return results

{lean_explore-0.2.2 → lean_explore-0.3.0}/src/lean_explore/cli/agent.py

@@ -520,19 +520,27 @@ async def _run_agent_session(
                     "to the user.\n"
                     "**Output:** CLI-friendly (plain text, simple lists). "
                     "NO complex Markdown/LaTeX.\n\n"
+                    "**Tool Usage & Efficiency:**\n"
+                    "* The `search`, `get_by_id`, and `get_dependencies` tools can "
+                    "all accept a list of inputs (queries or integer IDs) to "
+                    "perform batch operations. This is highly efficient. For "
+                    "example, `search(query=['query 1', 'query 2'])` or "
+                    "`get_by_id(group_id=[123, 456])`.\n"
+                    "* Always prefer making one batch call over multiple single "
+                    "calls.\n\n"
                     "**Packages:** Use exact top-level names for filters (Batteries, "
                     "Init, Lean, Mathlib, PhysLean, Std). Map subpackage mentions "
                     "to top-level (e.g., 'Mathlib.Analysis' -> 'Mathlib').\n\n"
                     "**Core Workflow:**\n"
                     "1.  **Search & Analyze:**\n"
                     "    * Execute multiple distinct `search` queries for each user "
-                    "request (e.g., using full statements, rephrasing). Set `limit` "
+                    "request by passing a list of queries to the tool. Set `limit` "
                     ">= 10 for each search.\n"
                     "    * From all search results, select the statement(s) most "
                     "helpful to the user.\n"
-                    "    * For each selected statement, **MUST** use "
-                    "`get_dependencies` to understand its context before "
-                    "explaining.\n\n"
+                    "    * For each selected statement, use `get_dependencies` to "
+                    "understand its context. Do this efficiently by collecting all "
+                    "relevant IDs and passing them in a single list call.\n\n"
                     "2.  **Explain Results (Conversational & CLI-Friendly):**\n"
                     "    * Briefly state your search approach (e.g., 'I looked into X "
                     "in Mathlib...').\n"
@@ -543,15 +551,14 @@ async def _run_agent_session(
                     "`informal_description`, `statement_text`).\n"
                     "        * Provide the full Lean code (`statement_text`).\n"
                     "        * Explain key dependencies (what they are, their role, "
-                    "using `statement_text` or `display_statement_text` from "
-                    "`get_dependencies` output).\n"
+                    "using `statement_text` from `get_dependencies` output).\n"
                     "3.  **Specific User Follow-ups (If Asked):**\n"
-                    "    * **`get_by_id`:** For a specific ID, provide: ID, Lean name, "
-                    "statement text, source/line, docstring, informal description "
-                    "(structured CLI format).\n"
-                    "    * **`get_dependencies` (Direct Request):** For all "
-                    "dependencies of an ID, list: ID, Lean name, statement "
-                    "text/summary. State total count.\n\n"
+                    "    * **`get_by_id`:** For one or more IDs, provide: ID, "
+                    "Lean name, statement text, source/line, docstring, informal "
+                    "description (structured CLI format).\n"
+                    "    * **`get_dependencies` (Direct Request):** For one or more "
+                    "IDs, list dependencies for each: ID, Lean name, statement "
+                    "text/summary. State total count per ID.\n\n"
                     "Always be concise, helpful, and clear."
                 ),
                 mcp_servers=[server_instance],