LCORE-461: sequence diagram for streaming query endpoint#792
Conversation
WalkthroughDocumentation additions for a streaming query endpoint REST API handler. The changes include a new table of contents entry and documentation section in README.md, plus a new UML sequence diagram file detailing the endpoint's control flow and component interactions. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant Endpoint as Streaming Query<br/>Endpoint Handler
participant Auth
participant LlamaStack as Llama Stack<br/>Client
participant Handler as Stream Build<br/>Event Handler
participant SSE as SSE Response<br/>Stream
Client->>Endpoint: HTTP POST /stream_query
Endpoint->>Auth: Authenticate & Authorize
Auth-->>Endpoint: ✓ Authorized
Note over Endpoint,LlamaStack: Initialization Phase
Endpoint->>LlamaStack: Request async response chunks
LlamaStack-->>Endpoint: Stream chunks
Endpoint->>SSE: Initialize SSE stream
SSE-->>Client: Connection opened
Note over Endpoint,Handler: Per-Chunk Processing
loop For each chunk
LlamaStack->>Handler: Deliver chunk
Handler->>Handler: Branch on chunk type<br/>(turn_start | inference |<br/>tool_execution | shield |<br/>turn_complete | error)
Handler->>SSE: Emit SSE event
SSE-->>Client: Send event
end
Note over Endpoint,Handler: Finalization Phase
Handler->>SSE: stream_end event<br/>(metadata + token_usage)
SSE-->>Client: Final event
SSE->>Endpoint: Stream closed
opt Persistence
Endpoint->>Endpoint: Cache/persist transcript
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Notes:
Possibly related PRs
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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: 2
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
docs/streaming_query_endpoint.svgis excluded by!**/*.svg
📒 Files selected for processing (2)
README.md(2 hunks)docs/streaming_query_endpoint.puml(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-10-29T13:05:22.438Z
Learnt from: luis5tb
Repo: lightspeed-core/lightspeed-stack PR: 727
File: src/app/endpoints/a2a.py:43-43
Timestamp: 2025-10-29T13:05:22.438Z
Learning: In the lightspeed-stack repository, endpoint files in src/app/endpoints/ intentionally use a shared logger name "app.endpoints.handlers" rather than __name__, allowing unified logging configuration across all endpoint handlers (query.py, streaming_query.py, a2a.py).
Applied to files:
README.md
🪛 markdownlint-cli2 (0.18.1)
README.md
83-83: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: build-pr
- GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request
- GitHub Check: e2e_tests (ci)
- GitHub Check: e2e_tests (azure)
🔇 Additional comments (4)
docs/streaming_query_endpoint.puml (4)
1-8: LGTM! Clear participant declarations.The PlantUML syntax is correct, and the participant declarations are clear and descriptive with appropriate aliases.
10-14: LGTM! Proper authentication and streaming setup.The initial flow correctly shows authentication/authorization before calling the LlamaStack backend, and appropriately indicates the streaming nature with
AsyncIterator[AgentTurnResponseStreamChunk].
16-35: LGTM! Comprehensive chunk processing with proper error handling.The loop structure effectively illustrates the streaming flow with all major chunk types (turn_start, inference, tool_execution, shield, turn_complete) and includes error handling. The event handler pattern provides good separation of concerns.
37-41: LGTM! Proper stream finalization.The finalization flow correctly includes metadata and token usage in the end event, shows conditional persistence/caching, and explicitly closes the stream.
| * [REST API](#rest-api) | ||
| * [Sequence diagrams](#sequence-diagrams) | ||
| * [Query endpoint REST API handler](#query-endpoint-rest-api-handler) | ||
| * [Streaming query endpoint REST API handler](#streaming-query-endpoint-rest-api-handler) |
There was a problem hiding this comment.
Minor: Indentation inconsistent with markdown linting standards.
The 4-space indentation is consistent with the existing ToC entry on line 82, but markdownlint expects 2 spaces for nested list items. While this maintains consistency with the current style, consider updating both entries to use 2-space indentation in a follow-up to comply with markdown standards.
Apply this diff to fix the indentation:
* [Sequence diagrams](#sequence-diagrams)
* [Query endpoint REST API handler](#query-endpoint-rest-api-handler)
- * [Streaming query endpoint REST API handler](#streaming-query-endpoint-rest-api-handler)
+ * [Streaming query endpoint REST API handler](#streaming-query-endpoint-rest-api-handler)Note: You may also want to fix line 82 in the same way for full compliance.
📝 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.
| * [Streaming query endpoint REST API handler](#streaming-query-endpoint-rest-api-handler) | |
| * [Streaming query endpoint REST API handler](#streaming-query-endpoint-rest-api-handler) |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
83-83: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
🤖 Prompt for AI Agents
In README.md around line 83, the ToC entry uses 4-space indentation which
conflicts with markdownlint's 2-space expectation for nested list items; change
the indentation of the line 83 entry from 4 spaces to 2 spaces to match
markdownlint rules, and also update the adjacent line 82 to 2-space indentation
for consistent nested list formatting across both entries.
| ## Streaming query endpoint REST API handler | ||
|
|
||
|  |
There was a problem hiding this comment.
Fix heading level to match document structure.
The heading uses ## (h2) but should use ### (h3) to match the existing "Query endpoint REST API handler" section at line 901 and align with the ToC structure where both entries are nested under "Sequence diagrams".
Apply this diff to fix the heading level:
-## Streaming query endpoint REST API handler
+### Streaming query endpoint REST API handler📝 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.
| ## Streaming query endpoint REST API handler | |
|  | |
| ### Streaming query endpoint REST API handler | |
|  |
🤖 Prompt for AI Agents
In README.md around lines 905 to 907, change the heading level for "Streaming
query endpoint REST API handler" from an h2 (##) to an h3 (###) so it matches
the "Query endpoint REST API handler" section at line 901 and aligns with the
Table of Contents under "Sequence diagrams"; open the file, replace the leading
"##" with "###" on that heading line and save.
1 participant
Description
LCORE-461: sequence diagram for streaming query endpoint
Type of change
Related Tickets & Documents
Summary by CodeRabbit