flow.md

● 🔄 Complete Function Flow

  Input: "Create an order for John Doe at 123 Main St, San 
  Francisco"

  Let me trace every single function call with this exact example!      

  ---
  📞 FUNCTION CALL SEQUENCE:

  STEP 1: User Clicks Send Button

  FILE: ui/app.py
  LINE: 448-452

  User clicks "Send" button in Gradio UI
      ↓
  FUNCTION CALLED: send_message(message, conv_state)
      message = "Create an order for John Doe at 123 Main St, San       
  Francisco"
      conv_state = ConversationManager object

  Function Code:
  def send_message(message, conv_state):
      """Handle send button click"""
      chat_history, tools, new_state = handle_chat_message(message,     
  conv_state)
      #                                 ↑
      #                                 CALLS THIS NEXT
      return chat_history, tools, new_state, ""

  ---
  STEP 2: handle_chat_message()

  FILE: ui/app.py
  LINE: 223-241

  FUNCTION: handle_chat_message(message, conversation_state)
      message = "Create an order for John Doe at 123 Main St, San       
  Francisco"
      conversation_state = ConversationManager object

  Function Code:
  def handle_chat_message(message, conversation_state):
      if not message.strip():
          return ...

      # Process message through chat engine
      response, tool_calls = chat_engine.process_message(message,       
  conversation_state)
      #                      ↑
      #                      CALLS THIS NEXT

      # Return updated UI
      return conversation_state.get_formatted_history(),
  conversation_state.get_tool_calls(), conversation_state

  ---
  STEP 3: chat_engine.process_message()

  FILE: chat/chat_engine.py
  LINE: 58-73

  FUNCTION: ChatEngine.process_message(user_message, conversation)      
      user_message = "Create an order for John Doe at 123 Main St,      
  San Francisco"
      conversation = ConversationManager object

  Function Code:
  def process_message(self, user_message, conversation):
      """Process user message and return AI response"""
      return self.provider.process_message(user_message,
  conversation)
      #      ↑
      #      self.provider = GeminiProvider (from chat_engine.py:26)    
      #      CALLS GeminiProvider.process_message() NEXT

  ---
  STEP 4: GeminiProvider.process_message()

  FILE: chat/providers/gemini_provider.py
  LINE: 173-212

  FUNCTION: GeminiProvider.process_message(user_message,
  conversation)
      user_message = "Create an order for John Doe at 123 Main St,      
  San Francisco"
      conversation = ConversationManager object

  Function Code:
  def process_message(self, user_message, conversation):
      """Process user message with Gemini"""
      if not self.api_available:
          return self._handle_no_api(), []

      # Lazy initialization on first use
      self._ensure_initialized()  # ← CALLS THIS if not initialized     

      if not self._initialized:
          return "⚠️ Failed to initialize...", []

      try:
          # Build conversation history for Gemini
          chat =
  self.model.start_chat(history=self._convert_history(conversation))    
          #                                      ↑
          #                                      CALLS
  _convert_history()

          # Send message and get response
          response = chat.send_message(user_message,
  safety_settings={...})
          #          ↑
          #          🌐 API CALL TO GOOGLE GEMINI
          #          Sends: "Create an order for John Doe at 123        
  Main St, San Francisco"

          # Add user message to conversation
          conversation.add_message("user", user_message)

          # Process response and handle function calls
          return self._process_response(response, conversation,
  chat)
          #      ↑
          #      CALLS THIS NEXT

  ---
  STEP 5: Gemini API Processes Request

  🌐 GOOGLE GEMINI API (External)

  RECEIVES:
  - System Prompt: "You are an AI assistant for FleetMind..."
  - User Message: "Create an order for John Doe at 123 Main St, San     
  Francisco"
  - Available Tools: [geocode_address, create_order]

  AI ANALYZES:
  "User wants to create an order. I have:
   ✅ Customer Name: John Doe
   ✅ Address: 123 Main St, San Francisco
   ❌ GPS Coordinates: Missing!

   DECISION: Call geocode_address tool first to get coordinates."       

  RETURNS TO CODE:
  response = {
      candidates: [{
          content: {
              parts: [{
                  function_call: {
                      name: "geocode_address",
                      args: {
                          "address": "123 Main St, San Francisco"       
                      }
                  }
              }]
          }
      }]
  }

  ---
  STEP 6: _process_response() - Detects Function Call

  FILE: chat/providers/gemini_provider.py
  LINE: 226-393

  FUNCTION: _process_response(response, conversation, chat)
      response = Response from Gemini with function_call
      conversation = ConversationManager object
      chat = Gemini chat session

  Function Code:
  def _process_response(self, response, conversation, chat):
      """Process Gemini's response and handle function calls"""
      tool_calls_made = []

      try:
          # Check ALL parts for function calls
          parts = response.candidates[0].content.parts
          logger.info(f"Processing response with {len(parts)}
  part(s)")
          #            ↑
          #            LOGS: "Processing response with 1 part(s)"       

          for part in parts:
              if hasattr(part, 'function_call'):
                  fc = part.function_call
                  if fc and hasattr(fc, 'name') and fc.name:
                      has_function_call = True
                      logger.info(f"Detected function call:
  {fc.name}")
                      #            ↑
                      #            LOGS: "Detected function call:       
  geocode_address"
                      break

          if has_function_call:
              # Handle function calls (potentially multiple in
  sequence)
              current_response = response
              max_iterations = 10

              for iteration in range(max_iterations):  # ← LOOP
  STARTS
                  # Extract function call details
                  first_part =
  current_response.candidates[0].content.parts[0]
                  function_call = first_part.function_call
                  function_name = function_call.name  #
  "geocode_address"
                  function_args = dict(function_call.args)  #
  {"address": "123 Main St, San Francisco"}

                  logger.info(f"Gemini executing function:
  {function_name} (iteration {iteration + 1})")
                  #            ↑
                  #            LOGS: "Gemini executing function:        
  geocode_address (iteration 1)"

                  # Execute the tool
                  tool_result = execute_tool(function_name,
  function_args)
                  #             ↑
                  #             CALLS execute_tool() NEXT

  ---
  STEP 7: execute_tool() - Routes to Handler

  FILE: chat/tools.py
  LINE: 92-118

  FUNCTION: execute_tool(tool_name, tool_input)
      tool_name = "geocode_address"
      tool_input = {"address": "123 Main St, San Francisco"}

  Function Code:
  def execute_tool(tool_name, tool_input):
      """Route tool execution to appropriate handler"""
      try:
          if tool_name == "geocode_address":
              return handle_geocode_address(tool_input)
              #      ↑
              #      CALLS THIS NEXT
          elif tool_name == "create_order":
              return handle_create_order(tool_input)
          else:
              return {"success": False, "error": f"Unknown tool:        
  {tool_name}"}
      except Exception as e:
          logger.error(f"Tool execution error ({tool_name}): {e}")      
          return {"success": False, "error": str(e)}

  ---
  STEP 8: handle_geocode_address()

  FILE: chat/tools.py
  LINE: 121-150

  FUNCTION: handle_geocode_address(tool_input)
      tool_input = {"address": "123 Main St, San Francisco"}

  Function Code:
  def handle_geocode_address(tool_input):
      """Execute geocoding tool"""
      address = tool_input.get("address", "")  # "123 Main St, San      
  Francisco"

      if not address:
          return {"success": False, "error": "Address is required"}     

      logger.info(f"Geocoding address: {address}")
      #            ↑
      #            LOGS: "Geocoding address: 123 Main St, San
  Francisco"

      result = geocoding_service.geocode(address)
      #        ↑
      #        CALLS geocoding_service.geocode() NEXT

      return {
          "success": True,
          "latitude": result["lat"],
          "longitude": result["lng"],
          "formatted_address": result["formatted_address"],
          "confidence": result["confidence"],
          "message": f"Address geocoded successfully
  ({result['confidence']})"
      }

  ---
  STEP 9: GeocodingService.geocode()

  FILE: chat/geocoding.py
  LINE: 28-65

  FUNCTION: GeocodingService.geocode(address)
      address = "123 Main St, San Francisco"

  Function Code:
  def geocode(self, address):
      """Geocode an address to coordinates"""
      if not address:
          return self._error_response("Address is required")

      # Use mock or real API
      if self.use_mock:  # True (no HERE_API_KEY configured)
          return self._geocode_mock(address)
          #      ↑
          #      CALLS THIS NEXT
      else:
          return self._geocode_here(address)

  ---
  STEP 10: _geocode_mock() - Returns Coordinates

  FILE: chat/geocoding.py
  LINE: 52-70

  FUNCTION: _geocode_mock(address)
      address = "123 Main St, San Francisco"

  Function Code:
  def _geocode_mock(self, address):
      """Mock geocoding using city detection"""
      address_lower = address.lower()

      # Try to detect city in address
      for city_name, (lat, lng) in CITY_COORDINATES.items():
          if city_name in address_lower:
              logger.info(f"Mock geocoding detected city:
  {city_name}")
              #            ↑
              #            LOGS: "Mock geocoding detected city: san     
  francisco"

              return {
                  "lat": lat,      # 37.7749
                  "lng": lng,      # -122.4194
                  "formatted_address": address,
                  "confidence": "mock"
              }

      # Default to San Francisco if no city detected
      return {
          "lat": 37.7749,
          "lng": -122.4194,
          "formatted_address": address,
          "confidence": "mock"
      }

  RETURNS:
  {
      "lat": 37.7749,
      "lng": -122.4194,
      "formatted_address": "123 Main St, San Francisco",
      "confidence": "mock"
  }

  ---
  STEP 11: Back to handle_geocode_address()

  FILE: chat/tools.py
  LINE: 141-150

  result = {
      "lat": 37.7749,
      "lng": -122.4194,
      "formatted_address": "123 Main St, San Francisco",
      "confidence": "mock"
  }

  RETURNS:
  {
      "success": True,
      "latitude": 37.7749,
      "longitude": -122.4194,
      "formatted_address": "123 Main St, San Francisco",
      "confidence": "mock",
      "message": "Address geocoded successfully (mock)"
  }

  ---
  STEP 12: Back to _process_response() - Tool Result Received

  FILE: chat/providers/gemini_provider.py
  LINE: 285-310

  tool_result = {
      "success": True,
      "latitude": 37.7749,
      "longitude": -122.4194,
      "formatted_address": "123 Main St, San Francisco",
      "confidence": "mock",
      "message": "Address geocoded successfully (mock)"
  }

  # Track for transparency
  tool_calls_made.append({
      "tool": "geocode_address",
      "input": {"address": "123 Main St, San Francisco"},
      "result": tool_result
  })

  conversation.add_tool_result("geocode_address", function_args,        
  tool_result)

  # Send function result back to Gemini
  current_response = chat.send_message(
      genai.protos.Content(
          parts=[genai.protos.Part(
              function_response=genai.protos.FunctionResponse(
                  name="geocode_address",
                  response={"result": tool_result}
              )
          )]
      )
  )
  #  ↑
  #  🌐 API CALL TO GEMINI WITH GEOCODING RESULT

  ---
  STEP 13: Gemini Receives Geocoding Result

  🌐 GOOGLE GEMINI API (External)

  RECEIVES:
  - Function: geocode_address
  - Result: {
      "success": True,
      "latitude": 37.7749,
      "longitude": -122.4194
    }

  AI ANALYZES:
  "Great! I now have GPS coordinates:
   ✅ Customer Name: John Doe
   ✅ Address: 123 Main St, San Francisco
   ✅ Latitude: 37.7749
   ✅ Longitude: -122.4194

   DECISION: Now I can create the order in the database!
             Call create_order tool."

  RETURNS TO CODE:
  response = {
      candidates: [{
          content: {
              parts: [{
                  function_call: {
                      name: "create_order",
                      args: {
                          "customer_name": "John Doe",
                          "delivery_address": "123 Main St, San
  Francisco",
                          "delivery_lat": 37.7749,
                          "delivery_lng": -122.4194,
                          "priority": "standard"
                      }
                  }
              }]
          }
      }]
  }

  ---
  STEP 14: Loop Continues - Detects create_order

  FILE: chat/providers/gemini_provider.py
  LINE: 252-285

  # Still in the for loop (iteration 2)
  first_part = current_response.candidates[0].content.parts[0]
  has_fc = True  # Another function call detected

  function_call = first_part.function_call
  function_name = function_call.name  # "create_order"
  function_args = dict(function_call.args)  # {customer_name,
  address, lat, lng...}

  logger.info(f"Gemini executing function: {function_name}
  (iteration 2)")
  #            ↑
  #            LOGS: "Gemini executing function: create_order
  (iteration 2)"

  # Execute the tool
  tool_result = execute_tool(function_name, function_args)
  #             ↑
  #             CALLS execute_tool() AGAIN

  ---
  STEP 15: execute_tool() - Routes to create_order

  FILE: chat/tools.py
  LINE: 92-118

  FUNCTION: execute_tool(tool_name, tool_input)
      tool_name = "create_order"
      tool_input = {
          "customer_name": "John Doe",
          "delivery_address": "123 Main St, San Francisco",
          "delivery_lat": 37.7749,
          "delivery_lng": -122.4194,
          "priority": "standard"
      }

  Function Code:
  def execute_tool(tool_name, tool_input):
      try:
          if tool_name == "geocode_address":
              return handle_geocode_address(tool_input)
          elif tool_name == "create_order":
              return handle_create_order(tool_input)
              #      ↑
              #      CALLS THIS NEXT

  ---
  STEP 16: handle_create_order()

  FILE: chat/tools.py
  LINE: 153-242

  FUNCTION: handle_create_order(tool_input)
      tool_input = {
          "customer_name": "John Doe",
          "delivery_address": "123 Main St, San Francisco",
          "delivery_lat": 37.7749,
          "delivery_lng": -122.4194,
          "priority": "standard"
      }

  Function Code:
  def handle_create_order(tool_input):
      """Execute order creation tool"""

      # Extract fields with defaults
      customer_name = tool_input.get("customer_name")  # "John Doe"     
      customer_phone = tool_input.get("customer_phone")  # None
      customer_email = tool_input.get("customer_email")  # None
      delivery_address = tool_input.get("delivery_address")  # "123     
  Main St, San Francisco"
      delivery_lat = tool_input.get("delivery_lat")  # 37.7749
      delivery_lng = tool_input.get("delivery_lng")  # -122.4194        
      priority = tool_input.get("priority", "standard")  #
  "standard"
      special_instructions = tool_input.get("special_instructions")     
   # None
      weight_kg = tool_input.get("weight_kg", 5.0)  # 5.0

      # Validate required fields
      if not all([customer_name, delivery_address, delivery_lat,        
  delivery_lng]):
          return {"success": False, "error": "Missing required
  fields..."}

      # Generate order ID
      now = datetime.now()
      order_id = f"ORD-{now.strftime('%Y%m%d%H%M%S')}"
      #          ↑
      #          e.g., "ORD-20251114015858"

      # Handle time window
      time_window_end = now + timedelta(hours=6)  # 6 hours from now    
      time_window_start = now + timedelta(hours=2)  # 2 hours from      
  now

      # Insert into database
      query = """
          INSERT INTO orders (
              order_id, customer_name, customer_phone,
  customer_email,
              delivery_address, delivery_lat, delivery_lng,
              time_window_start, time_window_end,
              priority, weight_kg, status, special_instructions
          ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s,     
  %s)
      """

      params = (
          order_id,                # "ORD-20251114015858"
          customer_name,           # "John Doe"
          customer_phone,          # None
          customer_email,          # None
          delivery_address,        # "123 Main St, San Francisco"       
          delivery_lat,            # 37.7749
          delivery_lng,            # -122.4194
          time_window_start,       # 2025-11-14 03:58:58
          time_window_end,         # 2025-11-14 07:58:58
          priority,                # "standard"
          weight_kg,               # 5.0
          "pending",               # status
          special_instructions     # None
      )

      try:
          execute_write(query, params)
          #     ↑
          #     CALLS THIS NEXT - DATABASE WRITE!

  ---
  STEP 17: execute_write() - INSERT INTO DATABASE

  FILE: database/connection.py
  LINE: 71-97

  FUNCTION: execute_write(query, params)
      query = "INSERT INTO orders (...) VALUES (%s, %s, ...)"
      params = ("ORD-20251114015858", "John Doe", None, None, "123      
  Main St...", ...)

  Function Code:
  def execute_write(query, params=None):
      """Execute a write query (INSERT, UPDATE, DELETE)"""
      try:
          # Connect to PostgreSQL
          conn = get_db_connection()
          #      ↑
          #      Opens connection to localhost:5432/fleetmind

          logger.info("Database connection established:
  fleetmind@localhost")

          cursor = conn.cursor()

          # Execute INSERT query
          cursor.execute(query, params)
          #     ↑
          #     💾 EXECUTES SQL:
          #     INSERT INTO orders (order_id, customer_name, ...)       
          #     VALUES ('ORD-20251114015858', 'John Doe', ...)

          conn.commit()  # ← SAVES TO POSTGRESQL PERMANENTLY!

          rows_affected = cursor.rowcount  # 1

          cursor.close()
          conn.close()

          logger.info("Database connection closed")

          return rows_affected  # Returns 1

  DATABASE STATE:
  -- New row added to orders table:
  ORDER_ID: ORD-20251114015858
  CUSTOMER_NAME: John Doe
  CUSTOMER_PHONE: NULL
  CUSTOMER_EMAIL: NULL
  DELIVERY_ADDRESS: 123 Main St, San Francisco
  DELIVERY_LAT: 37.7749
  DELIVERY_LNG: -122.4194
  STATUS: pending
  PRIORITY: standard
  WEIGHT_KG: 5.0
  CREATED_AT: 2025-11-14 01:58:58

  ---
  STEP 18: Back to handle_create_order() - Success!

  FILE: chat/tools.py
  LINE: 224-242

  execute_write(query, params)  # Returned 1 (success)

  logger.info(f"Order created: {order_id}")
  #            ↑
  #            LOGS: "Order created: ORD-20251114015858"

  return {
      "success": True,
      "order_id": "ORD-20251114015858",
      "status": "pending",
      "customer": "John Doe",
      "address": "123 Main St, San Francisco",
      "deadline": "2025-11-14 07:58",
      "priority": "standard",
      "message": "Order ORD-20251114015858 created successfully!"       
  }

  ---
  STEP 19: Back to _process_response() - Second Tool Complete

  FILE: chat/providers/gemini_provider.py
  LINE: 285-310

  tool_result = {
      "success": True,
      "order_id": "ORD-20251114015858",
      "status": "pending",
      "customer": "John Doe",
      ...
  }

  # Track for transparency
  tool_calls_made.append({
      "tool": "create_order",
      "input": {
          "customer_name": "John Doe",
          "delivery_address": "123 Main St, San Francisco",
          "delivery_lat": 37.7749,
          "delivery_lng": -122.4194
      },
      "result": tool_result
  })

  conversation.add_tool_result("create_order", function_args,
  tool_result)

  # Send function result back to Gemini
  current_response = chat.send_message(
      genai.protos.Content(
          parts=[genai.protos.Part(
              function_response=genai.protos.FunctionResponse(
                  name="create_order",
                  response={"result": tool_result}
              )
          )]
      )
  )
  #  ↑
  #  🌐 API CALL TO GEMINI WITH ORDER CREATION RESULT

  ---
  STEP 20: Gemini Generates Final Response

  🌐 GOOGLE GEMINI API (External)

  RECEIVES:
  - Function: create_order
  - Result: {
      "success": True,
      "order_id": "ORD-20251114015858",
      "customer": "John Doe",
      "address": "123 Main St, San Francisco"
    }

  AI ANALYZES:
  "Perfect! Order successfully created in database!
   Let me tell the user with a nice summary."

  GENERATES TEXT RESPONSE:
  "Awesome! I have created the order for John Doe.

  **Here's a summary:**
  • Order ID: ORD-20251114015858
  • Customer: John Doe
  • Address: 123 Main St, San Francisco
  • Status: Pending
  • Priority: Standard

  The order has been successfully saved to the database!"

  RETURNS TO CODE:
  response = {
      candidates: [{
          content: {
              parts: [{
                  text: "Awesome! I have created the order for John     
  Doe.\n\n**Here's a summary:**..."
              }]
          }
      }]
  }

  ---
  STEP 21: _process_response() - Extract Final Text

  FILE: chat/providers/gemini_provider.py
  LINE: 272-356

  # Loop detects no more function calls
  logger.info(f"No more function calls after iteration 2")

  # Extract text from final response
  parts = current_response.candidates[0].content.parts
  logger.info(f"Extracting text from {len(parts)} parts")

  for idx, part in enumerate(parts):
      if hasattr(part, 'text') and part.text:
          logger.info(f"Part {idx} has text: {part.text[:50]}...")      
          final_text += part.text

  # final_text = "Awesome! I have created the order for John Doe..."    

  logger.info(f"Returning response: {final_text[:100]}")

  conversation.add_message("assistant", final_text)

  return final_text, tool_calls_made
  #      ↑           ↑
  #      Response    List of 2 tool calls [geocode, create_order]       

  RETURNS:
  (
      "Awesome! I have created the order for John Doe.\n\n**Here's a    
   summary:**...",
      [
          {"tool": "geocode_address", "input": {...}, "result":
  {...}},
          {"tool": "create_order", "input": {...}, "result": {...}}     
      ]
  )

  ---
  STEP 22: Back Through All Functions

  ← Returns to: GeminiProvider.process_message() (line 206)
  ← Returns to: ChatEngine.process_message() (line 58)
  ← Returns to: handle_chat_message() (line 223)
  ← Returns to: send_message() (line 443)
  ← Returns to: Gradio UI (line 448)

  ---
  STEP 23: Gradio Updates UI

  FILE: ui/app.py
  LINE: 448-452

  send_btn.click(
      fn=send_message,
      outputs=[chatbot, tool_display, conversation_state, msg_input]    
      #        ↑        ↑
      #        Updates  Shows tool calls
  )

  CHATBOT DISPLAYS:
  User: "Create an order for John Doe at 123 Main St, San Francisco"