Skip to main content

​
Prerequisites

Before installing Sonore Phone Agent, ensure you have the following:
  • Python 3.12 or higher - The application requires Python 3.12+
  • uv - Fast Python package installer and resolver (installation guide)
  • MongoDB - Database for storing call transcripts and metadata
  • OpenAI API Key - For AI-powered call handling

​
Installation Steps

1

Clone the repository

Clone the Sonore Phone Agent repository to your local machine:
git clone https://github.com/your-org/sonore-phone-agent.git
cd sonore-phone-agent
2

Install dependencies

Use the uv package manager to install all dependencies:
make sync
This command runs uv sync --dev, which installs both production and development dependencies defined in pyproject.toml.Core dependencies installed:
  • fastapi - Web framework for building APIs
  • uvicorn - ASGI server for running the application
  • pydantic - Data validation and settings management
  • pymongo - MongoDB driver for Python
  • openai - OpenAI Python SDK
  • httpx - HTTP client for async requests
  • phonenumbers - Phone number parsing and validation
3

Configure environment variables

Create a .env file in the project root with your configuration:
# General settings
APP_ENV=prod
LOG_LEVEL=INFO
DEBUG=false

# Database
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB=sonore_phone_agent
MONGODB_TRANSCRIPTS_COLLECTION=calls-transcripts
MONGODB_METADATA_COLLECTION=calls-metadata

# OpenAI configuration
OPENAI_API_KEY=sk-...
OPENAI_PROJECT_ID=proj_...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_SUMMARY_MODEL=gpt-4o-mini
OPENAI_SIP_MODEL=gpt-realtime
OPENAI_WS_REALTIME_MODEL=gpt-realtime-mini
OPENAI_WS_URL=wss://api.openai.com/v1/realtime?

# Security
ADMIN_TOKEN=your-secure-admin-token
OPENAI_WEBHOOK_SECRET=your-webhook-secret

# Application settings
DEFAULT_VOICE=marin
VOICE_SPEED=1.0
MAX_OUTPUT_TOKENS=4096
MAX_CONCURRENT_CALLS=100
TOOL_CHOICE=auto

# Instructions
INSTRUCTIONS_FILE=baseline.md
GREETING_FILE=greeting.md

# Service URIs
POST_CALL_URI=http://127.0.0.1:8001
CALLS_URI=http://localhost:8000/

# SMTP email settings (optional)
SMTP_SERVER=smtp.mail.me.com
SMTP_PORT=587
SMTP_USER=
SMTP_PW=
SMTP_FROM=
SMTP_TO=
SMTP_BCC=
The application validates that OPENAI_API_KEY, OPENAI_PROJECT_ID, and OPENAI_WS_URL are set when APP_ENV is not test. Missing required variables will cause a startup error.
4

Verify installation

Run the test suite to ensure everything is set up correctly:
make test
This runs the pytest test suite with quiet output.

​
Running the Application

​
Development Mode

For local development with auto-reload: 
./start.sh
The start.sh script launches both services:
  • Calls service on port 8000 (or $PORT) - Public-facing API for handling inbound calls
  • Post-call service on port 8001 (or $POSTCALL_PORT) - Internal service for post-call processing

​
Production Mode

For production deployments, use the individual startup scripts: 
# Start calls service (public)
./start_call.sh

# Start post-call service (internal)
./start_postcall.sh
The post-call service in start.sh binds to 127.0.0.1 (localhost only), while start_postcall.sh binds to 0.0.0.0. Ensure proper network security when deploying to production.

​
Service Endpoints

Once running, the services are available at:
  • Calls API: http://localhost:8000
  • Health check: http://localhost:8000/health
  • API documentation: http://localhost:8000/docs
  • Post-call API: http://localhost:8001

​
Development Tools

​
Code Quality

The project includes several make targets for code quality: 
# Format code with Black
make format

# Check formatting without changes
make format-check

# Run linter (Ruff)
make lint

# Auto-fix linting issues
make lint-fix

# Run both format-check and lint
make check

​
Testing

# Run test suite
make test

# Run tests with coverage
uv run pytest --cov=src tests/

​
Exposing Local Development

To expose your local development server for testing with external services: 
make ngrok
This starts an ngrok tunnel on port 8000.

​
Troubleshooting

​
Common Issues

Ensure MongoDB is running and accessible at the URI specified in MONGODB_URI. Check that:
  • MongoDB service is running: systemctl status mongod or brew services list
  • The connection string is correct
  • Network/firewall allows the connection
Verify that:
  • OPENAI_API_KEY is set and valid
  • OPENAI_PROJECT_ID is correct for your organization
  • Your API key has access to the specified models
If ports 8000 or 8001 are already in use, set custom ports:
PORT=8080 POSTCALL_PORT=8081 ./start.sh
Ensure dependencies are installed:
make sync
If issues persist, try removing the virtual environment and reinstalling:
rm -rf .venv
make sync

​
Next Steps

Docker Deployment

Deploy with Docker and Docker Compose

Monitoring

Set up logging and metrics

Build docs developers (and LLMs) love

Get started for freeTalk to us