Skip to content

LCORE-1438: updated docs #1324

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tisnik merged 2 commits into from
Mar 16, 2026
Merged

LCORE-1438: updated docs #1324

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bd62934
Updated OpenAPI specification
tisnik Mar 16, 2026
4ec185c
Updated configuration doc
tisnik Mar 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 97 additions & 35 deletions docs/config.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -376,6 +376,11 @@ <h2 id="azureentraidconfiguration">AzureEntraIdConfiguration</h2>
<h2 id="byokrag">ByokRag</h2>
<p>BYOK (Bring Your Own Knowledge) RAG configuration.</p>
<table>
<colgroup>
<col style="width: 26%"/>
<col style="width: 23%"/>
<col style="width: 50%"/>
</colgroup>
<thead>
<tr class="header">
<th>Field</th>
Expand Down Expand Up @@ -414,6 +419,13 @@ <h2 id="byokrag">ByokRag</h2>
<td>string</td>
<td>Path to RAG database.</td>
</tr>
<tr class="odd">
<td>score_multiplier</td>
<td>number</td>
<td>Multiplier applied to relevance scores from this vector store. Used
to weight results when querying multiple knowledge sources. Values &gt;
1 boost this store&#x2019;s results; values &lt; 1 reduce them.</td>
</tr>
</tbody>
</table>
<h2 id="corsconfiguration">CORSConfiguration</h2>
Expand Down Expand Up @@ -603,9 +615,15 @@ <h2 id="configuration">Configuration</h2>
&#x2018;production&#x2019;). Used in telemetry events.</td>
</tr>
<tr class="even">
<td>solr</td>
<td>rag</td>
<td/>
<td>Configuration for Solr vector search operations.</td>
<td>Configuration for all RAG strategies (inline and tool-based).</td>
</tr>
<tr class="odd">
<td>okp</td>
<td/>
<td>OKP provider settings. Only used when &#x2018;okp&#x2019; is listed in rag.inline
or rag.tool.</td>
</tr>
</tbody>
</table>
Expand Down Expand Up @@ -1089,6 +1107,41 @@ <h2 id="modelcontextprotocolserver">ModelContextProtocolServer</h2>
</tr>
</tbody>
</table>
<h2 id="okpconfiguration">OkpConfiguration</h2>
<p>OKP (Offline Knowledge Portal) provider configuration.</p>
<p>Controls provider-specific behaviour for the OKP vector store. Only
relevant when <code>"okp"</code> is listed in <code>rag.inline</code> or
<code>rag.tool</code>.</p>
<table>
<colgroup>
<col style="width: 26%"/>
<col style="width: 23%"/>
<col style="width: 50%"/>
</colgroup>
<thead>
<tr class="header">
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>offline</td>
<td>boolean</td>
<td>When True, use parent_id for OKP chunk source URLs. When False, use
reference_url for chunk source URLs.</td>
</tr>
<tr class="even">
<td>chunk_filter_query</td>
<td>string</td>
<td>OKP filter query applied to every OKP search request. Defaults to
&#x2018;is_chunk:true&#x2019; to restrict results to chunk documents. To add extra
constraints, extend the expression using boolean syntax,
e.g.&#xA0;&#x2018;is_chunk:true AND product:<em>openshift</em>&#x2019;.</td>
</tr>
</tbody>
</table>
<h2 id="postgresqldatabaseconfiguration">PostgreSQLDatabaseConfiguration</h2>
<p>PostgreSQL database configuration.</p>
<p>PostgreSQL database is used by Lightspeed Core Stack service for
Expand Down Expand Up @@ -1337,6 +1390,48 @@ <h2 id="rhidentityconfiguration">RHIdentityConfiguration</h2>
</tr>
</tbody>
</table>
<h2 id="ragconfiguration">RagConfiguration</h2>
<p>RAG strategy configuration.</p>
<p>Controls which RAG sources are used for inline and tool-based
retrieval.</p>
<p>Each strategy lists RAG IDs to include. The special ID
<code>"okp"</code> defined in constants, activates the OKP provider; all
other IDs refer to entries in <code>byok_rag</code>.</p>
<p>Backward compatibility: - <code>inline</code> defaults to
<code>[]</code> (no inline RAG). - <code>tool</code> defaults to
<code>None</code> which means all registered vector stores are used
(identical to the previous <code>tool.byok.enabled = True</code>
default).</p>
<table>
<colgroup>
<col style="width: 26%"/>
<col style="width: 23%"/>
<col style="width: 50%"/>
</colgroup>
<thead>
<tr class="header">
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>inline</td>
<td>array</td>
<td>RAG IDs whose sources are injected as context before the LLM call.
Use &#x2018;okp&#x2019; to enable OKP inline RAG. Empty by default (no inline
RAG).</td>
</tr>
<tr class="even">
<td>tool</td>
<td>array</td>
<td>RAG IDs made available to the LLM as a file_search tool. Use &#x2018;okp&#x2019;
to include the OKP vector store. When omitted, all registered BYOK
vector stores are used (backward compatibility).</td>
</tr>
</tbody>
</table>
<h2 id="sqlitedatabaseconfiguration">SQLiteDatabaseConfiguration</h2>
<p>SQLite database configuration.</p>
<table>
Expand Down Expand Up @@ -1429,39 +1524,6 @@ <h2 id="serviceconfiguration">ServiceConfiguration</h2>
</tr>
</tbody>
</table>
<h2 id="solrconfiguration">SolrConfiguration</h2>
<p>Solr configuration for vector search queries.</p>
<p>Controls whether to use offline or online mode when building document
URLs from vector search results, and enables/disables Solr vector IO
functionality.</p>
<table>
<colgroup>
<col style="width: 26%"/>
<col style="width: 23%"/>
<col style="width: 50%"/>
</colgroup>
<thead>
<tr class="header">
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>enabled</td>
<td>boolean</td>
<td>When True, enables Solr vector IO functionality for vector search
queries. When False, disables Solr vector search processing.</td>
</tr>
<tr class="even">
<td>offline</td>
<td>boolean</td>
<td>When True, use parent_id for chunk source URLs. When False, use
reference_url for chunk source URLs.</td>
</tr>
</tbody>
</table>
<h2 id="splunkconfiguration">SplunkConfiguration</h2>
<p>Splunk HEC (HTTP Event Collector) configuration.</p>
<p>Splunk HEC allows sending events directly to Splunk over HTTP/HTTPS.
Expand Down
100 changes: 41 additions & 59 deletions docs/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,12 +130,12 @@ byok_rag:
| Field | Type | Description |
|-------|------|-------------|
| rag_id | string | Unique RAG ID |
| rag_type | string | Type of RAG database (e.g. `inline::faiss`). |
| rag_type | string | Type of RAG database. |
| 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. |
| score_multiplier | number | Multiplier applied to relevance scores from this vector store when querying multiple sources. Values > 1 boost results; values < 1 reduce them. Default: 1.0. |
| 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. |

@coderabbitai coderabbitai Bot Mar 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Document the score_multiplier validation boundary.

The model only accepts values > 0, but the current description makes 0 look like a valid way to suppress a store. That will fail validation instead of disabling the source.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/config.md` at line 138, Update the docs entry for score_multiplier to
explicitly state the validation boundary is strictly greater than 0 (values must
be > 0) and that 0 is invalid; mention that to effectively disable or suppress a
store you should omit the score_multiplier or use a very small positive value
rather than setting it to 0. Ensure the text references the symbol
score_multiplier and clarifies that values >1 boost and values between 0 and 1
reduce relevance, but must not be zero or negative.



## CORSConfiguration
Expand Down Expand Up @@ -187,7 +187,8 @@ Global service configuration.
| azure_entra_id | | |
| splunk | | Splunk HEC configuration for sending telemetry events. |
| deployment_environment | string | Deployment environment name (e.g., 'development', 'staging', 'production'). Used in telemetry events. |
| rag | | RAG strategy configuration (OKP and BYOK). Controls pre-query (Inline RAG) and tool-based (Tool RAG) retrieval. |
| 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. |


## ConversationHistoryConfiguration
Expand Down Expand Up @@ -395,6 +396,21 @@ Useful resources:
| timeout | integer | Timeout in seconds for requests to the MCP server. If not specified, the default timeout from Llama Stack will be used. Note: This field is reserved for future use when Llama Stack adds timeout support. |


## OkpConfiguration


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``.


| Field | Type | Description |
|-------|------|-------------|
| 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 | 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*'. |
Comment on lines +410 to +411

@coderabbitai coderabbitai Bot Mar 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Preserve the literal OKP query example.

product:*openshift* is being parsed as emphasis, so the generated HTML no longer shows the wildcard characters. Wrap the example in backticks so readers can copy the actual filter.

📝 Suggested doc tweak 
-| chunk_filter_query | string | 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*'. |
+| chunk_filter_query | string | 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*`. |
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| 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 | 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*'. |
| 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 | 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*`. |
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/config.md` around lines 410 - 411, The example filter in the
chunk_filter_query description is being interpreted as emphasis and losing the
wildcard characters; update the chunk_filter_query documentation string so the
example is wrapped in inline code (backticks) — e.g., change product:*openshift*
to `product:*openshift*` inside the chunk_filter_query description to preserve
the literal query in generated HTML.



## PostgreSQLDatabaseConfiguration


Expand Down Expand Up @@ -501,6 +517,28 @@ Red Hat Identity authentication configuration.
| required_entitlements | array | List of all required entitlements. |


## RagConfiguration


RAG strategy configuration.

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``.

Backward compatibility:
- ``inline`` defaults to ``[]`` (no inline RAG).
- ``tool`` defaults to ``None`` which means all registered vector stores
are used (identical to the previous ``tool.byok.enabled = True`` default).


| 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, all registered BYOK vector stores are used (backward compatibility). |


## SQLiteDatabaseConfiguration


Expand Down Expand Up @@ -537,62 +575,6 @@ the service can handle requests concurrently.
| cors | | Cross-Origin Resource Sharing configuration for cross-domain requests |


## RagConfiguration


Top-level RAG strategy configuration. Controls two complementary retrieval modes:

- **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 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` activates the OKP provider (no `byok_rag` entry needed).

**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.

Example:

```yaml
rag:
inline:
- my-docs # inject context from my-docs before the LLM request
tool:
- okp # LLM can search OKP as a tool
- my-docs # LLM can also search my-docs as a tool

okp:
offline: true # use parent_id for OKP URL construction
```


| Field | Type | Description |
|-------|------|-------------|
| inline | list[string] | RAG IDs whose content is injected before the LLM request. Use `okp` 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` to include OKP. When omitted, all registered BYOK vector stores are used (backward compatibility). |


## OkpConfiguration

OKP (Offline Knowledge Portal) provider settings. Only used when `okp` is listed in `rag.inline` or `rag.tool`.

Example:

```yaml
okp:
offline: true # use parent_id for OKP URL construction
chunk_filter_query: "is_chunk:true"
```

| Field | Type | Description |
|-------|------|-------------|
| 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


Expand Down
Loading
Loading