Update service to interface with AI agents /insight/iteneraries endpoint

[Copilot]

Updates the backend service layer to interface with the AI agents server's /api/v1/insight/iteneraries endpoint for getting insights on multiple itineraries at once.

Changes

Schema updates (app/schemas/ai_agents.py):

• Updated ItineraryInsightRequest: itineraries: List[Itinerary], user_preferences: List[PreferenceBase]
• Updated ItineraryInsightResponse: itenerary_insights: List[ItineraryInsight]
• Added ItineraryInsight: ai_insight: str, leg_insights: List[LegInsight]
• Added LegInsight: ai_insight: str

Service updates (app/services/ai_agents_service.py):

• Updated get_itinerary_insight() to wrap the new batch API
• Added get_itineraries_insight() that calls AI agents server at /api/v1/insight/iteneraries
• Both methods modify itineraries in place for backward compatibility
• Error handling for timeouts and non-200 responses

How It Works

The backend acts as an intermediary that interfaces with the AI agents server:

1. Users call the routes search endpoint (/api/v1/routes/search)
2. The routes endpoint internally calls get_itinerary_insight() for each itinerary
3. The service makes HTTP requests to the AI agents server at /api/v1/insight/iteneraries
4. Response insights are mapped back to enrich the itineraries in place
5. Users receive routes with AI insights included

AI Agents API Contract

# Request to AI agents server
{
  "itineraries": [
    {
      "start": "2025-10-14T10:00:00Z",
      "end": "2025-10-14T10:45:00Z",
      "duration": 2700,
      "walk_distance": 500.0,
      "walk_time": 400,
      "legs": [...]
    }
  ],
  "user_preferences": [
    {"prompt": "prefer minimal walking"}
  ]
}

# Response from AI agents server
{
  "itenerary_insights": [
    {
      "ai_insight": "Convenient route with minimal walking",
      "leg_insights": [
        {"ai_insight": "Short walk to bus stop"},
        {"ai_insight": "Direct bus connection"}
      ]
    }
  ]
}

Note: The backend does NOT expose /api/v1/insight/iteneraries as a user-facing endpoint. It only interfaces with the AI agents server via HTTP. Spelling (iteneraries, itenerary_insights) matches the external AI agents API specification.

• Fixes Change /insight/iteneraries #47

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Change /insight/iteneraries</issue_title>
<issue_description>Change endpoint and schemas to match endpoint in Commute-ai/commute-ai-agents.

1. Update the endpoint from insight/itinerary to /insight/iteneraries

2. Update the Request and Response schema
   ItineraryInsightRequest:

• itineraries: list[Itinerary]
• user_preferences: list[PreferenceBase]

ItineraryInsightResponse:

• itenerary_insights: list[ItineraryInsight]

ItineraryInsight:

• ai_insight: str
• leg_insights: list[LegInsight]

LegInsight:

• ai_insight: str</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Change /insight/iteneraries #47

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[zlendo1]

@copilot The /api/v1/insight/iteneraries endpoint doesn't exist in the backend. Rather, it is provided by the Commute-ai/commute-ai-agents server and only interfaced to by the backend through HTTP.

[Copilot]

@copilot The /api/v1/insight/iteneraries endpoint doesn't exist in the backend. Rather, it is provided by the Commute-ai/commute-ai-agents server and only interfaced to by the backend through HTTP.

You're absolutely right. I've corrected the implementation in commit 8931feb.

The backend now only interfaces with the AI agents server via HTTP - it doesn't expose /api/v1/insight/iteneraries as a user-facing endpoint. Instead:

1. Updated schemas to match the new API contract
2. Modified the service to call the AI agents server's /api/v1/insight/iteneraries endpoint
3. Removed the incorrectly created backend endpoint

The routes endpoint continues to work as before, but now uses the updated service method that calls the AI agents server.

[zlendo1]

Parent issue #47 solved by #50.