From 029503443fc06bdd46a813a2d88690d78b43130e Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Wed, 15 Apr 2026 14:32:59 +0200 Subject: [PATCH] LCORE-1348: Updated OpenAPI schema --- docs/openapi.json | 7679 ++++++++++++++++++++++++++++----------------- docs/openapi.md | 189 ++ 2 files changed, 5062 insertions(+), 2806 deletions(-) diff --git a/docs/openapi.json b/docs/openapi.json index 29ad9da57..8679b5a03 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -1819,65 +1819,45 @@ } } }, - "/v1/query": { - "post": { + "/v1/vector-stores": { + "get": { "tags": [ - "query" + "vector-stores" ], - "summary": "Query Endpoint Handler", - "description": "Handle request to the /query endpoint using Responses API.\n\nProcesses a POST request to a query endpoint, forwarding the\nuser's query to a selected Llama Stack LLM and returning the generated response.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- query_request: Request to the LLM.\n- auth: Auth context tuple resolved from the authentication dependency.\n- mcp_headers: Headers that should be pass to MCP servers.\n\n### Returns:\n- QueryResponse: Contains the conversation ID and the LLM-generated response.\n\n### Raises:\n- HTTPException:\n- 401: Unauthorized - Missing or invalid credentials\n- 403: Forbidden - Insufficient permissions or model override not allowed\n- 404: Not Found - Conversation, model, or provider not found\n- 413: Prompt too long - Prompt exceeded model's context window size\n- 422: Unprocessable Entity - Request validation failed\n- 429: Quota limit exceeded - The token quota for model or user has been exceeded\n- 500: Internal Server Error - Configuration not loaded or other server errors\n- 503: Service Unavailable - Unable to connect to Llama Stack backend", - "operationId": "query_endpoint_handler_v1_query_post", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QueryRequest" - } - } - }, - "required": true - }, + "summary": "List Vector Stores", + "description": "List all vector stores.\n\nParameters:\n request: The incoming HTTP request.\n auth: Authentication tuple from the auth dependency.\n\nReturns:\n VectorStoresListResponse: List of all vector stores.\n\nRaises:\n HTTPException:\n - 401: Authentication failed\n - 403: Authorization failed\n - 500: Lightspeed Stack configuration not loaded\n - 503: Unable to connect to Llama Stack", + "operationId": "list_vector_stores_v1_vector_stores_get", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/QueryResponse" + "$ref": "#/components/schemas/VectorStoresListResponse" }, "example": { - "available_quotas": { - "ClusterQuotaLimiter": 998911, - "UserQuotaLimiter": 998911 - }, - "conversation_id": "123e4567-e89b-12d3-a456-426614174000", - "input_tokens": 123, - "output_tokens": 456, - "referenced_documents": [ - { - "doc_title": "Operator Lifecycle Manager concepts and resources", - "doc_url": "https://docs.openshift.com/container-platform/4.15/operators/understanding/olm/olm-understanding-olm.html" - } - ], - "response": "Operator Lifecycle Manager (OLM) helps users install...", - "tool_calls": [ + "data": [ { - "args": {}, - "id": "1", - "name": "tool1", - "type": "tool_call" - } - ], - "tool_results": [ + "created_at": 1704067200, + "id": "vs_abc123", + "last_active_at": 1704153600, + "metadata": { + "conversation_id": "conv_123" + }, + "name": "customer_support_docs", + "status": "active", + "usage_bytes": 1048576 + }, { - "content": "bla", - "id": "1", - "round": 1, - "status": "success", - "type": "tool_result" + "created_at": 1704070800, + "id": "vs_def456", + "last_active_at": 1704157200, + "name": "product_documentation", + "status": "active", + "usage_bytes": 2097152 } ], - "truncated": false + "object": "list" } } } @@ -1918,14 +1898,6 @@ "$ref": "#/components/schemas/ForbiddenResponse" }, "examples": { - "conversation read": { - "value": { - "detail": { - "cause": "User 6789 does not have permission to read conversation with ID 123e4567-e89b-12d3-a456-426614174000", - "response": "User does not have permission to perform this action" - } - } - }, "endpoint": { "value": { "detail": { @@ -1933,154 +1905,6 @@ "response": "User does not have permission to access this endpoint" } } - }, - "model override": { - "value": { - "detail": { - "cause": "User lacks model_override permission required to override model/provider.", - "response": "This instance does not permit overriding model/provider in the query request (missing permission: MODEL_OVERRIDE). Please remove the model and provider fields from your request." - } - } - } - } - } - } - }, - "404": { - "description": "Resource not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NotFoundResponse" - }, - "examples": { - "conversation": { - "value": { - "detail": { - "cause": "Conversation with ID 123e4567-e89b-12d3-a456-426614174000 does not exist", - "response": "Conversation not found" - } - } - }, - "provider": { - "value": { - "detail": { - "cause": "Provider with ID openai does not exist", - "response": "Provider not found" - } - } - }, - "model": { - "value": { - "detail": { - "cause": "Model with ID gpt-4-turbo is not configured", - "response": "Model not found" - } - } - } - } - } - } - }, - "422": { - "description": "Request validation failed", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UnprocessableEntityResponse" - }, - "examples": { - "invalid format": { - "value": { - "detail": { - "cause": "Invalid request format. The request body could not be parsed.", - "response": "Invalid request format" - } - } - }, - "missing attributes": { - "value": { - "detail": { - "cause": "Missing required attributes: ['query', 'model', 'provider']", - "response": "Missing required attributes" - } - } - }, - "invalid value": { - "value": { - "detail": { - "cause": "Invalid attachment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']", - "response": "Invalid attribute value" - } - } - } - } - } - } - }, - "429": { - "description": "Quota limit exceeded", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QuotaExceededResponse" - }, - "examples": { - "model": { - "value": { - "detail": { - "cause": "The token quota for model gpt-4-turbo has been exceeded.", - "response": "The model quota has been exceeded" - } - } - }, - "user none": { - "value": { - "detail": { - "cause": "User 123 has no available tokens.", - "response": "The quota has been exceeded" - } - } - }, - "cluster none": { - "value": { - "detail": { - "cause": "Cluster has no available tokens.", - "response": "The quota has been exceeded" - } - } - }, - "subject none": { - "value": { - "detail": { - "cause": "Unknown subject 999 has no available tokens.", - "response": "The quota has been exceeded" - } - } - }, - "user insufficient": { - "value": { - "detail": { - "cause": "User 123 has 5 tokens, but 10 tokens are needed.", - "response": "The quota has been exceeded" - } - } - }, - "cluster insufficient": { - "value": { - "detail": { - "cause": "Cluster has 500 tokens, but 900 tokens are needed.", - "response": "The quota has been exceeded" - } - } - }, - "subject insufficient": { - "value": { - "detail": { - "cause": "Unknown subject 999 has 3 tokens, but 6 tokens are needed.", - "response": "The quota has been exceeded" - } - } } } } @@ -2135,21 +1959,19 @@ } } } - } - }, - "/v1/streaming_query": { + }, "post": { "tags": [ - "streaming_query" + "vector-stores" ], - "summary": "Streaming Query Endpoint Handler", - "description": "Handle request to the /streaming_query endpoint using Responses API.\n\nReturns a streaming response using Server-Sent Events (SSE) format with\ncontent type text/event-stream.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- query_request: Request to the LLM.\n- auth: Auth context tuple resolved from the authentication dependency.\n- mcp_headers: Headers that should be passed to MCP servers.\n\n### Returns:\n- SSE-formatted events for the query lifecycle.\n\n### Raises:\n- HTTPException:\n- 401: Unauthorized - Missing or invalid credentials\n- 403: Forbidden - Insufficient permissions or model override not allowed\n- 404: Not Found - Conversation, model, or provider not found\n- 413: Prompt too long - Prompt exceeded model's context window size\n- 422: Unprocessable Entity - Request validation failed\n- 429: Quota limit exceeded - The token quota for model or user has been exceeded\n- 500: Internal Server Error - Configuration not loaded or other server errors\n- 503: Service Unavailable - Unable to connect to Llama Stack backend", - "operationId": "streaming_query_endpoint_handler_v1_streaming_query_post", + "summary": "Create Vector Store", + "description": "Create a new vector store.\n\nParameters:\n request: The incoming HTTP request.\n auth: Authentication tuple from the auth dependency.\n body: Vector store creation parameters.\n\nReturns:\n VectorStoreResponse: The created vector store object.\n\nRaises:\n HTTPException:\n - 401: Authentication failed\n - 403: Authorization failed\n - 500: Lightspeed Stack configuration not loaded\n - 503: Unable to connect to Llama Stack", + "operationId": "create_vector_store_v1_vector_stores_post", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/QueryRequest" + "$ref": "#/components/schemas/VectorStoreCreateRequest" } } }, @@ -2159,12 +1981,25 @@ "200": { "description": "Successful response", "content": { - "text/event-stream": { + "application/json": { "schema": { - "type": "string", - "format": "text/event-stream" + "$ref": "#/components/schemas/VectorStoreResponse" }, - "example": "data: {\"event\": \"start\", \"data\": {\"conversation_id\": \"123e4567-e89b-12d3-a456-426614174000\", \"request_id\": \"123e4567-e89b-12d3-a456-426614174001\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 0, \"token\": \"No Violation\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 1, \"token\": \"\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 2, \"token\": \"Hello\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 3, \"token\": \"!\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 4, \"token\": \" How\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 5, \"token\": \" can\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 6, \"token\": \" I\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 7, \"token\": \" assist\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 8, \"token\": \" you\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 9, \"token\": \" today\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 10, \"token\": \"?\"}}\n\ndata: {\"event\": \"turn_complete\", \"data\": {\"token\": \"Hello! How can I assist you today?\"}}\n\ndata: {\"event\": \"end\", \"data\": {\"referenced_documents\": [], \"truncated\": null, \"input_tokens\": 11, \"output_tokens\": 19}, \"available_quotas\": {}}\n\n" + "example": { + "created_at": 1704067200, + "id": "vs_abc123", + "last_active_at": 1704153600, + "metadata": { + "conversation_id": "conv_123", + "document_ids": [ + "doc_456", + "doc_789" + ] + }, + "name": "customer_support_docs", + "status": "active", + "usage_bytes": 1048576 + } } } }, @@ -2204,14 +2039,6 @@ "$ref": "#/components/schemas/ForbiddenResponse" }, "examples": { - "conversation read": { - "value": { - "detail": { - "cause": "User 6789 does not have permission to read conversation with ID 123e4567-e89b-12d3-a456-426614174000", - "response": "User does not have permission to perform this action" - } - } - }, "endpoint": { "value": { "detail": { @@ -2219,14 +2046,6 @@ "response": "User does not have permission to access this endpoint" } } - }, - "model override": { - "value": { - "detail": { - "cause": "User lacks model_override permission required to override model/provider.", - "response": "This instance does not permit overriding model/provider in the query request (missing permission: MODEL_OVERRIDE). Please remove the model and provider fields from your request." - } - } } } } @@ -2240,27 +2059,11 @@ "$ref": "#/components/schemas/NotFoundResponse" }, "examples": { - "conversation": { + "vector store": { "value": { "detail": { - "cause": "Conversation with ID 123e4567-e89b-12d3-a456-426614174000 does not exist", - "response": "Conversation not found" - } - } - }, - "provider": { - "value": { - "detail": { - "cause": "Provider with ID openai does not exist", - "response": "Provider not found" - } - } - }, - "model": { - "value": { - "detail": { - "cause": "Model with ID gpt-4-turbo is not configured", - "response": "Model not found" + "cause": "Vector Store with ID vs_abc123 does not exist", + "response": "Vector Store not found" } } } @@ -2268,35 +2071,19 @@ } } }, - "422": { - "description": "Request validation failed", + "500": { + "description": "Internal server error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnprocessableEntityResponse" + "$ref": "#/components/schemas/InternalServerErrorResponse" }, "examples": { - "invalid format": { - "value": { - "detail": { - "cause": "Invalid request format. The request body could not be parsed.", - "response": "Invalid request format" - } - } - }, - "missing attributes": { - "value": { - "detail": { - "cause": "Missing required attributes: ['query', 'model', 'provider']", - "response": "Missing required attributes" - } - } - }, - "invalid value": { + "configuration": { "value": { "detail": { - "cause": "Invalid attachment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']", - "response": "Invalid attribute value" + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" } } } @@ -2304,70 +2091,156 @@ } } }, - "429": { - "description": "Quota limit exceeded", + "503": { + "description": "Service unavailable", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/QuotaExceededResponse" + "$ref": "#/components/schemas/ServiceUnavailableResponse" }, "examples": { - "model": { - "value": { - "detail": { - "cause": "The token quota for model gpt-4-turbo has been exceeded.", - "response": "The model quota has been exceeded" - } - } - }, - "user none": { + "llama stack": { "value": { "detail": { - "cause": "User 123 has no available tokens.", - "response": "The quota has been exceeded" + "cause": "Connection error while trying to reach backend service.", + "response": "Unable to connect to Llama Stack" } } }, - "cluster none": { + "kubernetes api": { "value": { "detail": { - "cause": "Cluster has no available tokens.", - "response": "The quota has been exceeded" + "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", + "response": "Unable to connect to Kubernetes API" } } + } + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/vector-stores/{vector_store_id}": { + "get": { + "tags": [ + "vector-stores" + ], + "summary": "Get Vector Store", + "description": "Retrieve a vector store by ID.\n\nParameters:\n request: The incoming HTTP request.\n vector_store_id: ID of the vector store to retrieve.\n auth: Authentication tuple from the auth dependency.\n\nReturns:\n VectorStoreResponse: The vector store object.\n\nRaises:\n HTTPException:\n - 401: Authentication failed\n - 403: Authorization failed\n - 404: Vector store not found\n - 500: Lightspeed Stack configuration not loaded\n - 503: Unable to connect to Llama Stack", + "operationId": "get_vector_store_v1_vector_stores__vector_store_id__get", + "parameters": [ + { + "name": "vector_store_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Vector Store Id" + } + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VectorStoreResponse" + }, + "example": { + "created_at": 1704067200, + "id": "vs_abc123", + "last_active_at": 1704153600, + "metadata": { + "conversation_id": "conv_123", + "document_ids": [ + "doc_456", + "doc_789" + ] }, - "subject none": { + "name": "customer_support_docs", + "status": "active", + "usage_bytes": 1048576 + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "examples": { + "missing header": { "value": { "detail": { - "cause": "Unknown subject 999 has no available tokens.", - "response": "The quota has been exceeded" + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" } } }, - "user insufficient": { + "missing token": { "value": { "detail": { - "cause": "User 123 has 5 tokens, but 10 tokens are needed.", - "response": "The quota has been exceeded" + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" } } - }, - "cluster insufficient": { + } + }, + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + } + } + } + }, + "403": { + "description": "Permission denied", + "content": { + "application/json": { + "examples": { + "endpoint": { "value": { "detail": { - "cause": "Cluster has 500 tokens, but 900 tokens are needed.", - "response": "The quota has been exceeded" + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" } } - }, - "subject insufficient": { + } + }, + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "examples": { + "vector store": { "value": { "detail": { - "cause": "Unknown subject 999 has 3 tokens, but 6 tokens are needed.", - "response": "The quota has been exceeded" + "cause": "Vector Store with ID vs_abc123 does not exist", + "response": "Vector Store not found" } } } + }, + "schema": { + "$ref": "#/components/schemas/NotFoundResponse" } } } @@ -2376,9 +2249,6 @@ "description": "Internal server error", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/InternalServerErrorResponse" - }, "examples": { "configuration": { "value": { @@ -2388,6 +2258,9 @@ } } } + }, + "schema": { + "$ref": "#/components/schemas/InternalServerErrorResponse" } } } @@ -2396,9 +2269,6 @@ "description": "Service unavailable", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/ServiceUnavailableResponse" - }, "examples": { "llama stack": { "value": { @@ -2416,30 +2286,52 @@ } } } + }, + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" } } } } } - } - }, - "/v1/streaming_query/interrupt": { - "post": { + }, + "put": { "tags": [ - "streaming_query_interrupt" + "vector-stores" + ], + "summary": "Update Vector Store", + "description": "Update a vector store.\n\nParameters:\n request: The incoming HTTP request.\n vector_store_id: ID of the vector store to update.\n auth: Authentication tuple from the auth dependency.\n body: Vector store update parameters.\n\nReturns:\n VectorStoreResponse: The updated vector store object.\n\nRaises:\n HTTPException:\n - 401: Authentication failed\n - 403: Authorization failed\n - 404: Vector store not found\n - 500: Lightspeed Stack configuration not loaded\n - 503: Unable to connect to Llama Stack", + "operationId": "update_vector_store_v1_vector_stores__vector_store_id__put", + "parameters": [ + { + "name": "vector_store_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Vector Store Id" + } + } ], - "summary": "Streaming Query Interrupt Endpoint Handler", - "description": "Interrupt an in-progress streaming query by request identifier.\n\n### Parameters:\n- interrupt_request: Request payload containing the stream request ID.\n- auth: Auth context tuple resolved from the authentication dependency.\n- registry: Stream interrupt registry dependency used to cancel streams.\n\n### Returns:\n- StreamingInterruptResponse: Confirmation payload when interruption succeeds.\n\n### Raises:\n- HTTPException: If no active stream for the given request ID can be interrupted.", - "operationId": "stream_interrupt_endpoint_handler_v1_streaming_query_interrupt_post", "requestBody": { + "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/StreamingInterruptRequest" + "$ref": "#/components/schemas/VectorStoreUpdateRequest" } } - }, - "required": true + } }, "responses": { "200": { @@ -2447,12 +2339,22 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/StreamingInterruptResponse" + "$ref": "#/components/schemas/VectorStoreResponse" }, "example": { - "interrupted": true, - "message": "Streaming request interrupted", - "request_id": "123e4567-e89b-12d3-a456-426614174000" + "created_at": 1704067200, + "id": "vs_abc123", + "last_active_at": 1704153600, + "metadata": { + "conversation_id": "conv_123", + "document_ids": [ + "doc_456", + "doc_789" + ] + }, + "name": "customer_support_docs", + "status": "active", + "usage_bytes": 1048576 } } } @@ -2461,9 +2363,6 @@ "description": "Unauthorized", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/UnauthorizedResponse" - }, "examples": { "missing header": { "value": { @@ -2481,6 +2380,9 @@ } } } + }, + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" } } } @@ -2489,9 +2391,6 @@ "description": "Permission denied", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenResponse" - }, "examples": { "endpoint": { "value": { @@ -2501,6 +2400,9 @@ } } } + }, + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" } } } @@ -2509,187 +2411,110 @@ "description": "Resource not found", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/NotFoundResponse" - }, "examples": { - "streaming request": { + "vector store": { "value": { "detail": { - "cause": "Streaming Request with ID 123e4567-e89b-12d3-a456-426614174000 does not exist", - "response": "Streaming Request not found" + "cause": "Vector Store with ID vs_abc123 does not exist", + "response": "Vector Store not found" } } } + }, + "schema": { + "$ref": "#/components/schemas/NotFoundResponse" } } } }, - "422": { - "description": "Validation Error", + "500": { + "description": "Internal server error", "content": { "application/json": { + "examples": { + "configuration": { + "value": { + "detail": { + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" + } + } + } + }, "schema": { - "$ref": "#/components/schemas/HTTPValidationError" - } - } - } - } - } - } - }, - "/v1/config": { - "get": { - "tags": [ - "config" - ], - "summary": "Config Endpoint Handler", - "description": "Handle requests to the /config endpoint.\n\nProcess GET requests to the /config endpoint and returns the\ncurrent service configuration.\n\nEnsures the application configuration is loaded before returning it.\n\n### Parameters:\n- request: The incoming HTTP request.\n- auth: Authentication tuple from the auth dependency.\n\n### Returns:\n- ConfigurationResponse: The loaded service configuration response.", - "operationId": "config_endpoint_handler_v1_config_get", - "responses": { - "200": { - "description": "Successful response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConfigurationResponse" - }, - "example": { - "configuration": { - "authentication": { - "module": "noop", - "skip_tls_verification": false - }, - "authorization": { - "access_rules": [] - }, - "byok_rag": [], - "conversation_cache": {}, - "database": { - "sqlite": { - "db_path": "/tmp/lightspeed-stack.db" - } - }, - "inference": { - "default_model": "gpt-4-turbo", - "default_provider": "openai" - }, - "llama_stack": { - "api_key": "*****", - "url": "http://localhost:8321", - "use_as_library_client": false - }, - "mcp_servers": [ - { - "name": "server1", - "provider_id": "provider1", - "url": "http://url.com:1" - } - ], - "name": "lightspeed-stack", - "quota_handlers": { - "enable_token_history": false, - "limiters": [], - "scheduler": { - "period": 1 - } - }, - "service": { - "access_log": true, - "auth_enabled": false, - "color_log": true, - "cors": { - "allow_credentials": false, - "allow_headers": [ - "*" - ], - "allow_methods": [ - "*" - ], - "allow_origins": [ - "*" - ] - }, - "host": "localhost", - "port": 8080, - "tls_config": {}, - "workers": 1 - }, - "user_data_collection": { - "feedback_enabled": true, - "feedback_storage": "/tmp/data/feedback", - "transcripts_enabled": false, - "transcripts_storage": "/tmp/data/transcripts" - } - } + "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, - "401": { - "description": "Unauthorized", + "503": { + "description": "Service unavailable", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/UnauthorizedResponse" - }, "examples": { - "missing header": { + "llama stack": { "value": { "detail": { - "cause": "No Authorization header found", - "response": "Missing or invalid credentials provided by client" + "cause": "Connection error while trying to reach backend service.", + "response": "Unable to connect to Llama Stack" } } }, - "missing token": { + "kubernetes api": { "value": { "detail": { - "cause": "No token found in Authorization header", - "response": "Missing or invalid credentials provided by client" + "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", + "response": "Unable to connect to Kubernetes API" } } } + }, + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableResponse" } } } }, - "403": { - "description": "Permission denied", + "422": { + "description": "Validation Error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ForbiddenResponse" - }, - "examples": { - "endpoint": { - "value": { - "detail": { - "cause": "User 6789 is not authorized to access this endpoint.", - "response": "User does not have permission to access this endpoint" - } - } - } + "$ref": "#/components/schemas/HTTPValidationError" } } } + } + } + }, + "delete": { + "tags": [ + "vector-stores" + ], + "summary": "Delete Vector Store", + "description": "Delete a vector store.\n\nParameters:\n request: The incoming HTTP request.\n vector_store_id: ID of the vector store to delete.\n auth: Authentication tuple from the auth dependency.\n\nRaises:\n HTTPException:\n - 401: Authentication failed\n - 403: Authorization failed\n - 404: Vector store not found\n - 500: Lightspeed Stack configuration not loaded\n - 503: Unable to connect to Llama Stack", + "operationId": "delete_vector_store_v1_vector_stores__vector_store_id__delete", + "parameters": [ + { + "name": "vector_store_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Vector Store Id" + } + } + ], + "responses": { + "204": { + "description": "Vector store deleted" }, - "500": { - "description": "Internal server error", + "422": { + "description": "Validation Error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InternalServerErrorResponse" - }, - "examples": { - "configuration": { - "value": { - "detail": { - "cause": "Lightspeed Stack configuration has not been initialized.", - "response": "Configuration is not loaded" - } - } - } + "$ref": "#/components/schemas/HTTPValidationError" } } } @@ -2697,19 +2522,19 @@ } } }, - "/v1/feedback": { + "/v1/files": { "post": { "tags": [ - "feedback" + "vector-stores" ], - "summary": "Feedback Endpoint Handler", - "description": "Handle feedback requests.\n\nProcesses a user feedback submission, storing the feedback and\nreturning a confirmation response.\n\n### Parameters:\n- feedback_request: The request containing feedback information.\n- ensure_feedback_enabled: The feedback handler (FastAPI Depends) that will\n handle feedback status checks.\n- auth: The Authentication handler (FastAPI Depends) that will handle\n authentication Logic.\n\n### Returns:\n- Response indicating the status of the feedback storage request.\n\n### Raises:\n- HTTPException: Returns HTTP 404 if conversation does not exist.\n- HTTPException: Returns HTTP 403 if conversation belongs to a different user.\n- HTTPException: Returns HTTP 500 if feedback storage fails.", - "operationId": "feedback_endpoint_handler_v1_feedback_post", + "summary": "Create File", + "description": "Upload a file.\n\nParameters:\n request: The incoming HTTP request.\n auth: Authentication tuple from the auth dependency.\n file: The file to upload.\n\nReturns:\n FileResponse: The uploaded file object.\n\nRaises:\n HTTPException:\n - 400: Bad request (e.g., file too large, invalid format)\n - 401: Authentication failed\n - 403: Authorization failed\n - 500: Lightspeed Stack configuration not loaded\n - 503: Unable to connect to Llama Stack", + "operationId": "create_file_v1_files_post", "requestBody": { "content": { - "application/json": { + "multipart/form-data": { "schema": { - "$ref": "#/components/schemas/FeedbackRequest" + "$ref": "#/components/schemas/Body_create_file_v1_files_post" } } }, @@ -2721,10 +2546,63 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/FeedbackResponse" + "$ref": "#/components/schemas/FileResponse" }, "example": { - "response": "feedback received" + "bytes": 524288, + "created_at": 1704067200, + "filename": "documentation.pdf", + "id": "file_abc123", + "object": "file", + "purpose": "assistants" + } + } + } + }, + "400": { + "description": "Invalid request format", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestResponse" + }, + "examples": { + "file_upload": { + "value": { + "detail": { + "cause": "File upload rejected: Invalid file format", + "response": "Invalid file upload" + } + } + } + } + } + } + }, + "413": { + "description": "File upload exceeds size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileTooLargeResponse" + }, + "examples": { + "file upload": { + "value": { + "detail": { + "cause": "File size 150000000 bytes exceeds maximum allowed size of 104857600 bytes (100 MB)", + "response": "File too large" + } + } + }, + "backend rejection": { + "value": { + "detail": { + "cause": "File upload rejected by Llama Stack: File size exceeds limit", + "response": "Invalid file upload" + } + } + } } } } @@ -2772,32 +2650,24 @@ "response": "User does not have permission to access this endpoint" } } - }, - "feedback": { - "value": { - "detail": { - "cause": "Storing feedback is disabled.", - "response": "Storing feedback is disabled" - } - } } } } } }, - "404": { - "description": "Resource not found", + "500": { + "description": "Internal server error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NotFoundResponse" + "$ref": "#/components/schemas/InternalServerErrorResponse" }, "examples": { - "conversation": { + "configuration": { "value": { "detail": { - "cause": "Conversation with ID 123e4567-e89b-12d3-a456-426614174000 does not exist", - "response": "Conversation not found" + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" } } } @@ -2805,27 +2675,27 @@ } } }, - "500": { - "description": "Internal server error", + "503": { + "description": "Service unavailable", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InternalServerErrorResponse" + "$ref": "#/components/schemas/ServiceUnavailableResponse" }, "examples": { - "configuration": { + "llama stack": { "value": { "detail": { - "cause": "Lightspeed Stack configuration has not been initialized.", - "response": "Configuration is not loaded" + "cause": "Connection error while trying to reach backend service.", + "response": "Unable to connect to Llama Stack" } } }, - "feedback storage": { + "kubernetes api": { "value": { "detail": { - "cause": "Failed to store feedback at directory: /path/example", - "response": "Failed to store feedback" + "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", + "response": "Unable to connect to Kubernetes API" } } } @@ -2846,49 +2716,34 @@ } } }, - "/v1/feedback/status": { - "get": { + "/v1/vector-stores/{vector_store_id}/files": { + "post": { "tags": [ - "feedback" + "vector-stores" ], - "summary": "Feedback Status", - "description": "Handle feedback status requests.\n\nReturn the current enabled status of the feedback\nfunctionality.\n\n### Parameters:\n- None\n\n### Returns:\n- StatusResponse: Indicates whether feedback collection is enabled.", - "operationId": "feedback_status_v1_feedback_status_get", - "responses": { - "200": { - "description": "Successful response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/StatusResponse" - }, - "example": { - "functionality": "feedback", - "status": { - "enabled": true - } - } - } + "summary": "Add File To Vector Store", + "description": "Add a file to a vector store.\n\nParameters:\n request: The incoming HTTP request.\n vector_store_id: ID of the vector store.\n auth: Authentication tuple from the auth dependency.\n body: File addition parameters.\n\nReturns:\n VectorStoreFileResponse: The vector store file object.\n\nRaises:\n HTTPException:\n - 401: Authentication failed\n - 403: Authorization failed\n - 404: Vector store or file not found\n - 500: Lightspeed Stack configuration not loaded\n - 503: Unable to connect to Llama Stack", + "operationId": "add_file_to_vector_store_v1_vector_stores__vector_store_id__files_post", + "parameters": [ + { + "name": "vector_store_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Vector Store Id" } } - } - }, - "put": { - "tags": [ - "feedback" ], - "summary": "Update Feedback Status", - "description": "Handle feedback status update requests.\n\nTakes a request with the desired state of the feedback status.\nReturns the updated state of the feedback status based on the request's value.\nThese changes are for the life of the service and are on a per-worker basis.\n\n### Parameters:\n- feedback_update_request: Structure containing desired state of the\n feedback status.\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- FeedbackStatusUpdateResponse: Indicates whether feedback is enabled.", - "operationId": "update_feedback_status_v1_feedback_status_put", "requestBody": { + "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/FeedbackStatusUpdateRequest" + "$ref": "#/components/schemas/VectorStoreFileCreateRequest" } } - }, - "required": true + } }, "responses": { "200": { @@ -2896,15 +2751,17 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/FeedbackStatusUpdateResponse" + "$ref": "#/components/schemas/VectorStoreFileResponse" }, "example": { - "status": { - "previous_status": true, - "timestamp": "2023-03-15 12:34:56", - "updated_by": "user/test", - "updated_status": false - } + "attributes": { + "chunk_size": "512", + "indexed": true + }, + "id": "file_abc123", + "object": "vector_store.file", + "status": "completed", + "vector_store_id": "vs_abc123" } } } @@ -2913,9 +2770,6 @@ "description": "Unauthorized", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/UnauthorizedResponse" - }, "examples": { "missing header": { "value": { @@ -2933,6 +2787,9 @@ } } } + }, + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" } } } @@ -2941,9 +2798,6 @@ "description": "Permission denied", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenResponse" - }, "examples": { "endpoint": { "value": { @@ -2953,178 +2807,108 @@ } } } + }, + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" } } } }, - "500": { - "description": "Internal server error", + "404": { + "description": "Resource not found", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/InternalServerErrorResponse" - }, "examples": { - "configuration": { + "file": { "value": { "detail": { - "cause": "Lightspeed Stack configuration has not been initialized.", - "response": "Configuration is not loaded" + "cause": "File with ID file_abc123 does not exist", + "response": "File not found" } } } - } - } - } - }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HTTPValidationError" - } - } - } - } - } - } - }, - "/v1/conversations": { - "get": { - "tags": [ - "conversations_v1" - ], - "summary": "Conversations List Endpoint Handler V1", - "description": "Handle request to retrieve all conversations for the authenticated user.", - "operationId": "get_conversations_list_endpoint_handler_v1_conversations_get", - "responses": { - "200": { - "description": "Successful response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConversationsListResponse" }, - "example": { - "conversations": [ - { - "conversation_id": "123e4567-e89b-12d3-a456-426614174000", - "created_at": "2024-01-01T00:00:00Z", - "last_message_at": "2024-01-01T00:05:00Z", - "last_used_model": "gemini/gemini-2.0-flash", - "last_used_provider": "gemini", - "message_count": 5, - "topic_summary": "Openshift Microservices Deployment Strategies" - }, - { - "conversation_id": "456e7890-e12b-34d5-a678-901234567890", - "created_at": "2024-01-01T01:00:00Z", - "last_used_model": "gemini/gemini-2.5-flash", - "last_used_provider": "gemini", - "message_count": 2, - "topic_summary": "RHDH Purpose Summary" - } - ] + "schema": { + "$ref": "#/components/schemas/NotFoundResponse" } } } }, - "401": { - "description": "Unauthorized", + "500": { + "description": "Internal server error", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/UnauthorizedResponse" - }, "examples": { - "missing header": { - "value": { - "detail": { - "cause": "No Authorization header found", - "response": "Missing or invalid credentials provided by client" - } - } - }, - "missing token": { + "configuration": { "value": { "detail": { - "cause": "No token found in Authorization header", - "response": "Missing or invalid credentials provided by client" + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" } } } + }, + "schema": { + "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, - "403": { - "description": "Permission denied", + "503": { + "description": "Service unavailable", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenResponse" - }, "examples": { - "endpoint": { + "llama stack": { "value": { "detail": { - "cause": "User 6789 is not authorized to access this endpoint.", - "response": "User does not have permission to access this endpoint" + "cause": "Connection error while trying to reach backend service.", + "response": "Unable to connect to Llama Stack" + } + } + }, + "kubernetes api": { + "value": { + "detail": { + "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", + "response": "Unable to connect to Kubernetes API" } } } + }, + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableResponse" } } } }, - "500": { - "description": "Internal server error", + "422": { + "description": "Validation Error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InternalServerErrorResponse" - }, - "examples": { - "configuration": { - "value": { - "detail": { - "cause": "Lightspeed Stack configuration has not been initialized.", - "response": "Configuration is not loaded" - } - } - }, - "database": { - "value": { - "detail": { - "cause": "Failed to query the database", - "response": "Database query failed" - } - } - } + "$ref": "#/components/schemas/HTTPValidationError" } } } } } - } - }, - "/v1/conversations/{conversation_id}": { + }, "get": { "tags": [ - "conversations_v1" + "vector-stores" ], - "summary": "Conversation Get Endpoint Handler V1", - "description": "Handle request to retrieve a conversation identified by ID using Conversations API.\n\nRetrieve a conversation's chat history by its ID using the LlamaStack\nConversations API. This endpoint fetches the conversation items from\nthe backend, simplifies them to essential chat history, and returns\nthem in a structured response. Raises HTTP 400 for invalid IDs, 404\nif not found, 503 if the backend is unavailable, and 500 for\nunexpected errors.\n\nArgs:\n request: The FastAPI request object\n conversation_id: Unique identifier of the conversation to retrieve\n auth: Authentication tuple from dependency\n\nReturns:\n ConversationResponse: Structured response containing the conversation\n ID and simplified chat history", - "operationId": "get_conversation_endpoint_handler_v1_conversations__conversation_id__get", + "summary": "List Vector Store Files", + "description": "List files in a vector store.\n\nParameters:\n request: The incoming HTTP request.\n vector_store_id: ID of the vector store.\n auth: Authentication tuple from the auth dependency.\n\nReturns:\n VectorStoreFilesListResponse: List of files in the vector store.\n\nRaises:\n HTTPException:\n - 401: Authentication failed\n - 403: Authorization failed\n - 404: Vector store not found\n - 500: Lightspeed Stack configuration not loaded\n - 503: Unable to connect to Llama Stack", + "operationId": "list_vector_store_files_v1_vector_stores__vector_store_id__files_get", "parameters": [ { - "name": "conversation_id", + "name": "vector_store_id", "in": "path", "required": true, "schema": { "type": "string", - "title": "Conversation Id" + "title": "Vector Store Id" } } ], @@ -3134,50 +2918,27 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConversationResponse" + "$ref": "#/components/schemas/VectorStoreFilesListResponse" }, "example": { - "chat_history": [ + "data": [ { - "completed_at": "2024-01-01T00:01:05Z", - "messages": [ - { - "content": "Hello", - "type": "user" - }, - { - "content": "Hi there!", - "type": "assistant" - } - ], - "model": "gpt-4o-mini", - "provider": "openai", - "started_at": "2024-01-01T00:01:00Z", - "tool_calls": [], - "tool_results": [] + "attributes": { + "chunk_size": "512" + }, + "id": "file_abc123", + "object": "vector_store.file", + "status": "completed", + "vector_store_id": "vs_abc123" + }, + { + "id": "file_def456", + "object": "vector_store.file", + "status": "processing", + "vector_store_id": "vs_abc123" } ], - "conversation_id": "123e4567-e89b-12d3-a456-426614174000" - } - } - } - }, - "400": { - "description": "Invalid request format", - "content": { - "application/json": { - "examples": { - "conversation_id": { - "value": { - "detail": { - "cause": "The conversation ID 123e4567-e89b-12d3-a456-426614174000 has invalid format.", - "response": "Invalid conversation ID format" - } - } - } - }, - "schema": { - "$ref": "#/components/schemas/BadRequestResponse" + "object": "list" } } } @@ -3215,14 +2976,6 @@ "content": { "application/json": { "examples": { - "conversation read": { - "value": { - "detail": { - "cause": "User 6789 does not have permission to read conversation with ID 123e4567-e89b-12d3-a456-426614174000", - "response": "User does not have permission to perform this action" - } - } - }, "endpoint": { "value": { "detail": { @@ -3243,11 +2996,11 @@ "content": { "application/json": { "examples": { - "conversation": { + "vector store": { "value": { "detail": { - "cause": "Conversation with ID 123e4567-e89b-12d3-a456-426614174000 does not exist", - "response": "Conversation not found" + "cause": "Vector Store with ID vs_abc123 does not exist", + "response": "Vector Store not found" } } } @@ -3270,14 +3023,6 @@ "response": "Configuration is not loaded" } } - }, - "database": { - "value": { - "detail": { - "cause": "Failed to query the database", - "response": "Database query failed" - } - } } }, "schema": { @@ -3325,22 +3070,33 @@ } } } - }, - "delete": { + } + }, + "/v1/vector-stores/{vector_store_id}/files/{file_id}": { + "get": { "tags": [ - "conversations_v1" + "vector-stores" ], - "summary": "Conversation Delete Endpoint Handler V1", - "description": "Handle request to delete a conversation by ID using Conversations API.\n\nValidates the conversation ID format and attempts to delete the\nconversation from the Llama Stack backend using the Conversations API.\nRaises HTTP errors for invalid IDs, not found conversations, connection\nissues, or unexpected failures.\n\nArgs:\n request: The FastAPI request object\n conversation_id: Unique identifier of the conversation to delete\n auth: Authentication tuple from dependency\n\nReturns:\n ConversationDeleteResponse: Response indicating the result of the deletion operation", - "operationId": "delete_conversation_endpoint_handler_v1_conversations__conversation_id__delete", + "summary": "Get Vector Store File", + "description": "Retrieve a file from a vector store.\n\nParameters:\n request: The incoming HTTP request.\n vector_store_id: ID of the vector store.\n file_id: ID of the file.\n auth: Authentication tuple from the auth dependency.\n\nReturns:\n VectorStoreFileResponse: The vector store file object.\n\nRaises:\n HTTPException:\n - 401: Authentication failed\n - 403: Authorization failed\n - 404: File not found in vector store\n - 500: Lightspeed Stack configuration not loaded\n - 503: Unable to connect to Llama Stack", + "operationId": "get_vector_store_file_v1_vector_stores__vector_store_id__files__file_id__get", "parameters": [ { - "name": "conversation_id", + "name": "vector_store_id", "in": "path", "required": true, "schema": { "type": "string", - "title": "Conversation Id" + "title": "Vector Store Id" + } + }, + { + "name": "file_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "File Id" } } ], @@ -3350,43 +3106,17 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConversationDeleteResponse" + "$ref": "#/components/schemas/VectorStoreFileResponse" }, - "examples": { - "deleted": { - "value": { - "conversation_id": "123e4567-e89b-12d3-a456-426614174000", - "response": "Conversation deleted successfully", - "success": true - } + "example": { + "attributes": { + "chunk_size": "512", + "indexed": true }, - "not found": { - "value": { - "conversation_id": "123e4567-e89b-12d3-a456-426614174000", - "response": "Conversation can not be deleted", - "success": true - } - } - } - } - } - }, - "400": { - "description": "Invalid request format", - "content": { - "application/json": { - "examples": { - "conversation_id": { - "value": { - "detail": { - "cause": "The conversation ID 123e4567-e89b-12d3-a456-426614174000 has invalid format.", - "response": "Invalid conversation ID format" - } - } - } - }, - "schema": { - "$ref": "#/components/schemas/BadRequestResponse" + "id": "file_abc123", + "object": "vector_store.file", + "status": "completed", + "vector_store_id": "vs_abc123" } } } @@ -3424,14 +3154,6 @@ "content": { "application/json": { "examples": { - "conversation delete": { - "value": { - "detail": { - "cause": "User 6789 does not have permission to delete conversation with ID 123e4567-e89b-12d3-a456-426614174000", - "response": "User does not have permission to perform this action" - } - } - }, "endpoint": { "value": { "detail": { @@ -3447,6 +3169,26 @@ } } }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "examples": { + "file": { + "value": { + "detail": { + "cause": "File with ID file_abc123 does not exist", + "response": "File not found" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/NotFoundResponse" + } + } + } + }, "500": { "description": "Internal server error", "content": { @@ -3459,14 +3201,6 @@ "response": "Configuration is not loaded" } } - }, - "database": { - "value": { - "detail": { - "cause": "Failed to query the database", - "response": "Database query failed" - } - } } }, "schema": { @@ -3515,33 +3249,67 @@ } } }, - "put": { + "delete": { "tags": [ - "conversations_v1" + "vector-stores" ], - "summary": "Conversation Update Endpoint Handler V1", - "description": "Handle request to update a conversation metadata using Conversations API.\n\nUpdates the conversation metadata (including topic summary) in both the\nLlamaStack backend using the Conversations API and the local database.\n\nArgs:\n request: The FastAPI request object\n conversation_id: Unique identifier of the conversation to update\n update_request: Request containing the topic summary to update\n auth: Authentication tuple from dependency\n\nReturns:\n ConversationUpdateResponse: Response indicating the result of the update operation", - "operationId": "update_conversation_endpoint_handler_v1_conversations__conversation_id__put", + "summary": "Delete Vector Store File", + "description": "Delete a file from a vector store.\n\nParameters:\n request: The incoming HTTP request.\n vector_store_id: ID of the vector store.\n file_id: ID of the file to delete.\n auth: Authentication tuple from the auth dependency.\n\nRaises:\n HTTPException:\n - 401: Authentication failed\n - 403: Authorization failed\n - 404: File not found in vector store\n - 500: Lightspeed Stack configuration not loaded\n - 503: Unable to connect to Llama Stack", + "operationId": "delete_vector_store_file_v1_vector_stores__vector_store_id__files__file_id__delete", "parameters": [ { - "name": "conversation_id", + "name": "vector_store_id", "in": "path", "required": true, "schema": { "type": "string", - "title": "Conversation Id" + "title": "Vector Store Id" + } + }, + { + "name": "file_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "File Id" + } + } + ], + "responses": { + "204": { + "description": "File deleted from vector store" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } } } + } + } + }, + "/v1/query": { + "post": { + "tags": [ + "query" ], + "summary": "Query Endpoint Handler", + "description": "Handle request to the /query endpoint using Responses API.\n\nProcesses a POST request to a query endpoint, forwarding the\nuser's query to a selected Llama Stack LLM and returning the generated response.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- query_request: Request to the LLM.\n- auth: Auth context tuple resolved from the authentication dependency.\n- mcp_headers: Headers that should be pass to MCP servers.\n\n### Returns:\n- QueryResponse: Contains the conversation ID and the LLM-generated response.\n\n### Raises:\n- HTTPException:\n- 401: Unauthorized - Missing or invalid credentials\n- 403: Forbidden - Insufficient permissions or model override not allowed\n- 404: Not Found - Conversation, model, or provider not found\n- 413: Prompt too long - Prompt exceeded model's context window size\n- 422: Unprocessable Entity - Request validation failed\n- 429: Quota limit exceeded - The token quota for model or user has been exceeded\n- 500: Internal Server Error - Configuration not loaded or other server errors\n- 503: Service Unavailable - Unable to connect to Llama Stack backend", + "operationId": "query_endpoint_handler_v1_query_post", "requestBody": { - "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConversationUpdateRequest" + "$ref": "#/components/schemas/QueryRequest" } } - } + }, + "required": true }, "responses": { "200": { @@ -3549,32 +3317,41 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConversationUpdateResponse" + "$ref": "#/components/schemas/QueryResponse" }, "example": { + "available_quotas": { + "ClusterQuotaLimiter": 998911, + "UserQuotaLimiter": 998911 + }, "conversation_id": "123e4567-e89b-12d3-a456-426614174000", - "message": "Topic summary updated successfully", - "success": true - } - } - } - }, - "400": { - "description": "Invalid request format", - "content": { - "application/json": { - "examples": { - "conversation_id": { - "value": { - "detail": { - "cause": "The conversation ID 123e4567-e89b-12d3-a456-426614174000 has invalid format.", - "response": "Invalid conversation ID format" - } + "input_tokens": 123, + "output_tokens": 456, + "referenced_documents": [ + { + "doc_title": "Operator Lifecycle Manager concepts and resources", + "doc_url": "https://docs.openshift.com/container-platform/4.15/operators/understanding/olm/olm-understanding-olm.html" } - } - }, - "schema": { - "$ref": "#/components/schemas/BadRequestResponse" + ], + "response": "Operator Lifecycle Manager (OLM) helps users install...", + "tool_calls": [ + { + "args": {}, + "id": "1", + "name": "tool1", + "type": "tool_call" + } + ], + "tool_results": [ + { + "content": "bla", + "id": "1", + "round": 1, + "status": "success", + "type": "tool_result" + } + ], + "truncated": false } } } @@ -3583,6 +3360,9 @@ "description": "Unauthorized", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + }, "examples": { "missing header": { "value": { @@ -3600,9 +3380,6 @@ } } } - }, - "schema": { - "$ref": "#/components/schemas/UnauthorizedResponse" } } } @@ -3611,7 +3388,18 @@ "description": "Permission denied", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + }, "examples": { + "conversation read": { + "value": { + "detail": { + "cause": "User 6789 does not have permission to read conversation with ID 123e4567-e89b-12d3-a456-426614174000", + "response": "User does not have permission to perform this action" + } + } + }, "endpoint": { "value": { "detail": { @@ -3619,10 +3407,15 @@ "response": "User does not have permission to access this endpoint" } } + }, + "model override": { + "value": { + "detail": { + "cause": "User lacks model_override permission required to override model/provider.", + "response": "This instance does not permit overriding model/provider in the query request (missing permission: MODEL_OVERRIDE). Please remove the model and provider fields from your request." + } + } } - }, - "schema": { - "$ref": "#/components/schemas/ForbiddenResponse" } } } @@ -3631,6 +3424,9 @@ "description": "Resource not found", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundResponse" + }, "examples": { "conversation": { "value": { @@ -3639,132 +3435,124 @@ "response": "Conversation not found" } } - } - }, - "schema": { - "$ref": "#/components/schemas/NotFoundResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "examples": { - "configuration": { + }, + "provider": { "value": { "detail": { - "cause": "Lightspeed Stack configuration has not been initialized.", - "response": "Configuration is not loaded" + "cause": "Provider with ID openai does not exist", + "response": "Provider not found" } } }, - "database": { + "model": { "value": { "detail": { - "cause": "Failed to query the database", - "response": "Database query failed" + "cause": "Model with ID gpt-4-turbo is not configured", + "response": "Model not found" } } } - }, - "schema": { - "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, - "503": { - "description": "Service unavailable", + "422": { + "description": "Request validation failed", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableEntityResponse" + }, "examples": { - "llama stack": { + "invalid format": { "value": { "detail": { - "cause": "Connection error while trying to reach backend service.", - "response": "Unable to connect to Llama Stack" + "cause": "Invalid request format. The request body could not be parsed.", + "response": "Invalid request format" } } }, - "kubernetes api": { + "missing attributes": { "value": { "detail": { - "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", - "response": "Unable to connect to Kubernetes API" + "cause": "Missing required attributes: ['query', 'model', 'provider']", + "response": "Missing required attributes" } } - } - }, - "schema": { - "$ref": "#/components/schemas/ServiceUnavailableResponse" - } - } - } - }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HTTPValidationError" - } - } - } - } - } - } - }, - "/v2/conversations": { - "get": { - "tags": [ - "conversations_v2" - ], - "summary": "Get Conversations List Endpoint Handler", - "description": "Handle request to retrieve all conversations for the authenticated user.", - "operationId": "get_conversations_list_endpoint_handler_v2_conversations_get", - "responses": { - "200": { - "description": "Successful response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConversationsListResponseV2" - }, - "example": { - "conversations": [ - { - "conversation_id": "123e4567-e89b-12d3-a456-426614174000", - "last_message_timestamp": 1704067200.0, - "topic_summary": "Openshift Microservices Deployment Strategies" + }, + "invalid value": { + "value": { + "detail": { + "cause": "Invalid attachment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']", + "response": "Invalid attribute value" + } } - ] + } } } } }, - "401": { - "description": "Unauthorized", + "429": { + "description": "Quota limit exceeded", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnauthorizedResponse" + "$ref": "#/components/schemas/QuotaExceededResponse" }, "examples": { - "missing header": { + "model": { "value": { "detail": { - "cause": "No Authorization header found", - "response": "Missing or invalid credentials provided by client" + "cause": "The token quota for model gpt-4-turbo has been exceeded.", + "response": "The model quota has been exceeded" } } }, - "missing token": { + "user none": { "value": { "detail": { - "cause": "No token found in Authorization header", - "response": "Missing or invalid credentials provided by client" + "cause": "User 123 has no available tokens.", + "response": "The quota has been exceeded" + } + } + }, + "cluster none": { + "value": { + "detail": { + "cause": "Cluster has no available tokens.", + "response": "The quota has been exceeded" + } + } + }, + "subject none": { + "value": { + "detail": { + "cause": "Unknown subject 999 has no available tokens.", + "response": "The quota has been exceeded" + } + } + }, + "user insufficient": { + "value": { + "detail": { + "cause": "User 123 has 5 tokens, but 10 tokens are needed.", + "response": "The quota has been exceeded" + } + } + }, + "cluster insufficient": { + "value": { + "detail": { + "cause": "Cluster has 500 tokens, but 900 tokens are needed.", + "response": "The quota has been exceeded" + } + } + }, + "subject insufficient": { + "value": { + "detail": { + "cause": "Unknown subject 999 has 3 tokens, but 6 tokens are needed.", + "response": "The quota has been exceeded" } } } @@ -3772,19 +3560,19 @@ } } }, - "403": { - "description": "Permission denied", + "500": { + "description": "Internal server error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ForbiddenResponse" + "$ref": "#/components/schemas/InternalServerErrorResponse" }, "examples": { - "endpoint": { + "configuration": { "value": { "detail": { - "cause": "User 6789 is not authorized to access this endpoint.", - "response": "User does not have permission to access this endpoint" + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" } } } @@ -3792,27 +3580,27 @@ } } }, - "500": { - "description": "Internal server error", + "503": { + "description": "Service unavailable", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InternalServerErrorResponse" + "$ref": "#/components/schemas/ServiceUnavailableResponse" }, "examples": { - "configuration": { + "llama stack": { "value": { "detail": { - "cause": "Lightspeed Stack configuration has not been initialized.", - "response": "Configuration is not loaded" + "cause": "Connection error while trying to reach backend service.", + "response": "Unable to connect to Llama Stack" } } }, - "conversation cache": { + "kubernetes api": { "value": { "detail": { - "cause": "Conversation cache is not configured or unavailable.", - "response": "Conversation cache not configured" + "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", + "response": "Unable to connect to Kubernetes API" } } } @@ -3823,76 +3611,34 @@ } } }, - "/v2/conversations/{conversation_id}": { - "get": { + "/v1/streaming_query": { + "post": { "tags": [ - "conversations_v2" + "streaming_query" ], - "summary": "Get Conversation Endpoint Handler", - "description": "Handle request to retrieve a conversation identified by its ID.", - "operationId": "get_conversation_endpoint_handler_v2_conversations__conversation_id__get", - "parameters": [ - { - "name": "conversation_id", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Conversation Id" + "summary": "Streaming Query Endpoint Handler", + "description": "Handle request to the /streaming_query endpoint using Responses API.\n\nReturns a streaming response using Server-Sent Events (SSE) format with\ncontent type text/event-stream.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- query_request: Request to the LLM.\n- auth: Auth context tuple resolved from the authentication dependency.\n- mcp_headers: Headers that should be passed to MCP servers.\n\n### Returns:\n- SSE-formatted events for the query lifecycle.\n\n### Raises:\n- HTTPException:\n- 401: Unauthorized - Missing or invalid credentials\n- 403: Forbidden - Insufficient permissions or model override not allowed\n- 404: Not Found - Conversation, model, or provider not found\n- 413: Prompt too long - Prompt exceeded model's context window size\n- 422: Unprocessable Entity - Request validation failed\n- 429: Quota limit exceeded - The token quota for model or user has been exceeded\n- 500: Internal Server Error - Configuration not loaded or other server errors\n- 503: Service Unavailable - Unable to connect to Llama Stack backend", + "operationId": "streaming_query_endpoint_handler_v1_streaming_query_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryRequest" + } } - } - ], + }, + "required": true + }, "responses": { "200": { "description": "Successful response", "content": { - "application/json": { + "text/event-stream": { "schema": { - "$ref": "#/components/schemas/ConversationResponse" - }, - "example": { - "chat_history": [ - { - "completed_at": "2024-01-01T00:01:05Z", - "messages": [ - { - "content": "Hello", - "type": "user" - }, - { - "content": "Hi there!", - "type": "assistant" - } - ], - "model": "gpt-4o-mini", - "provider": "openai", - "started_at": "2024-01-01T00:01:00Z", - "tool_calls": [], - "tool_results": [] - } - ], - "conversation_id": "123e4567-e89b-12d3-a456-426614174000" - } - } - } - }, - "400": { - "description": "Invalid request format", - "content": { - "application/json": { - "examples": { - "conversation_id": { - "value": { - "detail": { - "cause": "The conversation ID 123e4567-e89b-12d3-a456-426614174000 has invalid format.", - "response": "Invalid conversation ID format" - } - } - } + "type": "string", + "format": "text/event-stream" }, - "schema": { - "$ref": "#/components/schemas/BadRequestResponse" - } + "example": "data: {\"event\": \"start\", \"data\": {\"conversation_id\": \"123e4567-e89b-12d3-a456-426614174000\", \"request_id\": \"123e4567-e89b-12d3-a456-426614174001\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 0, \"token\": \"No Violation\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 1, \"token\": \"\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 2, \"token\": \"Hello\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 3, \"token\": \"!\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 4, \"token\": \" How\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 5, \"token\": \" can\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 6, \"token\": \" I\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 7, \"token\": \" assist\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 8, \"token\": \" you\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 9, \"token\": \" today\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 10, \"token\": \"?\"}}\n\ndata: {\"event\": \"turn_complete\", \"data\": {\"token\": \"Hello! How can I assist you today?\"}}\n\ndata: {\"event\": \"end\", \"data\": {\"referenced_documents\": [], \"truncated\": null, \"input_tokens\": 11, \"output_tokens\": 19}, \"available_quotas\": {}}\n\n" } } }, @@ -3900,6 +3646,9 @@ "description": "Unauthorized", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + }, "examples": { "missing header": { "value": { @@ -3917,9 +3666,6 @@ } } } - }, - "schema": { - "$ref": "#/components/schemas/UnauthorizedResponse" } } } @@ -3928,7 +3674,18 @@ "description": "Permission denied", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + }, "examples": { + "conversation read": { + "value": { + "detail": { + "cause": "User 6789 does not have permission to read conversation with ID 123e4567-e89b-12d3-a456-426614174000", + "response": "User does not have permission to perform this action" + } + } + }, "endpoint": { "value": { "detail": { @@ -3936,10 +3693,15 @@ "response": "User does not have permission to access this endpoint" } } + }, + "model override": { + "value": { + "detail": { + "cause": "User lacks model_override permission required to override model/provider.", + "response": "This instance does not permit overriding model/provider in the query request (missing permission: MODEL_OVERRIDE). Please remove the model and provider fields from your request." + } + } } - }, - "schema": { - "$ref": "#/components/schemas/ForbiddenResponse" } } } @@ -3948,6 +3710,9 @@ "description": "Resource not found", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundResponse" + }, "examples": { "conversation": { "value": { @@ -3956,115 +3721,212 @@ "response": "Conversation not found" } } - } - }, - "schema": { - "$ref": "#/components/schemas/NotFoundResponse" + }, + "provider": { + "value": { + "detail": { + "cause": "Provider with ID openai does not exist", + "response": "Provider not found" + } + } + }, + "model": { + "value": { + "detail": { + "cause": "Model with ID gpt-4-turbo is not configured", + "response": "Model not found" + } + } + } } } } }, - "500": { - "description": "Internal server error", + "422": { + "description": "Request validation failed", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableEntityResponse" + }, "examples": { - "configuration": { + "invalid format": { "value": { "detail": { - "cause": "Lightspeed Stack configuration has not been initialized.", - "response": "Configuration is not loaded" + "cause": "Invalid request format. The request body could not be parsed.", + "response": "Invalid request format" } } }, - "conversation cache": { + "missing attributes": { "value": { "detail": { - "cause": "Conversation cache is not configured or unavailable.", - "response": "Conversation cache not configured" + "cause": "Missing required attributes: ['query', 'model', 'provider']", + "response": "Missing required attributes" + } + } + }, + "invalid value": { + "value": { + "detail": { + "cause": "Invalid attachment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']", + "response": "Invalid attribute value" } } } - }, - "schema": { - "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, - "422": { - "description": "Validation Error", + "429": { + "description": "Quota limit exceeded", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/HTTPValidationError" + "$ref": "#/components/schemas/QuotaExceededResponse" + }, + "examples": { + "model": { + "value": { + "detail": { + "cause": "The token quota for model gpt-4-turbo has been exceeded.", + "response": "The model quota has been exceeded" + } + } + }, + "user none": { + "value": { + "detail": { + "cause": "User 123 has no available tokens.", + "response": "The quota has been exceeded" + } + } + }, + "cluster none": { + "value": { + "detail": { + "cause": "Cluster has no available tokens.", + "response": "The quota has been exceeded" + } + } + }, + "subject none": { + "value": { + "detail": { + "cause": "Unknown subject 999 has no available tokens.", + "response": "The quota has been exceeded" + } + } + }, + "user insufficient": { + "value": { + "detail": { + "cause": "User 123 has 5 tokens, but 10 tokens are needed.", + "response": "The quota has been exceeded" + } + } + }, + "cluster insufficient": { + "value": { + "detail": { + "cause": "Cluster has 500 tokens, but 900 tokens are needed.", + "response": "The quota has been exceeded" + } + } + }, + "subject insufficient": { + "value": { + "detail": { + "cause": "Unknown subject 999 has 3 tokens, but 6 tokens are needed.", + "response": "The quota has been exceeded" + } + } + } } } } - } - } - }, - "delete": { - "tags": [ - "conversations_v2" - ], - "summary": "Delete Conversation Endpoint Handler", - "description": "Handle request to delete a conversation by ID.", - "operationId": "delete_conversation_endpoint_handler_v2_conversations__conversation_id__delete", - "parameters": [ - { - "name": "conversation_id", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Conversation Id" - } - } - ], - "responses": { - "200": { - "description": "Successful response", + }, + "500": { + "description": "Internal server error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConversationDeleteResponse" + "$ref": "#/components/schemas/InternalServerErrorResponse" }, "examples": { - "deleted": { - "value": { - "conversation_id": "123e4567-e89b-12d3-a456-426614174000", - "response": "Conversation deleted successfully", - "success": true - } - }, - "not found": { + "configuration": { "value": { - "conversation_id": "123e4567-e89b-12d3-a456-426614174000", - "response": "Conversation can not be deleted", - "success": true + "detail": { + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" + } } } } } } }, - "400": { - "description": "Invalid request format", + "503": { + "description": "Service unavailable", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableResponse" + }, "examples": { - "conversation_id": { + "llama stack": { "value": { "detail": { - "cause": "The conversation ID 123e4567-e89b-12d3-a456-426614174000 has invalid format.", - "response": "Invalid conversation ID format" + "cause": "Connection error while trying to reach backend service.", + "response": "Unable to connect to Llama Stack" + } + } + }, + "kubernetes api": { + "value": { + "detail": { + "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", + "response": "Unable to connect to Kubernetes API" } } } - }, + } + } + } + } + } + } + }, + "/v1/streaming_query/interrupt": { + "post": { + "tags": [ + "streaming_query_interrupt" + ], + "summary": "Streaming Query Interrupt Endpoint Handler", + "description": "Interrupt an in-progress streaming query by request identifier.\n\n### Parameters:\n- interrupt_request: Request payload containing the stream request ID.\n- auth: Auth context tuple resolved from the authentication dependency.\n- registry: Stream interrupt registry dependency used to cancel streams.\n\n### Returns:\n- StreamingInterruptResponse: Confirmation payload when interruption succeeds.\n\n### Raises:\n- HTTPException: If no active stream for the given request ID can be interrupted.", + "operationId": "stream_interrupt_endpoint_handler_v1_streaming_query_interrupt_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StreamingInterruptRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { "schema": { - "$ref": "#/components/schemas/BadRequestResponse" + "$ref": "#/components/schemas/StreamingInterruptResponse" + }, + "example": { + "interrupted": true, + "message": "Streaming request interrupted", + "request_id": "123e4567-e89b-12d3-a456-426614174000" } } } @@ -4073,6 +3935,9 @@ "description": "Unauthorized", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + }, "examples": { "missing header": { "value": { @@ -4090,9 +3955,6 @@ } } } - }, - "schema": { - "$ref": "#/components/schemas/UnauthorizedResponse" } } } @@ -4101,6 +3963,9 @@ "description": "Permission denied", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + }, "examples": { "endpoint": { "value": { @@ -4110,37 +3975,26 @@ } } } - }, - "schema": { - "$ref": "#/components/schemas/ForbiddenResponse" } } } }, - "500": { - "description": "Internal server error", + "404": { + "description": "Resource not found", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundResponse" + }, "examples": { - "configuration": { - "value": { - "detail": { - "cause": "Lightspeed Stack configuration has not been initialized.", - "response": "Configuration is not loaded" - } - } - }, - "conversation cache": { + "streaming request": { "value": { "detail": { - "cause": "Conversation cache is not configured or unavailable.", - "response": "Conversation cache not configured" + "cause": "Streaming Request with ID 123e4567-e89b-12d3-a456-426614174000 does not exist", + "response": "Streaming Request not found" } } } - }, - "schema": { - "$ref": "#/components/schemas/InternalServerErrorResponse" } } } @@ -4156,67 +4010,92 @@ } } } - }, - "put": { - "tags": [ - "conversations_v2" - ], - "summary": "Update Conversation Endpoint Handler", - "description": "Handle request to update a conversation topic summary by ID.", - "operationId": "update_conversation_endpoint_handler_v2_conversations__conversation_id__put", - "parameters": [ - { - "name": "conversation_id", - "in": "path", - "required": true, - "schema": { - "type": "string", - "title": "Conversation Id" - } - } + } + }, + "/v1/config": { + "get": { + "tags": [ + "config" ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConversationUpdateRequest" - } - } - } - }, + "summary": "Config Endpoint Handler", + "description": "Handle requests to the /config endpoint.\n\nProcess GET requests to the /config endpoint and returns the\ncurrent service configuration.\n\nEnsures the application configuration is loaded before returning it.\n\n### Parameters:\n- request: The incoming HTTP request.\n- auth: Authentication tuple from the auth dependency.\n\n### Returns:\n- ConfigurationResponse: The loaded service configuration response.", + "operationId": "config_endpoint_handler_v1_config_get", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConversationUpdateResponse" + "$ref": "#/components/schemas/ConfigurationResponse" }, "example": { - "conversation_id": "123e4567-e89b-12d3-a456-426614174000", - "message": "Topic summary updated successfully", - "success": true - } - } - } - }, - "400": { - "description": "Invalid request format", - "content": { - "application/json": { - "examples": { - "conversation_id": { - "value": { - "detail": { - "cause": "The conversation ID 123e4567-e89b-12d3-a456-426614174000 has invalid format.", - "response": "Invalid conversation ID format" + "configuration": { + "authentication": { + "module": "noop", + "skip_tls_verification": false + }, + "authorization": { + "access_rules": [] + }, + "byok_rag": [], + "conversation_cache": {}, + "database": { + "sqlite": { + "db_path": "/tmp/lightspeed-stack.db" + } + }, + "inference": { + "default_model": "gpt-4-turbo", + "default_provider": "openai" + }, + "llama_stack": { + "api_key": "*****", + "url": "http://localhost:8321", + "use_as_library_client": false + }, + "mcp_servers": [ + { + "name": "server1", + "provider_id": "provider1", + "url": "http://url.com:1" + } + ], + "name": "lightspeed-stack", + "quota_handlers": { + "enable_token_history": false, + "limiters": [], + "scheduler": { + "period": 1 } + }, + "service": { + "access_log": true, + "auth_enabled": false, + "color_log": true, + "cors": { + "allow_credentials": false, + "allow_headers": [ + "*" + ], + "allow_methods": [ + "*" + ], + "allow_origins": [ + "*" + ] + }, + "host": "localhost", + "port": 8080, + "tls_config": {}, + "workers": 1 + }, + "user_data_collection": { + "feedback_enabled": true, + "feedback_storage": "/tmp/data/feedback", + "transcripts_enabled": false, + "transcripts_storage": "/tmp/data/transcripts" } } - }, - "schema": { - "$ref": "#/components/schemas/BadRequestResponse" } } } @@ -4225,6 +4104,9 @@ "description": "Unauthorized", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + }, "examples": { "missing header": { "value": { @@ -4242,9 +4124,6 @@ } } } - }, - "schema": { - "$ref": "#/components/schemas/UnauthorizedResponse" } } } @@ -4253,6 +4132,9 @@ "description": "Permission denied", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + }, "examples": { "endpoint": { "value": { @@ -4262,29 +4144,6 @@ } } } - }, - "schema": { - "$ref": "#/components/schemas/ForbiddenResponse" - } - } - } - }, - "404": { - "description": "Resource not found", - "content": { - "application/json": { - "examples": { - "conversation": { - "value": { - "detail": { - "cause": "Conversation with ID 123e4567-e89b-12d3-a456-426614174000 does not exist", - "response": "Conversation not found" - } - } - } - }, - "schema": { - "$ref": "#/components/schemas/NotFoundResponse" } } } @@ -4293,6 +4152,9 @@ "description": "Internal server error", "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalServerErrorResponse" + }, "examples": { "configuration": { "value": { @@ -4301,28 +4163,7 @@ "response": "Configuration is not loaded" } } - }, - "conversation cache": { - "value": { - "detail": { - "cause": "Conversation cache is not configured or unavailable.", - "response": "Conversation cache not configured" - } - } } - }, - "schema": { - "$ref": "#/components/schemas/InternalServerErrorResponse" - } - } - } - }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HTTPValidationError" } } } @@ -4330,19 +4171,19 @@ } } }, - "/v1/responses": { + "/v1/feedback": { "post": { "tags": [ - "responses" + "feedback" ], - "summary": "Responses Endpoint Handler", - "description": "Handle request to the /responses endpoint using Responses API (LCORE specification).\n\nProcesses a POST request to the responses endpoint, forwarding the\nuser's request to a selected Llama Stack LLM and returning the generated response\nfollowing the LCORE OpenAPI specification.\n\nReturns:\n ResponsesResponse: Contains the response following LCORE specification (non-streaming).\n StreamingResponse: SSE-formatted streaming response with enriched events (streaming).\n - response.created event includes conversation attribute\n - response.completed event includes available_quotas attribute\n\nRaises:\n HTTPException:\n - 401: Unauthorized - Missing or invalid credentials\n - 403: Forbidden - Insufficient permissions or model override not allowed\n - 404: Not Found - Conversation, model, or provider not found\n - 413: Prompt too long - Prompt exceeded model's context window size\n - 422: Unprocessable Entity - Request validation failed\n - 429: Quota limit exceeded - The token quota for model or user has been exceeded\n - 500: Internal Server Error - Configuration not loaded or other server errors\n - 503: Service Unavailable - Unable to connect to Llama Stack backend", - "operationId": "responses_endpoint_handler_v1_responses_post", + "summary": "Feedback Endpoint Handler", + "description": "Handle feedback requests.\n\nProcesses a user feedback submission, storing the feedback and\nreturning a confirmation response.\n\n### Parameters:\n- feedback_request: The request containing feedback information.\n- ensure_feedback_enabled: The feedback handler (FastAPI Depends) that will\n handle feedback status checks.\n- auth: The Authentication handler (FastAPI Depends) that will handle\n authentication Logic.\n\n### Returns:\n- Response indicating the status of the feedback storage request.\n\n### Raises:\n- HTTPException: Returns HTTP 404 if conversation does not exist.\n- HTTPException: Returns HTTP 403 if conversation belongs to a different user.\n- HTTPException: Returns HTTP 500 if feedback storage fails.", + "operationId": "feedback_endpoint_handler_v1_feedback_post", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ResponsesRequest" + "$ref": "#/components/schemas/FeedbackRequest" } } }, @@ -4354,61 +4195,11 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ResponsesResponse" + "$ref": "#/components/schemas/FeedbackResponse" }, "example": { - "available_quotas": { - "daily": 1000, - "monthly": 50000 - }, - "completed_at": 1704067250, - "conversation": "0d21ba731f21f798dc9680125d5d6f493e4a7ab79f25670e", - "created_at": 1704067200, - "id": "resp_abc123", - "instructions": "You are a helpful assistant", - "model": "openai/gpt-4-turbo", - "object": "response", - "output": [ - { - "content": [ - { - "text": "Kubernetes is an open-source container orchestration system...", - "type": "output_text" - } - ], - "role": "assistant", - "type": "message" - } - ], - "output_text": "Kubernetes is an open-source container orchestration system...", - "parallel_tool_calls": true, - "status": "completed", - "store": true, - "temperature": 0.7, - "text": { - "format": { - "type": "text" - } - }, - "usage": { - "input_tokens": 100, - "input_tokens_details": { - "cached_tokens": 0 - }, - "output_tokens": 50, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 150 - } + "response": "feedback received" } - }, - "text/event-stream": { - "schema": { - "type": "string" - }, - "example": "event: response.created\ndata: {\"type\":\"response.created\",\"sequence_number\":0,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"in_progress\",\"model\":\"openai/gpt-4o-mini\",\"output\":[],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{},\"output_text\":\"\"}}\n\nevent: response.output_item.added\ndata: {\"type\":\"response.output_item.added\",\"sequence_number\":1,\"response_id\":\"resp_abc\",\"output_index\":0,\"item\":{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"in_progress\",\"role\":\"assistant\",\"content\":[]}}\n\n...\n\nevent: response.completed\ndata: {\"type\":\"response.completed\",\"sequence_number\":30,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"completed\",\"model\":\"openai/gpt-4o-mini\",\"output\":[{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello! How can I help?\",\"annotations\":[]}]}],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"usage\":{\"input_tokens\":10,\"output_tokens\":6,\"total_tokens\":16,\"input_tokens_details\":{\"cached_tokens\":0},\"output_tokens_details\":{\"reasoning_tokens\":0}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{\"daily\":1000,\"monthly\":50000},\"output_text\":\"Hello! How can I help?\"}}\n\ndata: [DONE]\n\n", - "description": "SSE stream of events" } } }, @@ -4448,14 +4239,6 @@ "$ref": "#/components/schemas/ForbiddenResponse" }, "examples": { - "conversation read": { - "value": { - "detail": { - "cause": "User 6789 does not have permission to read conversation with ID 123e4567-e89b-12d3-a456-426614174000", - "response": "User does not have permission to perform this action" - } - } - }, "endpoint": { "value": { "detail": { @@ -4464,11 +4247,11 @@ } } }, - "model override": { + "feedback": { "value": { "detail": { - "cause": "User lacks model_override permission required to override model/provider.", - "response": "This instance does not permit overriding model/provider in the query request (missing permission: MODEL_OVERRIDE). Please remove the model and provider fields from your request." + "cause": "Storing feedback is disabled.", + "response": "Storing feedback is disabled" } } } @@ -4491,144 +4274,32 @@ "response": "Conversation not found" } } - }, - "provider": { - "value": { - "detail": { - "cause": "Provider with ID openai does not exist", - "response": "Provider not found" - } - } - }, - "model": { - "value": { - "detail": { - "cause": "Model with ID gpt-4-turbo is not configured", - "response": "Model not found" - } - } - } - } - } - } - }, - "413": { - "description": "Prompt is too long", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PromptTooLongResponse" - }, - "examples": { - "prompt too long": { - "value": { - "detail": { - "cause": "The prompt exceeds the maximum allowed length.", - "response": "Prompt is too long" - } - } - } - } - } - } - }, - "422": { - "description": "Request validation failed", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UnprocessableEntityResponse" - }, - "examples": { - "invalid format": { - "value": { - "detail": { - "cause": "Invalid request format. The request body could not be parsed.", - "response": "Invalid request format" - } - } - }, - "missing attributes": { - "value": { - "detail": { - "cause": "Missing required attributes: ['query', 'model', 'provider']", - "response": "Missing required attributes" - } - } - }, - "invalid value": { - "value": { - "detail": { - "cause": "Invalid attachment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']", - "response": "Invalid attribute value" - } - } } } } } }, - "429": { - "description": "Quota limit exceeded", + "500": { + "description": "Internal server error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/QuotaExceededResponse" + "$ref": "#/components/schemas/InternalServerErrorResponse" }, "examples": { - "model": { - "value": { - "detail": { - "cause": "The token quota for model gpt-4-turbo has been exceeded.", - "response": "The model quota has been exceeded" - } - } - }, - "user none": { - "value": { - "detail": { - "cause": "User 123 has no available tokens.", - "response": "The quota has been exceeded" - } - } - }, - "cluster none": { - "value": { - "detail": { - "cause": "Cluster has no available tokens.", - "response": "The quota has been exceeded" - } - } - }, - "subject none": { - "value": { - "detail": { - "cause": "Unknown subject 999 has no available tokens.", - "response": "The quota has been exceeded" - } - } - }, - "user insufficient": { - "value": { - "detail": { - "cause": "User 123 has 5 tokens, but 10 tokens are needed.", - "response": "The quota has been exceeded" - } - } - }, - "cluster insufficient": { + "configuration": { "value": { "detail": { - "cause": "Cluster has 500 tokens, but 900 tokens are needed.", - "response": "The quota has been exceeded" + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" } } }, - "subject insufficient": { + "feedback storage": { "value": { "detail": { - "cause": "Unknown subject 999 has 3 tokens, but 6 tokens are needed.", - "response": "The quota has been exceeded" + "cause": "Failed to store feedback at directory: /path/example", + "response": "Failed to store feedback" } } } @@ -4636,70 +4307,58 @@ } } }, - "500": { - "description": "Internal server error", + "422": { + "description": "Validation Error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InternalServerErrorResponse" - }, - "examples": { - "configuration": { - "value": { - "detail": { - "cause": "Lightspeed Stack configuration has not been initialized.", - "response": "Configuration is not loaded" - } - } - } + "$ref": "#/components/schemas/HTTPValidationError" } } } - }, - "503": { - "description": "Service unavailable", + } + } + } + }, + "/v1/feedback/status": { + "get": { + "tags": [ + "feedback" + ], + "summary": "Feedback Status", + "description": "Handle feedback status requests.\n\nReturn the current enabled status of the feedback\nfunctionality.\n\n### Parameters:\n- None\n\n### Returns:\n- StatusResponse: Indicates whether feedback collection is enabled.", + "operationId": "feedback_status_v1_feedback_status_get", + "responses": { + "200": { + "description": "Successful response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ServiceUnavailableResponse" + "$ref": "#/components/schemas/StatusResponse" }, - "examples": { - "llama stack": { - "value": { - "detail": { - "cause": "Connection error while trying to reach backend service.", - "response": "Unable to connect to Llama Stack" - } - } - }, - "kubernetes api": { - "value": { - "detail": { - "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", - "response": "Unable to connect to Kubernetes API" - } - } + "example": { + "functionality": "feedback", + "status": { + "enabled": true } } } } } } - } - }, - "/v1/infer": { - "post": { + }, + "put": { "tags": [ - "rlsapi-v1" + "feedback" ], - "summary": "Infer Endpoint", - "description": "Handle rlsapi v1 /infer requests for stateless inference.\n\nThis endpoint serves requests from the RHEL Lightspeed Command Line Assistant (CLA).\n\nAccepts a question with optional context (stdin, attachments, terminal output,\nsystem info) and returns an LLM-generated response.\n\nArgs:\n infer_request: The inference request containing question and context.\n request: The FastAPI request object for accessing headers and state.\n background_tasks: FastAPI background tasks for async Splunk event sending.\n auth: Authentication tuple from the configured auth provider.\n\nReturns:\n RlsapiV1InferResponse containing the generated response text and request ID.\n\nRaises:\n HTTPException: 503 if the LLM service is unavailable.", - "operationId": "infer_endpoint_v1_infer_post", + "summary": "Update Feedback Status", + "description": "Handle feedback status update requests.\n\nTakes a request with the desired state of the feedback status.\nReturns the updated state of the feedback status based on the request's value.\nThese changes are for the life of the service and are on a per-worker basis.\n\n### Parameters:\n- feedback_update_request: Structure containing desired state of the\n feedback status.\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- FeedbackStatusUpdateResponse: Indicates whether feedback is enabled.", + "operationId": "update_feedback_status_v1_feedback_status_put", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RlsapiV1InferRequest" + "$ref": "#/components/schemas/FeedbackStatusUpdateRequest" } } }, @@ -4711,12 +4370,14 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RlsapiV1InferResponse" + "$ref": "#/components/schemas/FeedbackStatusUpdateResponse" }, "example": { - "data": { - "request_id": "01JDKR8N7QW9ZMXVGK3PB5TQWZ", - "text": "To list files in Linux, use the `ls` command." + "status": { + "previous_status": true, + "timestamp": "2023-03-15 12:34:56", + "updated_by": "user/test", + "updated_status": false } } } @@ -4770,19 +4431,19 @@ } } }, - "404": { - "description": "Resource not found", + "500": { + "description": "Internal server error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NotFoundResponse" + "$ref": "#/components/schemas/InternalServerErrorResponse" }, "examples": { - "model": { + "configuration": { "value": { "detail": { - "cause": "Model with ID gpt-4-turbo is not configured", - "response": "Model not found" + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" } } } @@ -4790,164 +4451,12 @@ } } }, - "413": { - "description": "Prompt is too long", + "422": { + "description": "Validation Error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PromptTooLongResponse" - }, - "examples": { - "prompt too long": { - "value": { - "detail": { - "cause": "The prompt exceeds the maximum allowed length.", - "response": "Prompt is too long" - } - } - } - } - } - } - }, - "422": { - "description": "Request validation failed", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UnprocessableEntityResponse" - }, - "examples": { - "invalid format": { - "value": { - "detail": { - "cause": "Invalid request format. The request body could not be parsed.", - "response": "Invalid request format" - } - } - }, - "missing attributes": { - "value": { - "detail": { - "cause": "Missing required attributes: ['query', 'model', 'provider']", - "response": "Missing required attributes" - } - } - }, - "invalid value": { - "value": { - "detail": { - "cause": "Invalid attachment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']", - "response": "Invalid attribute value" - } - } - } - } - } - } - }, - "429": { - "description": "Quota limit exceeded", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/QuotaExceededResponse" - }, - "examples": { - "model": { - "value": { - "detail": { - "cause": "The token quota for model gpt-4-turbo has been exceeded.", - "response": "The model quota has been exceeded" - } - } - }, - "user none": { - "value": { - "detail": { - "cause": "User 123 has no available tokens.", - "response": "The quota has been exceeded" - } - } - }, - "cluster none": { - "value": { - "detail": { - "cause": "Cluster has no available tokens.", - "response": "The quota has been exceeded" - } - } - }, - "subject none": { - "value": { - "detail": { - "cause": "Unknown subject 999 has no available tokens.", - "response": "The quota has been exceeded" - } - } - }, - "user insufficient": { - "value": { - "detail": { - "cause": "User 123 has 5 tokens, but 10 tokens are needed.", - "response": "The quota has been exceeded" - } - } - }, - "cluster insufficient": { - "value": { - "detail": { - "cause": "Cluster has 500 tokens, but 900 tokens are needed.", - "response": "The quota has been exceeded" - } - } - }, - "subject insufficient": { - "value": { - "detail": { - "cause": "Unknown subject 999 has 3 tokens, but 6 tokens are needed.", - "response": "The quota has been exceeded" - } - } - } - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/InternalServerErrorResponse" - } - } - } - }, - "503": { - "description": "Service unavailable", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ServiceUnavailableResponse" - }, - "examples": { - "llama stack": { - "value": { - "detail": { - "cause": "Connection error while trying to reach backend service.", - "response": "Unable to connect to Llama Stack" - } - } - }, - "kubernetes api": { - "value": { - "detail": { - "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", - "response": "Unable to connect to Kubernetes API" - } - } - } + "$ref": "#/components/schemas/HTTPValidationError" } } } @@ -4955,26 +4464,42 @@ } } }, - "/readiness": { + "/v1/conversations": { "get": { "tags": [ - "health" + "conversations_v1" ], - "summary": "Readiness Probe Get Method", - "description": "Handle the readiness probe endpoint, returning service readiness.\n\nIf any provider reports an error status, responds with HTTP 503\nand details of unhealthy providers; otherwise, indicates the\nservice is ready.\n\n### Parameters:\n- response: The outgoing HTTP response (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- ReadinessResponse: Object with `ready` indicating overall readiness,\n `reason` explaining the outcome, and `providers` containing the list of\n unhealthy ProviderHealthStatus entries (empty when ready).", - "operationId": "readiness_probe_get_method_readiness_get", + "summary": "Conversations List Endpoint Handler V1", + "description": "Handle request to retrieve all conversations for the authenticated user.", + "operationId": "get_conversations_list_endpoint_handler_v1_conversations_get", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ReadinessResponse" + "$ref": "#/components/schemas/ConversationsListResponse" }, "example": { - "providers": [], - "ready": true, - "reason": "Service is ready" + "conversations": [ + { + "conversation_id": "123e4567-e89b-12d3-a456-426614174000", + "created_at": "2024-01-01T00:00:00Z", + "last_message_at": "2024-01-01T00:05:00Z", + "last_used_model": "gemini/gemini-2.0-flash", + "last_used_provider": "gemini", + "message_count": 5, + "topic_summary": "Openshift Microservices Deployment Strategies" + }, + { + "conversation_id": "456e7890-e12b-34d5-a678-901234567890", + "created_at": "2024-01-01T01:00:00Z", + "last_used_model": "gemini/gemini-2.5-flash", + "last_used_provider": "gemini", + "message_count": 2, + "topic_summary": "RHDH Purpose Summary" + } + ] } } } @@ -5027,27 +4552,27 @@ } } }, - "503": { - "description": "Service unavailable", + "500": { + "description": "Internal server error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ServiceUnavailableResponse" + "$ref": "#/components/schemas/InternalServerErrorResponse" }, "examples": { - "llama stack": { + "configuration": { "value": { "detail": { - "cause": "Connection error while trying to reach backend service.", - "response": "Unable to connect to Llama Stack" + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" } } }, - "kubernetes api": { + "database": { "value": { "detail": { - "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", - "response": "Unable to connect to Kubernetes API" + "cause": "Failed to query the database", + "response": "Database query failed" } } } @@ -5058,24 +4583,83 @@ } } }, - "/liveness": { + "/v1/conversations/{conversation_id}": { "get": { "tags": [ - "health" + "conversations_v1" + ], + "summary": "Conversation Get Endpoint Handler V1", + "description": "Handle request to retrieve a conversation identified by ID using Conversations API.\n\nRetrieve a conversation's chat history by its ID using the LlamaStack\nConversations API. This endpoint fetches the conversation items from\nthe backend, simplifies them to essential chat history, and returns\nthem in a structured response. Raises HTTP 400 for invalid IDs, 404\nif not found, 503 if the backend is unavailable, and 500 for\nunexpected errors.\n\nArgs:\n request: The FastAPI request object\n conversation_id: Unique identifier of the conversation to retrieve\n auth: Authentication tuple from dependency\n\nReturns:\n ConversationResponse: Structured response containing the conversation\n ID and simplified chat history", + "operationId": "get_conversation_endpoint_handler_v1_conversations__conversation_id__get", + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Conversation Id" + } + } ], - "summary": "Liveness Probe Get Method", - "description": "Return the liveness status of the service.\n\n### Parameters:\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- LivenessResponse: Indicates that the service is alive.", - "operationId": "liveness_probe_get_method_liveness_get", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/LivenessResponse" + "$ref": "#/components/schemas/ConversationResponse" }, "example": { - "alive": true + "chat_history": [ + { + "completed_at": "2024-01-01T00:01:05Z", + "messages": [ + { + "content": "Hello", + "type": "user" + }, + { + "content": "Hi there!", + "type": "assistant" + } + ], + "model": "gpt-4o-mini", + "provider": "openai", + "started_at": "2024-01-01T00:01:00Z", + "tool_calls": [], + "tool_results": [] + } + ], + "conversation_id": "123e4567-e89b-12d3-a456-426614174000" + } + } + } + }, + "400": { + "description": "Invalid request format", + "content": { + "application/json": { + "examples": { + "conversation_id": { + "value": { + "detail": { + "cause": "The conversation ID 123e4567-e89b-12d3-a456-426614174000 has invalid format.", + "response": "Invalid conversation ID format" + } + } + }, + "file_upload": { + "value": { + "detail": { + "cause": "File upload rejected: Invalid file format", + "response": "Invalid file upload" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/BadRequestResponse" } } } @@ -5084,9 +4668,6 @@ "description": "Unauthorized", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/UnauthorizedResponse" - }, "examples": { "missing header": { "value": { @@ -5104,6 +4685,9 @@ } } } + }, + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" } } } @@ -5112,10 +4696,15 @@ "description": "Permission denied", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenResponse" - }, "examples": { + "conversation read": { + "value": { + "detail": { + "cause": "User 6789 does not have permission to read conversation with ID 123e4567-e89b-12d3-a456-426614174000", + "response": "User does not have permission to perform this action" + } + } + }, "endpoint": { "value": { "detail": { @@ -5124,103 +4713,170 @@ } } } + }, + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" } } } - } - } - } - }, - "/authorized": { - "post": { - "tags": [ - "authorized" - ], - "summary": "Authorized Endpoint Handler", - "description": "Handle request to the /authorized endpoint.\n\nProcess POST requests to the /authorized endpoint, returning\nthe authenticated user's ID and username.\n\nThe response intentionally omits any authentication token.\n\n### Parameters:\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- AuthorizedResponse: Contains the user ID and username of the authenticated user.", - "operationId": "authorized_endpoint_handler_authorized_post", - "responses": { - "200": { - "description": "Successful response", + }, + "404": { + "description": "Resource not found", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthorizedResponse" + "examples": { + "conversation": { + "value": { + "detail": { + "cause": "Conversation with ID 123e4567-e89b-12d3-a456-426614174000 does not exist", + "response": "Conversation not found" + } + } + } }, - "example": { - "skip_userid_check": false, - "user_id": "123e4567-e89b-12d3-a456-426614174000", - "username": "user1" + "schema": { + "$ref": "#/components/schemas/NotFoundResponse" } } } }, - "401": { - "description": "Unauthorized", + "500": { + "description": "Internal server error", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/UnauthorizedResponse" - }, "examples": { - "missing header": { + "configuration": { "value": { "detail": { - "cause": "No Authorization header found", - "response": "Missing or invalid credentials provided by client" + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" } } }, - "missing token": { + "database": { "value": { "detail": { - "cause": "No token found in Authorization header", - "response": "Missing or invalid credentials provided by client" + "cause": "Failed to query the database", + "response": "Database query failed" } } } + }, + "schema": { + "$ref": "#/components/schemas/InternalServerErrorResponse" } } } }, - "403": { - "description": "Permission denied", + "503": { + "description": "Service unavailable", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/ForbiddenResponse" - }, "examples": { - "endpoint": { + "llama stack": { "value": { "detail": { - "cause": "User 6789 is not authorized to access this endpoint.", - "response": "User does not have permission to access this endpoint" + "cause": "Connection error while trying to reach backend service.", + "response": "Unable to connect to Llama Stack" + } + } + }, + "kubernetes api": { + "value": { + "detail": { + "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", + "response": "Unable to connect to Kubernetes API" } } } + }, + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" } } } } } - } - }, - "/metrics": { - "get": { + }, + "delete": { "tags": [ - "metrics" + "conversations_v1" + ], + "summary": "Conversation Delete Endpoint Handler V1", + "description": "Handle request to delete a conversation by ID using Conversations API.\n\nValidates the conversation ID format and attempts to delete the\nconversation from the Llama Stack backend using the Conversations API.\nRaises HTTP errors for invalid IDs, not found conversations, connection\nissues, or unexpected failures.\n\nArgs:\n request: The FastAPI request object\n conversation_id: Unique identifier of the conversation to delete\n auth: Authentication tuple from dependency\n\nReturns:\n ConversationDeleteResponse: Response indicating the result of the deletion operation", + "operationId": "delete_conversation_endpoint_handler_v1_conversations__conversation_id__delete", + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Conversation Id" + } + } ], - "summary": "Metrics Endpoint Handler", - "description": "Handle request to the /metrics endpoint.\n\nProcess GET requests to the /metrics endpoint, returning the\nlatest Prometheus metrics in form of a plain text.\n\nInitializes model metrics on the first request if not already\nset up, then responds with the current metrics snapshot in\nPrometheus format.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- PlainTextResponse: Response body containing the Prometheus metrics text\n and the Prometheus content type.", - "operationId": "metrics_endpoint_handler_metrics_get", "responses": { "200": { - "description": "Successful Response", + "description": "Successful response", "content": { - "text/plain": { + "application/json": { "schema": { - "type": "string" + "$ref": "#/components/schemas/ConversationDeleteResponse" + }, + "examples": { + "deleted": { + "value": { + "conversation_id": "123e4567-e89b-12d3-a456-426614174000", + "response": "Conversation deleted successfully", + "success": true + } + }, + "not found": { + "value": { + "conversation_id": "123e4567-e89b-12d3-a456-426614174000", + "response": "Conversation can not be deleted", + "success": true + } + } + } + } + } + }, + "400": { + "description": "Invalid request format", + "content": { + "application/json": { + "examples": { + "conversation_id": { + "value": { + "detail": { + "cause": "The conversation ID 123e4567-e89b-12d3-a456-426614174000 has invalid format.", + "response": "Invalid conversation ID format" + } + } + }, + "file_upload": { + "value": { + "detail": { + "cause": "File upload rejected: Invalid file format", + "response": "Invalid file upload" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/BadRequestResponse" } } } @@ -5246,9 +4902,7 @@ } } } - } - }, - "text/plain": { + }, "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } @@ -5260,6 +4914,14 @@ "content": { "application/json": { "examples": { + "conversation delete": { + "value": { + "detail": { + "cause": "User 6789 does not have permission to delete conversation with ID 123e4567-e89b-12d3-a456-426614174000", + "response": "User does not have permission to perform this action" + } + } + }, "endpoint": { "value": { "detail": { @@ -5268,9 +4930,7 @@ } } } - } - }, - "text/plain": { + }, "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } @@ -5289,10 +4949,16 @@ "response": "Configuration is not loaded" } } + }, + "database": { + "value": { + "detail": { + "cause": "Failed to query the database", + "response": "Database query failed" + } + } } - } - }, - "text/plain": { + }, "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } @@ -5320,70 +4986,1954 @@ } } } - } - }, - "text/plain": { + }, "schema": { "$ref": "#/components/schemas/ServiceUnavailableResponse" } } } - } - } - } - }, - "/.well-known/agent-card.json": { - "get": { - "tags": [ - "a2a" - ], - "summary": "Get Agent Card", - "description": "Serve the A2A Agent Card at the well-known location.\n\nThis endpoint provides the agent card that describes Lightspeed's\ncapabilities according to the A2A protocol specification.\n\nReturns:\n AgentCard: The agent card describing this agent's capabilities.", - "operationId": "get_agent_card__well_known_agent_card_json_get", - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentCard" - } - } - } - } - } - } - }, - "/.well-known/agent.json": { - "get": { - "tags": [ - "a2a" - ], - "summary": "Get Agent Card", - "description": "Serve the A2A Agent Card at the well-known location.\n\nThis endpoint provides the agent card that describes Lightspeed's\ncapabilities according to the A2A protocol specification.\n\nReturns:\n AgentCard: The agent card describing this agent's capabilities.", - "operationId": "get_agent_card__well_known_agent_json_get", - "responses": { - "200": { - "description": "Successful Response", + }, + "422": { + "description": "Validation Error", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AgentCard" + "$ref": "#/components/schemas/HTTPValidationError" } } } } } - } - }, - "/a2a": { - "get": { + }, + "put": { "tags": [ - "a2a" + "conversations_v1" + ], + "summary": "Conversation Update Endpoint Handler V1", + "description": "Handle request to update a conversation metadata using Conversations API.\n\nUpdates the conversation metadata (including topic summary) in both the\nLlamaStack backend using the Conversations API and the local database.\n\nArgs:\n request: The FastAPI request object\n conversation_id: Unique identifier of the conversation to update\n update_request: Request containing the topic summary to update\n auth: Authentication tuple from dependency\n\nReturns:\n ConversationUpdateResponse: Response indicating the result of the update operation", + "operationId": "update_conversation_endpoint_handler_v1_conversations__conversation_id__put", + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Conversation Id" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationUpdateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationUpdateResponse" + }, + "example": { + "conversation_id": "123e4567-e89b-12d3-a456-426614174000", + "message": "Topic summary updated successfully", + "success": true + } + } + } + }, + "400": { + "description": "Invalid request format", + "content": { + "application/json": { + "examples": { + "conversation_id": { + "value": { + "detail": { + "cause": "The conversation ID 123e4567-e89b-12d3-a456-426614174000 has invalid format.", + "response": "Invalid conversation ID format" + } + } + }, + "file_upload": { + "value": { + "detail": { + "cause": "File upload rejected: Invalid file format", + "response": "Invalid file upload" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/BadRequestResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "examples": { + "missing header": { + "value": { + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } + } + }, + "missing token": { + "value": { + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + } + } + } + }, + "403": { + "description": "Permission denied", + "content": { + "application/json": { + "examples": { + "endpoint": { + "value": { + "detail": { + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "examples": { + "conversation": { + "value": { + "detail": { + "cause": "Conversation with ID 123e4567-e89b-12d3-a456-426614174000 does not exist", + "response": "Conversation not found" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/NotFoundResponse" + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "examples": { + "configuration": { + "value": { + "detail": { + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" + } + } + }, + "database": { + "value": { + "detail": { + "cause": "Failed to query the database", + "response": "Database query failed" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/InternalServerErrorResponse" + } + } + } + }, + "503": { + "description": "Service unavailable", + "content": { + "application/json": { + "examples": { + "llama stack": { + "value": { + "detail": { + "cause": "Connection error while trying to reach backend service.", + "response": "Unable to connect to Llama Stack" + } + } + }, + "kubernetes api": { + "value": { + "detail": { + "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", + "response": "Unable to connect to Kubernetes API" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v2/conversations": { + "get": { + "tags": [ + "conversations_v2" + ], + "summary": "Get Conversations List Endpoint Handler", + "description": "Handle request to retrieve all conversations for the authenticated user.", + "operationId": "get_conversations_list_endpoint_handler_v2_conversations_get", + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationsListResponseV2" + }, + "example": { + "conversations": [ + { + "conversation_id": "123e4567-e89b-12d3-a456-426614174000", + "last_message_timestamp": 1704067200.0, + "topic_summary": "Openshift Microservices Deployment Strategies" + } + ] + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + }, + "examples": { + "missing header": { + "value": { + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } + } + }, + "missing token": { + "value": { + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + } + } + } + } + } + } + }, + "403": { + "description": "Permission denied", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + }, + "examples": { + "endpoint": { + "value": { + "detail": { + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" + } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalServerErrorResponse" + }, + "examples": { + "configuration": { + "value": { + "detail": { + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" + } + } + }, + "conversation cache": { + "value": { + "detail": { + "cause": "Conversation cache is not configured or unavailable.", + "response": "Conversation cache not configured" + } + } + } + } + } + } + } + } + } + }, + "/v2/conversations/{conversation_id}": { + "get": { + "tags": [ + "conversations_v2" + ], + "summary": "Get Conversation Endpoint Handler", + "description": "Handle request to retrieve a conversation identified by its ID.", + "operationId": "get_conversation_endpoint_handler_v2_conversations__conversation_id__get", + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Conversation Id" + } + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationResponse" + }, + "example": { + "chat_history": [ + { + "completed_at": "2024-01-01T00:01:05Z", + "messages": [ + { + "content": "Hello", + "type": "user" + }, + { + "content": "Hi there!", + "type": "assistant" + } + ], + "model": "gpt-4o-mini", + "provider": "openai", + "started_at": "2024-01-01T00:01:00Z", + "tool_calls": [], + "tool_results": [] + } + ], + "conversation_id": "123e4567-e89b-12d3-a456-426614174000" + } + } + } + }, + "400": { + "description": "Invalid request format", + "content": { + "application/json": { + "examples": { + "conversation_id": { + "value": { + "detail": { + "cause": "The conversation ID 123e4567-e89b-12d3-a456-426614174000 has invalid format.", + "response": "Invalid conversation ID format" + } + } + }, + "file_upload": { + "value": { + "detail": { + "cause": "File upload rejected: Invalid file format", + "response": "Invalid file upload" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/BadRequestResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "examples": { + "missing header": { + "value": { + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } + } + }, + "missing token": { + "value": { + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + } + } + } + }, + "403": { + "description": "Permission denied", + "content": { + "application/json": { + "examples": { + "endpoint": { + "value": { + "detail": { + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "examples": { + "conversation": { + "value": { + "detail": { + "cause": "Conversation with ID 123e4567-e89b-12d3-a456-426614174000 does not exist", + "response": "Conversation not found" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/NotFoundResponse" + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "examples": { + "configuration": { + "value": { + "detail": { + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" + } + } + }, + "conversation cache": { + "value": { + "detail": { + "cause": "Conversation cache is not configured or unavailable.", + "response": "Conversation cache not configured" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/InternalServerErrorResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "conversations_v2" + ], + "summary": "Delete Conversation Endpoint Handler", + "description": "Handle request to delete a conversation by ID.", + "operationId": "delete_conversation_endpoint_handler_v2_conversations__conversation_id__delete", + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Conversation Id" + } + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationDeleteResponse" + }, + "examples": { + "deleted": { + "value": { + "conversation_id": "123e4567-e89b-12d3-a456-426614174000", + "response": "Conversation deleted successfully", + "success": true + } + }, + "not found": { + "value": { + "conversation_id": "123e4567-e89b-12d3-a456-426614174000", + "response": "Conversation can not be deleted", + "success": true + } + } + } + } + } + }, + "400": { + "description": "Invalid request format", + "content": { + "application/json": { + "examples": { + "conversation_id": { + "value": { + "detail": { + "cause": "The conversation ID 123e4567-e89b-12d3-a456-426614174000 has invalid format.", + "response": "Invalid conversation ID format" + } + } + }, + "file_upload": { + "value": { + "detail": { + "cause": "File upload rejected: Invalid file format", + "response": "Invalid file upload" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/BadRequestResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "examples": { + "missing header": { + "value": { + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } + } + }, + "missing token": { + "value": { + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + } + } + } + }, + "403": { + "description": "Permission denied", + "content": { + "application/json": { + "examples": { + "endpoint": { + "value": { + "detail": { + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "examples": { + "configuration": { + "value": { + "detail": { + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" + } + } + }, + "conversation cache": { + "value": { + "detail": { + "cause": "Conversation cache is not configured or unavailable.", + "response": "Conversation cache not configured" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/InternalServerErrorResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "put": { + "tags": [ + "conversations_v2" + ], + "summary": "Update Conversation Endpoint Handler", + "description": "Handle request to update a conversation topic summary by ID.", + "operationId": "update_conversation_endpoint_handler_v2_conversations__conversation_id__put", + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Conversation Id" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationUpdateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationUpdateResponse" + }, + "example": { + "conversation_id": "123e4567-e89b-12d3-a456-426614174000", + "message": "Topic summary updated successfully", + "success": true + } + } + } + }, + "400": { + "description": "Invalid request format", + "content": { + "application/json": { + "examples": { + "conversation_id": { + "value": { + "detail": { + "cause": "The conversation ID 123e4567-e89b-12d3-a456-426614174000 has invalid format.", + "response": "Invalid conversation ID format" + } + } + }, + "file_upload": { + "value": { + "detail": { + "cause": "File upload rejected: Invalid file format", + "response": "Invalid file upload" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/BadRequestResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "examples": { + "missing header": { + "value": { + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } + } + }, + "missing token": { + "value": { + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + } + } + } + }, + "403": { + "description": "Permission denied", + "content": { + "application/json": { + "examples": { + "endpoint": { + "value": { + "detail": { + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "examples": { + "conversation": { + "value": { + "detail": { + "cause": "Conversation with ID 123e4567-e89b-12d3-a456-426614174000 does not exist", + "response": "Conversation not found" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/NotFoundResponse" + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "examples": { + "configuration": { + "value": { + "detail": { + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" + } + } + }, + "conversation cache": { + "value": { + "detail": { + "cause": "Conversation cache is not configured or unavailable.", + "response": "Conversation cache not configured" + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/InternalServerErrorResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/responses": { + "post": { + "tags": [ + "responses" + ], + "summary": "Responses Endpoint Handler", + "description": "Handle request to the /responses endpoint using Responses API (LCORE specification).\n\nProcesses a POST request to the responses endpoint, forwarding the\nuser's request to a selected Llama Stack LLM and returning the generated response\nfollowing the LCORE OpenAPI specification.\n\nReturns:\n ResponsesResponse: Contains the response following LCORE specification (non-streaming).\n StreamingResponse: SSE-formatted streaming response with enriched events (streaming).\n - response.created event includes conversation attribute\n - response.completed event includes available_quotas attribute\n\nRaises:\n HTTPException:\n - 401: Unauthorized - Missing or invalid credentials\n - 403: Forbidden - Insufficient permissions or model override not allowed\n - 404: Not Found - Conversation, model, or provider not found\n - 413: Prompt too long - Prompt exceeded model's context window size\n - 422: Unprocessable Entity - Request validation failed\n - 429: Quota limit exceeded - The token quota for model or user has been exceeded\n - 500: Internal Server Error - Configuration not loaded or other server errors\n - 503: Service Unavailable - Unable to connect to Llama Stack backend", + "operationId": "responses_endpoint_handler_v1_responses_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResponsesRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResponsesResponse" + }, + "example": { + "available_quotas": { + "daily": 1000, + "monthly": 50000 + }, + "completed_at": 1704067250, + "conversation": "0d21ba731f21f798dc9680125d5d6f493e4a7ab79f25670e", + "created_at": 1704067200, + "id": "resp_abc123", + "instructions": "You are a helpful assistant", + "model": "openai/gpt-4-turbo", + "object": "response", + "output": [ + { + "content": [ + { + "text": "Kubernetes is an open-source container orchestration system...", + "type": "output_text" + } + ], + "role": "assistant", + "type": "message" + } + ], + "output_text": "Kubernetes is an open-source container orchestration system...", + "parallel_tool_calls": true, + "status": "completed", + "store": true, + "temperature": 0.7, + "text": { + "format": { + "type": "text" + } + }, + "usage": { + "input_tokens": 100, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 50, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 150 + } + } + }, + "text/event-stream": { + "schema": { + "type": "string" + }, + "example": "event: response.created\ndata: {\"type\":\"response.created\",\"sequence_number\":0,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"in_progress\",\"model\":\"openai/gpt-4o-mini\",\"output\":[],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{},\"output_text\":\"\"}}\n\nevent: response.output_item.added\ndata: {\"type\":\"response.output_item.added\",\"sequence_number\":1,\"response_id\":\"resp_abc\",\"output_index\":0,\"item\":{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"in_progress\",\"role\":\"assistant\",\"content\":[]}}\n\n...\n\nevent: response.completed\ndata: {\"type\":\"response.completed\",\"sequence_number\":30,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"completed\",\"model\":\"openai/gpt-4o-mini\",\"output\":[{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello! How can I help?\",\"annotations\":[]}]}],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"usage\":{\"input_tokens\":10,\"output_tokens\":6,\"total_tokens\":16,\"input_tokens_details\":{\"cached_tokens\":0},\"output_tokens_details\":{\"reasoning_tokens\":0}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{\"daily\":1000,\"monthly\":50000},\"output_text\":\"Hello! How can I help?\"}}\n\ndata: [DONE]\n\n", + "description": "SSE stream of events" + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + }, + "examples": { + "missing header": { + "value": { + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } + } + }, + "missing token": { + "value": { + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + } + } + } + } + } + } + }, + "403": { + "description": "Permission denied", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + }, + "examples": { + "conversation read": { + "value": { + "detail": { + "cause": "User 6789 does not have permission to read conversation with ID 123e4567-e89b-12d3-a456-426614174000", + "response": "User does not have permission to perform this action" + } + } + }, + "endpoint": { + "value": { + "detail": { + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" + } + } + }, + "model override": { + "value": { + "detail": { + "cause": "User lacks model_override permission required to override model/provider.", + "response": "This instance does not permit overriding model/provider in the query request (missing permission: MODEL_OVERRIDE). Please remove the model and provider fields from your request." + } + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundResponse" + }, + "examples": { + "conversation": { + "value": { + "detail": { + "cause": "Conversation with ID 123e4567-e89b-12d3-a456-426614174000 does not exist", + "response": "Conversation not found" + } + } + }, + "provider": { + "value": { + "detail": { + "cause": "Provider with ID openai does not exist", + "response": "Provider not found" + } + } + }, + "model": { + "value": { + "detail": { + "cause": "Model with ID gpt-4-turbo is not configured", + "response": "Model not found" + } + } + } + } + } + } + }, + "409": { + "description": "Resource already exists", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictResponse" + }, + "examples": { + "mcp tool conflict": { + "value": { + "detail": { + "cause": "Client MCP tool with server_label 'my-server' conflicts with a server-configured MCP tool. Rename the client tool to avoid the conflict.", + "response": "Tool conflict" + } + } + }, + "file search conflict": { + "value": { + "detail": { + "cause": "Client file_search tool conflicts with a server-configured file_search tool. Remove the client file_search to use the server's configuration.", + "response": "Tool conflict" + } + } + } + } + } + } + }, + "413": { + "description": "Prompt is too long", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PromptTooLongResponse" + }, + "examples": { + "prompt too long": { + "value": { + "detail": { + "cause": "The prompt exceeds the maximum allowed length.", + "response": "Prompt is too long" + } + } + } + } + } + } + }, + "422": { + "description": "Request validation failed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableEntityResponse" + }, + "examples": { + "invalid format": { + "value": { + "detail": { + "cause": "Invalid request format. The request body could not be parsed.", + "response": "Invalid request format" + } + } + }, + "missing attributes": { + "value": { + "detail": { + "cause": "Missing required attributes: ['query', 'model', 'provider']", + "response": "Missing required attributes" + } + } + }, + "invalid value": { + "value": { + "detail": { + "cause": "Invalid attachment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']", + "response": "Invalid attribute value" + } + } + } + } + } + } + }, + "429": { + "description": "Quota limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QuotaExceededResponse" + }, + "examples": { + "model": { + "value": { + "detail": { + "cause": "The token quota for model gpt-4-turbo has been exceeded.", + "response": "The model quota has been exceeded" + } + } + }, + "user none": { + "value": { + "detail": { + "cause": "User 123 has no available tokens.", + "response": "The quota has been exceeded" + } + } + }, + "cluster none": { + "value": { + "detail": { + "cause": "Cluster has no available tokens.", + "response": "The quota has been exceeded" + } + } + }, + "subject none": { + "value": { + "detail": { + "cause": "Unknown subject 999 has no available tokens.", + "response": "The quota has been exceeded" + } + } + }, + "user insufficient": { + "value": { + "detail": { + "cause": "User 123 has 5 tokens, but 10 tokens are needed.", + "response": "The quota has been exceeded" + } + } + }, + "cluster insufficient": { + "value": { + "detail": { + "cause": "Cluster has 500 tokens, but 900 tokens are needed.", + "response": "The quota has been exceeded" + } + } + }, + "subject insufficient": { + "value": { + "detail": { + "cause": "Unknown subject 999 has 3 tokens, but 6 tokens are needed.", + "response": "The quota has been exceeded" + } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalServerErrorResponse" + }, + "examples": { + "configuration": { + "value": { + "detail": { + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" + } + } + } + } + } + } + }, + "503": { + "description": "Service unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableResponse" + }, + "examples": { + "llama stack": { + "value": { + "detail": { + "cause": "Connection error while trying to reach backend service.", + "response": "Unable to connect to Llama Stack" + } + } + }, + "kubernetes api": { + "value": { + "detail": { + "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", + "response": "Unable to connect to Kubernetes API" + } + } + } + } + } + } + } + } + } + }, + "/v1/infer": { + "post": { + "tags": [ + "rlsapi-v1" + ], + "summary": "Infer Endpoint", + "description": "Handle rlsapi v1 /infer requests for stateless inference.\n\nThis endpoint serves requests from the RHEL Lightspeed Command Line Assistant (CLA).\n\nAccepts a question with optional context (stdin, attachments, terminal output,\nsystem info) and returns an LLM-generated response.\n\nArgs:\n infer_request: The inference request containing question and context.\n request: The FastAPI request object for accessing headers and state.\n background_tasks: FastAPI background tasks for async Splunk event sending.\n auth: Authentication tuple from the configured auth provider.\n\nReturns:\n RlsapiV1InferResponse containing the generated response text and request ID.\n\nRaises:\n HTTPException: 503 if the LLM service is unavailable.", + "operationId": "infer_endpoint_v1_infer_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RlsapiV1InferRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RlsapiV1InferResponse" + }, + "example": { + "data": { + "request_id": "01JDKR8N7QW9ZMXVGK3PB5TQWZ", + "text": "To list files in Linux, use the `ls` command." + } + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + }, + "examples": { + "missing header": { + "value": { + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } + } + }, + "missing token": { + "value": { + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + } + } + } + } + } + } + }, + "403": { + "description": "Permission denied", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + }, + "examples": { + "endpoint": { + "value": { + "detail": { + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" + } + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFoundResponse" + }, + "examples": { + "model": { + "value": { + "detail": { + "cause": "Model with ID gpt-4-turbo is not configured", + "response": "Model not found" + } + } + } + } + } + } + }, + "413": { + "description": "Prompt is too long", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PromptTooLongResponse" + }, + "examples": { + "prompt too long": { + "value": { + "detail": { + "cause": "The prompt exceeds the maximum allowed length.", + "response": "Prompt is too long" + } + } + } + } + } + } + }, + "422": { + "description": "Request validation failed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableEntityResponse" + }, + "examples": { + "invalid format": { + "value": { + "detail": { + "cause": "Invalid request format. The request body could not be parsed.", + "response": "Invalid request format" + } + } + }, + "missing attributes": { + "value": { + "detail": { + "cause": "Missing required attributes: ['query', 'model', 'provider']", + "response": "Missing required attributes" + } + } + }, + "invalid value": { + "value": { + "detail": { + "cause": "Invalid attachment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']", + "response": "Invalid attribute value" + } + } + } + } + } + } + }, + "429": { + "description": "Quota limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QuotaExceededResponse" + }, + "examples": { + "model": { + "value": { + "detail": { + "cause": "The token quota for model gpt-4-turbo has been exceeded.", + "response": "The model quota has been exceeded" + } + } + }, + "user none": { + "value": { + "detail": { + "cause": "User 123 has no available tokens.", + "response": "The quota has been exceeded" + } + } + }, + "cluster none": { + "value": { + "detail": { + "cause": "Cluster has no available tokens.", + "response": "The quota has been exceeded" + } + } + }, + "subject none": { + "value": { + "detail": { + "cause": "Unknown subject 999 has no available tokens.", + "response": "The quota has been exceeded" + } + } + }, + "user insufficient": { + "value": { + "detail": { + "cause": "User 123 has 5 tokens, but 10 tokens are needed.", + "response": "The quota has been exceeded" + } + } + }, + "cluster insufficient": { + "value": { + "detail": { + "cause": "Cluster has 500 tokens, but 900 tokens are needed.", + "response": "The quota has been exceeded" + } + } + }, + "subject insufficient": { + "value": { + "detail": { + "cause": "Unknown subject 999 has 3 tokens, but 6 tokens are needed.", + "response": "The quota has been exceeded" + } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalServerErrorResponse" + } + } + } + }, + "503": { + "description": "Service unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableResponse" + }, + "examples": { + "llama stack": { + "value": { + "detail": { + "cause": "Connection error while trying to reach backend service.", + "response": "Unable to connect to Llama Stack" + } + } + }, + "kubernetes api": { + "value": { + "detail": { + "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", + "response": "Unable to connect to Kubernetes API" + } + } + } + } + } + } + } + } + } + }, + "/readiness": { + "get": { + "tags": [ + "health" + ], + "summary": "Readiness Probe Get Method", + "description": "Handle the readiness probe endpoint, returning service readiness.\n\nIf any provider reports an error status, responds with HTTP 503\nand details of unhealthy providers; otherwise, indicates the\nservice is ready.\n\n### Parameters:\n- response: The outgoing HTTP response (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- ReadinessResponse: Object with `ready` indicating overall readiness,\n `reason` explaining the outcome, and `providers` containing the list of\n unhealthy ProviderHealthStatus entries (empty when ready).", + "operationId": "readiness_probe_get_method_readiness_get", + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReadinessResponse" + }, + "example": { + "providers": [], + "ready": true, + "reason": "Service is ready" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + }, + "examples": { + "missing header": { + "value": { + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } + } + }, + "missing token": { + "value": { + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + } + } + } + } + } + } + }, + "403": { + "description": "Permission denied", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + }, + "examples": { + "endpoint": { + "value": { + "detail": { + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" + } + } + } + } + } + } + }, + "503": { + "description": "Service unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableResponse" + }, + "examples": { + "llama stack": { + "value": { + "detail": { + "cause": "Connection error while trying to reach backend service.", + "response": "Unable to connect to Llama Stack" + } + } + }, + "kubernetes api": { + "value": { + "detail": { + "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", + "response": "Unable to connect to Kubernetes API" + } + } + } + } + } + } + } + } + } + }, + "/liveness": { + "get": { + "tags": [ + "health" + ], + "summary": "Liveness Probe Get Method", + "description": "Return the liveness status of the service.\n\n### Parameters:\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- LivenessResponse: Indicates that the service is alive.", + "operationId": "liveness_probe_get_method_liveness_get", + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LivenessResponse" + }, + "example": { + "alive": true + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + }, + "examples": { + "missing header": { + "value": { + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } + } + }, + "missing token": { + "value": { + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + } + } + } + } + } + } + }, + "403": { + "description": "Permission denied", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + }, + "examples": { + "endpoint": { + "value": { + "detail": { + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" + } + } + } + } + } + } + } + } + } + }, + "/authorized": { + "post": { + "tags": [ + "authorized" + ], + "summary": "Authorized Endpoint Handler", + "description": "Handle request to the /authorized endpoint.\n\nProcess POST requests to the /authorized endpoint, returning\nthe authenticated user's ID and username.\n\nThe response intentionally omits any authentication token.\n\n### Parameters:\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- AuthorizedResponse: Contains the user ID and username of the authenticated user.", + "operationId": "authorized_endpoint_handler_authorized_post", + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthorizedResponse" + }, + "example": { + "skip_userid_check": false, + "user_id": "123e4567-e89b-12d3-a456-426614174000", + "username": "user1" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + }, + "examples": { + "missing header": { + "value": { + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } + } + }, + "missing token": { + "value": { + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + } + } + } + } + } + } + }, + "403": { + "description": "Permission denied", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + }, + "examples": { + "endpoint": { + "value": { + "detail": { + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" + } + } + } + } + } + } + } + } + } + }, + "/metrics": { + "get": { + "tags": [ + "metrics" + ], + "summary": "Metrics Endpoint Handler", + "description": "Handle request to the /metrics endpoint.\n\nProcess GET requests to the /metrics endpoint, returning the\nlatest Prometheus metrics in form of a plain text.\n\nInitializes model metrics on the first request if not already\nset up, then responds with the current metrics snapshot in\nPrometheus format.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- PlainTextResponse: Response body containing the Prometheus metrics text\n and the Prometheus content type.", + "operationId": "metrics_endpoint_handler_metrics_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "examples": { + "missing header": { + "value": { + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } + } + }, + "missing token": { + "value": { + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + } + } + } + } + }, + "text/plain": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + } + } + } + }, + "403": { + "description": "Permission denied", + "content": { + "application/json": { + "examples": { + "endpoint": { + "value": { + "detail": { + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" + } + } + } + } + }, + "text/plain": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "examples": { + "configuration": { + "value": { + "detail": { + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" + } + } + } + } + }, + "text/plain": { + "schema": { + "$ref": "#/components/schemas/InternalServerErrorResponse" + } + } + } + }, + "503": { + "description": "Service unavailable", + "content": { + "application/json": { + "examples": { + "llama stack": { + "value": { + "detail": { + "cause": "Connection error while trying to reach backend service.", + "response": "Unable to connect to Llama Stack" + } + } + }, + "kubernetes api": { + "value": { + "detail": { + "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", + "response": "Unable to connect to Kubernetes API" + } + } + } + } + }, + "text/plain": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableResponse" + } + } + } + } + } + } + }, + "/.well-known/agent-card.json": { + "get": { + "tags": [ + "a2a" + ], + "summary": "Get Agent Card", + "description": "Serve the A2A Agent Card at the well-known location.\n\nThis endpoint provides the agent card that describes Lightspeed's\ncapabilities according to the A2A protocol specification.\n\nReturns:\n AgentCard: The agent card describing this agent's capabilities.", + "operationId": "get_agent_card__well_known_agent_card_json_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentCard" + } + } + } + } + } + } + }, + "/.well-known/agent.json": { + "get": { + "tags": [ + "a2a" + ], + "summary": "Get Agent Card", + "description": "Serve the A2A Agent Card at the well-known location.\n\nThis endpoint provides the agent card that describes Lightspeed's\ncapabilities according to the A2A protocol specification.\n\nReturns:\n AgentCard: The agent card describing this agent's capabilities.", + "operationId": "get_agent_card__well_known_agent_json_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentCard" + } + } + } + } + } + } + }, + "/a2a": { + "get": { + "tags": [ + "a2a" ], "summary": "Handle A2A Jsonrpc", "description": "Handle A2A JSON-RPC requests following the A2A protocol specification.\n\nThis endpoint uses the DefaultRequestHandler from the A2A SDK to handle\nall JSON-RPC requests including message/send, message/stream, etc.\n\nThe A2A SDK application is created per-request to include authentication\ncontext while still leveraging FastAPI's authorization middleware.\n\nAutomatically detects streaming requests (message/stream JSON-RPC method)\nand returns a StreamingResponse to enable real-time chunk delivery.\n\nArgs:\n request: FastAPI request object\n auth: Authentication tuple\n mcp_headers: MCP headers for context propagation\n\nReturns:\n JSON-RPC response or streaming response", - "operationId": "handle_a2a_jsonrpc_a2a_post", + "operationId": "handle_a2a_jsonrpc_a2a_get", "responses": { "200": { "description": "Successful Response", @@ -5401,7 +6951,7 @@ ], "summary": "Handle A2A Jsonrpc", "description": "Handle A2A JSON-RPC requests following the A2A protocol specification.\n\nThis endpoint uses the DefaultRequestHandler from the A2A SDK to handle\nall JSON-RPC requests including message/send, message/stream, etc.\n\nThe A2A SDK application is created per-request to include authentication\ncontext while still leveraging FastAPI's authorization middleware.\n\nAutomatically detects streaming requests (message/stream JSON-RPC method)\nand returns a StreamingResponse to enable real-time chunk delivery.\n\nArgs:\n request: FastAPI request object\n auth: Authentication tuple\n mcp_headers: MCP headers for context propagation\n\nReturns:\n JSON-RPC response or streaming response", - "operationId": "handle_a2a_jsonrpc_a2a_post", + "operationId": "handle_a2a_jsonrpc_a2a_get", "responses": { "200": { "description": "Successful Response", @@ -5589,7 +7139,10 @@ "a2a_agent_card", "a2a_task_execution", "a2a_message", - "a2a_jsonrpc" + "a2a_jsonrpc", + "manage_vector_stores", + "read_vector_stores", + "manage_files" ], "title": "Action", "description": "Available actions in the system.\n\nNote: this is not a real model, just an enumeration of all action names." @@ -6457,9 +8010,30 @@ "response": "Invalid conversation ID format" }, "label": "conversation_id" + }, + { + "detail": { + "cause": "File upload rejected: Invalid file format", + "response": "Invalid file upload" + }, + "label": "file_upload" } ] }, + "Body_create_file_v1_files_post": { + "properties": { + "file": { + "type": "string", + "contentMediaType": "application/octet-stream", + "title": "File" + } + }, + "type": "object", + "required": [ + "file" + ], + "title": "Body_create_file_v1_files_post" + }, "ByokRag": { "properties": { "rag_id": { @@ -6854,6 +8428,20 @@ "response": "Mcp Server already exists" }, "label": "mcp server" + }, + { + "detail": { + "cause": "Client MCP tool with server_label 'my-server' conflicts with a server-configured MCP tool. Rename the client tool to avoid the conflict.", + "response": "Tool conflict" + }, + "label": "mcp tool conflict" + }, + { + "detail": { + "cause": "Client file_search tool conflicts with a server-configured file_search tool. Remove the client file_search to use the server's configuration.", + "response": "Tool conflict" + }, + "label": "file search conflict" } ] }, @@ -7750,6 +9338,98 @@ } ] }, + "FileResponse": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "File ID" + }, + "filename": { + "type": "string", + "title": "Filename", + "description": "File name" + }, + "bytes": { + "type": "integer", + "title": "Bytes", + "description": "File size in bytes" + }, + "created_at": { + "type": "integer", + "title": "Created At", + "description": "Unix timestamp when created" + }, + "purpose": { + "type": "string", + "title": "Purpose", + "description": "File purpose", + "default": "assistants" + }, + "object": { + "type": "string", + "title": "Object", + "description": "Object type", + "default": "file" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id", + "filename", + "bytes", + "created_at" + ], + "title": "FileResponse", + "description": "Response model containing a file object.\n\nAttributes:\n id: File ID.\n filename: File name.\n bytes: File size in bytes.\n created_at: Unix timestamp when created.\n purpose: File purpose.\n object: Object type (always \"file\").", + "examples": [ + { + "bytes": 524288, + "created_at": 1704067200, + "filename": "documentation.pdf", + "id": "file_abc123", + "object": "file", + "purpose": "assistants" + } + ] + }, + "FileTooLargeResponse": { + "properties": { + "status_code": { + "type": "integer", + "title": "Status Code", + "description": "HTTP status code for the errors response" + }, + "detail": { + "$ref": "#/components/schemas/DetailModel", + "description": "The detail model containing error summary and cause" + } + }, + "type": "object", + "required": [ + "status_code", + "detail" + ], + "title": "FileTooLargeResponse", + "description": "413 Content Too Large - File upload exceeds size limit.", + "examples": [ + { + "detail": { + "cause": "File size 150000000 bytes exceeds maximum allowed size of 104857600 bytes (100 MB)", + "response": "File too large" + }, + "label": "file upload" + }, + { + "detail": { + "cause": "File upload rejected by Llama Stack: File size exceeds limit", + "response": "Invalid file upload" + }, + "label": "backend rejection" + } + ] + }, "ForbiddenResponse": { "properties": { "status_code": { @@ -8882,6 +10562,20 @@ "response": "Mcp Server not found" }, "label": "mcp server" + }, + { + "detail": { + "cause": "Vector Store with ID vs_abc123 does not exist", + "response": "Vector Store not found" + }, + "label": "vector store" + }, + { + "detail": { + "cause": "File with ID file_abc123 does not exist", + "response": "File not found" + }, + "label": "file" } ] }, @@ -9834,131 +11528,19 @@ }, "OpenAIResponseMCPApprovalResponse": { "properties": { - "approval_request_id": { - "type": "string", - "title": "Approval Request Id" - }, - "approve": { - "type": "boolean", - "title": "Approve" - }, - "type": { - "type": "string", - "const": "mcp_approval_response", - "title": "Type", - "default": "mcp_approval_response" - }, - "id": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Id" - }, - "reason": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Reason" - } - }, - "type": "object", - "required": [ - "approval_request_id", - "approve" - ], - "title": "OpenAIResponseMCPApprovalResponse", - "description": "A response to an MCP approval request." - }, - "OpenAIResponseMessage-Input": { - "properties": { - "content": { - "anyOf": [ - { - "type": "string" - }, - { - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/OpenAIResponseInputMessageContentText" - }, - { - "$ref": "#/components/schemas/OpenAIResponseInputMessageContentImage" - }, - { - "$ref": "#/components/schemas/OpenAIResponseInputMessageContentFile" - } - ], - "discriminator": { - "propertyName": "type", - "mapping": { - "input_file": "#/components/schemas/OpenAIResponseInputMessageContentFile", - "input_image": "#/components/schemas/OpenAIResponseInputMessageContentImage", - "input_text": "#/components/schemas/OpenAIResponseInputMessageContentText" - } - } - }, - "type": "array" - }, - { - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/OpenAIResponseOutputMessageContentOutputText-Input" - }, - { - "$ref": "#/components/schemas/OpenAIResponseContentPartRefusal" - } - ], - "discriminator": { - "propertyName": "type", - "mapping": { - "output_text": "#/components/schemas/OpenAIResponseOutputMessageContentOutputText-Input", - "refusal": "#/components/schemas/OpenAIResponseContentPartRefusal" - } - } - }, - "type": "array" - } - ], - "title": "Content" - }, - "role": { - "anyOf": [ - { - "type": "string", - "const": "system" - }, - { - "type": "string", - "const": "developer" - }, - { - "type": "string", - "const": "user" - }, - { - "type": "string", - "const": "assistant" - } - ], - "title": "Role" + "approval_request_id": { + "type": "string", + "title": "Approval Request Id" + }, + "approve": { + "type": "boolean", + "title": "Approve" }, "type": { "type": "string", - "const": "message", + "const": "mcp_approval_response", "title": "Type", - "default": "message" + "default": "mcp_approval_response" }, "id": { "anyOf": [ @@ -9971,7 +11553,7 @@ ], "title": "Id" }, - "status": { + "reason": { "anyOf": [ { "type": "string" @@ -9980,18 +11562,18 @@ "type": "null" } ], - "title": "Status" + "title": "Reason" } }, "type": "object", "required": [ - "content", - "role" + "approval_request_id", + "approve" ], - "title": "OpenAIResponseMessage", - "description": "Corresponds to the various Message types in the Responses API.\nThey are all under one type because the Responses API gives them all\nthe same \"type\" value, and there is no way to tell them apart in certain\nscenarios." + "title": "OpenAIResponseMCPApprovalResponse", + "description": "A response to an MCP approval request." }, - "OpenAIResponseMessage-Output": { + "OpenAIResponseMessage": { "properties": { "content": { "anyOf": [ @@ -10026,7 +11608,7 @@ "items": { "oneOf": [ { - "$ref": "#/components/schemas/OpenAIResponseOutputMessageContentOutputText-Output" + "$ref": "#/components/schemas/OpenAIResponseOutputMessageContentOutputText" }, { "$ref": "#/components/schemas/OpenAIResponseContentPartRefusal" @@ -10035,7 +11617,7 @@ "discriminator": { "propertyName": "type", "mapping": { - "output_text": "#/components/schemas/OpenAIResponseOutputMessageContentOutputText-Output", + "output_text": "#/components/schemas/OpenAIResponseOutputMessageContentOutputText", "refusal": "#/components/schemas/OpenAIResponseContentPartRefusal" } } @@ -10103,69 +11685,7 @@ "title": "OpenAIResponseMessage", "description": "Corresponds to the various Message types in the Responses API.\nThey are all under one type because the Responses API gives them all\nthe same \"type\" value, and there is no way to tell them apart in certain\nscenarios." }, - "OpenAIResponseOutputMessageContentOutputText-Input": { - "properties": { - "text": { - "type": "string", - "title": "Text" - }, - "type": { - "type": "string", - "const": "output_text", - "title": "Type", - "default": "output_text" - }, - "annotations": { - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/OpenAIResponseAnnotationFileCitation" - }, - { - "$ref": "#/components/schemas/OpenAIResponseAnnotationCitation" - }, - { - "$ref": "#/components/schemas/OpenAIResponseAnnotationContainerFileCitation" - }, - { - "$ref": "#/components/schemas/OpenAIResponseAnnotationFilePath" - } - ], - "discriminator": { - "propertyName": "type", - "mapping": { - "container_file_citation": "#/components/schemas/OpenAIResponseAnnotationContainerFileCitation", - "file_citation": "#/components/schemas/OpenAIResponseAnnotationFileCitation", - "file_path": "#/components/schemas/OpenAIResponseAnnotationFilePath", - "url_citation": "#/components/schemas/OpenAIResponseAnnotationCitation" - } - } - }, - "type": "array", - "title": "Annotations" - }, - "logprobs": { - "anyOf": [ - { - "items": { - "$ref": "#/components/schemas/OpenAITokenLogProb" - }, - "type": "array" - }, - { - "type": "null" - } - ], - "title": "Logprobs" - } - }, - "type": "object", - "required": [ - "text" - ], - "title": "OpenAIResponseOutputMessageContentOutputText" - }, - "OpenAIResponseOutputMessageContentOutputText-Output": { + "OpenAIResponseOutputMessageContentOutputText": { "properties": { "text": { "type": "string", @@ -12144,7 +13664,7 @@ "ResponseItem": { "anyOf": [ { - "$ref": "#/components/schemas/OpenAIResponseMessage-Input" + "$ref": "#/components/schemas/OpenAIResponseMessage" }, { "$ref": "#/components/schemas/OpenAIResponseOutputMessageWebSearchToolCall" @@ -12543,7 +14063,7 @@ "items": { "oneOf": [ { - "$ref": "#/components/schemas/OpenAIResponseMessage-Output" + "$ref": "#/components/schemas/OpenAIResponseMessage" }, { "$ref": "#/components/schemas/OpenAIResponseOutputMessageWebSearchToolCall" @@ -12572,7 +14092,7 @@ "mcp_approval_request": "#/components/schemas/OpenAIResponseMCPApprovalRequest", "mcp_call": "#/components/schemas/OpenAIResponseOutputMessageMCPCall", "mcp_list_tools": "#/components/schemas/OpenAIResponseOutputMessageMCPListTools", - "message": "#/components/schemas/OpenAIResponseMessage-Output", + "message": "#/components/schemas/OpenAIResponseMessage", "web_search_call": "#/components/schemas/OpenAIResponseOutputMessageWebSearchToolCall" } } @@ -12725,31 +14245,326 @@ { "type": "null" } - ], - "title": "Tool Choice" + ], + "title": "Tool Choice" + }, + "truncation": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Truncation" + }, + "usage": { + "anyOf": [ + { + "$ref": "#/components/schemas/OpenAIResponseUsage" + }, + { + "type": "null" + } + ] + }, + "instructions": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Instructions" + }, + "max_tool_calls": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Max Tool Calls" + }, + "reasoning": { + "anyOf": [ + { + "$ref": "#/components/schemas/OpenAIResponseReasoning" + }, + { + "type": "null" + } + ] + }, + "max_output_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Max Output Tokens" + }, + "safety_identifier": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Safety Identifier" + }, + "metadata": { + "anyOf": [ + { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Metadata" + }, + "store": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Store" + }, + "conversation": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Conversation" + }, + "available_quotas": { + "additionalProperties": { + "type": "integer" + }, + "type": "object", + "title": "Available Quotas" + }, + "output_text": { + "type": "string", + "title": "Output Text" + } + }, + "type": "object", + "required": [ + "created_at", + "id", + "model", + "output", + "status", + "available_quotas", + "output_text" + ], + "title": "ResponsesResponse", + "description": "Model representing a response from the Responses API following LCORE specification.\n\nAttributes:\n created_at: Unix timestamp when the response was created.\n completed_at: Unix timestamp when the response was completed, if applicable.\n error: Error details if the response failed or was blocked.\n id: Unique identifier for this response.\n model: Model identifier in \"provider/model\" format used for generation.\n object: Object type identifier, always \"response\".\n output: List of structured output items containing messages, tool calls, and\n other content. This is the primary response content.\n parallel_tool_calls: Whether the model can make multiple tool calls in parallel.\n previous_response_id: Identifier of the previous response in a multi-turn\n conversation.\n prompt: The input prompt object that was sent to the model.\n status: Current status of the response (e.g., \"completed\", \"blocked\",\n \"in_progress\").\n temperature: Temperature parameter used for generation (controls randomness).\n text: Text response configuration object used for OpenAI responses.\n top_p: Top-p sampling parameter used for generation.\n tools: List of tools available to the model during generation.\n tool_choice: Tool selection strategy used (e.g., \"auto\", \"required\", \"none\").\n truncation: Strategy used for handling content that exceeds context limits.\n usage: Token usage statistics including input_tokens, output_tokens, and\n total_tokens.\n instructions: System instructions or guidelines provided to the model.\n max_tool_calls: Maximum number of tool calls allowed in a single response.\n reasoning: Reasoning configuration (effort level) used for the response.\n max_output_tokens: Upper bound for tokens generated in the response.\n safety_identifier: Safety/guardrail identifier applied to the request.\n metadata: Additional metadata dictionary with custom key-value pairs.\n store: Whether the response was stored.\n conversation: Conversation ID linking this response to a conversation thread\n (LCORE-specific).\n available_quotas: Remaining token quotas for the user (LCORE-specific).\n output_text: Aggregated text output from all output_text items in the\n output array.", + "examples": [ + { + "available_quotas": { + "daily": 1000, + "monthly": 50000 + }, + "completed_at": 1704067250, + "conversation": "0d21ba731f21f798dc9680125d5d6f493e4a7ab79f25670e", + "created_at": 1704067200, + "id": "resp_abc123", + "instructions": "You are a helpful assistant", + "model": "openai/gpt-4-turbo", + "object": "response", + "output": [ + { + "content": [ + { + "text": "Kubernetes is an open-source container orchestration system...", + "type": "output_text" + } + ], + "role": "assistant", + "type": "message" + } + ], + "output_text": "Kubernetes is an open-source container orchestration system...", + "parallel_tool_calls": true, + "status": "completed", + "store": true, + "temperature": 0.7, + "text": { + "format": { + "type": "text" + } + }, + "usage": { + "input_tokens": 100, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 50, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 150 + } + } + ], + "sse_example": "event: response.created\ndata: {\"type\":\"response.created\",\"sequence_number\":0,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"in_progress\",\"model\":\"openai/gpt-4o-mini\",\"output\":[],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{},\"output_text\":\"\"}}\n\nevent: response.output_item.added\ndata: {\"type\":\"response.output_item.added\",\"sequence_number\":1,\"response_id\":\"resp_abc\",\"output_index\":0,\"item\":{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"in_progress\",\"role\":\"assistant\",\"content\":[]}}\n\n...\n\nevent: response.completed\ndata: {\"type\":\"response.completed\",\"sequence_number\":30,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"completed\",\"model\":\"openai/gpt-4o-mini\",\"output\":[{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello! How can I help?\",\"annotations\":[]}]}],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"usage\":{\"input_tokens\":10,\"output_tokens\":6,\"total_tokens\":16,\"input_tokens_details\":{\"cached_tokens\":0},\"output_tokens_details\":{\"reasoning_tokens\":0}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{\"daily\":1000,\"monthly\":50000},\"output_text\":\"Hello! How can I help?\"}}\n\ndata: [DONE]\n\n" + }, + "RlsapiV1Attachment": { + "properties": { + "contents": { + "type": "string", + "maxLength": 65536, + "title": "Contents", + "description": "File contents read on client", + "default": "", + "examples": [ + "# Configuration file\nkey=value" + ] }, - "truncation": { + "mimetype": { + "type": "string", + "title": "Mimetype", + "description": "MIME type of the file", + "default": "", + "examples": [ + "text/plain", + "application/json" + ] + } + }, + "additionalProperties": false, + "type": "object", + "title": "RlsapiV1Attachment", + "description": "Attachment data from rlsapi v1 context.\n\nAttributes:\n contents: The textual contents of the file read on the client machine.\n mimetype: The MIME type of the file." + }, + "RlsapiV1CLA": { + "properties": { + "nevra": { + "type": "string", + "pattern": "^[a-zA-Z0-9._:+~\\-]*$", + "title": "Nevra", + "description": "CLA NEVRA identifier", + "default": "", + "examples": [ + "command-line-assistant-0:0.2.0-1.el9.noarch" + ] + }, + "version": { + "type": "string", + "pattern": "^[a-zA-Z0-9._\\-]*$", + "title": "Version", + "description": "Command line assistant version", + "default": "", + "examples": [ + "0.2.0" + ] + } + }, + "additionalProperties": false, + "type": "object", + "title": "RlsapiV1CLA", + "description": "Command Line Assistant information from rlsapi v1 context.\n\nAttributes:\n nevra: The NEVRA (Name-Epoch-Version-Release-Architecture) of the CLA.\n version: The version of the command line assistant." + }, + "RlsapiV1Configuration": { + "properties": { + "allow_verbose_infer": { + "type": "boolean", + "title": "Allow verbose infer", + "description": "Allow /v1/infer to return extended metadata (tool_calls, rag_chunks, token_usage) when the client sends \"include_metadata\": true. Should NOT be enabled in production. If production use is needed, consider RBAC-based access control via an Action.RLSAPI_V1_INFER authorization rule.", + "default": false + }, + "quota_subject": { "anyOf": [ { - "type": "string" + "type": "string", + "enum": [ + "user_id", + "org_id", + "system_id" + ] }, { "type": "null" } ], - "title": "Truncation" + "title": "Quota subject", + "description": "Identity field used as the quota subject for /v1/infer. When set, token quota enforcement is enabled for this endpoint. Requires quota_handlers to be configured. \"org_id\" and \"system_id\" require rh-identity authentication; falls back to user_id when rh-identity data is unavailable." + } + }, + "additionalProperties": false, + "type": "object", + "title": "RlsapiV1Configuration", + "description": "Configuration for the rlsapi v1 /infer endpoint.\n\nSettings specific to the RHEL Lightspeed Command Line Assistant (CLA)\nstateless inference endpoint. Kept separate from shared configuration\nsections so that CLA-specific options do not affect other endpoints." + }, + "RlsapiV1Context": { + "properties": { + "stdin": { + "type": "string", + "maxLength": 65536, + "title": "Stdin", + "description": "Redirect input from stdin", + "default": "", + "examples": [ + "piped input from previous command" + ] }, - "usage": { - "anyOf": [ - { - "$ref": "#/components/schemas/OpenAIResponseUsage" - }, - { - "type": "null" - } + "attachments": { + "$ref": "#/components/schemas/RlsapiV1Attachment", + "description": "File attachment data" + }, + "terminal": { + "$ref": "#/components/schemas/RlsapiV1Terminal", + "description": "Terminal output context" + }, + "systeminfo": { + "$ref": "#/components/schemas/RlsapiV1SystemInfo", + "description": "Client system information" + }, + "cla": { + "$ref": "#/components/schemas/RlsapiV1CLA", + "description": "Command line assistant metadata" + } + }, + "additionalProperties": false, + "type": "object", + "title": "RlsapiV1Context", + "description": "Context data for rlsapi v1 /infer request.\n\nAttributes:\n stdin: Redirect input read by command-line-assistant.\n attachments: Attachment object received by the client.\n terminal: Terminal object received by the client.\n systeminfo: System information object received by the client.\n cla: Command Line Assistant information." + }, + "RlsapiV1InferData": { + "properties": { + "text": { + "type": "string", + "title": "Text", + "description": "Generated response text", + "examples": [ + "To list files in Linux, use the `ls` command." ] }, - "instructions": { + "request_id": { "anyOf": [ { "type": "string" @@ -12758,733 +14573,919 @@ "type": "null" } ], - "title": "Instructions" + "title": "Request Id", + "description": "Unique request identifier", + "examples": [ + "01JDKR8N7QW9ZMXVGK3PB5TQWZ" + ] }, - "max_tool_calls": { + "tool_calls": { "anyOf": [ { - "type": "integer" + "items": { + "$ref": "#/components/schemas/ToolCallSummary" + }, + "type": "array" }, { "type": "null" } ], - "title": "Max Tool Calls" - }, - "reasoning": { - "anyOf": [ - { - "$ref": "#/components/schemas/OpenAIResponseReasoning" - }, - { - "type": "null" - } - ] + "title": "Tool Calls", + "description": "Tool calls made during inference (requires include_metadata=true)" }, - "max_output_tokens": { + "tool_results": { "anyOf": [ { - "type": "integer" + "items": { + "$ref": "#/components/schemas/ToolResultSummary" + }, + "type": "array" }, { "type": "null" } ], - "title": "Max Output Tokens" + "title": "Tool Results", + "description": "Results from tool calls (requires include_metadata=true)" }, - "safety_identifier": { + "rag_chunks": { "anyOf": [ { - "type": "string" + "items": { + "$ref": "#/components/schemas/RAGChunk" + }, + "type": "array" }, { "type": "null" } ], - "title": "Safety Identifier" + "title": "Rag Chunks", + "description": "Retrieved RAG documentation chunks (requires include_metadata=true)" }, - "metadata": { + "referenced_documents": { "anyOf": [ { - "additionalProperties": { - "type": "string" + "items": { + "$ref": "#/components/schemas/ReferencedDocument" }, - "type": "object" + "type": "array" }, { "type": "null" } ], - "title": "Metadata" + "title": "Referenced Documents", + "description": "Source documents referenced in answer (requires include_metadata=true)" }, - "store": { + "input_tokens": { "anyOf": [ { - "type": "boolean" + "type": "integer" }, { "type": "null" } ], - "title": "Store" + "title": "Input Tokens", + "description": "Number of input tokens consumed (requires include_metadata=true)" }, - "conversation": { + "output_tokens": { "anyOf": [ { - "type": "string" + "type": "integer" }, { "type": "null" } ], - "title": "Conversation" + "title": "Output Tokens", + "description": "Number of output tokens generated (requires include_metadata=true)" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "text" + ], + "title": "RlsapiV1InferData", + "description": "Response data for rlsapi v1 /infer endpoint.\n\nAttributes:\n text: The generated response text.\n request_id: Unique identifier for the request.\n tool_calls: MCP tool calls made during inference (verbose mode only).\n tool_results: Results from MCP tool calls (verbose mode only).\n rag_chunks: RAG chunks retrieved from documentation (verbose mode only).\n referenced_documents: Source documents referenced (verbose mode only).\n input_tokens: Number of input tokens consumed (verbose mode only).\n output_tokens: Number of output tokens generated (verbose mode only)." + }, + "RlsapiV1InferRequest": { + "properties": { + "question": { + "type": "string", + "maxLength": 10240, + "minLength": 1, + "title": "Question", + "description": "User question", + "examples": [ + "How do I list files?", + "How do I configure SELinux?" + ] }, - "available_quotas": { - "additionalProperties": { - "type": "integer" - }, - "type": "object", - "title": "Available Quotas" + "context": { + "$ref": "#/components/schemas/RlsapiV1Context", + "description": "Optional context (system info, terminal output, stdin, attachments)" + }, + "skip_rag": { + "type": "boolean", + "title": "Skip Rag", + "description": "Reserved for future use. RAG retrieval is not yet implemented.", + "default": false, + "examples": [ + false, + true + ] }, - "output_text": { - "type": "string", - "title": "Output Text" + "include_metadata": { + "type": "boolean", + "title": "Include Metadata", + "description": "[Development/Testing Only] Return extended response with debugging metadata (tool_calls, rag_chunks, tokens). Only honored when allow_verbose_infer is enabled. Not available in production.", + "default": false, + "examples": [ + false, + true + ] } }, + "additionalProperties": false, "type": "object", "required": [ - "created_at", - "id", - "model", - "output", - "status", - "available_quotas", - "output_text" + "question" ], - "title": "ResponsesResponse", - "description": "Model representing a response from the Responses API following LCORE specification.\n\nAttributes:\n created_at: Unix timestamp when the response was created.\n completed_at: Unix timestamp when the response was completed, if applicable.\n error: Error details if the response failed or was blocked.\n id: Unique identifier for this response.\n model: Model identifier in \"provider/model\" format used for generation.\n object: Object type identifier, always \"response\".\n output: List of structured output items containing messages, tool calls, and\n other content. This is the primary response content.\n parallel_tool_calls: Whether the model can make multiple tool calls in parallel.\n previous_response_id: Identifier of the previous response in a multi-turn\n conversation.\n prompt: The input prompt object that was sent to the model.\n status: Current status of the response (e.g., \"completed\", \"blocked\",\n \"in_progress\").\n temperature: Temperature parameter used for generation (controls randomness).\n text: Text response configuration object used for OpenAI responses.\n top_p: Top-p sampling parameter used for generation.\n tools: List of tools available to the model during generation.\n tool_choice: Tool selection strategy used (e.g., \"auto\", \"required\", \"none\").\n truncation: Strategy used for handling content that exceeds context limits.\n usage: Token usage statistics including input_tokens, output_tokens, and\n total_tokens.\n instructions: System instructions or guidelines provided to the model.\n max_tool_calls: Maximum number of tool calls allowed in a single response.\n reasoning: Reasoning configuration (effort level) used for the response.\n max_output_tokens: Upper bound for tokens generated in the response.\n safety_identifier: Safety/guardrail identifier applied to the request.\n metadata: Additional metadata dictionary with custom key-value pairs.\n store: Whether the response was stored.\n conversation: Conversation ID linking this response to a conversation thread\n (LCORE-specific).\n available_quotas: Remaining token quotas for the user (LCORE-specific).\n output_text: Aggregated text output from all output_text items in the\n output array.", + "title": "RlsapiV1InferRequest", + "description": "RHEL Lightspeed rlsapi v1 /infer request.\n\nAttributes:\n question: User question string.\n context: Context with system info, terminal output, etc. (defaults provided).\n skip_rag: Reserved for future use. RAG retrieval is not yet implemented.\n include_metadata: Request extended response with debugging metadata (dev/testing only).\n\nExample:\n ```python\n request = RlsapiV1InferRequest(\n question=\"How do I list files?\",\n context=RlsapiV1Context(\n systeminfo=RlsapiV1SystemInfo(os=\"RHEL\", version=\"9.3\"),\n terminal=RlsapiV1Terminal(output=\"bash: command not found\"),\n ),\n )\n ```" + }, + "RlsapiV1InferResponse": { + "properties": { + "data": { + "$ref": "#/components/schemas/RlsapiV1InferData", + "description": "Response data containing text and request_id" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "data" + ], + "title": "RlsapiV1InferResponse", + "description": "RHEL Lightspeed rlsapi v1 /infer response.\n\nAttributes:\n data: Response data containing text and request_id.", "examples": [ { - "available_quotas": { - "daily": 1000, - "monthly": 50000 - }, - "completed_at": 1704067250, - "conversation": "0d21ba731f21f798dc9680125d5d6f493e4a7ab79f25670e", - "created_at": 1704067200, - "id": "resp_abc123", - "instructions": "You are a helpful assistant", - "model": "openai/gpt-4-turbo", - "object": "response", - "output": [ - { - "content": [ - { - "text": "Kubernetes is an open-source container orchestration system...", - "type": "output_text" - } - ], - "role": "assistant", - "type": "message" - } - ], - "output_text": "Kubernetes is an open-source container orchestration system...", - "parallel_tool_calls": true, - "status": "completed", - "store": true, - "temperature": 0.7, - "text": { - "format": { - "type": "text" - } - }, - "usage": { - "input_tokens": 100, - "input_tokens_details": { - "cached_tokens": 0 - }, - "output_tokens": 50, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 150 + "data": { + "request_id": "01JDKR8N7QW9ZMXVGK3PB5TQWZ", + "text": "To list files in Linux, use the `ls` command." } } - ], - "sse_example": "event: response.created\ndata: {\"type\":\"response.created\",\"sequence_number\":0,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"in_progress\",\"model\":\"openai/gpt-4o-mini\",\"output\":[],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{},\"output_text\":\"\"}}\n\nevent: response.output_item.added\ndata: {\"type\":\"response.output_item.added\",\"sequence_number\":1,\"response_id\":\"resp_abc\",\"output_index\":0,\"item\":{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"in_progress\",\"role\":\"assistant\",\"content\":[]}}\n\n...\n\nevent: response.completed\ndata: {\"type\":\"response.completed\",\"sequence_number\":30,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"completed\",\"model\":\"openai/gpt-4o-mini\",\"output\":[{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello! How can I help?\",\"annotations\":[]}]}],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"usage\":{\"input_tokens\":10,\"output_tokens\":6,\"total_tokens\":16,\"input_tokens_details\":{\"cached_tokens\":0},\"output_tokens_details\":{\"reasoning_tokens\":0}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{\"daily\":1000,\"monthly\":50000},\"output_text\":\"Hello! How can I help?\"}}\n\ndata: [DONE]\n\n" + ] }, - "RlsapiV1Attachment": { + "RlsapiV1SystemInfo": { "properties": { - "contents": { + "os": { "type": "string", - "maxLength": 65536, - "title": "Contents", - "description": "File contents read on client", + "pattern": "^[a-zA-Z0-9._ \\-]*$", + "title": "Os", + "description": "Operating system name", "default": "", "examples": [ - "# Configuration file\nkey=value" + "RHEL" ] }, - "mimetype": { + "version": { "type": "string", - "title": "Mimetype", - "description": "MIME type of the file", + "pattern": "^[a-zA-Z0-9._ \\-]*$", + "title": "Version", + "description": "Operating system version", "default": "", "examples": [ - "text/plain", - "application/json" + "9.3", + "8.10" ] - } - }, - "additionalProperties": false, - "type": "object", - "title": "RlsapiV1Attachment", - "description": "Attachment data from rlsapi v1 context.\n\nAttributes:\n contents: The textual contents of the file read on the client machine.\n mimetype: The MIME type of the file." - }, - "RlsapiV1CLA": { - "properties": { - "nevra": { + }, + "arch": { "type": "string", - "pattern": "^[a-zA-Z0-9._:+~\\-]*$", - "title": "Nevra", - "description": "CLA NEVRA identifier", + "pattern": "^[a-zA-Z0-9._ \\-]*$", + "title": "Arch", + "description": "System architecture", "default": "", "examples": [ - "command-line-assistant-0:0.2.0-1.el9.noarch" + "x86_64", + "aarch64" ] }, - "version": { + "id": { "type": "string", "pattern": "^[a-zA-Z0-9._\\-]*$", - "title": "Version", - "description": "Command line assistant version", + "title": "Id", + "description": "Client machine ID", "default": "", "examples": [ - "0.2.0" + "01JDKR8N7QW9ZMXVGK3PB5TQWZ" ] } }, "additionalProperties": false, "type": "object", - "title": "RlsapiV1CLA", - "description": "Command Line Assistant information from rlsapi v1 context.\n\nAttributes:\n nevra: The NEVRA (Name-Epoch-Version-Release-Architecture) of the CLA.\n version: The version of the command line assistant." + "title": "RlsapiV1SystemInfo", + "description": "System information from rlsapi v1 context.\n\nAttributes:\n os: The operating system of the client machine.\n version: The version of the operating system.\n arch: The architecture of the client machine.\n system_id: The id of the client machine." }, - "RlsapiV1Configuration": { + "RlsapiV1Terminal": { "properties": { - "allow_verbose_infer": { - "type": "boolean", - "title": "Allow verbose infer", - "description": "Allow /v1/infer to return extended metadata (tool_calls, rag_chunks, token_usage) when the client sends \"include_metadata\": true. Should NOT be enabled in production. If production use is needed, consider RBAC-based access control via an Action.RLSAPI_V1_INFER authorization rule.", - "default": false - }, - "quota_subject": { - "anyOf": [ - { - "type": "string", - "enum": [ - "user_id", - "org_id", - "system_id" - ] - }, - { - "type": "null" - } - ], - "title": "Quota subject", - "description": "Identity field used as the quota subject for /v1/infer. When set, token quota enforcement is enabled for this endpoint. Requires quota_handlers to be configured. \"org_id\" and \"system_id\" require rh-identity authentication; falls back to user_id when rh-identity data is unavailable." + "output": { + "type": "string", + "maxLength": 65536, + "title": "Output", + "description": "Terminal output from client", + "default": "", + "examples": [ + "bash: command not found", + "Permission denied" + ] } }, "additionalProperties": false, "type": "object", - "title": "RlsapiV1Configuration", - "description": "Configuration for the rlsapi v1 /infer endpoint.\n\nSettings specific to the RHEL Lightspeed Command Line Assistant (CLA)\nstateless inference endpoint. Kept separate from shared configuration\nsections so that CLA-specific options do not affect other endpoints." + "title": "RlsapiV1Terminal", + "description": "Terminal output from rlsapi v1 context.\n\nAttributes:\n output: The textual contents of the terminal read on the client machine." }, - "RlsapiV1Context": { + "SQLiteDatabaseConfiguration": { "properties": { - "stdin": { + "db_path": { "type": "string", - "maxLength": 65536, - "title": "Stdin", - "description": "Redirect input from stdin", - "default": "", - "examples": [ - "piped input from previous command" - ] - }, - "attachments": { - "$ref": "#/components/schemas/RlsapiV1Attachment", - "description": "File attachment data" - }, - "terminal": { - "$ref": "#/components/schemas/RlsapiV1Terminal", - "description": "Terminal output context" - }, - "systeminfo": { - "$ref": "#/components/schemas/RlsapiV1SystemInfo", - "description": "Client system information" - }, - "cla": { - "$ref": "#/components/schemas/RlsapiV1CLA", - "description": "Command line assistant metadata" + "title": "DB path", + "description": "Path to file where SQLite database is stored" } }, "additionalProperties": false, "type": "object", - "title": "RlsapiV1Context", - "description": "Context data for rlsapi v1 /infer request.\n\nAttributes:\n stdin: Redirect input read by command-line-assistant.\n attachments: Attachment object received by the client.\n terminal: Terminal object received by the client.\n systeminfo: System information object received by the client.\n cla: Command Line Assistant information." + "required": [ + "db_path" + ], + "title": "SQLiteDatabaseConfiguration", + "description": "SQLite database configuration." }, - "RlsapiV1InferData": { + "SearchRankingOptions": { "properties": { - "text": { - "type": "string", - "title": "Text", - "description": "Generated response text", - "examples": [ - "To list files in Linux, use the `ls` command." - ] + "ranker": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Ranker" + }, + "score_threshold": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Score Threshold", + "default": 0.0 }, - "request_id": { + "alpha": { "anyOf": [ { - "type": "string" + "type": "number", + "maximum": 1.0, + "minimum": 0.0 }, { "type": "null" } ], - "title": "Request Id", - "description": "Unique request identifier", - "examples": [ - "01JDKR8N7QW9ZMXVGK3PB5TQWZ" - ] + "title": "Alpha", + "description": "Weight factor for weighted ranker" }, - "tool_calls": { + "impact_factor": { "anyOf": [ { - "items": { - "$ref": "#/components/schemas/ToolCallSummary" - }, - "type": "array" + "type": "number", + "exclusiveMinimum": 0.0 }, { "type": "null" } ], - "title": "Tool Calls", - "description": "Tool calls made during inference (requires include_metadata=true)" + "title": "Impact Factor", + "description": "Impact factor for RRF algorithm" }, - "tool_results": { + "weights": { "anyOf": [ { - "items": { - "$ref": "#/components/schemas/ToolResultSummary" + "additionalProperties": { + "type": "number" }, - "type": "array" + "type": "object" }, { "type": "null" } ], - "title": "Tool Results", - "description": "Results from tool calls (requires include_metadata=true)" + "title": "Weights", + "description": "Weights for combining vector, keyword, and neural scores. Keys: 'vector', 'keyword', 'neural'" }, - "rag_chunks": { + "model": { "anyOf": [ { - "items": { - "$ref": "#/components/schemas/RAGChunk" - }, - "type": "array" + "type": "string" }, { "type": "null" } ], - "title": "Rag Chunks", - "description": "Retrieved RAG documentation chunks (requires include_metadata=true)" + "title": "Model", + "description": "Model identifier for neural reranker" + } + }, + "type": "object", + "title": "SearchRankingOptions", + "description": "Options for ranking and filtering search results.\n\nThis class configures how search results are ranked and filtered. You can use algorithm-based\nrerankers (weighted, RRF) or neural rerankers. Defaults from VectorStoresConfig are\nused when parameters are not provided.\n\nExamples:\n # Weighted ranker with custom alpha\n SearchRankingOptions(ranker=\"weighted\", alpha=0.7)\n\n # RRF ranker with custom impact factor\n SearchRankingOptions(ranker=\"rrf\", impact_factor=50.0)\n\n # Use config defaults (just specify ranker type)\n SearchRankingOptions(ranker=\"weighted\") # Uses alpha from VectorStoresConfig\n\n # Score threshold filtering\n SearchRankingOptions(ranker=\"weighted\", score_threshold=0.5)\n\n:param ranker: (Optional) Name of the ranking algorithm to use. Supported values:\n - \"weighted\": Weighted combination of vector and keyword scores\n - \"rrf\": Reciprocal Rank Fusion algorithm\n - \"neural\": Neural reranking model (requires model parameter, Part II)\n Note: For OpenAI API compatibility, any string value is accepted, but only the above values are supported.\n:param score_threshold: (Optional) Minimum relevance score threshold for results. Default: 0.0\n:param alpha: (Optional) Weight factor for weighted ranker (0-1).\n - 0.0 = keyword only\n - 0.5 = equal weight (default)\n - 1.0 = vector only\n Only used when ranker=\"weighted\" and weights is not provided.\n Falls back to VectorStoresConfig.chunk_retrieval_params.weighted_search_alpha if not provided.\n:param impact_factor: (Optional) Impact factor (k) for RRF algorithm.\n Lower values emphasize higher-ranked results. Default: 60.0 (optimal from research).\n Only used when ranker=\"rrf\".\n Falls back to VectorStoresConfig.chunk_retrieval_params.rrf_impact_factor if not provided.\n:param weights: (Optional) Dictionary of weights for combining different signal types.\n Keys can be \"vector\", \"keyword\", \"neural\". Values should sum to 1.0.\n Used when combining algorithm-based reranking with neural reranking (Part II).\n Example: {\"vector\": 0.3, \"keyword\": 0.3, \"neural\": 0.4}\n:param model: (Optional) Model identifier for neural reranker (e.g., \"vllm/Qwen3-Reranker-0.6B\").\n Required when ranker=\"neural\" or when weights contains \"neural\" (Part II)." + }, + "SecurityScheme": { + "anyOf": [ + { + "$ref": "#/components/schemas/APIKeySecurityScheme" }, - "referenced_documents": { + { + "$ref": "#/components/schemas/HTTPAuthSecurityScheme" + }, + { + "$ref": "#/components/schemas/OAuth2SecurityScheme" + }, + { + "$ref": "#/components/schemas/OpenIdConnectSecurityScheme" + }, + { + "$ref": "#/components/schemas/MutualTLSSecurityScheme" + } + ], + "title": "SecurityScheme" + }, + "ServiceConfiguration": { + "properties": { + "host": { + "type": "string", + "title": "Host", + "description": "Service hostname", + "default": "localhost" + }, + "port": { + "type": "integer", + "exclusiveMinimum": 0.0, + "title": "Port", + "description": "Service port", + "default": 8080 + }, + "base_url": { "anyOf": [ { - "items": { - "$ref": "#/components/schemas/ReferencedDocument" - }, - "type": "array" + "type": "string" }, { "type": "null" } ], - "title": "Referenced Documents", - "description": "Source documents referenced in answer (requires include_metadata=true)" + "title": "Base URL", + "description": "Externally reachable base URL for the service; needed for A2A support." }, - "input_tokens": { + "auth_enabled": { + "type": "boolean", + "title": "Authentication enabled", + "description": "Enables the authentication subsystem", + "default": false + }, + "workers": { + "type": "integer", + "exclusiveMinimum": 0.0, + "title": "Number of workers", + "description": "Number of Uvicorn worker processes to start", + "default": 1 + }, + "color_log": { + "type": "boolean", + "title": "Color log", + "description": "Enables colorized logging", + "default": true + }, + "access_log": { + "type": "boolean", + "title": "Access log", + "description": "Enables logging of all access information", + "default": true + }, + "tls_config": { + "$ref": "#/components/schemas/TLSConfiguration", + "title": "TLS configuration", + "description": "Transport Layer Security configuration for HTTPS support" + }, + "root_path": { + "type": "string", + "title": "Root path", + "description": "ASGI root path for serving behind a reverse proxy on a subpath", + "default": "" + }, + "cors": { + "$ref": "#/components/schemas/CORSConfiguration", + "title": "CORS configuration", + "description": "Cross-Origin Resource Sharing configuration for cross-domain requests" + } + }, + "additionalProperties": false, + "type": "object", + "title": "ServiceConfiguration", + "description": "Service configuration.\n\nLightspeed Core Stack is a REST API service that accepts requests on a\nspecified hostname and port. It is also possible to enable authentication\nand specify the number of Uvicorn workers. When more workers are specified,\nthe service can handle requests concurrently." + }, + "ServiceUnavailableResponse": { + "properties": { + "status_code": { + "type": "integer", + "title": "Status Code", + "description": "HTTP status code for the errors response" + }, + "detail": { + "$ref": "#/components/schemas/DetailModel", + "description": "The detail model containing error summary and cause" + } + }, + "type": "object", + "required": [ + "status_code", + "detail" + ], + "title": "ServiceUnavailableResponse", + "description": "503 Backend Unavailable.", + "examples": [ + { + "detail": { + "cause": "Connection error while trying to reach backend service.", + "response": "Unable to connect to Llama Stack" + }, + "label": "llama stack" + }, + { + "detail": { + "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", + "response": "Unable to connect to Kubernetes API" + }, + "label": "kubernetes api" + } + ] + }, + "ShieldsResponse": { + "properties": { + "shields": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array", + "title": "Shields", + "description": "List of shields available" + } + }, + "type": "object", + "required": [ + "shields" + ], + "title": "ShieldsResponse", + "description": "Model representing a response to shields request.", + "examples": [ + { + "shields": [ + { + "identifier": "lightspeed_question_validity-shield", + "params": {}, + "provider_id": "lightspeed_question_validity", + "provider_resource_id": "lightspeed_question_validity-shield", + "type": "shield" + } + ] + } + ] + }, + "SplunkConfiguration": { + "properties": { + "enabled": { + "type": "boolean", + "title": "Enabled", + "description": "Enable or disable Splunk HEC integration.", + "default": false + }, + "url": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Input Tokens", - "description": "Number of input tokens consumed (requires include_metadata=true)" + "title": "HEC URL", + "description": "Splunk HEC endpoint URL." }, - "output_tokens": { + "token_path": { "anyOf": [ { - "type": "integer" + "type": "string", + "format": "file-path" }, { "type": "null" } ], - "title": "Output Tokens", - "description": "Number of output tokens generated (requires include_metadata=true)" + "title": "Token path", + "description": "Path to file containing the Splunk HEC authentication token." + }, + "index": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Index", + "description": "Target Splunk index for events." + }, + "source": { + "type": "string", + "title": "Source", + "description": "Event source identifier.", + "default": "lightspeed-stack" + }, + "timeout": { + "type": "integer", + "exclusiveMinimum": 0.0, + "title": "Timeout", + "description": "HTTP timeout in seconds for HEC requests.", + "default": 5 + }, + "verify_ssl": { + "type": "boolean", + "title": "Verify SSL", + "description": "Whether to verify SSL certificates for HEC endpoint.", + "default": true } }, "additionalProperties": false, "type": "object", - "required": [ - "text" - ], - "title": "RlsapiV1InferData", - "description": "Response data for rlsapi v1 /infer endpoint.\n\nAttributes:\n text: The generated response text.\n request_id: Unique identifier for the request.\n tool_calls: MCP tool calls made during inference (verbose mode only).\n tool_results: Results from MCP tool calls (verbose mode only).\n rag_chunks: RAG chunks retrieved from documentation (verbose mode only).\n referenced_documents: Source documents referenced (verbose mode only).\n input_tokens: Number of input tokens consumed (verbose mode only).\n output_tokens: Number of output tokens generated (verbose mode only)." + "title": "SplunkConfiguration", + "description": "Splunk HEC (HTTP Event Collector) configuration.\n\nSplunk HEC allows sending events directly to Splunk over HTTP/HTTPS.\nThis configuration is used to send telemetry events for inference\nrequests to the corporate Splunk deployment.\n\nUseful resources:\n\n - [Splunk HEC Docs](https://docs.splunk.com/Documentation/SplunkCloud)\n - [About HEC](https://docs.splunk.com/Documentation/Splunk/latest/Data)" }, - "RlsapiV1InferRequest": { + "StatusResponse": { "properties": { - "question": { + "functionality": { "type": "string", - "maxLength": 10240, - "minLength": 1, - "title": "Question", - "description": "User question", - "examples": [ - "How do I list files?", - "How do I configure SELinux?" - ] - }, - "context": { - "$ref": "#/components/schemas/RlsapiV1Context", - "description": "Optional context (system info, terminal output, stdin, attachments)" - }, - "skip_rag": { - "type": "boolean", - "title": "Skip Rag", - "description": "Reserved for future use. RAG retrieval is not yet implemented.", - "default": false, + "title": "Functionality", + "description": "The functionality of the service", "examples": [ - false, - true + "feedback" ] }, - "include_metadata": { - "type": "boolean", - "title": "Include Metadata", - "description": "[Development/Testing Only] Return extended response with debugging metadata (tool_calls, rag_chunks, tokens). Only honored when allow_verbose_infer is enabled. Not available in production.", - "default": false, + "status": { + "additionalProperties": true, + "type": "object", + "title": "Status", + "description": "The status of the service", "examples": [ - false, - true + { + "enabled": true + } ] } }, - "additionalProperties": false, "type": "object", "required": [ - "question" + "functionality", + "status" ], - "title": "RlsapiV1InferRequest", - "description": "RHEL Lightspeed rlsapi v1 /infer request.\n\nAttributes:\n question: User question string.\n context: Context with system info, terminal output, etc. (defaults provided).\n skip_rag: Reserved for future use. RAG retrieval is not yet implemented.\n include_metadata: Request extended response with debugging metadata (dev/testing only).\n\nExample:\n ```python\n request = RlsapiV1InferRequest(\n question=\"How do I list files?\",\n context=RlsapiV1Context(\n systeminfo=RlsapiV1SystemInfo(os=\"RHEL\", version=\"9.3\"),\n terminal=RlsapiV1Terminal(output=\"bash: command not found\"),\n ),\n )\n ```" + "title": "StatusResponse", + "description": "Model representing a response to a status request.\n\nAttributes:\n functionality: The functionality of the service.\n status: The status of the service.\n\nExample:\n ```python\n status_response = StatusResponse(\n functionality=\"feedback\",\n status={\"enabled\": True},\n )\n ```", + "examples": [ + { + "functionality": "feedback", + "status": { + "enabled": true + } + } + ] }, - "RlsapiV1InferResponse": { + "StreamingInterruptRequest": { "properties": { - "data": { - "$ref": "#/components/schemas/RlsapiV1InferData", - "description": "Response data containing text and request_id" + "request_id": { + "type": "string", + "title": "Request Id", + "description": "The active streaming request ID to interrupt", + "examples": [ + "123e4567-e89b-12d3-a456-426614174000" + ] } }, "additionalProperties": false, "type": "object", "required": [ - "data" + "request_id" ], - "title": "RlsapiV1InferResponse", - "description": "RHEL Lightspeed rlsapi v1 /infer response.\n\nAttributes:\n data: Response data containing text and request_id.", + "title": "StreamingInterruptRequest", + "description": "Model representing a request to interrupt an active streaming query.\n\nAttributes:\n request_id: Unique ID of the active streaming request to interrupt.", "examples": [ { - "data": { - "request_id": "01JDKR8N7QW9ZMXVGK3PB5TQWZ", - "text": "To list files in Linux, use the `ls` command." - } + "request_id": "123e4567-e89b-12d3-a456-426614174000" } ] }, - "RlsapiV1SystemInfo": { + "StreamingInterruptResponse": { "properties": { - "os": { - "type": "string", - "pattern": "^[a-zA-Z0-9._ \\-]*$", - "title": "Os", - "description": "Operating system name", - "default": "", - "examples": [ - "RHEL" - ] - }, - "version": { + "request_id": { "type": "string", - "pattern": "^[a-zA-Z0-9._ \\-]*$", - "title": "Version", - "description": "Operating system version", - "default": "", + "title": "Request Id", + "description": "The streaming request ID targeted by the interrupt call", "examples": [ - "9.3", - "8.10" + "123e4567-e89b-12d3-a456-426614174000" ] }, - "arch": { - "type": "string", - "pattern": "^[a-zA-Z0-9._ \\-]*$", - "title": "Arch", - "description": "System architecture", - "default": "", + "interrupted": { + "type": "boolean", + "title": "Interrupted", + "description": "Whether an in-progress stream was interrupted", "examples": [ - "x86_64", - "aarch64" + true ] }, - "id": { - "type": "string", - "pattern": "^[a-zA-Z0-9._\\-]*$", - "title": "Id", - "description": "Client machine ID", - "default": "", - "examples": [ - "01JDKR8N7QW9ZMXVGK3PB5TQWZ" - ] - } - }, - "additionalProperties": false, - "type": "object", - "title": "RlsapiV1SystemInfo", - "description": "System information from rlsapi v1 context.\n\nAttributes:\n os: The operating system of the client machine.\n version: The version of the operating system.\n arch: The architecture of the client machine.\n system_id: The id of the client machine." - }, - "RlsapiV1Terminal": { - "properties": { - "output": { + "message": { "type": "string", - "maxLength": 65536, - "title": "Output", - "description": "Terminal output from client", - "default": "", + "title": "Message", + "description": "Human-readable interruption status message", "examples": [ - "bash: command not found", - "Permission denied" + "Streaming request interrupted" ] } }, - "additionalProperties": false, - "type": "object", - "title": "RlsapiV1Terminal", - "description": "Terminal output from rlsapi v1 context.\n\nAttributes:\n output: The textual contents of the terminal read on the client machine." - }, - "SQLiteDatabaseConfiguration": { - "properties": { - "db_path": { - "type": "string", - "title": "DB path", - "description": "Path to file where SQLite database is stored" - } - }, - "additionalProperties": false, "type": "object", "required": [ - "db_path" + "request_id", + "interrupted", + "message" ], - "title": "SQLiteDatabaseConfiguration", - "description": "SQLite database configuration." + "title": "StreamingInterruptResponse", + "description": "Model representing a response to a streaming interrupt request.\n\nAttributes:\n request_id: The streaming request ID targeted by the interrupt call.\n interrupted: Whether an in-progress stream was interrupted.\n message: Human-readable interruption status message.\n\nExample:\n ```python\n response = StreamingInterruptResponse(\n request_id=\"123e4567-e89b-12d3-a456-426614174000\",\n interrupted=True,\n message=\"Streaming request interrupted\",\n )\n ```", + "examples": [ + { + "interrupted": true, + "message": "Streaming request interrupted", + "request_id": "123e4567-e89b-12d3-a456-426614174000" + } + ] }, - "SearchRankingOptions": { + "TLSConfiguration": { "properties": { - "ranker": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Ranker" - }, - "score_threshold": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ], - "title": "Score Threshold", - "default": 0.0 - }, - "alpha": { - "anyOf": [ - { - "type": "number", - "maximum": 1.0, - "minimum": 0.0 - }, - { - "type": "null" - } - ], - "title": "Alpha", - "description": "Weight factor for weighted ranker" - }, - "impact_factor": { + "tls_certificate_path": { "anyOf": [ { - "type": "number", - "exclusiveMinimum": 0.0 + "type": "string", + "format": "file-path" }, { "type": "null" } ], - "title": "Impact Factor", - "description": "Impact factor for RRF algorithm" + "title": "TLS certificate path", + "description": "SSL/TLS certificate file path for HTTPS support." }, - "weights": { + "tls_key_path": { "anyOf": [ { - "additionalProperties": { - "type": "number" - }, - "type": "object" + "type": "string", + "format": "file-path" }, { "type": "null" } ], - "title": "Weights", - "description": "Weights for combining vector, keyword, and neural scores. Keys: 'vector', 'keyword', 'neural'" + "title": "TLS key path", + "description": "SSL/TLS private key file path for HTTPS support." }, - "model": { + "tls_key_password": { "anyOf": [ { - "type": "string" + "type": "string", + "format": "file-path" }, { "type": "null" } ], - "title": "Model", - "description": "Model identifier for neural reranker" + "title": "SSL/TLS key password path", + "description": "Path to file containing the password to decrypt the SSL/TLS private key." } }, + "additionalProperties": false, "type": "object", - "title": "SearchRankingOptions", - "description": "Options for ranking and filtering search results.\n\nThis class configures how search results are ranked and filtered. You can use algorithm-based\nrerankers (weighted, RRF) or neural rerankers. Defaults from VectorStoresConfig are\nused when parameters are not provided.\n\nExamples:\n # Weighted ranker with custom alpha\n SearchRankingOptions(ranker=\"weighted\", alpha=0.7)\n\n # RRF ranker with custom impact factor\n SearchRankingOptions(ranker=\"rrf\", impact_factor=50.0)\n\n # Use config defaults (just specify ranker type)\n SearchRankingOptions(ranker=\"weighted\") # Uses alpha from VectorStoresConfig\n\n # Score threshold filtering\n SearchRankingOptions(ranker=\"weighted\", score_threshold=0.5)\n\n:param ranker: (Optional) Name of the ranking algorithm to use. Supported values:\n - \"weighted\": Weighted combination of vector and keyword scores\n - \"rrf\": Reciprocal Rank Fusion algorithm\n - \"neural\": Neural reranking model (requires model parameter, Part II)\n Note: For OpenAI API compatibility, any string value is accepted, but only the above values are supported.\n:param score_threshold: (Optional) Minimum relevance score threshold for results. Default: 0.0\n:param alpha: (Optional) Weight factor for weighted ranker (0-1).\n - 0.0 = keyword only\n - 0.5 = equal weight (default)\n - 1.0 = vector only\n Only used when ranker=\"weighted\" and weights is not provided.\n Falls back to VectorStoresConfig.chunk_retrieval_params.weighted_search_alpha if not provided.\n:param impact_factor: (Optional) Impact factor (k) for RRF algorithm.\n Lower values emphasize higher-ranked results. Default: 60.0 (optimal from research).\n Only used when ranker=\"rrf\".\n Falls back to VectorStoresConfig.chunk_retrieval_params.rrf_impact_factor if not provided.\n:param weights: (Optional) Dictionary of weights for combining different signal types.\n Keys can be \"vector\", \"keyword\", \"neural\". Values should sum to 1.0.\n Used when combining algorithm-based reranking with neural reranking (Part II).\n Example: {\"vector\": 0.3, \"keyword\": 0.3, \"neural\": 0.4}\n:param model: (Optional) Model identifier for neural reranker (e.g., \"vllm/Qwen3-Reranker-0.6B\").\n Required when ranker=\"neural\" or when weights contains \"neural\" (Part II)." + "title": "TLSConfiguration", + "description": "TLS configuration.\n\nTransport Layer Security (TLS) is a cryptographic protocol designed to\nprovide communications security over a computer network, such as the\nInternet. The protocol is widely used in applications such as email,\ninstant messaging, and voice over IP, but its use in securing HTTPS remains\nthe most publicly visible.\n\nUseful resources:\n\n - [FastAPI HTTPS Deployment](https://fastapi.tiangolo.com/deployment/https/)\n - [Transport Layer Security Overview](https://en.wikipedia.org/wiki/Transport_Layer_Security)\n - [What is TLS](https://www.ssltrust.eu/learning/ssl/transport-layer-security-tls)" }, - "SecurityScheme": { - "anyOf": [ - { - "$ref": "#/components/schemas/APIKeySecurityScheme" - }, - { - "$ref": "#/components/schemas/HTTPAuthSecurityScheme" + "ToolCallSummary": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "ID of the tool call" }, - { - "$ref": "#/components/schemas/OAuth2SecurityScheme" + "name": { + "type": "string", + "title": "Name", + "description": "Name of the tool called" }, - { - "$ref": "#/components/schemas/OpenIdConnectSecurityScheme" + "args": { + "additionalProperties": true, + "type": "object", + "title": "Args", + "description": "Arguments passed to the tool" }, - { - "$ref": "#/components/schemas/MutualTLSSecurityScheme" + "type": { + "type": "string", + "title": "Type", + "description": "Type indicator for tool call", + "default": "tool_call" } + }, + "type": "object", + "required": [ + "id", + "name" ], - "title": "SecurityScheme" + "title": "ToolCallSummary", + "description": "Model representing a tool call made during response generation (for tool_calls list)." }, - "ServiceConfiguration": { + "ToolResultSummary": { "properties": { - "host": { + "id": { "type": "string", - "title": "Host", - "description": "Service hostname", - "default": "localhost" + "title": "Id", + "description": "ID of the tool call/result, matches the corresponding tool call 'id'" }, - "port": { - "type": "integer", - "exclusiveMinimum": 0.0, - "title": "Port", - "description": "Service port", - "default": 8080 + "status": { + "type": "string", + "title": "Status", + "description": "Status of the tool execution (e.g., 'success')" }, - "base_url": { - "anyOf": [ - { - "type": "string" - }, + "content": { + "type": "string", + "title": "Content", + "description": "Content/result returned from the tool" + }, + "type": { + "type": "string", + "title": "Type", + "description": "Type indicator for tool result", + "default": "tool_result" + }, + "round": { + "type": "integer", + "title": "Round", + "description": "Round number or step of tool execution" + } + }, + "type": "object", + "required": [ + "id", + "status", + "content", + "round" + ], + "title": "ToolResultSummary", + "description": "Model representing a result from a tool call (for tool_results list)." + }, + "ToolsResponse": { + "properties": { + "tools": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array", + "title": "Tools", + "description": "List of tools available from all configured MCP servers and built-in toolgroups" + } + }, + "type": "object", + "required": [ + "tools" + ], + "title": "ToolsResponse", + "description": "Model representing a response to tools request.", + "examples": [ + { + "tools": [ { - "type": "null" + "description": "Read contents of a file from the filesystem", + "identifier": "filesystem_read", + "parameters": [ + { + "description": "Path to the file to read", + "name": "path", + "parameter_type": "string", + "required": true + } + ], + "provider_id": "model-context-protocol", + "server_source": "http://localhost:3000", + "toolgroup_id": "filesystem-tools", + "type": "tool" } - ], - "title": "Base URL", - "description": "Externally reachable base URL for the service; needed for A2A support." + ] + } + ] + }, + "UnauthorizedResponse": { + "properties": { + "status_code": { + "type": "integer", + "title": "Status Code", + "description": "HTTP status code for the errors response" }, - "auth_enabled": { - "type": "boolean", - "title": "Authentication enabled", - "description": "Enables the authentication subsystem", - "default": false + "detail": { + "$ref": "#/components/schemas/DetailModel", + "description": "The detail model containing error summary and cause" + } + }, + "type": "object", + "required": [ + "status_code", + "detail" + ], + "title": "UnauthorizedResponse", + "description": "401 Unauthorized - Missing or invalid credentials.", + "examples": [ + { + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + }, + "label": "missing header" }, - "workers": { - "type": "integer", - "exclusiveMinimum": 0.0, - "title": "Number of workers", - "description": "Number of Uvicorn worker processes to start", - "default": 1 + { + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + }, + "label": "missing token" }, - "color_log": { - "type": "boolean", - "title": "Color log", - "description": "Enables colorized logging", - "default": true + { + "detail": { + "cause": "Token has expired", + "response": "Missing or invalid credentials provided by client" + }, + "label": "expired token" }, - "access_log": { - "type": "boolean", - "title": "Access log", - "description": "Enables logging of all access information", - "default": true + { + "detail": { + "cause": "Invalid token signature", + "response": "Missing or invalid credentials provided by client" + }, + "label": "invalid signature" }, - "tls_config": { - "$ref": "#/components/schemas/TLSConfiguration", - "title": "TLS configuration", - "description": "Transport Layer Security configuration for HTTPS support" + { + "detail": { + "cause": "Token signed by unknown key", + "response": "Missing or invalid credentials provided by client" + }, + "label": "invalid key" }, - "root_path": { - "type": "string", - "title": "Root path", - "description": "ASGI root path for serving behind a reverse proxy on a subpath", - "default": "" + { + "detail": { + "cause": "Token missing claim: user_id", + "response": "Missing or invalid credentials provided by client" + }, + "label": "missing claim" }, - "cors": { - "$ref": "#/components/schemas/CORSConfiguration", - "title": "CORS configuration", - "description": "Cross-Origin Resource Sharing configuration for cross-domain requests" - } - }, - "additionalProperties": false, - "type": "object", - "title": "ServiceConfiguration", - "description": "Service configuration.\n\nLightspeed Core Stack is a REST API service that accepts requests on a\nspecified hostname and port. It is also possible to enable authentication\nand specify the number of Uvicorn workers. When more workers are specified,\nthe service can handle requests concurrently." + { + "detail": { + "cause": "Invalid or expired Kubernetes token", + "response": "Missing or invalid credentials provided by client" + }, + "label": "invalid k8s token" + }, + { + "detail": { + "cause": "Authentication key server returned invalid data", + "response": "Missing or invalid credentials provided by client" + }, + "label": "invalid jwk token" + } + ] }, - "ServiceUnavailableResponse": { + "UnprocessableEntityResponse": { "properties": { "status_code": { "type": "integer", @@ -13501,66 +15502,41 @@ "status_code", "detail" ], - "title": "ServiceUnavailableResponse", - "description": "503 Backend Unavailable.", + "title": "UnprocessableEntityResponse", + "description": "422 Unprocessable Entity - Request validation failed.", "examples": [ { "detail": { - "cause": "Connection error while trying to reach backend service.", - "response": "Unable to connect to Llama Stack" + "cause": "Invalid request format. The request body could not be parsed.", + "response": "Invalid request format" }, - "label": "llama stack" + "label": "invalid format" }, { "detail": { - "cause": "Failed to connect to Kubernetes API: Service Unavailable (status 503)", - "response": "Unable to connect to Kubernetes API" - }, - "label": "kubernetes api" - } - ] - }, - "ShieldsResponse": { - "properties": { - "shields": { - "items": { - "additionalProperties": true, - "type": "object" + "cause": "Missing required attributes: ['query', 'model', 'provider']", + "response": "Missing required attributes" }, - "type": "array", - "title": "Shields", - "description": "List of shields available" - } - }, - "type": "object", - "required": [ - "shields" - ], - "title": "ShieldsResponse", - "description": "Model representing a response to shields request.", - "examples": [ + "label": "missing attributes" + }, { - "shields": [ - { - "identifier": "lightspeed_question_validity-shield", - "params": {}, - "provider_id": "lightspeed_question_validity", - "provider_resource_id": "lightspeed_question_validity-shield", - "type": "shield" - } - ] + "detail": { + "cause": "Invalid attachment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']", + "response": "Invalid attribute value" + }, + "label": "invalid value" } ] }, - "SplunkConfiguration": { + "UserDataCollection": { "properties": { - "enabled": { + "feedback_enabled": { "type": "boolean", - "title": "Enabled", - "description": "Enable or disable Splunk HEC integration.", + "title": "Feedback enabled", + "description": "When set to true the user feedback is stored and later sent for analysis.", "default": false }, - "url": { + "feedback_storage": { "anyOf": [ { "type": "string" @@ -13569,23 +15545,16 @@ "type": "null" } ], - "title": "HEC URL", - "description": "Splunk HEC endpoint URL." + "title": "Feedback storage directory", + "description": "Path to directory where feedback will be saved for further processing." }, - "token_path": { - "anyOf": [ - { - "type": "string", - "format": "file-path" - }, - { - "type": "null" - } - ], - "title": "Token path", - "description": "Path to file containing the Splunk HEC authentication token." + "transcripts_enabled": { + "type": "boolean", + "title": "Transcripts enabled", + "description": "When set to true the conversation history is stored and later sent for analysis.", + "default": false }, - "index": { + "transcripts_storage": { "anyOf": [ { "type": "string" @@ -13594,503 +15563,601 @@ "type": "null" } ], - "title": "Index", - "description": "Target Splunk index for events." - }, - "source": { - "type": "string", - "title": "Source", - "description": "Event source identifier.", - "default": "lightspeed-stack" - }, - "timeout": { - "type": "integer", - "exclusiveMinimum": 0.0, - "title": "Timeout", - "description": "HTTP timeout in seconds for HEC requests.", - "default": 5 - }, - "verify_ssl": { - "type": "boolean", - "title": "Verify SSL", - "description": "Whether to verify SSL certificates for HEC endpoint.", - "default": true + "title": "Transcripts storage directory", + "description": "Path to directory where conversation history will be saved for further processing." } }, "additionalProperties": false, "type": "object", - "title": "SplunkConfiguration", - "description": "Splunk HEC (HTTP Event Collector) configuration.\n\nSplunk HEC allows sending events directly to Splunk over HTTP/HTTPS.\nThis configuration is used to send telemetry events for inference\nrequests to the corporate Splunk deployment.\n\nUseful resources:\n\n - [Splunk HEC Docs](https://docs.splunk.com/Documentation/SplunkCloud)\n - [About HEC](https://docs.splunk.com/Documentation/Splunk/latest/Data)" + "title": "UserDataCollection", + "description": "User data collection configuration." }, - "StatusResponse": { + "ValidationError": { "properties": { - "functionality": { + "loc": { + "items": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "integer" + } + ] + }, + "type": "array", + "title": "Location" + }, + "msg": { "type": "string", - "title": "Functionality", - "description": "The functionality of the service", - "examples": [ - "feedback" - ] + "title": "Message" }, - "status": { - "additionalProperties": true, + "type": { + "type": "string", + "title": "Error Type" + }, + "input": { + "title": "Input" + }, + "ctx": { "type": "object", - "title": "Status", - "description": "The status of the service", - "examples": [ - { - "enabled": true - } - ] + "title": "Context" } }, "type": "object", "required": [ - "functionality", - "status" + "loc", + "msg", + "type" ], - "title": "StatusResponse", - "description": "Model representing a response to a status request.\n\nAttributes:\n functionality: The functionality of the service.\n status: The status of the service.\n\nExample:\n ```python\n status_response = StatusResponse(\n functionality=\"feedback\",\n status={\"enabled\": True},\n )\n ```", - "examples": [ - { - "functionality": "feedback", - "status": { - "enabled": true - } - } - ] + "title": "ValidationError" }, - "StreamingInterruptRequest": { + "VectorStoreCreateRequest": { "properties": { - "request_id": { + "name": { "type": "string", - "title": "Request Id", - "description": "The active streaming request ID to interrupt", + "maxLength": 256, + "minLength": 1, + "title": "Name", + "description": "Name of the vector store", "examples": [ - "123e4567-e89b-12d3-a456-426614174000" + "my_vector_store" ] - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "request_id" - ], - "title": "StreamingInterruptRequest", - "description": "Model representing a request to interrupt an active streaming query.\n\nAttributes:\n request_id: Unique ID of the active streaming request to interrupt.", - "examples": [ - { - "request_id": "123e4567-e89b-12d3-a456-426614174000" - } - ] - }, - "StreamingInterruptResponse": { - "properties": { - "request_id": { - "type": "string", - "title": "Request Id", - "description": "The streaming request ID targeted by the interrupt call", + }, + "embedding_model": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Embedding Model", + "description": "Embedding model to use for the vector store", "examples": [ - "123e4567-e89b-12d3-a456-426614174000" + "text-embedding-ada-002" ] }, - "interrupted": { - "type": "boolean", - "title": "Interrupted", - "description": "Whether an in-progress stream was interrupted", + "embedding_dimension": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Embedding Dimension", + "description": "Dimension of the embedding vectors", + "examples": [ + 1536 + ] + }, + "chunking_strategy": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Chunking Strategy", + "description": "Chunking strategy configuration", + "examples": [ + { + "chunk_overlap": 50, + "chunk_size": 512, + "type": "fixed" + } + ] + }, + "provider_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Provider Id", + "description": "Vector store provider identifier", "examples": [ - true + "rhdh-docs" ] }, - "message": { - "type": "string", - "title": "Message", - "description": "Human-readable interruption status message", + "metadata": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Metadata", + "description": "Metadata dictionary for storing session information", "examples": [ - "Streaming request interrupted" + { + "session_id": "sess456", + "user_id": "user123" + } ] } }, + "additionalProperties": false, "type": "object", "required": [ - "request_id", - "interrupted", - "message" + "name" ], - "title": "StreamingInterruptResponse", - "description": "Model representing a response to a streaming interrupt request.\n\nAttributes:\n request_id: The streaming request ID targeted by the interrupt call.\n interrupted: Whether an in-progress stream was interrupted.\n message: Human-readable interruption status message.\n\nExample:\n ```python\n response = StreamingInterruptResponse(\n request_id=\"123e4567-e89b-12d3-a456-426614174000\",\n interrupted=True,\n message=\"Streaming request interrupted\",\n )\n ```", + "title": "VectorStoreCreateRequest", + "description": "Model representing a request to create a vector store.\n\nAttributes:\n name: Name of the vector store.\n embedding_model: Optional embedding model to use.\n embedding_dimension: Optional embedding dimension.\n chunking_strategy: Optional chunking strategy configuration.\n provider_id: Optional vector store provider identifier.\n metadata: Optional metadata dictionary for storing session information.", "examples": [ { - "interrupted": true, - "message": "Streaming request interrupted", - "request_id": "123e4567-e89b-12d3-a456-426614174000" + "embedding_dimension": 1536, + "embedding_model": "text-embedding-ada-002", + "metadata": { + "user_id": "user123" + }, + "name": "my_vector_store", + "provider_id": "rhdh-docs" } ] }, - "TLSConfiguration": { + "VectorStoreFileCreateRequest": { "properties": { - "tls_certificate_path": { + "file_id": { + "type": "string", + "minLength": 1, + "title": "File Id", + "description": "ID of the file to add to the vector store", + "examples": [ + "file-abc123" + ] + }, + "attributes": { "anyOf": [ { - "type": "string", - "format": "file-path" + "additionalProperties": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + }, + "type": "object" }, { "type": "null" } ], - "title": "TLS certificate path", - "description": "SSL/TLS certificate file path for HTTPS support." - }, - "tls_key_path": { - "anyOf": [ - { - "type": "string", - "format": "file-path" - }, + "title": "Attributes", + "description": "Set of up to 16 key-value pairs for storing additional information. Keys: strings (max 64 chars). Values: strings (max 512 chars), booleans, or numbers.", + "examples": [ { - "type": "null" + "created_at": "2026-04-04T15:20:00Z", + "updated_at": "2026-04-04T15:20:00Z" } - ], - "title": "TLS key path", - "description": "SSL/TLS private key file path for HTTPS support." + ] }, - "tls_key_password": { + "chunking_strategy": { "anyOf": [ { - "type": "string", - "format": "file-path" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "SSL/TLS key password path", - "description": "Path to file containing the password to decrypt the SSL/TLS private key." + "title": "Chunking Strategy", + "description": "Chunking strategy configuration for this file", + "examples": [ + { + "chunk_overlap": 50, + "chunk_size": 512, + "type": "fixed" + } + ] } }, "additionalProperties": false, "type": "object", - "title": "TLSConfiguration", - "description": "TLS configuration.\n\nTransport Layer Security (TLS) is a cryptographic protocol designed to\nprovide communications security over a computer network, such as the\nInternet. The protocol is widely used in applications such as email,\ninstant messaging, and voice over IP, but its use in securing HTTPS remains\nthe most publicly visible.\n\nUseful resources:\n\n - [FastAPI HTTPS Deployment](https://fastapi.tiangolo.com/deployment/https/)\n - [Transport Layer Security Overview](https://en.wikipedia.org/wiki/Transport_Layer_Security)\n - [What is TLS](https://www.ssltrust.eu/learning/ssl/transport-layer-security-tls)" - }, - "ToolCallSummary": { - "properties": { - "id": { - "type": "string", - "title": "Id", - "description": "ID of the tool call" - }, - "name": { - "type": "string", - "title": "Name", - "description": "Name of the tool called" - }, - "args": { - "additionalProperties": true, - "type": "object", - "title": "Args", - "description": "Arguments passed to the tool" - }, - "type": { - "type": "string", - "title": "Type", - "description": "Type indicator for tool call", - "default": "tool_call" - } - }, - "type": "object", "required": [ - "id", - "name" + "file_id" ], - "title": "ToolCallSummary", - "description": "Model representing a tool call made during response generation (for tool_calls list)." + "title": "VectorStoreFileCreateRequest", + "description": "Model representing a request to add a file to a vector store.\n\nAttributes:\n file_id: ID of the file to add to the vector store.\n attributes: Optional metadata key-value pairs (max 16 pairs).\n chunking_strategy: Optional chunking strategy configuration.", + "examples": [ + { + "attributes": { + "created_at": "2026-04-04T15:20:00Z" + }, + "chunking_strategy": { + "chunk_size": 512, + "type": "fixed" + }, + "file_id": "file-abc123" + } + ] }, - "ToolResultSummary": { + "VectorStoreFileResponse": { "properties": { "id": { "type": "string", "title": "Id", - "description": "ID of the tool call/result, matches the corresponding tool call 'id'" - }, - "status": { - "type": "string", - "title": "Status", - "description": "Status of the tool execution (e.g., 'success')" + "description": "Vector store file ID" }, - "content": { + "vector_store_id": { "type": "string", - "title": "Content", - "description": "Content/result returned from the tool" + "title": "Vector Store Id", + "description": "ID of the vector store" }, - "type": { + "status": { "type": "string", - "title": "Type", - "description": "Type indicator for tool result", - "default": "tool_result" + "title": "Status", + "description": "File processing status" }, - "round": { - "type": "integer", - "title": "Round", - "description": "Round number or step of tool execution" - } - }, - "type": "object", - "required": [ - "id", - "status", - "content", - "round" - ], - "title": "ToolResultSummary", - "description": "Model representing a result from a tool call (for tool_results list)." - }, - "ToolsResponse": { - "properties": { - "tools": { - "items": { - "additionalProperties": true, - "type": "object" - }, - "type": "array", - "title": "Tools", - "description": "List of tools available from all configured MCP servers and built-in toolgroups" - } - }, - "type": "object", - "required": [ - "tools" - ], - "title": "ToolsResponse", - "description": "Model representing a response to tools request.", - "examples": [ - { - "tools": [ + "attributes": { + "anyOf": [ { - "description": "Read contents of a file from the filesystem", - "identifier": "filesystem_read", - "parameters": [ - { - "description": "Path to the file to read", - "name": "path", - "parameter_type": "string", - "required": true - } - ], - "provider_id": "model-context-protocol", - "server_source": "http://localhost:3000", - "toolgroup_id": "filesystem-tools", - "type": "tool" - } - ] - } - ] - }, - "UnauthorizedResponse": { - "properties": { - "status_code": { - "type": "integer", - "title": "Status Code", - "description": "HTTP status code for the errors response" - }, - "detail": { - "$ref": "#/components/schemas/DetailModel", - "description": "The detail model containing error summary and cause" - } - }, - "type": "object", - "required": [ - "status_code", - "detail" - ], - "title": "UnauthorizedResponse", - "description": "401 Unauthorized - Missing or invalid credentials.", - "examples": [ - { - "detail": { - "cause": "No Authorization header found", - "response": "Missing or invalid credentials provided by client" - }, - "label": "missing header" - }, - { - "detail": { - "cause": "No token found in Authorization header", - "response": "Missing or invalid credentials provided by client" - }, - "label": "missing token" - }, - { - "detail": { - "cause": "Token has expired", - "response": "Missing or invalid credentials provided by client" - }, - "label": "expired token" - }, - { - "detail": { - "cause": "Invalid token signature", - "response": "Missing or invalid credentials provided by client" - }, - "label": "invalid signature" + "additionalProperties": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + }, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Attributes", + "description": "Set of up to 16 key-value pairs for storing additional information. Keys: strings (max 64 chars). Values: strings (max 512 chars), booleans, or numbers." }, - { - "detail": { - "cause": "Token signed by unknown key", - "response": "Missing or invalid credentials provided by client" - }, - "label": "invalid key" + "last_error": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Error", + "description": "Error message if processing failed" }, + "object": { + "type": "string", + "title": "Object", + "description": "Object type", + "default": "vector_store.file" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id", + "vector_store_id", + "status" + ], + "title": "VectorStoreFileResponse", + "description": "Response model containing a vector store file object.\n\nAttributes:\n id: Vector store file ID.\n vector_store_id: ID of the vector store.\n status: File processing status.\n attributes: Optional metadata key-value pairs.\n last_error: Optional error message if processing failed.\n object: Object type (always \"vector_store.file\").", + "examples": [ { - "detail": { - "cause": "Token missing claim: user_id", - "response": "Missing or invalid credentials provided by client" + "attributes": { + "chunk_size": "512", + "indexed": true }, - "label": "missing claim" - }, - { - "detail": { - "cause": "Invalid or expired Kubernetes token", - "response": "Missing or invalid credentials provided by client" + "id": "file_abc123", + "object": "vector_store.file", + "status": "completed", + "vector_store_id": "vs_abc123" + } + ] + }, + "VectorStoreFilesListResponse": { + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/VectorStoreFileResponse" }, - "label": "invalid k8s token" + "type": "array", + "title": "Data", + "description": "List of vector store files" }, + "object": { + "type": "string", + "title": "Object", + "description": "Object type", + "default": "list" + } + }, + "additionalProperties": false, + "type": "object", + "title": "VectorStoreFilesListResponse", + "description": "Response model containing a list of vector store files.\n\nAttributes:\n data: List of vector store file objects.\n object: Object type (always \"list\").", + "examples": [ { - "detail": { - "cause": "Authentication key server returned invalid data", - "response": "Missing or invalid credentials provided by client" - }, - "label": "invalid jwk token" + "data": [ + { + "attributes": { + "chunk_size": "512" + }, + "id": "file_abc123", + "object": "vector_store.file", + "status": "completed", + "vector_store_id": "vs_abc123" + }, + { + "id": "file_def456", + "object": "vector_store.file", + "status": "processing", + "vector_store_id": "vs_abc123" + } + ], + "object": "list" } ] }, - "UnprocessableEntityResponse": { + "VectorStoreResponse": { "properties": { - "status_code": { + "id": { + "type": "string", + "title": "Id", + "description": "Vector store ID" + }, + "name": { + "type": "string", + "title": "Name", + "description": "Vector store name" + }, + "created_at": { "type": "integer", - "title": "Status Code", - "description": "HTTP status code for the errors response" + "title": "Created At", + "description": "Unix timestamp when created" }, - "detail": { - "$ref": "#/components/schemas/DetailModel", - "description": "The detail model containing error summary and cause" + "last_active_at": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Last Active At", + "description": "Unix timestamp of last activity" + }, + "expires_at": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Expires At", + "description": "Unix timestamp when it expires" + }, + "status": { + "type": "string", + "title": "Status", + "description": "Vector store status" + }, + "usage_bytes": { + "type": "integer", + "title": "Usage Bytes", + "description": "Storage usage in bytes", + "default": 0 + }, + "metadata": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Metadata", + "description": "Metadata dictionary for storing session information", + "examples": [ + { + "conversation_id": "conv_123", + "document_ids": [ + "doc_456", + "doc_789" + ] + } + ] } }, + "additionalProperties": false, "type": "object", "required": [ - "status_code", - "detail" + "id", + "name", + "created_at", + "status" ], - "title": "UnprocessableEntityResponse", - "description": "422 Unprocessable Entity - Request validation failed.", + "title": "VectorStoreResponse", + "description": "Response model containing a single vector store.\n\nAttributes:\n id: Vector store ID.\n name: Vector store name.\n created_at: Unix timestamp when created.\n last_active_at: Unix timestamp of last activity.\n expires_at: Optional Unix timestamp when it expires.\n status: Vector store status.\n usage_bytes: Storage usage in bytes.\n metadata: Optional metadata dictionary for storing session information.", "examples": [ { - "detail": { - "cause": "Invalid request format. The request body could not be parsed.", - "response": "Invalid request format" - }, - "label": "invalid format" - }, - { - "detail": { - "cause": "Missing required attributes: ['query', 'model', 'provider']", - "response": "Missing required attributes" - }, - "label": "missing attributes" - }, - { - "detail": { - "cause": "Invalid attachment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']", - "response": "Invalid attribute value" + "created_at": 1704067200, + "id": "vs_abc123", + "last_active_at": 1704153600, + "metadata": { + "conversation_id": "conv_123", + "document_ids": [ + "doc_456", + "doc_789" + ] }, - "label": "invalid value" + "name": "customer_support_docs", + "status": "active", + "usage_bytes": 1048576 } ] }, - "UserDataCollection": { + "VectorStoreUpdateRequest": { "properties": { - "feedback_enabled": { - "type": "boolean", - "title": "Feedback enabled", - "description": "When set to true the user feedback is stored and later sent for analysis.", - "default": false - }, - "feedback_storage": { + "name": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 256, + "minLength": 1 }, { "type": "null" } ], - "title": "Feedback storage directory", - "description": "Path to directory where feedback will be saved for further processing." + "title": "Name", + "description": "New name for the vector store", + "examples": [ + "updated_vector_store" + ] }, - "transcripts_enabled": { - "type": "boolean", - "title": "Transcripts enabled", - "description": "When set to true the conversation history is stored and later sent for analysis.", - "default": false + "expires_at": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Expires At", + "description": "Unix timestamp when the vector store should expire", + "examples": [ + 1735689600 + ] }, - "transcripts_storage": { + "metadata": { "anyOf": [ { - "type": "string" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "Transcripts storage directory", - "description": "Path to directory where conversation history will be saved for further processing." + "title": "Metadata", + "description": "Metadata dictionary for storing session information", + "examples": [ + { + "session_id": "sess456", + "user_id": "user123" + } + ] } }, "additionalProperties": false, "type": "object", - "title": "UserDataCollection", - "description": "User data collection configuration." + "title": "VectorStoreUpdateRequest", + "description": "Model representing a request to update a vector store.\n\nAttributes:\n name: New name for the vector store.\n expires_at: Optional expiration timestamp.\n metadata: Optional metadata dictionary for storing session information.", + "examples": [ + { + "expires_at": 1735689600, + "metadata": { + "user_id": "user123" + }, + "name": "updated_vector_store" + } + ] }, - "ValidationError": { + "VectorStoresListResponse": { "properties": { - "loc": { + "data": { "items": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "integer" - } - ] + "$ref": "#/components/schemas/VectorStoreResponse" }, "type": "array", - "title": "Location" - }, - "msg": { - "type": "string", - "title": "Message" + "title": "Data", + "description": "List of vector stores" }, - "type": { + "object": { "type": "string", - "title": "Error Type" - }, - "input": { - "title": "Input" - }, - "ctx": { - "type": "object", - "title": "Context" + "title": "Object", + "description": "Object type", + "default": "list" } }, + "additionalProperties": false, "type": "object", - "required": [ - "loc", - "msg", - "type" - ], - "title": "ValidationError" + "title": "VectorStoresListResponse", + "description": "Response model containing a list of vector stores.\n\nAttributes:\n data: List of vector store objects.\n object: Object type (always \"list\").", + "examples": [ + { + "data": [ + { + "created_at": 1704067200, + "id": "vs_abc123", + "last_active_at": 1704153600, + "metadata": { + "conversation_id": "conv_123" + }, + "name": "customer_support_docs", + "status": "active", + "usage_bytes": 1048576 + }, + { + "created_at": 1704070800, + "id": "vs_def456", + "last_active_at": 1704157200, + "name": "product_documentation", + "status": "active", + "usage_bytes": 2097152 + } + ], + "object": "list" + } + ] } } } diff --git a/docs/openapi.md b/docs/openapi.md index 6ce467992..7641999f7 100644 --- a/docs/openapi.md +++ b/docs/openapi.md @@ -4465,6 +4465,15 @@ Microsoft Entra ID authentication attributes for Azure. | detail | | The detail model containing error summary and cause | +## Body_create_file_v1_files_post + + + +| Field | Type | Description | +|-------|------|-------------| +| file | string | | + + ## ByokRag @@ -4947,6 +4956,42 @@ Example: | status | object | | +## FileResponse + + +Response model containing a file object. + +Attributes: + id: File ID. + filename: File name. + bytes: File size in bytes. + created_at: Unix timestamp when created. + purpose: File purpose. + object: Object type (always "file"). + + +| Field | Type | Description | +|-------|------|-------------| +| id | string | File ID | +| filename | string | File name | +| bytes | integer | File size in bytes | +| created_at | integer | Unix timestamp when created | +| purpose | string | File purpose | +| object | string | Object type | + + +## FileTooLargeResponse + + +413 Content Too Large - File upload exceeds size limit. + + +| Field | Type | Description | +|-------|------|-------------| +| status_code | integer | HTTP status code for the errors response | +| detail | | The detail model containing error summary and cause | + + ## ForbiddenResponse @@ -7211,3 +7256,147 @@ User data collection configuration. | type | string | | | input | | | | ctx | object | | + + +## VectorStoreCreateRequest + + +Model representing a request to create a vector store. + +Attributes: + name: Name of the vector store. + embedding_model: Optional embedding model to use. + embedding_dimension: Optional embedding dimension. + chunking_strategy: Optional chunking strategy configuration. + provider_id: Optional vector store provider identifier. + metadata: Optional metadata dictionary for storing session information. + + +| Field | Type | Description | +|-------|------|-------------| +| name | string | Name of the vector store | +| embedding_model | | Embedding model to use for the vector store | +| embedding_dimension | | Dimension of the embedding vectors | +| chunking_strategy | | Chunking strategy configuration | +| provider_id | | Vector store provider identifier | +| metadata | | Metadata dictionary for storing session information | + + +## VectorStoreFileCreateRequest + + +Model representing a request to add a file to a vector store. + +Attributes: + file_id: ID of the file to add to the vector store. + attributes: Optional metadata key-value pairs (max 16 pairs). + chunking_strategy: Optional chunking strategy configuration. + + +| Field | Type | Description | +|-------|------|-------------| +| file_id | string | ID of the file to add to the vector store | +| attributes | | Set of up to 16 key-value pairs for storing additional information. Keys: strings (max 64 chars). Values: strings (max 512 chars), booleans, or numbers. | +| chunking_strategy | | Chunking strategy configuration for this file | + + +## VectorStoreFileResponse + + +Response model containing a vector store file object. + +Attributes: + id: Vector store file ID. + vector_store_id: ID of the vector store. + status: File processing status. + attributes: Optional metadata key-value pairs. + last_error: Optional error message if processing failed. + object: Object type (always "vector_store.file"). + + +| Field | Type | Description | +|-------|------|-------------| +| id | string | Vector store file ID | +| vector_store_id | string | ID of the vector store | +| status | string | File processing status | +| attributes | | Set of up to 16 key-value pairs for storing additional information. Keys: strings (max 64 chars). Values: strings (max 512 chars), booleans, or numbers. | +| last_error | | Error message if processing failed | +| object | string | Object type | + + +## VectorStoreFilesListResponse + + +Response model containing a list of vector store files. + +Attributes: + data: List of vector store file objects. + object: Object type (always "list"). + + +| Field | Type | Description | +|-------|------|-------------| +| data | array | List of vector store files | +| object | string | Object type | + + +## VectorStoreResponse + + +Response model containing a single vector store. + +Attributes: + id: Vector store ID. + name: Vector store name. + created_at: Unix timestamp when created. + last_active_at: Unix timestamp of last activity. + expires_at: Optional Unix timestamp when it expires. + status: Vector store status. + usage_bytes: Storage usage in bytes. + metadata: Optional metadata dictionary for storing session information. + + +| Field | Type | Description | +|-------|------|-------------| +| id | string | Vector store ID | +| name | string | Vector store name | +| created_at | integer | Unix timestamp when created | +| last_active_at | | Unix timestamp of last activity | +| expires_at | | Unix timestamp when it expires | +| status | string | Vector store status | +| usage_bytes | integer | Storage usage in bytes | +| metadata | | Metadata dictionary for storing session information | + + +## VectorStoreUpdateRequest + + +Model representing a request to update a vector store. + +Attributes: + name: New name for the vector store. + expires_at: Optional expiration timestamp. + metadata: Optional metadata dictionary for storing session information. + + +| Field | Type | Description | +|-------|------|-------------| +| name | | New name for the vector store | +| expires_at | | Unix timestamp when the vector store should expire | +| metadata | | Metadata dictionary for storing session information | + + +## VectorStoresListResponse + + +Response model containing a list of vector stores. + +Attributes: + data: List of vector store objects. + object: Object type (always "list"). + + +| Field | Type | Description | +|-------|------|-------------| +| data | array | List of vector stores | +| object | string | Object type |