From 73e860a6e6e199ebe3fbbcbfb914e3d366781f83 Mon Sep 17 00:00:00 2001 From: Raghotham Murthy Date: Tue, 28 Oct 2025 14:13:55 -0700 Subject: [PATCH] chore(api)!: Add a parameter to inspect to only list v1 apis by default use parameter api_filter to pick from v1, v1alpha, v1beta, deprecated --- client-sdks/stainless/openapi.yml | 17 ++++++- docs/static/llama-stack-spec.html | 18 +++++++- docs/static/llama-stack-spec.yaml | 17 ++++++- docs/static/stainless-llama-stack-spec.html | 18 +++++++- docs/static/stainless-llama-stack-spec.yaml | 17 ++++++- src/llama_stack/apis/inspect/inspect.py | 15 +++--- src/llama_stack/core/inspect.py | 19 ++++---- tests/integration/inspect/test_inspect.py | 51 +++++++++++++++++++++ 8 files changed, 152 insertions(+), 20 deletions(-) diff --git a/client-sdks/stainless/openapi.yml b/client-sdks/stainless/openapi.yml index f531542c5..a1085c9eb 100644 --- a/client-sdks/stainless/openapi.yml +++ b/client-sdks/stainless/openapi.yml @@ -956,7 +956,22 @@ paths: List routes. List all available API routes with their methods and implementing providers. - parameters: [] + parameters: + - name: api_filter + in: query + description: >- + Optional filter to control which routes are returned. Can be an API level + ('v1', 'v1alpha', 'v1beta') to show non-deprecated routes at that level, + or 'deprecated' to show deprecated routes across all levels. If not specified, + returns only non-deprecated v1 routes. + required: false + schema: + type: string + enum: + - v1 + - v1alpha + - v1beta + - deprecated deprecated: false /v1/models: get: diff --git a/docs/static/llama-stack-spec.html b/docs/static/llama-stack-spec.html index c1d3658f4..c376e4b80 100644 --- a/docs/static/llama-stack-spec.html +++ b/docs/static/llama-stack-spec.html @@ -1258,7 +1258,23 @@ ], "summary": "List routes.", "description": "List routes.\nList all available API routes with their methods and implementing providers.", - "parameters": [], + "parameters": [ + { + "name": "api_filter", + "in": "query", + "description": "Optional filter to control which routes are returned. Can be an API level ('v1', 'v1alpha', 'v1beta') to show non-deprecated routes at that level, or 'deprecated' to show deprecated routes across all levels. If not specified, returns only non-deprecated v1 routes.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "v1", + "v1alpha", + "v1beta", + "deprecated" + ] + } + } + ], "deprecated": false } }, diff --git a/docs/static/llama-stack-spec.yaml b/docs/static/llama-stack-spec.yaml index 5b629a474..e35287952 100644 --- a/docs/static/llama-stack-spec.yaml +++ b/docs/static/llama-stack-spec.yaml @@ -953,7 +953,22 @@ paths: List routes. List all available API routes with their methods and implementing providers. - parameters: [] + parameters: + - name: api_filter + in: query + description: >- + Optional filter to control which routes are returned. Can be an API level + ('v1', 'v1alpha', 'v1beta') to show non-deprecated routes at that level, + or 'deprecated' to show deprecated routes across all levels. If not specified, + returns only non-deprecated v1 routes. + required: false + schema: + type: string + enum: + - v1 + - v1alpha + - v1beta + - deprecated deprecated: false /v1/models: get: diff --git a/docs/static/stainless-llama-stack-spec.html b/docs/static/stainless-llama-stack-spec.html index 59b6c28e7..a6208bf6f 100644 --- a/docs/static/stainless-llama-stack-spec.html +++ b/docs/static/stainless-llama-stack-spec.html @@ -1258,7 +1258,23 @@ ], "summary": "List routes.", "description": "List routes.\nList all available API routes with their methods and implementing providers.", - "parameters": [], + "parameters": [ + { + "name": "api_filter", + "in": "query", + "description": "Optional filter to control which routes are returned. Can be an API level ('v1', 'v1alpha', 'v1beta') to show non-deprecated routes at that level, or 'deprecated' to show deprecated routes across all levels. If not specified, returns only non-deprecated v1 routes.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "v1", + "v1alpha", + "v1beta", + "deprecated" + ] + } + } + ], "deprecated": false } }, diff --git a/docs/static/stainless-llama-stack-spec.yaml b/docs/static/stainless-llama-stack-spec.yaml index f531542c5..a1085c9eb 100644 --- a/docs/static/stainless-llama-stack-spec.yaml +++ b/docs/static/stainless-llama-stack-spec.yaml @@ -956,7 +956,22 @@ paths: List routes. List all available API routes with their methods and implementing providers. - parameters: [] + parameters: + - name: api_filter + in: query + description: >- + Optional filter to control which routes are returned. Can be an API level + ('v1', 'v1alpha', 'v1beta') to show non-deprecated routes at that level, + or 'deprecated' to show deprecated routes across all levels. If not specified, + returns only non-deprecated v1 routes. + required: false + schema: + type: string + enum: + - v1 + - v1alpha + - v1beta + - deprecated deprecated: false /v1/models: get: diff --git a/src/llama_stack/apis/inspect/inspect.py b/src/llama_stack/apis/inspect/inspect.py index 2f2925b4d..4e0e2548b 100644 --- a/src/llama_stack/apis/inspect/inspect.py +++ b/src/llama_stack/apis/inspect/inspect.py @@ -8,12 +8,16 @@ from typing import Literal, Protocol, runtime_checkable from pydantic import BaseModel -from llama_stack.apis.version import LLAMA_STACK_API_V1 +from llama_stack.apis.version import ( + LLAMA_STACK_API_V1, +) from llama_stack.providers.datatypes import HealthStatus from llama_stack.schema_utils import json_schema_type, webmethod -# Valid API level values for filtering routes -ApiLevel = Literal["v1", "v1alpha", "v1beta", "deprecated"] +# Valid values for the route filter parameter. +# Actual API levels: v1, v1alpha, v1beta (filters by level, excludes deprecated) +# Special filter value: "deprecated" (shows deprecated routes regardless of level) +ApiFilter = Literal["v1", "v1alpha", "v1beta", "deprecated"] @json_schema_type @@ -67,13 +71,12 @@ class Inspect(Protocol): """ @webmethod(route="/inspect/routes", method="GET", level=LLAMA_STACK_API_V1) - async def list_routes(self, api_level: ApiLevel | None = None) -> ListRoutesResponse: + async def list_routes(self, api_filter: ApiFilter | None = None) -> ListRoutesResponse: """List routes. List all available API routes with their methods and implementing providers. - :param api_level: Optional filter for API level. Can be 'v1', 'v1alpha', 'v1beta', or 'deprecated'. - If not specified, returns only non-deprecated v1 APIs and providers. + :param api_filter: Optional filter to control which routes are returned. Can be an API level ('v1', 'v1alpha', 'v1beta') to show non-deprecated routes at that level, or 'deprecated' to show deprecated routes across all levels. If not specified, returns only non-deprecated v1 routes. :returns: Response containing information about all available routes. """ ... diff --git a/src/llama_stack/core/inspect.py b/src/llama_stack/core/inspect.py index 42f9f695e..6352af00f 100644 --- a/src/llama_stack/core/inspect.py +++ b/src/llama_stack/core/inspect.py @@ -15,6 +15,7 @@ from llama_stack.apis.inspect import ( RouteInfo, VersionInfo, ) +from llama_stack.apis.version import LLAMA_STACK_API_V1 from llama_stack.core.datatypes import StackRunConfig from llama_stack.core.external import load_external_apis from llama_stack.core.server.routes import get_all_api_routes @@ -39,20 +40,20 @@ class DistributionInspectImpl(Inspect): async def initialize(self) -> None: pass - async def list_routes(self, api_level: str | None = None) -> ListRoutesResponse: + async def list_routes(self, api_filter: str | None = None) -> ListRoutesResponse: run_config: StackRunConfig = self.config.run_config - # Helper function to determine if a route should be included based on api_level filter + # Helper function to determine if a route should be included based on api_filter def should_include_route(webmethod) -> bool: - if api_level is None: + if api_filter is None: # Default: only non-deprecated v1 APIs - return not webmethod.deprecated and webmethod.level == "v1" - elif api_level == "deprecated": - # Include only deprecated routes - return webmethod.deprecated + return not webmethod.deprecated and webmethod.level == LLAMA_STACK_API_V1 + elif api_filter == "deprecated": + # Special filter: show deprecated routes regardless of their actual level + return bool(webmethod.deprecated) else: - # Include routes matching the specified level (non-deprecated) - return not webmethod.deprecated and webmethod.level == api_level + # Filter by API level (non-deprecated routes only) + return not webmethod.deprecated and webmethod.level == api_filter ret = [] external_apis = load_external_apis(run_config) diff --git a/tests/integration/inspect/test_inspect.py b/tests/integration/inspect/test_inspect.py index 1597a319b..fa2ae14e5 100644 --- a/tests/integration/inspect/test_inspect.py +++ b/tests/integration/inspect/test_inspect.py @@ -19,3 +19,54 @@ class TestInspect: version = llama_stack_client.inspect.version() assert version is not None assert version.version is not None + + def test_list_routes_default(self, llama_stack_client: LlamaStackAsLibraryClient | LlamaStackClient): + """Test list_routes with default filter (non-deprecated v1 routes).""" + response = llama_stack_client.routes.list() + assert response is not None + assert hasattr(response, "data") + routes = response.data + assert len(routes) > 0 + + # All routes should be non-deprecated + # Check that we don't see any /openai/ routes (which are deprecated) + openai_routes = [r for r in routes if "/openai/" in r.route] + assert len(openai_routes) == 0, "Default filter should not include deprecated /openai/ routes" + + # Should see standard v1 routes like /inspect/routes, /health, /version + paths = [r.route for r in routes] + assert "/inspect/routes" in paths or "/v1/inspect/routes" in paths + assert "/health" in paths or "/v1/health" in paths + + def test_list_routes_filter_by_deprecated(self, llama_stack_client: LlamaStackAsLibraryClient | LlamaStackClient): + """Test list_routes with deprecated filter.""" + response = llama_stack_client.routes.list(api_filter="deprecated") + assert response is not None + assert hasattr(response, "data") + routes = response.data + + # When filtering for deprecated, we should get deprecated routes + # At minimum, we should see some /openai/ routes which are deprecated + if len(routes) > 0: + # If there are any deprecated routes, they should include openai routes + openai_routes = [r for r in routes if "/openai/" in r.route] + assert len(openai_routes) > 0, "Deprecated filter should include /openai/ routes" + + def test_list_routes_filter_by_v1(self, llama_stack_client: LlamaStackAsLibraryClient | LlamaStackClient): + """Test list_routes with v1 filter.""" + response = llama_stack_client.routes.list(api_filter="v1") + assert response is not None + assert hasattr(response, "data") + routes = response.data + assert len(routes) > 0 + + # Should not include deprecated routes + openai_routes = [r for r in routes if "/openai/" in r.route] + assert len(openai_routes) == 0 + + # Should include v1 routes + paths = [r.route for r in routes] + assert any( + "/v1/" in p or p.startswith("/inspect/") or p.startswith("/health") or p.startswith("/version") + for p in paths + )