Merge pull request #41 from Commute-ai/copilot/integrate-ai-agents-service-client

Integrate AI-Agents Service Client

Author: zlendo1

app/api/v1/endpoints/routes.py

@@ -61,16 +61,13 @@ 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 insights (with graceful degradation)
         for itinerary in itineraries:
-            for leg in itinerary.legs:
-                try:
-                    ai_insight = await ai_agents_service.get_route_insight(leg)
-                    leg.ai_insight = ai_insight
-                except Exception as e:  # pylint: disable=broad-except
-                    # Gracefully degrade - log warning but continue without AI insight
-                    logger.warning("Failed to get AI insight for leg: %s", str(e))
-                    leg.ai_insight = None
+            try:
+                await ai_agents_service.get_itinerary_insight(itinerary)
+            except Exception as e:  # pylint: disable=broad-except
+                # Gracefully degrade - log warning but continue without AI insights
+                logger.warning("Failed to get AI insights for itinerary: %s", str(e))
 
         logger.info("Route search successful: found %d itineraries", len(itineraries))
 

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 overall 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

@@ -5,7 +5,7 @@
 
 from app.core.config import settings
 from app.schemas.health import ServiceHealth
-from app.schemas.itinary import Leg
+from app.schemas.itinary import Itinerary
 
 logger = logging.getLogger(__name__)
 
@@ -65,53 +65,84 @@ 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_itinerary_insight(self, itinerary: Itinerary) -> None:
         """
-        Get AI-generated insight for a specific leg of the journey.
+        Get AI-generated insights for a complete itinerary and enrich it with AI data.
+
+        This method sends the entire itinerary to the AI service and receives back:
+        - ai_description: Overall description of the itinerary
+        - ai_insights: List of insights for each leg
+
+        The method directly modifies the itinerary object in place, setting:
+        - itinerary.ai_description
+        - leg.ai_insight for each leg
 
         Args:
-            leg: The leg object containing journey segment information
+            itinerary: The itinerary object containing the complete journey information
 
         Returns:
-            Optional[str]: AI-generated insight text, or None if unavailable
+            None - modifies the itinerary object in place
 
         Raises:
-            No exceptions - gracefully degrades by returning None on errors
+            No exceptions - gracefully degrades by returning without modification on errors
         """
         try:
             client = self._get_client()
 
-            # Prepare request payload with leg information
-            payload: dict[str, str | int | float | dict[str, str] | None] = {
-                "mode": leg.mode.value,
-                "duration": leg.duration,
-                "distance": leg.distance,
-                "from_place": leg.from_place.name,
-                "to_place": leg.to_place.name,
+            # Prepare request payload with itinerary information
+            payload = {
+                "start": itinerary.start.isoformat(),
+                "end": itinerary.end.isoformat(),
+                "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
+                ],
             }
 
-            # Include route information if available (e.g., bus number)
-            if leg.route:
-                payload["route"] = {
-                    "short_name": leg.route.short_name,
-                    "long_name": leg.route.long_name,
-                }
-
-            response = await client.post("/insights/route", json=payload)
+            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: %s", response.status_code)
-            return None
+                # Set the itinerary-level AI description
+                itinerary.ai_description = data.get("ai_description")
+
+                # Set AI insights for each leg
+                ai_insights = data.get("ai_insights", [])
+                for idx, leg in enumerate(itinerary.legs):
+                    if idx < len(ai_insights):
+                        leg.ai_insight = ai_insights[idx]
+                    else:
+                        leg.ai_insight = None
+
+                return
+
+            logger.warning(
+                "AI agents service returned non-200 status for itinerary insight: %s",
+                response.status_code,
+            )
 
         except httpx.TimeoutException:
-            logger.warning("AI agents service request timed out")
-            return None
+            logger.warning("AI agents service request timed out for itinerary insight")
         except Exception as e:  # pylint: disable=broad-except
-            logger.warning("Failed to get AI insight: %s", str(e))
-            return None
+            logger.warning("Failed to get AI itinerary insight: %s", str(e))
 
 
 # Singleton instance for dependency injection

tests/endpoints/test_routes.py

@@ -379,7 +379,7 @@ def test_search_routes_valid_edge_coordinates(client: TestClient, sample_itinera
 
 
 def test_search_routes_without_ai_description(client: TestClient, sample_itineraries):
-    """Test that route response works without ai_description (graceful degradation)."""
+    """Test that route response works without ai_description in itinerary (graceful degradation)."""
     with patch("app.api.v1.endpoints.routes.routing_service") as mock_service:
         mock_service.get_itinaries = AsyncMock(return_value=sample_itineraries)
 
@@ -394,29 +394,30 @@ def test_search_routes_without_ai_description(client: TestClient, sample_itinera
         assert response.status_code == 200
         data = response.json()
 
-        # Verify ai_description is present but can be None
-        assert "ai_description" in data
-        # When not provided, it should be None
-        assert data["ai_description"] is None
+        # Verify ai_description is not in the response (removed from RouteSearchResponse)
+        assert "ai_description" not in data
+        # But it should be in each itinerary
+        assert "ai_description" in data["itineraries"][0]
 
 
 def test_search_routes_with_ai_description(client: TestClient, sample_itineraries):
-    """Test that route response validates correctly when ai_description is provided."""
+    """Test that itinerary schema validates correctly when ai_description is provided."""
     # Test the schema validation directly
     from app.schemas.geo import Coordinates
     from app.schemas.routes import RouteSearchResponse
 
-    # Schema should validate with ai_description
+    # Schema should validate with ai_description in itinerary
+    itinerary_with_description = sample_itineraries[0]
+    itinerary_with_description.ai_description = "This is a fast route with minimal walking."
+
     response_data = RouteSearchResponse(
         origin=Coordinates(latitude=60.1699, longitude=24.9384),
         destination=Coordinates(latitude=60.2055, longitude=24.6559),
-        itineraries=sample_itineraries,
+        itineraries=[itinerary_with_description],
         search_time=datetime.now(timezone.utc),
-        ai_description="This route offers multiple options with varying travel times.",
     )
     assert (
-        response_data.ai_description
-        == "This route offers multiple options with varying travel times."
+        response_data.itineraries[0].ai_description == "This is a fast route with minimal walking."
     )
 
     # Schema should validate without ai_description
@@ -426,22 +427,30 @@ def test_search_routes_with_ai_description(client: TestClient, sample_itinerarie
         itineraries=sample_itineraries,
         search_time=datetime.now(timezone.utc),
     )
-    assert response_data_no_ai.ai_description is None
+    # ai_description field removed from RouteSearchResponse
+    assert not hasattr(response_data_no_ai, "ai_description") or (
+        hasattr(response_data_no_ai, "ai_description")
+        and response_data_no_ai.ai_description is None
+    )
 
 
 def test_search_routes_with_ai_insights_success(client: TestClient, sample_itineraries):
-    """Test successful route search with AI insights for each leg."""
+    """Test successful route search with AI insights for each leg and itinerary."""
     with patch("app.api.v1.endpoints.routes.routing_service") as mock_routing_service:
         with patch("app.api.v1.endpoints.routes.ai_agents_service") as mock_ai_service:
             mock_routing_service.get_itinaries = AsyncMock(return_value=sample_itineraries)
 
-            # Mock AI service to return insights
-            async def mock_get_insight(leg):
-                if leg.mode == TransportMode.WALK:
-                    return "Short walk to the bus stop."
-                return "Express bus with comfortable seats."
+            # Mock AI service to enrich itinerary in place
+            async def mock_get_itinerary_insight(itinerary):
+                itinerary.ai_description = (
+                    "This route offers a good balance of walking and public transport."
+                )
+                itinerary.legs[0].ai_insight = "Short walk to the bus stop."
+                itinerary.legs[1].ai_insight = "Express bus with comfortable seats."
 
-            mock_ai_service.get_route_insight = AsyncMock(side_effect=mock_get_insight)
+            mock_ai_service.get_itinerary_insight = AsyncMock(
+                side_effect=mock_get_itinerary_insight
+            )
 
             response = client.post(
                 "/api/v1/routes/search",
@@ -465,8 +474,13 @@ async def mock_get_insight(leg):
             # Check second leg (BUS)
             assert itinerary["legs"][1]["ai_insight"] == "Express bus with comfortable seats."
 
-            # Verify AI service was called for each leg
-            assert mock_ai_service.get_route_insight.call_count == 2
+            # Verify AI description for the itinerary
+            assert (
+                itinerary["ai_description"]
+                == "This route offers a good balance of walking and public transport."
+            )
+            # Verify AI service was called for itinerary insight
+            assert mock_ai_service.get_itinerary_insight.call_count == 1
 
 
 def test_search_routes_with_ai_service_unavailable(client: TestClient, sample_itineraries):
@@ -475,8 +489,14 @@ def test_search_routes_with_ai_service_unavailable(client: TestClient, sample_it
         with patch("app.api.v1.endpoints.routes.ai_agents_service") as mock_ai_service:
             mock_routing_service.get_itinaries = AsyncMock(return_value=sample_itineraries)
 
-            # Mock AI service to return None (service unavailable)
-            mock_ai_service.get_route_insight = AsyncMock(return_value=None)
+            # Mock AI service to do nothing (service unavailable)
+            async def mock_get_itinerary_insight_unavailable(itinerary):
+                # Service unavailable - does not modify itinerary
+                pass
+
+            mock_ai_service.get_itinerary_insight = AsyncMock(
+                side_effect=mock_get_itinerary_insight_unavailable
+            )
 
             response = client.post(
                 "/api/v1/routes/search",
@@ -498,25 +518,24 @@ def test_search_routes_with_ai_service_unavailable(client: TestClient, sample_it
             # AI insights should be None
             assert itinerary["legs"][0]["ai_insight"] is None
             assert itinerary["legs"][1]["ai_insight"] is None
+            # AI description should be None
+            assert itinerary["ai_description"] is None
 
 
 def test_search_routes_with_ai_service_partial_failure(client: TestClient, sample_itineraries):
-    """Test graceful degradation when AI service fails for some legs."""
+    """Test graceful degradation when AI service provides partial data."""
     with patch("app.api.v1.endpoints.routes.routing_service") as mock_routing_service:
         with patch("app.api.v1.endpoints.routes.ai_agents_service") as mock_ai_service:
             mock_routing_service.get_itinaries = AsyncMock(return_value=sample_itineraries)
 
-            # Mock AI service to succeed for first leg, fail for second
-            call_count = 0
-
-            async def mock_get_insight_partial(leg):
-                nonlocal call_count
-                call_count += 1
-                if call_count == 1:
-                    return "Short walk to the bus stop."
-                return None  # Simulate failure for second leg
+            # Mock AI service to provide partial data
+            async def mock_get_itinerary_insight_partial(itinerary):
+                # Only set description, not leg insights
+                itinerary.ai_description = "This is a good route."
 
-            mock_ai_service.get_route_insight = AsyncMock(side_effect=mock_get_insight_partial)
+            mock_ai_service.get_itinerary_insight = AsyncMock(
+                side_effect=mock_get_itinerary_insight_partial
+            )
 
             response = client.post(
                 "/api/v1/routes/search",
@@ -529,10 +548,9 @@ async def mock_get_insight_partial(leg):
             assert response.status_code == 200
             data = response.json()
 
-            # Verify first leg has insight
-            assert data["itineraries"][0]["legs"][0]["ai_insight"] == "Short walk to the bus stop."
-
-            # Verify second leg has no insight (graceful degradation)
+            # Verify itinerary has description but legs don't have insights
+            assert data["itineraries"][0]["ai_description"] == "This is a good route."
+            assert data["itineraries"][0]["legs"][0]["ai_insight"] is None
             assert data["itineraries"][0]["legs"][1]["ai_insight"] is None
 
 
@@ -543,7 +561,9 @@ def test_search_routes_with_ai_service_exception(client: TestClient, sample_itin
             mock_routing_service.get_itinaries = AsyncMock(return_value=sample_itineraries)
 
             # Mock AI service to raise an exception
-            mock_ai_service.get_route_insight = AsyncMock(side_effect=Exception("AI service error"))
+            mock_ai_service.get_itinerary_insight = AsyncMock(
+                side_effect=Exception("AI service error")
+            )
 
             response = client.post(
                 "/api/v1/routes/search",
@@ -565,6 +585,8 @@ def test_search_routes_with_ai_service_exception(client: TestClient, sample_itin
             # AI insights should be None due to graceful degradation
             assert itinerary["legs"][0]["ai_insight"] is None
             assert itinerary["legs"][1]["ai_insight"] is None
+            # AI description should be None due to graceful degradation
+            assert itinerary["ai_description"] is None
 
 
 def test_leg_schema_with_ai_insight():