Metadata-Version: 2.4
Name: cerul
Version: 0.0.5
Summary: The video search layer for AI agents — Python SDK
Project-URL: Homepage, https://cerul.ai
Project-URL: Documentation, https://cerul.ai/docs
Project-URL: Repository, https://github.com/cerul-ai/cerul-python
Project-URL: Issues, https://github.com/cerul-ai/cerul-python/issues
Author: Cerul
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agent,api,cerul,mcp,video,video-search
Classifier: Development Status :: 3 - Alpha
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
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Description-Content-Type: text/markdown

cerul
  
The video search layer for AI agents.

    Python

    Docs (https://cerul.ai/docs) ·
    Website (https://cerul.ai) ·
    GitHub (https://github.com/cerul-ai/cerul)

Search what was said, shown, or presented in any video — tech talks, podcasts, conference presentations, and earnings calls.

```bash
pip install cerul
```

```python
from cerul import Cerul

client = Cerul()  # reads CERUL_API_KEY

for r in client.search(query="Sam Altman on AGI timeline"):
    print(r.title, r.url)
```

Get a free API key at [cerul.ai/dashboard](https://cerul.ai/dashboard).

## Examples

```python
# Search with filters
result = client.search(
    query="Jensen Huang on AI infrastructure",
    max_results=5,
    ranking_mode="rerank",
    include_answer=True,
    filters={"speaker": "Jensen Huang", "published_after": "2024-01-01"},
)

# AI-generated answer
print(result.answer)

# Results print as JSON
print(result[0])

# Check credits
usage = client.usage()
print(f"{usage.credits_remaining} credits remaining")
```

## Async

```python
from cerul import AsyncCerul

async with AsyncCerul() as client:
    result = await client.search(query="attention mechanism explained")
```

## Configuration

```python
client = Cerul(
    api_key="cerul_sk_...",   # or CERUL_API_KEY env var
    timeout=30.0,             # default 30s
    retry=True,               # retry 429/5xx/network errors
)
```

## Error handling

```python
from cerul import CerulError

try:
    client.search(query="test")
except CerulError as e:
    print(e.status_code, e.code, e.message)
```

## Links

- [TypeScript SDK](https://www.npmjs.com/package/cerul) — `npm install cerul`
- [CLI](https://github.com/cerul-ai/cerul-cli) — `curl -fsSL .../install.sh | bash`
- [Main repo](https://github.com/cerul-ai/cerul) — API, docs, skills, remote MCP

## License

[MIT](./LICENSE)
