Migrating to v0.7.0

Table of Contents

• RAG Configuration
• OGX naming (llama_stack → ogx)
• Vector stores API deprecation
• Conversations API v1 deprecation

---

OGX naming (llama_stack → ogx)

In v0.7.0, Lightspeed Core Stack adopts ogx as the canonical name for the OGX configuration section in lightspeed-stack.yaml. The deprecated llama_stack: top-level YAML key remains accepted with a startup warning. API response fields were renamed without backward-compatible aliases.

Configuration YAML

v0.6.x	v0.7.0 (canonical)	v0.7.0 (deprecated alias)
llama_stack: top-level section	ogx: top-level section	llama_stack: still accepted with a startup warning

Before (v0.6.x):

llama_stack:
  url: http://localhost:8321

After (v0.7.0 — preferred):

ogx:
  url: http://localhost:8321

Still accepted in v0.7.0 (deprecated):

llama_stack:
  url: http://localhost:8321

A startup warning is logged when the deprecated llama_stack key is used. Migrate configs to ogx: when convenient.

/info API

The /info response field was renamed; the old name is not returned:

v0.6.x	v0.7.0
llama_stack_version	ogx_version

Update clients that read /info to use ogx_version.

---

RAG Configuration

In v0.7.0, the RAG configuration in lightspeed-stack.yaml will be unified under a single rag section. The four separate top-level sections (byok_rag, rag, okp, reranker) will be replaced by a nested structure that groups BYOK stores, OKP settings, retrieval strategies, and reranker settings together. The rag_type field will be renamed to backend and the inline::/remote:: prefix will be dropped (e.g. inline::faiss becomes faiss). Hardcoded chunk limit constants will become 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):

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):

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, currently hardcoded as constants, will be 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

---

Vector stores API deprecation

The /v1/vector-stores and /v1/files routes proxy OGX vector-store and file APIs. They are deprecated in v0.7.0 and will be removed in v0.8.0 when OGX is dropped from Lightspeed Core Stack.

Migrate to BYOK RAG for document retrieval. The OpenAPI schema marks these operations as deprecated.

---

Conversations API v1 deprecation

The /v1/conversations routes use OGX Conversations persistence. They are deprecated in v0.7.0 and will be removed in a later release when OGX is dropped from Lightspeed Core Stack.

Migrate to /v2/conversations, which uses LCORE-owned storage. After OGX removal, keeping both surfaces would duplicate the same CRUD API, so v2 remains the sole conversations API. The OpenAPI schema marks the v1 operations as deprecated.