Merge pull request #1511 from asimurka/add_solr_mode_request_attribute

LCORE-1429: Added configurable search mode option for solr provider

Author: tisnik

docs/rag_guide.md

@@ -339,7 +339,7 @@ curl -sX POST http://localhost:8080/v1/query \
 2. Vector search is performed with configurable parameters:
    - `k`: Number of results (default: 5)
    - `score_threshold`: Minimum similarity score (default: 0.0)  
-   - `mode`: Search mode (default: "hybrid")
+   - `mode`: Search mode (default: "hybrid"). Per-request configurable.
 3. Results include document metadata and source URLs
 4. Document URLs are built based on the `offline` setting:
    - **Offline mode**: Uses `parent_id` with Mimir base URL
@@ -357,8 +357,19 @@ okp:
   chunk_filter_query: "product:*openshift*"
 ```
 
-> [!NOTE]
-> This static filter is a temporary work-around until dynamic per-request filtering is supported.
+Per-request filtering is also available on all inference endpoints via request field **`solr`**: `mode` (`semantic`, `hybrid`, or `lexical`) and `filters` (key:value format). Legacy payloads that omit `mode`/`filters` and send filter key:value pairs at the top level still work with `mode` set to `hybrid`. 
+
+Example:
+
+```json
+{
+  "query": "How do I configure routes?",
+  "solr": {
+    "mode": "hybrid",
+    "filters": { "fq": ["product:*openshift*"] }
+  }
+}
+```
 
 **Prerequisites:**
 

docs/responses.md

@@ -108,7 +108,7 @@ The following fields are LCORE-specific request extensions and are not part of t
 |-------|------|-------------|----------|
 | `generate_topic_summary` | boolean | Generate topic summary for new conversations. Default: true | No |
 | `shield_ids` | array[string] | Shield IDs to apply. If omitted, all configured shields in LCORE are used | No |
-| `solr` | dictionary | Solr vector_io provider query parameters | No |
+| `solr` | object | Optional `mode` and `filters`. Legacy top-level filter-only objects are still accepted. | No |
 
 
 ### Field Mappings
@@ -599,7 +599,7 @@ The API introduces extensions that are not part of the OpenResponses specificati
 
 - `generate_topic_summary` (request) — When set to `true` and a new conversation is created, a topic summary is automatically generated and stored in conversation metadata.
 - `shield_ids` (request) — Optional list of safety shield IDs to apply. If omitted, all configured shields are used.
-- `solr` (request) — Solr vector_io provider query parameters (e.g. filter queries).
+- `solr` (request) — Object with optional `mode` (`semantic`, `hybrid`, or `lexical`) and `filters` (Solr vector_io provider payload). Legacy filter-only objects (no `mode`/`filters` wrapper) still work.
 - `available_quotas` (response) — Provides real-time quota information from all configured quota limiters.
 
 ### System Prompt Resolution

src/models/requests.py

@@ -4,7 +4,7 @@
 
 import json
 from enum import Enum
-from typing import Any, Optional, Self
+from typing import Any, Literal, Optional, Self
 
 from llama_stack_api.openai_responses import (
     OpenAIResponseInputTool as InputTool,
@@ -24,7 +24,7 @@
 from llama_stack_api.openai_responses import (
     OpenAIResponseToolMCP as OutputToolMCP,
 )
-from pydantic import BaseModel, Field, field_validator, model_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 from configuration import configuration
 from constants import (
@@ -34,6 +34,7 @@
     MEDIA_TYPE_JSON,
     MEDIA_TYPE_TEXT,
     RESPONSES_REQUEST_MAX_SIZE,
+    SOLR_VECTOR_SEARCH_DEFAULT_MODE,
 )
 from log import get_logger
 from utils import suid
@@ -122,6 +123,56 @@ class Attachment(BaseModel):
     }
 
 
+class SolrVectorSearchRequest(BaseModel):
+    """LCORE Solr inline RAG options for ``vector_io.query`` (mode and provider filters).
+
+    Attributes:
+        mode: Solr vector_io search mode. When omitted, the server default (hybrid) is used.
+        filters: Solr provider filter payload passed through as params['solr'].
+
+    Legacy clients may send a plain JSON object with filter keys only;
+    that object is accepted as filters with mode unset (server default applies).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    mode: Optional[Literal["semantic", "hybrid", "lexical"]] = Field(
+        None,
+        description=(
+            "Solr vector_io search mode. When omitted, the server default "
+            f"({SOLR_VECTOR_SEARCH_DEFAULT_MODE!r}) is used."
+        ),
+        examples=["hybrid", "semantic", "lexical"],
+    )
+    filters: Optional[dict[str, Any]] = Field(
+        None,
+        description="Solr provider filter payload passed through as params['solr'].",
+        examples=[{"fq": ["product:*openshift*", "product_version:*4.16*"]}],
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def coerce_legacy_plain_dict(cls, data: Any) -> Any:
+        """Treat a legacy top-level filter dict as filters (backward compatibility).
+
+        Args:
+            data: Raw JSON, typically a dict or None.
+
+        Returns:
+            Normalized dict for Pydantic model validation, or the original non-dict value.
+        """
+        if data is None or not isinstance(data, dict):
+            return data
+        if "filters" in data or "mode" in data:
+            return data
+        logger.warning(
+            "Solr inline RAG: sending filter fields at the top level of `solr` without "
+            "`mode` or `filters` is deprecated and will be removed; use "
+            '`{"mode": "<semantic|hybrid|lexical>", "filters": {...}}` instead.'
+        )
+        return {"mode": None, "filters": data}
+
+
 class QueryRequest(BaseModel):
     """Model representing a request for the LLM (Language Model).
 
@@ -137,6 +188,7 @@ class QueryRequest(BaseModel):
         media_type: The optional media type for response format (application/json or text/plain).
         vector_store_ids: The optional list of specific vector store IDs to query for RAG.
         shield_ids: The optional list of safety shield IDs to apply.
+        solr: Optional Solr inline RAG options (mode, filters) or legacy filter-only dict.
 
     Example:
         ```python
@@ -227,13 +279,18 @@ class QueryRequest(BaseModel):
         examples=["llama-guard", "custom-shield"],
     )
 
-    solr: Optional[dict[str, Any]] = Field(
+    solr: Optional[SolrVectorSearchRequest] = Field(
         None,
-        description="Solr-specific query parameters including filter queries",
+        description=(
+            "Solr inline RAG config: mode (semantic, hybrid, lexical) and filters; "
+            "a legacy filter-only object (e.g. fq) is still accepted."
+        ),
         examples=[
-            {"fq": ["product:*openshift*", "product_version:*4.16*"]},
+            {"mode": "hybrid", "filters": {"fq": ["product:*openshift*"]}},
+            {"filters": {"fq": ["product:*openshift*", "product_version:*4.16*"]}},
         ],
     )
+
     # provides examples for /docs endpoint
     model_config = {
         "extra": "forbid",
@@ -695,8 +752,7 @@ class ResponsesRequest(BaseModel):
             topic summary for new conversations. Defaults to True.
         shield_ids: LCORE-specific list of safety shield IDs to apply. If None, all
             configured shields are used.
-        solr: LCORE-specific Solr vector_io provider query parameters (e.g. filter
-            queries). Optional.
+        solr: Optional Solr inline RAG options (mode, filters) or legacy filter-only dict.
     """
 
     input: ResponseInput
@@ -722,7 +778,7 @@ class ResponsesRequest(BaseModel):
     # LCORE-specific attributes
     generate_topic_summary: Optional[bool] = True
     shield_ids: Optional[list[str]] = None
-    solr: Optional[dict[str, Any]] = None
+    solr: Optional[SolrVectorSearchRequest] = None
 
     model_config = {
         "extra": "forbid",

src/utils/vector_search.py

@@ -17,6 +17,7 @@
 import constants
 from configuration import configuration
 from log import get_logger
+from models.requests import SolrVectorSearchRequest
 from models.responses import ReferencedDocument
 from utils.responses import resolve_vector_store_ids
 from utils.types import RAGChunk, RAGContext, ResponseInput
@@ -52,18 +53,32 @@ def _get_solr_vector_store_ids() -> list[str]:
     return vector_store_ids
 
 
-def _build_query_params(solr: Optional[dict[str, Any]] = None) -> dict[str, Any]:
-    """Build query parameters for vector search."""
+def _build_query_params(
+    solr: Optional[SolrVectorSearchRequest] = None,
+) -> dict[str, Any]:
+    """Build query parameters for Solr vector_io search.
+
+    Args:
+        solr: Optional structured Solr request (mode and filters from the API).
+
+    Returns:
+        Parameter dictionary for ``vector_io.query``.
+    """
+    resolved_mode = (
+        solr.mode
+        if solr is not None and solr.mode is not None
+        else constants.SOLR_VECTOR_SEARCH_DEFAULT_MODE
+    )
     params: dict[str, Any] = {
         "k": constants.SOLR_VECTOR_SEARCH_DEFAULT_K,
         "score_threshold": constants.SOLR_VECTOR_SEARCH_DEFAULT_SCORE_THRESHOLD,
-        "mode": constants.SOLR_VECTOR_SEARCH_DEFAULT_MODE,
+        "mode": resolved_mode,
     }
     logger.debug("Initial params: %s", params)
     logger.debug("query_request.solr: %s", solr)
 
-    if solr is not None:
-        params["solr"] = solr
+    if solr is not None and solr.filters is not None:
+        params["solr"] = solr.filters
         logger.debug("Final params with solr filters: %s", params)
     else:
         logger.debug("No solr filters provided")
@@ -438,14 +453,14 @@ async def _fetch_byok_rag(
 async def _fetch_solr_rag(
     client: AsyncLlamaStackClient,
     query: str,
-    solr: Optional[dict[str, Any]] = None,
+    solr: Optional[SolrVectorSearchRequest] = None,
 ) -> tuple[list[RAGChunk], list[ReferencedDocument]]:
     """Fetch chunks and documents from Solr RAG source.
 
     Args:
         client: The AsyncLlamaStackClient to use for the request
         query: The user's query
-        solr: Solr query parameters
+        solr: Structured Solr inline RAG request from the API (optional).
 
     Returns:
         Tuple containing:
@@ -516,7 +531,7 @@ async def build_rag_context(
     moderation_decision: str,
     query: str,
     vector_store_ids: Optional[list[str]],
-    solr: Optional[dict[str, Any]] = None,
+    solr: Optional[SolrVectorSearchRequest] = None,
 ) -> RAGContext:
     """Build RAG context by fetching and merging chunks from all enabled sources.
 
@@ -527,7 +542,7 @@ async def build_rag_context(
         moderation_decision: The moderation decision
         query: The user's query
         vector_store_ids: The vector store IDs to query
-        solr: The Solr query parameters
+        solr: Structured Solr inline RAG request from the API (optional).
 
     Returns:
         RAGContext containing formatted context text and referenced documents

tests/unit/models/requests/test_query_request.py

@@ -5,7 +5,7 @@
 import pytest
 from pytest_mock import MockerFixture
 
-from models.requests import Attachment, QueryRequest
+from models.requests import Attachment, QueryRequest, SolrVectorSearchRequest
 
 
 class TestQueryRequest:
@@ -140,3 +140,23 @@ def test_generate_topic_summary_explicit_true(self) -> None:
             query="Tell me about Kubernetes", generate_topic_summary=True
         )  # pyright: ignore[reportCallIssue]
         assert qr.generate_topic_summary is True
+
+    def test_solr_legacy_plain_dict(self) -> None:
+        """Legacy clients may send filter keys as a plain object on ``solr``."""
+        qr = QueryRequest(
+            query="q",
+            solr={"fq": ["a:b"]},
+        )  # pyright: ignore[reportCallIssue]
+        solr_request = SolrVectorSearchRequest.model_validate(qr.solr)
+        assert solr_request.mode is None
+        assert solr_request.filters == {"fq": ["a:b"]}
+
+    def test_solr_structured_mode_and_filters(self) -> None:
+        """New clients send ``mode`` and ``filters`` under ``solr``."""
+        qr = QueryRequest(
+            query="q",
+            solr={"mode": "hybrid", "filters": {"fq": ["x:y"]}},
+        )  # pyright: ignore[reportCallIssue]
+        solr_request = SolrVectorSearchRequest.model_validate(qr.solr)
+        assert solr_request.mode == "hybrid"
+        assert solr_request.filters == {"fq": ["x:y"]}

tests/unit/utils/test_vector_search.py

@@ -6,6 +6,7 @@
 
 import constants
 from configuration import AppConfig
+from models.requests import SolrVectorSearchRequest
 from utils.types import RAGChunk
 from utils.vector_search import (
     _build_document_url,
@@ -68,12 +69,38 @@ def test_default_params(self) -> None:
 
     def test_with_solr_filters(self) -> None:
         """Test parameters when solr filters are provided."""
-        solr_filters = {"filter": "value"}
-        params = _build_query_params(solr=solr_filters)
+        solr = SolrVectorSearchRequest.model_validate({"filter": "value"})
+        params = _build_query_params(solr=solr)
 
-        assert params["solr"] == solr_filters
+        assert params["solr"] == {"filter": "value"}
         assert params["k"] == constants.SOLR_VECTOR_SEARCH_DEFAULT_K
 
+    def test_custom_mode(self) -> None:
+        """Request mode overrides the default Solr vector_io mode."""
+        solr = SolrVectorSearchRequest(mode="lexical")
+        params = _build_query_params(solr=solr)
+
+        assert params["mode"] == "lexical"
+        assert "solr" not in params
+
+    def test_mode_with_solr_filters(self) -> None:
+        """Custom mode is combined with solr filter payload."""
+        solr = SolrVectorSearchRequest(
+            mode="semantic", filters={"fq": ["product:*openshift*"]}
+        )
+        params = _build_query_params(solr=solr)
+
+        assert params["mode"] == "semantic"
+        assert params["solr"] == {"fq": ["product:*openshift*"]}
+
+    def test_mode_with_only_filters(self) -> None:
+        """Mode is set to default value when only filters are provided."""
+        solr = SolrVectorSearchRequest(filters={"fq": ["product:*openshift*"]})
+        params = _build_query_params(solr=solr)
+
+        assert params["mode"] == constants.SOLR_VECTOR_SEARCH_DEFAULT_MODE
+        assert params["solr"] == {"fq": ["product:*openshift*"]}
+
 
 class TestExtractByokRagChunks:
     """Tests for _extract_byok_rag_chunks function."""
@@ -604,6 +631,40 @@ async def test_solr_enabled_success(self, mocker: MockerFixture) -> None:
         assert rag_chunks[0].content == "Solr content"
         assert rag_chunks[0].source == constants.OKP_RAG_ID
 
+    @pytest.mark.asyncio
+    async def test_solr_enabled_passes_request_mode_to_vector_io(
+        self, mocker: MockerFixture
+    ) -> None:
+        """OKP vector_io.query receives the mode from the API request."""
+        config_mock = mocker.Mock(spec=AppConfig)
+        config_mock.inline_solr_enabled = True
+        config_mock.okp.offline = True
+        config_mock.okp.rhokp_url = "https://okp.test"
+        mocker.patch("utils.vector_search.configuration", config_mock)
+
+        chunk_mock = mocker.Mock()
+        chunk_mock.content = "Solr content"
+        chunk_mock.metadata = {"parent_id": "parent_1", "title": "Solr Doc"}
+        chunk_mock.chunk_metadata = None
+
+        query_response = mocker.Mock()
+        query_response.chunks = [chunk_mock]
+        query_response.scores = [0.85]
+
+        client_mock = mocker.AsyncMock()
+        client_mock.vector_io.query.return_value = query_response
+
+        await _fetch_solr_rag(
+            client_mock,
+            "test query",
+            SolrVectorSearchRequest(mode="semantic", filters={"fq": ["x:y"]}),
+        )
+
+        client_mock.vector_io.query.assert_called_once()
+        call_kwargs = client_mock.vector_io.query.call_args.kwargs
+        assert call_kwargs["params"]["mode"] == "semantic"
+        assert call_kwargs["params"]["solr"] == {"fq": ["x:y"]}
+
 
 class TestBuildRagContext:
     """Tests for build_rag_context async function."""