Metadata-Version: 2.4
Name: jambonz-sdk
Version: 0.1.1
Summary: Python SDK for the jambonz CPaaS platform
Project-URL: Homepage, https://github.com/JavierSanchezCastro/jambonz-sdk
Project-URL: Documentation, https://javiersanchezcastro.github.io/jambonz-sdk
Project-URL: Repository, https://github.com/JavierSanchezCastro/jambonz-sdk
Project-URL: Issues, https://github.com/JavierSanchezCastro/jambonz-sdk/issues
Author-email: Javier Sánchez <javsanchezcas@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cpaas,jambonz,sdk,sip,telephony,voip
Classifier: Development Status :: 3 - Alpha
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
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: pydantic>=2.12.5
Description-Content-Type: text/markdown

# jambonz SDK for Python

A Python SDK for the [jambonz](https://jambonz.org) open-source CPaaS platform. Build voice applications, manage telephony infrastructure, and control calls programmatically.

## Install

```bash
pip install jambonz-sdk
```

## Quick start

### Environment variables

Create a `.env` file or set these environment variables:

```bash
JAMBONZ_ACCOUNT_SID=your-account-sid
JAMBONZ_API_KEY=your-api-key
```

The SDK reads them automatically. Get your credentials from the [jambonz portal](https://jambonz.cloud).

### REST API client

```python
import asyncio
from jambonz import AsyncJambonzClient

async def main():
    async with AsyncJambonzClient() as client:
        # List phone numbers
        for number in await client.phone_numbers.list():
            print(number.number)

        # List carriers and their gateways
        for carrier in await client.carriers.list():
            gateways = await client.gateways.list(voip_carrier_sid=carrier.voip_carrier_sid)
            for gw in gateways:
                print(f"  {gw.ipv4}:{gw.port}")

        # Recent call history
        for call in await client.recent_calls.list(days=7):
            print(f"{call.from_} -> {call.to} ({call.duration}s)")

asyncio.run(main())
```

### Webhook response

Build call flow instructions for incoming calls:

```python
from fastapi import FastAPI
from jambonz import CallWebhook, GatherResult, JambonzResponse, Say, Gather, Hangup, Input

app = FastAPI()

@app.post("/incoming-call")
def handle_call(call: CallWebhook) -> JambonzResponse:
    return [
        Say(text="Hello! Please say something."),
        Gather(input=[Input.SPEECH], action_hook="/handle-speech"),
    ]

@app.post("/handle-speech")
def handle_speech(result: GatherResult) -> JambonzResponse:
    return [
        Say(text=f"You said: {result.transcript}. Goodbye!"),
        Hangup(),
    ]
```

## Features

- **REST API client** with sync and async support
- **Typed models** for all jambonz resources (Pydantic v2)
- **Webhook response builder** with typed verbs (Say, Gather, LLM, Dial...)
- **Webhook incoming models** for parsing call events, gather results, tool calls
- **Framework agnostic** — works with FastAPI, Flask, Django
- **Auto-config** from environment variables and `.env` files
- **Retry with backoff** on rate limits and server errors
- **Typed exceptions** for clean error handling

## Resources

| Resource | Usage |
|---|---|
| `client.accounts` | Account management |
| `client.users` | User management |
| `client.api_keys` | API key management |
| `client.carriers` | VoIP carriers (Telnyx, Twilio, etc.) |
| `client.gateways` | SIP gateways |
| `client.phone_numbers` | Phone number provisioning |
| `client.applications` | Application configuration |
| `client.speech_services` | Speech credentials (Google, AWS, ElevenLabs...) |
| `client.calls` | Active call control (create, update, hangup) |
| `client.recent_calls` | Call history |

## Documentation

Full docs at [javiersanchezcastro.github.io/jambonz-sdk](https://javiersanchezcastro.github.io/jambonz-sdk)

## License

MIT
