langchain-crustapi 0.1.0__tar.gz

langchain_crustapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 COLDWIRES LLC
+
+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.

langchain_crustapi-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: langchain-crustapi
+Version: 0.1.0
+Summary: An integration package connecting CrustAPI (Google search data) and LangChain
+License: MIT
+License-File: LICENSE
+Keywords: langchain,crustapi,google,search,serp,maps,tools
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: aiohttp (>=3.9,<4.0)
+Requires-Dist: langchain-core (>=0.3,<2.0)
+Requires-Dist: requests (>=2.32,<3.0)
+Project-URL: Repository, https://github.com/crustapi/langchain-crustapi
+Description-Content-Type: text/markdown
+
+# langchain-crustapi
+
+This package connects [CrustAPI](https://crustapi.com) to LangChain, giving your chains and agents clean, structured Google data from one endpoint: web search, Maps, News, Shopping, Images, Videos, Places, Scholar, and Patents. You only pay for successful results, and there's a free tier with no card.
+
+## Installation
+
+```bash
+pip install -U langchain-crustapi
+export CRUSTAPI_API_KEY="your-key"   # free at https://crustapi.com
+```
+
+## Usage
+
+```python
+from langchain_crustapi import CrustAPISearch
+
+# Web search (default)
+tool = CrustAPISearch(max_results=5)
+tool.invoke({"query": "best crm software"})
+
+# Pick a Google surface
+maps = CrustAPISearch(search_type="maps", location="Austin, TX")
+maps.invoke({"query": "dentists"})
+
+news = CrustAPISearch(search_type="news")
+news.invoke({"query": "openai"})
+```
+
+Bind it to an agent like any other LangChain tool:
+
+```python
+from langchain.chat_models import init_chat_model
+from langchain_crustapi import CrustAPISearch
+
+llm = init_chat_model("gpt-4o-mini")
+agent_llm = llm.bind_tools([CrustAPISearch()])
+```
+
+## Parameters
+
+- `search_type`: the Google surface — `web` (default), `news`, `maps`, `places`, `shopping`, `images`, `videos`, `scholar`, `patents`.
+- `max_results`: number of results to return (default `10`).
+- `gl`: two-letter country code, e.g. `us`.
+- `hl`: two-letter language code, e.g. `en`.
+- `location`: city or region for local results, e.g. `Austin, TX`.
+
+The API key is read from the `CRUSTAPI_API_KEY` environment variable, or you can pass `crustapi_api_key` when constructing the tool.
+

langchain_crustapi-0.1.0/README.md

@@ -0,0 +1,47 @@
+# langchain-crustapi
+
+This package connects [CrustAPI](https://crustapi.com) to LangChain, giving your chains and agents clean, structured Google data from one endpoint: web search, Maps, News, Shopping, Images, Videos, Places, Scholar, and Patents. You only pay for successful results, and there's a free tier with no card.
+
+## Installation
+
+```bash
+pip install -U langchain-crustapi
+export CRUSTAPI_API_KEY="your-key"   # free at https://crustapi.com
+```
+
+## Usage
+
+```python
+from langchain_crustapi import CrustAPISearch
+
+# Web search (default)
+tool = CrustAPISearch(max_results=5)
+tool.invoke({"query": "best crm software"})
+
+# Pick a Google surface
+maps = CrustAPISearch(search_type="maps", location="Austin, TX")
+maps.invoke({"query": "dentists"})
+
+news = CrustAPISearch(search_type="news")
+news.invoke({"query": "openai"})
+```
+
+Bind it to an agent like any other LangChain tool:
+
+```python
+from langchain.chat_models import init_chat_model
+from langchain_crustapi import CrustAPISearch
+
+llm = init_chat_model("gpt-4o-mini")
+agent_llm = llm.bind_tools([CrustAPISearch()])
+```
+
+## Parameters
+
+- `search_type`: the Google surface — `web` (default), `news`, `maps`, `places`, `shopping`, `images`, `videos`, `scholar`, `patents`.
+- `max_results`: number of results to return (default `10`).
+- `gl`: two-letter country code, e.g. `us`.
+- `hl`: two-letter language code, e.g. `en`.
+- `location`: city or region for local results, e.g. `Austin, TX`.
+
+The API key is read from the `CRUSTAPI_API_KEY` environment variable, or you can pass `crustapi_api_key` when constructing the tool.

langchain_crustapi-0.1.0/langchain_crustapi/__init__.py

@@ -0,0 +1,17 @@
+from importlib import metadata
+from typing import List
+
+from langchain_crustapi.crustapi_search import CrustAPISearch
+from langchain_crustapi._utilities import CrustAPISearchAPIWrapper
+
+try:
+    __version__: str = metadata.version(__package__)
+except metadata.PackageNotFoundError:
+    __version__ = ""
+del metadata
+
+__all__: List[str] = [
+    "CrustAPISearch",
+    "CrustAPISearchAPIWrapper",
+    "__version__",
+]

langchain_crustapi-0.1.0/langchain_crustapi/_utilities.py

@@ -0,0 +1,109 @@
+"""Utility wrapper for the CrustAPI Google search endpoint."""
+
+from typing import Any, Dict, Optional
+
+import aiohttp
+import requests
+from langchain_core.utils import get_from_dict_or_env
+from pydantic import BaseModel, ConfigDict, SecretStr, model_validator
+
+CRUSTAPI_URL = "https://crustapi.com/v1/search"
+
+# Google surfaces CrustAPI exposes through the single search endpoint.
+SEARCH_TYPES = (
+    "web",
+    "news",
+    "maps",
+    "places",
+    "shopping",
+    "images",
+    "videos",
+    "scholar",
+    "patents",
+)
+
+
+class CrustAPISearchAPIWrapper(BaseModel):
+    """Wrapper around the CrustAPI search endpoint.
+
+    Reads the API key from the ``crustapi_api_key`` argument or the
+    ``CRUSTAPI_API_KEY`` environment variable. Get a free key at
+    https://crustapi.com (3,000 credits per month, no card).
+    """
+
+    crustapi_api_key: SecretStr
+    api_base_url: Optional[str] = None
+
+    model_config = ConfigDict(extra="forbid")
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_environment(cls, values: Dict) -> Any:
+        """Validate that the API key exists in the arguments or environment."""
+        values["crustapi_api_key"] = get_from_dict_or_env(
+            values, "crustapi_api_key", "CRUSTAPI_API_KEY"
+        )
+        return values
+
+    def _build_params(
+        self,
+        query: str,
+        search_type: str,
+        num: int,
+        gl: Optional[str],
+        hl: Optional[str],
+        location: Optional[str],
+    ) -> Dict[str, Any]:
+        if search_type not in SEARCH_TYPES:
+            raise ValueError(
+                f"Invalid search_type: {search_type}. "
+                f"Must be one of: {', '.join(SEARCH_TYPES)}"
+            )
+        params: Dict[str, Any] = {"type": search_type, "q": query, "num": num}
+        if gl:
+            params["gl"] = gl
+        if hl:
+            params["hl"] = hl
+        if location:
+            params["location"] = location
+        return params
+
+    def raw_results(
+        self,
+        query: str,
+        search_type: str = "web",
+        num: int = 10,
+        gl: Optional[str] = None,
+        hl: Optional[str] = None,
+        location: Optional[str] = None,
+    ) -> Dict:
+        """Run a search and return the raw JSON response."""
+        params = self._build_params(query, search_type, num, gl, hl, location)
+        headers = {"x-api-key": self.crustapi_api_key.get_secret_value()}
+        base_url = self.api_base_url or CRUSTAPI_URL
+        response = requests.get(base_url, params=params, headers=headers, timeout=30)
+        response.raise_for_status()
+        return response.json()
+
+    async def raw_results_async(
+        self,
+        query: str,
+        search_type: str = "web",
+        num: int = 10,
+        gl: Optional[str] = None,
+        hl: Optional[str] = None,
+        location: Optional[str] = None,
+    ) -> Dict:
+        """Run a search asynchronously and return the raw JSON response."""
+        params = self._build_params(query, search_type, num, gl, hl, location)
+        headers = {"x-api-key": self.crustapi_api_key.get_secret_value()}
+        base_url = self.api_base_url or CRUSTAPI_URL
+        async with aiohttp.ClientSession() as session:
+            async with session.get(
+                base_url,
+                params=params,
+                headers=headers,
+                timeout=aiohttp.ClientTimeout(total=30),
+            ) as response:
+                response.raise_for_status()
+                return await response.json()

langchain_crustapi-0.1.0/langchain_crustapi/crustapi_search.py

@@ -0,0 +1,126 @@
+"""CrustAPI Google search tool for LangChain."""
+
+from typing import Any, Dict, Literal, Optional, Type
+
+from langchain_core.callbacks import (
+    AsyncCallbackManagerForToolRun,
+    CallbackManagerForToolRun,
+)
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from langchain_crustapi._utilities import CrustAPISearchAPIWrapper
+
+
+class CrustAPISearchInput(BaseModel):
+    """Input for the CrustAPI search tool."""
+
+    query: str = Field(description="Search query to look up on Google")
+
+
+class CrustAPISearch(BaseTool):  # type: ignore[override]
+    """Search Google through CrustAPI and get clean, structured JSON.
+
+    One tool covers multiple Google surfaces via ``search_type``: ``web``
+    (default), ``news``, ``maps``, ``places``, ``shopping``, ``images``,
+    ``videos``, ``scholar``, and ``patents``. You only pay for successful
+    results, and there is a free tier with no card.
+
+    Setup:
+        Install ``langchain-crustapi`` and set the ``CRUSTAPI_API_KEY``
+        environment variable with a key from https://crustapi.com.
+
+        .. code-block:: bash
+
+            pip install langchain-crustapi
+            export CRUSTAPI_API_KEY="your-key"
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_crustapi import CrustAPISearch
+
+            tool = CrustAPISearch(max_results=5)
+
+    Invoke:
+        .. code-block:: python
+
+            tool.invoke({"query": "best crm software"})
+    """
+
+    name: str = "crustapi_search"
+    description: str = (
+        "Search Google via CrustAPI and return clean, structured JSON. "
+        "Useful for current web results, local businesses (maps), news, "
+        "shopping, images, videos, scholar, and patents. Input is a search query."
+    )
+    args_schema: Type[BaseModel] = CrustAPISearchInput
+
+    search_type: Literal[
+        "web",
+        "news",
+        "maps",
+        "places",
+        "shopping",
+        "images",
+        "videos",
+        "scholar",
+        "patents",
+    ] = "web"
+    """Which Google surface to query."""
+
+    max_results: int = 10
+    """Maximum number of results to return."""
+
+    gl: Optional[str] = None
+    """Two-letter country code, e.g. ``us``."""
+
+    hl: Optional[str] = None
+    """Two-letter language code, e.g. ``en``."""
+
+    location: Optional[str] = None
+    """City or region for local results, e.g. ``Austin, TX``."""
+
+    api_wrapper: CrustAPISearchAPIWrapper = Field(default_factory=CrustAPISearchAPIWrapper)  # type: ignore[arg-type]
+
+    def __init__(self, **kwargs: Any) -> None:
+        # Let callers pass crustapi_api_key / api_base_url straight through to the wrapper.
+        if "api_wrapper" not in kwargs:
+            wrapper_kwargs = {}
+            if "crustapi_api_key" in kwargs:
+                wrapper_kwargs["crustapi_api_key"] = kwargs.pop("crustapi_api_key")
+            if "api_base_url" in kwargs:
+                wrapper_kwargs["api_base_url"] = kwargs.pop("api_base_url")
+            if wrapper_kwargs:
+                kwargs["api_wrapper"] = CrustAPISearchAPIWrapper(**wrapper_kwargs)
+        super().__init__(**kwargs)
+
+    def _run(
+        self,
+        query: str,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> Dict[str, Any]:
+        """Run the search."""
+        return self.api_wrapper.raw_results(
+            query=query,
+            search_type=self.search_type,
+            num=self.max_results,
+            gl=self.gl,
+            hl=self.hl,
+            location=self.location,
+        )
+
+    async def _arun(
+        self,
+        query: str,
+        run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
+    ) -> Dict[str, Any]:
+        """Run the search asynchronously."""
+        return await self.api_wrapper.raw_results_async(
+            query=query,
+            search_type=self.search_type,
+            num=self.max_results,
+            gl=self.gl,
+            hl=self.hl,
+            location=self.location,
+        )

langchain_crustapi-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "langchain-crustapi"
+version = "0.1.0"
+description = "An integration package connecting CrustAPI (Google search data) and LangChain"
+authors = []
+readme = "README.md"
+repository = "https://github.com/crustapi/langchain-crustapi"
+license = "MIT"
+keywords = ["langchain", "crustapi", "google", "search", "serp", "maps", "tools"]
+include = ["langchain_crustapi/py.typed"]
+
+[tool.poetry.dependencies]
+python = ">=3.9,<4.0"
+langchain-core = ">=0.3,<2.0"
+aiohttp = "^3.9"
+requests = "^2.32"
+
+[tool.poetry.group.test]
+optional = true
+
+[tool.poetry.group.test.dependencies]
+pytest = "^8.0"
+pytest-asyncio = "^0.23"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"