caesar-search 0.1.0__py3-none-any.whl

caesar_search/__init__.py

@@ -0,0 +1,31 @@
+"""caesar-search: official Python SDK for the Caesar search API."""
+
+from . import models
+from ._client import DEFAULT_BASE_URL, AsyncCaesar, Caesar
+from ._exceptions import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    CaesarError,
+    RateLimitError,
+)
+from ._version import __version__
+from .models import DocumentResponse, FeedbackResponse, SearchResponse
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "APIConnectionError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AsyncCaesar",
+    "AuthenticationError",
+    "Caesar",
+    "CaesarError",
+    "DocumentResponse",
+    "FeedbackResponse",
+    "RateLimitError",
+    "SearchResponse",
+    "__version__",
+    "models",
+]

caesar_search/_client.py

@@ -0,0 +1,482 @@
+from __future__ import annotations
+
+import os
+import re
+import time
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from ._exceptions import APIConnectionError, APITimeoutError, status_error_from_response
+from ._version import __version__
+from .models import DocumentResponse, FeedbackResponse, SearchResponse
+
+DEFAULT_BASE_URL = "https://search-api-staging-779189860552.europe-west1.run.app"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+_BASE_DELAY = 0.5
+_MAX_DELAY = 8.0
+_RETRYABLE_STATUSES = frozenset({429, 500, 502, 503, 504})
+_UUID_PATTERN = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE)
+
+
+def _resolve_key(api_key: str | None) -> str | None:
+    return api_key or os.environ.get("CAESAR_API_KEY") or None
+
+
+def _resolve_base_url(base_url: str | None) -> str:
+    return (base_url or os.environ.get("CAESAR_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+
+def _headers(api_key: str | None) -> dict[str, str]:
+    headers = {
+        "Accept": "application/json",
+        "X-Caesar-Client": f"python-sdk/{__version__}",
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+def _retry_delay(attempt: int, retry_after: str | None) -> float:
+    if retry_after:
+        try:
+            seconds = float(retry_after)
+            if seconds >= 0:
+                return float(min(seconds, _MAX_DELAY))
+        except ValueError:
+            pass
+    return float(min(_BASE_DELAY * (2**attempt), _MAX_DELAY))
+
+
+def _search_body(
+    query: str,
+    *,
+    mode: str | None,
+    max_results: int | None,
+    objective: str | None,
+    session_id: str | None,
+    verbosity: str | None,
+    max_chars_total: int | None,
+    extra_body: dict[str, Any] | None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {"query": query, "client_model": "python-sdk"}
+    if mode is not None:
+        body["mode"] = mode
+    if max_results is not None:
+        body["max_results"] = max_results
+    if objective is not None:
+        body["objective"] = objective
+    if session_id is not None:
+        body["session_id"] = session_id
+    response_shape: dict[str, Any] = {}
+    if verbosity is not None:
+        response_shape["verbosity"] = verbosity
+    if max_chars_total is not None:
+        response_shape["budget"] = {"max_chars_total": max_chars_total}
+    if response_shape:
+        body["response"] = response_shape
+    if extra_body:
+        body.update(extra_body)
+    return body
+
+
+def _read_body(
+    target: str | None,
+    *,
+    doc_id: str | None,
+    url: str | None,
+    query: str | None,
+    max_chars: int | None,
+    start_char: int | None,
+    include: list[str] | None,
+    extra_body: dict[str, Any] | None,
+) -> dict[str, Any]:
+    if target is not None:
+        if _UUID_PATTERN.match(target):
+            doc_id = doc_id or target
+        else:
+            url = url or target
+    if not doc_id and not url:
+        raise ValueError("provide a doc_id or a url")
+
+    content: dict[str, Any] = {
+        "selection": "query_relevant" if query else "full_document",
+        "format": "markdown",
+    }
+    if max_chars is not None:
+        content["max_chars"] = max_chars
+    if start_char:
+        # Continuation reads address the raw document text so offsets stay
+        # contiguous between calls.
+        content["selection"] = "full_document"
+        content["range"] = {"start_char": start_char}
+
+    body: dict[str, Any] = {
+        "include": include if include is not None else ["metadata", "content"],
+        "content": content,
+    }
+    if doc_id:
+        body["doc_id"] = doc_id
+    elif url:
+        body["canonical_url"] = url
+    if query:
+        body["query"] = query
+    if extra_body:
+        body.update(extra_body)
+    return body
+
+
+def _feedback_body(
+    event_type: str,
+    *,
+    search_id: str | None,
+    doc_id: str | None,
+    passage_id: str | None,
+    query: str | None,
+    rank: int | None,
+    notes: str | None,
+    extra_body: dict[str, Any] | None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "event_type": event_type,
+        "agent_context": {"client_model": "python-sdk"},
+    }
+    if search_id is not None:
+        body["search_id"] = search_id
+    if doc_id is not None:
+        body["doc_id"] = doc_id
+    if passage_id is not None:
+        body["passage_id"] = passage_id
+    if query is not None:
+        body["query"] = query
+    if rank is not None:
+        body["rank"] = rank
+    if notes is not None:
+        body["notes"] = notes
+    if extra_body:
+        body.update(extra_body)
+    return body
+
+
+class Caesar:
+    """Synchronous client for the Caesar search API.
+
+    Reads ``CAESAR_API_KEY`` and ``CAESAR_BASE_URL`` from the environment when
+    not passed explicitly. Anonymous access works at a lower rate limit when
+    the deployment allows it.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._api_key = _resolve_key(api_key)
+        self._base_url = _resolve_base_url(base_url)
+        self._max_retries = max_retries
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self.with_raw_response = _RawResponses(self)
+
+    # -- public surface -------------------------------------------------
+
+    def search(
+        self,
+        query: str,
+        *,
+        mode: str | None = None,
+        max_results: int | None = None,
+        objective: str | None = None,
+        session_id: str | None = None,
+        verbosity: str | None = None,
+        max_chars_total: int | None = None,
+        extra_body: dict[str, Any] | None = None,
+    ) -> SearchResponse:
+        """Search the web. Returns ranked results with provenance handles."""
+        body = _search_body(
+            query,
+            mode=mode,
+            max_results=max_results,
+            objective=objective,
+            session_id=session_id,
+            verbosity=verbosity,
+            max_chars_total=max_chars_total,
+            extra_body=extra_body,
+        )
+        return SearchResponse.model_validate(self._request("/v1/search", body).json())
+
+    def read(
+        self,
+        target: str | None = None,
+        *,
+        doc_id: str | None = None,
+        url: str | None = None,
+        query: str | None = None,
+        max_chars: int | None = None,
+        start_char: int | None = None,
+        include: list[str] | None = None,
+        extra_body: dict[str, Any] | None = None,
+    ) -> DocumentResponse:
+        """Read a document as clean markdown by doc_id or URL.
+
+        Truncated reads report ``content.start_char``/``char_count``; continue
+        with ``start_char=start + count`` instead of retrying bigger.
+        """
+        body = _read_body(
+            target,
+            doc_id=doc_id,
+            url=url,
+            query=query,
+            max_chars=max_chars,
+            start_char=start_char,
+            include=include,
+            extra_body=extra_body,
+        )
+        return DocumentResponse.model_validate(self._request("/v1/document", body).json())
+
+    def feedback(
+        self,
+        event_type: str,
+        *,
+        search_id: str | None = None,
+        doc_id: str | None = None,
+        passage_id: str | None = None,
+        query: str | None = None,
+        rank: int | None = None,
+        notes: str | None = None,
+        extra_body: dict[str, Any] | None = None,
+    ) -> FeedbackResponse:
+        """Send a feedback event about a search result or document."""
+        body = _feedback_body(
+            event_type,
+            search_id=search_id,
+            doc_id=doc_id,
+            passage_id=passage_id,
+            query=query,
+            rank=rank,
+            notes=notes,
+            extra_body=extra_body,
+        )
+        return FeedbackResponse.model_validate(self._request("/v1/feedback", body).json())
+
+    # -- plumbing ---------------------------------------------------------
+
+    def _request(self, path: str, body: dict[str, Any]) -> httpx.Response:
+        last_response: httpx.Response | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.post(
+                    f"{self._base_url}{path}",
+                    json=body,
+                    headers=_headers(self._api_key),
+                )
+            except httpx.TimeoutException as error:
+                raise APITimeoutError(f"request timed out: {error}") from error
+            except httpx.HTTPError as error:
+                raise APIConnectionError(f"request failed: {error}") from error
+
+            if response.status_code in _RETRYABLE_STATUSES and attempt < self._max_retries:
+                time.sleep(_retry_delay(attempt, response.headers.get("Retry-After")))
+                last_response = response
+                continue
+            if response.is_success:
+                return response
+            raise status_error_from_response(response)
+
+        raise status_error_from_response(last_response)  # type: ignore[arg-type]  # pragma: no cover
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Caesar:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class _RawResponses:
+    """Escape hatch: the same methods, returning the raw httpx.Response."""
+
+    def __init__(self, client: Caesar) -> None:
+        self._client = client
+
+    def search(self, query: str, **kwargs: Any) -> httpx.Response:
+        extra_body = kwargs.pop("extra_body", None)
+        body = _search_body(
+            query,
+            mode=kwargs.pop("mode", None),
+            max_results=kwargs.pop("max_results", None),
+            objective=kwargs.pop("objective", None),
+            session_id=kwargs.pop("session_id", None),
+            verbosity=kwargs.pop("verbosity", None),
+            max_chars_total=kwargs.pop("max_chars_total", None),
+            extra_body=extra_body,
+        )
+        return self._client._request("/v1/search", body)
+
+    def read(self, target: str | None = None, **kwargs: Any) -> httpx.Response:
+        body = _read_body(
+            target,
+            doc_id=kwargs.pop("doc_id", None),
+            url=kwargs.pop("url", None),
+            query=kwargs.pop("query", None),
+            max_chars=kwargs.pop("max_chars", None),
+            start_char=kwargs.pop("start_char", None),
+            include=kwargs.pop("include", None),
+            extra_body=kwargs.pop("extra_body", None),
+        )
+        return self._client._request("/v1/document", body)
+
+    def feedback(self, event_type: str, **kwargs: Any) -> httpx.Response:
+        body = _feedback_body(
+            event_type,
+            search_id=kwargs.pop("search_id", None),
+            doc_id=kwargs.pop("doc_id", None),
+            passage_id=kwargs.pop("passage_id", None),
+            query=kwargs.pop("query", None),
+            rank=kwargs.pop("rank", None),
+            notes=kwargs.pop("notes", None),
+            extra_body=kwargs.pop("extra_body", None),
+        )
+        return self._client._request("/v1/feedback", body)
+
+
+class AsyncCaesar:
+    """Asynchronous client for the Caesar search API. Mirrors :class:`Caesar`."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._api_key = _resolve_key(api_key)
+        self._base_url = _resolve_base_url(base_url)
+        self._max_retries = max_retries
+        self._client = http_client or httpx.AsyncClient(timeout=timeout)
+
+    async def search(
+        self,
+        query: str,
+        *,
+        mode: str | None = None,
+        max_results: int | None = None,
+        objective: str | None = None,
+        session_id: str | None = None,
+        verbosity: str | None = None,
+        max_chars_total: int | None = None,
+        extra_body: dict[str, Any] | None = None,
+    ) -> SearchResponse:
+        body = _search_body(
+            query,
+            mode=mode,
+            max_results=max_results,
+            objective=objective,
+            session_id=session_id,
+            verbosity=verbosity,
+            max_chars_total=max_chars_total,
+            extra_body=extra_body,
+        )
+        return SearchResponse.model_validate((await self._request("/v1/search", body)).json())
+
+    async def read(
+        self,
+        target: str | None = None,
+        *,
+        doc_id: str | None = None,
+        url: str | None = None,
+        query: str | None = None,
+        max_chars: int | None = None,
+        start_char: int | None = None,
+        include: list[str] | None = None,
+        extra_body: dict[str, Any] | None = None,
+    ) -> DocumentResponse:
+        body = _read_body(
+            target,
+            doc_id=doc_id,
+            url=url,
+            query=query,
+            max_chars=max_chars,
+            start_char=start_char,
+            include=include,
+            extra_body=extra_body,
+        )
+        return DocumentResponse.model_validate((await self._request("/v1/document", body)).json())
+
+    async def feedback(
+        self,
+        event_type: str,
+        *,
+        search_id: str | None = None,
+        doc_id: str | None = None,
+        passage_id: str | None = None,
+        query: str | None = None,
+        rank: int | None = None,
+        notes: str | None = None,
+        extra_body: dict[str, Any] | None = None,
+    ) -> FeedbackResponse:
+        body = _feedback_body(
+            event_type,
+            search_id=search_id,
+            doc_id=doc_id,
+            passage_id=passage_id,
+            query=query,
+            rank=rank,
+            notes=notes,
+            extra_body=extra_body,
+        )
+        return FeedbackResponse.model_validate((await self._request("/v1/feedback", body)).json())
+
+    async def _request(self, path: str, body: dict[str, Any]) -> httpx.Response:
+        import asyncio
+
+        last_response: httpx.Response | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._client.post(
+                    f"{self._base_url}{path}",
+                    json=body,
+                    headers=_headers(self._api_key),
+                )
+            except httpx.TimeoutException as error:
+                raise APITimeoutError(f"request timed out: {error}") from error
+            except httpx.HTTPError as error:
+                raise APIConnectionError(f"request failed: {error}") from error
+
+            if response.status_code in _RETRYABLE_STATUSES and attempt < self._max_retries:
+                await asyncio.sleep(_retry_delay(attempt, response.headers.get("Retry-After")))
+                last_response = response
+                continue
+            if response.is_success:
+                return response
+            raise status_error_from_response(response)
+
+        raise status_error_from_response(last_response)  # type: ignore[arg-type]  # pragma: no cover
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncCaesar:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()

caesar_search/_exceptions.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import httpx
+
+
+class CaesarError(Exception):
+    """Base class for all caesar-search errors."""
+
+
+class APIConnectionError(CaesarError):
+    """The API could not be reached."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The request timed out."""
+
+
+class APIStatusError(CaesarError):
+    """The API returned a non-2xx response."""
+
+    def __init__(
+        self, *, status_code: int, code: str, message: str, request_id: str | None, response: httpx.Response
+    ):
+        super().__init__(f"{code}: {message}")
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.response = response
+
+
+class AuthenticationError(APIStatusError):
+    """Missing or invalid API key (HTTP 401/403)."""
+
+
+class RateLimitError(APIStatusError):
+    """Rate limit exceeded (HTTP 429)."""
+
+
+def status_error_from_response(response: httpx.Response) -> APIStatusError:
+    code = f"http_{response.status_code}"
+    message = f"API request failed with status {response.status_code}"
+    request_id: str | None = None
+    try:
+        payload = response.json()
+        error = payload.get("error") or {}
+        code = error.get("code") or code
+        message = error.get("message") or message
+        request_id = payload.get("request_id")
+    except Exception:  # noqa: BLE001 - non-JSON error bodies fall back to defaults
+        pass
+
+    error_class = APIStatusError
+    if response.status_code in (401, 403):
+        error_class = AuthenticationError
+    elif response.status_code == 429:
+        error_class = RateLimitError
+    return error_class(
+        status_code=response.status_code,
+        code=code,
+        message=message,
+        request_id=request_id,
+        response=response,
+    )

caesar_search/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

caesar_search/models/__init__.py

@@ -0,0 +1,57 @@
+"""Generated pydantic models for the Caesar public API contract.
+
+Everything here is generated from spec/openapi-public.json by
+datamodel-code-generator — do not hand-edit `_models.py`.
+"""
+
+from ._models import (
+    Access,
+    CaptureHistoryEntry,
+    ContentRange,
+    Document,
+    DocumentContent,
+    DocumentContentRequest,
+    DocumentProvenance,
+    DocumentResponse,
+    ErrorBody,
+    ErrorEnvelope,
+    FeedbackAgentContext,
+    FeedbackResponse,
+    Passage,
+    Ranking,
+    RateLimit,
+    ResponseBudget,
+    ResponseShape,
+    SearchResponse,
+    SearchResult,
+    SearchResultMetadata,
+    SearchScore,
+    Usage,
+    Warning,
+)
+
+__all__ = [
+    "Access",
+    "CaptureHistoryEntry",
+    "ContentRange",
+    "Document",
+    "DocumentContent",
+    "DocumentContentRequest",
+    "DocumentProvenance",
+    "DocumentResponse",
+    "ErrorBody",
+    "ErrorEnvelope",
+    "FeedbackAgentContext",
+    "FeedbackResponse",
+    "Passage",
+    "Ranking",
+    "RateLimit",
+    "ResponseBudget",
+    "ResponseShape",
+    "SearchResponse",
+    "SearchResult",
+    "SearchResultMetadata",
+    "SearchScore",
+    "Usage",
+    "Warning",
+]

caesar_search/models/_models.py

@@ -0,0 +1,408 @@
+# generated by datamodel-codegen:
+#   filename:  openapi-public.json
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import AnyUrl, BaseModel, ConfigDict, Field
+
+
+class CaptureHistoryEntry(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    capture_id: str
+    capture_time: str
+    content_digest: str
+    content_format: str | None = None
+
+
+class ContentRange(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    capture_id: str | None = None
+    """
+    Optional capture pin; a stale_range warning is returned when the latest capture differs.
+    """
+    max_chars: int | None = Field(None, ge=1)
+    """
+    Maximum characters for this range; overrides content.max_chars.
+    """
+    start_char: int | None = Field(None, ge=0)
+    """
+    Character offset to start content from.
+    """
+
+
+class Document(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    canonical_url: str
+    content_digest: str | None = None
+    doc_id: str
+    first_seen_at: str
+    headings: list[str] | None = None
+    last_seen_at: str
+    latest_capture_id: str | None = None
+    meta_description: str | None = None
+    published_at: str | None = None
+    source_url: str
+    title: str | None = None
+
+
+class DocumentContent(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    char_count: int
+    format: str
+    selection: str
+    start_char: int | None = None
+    text: str
+    truncated: bool
+
+
+class Format(Enum):
+    """
+    Returned content format.
+    """
+
+    text = "text"
+    markdown = "markdown"
+
+
+class Selection(Enum):
+    """
+    Content selection strategy.
+    """
+
+    none = "none"
+    query_relevant = "query_relevant"
+    top_passages = "top_passages"
+    passage_ids = "passage_ids"
+    full_document = "full_document"
+
+
+class DocumentContentRequest(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    format: Format | None = "markdown"
+    """
+    Returned content format.
+    """
+    include_offsets: bool | None = None
+    """
+    Whether passage offsets should be included when available.
+    """
+    max_chars: int | None = Field(12000, ge=1)
+    """
+    Maximum content.text characters to return.
+    """
+    passage_ids: list[str] | None = None
+    """
+    Passage IDs to return when selection is passage_ids.
+    """
+    range: ContentRange | None = None
+    """
+    Continuation read: return content starting at a character offset of the same document.
+    """
+    selection: Selection | None = "query_relevant"
+    """
+    Content selection strategy.
+    """
+
+
+class DocumentProvenance(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    capture_id: str
+    capture_time: str
+
+
+class ErrorBody(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    code: str
+    """
+    Stable machine-readable error code.
+    """
+    details: dict[str, Any] | None = None
+    """
+    Optional structured error details.
+    """
+    message: str
+    """
+    Human-readable error message.
+    """
+
+
+class Type(Enum):
+    """
+    Envelope discriminator.
+    """
+
+    error = "error"
+
+
+class ErrorEnvelope(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    field_schema: AnyUrl | None = Field(
+        None,
+        alias="$schema",
+        examples=[
+            "https://search-api-staging-779189860552.europe-west1.run.app/ErrorEnvelope.json"
+        ],
+    )
+    """
+    A URL to the JSON Schema for this object.
+    """
+    error: ErrorBody
+    """
+    Error details.
+    """
+    request_id: str
+    """
+    Server request identifier.
+    """
+    type: Type
+    """
+    Envelope discriminator.
+    """
+
+
+class FeedbackAgentContext(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    client_model: str | None = None
+    """
+    Calling model identifier.
+    """
+    task_type: str | None = None
+    """
+    Agent task type or evaluation bucket.
+    """
+
+
+class Passage(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    char_end: int | None = None
+    char_start: int | None = None
+    doc_id: str
+    ordinal: int
+    passage_id: str
+    section_heading: str | None = None
+    section_path: list[str] | None = None
+    text: str
+
+
+class Ranking(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    mode: str
+    ranker_version: str
+    score_scope: str
+
+
+class RateLimit(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    limit_rps: int
+    remaining: int
+    reset_at: str
+
+
+class OnExceed(Enum):
+    """
+    What to do when the budget binds: shed payload in the documented order, or fail with response_too_large.
+    """
+
+    shed = "shed"
+    error = "error"
+
+
+class ResponseBudget(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    max_chars_total: int | None = Field(None, ge=1)
+    """
+    Maximum serialized response size in characters. Roughly 4 characters per token.
+    """
+    on_exceed: OnExceed | None = "shed"
+    """
+    What to do when the budget binds: shed payload in the documented order, or fail with response_too_large.
+    """
+
+
+class Verbosity(Enum):
+    """
+    Field preset: ids_only (rank, doc_id, url, title), compact (adds snippet, score, key dates), standard (today's default), full (adds provenance).
+    """
+
+    ids_only = "ids_only"
+    compact = "compact"
+    standard = "standard"
+    full = "full"
+
+
+class ResponseShape(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    budget: ResponseBudget | None = None
+    """
+    Total serialized response budget in characters with deterministic shedding.
+    """
+    verbosity: Verbosity | None = "standard"
+    """
+    Field preset: ids_only (rank, doc_id, url, title), compact (adds snippet, score, key dates), standard (today's default), full (adds provenance).
+    """
+
+
+class SearchResultMetadata(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    content_digest: str | None = None
+    extracted_at: str | None = None
+    first_seen_at: str | None = None
+    last_crawled_at: str | None = None
+    last_seen_at: str | None = None
+    published_at: str | None = None
+
+
+class SearchScore(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    value: float
+
+
+class Usage(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    approx_tokens: int
+    bytes_returned: int
+    requests: int
+
+
+class Warning(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    code: str
+    details: dict[str, Any] | None = None
+    message: str
+
+
+class Access(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    rate_limit: RateLimit
+    tier: str
+
+
+class DocumentResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    field_schema: AnyUrl | None = Field(
+        None,
+        alias="$schema",
+        examples=[
+            "https://search-api-staging-779189860552.europe-west1.run.app/DocumentResponse.json"
+        ],
+    )
+    """
+    A URL to the JSON Schema for this object.
+    """
+    access: Access
+    capture_history: list[CaptureHistoryEntry] | None = None
+    content: DocumentContent | None = None
+    doc: Document
+    passages: list[Passage] | None = None
+    provenance: DocumentProvenance | None = None
+    request_id: str
+    session_id: str
+    usage: Usage | None = None
+    warnings: list[Warning] | None = None
+
+
+class FeedbackResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    field_schema: AnyUrl | None = Field(
+        None,
+        alias="$schema",
+        examples=[
+            "https://search-api-staging-779189860552.europe-west1.run.app/FeedbackResponse.json"
+        ],
+    )
+    """
+    A URL to the JSON Schema for this object.
+    """
+    accepted: bool
+    access: Access
+    feedback_id: str
+    request_id: str
+    session_id: str
+    usage: Usage | None = None
+
+
+class SearchResult(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    canonical_url: str
+    description: str | None = None
+    doc_id: str
+    metadata: SearchResultMetadata | None = None
+    passages: list[Passage] | None = None
+    provenance: DocumentProvenance | None = None
+    rank: int
+    score: SearchScore | None = None
+    snippet: str | None = None
+    source_url: str | None = None
+    title: str | None = None
+
+
+class SearchResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    field_schema: AnyUrl | None = Field(
+        None,
+        alias="$schema",
+        examples=[
+            "https://search-api-staging-779189860552.europe-west1.run.app/SearchResponse.json"
+        ],
+    )
+    """
+    A URL to the JSON Schema for this object.
+    """
+    access: Access | None = None
+    ranking: Ranking | None = None
+    request_id: str
+    results: list[SearchResult] | None
+    search_id: str
+    session_id: str
+    truncated: bool | None = None
+    usage: Usage | None = None
+    warnings: list[Warning] | None = None

caesar_search-0.1.0.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: caesar-search
+Version: 0.1.0
+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)

caesar_search-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+caesar_search/__init__.py,sha256=0bClWbimpuV1ll8UqHXs4lOsk45Rx9TXNU1OWEs3nBU,724
+caesar_search/_client.py,sha256=9Z4Nu8VsoKOQ-bRC-8l-dew_j8mcl2aP8kk9z89MgUU,15727
+caesar_search/_exceptions.py,sha256=R6GcXNnvWd0WJ992sx9gxeGVMijsIqwYZtbr7Q1mXiU,1816
+caesar_search/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+caesar_search/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+caesar_search/models/__init__.py,sha256=Oo1kVKi4VAEq1ERk5zjK4M-uyWmmo0TE7og0F3iARjE,1141
+caesar_search/models/_models.py,sha256=F-n3d0Q1MUqOcAlCRIQm0_4icgl49g5MRS17UG8N-Lg,9115
+caesar_search-0.1.0.dist-info/METADATA,sha256=lN6TAXUOIaKz_UA-XRjf6DuAO_pq7MnW5g9u8eQdR4s,2563
+caesar_search-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+caesar_search-0.1.0.dist-info/licenses/LICENSE,sha256=O9WfHubv0fg_DEnziZs8MtsruiasOY_Ym5VbN168nU0,1063
+caesar_search-0.1.0.dist-info/RECORD,,

caesar_search-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

caesar_search-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Caesar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.