feat: Add url field to PaginatedResponse and populate it using route … (#2419)

…path


# What does this PR do?

Closes #1847 

Changes:
- llama_stack/apis/common/responses.py: adds optional `url` field to
PaginatedResponse
- llama_stack/distribution/server/server.py: automatically populate the
URL field with route path



## Test Plan

- Built and ran llama stack server using the following cmds:  
  ```bash  
  export INFERENCE_MODEL=llama3.1:8b  
  llama stack build --run --template ollama --image-type container
  llama stack run llama_stack/templates/ollama/run.yaml
  ```
- Ran `curl` to test if we are seeing the `url` param in response:
  ```bash
  curl -X 'GET' \
    'http://localhost:8321/v1/agents' \
    -H 'accept: application/json'
  ```
- Expected and Received Output:
`{"data":[],"has_more":false,"url":"/v1/agents"}`

---------

Co-authored-by: Rohan Awhad <rawhad@redhat.com>

docs/_static/llama-stack-spec.html

@@ -11157,6 +11157,10 @@
                     "has_more": {
                         "type": "boolean",
                         "description": "Whether there are more items available after this set"
+                    },
+                    "url": {
+                        "type": "string",
+                        "description": "The URL for accessing this list"
                     }
                 },
                 "additionalProperties": false,

docs/_static/llama-stack-spec.yaml

@@ -7818,6 +7818,9 @@ components:
           type: boolean
           description: >-
             Whether there are more items available after this set
+        url:
+          type: string
+          description: The URL for accessing this list
       additionalProperties: false
       required:
         - data

llama_stack/apis/common/responses.py

@@ -23,7 +23,9 @@ class PaginatedResponse(BaseModel):
 
     :param data: The list of items for the current page
     :param has_more: Whether there are more items available after this set
+    :param url: The URL for accessing this list
     """
 
     data: list[dict[str, Any]]
     has_more: bool
+    url: str | None = None

llama_stack/distribution/server/server.py

@@ -30,6 +30,7 @@ from fastapi.responses import JSONResponse, StreamingResponse
 from openai import BadRequestError
 from pydantic import BaseModel, ValidationError
 
+from llama_stack.apis.common.responses import PaginatedResponse
 from llama_stack.distribution.datatypes import AuthenticationRequiredError, LoggingConfig, StackRunConfig
 from llama_stack.distribution.distribution import builtin_automatically_routed_apis
 from llama_stack.distribution.request_headers import PROVIDER_DATA_VAR, User, request_provider_data_context
@@ -230,7 +231,10 @@ def create_dynamic_typed_route(func: Any, method: str, route: str) -> Callable:
                     return StreamingResponse(gen, media_type="text/event-stream")
                 else:
                     value = func(**kwargs)
-                    return await maybe_await(value)
+                    result = await maybe_await(value)
+                    if isinstance(result, PaginatedResponse) and result.url is None:
+                        result.url = route
+                    return result
             except Exception as e:
                 logger.exception(f"Error executing endpoint {route=} {method=}")
                 raise translate_exception(e) from e

tests/unit/server/test_sse.py

@@ -5,10 +5,12 @@
 # the root directory of this source tree.
 
 import asyncio
+from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 
-from llama_stack.distribution.server.server import create_sse_event, sse_generator
+from llama_stack.apis.common.responses import PaginatedResponse
+from llama_stack.distribution.server.server import create_dynamic_typed_route, create_sse_event, sse_generator
 
 
 @pytest.mark.asyncio
@@ -89,3 +91,24 @@ async def test_sse_generator_error_before_response_starts():
     # We should have 1 error event
     assert len(seen_events) == 1
     assert 'data: {"error":' in seen_events[0]
+
+
+@pytest.mark.asyncio
+async def test_paginated_response_url_setting():
+    """Test that PaginatedResponse gets url set to route path."""
+
+    async def mock_api_method():
+        return PaginatedResponse(data=[], has_more=False, url=None)
+
+    route_handler = create_dynamic_typed_route(mock_api_method, "get", "/test/route")
+
+    # Mock minimal request
+    request = MagicMock()
+    request.scope = {"user_attributes": {}, "principal": ""}
+    request.headers = {}
+    request.body = AsyncMock(return_value=b"")
+
+    result = await route_handler(request)
+
+    assert isinstance(result, PaginatedResponse)
+    assert result.url == "/test/route"