pyai-sdk 0.1.0__tar.gz

pyai_sdk-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Node
+node_modules/
+dist/
+*.tsbuildinfo
+npm-debug.log*
+
+# Go
+/gateway/bin/
+*.out
+
+# Env / secrets — NEVER commit
+.env
+.env.*
+*.pem
+*.key
+secrets/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

pyai_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: pyai-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the PyAI API (Hear, Speak, Cue, Omni).
+Project-URL: Homepage, https://pyai.com
+Project-URL: Documentation, https://api.pyai.com/docs
+Project-URL: Repository, https://github.com/atomsai/pyai-platform-backend
+License: MIT
+Keywords: openai-compatible,pyai,speech,stt,tts,voice-ai
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# pyai-sdk (Python SDK)
+
+Official Python SDK for the [PyAI API](https://api.pyai.com) — Hear
+(speech-to-text), Speak (text-to-speech + cloning), Cue (turn detection + KB
+context), and Omni (realtime voice agents). Zero third-party dependencies
+(standard library only); Python 3.9+.
+
+The contract is `https://api.pyai.com/openapi.json`. This SDK wraps it with
+typed errors, automatic retries, and realtime URL helpers.
+
+## Install
+
+```bash
+pip install pyai-sdk
+```
+
+## Quickstart
+
+```python
+import os
+from pyai import PyAI, new_idempotency_key
+
+pyai = PyAI(api_key=os.environ["PYAI_API_KEY"])
+
+# Text-to-speech
+audio = pyai.audio.speech(input="Hello from PyAI.", voice="stock_sarah_style2")
+open("hello.wav", "wb").write(audio)
+
+# Voices
+voices = pyai.voices.list(gender="female")
+
+# Async transcription (safe retry with an idempotency key)
+job = pyai.transcription_jobs.create(
+    audio_url="https://example.com/call.wav",
+    diarize=True,
+    idempotency_key=new_idempotency_key(),
+)
+done = pyai.transcription_jobs.get(job["job_id"])
+```
+
+## Realtime (Omni)
+
+Keys travel as a WebSocket subprotocol. Use the helpers with your preferred WS
+library (e.g. `websockets`):
+
+```python
+url = pyai.realtime_url(product="omni", agent_id="agent_123")
+subprotocol = pyai.realtime_subprotocol()
+
+import asyncio, websockets
+
+async def main():
+    async with websockets.connect(url, subprotocols=[subprotocol]) as ws:
+        async for frame in ws:
+            print(frame)
+
+asyncio.run(main())
+```
+
+> Omni uses the native `wss://api.pyai.com/v1/omni` surface (the default for
+> `product="omni"`); `product="flow"` uses `/v1/realtime`. The older
+> `/v2/omni/chat` URL is deprecated but still works.
+
+## Errors
+
+Failures raise `PyAIError` with a stable `code` (branch on it, not the message):
+
+```python
+from pyai import PyAIError
+
+try:
+    pyai.audio.speech(input="hi")
+except PyAIError as err:
+    if err.code == "credit_exhausted":
+        ...  # out of prepaid credit — add credit or use a sandbox key
+```
+
+Common codes: `unauthorized`, `forbidden`, `credit_exhausted`,
+`rate_limit_exceeded`, `concurrency_limit_exceeded`, `idempotency_conflict`.
+`429`/`5xx` are retried automatically (honoring `Retry-After`); tune with
+`PyAI(api_key, max_retries=...)`.
+
+## Develop
+
+```bash
+python -m unittest discover -s tests -v   # no network; transport injected
+```

pyai_sdk-0.1.0/README.md

@@ -0,0 +1,87 @@
+# pyai-sdk (Python SDK)
+
+Official Python SDK for the [PyAI API](https://api.pyai.com) — Hear
+(speech-to-text), Speak (text-to-speech + cloning), Cue (turn detection + KB
+context), and Omni (realtime voice agents). Zero third-party dependencies
+(standard library only); Python 3.9+.
+
+The contract is `https://api.pyai.com/openapi.json`. This SDK wraps it with
+typed errors, automatic retries, and realtime URL helpers.
+
+## Install
+
+```bash
+pip install pyai-sdk
+```
+
+## Quickstart
+
+```python
+import os
+from pyai import PyAI, new_idempotency_key
+
+pyai = PyAI(api_key=os.environ["PYAI_API_KEY"])
+
+# Text-to-speech
+audio = pyai.audio.speech(input="Hello from PyAI.", voice="stock_sarah_style2")
+open("hello.wav", "wb").write(audio)
+
+# Voices
+voices = pyai.voices.list(gender="female")
+
+# Async transcription (safe retry with an idempotency key)
+job = pyai.transcription_jobs.create(
+    audio_url="https://example.com/call.wav",
+    diarize=True,
+    idempotency_key=new_idempotency_key(),
+)
+done = pyai.transcription_jobs.get(job["job_id"])
+```
+
+## Realtime (Omni)
+
+Keys travel as a WebSocket subprotocol. Use the helpers with your preferred WS
+library (e.g. `websockets`):
+
+```python
+url = pyai.realtime_url(product="omni", agent_id="agent_123")
+subprotocol = pyai.realtime_subprotocol()
+
+import asyncio, websockets
+
+async def main():
+    async with websockets.connect(url, subprotocols=[subprotocol]) as ws:
+        async for frame in ws:
+            print(frame)
+
+asyncio.run(main())
+```
+
+> Omni uses the native `wss://api.pyai.com/v1/omni` surface (the default for
+> `product="omni"`); `product="flow"` uses `/v1/realtime`. The older
+> `/v2/omni/chat` URL is deprecated but still works.
+
+## Errors
+
+Failures raise `PyAIError` with a stable `code` (branch on it, not the message):
+
+```python
+from pyai import PyAIError
+
+try:
+    pyai.audio.speech(input="hi")
+except PyAIError as err:
+    if err.code == "credit_exhausted":
+        ...  # out of prepaid credit — add credit or use a sandbox key
+```
+
+Common codes: `unauthorized`, `forbidden`, `credit_exhausted`,
+`rate_limit_exceeded`, `concurrency_limit_exceeded`, `idempotency_conflict`.
+`429`/`5xx` are retried automatically (honoring `Retry-After`); tune with
+`PyAI(api_key, max_retries=...)`.
+
+## Develop
+
+```bash
+python -m unittest discover -s tests -v   # no network; transport injected
+```

pyai_sdk-0.1.0/pyai/__init__.py

@@ -0,0 +1,6 @@
+"""PyAI — official Python SDK for the PyAI API."""
+
+from .client import PyAI, PyAIError, new_idempotency_key
+
+__all__ = ["PyAI", "PyAIError", "new_idempotency_key"]
+__version__ = "0.1.0"

pyai_sdk-0.1.0/pyai/client.py

@@ -0,0 +1,269 @@
+"""Official Python SDK for the PyAI API (Hear, Speak, Cue, Omni).
+
+Zero third-party dependencies — uses the standard library (urllib). The public
+contract is https://api.pyai.com/openapi.json; this client wraps it with typed
+errors, automatic retries, and realtime URL helpers. Keys are opaque — never
+parse them.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Callable, Optional
+
+__all__ = ["PyAI", "PyAIError"]
+
+# transport(method, url, headers, body) -> (status, headers, body_bytes)
+Transport = Callable[[str, str, dict, Optional[bytes]], "tuple[int, dict, bytes]"]
+
+_RETRYABLE = {429, 500, 502, 503, 504}
+_DEFAULT_BASE_URL = "https://api.pyai.com"
+
+
+class PyAIError(Exception):
+    """A PyAI API error. Branch on ``code`` (stable), not ``message``."""
+
+    def __init__(
+        self,
+        status: int,
+        message: str,
+        code: Optional[str] = None,
+        type: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(f"[{status}{f'/{code}' if code else ''}] {message}")
+        self.status = status
+        self.message = message
+        self.code = code
+        self.type = type
+        self.request_id = request_id
+
+
+def _default_transport(method: str, url: str, headers: dict, body: Optional[bytes]):
+    req = urllib.request.Request(url, data=body, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(req) as resp:  # noqa: S310 (trusted base URL)
+            return resp.status, dict(resp.headers), resp.read()
+    except urllib.error.HTTPError as err:
+        return err.code, dict(err.headers), err.read()
+
+
+class PyAI:
+    """PyAI API client.
+
+    >>> pyai = PyAI(api_key="pyai_test_...")
+    >>> pyai.voices.list(gender="female")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        max_retries: int = 2,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._transport = transport or _default_transport
+        # Sub-resources mirror the TS SDK ergonomics.
+        self.models = _Models(self)
+        self.voices = _Voices(self)
+        self.audio = _Audio(self)
+        self.transcription_jobs = _TranscriptionJobs(self)
+
+    # --- transport ---------------------------------------------------------
+
+    def _headers(self, extra: Optional[dict] = None) -> dict:
+        h = {"Authorization": f"Bearer {self.api_key}"}
+        if extra:
+            h.update(extra)
+        return h
+
+    def _request(self, method: str, path: str, headers: dict, body: Optional[bytes]) -> "tuple[int, dict, bytes]":
+        url = f"{self.base_url}{path}"
+        attempt = 0
+        while True:
+            status, resp_headers, resp_body = self._transport(method, url, headers, body)
+            if status < 400:
+                return status, resp_headers, resp_body
+            if status in _RETRYABLE and attempt < self.max_retries:
+                retry_after = _to_float(resp_headers.get("Retry-After") or resp_headers.get("retry-after"))
+                delay = retry_after if retry_after and retry_after > 0 else (2**attempt) * 0.25
+                time.sleep(delay)
+                attempt += 1
+                continue
+            raise _to_error(status, resp_headers, resp_body)
+
+    def _get_json(self, path: str) -> Any:
+        _, _, body = self._request("GET", path, self._headers(), None)
+        return json.loads(body.decode("utf-8"))
+
+    def _post_json(self, path: str, payload: dict, extra_headers: Optional[dict] = None) -> Any:
+        headers = self._headers({"Content-Type": "application/json", **(extra_headers or {})})
+        body = json.dumps(payload).encode("utf-8")
+        _, _, resp = self._request("POST", path, headers, body)
+        return json.loads(resp.decode("utf-8"))
+
+    def _post_for_bytes(self, path: str, payload: dict) -> bytes:
+        headers = self._headers({"Content-Type": "application/json"})
+        body = json.dumps(payload).encode("utf-8")
+        _, _, resp = self._request("POST", path, headers, body)
+        return resp
+
+    # --- realtime ----------------------------------------------------------
+
+    def realtime_url(self, product: str = "omni", agent_id: Optional[str] = None, query: Optional[dict] = None) -> str:
+        """Build the realtime WebSocket URL for ``omni`` or ``flow``."""
+        ws_base = self.base_url.replace("https://", "wss://").replace("http://", "ws://")
+        params = dict(query or {})
+        if product == "omni":
+            # Omni's native realtime surface is /v1/omni. agent_id is an opaque
+            # label authorized by the key's org. format/rate are load-bearing on
+            # the connect URL, so default to browser-grade PCM16/24kHz.
+            if agent_id:
+                params["agent_id"] = agent_id
+            params.setdefault("format", "pcm16")
+            params.setdefault("rate", "24000")
+            qs = urllib.parse.urlencode(params)
+            return f"{ws_base}/v1/omni{('?' + qs) if qs else ''}"
+        params["model"] = "pyai-flow-realtime"
+        return f"{ws_base}/v1/realtime?{urllib.parse.urlencode(params)}"
+
+    def realtime_subprotocol(self) -> str:
+        """The WS subprotocol that carries the key (browser-safe auth)."""
+        return f"pyai-key.{self.api_key}"
+
+
+class _Models:
+    def __init__(self, client: PyAI) -> None:
+        self._c = client
+
+    def list(self) -> dict:
+        return self._c._get_json("/v1/models")
+
+
+class _Voices:
+    def __init__(self, client: PyAI) -> None:
+        self._c = client
+
+    def list(self, gender: Optional[str] = None, region: Optional[str] = None) -> dict:
+        params = {}
+        if gender:
+            params["gender"] = gender
+        if region:
+            params["region"] = region
+        qs = urllib.parse.urlencode(params)
+        return self._c._get_json(f"/v1/voices{('?' + qs) if qs else ''}")
+
+    def get(self, voice_id: str) -> dict:
+        return self._c._get_json(f"/v1/voices/{urllib.parse.quote(voice_id)}")
+
+
+class _Audio:
+    def __init__(self, client: PyAI) -> None:
+        self._c = client
+
+    def speech(
+        self,
+        input: str,
+        voice: Optional[str] = None,
+        model: str = "pyai-voice",
+        response_format: Optional[str] = None,
+        sample_rate: Optional[int] = None,
+        speed: Optional[float] = None,
+    ) -> bytes:
+        """Text-to-speech. Returns the raw audio bytes (default WAV).
+
+        ``response_format="pcm"`` returns raw, headerless 16-bit little-endian
+        mono samples at ``sample_rate`` (Hz, 8000-48000; defaults to the native
+        24 kHz) — the shape voice-agent pipelines consume directly.
+        """
+        payload: dict = {"model": model, "input": input}
+        if voice:
+            payload["voice"] = voice
+        if response_format:
+            payload["response_format"] = response_format
+        if sample_rate is not None:
+            payload["sample_rate"] = sample_rate
+        if speed is not None:
+            payload["speed"] = speed
+        return self._c._post_for_bytes("/v1/audio/speech", payload)
+
+
+class _TranscriptionJobs:
+    def __init__(self, client: PyAI) -> None:
+        self._c = client
+
+    def create(
+        self,
+        audio_url: str,
+        model: Optional[str] = None,
+        diarize: Optional[bool] = None,
+        channel: Optional[bool] = None,
+        output_formats: Optional[list] = None,
+        webhook_url: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict:
+        payload: dict = {"audio_url": audio_url}
+        if model:
+            payload["model"] = model
+        if diarize is not None:
+            payload["diarize"] = diarize
+        if channel is not None:
+            payload["channel"] = channel
+        if output_formats is not None:
+            payload["output_formats"] = output_formats
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        extra = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._c._post_json("/v1/transcription/jobs", payload, extra)
+
+    def get(self, job_id: str) -> dict:
+        return self._c._get_json(f"/v1/transcription/jobs/{urllib.parse.quote(job_id)}")
+
+    def list(self, limit: Optional[int] = None, cursor: Optional[str] = None) -> dict:
+        params = {}
+        if limit is not None:
+            params["limit"] = str(limit)
+        if cursor:
+            params["cursor"] = cursor
+        qs = urllib.parse.urlencode(params)
+        return self._c._get_json(f"/v1/transcription/jobs{('?' + qs) if qs else ''}")
+
+
+def new_idempotency_key() -> str:
+    """Convenience: a fresh idempotency key for safe retries."""
+    return str(uuid.uuid4())
+
+
+def _to_float(value: Optional[str]) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _to_error(status: int, headers: dict, body: bytes) -> PyAIError:
+    request_id = headers.get("X-Request-Id") or headers.get("x-request-id")
+    try:
+        parsed = json.loads(body.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return PyAIError(status, f"HTTP {status}", request_id=request_id)
+    err = parsed.get("error") if isinstance(parsed, dict) else None
+    if isinstance(err, dict):
+        return PyAIError(status, err.get("message", f"HTTP {status}"), err.get("code"), err.get("type"), request_id)
+    # RFC 7807 problem: code is the last segment of `type`.
+    type_url = parsed.get("type") if isinstance(parsed, dict) else None
+    code = type_url.rsplit("/", 1)[-1] if isinstance(type_url, str) else None
+    detail = parsed.get("detail") or parsed.get("title") if isinstance(parsed, dict) else None
+    return PyAIError(status, detail or f"HTTP {status}", code, request_id=parsed.get("request_id") or request_id)

pyai_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyai-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the PyAI API (Hear, Speak, Cue, Omni)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["pyai", "voice-ai", "tts", "stt", "speech", "openai-compatible"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://pyai.com"
+Documentation = "https://api.pyai.com/docs"
+Repository = "https://github.com/atomsai/pyai-platform-backend"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pyai"]

pyai_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,98 @@
+"""Tests for the PyAI Python SDK. No network — a fake transport is injected."""
+
+import json
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from pyai import PyAI, PyAIError  # noqa: E402
+
+
+def make_transport(handler):
+    """handler(method, url, headers, body) -> (status, headers, body_bytes)."""
+    calls = []
+
+    def transport(method, url, headers, body):
+        calls.append({"method": method, "url": url, "headers": headers, "body": body})
+        return handler(method, url, headers, body)
+
+    transport.calls = calls
+    return transport
+
+
+def json_body(obj):
+    return json.dumps(obj).encode("utf-8")
+
+
+class TestClient(unittest.TestCase):
+    def test_bearer_auth_and_models_list(self):
+        t = make_transport(lambda *a: (200, {}, json_body({"object": "list", "data": [{"id": "pyai-voice"}]})))
+        pyai = PyAI(api_key="pyai_test_k", transport=t)
+        res = pyai.models.list()
+        self.assertEqual(res["data"][0]["id"], "pyai-voice")
+        self.assertEqual(t.calls[0]["headers"]["Authorization"], "Bearer pyai_test_k")
+
+    def test_voices_query(self):
+        t = make_transport(lambda *a: (200, {}, json_body({"object": "list", "data": []})))
+        pyai = PyAI(api_key="k", transport=t)
+        pyai.voices.list(gender="female", region="en_us")
+        self.assertIn("gender=female", t.calls[0]["url"])
+        self.assertIn("region=en_us", t.calls[0]["url"])
+
+    def test_speech_returns_bytes(self):
+        t = make_transport(lambda *a: (200, {}, b"\x01\x02\x03"))
+        pyai = PyAI(api_key="k", transport=t)
+        audio = pyai.audio.speech(input="hi", voice="v")
+        self.assertEqual(audio, b"\x01\x02\x03")
+
+    def test_idempotency_header_forwarded(self):
+        t = make_transport(lambda *a: (202, {}, json_body({"job_id": "job_1", "status": "queued"})))
+        pyai = PyAI(api_key="k", transport=t)
+        job = pyai.transcription_jobs.create(audio_url="https://x/a.wav", idempotency_key="abc")
+        self.assertEqual(job["job_id"], "job_1")
+        self.assertEqual(t.calls[0]["headers"]["Idempotency-Key"], "abc")
+
+    def test_openai_error_mapping(self):
+        t = make_transport(lambda *a: (402, {}, json_body({"error": {"message": "no credit", "code": "credit_exhausted"}})))
+        pyai = PyAI(api_key="k", max_retries=0, transport=t)
+        with self.assertRaises(PyAIError) as ctx:
+            pyai.models.list()
+        self.assertEqual(ctx.exception.status, 402)
+        self.assertEqual(ctx.exception.code, "credit_exhausted")
+
+    def test_problem_json_error_mapping(self):
+        body = {"type": "https://api.pyai.com/problems/idempotency_conflict", "title": "Conflict", "status": 409}
+        t = make_transport(lambda *a: (409, {}, json_body(body)))
+        pyai = PyAI(api_key="k", max_retries=0, transport=t)
+        with self.assertRaises(PyAIError) as ctx:
+            pyai.transcription_jobs.get("job_1")
+        self.assertEqual(ctx.exception.code, "idempotency_conflict")
+
+    def test_retry_on_429(self):
+        state = {"n": 0}
+
+        def handler(method, url, headers, body):
+            state["n"] += 1
+            if state["n"] == 1:
+                return 429, {"Retry-After": "0"}, json_body({})
+            return 200, {}, json_body({"object": "list", "data": []})
+
+        t = make_transport(handler)
+        pyai = PyAI(api_key="k", max_retries=2, transport=t)
+        pyai.models.list()
+        self.assertEqual(len(t.calls), 2)
+
+    def test_realtime_url_and_subprotocol(self):
+        pyai = PyAI(api_key="pyai_live_z")
+        self.assertEqual(
+            pyai.realtime_url(product="omni", agent_id="agent_1"),
+            "wss://api.pyai.com/v1/omni?agent_id=agent_1&format=pcm16&rate=24000",
+        )
+        self.assertTrue(pyai.realtime_url(product="flow").endswith("/v1/realtime?model=pyai-flow-realtime"))
+        self.assertEqual(pyai.realtime_subprotocol(), "pyai-key.pyai_live_z")
+
+
+if __name__ == "__main__":
+    unittest.main()