codai-sdk 0.1.0__tar.gz

codai_sdk-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,33 @@
+name: Bug report
+description: Report a problem with codai-sdk
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: A clear description of the bug and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Smallest code snippet that reproduces the issue. Do NOT include your API key.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: SDK version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.2"
+    validations:
+      required: true

codai_sdk-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,17 @@
+name: Feature request
+description: Suggest an idea for codai-sdk
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do that the SDK doesn't support today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+    validations:
+      required: false

codai_sdk-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

codai_sdk-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## Summary
+
+<!-- What does this change and why? -->
+
+## Checklist
+
+- [ ] No credentials/secrets included
+- [ ] SDK remains dependency-free (stdlib only)
+- [ ] `python -m build` succeeds
+- [ ] CHANGELOG updated (Unreleased)

codai_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write # required for PyPI trusted publishing (OIDC)
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches pyproject version
+        if: github.event_name == 'push'
+        run: |
+          PKG_VERSION="$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")"
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::tag $TAG_VERSION != pyproject $PKG_VERSION"
+            exit 1
+          fi
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Uses PyPI Trusted Publishing (OIDC) — no API token needed once the
+        # trusted publisher is configured on pypi.org for this repo+workflow.

codai_sdk-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.venv/
+.DS_Store
+.pytest_cache/

codai_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to `codai-sdk` are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-23
+
+### Added
+
+- Initial public release.
+- `Codai.chat()` — OpenAI-compatible completions with codai extensions
+  (`session_id`, `agent_mode`, `compact`, `best_of`).
+- `Codai.chat_stream()` — streaming via generator.
+- `Codai.agents_run()` — server-side agent loop.
+- `Codai.feedback()` — thumbs rating on a completed request.
+- `Codai.models()` — list models available to the key.
+- Zero dependencies (stdlib only), Python 3.9+.
+
+[Unreleased]: https://github.com/dragoscv/codai-sdk-python/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dragoscv/codai-sdk-python/releases/tag/v0.1.0

codai_sdk-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Contributor Code of Conduct
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting or derogatory comments, and personal attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers at **conduct@codai.ro**. All complaints will be
+reviewed and investigated promptly and fairly.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

codai_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+Thanks for your interest in `codai-sdk`!
+
+> **Note:** This repository is a published mirror of the SDK developed inside
+> the codai monorepo. Source changes are made upstream and synced here on
+> release. Issues and PRs are welcome and will be triaged upstream.
+
+## Reporting issues
+
+Open an issue with a minimal reproduction, the SDK version, and your Python
+version.
+
+## Pull requests
+
+- Keep changes focused and small.
+- Keep the SDK **dependency-free** (stdlib only).
+- Add or update tests where it makes sense.
+- Do not include any credentials in code, tests, or examples.
+
+## Local development
+
+```bash
+python -m pip install --upgrade build
+python -m build      # produces wheel + sdist in dist/
+```
+
+## Code of Conduct
+
+By participating you agree to abide by the [Code of Conduct](./CODE_OF_CONDUCT.md).

codai_sdk-0.1.0/LICENSE

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

codai_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: codai-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the codai AI gateway — chat, streaming, agents, feedback, models.
+Project-URL: Homepage, https://codai.ro
+Project-URL: Repository, https://github.com/dragoscv/codai-sdk-python
+Project-URL: Issues, https://github.com/dragoscv/codai-sdk-python/issues
+Author-email: codai <support@codai.ro>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,codai,gateway,llm,openai-compatible
+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.9
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# codai-sdk — Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/codai-sdk.svg)](https://pypi.org/project/codai-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/codai-sdk.svg)](https://pypi.org/project/codai-sdk/)
+[![license](https://img.shields.io/pypi/l/codai-sdk.svg)](./LICENSE)
+
+Official Python client for the [codai](https://codai.ro) AI gateway.
+Zero dependencies (stdlib only), Python 3.9+.
+
+```bash
+pip install codai-sdk
+```
+
+> You need a codai API key. Get one at **[codai.ro](https://codai.ro)**.
+> The import name stays `codai`:
+
+```python
+from codai import Codai
+
+client = Codai(api_key="ck-...", session_id="my-project")
+
+# Chat (OpenAI-compatible, smart-routed)
+result = client.chat([{"role": "user", "content": "Explain asyncio.gather"}])
+print(result.content)
+print(result.routed_to)   # which model actually served
+
+# Streaming
+for delta in client.chat_stream([{"role": "user", "content": "hi"}]):
+    print(delta, end="", flush=True)
+
+# Server-side agent loop
+run = client.agents_run("Find and summarize the TODOs in this codebase")
+print(run.result)
+
+# Feedback (improves routing for everyone)
+client.feedback(result.request_id, 1)
+```
+
+## codai extensions
+
+| Option            | Effect                               |
+| ----------------- | ------------------------------------ |
+| `session_id`      | Session memory + routing stickiness  |
+| `agent_mode=True` | Plan-and-execute loop (Pro+)         |
+| `compact="auto"`  | Server-side context compaction       |
+| `best_of=0/3`     | Disable / force best-of-N ensembling |
+
+MIT © codai

codai_sdk-0.1.0/README.md

@@ -0,0 +1,48 @@
+# codai-sdk — Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/codai-sdk.svg)](https://pypi.org/project/codai-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/codai-sdk.svg)](https://pypi.org/project/codai-sdk/)
+[![license](https://img.shields.io/pypi/l/codai-sdk.svg)](./LICENSE)
+
+Official Python client for the [codai](https://codai.ro) AI gateway.
+Zero dependencies (stdlib only), Python 3.9+.
+
+```bash
+pip install codai-sdk
+```
+
+> You need a codai API key. Get one at **[codai.ro](https://codai.ro)**.
+> The import name stays `codai`:
+
+```python
+from codai import Codai
+
+client = Codai(api_key="ck-...", session_id="my-project")
+
+# Chat (OpenAI-compatible, smart-routed)
+result = client.chat([{"role": "user", "content": "Explain asyncio.gather"}])
+print(result.content)
+print(result.routed_to)   # which model actually served
+
+# Streaming
+for delta in client.chat_stream([{"role": "user", "content": "hi"}]):
+    print(delta, end="", flush=True)
+
+# Server-side agent loop
+run = client.agents_run("Find and summarize the TODOs in this codebase")
+print(run.result)
+
+# Feedback (improves routing for everyone)
+client.feedback(result.request_id, 1)
+```
+
+## codai extensions
+
+| Option            | Effect                               |
+| ----------------- | ------------------------------------ |
+| `session_id`      | Session memory + routing stickiness  |
+| `agent_mode=True` | Plan-and-execute loop (Pro+)         |
+| `compact="auto"`  | Server-side context compaction       |
+| `best_of=0/3`     | Disable / force best-of-N ensembling |
+
+MIT © codai

codai_sdk-0.1.0/SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please **do not** open public issues for security vulnerabilities.
+
+Email **security@codai.ro** with details and reproduction steps. We aim to
+acknowledge reports within 72 hours.
+
+## Scope
+
+This repository contains the public client SDK only. It holds no credentials
+and no server-side logic. Never commit your codai API key — load it from an
+environment variable (e.g. `CODAI_API_KEY`).

codai_sdk-0.1.0/examples/agent.py

@@ -0,0 +1,16 @@
+"""Server-side agent run.
+
+    CODAI_API_KEY=sk_... python examples/agent.py
+"""
+import os
+
+from codai import Codai
+
+client = Codai(api_key=os.environ["CODAI_API_KEY"])
+
+run = client.agents_run(
+    "Summarize the following text in 3 bullet points.",
+    context="codai is an OpenAI-compatible AI gateway with smart routing.",
+)
+
+print(run.result)

codai_sdk-0.1.0/examples/chat.py

@@ -0,0 +1,14 @@
+"""Basic chat completion.
+
+    CODAI_API_KEY=sk_... python examples/chat.py
+"""
+import os
+
+from codai import Codai
+
+client = Codai(api_key=os.environ["CODAI_API_KEY"])
+
+result = client.chat([{"role": "user", "content": "Give me one tip for clean Python."}])
+
+print(result.content)
+print("routed to:", result.routed_to)

codai_sdk-0.1.0/examples/feedback.py

@@ -0,0 +1,15 @@
+"""Submit feedback on a completion.
+
+    CODAI_API_KEY=sk_... python examples/feedback.py
+"""
+import os
+
+from codai import Codai
+
+client = Codai(api_key=os.environ["CODAI_API_KEY"])
+
+result = client.chat([{"role": "user", "content": "Hello!"}])
+
+if result.request_id:
+    client.feedback(result.request_id, 1)  # 1 = up, -1 = down
+    print("feedback submitted for", result.request_id)

codai_sdk-0.1.0/examples/streaming.py

@@ -0,0 +1,15 @@
+"""Streaming chat completion.
+
+    CODAI_API_KEY=sk_... python examples/streaming.py
+"""
+import os
+import sys
+
+from codai import Codai
+
+client = Codai(api_key=os.environ["CODAI_API_KEY"])
+
+for delta in client.chat_stream([{"role": "user", "content": "Write a haiku about Python."}]):
+    sys.stdout.write(delta)
+    sys.stdout.flush()
+print()

codai_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codai-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the codai AI gateway — chat, streaming, agents, feedback, models."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "codai", email = "support@codai.ro" }]
+keywords = ["codai", "ai", "llm", "openai-compatible", "gateway", "agents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://codai.ro"
+Repository = "https://github.com/dragoscv/codai-sdk-python"
+Issues = "https://github.com/dragoscv/codai-sdk-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codai"]

codai_sdk-0.1.0/src/codai/__init__.py

@@ -0,0 +1,338 @@
+"""codai — official Python SDK for the codai AI gateway.
+
+Zero-dependency (stdlib urllib) client mirroring @codai/sdk:
+
+    from codai import Codai
+
+    client = Codai(api_key="ck-...", session_id="my-session")
+    result = client.chat([{"role": "user", "content": "hello"}])
+    print(result.content, result.routed_to)
+
+    for delta in client.chat_stream([{"role": "user", "content": "hi"}]):
+        print(delta, end="")
+
+    run = client.agents_run("summarize the repo structure")
+    client.feedback(result.request_id, 1)
+
+Memory tools (memory_recall/memory_remember) and skills are GATEWAY-NATIVE:
+pass a stable session_id and the model uses them server-side.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Dict, Generator, List, Optional
+
+__all__ = ["Codai", "CodaiError", "ChatResult", "AgentRunResult"]
+__version__ = "0.1.0"
+
+_RETRYABLE = {429, 500, 502, 503, 504}
+
+
+class CodaiError(Exception):
+    def __init__(self, message: str, status: int = 0, body: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+@dataclass
+class ChatResult:
+    content: str
+    raw: Dict[str, Any]
+    request_id: Optional[str]
+    routed_to: Optional[str]
+    exec_verify: Optional[str]
+    usage: Optional[Dict[str, int]]
+
+
+@dataclass
+class AgentRunResult:
+    result: str
+    model: str
+    event_id: Optional[str]
+    usage: Optional[Dict[str, Any]] = field(default=None)
+
+
+class Codai:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://ai.codai.ro",
+        session_id: Optional[str] = None,
+        timeout: float = 120.0,
+        max_retries: int = 2,
+    ) -> None:
+        if not api_key:
+            raise ValueError("Codai: api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.session_id = session_id
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    # ------------------------------------------------------------- chat
+    def chat(
+        self,
+        messages: List[Dict[str, Any]],
+        model: str = "codai",
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+        agent_mode: bool = False,
+        compact: Optional[str] = None,
+        best_of: Optional[int] = None,
+        session_id: Optional[str] = None,
+    ) -> ChatResult:
+        body: Dict[str, Any] = {"model": model, "messages": messages, "stream": False}
+        if temperature is not None:
+            body["temperature"] = temperature
+        if max_tokens is not None:
+            body["max_tokens"] = max_tokens
+        if tools:
+            body["tools"] = tools
+        headers = self._chat_headers(agent_mode, compact, best_of, session_id)
+        status, resp_headers, data = self._request(
+            "/v1/chat/completions", body, extra_headers=headers
+        )
+        raw = json.loads(data)
+        choices = raw.get("choices") or []
+        usage_raw = raw.get("usage") or {}
+        return ChatResult(
+            content=str((choices[0].get("message") or {}).get("content") or "")
+            if choices
+            else "",
+            raw=raw,
+            request_id=resp_headers.get("x-request-id"),
+            routed_to=resp_headers.get("x-codai-routed-to"),
+            exec_verify=resp_headers.get("x-codai-exec-verify"),
+            usage=(
+                {
+                    "prompt_tokens": int(usage_raw.get("prompt_tokens") or 0),
+                    "completion_tokens": int(usage_raw.get("completion_tokens") or 0),
+                }
+                if usage_raw
+                else None
+            ),
+        )
+
+    def chat_stream(
+        self,
+        messages: List[Dict[str, Any]],
+        model: str = "codai",
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        agent_mode: bool = False,
+        session_id: Optional[str] = None,
+    ) -> Generator[str, None, None]:
+        body: Dict[str, Any] = {"model": model, "messages": messages, "stream": True}
+        if temperature is not None:
+            body["temperature"] = temperature
+        if max_tokens is not None:
+            body["max_tokens"] = max_tokens
+        headers = self._chat_headers(agent_mode, None, None, session_id)
+        req = self._build_request("/v1/chat/completions", body, headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                buffer = b""
+                for chunk in iter(lambda: resp.read(1024), b""):
+                    buffer += chunk
+                    while b"\n\n" in buffer:
+                        frame, buffer = buffer.split(b"\n\n", 1)
+                        for line in frame.split(b"\n"):
+                            if not line.startswith(b"data:"):
+                                continue
+                            payload = line[5:].strip()
+                            if payload == b"[DONE]":
+                                return
+                            try:
+                                parsed = json.loads(payload)
+                                delta = (
+                                    (parsed.get("choices") or [{}])[0]
+                                    .get("delta", {})
+                                    .get("content")
+                                )
+                                if delta:
+                                    yield delta
+                            except json.JSONDecodeError:
+                                continue
+        except urllib.error.HTTPError as e:  # pragma: no cover
+            raise CodaiError(f"codai stream → {e.code}", e.code, e.read()) from e
+
+    # ------------------------------------------------------------ agents
+    def agents_run(
+        self,
+        task: str,
+        context: Optional[str] = None,
+        system: Optional[str] = None,
+        model: Optional[str] = None,
+    ) -> AgentRunResult:
+        body: Dict[str, Any] = {"task": task}
+        if context:
+            body["context"] = context
+        if system:
+            body["system"] = system
+        if model:
+            body["model"] = model
+        _, _, data = self._request("/v1/agents/run", body)
+        raw = json.loads(data)
+        return AgentRunResult(
+            result=str(raw.get("result") or ""),
+            model=str(raw.get("model") or ""),
+            event_id=raw.get("event_id"),
+            usage=raw.get("usage"),
+        )
+
+    # ---------------------------------------------------------- feedback
+    def feedback(self, request_id: str, rating: int, comment: Optional[str] = None) -> None:
+        body: Dict[str, Any] = {"event_id": request_id, "rating": rating}
+        if comment:
+            body["comment"] = comment
+        self._request("/v1/feedback", body)
+
+    # ------------------------------------------------------------ models
+    def models(self) -> List[Dict[str, Any]]:
+        _, _, data = self._request("/v1/models", None, method="GET")
+        return json.loads(data).get("data") or []
+
+    # ------------------------------------------------------------ tokens
+    def mint_token(self, scope: str, ttl_seconds: Optional[int] = None) -> Dict[str, Any]:
+        """Mint an ephemeral scoped token ('realtime'|'audio'|'embeddings').
+
+        Returns {"token", "expires_at", "scope"}. Hand the token to a
+        browser/webview client; it expires in 60-3600s and only works on
+        its scope's surface.
+        """
+        body: Dict[str, Any] = {"scope": scope}
+        if ttl_seconds is not None:
+            body["ttl_seconds"] = ttl_seconds
+        _, _, data = self._request("/v1/tokens", body)
+        return json.loads(data)
+
+    # -------------------------------------------------------- embeddings
+    def embeddings(
+        self,
+        input: Any,
+        model: str = "codai-embed",
+        dimensions: Optional[int] = None,
+    ) -> List[List[float]]:
+        body: Dict[str, Any] = {"model": model, "input": input}
+        if dimensions is not None:
+            body["dimensions"] = dimensions
+        _, _, data = self._request("/v1/embeddings", body)
+        return [d["embedding"] for d in json.loads(data).get("data") or []]
+
+    # ------------------------------------------------------------- audio
+    def transcribe(
+        self,
+        file_bytes: bytes,
+        filename: str = "audio.webm",
+        model: str = "codai-transcribe",
+    ) -> str:
+        """Speech-to-text via multipart upload (max 25 MB). Returns transcript."""
+        boundary = f"----codai{int(time.time() * 1000)}"
+        parts = []
+        parts.append(
+            f"--{boundary}\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\n{model}\r\n".encode()
+        )
+        parts.append(
+            (
+                f"--{boundary}\r\nContent-Disposition: form-data; name=\"file\"; "
+                f"filename=\"{filename}\"\r\nContent-Type: application/octet-stream\r\n\r\n"
+            ).encode()
+        )
+        parts.append(file_bytes)
+        parts.append(f"\r\n--{boundary}--\r\n".encode())
+        payload = b"".join(parts)
+        req = urllib.request.Request(
+            f"{self.base_url}/v1/audio/transcriptions",
+            data=payload,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": f"multipart/form-data; boundary={boundary}",
+            },
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return str(json.loads(resp.read()).get("text") or "")
+        except urllib.error.HTTPError as e:
+            try:
+                err_body = json.loads(e.read())
+            except Exception:  # noqa: BLE001
+                err_body = None
+            raise CodaiError(f"codai /v1/audio/transcriptions → {e.code}", e.code, err_body) from e
+
+    def speech(
+        self,
+        input: str,
+        model: str = "codai-tts",
+        voice: str = "alloy",
+    ) -> bytes:
+        """Text-to-speech. Returns audio bytes (default mp3)."""
+        _, _, data = self._request(
+            "/v1/audio/speech", {"model": model, "input": input, "voice": voice}
+        )
+        return data
+
+    # ---------------------------------------------------------- internal
+    def _chat_headers(
+        self,
+        agent_mode: bool,
+        compact: Optional[str],
+        best_of: Optional[int],
+        session_id: Optional[str],
+    ) -> Dict[str, str]:
+        h: Dict[str, str] = {}
+        session = session_id or self.session_id
+        if session:
+            h["x-codai-session-id"] = session
+        if agent_mode:
+            h["x-codai-mode"] = "agent"
+        if compact:
+            h["x-codai-compact"] = compact
+        if best_of is not None:
+            h["x-codai-best-of"] = str(best_of)
+        return h
+
+    def _build_request(
+        self, path: str, body: Any, extra_headers: Optional[Dict[str, str]] = None, method: str = "POST"
+    ) -> urllib.request.Request:
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode()
+        headers.update(extra_headers or {})
+        return urllib.request.Request(
+            f"{self.base_url}{path}", data=data, headers=headers, method=method
+        )
+
+    def _request(
+        self, path: str, body: Any, extra_headers: Optional[Dict[str, str]] = None, method: str = "POST"
+    ) -> tuple:
+        last_err: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            req = self._build_request(path, body, extra_headers, method)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    return resp.status, dict(resp.headers), resp.read()
+            except urllib.error.HTTPError as e:
+                if e.code in _RETRYABLE and attempt < self.max_retries:
+                    time.sleep(0.5 * 2**attempt)
+                    continue
+                try:
+                    err_body = json.loads(e.read())
+                except Exception:  # noqa: BLE001
+                    err_body = None
+                raise CodaiError(f"codai {path} → {e.code}", e.code, err_body) from e
+            except Exception as e:  # noqa: BLE001 — network-level
+                last_err = e
+                if attempt < self.max_retries:
+                    time.sleep(0.5 * 2**attempt)
+                    continue
+        raise CodaiError(f"codai {path} failed after retries: {last_err}")