LCORE-2933: Developer doc#2159
Conversation
|
Warning Review limit reached
Next review available in: 28 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (2)
WalkthroughThe PR reorganizes documentation navigation and adds comprehensive architecture, installation, contribution, container orchestration, API, conversation, provider, and version-maintenance documentation. ChangesDeveloper documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Important Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (1 error, 1 inconclusive)
✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
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}
There was a problem hiding this comment.
Actionable comments posted: 25
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/devel_doc/ARCHITECTURE.md`:
- Line 44: Update the fenced architecture diagram in ARCHITECTURE.md to specify
the text language identifier, changing the opening fence to use text while
preserving the diagram contents and closing fence.
- Around line 459-462: Update the Streaming Query API documentation to list the
registered /v1/streaming_query route instead of /v2/streaming_query, matching
the mounting configured by the streaming_query endpoint and routers.py. Keep the
deprecated Agent API entry unchanged unless its registration also requires
correction.
In `@docs/devel_doc/container_orchestration.md`:
- Around line 591-597: Update the firewall guidance in the container
orchestration documentation to avoid recommending globally opening port 8321. In
the “Check firewall rules” section, recommend binding the mapped service to
loopback or using a narrowly scoped firewall rule, and remove the permanent
unrestricted 8321/tcp opening instructions.
- Around line 740-748: Update the “Run the Container” podman command to include
the entrypoint and enrichment script mounts required for automatic enrichment,
matching the documented enrichment setup; alternatively, explicitly document
that the mounted configuration must already be pre-enriched.
- Around line 353-363: Update the health-check and troubleshooting examples in
the container orchestration guide to support both runtimes by using the selected
CONTAINER_RUNTIME in generic commands or providing equivalent Docker commands.
Replace hard-coded podman invocations while preserving the existing container
name, inspect format, and documented health-status values.
- Around line 29-36: Update the cleanup description in the make run workflow to
attribute automatic cleanup specifically to the run target, not run-stack.
Clarify that the trap is installed before run-stack is invoked, and avoid
implying that running make run-stack directly provides the same cleanup
behavior.
- Around line 751-760: Update the manual container instructions near “Monitor
the Container” so health inspection is valid: either add the required
healthcheck command and timing options to the documented podman run invocation,
or replace the podman inspect health-status step with the existing direct
/v1/health request.
- Around line 616-623: Update the “Option 1: Use 644 permissions” guidance in
the container orchestration documentation to clearly label chmod 644 as a
last-resort workaround only for disposable development credentials, and prefer
UID-compatible mounts, ACLs, or secret injection before it. Strengthen the
security note to explicitly state that the file is world-readable and must not
be used for production or sensitive credentials.
- Around line 447-450: Update the “Check logs saved by Makefile” troubleshooting
step in container_orchestration.md so health-check failures direct users to the
actual container/runtime logs instead of /tmp/llama-stack-failure.log, which is
only created for graceful-stop failures. If a file-based command is retained,
reference only a log file produced by the health-wait target.
In `@docs/devel_doc/contributing_guide.md`:
- Around line 193-199: Resolve the shared Markdownlint violations by adding
language identifiers to fenced code blocks and required blank lines around
headings and fences in docs/devel_doc/contributing_guide.md lines 193-199 and
docs/devel_doc/container_orchestration.md lines 133-139.
In `@docs/devel_doc/conversations_api.md`:
- Around line 194-269: Update the endpoint URLs in the Query Endpoint, Streaming
Query Endpoint, Conversations List Endpoint, and Conversation Detail Endpoint
sections to match the mounted routers: use /v1/query and /v1/streaming_query for
query routes, and /v2/conversations plus /v2/conversations/{conversation_id} for
conversation routes. Keep the request and response examples unchanged.
In `@docs/devel_doc/installation_linux.md`:
- Around line 13-17: Update the Linux installation steps in the documented setup
sequence to change the directory command to lightspeed-stack, matching the
directory created by git clone, and replace the uv info and uv install commands
with uv sync.
In `@docs/devel_doc/openapi.json`:
- Around line 2-3: Update the OpenAPI generation configuration associated with
the specification’s "openapi" and "info" definitions to declare the
authentication scheme under components.securitySchemes and apply it through the
top-level security array. Configure the backend’s OpenAPI settings, such as the
FastAPI security dependency or equivalent, so regenerated documentation
preserves these global definitions and enables client and Swagger authentication
support.
- Around line 7526-7533: Update the GET operation definitions in
docs/devel_doc/openapi.json at lines 7526-7533, 8472-8479, 5107-5114, 3597-3604,
2079-2086, and 894-901 to declare pagination parameters such as limit and
offset, with appropriate bounds/defaults consistent across list endpoints;
ensure the documented parameters are enforced by the corresponding API handlers
so responses remain bounded.
In `@docs/devel_doc/openapi.md`:
- Around line 3969-3974: Update both failed-deletion response examples in the
OpenAPI documentation to set the "success" field to false instead of true, while
preserving their existing error response text and structure.
- Around line 4628-4665: Update the Responses endpoint documentation around the
ResponsesResponse section to distinguish non-streaming JSON from stream=true
output. Document the streaming response as text/event-stream with its SSE event
schema, and remove any presentation of raw SSE events as a JSON example while
retaining the existing ResponsesResponse documentation for non-streaming
requests.
- Line 8: Update the APIs entry in the table of contents so its link fragment
matches the renderer-generated anchor for the “🛠️ APIs” heading. Regenerate the
TOC or replace `#apis` with the actual generated fragment, ensuring markdownlint
MD051 passes.
- Around line 471-479: Update the documentation generator responsible for the
OpenAPI Markdown sections so headings such as Parameters, Raises, and Returns
are followed by blank lines, and ensure equivalent spacing around related lists
and block content throughout the generated document. Regenerate the document or
apply the project’s Markdown formatter so the repeated MD022, MD031, and MD058
violations are resolved consistently.
- Around line 97-101: Update the OpenAPI endpoint inventory and detailed
sections around the existing `/v1/rags` documentation to cover
`/v1/vector-stores`, `/v1/files`, and all related advertised operations with
their requests, responses, and status codes; alternatively remove any
undocumented endpoints from the inventory. Keep the table of contents anchors
synchronized with the documented sections.
- Line 795: Update the examples throughout openapi.md, including the curl
command and the referenced ranges, to use fenced code blocks with appropriate
language tags such as bash or yaml. Replace indented code blocks and unlabeled
fences while preserving each example’s content and formatting.
- Around line 67-90: Update the inventory table entry for the `/v1/prompts`
endpoint to remove the trailing slash and use the canonical `/v1/prompts`
spelling consistently with the TOC and endpoint documentation.
In `@docs/devel_doc/providers.md`:
- Around line 353-365: Correct the YAML indentation in the models example so the
sequence item is nested under models and its fields, including model_id,
provider_id, model_type, and provider_model_id, are consistently indented within
that entry; preserve the surrounding providers and shields examples.
In `@docs/maintenance/version_status.md`:
- Line 1: Change the document’s opening heading from level two to a top-level
level-one heading in the version status page, preserving the existing heading
text and satisfying the document hierarchy requirement.
In `@docs/maintenance/versions_supported.md`:
- Line 3: Align both maintenance pages with their scheduled-date note by
italicizing scheduled dates in the tables while keeping the existing note
accurate. Apply the same correction in docs/maintenance/versions_supported.md
lines 3-3 and docs/maintenance/versions_unsupported.md lines 3-3.
In `@docs/README.md`:
- Line 65: Correct the operating-system capitalization in the installation
links: update “Installation on MacOS” to “Installation on macOS” in
docs/README.md lines 65-65 and docs/index.md lines 72-72.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 347670cf-60a9-45b4-b127-ef75ecac0adc
⛔ Files ignored due to path filters (3)
docs/devel_doc/architecture.pngis excluded by!**/*.pngdocs/devel_doc/architecture.svgis excluded by!**/*.svgdocs/maintenance/version_status.svgis excluded by!**/*.svg
📒 Files selected for processing (15)
docs/README.mddocs/devel_doc/ARCHITECTURE.mddocs/devel_doc/container_orchestration.mddocs/devel_doc/contributing_guide.mddocs/devel_doc/conversations_api.mddocs/devel_doc/installation_linux.mddocs/devel_doc/installation_macos.mddocs/devel_doc/openapi.jsondocs/devel_doc/openapi.mddocs/devel_doc/providers.mddocs/index.mddocs/maintenance/version_status.mddocs/maintenance/version_status.pumldocs/maintenance/versions_supported.mddocs/maintenance/versions_unsupported.md
📜 Review details
⏰ Context from checks skipped due to timeout. (13)
- GitHub Check: integration_tests (3.13)
- GitHub Check: integration_tests (3.12)
- GitHub Check: unit_tests (3.13)
- GitHub Check: unit_tests (3.12)
- GitHub Check: Pylinter
- GitHub Check: build-pr
- GitHub Check: E2E Tests for Lightspeed Evaluation job
- GitHub Check: E2E: library mode / ci / group 2
- GitHub Check: E2E: server mode / ci / group 3
- GitHub Check: E2E: library mode / ci / group 1
- GitHub Check: E2E: server mode / ci / group 2
- GitHub Check: E2E: server mode / ci / group 1
- GitHub Check: E2E: library mode / ci / group 3
⚠️ CI failures not shown inline (2)
GitHub Actions: OpenAPI (Spectral) / 0_spectral.txt: LCORE-2933: Developer doc
Conclusion: failure
##[group]Run set -euo pipefail
�[36;1mset -euo pipefail�[0m
�[36;1muv run python scripts/generate_openapi_schema.py /tmp/openapi-generated.json�[0m
�[36;1mif ! diff -u docs/openapi.json /tmp/openapi-generated.json; then�[0m
�[36;1m echo "::error::docs/openapi.json is out of date. Regenerate with: uv run scripts/generate_openapi_schema.py docs/openapi.json"�[0m
GitHub Actions: OpenAPI (Spectral) / spectral: LCORE-2933: Developer doc
Conclusion: failure
##[group]Run set -euo pipefail
�[36;1mset -euo pipefail�[0m
�[36;1muv run python scripts/generate_openapi_schema.py /tmp/openapi-generated.json�[0m
�[36;1mif ! diff -u docs/openapi.json /tmp/openapi-generated.json; then�[0m
�[36;1m echo "::error::docs/openapi.json is out of date. Regenerate with: uv run scripts/generate_openapi_schema.py docs/openapi.json"�[0m
🧰 Additional context used
📓 Path-based instructions (2)
**/*
📄 CodeRabbit inference engine (Custom checks)
**/*: Flag meaningful O(n^2)+ algorithms on non-trivial inputs, including handlers and Kubernetes list operations.
Flag N+1 patterns that list items and then query once per item, including Kubernetes API and database access.
Flag expensive work inside loops, including API calls, JSON parsing, and regex compilation.
Flag unbounded growth in caches, watchers, or buffers when eviction or limits are missing.
Flag missing pagination or limits on list operations and API endpoints.
Flag secrets or tokens logged in plaintext or hardcoded in source.
Flag API endpoints missing authentication or authorization.
Flag injection vulnerabilities, including SQL injection, command injection, and path traversal.
Flag sensitive data leaked in API responses, WebSocket messages, or logs.
Flag Kubernetes Secrets and Red Hat secrets missing OwnerReferences.
Files:
docs/devel_doc/openapi.jsondocs/maintenance/version_status.pumldocs/maintenance/version_status.mddocs/maintenance/versions_supported.mddocs/devel_doc/installation_macos.mddocs/devel_doc/installation_linux.mddocs/maintenance/versions_unsupported.mddocs/devel_doc/conversations_api.mddocs/README.mddocs/index.mddocs/devel_doc/ARCHITECTURE.mddocs/devel_doc/openapi.mddocs/devel_doc/contributing_guide.mddocs/devel_doc/providers.mddocs/devel_doc/container_orchestration.md
**/*.{py,yaml,yml,json,toml}
📄 CodeRabbit inference engine (AGENTS.md)
Never commit secrets or keys; use environment variables for sensitive data.
Files:
docs/devel_doc/openapi.json
🪛 Checkov (3.3.8)
docs/devel_doc/openapi.json
[high] 1-21331: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
[high] 1-21331: Ensure that security operations is not empty.
(CKV_OPENAPI_5)
[medium] 10972-10979: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🪛 LanguageTool
docs/README.md
[uncategorized] ~65-~65: The operating system from Apple is written “macOS”.
Context: ...tallation_linux.html) [Installation on MacOS](https://lightspeed-core.github.io/ligh...
(MAC_OS)
docs/index.md
[uncategorized] ~72-~72: The operating system from Apple is written “macOS”.
Context: ...tallation_linux.html) [Installation on MacOS](https://lightspeed-core.github.io/ligh...
(MAC_OS)
docs/devel_doc/ARCHITECTURE.md
[grammar] ~342-~342: Ensure spelling is correct
Context: ... Client-Provided Authentication (MCP-HEADERS): Clients can provide their own authentica...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/devel_doc/contributing_guide.md
[style] ~40-~40: Consider shortening or rephrasing this to strengthen your wording.
Context: ... 1. Create your own fork of the repo 2. Make changes to the code in your fork 3. Run unit tests...
(MAKE_CHANGES)
[style] ~223-~223: Consider a more concise word here.
Context: .... We measured and checked code coverage in order to be able to develop software with high q...
(IN_ORDER_TO_PREMIUM)
docs/devel_doc/providers.md
[grammar] ~23-~23: Ensure spelling is correct
Context: ...ider category, containing the following atributes: - Name – Provider identifier in llama-st...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~229-~229: Use a hyphen to join words.
Context: ...o-http` | ✅ | --- ## Post Training Providers | Name | ...
(QB_NEW_EN_HYPHEN)
[grammar] ~339-~339: Ensure spelling is correct
Context: ...ema <type>::<name> and comes from the deffinition on upstream. The provider_id is y...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~393-~393: Consider a different adjective to strengthen your wording.
Context: ...d responding as expected. --- For a deeper understanding, see the [official llama-...
(DEEP_PROFOUND)
docs/devel_doc/container_orchestration.md
[grammar] ~129-~129: Use a hyphen to join words.
Context: ...lth status (30 attempts × 2 seconds = 60 second timeout) - Shows status on each a...
(QB_NEW_EN_HYPHEN)
[grammar] ~370-~370: Use a hyphen to join words.
Context: ...marking unhealthy - Start Period: 15 second grace period on startup ### LCOR...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.23.0)
docs/maintenance/version_status.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
docs/devel_doc/conversations_api.md
[warning] 58-58: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 63-63: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 63-63: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 77-77: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 77-77: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 170-170: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 199-199: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 209-209: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 234-234: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 251-251: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 272-272: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 322-322: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 369-369: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 369-369: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 469-469: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 469-469: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/devel_doc/ARCHITECTURE.md
[warning] 44-44: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/devel_doc/openapi.md
[warning] 8-8: Link fragments should be valid
(MD051, link-fragments)
[warning] 471-471: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 475-475: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 479-479: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 629-629: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 633-633: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 639-639: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 795-795: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 800-800: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 805-805: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 815-815: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 988-988: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 993-993: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1003-1003: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1110-1110: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1115-1115: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1259-1259: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1263-1263: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1266-1266: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1336-1336: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1341-1341: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1345-1345: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1448-1448: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1453-1453: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1457-1457: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1577-1577: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1581-1581: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1589-1589: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1669-1669: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 1670-1670: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
[warning] 1676-1676: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1680-1680: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1688-1688: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1768-1768: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 1769-1769: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
[warning] 1775-1775: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1780-1780: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1783-1783: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1888-1888: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 1889-1889: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
[warning] 1898-1898: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 1900-1900: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1904-1904: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1908-1908: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 1990-1990: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 1991-1991: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
[warning] 2001-2001: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 2005-2005: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2010-2010: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2014-2014: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2102-2102: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 2103-2103: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
[warning] 2113-2113: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 2115-2115: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2121-2121: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2130-2130: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2242-2242: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 2243-2243: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
[warning] 2254-2254: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 2258-2258: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2264-2264: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2269-2269: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2376-2376: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 2377-2377: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
[warning] 2387-2387: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 2392-2392: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2397-2397: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2401-2401: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2512-2512: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 2513-2513: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
[warning] 2519-2519: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2523-2523: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2531-2531: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2532-2532: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 2619-2619: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2624-2624: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2634-2634: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2734-2734: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2740-2740: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 2743-2743: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3017-3017: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3023-3023: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3026-3026: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3297-3297: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3302-3302: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3305-3305: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3366-3366: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 3367-3367: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
[warning] 3378-3378: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3382-3382: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3390-3390: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3463-3463: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3470-3470: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3473-3473: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3589-3589: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3592-3592: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3615-3615: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3620-3620: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 3911-3911: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 3912-3912: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
[warning] 5151-5151: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5155-5155: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5163-5163: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5240-5240: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5243-5243: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5251-5251: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5315-5315: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5318-5318: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5383-5383: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5387-5387: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5471-5471: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5474-5474: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5480-5480: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5502-5502: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5505-5505: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5511-5511: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5596-5596: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5599-5599: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5602-5602: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 5613-5613: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
[warning] 5882-5882: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 5882-5882: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 8576-8576: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/devel_doc/contributing_guide.md
[warning] 193-193: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 199-199: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 238-238: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 252-252: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 268-268: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 286-286: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 325-325: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 329-329: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
docs/devel_doc/providers.md
[warning] 229-229: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
[warning] 239-239: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
[warning] 292-292: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 294-294: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 296-296: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 308-308: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 310-310: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 316-316: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 323-323: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 325-325: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 338-338: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 353-353: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 365-365: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 370-370: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 372-372: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 378-378: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 380-380: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 382-382: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
docs/devel_doc/container_orchestration.md
[warning] 133-133: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 133-133: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 168-168: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 173-173: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 175-175: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 180-180: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 182-182: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 207-207: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 209-209: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 213-213: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 218-218: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 223-223: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 247-247: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 260-260: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 322-322: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 329-329: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 339-339: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 404-404: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 410-410: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 416-416: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 433-433: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 433-433: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 448-448: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 453-453: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 460-460: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 472-472: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 480-480: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 480-480: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 487-487: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 494-494: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 499-499: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 507-507: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 507-507: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 529-529: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 529-529: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 536-536: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 541-541: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 548-548: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 556-556: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 556-556: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 561-561: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 580-580: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 587-587: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 592-592: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 602-602: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 602-602: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 617-617: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 630-630: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 639-639: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 671-671: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 735-735: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 736-736: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 740-740: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 741-741: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 751-751: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 752-752: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 766-766: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 767-767: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 781-781: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 788-788: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🔇 Additional comments (12)
docs/devel_doc/installation_macos.md (1)
1-17: LGTM!docs/maintenance/version_status.md (1)
3-3: 🎯 Functional CorrectnessVerify that the referenced SVG is generated at this path.
This page references
./version_status.svg, while the supplied source isversion_status.puml. Confirm the documentation build generates or copies the SVG beside this Markdown file; otherwise the published page will show a broken image.docs/maintenance/version_status.puml (1)
13-16: 🎯 Functional CorrectnessThe RC timeline matches the scheduled maintenance dates. The chart uses the schedule column, while the first-release/end-of-life columns describe different milestones, so there’s no mismatch here.
> Likely an incorrect or invalid review comment.docs/maintenance/versions_supported.md (1)
9-11: 🎯 Functional CorrectnessLeave the
Futurestatuses as-is. TheScheduledates are planned and adjustable, so a passed date doesn’t by itself make the status wrong.> Likely an incorrect or invalid review comment.docs/devel_doc/ARCHITECTURE.md (1)
1-43: LGTM!Also applies to: 45-458, 463-581
docs/devel_doc/openapi.md (2)
8851-8860: 🔒 Security & PrivacyNo action needed on the default behavior.
allowed_service_accounts=Noneand[]are intentionally treated as unrestricted, and the docs/tests already reflect that.> Likely an incorrect or invalid review comment.
3371-3391: 🔒 Security & PrivacyConfiguration responses already mask secrets
The
/configresponse is backed bymodels.config.Configuration, and sensitive fields are declared asSecretStr, which serializes as masked values rather than raw credentials.tls_key_passwordis a file path, not the password itself.> Likely an incorrect or invalid review comment.docs/devel_doc/conversations_api.md (2)
1-168: LGTM!Also applies to: 177-193, 270-295, 414-514
169-176: 🗄️ Data Integrity & IntegrationNo config mismatch here.
storage.stores.conversationsmatches the runtime config layout used insrc/data/default_run.yamland the other run configs.> Likely an incorrect or invalid review comment.docs/devel_doc/providers.md (1)
1-352: LGTM!Also applies to: 366-393
docs/README.md (1)
12-15: LGTM!docs/index.md (1)
19-22: LGTM!
There was a problem hiding this comment.
Caution
Inline review comments failed to post. This is likely due to GitHub's internal server error or limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.
Actionable comments posted: 25
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/devel_doc/ARCHITECTURE.md`:
- Line 44: Update the fenced architecture diagram in ARCHITECTURE.md to specify
the text language identifier, changing the opening fence to use text while
preserving the diagram contents and closing fence.
- Around line 459-462: Update the Streaming Query API documentation to list the
registered /v1/streaming_query route instead of /v2/streaming_query, matching
the mounting configured by the streaming_query endpoint and routers.py. Keep the
deprecated Agent API entry unchanged unless its registration also requires
correction.
In `@docs/devel_doc/container_orchestration.md`:
- Around line 591-597: Update the firewall guidance in the container
orchestration documentation to avoid recommending globally opening port 8321. In
the “Check firewall rules” section, recommend binding the mapped service to
loopback or using a narrowly scoped firewall rule, and remove the permanent
unrestricted 8321/tcp opening instructions.
- Around line 740-748: Update the “Run the Container” podman command to include
the entrypoint and enrichment script mounts required for automatic enrichment,
matching the documented enrichment setup; alternatively, explicitly document
that the mounted configuration must already be pre-enriched.
- Around line 353-363: Update the health-check and troubleshooting examples in
the container orchestration guide to support both runtimes by using the selected
CONTAINER_RUNTIME in generic commands or providing equivalent Docker commands.
Replace hard-coded podman invocations while preserving the existing container
name, inspect format, and documented health-status values.
- Around line 29-36: Update the cleanup description in the make run workflow to
attribute automatic cleanup specifically to the run target, not run-stack.
Clarify that the trap is installed before run-stack is invoked, and avoid
implying that running make run-stack directly provides the same cleanup
behavior.
- Around line 751-760: Update the manual container instructions near “Monitor
the Container” so health inspection is valid: either add the required
healthcheck command and timing options to the documented podman run invocation,
or replace the podman inspect health-status step with the existing direct
/v1/health request.
- Around line 616-623: Update the “Option 1: Use 644 permissions” guidance in
the container orchestration documentation to clearly label chmod 644 as a
last-resort workaround only for disposable development credentials, and prefer
UID-compatible mounts, ACLs, or secret injection before it. Strengthen the
security note to explicitly state that the file is world-readable and must not
be used for production or sensitive credentials.
- Around line 447-450: Update the “Check logs saved by Makefile” troubleshooting
step in container_orchestration.md so health-check failures direct users to the
actual container/runtime logs instead of /tmp/llama-stack-failure.log, which is
only created for graceful-stop failures. If a file-based command is retained,
reference only a log file produced by the health-wait target.
In `@docs/devel_doc/contributing_guide.md`:
- Around line 193-199: Resolve the shared Markdownlint violations by adding
language identifiers to fenced code blocks and required blank lines around
headings and fences in docs/devel_doc/contributing_guide.md lines 193-199 and
docs/devel_doc/container_orchestration.md lines 133-139.
In `@docs/devel_doc/conversations_api.md`:
- Around line 194-269: Update the endpoint URLs in the Query Endpoint, Streaming
Query Endpoint, Conversations List Endpoint, and Conversation Detail Endpoint
sections to match the mounted routers: use /v1/query and /v1/streaming_query for
query routes, and /v2/conversations plus /v2/conversations/{conversation_id} for
conversation routes. Keep the request and response examples unchanged.
In `@docs/devel_doc/installation_linux.md`:
- Around line 13-17: Update the Linux installation steps in the documented setup
sequence to change the directory command to lightspeed-stack, matching the
directory created by git clone, and replace the uv info and uv install commands
with uv sync.
In `@docs/devel_doc/openapi.json`:
- Around line 2-3: Update the OpenAPI generation configuration associated with
the specification’s "openapi" and "info" definitions to declare the
authentication scheme under components.securitySchemes and apply it through the
top-level security array. Configure the backend’s OpenAPI settings, such as the
FastAPI security dependency or equivalent, so regenerated documentation
preserves these global definitions and enables client and Swagger authentication
support.
- Around line 7526-7533: Update the GET operation definitions in
docs/devel_doc/openapi.json at lines 7526-7533, 8472-8479, 5107-5114, 3597-3604,
2079-2086, and 894-901 to declare pagination parameters such as limit and
offset, with appropriate bounds/defaults consistent across list endpoints;
ensure the documented parameters are enforced by the corresponding API handlers
so responses remain bounded.
In `@docs/devel_doc/openapi.md`:
- Around line 3969-3974: Update both failed-deletion response examples in the
OpenAPI documentation to set the "success" field to false instead of true, while
preserving their existing error response text and structure.
- Around line 4628-4665: Update the Responses endpoint documentation around the
ResponsesResponse section to distinguish non-streaming JSON from stream=true
output. Document the streaming response as text/event-stream with its SSE event
schema, and remove any presentation of raw SSE events as a JSON example while
retaining the existing ResponsesResponse documentation for non-streaming
requests.
- Line 8: Update the APIs entry in the table of contents so its link fragment
matches the renderer-generated anchor for the “🛠️ APIs” heading. Regenerate the
TOC or replace `#apis` with the actual generated fragment, ensuring markdownlint
MD051 passes.
- Around line 471-479: Update the documentation generator responsible for the
OpenAPI Markdown sections so headings such as Parameters, Raises, and Returns
are followed by blank lines, and ensure equivalent spacing around related lists
and block content throughout the generated document. Regenerate the document or
apply the project’s Markdown formatter so the repeated MD022, MD031, and MD058
violations are resolved consistently.
- Around line 97-101: Update the OpenAPI endpoint inventory and detailed
sections around the existing `/v1/rags` documentation to cover
`/v1/vector-stores`, `/v1/files`, and all related advertised operations with
their requests, responses, and status codes; alternatively remove any
undocumented endpoints from the inventory. Keep the table of contents anchors
synchronized with the documented sections.
- Line 795: Update the examples throughout openapi.md, including the curl
command and the referenced ranges, to use fenced code blocks with appropriate
language tags such as bash or yaml. Replace indented code blocks and unlabeled
fences while preserving each example’s content and formatting.
- Around line 67-90: Update the inventory table entry for the `/v1/prompts`
endpoint to remove the trailing slash and use the canonical `/v1/prompts`
spelling consistently with the TOC and endpoint documentation.
In `@docs/devel_doc/providers.md`:
- Around line 353-365: Correct the YAML indentation in the models example so the
sequence item is nested under models and its fields, including model_id,
provider_id, model_type, and provider_model_id, are consistently indented within
that entry; preserve the surrounding providers and shields examples.
In `@docs/maintenance/version_status.md`:
- Line 1: Change the document’s opening heading from level two to a top-level
level-one heading in the version status page, preserving the existing heading
text and satisfying the document hierarchy requirement.
In `@docs/maintenance/versions_supported.md`:
- Line 3: Align both maintenance pages with their scheduled-date note by
italicizing scheduled dates in the tables while keeping the existing note
accurate. Apply the same correction in docs/maintenance/versions_supported.md
lines 3-3 and docs/maintenance/versions_unsupported.md lines 3-3.
In `@docs/README.md`:
- Line 65: Correct the operating-system capitalization in the installation
links: update “Installation on MacOS” to “Installation on macOS” in
docs/README.md lines 65-65 and docs/index.md lines 72-72.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 347670cf-60a9-45b4-b127-ef75ecac0adc
⛔ Files ignored due to path filters (3)
docs/devel_doc/architecture.pngis excluded by!**/*.pngdocs/devel_doc/architecture.svgis excluded by!**/*.svgdocs/maintenance/version_status.svgis excluded by!**/*.svg
📒 Files selected for processing (15)
docs/README.mddocs/devel_doc/ARCHITECTURE.mddocs/devel_doc/container_orchestration.mddocs/devel_doc/contributing_guide.mddocs/devel_doc/conversations_api.mddocs/devel_doc/installation_linux.mddocs/devel_doc/installation_macos.mddocs/devel_doc/openapi.jsondocs/devel_doc/openapi.mddocs/devel_doc/providers.mddocs/index.mddocs/maintenance/version_status.mddocs/maintenance/version_status.pumldocs/maintenance/versions_supported.mddocs/maintenance/versions_unsupported.md
📜 Review details
🔇 Additional comments (12)
docs/devel_doc/installation_macos.md (1)
1-17: LGTM!docs/maintenance/version_status.md (1)
3-3: 🎯 Functional CorrectnessVerify that the referenced SVG is generated at this path.
This page references
./version_status.svg, while the supplied source isversion_status.puml. Confirm the documentation build generates or copies the SVG beside this Markdown file; otherwise the published page will show a broken image.docs/maintenance/version_status.puml (1)
13-16: 🎯 Functional CorrectnessThe RC timeline matches the scheduled maintenance dates. The chart uses the schedule column, while the first-release/end-of-life columns describe different milestones, so there’s no mismatch here.
> Likely an incorrect or invalid review comment.docs/maintenance/versions_supported.md (1)
9-11: 🎯 Functional CorrectnessLeave the
Futurestatuses as-is. TheScheduledates are planned and adjustable, so a passed date doesn’t by itself make the status wrong.> Likely an incorrect or invalid review comment.docs/devel_doc/ARCHITECTURE.md (1)
1-43: LGTM!Also applies to: 45-458, 463-581
docs/devel_doc/openapi.md (2)
8851-8860: 🔒 Security & PrivacyNo action needed on the default behavior.
allowed_service_accounts=Noneand[]are intentionally treated as unrestricted, and the docs/tests already reflect that.> Likely an incorrect or invalid review comment.
3371-3391: 🔒 Security & PrivacyConfiguration responses already mask secrets
The
/configresponse is backed bymodels.config.Configuration, and sensitive fields are declared asSecretStr, which serializes as masked values rather than raw credentials.tls_key_passwordis a file path, not the password itself.> Likely an incorrect or invalid review comment.docs/devel_doc/conversations_api.md (2)
1-168: LGTM!Also applies to: 177-193, 270-295, 414-514
169-176: 🗄️ Data Integrity & IntegrationNo config mismatch here.
storage.stores.conversationsmatches the runtime config layout used insrc/data/default_run.yamland the other run configs.> Likely an incorrect or invalid review comment.docs/devel_doc/providers.md (1)
1-352: LGTM!Also applies to: 366-393
docs/README.md (1)
12-15: LGTM!docs/index.md (1)
19-22: LGTM!
🛑 Comments failed to post (25)
docs/devel_doc/ARCHITECTURE.md (2)
44-44: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Specify a language for the fenced architecture diagram.
Use
textfor this ASCII diagram so Markdown linting passes.Proposed fix
-``` +```text📝 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.🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 44-44: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/ARCHITECTURE.md` at line 44, Update the fenced architecture diagram in ARCHITECTURE.md to specify the text language identifier, changing the opening fence to use text while preserving the diagram contents and closing fence.Source: Linters/SAST tools
459-462: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash rg -n -C4 'streaming_query|include_router' src app --glob '*.py'Repository: lightspeed-core/lightspeed-stack
Length of output: 10662
🏁 Script executed:
#!/bin/bash sed -n '450,470p' docs/devel_doc/ARCHITECTURE.md printf '\n---\n' sed -n '60,75p' src/app/routers.py printf '\n---\n' sed -n '166,186p' src/app/endpoints/streaming_query.pyRepository: lightspeed-core/lightspeed-stack
Length of output: 2397
Update the streaming query path in the docs.
src/app/endpoints/streaming_query.pyis mounted throughsrc/app/routers.pyunder/v1, so the published contract should not list/v2/streaming_queryhere. Use the registered/v1/streaming_queryroute, or add a v2 router if that is the intended public endpoint.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/ARCHITECTURE.md` around lines 459 - 462, Update the Streaming Query API documentation to list the registered /v1/streaming_query route instead of /v2/streaming_query, matching the mounting configured by the streaming_query endpoint and routers.py. Keep the deprecated Agent API entry unchanged unless its registration also requires correction.docs/devel_doc/container_orchestration.md (7)
29-36: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Attribute the cleanup trap to
make run, notrun-stack.The Makefile installs the trap in the
runtarget before invokingrun-stack;make run-stackitself is not shown to install that trap. Update this description so users do not expect cleanup when runningmake run-stackdirectly.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/container_orchestration.md` around lines 29 - 36, Update the cleanup description in the make run workflow to attribute automatic cleanup specifically to the run target, not run-stack. Clarify that the trap is installed before run-stack is invoked, and avoid implying that running make run-stack directly provides the same cleanup behavior.
353-363: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Support both container runtimes in generic commands.
The guide supports Podman and Docker, but the health and troubleshooting examples hard-code
podman. Docker users cannot follow these commands. Use the selectedCONTAINER_RUNTIMEor provide equivalent Docker commands throughout.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/container_orchestration.md` around lines 353 - 363, Update the health-check and troubleshooting examples in the container orchestration guide to support both runtimes by using the selected CONTAINER_RUNTIME in generic commands or providing equivalent Docker commands. Replace hard-coded podman invocations while preserving the existing container name, inspect format, and documented health-status values.
447-450: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Do not use the stop-timeout log for health-check failures.
The documented
/tmp/llama-stack-failure.logis created for graceful-stop failures, while a health timeout is handled by displaying container logs. Point users to the actual runtime logs or document a file that the health-wait target really creates.🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 448-448: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/container_orchestration.md` around lines 447 - 450, Update the “Check logs saved by Makefile” troubleshooting step in container_orchestration.md so health-check failures direct users to the actual container/runtime logs instead of /tmp/llama-stack-failure.log, which is only created for graceful-stop failures. If a file-based command is retained, reference only a log file produced by the health-wait target.
591-597: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Do not recommend exposing port 8321 globally.
The Makefile maps the container port without a loopback restriction. Permanently opening
8321/tcpcan expose an unauthenticated Llama Stack service to the network. Recommend loopback binding or a narrowly scoped firewall rule instead.🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 592-592: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/container_orchestration.md` around lines 591 - 597, Update the firewall guidance in the container orchestration documentation to avoid recommending globally opening port 8321. In the “Check firewall rules” section, recommend binding the mapped service to loopback or using a narrowly scoped firewall rule, and remove the permanent unrestricted 8321/tcp opening instructions.
616-623: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Avoid making cloud credentials world-readable.
The macOS guidance says users must use
chmod 644, which allows every local user and process to read the credential file. Make this a last-resort workaround for disposable development credentials and prefer UID-compatible mounts, ACLs, or secret injection.Also applies to: 649-649
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 617-617: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/container_orchestration.md` around lines 616 - 623, Update the “Option 1: Use 644 permissions” guidance in the container orchestration documentation to clearly label chmod 644 as a last-resort workaround only for disposable development credentials, and prefer UID-compatible mounts, ACLs, or secret injection before it. Strengthen the security note to explicitly state that the file is world-readable and must not be used for production or sensitive credentials.Source: Coding guidelines
740-748: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Include the enrichment mounts in the manual container command.
The documented automatic enrichment requires the entrypoint and enrichment script mounts, but this
podman runcommand mounts only the two YAML files. Add the missing mounts/entrypoint or explicitly require a pre-enriched configuration.🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 740-740: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
[warning] 741-741: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/container_orchestration.md` around lines 740 - 748, Update the “Run the Container” podman command to include the entrypoint and enrichment script mounts required for automatic enrichment, matching the documented enrichment setup; alternatively, explicitly document that the mounted configuration must already be pre-enriched.
751-760: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Define a healthcheck before inspecting container health.
The manual
podman runcommand does not pass--health-cmdor health timing options, so.State.Health.Statuswill not provide the documented status. Add the healthcheck configuration or replace this step with a direct/v1/healthrequest.🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 751-751: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
[warning] 752-752: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/container_orchestration.md` around lines 751 - 760, Update the manual container instructions near “Monitor the Container” so health inspection is valid: either add the required healthcheck command and timing options to the documented podman run invocation, or replace the podman inspect health-status step with the existing direct /v1/health request.docs/devel_doc/contributing_guide.md (1)
193-199: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Resolve the shared Markdownlint violations before merging.
Both documents contain newly added MD022, MD031, and MD040 violations. Fix the reported heading spacing, fence spacing, and missing fence-language issues at each site.
docs/devel_doc/contributing_guide.md#L193-L199: add fence language identifiers and required blank lines throughout the document.docs/devel_doc/container_orchestration.md#L133-L139: add fence language identifiers and required blank lines throughout the document.🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 193-193: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 199-199: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
📍 Affects 2 files
docs/devel_doc/contributing_guide.md#L193-L199(this comment)docs/devel_doc/container_orchestration.md#L133-L139🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/contributing_guide.md` around lines 193 - 199, Resolve the shared Markdownlint violations by adding language identifiers to fenced code blocks and required blank lines around headings and fences in docs/devel_doc/contributing_guide.md lines 193-199 and docs/devel_doc/container_orchestration.md lines 133-139.Source: Linters/SAST tools
docs/devel_doc/conversations_api.md (1)
194-269: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash set -euo pipefail printf '--- routers candidates ---\n' git ls-files | rg '(^|/)routers\.py$|(^|/)router(s)?\.py$|(^|/)routes?\.py$' printf '\n--- docs candidate ---\n' git ls-files docs/devel_doc/conversations_api.md printf '\n--- routers.py outline (if present) ---\n' if git ls-files | rg -q '(^|/)routers\.py$'; then router_file=$(git ls-files | rg '(^|/)routers\.py$' | head -n 1) ast-grep outline "$router_file" --view expanded || true fi printf '\n--- doc excerpt ---\n' sed -n '194,410p' docs/devel_doc/conversations_api.mdRepository: lightspeed-core/lightspeed-stack
Length of output: 261
🏁 Script executed:
#!/bin/bash set -euo pipefail echo "ping"Repository: lightspeed-core/lightspeed-stack
Length of output: 175
🏁 Script executed:
#!/bin/bash set -euo pipefail echo '--- routers candidates ---' git ls-files | rg '(^|/)routers\.py$|(^|/)router(s)?\.py$|(^|/)routes?\.py$' || true echo echo '--- docs candidate ---' git ls-files docs/devel_doc/conversations_api.md || true echo echo '--- routers outline ---' router_file=$(git ls-files | rg '(^|/)routers\.py$' | head -n 1 || true) if [ -n "${router_file:-}" ]; then ast-grep outline "$router_file" --view expanded || true fi echo echo '--- routers registration search ---' if [ -n "${router_file:-}" ]; then rg -n 'include_router|APIRouter|prefix=|query|streaming_query|conversations' "$router_file" || true fi echo echo '--- doc excerpt 194-410 ---' sed -n '194,410p' docs/devel_doc/conversations_api.mdRepository: lightspeed-core/lightspeed-stack
Length of output: 7543
🏁 Script executed:
#!/bin/bash set -euo pipefail files=( src/app/query.py src/app/streaming_query.py src/app/conversations_v2.py src/app/conversations_v1.py ) for f in "${files[@]}"; do if git ls-files --error-unmatch "$f" >/dev/null 2>&1; then echo "=== $f ===" ast-grep outline "$f" --view expanded || true echo rg -n 'APIRouter|router =|`@router`\.(get|post|put|delete|patch)|prefix=|/v[123]/conversations|/query|/streaming_query|/conversations' "$f" || true echo fi done echo '=== search for /v3/conversations across repo ===' rg -n '/v3/conversations|conversations_v3|/v2/streaming_query|/v2/query' src docs || trueRepository: lightspeed-core/lightspeed-stack
Length of output: 2235
🏁 Script executed:
#!/bin/bash set -euo pipefail echo '=== files matching conversation/query route modules ===' git ls-files | rg '(^|/)(conversations(_v[0-9]+)?|query|streaming_query)\.(py|ts|tsx|js|jsx)$' || true echo echo '=== references to conversations_v2 / conversations_v1 symbols ===' rg -n 'conversations_v2|conversations_v1|streaming_query|query\.router|router\.prefix|APIRouter' src || true echo echo '=== inspect routers.py imports ===' sed -n '1,120p' src/app/routers.pyRepository: lightspeed-core/lightspeed-stack
Length of output: 9765
🏁 Script executed:
#!/bin/bash set -euo pipefail for f in src/app/endpoints/query.py src/app/endpoints/streaming_query.py src/app/endpoints/conversations_v2.py src/app/endpoints/conversations_v1.py; do if git ls-files --error-unmatch "$f" >/dev/null 2>&1; then echo "=== $f ===" rg -n 'APIRouter|router =|`@router`\.(get|post|put|delete|patch)|"/[^"]+"' "$f" || true echo fi doneRepository: lightspeed-core/lightspeed-stack
Length of output: 1484
Update the documented URLs to match the mounted routers.
queryandstreaming_querylive under/v1, and conversations live under/v2; the/v2/query,/v2/streaming_query, and/v3/conversations*examples will point to nonexistent routes.🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 199-199: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 209-209: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 234-234: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 251-251: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/conversations_api.md` around lines 194 - 269, Update the endpoint URLs in the Query Endpoint, Streaming Query Endpoint, Conversations List Endpoint, and Conversation Detail Endpoint sections to match the mounted routers: use /v1/query and /v1/streaming_query for query routes, and /v2/conversations plus /v2/conversations/{conversation_id} for conversation routes. Keep the request and response examples unchanged.docs/devel_doc/installation_linux.md (1)
13-17: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash rg -n 'cd (service|lightspeed-stack)|uv (info|install|sync)' \ docs/devel_doc/installation_linux.md \ docs/devel_doc/installation_macos.md \ docs/devel_doc/contributing_guide.mdRepository: lightspeed-core/lightspeed-stack
Length of output: 599
🏁 Script executed:
#!/bin/bash set -euo pipefail printf '\n== installation_linux.md ==\n' cat -n docs/devel_doc/installation_linux.md | sed -n '1,80p' printf '\n== installation_macos.md ==\n' cat -n docs/devel_doc/installation_macos.md | sed -n '1,80p' printf '\n== contributing_guide.md ==\n' cat -n docs/devel_doc/contributing_guide.md | sed -n '60,90p'Repository: lightspeed-core/lightspeed-stack
Length of output: 2452
🌐 Web query:
uv CLI reference info install sync official docs💡 Result:
The uv CLI is a fast Python package installer and project manager [1]. Below is the reference information for installation and synchronization based on the official documentation. Installation uv provides a standalone installer for macOS, Linux, and Windows [2][1]. For macOS and Linux, use: curl -LsSf https://astral.sh/uv/install.sh | sh [2][1] For Windows, use PowerShell: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" [2][1] Other installation methods, including package managers like pip or Homebrew, are also supported [2][1]. Synchronization (Syncing) In uv, syncing is the process of installing dependencies from a project lockfile into the project environment [3][4]. Automatic Syncing Syncing is often automatic. Commands such as uv run or uv tree will automatically lock and sync the project environment before executing to ensure it remains up-to-date [3][4]. Explicit Syncing To manually sync the environment, use the command: uv sync [3][4] Key behaviors and flags: - Exact vs. Inexact: By default, uv sync performs an "exact" sync, which removes any packages in the environment that are not present in the lockfile [3][4]. To retain extraneous packages, use the --inexact flag [3][4]. - uv run: By default, uv run uses "inexact" syncing. To enable exact syncing with uv run, use the --exact flag [3][4]. - Partial Installations: For use cases like Docker image layer caching, flags such as --no-install-project, --no-install-workspace, and --no-install-package can be used to skip specific installations while still installing dependencies [3][4]. Pip-compatible Interface For users migrating from pip, uv provides a compatible interface. For example, to install dependencies from a requirements file, you can use: uv pip sync requirements.txt [1]
Citations:
- 1: https://docs.astral.sh/uv/
- 2: https://docs.astral.sh/uv/getting-started/installation/
- 3: https://docs.astral.sh/uv/concepts/projects/sync/
- 4: https://docs.astral.sh/uv/concepts/projects/sync/index.md
Fix the Linux install steps.
git clonecreateslightspeed-stack, socd servicepoints to the wrong directory. Usecd lightspeed-stackanduv syncinstead ofuv info/uv install. docs/devel_doc/installation_linux.md:13-17🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/installation_linux.md` around lines 13 - 17, Update the Linux installation steps in the documented setup sequence to change the directory command to lightspeed-stack, matching the directory created by git clone, and replace the uv info and uv install commands with uv sync.docs/devel_doc/openapi.json (2)
2-3: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Define global security schemes in the OpenAPI specification.
The OpenAPI specification lacks the global
securityarray andcomponents.securitySchemesdefinitions. Although the endpoint descriptions and 401/403 HTTP responses indicate that authentication is enforced by the API (likely via middleware), the absence of formal security definitions in the schema prevents API clients and interactive documentation (like Swagger UI) from automatically supporting authentication correctly.Consider configuring the security schemes in the backend application (e.g., FastAPI) so they are included in the generated OpenAPI specification.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/openapi.json` around lines 2 - 3, Update the OpenAPI generation configuration associated with the specification’s "openapi" and "info" definitions to declare the authentication scheme under components.securitySchemes and apply it through the top-level security array. Configure the backend’s OpenAPI settings, such as the FastAPI security dependency or equivalent, so regenerated documentation preserves these global definitions and enables client and Swagger authentication support.Source: Linters/SAST tools
7526-7533: 🚀 Performance & Scalability | 🟠 Major | 🏗️ Heavy lift
Missing pagination on list operations.
As per coding guidelines, list operations and API endpoints must implement pagination or limits. The following endpoints return lists but do not specify pagination parameters (e.g.,
limit,offset), which can lead to performance degradation and unbounded memory usage as the data set grows. Consider updating the API route definitions to accept and enforce pagination limits.
docs/devel_doc/openapi.json#L7526-L7533: add pagination parameters to the/v1/conversationsGET endpoint.docs/devel_doc/openapi.json#L8472-L8479: add pagination parameters to the/v2/conversationsGET endpoint.docs/devel_doc/openapi.json#L5107-L5114: add pagination parameters to the/v1/vector-stores/{vector_store_id}/filesGET endpoint.docs/devel_doc/openapi.json#L3597-L3604: add pagination parameters to the/v1/vector-storesGET endpoint.docs/devel_doc/openapi.json#L2079-L2086: add pagination parameters to the/v1/promptsGET endpoint.docs/devel_doc/openapi.json#L894-L901: add pagination parameters to the/v1/mcp-serversGET endpoint.📍 Affects 1 file
docs/devel_doc/openapi.json#L7526-L7533(this comment)docs/devel_doc/openapi.json#L8472-L8479docs/devel_doc/openapi.json#L5107-L5114docs/devel_doc/openapi.json#L3597-L3604docs/devel_doc/openapi.json#L2079-L2086docs/devel_doc/openapi.json#L894-L901🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/openapi.json` around lines 7526 - 7533, Update the GET operation definitions in docs/devel_doc/openapi.json at lines 7526-7533, 8472-8479, 5107-5114, 3597-3604, 2079-2086, and 894-901 to declare pagination parameters such as limit and offset, with appropriate bounds/defaults consistent across list endpoints; ensure the documented parameters are enforced by the corresponding API handlers so responses remain bounded.Source: Coding guidelines
docs/devel_doc/openapi.md (7)
8-8: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Fix the invalid TOC anchor.
The
#apisfragment does not match the generated anchor for# 🛠️ APIs; markdownlint reports MD051. Regenerate the TOC or replace this link with the renderer’s actual fragment.🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 8-8: Link fragments should be valid
(MD051, link-fragments)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/openapi.md` at line 8, Update the APIs entry in the table of contents so its link fragment matches the renderer-generated anchor for the “🛠️ APIs” heading. Regenerate the TOC or replace `#apis` with the actual generated fragment, ensuring markdownlint MD051 passes.Source: Linters/SAST tools
67-90: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash set -euo pipefail echo "== relevant lines from docs/devel_doc/openapi.md ==" nl -ba docs/devel_doc/openapi.md | sed -n '60,100p' echo echo "== all prompts route occurrences ==" rg -n --fixed-strings '/v1/prompts' docs/devel_doc/openapi.md echo echo "== nearby route-related headings ==" rg -n --fixed-strings 'prompts' docs/devel_doc/openapi.md | sed -n '1,80p'Repository: lightspeed-core/lightspeed-stack
Length of output: 262
🏁 Script executed:
#!/bin/bash set -euo pipefail echo "== docs/devel_doc/openapi.md lines 60-100 ==" awk 'NR>=60 && NR<=100 { printf "%d:%s\n", NR, $0 }' docs/devel_doc/openapi.md echo echo "== all /v1/prompts occurrences in docs/devel_doc/openapi.md ==" rg -n --fixed-strings '/v1/prompts' docs/devel_doc/openapi.md echo echo "== all prompts route mentions in repository ==" rg -n --fixed-strings '/v1/prompts' . echo echo "== all prompts route mentions with trailing slash ==" rg -n --fixed-strings '/v1/prompts/' .Repository: lightspeed-core/lightspeed-stack
Length of output: 21417
Normalize
/v1/promptsto one spelling. The inventory table at 420-421 uses/v1/prompts/, while the TOC, examples, generated OpenAPI, and endpoint docs use/v1/prompts. Make the table match the canonical path to avoid ambiguity.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/openapi.md` around lines 67 - 90, Update the inventory table entry for the `/v1/prompts` endpoint to remove the trailing slash and use the canonical `/v1/prompts` spelling consistently with the TOC and endpoint documentation.
97-101: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Document the vector-store and file endpoints listed here.
The endpoint inventory advertises
/v1/vector-stores,/v1/files, and related operations, but the TOC and detailed API sections contain no corresponding entries. Add their request/response/status documentation, or remove them from the inventory until documented.Also applies to: 407-436
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/openapi.md` around lines 97 - 101, Update the OpenAPI endpoint inventory and detailed sections around the existing `/v1/rags` documentation to cover `/v1/vector-stores`, `/v1/files`, and all related advertised operations with their requests, responses, and status codes; alternatively remove any undocumented endpoints from the inventory. Keep the table of contents anchors synchronized with the documented sections.
471-479: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win
Fix the repeated heading-spacing violations.
### Parameters,### Raises, and### Returnsare not separated from their following content by blank lines, and the same pattern is repeated throughout the generated document. Update the generator or run a Markdown formatter to resolve the reported MD022/MD031/MD058 violations.🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 471-471: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
[warning] 475-475: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
[warning] 479-479: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/openapi.md` around lines 471 - 479, Update the documentation generator responsible for the OpenAPI Markdown sections so headings such as Parameters, Raises, and Returns are followed by blank lines, and ensure equivalent spacing around related lists and block content throughout the generated document. Regenerate the document or apply the project’s Markdown formatter so the repeated MD022, MD031, and MD058 violations are resolved consistently.Source: Linters/SAST tools
795-795: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win
Use fenced, language-tagged code blocks consistently.
The document contains multiple indented code blocks and an unlabeled YAML fence. Convert examples to fenced blocks such as
yamlorbashto satisfy markdownlint and preserve syntax highlighting.Also applies to: 1898-1898, 2001-2003, 2113-2113, 2254-2256, 2387-2387, 2532-2532, 5882-5886, 8573-8580
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 795-795: Code block style
Expected: fenced; Actual: indented(MD046, code-block-style)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/openapi.md` at line 795, Update the examples throughout openapi.md, including the curl command and the referenced ranges, to use fenced code blocks with appropriate language tags such as bash or yaml. Replace indented code blocks and unlabeled fences while preserving each example’s content and formatting.Source: Linters/SAST tools
3969-3974: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Correct the failed-deletion examples.
Both examples say
"can not be deleted"but set"success": true. Change those examples tofalseso clients are not taught to interpret a failed deletion as successful.Also applies to: 4426-4431
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/openapi.md` around lines 3969 - 3974, Update both failed-deletion response examples in the OpenAPI documentation to set the "success" field to false instead of true, while preserving their existing error response text and structure.
4628-4665: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Document the streaming response as SSE, not JSON.
The endpoint describes streaming behavior, but the response table advertises only
ResponsesResponse, and the example places raw SSE events inside ajsonblock. Document thestream=trueresponse astext/event-streamwith its event schema separately from the non-streaming JSON response.Also applies to: 4670-4672
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/openapi.md` around lines 4628 - 4665, Update the Responses endpoint documentation around the ResponsesResponse section to distinguish non-streaming JSON from stream=true output. Document the streaming response as text/event-stream with its SSE event schema, and remove any presentation of raw SSE events as a JSON example while retaining the existing ResponsesResponse documentation for non-streaming requests.docs/devel_doc/providers.md (1)
353-365: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Fix the indentation in the
modelsYAML example.The sequence item and its mapping fields are misindented:
models: - model_id: gpt-4-turbo provider_id: openaiCopied as shown, this is not a valid resource definition. Use consistent nesting for each model entry.
Proposed correction
models: -- model_id: gpt-4-turbo - provider_id: openai - model_type: llm - provider_model_id: gpt-4-turbo + - model_id: gpt-4-turbo + provider_id: openai + model_type: llm + provider_model_id: gpt-4-turbo🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 353-353: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 365-365: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/devel_doc/providers.md` around lines 353 - 365, Correct the YAML indentation in the models example so the sequence item is nested under models and its fields, including model_id, provider_id, model_type, and provider_model_id, are consistently indented within that entry; preserve the surrounding providers and shields examples.docs/maintenance/version_status.md (1)
1-1: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use a top-level heading.
Change
## Status of Lightspeed Core Stack versionsto# Status of Lightspeed Core Stack versionsto satisfy MD041 and keep this page’s document hierarchy valid.🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/maintenance/version_status.md` at line 1, Change the document’s opening heading from level two to a top-level level-one heading in the version status page, preserving the existing heading text and satisfying the document hierarchy requirement.Source: Linters/SAST tools
docs/maintenance/versions_supported.md (1)
3-3: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Align the scheduled-date note with both maintenance tables.
Both pages claim scheduled dates are italicized, but their schedule cells are plain text.
docs/maintenance/versions_supported.md#L3-L3: italicize the schedule dates or revise the note.docs/maintenance/versions_unsupported.md#L3-L3: apply the same correction.📍 Affects 2 files
docs/maintenance/versions_supported.md#L3-L3(this comment)docs/maintenance/versions_unsupported.md#L3-L3🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/maintenance/versions_supported.md` at line 3, Align both maintenance pages with their scheduled-date note by italicizing scheduled dates in the tables while keeping the existing note accurate. Apply the same correction in docs/maintenance/versions_supported.md lines 3-3 and docs/maintenance/versions_unsupported.md lines 3-3.docs/README.md (1)
65-65: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Correct the duplicated
macOScapitalization.
docs/README.md#L65-L65: change “Installation on MacOS” to “Installation on macOS”.docs/index.md#L72-L72: change “Installation on MacOS” to “Installation on macOS”.🧰 Tools
🪛 LanguageTool
[uncategorized] ~65-~65: The operating system from Apple is written “macOS”.
Context: ...tallation_linux.html) [Installation on MacOS](https://lightspeed-core.github.io/ligh...(MAC_OS)
📍 Affects 2 files
docs/README.md#L65-L65(this comment)docs/index.md#L72-L72🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/README.md` at line 65, Correct the operating-system capitalization in the installation links: update “Installation on MacOS” to “Installation on macOS” in docs/README.md lines 65-65 and docs/index.md lines 72-72.Source: Linters/SAST tools
1 participant
Description
LCORE-2933: Developer doc
Type of change
Tools used to create PR
Related Tickets & Documents
Summary by CodeRabbit