Vanessa AI Agent - Real Estate Acquisition Platform

Project Overview

Vanessa AI Agent is an intelligent real estate acquisition platform that automates the process of identifying and qualifying potential property sellers through AI-powered voice calls. The system combines automated calling, machine learning lead scoring, and comprehensive analytics to optimize real estate acquisition efforts.

Key Features

AI-Powered Voice Calls

• Automated outbound calling with Twilio integration
• Interactive voice response system with TwiML
• Intelligent call flow management
• Real-time call status tracking

Machine Learning & Analytics

• Lead Scoring Algorithm (0-100 scale) based on:
  • Seller intent confirmation (40 points max)
  • Price range preferences (15-30 points)
  • Timing urgency (10-25 points)
  • Call engagement metrics (10-20 points)
  • Property condition (10-15 points)
  • Optimal calling time (5-10 points)
• Conversion Probability Prediction with 15% base rate
• Optimal Calling Time Analysis using historical data
• Market Insights and trend analysis

Analytics Dashboard

• Real-time analytics and statistics
• Interactive charts and visualizations
• ML-powered insights and recommendations
• Auto-refresh every 30 seconds
• Professional UI/UX with Tailwind CSS

Lead Management System

• Comprehensive lead tracking and management
• Status updates and progress tracking
• Lead analytics and distribution charts
• Real-time lead statistics

Technology Stack

Backend

• FastAPI (0.104.1) - Modern Python web framework
• SQLAlchemy (2.0.23) - Database ORM
• SQLite - Database (development)
• Pydantic (2.5.0) - Data validation
• Uvicorn (0.24.0) - ASGI server

Communication & AI

• Twilio (8.10.0) - Voice calling platform
• TwiML - Call flow control

Frontend

• HTML5/CSS3 - Structure and styling
• Tailwind CSS - Utility-first CSS framework
• Alpine.js - Reactive JavaScript framework
• Chart.js - Data visualization
• Font Awesome - Icon library

Machine Learning

• Pandas (2.1.3) - Data analysis
• NumPy (1.25.2) - Numerical computing
• Custom ML Service - Lead scoring algorithms

Development & Testing

• Pytest (7.4.3) - Testing framework
• HTTPX (0.25.2) - HTTP client for testing
• Python-dotenv (1.0.0) - Environment variables

Project Structure

vanessa-ai-agent/
├── app/                          # Main application package
│   ├── main.py                  # FastAPI application entry point
│   ├── api/                     # API endpoints
│   │   ├── calls.py             # Call management API
│   │   ├── leads.py             # Lead management API
│   │   └── twilio_webhooks.py   # Twilio webhook handlers
│   ├── models/                  # Data models
│   │   ├── database.py          # SQLAlchemy models
│   │   └── schemas.py           # Pydantic schemas
│   └── services/                # Business logic services
│       ├── twilio_service.py    # Twilio integration
│       ├── voice_ai.py          # AI voice service (Vapi.ai integration)
│       └── ml_service.py        # Machine learning service
├── templates/                   # HTML templates
│   ├── dashboard.html           # Main analytics dashboard
│   └── leads.html              # Leads management page
├── tests/                      # Test suite
├── requirements.txt            # Python dependencies
├── run.py                      # Application runner
└── vanessa.db                 # SQLite database

Quick Start

Prerequisites

• Python 3.10 or higher
• Twilio account with phone number
• ngrok account (for webhook development)
• Optional: Vapi.ai account (for advanced AI voice features)

Installation

# Clone the repository
git clone https://github.com/Candice0313/vanessa-ai-agent
cd vanessa-ai-agent

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your Twilio credentials

Configuration

1. Twilio Setup:

   • Get Account SID and Auth Token from Twilio Console
   • Purchase a phone number
   • Update .env file with credentials

2. ngrok Setup (for webhooks):

   • Sign up at https://ngrok.com
   • Install authtoken: ngrok authtoken <your-token>
   • Start tunnel: ngrok http 8000
   • Update BASE_URL in .env with ngrok URL

3. Vapi.ai Setup (optional, for advanced AI features):

   • Sign up at https://vapi.ai
   • Create an assistant and get API credentials
   • Update Vapi configuration in .env file

Running the Application

# Development mode
python run.py

# Or using uvicorn directly
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Access Points

• Analytics Dashboard: http://localhost:8000/
• Leads Management: http://localhost:8000/leads
• API Documentation: http://localhost:8000/docs

ML Algorithm Details

Lead Scoring (0-100 points)

• Seller Intent: 40 points (confirmed) / 0 points (denied) / 10 points (unknown)
• Price Range: 15-30 points based on property value
• Timing: 10-25 points (3 months = highest urgency)
• Call Duration: 10-20 points (longer calls = more engagement)
• Property Condition: 10-15 points
• Optimal Timing: 5-10 points for calls during best hours

Conversion Probability

• Base Rate: 15%
• Adjustments: Lead score multiplier × timing urgency multiplier
• Range: 1% - 95%

Priority Classification

• High Priority: >70 points
• Medium Priority: 40-70 points
• Low Priority: <40 points

API Endpoints

Call Management

• GET /api/calls/ - List calls
• POST /api/calls/ - Create call
• GET /api/calls/stats/summary - Call statistics
• GET /api/calls/analytics/advanced - Advanced analytics

Lead Management

• GET /api/leads/ - List leads
• PUT /api/leads/{id} - Update lead
• GET /api/leads/stats/summary - Lead statistics

ML & Analytics

• GET /api/calls/ml/lead-score/{id} - Get lead score
• GET /api/calls/ml/optimal-timing - Optimal times
• GET /api/calls/ml/market-insights - Market insights

Webhooks

• POST /api/twilio/voice - Call initiation
• POST /api/twilio/response - User responses
• POST /api/twilio/status - Call status updates
• POST /api/twilio/vapi-webhook - Vapi.ai webhook (optional)

Use Cases

Real Estate Companies

• Automated lead generation
• Qualification of potential sellers
• Market analysis and insights
• Performance tracking and optimization

Property Investors

• Systematic property acquisition
• Lead scoring and prioritization
• Market trend analysis
• ROI optimization

Call Centers

• Automated outbound calling
• Lead qualification workflows
• Performance analytics
• Agent productivity tools

Testing

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=app

# Run specific test file
pytest tests/test_api.py

Test Coverage

• Unit Tests: Individual function testing
• Integration Tests: API endpoint testing
• End-to-End Tests: Complete workflow testing

Configuration

Environment Variables

Create a .env file with the following variables:

# Database
DATABASE_URL=sqlite:///./vanessa.db

# Twilio Configuration (get these from Twilio Console)
TWILIO_ACCOUNT_SID=your_twilio_account_sid_here
TWILIO_AUTH_TOKEN=your_twilio_auth_token_here
TWILIO_PHONE_NUMBER=+1234567890
TWILIO_STUDIO_FLOW_SID=your_studio_flow_sid_here

# Optional: Vapi.ai Configuration (for advanced AI voice features)
VAPI_API_KEY=your_vapi_api_key_here
VAPI_ASSISTANT_ID=your_vapi_assistant_id_here
VAPI_PHONE_NUMBER_ID=your_vapi_phone_number_id_here

# Application
BASE_URL=https://yourdomain.com
DEBUG=False
LOG_LEVEL=INFO

Security Features

• Environment variable protection
• Input validation with Pydantic
• SQL injection prevention with SQLAlchemy
• Secure webhook handling
• Rate limiting (production ready)

File Descriptions

Core Files

• app/main.py: FastAPI application entry point and configuration
• run.py: Application runner script
• requirements.txt: Python package dependencies

API Layer

• app/api/calls.py: Call management API endpoints
• app/api/leads.py: Lead management API endpoints
• app/api/twilio_webhooks.py: Twilio webhook handlers

Data Models

• app/models/database.py: SQLAlchemy database models
• app/models/schemas.py: Pydantic schemas for validation

Services

• app/services/twilio_service.py: Twilio API integration
• app/services/ml_service.py: Machine learning and analytics
• app/services/voice_ai.py: AI voice service integration (Vapi.ai - optional)

Frontend

• templates/dashboard.html: Main analytics dashboard
• templates/leads.html: Leads management interface

Competitive Advantages

Technical Excellence

• Modern Architecture: FastAPI + SQLAlchemy + ML
• Real-time Processing: Live updates and analytics
• Scalable Design: Ready for enterprise deployment
• Comprehensive Testing: High code quality and reliability

Business Value

• Immediate ROI: Quick implementation and results
• Cost Effective: Reduces manual calling costs
• Data Driven: ML-powered insights and optimization
• User Friendly: Intuitive dashboard and management

Innovation

• AI Integration: Advanced lead scoring algorithms
• Real-time Analytics: Live performance monitoring
• Automated Workflows: End-to-end process automation
• Market Intelligence: Predictive analytics and insights