serphouse-ai-sdk 0.1.0__tar.gz

serphouse_ai_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: serphouse-ai-sdk
+Version: 0.1.0
+Summary: SERPHouse AI SDK — search API tools for LangChain and LlamaIndex
+Author-email: SERPHouse <support@serphouse.com>
+License: MIT
+Project-URL: Homepage, https://serphouse.com
+Project-URL: Source, https://github.com/SERPHouse/ai-sdk-python
+Project-URL: Documentation, https://serphouse.com/docs
+Keywords: serphouse,search,ai,langchain,llamaindex,seo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.3.0; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index>=0.12.0; extra == "llamaindex"
+Provides-Extra: all
+Requires-Dist: serphouse-ai-sdk[langchain,llamaindex]; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Requires-Dist: langchain-openai>=0.2; extra == "test"
+Requires-Dist: llama-index-llms-openai>=0.3; extra == "test"
+Requires-Dist: python-dotenv>=1.0; extra == "test"
+
+<div align="center">
+
+<img src="./assets/serphouse-logo.png" alt="SERPHouse logo" width="80" />
+
+# SERPHouse AI SDK
+
+**Python SDK for the SERPHouse search API — with first-class integrations for LangChain and LlamaIndex.**
+
+Drop live Google, Bing, and Yahoo search data into your AI agents. No boilerplate, no custom API clients — just import, configure, and let your agent search the web.
+
+<br />
+
+[![PyPI](https://img.shields.io/pypi/v/serphouse-ai-sdk?color=7B42BC&logo=pypi&logoColor=white)](https://pypi.org/project/serphouse-ai-sdk/)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
+[![LangChain](https://img.shields.io/badge/LangChain-Compatible-7B42BC)](https://langchain.com/)
+[![LlamaIndex](https://img.shields.io/badge/LlamaIndex-Compatible-7B42BC)](https://llamaindex.ai/)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Website](https://img.shields.io/badge/Website-serphouse.com-7B42BC)](https://serphouse.com)
+[![GitHub](https://img.shields.io/badge/GitHub-SERPHouse-181717?logo=github)](https://github.com/SERPHouse)
+
+</div>
+
+---
+
+## Table of Contents
+
+- [Why SERPHouse AI SDK](#why-serphouse-ai-sdk)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [LangChain](#langchain)
+  - [LlamaIndex](#llamaindex)
+- [API Key](#api-key)
+- [Tools Reference](#tools-reference)
+- [Advanced Usage](#advanced-usage)
+  - [Custom API key per tool](#custom-api-key-per-tool)
+  - [SERPHouseClient](#serphouseclient)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Why SERPHouse AI SDK
+
+| | |
+|---|---|
+| **Zero boilerplate** | Two lines to add web search, news, or video results to any LangChain or LlamaIndex agent |
+| **Framework-native** | Functions return standard `StructuredTool` / `FunctionTool` objects — no wrappers, no adapters |
+| **Live SERP data** | Every call hits the SERPHouse API in real time. No cached or stale results. |
+| **Production-ready** | Built on `requests` and `pydantic` with typed schemas, configurable timeouts, and clear error handling |
+
+---
+
+## Installation
+
+```bash
+pip install serphouse-ai-sdk
+```
+
+With framework extras:
+
+```bash
+pip install serphouse-ai-sdk[langchain]
+pip install serphouse-ai-sdk[llamaindex]
+pip install serphouse-ai-sdk[all]      # both frameworks
+```
+
+---
+
+## Quick Start
+
+Set the `SERPHOUSE_API_KEY` environment variable (or [pass it per tool](#custom-api-key-per-tool)).
+
+### LangChain
+
+```python
+from langchain.agents import create_agent
+from langchain_openai import ChatOpenAI
+from serphouse.langchain import search, news, short_video
+
+agent = create_agent(
+    model=ChatOpenAI(model="gpt-4"),
+    tools=[search(), news(), short_video()],
+)
+
+response = agent.invoke({
+    "messages": [{"role": "user", "content": "Latest AI news from OpenAI"}]
+})
+print(response["messages"][-1].content)
+```
+
+### LlamaIndex
+
+```python
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.openai import OpenAI
+from serphouse.llamaindex import search, news, short_video
+
+agent = FunctionAgent(
+    llm=OpenAI(model="gpt-4"),
+    tools=[search(), news(), short_video()],
+)
+
+response = agent.run("Latest AI news from OpenAI")
+print(response)
+```
+
+---
+
+## API Key
+
+Get your key at [serphouse.com](https://serphouse.com) and choose one of:
+
+| Method | Example |
+|--------|---------|
+| **Environment variable** (recommended) | `export SERPHOUSE_API_KEY=your_key_here` |
+| **Per-tool options dict** | `search({"api_key": "your_key_here"})` |
+| **SERPHouseClient** | `SERPHouseClient(api_key="your_key_here")` |
+
+---
+
+## Tools Reference
+
+| Tool | Framework | Endpoint | Description |
+|------|-----------|----------|-------------|
+| `search()` | LangChain, LlamaIndex | `/web-search-lite` | General web search |
+| `news()` | LangChain, LlamaIndex | `/google-news` | Google News search |
+| `short_video()` | LangChain, LlamaIndex | `/google-short-videos-api` | Google Short Videos (Shorts) |
+
+All tools accept the following parameters:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `q` | `str` | — | Search query (required) |
+| `domain` | `str` | `google.com` | Search domain |
+| `lang` | `str` | `en` | Search language code |
+| `loc` | `str` | `New York,New York,United States` | Location (`City,State,Country`) |
+| `device` | `str` | `desktop` | `desktop` or `mobile` |
+| `page` | `int` | — | Page number |
+| `date_range` | `str` | `y` | `h` (hour), `d` (24h), `w` (week), `m` (month), `y` (year), or `YYYY-MM-DD,YYYY-MM-DD` |
+| `gl` | `str` | `US` | Country code (ISO 3166-1 alpha-2, search only) |
+| `video_quality` | `str` | `high` | Video quality (short_video only) |
+
+---
+
+## Advanced Usage
+
+### Custom API key per tool
+
+```python
+from serphouse.langchain import search
+
+tool = search({"api_key": "your-key"})
+```
+
+### SERPHouseClient
+
+Use the raw client directly for custom integrations:
+
+```python
+from serphouse import SERPHouseClient
+
+client = SERPHouseClient(api_key="your-key")
+result = client.post("/web-search-lite", {"q": "python sdk"})
+print(result)
+```
+
+---
+
+## Development
+
+```bash
+# Clone and enter the repo
+git clone https://github.com/serphouse/ai-sdk.git
+cd ai-sdk
+
+# Create a virtual environment
+python3 -m venv venv
+source venv/bin/activate
+
+# Install in editable mode with all dev dependencies
+pip install -e ".[test]"
+
+# Run tests
+pytest tests -v
+
+# Run only unit tests (skip OpenAI integration tests)
+pytest tests -v -k "not Integration"
+
+# Run integration tests (requires OPENAI_API_KEY)
+OPENAI_API_KEY=sk-... pytest tests -v -k "Integration"
+```
+
+---
+
+## Contributing
+
+Contributions are welcome. Please keep changes focused and match existing code style.
+
+```bash
+git checkout -b feature/your-feature
+pip install -e ".[test]"
+# make changes
+pytest tests -v
+git commit -m "Add your feature"
+git push origin feature/your-feature
+```
+
+Then open a Pull Request. Update this README if you change setup or configuration.
+
+---
+
+## License
+
+[MIT License](LICENSE) — Copyright SERPHouse.

serphouse_ai_sdk-0.1.0/README.md

@@ -0,0 +1,215 @@
+<div align="center">
+
+<img src="./assets/serphouse-logo.png" alt="SERPHouse logo" width="80" />
+
+# SERPHouse AI SDK
+
+**Python SDK for the SERPHouse search API — with first-class integrations for LangChain and LlamaIndex.**
+
+Drop live Google, Bing, and Yahoo search data into your AI agents. No boilerplate, no custom API clients — just import, configure, and let your agent search the web.
+
+<br />
+
+[![PyPI](https://img.shields.io/pypi/v/serphouse-ai-sdk?color=7B42BC&logo=pypi&logoColor=white)](https://pypi.org/project/serphouse-ai-sdk/)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
+[![LangChain](https://img.shields.io/badge/LangChain-Compatible-7B42BC)](https://langchain.com/)
+[![LlamaIndex](https://img.shields.io/badge/LlamaIndex-Compatible-7B42BC)](https://llamaindex.ai/)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Website](https://img.shields.io/badge/Website-serphouse.com-7B42BC)](https://serphouse.com)
+[![GitHub](https://img.shields.io/badge/GitHub-SERPHouse-181717?logo=github)](https://github.com/SERPHouse)
+
+</div>
+
+---
+
+## Table of Contents
+
+- [Why SERPHouse AI SDK](#why-serphouse-ai-sdk)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [LangChain](#langchain)
+  - [LlamaIndex](#llamaindex)
+- [API Key](#api-key)
+- [Tools Reference](#tools-reference)
+- [Advanced Usage](#advanced-usage)
+  - [Custom API key per tool](#custom-api-key-per-tool)
+  - [SERPHouseClient](#serphouseclient)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Why SERPHouse AI SDK
+
+| | |
+|---|---|
+| **Zero boilerplate** | Two lines to add web search, news, or video results to any LangChain or LlamaIndex agent |
+| **Framework-native** | Functions return standard `StructuredTool` / `FunctionTool` objects — no wrappers, no adapters |
+| **Live SERP data** | Every call hits the SERPHouse API in real time. No cached or stale results. |
+| **Production-ready** | Built on `requests` and `pydantic` with typed schemas, configurable timeouts, and clear error handling |
+
+---
+
+## Installation
+
+```bash
+pip install serphouse-ai-sdk
+```
+
+With framework extras:
+
+```bash
+pip install serphouse-ai-sdk[langchain]
+pip install serphouse-ai-sdk[llamaindex]
+pip install serphouse-ai-sdk[all]      # both frameworks
+```
+
+---
+
+## Quick Start
+
+Set the `SERPHOUSE_API_KEY` environment variable (or [pass it per tool](#custom-api-key-per-tool)).
+
+### LangChain
+
+```python
+from langchain.agents import create_agent
+from langchain_openai import ChatOpenAI
+from serphouse.langchain import search, news, short_video
+
+agent = create_agent(
+    model=ChatOpenAI(model="gpt-4"),
+    tools=[search(), news(), short_video()],
+)
+
+response = agent.invoke({
+    "messages": [{"role": "user", "content": "Latest AI news from OpenAI"}]
+})
+print(response["messages"][-1].content)
+```
+
+### LlamaIndex
+
+```python
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.openai import OpenAI
+from serphouse.llamaindex import search, news, short_video
+
+agent = FunctionAgent(
+    llm=OpenAI(model="gpt-4"),
+    tools=[search(), news(), short_video()],
+)
+
+response = agent.run("Latest AI news from OpenAI")
+print(response)
+```
+
+---
+
+## API Key
+
+Get your key at [serphouse.com](https://serphouse.com) and choose one of:
+
+| Method | Example |
+|--------|---------|
+| **Environment variable** (recommended) | `export SERPHOUSE_API_KEY=your_key_here` |
+| **Per-tool options dict** | `search({"api_key": "your_key_here"})` |
+| **SERPHouseClient** | `SERPHouseClient(api_key="your_key_here")` |
+
+---
+
+## Tools Reference
+
+| Tool | Framework | Endpoint | Description |
+|------|-----------|----------|-------------|
+| `search()` | LangChain, LlamaIndex | `/web-search-lite` | General web search |
+| `news()` | LangChain, LlamaIndex | `/google-news` | Google News search |
+| `short_video()` | LangChain, LlamaIndex | `/google-short-videos-api` | Google Short Videos (Shorts) |
+
+All tools accept the following parameters:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `q` | `str` | — | Search query (required) |
+| `domain` | `str` | `google.com` | Search domain |
+| `lang` | `str` | `en` | Search language code |
+| `loc` | `str` | `New York,New York,United States` | Location (`City,State,Country`) |
+| `device` | `str` | `desktop` | `desktop` or `mobile` |
+| `page` | `int` | — | Page number |
+| `date_range` | `str` | `y` | `h` (hour), `d` (24h), `w` (week), `m` (month), `y` (year), or `YYYY-MM-DD,YYYY-MM-DD` |
+| `gl` | `str` | `US` | Country code (ISO 3166-1 alpha-2, search only) |
+| `video_quality` | `str` | `high` | Video quality (short_video only) |
+
+---
+
+## Advanced Usage
+
+### Custom API key per tool
+
+```python
+from serphouse.langchain import search
+
+tool = search({"api_key": "your-key"})
+```
+
+### SERPHouseClient
+
+Use the raw client directly for custom integrations:
+
+```python
+from serphouse import SERPHouseClient
+
+client = SERPHouseClient(api_key="your-key")
+result = client.post("/web-search-lite", {"q": "python sdk"})
+print(result)
+```
+
+---
+
+## Development
+
+```bash
+# Clone and enter the repo
+git clone https://github.com/serphouse/ai-sdk.git
+cd ai-sdk
+
+# Create a virtual environment
+python3 -m venv venv
+source venv/bin/activate
+
+# Install in editable mode with all dev dependencies
+pip install -e ".[test]"
+
+# Run tests
+pytest tests -v
+
+# Run only unit tests (skip OpenAI integration tests)
+pytest tests -v -k "not Integration"
+
+# Run integration tests (requires OPENAI_API_KEY)
+OPENAI_API_KEY=sk-... pytest tests -v -k "Integration"
+```
+
+---
+
+## Contributing
+
+Contributions are welcome. Please keep changes focused and match existing code style.
+
+```bash
+git checkout -b feature/your-feature
+pip install -e ".[test]"
+# make changes
+pytest tests -v
+git commit -m "Add your feature"
+git push origin feature/your-feature
+```
+
+Then open a Pull Request. Update this README if you change setup or configuration.
+
+---
+
+## License
+
+[MIT License](LICENSE) — Copyright SERPHouse.

serphouse_ai_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "serphouse-ai-sdk"
+version = "0.1.0"
+description = "SERPHouse AI SDK — search API tools for LangChain and LlamaIndex"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "SERPHouse", email = "support@serphouse.com" },
+]
+keywords = ["serphouse", "search", "ai", "langchain", "llamaindex", "seo"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+  "requests>=2.28.0",
+  "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+langchain = [
+  "langchain>=0.3.0",
+]
+llamaindex = [
+  "llama-index>=0.12.0",
+]
+all = [
+  "serphouse-ai-sdk[langchain,llamaindex]",
+]
+test = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.24",
+  "langchain-openai>=0.2",
+  "llama-index-llms-openai>=0.3",
+  "python-dotenv>=1.0",
+]
+
+[project.urls]
+Homepage = "https://serphouse.com"
+Source = "https://github.com/SERPHouse/ai-sdk-python"
+Documentation = "https://serphouse.com/docs"
+
+[tool.setuptools.packages.find]
+include = ["serphouse*"]

serphouse_ai_sdk-0.1.0/serphouse/__init__.py

@@ -0,0 +1 @@
+from .client import SERPHouseClient, ApiError

serphouse_ai_sdk-0.1.0/serphouse/client.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import requests
+
+BASE_URL = "https://api.serphouse.com"
+DEFAULT_API_KEY_ENV = "SERPHOUSE_API_KEY"
+
+
+class ApiError(Exception):
+    def __init__(self, status: int, body: Any):
+        self.status = status
+        self.body = body
+
+        if isinstance(body, str):
+            message = body
+        elif isinstance(body, dict):
+            message = str(
+                body.get("message")
+                or body.get("error")
+                or f"HTTP {status}"
+            )
+        else:
+            message = f"HTTP {status}"
+
+        super().__init__(message)
+
+
+class SERPHouseClient:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = BASE_URL,
+        timeout: int = 30,
+    ):
+        self.api_key = api_key or os.getenv(DEFAULT_API_KEY_ENV)
+
+        if not self.api_key:
+            raise ValueError(
+                f"Missing API key. Set {DEFAULT_API_KEY_ENV} or pass api_key."
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            }
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None = None,
+    ) -> Any:
+        url = (
+            path
+            if path.startswith(("http://", "https://"))
+            else f"{self.base_url}{path if path.startswith('/') else '/' + path}"
+        )
+
+        response = self.session.request(
+            method=method,
+            url=url,
+            json=body,
+            timeout=self.timeout,
+        )
+
+        content_type = response.headers.get("Content-Type", "")
+
+        if "application/json" in content_type:
+            data = response.json()
+        else:
+            data = response.text
+
+        if not response.ok:
+            raise ApiError(response.status_code, data)
+
+        return data
+
+    def get(self, path: str) -> Any:
+        return self._request("GET", path)
+
+    def post(
+        self,
+        path: str,
+        data: dict[str, Any],
+    ) -> Any:
+        return self._request(
+            "POST",
+            path,
+            {
+                "data": data,
+            },
+        )

serphouse_ai_sdk-0.1.0/serphouse/langchain.py

@@ -0,0 +1,66 @@
+from langchain_core.tools import StructuredTool
+
+from .client import SERPHouseClient
+from .schema import NewsSchema, SearchSchema, ShortVideoSchema
+
+ToolOptions = dict[str, str] | None
+
+
+def search(options: ToolOptions = None) -> StructuredTool:
+    """
+    Search the web using SERPHouse.
+    """
+    client = SERPHouseClient(api_key=options.get("api_key") if options else None)
+
+    def execute(**kwargs):
+        return client.post(
+            "/web-search-lite",
+            {k: v for k, v in kwargs.items() if v is not None},
+        )
+
+    return StructuredTool.from_function(
+        func=execute,
+        name="search",
+        description="Search the web for information.",
+        args_schema=SearchSchema,
+    )
+
+
+def news(options: ToolOptions = None) -> StructuredTool:
+    """
+    Search news using SERPHouse.
+    """
+    client = SERPHouseClient(api_key=options.get("api_key") if options else None)
+
+    def execute(**kwargs):
+        return client.post(
+            "/google-news",
+            {k: v for k, v in kwargs.items() if v is not None},
+        )
+
+    return StructuredTool.from_function(
+        func=execute,
+        name="news",
+        description="Search for news on the web.",
+        args_schema=NewsSchema,
+    )
+
+
+def short_video(options: ToolOptions = None) -> StructuredTool:
+    """
+    Search short videos using SERPHouse.
+    """
+    client = SERPHouseClient(api_key=options.get("api_key") if options else None)
+
+    def execute(**kwargs):
+        return client.post(
+            "/google-short-videos-api",
+            {k: v for k, v in kwargs.items() if v is not None},
+        )
+
+    return StructuredTool.from_function(
+        func=execute,
+        name="short_video",
+        description="Search for short videos on the web.",
+        args_schema=ShortVideoSchema,
+    )