LCORE-1438: updated docs#1324
Merged
Merged
Conversation
Contributor
WalkthroughDocumentation updates reflecting architectural configuration changes: replacing Solr-specific configuration references with generalized RAG (Retrieval-Augmented Generation) configuration, introducing OKP (Offline Knowledge Portal) provider configuration, adding score_multiplier field to ByokRag, and referenced_documents field to Message model. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/config.md`:
- 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.
- Around line 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.
In `@docs/openapi.md`:
- Line 4791: The docs entry for the parameter "shield_ids" uses Python-specific
"None" in a JSON/YAML-facing description; update the text to use
JSON/YAML-friendly terms such as "null" or "omitted" (e.g., "If null or omitted,
all configured shields are used.") and make the same change for the other
occurrences referenced (around lines 4971-4973) so the public OpenAPI docs do
not leak Python implementation terminology.
- Around line 4640-4641: The Markdown example in the docs for the
chunk_filter_query column renders product:*openshift* as emphasis; update the
docs by wrapping the example query (e.g. product:*openshift*) in inline code
spans so the asterisks are preserved literally—locate the table row describing
chunk_filter_query and change the example text to use backticks around the
query.
- Around line 4528-4535: The table row for referenced_documents is missing a
type; update the docs/openapi.md table so the Type column for
referenced_documents clearly states that it is an array of ReferencedDocument
(e.g., "array[ReferencedDocument]" or "Optional[list[ReferencedDocument]]") and
ensure the Description still notes it is a list of documents referenced in the
response (assistant messages only); reference the symbols referenced_documents
and ReferencedDocument when making the change.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 8a1d7f88-c829-4928-b242-5254b6e45d87
⛔ Files ignored due to path filters (1)
docs/config.svgis excluded by!**/*.svg
📒 Files selected for processing (4)
docs/config.htmldocs/config.mddocs/config.pumldocs/openapi.md
| | 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. | |
Contributor
There was a problem hiding this comment.
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.
Comment on lines
+410
to
+411
| | 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*'. | |
Contributor
There was a problem hiding this comment.
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.
Comment on lines
+4528
to
+4535
| referenced_documents: Optional list of documents referenced in an assistant response. | ||
|
|
||
|
|
||
| | Field | Type | Description | | ||
| |-------|------|-------------| | ||
| | content | string | The message content | | ||
| | type | string | The type of message | | ||
| | referenced_documents | | List of documents referenced in the response (assistant messages only) | |
Contributor
There was a problem hiding this comment.
Add the referenced_documents type to the table.
The new field is shown without a type even though the model is Optional[list[ReferencedDocument]], so clients cannot tell that this is an array of ReferencedDocument objects.
📝 Suggested doc tweak
-| referenced_documents | | List of documents referenced in the response (assistant messages only) |
+| referenced_documents | array | List of ReferencedDocument objects referenced in the response (assistant messages only) |📝 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
| referenced_documents: Optional list of documents referenced in an assistant response. | |
| | Field | Type | Description | | |
| |-------|------|-------------| | |
| | content | string | The message content | | |
| | type | string | The type of message | | |
| | referenced_documents | | List of documents referenced in the response (assistant messages only) | | |
| referenced_documents: Optional list of documents referenced in an assistant response. | |
| | Field | Type | Description | | |
| |-------|------|-------------| | |
| | content | string | The message content | | |
| | type | string | The type of message | | |
| | referenced_documents | array | List of ReferencedDocument objects referenced in the response (assistant messages only) | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/openapi.md` around lines 4528 - 4535, The table row for
referenced_documents is missing a type; update the docs/openapi.md table so the
Type column for referenced_documents clearly states that it is an array of
ReferencedDocument (e.g., "array[ReferencedDocument]" or
"Optional[list[ReferencedDocument]]") and ensure the Description still notes it
is a list of documents referenced in the response (assistant messages only);
reference the symbols referenced_documents and ReferencedDocument when making
the change.
Comment on lines
+4640
to
+4641
| | 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*'. | |
Contributor
There was a problem hiding this comment.
Wrap the OKP filter example in code spans.
product:*openshift* is Markdown emphasis here, so the rendered docs drop the literal * wildcards. That turns the example into the wrong query syntax.
📝 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/openapi.md` around lines 4640 - 4641, The Markdown example in the docs
for the chunk_filter_query column renders product:*openshift* as emphasis;
update the docs by wrapping the example query (e.g. product:*openshift*) in
inline code spans so the asterisks are preserved literally—locate the table row
describing chunk_filter_query and change the example text to use backticks
around the query.
| | media_type | | Media type for the response format | | ||
| | vector_store_ids | | Optional list of specific vector store IDs to query for RAG. If not provided, all available vector stores will be queried. | | ||
| | shield_ids | | Optional list of safety shield IDs to apply. If None, all configured shields are used. If provided, must contain at least one valid shield ID (empty list raises 422 error). | | ||
| | shield_ids | | Optional list of safety shield IDs to apply. If None, all configured shields are used. | |
Contributor
There was a problem hiding this comment.
Prefer null or “omitted” over Python None in public docs.
These sections describe JSON/YAML-facing data, so None leaks implementation terminology and can mislead non-Python consumers.
📝 Suggested doc tweak
-| shield_ids | | Optional list of safety shield IDs to apply. If None, all configured shields are used. |
+| shield_ids | | Optional list of safety shield IDs to apply. If omitted or `null`, all configured shields are used. |- - ``tool`` defaults to ``None`` which means all registered vector stores
- are used (identical to the previous ``tool.byok.enabled = True`` default).
+ - When ``tool`` is omitted or set to ``null``, all registered vector
+ stores are used (identical to the previous ``tool.byok.enabled = True``
+ default).Also applies to: 4971-4973
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/openapi.md` at line 4791, The docs entry for the parameter "shield_ids"
uses Python-specific "None" in a JSON/YAML-facing description; update the text
to use JSON/YAML-friendly terms such as "null" or "omitted" (e.g., "If null or
omitted, all configured shields are used.") and make the same change for the
other occurrences referenced (around lines 4971-4973) so the public OpenAPI docs
do not leak Python implementation terminology.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
LCORE-1438: updated docs
Type of change
Tools used to create PR
Related Tickets & Documents
Summary by CodeRabbit
New Features
Documentation