HVAC Service Dispatch Agent Fleet

How It Works

1. 1
   Extract Daily Jobs

   Query ServiceTitan API for all pending jobs scheduled for current day, including job locations, priority levels, estimated duration, and required technician skills

   ServiceTitan REST API
2. 2
   Retrieve Technician Data

   Fetch available technicians with their skill sets, work hours, and current location/assignments from ServiceTitan scheduling module

   ServiceTitan REST API
3. 3
   Calculate Route Matrix

   Send all job locations to Google Maps Distance Matrix API to get travel times and distances between all location pairs, accounting for current traffic conditions

   Google Maps Distance Matrix API
4. 4
   Optimize Assignments

   Run optimization algorithm considering job priority, technician skills, travel time, and working hours to generate optimal daily routes for each technician

   Python optimization library
5. 5
   Update Schedules

   Push optimized job assignments and route sequences back to ServiceTitan, updating technician schedules and job dispatch times

   ServiceTitan REST API

Implementation

```bash
# Create project structure
mkdir coolbreeze-dispatcher
cd coolbreeze-dispatcher
mkdir src config logs data

# Install dependencies
pip install requests googlemaps python-dotenv schedule pandas numpy

# Environment variables (.env)
SERVICETITAN_API_KEY=your_api_key
SERVICETITAN_BASE_URL=https://api.servicetitan.com
GOOGLE_MAPS_API_KEY=your_maps_key
LOG_LEVEL=INFO
DISPATCH_START_LOCATION=company_address

# Main dispatcher (src/smart_dispatcher.py)
import os, requests, googlemaps, json
from datetime import datetime, timedelta
from dataclasses import dataclass
from typing import List, Dict

@dataclass
class Job:
    id: str
    location: str
    priority: int
    duration_hours: float
    required_skills: List[str]

class SmartDispatcher:
    def __init__(self):
        self.st_client = ServiceTitanClient()
        self.gmaps = googlemaps.Client(key=os.getenv('GOOGLE_MAPS_API_KEY'))
        
    def run_daily_optimization(self):
        jobs = self.st_client.get_todays_jobs()
        technicians = self.st_client.get_available_techs()
        
        # Build distance matrix
        locations = [job.location for job in jobs]
        matrix = self.gmaps.distance_matrix(locations, locations, mode='driving')
        
        # Run optimization
        assignments = self.optimize_routes(jobs, technicians, matrix)
        
        # Update ServiceTitan
        for tech_id, job_list in assignments.items():
            self.st_client.update_technician_schedule(tech_id, job_list)
            
class ServiceTitanClient:
    def __init__(self):
        self.base_url = os.getenv('SERVICETITAN_BASE_URL')
        self.headers = {'Authorization': f'Bearer {os.getenv("SERVICETITAN_API_KEY")}'}
    
    def get_todays_jobs(self):
        today = datetime.now().strftime('%Y-%m-%d')
        response = requests.get(f'{self.base_url}/jobs?scheduledDate={today}', headers=self.headers)
        return [Job(**job) for job in response.json()['data']]

# Setup cron job
# crontab -e
# 0 5 * * * cd /path/to/coolbreeze-dispatcher && python src/smart_dispatcher.py >> logs/dispatcher.log 2>&1

if __name__ == '__main__':
    dispatcher = SmartDispatcher()
    dispatcher.run_daily_optimization()
```

Data Flow

Prerequisites

• -ServiceTitan API credentials with scheduling write access
• -Google Maps API key with Distance Matrix API enabled
• -Server with reliable 5am cron execution
• -Python environment with optimization libraries

Error Handling