Remove fallback to all registered vector stores when tool RAG is unconfigured

Previously, when neither rag.tool nor rag.inline were configured,
prepare_tools would fetch and register all vector stores from
llama-stack as a backward-compatibility fallback. This implicit
behavior is removed — tool RAG now requires explicit configuration
via rag.tool. Updated docs, config model, example YAML, and tests
to reflect the new behavior.

Author: Jazzcort

docs/byok_guide.md

@@ -261,7 +261,7 @@ rag:
     - okp             # include OKP context inline
 
   # Tool RAG: the LLM can call file_search to retrieve context on demand
-  # If omitted, tool RAG is disabled. If both tool and inline are omitted, all registered stores are used as fallback
+  # If omitted, tool RAG is disabled
   tool:
     - my-docs         # expose this BYOK store as the file_search tool
     - okp             # expose OKP as the file_search tool

docs/config.md

@@ -606,18 +606,14 @@ Controls which RAG sources are used for inline and tool-based retrieval.
 Each strategy lists RAG IDs to include. The special ID ``"okp"`` defined in constants,
 activates the OKP provider; all other IDs refer to entries in ``byok_rag``.
 
-Backward compatibility:
-    - ``inline`` defaults to ``[]`` (no inline RAG).
-    - ``tool`` defaults to ``[]`` (no tool RAG).
-
-If no RAG strategy is defined (inline and tool are empty),
-the RAG tool will register all stores available to llama-stack.
+Both ``inline`` and ``tool`` default to ``[]`` (disabled).
+Each must be explicitly configured to activate its respective RAG strategy.
 
 
 | Field  | Type  | Description                                                                                                                                                                            |
 |--------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | inline | array | RAG IDs whose sources are injected as context before the LLM call. Use 'okp' to enable OKP inline RAG. Empty by default (no inline RAG).                                               |
-| tool   | array | RAG IDs made available to the LLM as a file_search tool. Use 'okp' to include the OKP vector store. When omitted, all registered BYOK vector stores are used (backward compatibility). |
+| tool   | array | RAG IDs made available to the LLM as a file_search tool. Use 'okp' to include the OKP vector store. When omitted, tool RAG is disabled.                                               |
 
 
 ## RerankerConfiguration

docs/models/responses_succ.md

@@ -1840,18 +1840,14 @@ Controls which RAG sources are used for inline and tool-based retrieval.
 Each strategy lists RAG IDs to include. The special ID ``"okp"`` defined in constants,
 activates the OKP provider; all other IDs refer to entries in ``byok_rag``.
 
-Backward compatibility:
-    - ``inline`` defaults to ``[]`` (no inline RAG).
-    - ``tool`` defaults to ``[]`` (no tool RAG).
-
-If no RAG strategy is defined (inline and tool are empty),
-the RAG tool will register all stores available to llama-stack.
+Both ``inline`` and ``tool`` default to ``[]`` (disabled).
+Each must be explicitly configured to activate its respective RAG strategy.
 
 
 | Field | Type | Description |
 |-------|------|-------------|
 | inline | array | RAG IDs whose sources are injected as context before the LLM call. Use 'okp' to enable OKP inline RAG. Empty by default (no inline RAG). |
-| tool | array | RAG IDs made available to the LLM as a file_search tool. Use 'okp' to include the OKP vector store. When omitted, all registered BYOK vector stores are used (backward compatibility). |
+| tool | array | RAG IDs made available to the LLM as a file_search tool. Use 'okp' to include the OKP vector store. When omitted, tool RAG is disabled. |
 
 
 ## ReadinessResponse

docs/openapi.json

@@ -18084,13 +18084,13 @@
                         },
                         "type": "array",
                         "title": "Tool RAG IDs",
-                        "description": "RAG IDs made available to the LLM as a file_search tool. Use 'okp' to include the OKP vector store. When omitted, all registered BYOK vector stores are used (backward compatibility)."
+                        "description": "RAG IDs made available to the LLM as a file_search tool. Use 'okp' to include the OKP vector store. When omitted, tool RAG is disabled."
                     }
                 },
                 "additionalProperties": false,
                 "type": "object",
                 "title": "RagConfiguration",
-                "description": "RAG strategy configuration.\n\nControls which RAG sources are used for inline and tool-based retrieval.\n\nEach strategy lists RAG IDs to include. The special ID ``\"okp\"`` defined in constants,\nactivates the OKP provider; all other IDs refer to entries in ``byok_rag``.\n\nBackward compatibility:\n    - ``inline`` defaults to ``[]`` (no inline RAG).\n    - ``tool`` defaults to ``[]`` (no tool RAG).\n\nIf no RAG strategy is defined (inline and tool are empty),\nthe RAG tool will register all stores available to llama-stack."
+                "description": "RAG strategy configuration.\n\nControls which RAG sources are used for inline and tool-based retrieval.\n\nEach strategy lists RAG IDs to include. The special ID ``\"okp\"`` defined in constants,\nactivates the OKP provider; all other IDs refer to entries in ``byok_rag``.\n\nBoth ``inline`` and ``tool`` default to ``[]`` (disabled).\nEach must be explicitly configured to activate its respective RAG strategy."
             },
             "ReadinessResponse": {
                 "properties": {

docs/openapi.md

@@ -8155,18 +8155,14 @@ Controls which RAG sources are used for inline and tool-based retrieval.
 Each strategy lists RAG IDs to include. The special ID ``"okp"`` defined in constants,
 activates the OKP provider; all other IDs refer to entries in ``byok_rag``.
 
-Backward compatibility:
-    - ``inline`` defaults to ``[]`` (no inline RAG).
-    - ``tool`` defaults to ``[]`` (no tool RAG).
-
-If no RAG strategy is defined (inline and tool are empty),
-the RAG tool will register all stores available to llama-stack.
+Both ``inline`` and ``tool`` default to ``[]`` (disabled).
+Each must be explicitly configured to activate its respective RAG strategy.
 
 
 | Field | Type | Description |
 |-------|------|-------------|
 | inline | array | RAG IDs whose sources are injected as context before the LLM call. Use 'okp' to enable OKP inline RAG. Empty by default (no inline RAG). |
-| tool | array | RAG IDs made available to the LLM as a file_search tool. Use 'okp' to include the OKP vector store. When omitted, all registered BYOK vector stores are used (backward compatibility). |
+| tool | array | RAG IDs made available to the LLM as a file_search tool. Use 'okp' to include the OKP vector store. When omitted, tool RAG is disabled. |
 
 
 ## ReadinessResponse

examples/lightspeed-stack-byok-okp-rag.yaml

@@ -60,7 +60,7 @@ rag:
     - okp
   # Tool RAG: LLM can call file_search on demand to retrieve context
   # List rag_ids from byok_rag, or 'okp' to include OKP
-  # Omit to use all registered BYOK stores (backward compatibility)
+  # Omit to disable tool RAG
   tool:
     - ocp-docs
     - knowledge-base

src/models/config.py

@@ -2258,12 +2258,8 @@ class RagConfiguration(ConfigurationBase):
     Each strategy lists RAG IDs to include. The special ID ``"okp"`` defined in constants,
     activates the OKP provider; all other IDs refer to entries in ``byok_rag``.
 
-    Backward compatibility:
-        - ``inline`` defaults to ``[]`` (no inline RAG).
-        - ``tool`` defaults to ``[]`` (no tool RAG).
-
-    If no RAG strategy is defined (inline and tool are empty),
-    the RAG tool will register all stores available to llama-stack.
+    Both ``inline`` and ``tool`` default to ``[]`` (disabled).
+    Each must be explicitly configured to activate its respective RAG strategy.
     """
 
     inline: list[str] = Field(
@@ -2278,7 +2274,7 @@ class RagConfiguration(ConfigurationBase):
         title="Tool RAG IDs",
         description="RAG IDs made available to the LLM as a file_search tool. "
         f"Use '{constants.OKP_RAG_ID}' to include the OKP vector store. "
-        "When omitted, all registered BYOK vector stores are used (backward compatibility).",
+        "When omitted, tool RAG is disabled.",
     )
 
 

src/utils/responses.py

@@ -130,7 +130,7 @@
 async def get_vector_store_ids(
     client: AsyncLlamaStackClient,
 ) -> list[str]:
-    """Fetche all available vector stores from Llama Stack.
+    """Fetch all available vector stores from Llama Stack.
 
     Args:
         client: The AsyncLlamaStackClient to use for fetching stores
@@ -219,7 +219,7 @@ async def maybe_get_topic_summary(
     return await get_topic_summary(input_text, client, model_id)
 
 
-async def prepare_tools(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+async def prepare_tools(  # pylint: disable=too-many-arguments,too-many-positional-arguments,unused-argument
     client: AsyncLlamaStackClient,
     vector_store_ids: Optional[list[str]],
     no_tools: Optional[bool],
@@ -232,7 +232,7 @@ async def prepare_tools(  # pylint: disable=too-many-arguments,too-many-position
     Args:
         client: The Llama Stack client instance
         vector_store_ids: The list of vector store IDs to use for RAG tools
-            or None if all vector stores should be used
+            or None to fall back to rag.tool configuration
         no_tools: Whether to skip tool preparation
         token: Authentication token for MCP tools
         mcp_headers: Per-request headers for MCP servers
@@ -250,22 +250,16 @@ async def prepare_tools(  # pylint: disable=too-many-arguments,too-many-position
     # Vector store ID resolution priority:
     #   1. Per-request IDs: highest prio; customer-facing rag_ids are translated to vector_db_ids.
     #   2. rag.tool config IDs: used when no per-request IDs provided, and rag.tool is configured.
-    #      If rag.inline is configured, but not rag.tool, tool RAG is disabled.
-    #   3. All registered vector DBs: fallback when neither rag.tool nor rag.inline are configured.
-    #      IDs fetched from llama-stack are already internal and need no translation.
     byok_rags = configuration.configuration.byok_rag
 
     is_tool_rag_enabled = len(configuration.configuration.rag.tool) > 0
-    is_inline_rag_enabled = len(configuration.configuration.rag.inline) > 0
 
     if vector_store_ids is not None:
         effective_ids = resolve_vector_store_ids(vector_store_ids, byok_rags)
     elif is_tool_rag_enabled:
         effective_ids = resolve_vector_store_ids(
             configuration.configuration.rag.tool, byok_rags
         )
-    elif not is_inline_rag_enabled:
-        effective_ids = await get_vector_store_ids(client, None)
 
     # Add RAG tools if vector stores are available
     rag_tools = get_rag_tools(effective_ids)

tests/unit/utils/test_responses.py

@@ -1614,43 +1614,6 @@ async def test_prepare_tools_with_vector_store_ids(
         assert result[0].type == "file_search"
         assert result[0].vector_store_ids == ["vs1", "vs2"]
 
-    @pytest.mark.asyncio
-    async def test_prepare_tools_fetch_vector_stores(
-        self, mocker: MockerFixture
-    ) -> None:
-        """Test prepare_tools fetches vector stores when not specified."""
-        mock_client = mocker.AsyncMock()
-        mock_vector_store1 = mocker.Mock()
-        mock_vector_store1.id = "vs1"
-        mock_vector_store2 = mocker.Mock()
-        mock_vector_store2.id = "vs2"
-        mock_vector_stores = mocker.Mock()
-        mock_vector_stores.data = [mock_vector_store1, mock_vector_store2]
-        mock_client.vector_stores.list = mocker.AsyncMock(
-            return_value=mock_vector_stores
-        )
-        mocker.patch("utils.responses.get_mcp_tools", return_value=None)
-
-        result = await prepare_tools(mock_client, None, False, "token")
-        assert result is not None
-        assert len(result) == 1
-        assert isinstance(result[0], InputToolFileSearch)
-        assert result[0].vector_store_ids == ["vs1", "vs2"]
-
-    @pytest.mark.asyncio
-    async def test_prepare_tools_connection_error(self, mocker: MockerFixture) -> None:
-        """Test prepare_tools raises HTTPException on connection error."""
-        mock_client = mocker.AsyncMock()
-        mock_client.vector_stores.list = mocker.AsyncMock(
-            side_effect=APIConnectionError(
-                message="Connection failed", request=mocker.Mock()
-            )
-        )
-
-        with pytest.raises(HTTPException) as exc_info:
-            await prepare_tools(mock_client, None, False, "token")
-        assert exc_info.value.status_code == 503
-
     @pytest.mark.asyncio
     async def test_prepare_tools_with_mcp_servers(self, mocker: MockerFixture) -> None:
         """Test prepare_tools includes MCP tools."""
@@ -1666,20 +1629,6 @@ async def test_prepare_tools_with_mcp_servers(self, mocker: MockerFixture) -> No
         assert len(result) == 2  # RAG tool + MCP tool
         assert any(tool.type == "mcp" for tool in result)
 
-    @pytest.mark.asyncio
-    async def test_prepare_tools_api_status_error(self, mocker: MockerFixture) -> None:
-        """Test prepare_tools raises HTTPException on API status error when fetching vector stores."""
-        mock_client = mocker.AsyncMock()
-        mock_client.vector_stores.list = mocker.AsyncMock(
-            side_effect=APIStatusError(
-                message="API error", response=mocker.Mock(request=None), body=None
-            )
-        )
-
-        with pytest.raises(HTTPException) as exc_info:
-            await prepare_tools(mock_client, None, False, "token")
-        assert exc_info.value.status_code == 500
-
     @pytest.mark.asyncio
     async def test_prepare_tools_empty_toolgroups(self, mocker: MockerFixture) -> None:
         """Test prepare_tools returns None when no tools are available."""
@@ -1812,38 +1761,6 @@ async def test_passes_through_unknown_ids_in_prepare_tools(
         assert isinstance(result[0], InputToolFileSearch)
         assert result[0].vector_store_ids == ["raw-internal-id"]
 
-    @pytest.mark.asyncio
-    async def test_does_not_translate_when_ids_fetched_from_llama_stack(
-        self, mocker: MockerFixture
-    ) -> None:
-        """Test that IDs fetched from llama-stack (None path) are not translated."""
-        mock_client = mocker.AsyncMock()
-        mock_vector_store = mocker.Mock()
-        mock_vector_store.id = "vs-internal"
-        mock_vector_stores = mocker.Mock()
-        mock_vector_stores.data = [mock_vector_store]
-        mock_client.vector_stores.list = mocker.AsyncMock(
-            return_value=mock_vector_stores
-        )
-        mocker.patch("utils.responses.get_mcp_tools", return_value=None)
-
-        # Configure BYOK RAG whose rag_id matches the fetched ID so that
-        # accidental translation would change the result and fail the assertion
-        mock_byok_rag = mocker.Mock()
-        mock_byok_rag.rag_id = "vs-internal"
-        mock_byok_rag.vector_db_id = "vs-translated"
-        mock_config = mocker.Mock()
-        mock_config.configuration.byok_rag = [mock_byok_rag]
-        mock_config.configuration.rag.tool = []
-        mock_config.configuration.rag.inline = []
-        mocker.patch("utils.responses.configuration", mock_config)
-
-        result = await prepare_tools(mock_client, None, False, "token")
-        assert result is not None
-        # The IDs from llama-stack should be used as-is (no BYOK translation on None path)
-        assert isinstance(result[0], InputToolFileSearch)
-        assert result[0].vector_store_ids == ["vs-internal"]
-
 
 class TestPrepareToolsVectorStoreResolution:
     """Tests for vector store ID resolution priority in prepare_tools."""
@@ -1895,8 +1812,10 @@ async def test_rag_tool_config_ids_are_translated(
         mock_client.vector_stores.list.assert_not_called()
 
     @pytest.mark.asyncio
-    async def test_inline_rag_disables_tool_rag(self, mocker: MockerFixture) -> None:
-        """Test that configuring rag.inline without rag.tool disables tool RAG."""
+    async def test_inline_rag_config_does_not_affect_tool_rag(
+        self, mocker: MockerFixture
+    ) -> None:
+        """Test that configuring rag.inline have no effect on tool rag."""
         mock_client = mocker.AsyncMock()
         mocker.patch("utils.responses.get_mcp_tools", return_value=None)
 
@@ -1910,7 +1829,6 @@ async def test_inline_rag_disables_tool_rag(self, mocker: MockerFixture) -> None
 
         result = await prepare_tools(mock_client, None, False, "token")
 
-        # Tool RAG should be disabled — no RAG tool in result, no llama-stack fetch
         assert result is None
         mock_client.vector_stores.list.assert_not_called()
 
@@ -1936,30 +1854,22 @@ async def test_per_request_ids_override_rag_tool_config(
         mock_client.vector_stores.list.assert_not_called()
 
     @pytest.mark.asyncio
-    async def test_all_registered_dbs_used_when_neither_tool_nor_inline_configured(
+    async def test_tool_rag_disabled_when_tool_not_configured(
         self, mocker: MockerFixture
     ) -> None:
-        """Test fallback to all registered vector DBs when neither rag.tool nor rag.inline are set."""
+        """Test no rag tools is returned when rag.tool is not set and there is no per-request vector ids."""
         mock_client = mocker.AsyncMock()
-        mock_vs = mocker.Mock()
-        mock_vs.id = "vs-registered"
-        mock_list = mocker.Mock()
-        mock_list.data = [mock_vs]
-        mock_client.vector_stores.list = mocker.AsyncMock(return_value=mock_list)
         mocker.patch("utils.responses.get_mcp_tools", return_value=None)
 
         mock_config = mocker.Mock()
         mock_config.configuration.byok_rag = []
         mock_config.configuration.rag.tool = []
-        mock_config.configuration.rag.inline = []
         mocker.patch("utils.responses.configuration", mock_config)
 
         result = await prepare_tools(mock_client, None, False, "token")
 
-        assert result is not None
-        assert isinstance(result[0], InputToolFileSearch)
-        assert result[0].vector_store_ids == ["vs-registered"]
-        mock_client.vector_stores.list.assert_called_once()
+        assert result is None
+        mock_client.vector_stores.list.assert_not_called()
 
 
 class TestPrepareResponsesParams:
@@ -2150,9 +2060,9 @@ async def test_prepare_responses_params_includes_mcp_provider_data_headers(
 
         # The result should contain extra_headers with x-llamastack-provider-data
         dumped = result.model_dump()
-        assert dumped["extra_headers"] is not None, (
-            "extra_headers should not be None when MCP tools have headers"
-        )
+        assert (
+            dumped["extra_headers"] is not None
+        ), "extra_headers should not be None when MCP tools have headers"
         assert "x-llamastack-provider-data" in dumped["extra_headers"]
 
         provider_data = json.loads(