cerul 0.0.2

Official Python SDK for the Cerul video search API

cerul

The video search layer for AI agents — Python SDK.

Teach your AI agents to see. Search what was said, shown, or presented in any video.

Docs · Website · Main Repo

Install

pip install cerul

Quick Start

from cerul import Cerul

client = Cerul()  # reads CERUL_API_KEY from env

result = client.search(
    query="Sam Altman on AGI timeline",
    max_results=5,
    include_answer=True,
    filters={"speaker": "Sam Altman"},
)

for r in result.results:
    print(f"{r.title} ({r.score}) — {r.url}")

Features

• Sync + Async — Cerul for sync, AsyncCerul for async
• Minimal dependencies — httpx only
• Dataclass responses — typed results, no pydantic required
• Timeout — configurable, default 30s
• Optional retry — 429 reads Retry-After, 5xx exponential backoff
• API key resolution — parameter > CERUL_API_KEY env var

Async

from cerul import AsyncCerul

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

Configuration

client = Cerul(
    api_key="cerul_sk_...",     # or reads CERUL_API_KEY
    timeout=30.0,               # seconds, default 30
    retry=True,                 # retry 429/5xx, default False
)

Usage Monitoring

usage = client.usage()
print(f"{usage.credits_used} / {usage.credits_remaining} credits")

Errors

from cerul import Cerul, CerulError

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

Ecosystem

Package	Description
cerul	Main repo — API, docs, skills, remote MCP
cerul	TypeScript SDK
cerul-cli	CLI tool (Rust)

License

MIT