Metadata-Version: 2.4
Name: vaani-sdk-webrtc
Version: 0.1.0
Summary: Official Python WebRTC SDK for Vaani Voice AI
License: MIT
License-File: LICENSE
Keywords: ai,sdk,vaani,voice,webrtc
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# Vaani WebRTC Python SDK

Python client for creating and managing Vaani WebRTC voice sessions, plus related calls and agents APIs.

The SDK handles Vaani API authentication, HTTP errors, timeouts, and response models. Your frontend still joins the WebRTC room with the LiveKit client SDK using credentials returned by `sessions.connect()`.

## Installation

```bash
pip install vaani-sdk-webrtc
```

## WebRTC Flow

The programmatic WebRTC flow is:

1. Create a session with `client.sessions.create(...)`.
2. Send `session.session_url` to a user, or keep `session.session_token` for your own UI flow.
3. Call `client.sessions.connect(session.session_token)` when the user is ready to join.
4. Pass `creds.lk_url` and `creds.lk_token` to the LiveKit client SDK in your browser or mobile app.
5. Optionally watch session events with `client.sessions.ws_url(...)`.
6. Check status with `client.sessions.get(...)` or end the session with `client.sessions.disconnect(...)`.

## Sync Quickstart

```python
from vaani import VaaniClient

with VaaniClient(
    api_key="your_api_key",
    base_url="https://api.vaanivoice.ai",
    timeout=30,
) as client:
    session = client.sessions.create(
        agent_id="agent-uuid-or-name",
        ui_type="widget",
        grace_period=60,
        session_ttl=1800,
        initial_message="User is asking about order #1234",
        metadata={
            "user_id": "user_123",
            "ticket_id": "T-1234",
        },
    )

    creds = client.sessions.connect(session.session_token)

print(session.session_url)
print(creds.lk_url)
print(creds.lk_token)
print(creds.room_name)
```

Use `session.session_url` when you want Vaani's embeddable/shareable session URL. Use `creds.lk_url` and `creds.lk_token` when you are building your own frontend and joining LiveKit directly.

## Async Quickstart

```python
from vaani import AsyncVaaniClient

async with AsyncVaaniClient(
    api_key="your_api_key",
    base_url="https://api.vaanivoice.ai",
    timeout=30,
) as client:
    session = await client.sessions.create(agent_id="agent-uuid-or-name")
    creds = await client.sessions.connect(session.session_token)
    status = await client.sessions.get(session.session_token)
```

## Session Events

The SDK can build the WebSocket URL for server-side event listeners:

```python
import asyncio
import json

import websockets
from vaani import VaaniClient

client = VaaniClient(api_key="your_api_key")

async def listen(session_token: str) -> None:
    url = client.sessions.ws_url(session_token)
    async with websockets.connect(url) as ws:
        async for message in ws:
            event = json.loads(message)
            if event["event"] == "agent_ready":
                print("Agent is ready")
            elif event["event"] == "agent_timeout":
                print(event.get("reason"))
            elif event["event"] == "session_ended":
                print(event.get("reason"))

asyncio.run(listen("session-token"))
```

## Ending A Session

```python
# Start the configured grace period so the user can reconnect.
client.sessions.disconnect(session.session_token)

# End immediately with no grace period.
client.sessions.disconnect(session.session_token, explicit_end=True)
```

## Resources

### Sessions

| Method | Description | Returns |
| :--- | :--- | :--- |
| `client.sessions.create(...)` | Creates a WebRTC session and returns a token plus embeddable URL. | `WebRTCSession` |
| `client.sessions.connect(token)` | Exchanges the session token for LiveKit credentials and dispatches the agent for inbound sessions. | `WebRTCSessionConnect` |
| `client.sessions.get(token)` | Fetches current session state. | `WebRTCSessionStatus` |
| `client.sessions.disconnect(token, explicit_end=False)` | Marks a participant disconnect or ends the session. | `WebRTCSessionStatus` |
| `client.sessions.ws_url(token)` | Builds the WebSocket URL for real-time session events. | `str` |

### Calls

```python
call = client.calls.trigger(
    agent_id="agent-uuid-or-name",
    contact_number="+1234567890",
    name="Ayush",
    metadata={"ticket_id": "T-1234"},
)

call = client.calls.get(call.call_id)
transcript = client.calls.get_transcript(call.call_id)
calls = client.calls.list(agent_id="agent-uuid-or-name", page=1, page_size=50)
```

### Agents

```python
agents = client.agents.list()
agent = client.agents.get("agent-uuid-or-name")
```

## Response Models

`WebRTCSession`

| Field | Type |
| :--- | :--- |
| `session_token` | `str` |
| `session_url` | `str` |
| `expires_at` | `datetime` |

`WebRTCSessionConnect`

| Field | Type |
| :--- | :--- |
| `lk_url` | `str` |
| `lk_token` | `str` |
| `room_name` | `str` |

`WebRTCSessionStatus`

| Field | Type |
| :--- | :--- |
| `status` | `str` |
| `expires_at` | `datetime` |
| `ui_type` | `str` |
| `room_name` | `str` |
| `agent_id` | `str` |
| `client_id` | `str` |
| `metadata` | `dict` |
| `grace_period_ends_at` | `datetime | None` |

## Error Handling

All SDK exceptions inherit from `VaaniError`.

```python
from vaani import (
    AuthenticationError,
    ConnectionError,
    InsufficientBalanceError,
    RateLimitError,
    ServerError,
    TimeoutError,
    VaaniError,
)

try:
    session = client.sessions.create(agent_id="agent-uuid-or-name")
except AuthenticationError:
    print("Invalid API key")
except InsufficientBalanceError:
    print("Wallet balance is too low")
except RateLimitError:
    print("Too many requests")
except (TimeoutError, ConnectionError, ServerError):
    print("Vaani API is temporarily unavailable")
except VaaniError as exc:
    print(exc.message, exc.status_code)
```

## Development

```bash
uv run --extra dev pytest -q
```

## License

MIT
