phone-agent-keiko-tv

What it is

This project implements an automated phone customer service agent. It combines a Python backend for call logic and contact management with a lightweight web interface. The system normalizes caller IDs, stores lead information in a local SQLite database, and uses an FSM (Finite State Machine) bridge to handle complex conversational states like scheduling, falling back to basic LLM responses if the FSM service is unavailable.

Features

• Automated inbound call handling with AI-driven conversation logic
• SQLite-backed contact database for caller ID lookup and lead capture
• Phone number normalization for consistent North American formatting
• Integration with FSM-generic for state-aware scheduling and tool use
• Real-time web UI for monitoring agent status and interactions
• Graceful fallback mechanisms when external FSM services are unavailable

Quickstart

pip install -e .
python -m phone_agent

Architecture

flowchart TD
    Caller[Inbound Call] --> Telephony[Telephony Gateway]
    Telephony --> Server[Python Server]
    Server --> ContactsDB[(SQLite Contacts DB)]
    Server --> FSMBridge[FSM Bridge]
    FSMBridge --> FSMGeneric[FSM-Generic Service]
    FSMBridge --> LLM[Fallback LLM]
    Server --> WebUI[Real-time Web UI]
    Admin[Admin User] --> WebUI

How it's built

The core logic is written in Python, utilizing `sqlite3` for persistent contact storage and `httpx` for asynchronous HTTP communication with external AI/FSM services. The entry point is a standard Python module (`__main__.py`) that launches a server. A minimal JavaScript snippet handles frontend authentication visibility. The architecture separates concerns into contact management (`contacts.py`), conversation bridging (`fsm_bridge.py`), and server orchestration.

How it runs

sequenceDiagram
    participant C as Caller
    participant S as Phone Agent Server
    participant DB as Contacts DB
    participant B as FSM Bridge
    participant F as FSM-Generic
    
    C->>S: Initiate Call
    S->>DB: Lookup/Normalize Phone Number
    DB-->>S: Return Contact Info
    S->>B: Process Conversation Input
    alt FSM Available
        B->>F: Send State/Context
        F-->>B: Return Action/Response
    else FSM Unavailable
        B->>B: Fallback to Basic LLM
    end
    B-->>S: Return Spoken Response
    S->>C: Play Audio Response
    S->>DB: Update Lead Status/Notes

How to apply & reuse

Deploy this as a backend service for handling inbound customer support calls. Use it to automatically capture lead details, normalize phone numbers for CRM consistency, and manage appointment scheduling conversations without human intervention. It is suitable for small-to-medium businesses needing 24/7 initial triage.

At a glance