allow disabling query model and provider

Author: zszabo-rh

README.md

@@ -369,6 +369,19 @@ customization:
   disable_query_system_prompt: true
 ```
 
+### Disable model/provider overrides from requests
+
+By default, clients may specify `model` and `provider` in `/v1/query` and `/v1/streaming_query` requests to select a model at runtime. You can disable this behavior and enforce the configured defaults by setting:
+
+```yaml
+customization:
+  disable_query_model_override: true
+```
+
+When enabled, requests that include `model` or `provider` will be rejected with HTTP 422 and the following message:
+
+"This instance does not support overriding model/provider in the query request (disable_query_model_override is set). Please remove the model and provider fields from your request."
+
 ## Safety Shields
 
 A single Llama Stack configuration file can include multiple safety shields, which are utilized in agent

docs/openapi.json

@@ -1252,6 +1252,11 @@
                         "title": "Disable Query System Prompt",
                         "default": false
                     },
+                    "disable_query_model_override": {
+                        "type": "boolean",
+                        "title": "Disable Query Model Override",
+                        "default": false
+                    },
                     "system_prompt_path": {
                         "anyOf": [
                             {

docs/openapi.md

@@ -1225,4 +1225,4 @@ User data collection configuration.
 |-------|------|-------------|
 | loc | array |  |
 | msg | string |  |
-| type | string |  |
+| type | string |  |

src/app/endpoints/query.py

@@ -35,6 +35,7 @@
     get_agent,
     get_system_prompt,
     validate_conversation_ownership,
+    validate_model_provider_override,
 )
 from utils.mcp_headers import mcp_headers_dependency, handle_mcp_headers_with_toolgroups
 from utils.transcripts import store_transcript
@@ -174,6 +175,9 @@ async def query_endpoint_handler(
     """
     check_configuration_loaded(configuration)
 
+    # Enforce configuration: optionally disallow overriding model/provider in requests
+    validate_model_provider_override(query_request, configuration)
+
     # log Llama Stack configuration, but without sensitive information
     llama_stack_config = configuration.llama_stack_configuration.model_copy()
     llama_stack_config.api_key = "********"

src/app/endpoints/streaming_query.py

@@ -33,6 +33,7 @@
 from utils.mcp_headers import mcp_headers_dependency, handle_mcp_headers_with_toolgroups
 from utils.transcripts import store_transcript
 from utils.types import TurnSummary
+from utils.endpoints import validate_model_provider_override
 
 from app.endpoints.query import (
     get_rag_toolgroups,
@@ -548,6 +549,9 @@ async def streaming_query_endpoint_handler(  # pylint: disable=too-many-locals
 
     check_configuration_loaded(configuration)
 
+    # Enforce configuration: optionally disallow overriding model/provider in requests
+    validate_model_provider_override(query_request, configuration)
+
     # log Llama Stack configuration, but without sensitive information
     llama_stack_config = configuration.llama_stack_configuration.model_copy()
     llama_stack_config.api_key = "********"

src/models/config.py

@@ -388,6 +388,7 @@ class Customization(ConfigurationBase):
     """Service customization."""
 
     disable_query_system_prompt: bool = False
+    disable_query_model_override: bool = False
     system_prompt_path: Optional[FilePath] = None
     system_prompt: Optional[str] = None
 

src/utils/endpoints.py

@@ -84,6 +84,31 @@ def get_system_prompt(query_request: QueryRequest, config: AppConfig) -> str:
     return constants.DEFAULT_SYSTEM_PROMPT
 
 
+def validate_model_provider_override(
+    query_request: QueryRequest, config: AppConfig
+) -> None:
+    """Validate whether model/provider overrides are allowed.
+
+    Raises HTTP 422 if overrides are disabled and the request includes model or provider.
+    """
+    disabled = config.customization is not None and getattr(
+        config.customization, "disable_query_model_override", False
+    )
+    if disabled and (
+        query_request.model is not None or query_request.provider is not None
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail={
+                "response": (
+                    "This instance does not support overriding model/provider in the query request "
+                    "(disable_query_model_override is set). Please remove the model and "
+                    "provider fields from your request."
+                )
+            },
+        )
+
+
 # # pylint: disable=R0913,R0917
 async def get_agent(
     client: AsyncLlamaStackClient,

tests/unit/app/endpoints/test_query.py

@@ -1507,3 +1507,57 @@ def test_evaluate_model_hints(
 
     assert provider_id == expected_provider
     assert model_id == expected_model
+
+
+@pytest.mark.asyncio
+async def test_query_endpoint_rejects_model_provider_override_when_disabled(
+    mocker, dummy_request
+):
+    """Assert 422 and message when the override is disabled.
+
+    Validates behavior when request includes model/provider and
+    customization.disable_query_model_override is set.
+    """
+    # Prepare configuration with the override disabled
+    config_dict = {
+        "name": "test",
+        "service": {
+            "host": "localhost",
+            "port": 8080,
+            "auth_enabled": False,
+            "workers": 1,
+            "color_log": True,
+            "access_log": True,
+        },
+        "llama_stack": {
+            "api_key": "test-key",
+            "url": "http://test.com:1234",
+            "use_as_library_client": False,
+        },
+        "user_data_collection": {"transcripts_enabled": False},
+        "mcp_servers": [],
+        "customization": {
+            "disable_query_model_override": True,
+        },
+    }
+    cfg = AppConfig()
+    cfg.init_from_dict(config_dict)
+
+    # Patch endpoint configuration
+    mocker.patch("app.endpoints.query.configuration", cfg)
+
+    # Build a request that tries to override model/provider
+    query_request = QueryRequest(query="What?", model="m", provider="p")
+
+    with pytest.raises(HTTPException) as exc_info:
+        await query_endpoint_handler(
+            request=dummy_request, query_request=query_request, auth=MOCK_AUTH
+        )
+
+    expected_msg = (
+        "This instance does not support overriding model/provider in the query request "
+        "(disable_query_model_override is set). Please remove the model and "
+        "provider fields from your request."
+    )
+    assert exc_info.value.status_code == status.HTTP_422_UNPROCESSABLE_ENTITY
+    assert exc_info.value.detail["response"] == expected_msg

tests/unit/app/endpoints/test_streaming_query.py

@@ -1515,3 +1515,61 @@ async def test_retrieve_response_no_tools_false_preserves_functionality(
         stream=True,
         toolgroups=expected_toolgroups,
     )
+
+
+@pytest.mark.asyncio
+async def test_streaming_query_endpoint_rejects_model_provider_override_when_disabled(
+    mocker,
+):
+    """Assert 422 and message when the override is disabled.
+
+    Validates behavior when request includes model/provider and
+    customization.disable_query_model_override is set.
+    """
+    # Prepare configuration with the override disabled
+    config_dict = {
+        "name": "test",
+        "service": {
+            "host": "localhost",
+            "port": 8080,
+            "auth_enabled": False,
+            "workers": 1,
+            "color_log": True,
+            "access_log": True,
+        },
+        "llama_stack": {
+            "api_key": "test-key",
+            "url": "http://test.com:1234",
+            "use_as_library_client": False,
+        },
+        "user_data_collection": {"transcripts_enabled": False},
+        "mcp_servers": [],
+        "customization": {
+            "disable_query_model_override": True,
+        },
+    }
+    cfg = AppConfig()
+    cfg.init_from_dict(config_dict)
+
+    # Patch endpoint configuration
+    mocker.patch("app.endpoints.streaming_query.configuration", cfg)
+
+    # Build a query request that tries to override model/provider
+    query_request = QueryRequest(query="What?", model="m", provider="p")
+
+    request = Request(
+        scope={
+            "type": "http",
+        }
+    )
+
+    with pytest.raises(HTTPException) as exc_info:
+        await streaming_query_endpoint_handler(request, query_request, auth=MOCK_AUTH)
+
+    expected_msg = (
+        "This instance does not support overriding model/provider in the query request "
+        "(disable_query_model_override is set). Please remove the model and "
+        "provider fields from your request."
+    )
+    assert exc_info.value.status_code == status.HTTP_422_UNPROCESSABLE_ENTITY
+    assert exc_info.value.detail["response"] == expected_msg

tests/unit/utils/test_endpoints.py

@@ -591,3 +591,61 @@ async def test_get_agent_no_tools_false_preserves_parser(
         tool_parser=mock_parser,
         enable_session_persistence=True,
     )
+
+
+@pytest.fixture(name="config_with_override_disabled")
+def config_with_override_disabled_fixture():
+    """Configuration where overriding model/provider is allowed (flag False)."""
+    test_config = config_dict.copy()
+    test_config["customization"] = {
+        "disable_query_model_override": False,
+    }
+    cfg = AppConfig()
+    cfg.init_from_dict(test_config)
+    return cfg
+
+
+@pytest.fixture(name="config_with_override_enabled")
+def config_with_override_enabled_fixture():
+    """Configuration where overriding model/provider is NOT allowed (flag True)."""
+    test_config = config_dict.copy()
+    test_config["customization"] = {
+        "disable_query_model_override": True,
+    }
+    cfg = AppConfig()
+    cfg.init_from_dict(test_config)
+    return cfg
+
+
+def test_validate_model_provider_override_allowed_when_flag_false(
+    config_with_override_disabled,
+):
+    """Ensure no exception when overrides are allowed and request includes model/provider."""
+    query_request = QueryRequest(query="q", model="m", provider="p")
+    # Should not raise
+    endpoints.validate_model_provider_override(
+        query_request, config_with_override_disabled
+    )
+
+
+def test_validate_model_provider_override_rejected_when_flag_true(
+    config_with_override_enabled,
+):
+    """Ensure HTTP 422 when overrides are disabled and request includes model/provider."""
+    query_request = QueryRequest(query="q", model="m", provider="p")
+    with pytest.raises(HTTPException) as exc_info:
+        endpoints.validate_model_provider_override(
+            query_request, config_with_override_enabled
+        )
+    assert exc_info.value.status_code == 422
+
+
+def test_validate_model_provider_override_no_override_with_flag_true(
+    config_with_override_enabled,
+):
+    """No exception when overrides are disabled but request does not include model/provider."""
+    query_request = QueryRequest(query="q")
+    # Should not raise
+    endpoints.validate_model_provider_override(
+        query_request, config_with_override_enabled
+    )