pyai-sdk 0.1.0__py3-none-any.whl

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,5 @@
+pyai/__init__.py,sha256=tHlWFpRcaQrYy49ZcmFTWBZihqtqYk9TgZQ6E-ka2V8,189
+pyai/client.py,sha256=nDMt8X71Dci9YY3hP0FS-f88WddQGuo8wAF-eNY6iDQ,10160
+pyai_sdk-0.1.0.dist-info/METADATA,sha256=amQZAwJ21Zn8mpEZeFxdkG46cBP-fzg0cq6FtXnc2jo,2776
+pyai_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pyai_sdk-0.1.0.dist-info/RECORD,,

pyai_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any