AI Receptionist

A local, real-time voice agent for small businesses. Handles calls, books appointments, answers FAQs — no cloud dependency.

Pipeline: Mic → VAD → Whisper (STT) → Ollama (LLM) → Piper (TTS) → Speaker

Structure

receptionist/
├── config.py       ← settings (.env)
├── main.py         ← entry point
├── api/            ← FastAPI web UI + WebSocket
├── audio/          ← mic capture, VAD, playback
├── stt/            ← Whisper
├── llm/            ← Ollama client + prompt builder
├── tts/            ← Piper synthesiser
├── tools/          ← appointment booking, FAQ lookup
├── session/        ← conversation history
├── data/           ← CSV appointment store
└── pipeline/       ← main orchestration loop

Setup

python -m venv .venv
source .venv/bin/activate

pip install torch --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt

ollama pull gemma3:4b
cp .env.example .env   # edit business name, model paths, etc.

Run

CLI (mic/speaker):

python -m receptionist.main

Web UI:

python -m receptionist.api.server
# open http://localhost:8000

Key Settings (.env)

Variable	Default	Notes
WHISPER_MODEL_SIZE	small	tiny / base / small / medium / large-v3
OLLAMA_MODEL	gemma3:4b	any Ollama-compatible model
VAD_THRESHOLD	0.5	speech detection sensitivity
BUSINESS_NAME	Sunrise Dental	shown in prompts/UI

Real Phone Calls with Twilio

The system includes built-in support for Twilio Media Streams for incoming and outgoing real phone calls.

Setup Instructions

1. Expose your local FastAPI server to the internet using ngrok:

   ngrok http 8000

   Copy your public forwarding domain (e.g. abc1234.ngrok-free.app).

2. Configure your .env file:

   TWILIO_ACCOUNT_SID=ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   TWILIO_AUTH_TOKEN=your_auth_token_here
   TWILIO_PHONE_NUMBER=+18885550199
   TWILIO_PUBLIC_HOST=abc1234.ngrok-free.app

3. Configure Webhook in Twilio Console:

   • Go to Twilio Console → Phone Numbers → Manage → Active numbers.
   • Click on your Twilio Phone Number.
   • Under A CALL COMES IN, set:
     • Webhook: https://abc1234.ngrok-free.app/api/twilio/voice
     • HTTP Method: HTTP POST
   • Save configuration.

4. Test Real Inbound Phone Call:

   • Call your Twilio phone number from your mobile phone!

5. Test Outbound Phone Call (API):

   curl -X POST http://localhost:8000/api/twilio/call \
     -H "Content-Type: application/json" \
     -d '{"to_number": "+1234567890"}'

License

Proprietary — All rights reserved. This code is not licensed for reuse, redistribution, or modification without permission.