jambonz-python-sdk 0.2.0__tar.gz

jambonz_python_sdk-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+*.egg
+mcp.json
+.vscode/

jambonz_python_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: jambonz-python-sdk
+Version: 0.2.0
+Summary: Python SDK for jambonz CPaaS platform
+Project-URL: Homepage, https://github.com/jambonz/jambonz-python-sdk
+Project-URL: Repository, https://github.com/jambonz/jambonz-python-sdk
+Project-URL: Issues, https://github.com/jambonz/jambonz-python-sdk/issues
+Project-URL: Documentation, https://jambonz.org
+License-Expression: MIT
+Keywords: cpaas,jambonz,sip,telephony,voip,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Communications :: Telephony
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: referencing>=0.31
+Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: aioresponses>=0.7; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# jambonz Python SDK
+
+Python SDK for the [jambonz](https://jambonz.org) CPaaS platform.
+
+## Installation
+
+```bash
+pip install jambonz-python-sdk
+```
+
+## Quick Start
+
+### Webhook (HTTP)
+
+```python
+from aiohttp import web
+from jambonz_sdk.webhook import WebhookResponse
+
+async def handle_incoming(request: web.Request) -> web.Response:
+    jambonz = WebhookResponse()
+    jambonz.say(text="Hello!").gather(
+        input=["speech"],
+        actionHook="/handle-input",
+        timeout=10,
+        say={"text": "Please say something."},
+    ).hangup()
+    return web.json_response(jambonz.to_json())
+
+app = web.Application()
+app.router.add_post("/incoming", handle_incoming)
+web.run_app(app, port=3000)
+```
+
+### WebSocket
+
+```python
+import asyncio
+from jambonz_sdk.websocket import create_endpoint
+
+async def main():
+    make_service, runner = await create_endpoint(port=3000)
+    svc = make_service(path="/")
+
+    async def handle_session(session):
+        session.say(text="Hello!").hangup()
+        await session.send()
+
+    svc.on("session:new", handle_session)
+    await asyncio.Future()
+
+asyncio.run(main())
+```
+
+### REST Client
+
+```python
+from jambonz_sdk.client import JambonzClient
+
+async with JambonzClient(
+    base_url="https://api.jambonz.us",
+    account_sid="your-account-sid",
+    api_key="your-api-key",
+) as client:
+    call_sid = await client.calls.create({
+        "from": "+15085551212",
+        "to": {"type": "phone", "number": "+15085551213"},
+        "call_hook": "/incoming",
+    })
+```
+
+## How It Works
+
+### Spec-driven verb generation
+
+The SDK does **not** hardcode verb method signatures. Instead, verb methods (`.say()`, `.gather()`, `.dial()`, `.pipeline()`, etc.) are **auto-generated at import time** from [JSON Schema](https://github.com/jambonz/schema) files — the same schemas used by the Node.js SDK and the jambonz server.
+
+**What this means:**
+
+- When the schema adds a new property to a verb, the SDK picks it up automatically — no code change needed
+- Every method has **real typed parameters** (not `**kwargs: Any`) so IDEs show autocomplete and type hints
+- Verb synonyms (`stream` ↔ `listen`, `openai_s2s` → `llm` with `vendor: "openai"`) are handled by the registry
+
+### Updating the schema
+
+```bash
+# Download the pinned version from @jambonz/schema:
+python scripts/sync_schema.py
+
+# Or copy from a local clone:
+python scripts/sync_schema.py --local /path/to/schema
+```
+
+If a **new verb** was added (not just new properties), add one line to `verb_registry.py`:
+
+```python
+VerbDef("new_verb", "new_verb", doc="Description.")
+```
+
+## Features
+
+- **All 31 jambonz verbs**: say, play, gather, dial, conference, enqueue/dequeue, hangup, pause, redirect, config, tag, dtmf, dub, message, alert, answer, leave, listen/stream, transcribe, openai_s2s, google_s2s, deepgram_s2s, elevenlabs_s2s, ultravox_s2s, s2s, llm, dialogflow, pipeline, sip_decline, sip_request, sip_refer
+- **Fluent chainable API**: `.say(...).gather(...).hangup()`
+- **Webhook transport**: `WebhookResponse` for HTTP apps (works with aiohttp, FastAPI, Flask, etc.)
+- **WebSocket transport**: `create_endpoint` with `Session`, event handling, `send()`/`reply()`
+- **REST client**: `JambonzClient` with calls, conferences, queues, mid-call control
+- **Audio streaming**: Bidirectional audio via `AudioStream`
+- **Mid-call control**: inject commands (mute, whisper, record, DTMF, tag)
+- **TTS token streaming**: `send_tts_tokens()` / `flush_tts_tokens()`
+- **Pipeline updates**: `update_pipeline()` for mid-conversation LLM changes
+- **Signature verification**: HMAC-SHA256 webhook signature validation
+- **Env vars**: Portal discovery via OPTIONS + runtime reading
+
+## Examples
+
+See the [`examples/`](examples/) directory:
+
+| Example | Webhook | WebSocket | Description |
+|---------|---------|-----------|-------------|
+| hello-world | [webhook](examples/hello-world/webhook_app.py) | [websocket](examples/hello-world/websocket_app.py) | Minimal greeting |
+| echo | [webhook](examples/echo/webhook_app.py) | [websocket](examples/echo/websocket_app.py) | Speech echo with gather |
+| ivr-menu | [webhook](examples/ivr-menu/webhook_app.py) | — | IVR menu with speech + DTMF |
+| voice-agent | [webhook](examples/voice-agent/webhook_app.py) | [websocket](examples/voice-agent/websocket_app.py) | LLM pipeline with tool calls |
+| dial | [webhook](examples/dial/webhook_app.py) | — | Outbound dial with fallback |
+| listen-record | [webhook](examples/listen-record/webhook_app.py) | [websocket](examples/listen-record/websocket_app.py) | Audio recording |
+
+## Development
+
+```bash
+# Create venv and install
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/unit/          # Fast unit tests (253)
+pytest tests/integration/   # Real server tests (26)
+pytest                      # All 279 tests
+
+# Sync schema from upstream
+python scripts/sync_schema.py
+```
+
+## License
+
+MIT

jambonz_python_sdk-0.2.0/README.md

@@ -0,0 +1,145 @@
+# jambonz Python SDK
+
+Python SDK for the [jambonz](https://jambonz.org) CPaaS platform.
+
+## Installation
+
+```bash
+pip install jambonz-python-sdk
+```
+
+## Quick Start
+
+### Webhook (HTTP)
+
+```python
+from aiohttp import web
+from jambonz_sdk.webhook import WebhookResponse
+
+async def handle_incoming(request: web.Request) -> web.Response:
+    jambonz = WebhookResponse()
+    jambonz.say(text="Hello!").gather(
+        input=["speech"],
+        actionHook="/handle-input",
+        timeout=10,
+        say={"text": "Please say something."},
+    ).hangup()
+    return web.json_response(jambonz.to_json())
+
+app = web.Application()
+app.router.add_post("/incoming", handle_incoming)
+web.run_app(app, port=3000)
+```
+
+### WebSocket
+
+```python
+import asyncio
+from jambonz_sdk.websocket import create_endpoint
+
+async def main():
+    make_service, runner = await create_endpoint(port=3000)
+    svc = make_service(path="/")
+
+    async def handle_session(session):
+        session.say(text="Hello!").hangup()
+        await session.send()
+
+    svc.on("session:new", handle_session)
+    await asyncio.Future()
+
+asyncio.run(main())
+```
+
+### REST Client
+
+```python
+from jambonz_sdk.client import JambonzClient
+
+async with JambonzClient(
+    base_url="https://api.jambonz.us",
+    account_sid="your-account-sid",
+    api_key="your-api-key",
+) as client:
+    call_sid = await client.calls.create({
+        "from": "+15085551212",
+        "to": {"type": "phone", "number": "+15085551213"},
+        "call_hook": "/incoming",
+    })
+```
+
+## How It Works
+
+### Spec-driven verb generation
+
+The SDK does **not** hardcode verb method signatures. Instead, verb methods (`.say()`, `.gather()`, `.dial()`, `.pipeline()`, etc.) are **auto-generated at import time** from [JSON Schema](https://github.com/jambonz/schema) files — the same schemas used by the Node.js SDK and the jambonz server.
+
+**What this means:**
+
+- When the schema adds a new property to a verb, the SDK picks it up automatically — no code change needed
+- Every method has **real typed parameters** (not `**kwargs: Any`) so IDEs show autocomplete and type hints
+- Verb synonyms (`stream` ↔ `listen`, `openai_s2s` → `llm` with `vendor: "openai"`) are handled by the registry
+
+### Updating the schema
+
+```bash
+# Download the pinned version from @jambonz/schema:
+python scripts/sync_schema.py
+
+# Or copy from a local clone:
+python scripts/sync_schema.py --local /path/to/schema
+```
+
+If a **new verb** was added (not just new properties), add one line to `verb_registry.py`:
+
+```python
+VerbDef("new_verb", "new_verb", doc="Description.")
+```
+
+## Features
+
+- **All 31 jambonz verbs**: say, play, gather, dial, conference, enqueue/dequeue, hangup, pause, redirect, config, tag, dtmf, dub, message, alert, answer, leave, listen/stream, transcribe, openai_s2s, google_s2s, deepgram_s2s, elevenlabs_s2s, ultravox_s2s, s2s, llm, dialogflow, pipeline, sip_decline, sip_request, sip_refer
+- **Fluent chainable API**: `.say(...).gather(...).hangup()`
+- **Webhook transport**: `WebhookResponse` for HTTP apps (works with aiohttp, FastAPI, Flask, etc.)
+- **WebSocket transport**: `create_endpoint` with `Session`, event handling, `send()`/`reply()`
+- **REST client**: `JambonzClient` with calls, conferences, queues, mid-call control
+- **Audio streaming**: Bidirectional audio via `AudioStream`
+- **Mid-call control**: inject commands (mute, whisper, record, DTMF, tag)
+- **TTS token streaming**: `send_tts_tokens()` / `flush_tts_tokens()`
+- **Pipeline updates**: `update_pipeline()` for mid-conversation LLM changes
+- **Signature verification**: HMAC-SHA256 webhook signature validation
+- **Env vars**: Portal discovery via OPTIONS + runtime reading
+
+## Examples
+
+See the [`examples/`](examples/) directory:
+
+| Example | Webhook | WebSocket | Description |
+|---------|---------|-----------|-------------|
+| hello-world | [webhook](examples/hello-world/webhook_app.py) | [websocket](examples/hello-world/websocket_app.py) | Minimal greeting |
+| echo | [webhook](examples/echo/webhook_app.py) | [websocket](examples/echo/websocket_app.py) | Speech echo with gather |
+| ivr-menu | [webhook](examples/ivr-menu/webhook_app.py) | — | IVR menu with speech + DTMF |
+| voice-agent | [webhook](examples/voice-agent/webhook_app.py) | [websocket](examples/voice-agent/websocket_app.py) | LLM pipeline with tool calls |
+| dial | [webhook](examples/dial/webhook_app.py) | — | Outbound dial with fallback |
+| listen-record | [webhook](examples/listen-record/webhook_app.py) | [websocket](examples/listen-record/websocket_app.py) | Audio recording |
+
+## Development
+
+```bash
+# Create venv and install
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/unit/          # Fast unit tests (253)
+pytest tests/integration/   # Real server tests (26)
+pytest                      # All 279 tests
+
+# Sync schema from upstream
+python scripts/sync_schema.py
+```
+
+## License
+
+MIT

jambonz_python_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jambonz-python-sdk"
+version = "0.2.0"
+description = "Python SDK for jambonz CPaaS platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["jambonz", "voip", "sip", "cpaas", "telephony", "websocket"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Telephony",
+    "Framework :: AsyncIO",
+]
+dependencies = [
+    "aiohttp>=3.9",
+    "jsonschema>=4.20",
+    "referencing>=0.31",
+    "typing_extensions>=4.0; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://github.com/jambonz/jambonz-python-sdk"
+Repository = "https://github.com/jambonz/jambonz-python-sdk"
+Issues = "https://github.com/jambonz/jambonz-python-sdk/issues"
+Documentation = "https://jambonz.org"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "aioresponses>=0.7",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jambonz_sdk"]
+
+[tool.hatch.build]
+include = ["src/jambonz_sdk/**/*.py", "src/jambonz_sdk/**/*.pyi", "src/jambonz_sdk/schema/**/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "integration: integration tests that start real servers",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]
+ignore = ["UP007", "E501"]  # UP007: Union needed at runtime; E501: long lines in test data
+
+[tool.ruff.lint.per-file-ignores]
+"*.pyi" = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

jambonz_python_sdk-0.2.0/src/jambonz_sdk/__init__.py

@@ -0,0 +1,52 @@
+"""jambonz Python SDK.
+
+A Python SDK for the jambonz CPaaS platform, providing:
+
+- **Webhook**: HTTP transport for building jambonz voice apps
+- **WebSocket**: Persistent connection transport for real-time voice AI
+- **Client**: REST API client for call control and management
+
+Quick start (webhook)::
+
+    from jambonz_sdk.webhook import WebhookResponse
+
+    jambonz = WebhookResponse()
+    jambonz.say(text="Hello!").hangup()
+    response_body = jambonz.to_json()
+
+Quick start (websocket)::
+
+    from jambonz_sdk.websocket import create_endpoint
+
+    make_service, server = await create_endpoint(port=3000)
+    svc = make_service(path="/")
+
+    def handle_session(session):
+        session.say(text="Hello!").hangup()
+        await session.send()
+
+    svc.on("session:new", handle_session)
+
+Quick start (REST client)::
+
+    from jambonz_sdk.client import JambonzClient
+
+    async with JambonzClient(base_url=url, account_sid=sid, api_key=key) as client:
+        call_sid = await client.calls.create({...})
+"""
+
+__version__ = "0.1.0"
+
+# Re-export main classes for convenience
+from jambonz_sdk.client import JambonzClient
+from jambonz_sdk.validator import JambonzValidator
+from jambonz_sdk.verb_builder import VerbBuilder
+from jambonz_sdk.webhook import WebhookResponse
+
+__all__ = [
+    "JambonzClient",
+    "JambonzValidator",
+    "VerbBuilder",
+    "WebhookResponse",
+    "__version__",
+]

jambonz_python_sdk-0.2.0/src/jambonz_sdk/_signature.py

@@ -0,0 +1,73 @@
+"""HMAC-SHA256 webhook signature verification.
+
+jambonz signs webhook requests with the header:
+    Jambonz-Signature: t=<timestamp>,v1=<signature>
+
+The signature is computed as:
+    HMAC-SHA256(secret, timestamp + "." + raw_body)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+DEFAULT_TOLERANCE = 300  # 5 minutes
+
+
+def verify_signature(
+    payload: bytes,
+    signature_header: str,
+    secret: str,
+    tolerance: int = DEFAULT_TOLERANCE,
+) -> bool:
+    """Verify a jambonz webhook signature.
+
+    Args:
+        payload: Raw request body bytes.
+        signature_header: Value of the ``Jambonz-Signature`` header.
+        secret: The webhook signing secret.
+        tolerance: Maximum age in seconds for the timestamp (default 300).
+
+    Returns:
+        True if the signature is valid.
+
+    Raises:
+        ValueError: If the signature header is malformed, the signature
+            doesn't match, or the timestamp is outside the tolerance window.
+    """
+    parts: dict[str, str] = {}
+    for item in signature_header.split(","):
+        key, _, value = item.strip().partition("=")
+        parts[key] = value
+
+    timestamp_str = parts.get("t")
+    sig = parts.get("v1")
+
+    if not timestamp_str or not sig:
+        raise ValueError("Invalid Jambonz-Signature header format")
+
+    try:
+        timestamp = int(timestamp_str)
+    except (ValueError, TypeError) as exc:
+        raise ValueError("Invalid timestamp in Jambonz-Signature header") from exc
+
+    if tolerance > 0:
+        age = int(time.time()) - timestamp
+        if age > tolerance:
+            raise ValueError(
+                f"Signature timestamp too old: {age}s > {tolerance}s tolerance"
+            )
+
+    signed_payload = f"{timestamp}.".encode() + payload
+    expected = hmac.new(
+        secret.encode(),
+        signed_payload,
+        hashlib.sha256,
+    ).hexdigest()
+
+    if not hmac.compare_digest(expected, sig):
+        raise ValueError("Signature verification failed")
+
+    return True

jambonz_python_sdk-0.2.0/src/jambonz_sdk/client/__init__.py

@@ -0,0 +1,15 @@
+"""REST API client for jambonz platform."""
+
+from jambonz_sdk.client.api import (
+    CallsResource,
+    ConferencesResource,
+    JambonzClient,
+    QueuesResource,
+)
+
+__all__ = [
+    "CallsResource",
+    "ConferencesResource",
+    "JambonzClient",
+    "QueuesResource",
+]