- Abstracted Solr away from user

- Config changed to list rag_id / okp stores per RAG mode: inline / tool

Author: are-ces

docs/byok_guide.md

@@ -36,9 +36,9 @@ BYOK (Bring Your Own Knowledge) is Lightspeed Core's implementation of Retrieval
 
 BYOK knowledge sources can be queried in two complementary modes, configured independently:
 
-### Inline RAG (pre-query injection)
+### Inline RAG
 
-Context is fetched from your BYOK vector stores and/or OKP **before** the LLM generates a response, and injected into every query automatically. No tool calls are required.
+Context is fetched from your BYOK vector stores and/or OKP and injected before the LLM request. No tool calls are required.
 
 ```mermaid
 graph TD
@@ -54,7 +54,7 @@ graph TD
 
 ### Tool RAG (on-demand retrieval)
 
-The LLM can call the `file_search` tool during generation when it decides external knowledge is needed. Only BYOK vector stores are supported in Tool RAG mode.
+The LLM can call the `file_search` tool during generation when it decides external knowledge is needed. Both BYOK vector stores and OKP are supported in Tool RAG mode.
 
 ```mermaid
 graph TD
@@ -67,7 +67,7 @@ graph TD
     B --> C{Need External Knowledge?}
     C -->|Yes| D[file_search Tool]
     C -->|No| E[Generate Response]
-    D --> F[BYOK Vector Stores]
+    D --> F[BYOK / OKP Vector Stores]
     F --> G[Retrieve Relevant Context]
     G --> B
     E --> H[Response to User]
@@ -78,7 +78,13 @@ Both modes rely on:
 - **Embedding Model**: Converts queries and documents into vector representations for similarity matching
 
 Inline RAG additionally supports:
-- **Score Multiplier**: Optional weight applied per BYOK vector store when mixing multiple sources. Allows custom prioritization of content. 
+- **Score Multiplier**: Optional weight applied per BYOK vector store when mixing multiple sources. Allows custom prioritization of content.
+
+> [!NOTE]
+> OKP and BYOK scores are not directly comparable (different scoring systems), so
+> `score_multiplier` does not apply to OKP results. To control the amount of retrieved
+> context, set the `BYOK_RAG_MAX_CHUNKS` and `OKP_RAG_MAX_CHUNKS` constants in `src/constants.py`
+> (defaults: 10 and 5 respectively). For Tool RAG, use `TOOL_RAG_MAX_CHUNKS` (default: 10).
 
 ---
 
@@ -290,29 +296,37 @@ registered_resources:
 
 ### Step 5: Configure RAG Strategy
 
-Add a `rag` section to your `lightspeed-stack.yaml` to choose how BYOK knowledge is used:
+Add a `rag` section to your `lightspeed-stack.yaml` to choose how BYOK knowledge is used.
+Each list entry is a `rag_id` from `byok_rag`, or the special value `okp-rag` for OKP.
 
 ```yaml
 rag:
-  # Inline RAG: inject context before every LLM response (no tool calls needed)
+  # Inline RAG: inject context before the LLM request (no tool calls needed)
   inline:
-    byok:
-      enabled: true   # fetch and inject BYOK vector store context pre-query
-    okp:
-      enabled: true   # fetch and inject OKP context pre-query
+    - my-docs         # rag_id from byok_rag
+    - okp-rag         # include OKP context inline
 
   # Tool RAG: the LLM can call file_search to retrieve context on demand
+  # Omit to use all registered BYOK stores (backward compatibility)
   tool:
-    byok:
-      enabled: true   # expose BYOK vector stores as the file_search tool
+    - my-docs         # expose this BYOK store as the file_search tool
+    - okp-rag         # expose OKP as the file_search tool
+
+# OKP provider settings (only relevant when okp-rag is listed above)
+okp:
+  offline: true       # true = use parent_id for source URLs, false = use reference_url
 ```
 
 Both modes can be enabled simultaneously. Choose based on your latency and control preferences:
 
 | Mode | When context is fetched | Tool call needed | Supported sources | score_multiplier |
 |------|------------------------|------------------|-------------------|-----------------|
-| Inline RAG | Before every query | No | BYOK + OKP | Yes (BYOK only) |
-| Tool RAG | On LLM demand | Yes | BYOK only | No |
+| Inline RAG | With every query | No | BYOK + OKP | Yes (BYOK only) |
+| Tool RAG | On LLM demand | Yes | BYOK + OKP | No |
+
+> [!TIP]
+> A ready-to-use example combining BYOK and OKP is available at
+> [`examples/lightspeed-stack-byok-okp-rag.yaml`](../examples/lightspeed-stack-byok-okp-rag.yaml).
 
 ---
 

docs/config.md

@@ -110,6 +110,22 @@ Microsoft Entra ID authentication attributes for Azure.
 
 BYOK (Bring Your Own Knowledge) RAG configuration.
 
+Each entry registers a local vector store with the service. The `rag_id` is the
+identifier used in `rag.inline` and `rag.tool` to select which stores to use.
+
+Example:
+
+```yaml
+byok_rag:
+  - rag_id: my-docs          # referenced in rag.inline / rag.tool
+    rag_type: inline::faiss
+    embedding_model: sentence-transformers/all-MiniLM-L6-v2
+    embedding_dimension: 384
+    vector_db_id: vs_abc123
+    db_path: /path/to/faiss_store.db
+    score_multiplier: 1.0
+```
+
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -526,68 +542,55 @@ the service can handle requests concurrently.
 
 Top-level RAG strategy configuration. Controls two complementary retrieval modes:
 
-- **Inline RAG**: context is fetched from OKP and/or BYOK vector stores and injected
-  into every query before the LLM responds.
+- **Inline RAG**: context is fetched from the listed sources and injected before the
+  LLM request.
 - **Tool RAG**: the LLM can call the `file_search` tool during generation to retrieve
-  context on demand from BYOK vector stores.
-
-
-| Field | Type | Description |
-|-------|------|-------------|
-| inline |  | Pre-query RAG from OKP and BYOK. See InlineRagConfiguration. |
-| tool |  | Tool-based RAG that the LLM can invoke. See ToolRagConfiguration. |
-
-
-## InlineRagConfiguration
-
-
-Pre-query RAG configuration that injects context before the LLM generates a response.
-
-Both OKP and BYOK sources can be enabled independently. When enabled, retrieved
-chunks are added as context on every query.
+  context on demand from the listed vector stores. Supports both BYOK and OKP.
 
+Each strategy is configured as a list of RAG IDs referencing entries in `byok_rag`.
+The special ID `okp-rag` activates the OKP provider (no `byok_rag` entry needed).
 
-| Field | Type | Description |
-|-------|------|-------------|
-| okp |  | OKP RAG configuration for pre-query context injection. |
-| byok |  | BYOK RAG configuration for pre-query context injection. |
-
-
-## OkpRagConfiguration
-
-
-OKP configuration for Inline RAG (pre-query context injection).
-
-Controls whether to use offline or online mode when building document URLs
-from vector search results, and enables/disables OKP vector IO functionality.
-
-
-| Field | Type | Description |
-|-------|------|-------------|
-| enabled | boolean | When True, enables OKP vector IO functionality for vector search queries. When False, disables OKP vector search processing. |
-| offline | boolean | When True, use parent_id for chunk source URLs. When False, use reference_url for chunk source URLs. |
-
+**Backward compatibility**: omitting `tool` uses all registered BYOK vector stores
+(equivalent to the old `tool.byok.enabled = True`). Omitting `inline` means no
+context is injected before the LLM request.
 
-## ByokRagConfiguration
+Example:
 
+```yaml
+rag:
+  inline:
+    - my-docs       # inject context from my-docs before the LLM request
+  tool:
+    - okp-rag       # LLM can search OKP as a tool
+    - my-docs       # LLM can also search my-docs as a tool
 
-Configuration to enable or disable BYOK RAG retrieval.
+okp:
+  offline: true     # use parent_id for OKP URL construction
+```
 
 
 | Field | Type | Description |
 |-------|------|-------------|
-| enabled | boolean | When True, queries BYOK vector stores for RAG context. Default: False. |
+| inline | list[string] | RAG IDs whose content is injected before the LLM request. Use `okp-rag` for OKP. Empty by default (no inline RAG). |
+| tool | list[string] or null | RAG IDs exposed as a `file_search` tool the LLM can invoke. Use `okp-rag` to include OKP. When omitted, all registered BYOK vector stores are used (backward compatibility). |
 
 
-## ToolRagConfiguration
+## OkpConfiguration
 
+OKP (Offline Knowledge Portal) provider settings. Only used when `okp-rag` is listed in `rag.inline` or `rag.tool`.
 
-Configuration for exposing RAG as a tool the LLM can call during generation.
+Example:
 
+```yaml
+okp:
+  offline: true                    # use parent_id for OKP URL construction
+  chunk_filter_query: "is_chunk:true"
+```
 
 | Field | Type | Description |
 |-------|------|-------------|
-| byok |  | BYOK RAG configuration for tool-based retrieval. Default: enabled. |
+| offline | boolean | When `true` (default), use `parent_id` for OKP chunk source URLs. When `false`, use `reference_url`. |
+| chunk_filter_query | string | OKP filter query (`fq`) applied to every OKP search request. Defaults to `"is_chunk:true"`. Extend with `AND` for extra constraints. |
 
 
 ## SplunkConfiguration

docs/openapi.json

@@ -4447,7 +4447,7 @@
                 ],
                 "summary": "Handle A2A Jsonrpc",
                 "description": "Handle A2A JSON-RPC requests following the A2A protocol specification.\n\nThis endpoint uses the DefaultRequestHandler from the A2A SDK to handle\nall JSON-RPC requests including message/send, message/stream, etc.\n\nThe A2A SDK application is created per-request to include authentication\ncontext while still leveraging FastAPI's authorization middleware.\n\nAutomatically detects streaming requests (message/stream JSON-RPC method)\nand returns a StreamingResponse to enable real-time chunk delivery.\n\nArgs:\n    request: FastAPI request object\n    auth: Authentication tuple\n    mcp_headers: MCP headers for context propagation\n\nReturns:\n    JSON-RPC response or streaming response",
-                "operationId": "handle_a2a_jsonrpc_a2a_post",
+                "operationId": "handle_a2a_jsonrpc_a2a_get",
                 "responses": {
                     "200": {
                         "description": "Successful Response",
@@ -4465,7 +4465,7 @@
                 ],
                 "summary": "Handle A2A Jsonrpc",
                 "description": "Handle A2A JSON-RPC requests following the A2A protocol specification.\n\nThis endpoint uses the DefaultRequestHandler from the A2A SDK to handle\nall JSON-RPC requests including message/send, message/stream, etc.\n\nThe A2A SDK application is created per-request to include authentication\ncontext while still leveraging FastAPI's authorization middleware.\n\nAutomatically detects streaming requests (message/stream JSON-RPC method)\nand returns a StreamingResponse to enable real-time chunk delivery.\n\nArgs:\n    request: FastAPI request object\n    auth: Authentication tuple\n    mcp_headers: MCP headers for context propagation\n\nReturns:\n    JSON-RPC response or streaming response",
-                "operationId": "handle_a2a_jsonrpc_a2a_post",
+                "operationId": "handle_a2a_jsonrpc_a2a_get",
                 "responses": {
                     "200": {
                         "description": "Successful Response",
@@ -5522,20 +5522,6 @@
                 "title": "ByokRag",
                 "description": "BYOK (Bring Your Own Knowledge) RAG configuration."
             },
-            "ByokRagConfiguration": {
-                "properties": {
-                    "enabled": {
-                        "type": "boolean",
-                        "title": "BYOK RAG enabled",
-                        "description": "When True, queries BYOK vector stores for RAG context.",
-                        "default": false
-                    }
-                },
-                "additionalProperties": false,
-                "type": "object",
-                "title": "ByokRagConfiguration",
-                "description": "BYOK RAG configuration."
-            },
             "CORSConfiguration": {
                 "properties": {
                     "allow_origins": {
@@ -5739,6 +5725,11 @@
                         "$ref": "#/components/schemas/RagConfiguration",
                         "title": "RAG configuration",
                         "description": "Configuration for all RAG strategies (inline and tool-based)."
+                    },
+                    "okp": {
+                        "$ref": "#/components/schemas/OkpConfiguration",
+                        "title": "OKP configuration",
+                        "description": "OKP provider settings. Only used when 'okp-rag' is listed in rag.inline or rag.tool."
                     }
                 },
                 "additionalProperties": false,
@@ -6980,24 +6971,6 @@
                     }
                 ]
             },
-            "InlineRagConfiguration": {
-                "properties": {
-                    "okp": {
-                        "$ref": "#/components/schemas/OkpRagConfiguration",
-                        "title": "OKP RAG configuration",
-                        "description": "Configuration for OKP RAG (inline)."
-                    },
-                    "byok": {
-                        "$ref": "#/components/schemas/ByokRagConfiguration",
-                        "title": "BYOK RAG configuration",
-                        "description": "Configuration for BYOK RAG (inline)."
-                    }
-                },
-                "additionalProperties": false,
-                "type": "object",
-                "title": "InlineRagConfiguration",
-                "description": "Inline RAG configuration.\n\nControls inline RAG from OKP and BYOK vector stores."
-            },
             "InternalServerErrorResponse": {
                 "properties": {
                     "status_code": {
@@ -7607,25 +7580,25 @@
                 "title": "OAuthFlows",
                 "description": "Defines the configuration for the supported OAuth 2.0 flows."
             },
-            "OkpRagConfiguration": {
+            "OkpConfiguration": {
                 "properties": {
-                    "enabled": {
-                        "type": "boolean",
-                        "title": "OKP RAG enabled",
-                        "description": "When True, queries OKP for RAG context.",
-                        "default": false
-                    },
                     "offline": {
                         "type": "boolean",
-                        "title": "Offline mode",
-                        "description": "When True, use parent_id for chunk source URLs. When False, use reference_url for chunk source URLs.",
+                        "title": "OKP offline mode",
+                        "description": "When True, use parent_id for OKP chunk source URLs. When False, use reference_url for chunk source URLs.",
                         "default": true
+                    },
+                    "chunk_filter_query": {
+                        "type": "string",
+                        "title": "OKP chunk filter query",
+                        "description": "OKP filter query applied to every OKP search request. Defaults to 'is_chunk:true' to restrict results to chunk documents. To add extra constraints, extend the expression using boolean syntax, e.g. 'is_chunk:true AND product:*openshift*'.",
+                        "default": "is_chunk:true"
                     }
                 },
                 "additionalProperties": false,
                 "type": "object",
-                "title": "OkpRagConfiguration",
-                "description": "OKP RAG configuration."
+                "title": "OkpConfiguration",
+                "description": "OKP (Offline Knowledge Portal) provider configuration.\n\nControls provider-specific behaviour for the OKP vector store.\nOnly relevant when ``\"okp-rag\"`` is listed in ``rag.inline`` or ``rag.tool``."
             },
             "OpenIdConnectSecurityScheme": {
                 "properties": {
@@ -8804,20 +8777,33 @@
             "RagConfiguration": {
                 "properties": {
                     "inline": {
-                        "$ref": "#/components/schemas/InlineRagConfiguration",
-                        "title": "Inline RAG configuration",
-                        "description": "Configuration for inline RAG from OKP and BYOK vector stores."
+                        "items": {
+                            "type": "string"
+                        },
+                        "type": "array",
+                        "title": "Inline RAG IDs",
+                        "description": "RAG IDs whose sources are injected as context before the LLM call. Use 'okp-rag' to enable OKP inline RAG. Empty by default (no inline RAG)."
                     },
                     "tool": {
-                        "$ref": "#/components/schemas/ToolRagConfiguration",
-                        "title": "Tool RAG configuration",
-                        "description": "Configuration for exposing RAG as a tool that the LLM can call."
+                        "anyOf": [
+                            {
+                                "items": {
+                                    "type": "string"
+                                },
+                                "type": "array"
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ],
+                        "title": "Tool RAG IDs",
+                        "description": "RAG IDs made available to the LLM as a file_search tool. Use 'okp-rag' to include the OKP vector store. When omitted, all registered BYOK vector stores are used (backward compatibility)."
                     }
                 },
                 "additionalProperties": false,
                 "type": "object",
                 "title": "RagConfiguration",
-                "description": "RAG strategy configuration.\n\nControls different RAG strategies: inline and tool-based."
+                "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-rag\"`` 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 ``None`` which means all registered vector stores\n      are used (identical to the previous ``tool.byok.enabled = True`` default)."
             },
             "ReadinessResponse": {
                 "properties": {
@@ -9585,19 +9571,6 @@
                 "title": "ToolCallSummary",
                 "description": "Model representing a tool call made during response generation (for tool_calls list)."
             },
-            "ToolRagConfiguration": {
-                "properties": {
-                    "byok": {
-                        "$ref": "#/components/schemas/ByokRagConfiguration",
-                        "title": "BYOK RAG configuration",
-                        "description": "Configuration for BYOK RAG as a tool."
-                    }
-                },
-                "additionalProperties": false,
-                "type": "object",
-                "title": "ToolRagConfiguration",
-                "description": "Tool RAG configuration.\n\nControls whether RAG functionality is exposed as a tool that the LLM can call."
-            },
             "ToolResultSummary": {
                 "properties": {
                     "id": {