Skip to main content

​
Overview

The Chat API provides a conversational interface powered by Google Gemini for querying tracking data using natural language. The AI agent has access to tools that query movements, drivers, tractors, and trailers from the database. AI Model: Google Gemini (configurable via GEMINI_MODEL environment variable) Service: ChatAgentService singleton

​
Send Chat Message

​
POST /api/chat

Send a natural language message to the AI agent and receive a response. Request Body: 
{
  "message": "How many drivers named Charles are on an active movement?",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}
FieldTypeRequiredDescription
messagestringYesNatural language query or message
session_idstringNoSession ID for conversation continuity. If not provided, a new session is created.
Response: 
{
  "response": "I found 2 drivers named Charles on active movements. Charles Robinson is on movement 762965 going to Dallas, and Charles Smith is on movement 762966 going to Austin.",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "tool_calls": [
    {
      "tool": "get_drivers_tool",
      "args": {}
    },
    {
      "tool": "get_movements_tool",
      "args": {"status": "P"}
    }
  ]
}
FieldTypeDescription
responsestringAI-generated response text
session_idstringSession ID (use for follow-up messages)
tool_callsarrayList of tools called by the AI, or null if none
errorstringError code if request failed (e.g., quota_exceeded)
Error Response (Quota Exceeded): 
{
  "response": "The AI assistant is currently experiencing high usage. Please try again in about a minute.",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "tool_calls": null,
  "error": "quota_exceeded"
}

​
How It Works

​
1. Message Processing

  1. Session Management: Gets or creates a chat session for conversation continuity
  2. Message Send: Sends user message to Gemini model
  3. Function Calling Loop: Executes up to 10 function calls to gather data
  4. Response Generation: Gemini generates natural language response from tool results

​
2. Available Tools

The AI agent has access to these database query tools:
Description: Get movements (shipments/loads) with nested stops from database.Parameters:
  • status (optional): Status filter (e.g., "P" for Progress/active)
  • limit (optional): Maximum movements to return (default: 100)
Data Source: Queries movements table with LEFT JOIN to movement_stops and tractors
Description: Get drivers snapshot from database with location, HOS status, and contact information.Parameters:
  • limit (optional): Maximum drivers to return
  • since (optional): ISO 8601 timestamp filter
Data Source: Queries drivers table via get_drivers_snapshot()
Description: Get tractors (trucks/power units) from database with location and speed.Parameters:
  • limit (optional): Maximum tractors to return
Data Source: Queries tractors table via get_latest_vehicle_locations()
Description: Get trailers from database with location and metadata.Parameters:
  • limit (optional): Maximum trailers to return
Data Source: Queries trailers2 table via get_latest_trailer_locations()
Description: Check if a driver is currently on an active movement by searching by name.Parameters:
  • driver_name (required): Driver name to search (partial match, case-insensitive)
Data Source: Cross-references drivers and movements tables
Description: Get movements with stops in a specific state (optimized query).Parameters:
  • state (required): Two-letter state code (e.g., "CA", "TX")
  • status (optional): Movement status filter (default: "P")
Data Source: Queries movements JOIN movement_stops with state filter
Description: Get driver names from McLeod API by driver IDs.Parameters:
  • driver_ids (required): Comma-separated McLeod driver IDs (e.g., "S9932,S8170")
Data Source: Calls McLeod API /v1/driver?id={driver_id} for each ID

​
3. Multi-Step Reasoning

The AI agent can make multiple tool calls to answer complex questions. Examples: Query: “How many drivers named Charles are on a movement?” Steps:
  1. get_drivers_tool() → Get all drivers
  2. Filter results for “Charles” in name
  3. get_movements_tool(status='P') → Get active movements
  4. Cross-reference driver source_id with movement __driverids
  5. Report matches
Query: “Where is the tractor on movement 12345?” Steps:
  1. get_movements_tool() → Find movement 12345
  2. Extract tractor_id from movement
  3. get_tractor_by_mcleod_id_tool(tractor_id) → Get tractor location
  4. Report location

​
Example Queries

Here are example natural language queries the AI can answer:
QueryTools Used
”How many active movements are there?”get_movements_tool
”Where is driver John Smith?”get_drivers_tool
”What tractors have fault codes?”get_tractors_tool, get_tractor_fault_codes_tool
”Which movements are going to California?”get_movements_by_destination_state_tool
”Is Charles on a movement right now?”check_driver_on_movement_tool
”What’s the status of movement 762965?”get_movements_tool
”How many trailers are in Texas?”get_trailers_tool
”List all drivers on movements to NY”get_movements_by_destination_state_tool, get_driver_names_from_mcleod_tool

​
Session Management

​
Clear Session

​
DELETE /api/chat/session/

Clear a specific chat session and its history. Response: 
{
  "success": true,
  "message": "Session cleared"
}

​
Get Session Stats

​
GET /api/chat/stats

Get statistics about active chat sessions. Response: 
{
  "active_sessions": 5,
  "model": "gemini-1.5-pro"
}

​
Configuration

Environment VariableDefaultDescription
GEMINI_API_KEY(required)Google Gemini API key
GEMINI_MODELgemini-1.5-proGemini model to use

​
Rate Limiting

The Gemini API has rate limits. If quota is exceeded, the response will include: 
{
  "error": "quota_exceeded",
  "response": "The AI assistant is currently experiencing high usage. Please try again in about a minute."
}
Recommendation: Implement client-side retry with exponential backoff when receiving this error.