caetherai 0.1.0__tar.gz

caetherai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CaetherAI
+
+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.

caetherai-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: caetherai
+Version: 0.1.0
+Summary: Official Python SDK for the CaetherAI API
+Project-URL: Homepage, https://caether.ai
+Project-URL: Documentation, https://docs.caether.ai
+Author: CaetherAI
+License: MIT
+License-File: LICENSE
+Keywords: ai,api,caether,caetherai,llm,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CaetherAI Python SDK
+
+Official Python SDK for the [CaetherAI](https://caether.ai) API. Synchronous and asynchronous
+clients with a unified interface across products.
+
+## Installation
+
+```bash
+pip install caetherai
+```
+
+## Quickstart
+
+```python
+import os
+from caetherai import Client
+from caetherai.chat import user, system
+
+client = Client(api_key=os.getenv("CAETHER_API_KEY"))
+
+chat = client.chat.create(model="caether-1.1")
+chat.append(system("You are Caether, an AI agent built to answer helpful questions."))
+chat.append(user("How big is the universe?"))
+response = chat.sample()
+
+print(response)
+print(response.id)
+```
+
+See [docs.caether.ai](https://docs.caether.ai) for full documentation.

caetherai-0.1.0/README.md

@@ -0,0 +1,30 @@
+# CaetherAI Python SDK
+
+Official Python SDK for the [CaetherAI](https://caether.ai) API. Synchronous and asynchronous
+clients with a unified interface across products.
+
+## Installation
+
+```bash
+pip install caetherai
+```
+
+## Quickstart
+
+```python
+import os
+from caetherai import Client
+from caetherai.chat import user, system
+
+client = Client(api_key=os.getenv("CAETHER_API_KEY"))
+
+chat = client.chat.create(model="caether-1.1")
+chat.append(system("You are Caether, an AI agent built to answer helpful questions."))
+chat.append(user("How big is the universe?"))
+response = chat.sample()
+
+print(response)
+print(response.id)
+```
+
+See [docs.caether.ai](https://docs.caether.ai) for full documentation.

caetherai-0.1.0/caetherai/__init__.py

@@ -0,0 +1,35 @@
+from ._client import AsyncClient, Client
+from ._constants import DEFAULT_BASE_URL, SDK_VERSION
+from ._errors import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    CaetherError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnprocessableEntityError,
+)
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "DEFAULT_BASE_URL",
+    "CaetherError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "RateLimitError",
+    "BadRequestError",
+    "UnprocessableEntityError",
+    "InternalServerError",
+    "__version__",
+]

caetherai-0.1.0/caetherai/_client.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import os
+from typing import Mapping, Optional
+
+import httpx
+
+from ._constants import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT
+from ._errors import CaetherError
+from ._transport import AsyncTransport, SyncTransport
+from .chat import AsyncChatClient, ChatClient
+
+
+def _resolve_api_key(api_key: Optional[str]) -> str:
+    key = api_key or os.getenv("CAETHER_API_KEY")
+    if not key:
+        raise CaetherError(
+            "No API key provided. Pass api_key=... or set the CAETHER_API_KEY environment variable."
+        )
+    return key
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self.api_key = _resolve_api_key(api_key)
+        self.base_url = (base_url or os.getenv("CAETHER_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._transport = SyncTransport(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+            http_client=http_client,
+        )
+        self.chat = ChatClient(self._transport, path="/chat/completions")
+        self.code = ChatClient(self._transport, path="/code/stream")
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self.api_key = _resolve_api_key(api_key)
+        self.base_url = (base_url or os.getenv("CAETHER_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._transport = AsyncTransport(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+            http_client=http_client,
+        )
+        self.chat = AsyncChatClient(self._transport, path="/chat/completions")
+        self.code = AsyncChatClient(self._transport, path="/code/stream")
+
+    async def close(self) -> None:
+        await self._transport.close()
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()

caetherai-0.1.0/caetherai/_constants.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+DEFAULT_API_HOST = "api.caether.ai"
+DEFAULT_BASE_URL = f"https://{DEFAULT_API_HOST}"
+
+DEFAULT_TIMEOUT = 3600.0
+DEFAULT_MAX_RETRIES = 2
+
+USER_AGENT = "caetherai-python"
+SDK_VERSION = "0.1.0"

caetherai-0.1.0/caetherai/_errors.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+
+class CaetherError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+        body: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.body = body
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.code:
+            parts.append(f"code={self.code}")
+        if self.status_code is not None:
+            parts.append(f"status={self.status_code}")
+        return " ".join(parts) if len(parts) == 1 else f"{self.message} ({', '.join(parts[1:])})"
+
+
+class APIConnectionError(CaetherError):
+    pass
+
+
+class APITimeoutError(APIConnectionError):
+    pass
+
+
+class APIStatusError(CaetherError):
+    pass
+
+
+class AuthenticationError(APIStatusError):
+    pass
+
+
+class PermissionDeniedError(APIStatusError):
+    pass
+
+
+class NotFoundError(APIStatusError):
+    pass
+
+
+class RateLimitError(APIStatusError):
+    pass
+
+
+class BadRequestError(APIStatusError):
+    pass
+
+
+class UnprocessableEntityError(APIStatusError):
+    pass
+
+
+class InternalServerError(APIStatusError):
+    pass
+
+
+_STATUS_TO_ERROR = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+}
+
+
+def error_from_response(status_code: int, body: Any) -> APIStatusError:
+    message = f"HTTP {status_code}"
+    code: Optional[str] = None
+    if isinstance(body, Mapping):
+        err = body.get("error")
+        if isinstance(err, Mapping):
+            message = err.get("message") or message
+            code = err.get("code")
+        elif isinstance(err, str):
+            message = err
+        elif isinstance(body.get("message"), str):
+            message = body["message"]
+
+    if status_code in _STATUS_TO_ERROR:
+        cls = _STATUS_TO_ERROR[status_code]
+    elif status_code >= 500:
+        cls = InternalServerError
+    else:
+        cls = APIStatusError
+
+    return cls(message, status_code=status_code, code=code, body=body)

caetherai-0.1.0/caetherai/_transport.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, AsyncIterator, Dict, Iterator, Mapping, Optional
+
+import httpx
+
+from ._constants import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, SDK_VERSION, USER_AGENT
+from ._errors import (
+    APIConnectionError,
+    APITimeoutError,
+    error_from_response,
+)
+
+_RETRY_STATUS = {408, 409, 429, 500, 502, 503, 504}
+
+
+def _build_headers(api_key: str, extra: Optional[Mapping[str, str]]) -> Dict[str, str]:
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "User-Agent": f"{USER_AGENT}/{SDK_VERSION}",
+    }
+    if extra:
+        headers.update({k: v for k, v in extra.items() if v is not None})
+    return headers
+
+
+def _retry_delay(attempt: int) -> float:
+    return min(0.5 * (2 ** attempt), 8.0)
+
+
+def _parse_body(response: httpx.Response) -> Any:
+    ct = response.headers.get("content-type", "")
+    if "application/json" in ct:
+        try:
+            return response.json()
+        except ValueError:
+            return response.text
+    return response.text
+
+
+def _iter_sse(lines: Iterator[str]) -> Iterator[Dict[str, Any]]:
+    for raw in lines:
+        line = raw.strip()
+        if not line or not line.startswith("data:"):
+            continue
+        data = line[len("data:"):].strip()
+        if data == "[DONE]":
+            return
+        try:
+            yield json.loads(data)
+        except ValueError:
+            continue
+
+
+class SyncTransport:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._max_retries = max_retries
+        self._default_headers = dict(default_headers or {})
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self._owns_client = http_client is None
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}/{path.lstrip('/')}"
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[Any] = None,
+        params: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        files: Optional[Any] = None,
+        data: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        merged = _build_headers(self._api_key, {**self._default_headers, **(headers or {})})
+        if files is not None:
+            merged.pop("Content-Type", None)
+        last_exc: Optional[Exception] = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.request(
+                    method,
+                    self._url(path),
+                    json=json_body if files is None else None,
+                    params=params,
+                    headers=merged,
+                    files=files,
+                    data=data,
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = APITimeoutError("Request timed out")
+                if attempt < self._max_retries:
+                    time.sleep(_retry_delay(attempt))
+                    continue
+                raise last_exc from exc
+            except httpx.HTTPError as exc:
+                last_exc = APIConnectionError(f"Connection error: {exc}")
+                if attempt < self._max_retries:
+                    time.sleep(_retry_delay(attempt))
+                    continue
+                raise last_exc from exc
+
+            if response.status_code in _RETRY_STATUS and attempt < self._max_retries:
+                time.sleep(_retry_delay(attempt))
+                continue
+            if response.status_code >= 400:
+                raise error_from_response(response.status_code, _parse_body(response))
+            return _parse_body(response)
+        raise last_exc or APIConnectionError("Request failed")
+
+    def stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[Any] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Iterator[Dict[str, Any]]:
+        merged = _build_headers(self._api_key, {**self._default_headers, **(headers or {})})
+        merged["Accept"] = "text/event-stream"
+        with self._client.stream(method, self._url(path), json=json_body, headers=merged) as response:
+            if response.status_code >= 400:
+                response.read()
+                raise error_from_response(response.status_code, _parse_body(response))
+            yield from _iter_sse(response.iter_lines())
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+
+class AsyncTransport:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._max_retries = max_retries
+        self._default_headers = dict(default_headers or {})
+        self._client = http_client or httpx.AsyncClient(timeout=timeout)
+        self._owns_client = http_client is None
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}/{path.lstrip('/')}"
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[Any] = None,
+        params: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        files: Optional[Any] = None,
+        data: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        import asyncio
+
+        merged = _build_headers(self._api_key, {**self._default_headers, **(headers or {})})
+        if files is not None:
+            merged.pop("Content-Type", None)
+        last_exc: Optional[Exception] = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method,
+                    self._url(path),
+                    json=json_body if files is None else None,
+                    params=params,
+                    headers=merged,
+                    files=files,
+                    data=data,
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = APITimeoutError("Request timed out")
+                if attempt < self._max_retries:
+                    await asyncio.sleep(_retry_delay(attempt))
+                    continue
+                raise last_exc from exc
+            except httpx.HTTPError as exc:
+                last_exc = APIConnectionError(f"Connection error: {exc}")
+                if attempt < self._max_retries:
+                    await asyncio.sleep(_retry_delay(attempt))
+                    continue
+                raise last_exc from exc
+
+            if response.status_code in _RETRY_STATUS and attempt < self._max_retries:
+                await asyncio.sleep(_retry_delay(attempt))
+                continue
+            if response.status_code >= 400:
+                raise error_from_response(response.status_code, _parse_body(response))
+            return _parse_body(response)
+        raise last_exc or APIConnectionError("Request failed")
+
+    async def stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[Any] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> AsyncIterator[Dict[str, Any]]:
+        merged = _build_headers(self._api_key, {**self._default_headers, **(headers or {})})
+        merged["Accept"] = "text/event-stream"
+        async with self._client.stream(method, self._url(path), json=json_body, headers=merged) as response:
+            if response.status_code >= 400:
+                await response.aread()
+                raise error_from_response(response.status_code, _parse_body(response))
+            async for raw in response.aiter_lines():
+                line = raw.strip()
+                if not line or not line.startswith("data:"):
+                    continue
+                payload = line[len("data:"):].strip()
+                if payload == "[DONE]":
+                    return
+                try:
+                    yield json.loads(payload)
+                except ValueError:
+                    continue
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()

caetherai-0.1.0/caetherai/aio/__init__.py

@@ -0,0 +1,3 @@
+from .._client import AsyncClient
+
+__all__ = ["AsyncClient"]

caetherai-0.1.0/caetherai/chat/__init__.py

@@ -0,0 +1,23 @@
+from ._async_chat import AsyncChat, AsyncChatClient
+from ._chat import Chat, ChatClient
+from ._content import assistant, file, image, system, text, tool_result, user, video
+from ._types import FunctionCall, Response, ResponseChunk, Usage
+
+__all__ = [
+    "Chat",
+    "ChatClient",
+    "AsyncChat",
+    "AsyncChatClient",
+    "Response",
+    "ResponseChunk",
+    "Usage",
+    "FunctionCall",
+    "system",
+    "user",
+    "assistant",
+    "text",
+    "image",
+    "video",
+    "file",
+    "tool_result",
+]

caetherai-0.1.0/caetherai/chat/_async_chat.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Dict, List, Mapping, Optional, Tuple, Union
+
+from .._transport import AsyncTransport
+from ._types import Response, ResponseChunk
+
+Message = Dict[str, Any]
+
+
+class AsyncChat:
+    def __init__(
+        self,
+        transport: AsyncTransport,
+        *,
+        model: str,
+        path: str,
+        store_messages: bool = True,
+        previous_response_id: Optional[str] = None,
+        use_encrypted_content: bool = False,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+        max_output_tokens: Optional[int] = None,
+        reasoning_effort: Optional[str] = None,
+        tools: Optional[List[Any]] = None,
+        tool_choice: Optional[Any] = None,
+        extra_body: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        self._transport = transport
+        self._path = path
+        self.model = model
+        self.store_messages = store_messages
+        self.previous_response_id = previous_response_id
+        self.use_encrypted_content = use_encrypted_content
+        self.temperature = temperature
+        self.top_p = top_p
+        self.max_output_tokens = max_output_tokens
+        self.reasoning_effort = reasoning_effort
+        self.tools = tools
+        self.tool_choice = tool_choice
+        self.extra_body = dict(extra_body or {})
+        self.messages: List[Message] = []
+
+    def append(self, message: Union[Message, Response]) -> "AsyncChat":
+        if isinstance(message, Response):
+            self.previous_response_id = message.id or self.previous_response_id
+            for item in message.output:
+                self.messages.append(item)
+        else:
+            self.messages.append(message)
+        return self
+
+    def _build_body(self, stream: bool) -> Dict[str, Any]:
+        body: Dict[str, Any] = {
+            "model": self.model,
+            "messages": self.messages,
+            "stream": stream,
+            "store": self.store_messages,
+        }
+        if self.previous_response_id is not None:
+            body["previous_response_id"] = self.previous_response_id
+        if self.temperature is not None:
+            body["temperature"] = self.temperature
+        if self.top_p is not None:
+            body["top_p"] = self.top_p
+        if self.max_output_tokens is not None:
+            body["max_output_tokens"] = self.max_output_tokens
+        if self.reasoning_effort is not None:
+            body["reasoning_effort"] = self.reasoning_effort
+        if self.tools is not None:
+            body["tools"] = self.tools
+        if self.tool_choice is not None:
+            body["tool_choice"] = self.tool_choice
+        if self.use_encrypted_content:
+            body["include"] = ["reasoning.encrypted_content"]
+        body.update(self.extra_body)
+        return body
+
+    async def sample(self) -> Response:
+        data = await self._transport.request("POST", self._path, json_body=self._build_body(stream=False))
+        response = Response.from_dict(data)
+        if response.id:
+            self.previous_response_id = response.id
+        return response
+
+    def stream(self) -> Tuple[Response, AsyncIterator[ResponseChunk]]:
+        accumulator = Response(
+            id=None, model=self.model, content="", reasoning_content=None,
+            output=[], function_calls=[], usage=None, raw={},  # type: ignore[arg-type]
+        )
+        body = self._build_body(stream=True)
+        transport = self._transport
+        path = self._path
+
+        async def _generator() -> AsyncIterator[ResponseChunk]:
+            content_parts: List[str] = []
+            reasoning_parts: List[str] = []
+            async for event in transport.stream("POST", path, json_body=body):
+                chunk = ResponseChunk.from_event(event)
+                if chunk.content:
+                    content_parts.append(chunk.content)
+                    accumulator.content = "".join(content_parts)
+                if chunk.reasoning_content:
+                    reasoning_parts.append(chunk.reasoning_content)
+                    accumulator.reasoning_content = "".join(reasoning_parts)
+                if chunk.usage is not None:
+                    accumulator.usage = chunk.usage
+                if chunk.function_call is not None:
+                    accumulator.function_calls.append(chunk.function_call)
+                yield chunk
+
+        return accumulator, _generator()
+
+
+class AsyncChatClient:
+    def __init__(self, transport: AsyncTransport, *, path: str = "/chat/completions") -> None:
+        self._transport = transport
+        self._path = path
+
+    def create(
+        self,
+        *,
+        model: str,
+        store_messages: bool = True,
+        previous_response_id: Optional[str] = None,
+        use_encrypted_content: bool = False,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+        max_output_tokens: Optional[int] = None,
+        reasoning_effort: Optional[str] = None,
+        tools: Optional[List[Any]] = None,
+        tool_choice: Optional[Any] = None,
+        **extra_body: Any,
+    ) -> AsyncChat:
+        return AsyncChat(
+            self._transport,
+            model=model,
+            path=self._path,
+            store_messages=store_messages,
+            previous_response_id=previous_response_id,
+            use_encrypted_content=use_encrypted_content,
+            temperature=temperature,
+            top_p=top_p,
+            max_output_tokens=max_output_tokens,
+            reasoning_effort=reasoning_effort,
+            tools=tools,
+            tool_choice=tool_choice,
+            extra_body=extra_body or None,
+        )
+
+    async def get_stored_completion(self, response_id: str) -> Response:
+        data = await self._transport.request("GET", f"{self._path}/{response_id}")
+        return Response.from_dict(data)
+
+    async def delete_stored_completion(self, response_id: str) -> Dict[str, Any]:
+        return await self._transport.request("DELETE", f"{self._path}/{response_id}")

caetherai-0.1.0/caetherai/chat/_chat.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Iterator, List, Mapping, Optional, Tuple, Union
+
+from .._transport import SyncTransport
+from ._types import Response, ResponseChunk, _extract_output_text
+
+Message = Dict[str, Any]
+
+
+class Chat:
+    def __init__(
+        self,
+        transport: SyncTransport,
+        *,
+        model: str,
+        path: str,
+        store_messages: bool = True,
+        previous_response_id: Optional[str] = None,
+        use_encrypted_content: bool = False,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+        max_output_tokens: Optional[int] = None,
+        reasoning_effort: Optional[str] = None,
+        tools: Optional[List[Any]] = None,
+        tool_choice: Optional[Any] = None,
+        extra_body: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        self._transport = transport
+        self._path = path
+        self.model = model
+        self.store_messages = store_messages
+        self.previous_response_id = previous_response_id
+        self.use_encrypted_content = use_encrypted_content
+        self.temperature = temperature
+        self.top_p = top_p
+        self.max_output_tokens = max_output_tokens
+        self.reasoning_effort = reasoning_effort
+        self.tools = tools
+        self.tool_choice = tool_choice
+        self.extra_body = dict(extra_body or {})
+        self.messages: List[Message] = []
+
+    def append(self, message: Union[Message, Response]) -> "Chat":
+        if isinstance(message, Response):
+            self.previous_response_id = message.id or self.previous_response_id
+            for item in message.output:
+                self.messages.append(item)
+        else:
+            self.messages.append(message)
+        return self
+
+    def _build_body(self, stream: bool) -> Dict[str, Any]:
+        body: Dict[str, Any] = {
+            "model": self.model,
+            "messages": self.messages,
+            "stream": stream,
+            "store": self.store_messages,
+        }
+        if self.previous_response_id is not None:
+            body["previous_response_id"] = self.previous_response_id
+        if self.temperature is not None:
+            body["temperature"] = self.temperature
+        if self.top_p is not None:
+            body["top_p"] = self.top_p
+        if self.max_output_tokens is not None:
+            body["max_output_tokens"] = self.max_output_tokens
+        if self.reasoning_effort is not None:
+            body["reasoning_effort"] = self.reasoning_effort
+        if self.tools is not None:
+            body["tools"] = self.tools
+        if self.tool_choice is not None:
+            body["tool_choice"] = self.tool_choice
+        if self.use_encrypted_content:
+            body["include"] = ["reasoning.encrypted_content"]
+        body.update(self.extra_body)
+        return body
+
+    def sample(self) -> Response:
+        data = self._transport.request("POST", self._path, json_body=self._build_body(stream=False))
+        response = Response.from_dict(data)
+        if response.id:
+            self.previous_response_id = response.id
+        return response
+
+    def stream(self) -> Tuple[Response, Iterator[ResponseChunk]]:
+        accumulator = Response(
+            id=None, model=self.model, content="", reasoning_content=None,
+            output=[], function_calls=[], usage=None, raw={},  # type: ignore[arg-type]
+        )
+        events = self._transport.stream("POST", self._path, json_body=self._build_body(stream=True))
+
+        def _generator() -> Iterator[ResponseChunk]:
+            content_parts: List[str] = []
+            reasoning_parts: List[str] = []
+            for event in events:
+                chunk = ResponseChunk.from_event(event)
+                if chunk.content:
+                    content_parts.append(chunk.content)
+                    accumulator.content = "".join(content_parts)
+                if chunk.reasoning_content:
+                    reasoning_parts.append(chunk.reasoning_content)
+                    accumulator.reasoning_content = "".join(reasoning_parts)
+                if chunk.usage is not None:
+                    accumulator.usage = chunk.usage
+                if chunk.function_call is not None:
+                    accumulator.function_calls.append(chunk.function_call)
+                yield chunk
+
+        return accumulator, _generator()
+
+
+class ChatClient:
+    def __init__(self, transport: SyncTransport, *, path: str = "/chat/completions") -> None:
+        self._transport = transport
+        self._path = path
+
+    def create(
+        self,
+        *,
+        model: str,
+        store_messages: bool = True,
+        previous_response_id: Optional[str] = None,
+        use_encrypted_content: bool = False,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+        max_output_tokens: Optional[int] = None,
+        reasoning_effort: Optional[str] = None,
+        tools: Optional[List[Any]] = None,
+        tool_choice: Optional[Any] = None,
+        **extra_body: Any,
+    ) -> Chat:
+        return Chat(
+            self._transport,
+            model=model,
+            path=self._path,
+            store_messages=store_messages,
+            previous_response_id=previous_response_id,
+            use_encrypted_content=use_encrypted_content,
+            temperature=temperature,
+            top_p=top_p,
+            max_output_tokens=max_output_tokens,
+            reasoning_effort=reasoning_effort,
+            tools=tools,
+            tool_choice=tool_choice,
+            extra_body=extra_body or None,
+        )
+
+    def get_stored_completion(self, response_id: str) -> Response:
+        data = self._transport.request("GET", f"{self._path}/{response_id}")
+        return Response.from_dict(data)
+
+    def delete_stored_completion(self, response_id: str) -> Dict[str, Any]:
+        return self._transport.request("DELETE", f"{self._path}/{response_id}")

caetherai-0.1.0/caetherai/chat/_content.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Union
+
+Content = Union[str, Dict[str, Any]]
+
+
+def text(value: str) -> Dict[str, Any]:
+    return {"type": "text", "text": value}
+
+
+def image(url: str) -> Dict[str, Any]:
+    return {"type": "image", "image": url}
+
+
+def video(url: str) -> Dict[str, Any]:
+    return {"type": "video", "video": url}
+
+
+def file(value: str, name: str | None = None) -> Dict[str, Any]:
+    part: Dict[str, Any] = {"type": "file", "file": value}
+    if name is not None:
+        part["name"] = name
+    return part
+
+
+def _message(role: str, *parts: Content) -> Dict[str, Any]:
+    if len(parts) == 1 and isinstance(parts[0], str):
+        return {"role": role, "content": parts[0]}
+    content = [text(p) if isinstance(p, str) else p for p in parts]
+    return {"role": role, "content": content}
+
+
+def system(*parts: Content) -> Dict[str, Any]:
+    return _message("system", *parts)
+
+
+def user(*parts: Content) -> Dict[str, Any]:
+    return _message("user", *parts)
+
+
+def assistant(*parts: Content) -> Dict[str, Any]:
+    return _message("assistant", *parts)
+
+
+def tool_result(call_id: str, output: str) -> Dict[str, Any]:
+    return {"type": "function_call_output", "call_id": call_id, "output": output}

caetherai-0.1.0/caetherai/chat/_types.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, Optional
+
+Role = str
+
+
+@dataclass
+class Usage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+    cost_in_usd_ticks: Optional[int] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: Optional[Mapping[str, Any]]) -> "Usage":
+        if not data:
+            return cls()
+        return cls(
+            input_tokens=int(data.get("input_tokens", 0) or 0),
+            output_tokens=int(data.get("output_tokens", 0) or 0),
+            total_tokens=int(data.get("total_tokens", 0) or 0),
+            cost_in_usd_ticks=data.get("cost_in_usd_ticks"),
+            raw=dict(data),
+        )
+
+
+@dataclass
+class FunctionCall:
+    name: str
+    arguments: str
+    call_id: Optional[str] = None
+
+
+@dataclass
+class Response:
+    id: Optional[str]
+    model: Optional[str]
+    content: str
+    reasoning_content: Optional[str]
+    output: List[Dict[str, Any]]
+    function_calls: List[FunctionCall]
+    usage: Usage
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "Response":
+        output = list(data.get("output") or [])
+        content = _extract_output_text(output)
+        reasoning = _extract_reasoning(output)
+        fcs = [
+            FunctionCall(name=fc.get("name", ""), arguments=fc.get("arguments", ""), call_id=fc.get("call_id"))
+            for fc in (data.get("function_calls") or [])
+        ]
+        return cls(
+            id=data.get("id"),
+            model=data.get("model"),
+            content=content,
+            reasoning_content=reasoning,
+            output=output,
+            function_calls=fcs,
+            usage=Usage.from_dict(data.get("usage")),
+            raw=dict(data),
+        )
+
+    def __str__(self) -> str:
+        return self.content
+
+
+@dataclass
+class ResponseChunk:
+    content: str = ""
+    reasoning_content: str = ""
+    type: Optional[str] = None
+    status: Optional[str] = None
+    usage: Optional[Usage] = None
+    function_call: Optional[FunctionCall] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_event(cls, event: Mapping[str, Any]) -> "ResponseChunk":
+        chunk = cls(type=event.get("type"), raw=dict(event))
+        if "usage" in event and isinstance(event["usage"], Mapping):
+            chunk.usage = Usage.from_dict(event["usage"])
+        if event.get("type") == "reasoning_delta":
+            chunk.reasoning_content = event.get("content", "") or ""
+        elif event.get("type") == "function_call":
+            chunk.function_call = FunctionCall(
+                name=event.get("name", ""), arguments=event.get("arguments", "")
+            )
+        elif event.get("type") in ("tool_update", "search_status", "search_query", "search_started"):
+            chunk.status = event.get("status")
+        choices = event.get("choices")
+        if isinstance(choices, list) and choices:
+            delta = choices[0].get("delta") or {}
+            chunk.content = delta.get("content", "") or ""
+        return chunk
+
+
+def _extract_output_text(output: List[Mapping[str, Any]]) -> str:
+    parts: List[str] = []
+    for item in output:
+        if item.get("type") == "message":
+            for block in item.get("content") or []:
+                if block.get("type") == "output_text" and block.get("text"):
+                    parts.append(block["text"])
+        elif item.get("type") == "output_text" and item.get("text"):
+            parts.append(item["text"])
+        elif item.get("type") == "text" and item.get("text"):
+            parts.append(item["text"])
+    return "".join(parts)
+
+
+def _extract_reasoning(output: List[Mapping[str, Any]]) -> Optional[str]:
+    for item in output:
+        if item.get("type") == "reasoning":
+            summary = item.get("summary")
+            if isinstance(summary, list):
+                texts = [s.get("text", "") for s in summary if isinstance(s, Mapping)]
+                joined = "".join(texts)
+                if joined:
+                    return joined
+            if item.get("encrypted_content"):
+                return item["encrypted_content"]
+    return None

caetherai-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "caetherai"
+version = "0.1.0"
+description = "Official Python SDK for the CaetherAI API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "CaetherAI" }]
+keywords = ["caether", "caetherai", "ai", "llm", "sdk", "api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21", "respx>=0.20"]
+
+[project.urls]
+Homepage = "https://caether.ai"
+Documentation = "https://docs.caether.ai"
+
+[tool.hatch.build.targets.wheel]
+packages = ["caetherai"]