From a3dc0ff343f8c61bb24931dd5405d0c0f2c4c32e Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Thu, 13 Nov 2025 08:42:13 +0100 Subject: [PATCH] LCORE-460: sequence diagram for query endpoint --- README.md | 11 +++ docs/query_endpoint.puml | 43 +++++++++++ docs/query_endpoint.svg | 156 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 210 insertions(+) create mode 100644 docs/query_endpoint.puml create mode 100644 docs/query_endpoint.svg diff --git a/README.md b/README.md index 18be9bd0..89c0784e 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,9 @@ The service includes comprehensive user data collection capabilities for various * [Llama Stack version check](#llama-stack-version-check) * [User data collection](#user-data-collection) * [System prompt](#system-prompt) + * [System Prompt Path](#system-prompt-path) + * [System Prompt Literal](#system-prompt-literal) + * [Custom Profile](#custom-profile) * [Control model/provider overrides via authorization](#control-modelprovider-overrides-via-authorization) * [Safety Shields](#safety-shields) * [Authentication](#authentication) @@ -75,6 +78,8 @@ The service includes comprehensive user data collection capabilities for various * [Project structure](#project-structure) * [Configuration classes](#configuration-classes) * [REST API](#rest-api) + * [Sequence diagrams](#sequence-diagrams) + * [Query endpoint REST API handler](#query-endpoint-rest-api-handler) @@ -889,3 +894,9 @@ For complete integration setup, deployment options, and configuration details, s ## REST API ![REST API](docs/rest_api.png) + +## Sequence diagrams + +### Query endpoint REST API handler + +![Query endpoint](docs/query_endpoint.svg) diff --git a/docs/query_endpoint.puml b/docs/query_endpoint.puml new file mode 100644 index 00000000..3e76d84b --- /dev/null +++ b/docs/query_endpoint.puml @@ -0,0 +1,43 @@ +@startuml + +participant Client +participant Endpoint as "Query Endpoint handler" +participant Auth +participant LlamaStack as "Llama Stack Client" +participant Cache as Cache + +Client->>Endpoint: POST /query + attachments +Endpoint->>Auth: Validate auth & permissions +Auth-->>Endpoint: Authorized ✓ +Endpoint->>Auth: Check config & token quota +Auth-->>Endpoint: Config valid, tokens available +Endpoint->>DB: Retrieve user conversation (optional) +DB-->>Endpoint: UserConversation or None +Endpoint->>Endpoint: Select model/provider from hints/config +Endpoint->>LlamaStack: Get model capabilities +LlamaStack-->>Endpoint: Capabilities response +Endpoint->>Endpoint: Build system prompt, toolgroups, MCP headers +Endpoint->>LlamaStack: Create turn (agent interaction) +LlamaStack-->>Endpoint: Turn response + tool calls + RAG chunks +Endpoint->>Endpoint: Parse metadata & referenced documents +Endpoint->>Endpoint: Transform to QueryResponse +Endpoint->>DB: Persist conversation metadata (model, topic, count) +Endpoint->>Cache: Store conversation with timing metadata +Endpoint-->>Client: Return QueryResponse + token metrics + +alt Connection Error + LlamaStack-->>Endpoint: APIConnectionError + Endpoint-->>Client: HTTP 500 +end + +alt Quota Exceeded + Auth-->>Endpoint: Rate limit violation + Endpoint-->>Client: HTTP 429 +end + +alt Invalid Request + Endpoint-->>Client: Missing/invalid conversation or attachments + Endpoint-->>Client: HTTP 400/403/404 +end + +@enduml diff --git a/docs/query_endpoint.svg b/docs/query_endpoint.svg new file mode 100644 index 00000000..a025f12d --- /dev/null +++ b/docs/query_endpoint.svg @@ -0,0 +1,156 @@ + + + + + + + + + + + + + + + Client + + Client + + Query Endpoint handler + + Query Endpoint handler + + Auth + + Auth + + Llama Stack Client + + Llama Stack Client + + Cache + + Cache + + DB + + DB + + + + POST /query + attachments + + + + Validate auth & permissions + + + + Authorized ✓ + + + + Check config & token quota + + + + Config valid, tokens available + + + + Retrieve user conversation (optional) + + + + UserConversation or None + + + + + + Select model/provider from hints/config + + + + Get model capabilities + + + + Capabilities response + + + + + + Build system prompt, toolgroups, MCP headers + + + + Create turn (agent interaction) + + + + Turn response + tool calls + RAG chunks + + + + + + Parse metadata & referenced documents + + + + + + Transform to QueryResponse + + + + Persist conversation metadata (model, topic, count) + + + + Store conversation with timing metadata + + + + Return QueryResponse + token metrics + + + alt + [Connection Error] + + + + APIConnectionError + + + + HTTP 500 + + + alt + [Quota Exceeded] + + + + Rate limit violation + + + + HTTP 429 + + + alt + [Invalid Request] + + + + Missing/invalid conversation or attachments + + + + HTTP 400/403/404 + + +