Metadata-Version: 2.4
Name: serpdive
Version: 0.1.0
Summary: Official Python SDK for SERPdive, the AI Search API: answer-ready web content for LLMs and agents
Project-URL: Homepage, https://serpdive.com
Project-URL: Documentation, https://serpdive.com/docs
Project-URL: Repository, https://github.com/serpdive/serpdive-python
Author: SERPdive
License: MIT
License-File: LICENSE
Keywords: agents,ai,api,llm,rag,search,serpdive,web-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.27
Description-Content-Type: text/markdown

# SERPdive Python SDK

The official Python client for [SERPdive](https://serpdive.com), the AI Search API: ask a question, get answer-ready web content that is extracted, cleaned, and sized for an LLM. On a [public, replayable 1,000-question benchmark](https://github.com/edendalexis/serpdive-benchmark), SERPdive runs at the same speed as Tavily, feeds your LLM 20.2% fewer tokens, and wins 60.7% of decided quality duels.

## Install

```bash
pip install serpdive
```

## Quickstart

```python
from serpdive import SerpDive

client = SerpDive(api_key="sd_live_...")  # or set SERPDIVE_API_KEY
response = client.search("who won the 2026 champions league final", answer=True)

print(response.answer)
for result in response.results:
    print(result.url, result.content[:100])
```

Get your API key at [serpdive.com/dashboard/keys](https://serpdive.com/dashboard/keys).

## Usage

### Choosing a model

```python
# mako (default): answers in a few seconds
client.search("best rust web frameworks")

# moby: reads whole pages, for deep research
client.search("timeline of the OpenAI board dispute", model="moby", answer=True)
```

### Options

```python
client.search(
    "your question",
    model="moby",        # "mako" (fast, default) or "moby" (whole pages)
    answer=True,         # also return a written answer built from the sources
    max_results=5,       # hard cap on delivered results, 1 to 10
)
```

Localization is automatic: the language of the query picks where we search. There is no country parameter to configure.

### Async

```python
from serpdive import AsyncSerpDive

async with AsyncSerpDive() as client:
    response = await client.search("latest developments in solid state batteries")
```

### Errors

Every API error is a typed exception with a stable `code`, the human `message`, and the HTTP `status_code`:

```python
from serpdive import SerpDive, RateLimitError, QuotaExceededError, SerpDiveError

try:
    response = client.search("your question")
except RateLimitError:
    ...  # slow down, then retry
except QuotaExceededError:
    ...  # monthly credits exhausted
except SerpDiveError as e:
    print(e.code, e.message)
```

Transient failures (HTTP 502/503) are retried automatically; failed searches are never billed. Tune with `SerpDive(max_retries=..., timeout=...)`.

## Response shape

`search()` returns a `SearchResponse`:

| Field | Type | Notes |
|---|---|---|
| `query` | `str` | your query, echoed |
| `results` | `list[SearchResult]` | each has `url`, `content`, optional `title` and ISO `date` |
| `answer` | `str \| None` | only when `answer=True` was requested |
| `extra_info` | `dict \| None` | direct-answer block (weather, rates, scores...) when the query has one |
| `model` | `str` | which model answered |
| `response_time_ms` | `int` | end-to-end latency |
| `raw` | `dict` | the verbatim API payload |

## Docs

Full documentation: [serpdive.com/docs](https://serpdive.com/docs). The API is also self-describing for agents: [llms.txt](https://serpdive.com/llms.txt), [openapi.json](https://serpdive.com/openapi.json).

## License

MIT
