kupe 0.1.0__tar.gz

kupe-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: kupe
+Version: 0.1.0
+Summary: Official Python SDK for the Kupe voice API
+Author: Kupe
+License: MIT
+Project-URL: Homepage, https://docs.kupe.in
+Project-URL: Documentation, https://docs.kupe.in
+Keywords: kupe,voice,realtime,agents
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# Kupe Python SDK
+
+Official client for the [Kupe](https://x.kupe.in) voice API.
+
+```bash
+pip install kupe
+```
+
+Local checkout:
+
+```bash
+pip install -e ./kupe-sdk
+```
+
+## Quickstart
+
+```python
+from kupe import Kupe
+
+client = Kupe()  # KUPE_API_KEY
+session = client.realtime.sessions.create(agent_id="agt_...", voice="priya")
+with client.realtime.connect(session) as rt:
+    rt.send_text("Hi — remind them EMI is due tomorrow.")
+    for event in rt:
+        if event.type == "response.output_audio_transcript.done":
+            print(event.transcript)
+```
+
+Auth is `Authorization: Bearer sk-kupe-...` (or a Supabase JWT). Default base is `https://x.kupe.in`. Env: `KUPE_API_KEY`, optional `KUPE_BASE_URL`.
+
+Every HTTP path is `{base}/v1/...`. Passing `base_url="https://x.kupe.in/v1"` is fine — the client will not drop `/v1`.
+
+When `org_id` / `project_id` are omitted, they are filled from `GET /v1/me`.
+
+## Resources
+
+`client.agents`, `realtime`, `sessions`, `inbound`, `campaigns`, `recipient_lists`, `tools`, `composio`, `analyses`, `databases`, `knowledge_bases`, `phones`, `voices`, `providers`, `logs`, `billing`, `usage`, `orgs`, `projects`.
+
+Realtime audio is PCM16 mono at 24 kHz (`rt.append_audio(pcm)`). Voice clone / patch / delete require a user JWT — calling them with an API key raises `JWTRequiredError`.
+
+Payments, credit checkout, and per-service usage breakdown are not included.
+
+See `examples/realtime_text_turn.py`.

kupe-0.1.0/README.md

@@ -0,0 +1,43 @@
+# Kupe Python SDK
+
+Official client for the [Kupe](https://x.kupe.in) voice API.
+
+```bash
+pip install kupe
+```
+
+Local checkout:
+
+```bash
+pip install -e ./kupe-sdk
+```
+
+## Quickstart
+
+```python
+from kupe import Kupe
+
+client = Kupe()  # KUPE_API_KEY
+session = client.realtime.sessions.create(agent_id="agt_...", voice="priya")
+with client.realtime.connect(session) as rt:
+    rt.send_text("Hi — remind them EMI is due tomorrow.")
+    for event in rt:
+        if event.type == "response.output_audio_transcript.done":
+            print(event.transcript)
+```
+
+Auth is `Authorization: Bearer sk-kupe-...` (or a Supabase JWT). Default base is `https://x.kupe.in`. Env: `KUPE_API_KEY`, optional `KUPE_BASE_URL`.
+
+Every HTTP path is `{base}/v1/...`. Passing `base_url="https://x.kupe.in/v1"` is fine — the client will not drop `/v1`.
+
+When `org_id` / `project_id` are omitted, they are filled from `GET /v1/me`.
+
+## Resources
+
+`client.agents`, `realtime`, `sessions`, `inbound`, `campaigns`, `recipient_lists`, `tools`, `composio`, `analyses`, `databases`, `knowledge_bases`, `phones`, `voices`, `providers`, `logs`, `billing`, `usage`, `orgs`, `projects`.
+
+Realtime audio is PCM16 mono at 24 kHz (`rt.append_audio(pcm)`). Voice clone / patch / delete require a user JWT — calling them with an API key raises `JWTRequiredError`.
+
+Payments, credit checkout, and per-service usage breakdown are not included.
+
+See `examples/realtime_text_turn.py`.

kupe-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kupe"
+version = "0.1.0"
+description = "Official Python SDK for the Kupe voice API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Kupe" }]
+keywords = ["kupe", "voice", "realtime", "agents"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27.0",
+  "pydantic>=2.0",
+  "websockets>=12.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://docs.kupe.in"
+Documentation = "https://docs.kupe.in"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+kupe = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [".", "src"]

kupe-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kupe-0.1.0/src/kupe/__init__.py

@@ -0,0 +1,13 @@
+from kupe.client import Kupe
+from kupe.errors import APIError, AuthenticationError, JWTRequiredError, KupeError
+from kupe.realtime import RealtimeConnection
+
+__all__ = [
+    "Kupe",
+    "KupeError",
+    "APIError",
+    "AuthenticationError",
+    "JWTRequiredError",
+    "RealtimeConnection",
+]
+__version__ = "0.1.0"

kupe-0.1.0/src/kupe/_models.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+def parse(value: Any) -> Any:
+    """Wrap dicts as :class:`KupeObject` so nested fields are attributes."""
+    if isinstance(value, KupeObject):
+        return value
+    if isinstance(value, Mapping):
+        return KupeObject(value)
+    if isinstance(value, list):
+        return [parse(item) for item in value]
+    return value
+
+
+class KupeObject:
+    """Attribute- and dict-accessible API payload."""
+
+    def __init__(self, data: Mapping[str, Any] | None = None, **extra: Any) -> None:
+        payload = dict(data or {})
+        payload.update(extra)
+        object.__setattr__(self, "_data", payload)
+        for key, value in payload.items():
+            object.__setattr__(self, key, parse(value))
+
+    def __repr__(self) -> str:
+        return f"KupeObject({self._data!r})"
+
+    def __getitem__(self, key: str) -> Any:
+        return getattr(self, key)
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._data
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return getattr(self, key, default)
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self._data)
+
+    def model_dump(self) -> dict[str, Any]:
+        return self.to_dict()
+
+
+class RealtimeEvent(BaseModel):
+    """A server event from the realtime WebSocket."""
+
+    model_config = ConfigDict(extra="allow")
+
+    type: str = ""
+
+    def __getitem__(self, key: str) -> Any:
+        extra = self.__pydantic_extra__ or {}
+        if key in extra:
+            return extra[key]
+        return getattr(self, key)
+
+
+class RealtimeClientSecret(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    value: str
+    expires_at: int | None = None
+
+
+class RealtimeSession(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    id: str = ""
+    object: str = "realtime.session"
+    model: str = "kupe-realtime"
+    modalities: list[str] = Field(default_factory=lambda: ["audio", "text"])
+    instructions: str = ""
+    voice: str = ""
+    input_audio_format: str = "pcm16"
+    output_audio_format: str = "pcm16"
+    tools: list[dict[str, Any]] = Field(default_factory=list)
+    client_secret: RealtimeClientSecret
+    websocket_url: str
+    session_id: str | None = None

kupe-0.1.0/src/kupe/_urls.py

@@ -0,0 +1,34 @@
+"""URL helpers. Paths always join as ``{origin}/v1/...``.
+
+The OpenAI SDK treats a leading-slash path as host-absolute, so
+``OpenAI(base_url="https://x.kupe.in/v1").post("/realtime/sessions")`` hits
+``https://x.kupe.in/realtime/sessions`` (no ``/v1``). This package never
+does that: every HTTP call is built with :func:`v1_url`.
+"""
+
+from __future__ import annotations
+
+DEFAULT_BASE_URL = "https://x.kupe.in"
+
+
+def origin(base_url: str | None) -> str:
+    """Host origin with no trailing slash and no ``/v1`` suffix.
+
+    Callers may pass ``https://x.kupe.in`` or ``https://x.kupe.in/v1``;
+    both resolve to the same origin so we never double-prefix ``/v1``.
+    """
+    url = (base_url or DEFAULT_BASE_URL).strip().rstrip("/")
+    if url.endswith("/v1"):
+        url = url[: -len("/v1")].rstrip("/")
+    return url
+
+
+def v1_url(base_url: str | None, path: str) -> str:
+    """Return ``{origin}/v1/{path}``. Leading slashes and a ``v1/`` prefix on
+    *path* are stripped so a caller cannot accidentally drop ``/v1``.
+    """
+    path = (path or "").lstrip("/")
+    if path.startswith("v1/"):
+        path = path[3:]
+    path = path.lstrip("/")
+    return f"{origin(base_url)}/v1/{path}"

kupe-0.1.0/src/kupe/client.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from kupe._models import KupeObject, parse
+from kupe._urls import DEFAULT_BASE_URL, origin, v1_url
+from kupe.errors import APIConnectionError, APIError, AuthenticationError, JWTRequiredError, KupeError
+from kupe.resources.agents import AgentsResource
+from kupe.resources.analyses import AnalysesResource
+from kupe.resources.billing import BillingResource
+from kupe.resources.campaigns import CampaignsResource
+from kupe.resources.composio import ComposioResource
+from kupe.resources.databases import DatabasesResource
+from kupe.resources.inbound import InboundResource
+from kupe.resources.knowledge_bases import KnowledgeBasesResource
+from kupe.resources.logs import LogsResource
+from kupe.resources.orgs import OrgsResource
+from kupe.resources.phones import PhonesResource
+from kupe.resources.projects import ProjectsResource
+from kupe.resources.providers import ProvidersResource
+from kupe.resources.realtime import RealtimeResource
+from kupe.resources.recipient_lists import RecipientListsResource
+from kupe.resources.sessions import SessionsResource
+from kupe.resources.tools import ToolsResource
+from kupe.resources.usage import UsageResource
+from kupe.resources.voices import VoicesResource
+
+__version__ = "0.1.0"
+
+
+def _looks_like_jwt(token: str) -> bool:
+    return (not token.startswith("sk-")) and token.count(".") == 2
+
+
+class Kupe:
+    """Synchronous client for the Kupe HTTP API and realtime WebSocket.
+
+    Parameters
+    ----------
+    api_key:
+        ``sk-kupe-...`` or a Supabase user JWT. Defaults to ``KUPE_API_KEY``.
+    base_url:
+        API origin, default ``https://x.kupe.in``. ``/v1`` is always appended;
+        passing ``https://x.kupe.in/v1`` is fine and will not double-prefix.
+    org_id / project_id:
+        Optional. When omitted, filled from ``GET /v1/me``.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        org_id: str | None = None,
+        project_id: str | None = None,
+        timeout: float = 60.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get("KUPE_API_KEY")
+        if not key:
+            raise AuthenticationError("No API key provided. Pass api_key= or set KUPE_API_KEY.")
+        self.api_key = key
+        env_base = os.environ.get("KUPE_BASE_URL")
+        self.base_url = origin(base_url if base_url is not None else (env_base or DEFAULT_BASE_URL))
+        self._org_id = org_id
+        self._project_id = project_id
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(
+            timeout=timeout,
+            headers={"User-Agent": f"kupe-python/{__version__}"},
+        )
+
+        self.agents = AgentsResource(self)
+        self.realtime = RealtimeResource(self)
+        self.sessions = SessionsResource(self)
+        self.inbound = InboundResource(self)
+        self.campaigns = CampaignsResource(self)
+        self.recipient_lists = RecipientListsResource(self)
+        self.tools = ToolsResource(self)
+        self.composio = ComposioResource(self)
+        self.analyses = AnalysesResource(self)
+        self.databases = DatabasesResource(self)
+        self.knowledge_bases = KnowledgeBasesResource(self)
+        self.phones = PhonesResource(self)
+        self.voices = VoicesResource(self)
+        self.providers = ProvidersResource(self)
+        self.logs = LogsResource(self)
+        self.billing = BillingResource(self)
+        self.usage = UsageResource(self)
+        self.orgs = OrgsResource(self)
+        self.projects = ProjectsResource(self)
+
+    @property
+    def org_id(self) -> str | None:
+        if self._org_id is None:
+            self._ensure_scope()
+        return self._org_id
+
+    @property
+    def project_id(self) -> str | None:
+        if self._project_id is None:
+            self._ensure_scope()
+        return self._project_id
+
+    def me(self) -> KupeObject:
+        return self._request("GET", "me")
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> Kupe:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _uses_jwt(self) -> bool:
+        return _looks_like_jwt(self.api_key)
+
+    def _require_jwt(self, action: str) -> None:
+        if not self._uses_jwt():
+            raise JWTRequiredError(
+                f"{action} requires a user JWT. API keys cannot own a voice — "
+                "sign in and pass a Supabase access token as api_key=."
+            )
+
+    def _ensure_scope(self) -> None:
+        if self._org_id and self._project_id:
+            return
+        me = self.me()
+        data = me.to_dict() if isinstance(me, KupeObject) else dict(me)
+        if not self._org_id:
+            self._org_id = data.get("org_id") or None
+        if not self._project_id:
+            self._project_id = data.get("project_id") or None
+
+    def _org(self, org_id: str | None = None) -> str:
+        if org_id:
+            return org_id
+        self._ensure_scope()
+        if not self._org_id:
+            raise KupeError(
+                "org_id is required. Pass org_id= to Kupe() or ensure GET /v1/me returns org_id."
+            )
+        return self._org_id
+
+    def _scope(
+        self,
+        org_id: str | None = None,
+        project_id: str | None = None,
+    ) -> tuple[str, str]:
+        if not org_id or not project_id:
+            self._ensure_scope()
+        resolved_org = org_id or self._org_id
+        resolved_project = project_id or self._project_id
+        if not resolved_org or not resolved_project:
+            raise KupeError(
+                "org_id and project_id are required. Pass them to Kupe() or "
+                "ensure GET /v1/me returns both."
+            )
+        return resolved_org, resolved_project
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        files: Any = None,
+        data: Any = None,
+        raw: bool = False,
+    ) -> Any:
+        url = v1_url(self.base_url, path)
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": f"kupe-python/{__version__}",
+        }
+        if not raw:
+            headers["Accept"] = "application/json"
+
+        request_kwargs: dict[str, Any] = {
+            "headers": headers,
+            "params": {k: v for k, v in (params or {}).items() if v is not None} or None,
+        }
+        if files is not None:
+            request_kwargs["files"] = files
+            if data is not None:
+                request_kwargs["data"] = data
+        elif data is not None:
+            request_kwargs["data"] = data
+        elif json is not None:
+            request_kwargs["json"] = json
+
+        try:
+            response = self._http.request(method, url, **request_kwargs)
+        except httpx.RequestError as exc:
+            raise APIConnectionError(f"Failed to reach {url}: {exc}") from exc
+
+        if response.status_code >= 400:
+            try:
+                body: Any = response.json()
+                detail = body.get("detail", body) if isinstance(body, dict) else body
+            except Exception:
+                body = response.text
+                detail = body
+            raise APIError(
+                f"HTTP {response.status_code} for {method} {url}: {detail}",
+                status_code=response.status_code,
+                body=body,
+                path=url,
+            )
+
+        if raw:
+            return response.content
+        if response.status_code == 204 or not response.content:
+            return None
+        try:
+            payload = response.json()
+        except Exception:
+            return response.text
+        return parse(payload)

kupe-0.1.0/src/kupe/errors.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class KupeError(Exception):
+    """Base error for the Kupe SDK."""
+
+
+class AuthenticationError(KupeError):
+    """Missing or invalid credentials."""
+
+
+class JWTRequiredError(AuthenticationError):
+    """This method requires a user JWT; API keys are not accepted.
+
+    Voice clone / patch / delete (and related ownership endpoints) are
+    JWT-only on the backend — API keys cannot own a voice.
+    """
+
+
+class APIConnectionError(KupeError):
+    """Network failure talking to the Kupe API."""
+
+
+class APIError(KupeError):
+    """Non-success HTTP response from the Kupe API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        body: Any = None,
+        path: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+        self.path = path