LCORE-2505: Add migration guide and deprecation notes for BYOK config refactoring

docs/byok_guide.md

@@ -113,6 +113,14 @@ Before implementing BYOK, ensure you have:
 
 ## Configuration Guide
 
+> [!WARNING]
+> **Deprecated in 0.7.0**: The top-level `byok_rag`, `rag`, `okp`, and `reranker` sections
+> are deprecated. In 0.7.0, all RAG-related configuration is unified under a single `rag`
+> section: BYOK stores move to `rag.byok.stores` (with `backend` instead of `rag_type`),
+> retrieval strategies move to `rag.retrieval.inline`/`rag.retrieval.tool`, OKP moves to
+> `rag.okp`, and the reranker moves to `rag.retrieval.inline.reranker`.
+> See the [v0.7.0 Migration Guide](migrations/v0.7.0.md) for full details and examples.
+
 ### Step 1: Prepare Your Knowledge Sources
 
 1. **Collect your documents**: Gather all knowledge sources you want to include

docs/migrations/v0.7.0.md

@@ -0,0 +1,128 @@
+# Migrating to v0.7.0
+
+## Table of Contents
+
+* [RAG Configuration](#rag-configuration)
+
+---
+
+## RAG Configuration
+
+In v0.7.0, the RAG configuration in `lightspeed-stack.yaml` is unified under a single `rag` section. The four separate top-level sections (`byok_rag`, `rag`, `okp`, `reranker`) are replaced by a nested structure that groups BYOK stores, OKP settings, retrieval strategies, and reranker settings together. The `rag_type` field is renamed to `backend` and the `inline::`/`remote::` prefix is dropped (e.g. `inline::faiss` becomes `faiss`). Hardcoded chunk limit constants are now user-configurable fields with sensible defaults.
+
+### Field Mapping
+
+| Old config path | New config path | Notes |
+|---|---|---|
+| `byok_rag` (top-level list) | `rag.byok.stores` | Moved under `rag.byok` |
+| `byok_rag[].rag_type` | `rag.byok.stores[].backend` | Drop the `inline::`/`remote::` prefix (e.g. `inline::faiss` becomes `faiss`) |
+| `rag.inline` (list of IDs) | `rag.retrieval.inline.sources` | Moved under `rag.retrieval.inline` |
+| `rag.tool` (list of IDs) | `rag.retrieval.tool.sources` | Moved under `rag.retrieval.tool` |
+| `okp` (top-level section) | `rag.okp` | Moved under `rag` |
+| `BYOK_RAG_MAX_CHUNKS` constant | `rag.byok.max_chunks` | Default: 10 |
+| `OKP_RAG_MAX_CHUNKS` constant | `rag.okp.max_chunks` | Default: 5 |
+| `INLINE_RAG_MAX_CHUNKS` constant | `rag.retrieval.inline.max_chunks` | Default: 10 |
+| `TOOL_RAG_MAX_CHUNKS` constant | `rag.retrieval.tool.max_chunks` | Default: 10 |
+| `reranker` (top-level section) | `rag.retrieval.inline.reranker` | Moved under `rag.retrieval.inline` |
+
+---
+
+### Before / After Examples
+
+#### Full RAG Configuration Example
+
+**Before (v0.6.x):**
+
+```yaml
+byok_rag:
+  - rag_id: ocp-docs
+    rag_type: inline::faiss
+    embedding_model: sentence-transformers/all-mpnet-base-v2
+    embedding_dimension: 768
+    vector_db_id: vs_123
+    db_path: /tmp/ocp.faiss
+    score_multiplier: 1.0
+  - rag_id: knowledge-base
+    rag_type: inline::faiss
+    embedding_model: sentence-transformers/all-mpnet-base-v2
+    embedding_dimension: 768
+    vector_db_id: vs_456
+    db_path: /tmp/kb.faiss
+    score_multiplier: 1.2
+
+rag:
+  inline:
+    - ocp-docs
+    - knowledge-base
+    - okp
+  tool:
+    - ocp-docs
+    - knowledge-base
+
+okp:
+  rhokp_url: ${env.RH_SERVER_OKP}
+  offline: true
+  # chunk_filter_query: "product:*ansible* AND product:*openshift*"
+
+reranker:
+  enabled: true
+  model: cross-encoder/ms-marco-MiniLM-L6-v2
+```
+
+**After (v0.7.0):**
+
+```yaml
+rag:
+  byok:
+    max_chunks: 10                 # Was BYOK_RAG_MAX_CHUNKS constant
+    stores:
+      - rag_id: ocp-docs
+        backend: faiss              # Was 'rag_type: inline::faiss'
+        embedding_model: sentence-transformers/all-mpnet-base-v2
+        embedding_dimension: 768
+        vector_db_id: vs_123
+        db_path: /tmp/ocp.faiss
+        score_multiplier: 1.0
+      - rag_id: knowledge-base
+        backend: faiss              # Was 'rag_type: inline::faiss'
+        embedding_model: sentence-transformers/all-mpnet-base-v2
+        embedding_dimension: 768
+        vector_db_id: vs_456
+        db_path: /tmp/kb.faiss
+        score_multiplier: 1.2
+
+  okp:
+    rhokp_url: ${env.RH_SERVER_OKP}
+    offline: true
+    max_chunks: 5                  # Was OKP_RAG_MAX_CHUNKS constant
+    # chunk_filter_query: "product:*ansible* AND product:*openshift*"
+
+  retrieval:
+    inline:
+      sources:
+        - ocp-docs
+        - knowledge-base
+        - okp
+      max_chunks: 10               # Was INLINE_RAG_MAX_CHUNKS constant
+      reranker:
+        enabled: true
+        model: cross-encoder/ms-marco-MiniLM-L6-v2
+    tool:
+      sources:
+        - ocp-docs
+        - knowledge-base
+      max_chunks: 10               # Was TOOL_RAG_MAX_CHUNKS constant
+```
+
+---
+
+### Chunk Limits
+
+Chunk limits were previously hardcoded as constants in `src/constants.py`. They are now configurable fields in `lightspeed-stack.yaml` with the same default values:
+
+| Old constant | New config field | Default |
+|---|---|---|
+| `BYOK_RAG_MAX_CHUNKS` | `rag.byok.max_chunks` | 10 |
+| `OKP_RAG_MAX_CHUNKS` | `rag.okp.max_chunks` | 5 |
+| `INLINE_RAG_MAX_CHUNKS` | `rag.retrieval.inline.max_chunks` | 10 |
+| `TOOL_RAG_MAX_CHUNKS` | `rag.retrieval.tool.max_chunks` | 10 |

docs/rag_guide.md

@@ -63,6 +63,14 @@ Download a local embedding model such as `sentence-transformers/all-mpnet-base-v
 
 ## Configure BYOK Knowledge Sources
 
+> [!WARNING]
+> **Deprecated in 0.7.0**: The top-level `byok_rag`, `rag`, `okp`, and `reranker` sections
+> are deprecated. In 0.7.0, all RAG-related configuration is unified under a single `rag`
+> section: stores move to `rag.byok.stores` (with `backend` instead of `rag_type`),
+> retrieval strategies move to `rag.retrieval.inline`/`rag.retrieval.tool`, OKP moves to
+> `rag.okp`, and the reranker moves to `rag.retrieval.inline.reranker`.
+> See the [v0.7.0 Migration Guide](migrations/v0.7.0.md) for full details and examples.
+
 BYOK knowledge sources are configured in the `byok_rag` section of `lightspeed-stack.yaml`. The required configuration is automatically generated at startup when using `make run`, `make run-stack`, `docker-compose`, or library mode — no manual enrichment is needed.
 
 ### FAISS example
@@ -312,6 +320,12 @@ Example:
 
 **Chunk volume:**
 
+> [!WARNING]
+> **Deprecated in 0.7.0**: The chunk limit constants below are replaced by configurable
+> fields in `lightspeed-stack.yaml` (`rag.byok.max_chunks`, `rag.okp.max_chunks`,
+> `rag.retrieval.inline.max_chunks`, `rag.retrieval.tool.max_chunks`).
+> See the [v0.7.0 Migration Guide](migrations/v0.7.0.md) for details.
+
 OKP and BYOK scores are not directly comparable (different scoring systems), so
 `score_multiplier` (a BYOK-only concept) does not apply to OKP results. To control
 the number of retrieved chunks, set the constants in `src/constants.py`: