diff --git a/docs/models/common.json b/docs/models/common.json
index d4c2034f8..26b7533d3 100644
--- a/docs/models/common.json
+++ b/docs/models/common.json
@@ -1610,16 +1610,17 @@
},
"SolrVectorSearchRequest": {
"additionalProperties": false,
- "description": "LCORE Solr inline RAG options for vector_io.query (mode and provider filters).\n\nAttributes:\n mode: Solr vector_io search mode. When omitted, the server default (hybrid) is used.\n filters: Solr provider filter payload passed through as params['solr'].\n\nLegacy clients may send a plain JSON object with filter keys only;\nthat object is accepted as filters with mode unset (server default applies).",
+ "description": "LCORE Solr inline RAG options for vector_io.query (mode and provider filters).\n\nAttributes:\n mode: Solr vector_io search mode. When omitted, the configured OKP default is used.\n filters: Solr provider filter payload passed through as params['solr'].\n\nLegacy clients may send a plain JSON object with filter keys only;\nthat object is accepted as filters with mode unset (server default applies).",
"properties": {
"mode": {
"type": "string",
"nullable": true,
"default": null,
- "description": "Solr vector_io search mode. When omitted, the server default ('hybrid') is used.",
+ "description": "Solr vector_io search mode. When omitted, the configured OKP default is used; otherwise 'hybrid' applies. 'keyword' and 'lexical' both use BM25 text search.",
"examples": [
"hybrid",
"semantic",
+ "keyword",
"lexical"
],
"title": "Mode"
diff --git a/docs/models/common.md b/docs/models/common.md
index 1846c3a73..d572b0b39 100644
--- a/docs/models/common.md
+++ b/docs/models/common.md
@@ -777,7 +777,7 @@ Attributes:
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.
+ mode: Solr vector_io search mode. When omitted, the configured OKP default is used.
filters: Solr provider filter payload passed through as params['solr'].
Legacy clients may send a plain JSON object with filter keys only;
@@ -786,7 +786,7 @@ that object is accepted as filters with mode unset (server default applies).
| Field | Type | Description |
|-------|------|-------------|
-| mode | string | Solr vector_io search mode. When omitted, the server default ('hybrid') is used. |
+| mode | string | Solr vector_io search mode. When omitted, the configured OKP default is used; otherwise 'hybrid' applies. 'keyword' and 'lexical' both use BM25 text search. |
| filters | object | Solr provider filter payload passed through as params['solr']. Supports structured metadata filters (eq, ne, in, nin comparison operators). Legacy filter-only objects (e.g. fq) are still accepted. |
diff --git a/docs/models/common.puml b/docs/models/common.puml
index 8090972f0..42f754979 100644
--- a/docs/models/common.puml
+++ b/docs/models/common.puml
@@ -240,7 +240,7 @@ class "SkillMetadata" as src.models.common.skills.SkillMetadata {
}
class "SolrVectorSearchRequest" as src.models.common.query.SolrVectorSearchRequest {
filters : Optional[dict[str, Any]]
- mode : Optional[Literal['semantic', 'hybrid', 'lexical']]
+ mode : Optional[Literal['semantic', 'hybrid', 'lexical', 'keyword']]
model_config : ConfigDict
coerce_legacy_plain_dict(data: Any) -> Any
}
diff --git a/docs/models/common.svg b/docs/models/common.svg
index 62325d509..18e82fa16 100644
--- a/docs/models/common.svg
+++ b/docs/models/common.svg
@@ -480,16 +480,16 @@
-
-
-
- SolrVectorSearchRequest
-
- filters : Optional[dict[str, Any]]
- mode : Optional[Literal['semantic', 'hybrid', 'lexical']]
- model_config : ConfigDict
-
- coerce_legacy_plain_dict(data: Any) -> Any
+
+
+
+ SolrVectorSearchRequest
+
+ filters : Optional[dict[str, Any]]
+ mode : Optional[Literal['semantic', 'hybrid', 'lexical', 'keyword']]
+ model_config : ConfigDict
+
+ coerce_legacy_plain_dict(data: Any) -> Any
@@ -564,16 +564,16 @@
-
-
-
- ToolCallSummary
-
- args : Optional[dict[str, Any]]
- id : Optional[str]
- name : Optional[str]
- type : Optional[str]
-
+
+
+
+ ToolCallSummary
+
+ args : Optional[dict[str, Any]]
+ id : Optional[str]
+ name : Optional[str]
+ type : Optional[str]
+
@@ -760,6 +760,6 @@
metadata
-
+
diff --git a/docs/models/requests.json b/docs/models/requests.json
index 746de36d6..e06bff83d 100644
--- a/docs/models/requests.json
+++ b/docs/models/requests.json
@@ -2657,16 +2657,17 @@
},
"SolrVectorSearchRequest": {
"additionalProperties": false,
- "description": "LCORE Solr inline RAG options for vector_io.query (mode and provider filters).\n\nAttributes:\n mode: Solr vector_io search mode. When omitted, the server default (hybrid) is used.\n filters: Solr provider filter payload passed through as params['solr'].\n\nLegacy clients may send a plain JSON object with filter keys only;\nthat object is accepted as filters with mode unset (server default applies).",
+ "description": "LCORE Solr inline RAG options for vector_io.query (mode and provider filters).\n\nAttributes:\n mode: Solr vector_io search mode. When omitted, the configured OKP default is used.\n filters: Solr provider filter payload passed through as params['solr'].\n\nLegacy clients may send a plain JSON object with filter keys only;\nthat object is accepted as filters with mode unset (server default applies).",
"properties": {
"mode": {
"type": "string",
"nullable": true,
"default": null,
- "description": "Solr vector_io search mode. When omitted, the server default ('hybrid') is used.",
+ "description": "Solr vector_io search mode. When omitted, the configured OKP default is used; otherwise 'hybrid' applies. 'keyword' and 'lexical' both use BM25 text search.",
"examples": [
"hybrid",
"semantic",
+ "keyword",
"lexical"
],
"title": "Mode"
diff --git a/docs/models/requests.md b/docs/models/requests.md
index 0d9821e9d..bec56c568 100644
--- a/docs/models/requests.md
+++ b/docs/models/requests.md
@@ -1194,7 +1194,7 @@ Examples:
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.
+ mode: Solr vector_io search mode. When omitted, the configured OKP default is used.
filters: Solr provider filter payload passed through as params['solr'].
Legacy clients may send a plain JSON object with filter keys only;
@@ -1203,7 +1203,7 @@ that object is accepted as filters with mode unset (server default applies).
| Field | Type | Description |
|-------|------|-------------|
-| mode | string | Solr vector_io search mode. When omitted, the server default ('hybrid') is used. |
+| mode | string | Solr vector_io search mode. When omitted, the configured OKP default is used; otherwise 'hybrid' applies. 'keyword' and 'lexical' both use BM25 text search. |
| filters | object | Solr provider filter payload passed through as params['solr']. Supports structured metadata filters (eq, ne, in, nin comparison operators). Legacy filter-only objects (e.g. fq) are still accepted. |
diff --git a/docs/models/successful_responses.json b/docs/models/successful_responses.json
index 54217f527..b959037fe 100644
--- a/docs/models/successful_responses.json
+++ b/docs/models/successful_responses.json
@@ -400,107 +400,27 @@
"title": "AzureEntraIdConfiguration",
"type": "object"
},
- "ByokRag": {
+ "ByokConfiguration": {
"additionalProperties": false,
- "description": "BYOK (Bring Your Own Knowledge) RAG configuration.",
+ "description": "BYOK (Bring Your Own Knowledge) configuration.",
"properties": {
- "rag_id": {
- "description": "Unique RAG ID",
- "minLength": 1,
- "title": "RAG ID",
- "type": "string"
- },
- "rag_type": {
- "default": "inline::faiss",
- "description": "Type of RAG database (e.g. 'inline::faiss', 'remote::pgvector').",
- "minLength": 1,
- "title": "RAG type",
- "type": "string"
- },
- "embedding_model": {
- "default": "sentence-transformers/all-mpnet-base-v2",
- "description": "Embedding model identification",
- "minLength": 1,
- "title": "Embedding model",
- "type": "string"
- },
- "embedding_dimension": {
- "default": 768,
- "description": "Dimensionality of embedding vectors.",
+ "max_chunks": {
+ "default": 10,
+ "description": "Maximum total number of chunks returned across all BYOK stores.",
"minimum": 0,
- "title": "Embedding dimension",
+ "title": "Max BYOK chunks",
"type": "integer"
},
- "vector_db_id": {
- "description": "Vector database identification.",
- "minLength": 1,
- "title": "Vector DB ID",
- "type": "string"
- },
- "db_path": {
- "type": "string",
- "nullable": true,
- "default": null,
- "description": "Path to RAG database. Required for inline::faiss.",
- "title": "DB path"
- },
- "score_multiplier": {
- "default": 1.0,
- "description": "Multiplier applied to relevance scores from this vector store. Used to weight results when querying multiple knowledge sources. Values > 1 boost this store's results; values < 1 reduce them.",
- "minimum": 0,
- "title": "Score multiplier",
- "type": "number"
- },
- "host": {
- "type": "string",
- "nullable": true,
- "default": null,
- "description": "PostgreSQL host for remote::pgvector. Defaults to ${env.POSTGRES_HOST} when rag_type is remote::pgvector.",
- "title": "PostgreSQL host"
- },
- "port": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "integer"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "PostgreSQL port for remote::pgvector. Defaults to ${env.POSTGRES_PORT} when rag_type is remote::pgvector. Accepts string placeholders and integer values.",
- "title": "PostgreSQL port"
- },
- "db": {
- "type": "string",
- "nullable": true,
- "default": null,
- "description": "PostgreSQL database name for remote::pgvector. Defaults to ${env.POSTGRES_DATABASE} when rag_type is remote::pgvector.",
- "title": "PostgreSQL database"
- },
- "user": {
- "type": "string",
- "nullable": true,
- "default": null,
- "description": "PostgreSQL user for remote::pgvector. Defaults to ${env.POSTGRES_USER} when rag_type is remote::pgvector.",
- "title": "PostgreSQL user"
- },
- "password": {
- "type": "string",
- "nullable": true,
- "default": null,
- "description": "PostgreSQL password for remote::pgvector. Defaults to ${env.POSTGRES_PASSWORD} when rag_type is remote::pgvector.",
- "title": "PostgreSQL password"
+ "stores": {
+ "description": "List of BYOK RAG store configurations.",
+ "items": {
+ "$ref": "`#/components/schemas/`RagStore"
+ },
+ "title": "BYOK RAG stores",
+ "type": "array"
}
},
- "required": [
- "rag_id",
- "vector_db_id"
- ],
- "title": "ByokRag",
+ "title": "ByokConfiguration",
"type": "object"
},
"CORSConfiguration": {
@@ -775,6 +695,13 @@
"title": "Service name",
"type": "string"
},
+ "config_format_version": {
+ "type": "string",
+ "nullable": true,
+ "default": null,
+ "description": "Optional explicit marker of the configuration format. When set, it must agree with the shape detected from the configuration body: 'unified' requires a synthesis input (a non-empty inference.providers, a non-empty vector_store.providers, or a llama_stack.config block), 'legacy' requires no synthesis input. Reserved as the lever for a future breaking change of the unified schema (R11).",
+ "title": "Configuration format version"
+ },
"service": {
"$ref": "`#/components/schemas/`ServiceConfiguration",
"description": "This section contains Lightspeed Core Stack service configuration.",
@@ -853,17 +780,9 @@
"description": "Settings for human-in-the-loop approval of MCP tool invocations",
"title": "Approvals configuration"
},
- "byok_rag": {
- "description": "BYOK RAG configuration. This configuration can be used to reconfigure Llama Stack through its run.yaml configuration file",
- "items": {
- "$ref": "`#/components/schemas/`ByokRag"
- },
- "title": "BYOK RAG configuration",
- "type": "array"
- },
"vector_store": {
"$ref": "`#/components/schemas/`VectorStoreConfiguration",
- "description": "Dynamic vector-store provider capacity for runtime POST /v1/vector-stores creates. Not the same as byok_rag (static registered corpora). When providers is non-empty, default_provider is required and must match one of providers[].id. Applied in unified synthesis only.",
+ "description": "Dynamic vector-store provider capacity for runtime POST /v1/vector-stores creates. Not the same as rag.byok.stores (static registered corpora). When providers is non-empty, default_provider is required and must match one of providers[].id. Applied in unified synthesis only.",
"title": "Vector store configuration"
},
"a2a_state": {
@@ -918,19 +837,9 @@
},
"rag": {
"$ref": "`#/components/schemas/`RagConfiguration",
- "description": "Configuration for all RAG strategies (inline and tool-based).",
+ "description": "Unified RAG configuration: BYOK stores, OKP provider, and retrieval strategies (inline and tool-based).",
"title": "RAG configuration"
},
- "okp": {
- "$ref": "`#/components/schemas/`OkpConfiguration",
- "description": "OKP provider settings. Only used when 'okp' is listed in rag.inline or rag.tool.",
- "title": "OKP configuration"
- },
- "reranker": {
- "$ref": "`#/components/schemas/`RerankerConfiguration",
- "description": "Configuration for neural reranking of RAG chunks using cross-encoder.",
- "title": "Reranker configuration"
- },
"skills": {
"anyOf": [
{
@@ -993,7 +902,6 @@
"authorization": {
"access_rules": []
},
- "byok_rag": [],
"conversation_cache": {
"memory": null,
"postgres": null,
@@ -1043,6 +951,33 @@
},
"sqlite": null
},
+ "rag": {
+ "byok": {
+ "max_chunks": 10,
+ "stores": []
+ },
+ "okp": {
+ "chunk_filter_query": null,
+ "max_chunks": 5,
+ "offline": true,
+ "rhokp_url": null
+ },
+ "retrieval": {
+ "inline": {
+ "max_chunks": 10,
+ "reranker": {
+ "enabled": false,
+ "model": "cross-encoder/ms-marco-MiniLM-L6-v2"
+ },
+ "sources": []
+ },
+ "tool": {
+ "max_chunks": 10,
+ "reranker": null,
+ "sources": []
+ }
+ }
+ },
"service": {
"access_log": true,
"auth_enabled": false,
@@ -2568,7 +2503,7 @@
},
"OkpConfiguration": {
"additionalProperties": false,
- "description": "OKP (Offline Knowledge Portal) provider configuration.\n\nControls provider-specific behaviour for the OKP vector store.\nOnly relevant when ``\"okp\"`` is listed in ``rag.inline`` or ``rag.tool``.",
+ "description": "OKP (Offline Knowledge Portal) provider configuration.\n\nControls provider-specific behaviour for the OKP vector store.\nOnly relevant when ``\"okp\"`` is listed in ``rag.retrieval.inline.sources``\nor ``rag.retrieval.tool.sources``.",
"properties": {
"rhokp_url": {
"type": "string",
@@ -2589,6 +2524,20 @@
"default": null,
"description": "Additional OKP filter query applied to every OKP search request. Use Solr boolean syntax, e.g. 'product:ansible AND product:*openshift*'.",
"title": "OKP chunk filter query"
+ },
+ "search_mode": {
+ "type": "string",
+ "nullable": true,
+ "default": null,
+ "description": "Default Solr search mode for OKP queries. 'keyword' uses BM25 text search (no embedding model needed). 'hybrid' combines vector + keyword search. 'semantic' uses pure vector search. When unset, falls back to the global default ('hybrid').",
+ "title": "OKP search mode"
+ },
+ "max_chunks": {
+ "default": 5,
+ "description": "Maximum number of chunks fetched from OKP.",
+ "minimum": 0,
+ "title": "Max OKP chunks",
+ "type": "integer"
}
},
"title": "OkpConfiguration",
@@ -4879,28 +4828,130 @@
},
"RagConfiguration": {
"additionalProperties": false,
- "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.",
+ "description": "Unified RAG configuration.\n\nGroups all RAG-related settings: BYOK stores, OKP provider, and\nretrieval strategies (inline and tool).",
"properties": {
- "inline": {
- "description": "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).",
- "items": {
- "type": "string"
- },
- "title": "Inline RAG IDs",
- "type": "array"
+ "byok": {
+ "$ref": "`#/components/schemas/`ByokConfiguration",
+ "description": "Bring Your Own Knowledge store configurations and settings.",
+ "title": "BYOK configuration"
},
- "tool": {
- "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.",
- "items": {
- "type": "string"
- },
- "title": "Tool RAG IDs",
- "type": "array"
+ "okp": {
+ "$ref": "`#/components/schemas/`OkpConfiguration",
+ "description": "OKP provider settings. Only used when 'okp' is listed in retrieval.inline.sources or retrieval.tool.sources.",
+ "title": "OKP configuration"
+ },
+ "retrieval": {
+ "$ref": "`#/components/schemas/`RetrievalConfiguration",
+ "description": "Inline and tool retrieval strategy settings.",
+ "title": "Retrieval configuration"
}
},
"title": "RagConfiguration",
"type": "object"
},
+ "RagStore": {
+ "additionalProperties": false,
+ "description": "BYOK (Bring Your Own Knowledge) RAG store configuration.",
+ "properties": {
+ "rag_id": {
+ "description": "Unique RAG ID",
+ "minLength": 1,
+ "title": "RAG ID",
+ "type": "string"
+ },
+ "backend": {
+ "default": "faiss",
+ "description": "Type of RAG database (e.g. 'faiss', 'pgvector').",
+ "minLength": 1,
+ "title": "RAG backend",
+ "type": "string"
+ },
+ "embedding_model": {
+ "default": "sentence-transformers/all-mpnet-base-v2",
+ "description": "Embedding model identification",
+ "minLength": 1,
+ "title": "Embedding model",
+ "type": "string"
+ },
+ "embedding_dimension": {
+ "default": 768,
+ "description": "Dimensionality of embedding vectors.",
+ "minimum": 0,
+ "title": "Embedding dimension",
+ "type": "integer"
+ },
+ "vector_db_id": {
+ "description": "Vector database identification.",
+ "minLength": 1,
+ "title": "Vector DB ID",
+ "type": "string"
+ },
+ "db_path": {
+ "type": "string",
+ "nullable": true,
+ "default": null,
+ "description": "Path to RAG database. Required for faiss backend.",
+ "title": "DB path"
+ },
+ "score_multiplier": {
+ "default": 1.0,
+ "description": "Multiplier applied to relevance scores from this vector store. Used to weight results when querying multiple knowledge sources. Values > 1 boost this store's results; values < 1 reduce them.",
+ "minimum": 0,
+ "title": "Score multiplier",
+ "type": "number"
+ },
+ "host": {
+ "type": "string",
+ "nullable": true,
+ "default": null,
+ "description": "PostgreSQL host for pgvector backend. Defaults to ${env.POSTGRES_HOST} when backend is pgvector.",
+ "title": "PostgreSQL host"
+ },
+ "port": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "PostgreSQL port for pgvector backend. Defaults to ${env.POSTGRES_PORT} when backend is pgvector.",
+ "title": "PostgreSQL port"
+ },
+ "db": {
+ "type": "string",
+ "nullable": true,
+ "default": null,
+ "description": "PostgreSQL database name for pgvector backend. Defaults to ${env.POSTGRES_DATABASE} when backend is pgvector.",
+ "title": "PostgreSQL database"
+ },
+ "user": {
+ "type": "string",
+ "nullable": true,
+ "default": null,
+ "description": "PostgreSQL user for pgvector backend. Defaults to ${env.POSTGRES_USER} when backend is pgvector.",
+ "title": "PostgreSQL user"
+ },
+ "password": {
+ "type": "string",
+ "nullable": true,
+ "default": null,
+ "description": "PostgreSQL password for pgvector backend. Defaults to ${env.POSTGRES_PASSWORD} when backend is pgvector.",
+ "title": "PostgreSQL password"
+ }
+ },
+ "required": [
+ "rag_id",
+ "vector_db_id"
+ ],
+ "title": "RagStore",
+ "type": "object"
+ },
"ReadinessResponse": {
"description": "Model representing response to a readiness request.\n\nAttributes:\n ready: If service is ready to handle requests.\n reason: The reason for the readiness status.\n overall_status: Overall service health status (healthy/degraded/unhealthy).\n impacts: Optional list of functional impacts when degraded or unhealthy.\n providers: List of unhealthy providers (empty when all healthy).",
"examples": [
@@ -5447,6 +5498,60 @@
"title": "ResponsesResponse",
"type": "object"
},
+ "RetrievalConfiguration": {
+ "additionalProperties": false,
+ "description": "Configuration for inline and tool retrieval strategies.",
+ "properties": {
+ "inline": {
+ "$ref": "`#/components/schemas/`RetrievalStrategyConfiguration",
+ "description": "Inline RAG: context injected before the LLM request.",
+ "title": "Inline retrieval"
+ },
+ "tool": {
+ "$ref": "`#/components/schemas/`RetrievalStrategyConfiguration",
+ "description": "Tool RAG: LLM can call file_search on demand.",
+ "title": "Tool retrieval"
+ }
+ },
+ "title": "RetrievalConfiguration",
+ "type": "object"
+ },
+ "RetrievalStrategyConfiguration": {
+ "additionalProperties": false,
+ "description": "Configuration for a single retrieval strategy (inline or tool).",
+ "properties": {
+ "sources": {
+ "description": "RAG IDs to use for this retrieval strategy. Use 'okp' to include the OKP vector store.",
+ "items": {
+ "type": "string"
+ },
+ "title": "RAG source IDs",
+ "type": "array"
+ },
+ "max_chunks": {
+ "default": 10,
+ "description": "Maximum number of chunks returned by this retrieval strategy.",
+ "minimum": 0,
+ "title": "Max chunks",
+ "type": "integer"
+ },
+ "reranker": {
+ "anyOf": [
+ {
+ "$ref": "`#/components/schemas/`RerankerConfiguration"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Neural reranking of RAG chunks using cross-encoder. Only applicable to inline retrieval.",
+ "title": "Reranker configuration"
+ }
+ },
+ "title": "RetrievalStrategyConfiguration",
+ "type": "object"
+ },
"RlsapiV1Configuration": {
"additionalProperties": false,
"description": "Configuration for the rlsapi v1 /infer endpoint.\n\nSettings specific to the RHEL Lightspeed Command Line Assistant (CLA)\nstateless inference endpoint. Kept separate from shared configuration\nsections so that CLA-specific options do not affect other endpoints.",
@@ -6486,7 +6591,7 @@
},
"VectorStoreConfiguration": {
"additionalProperties": false,
- "description": "Configuration for dynamic vector-store providers.\n\nMirrors ``InferenceConfiguration``: a providers list plus a sibling\n``default_provider`` pointer, rather than a per-entry default flag.\n\nAttributes:\n default_provider: Provider id used for vector_stores.default_* in the\n synthesized Llama Stack config. Required when providers is\n non-empty; must match one of providers[].id. Must be omitted when\n providers is empty.\n providers: Dynamic vector-store provider capacity for runtime\n POST /v1/vector-stores creates. Not the same as byok_rag (static\n registered corpora).",
+ "description": "Configuration for dynamic vector-store providers.\n\nMirrors ``InferenceConfiguration``: a providers list plus a sibling\n``default_provider`` pointer, rather than a per-entry default flag.\n\nAttributes:\n default_provider: Provider id used for vector_stores.default_* in the\n synthesized Llama Stack config. Required when providers is\n non-empty; must match one of providers[].id. Must be omitted when\n providers is empty.\n providers: Dynamic vector-store provider capacity for runtime\n POST /v1/vector-stores creates. Not the same as rag.byok.stores (static\n registered corpora).",
"properties": {
"default_provider": {
"type": "string",
@@ -6496,7 +6601,7 @@
"title": "Default provider"
},
"providers": {
- "description": "Dynamic vector-store provider capacity for runtime POST /v1/vector-stores creates. Not the same as byok_rag (static registered corpora).",
+ "description": "Dynamic vector-store provider capacity for runtime POST /v1/vector-stores creates. Not the same as rag.byok.stores (static registered corpora).",
"items": {
"discriminator": {
"mapping": {
diff --git a/docs/models/successful_responses.md b/docs/models/successful_responses.md
index 7971e6dff..6df3ae9c4 100644
--- a/docs/models/successful_responses.md
+++ b/docs/models/successful_responses.md
@@ -203,26 +203,16 @@ Microsoft Entra ID authentication attributes for Azure.
| scope | string | Azure Cognitive Services scope for token requests. Override only if using a different Azure service. |
-## ByokRag
+## ByokConfiguration
-BYOK (Bring Your Own Knowledge) RAG configuration.
+BYOK (Bring Your Own Knowledge) configuration.
| Field | Type | Description |
|-------|------|-------------|
-| rag_id | string | Unique RAG ID |
-| rag_type | string | Type of RAG database (e.g. 'inline::faiss', 'remote::pgvector'). |
-| embedding_model | string | Embedding model identification |
-| embedding_dimension | integer | Dimensionality of embedding vectors. |
-| vector_db_id | string | Vector database identification. |
-| db_path | string | Path to RAG database. Required for inline::faiss. |
-| score_multiplier | number | Multiplier applied to relevance scores from this vector store. Used to weight results when querying multiple knowledge sources. Values > 1 boost this store's results; values < 1 reduce them. |
-| host | string | PostgreSQL host for remote::pgvector. Defaults to ${env.POSTGRES_HOST} when rag_type is remote::pgvector. |
-| port | | PostgreSQL port for remote::pgvector. Defaults to ${env.POSTGRES_PORT} when rag_type is remote::pgvector. Accepts string placeholders and integer values. |
-| db | string | PostgreSQL database name for remote::pgvector. Defaults to ${env.POSTGRES_DATABASE} when rag_type is remote::pgvector. |
-| user | string | PostgreSQL user for remote::pgvector. Defaults to ${env.POSTGRES_USER} when rag_type is remote::pgvector. |
-| password | string | PostgreSQL password for remote::pgvector. Defaults to ${env.POSTGRES_PASSWORD} when rag_type is remote::pgvector. |
+| max_chunks | integer | Maximum total number of chunks returned across all BYOK stores. |
+| stores | array | List of BYOK RAG store configurations. |
## CORSConfiguration
@@ -368,6 +358,7 @@ Global service configuration.
| Field | Type | Description |
|-------|------|-------------|
| name | string | Name of the service. That value will be used in REST API endpoints. |
+| config_format_version | string | Optional explicit marker of the configuration format. When set, it must agree with the shape detected from the configuration body: 'unified' requires a synthesis input (a non-empty inference.providers, a non-empty vector_store.providers, or a llama_stack.config block), 'legacy' requires no synthesis input. Reserved as the lever for a future breaking change of the unified schema (R11). |
| service | | This section contains Lightspeed Core Stack service configuration. |
| llama_stack | | This section contains Llama Stack configuration. Lightspeed Core Stack service can call Llama Stack in library mode or in server mode. |
| user_data_collection | | This section contains configuration for subsystem that collects user data(transcription history and feedbacks). |
@@ -380,8 +371,7 @@ Global service configuration.
| conversation_cache | | |
| compaction | | Controls when conversation history is summarized to keep the model's input below the context window limit. Disabled by default — when disabled, requests that exceed the window continue to surface as HTTP 413. |
| approvals | | Settings for human-in-the-loop approval of MCP tool invocations |
-| byok_rag | array | BYOK RAG configuration. This configuration can be used to reconfigure Llama Stack through its run.yaml configuration file |
-| vector_store | | Dynamic vector-store provider capacity for runtime POST /v1/vector-stores creates. Not the same as byok_rag (static registered corpora). When providers is non-empty, default_provider is required and must match one of providers[].id. Applied in unified synthesis only. |
+| vector_store | | Dynamic vector-store provider capacity for runtime POST /v1/vector-stores creates. Not the same as rag.byok.stores (static registered corpora). When providers is non-empty, default_provider is required and must match one of providers[].id. Applied in unified synthesis only. |
| a2a_state | | Configuration for A2A protocol persistent state storage. |
| quota_handlers | | Quota handlers configuration |
| azure_entra_id | | |
@@ -389,9 +379,7 @@ Global service configuration.
| splunk | | Splunk HEC configuration for sending telemetry events. |
| observability | | OpenTelemetry and observability configuration collected from OTEL_* environment variables. |
| deployment_environment | string | Deployment environment name (e.g., 'development', 'staging', 'production'). Used in telemetry events. |
-| rag | | Configuration for all RAG strategies (inline and tool-based). |
-| okp | | OKP provider settings. Only used when 'okp' is listed in rag.inline or rag.tool. |
-| reranker | | Configuration for neural reranking of RAG chunks using cross-encoder. |
+| rag | | Unified RAG configuration: BYOK stores, OKP provider, and retrieval strategies (inline and tool-based). |
| skills | | Agent skills configuration. Specifies paths to skill directories. |
| saved_prompts | | Configuration for saved prompts feature limits including maximum prompts per user, display name length, and content length. |
| shields | array | List of pydantic-ai-lightspeed agent guardrail shields (question validity and PII redaction). Each entry has a unique 'name', a 'provider_id' ('question_validity' or 'redaction'), and a type-specific 'config'. |
@@ -1079,7 +1067,8 @@ Attributes:
OKP (Offline Knowledge Portal) provider configuration.
Controls provider-specific behaviour for the OKP vector store.
-Only relevant when ``"okp"`` is listed in ``rag.inline`` or ``rag.tool``.
+Only relevant when ``"okp"`` is listed in ``rag.retrieval.inline.sources``
+or ``rag.retrieval.tool.sources``.
| Field | Type | Description |
@@ -1087,6 +1076,8 @@ Only relevant when ``"okp"`` is listed in ``rag.inline`` or ``rag.tool``.
| rhokp_url | string | Base URL for the OKP server (http or https). Set to `${env.RH_SERVER_OKP}` in YAML to use the environment variable. When unset, the default from constants is used. |
| offline | boolean | When True, use parent_id for OKP chunk source URLs. When False, use reference_url for chunk source URLs. |
| chunk_filter_query | string | Additional OKP filter query applied to every OKP search request. Use Solr boolean syntax, e.g. 'product:ansible AND product:*openshift*'. |
+| search_mode | string | Default Solr search mode for OKP queries. 'keyword' uses BM25 text search (no embedding model needed). 'hybrid' combines vector + keyword search. 'semantic' uses pure vector search. When unset, falls back to the global default ('hybrid'). |
+| max_chunks | integer | Maximum number of chunks fetched from OKP. |
## OpenAIResponseAnnotationCitation
@@ -2116,21 +2107,39 @@ Red Hat Identity authentication configuration.
## RagConfiguration
-RAG strategy configuration.
+Unified RAG configuration.
+
+Groups all RAG-related settings: BYOK stores, OKP provider, and
+retrieval strategies (inline and tool).
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| byok | | Bring Your Own Knowledge store configurations and settings. |
+| okp | | OKP provider settings. Only used when 'okp' is listed in retrieval.inline.sources or retrieval.tool.sources. |
+| retrieval | | Inline and tool retrieval strategy settings. |
-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``.
+## RagStore
-Both ``inline`` and ``tool`` default to ``[]`` (disabled).
-Each must be explicitly configured to activate its respective RAG strategy.
+
+BYOK (Bring Your Own Knowledge) RAG store configuration.
| 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, tool RAG is disabled. |
+| rag_id | string | Unique RAG ID |
+| backend | string | Type of RAG database (e.g. 'faiss', 'pgvector'). |
+| embedding_model | string | Embedding model identification |
+| embedding_dimension | integer | Dimensionality of embedding vectors. |
+| vector_db_id | string | Vector database identification. |
+| db_path | string | Path to RAG database. Required for faiss backend. |
+| score_multiplier | number | Multiplier applied to relevance scores from this vector store. Used to weight results when querying multiple knowledge sources. Values > 1 boost this store's results; values < 1 reduce them. |
+| host | string | PostgreSQL host for pgvector backend. Defaults to ${env.POSTGRES_HOST} when backend is pgvector. |
+| port | | PostgreSQL port for pgvector backend. Defaults to ${env.POSTGRES_PORT} when backend is pgvector. |
+| db | string | PostgreSQL database name for pgvector backend. Defaults to ${env.POSTGRES_DATABASE} when backend is pgvector. |
+| user | string | PostgreSQL user for pgvector backend. Defaults to ${env.POSTGRES_USER} when backend is pgvector. |
+| password | string | PostgreSQL password for pgvector backend. Defaults to ${env.POSTGRES_PASSWORD} when backend is pgvector. |
## ReadinessResponse
@@ -2318,6 +2327,31 @@ Attributes:
| output_text | string | |
+## RetrievalConfiguration
+
+
+Configuration for inline and tool retrieval strategies.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| inline | | Inline RAG: context injected before the LLM request. |
+| tool | | Tool RAG: LLM can call file_search on demand. |
+
+
+## RetrievalStrategyConfiguration
+
+
+Configuration for a single retrieval strategy (inline or tool).
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| sources | array | RAG IDs to use for this retrieval strategy. Use 'okp' to include the OKP vector store. |
+| max_chunks | integer | Maximum number of chunks returned by this retrieval strategy. |
+| reranker | | Neural reranking of RAG chunks using cross-encoder. Only applicable to inline retrieval. |
+
+
## RlsapiV1Configuration
@@ -2875,14 +2909,14 @@ Attributes:
non-empty; must match one of providers[].id. Must be omitted when
providers is empty.
providers: Dynamic vector-store provider capacity for runtime
- POST /v1/vector-stores creates. Not the same as byok_rag (static
+ POST /v1/vector-stores creates. Not the same as rag.byok.stores (static
registered corpora).
| Field | Type | Description |
|-------|------|-------------|
| default_provider | string | Provider id used for vector_stores.default_* in the synthesized Llama Stack config. Required when providers is non-empty; must match one of providers[].id. |
-| providers | array | Dynamic vector-store provider capacity for runtime POST /v1/vector-stores creates. Not the same as byok_rag (static registered corpora). |
+| providers | array | Dynamic vector-store provider capacity for runtime POST /v1/vector-stores creates. Not the same as rag.byok.stores (static registered corpora). |
## VectorStoreDeleteResponse
diff --git a/src/utils/README.md b/src/utils/README.md
index 8beddf44d..d88b3c357 100644
--- a/src/utils/README.md
+++ b/src/utils/README.md
@@ -84,6 +84,10 @@ Function to dump the schema of all data models into OpenAPI-compatible format.
Utility function to dump schema with list of models into OpenAPI-compatible JSON format.
+## [otel_tracing.py](otel_tracing.py)
+
+OpenTelemetry tracing utilities for Lightspeed Core Stack.
+
## [prompts.py](prompts.py)
Utility functions for system prompts.
diff --git a/tests/unit/models/config/README.md b/tests/unit/models/config/README.md
index 6bbc662ce..1ae986b6b 100644
--- a/tests/unit/models/config/README.md
+++ b/tests/unit/models/config/README.md
@@ -18,7 +18,7 @@ Unit tests for AuthenticationConfiguration model.
## [test_byok_rag.py](test_byok_rag.py)
-Unit tests for ByokRag model.
+Unit tests for RagStore model.
## [test_compaction_configuration.py](test_compaction_configuration.py)
diff --git a/tests/unit/utils/README.md b/tests/unit/utils/README.md
index 55b32396d..a6d68fd7f 100644
--- a/tests/unit/utils/README.md
+++ b/tests/unit/utils/README.md
@@ -72,6 +72,10 @@ Unit tests for utils/model_list.py helpers.
Unit tests for utils/models_dumper module.
+## [test_otel_tracing.py](test_otel_tracing.py)
+
+Unit tests for utils/otel_tracing.py functions.
+
## [test_prompts.py](test_prompts.py)
Unit tests for prompts utility functions.