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.
