caedral 0.1.0__tar.gz

caedral-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.egg
+
+# Environment
+.env
+.env.*
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/

caedral-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,200 @@
+# 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/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "caedral"
+version = "0.1.0"
+description = "Official Python client for the Caedral API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Caedral", email = "hello@caedral.com" }]
+keywords = ["caedral", "llm", "api", "ai"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27.0",
+  "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "bcrypt>=4.0.0",
+  "psycopg[binary]>=3.1.0",
+  "python-dotenv>=1.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/caedral"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/caedral", "README.md", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[project.urls]
+Homepage = "https://caedral.com/docs/python"
+Repository = "https://github.com/caedral/caedral-python"
+Issues = "https://github.com/caedral/caedral-python/issues"

caedral-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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