diff --git a/docs/openapi.json b/docs/openapi.json index 96faeeae..d6f00c7f 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -38,7 +38,7 @@ "info" ], "summary": "Info Endpoint Handler", - "description": "Handle request to the /info endpoint.", + "description": "Handle request to the /info endpoint.\n\nProcess GET requests to the /info endpoint, returning the\nservice name and version.\n\nReturns:\n InfoResponse: An object containing the service's name and version.", "operationId": "info_endpoint_handler_v1_info_get", "responses": { "200": { @@ -220,7 +220,7 @@ "config" ], "summary": "Config Endpoint Handler", - "description": "Handle requests to the /config endpoint.", + "description": "Handle requests to the /config endpoint.\n\nProcess GET requests to the /config endpoint and returns the\ncurrent service configuration.\n\nReturns:\n Configuration: The loaded service configuration object.", "operationId": "config_endpoint_handler_v1_config_get", "responses": { "200": { @@ -367,6 +367,53 @@ } } }, + "/v1/conversations": { + "get": { + "tags": [ + "conversations" + ], + "summary": "Get Conversations List Endpoint Handler", + "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" + } + } + }, + "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-1.5-flash", + "last_used_provider": "gemini", + "message_count": 5 + }, + { + "conversation_id": "456e7890-e12b-34d5-a678-901234567890", + "created_at": "2024-01-01T01:00:00Z", + "last_message_at": "2024-01-01T01:02:00Z", + "last_used_model": "gemini/gemini-2.0-flash", + "last_used_provider": "gemini", + "message_count": 2 + } + ] + }, + "503": { + "description": "Service Unavailable", + "detail": { + "response": "Unable to connect to Llama Stack", + "cause": "Connection error." + } + } + } + } + }, "/v1/conversations/{conversation_id}": { "get": { "tags": [ @@ -505,7 +552,7 @@ "health" ], "summary": "Readiness Probe Get Method", - "description": "Ready status of service with provider health details.", + "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.", "operationId": "readiness_probe_get_method_readiness_get", "responses": { "200": { @@ -537,7 +584,7 @@ "health" ], "summary": "Liveness Probe Get Method", - "description": "Live status of service.", + "description": "Return the liveness status of the service.\n\nReturns:\n LivenessResponse: Indicates that the service is alive.", "operationId": "liveness_probe_get_method_liveness_get", "responses": { "200": { @@ -569,7 +616,7 @@ "authorized" ], "summary": "Authorized Endpoint Handler", - "description": "Handle request to the /authorized endpoint.", + "description": "Handle request to the /authorized endpoint.\n\nProcess POST requests to the /authorized endpoint, returning\nthe authenticated user's ID and username.\n\nReturns:\n AuthorizedResponse: Contains the user ID and username of the authenticated user.", "operationId": "authorized_endpoint_handler_authorized_post", "responses": { "200": { @@ -611,7 +658,7 @@ "metrics" ], "summary": "Metrics Endpoint Handler", - "description": "Handle request to the /metrics endpoint.", + "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.", "operationId": "metrics_endpoint_handler_metrics_get", "responses": { "200": { @@ -775,6 +822,14 @@ "user_data_collection": { "$ref": "#/components/schemas/UserDataCollection" }, + "database": { + "$ref": "#/components/schemas/DatabaseConfiguration", + "default": { + "sqlite": { + "db_path": "/tmp/lightspeed-stack.db" + } + } + }, "mcp_servers": { "items": { "$ref": "#/components/schemas/ModelContextProtocolServer" @@ -853,6 +908,75 @@ } ] }, + "ConversationDetails": { + "properties": { + "conversation_id": { + "type": "string", + "title": "Conversation Id" + }, + "created_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Created At" + }, + "last_message_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Message At" + }, + "message_count": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Message Count" + }, + "last_used_model": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Used Model" + }, + "last_used_provider": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Used Provider" + } + }, + "type": "object", + "required": [ + "conversation_id" + ], + "title": "ConversationDetails", + "description": "Model representing the details of a user conversation.\n\nAttributes:\n conversation_id: The conversation ID (UUID).\n created_at: When the conversation was created.\n last_message_at: When the last message was sent.\n message_count: Number of user messages in the conversation.\n model: The model used for the conversation.\n\nExample:\n ```python\n conversation = ConversationSummary(\n conversation_id=\"123e4567-e89b-12d3-a456-426614174000\"\n created_at=\"2024-01-01T00:00:00Z\",\n last_message_at=\"2024-01-01T00:05:00Z\",\n message_count=5,\n model=\"gemini/gemini-2.0-flash\"\n )\n ```" + }, "ConversationResponse": { "properties": { "conversation_id": { @@ -897,6 +1021,42 @@ } ] }, + "ConversationsListResponse": { + "properties": { + "conversations": { + "items": { + "$ref": "#/components/schemas/ConversationDetails" + }, + "type": "array", + "title": "Conversations" + } + }, + "type": "object", + "required": [ + "conversations" + ], + "title": "ConversationsListResponse", + "description": "Model representing a response for listing conversations of a user.\n\nAttributes:\n conversations: List of conversation details associated with the user.\n\nExample:\n ```python\n conversations_list = ConversationsListResponse(\n conversations=[\n ConversationDetails(\n conversation_id=\"123e4567-e89b-12d3-a456-426614174000\",\n created_at=\"2024-01-01T00:00:00Z\",\n last_message_at=\"2024-01-01T00:05:00Z\",\n message_count=5,\n model=\"gemini/gemini-2.0-flash\"\n ),\n ConversationDetails(\n conversation_id=\"456e7890-e12b-34d5-a678-901234567890\"\n created_at=\"2024-01-01T01:00:00Z\",\n message_count=2,\n model=\"gemini/gemini-2.5-flash\"\n )\n ]\n )\n ```", + "examples": [ + { + "conversations": [ + { + "conversation_id": "123e4567-e89b-12d3-a456-426614174000", + "created_at": "2024-01-01T00:00:00Z", + "last_message_at": "2024-01-01T00:05:00Z", + "message_count": 5, + "model": "gemini/gemini-2.0-flash" + }, + { + "conversation_id": "456e7890-e12b-34d5-a678-901234567890", + "created_at": "2024-01-01T01:00:00Z", + "message_count": 2, + "model": "gemini/gemini-2.5-flash" + } + ] + } + ] + }, "Customization": { "properties": { "disable_query_system_prompt": { @@ -994,6 +1154,33 @@ "title": "DataCollectorConfiguration", "description": "Data collector configuration for sending data to ingress server." }, + "DatabaseConfiguration": { + "properties": { + "sqlite": { + "anyOf": [ + { + "$ref": "#/components/schemas/SQLiteDatabaseConfiguration" + }, + { + "type": "null" + } + ] + }, + "postgres": { + "anyOf": [ + { + "$ref": "#/components/schemas/PostgreSQLDatabaseConfiguration" + }, + { + "type": "null" + } + ] + } + }, + "type": "object", + "title": "DatabaseConfiguration", + "description": "Database configuration." + }, "FeedbackCategory": { "type": "string", "enum": [ @@ -1382,6 +1569,74 @@ "title": "ModelsResponse", "description": "Model representing a response to models request." }, + "PostgreSQLDatabaseConfiguration": { + "properties": { + "host": { + "type": "string", + "title": "Host", + "default": "localhost" + }, + "port": { + "type": "integer", + "title": "Port", + "default": 5432 + }, + "db": { + "type": "string", + "title": "Db" + }, + "user": { + "type": "string", + "title": "User" + }, + "password": { + "type": "string", + "title": "Password" + }, + "namespace": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Namespace", + "default": "lightspeed-stack" + }, + "ssl_mode": { + "type": "string", + "title": "Ssl Mode", + "default": "prefer" + }, + "gss_encmode": { + "type": "string", + "title": "Gss Encmode", + "default": "prefer" + }, + "ca_cert_path": { + "anyOf": [ + { + "type": "string", + "format": "file-path" + }, + { + "type": "null" + } + ], + "title": "Ca Cert Path" + } + }, + "type": "object", + "required": [ + "db", + "user", + "password" + ], + "title": "PostgreSQLDatabaseConfiguration", + "description": "PostgreSQL database configuration." + }, "ProviderHealthStatus": { "properties": { "provider_id": { @@ -1649,6 +1904,20 @@ } ] }, + "SQLiteDatabaseConfiguration": { + "properties": { + "db_path": { + "type": "string", + "title": "Db Path" + } + }, + "type": "object", + "required": [ + "db_path" + ], + "title": "SQLiteDatabaseConfiguration", + "description": "SQLite database configuration." + }, "ServiceConfiguration": { "properties": { "host": { diff --git a/docs/openapi.md b/docs/openapi.md index 7a8929be..07677950 100644 --- a/docs/openapi.md +++ b/docs/openapi.md @@ -33,6 +33,12 @@ Handle request to the / endpoint. Handle request to the /info endpoint. +Process GET requests to the /info endpoint, returning the +service name and version. + +Returns: + InfoResponse: An object containing the service's name and version. + @@ -114,6 +120,12 @@ Handle request to the /streaming_query endpoint. Handle requests to the /config endpoint. +Process GET requests to the /config endpoint and returns the +current service configuration. + +Returns: + Configuration: The loaded service configuration object. + @@ -180,6 +192,23 @@ Returns: |-------------|-------------|-----------| | 200 | Successful Response | [StatusResponse](#statusresponse) | +## GET `/v1/conversations` + +> **Get Conversations List Endpoint Handler** + +Handle request to retrieve all conversations for the authenticated user. + + + + + +### ✅ Responses + +| Status Code | Description | Component | +|-------------|-------------|-----------| +| 200 | Successful Response | [ConversationsListResponse](#conversationslistresponse) + | +| 503 | Service Unavailable | | ## GET `/v1/conversations/{conversation_id}` > **Get Conversation Endpoint Handler** @@ -234,7 +263,11 @@ Handle request to delete a conversation by ID. > **Readiness Probe Get Method** -Ready status of service with provider health details. +Handle the readiness probe endpoint, returning service readiness. + +If any provider reports an error status, responds with HTTP 503 +and details of unhealthy providers; otherwise, indicates the +service is ready. @@ -252,7 +285,10 @@ Ready status of service with provider health details. > **Liveness Probe Get Method** -Live status of service. +Return the liveness status of the service. + +Returns: + LivenessResponse: Indicates that the service is alive. @@ -272,6 +308,12 @@ Live status of service. Handle request to the /authorized endpoint. +Process POST requests to the /authorized endpoint, returning +the authenticated user's ID and username. + +Returns: + AuthorizedResponse: Contains the user ID and username of the authenticated user. + @@ -292,6 +334,13 @@ Handle request to the /authorized endpoint. Handle request to the /metrics endpoint. +Process GET requests to the /metrics endpoint, returning the +latest Prometheus metrics in form of a plain text. + +Initializes model metrics on the first request if not already +set up, then responds with the current metrics snapshot in +Prometheus format. + @@ -379,6 +428,7 @@ Global service configuration. | service | | | | llama_stack | | | | user_data_collection | | | +| database | | | | mcp_servers | array | | | authentication | | | | customization | | | @@ -412,6 +462,40 @@ Example: | response | string | | +## ConversationDetails + + +Model representing the details of a user conversation. + +Attributes: + conversation_id: The conversation ID (UUID). + created_at: When the conversation was created. + last_message_at: When the last message was sent. + message_count: Number of user messages in the conversation. + model: The model used for the conversation. + +Example: + ```python + conversation = ConversationSummary( + conversation_id="123e4567-e89b-12d3-a456-426614174000" + created_at="2024-01-01T00:00:00Z", + last_message_at="2024-01-01T00:05:00Z", + message_count=5, + model="gemini/gemini-2.0-flash" + ) + ``` + + +| Field | Type | Description | +|-------|------|-------------| +| conversation_id | string | | +| created_at | | | +| last_message_at | | | +| message_count | | | +| last_used_model | | | +| last_used_provider | | | + + ## ConversationResponse @@ -445,6 +529,41 @@ Example: | chat_history | array | | +## ConversationsListResponse + + +Model representing a response for listing conversations of a user. + +Attributes: + conversations: List of conversation details associated with the user. + +Example: + ```python + conversations_list = ConversationsListResponse( + conversations=[ + ConversationDetails( + conversation_id="123e4567-e89b-12d3-a456-426614174000", + created_at="2024-01-01T00:00:00Z", + last_message_at="2024-01-01T00:05:00Z", + message_count=5, + model="gemini/gemini-2.0-flash" + ), + ConversationDetails( + conversation_id="456e7890-e12b-34d5-a678-901234567890" + created_at="2024-01-01T01:00:00Z", + message_count=2, + model="gemini/gemini-2.5-flash" + ) + ] + ) + ``` + + +| Field | Type | Description | +|-------|------|-------------| +| conversations | array | | + + ## Customization @@ -475,6 +594,18 @@ Data collector configuration for sending data to ingress server. | connection_timeout | integer | | +## DatabaseConfiguration + + +Database configuration. + + +| Field | Type | Description | +|-------|------|-------------| +| sqlite | | | +| postgres | | | + + ## FeedbackCategory @@ -485,14 +616,6 @@ when users provide negative feedback (thumbs down). Multiple categories can be selected to provide comprehensive feedback about response issues. -| Value | Description | -|-------|-------------| -| incorrect | The answer provided is completely wrong | -| not_relevant | This answer doesn't address my question at all | -| incomplete | The answer only covers part of what I asked about | -| outdated_information | This information is from several years ago and no longer accurate | -| unsafe | This response could be harmful or dangerous if followed | -| other | The response has issues not covered by other categories | ## FeedbackRequest @@ -697,6 +820,25 @@ Model representing a response to models request. | models | array | | +## PostgreSQLDatabaseConfiguration + + +PostgreSQL database configuration. + + +| Field | Type | Description | +|-------|------|-------------| +| host | string | | +| port | integer | | +| db | string | | +| user | string | | +| password | string | | +| namespace | | | +| ssl_mode | string | | +| gss_encmode | string | | +| ca_cert_path | | | + + ## ProviderHealthStatus @@ -796,6 +938,17 @@ Example: | providers | array | | +## SQLiteDatabaseConfiguration + + +SQLite database configuration. + + +| Field | Type | Description | +|-------|------|-------------| +| db_path | string | | + + ## ServiceConfiguration diff --git a/docs/output.md b/docs/output.md index c9ccd8de..20f4e99c 100644 --- a/docs/output.md +++ b/docs/output.md @@ -33,6 +33,12 @@ Handle request to the / endpoint. Handle request to the /info endpoint. +Process GET requests to the /info endpoint, returning the +service name and version. + +Returns: + InfoResponse: An object containing the service's name and version. + @@ -114,6 +120,12 @@ Handle request to the /streaming_query endpoint. Handle requests to the /config endpoint. +Process GET requests to the /config endpoint and returns the +current service configuration. + +Returns: + Configuration: The loaded service configuration object. + @@ -180,6 +192,23 @@ Returns: |-------------|-------------|-----------| | 200 | Successful Response | [StatusResponse](#statusresponse) | +## GET `/v1/conversations` + +> **Get Conversations List Endpoint Handler** + +Handle request to retrieve all conversations for the authenticated user. + + + + + +### ✅ Responses + +| Status Code | Description | Component | +|-------------|-------------|-----------| +| 200 | Successful Response | [ConversationsListResponse](#conversationslistresponse) + | +| 503 | Service Unavailable | | ## GET `/v1/conversations/{conversation_id}` > **Get Conversation Endpoint Handler** @@ -234,7 +263,11 @@ Handle request to delete a conversation by ID. > **Readiness Probe Get Method** -Ready status of service with provider health details. +Handle the readiness probe endpoint, returning service readiness. + +If any provider reports an error status, responds with HTTP 503 +and details of unhealthy providers; otherwise, indicates the +service is ready. @@ -252,7 +285,10 @@ Ready status of service with provider health details. > **Liveness Probe Get Method** -Live status of service. +Return the liveness status of the service. + +Returns: + LivenessResponse: Indicates that the service is alive. @@ -272,6 +308,12 @@ Live status of service. Handle request to the /authorized endpoint. +Process POST requests to the /authorized endpoint, returning +the authenticated user's ID and username. + +Returns: + AuthorizedResponse: Contains the user ID and username of the authenticated user. + @@ -292,6 +334,13 @@ Handle request to the /authorized endpoint. Handle request to the /metrics endpoint. +Process GET requests to the /metrics endpoint, returning the +latest Prometheus metrics in form of a plain text. + +Initializes model metrics on the first request if not already +set up, then responds with the current metrics snapshot in +Prometheus format. + @@ -379,6 +428,7 @@ Global service configuration. | service | | | | llama_stack | | | | user_data_collection | | | +| database | | | | mcp_servers | array | | | authentication | | | | customization | | | @@ -412,6 +462,40 @@ Example: | response | string | | +## ConversationDetails + + +Model representing the details of a user conversation. + +Attributes: + conversation_id: The conversation ID (UUID). + created_at: When the conversation was created. + last_message_at: When the last message was sent. + message_count: Number of user messages in the conversation. + model: The model used for the conversation. + +Example: + ```python + conversation = ConversationSummary( + conversation_id="123e4567-e89b-12d3-a456-426614174000" + created_at="2024-01-01T00:00:00Z", + last_message_at="2024-01-01T00:05:00Z", + message_count=5, + model="gemini/gemini-2.0-flash" + ) + ``` + + +| Field | Type | Description | +|-------|------|-------------| +| conversation_id | string | | +| created_at | | | +| last_message_at | | | +| message_count | | | +| last_used_model | | | +| last_used_provider | | | + + ## ConversationResponse @@ -445,6 +529,41 @@ Example: | chat_history | array | | +## ConversationsListResponse + + +Model representing a response for listing conversations of a user. + +Attributes: + conversations: List of conversation details associated with the user. + +Example: + ```python + conversations_list = ConversationsListResponse( + conversations=[ + ConversationDetails( + conversation_id="123e4567-e89b-12d3-a456-426614174000", + created_at="2024-01-01T00:00:00Z", + last_message_at="2024-01-01T00:05:00Z", + message_count=5, + model="gemini/gemini-2.0-flash" + ), + ConversationDetails( + conversation_id="456e7890-e12b-34d5-a678-901234567890" + created_at="2024-01-01T01:00:00Z", + message_count=2, + model="gemini/gemini-2.5-flash" + ) + ] + ) + ``` + + +| Field | Type | Description | +|-------|------|-------------| +| conversations | array | | + + ## Customization @@ -475,6 +594,18 @@ Data collector configuration for sending data to ingress server. | connection_timeout | integer | | +## DatabaseConfiguration + + +Database configuration. + + +| Field | Type | Description | +|-------|------|-------------| +| sqlite | | | +| postgres | | | + + ## FeedbackCategory @@ -679,6 +810,25 @@ Model representing a response to models request. | models | array | | +## PostgreSQLDatabaseConfiguration + + +PostgreSQL database configuration. + + +| Field | Type | Description | +|-------|------|-------------| +| host | string | | +| port | integer | | +| db | string | | +| user | string | | +| password | string | | +| namespace | | | +| ssl_mode | string | | +| gss_encmode | string | | +| ca_cert_path | | | + + ## ProviderHealthStatus @@ -778,6 +928,17 @@ Example: | providers | array | | +## SQLiteDatabaseConfiguration + + +SQLite database configuration. + + +| Field | Type | Description | +|-------|------|-------------| +| db_path | string | | + + ## ServiceConfiguration