ciralgo 1.1.0__tar.gz

ciralgo-1.1.0/LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Ciralgo BV
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   The full Apache License 2.0 text is available at the URL above.

ciralgo-1.1.0/NOTICE

@@ -0,0 +1,17 @@
+Ciralgo Python SDK
+Copyright 2026 Ciralgo B.V.
+
+This product is the official Python client for the Ciralgo Platform API
+(https://www.ciralgo.com).
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License. You may obtain
+a copy of the License at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

ciralgo-1.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: ciralgo
+Version: 1.1.0
+Summary: Official Python SDK for the Ciralgo Platform API
+Project-URL: Homepage, https://www.ciralgo.com
+Project-URL: Documentation, https://docs.ciralgo.com/sdk-python
+Project-URL: Repository, https://github.com/Ciralgo/ciralgo-python
+Project-URL: Changelog, https://github.com/Ciralgo/ciralgo-python/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Ciralgo/ciralgo-python/issues
+Author-email: Ciralgo <support@ciralgo.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ai,anthropic,ciralgo,compliance,eu-sovereignty,llm,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software 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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: typing-extensions>=4.5; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Ciralgo Python SDK
+
+Official Python SDK for the [Ciralgo Platform API](https://www.ciralgo.com).
+
+Version: `1.1.0` (mirrors `openapi.json info.version`).
+
+## Install
+
+```bash
+pip install ciralgo
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+from ciralgo import Client
+
+client = Client(api_key="sk-cg-...")  # or set CIRALGO_API_KEY in your env
+
+response = client.chat.completions.create(
+    model="openai/gpt-4o-mini",
+    messages=[{"role": "user", "content": "Say hello."}],
+)
+print(response["choices"][0]["message"]["content"])
+```
+
+## Authentication
+
+The SDK reads the API key from (in order):
+
+1. The `api_key=` argument to `Client(...)` or `AsyncClient(...)`.
+2. The `CIRALGO_API_KEY` environment variable.
+
+If neither is set, `AuthenticationError` is raised at construction time.
+
+The optional `CIRALGO_BASE_URL` env var overrides the default `https://api.ciralgo.com`. This is useful for staging or for self-hosted Ciralgo deployments.
+
+## Endpoints
+
+The four public proxy operations from the Ciralgo OpenAPI spec (v1.1.0):
+
+### Chat completions
+
+```python
+response = client.chat.completions.create(
+    model="anthropic/claude-sonnet-4-6",
+    messages=[
+        {"role": "system", "content": "You are a finance compliance assistant."},
+        {"role": "user", "content": "Summarise EU AI Act Article 15."},
+    ],
+    temperature=0.2,
+    max_tokens=400,
+    tags={"project": "ai-act-summariser", "env": "prod"},
+)
+```
+
+### Streaming chat completions
+
+```python
+for chunk in client.chat.completions.create(
+    model="openai/gpt-4o-mini",
+    messages=[{"role": "user", "content": "Stream me a haiku."}],
+    stream=True,
+):
+    delta = chunk["choices"][0]["delta"].get("content", "")
+    print(delta, end="", flush=True)
+```
+
+### Embeddings
+
+```python
+embedding = client.embeddings.create(
+    model="openai/text-embedding-3-small",
+    input="EU AI Act Article 15 covers accuracy, robustness and cybersecurity.",
+)
+print(len(embedding["data"][0]["embedding"]))  # → vector dimension
+```
+
+### Usage
+
+```python
+usage = client.usage.get(from_date="2026-06-01", to_date="2026-06-30")
+print(usage["total_cost_usd"], usage["calls"])
+```
+
+### Anthropic Messages
+
+```python
+response = client.anthropic.messages_create(
+    model="anthropic/claude-sonnet-4-6",
+    max_tokens=400,
+    system="You are an EU compliance assistant.",
+    messages=[{"role": "user", "content": "What is GDPR Article 32?"}],
+)
+print(response["content"][0]["text"])
+```
+
+## Error handling
+
+The SDK maps HTTP status codes to typed exceptions. Catch the specific class:
+
+```python
+from ciralgo import Client
+from ciralgo.errors import RateLimitError, UpstreamError, AuthenticationError
+
+try:
+    response = client.chat.completions.create(...)
+except RateLimitError as e:
+    time.sleep(e.retry_after or 5)
+    # retry
+except UpstreamError as e:
+    # upstream LLM provider 5xx, pick a different model
+    ...
+except AuthenticationError:
+    # rotate / re-issue the key
+    raise
+```
+
+Every exception carries:
+
+- `code`: stable string error code from the API envelope (e.g. `rate_limit_exceeded`)
+- `message`: human-readable
+- `trace_id`: pass this to Ciralgo support to look up the request server-side
+- `status_code`: HTTP status
+- `retry_after`: only set on 429
+
+## Async
+
+```python
+import asyncio
+from ciralgo import AsyncClient
+
+async def main():
+    async with AsyncClient() as client:
+        # NOTE: async surface in v1.1.0 is the client construction +
+        # close lifecycle. Full async parity for chat / embeddings ships
+        # in v1.2.0.
+        pass
+
+asyncio.run(main())
+```
+
+## Migration to a codegen client
+
+The current client is hand-written. A codegen-based replacement is
+viable using [openapi-python-client](https://github.com/openapi-generators/openapi-python-client)
+against the published Ciralgo OpenAPI spec. The hand-written client
+gives us control over:
+
+- Streaming semantics (`stream=True` returning an iterator).
+- The `X-Ciralgo-Tags` header marshalling.
+- The typed exception hierarchy (codegen produces a single error class).
+
+A future major bump (`v2.0.0`) can switch to codegen if the trade-offs
+change.
+
+## Development
+
+From the SDK repo root:
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src
+mypy src
+```
+
+## Publishing
+
+Publishing to PyPI is handled by a GitHub Actions workflow triggered on
+tags of the form `sdk-py-v*`. The workflow uses PyPI Trusted Publishing
+(OIDC). No long-lived API token is stored in CI secrets.
+
+The engineer-facing release runbook (version bump, tag push, environment
+approval, troubleshooting) is at [docs/publish-runbook.md](docs/publish-runbook.md).
+
+## License
+
+Apache-2.0

ciralgo-1.1.0/README.md

@@ -0,0 +1,181 @@
+# Ciralgo Python SDK
+
+Official Python SDK for the [Ciralgo Platform API](https://www.ciralgo.com).
+
+Version: `1.1.0` (mirrors `openapi.json info.version`).
+
+## Install
+
+```bash
+pip install ciralgo
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+from ciralgo import Client
+
+client = Client(api_key="sk-cg-...")  # or set CIRALGO_API_KEY in your env
+
+response = client.chat.completions.create(
+    model="openai/gpt-4o-mini",
+    messages=[{"role": "user", "content": "Say hello."}],
+)
+print(response["choices"][0]["message"]["content"])
+```
+
+## Authentication
+
+The SDK reads the API key from (in order):
+
+1. The `api_key=` argument to `Client(...)` or `AsyncClient(...)`.
+2. The `CIRALGO_API_KEY` environment variable.
+
+If neither is set, `AuthenticationError` is raised at construction time.
+
+The optional `CIRALGO_BASE_URL` env var overrides the default `https://api.ciralgo.com`. This is useful for staging or for self-hosted Ciralgo deployments.
+
+## Endpoints
+
+The four public proxy operations from the Ciralgo OpenAPI spec (v1.1.0):
+
+### Chat completions
+
+```python
+response = client.chat.completions.create(
+    model="anthropic/claude-sonnet-4-6",
+    messages=[
+        {"role": "system", "content": "You are a finance compliance assistant."},
+        {"role": "user", "content": "Summarise EU AI Act Article 15."},
+    ],
+    temperature=0.2,
+    max_tokens=400,
+    tags={"project": "ai-act-summariser", "env": "prod"},
+)
+```
+
+### Streaming chat completions
+
+```python
+for chunk in client.chat.completions.create(
+    model="openai/gpt-4o-mini",
+    messages=[{"role": "user", "content": "Stream me a haiku."}],
+    stream=True,
+):
+    delta = chunk["choices"][0]["delta"].get("content", "")
+    print(delta, end="", flush=True)
+```
+
+### Embeddings
+
+```python
+embedding = client.embeddings.create(
+    model="openai/text-embedding-3-small",
+    input="EU AI Act Article 15 covers accuracy, robustness and cybersecurity.",
+)
+print(len(embedding["data"][0]["embedding"]))  # → vector dimension
+```
+
+### Usage
+
+```python
+usage = client.usage.get(from_date="2026-06-01", to_date="2026-06-30")
+print(usage["total_cost_usd"], usage["calls"])
+```
+
+### Anthropic Messages
+
+```python
+response = client.anthropic.messages_create(
+    model="anthropic/claude-sonnet-4-6",
+    max_tokens=400,
+    system="You are an EU compliance assistant.",
+    messages=[{"role": "user", "content": "What is GDPR Article 32?"}],
+)
+print(response["content"][0]["text"])
+```
+
+## Error handling
+
+The SDK maps HTTP status codes to typed exceptions. Catch the specific class:
+
+```python
+from ciralgo import Client
+from ciralgo.errors import RateLimitError, UpstreamError, AuthenticationError
+
+try:
+    response = client.chat.completions.create(...)
+except RateLimitError as e:
+    time.sleep(e.retry_after or 5)
+    # retry
+except UpstreamError as e:
+    # upstream LLM provider 5xx, pick a different model
+    ...
+except AuthenticationError:
+    # rotate / re-issue the key
+    raise
+```
+
+Every exception carries:
+
+- `code`: stable string error code from the API envelope (e.g. `rate_limit_exceeded`)
+- `message`: human-readable
+- `trace_id`: pass this to Ciralgo support to look up the request server-side
+- `status_code`: HTTP status
+- `retry_after`: only set on 429
+
+## Async
+
+```python
+import asyncio
+from ciralgo import AsyncClient
+
+async def main():
+    async with AsyncClient() as client:
+        # NOTE: async surface in v1.1.0 is the client construction +
+        # close lifecycle. Full async parity for chat / embeddings ships
+        # in v1.2.0.
+        pass
+
+asyncio.run(main())
+```
+
+## Migration to a codegen client
+
+The current client is hand-written. A codegen-based replacement is
+viable using [openapi-python-client](https://github.com/openapi-generators/openapi-python-client)
+against the published Ciralgo OpenAPI spec. The hand-written client
+gives us control over:
+
+- Streaming semantics (`stream=True` returning an iterator).
+- The `X-Ciralgo-Tags` header marshalling.
+- The typed exception hierarchy (codegen produces a single error class).
+
+A future major bump (`v2.0.0`) can switch to codegen if the trade-offs
+change.
+
+## Development
+
+From the SDK repo root:
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src
+mypy src
+```
+
+## Publishing
+
+Publishing to PyPI is handled by a GitHub Actions workflow triggered on
+tags of the form `sdk-py-v*`. The workflow uses PyPI Trusted Publishing
+(OIDC). No long-lived API token is stored in CI secrets.
+
+The engineer-facing release runbook (version bump, tag push, environment
+approval, troubleshooting) is at [docs/publish-runbook.md](docs/publish-runbook.md).
+
+## License
+
+Apache-2.0

ciralgo-1.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ciralgo"
+version = "1.1.0"  # mirrors openapi.json info.version
+description = "Official Python SDK for the Ciralgo Platform API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+authors = [
+    { name = "Ciralgo", email = "support@ciralgo.com" }
+]
+keywords = [
+    "ciralgo",
+    "openai",
+    "anthropic",
+    "llm",
+    "ai",
+    "compliance",
+    "eu-sovereignty"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    # httpx is the standard async-first HTTP client for Python SDKs in
+    # 2026. Mature, sync + async surfaces, types built in. We pin a wide
+    # range to be a polite dep. Customers may already have httpx pinned
+    # tighter in their own apps.
+    "httpx>=0.27,<1.0",
+    # typing-extensions for Python 3.9 / 3.10 to handle older TypedDict,
+    # Required, NotRequired that 3.11+ ships natively.
+    "typing-extensions>=4.5; python_version < '3.11'"
+]
+
+[project.urls]
+Homepage = "https://www.ciralgo.com"
+Documentation = "https://docs.ciralgo.com/sdk-python"
+Repository = "https://github.com/Ciralgo/ciralgo-python"
+Changelog = "https://github.com/Ciralgo/ciralgo-python/blob/main/CHANGELOG.md"
+Issues = "https://github.com/Ciralgo/ciralgo-python/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",  # httpx mocking, no live network in unit tests
+    "mypy>=1.10",
+    "ruff>=0.5",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ciralgo"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/ciralgo",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

ciralgo-1.1.0/src/ciralgo/__init__.py

@@ -0,0 +1,49 @@
+"""Official Python SDK for the Ciralgo Platform API.
+
+Quick start:
+
+    from ciralgo import Client
+
+    client = Client(api_key="sk-cg-...")
+    response = client.chat.completions.create(
+        model="openai/gpt-4o-mini",
+        messages=[{"role": "user", "content": "Hello!"}],
+    )
+    print(response["choices"][0]["message"]["content"])
+
+The SDK is a thin, typed wrapper over the public proxy surface documented
+at https://docs.ciralgo.com. Same authentication, same error envelope.
+See the examples/ directory for chat, embeddings, usage, and Anthropic
+Messages examples.
+
+The package version mirrors `openapi.json info.version`. Bumping the API
+spec triggers a coordinated SDK release.
+"""
+
+from ciralgo.client import Client, AsyncClient
+from ciralgo.errors import (
+    CiralgoError,
+    AuthenticationError,
+    PermissionError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+    UpstreamError,
+    InternalError,
+)
+
+__version__ = "1.1.0"
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "CiralgoError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    "UpstreamError",
+    "InternalError",
+    "__version__",
+]

ciralgo-1.1.0/src/ciralgo/client.py

@@ -0,0 +1,374 @@
+"""Client implementation for the Ciralgo Platform API.
+
+This file ships hand-written wrappers over the four public proxy
+operations documented in the Ciralgo OpenAPI spec v1.1.0:
+
+    POST  /v1/chat/completions
+    POST  /v1/embeddings
+    GET   /v1/usage
+    POST  /anthropic/v1/messages
+
+A codegen approach using `openapi-python-client` is a viable replacement
+that produces fully typed dataclasses from the spec; the README documents
+the migration path. The hand-written client gives us full control over
+streaming semantics, error mapping, and retries without taking the
+codegen toolchain as a hard dependency for every release.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Iterator, List, Optional, Union
+
+import httpx
+
+from ciralgo.errors import (
+    AuthenticationError,
+    CiralgoError,
+    InternalError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    UpstreamError,
+    ValidationError,
+)
+
+DEFAULT_BASE_URL = "https://api.ciralgo.com"
+DEFAULT_TIMEOUT_SEC = 120
+USER_AGENT = "ciralgo-python/1.1.0"
+
+
+class _ChatCompletions:
+    """Sub-resource for /v1/chat/completions.
+
+    Accessed via `client.chat.completions.create(...)`.
+    """
+
+    def __init__(self, client: "Client") -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        model: str,
+        messages: List[Dict[str, Any]],
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        stream: bool = False,
+        stream_options: Optional[Dict[str, Any]] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+        tool_choice: Optional[Union[str, Dict[str, Any]]] = None,
+        response_format: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+        tags: Optional[Dict[str, str]] = None,
+    ) -> Union[Dict[str, Any], Iterator[Dict[str, Any]]]:
+        """Create a chat completion.
+
+        Returns the JSON dict when stream=False. When stream=True, returns
+        an iterator yielding the SSE chunks as decoded dicts. The final
+        `data: [DONE]` sentinel is consumed by the iterator and ends it.
+        """
+        body: Dict[str, Any] = {"model": model, "messages": messages}
+        if temperature is not None:
+            body["temperature"] = temperature
+        if max_tokens is not None:
+            body["max_tokens"] = max_tokens
+        if stream:
+            body["stream"] = True
+            if stream_options is not None:
+                body["stream_options"] = stream_options
+        if tools is not None:
+            body["tools"] = tools
+        if tool_choice is not None:
+            body["tool_choice"] = tool_choice
+        if response_format is not None:
+            body["response_format"] = response_format
+
+        headers: Dict[str, str] = {}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        if tags:
+            headers["X-Ciralgo-Tags"] = ",".join(f"{k}={v}" for k, v in tags.items())
+
+        if stream:
+            return self._client._stream("POST", "/v1/chat/completions", body, headers)
+        return self._client._request("POST", "/v1/chat/completions", body, headers)
+
+
+class _Embeddings:
+    """Sub-resource for /v1/embeddings."""
+
+    def __init__(self, client: "Client") -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        model: str,
+        input: Union[str, List[str]],
+        encoding_format: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"model": model, "input": input}
+        if encoding_format is not None:
+            body["encoding_format"] = encoding_format
+        return self._client._request("POST", "/v1/embeddings", body)
+
+
+class _Usage:
+    """Sub-resource for /v1/usage."""
+
+    def __init__(self, client: "Client") -> None:
+        self._client = client
+
+    def get(
+        self,
+        *,
+        from_date: Optional[str] = None,
+        to_date: Optional[str] = None,
+        group_by: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params: Dict[str, str] = {}
+        if from_date:
+            params["from"] = from_date
+        if to_date:
+            params["to"] = to_date
+        if group_by:
+            params["group_by"] = group_by
+        return self._client._request("GET", "/v1/usage", params=params)
+
+
+class _Anthropic:
+    """Sub-resource for /anthropic/v1/messages."""
+
+    def __init__(self, client: "Client") -> None:
+        self._client = client
+
+    def messages_create(
+        self,
+        *,
+        model: str,
+        messages: List[Dict[str, Any]],
+        max_tokens: int,
+        system: Optional[str] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+        stream: bool = False,
+    ) -> Union[Dict[str, Any], Iterator[Dict[str, Any]]]:
+        body: Dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "max_tokens": max_tokens,
+        }
+        if system is not None:
+            body["system"] = system
+        if tools is not None:
+            body["tools"] = tools
+        if stream:
+            body["stream"] = True
+            return self._client._stream("POST", "/anthropic/v1/messages", body)
+        return self._client._request("POST", "/anthropic/v1/messages", body)
+
+
+class _ChatNamespace:
+    """`client.chat.completions.create(...)` plumbing."""
+
+    def __init__(self, client: "Client") -> None:
+        self.completions = _ChatCompletions(client)
+
+
+class Client:
+    """Synchronous Ciralgo client.
+
+    Usage:
+
+        from ciralgo import Client
+        client = Client(api_key="sk-cg-...")
+        r = client.chat.completions.create(
+            model="openai/gpt-4o-mini",
+            messages=[{"role": "user", "content": "Hello"}],
+        )
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT_SEC,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("CIRALGO_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError(
+                code="missing_api_key",
+                message=(
+                    "No API key found. Pass api_key=... or set CIRALGO_API_KEY in the environment."
+                ),
+            )
+        self.base_url = (base_url or os.environ.get("CIRALGO_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._http = httpx.Client(timeout=timeout, headers=self._default_headers())
+        self.chat = _ChatNamespace(self)
+        self.embeddings = _Embeddings(self)
+        self.usage = _Usage(self)
+        self.anthropic = _Anthropic(self)
+
+    # Sentinel close method for `with Client(...) as client:` patterns.
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _default_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": USER_AGENT,
+            "Accept": "application/json",
+        }
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json_body: Optional[Dict[str, Any]] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        try:
+            resp = self._http.request(
+                method,
+                url,
+                json=json_body,
+                params=params,
+                headers=extra_headers or None,
+            )
+        except httpx.TimeoutException as e:
+            raise UpstreamError(
+                code="upstream_timeout",
+                message=f"Request timed out: {e}",
+            ) from e
+        return self._handle(resp)
+
+    def _stream(
+        self,
+        method: str,
+        path: str,
+        json_body: Dict[str, Any],
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Iterator[Dict[str, Any]]:
+        """Stream SSE chunks from /v1/chat/completions or /anthropic/v1/messages.
+
+        Yields decoded JSON chunks. Consumes and discards the `[DONE]`
+        sentinel so the iterator ends naturally.
+        """
+        import json as _json
+
+        url = f"{self.base_url}{path}"
+        headers = dict(self._default_headers())
+        headers["Accept"] = "text/event-stream"
+        if extra_headers:
+            headers.update(extra_headers)
+
+        with self._http.stream(method, url, json=json_body, headers=headers) as resp:
+            if resp.status_code >= 400:
+                # Read the body, route through _handle for a typed error.
+                body = resp.read()
+                resp_for_handle = httpx.Response(
+                    status_code=resp.status_code,
+                    headers=resp.headers,
+                    content=body,
+                )
+                self._handle(resp_for_handle)
+                return  # _handle always raises
+
+            for line in resp.iter_lines():
+                if not line.startswith("data:"):
+                    continue
+                payload = line[len("data:"):].strip()
+                if payload == "[DONE]":
+                    return
+                if not payload:
+                    continue
+                try:
+                    yield _json.loads(payload)
+                except Exception:
+                    # Skip malformed chunks rather than crash the stream.
+                    continue
+
+    def _handle(self, resp: httpx.Response) -> Dict[str, Any]:
+        """Map a finished httpx.Response to a body dict or a typed exception."""
+        if 200 <= resp.status_code < 300:
+            if not resp.content:
+                return {}
+            return resp.json()
+
+        # Error path. Pull what we can from the standard envelope.
+        try:
+            body = resp.json()
+        except Exception:
+            body = {}
+
+        err_obj = body.get("error") if isinstance(body, dict) else None
+        code = (err_obj or {}).get("code", "unknown_error")
+        message = (err_obj or {}).get("message", f"HTTP {resp.status_code}")
+        trace_id = (err_obj or {}).get("trace_id") or resp.headers.get("X-Trace-Id")
+        retry_after_raw = (err_obj or {}).get("retry_after") or resp.headers.get("Retry-After")
+        try:
+            retry_after = int(retry_after_raw) if retry_after_raw is not None else None
+        except (TypeError, ValueError):
+            retry_after = None
+
+        kwargs = dict(code=code, message=message, trace_id=trace_id, status_code=resp.status_code, retry_after=retry_after)
+        if resp.status_code == 400:
+            raise ValidationError(**kwargs)
+        if resp.status_code == 401:
+            raise AuthenticationError(**kwargs)
+        if resp.status_code == 403:
+            raise PermissionError(**kwargs)
+        if resp.status_code == 404:
+            raise NotFoundError(**kwargs)
+        if resp.status_code == 429:
+            raise RateLimitError(**kwargs)
+        if resp.status_code == 502:
+            raise UpstreamError(**kwargs)
+        if resp.status_code >= 500:
+            raise InternalError(**kwargs)
+        raise CiralgoError(**kwargs)
+
+
+class AsyncClient:
+    """Async sibling of Client. Same surface, async methods.
+
+    Intentionally minimal in v1.1.0. Covers the same four operations. A
+    follow-up release adds parity for streaming + retries.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT_SEC,
+    ) -> None:
+        # Reuse the sync client's auth + URL resolution by constructing a
+        # bare Client and copying its attributes. Avoids duplicating the
+        # config logic until the async surface diverges.
+        sync = Client(api_key=api_key, base_url=base_url, timeout=timeout)
+        sync.close()
+        self.api_key = sync.api_key
+        self.base_url = sync.base_url
+        self._http = httpx.AsyncClient(
+            timeout=timeout,
+            headers=sync._default_headers(),
+        )
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()

ciralgo-1.1.0/src/ciralgo/errors.py

@@ -0,0 +1,86 @@
+"""Typed error hierarchy mirroring the OpenAPI ErrorResponse envelope.
+
+Every API error from Ciralgo carries the shape:
+
+    {
+      "ok": false,
+      "error": {
+        "code": "<stable_code>",
+        "message": "<human readable>",
+        "trace_id": "<request id>",
+        "retry_after": <seconds, only on 429>
+      }
+    }
+
+The client maps HTTP status codes to one of these exception classes so
+customer code can catch the specific class rather than parsing the
+envelope by hand:
+
+    try:
+        client.chat.completions.create(...)
+    except RateLimitError as e:
+        time.sleep(e.retry_after or 5)
+        # retry
+    except UpstreamError as e:
+        # upstream LLM provider returned 5xx, try a different model
+        ...
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class CiralgoError(Exception):
+    """Base class for every Ciralgo SDK error.
+
+    Carries the API-level error code, the human message, the trace_id for
+    support correlation, and the raw HTTP status code.
+    """
+
+    def __init__(
+        self,
+        *,
+        code: str,
+        message: str,
+        trace_id: Optional[str] = None,
+        status_code: Optional[int] = None,
+        retry_after: Optional[int] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.trace_id = trace_id
+        self.status_code = status_code
+        self.retry_after = retry_after
+
+
+class ValidationError(CiralgoError):
+    """4xx: request shape rejected by the server (400)."""
+
+
+class AuthenticationError(CiralgoError):
+    """401: invalid or missing API key."""
+
+
+class PermissionError(CiralgoError):
+    """403: caller does not have permission (tenant policy, admin MFA, etc.)."""
+
+
+class NotFoundError(CiralgoError):
+    """404: resource does not exist or is not visible to this caller."""
+
+
+class RateLimitError(CiralgoError):
+    """429: per-key / per-org RPM or TPM limit exceeded.
+
+    The `retry_after` attribute is set when the server provided one.
+    """
+
+
+class UpstreamError(CiralgoError):
+    """502: upstream LLM provider returned an error or timed out."""
+
+
+class InternalError(CiralgoError):
+    """5xx: unexpected server-side error. Retry with exponential backoff."""