Metadata-Version: 2.4
Name: voicemaster
Version: 0.1.0
Summary: Real-time AI phone calls: Gemini Live bridged to Vobiz and Twilio, with call reports, tools and knowledge search.
Author: Rahul Wale
Keywords: voice,phone,gemini,gemini-live,vobiz,twilio,ai-calling,telephony
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Topic :: Communications :: Telephony
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1,>=0.141.1
Requires-Dist: uvicorn[standard]<1,>=0.52.4
Requires-Dist: aiohttp<4,>=3.14.3
Requires-Dist: google-genai<2,>=1.75.0
Requires-Dist: loguru<1,>=0.7.3
Requires-Dist: tzdata>=2025.2
Provides-Extra: test
Requires-Dist: httpx; extra == "test"

# voicemaster

Real-time AI phone calls. A caller (or a person being called) talks to a Gemini Live assistant over a Vobiz or Twilio phone
line. The library is the whole calling engine: the HTTP routes the telephony provider calls, the live audio stream in both
directions, the Gemini Live session, the tools the assistant may use (end the call, transfer it, search the customer's
documents), and the signed reports of how each call went.

```bash
pip install voicemaster
python -m voicemaster.server        # Vobiz at /vobiz/..., Twilio at /twilio/..., one port (PORT, default 8760)
```

## Settings (environment variables)

| Variable | Default | Meaning |
|---|---|---|
| `PUBLIC_URL` | – | This server's public address **ending in `/vobiz`** (Vobiz). |
| `TWILIO_PUBLIC_URL` | – | The same, **ending in `/twilio`** (Twilio). |
| `API_TOKEN` | empty | If set, `POST /start` and `POST /calls/{id}/config` need the header `x-api-token`. |
| `EVENTS_URL`, `EVENTS_SECRET` | empty | Where call reports go, and the secret that signs them (HMAC-SHA256). |
| `KNOWLEDGE_SEARCH_URL` | derived from `EVENTS_URL` | Where the `search_knowledge` tool asks for passages. |
| `MAX_CONCURRENT_CALLS` | 10 | Calls accepted at once. |
| `RECORD_CALLS`, `RECORD_FORMAT`, `RECORD_MAX_LENGTH_SECONDS` | false, mp3, 300 | Recording (a call is recorded only if this *and* the call both ask). |
| `GEMINI_LIVE_MODEL` | `gemini-3.1-flash-live-preview` | The Gemini Live model. |
| `TIME_CONTEXT_TIMEZONE` | `Asia/Kolkata` | Time zone of the "what time is it" line given to the model. |
| `LOG_LEVEL`, `LOG_DIR` | INFO, `logs` | Logging; files rotate at 50 MB and are kept 14 days. |

The library never loads a `.env` file; load it yourself (`dotenv.load_dotenv()`) before importing `voicemaster`.
Calling credentials (Vobiz / Twilio accounts, the Gemini key, the assistant's prompt) arrive **per call**, never from settings.

## Building blocks

```python
from voicemaster.request import VOBIZ, parse_call_request     # check a POST /start body
from voicemaster.tools import build_tools                      # end_call / transfer_call / search_knowledge
from voicemaster.live import live_config                       # the Gemini Live settings for a call
from voicemaster.call_events import sign                       # the HMAC signature of a report
```

See `voicemaster/__init__.py` for the full map of modules.
