voxevolv 0.1.0__py3-none-any.whl

voxevolv/__init__.py

@@ -0,0 +1,17 @@
+from .client import (
+    BrowserCredentials,
+    Session,
+    SessionsResource,
+    VoxEvolv,
+    VoxEvolvError,
+    idempotency_key_for,
+)
+
+__all__ = [
+    "BrowserCredentials",
+    "Session",
+    "SessionsResource",
+    "VoxEvolv",
+    "VoxEvolvError",
+    "idempotency_key_for",
+]

voxevolv/client.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import dataclass
+from email.utils import parsedate_to_datetime
+from typing import Any, Callable, Mapping, TypedDict
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+Transport = Callable[[Request, float], Any]
+
+
+class VoxEvolvError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str | None = None,
+        request_id: str | None = None,
+        details: list[Any] | None = None,
+        retryable: bool = False,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.details = details or []
+        self.retryable = retryable
+
+
+class BrowserCredentials(TypedDict):
+    id: str
+    connection: Mapping[str, str]
+    access_token: str
+    access_token_expires_at: str
+
+
+@dataclass(frozen=True)
+class Session:
+    payload: Mapping[str, Any]
+
+    @property
+    def id(self) -> str:
+        return str(self.payload["id"])
+
+    @property
+    def profile_revision(self) -> str:
+        return str(self.payload["profile_revision"])
+
+    def browser_credentials(self) -> BrowserCredentials:
+        return {
+            "id": self.id,
+            "connection": self.payload["connection"],
+            "access_token": str(self.payload["access_token"]),
+            "access_token_expires_at": str(self.payload["access_token_expires_at"]),
+        }
+
+
+class SessionsResource:
+    def __init__(self, client: VoxEvolv) -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        intent_id: str,
+        profile: str,
+        participant: Mapping[str, str],
+        instructions: str = "",
+        greeting: str = "",
+        language: str | None = None,
+        voice: str | None = None,
+        require: Mapping[str, Any] | None = None,
+        media: Mapping[str, Any] | None = None,
+        max_duration_seconds: int | None = None,
+        media_idle_timeout_seconds: int | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> Session:
+        _validate_create(intent_id=intent_id, profile=profile, participant=participant)
+        identity = participant["identity"]
+        body: dict[str, Any] = {
+            "protocol_version": 1,
+            "client_reference_id": intent_id,
+            "profile": profile,
+            "participant": {
+                "identity": identity,
+                **(
+                    {"display_name": participant["display_name"]}
+                    if "display_name" in participant
+                    else {}
+                ),
+            },
+            "instructions": instructions,
+            "greeting": greeting,
+            "metadata": dict(metadata or {}),
+        }
+        optional = {
+            "language": language,
+            "voice": voice,
+            "require": dict(require) if require is not None else None,
+            "media": dict(media) if media is not None else None,
+            "max_duration_seconds": max_duration_seconds,
+            "media_idle_timeout_seconds": media_idle_timeout_seconds,
+        }
+        body.update({key: value for key, value in optional.items() if value is not None})
+        payload = self._client._request(
+            "sessions/",
+            method="POST",
+            body=body,
+            headers={"Idempotency-Key": idempotency_key_for(intent_id)},
+        )
+        return Session(payload)
+
+    def get(self, session_id: str) -> Mapping[str, Any]:
+        return self._client._request(f"sessions/{session_id}")
+
+    def end(self, session_id: str) -> None:
+        self._client._request(f"sessions/{session_id}", method="DELETE")
+
+
+class VoxEvolv:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        max_retries: int = 2,
+        retry_base_seconds: float = 0.25,
+        timeout_seconds: float = 30.0,
+        transport: Transport | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        if not api_key.startswith("sk_"):
+            raise TypeError("api_key must be a VoxEvolv server API key")
+        if max_retries < 0:
+            raise ValueError("max_retries cannot be negative")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._retry_base_seconds = retry_base_seconds
+        self._timeout_seconds = timeout_seconds
+        self._transport = transport or _urlopen
+        self._sleep = sleep
+        self.sessions = SessionsResource(self)
+
+    def _request(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        body: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Mapping[str, Any]:
+        encoded = None if body is None else json.dumps(body).encode("utf-8")
+        request_headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            **({"Content-Type": "application/json"} if encoded is not None else {}),
+            **dict(headers or {}),
+        }
+        request = Request(
+            f"{self._base_url}/{path.lstrip('/')}",
+            data=encoded,
+            headers=request_headers,
+            method=method,
+        )
+        attempt = 0
+        while True:
+            try:
+                response = self._transport(request, self._timeout_seconds)
+                raw = response.read()
+                return {} if not raw else json.loads(raw)
+            except HTTPError as error:
+                retryable = error.code == 429 or error.code >= 500
+                if not retryable or attempt >= self._max_retries:
+                    raise _api_error(error, retryable=retryable) from error
+                delay = _retry_after_seconds(error.headers.get("Retry-After"))
+                self._sleep(
+                    delay
+                    if delay is not None
+                    else self._retry_base_seconds * (2**attempt)
+                )
+                attempt += 1
+            except URLError as error:
+                if attempt >= self._max_retries:
+                    raise VoxEvolvError(
+                        f"Could not reach VoxEvolv: {error.reason}",
+                        status=0,
+                        code="network_error",
+                        retryable=True,
+                    ) from error
+                self._sleep(self._retry_base_seconds * (2**attempt))
+                attempt += 1
+
+
+def idempotency_key_for(intent_id: str) -> str:
+    if not intent_id or len(intent_id) > 200:
+        raise TypeError("intent_id must be between 1 and 200 characters")
+    digest = hashlib.sha256(intent_id.encode("utf-8")).hexdigest()
+    return f"intent_{digest}"
+
+
+def _validate_create(
+    *,
+    intent_id: str,
+    profile: str,
+    participant: Mapping[str, str],
+) -> None:
+    import re
+
+    idempotency_key_for(intent_id)
+    if re.fullmatch(r"[a-z][a-z0-9-]{1,62}[a-z0-9]", profile) is None:
+        raise TypeError("profile must be a valid published profile name")
+    identity = participant.get("identity", "")
+    if re.fullmatch(r"[A-Za-z0-9_.:@-]{1,120}", identity) is None:
+        raise TypeError("participant identity is invalid")
+
+
+def _urlopen(request: Request, timeout: float) -> Any:
+    return urlopen(request, timeout=timeout)
+
+
+def _api_error(error: HTTPError, *, retryable: bool) -> VoxEvolvError:
+    try:
+        payload = json.loads(error.read())
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        payload = {}
+    return VoxEvolvError(
+        payload.get("message", f"VoxEvolv request failed ({error.code})"),
+        status=error.code,
+        code=payload.get("error"),
+        request_id=payload.get("request_id"),
+        details=payload.get("details", []),
+        retryable=retryable,
+    )
+
+
+def _retry_after_seconds(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        try:
+            return max(0.0, parsedate_to_datetime(value).timestamp() - time.time())
+        except (TypeError, ValueError, OverflowError):
+            return None

voxevolv/py.typed

@@ -0,0 +1 @@
+

voxevolv-0.1.0.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: voxevolv
+Version: 0.1.0
+Summary: Python server SDK for the VoxEvolv Voice Session API
+Author: VoxEvolv contributors
+License-Expression: MIT
+Project-URL: Repository, https://github.com/shobhansuri/VoxEvolv
+Project-URL: Issues, https://github.com/shobhansuri/VoxEvolv/issues
+Classifier: Development Status :: 3 - Alpha
+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
+License-File: LICENSE
+Dynamic: license-file
+
+# VoxEvolv Python SDK
+
+Server-only Python client for creating and managing VoxEvolv sessions.
+
+```python
+import os
+from voxevolv import VoxEvolv
+
+client = VoxEvolv(
+    api_key=os.environ["VOXEVOLV_API_KEY"],
+    base_url=os.environ["VOXEVOLV_API_BASE"],
+)
+session = client.sessions.create(
+    intent_id=interview_session_id,
+    profile="live-interviewer",
+    participant={"identity": user_id, "display_name": display_name},
+    instructions=instructions,
+    greeting=greeting,
+)
+
+return session.browser_credentials()
+```
+
+The SDK derives one deterministic idempotency key from `intent_id`, preserves it
+across bounded 429/5xx/network retries, and raises `VoxEvolvError` with typed API
+failure information.

voxevolv-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+voxevolv/__init__.py,sha256=FCJFGPpqjUtvyN0Auz-vnEgUEmv9M4tkMv9ban8Hgu8,285
+voxevolv/client.py,sha256=njwcEfgXH2Ymj6Ji1A38YyfzWGNaoMeJZtNJczqZxXM,8270
+voxevolv/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+voxevolv-0.1.0.dist-info/licenses/LICENSE,sha256=X_9ZBwoirbzx79QmG66rQY7_lgRoC3oM7gj8hYfpKcc,1078
+voxevolv-0.1.0.dist-info/METADATA,sha256=c7cQYAB9gZdp6vezjWtEquq32vPQRJE6KXot9avUGfI,1445
+voxevolv-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+voxevolv-0.1.0.dist-info/top_level.txt,sha256=_c6f2s_VekeRA2z9O9DAqUa2Nlu2b5pZ0mgD32o8ywg,9
+voxevolv-0.1.0.dist-info/RECORD,,

voxevolv-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

voxevolv-0.1.0.dist-info/licenses/LICENSE

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

voxevolv-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+voxevolv