Metadata-Version: 2.4
Name: autodial
Version: 0.3.1
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 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 navigate IVR menus, handle complex DTMF interactions, execute mass broadcasts, and notify your external systems via webhooks upon call conclusion.

---

## 🚀 Key Features

*   **Multi-Concurrent Interaction**: Built on FastAPI and Python's `asyncio`, handling dozens of simultaneous Twilio 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**: An active Account SID, Auth Token, and a verified outbound 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
OLLAMA_CHAT_URL=http://localhost:11434/api/chat
LLM_MODEL=llama3.2:3b
PIPER_MODEL=./en_US-lessac-medium.onnx

TWILIO_ACCOUNT_SID=your_sid_here
TWILIO_AUTH_TOKEN=your_token_here
TWILIO_PHONE_NUMBER=+1234567890
```

---

## 🖥 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.*

---

## 🐍 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"
)
```

---

## 📡 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. |

---

## 🛡 License

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

---

Built with ❤️ by the Autodial Maintainers.
