Metadata-Version: 2.4
Name: autodial
Version: 0.6.0
Summary: A self-hosted automated outbound dialer phone bot
Author: Autodial Maintainers
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: python-dotenv
Requires-Dist: twilio
Requires-Dist: faster-whisper
Requires-Dist: aiohttp
Requires-Dist: numpy
Requires-Dist: pydantic
Requires-Dist: requests

# 📞 Autodial PhoneBot: Self-Hosted AI Dialer

[![PyPI version](https://badge.fury.io/py/autodial.svg)](https://badge.fury.io/py/autodial)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Autodial** is a production-grade, self-hosted outbound and inbound phone automation engine. It leverages state-of-the-art Local Speech-to-Text (STT), Large Language Models (LLM), and Local Text-to-Speech (TTS) to create intelligent, human-like phone interactions.

Built for high-performance automation, Autodial can handle inbound calls gracefully, navigate IVR menus, handle complex DTMF interactions, execute mass broadcasts, and notify your external systems via webhooks upon call conclusion. It natively supports both **Twilio** and **Telnyx**.

---

## 🚀 Key Features

*   **Bidirectional Calling**: Make automated outbound calls via Python or handle inbound calls instantly by pointing your Twilio/Telnyx webhook to the `/incoming` endpoint.
*   **Provider Agnostic**: Native auto-detection and WebSocket formatting for both Twilio and Telnyx media streams. Fixes all edge-case payload validation errors out of the box.
*   **Multi-Concurrent Interaction**: Built on FastAPI and Python's `asyncio`, handling dozens of simultaneous Media Streams with low overhead.
*   **Local Transcription Engine**: Powered by `Faster-Whisper` (STT). Optimized for GPU (RTX series) with automatic CPU fallback.
*   **Dynamic AI Personalities**: Inject per-call context, goals, and keywords. The AI intelligently adapts its persona and strategy for every unique target.
*   **Developer-Defined Guardrails**: Set strict `system_instructions` to keep calls on track and ensure brand-safe communication.
*   **Intelligent Call Termination**: Built-in intent recognition for phrases like "stop calling me" or "goodbye," ensuring polite and immediate hang-ups.
*   **Broadcast & Direct Messaging**: Need to send a simple notification? Use Broadcast Mode to play a direct message and disconnect immediately.
*   **Automated Call Logs & Webhooks**: Every call generates a detailed JSON transcript. Configure a `callback_url` to receive data as soon as the session ends.

---

## 🛠 Prerequisites & Installation

### Core Requirements
1.  **Ollama**: Serving a chat-ready model (e.g., `llama3.2`) at a reachable URL.
2.  **Piper TTS**: The `piper` binary should be in your system PATH, along with its `.onnx` models.
3.  **Twilio or Telnyx**: An active Account SID/API Key, Auth Token, and a verified Phone Number.

### System Install
```bash
pip install autodial
```

---

## ⚙️ Configuration

Autodial consumes configuration via environment variables. Create a `.env` file in your execution directory:

```env
PORT=8000
TWILIO_ACCOUNT_SID=your_sid_here
TWILIO_AUTH_TOKEN=your_token_here
TWILIO_PHONE_NUMBER=+1234567890

# --- LLM Provider Selection ---
# Options: ollama (default), openai, gemini, mistral
LLM_PROVIDER=ollama
LLM_MODEL=llama3.2:3b

# Local Ollama URL (used if provider is ollama)
OLLAMA_CHAT_URL=http://localhost:11434/api/chat

# Cloud API Keys (Required depending on provider choice)
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AIza...
MISTRAL_API_KEY=...

# --- Local TTS Settings ---
PIPER_MODEL=./en_US-lessac-medium.onnx
```

---

## 🖥 Start the Server

Launch the Autodial engine with a single command:

```bash
autodial
```
*Note: The server will initialize Whisper on your GPU if available (CUDA), otherwise it fallbacks to CPU.*

---

## 🗣 Natural Language CLI

You don't have to write Python code to place intelligent calls. Autodial includes a powerful NLP-driven CLI that translates plain English into API actions!

Ensure your Autodial server is running in the background, then simply type:

```bash
autodial call bob at 613-444-0101 and ask how his day is going
```

The CLI uses your local LLM to instantly extract the target phone number, the conversation context, and the goals, and then dispatches the call automatically.

---

## 🐍 Python Client Usage

The library includes a professional `AutodialClient` to make programmatic orchestration seamless.

```python
from autodial import AutodialClient

# Connect to your Autodial instance
client = AutodialClient("http://localhost:8000")

# Scenario: Appointment Reminder with Guardrails
client.dial(
    target_number="+15551234567",
    context="Reminder for Dr. Smith's clinic",
    goals="Confirm the 2:00 PM slot today",
    system_instructions="Always be polite. If the user is busy, offer to call back later.",
    callback_url="https://api.yourclinic.com/webhooks/call-results"
)

# Scenario: Emergency Alert Broadcast
client.broadcast(
    numbers=["+15550001", "+15550002", "+15550003"],
    message="This is an automated alert from the city. Please evacuate immediately.",
    callback_url="https://api.city.gov/logs"
)
```

---

## 📞 Handling Inbound Calls (Bidirectional)

Autodial isn't just for outbound dialing. It exposes an `/incoming` REST endpoint that automatically generates the required TwiML/TeXML to connect callers to your AI bot.

**Setup Instructions:**
1. Log in to your Twilio or Telnyx Console.
2. Navigate to your active Phone Number settings.
3. Find the **Webhook URL** for incoming calls.
4. Set it to `POST https://your-autodial-server.com/incoming`

When a user dials your number, the provider hits the endpoint, receives the Media Stream instruction, and the AI connects automatically using the base `SYSTEM_PROMPT`.

---

## 📡 API Reference

### `POST /dial`
Initiates a single interactive AI session.

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `to_number` | `string` | **Required**. The target phone number in E.164 format. |
| `context` | `string` | Detailed background info for the AI to understand the call's nature. |
| `goals` | `string` | Specific outcomes or data points the AI should strive to achieve. |
| `keywords` | `string` | Focus phrases for the transcription engine to prioritize. |
| `system_instructions` | `string` | High-priority guardrails and behavioral rules for the session. |
| `callback_url` | `string` | POST endpoint to receive the final JSON transcript and status. |

### `POST /incoming`
A webhook endpoint for Twilio/Telnyx. Do not call this manually. It automatically returns `<Connect><Stream .../>` XML to start a bidirectional session.

---

## 🛡 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ by the Autodial Maintainers.
