caedral 0.1.0__py3-none-any.whl

caedral/__init__.py

@@ -0,0 +1,5 @@
+from caedral.client import Caedral
+from caedral.errors import CaedralAPIError, CaedralNetworkError
+
+__all__ = ["Caedral", "CaedralAPIError", "CaedralNetworkError"]
+__version__ = "0.1.0"

caedral/_sse.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from typing import Any, Callable, TypeVar
+
+import httpx
+
+from caedral.errors import CaedralAPIError
+
+T = TypeVar("T")
+
+
+def iter_sse_json(
+    response: httpx.Response,
+    *,
+    model_factory: Callable[[dict[str, Any]], T],
+) -> Iterator[T]:
+    """Parse Server-Sent Events lines into JSON objects."""
+    if response.is_closed:
+        raise CaedralAPIError("Streaming response has no body", status_code=502)
+
+    buffer = ""
+    for chunk in response.iter_text():
+        buffer += chunk
+        while "\n" in buffer:
+            line, buffer = buffer.split("\n", 1)
+            parsed = _parse_sse_line(line.strip(), model_factory)
+            if parsed is not None:
+                yield parsed
+
+    trailing = buffer.strip()
+    if trailing:
+        parsed = _parse_sse_line(trailing, model_factory)
+        if parsed is not None:
+            yield parsed
+
+
+def _parse_sse_line(
+    line: str,
+    model_factory: Callable[[dict[str, Any]], T],
+) -> T | None:
+    if not line.startswith("data:"):
+        return None
+
+    data = line[len("data:") :].strip()
+    if not data or data == "[DONE]":
+        return None
+
+    try:
+        payload = json.loads(data)
+    except json.JSONDecodeError as exc:
+        raise CaedralAPIError(
+            "Failed to parse streaming response chunk",
+            status_code=502,
+            error_type="upstream_error",
+        ) from exc
+
+    if not isinstance(payload, dict):
+        raise CaedralAPIError(
+            "Invalid streaming chunk payload",
+            status_code=502,
+            error_type="upstream_error",
+        )
+
+    return model_factory(payload)

caedral/client.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Any
+
+from caedral.http import HttpClient
+from caedral.resources.audio import AudioResource
+from caedral.resources.chat import ChatResource
+from caedral.resources.embeddings import EmbeddingsResource
+from caedral.resources.images import ImagesResource
+from caedral.resources.models import ModelsResource
+from caedral.resources.rerank import RerankResource
+from caedral.resources.usage import UsageResource
+
+
+class Caedral:
+    """Official synchronous Python client for the Caedral API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.caedral.com",
+        max_retries: int = 3,
+        timeout: float = 120.0,
+        **_: Any,
+    ) -> None:
+        """Create a new Caedral client.
+
+        Args:
+            api_key: Caedral API key used to authenticate every request.
+                Must be a non-empty, non-blank string.
+            base_url: Base URL of the Caedral API gateway. Defaults to
+                the production endpoint; use ``http://localhost:5001``
+                for local development.
+            max_retries: Maximum number of automatic retries for
+                idempotent (GET) requests. Defaults to ``3``.
+            timeout: Per-request timeout in seconds. Defaults to
+                ``120.0``.
+
+        Raises:
+            ValueError: If ``api_key`` is missing or blank.
+        """
+        if not api_key or not api_key.strip():
+            raise ValueError("Caedral: api_key is required")
+
+        self._http = HttpClient(
+            api_key=api_key.strip(),
+            base_url=base_url,
+            max_retries=max_retries,
+            timeout=timeout,
+        )
+
+        self.chat = ChatResource(self._http)
+        self.models = ModelsResource(self._http)
+        self.usage = UsageResource(self._http)
+        self.embeddings = EmbeddingsResource(self._http)
+        self.images = ImagesResource(self._http)
+        self.audio = AudioResource(self._http)
+        self.rerank = RerankResource(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Caedral:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

caedral/errors.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class CaedralAPIError(Exception):
+    """Raised when the Caedral API returns an error response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int = 0,
+        error_type: str = "unknown",
+        raw_body: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.type = error_type
+        self.raw_body = raw_body
+
+    @classmethod
+    def from_response(cls, status_code: int, body: Any) -> CaedralAPIError:
+        if isinstance(body, dict) and isinstance(body.get("error"), dict):
+            error = body["error"]
+            message = error.get("message") or f"Request failed with status {status_code}"
+            return cls(
+                message,
+                status_code=error.get("code") or status_code,
+                error_type=error.get("type") or "unknown",
+                raw_body=body,
+            )
+
+        if isinstance(body, dict) and isinstance(body.get("message"), str):
+            return cls(body["message"], status_code=status_code, raw_body=body)
+
+        if isinstance(body, str) and body.strip():
+            return cls(body, status_code=status_code, raw_body=body)
+
+        return cls(
+            f"Request failed with status {status_code}",
+            status_code=status_code,
+            raw_body=body,
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"CaedralAPIError(message={self.message!r}, "
+            f"status_code={self.status_code}, type={self.type!r})"
+        )
+
+
+class CaedralNetworkError(CaedralAPIError):
+    """Raised on network failures or timeouts."""
+
+    def __init__(self, message: str, *, cause: BaseException | None = None) -> None:
+        super().__init__(message, status_code=0, error_type="network_error")
+        self.__cause__ = cause

caedral/http.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+import httpx
+
+from caedral.errors import CaedralAPIError, CaedralNetworkError
+
+DEFAULT_BASE_URL = "https://api.caedral.com"
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_TIMEOUT = 120.0
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self._owns_client = client is None
+        self._client = client or httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def get(self, path: str) -> Any:
+        return self._request_with_retry("GET", path)
+
+    def post_json(self, path: str, body: dict[str, Any]) -> Any:
+        return self._request("POST", path, json_body=body)
+
+    def post_stream(self, path: str, body: dict[str, Any]) -> httpx.Response:
+        request = self._client.build_request(
+            "POST",
+            f"{self.base_url}{path}",
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+            json=body,
+        )
+        try:
+            return self._client.send(request, stream=True)
+        except httpx.TimeoutException as exc:
+            raise CaedralNetworkError(
+                f"Request timed out after {self.timeout}s",
+                cause=exc,
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise CaedralNetworkError(str(exc) or "Network request failed", cause=exc) from exc
+
+    def _request_with_retry(self, method: str, path: str) -> Any:
+        last_error: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                return self._request(method, path)
+            except Exception as exc:
+                last_error = exc
+                if not self._should_retry(exc, attempt):
+                    raise
+                time.sleep(self._backoff_ms(attempt) / 1000)
+        assert last_error is not None
+        raise last_error
+
+    def _should_retry(self, err: Exception, attempt: int) -> bool:
+        if attempt >= self.max_retries:
+            return False
+        if isinstance(err, CaedralNetworkError):
+            return True
+        if isinstance(err, CaedralAPIError):
+            return err.status_code in (502, 503)
+        return False
+
+    @staticmethod
+    def _backoff_ms(attempt: int) -> int:
+        return 100 * (2**attempt)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+    ) -> Any:
+        response = self._request_raw(method, path, json_body=json_body)
+        text = response.text
+        parsed = _safe_json_parse(text) if text else None
+        if response.status_code >= 400:
+            raise CaedralAPIError.from_response(response.status_code, parsed or text)
+        return parsed
+
+    def _request_raw(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+
+        try:
+            return self._client.request(
+                method,
+                f"{self.base_url}{path}",
+                headers=headers,
+                json=json_body,
+                timeout=self.timeout,
+            )
+        except httpx.TimeoutException as exc:
+            raise CaedralNetworkError(
+                f"Request timed out after {self.timeout}s",
+                cause=exc,
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise CaedralNetworkError(str(exc) or "Network request failed", cause=exc) from exc
+
+
+def _safe_json_parse(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return text

caedral/resources/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from caedral.resources.chat import ChatResource
+from caedral.resources.embeddings import EmbeddingsResource
+from caedral.resources.images import ImagesResource
+from caedral.resources.models import ModelsResource
+from caedral.resources.rerank import RerankResource
+from caedral.resources.usage import UsageResource
+
+__all__ = [
+    "ChatResource",
+    "ModelsResource",
+    "UsageResource",
+    "EmbeddingsResource",
+    "ImagesResource",
+    "RerankResource",
+]

caedral/resources/audio.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any
+
+from caedral.http import HttpClient
+from caedral.types import AudioGenerateResponse
+
+
+class AudioResource:
+    """Audio (text-to-speech) endpoint (``POST /v1/audio/speech``)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def generate(
+        self,
+        *,
+        input: str,
+        model: str | None = None,
+        voice: str | None = None,
+        **kwargs: Any,
+    ) -> AudioGenerateResponse:
+        """Synthesize speech audio from an input text string.
+
+        Args:
+            input: Text to convert to speech.
+            model: Optional model identifier. When omitted, the API
+                selects a default speech model.
+            voice: Optional voice identifier or style hint.
+            **kwargs: Additional request fields forwarded to the API.
+
+        Returns:
+            An :class:`AudioGenerateResponse` containing the generated
+            audio payload.
+
+        Raises:
+            CaedralAPIError: If the API returns a non-2xx response.
+        """
+        body: dict[str, Any] = {"input": input, **kwargs}
+        if model is not None:
+            body["model"] = model
+        if voice is not None:
+            body["voice"] = voice
+        data = self._http.post_json("/v1/audio/speech", body)
+        return AudioGenerateResponse.model_validate(data)

caedral/resources/chat.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any, Literal, overload
+
+from caedral._sse import iter_sse_json
+from caedral.errors import CaedralAPIError
+from caedral.http import HttpClient
+from caedral.types import ChatCompletion, ChatCompletionChunk
+
+
+class ChatCompletions:
+    """Chat completions endpoint (``POST /v1/chat/completions``).
+
+    Supports both buffered and Server-Sent Events (SSE) streaming
+    responses; the return type of :meth:`create` depends on the
+    ``stream`` flag.
+    """
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    @overload
+    def create(
+        self,
+        *,
+        model: str,
+        messages: list[dict[str, Any]],
+        stream: Literal[False] = False,
+        **kwargs: Any,
+    ) -> ChatCompletion: ...
+
+    @overload
+    def create(
+        self,
+        *,
+        model: str,
+        messages: list[dict[str, Any]],
+        stream: Literal[True],
+        **kwargs: Any,
+    ) -> Iterator[ChatCompletionChunk]: ...
+
+    def create(
+        self,
+        *,
+        model: str,
+        messages: list[dict[str, Any]],
+        stream: bool = False,
+        **kwargs: Any,
+    ) -> ChatCompletion | Iterator[ChatCompletionChunk]:
+        """Create a chat completion.
+
+        Args:
+            model: Model identifier (for example ``"caedral-base"``).
+            messages: Ordered list of chat messages in OpenAI-style
+                ``{"role": ..., "content": ...}`` format.
+            stream: When ``False`` (default), the full completion is
+                returned once ready. When ``True``, an iterator of
+                incremental ``ChatCompletionChunk`` deltas is returned
+                (SSE).
+            **kwargs: Additional request fields (``temperature``,
+                ``max_tokens``, ``top_p``, ``stop``, ``user``, etc.)
+                forwarded to the API.
+
+        Returns:
+            A :class:`ChatCompletion` when not streaming, or an
+            :class:`Iterator` of :class:`ChatCompletionChunk` when
+            ``stream=True``.
+
+        Raises:
+            CaedralAPIError: If the API returns a non-2xx response.
+
+        Example:
+            Streaming::
+
+                stream = client.chat.completions.create(
+                    model="caedral-base",
+                    messages=[{"role": "user", "content": "Hi"}],
+                    stream=True,
+                )
+                for chunk in stream:
+                    delta = chunk.choices[0].delta.content
+                    if delta:
+                        print(delta, end="", flush=True)
+        """
+        body: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "stream": stream,
+            **kwargs,
+        }
+
+        if stream:
+            return self._create_stream(body)
+        data = self._http.post_json("/v1/chat/completions", body)
+        return ChatCompletion.model_validate(data)
+
+    def _create_stream(self, body: dict[str, Any]) -> Iterator[ChatCompletionChunk]:
+        response = self._http.post_stream("/v1/chat/completions", body)
+        try:
+            if response.status_code >= 400:
+                error_body: Any
+                try:
+                    error_body = response.json()
+                except Exception:
+                    error_body = response.read().decode("utf-8", errors="replace")
+                raise CaedralAPIError.from_response(response.status_code, error_body)
+
+            yield from iter_sse_json(
+                response,
+                model_factory=ChatCompletionChunk.model_validate,
+            )
+        finally:
+            response.close()
+
+
+class ChatResource:
+    """Namespace grouping chat-related endpoints.
+
+    Currently exposes :attr:`completions` for
+    ``POST /v1/chat/completions``.
+    """
+
+    def __init__(self, http: HttpClient) -> None:
+        self.completions = ChatCompletions(http)

caedral/resources/embeddings.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any
+
+from caedral.http import HttpClient
+from caedral.types import EmbeddingCreateResponse
+
+
+class EmbeddingsResource:
+    """Text embeddings endpoint (``POST /v1/embeddings``)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        model: str,
+        input: str | list[str],
+        **kwargs: Any,
+    ) -> EmbeddingCreateResponse:
+        """Generate dense vector embeddings for one or more inputs.
+
+        Args:
+            model: Embedding model identifier (for example
+                ``"caedral-embed"``).
+            input: A single string or a list of strings to embed.
+                When a list is provided, the response returns one
+                vector per input in the same order.
+            **kwargs: Additional request fields forwarded to the API.
+
+        Returns:
+            An :class:`EmbeddingCreateResponse` containing the
+            generated vectors and token usage.
+
+        Raises:
+            CaedralAPIError: If the API returns a non-2xx response.
+        """
+        body = {"model": model, "input": input, **kwargs}
+        data = self._http.post_json("/v1/embeddings", body)
+        return EmbeddingCreateResponse.model_validate(data)

caedral/resources/images.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any
+
+from caedral.http import HttpClient
+from caedral.types import ImageGenerateResponse
+
+
+class ImagesResource:
+    """Image generation endpoint (``POST /v1/images/generations``)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def generate(
+        self,
+        *,
+        prompt: str,
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> ImageGenerateResponse:
+        """Generate one or more images from a text prompt.
+
+        Args:
+            prompt: Natural-language description of the desired image.
+            model: Optional model identifier. When omitted, the API
+                selects a default image model.
+            **kwargs: Additional request fields such as ``n`` (number
+                of images) or ``size`` (output resolution).
+
+        Returns:
+            An :class:`ImageGenerateResponse` containing the generated
+            images as URLs or base64-encoded data.
+
+        Raises:
+            CaedralAPIError: If the API returns a non-2xx response.
+        """
+        body: dict[str, Any] = {"prompt": prompt, **kwargs}
+        if model is not None:
+            body["model"] = model
+        data = self._http.post_json("/v1/images/generations", body)
+        return ImageGenerateResponse.model_validate(data)

caedral/resources/models.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from caedral.http import HttpClient
+from caedral.types import ModelListResponse
+
+
+class ModelsResource:
+    """Model catalog endpoint (``GET /v1/models``)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> ModelListResponse:
+        """List every model available to the authenticated account.
+
+        Returns:
+            A :class:`ModelListResponse` describing each model along
+            with its context window and pricing tier.
+
+        Raises:
+            CaedralAPIError: If the API returns a non-2xx response.
+        """
+        data = self._http.get("/v1/models")
+        return ModelListResponse.model_validate(data)

caedral/resources/rerank.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Any
+
+from caedral.http import HttpClient
+from caedral.types import RerankCreateResponse
+
+
+class RerankResource:
+    """Document rerank endpoint (``POST /v1/rerank``)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        query: str,
+        documents: list[str],
+        model: str | None = None,
+        top_n: int | None = None,
+        **kwargs: Any,
+    ) -> RerankCreateResponse:
+        """Reorder documents by semantic relevance to a query.
+
+        Args:
+            query: Query text used to score the documents.
+            documents: List of candidate documents to rerank.
+            model: Optional model identifier. When omitted, the API
+                selects a default rerank model.
+            top_n: Optional cap on the number of results returned,
+                keeping only the top-N most relevant documents.
+            **kwargs: Additional request fields forwarded to the API.
+
+        Returns:
+            A :class:`RerankCreateResponse` with relevance-scored
+            results ordered from most to least relevant.
+
+        Raises:
+            CaedralAPIError: If the API returns a non-2xx response.
+        """
+        body: dict[str, Any] = {
+            "query": query,
+            "documents": documents,
+            **kwargs,
+        }
+        if model is not None:
+            body["model"] = model
+        if top_n is not None:
+            body["top_n"] = top_n
+        data = self._http.post_json("/v1/rerank", body)
+        return RerankCreateResponse.model_validate(data)

caedral/resources/usage.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from caedral.http import HttpClient
+from caedral.types import UsageSummary
+
+
+class UsageResource:
+    """Account usage endpoint (``GET /v1/usage``)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def get(self) -> UsageSummary:
+        """Fetch a snapshot of the account's current billing state.
+
+        Returns:
+            A :class:`UsageSummary` describing the current plan,
+            weekly free pool utilization, prepaid balance, and
+            overage limits.
+
+        Raises:
+            CaedralAPIError: If the API returns a non-2xx response.
+        """
+        data = self._http.get("/v1/usage")
+        return UsageSummary.model_validate(data)

caedral/types.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class CaedralBaseModel(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class ChatMessageParam(CaedralBaseModel):
+    role: Literal["system", "user", "assistant", "tool"]
+    content: str | None
+    name: str | None = None
+
+
+class ChatCompletionChoice(CaedralBaseModel):
+    index: int
+    message: dict[str, Any]
+    finish_reason: str | None = None
+
+
+class CompletionUsage(CaedralBaseModel):
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+class ChatCompletion(CaedralBaseModel):
+    id: str
+    object: Literal["chat.completion"] = "chat.completion"
+    created: int
+    model: str
+    choices: list[ChatCompletionChoice]
+    usage: CompletionUsage | None = None
+
+
+class ChatCompletionChunkChoice(CaedralBaseModel):
+    index: int
+    delta: dict[str, Any] = Field(default_factory=dict)
+    finish_reason: str | None = None
+
+
+class ChatCompletionChunk(CaedralBaseModel):
+    id: str
+    object: Literal["chat.completion.chunk"] = "chat.completion.chunk"
+    created: int
+    model: str
+    choices: list[ChatCompletionChunkChoice]
+
+
+class Model(CaedralBaseModel):
+    id: str
+    object: Literal["model"] = "model"
+    created: int
+    owned_by: str
+    name: str
+    description: str
+    context_window: int
+    pricing_tier: str
+
+
+class ModelListResponse(CaedralBaseModel):
+    object: Literal["list"] = "list"
+    data: list[Model]
+
+
+class WeeklyPool(CaedralBaseModel):
+    limit: int
+    used: int
+    remaining: int
+
+
+class OverageSummary(CaedralBaseModel):
+    enabled: bool
+    limitCents: int | None = None
+    usedCents: int
+    remainingCents: int | None = None
+
+
+class UsageSummary(CaedralBaseModel):
+    accountStatus: str
+    plan: str
+    planStatus: str
+    balanceCents: int
+    weeklyPool: WeeklyPool
+    overage: OverageSummary
+    balanceWeightedUnitsAffordable: int
+
+
+class EmbeddingData(CaedralBaseModel):
+    object: str
+    embedding: list[float]
+    index: int
+
+
+class EmbeddingCreateResponse(CaedralBaseModel):
+    object: str
+    model: str
+    data: list[EmbeddingData]
+    usage: CompletionUsage | None = None
+
+
+class ImageData(CaedralBaseModel):
+    url: str | None = None
+    b64_json: str | None = None
+
+
+class ImageGenerateResponse(CaedralBaseModel):
+    model: str
+    data: list[ImageData]
+    usage: CompletionUsage | None = None
+
+
+class AudioGenerateResponse(CaedralBaseModel):
+    model: str
+    choices: list[dict[str, Any]] | None = None
+    usage: CompletionUsage | None = None
+
+
+class RerankResult(CaedralBaseModel):
+    index: int
+    relevance_score: float
+
+
+class RerankCreateResponse(CaedralBaseModel):
+    model: str
+    results: list[RerankResult]

caedral-0.1.0.dist-info/METADATA

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: caedral
+Version: 0.1.0
+Summary: Official Python client for the Caedral API
+Project-URL: Homepage, https://caedral.com/docs/python
+Project-URL: Repository, https://github.com/caedral/caedral-python
+Project-URL: Issues, https://github.com/caedral/caedral-python/issues
+Author-email: Caedral <hello@caedral.com>
+License: MIT
+Keywords: ai,api,caedral,llm
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: bcrypt>=4.0.0; extra == 'dev'
+Requires-Dist: psycopg[binary]>=3.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Caedral Python SDK
+
+Official Python client for the [Caedral API](https://caedral.com). OpenAI-compatible request shapes — point your existing code at Caedral with minimal changes.
+
+## Installation
+
+```bash
+pip install caedral
+```
+
+### Local development (editable install)
+
+```bash
+cd sdk-python
+python -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+from caedral import Caedral
+
+caedral = Caedral(
+    api_key="cd_live_...",
+    base_url="http://localhost:5001",  # local API gateway
+)
+
+completion = caedral.chat.completions.create(
+    model="caedral-titan",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+
+print(completion.choices[0].message["content"])
+caedral.close()
+```
+
+Or use a context manager:
+
+```python
+with Caedral(api_key="cd_live_...", base_url="http://localhost:5001") as caedral:
+    usage = caedral.usage.get()
+    print(usage.weeklyPool.remaining)
+```
+
+Production default base URL: `https://api.caedral.com`.
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | — | Required. Your `cd_live_...` API key |
+| `base_url` | `https://api.caedral.com` | API gateway base URL |
+| `max_retries` | `3` | Retries for idempotent GET requests (exponential backoff) |
+| `timeout` | `120.0` | Request timeout in seconds |
+
+## Methods
+
+### `caedral.chat.completions.create(...)`
+
+OpenAI-compatible chat completions.
+
+**Non-streaming:**
+
+```python
+response = caedral.chat.completions.create(
+    model="caedral-olympus",
+    messages=[
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "Explain quantum computing briefly."},
+    ],
+    temperature=0.7,
+    max_tokens=500,
+)
+
+print(response.choices[0].message["content"])
+print(response.usage.total_tokens if response.usage else None)
+```
+
+**Streaming** (generator):
+
+```python
+stream = caedral.chat.completions.create(
+    model="caedral-titan",
+    messages=[{"role": "user", "content": "Write a haiku about code."}],
+    stream=True,
+)
+
+for chunk in stream:
+    delta = chunk.choices[0].delta.get("content")
+    if delta:
+        print(delta, end="", flush=True)
+print()
+```
+
+Models: `caedral-base`, `caedral-titan`, `caedral-olympus`, `caedral-primordial`.
+
+### `caedral.models.list()`
+
+```python
+models = caedral.models.list()
+for model in models.data:
+    print(model.id, model.name, model.pricing_tier)
+```
+
+### `caedral.usage.get()`
+
+```python
+usage = caedral.usage.get()
+print("Pool remaining:", usage.weeklyPool.remaining)
+print("Balance (cents):", usage.balanceCents)
+print("Overage used:", usage.overage.usedCents)
+```
+
+### `caedral.embeddings.create(...)`
+
+```python
+result = caedral.embeddings.create(
+    model="caedral-embed",
+    input="Caedral unifies frontier models behind one API.",
+)
+print(len(result.data[0].embedding))
+```
+
+### `caedral.images.generate(...)`
+
+```python
+image = caedral.images.generate(
+    model="caedral-vision",
+    prompt="A minimal geometric logo on a dark background",
+)
+print(image.data[0].url or "b64 payload returned")
+```
+
+### `caedral.audio.generate(...)`
+
+```python
+audio = caedral.audio.generate(
+    model="caedral-voice",
+    input="Welcome to Caedral.",
+    voice="alloy",
+)
+print(audio.model)
+```
+
+### `caedral.rerank.create(...)`
+
+```python
+ranked = caedral.rerank.create(
+    model="caedral-rerank",
+    query="billing and subscriptions",
+    documents=[
+        "Caedral pricing tiers include Starter and Pro.",
+        "The API gateway runs on port 5001 in local dev.",
+    ],
+    top_n=2,
+)
+for item in ranked.results:
+    print(item.index, item.relevance_score)
+```
+
+## Error handling
+
+```python
+from caedral import Caedral, CaedralAPIError
+
+try:
+    caedral.chat.completions.create(
+        model="caedral-base",
+        messages=[{"role": "user", "content": "Hi"}],
+    )
+except CaedralAPIError as err:
+    print(err.status_code, err.type, err.message)
+```
+
+## Async client
+
+`AsyncCaedral` is planned as a fast-follow. The synchronous client covers all endpoints today.
+
+## Integration tests
+
+Requires a running local gateway (`http://localhost:5001`) and `DATABASE_URL` in the repo root `.env` (tests create a temporary API key automatically).
+
+```bash
+cd sdk-python
+pip install -e ".[dev]"
+pytest -v
+```
+
+Optional environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `CAEDRAL_BASE_URL` | Gateway URL (default `http://localhost:5001`) |
+| `CAEDRAL_TEST_API_KEY` | Skip auto key creation and use an existing key |
+
+## License
+
+MIT

caedral-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+caedral/__init__.py,sha256=ItiwPrxYwEKwBDdPK1TuQov26i_e5bC7Bjm7865fQV8,186
+caedral/_sse.py,sha256=EbGoDY0IfnR1UoGXnvVVBhDxgXqUly_DoBXmbv8gL90,1699
+caedral/client.py,sha256=eeeSry_EALqlwaJUfLAIVseXNFKz0VerU8bwMtOW9pQ,2240
+caedral/errors.py,sha256=EEUUA833txqKsIHoqWW4Pye-M9A8q_cYfIkmDBTrS4A,1925
+caedral/http.py,sha256=NR-Kfd46V1fS_XHeeeIa2gpswB9D3VlyWgZ23koMpu4,4402
+caedral/types.py,sha256=FouFDi9LtGYcRRGH1SbKRt-3Sl727owa9m_5Uja6NvA,2767
+caedral/resources/__init__.py,sha256=0DxdOWoEjotF0oF9y3ddJfZpzi9Doh9cu-hyIhPDKxY,498
+caedral/resources/audio.py,sha256=hub8oWviWMu_Y_bSICDdzh_N-Rbd6bSor_7laVZEMzQ,1390
+caedral/resources/chat.py,sha256=apT7WGuvHLhvNg2Dnl4K5pQzsY3dM1m9j0F0Pzof0-g,3938
+caedral/resources/embeddings.py,sha256=SCKYtTKrKp_4nVgZiLFj7L18ANeQaWI3ZMDMURmqcOc,1301
+caedral/resources/images.py,sha256=90QKuQCj5eHEfCjcN27gSCKScIjinZryPKYX9TicSco,1347
+caedral/resources/models.py,sha256=Ksx_54q5ZpnGW-TzpRto2yIB6jjV3M-vDzUVuEF_uQE,718
+caedral/resources/rerank.py,sha256=-EjEhWtDn1_InCr_c0u1Z5BOo3cDFNWH0XyomvYMNoo,1640
+caedral/resources/usage.py,sha256=zdx5sTT7qOCiIhf2vFBJrkJ3zCSQeg-1GdkYRbppUMI,732
+caedral-0.1.0.dist-info/METADATA,sha256=eTUlnBeTGRQbwPqYX2QAFYEwQgLdy033FHJln2da89E,5679
+caedral-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+caedral-0.1.0.dist-info/RECORD,,

caedral-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