voxevolv 0.1.0__tar.gz

voxevolv-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,26 @@
+# 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/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "voxevolv"
+version = "0.1.0"
+description = "Python server SDK for the VoxEvolv Voice Session API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "VoxEvolv contributors" }]
+requires-python = ">=3.10"
+dependencies = []
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "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",
+]
+
+[project.urls]
+Repository = "https://github.com/shobhansuri/VoxEvolv"
+Issues = "https://github.com/shobhansuri/VoxEvolv/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+voxevolv = ["py.typed"]

voxevolv-0.1.0/setup.cfg

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

voxevolv-0.1.0/src/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-0.1.0/src/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-0.1.0/src/voxevolv/py.typed

@@ -0,0 +1 @@
+

voxevolv-0.1.0/src/voxevolv.egg-info/PKG-INFO

@@ -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/src/voxevolv.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/voxevolv/__init__.py
+src/voxevolv/client.py
+src/voxevolv/py.typed
+src/voxevolv.egg-info/PKG-INFO
+src/voxevolv.egg-info/SOURCES.txt
+src/voxevolv.egg-info/dependency_links.txt
+src/voxevolv.egg-info/top_level.txt
+tests/test_client.py

voxevolv-0.1.0/src/voxevolv.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

voxevolv-0.1.0/src/voxevolv.egg-info/top_level.txt

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

voxevolv-0.1.0/tests/test_client.py

@@ -0,0 +1,129 @@
+import io
+import json
+import sys
+import unittest
+from pathlib import Path
+from urllib.error import HTTPError
+
+sys.path.insert(0, str(Path(__file__).parents[1] / "src"))
+
+from voxevolv import VoxEvolv, VoxEvolvError, idempotency_key_for  # noqa: E402
+
+
+class Response:
+    def __init__(self, payload):
+        self.payload = payload
+
+    def read(self):
+        return json.dumps(self.payload).encode("utf-8")
+
+
+class ClientTests(unittest.TestCase):
+    def test_create_projects_browser_credentials_and_uses_stable_key(self):
+        calls = []
+
+        def transport(request, timeout):
+            calls.append((request, timeout))
+            return Response(
+                {
+                    "id": "session-1",
+                    "status": "created",
+                    "profile_revision": "live-interviewer@1",
+                    "connection": {
+                        "url": "wss://rtc.example",
+                        "token": "room-token",
+                        "room_name": "room-1",
+                    },
+                    "access_token": "vsa_browser",
+                    "access_token_expires_at": "2026-07-18T12:00:00Z",
+                    "created_at": "2026-07-18T11:00:00Z",
+                }
+            )
+
+        client = VoxEvolv(
+            api_key="sk_test_server",
+            base_url="https://api.example.test/v1",
+            transport=transport,
+        )
+        session = client.sessions.create(
+            intent_id="interview:123",
+            profile="live-interviewer",
+            participant={"identity": "candidate_123", "display_name": "Candidate"},
+        )
+        self.assertEqual(session.id, "session-1")
+        self.assertEqual(calls[0][0].full_url, "https://api.example.test/v1/sessions/")
+        self.assertEqual(session.browser_credentials()["access_token"], "vsa_browser")
+        self.assertEqual(
+            calls[0][0].get_header("Idempotency-key"),
+            idempotency_key_for("interview:123"),
+        )
+
+    def test_retry_preserves_idempotency_key(self):
+        keys = []
+
+        def transport(request, _timeout):
+            keys.append(request.get_header("Idempotency-key"))
+            if len(keys) == 1:
+                raise HTTPError(
+                    request.full_url,
+                    503,
+                    "Unavailable",
+                    {},
+                    io.BytesIO(b"{}"),
+                )
+            return Response(
+                {
+                    "id": "session-1",
+                    "profile_revision": "profile@1",
+                    "connection": {},
+                    "access_token": "vsa",
+                    "access_token_expires_at": "later",
+                }
+            )
+
+        client = VoxEvolv(
+            api_key="sk_test_server",
+            base_url="https://api.example.test/v1",
+            transport=transport,
+            max_retries=1,
+            retry_base_seconds=0,
+            sleep=lambda _seconds: None,
+        )
+        client.sessions.create(
+            intent_id="retry-me",
+            profile="live-interviewer",
+            participant={"identity": "candidate"},
+        )
+        self.assertEqual(keys[0], keys[1])
+
+    def test_api_errors_are_typed(self):
+        def transport(request, _timeout):
+            raise HTTPError(
+                request.full_url,
+                409,
+                "Conflict",
+                {},
+                io.BytesIO(
+                    json.dumps(
+                        {"error": "invalid_profile", "message": "Profile is not published"}
+                    ).encode("utf-8")
+                ),
+            )
+
+        client = VoxEvolv(
+            api_key="sk_test_server",
+            base_url="https://api.example.test/v1",
+            transport=transport,
+        )
+        with self.assertRaises(VoxEvolvError) as raised:
+            client.sessions.create(
+                intent_id="invalid",
+                profile="live-interviewer",
+                participant={"identity": "candidate"},
+            )
+        self.assertEqual(raised.exception.status, 409)
+        self.assertEqual(raised.exception.code, "invalid_profile")
+
+
+if __name__ == "__main__":
+    unittest.main()