From dd6ef7f34e2ee8f6a07b7132940f07589033386d Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Thu, 9 Oct 2025 13:30:31 +0200 Subject: [PATCH] LCORE-632: updated OpenAPI Swagger --- docs/openapi.json | 386 +++++++++++++++++++++++++++++----------------- docs/openapi.md | 217 ++++++++++++++++++++++++++ docs/output.md | 217 ++++++++++++++++++++++++++ 3 files changed, 677 insertions(+), 143 deletions(-) diff --git a/docs/openapi.json b/docs/openapi.json index adb3be69..3fef744c 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -209,7 +209,7 @@ "providers" ], "summary": "Providers Endpoint Handler", - "description": "Handle requests to the /providers endpoint.\n\nProcess GET requests to the /providers endpoint, returning a list of available\nproviders from the Llama Stack service.\n\nRaises:\n HTTPException: If unable to connect to the Llama Stack server or if\n providers retrieval fails for any reason.\n\nReturns:\n ProvidersListResponse: An object containing the list of available providers.", + "description": "Handle GET requests to list all available providers.\n\nRetrieves providers from the Llama Stack service, groups them by API type.\n\nRaises:\n HTTPException:\n - 500 if configuration is not loaded,\n - 500 if unable to connect to Llama Stack,\n - 500 for any unexpected retrieval errors.\n\nReturns:\n ProvidersListResponse: Object mapping API types to lists of providers.", "operationId": "providers_endpoint_handler_v1_providers_get", "responses": { "200": { @@ -221,33 +221,32 @@ } } }, - "providers": { "agents": [ - { - "provider_id": "meta-reference", - "provider_type": "inline::meta-reference" - } + { + "provider_id": "meta-reference", + "provider_type": "inline::meta-reference" + } ], "datasetio": [ - { - "provider_id": "huggingface", - "provider_type": "remote::huggingface" - }, - { - "provider_id": "localfs", - "provider_type": "inline::localfs" - } + { + "provider_id": "huggingface", + "provider_type": "remote::huggingface" + }, + { + "provider_id": "localfs", + "provider_type": "inline::localfs" + } ], "inference": [ - { - "provider_id": "sentence-transformers", - "provider_type": "inline::sentence-transformers" - }, - { - "provider_id": "openai", - "provider_type": "remote::openai" - } + { + "provider_id": "sentence-transformers", + "provider_type": "inline::sentence-transformers" + }, + { + "provider_id": "openai", + "provider_type": "remote::openai" + } ] } }, @@ -259,61 +258,64 @@ }, "/v1/providers/{provider_id}": { "get": { - "summary": "Retrieve a single provider by ID", - "description": "Fetches detailed information about a specific provider, including its API, configuration, health status, provider ID, and type. Returns a 404 error if the provider with the specified ID does not exist, or a 500 error if there is a problem connecting to the Llama Stack service.", + "tags": [ + "providers" + ], + "summary": "Get Provider Endpoint Handler", + "description": "Retrieve a single provider by its unique ID.\n\nRaises:\n HTTPException:\n - 404 if provider with the given ID is not found,\n - 500 if unable to connect to Llama Stack,\n - 500 for any unexpected retrieval errors.\n\nReturns:\n ProviderResponse: A single provider's details including API, config, health,\n provider_id, and provider_type.", + "operationId": "get_provider_endpoint_handler_v1_providers__provider_id__get", "parameters": [ - { - "name": "provider_id", - "in": "path", - "required": true, - "description": "Unique identifier of the provider to retrieve", - "schema": { - "type": "string" + { + "name": "provider_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Provider Id" + } } - } ], "responses": { - "200": { - "description": "Provider found successfully", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ProviderResponse" }, - "example": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProviderResponse" + } + } + }, "api": "inference", - "config": {"api_key": "********"}, + "config": { + "api_key": "********" + }, "health": { "status": "Not Implemented", "message": "Provider does not implement health check" }, "provider_id": "openai", "provider_type": "remote::openai" - } - } - } - }, - "404": { - "description": "Provider with the specified ID was not found", - "content": { - "application/json": { - "example": { - "response": "Provider with given id not found" - } - } - } - }, - "500": { - "description": "Unable to retrieve provider due to server error or connection issues", - "content": { - "application/json": { - "example": { + }, + "404": { + "response": "Provider with given id not found", + "description": "Not Found" + }, + "500": { "response": "Unable to retrieve list of providers", - "cause": "Connection to Llama Stack is broken" + "cause": "Connection to Llama Stack is broken", + "description": "Internal Server Error" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } } } - } } - }, - "tags": ["providers"] } }, "/v1/query": { @@ -1536,6 +1538,52 @@ } ] }, + "ByokRag": { + "properties": { + "rag_id": { + "type": "string", + "minLength": 1, + "title": "Rag Id" + }, + "rag_type": { + "type": "string", + "minLength": 1, + "title": "Rag Type", + "default": "inline::faiss" + }, + "embedding_model": { + "type": "string", + "minLength": 1, + "title": "Embedding Model", + "default": "sentence-transformers/all-mpnet-base-v2" + }, + "embedding_dimension": { + "type": "integer", + "exclusiveMinimum": 0.0, + "title": "Embedding Dimension", + "default": 768 + }, + "vector_db_id": { + "type": "string", + "minLength": 1, + "title": "Vector Db Id" + }, + "db_path": { + "type": "string", + "format": "file-path", + "title": "Db Path" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "rag_id", + "vector_db_id", + "db_path" + ], + "title": "ByokRag", + "description": "BYOK RAG configuration." + }, "CORSConfiguration": { "properties": { "allow_origins": { @@ -1632,6 +1680,13 @@ }, "conversation_cache": { "$ref": "#/components/schemas/ConversationCacheConfiguration" + }, + "byok_rag": { + "items": { + "$ref": "#/components/schemas/ByokRag" + }, + "type": "array", + "title": "Byok Rag" } }, "additionalProperties": false, @@ -2878,101 +2933,146 @@ "description": "Model representing the health status of a provider.\n\nAttributes:\n provider_id: The ID of the provider.\n status: The health status ('ok', 'unhealthy', 'not_implemented').\n message: Optional message about the health status." }, "ProviderResponse": { - "type": "object", - "title": "ProviderResponse", - "description": "Model representing a provider and its configuration, health, and identification details.", "properties": { - "api": { - "type": "string", - "description": "The API name this provider implements" - }, - "config": { - "type": "object", - "description": "Configuration parameters for the provider", - "additionalProperties": true - }, - "health": { - "type": "object", - "description": "Current health status of the provider", - "additionalProperties": true - }, - "provider_id": { - "type": "string", - "description": "Unique identifier for the provider" - }, - "provider_type": { - "type": "string", - "description": "The type of provider implementation" - } + "api": { + "type": "string", + "title": "Api", + "description": "The API this provider implements", + "example": "inference" + }, + "config": { + "additionalProperties": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "number" + }, + { + "type": "string" + }, + { + "items": {}, + "type": "array" + }, + {}, + { + "type": "null" + } + ] + }, + "type": "object", + "title": "Config", + "description": "Provider configuration parameters", + "example": { + "api_key": "********" + } + }, + "health": { + "additionalProperties": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "number" + }, + { + "type": "string" + }, + { + "items": {}, + "type": "array" + }, + {}, + { + "type": "null" + } + ] + }, + "type": "object", + "title": "Health", + "description": "Current health status of the provider", + "example": { + "message": "Healthy", + "status": "OK" + } + }, + "provider_id": { + "type": "string", + "title": "Provider Id", + "description": "Unique provider identifier", + "example": "openai" + }, + "provider_type": { + "type": "string", + "title": "Provider Type", + "description": "Provider implementation type", + "example": "remote::openai" + } }, + "additionalProperties": true, + "type": "object", "required": [ - "api", - "config", - "health", - "provider_id", - "provider_type" - ], - "example": { - "api": "inference", - "config": {"api_key": "********"}, - "health": { - "status": "Not Implemented", - "message": "Provider does not implement health check" - }, - "provider_id": "openai", - "provider_type": "remote::openai" - } + "api", + "config", + "health", + "provider_id", + "provider_type" + ], + "title": "ProviderResponse", + "description": "Model representing a response to get specific provider request." }, "ProvidersListResponse": { - "type": "object", "properties": { "providers": { - "type": "object", - "description": "Mapping of API type to list of its available providers", - "additionalProperties": { - "type": "array", - "items": { - "type": "object", - "properties": { - "provider_id": { - "type": "string", - "description": "Unique local identifier of provider" + "additionalProperties": { + "items": { + "additionalProperties": true, + "type": "object" }, - "provider_type": { - "type": "string", - "description": "Llama stack identifier of provider (following schema ::)" - } + "type": "array" }, - "required": ["provider_id", "provider_type"] - } - }, - "examples": [ - { - "inference": [ - { - "provider_id": "sentence-transformers", - "provider_type": "inline::sentence-transformers" - }, - { - "provider_id": "openai", - "provider_type": "remote::openai" - } - ], - "datasetio": [ - { - "provider_id": "huggingface", - "provider_type": "remote::huggingface" - }, + "type": "object", + "title": "Providers", + "description": "List of available API types and their corresponding providers", + "examples": [ { - "provider_id": "localfs", - "provider_type": "inline::localfs" + "agents": [ + { + "provider_id": "meta-reference", + "provider_type": "inline::meta-reference" + } + ], + "datasetio": [ + { + "provider_id": "huggingface", + "provider_type": "remote::huggingface" + }, + { + "provider_id": "localfs", + "provider_type": "inline::localfs" + } + ], + "inference": [ + { + "provider_id": "sentence-transformers", + "provider_type": "inline::sentence-transformers" + }, + { + "provider_id": "openai", + "provider_type": "remote::openai" + } + ] } ] - } - ] } }, - "required": ["providers"], + "type": "object", + "required": [ + "providers" + ], "title": "ProvidersListResponse", "description": "Model representing a response to providers request." }, diff --git a/docs/openapi.md b/docs/openapi.md index 6bbba993..8a23abfc 100644 --- a/docs/openapi.md +++ b/docs/openapi.md @@ -80,6 +80,33 @@ Returns: |-------------|-------------|-----------| | 200 | Successful Response | [ModelsResponse](#modelsresponse) | | 500 | Connection to Llama Stack is broken | | +## GET `/v1/tools` + +> **Tools Endpoint Handler** + +Handle requests to the /tools endpoint. + +Process GET requests to the /tools endpoint, returning a consolidated list of +available tools from all configured MCP servers. + +Raises: + HTTPException: If unable to connect to the Llama Stack server or if + tool retrieval fails for any reason. + +Returns: + ToolsResponse: An object containing the consolidated list of available tools + with metadata including tool name, description, parameters, and server source. + + + + + +### ✅ Responses + +| Status Code | Description | Component | +|-------------|-------------|-----------| +| 200 | Successful Response | [ToolsResponse](#toolsresponse) | +| 500 | Connection to Llama Stack is broken or MCP server error | | ## GET `/v1/shields` > **Shields Endpoint Handler** @@ -106,6 +133,66 @@ Returns: |-------------|-------------|-----------| | 200 | Successful Response | [ShieldsResponse](#shieldsresponse) | | 500 | Connection to Llama Stack is broken | | +## GET `/v1/providers` + +> **Providers Endpoint Handler** + +Handle GET requests to list all available providers. + +Retrieves providers from the Llama Stack service, groups them by API type. + +Raises: + HTTPException: + - 500 if configuration is not loaded, + - 500 if unable to connect to Llama Stack, + - 500 for any unexpected retrieval errors. + +Returns: + ProvidersListResponse: Object mapping API types to lists of providers. + + + + + +### ✅ Responses + +| Status Code | Description | Component | +|-------------|-------------|-----------| +| 200 | Successful Response | [ProvidersListResponse](#providerslistresponse) | +| 500 | Connection to Llama Stack is broken | | +## GET `/v1/providers/{provider_id}` + +> **Get Provider Endpoint Handler** + +Retrieve a single provider by its unique ID. + +Raises: + HTTPException: + - 404 if provider with the given ID is not found, + - 500 if unable to connect to Llama Stack, + - 500 for any unexpected retrieval errors. + +Returns: + ProviderResponse: A single provider's details including API, config, health, + provider_id, and provider_type. + + + +### 🔗 Parameters + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| provider_id | string | True | | + + +### ✅ Responses + +| Status Code | Description | Component | +|-------------|-------------|-----------| +| 200 | Successful Response | [ProviderResponse](#providerresponse) | +| 404 | Not Found | | +| 500 | Internal Server Error | | +| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | ## POST `/v1/query` > **Query Endpoint Handler** @@ -442,6 +529,34 @@ Handle request to delete a conversation by ID. | 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) | | 404 | Not Found | | | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | +## PUT `/v2/conversations/{conversation_id}` + +> **Update Conversation Endpoint Handler** + +Handle request to update a conversation topic summary by ID. + + + +### 🔗 Parameters + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| conversation_id | string | True | | + + +### 📦 Request Body + +[ConversationUpdateRequest](#conversationupdaterequest) + +### ✅ Responses + +| Status Code | Description | Component | +|-------------|-------------|-----------| +| 200 | Successful Response | [ConversationUpdateResponse](#conversationupdateresponse) | +| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) | +| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) | +| 404 | Not Found | | +| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | ## GET `/readiness` > **Readiness Probe Get Method** @@ -624,6 +739,22 @@ Attributes: | skip_userid_check | boolean | Whether to skip the user ID check | +## ByokRag + + +BYOK RAG configuration. + + +| Field | Type | Description | +|-------|------|-------------| +| rag_id | string | | +| rag_type | string | | +| embedding_model | string | | +| embedding_dimension | integer | | +| vector_db_id | string | | +| db_path | string | | + + ## CORSConfiguration @@ -657,6 +788,7 @@ Global service configuration. | customization | | | | inference | | | | conversation_cache | | | +| byok_rag | array | | ## ConversationCacheConfiguration @@ -790,6 +922,54 @@ Example: | chat_history | array | The simplified chat history as a list of conversation turns | +## ConversationUpdateRequest + + +Model representing a request to update a conversation topic summary. + +Attributes: + topic_summary: The new topic summary for the conversation. + +Example: + ```python + update_request = ConversationUpdateRequest( + topic_summary="Discussion about machine learning algorithms" + ) + ``` + + +| Field | Type | Description | +|-------|------|-------------| +| topic_summary | string | The new topic summary for the conversation | + + +## ConversationUpdateResponse + + +Model representing a response for updating a conversation topic summary. + +Attributes: + conversation_id: The conversation ID (UUID) that was updated. + success: Whether the update was successful. + message: A message about the update result. + +Example: + ```python + update_response = ConversationUpdateResponse( + conversation_id="123e4567-e89b-12d3-a456-426614174000", + success=True, + message="Topic summary updated successfully", + ) + ``` + + +| Field | Type | Description | +|-------|------|-------------| +| conversation_id | string | The conversation ID (UUID) that was updated | +| success | boolean | Whether the update was successful | +| message | string | A message about the update result | + + ## ConversationsListResponse @@ -1219,6 +1399,32 @@ Attributes: | message | | Optional message about the health status | +## ProviderResponse + + +Model representing a response to get specific provider request. + + +| Field | Type | Description | +|-------|------|-------------| +| api | string | The API this provider implements | +| config | object | Provider configuration parameters | +| health | object | Current health status of the provider | +| provider_id | string | Unique provider identifier | +| provider_type | string | Provider implementation type | + + +## ProvidersListResponse + + +Model representing a response to providers request. + + +| Field | Type | Description | +|-------|------|-------------| +| providers | object | List of available API types and their corresponding providers | + + ## QueryRequest @@ -1430,6 +1636,17 @@ Model representing a tool call made during response generation. | result | | Result from the tool | +## ToolsResponse + + +Model representing a response to tools request. + + +| Field | Type | Description | +|-------|------|-------------| +| tools | array | List of tools available from all configured MCP servers and built-in toolgroups | + + ## UnauthorizedResponse diff --git a/docs/output.md b/docs/output.md index 6bbba993..8a23abfc 100644 --- a/docs/output.md +++ b/docs/output.md @@ -80,6 +80,33 @@ Returns: |-------------|-------------|-----------| | 200 | Successful Response | [ModelsResponse](#modelsresponse) | | 500 | Connection to Llama Stack is broken | | +## GET `/v1/tools` + +> **Tools Endpoint Handler** + +Handle requests to the /tools endpoint. + +Process GET requests to the /tools endpoint, returning a consolidated list of +available tools from all configured MCP servers. + +Raises: + HTTPException: If unable to connect to the Llama Stack server or if + tool retrieval fails for any reason. + +Returns: + ToolsResponse: An object containing the consolidated list of available tools + with metadata including tool name, description, parameters, and server source. + + + + + +### ✅ Responses + +| Status Code | Description | Component | +|-------------|-------------|-----------| +| 200 | Successful Response | [ToolsResponse](#toolsresponse) | +| 500 | Connection to Llama Stack is broken or MCP server error | | ## GET `/v1/shields` > **Shields Endpoint Handler** @@ -106,6 +133,66 @@ Returns: |-------------|-------------|-----------| | 200 | Successful Response | [ShieldsResponse](#shieldsresponse) | | 500 | Connection to Llama Stack is broken | | +## GET `/v1/providers` + +> **Providers Endpoint Handler** + +Handle GET requests to list all available providers. + +Retrieves providers from the Llama Stack service, groups them by API type. + +Raises: + HTTPException: + - 500 if configuration is not loaded, + - 500 if unable to connect to Llama Stack, + - 500 for any unexpected retrieval errors. + +Returns: + ProvidersListResponse: Object mapping API types to lists of providers. + + + + + +### ✅ Responses + +| Status Code | Description | Component | +|-------------|-------------|-----------| +| 200 | Successful Response | [ProvidersListResponse](#providerslistresponse) | +| 500 | Connection to Llama Stack is broken | | +## GET `/v1/providers/{provider_id}` + +> **Get Provider Endpoint Handler** + +Retrieve a single provider by its unique ID. + +Raises: + HTTPException: + - 404 if provider with the given ID is not found, + - 500 if unable to connect to Llama Stack, + - 500 for any unexpected retrieval errors. + +Returns: + ProviderResponse: A single provider's details including API, config, health, + provider_id, and provider_type. + + + +### 🔗 Parameters + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| provider_id | string | True | | + + +### ✅ Responses + +| Status Code | Description | Component | +|-------------|-------------|-----------| +| 200 | Successful Response | [ProviderResponse](#providerresponse) | +| 404 | Not Found | | +| 500 | Internal Server Error | | +| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | ## POST `/v1/query` > **Query Endpoint Handler** @@ -442,6 +529,34 @@ Handle request to delete a conversation by ID. | 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) | | 404 | Not Found | | | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | +## PUT `/v2/conversations/{conversation_id}` + +> **Update Conversation Endpoint Handler** + +Handle request to update a conversation topic summary by ID. + + + +### 🔗 Parameters + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| conversation_id | string | True | | + + +### 📦 Request Body + +[ConversationUpdateRequest](#conversationupdaterequest) + +### ✅ Responses + +| Status Code | Description | Component | +|-------------|-------------|-----------| +| 200 | Successful Response | [ConversationUpdateResponse](#conversationupdateresponse) | +| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) | +| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) | +| 404 | Not Found | | +| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | ## GET `/readiness` > **Readiness Probe Get Method** @@ -624,6 +739,22 @@ Attributes: | skip_userid_check | boolean | Whether to skip the user ID check | +## ByokRag + + +BYOK RAG configuration. + + +| Field | Type | Description | +|-------|------|-------------| +| rag_id | string | | +| rag_type | string | | +| embedding_model | string | | +| embedding_dimension | integer | | +| vector_db_id | string | | +| db_path | string | | + + ## CORSConfiguration @@ -657,6 +788,7 @@ Global service configuration. | customization | | | | inference | | | | conversation_cache | | | +| byok_rag | array | | ## ConversationCacheConfiguration @@ -790,6 +922,54 @@ Example: | chat_history | array | The simplified chat history as a list of conversation turns | +## ConversationUpdateRequest + + +Model representing a request to update a conversation topic summary. + +Attributes: + topic_summary: The new topic summary for the conversation. + +Example: + ```python + update_request = ConversationUpdateRequest( + topic_summary="Discussion about machine learning algorithms" + ) + ``` + + +| Field | Type | Description | +|-------|------|-------------| +| topic_summary | string | The new topic summary for the conversation | + + +## ConversationUpdateResponse + + +Model representing a response for updating a conversation topic summary. + +Attributes: + conversation_id: The conversation ID (UUID) that was updated. + success: Whether the update was successful. + message: A message about the update result. + +Example: + ```python + update_response = ConversationUpdateResponse( + conversation_id="123e4567-e89b-12d3-a456-426614174000", + success=True, + message="Topic summary updated successfully", + ) + ``` + + +| Field | Type | Description | +|-------|------|-------------| +| conversation_id | string | The conversation ID (UUID) that was updated | +| success | boolean | Whether the update was successful | +| message | string | A message about the update result | + + ## ConversationsListResponse @@ -1219,6 +1399,32 @@ Attributes: | message | | Optional message about the health status | +## ProviderResponse + + +Model representing a response to get specific provider request. + + +| Field | Type | Description | +|-------|------|-------------| +| api | string | The API this provider implements | +| config | object | Provider configuration parameters | +| health | object | Current health status of the provider | +| provider_id | string | Unique provider identifier | +| provider_type | string | Provider implementation type | + + +## ProvidersListResponse + + +Model representing a response to providers request. + + +| Field | Type | Description | +|-------|------|-------------| +| providers | object | List of available API types and their corresponding providers | + + ## QueryRequest @@ -1430,6 +1636,17 @@ Model representing a tool call made during response generation. | result | | Result from the tool | +## ToolsResponse + + +Model representing a response to tools request. + + +| Field | Type | Description | +|-------|------|-------------| +| tools | array | List of tools available from all configured MCP servers and built-in toolgroups | + + ## UnauthorizedResponse