Refactor AI-Agents service integration: rename endpoints, move ai_description to Itinerary

app/api/v1/endpoints/routes.py

@@ -61,11 +61,21 @@ async def search_routes(request: RouteSearchRequest) -> Any:
             first=request.num_itineraries,
         )
 
-        # Enhance each leg with AI insights (with graceful degradation)
+        # Enhance each itinerary with AI description and each leg with AI insights
         for itinerary in itineraries:
+            # Get AI description for the complete itinerary (with graceful degradation)
+            try:
+                ai_description = await ai_agents_service.get_itinerary_insight(itinerary)
+                itinerary.ai_description = ai_description
+            except Exception as e:  # pylint: disable=broad-except
+                # Gracefully degrade - log warning but continue without AI description
+                logger.warning("Failed to get AI description for itinerary: %s", str(e))
+                itinerary.ai_description = None
+
+            # Get AI insights for each leg (with graceful degradation)
             for leg in itinerary.legs:
                 try:
-                    ai_insight = await ai_agents_service.get_route_insight(leg)
+                    ai_insight = await ai_agents_service.get_leg_insight(leg)
                     leg.ai_insight = ai_insight
                 except Exception as e:  # pylint: disable=broad-except
                     # Gracefully degrade - log warning but continue without AI insight

app/schemas/itinary.py

@@ -59,3 +59,6 @@ class Itinerary(BaseModel):
     walk_distance: float = Field(..., description="Total walking distance in meters")
     walk_time: int = Field(..., description="Total walking time in seconds")
     legs: List[Leg]
+    ai_description: Optional[str] = Field(
+        default=None, description="AI-generated description of the complete itinerary"
+    )

app/schemas/routes.py

@@ -39,6 +39,3 @@ class RouteSearchResponse(BaseModel):
     destination: Coordinates
     itineraries: List[Itinerary] = Field(..., description="List of route itineraries")
     search_time: datetime = Field(..., description="Time when the search was performed")
-    ai_description: Optional[str] = Field(
-        default=None, description="AI-generated description of the route options"
-    )

app/services/ai_agents_service.py

@@ -65,7 +65,7 @@ async def health_check(self) -> ServiceHealth:
                 message=f"AI-agents API check failed: {str(e)}",
             )
 
-    async def get_route_insight(self, leg: Leg) -> Optional[str]:
+    async def get_leg_insight(self, leg: Leg) -> Optional[str]:
         """
         Get AI-generated insight for a specific leg of the journey.
 
@@ -97,7 +97,7 @@ async def get_route_insight(self, leg: Leg) -> Optional[str]:
                     "long_name": leg.route.long_name,
                 }
 
-            response = await client.post("/insights/route", json=payload)
+            response = await client.post("/api/v1/insight/leg", json=payload)
 
             if response.status_code == 200:
                 data = response.json()
@@ -113,6 +113,66 @@ async def get_route_insight(self, leg: Leg) -> Optional[str]:
             logger.warning("Failed to get AI insight: %s", str(e))
             return None
 
+    async def get_itinerary_insight(self, itinerary) -> Optional[str]:
+        """
+        Get AI-generated description for a complete itinerary.
+
+        Args:
+            itinerary: The itinerary object containing complete journey information
+
+        Returns:
+            Optional[str]: AI-generated description text, or None if unavailable
+
+        Raises:
+            No exceptions - gracefully degrades by returning None on errors
+        """
+        try:
+            client = self._get_client()
+
+            # Prepare request payload with itinerary information
+            payload = {
+                "duration": itinerary.duration,
+                "walk_distance": itinerary.walk_distance,
+                "walk_time": itinerary.walk_time,
+                "legs": [
+                    {
+                        "mode": leg.mode.value,
+                        "duration": leg.duration,
+                        "distance": leg.distance,
+                        "from_place": leg.from_place.name,
+                        "to_place": leg.to_place.name,
+                        "route": (
+                            {
+                                "short_name": leg.route.short_name,
+                                "long_name": leg.route.long_name,
+                            }
+                            if leg.route
+                            else None
+                        ),
+                    }
+                    for leg in itinerary.legs
+                ],
+            }
+
+            response = await client.post("/api/v1/insight/itinerary", json=payload)
+
+            if response.status_code == 200:
+                data = response.json()
+                return data.get("insight")
+
+            logger.warning(
+                "AI agents service returned non-200 status for itinerary: %s",
+                response.status_code,
+            )
+            return None
+
+        except httpx.TimeoutException:
+            logger.warning("AI agents service request timed out for itinerary")
+            return None
+        except Exception as e:  # pylint: disable=broad-except
+            logger.warning("Failed to get AI itinerary insight: %s", str(e))
+            return None
+
 
 # Singleton instance for dependency injection
 ai_agents_service = AiAgentsService()