Metadata-Version: 2.4
Name: caesar-search
Version: 0.1.2
Summary: Official Python SDK for the Caesar search API — web search with provenance, built for agents.
Project-URL: Homepage, https://github.com/caesar-data/caesar-search-python
Project-URL: Repository, https://github.com/caesar-data/caesar-search-python
Project-URL: Issues, https://github.com/caesar-data/caesar-search-python/issues
Project-URL: Changelog, https://github.com/caesar-data/caesar-search-python/releases
Author: Caesar
License-Expression: MIT
License-File: LICENSE
Keywords: agents,caesar,search,web-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Description-Content-Type: text/markdown

# caesar-search (Python)

Official Python SDK for the Caesar search API — web search with provenance, built for agents.

## Quickstart

```python
# pip install caesar-search    (or: uv add caesar-search)
from caesar_search import Caesar

client = Caesar()  # reads CAESAR_API_KEY; anonymous tier works without a key
results = client.search("rust async runtime comparison", max_results=5)
doc = client.read(results.results[0].doc_id, query="which runtime is fastest")
client.feedback("result_helpful", search_id=results.search_id, doc_id=doc.doc.doc_id)
```

## Clients

- `Caesar` — synchronous; `AsyncCaesar` — same surface with `async`/`await`. Both support context managers.
- Methods: `search()`, `read()` (doc_id **or** URL; `start_char=` continues truncated reads), `feedback()`.
- Responses are typed pydantic v2 models generated from the public OpenAPI spec; provenance fields (`doc_id`, `search_id`, `capture_id`, canonical/source URLs, crawl dates) are preserved verbatim.
- `client.with_raw_response.search(...)` returns the raw `httpx.Response`.
- Retries: 429/5xx with capped exponential backoff honoring `Retry-After` (`max_retries=` to tune, `0` to disable).
- Config: `api_key=` / `CAESAR_API_KEY`; `base_url=` / `CAESAR_BASE_URL`.

## Errors

`CaesarError` → `APIConnectionError` / `APITimeoutError` and `APIStatusError` (with `.status_code`, `.code`, `.message`, `.request_id`) → `AuthenticationError` (401/403), `RateLimitError` (429).

## License

[MIT](LICENSE)
