langchain-serpex-python 0.1.0__py3-none-any.whl

langchain_serpex_python/__init__.py

@@ -0,0 +1,10 @@
+"""SERPEX integration for LangChain.
+
+This module provides tools for searching the web using the SERPEX API,
+which supports multiple search engines including Google, Bing, DuckDuckGo,
+Baidu, and Yandex.
+"""
+
+from langchain_serpex_python.tools import SerpexSearchResults
+
+__all__ = ["SerpexSearchResults"]

langchain_serpex_python/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

langchain_serpex_python/tools.py

@@ -0,0 +1,285 @@
+"""SERPEX Search Tool for LangChain."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from pydantic import Field, SecretStr, model_validator
+
+
+class SerpexSearchResults(BaseTool):
+    """Tool for searching the web using the SERPEX API.
+
+    SERPEX provides multi-engine search results from Google, Bing, DuckDuckGo,
+    Brave, Yahoo, and Yandex search engines in JSON format.
+
+    Setup:
+        Install `langchain-serpex` and set environment variable `SERPEX_API_KEY`.
+
+        ```bash
+        pip install -U langchain-serpex
+        export SERPEX_API_KEY="your-serpex-api-key"
+        ```
+
+    Instantiation:
+        ```python
+        from langchain_serpex import SerpexSearchResults
+
+        # With explicit API key
+        tool = SerpexSearchResults(
+            api_key="your-serpex-api-key",
+            engine="auto",  # or google, bing, duckduckgo, brave, yahoo, yandex
+            time_range="day"  # optional: all, day, week, month, year
+        )
+
+        # Or using environment variable
+        tool = SerpexSearchResults()
+        ```
+
+    Invocation:
+        ```python
+        # Basic search
+        results = tool.invoke("latest AI developments")
+        print(results)
+
+        # With specific parameters
+        results = tool.invoke({
+            "query": "Python programming",
+            "engine": "google",
+            "time_range": "week"
+        })
+        ```
+
+    Example with Agent:
+        ```python
+        from langchain_serpex import SerpexSearchResults
+        from langchain_openai import ChatOpenAI
+        from langchain.agents import initialize_agent, AgentType
+
+        search = SerpexSearchResults(api_key="your-key")
+        llm = ChatOpenAI(temperature=0)
+
+        agent = initialize_agent(
+            tools=[search],
+            llm=llm,
+            agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION
+        )
+
+        result = agent.run("What's the latest news about AI?")
+        ```
+    """
+
+    name: str = "serpex_search"
+    description: str = (
+        "A powerful multi-engine web search tool. "
+        "Useful for answering questions about current events, "
+        "finding information from the web, and getting real-time data. "
+        "Input should be a search query string. "
+        "Supports automatic routing with retry logic and multiple search engines "
+        "(Google, Bing, DuckDuckGo, Brave, Yahoo, Yandex)."
+    )
+
+    api_key: SecretStr = Field(default_factory=lambda: SecretStr(""))
+    engine: str = Field(
+        default="auto",
+        description=(
+            "Search engine: auto, google, bing, duckduckgo, brave, yahoo, yandex"
+        ),
+    )
+    category: str = Field(
+        default="web",
+        description="Search category (currently only 'web' supported)",
+    )
+    time_range: str | None = Field(
+        default=None,
+        description=(
+            "Time range: all, day, week, month, year (not supported by Brave)"
+        ),
+    )
+
+    base_url: str = Field(default="https://api.serpex.dev")
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_environment(cls, values: dict[str, Any]) -> dict[str, Any]:
+        """Validate that API key exists in environment."""
+        api_key = values.get("api_key")
+        if not api_key or (
+            isinstance(api_key, SecretStr) and not api_key.get_secret_value()
+        ):
+            api_key_from_env = os.getenv("SERPEX_API_KEY", "")
+            if api_key_from_env:
+                values["api_key"] = SecretStr(api_key_from_env)
+        elif isinstance(api_key, str):
+            values["api_key"] = SecretStr(api_key)
+
+        return values
+
+    def _build_params(self, query: str, **kwargs: Any) -> dict[str, Any]:
+        """Build parameters for the API request."""
+        params: dict[str, Any] = {
+            "q": query,
+            "engine": kwargs.get("engine", self.engine),
+            "category": kwargs.get("category", self.category),
+        }
+
+        # Add time_range if specified
+        time_range = kwargs.get("time_range") or self.time_range
+        if time_range is not None:
+            params["time_range"] = time_range
+
+        return params
+
+    def _format_results(self, data: dict[str, Any]) -> str:
+        """Format the search results into a readable string."""
+        results_parts: list[str] = []
+
+        # Instant answers (from knowledge panels/answer boxes)
+        if (
+            "answers" in data
+            and isinstance(data["answers"], list)
+            and len(data["answers"]) > 0
+        ):
+            answer = data["answers"][0]
+            if "answer" in answer and answer["answer"]:
+                results_parts.append(f"Answer: {answer['answer']}")
+            elif "snippet" in answer and answer["snippet"]:
+                results_parts.append(f"Featured Snippet: {answer['snippet']}")
+
+        # Infoboxes (knowledge panels)
+        if (
+            "infoboxes" in data
+            and isinstance(data["infoboxes"], list)
+            and len(data["infoboxes"]) > 0
+        ):
+            infobox = data["infoboxes"][0]
+            if "description" in infobox and infobox["description"]:
+                results_parts.append(f"Knowledge Panel: {infobox['description']}")
+
+        # Organic search results
+        if (
+            "results" in data
+            and isinstance(data["results"], list)
+            and len(data["results"]) > 0
+        ):
+            num_results = data.get("metadata", {}).get(
+                "number_of_results", len(data["results"])
+            )
+            results_parts.append(f"\nFound {num_results} results:\n")
+
+            for i, result in enumerate(data["results"][:10], 1):
+                title = result.get("title", "")
+                url = result.get("url", "")
+                snippet = result.get("snippet", "")
+                published_date = result.get("published_date")
+
+                result_text = f"[{i}] {title}"
+                if url:
+                    result_text += f"\nURL: {url}"
+                if snippet:
+                    result_text += f"\n{snippet}"
+                if published_date:
+                    result_text += f"\nPublished: {published_date}"
+
+                results_parts.append(result_text)
+
+        # Search suggestions
+        if (
+            not results_parts
+            and "suggestions" in data
+            and isinstance(data["suggestions"], list)
+            and len(data["suggestions"]) > 0
+        ):
+            results_parts.append("No direct results found. Related searches:")
+            results_parts.extend(data["suggestions"])
+
+        # Query corrections
+        if (
+            not results_parts
+            and "corrections" in data
+            and isinstance(data["corrections"], list)
+            and len(data["corrections"]) > 0
+        ):
+            results_parts.append(f"Did you mean: {', '.join(data['corrections'])}?")
+
+        if not results_parts:
+            return "No search results found."
+
+        return "\n\n".join(results_parts)
+
+    def _run(
+        self,
+        query: str,
+        run_manager: CallbackManagerForToolRun | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Execute the search."""
+        params = self._build_params(query, **kwargs)
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key.get_secret_value()}",
+            "Content-Type": "application/json",
+        }
+
+        url = f"{self.base_url}/api/search"
+
+        try:
+            with httpx.Client() as client:
+                response = client.get(url, params=params, headers=headers, timeout=30.0)
+                response.raise_for_status()
+                data = response.json()
+
+                if "error" in data:
+                    return f"SERPEX API error: {data['error']}"
+
+                return self._format_results(data)
+
+        except httpx.HTTPStatusError as e:
+            return f"HTTP error occurred: {e.response.status_code} - {e.response.text}"
+        except httpx.RequestError as e:
+            return f"Request error occurred: {str(e)}"
+        except Exception as e:
+            return f"Error searching with SERPEX: {str(e)}"
+
+    async def _arun(
+        self,
+        query: str,
+        run_manager: CallbackManagerForToolRun | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Execute the search asynchronously."""
+        params = self._build_params(query, **kwargs)
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key.get_secret_value()}",
+            "Content-Type": "application/json",
+        }
+
+        url = f"{self.base_url}/api/search"
+
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.get(
+                    url, params=params, headers=headers, timeout=30.0
+                )
+                response.raise_for_status()
+                data = response.json()
+
+                if "error" in data:
+                    return f"SERPEX API error: {data['error']}"
+
+                return self._format_results(data)
+
+        except httpx.HTTPStatusError as e:
+            return f"HTTP error occurred: {e.response.status_code} - {e.response.text}"
+        except httpx.RequestError as e:
+            return f"Request error occurred: {str(e)}"
+        except Exception as e:
+            return f"Error searching with SERPEX: {str(e)}"
+
+
+__all__ = ["SerpexSearchResults"]

langchain_serpex_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: langchain-serpex-python
+Version: 0.1.0
+Summary: An integration package connecting SERPEX and LangChain (Python)
+Project-URL: Homepage, https://docs.langchain.com/oss/python/integrations/providers/serpex
+Project-URL: Documentation, https://serpex.dev/docs
+Project-URL: Source, https://github.com/divyeshradadiya/langchain-serpex
+Project-URL: Repository, https://github.com/divyeshradadiya/langchain-serpex
+License: MIT
+License-File: LICENSE
+Requires-Python: <4.0.0,>=3.10.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: langchain-core<2.0.0,>=1.0.0
+Description-Content-Type: text/markdown
+
+# langchain-serpex-python
+
+[![PyPI - Version](https://img.shields.io/pypi/v/langchain-serpex-python?label=%20)](https://pypi.org/project/langchain-serpex-python/#history)
+[![PyPI - License](https://img.shields.io/pypi/l/langchain-serpex-python)](https://opensource.org/licenses/MIT)
+[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/langchainai.svg?style=social&label=Follow%20%40LangChainAI)](https://twitter.com/langchainai)
+
+This package contains the LangChain integration with SERPEX (Python).
+
+## Installation
+
+```bash
+pip install langchain-serpex-python
+```
+
+## What is SERPEX?
+
+SERPEX is a powerful multi-engine search API that provides access to search results from Google, Bing, DuckDuckGo, Baidu, Yandex, and other search engines in JSON format. It's designed for developers building AI applications, SEO tools, market research platforms, and data aggregation services.
+
+## Features
+
+- **Multi-Engine Support**: Search across Google, Bing, DuckDuckGo, Baidu, and Yandex
+- **Rich Results**: Get organic results, answer boxes, knowledge graphs, news, images, videos, and shopping results
+- **Localization**: Support for location-based and language-specific searches
+- **Real-time Data**: Access to current search results
+- **Easy Integration**: Simple API with comprehensive documentation
+
+## Quick Start
+
+### Get Your API Key
+
+Sign up at [SERPEX](https://serpex.dev) to get your API key.
+
+### Basic Usage
+
+```python
+from langchain_serpex_python import SerpexSearchResults
+
+# Initialize the tool
+tool = SerpexSearchResults(
+    api_key="your-serpex-api-key",
+    engine="google",
+    num_results=10
+)
+
+# Perform a search
+results = tool.invoke("latest AI developments")
+print(results)
+```
+
+### With Agents
+
+```python
+from langchain_serpex_python import SerpexSearchResults
+from langchain_openai import ChatOpenAI
+from langchain.agents import initialize_agent, AgentType
+
+# Initialize the search tool
+search_tool = SerpexSearchResults(
+    api_key="your-serpex-api-key",
+    engine="google",
+    num_results=5
+)
+
+# Initialize the LLM
+llm = ChatOpenAI(temperature=0)
+
+# Create an agent with the search tool
+agent = initialize_agent(
+    tools=[search_tool],
+    llm=llm,
+    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
+    verbose=True
+)
+
+# Run the agent
+result = agent.run("What are the latest developments in quantum computing?")
+print(result)
+```
+
+### Advanced Configuration
+
+```python
+from langchain_serpex_python import SerpexSearchResults
+
+# Configure with advanced parameters
+tool = SerpexSearchResults(
+    api_key="your-serpex-api-key",
+    engine="google",
+    num_results=20,
+    gl="us",  # Country code
+    hl="en",  # Language code
+    location="New York",  # Specific location
+    time_period="m",  # Results from past month
+    safe_search="moderate"
+)
+
+# Search for location-specific results
+results = tool.invoke("best restaurants")
+print(results)
+```
+
+### Different Search Engines
+
+```python
+from langchain_serpex_python import SerpexSearchResults
+
+# Google Search
+google_tool = SerpexSearchResults(api_key="your-key", engine="google")
+google_results = google_tool.invoke("Python programming")
+
+# Bing Search
+bing_tool = SerpexSearchResults(api_key="your-key", engine="bing")
+bing_results = bing_tool.invoke("Python programming")
+
+# DuckDuckGo Search
+ddg_tool = SerpexSearchResults(api_key="your-key", engine="duckduckgo")
+ddg_results = ddg_tool.invoke("Python programming")
+```
+
+## Configuration
+
+### Environment Variables
+
+You can set your SERPEX API key as an environment variable:
+
+```bash
+export SERPEX_API_KEY="your-serpex-api-key"
+```
+
+Then use the tool without passing the API key:
+
+```python
+from langchain_serpex_python import SerpexSearchResults
+
+tool = SerpexSearchResults()  # Will use SERPEX_API_KEY from environment
+```
+
+### Parameters
+
+- `api_key` (str): Your SERPEX API key (required)
+- `engine` (str): Search engine to use - "google", "bing", "duckduckgo", "baidu", "yandex" (default: "google")
+- `num_results` (int): Number of results to return, 1-100 (default: 10)
+- `gl` (str): Country code for localized results (e.g., "us", "uk", "ca")
+- `hl` (str): Language code (e.g., "en", "es", "fr")
+- `location` (str): Specific location for localized results
+- `time_period` (str): Time filter - "d" (day), "w" (week), "m" (month), "y" (year)
+- `safe_search` (str): Safe search filter - "off", "moderate", "strict"
+
+## Documentation
+
+For more detailed documentation, visit:
+- [LangChain Documentation](https://python.langchain.com)
+- [SERPEX API Documentation](https://serpex.dev/docs)
+
+## Support
+
+For issues and questions:
+- GitHub Issues: [langchain-serpex issues](https://github.com/langchain-ai/langchain/issues)
+- SERPEX Support: [support@serpex.dev](mailto:support@serpex.dev)
+
+## License
+
+This package is licensed under the MIT License.
+
+## CI / Publishing
+
+A GitHub Actions workflow is provided to publish the package to PyPI when a tag like `v*` is pushed or when a release is published.
+
+Required repository secret:
+- `PYPI_API_TOKEN` — a PyPI API token with permission to upload the package. Set this in the repository's Settings → Secrets → Actions.
+
+To publish a new release, create a tag `vMAJOR.MINOR.PATCH` and push it or create a release in GitHub; the workflow will build sdist and wheel and upload them to PyPI.

langchain_serpex_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+langchain_serpex_python/__init__.py,sha256=owZSYVufiNrS44tCs9XlDkJdh3ZcW1cibAOxDbFqk0A,305
+langchain_serpex_python/py.typed,sha256=8PjyZ1aVoQpRVvt71muvuq5qE-jTFZkK-GLHkhdebmc,26
+langchain_serpex_python/tools.py,sha256=H45fTP0XvPBk_kkgGAcLDYclRQ96Z1V_oI36jc_knGU,9488
+langchain_serpex_python-0.1.0.dist-info/METADATA,sha256=v_2LDkohScvgs7xrsAUi-sIcgLMsZbMVFvfitgsbzXA,5906
+langchain_serpex_python-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+langchain_serpex_python-0.1.0.dist-info/licenses/LICENSE,sha256=oB3P_cEpG0BD8qgdJJqfPkXJA28jCMnN_u_hg3E3HoA,1066
+langchain_serpex_python-0.1.0.dist-info/RECORD,,

langchain_serpex_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

langchain_serpex_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 LangChain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.