openapi.json

{
    "openapi": "3.1.0",
    "info": {
        "title": "Swagger OpenShift LightSpeed Service - OpenAPI",
        "description": "OpenShift LightSpeed Service API specification.",
        "version": "0.2.0"
    },
    "paths": {
        "/v1/query": {
            "post": {
                "tags": [
                    "query"
                ],
                "summary": "Conversation Request",
                "description": "Handle conversation requests for the OLS endpoint.\n\nArgs:\n    llm_request: The request containing a query, conversation ID, and optional attachments.\n    auth: The Authentication handler (FastAPI Depends) that will handle authentication Logic.\n\nReturns:\n    Response containing the processed information.",
                "operationId": "conversation_request_v1_query_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/LLMRequest"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Query is valid and correct response from LLM is returned",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/LLMResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid credentials provided by client",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/UnauthorizedResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Client does not have permission to access resource",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ForbiddenResponse"
                                }
                            }
                        }
                    },
                    "413": {
                        "description": "Prompt is too long",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PromptTooLongResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Query can not be validated, LLM is not accessible or other internal error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/feedback/status": {
            "get": {
                "tags": [
                    "feedback"
                ],
                "summary": "Feedback Status",
                "description": "Handle feedback status requests.\n\nReturns:\n    Response indicating the status of the feedback.",
                "operationId": "feedback_status_v1_feedback_status_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/StatusResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/feedback": {
            "post": {
                "tags": [
                    "feedback"
                ],
                "summary": "Store User Feedback",
                "description": "Handle feedback requests.\n\nArgs:\n    feedback_request: The request containing feedback information.\n    ensure_feedback_enabled: The feedback handler (FastAPI Depends) that\n        will handle feedback status checks.\n    auth: The Authentication handler (FastAPI Depends) that will\n        handle authentication Logic.\n\nReturns:\n    Response indicating the status of the feedback storage request.",
                "operationId": "store_user_feedback_v1_feedback_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/FeedbackRequest"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Feedback received and stored",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/FeedbackResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid credentials provided by client",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/UnauthorizedResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Client does not have permission to access resource",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ForbiddenResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "User feedback can not be stored",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/readiness": {
            "get": {
                "tags": [
                    "health"
                ],
                "summary": "Readiness Probe Get Method",
                "description": "Ready status of service.",
                "operationId": "readiness_probe_get_method_readiness_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReadinessResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/liveness": {
            "get": {
                "tags": [
                    "health"
                ],
                "summary": "Liveness Probe Get Method",
                "description": "Live status of service.",
                "operationId": "liveness_probe_get_method_liveness_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/LivenessResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/metrics": {
            "get": {
                "tags": [
                    "metrics"
                ],
                "summary": "Get Metrics",
                "description": "Metrics Endpoint.\n\nArgs:\n    auth: The Authentication handler (FastAPI Depends) that will handle authentication Logic.\n\nReturns:\n    Response containing the latest metrics.",
                "operationId": "get_metrics_metrics_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "text/plain": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/authorized": {
            "post": {
                "tags": [
                    "authorized"
                ],
                "summary": "Is User Authorized",
                "description": "Validate if the logged-in user is authorized to access OLS.\n\nParameters:\n    request (Request): The FastAPI request object.\n\nReturns:\n    The user's UID and username if authentication and authorization succeed.\n\nRaises:\n    HTTPException: If authentication fails or the user does not have access.",
                "operationId": "is_user_authorized_authorized_post",
                "responses": {
                    "200": {
                        "description": "The user is logged-in and authorized to access OLS",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AuthorizationResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid credentials provided by client",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/UnauthorizedResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "User is not authorized",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ForbiddenResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Unexpected error during token review",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Attachment": {
                "properties": {
                    "attachment_type": {
                        "type": "string",
                        "title": "Attachment Type"
                    },
                    "content_type": {
                        "type": "string",
                        "title": "Content Type"
                    },
                    "content": {
                        "type": "string",
                        "title": "Content"
                    }
                },
                "type": "object",
                "required": [
                    "attachment_type",
                    "content_type",
                    "content"
                ],
                "title": "Attachment",
                "description": "Model representing an attachment that can be send from UI as part of query.\n\nList of attachments can be optional part of 'query' request.\n\nAttributes:\n    attachment_type: The attachment type, like \"log\", \"configuration\" etc.\n    content_type: The content type as defined in MIME standard\n    content: The actual attachment content\n\nYAML attachments with **kind** and **metadata/name** attributes will\nbe handled as resources with specified name:\n```\nkind: Pod\nmetadata:\n    name: private-reg\n```",
                "examples": [
                    {
                        "attachment_type": "log",
                        "content": "this is attachment",
                        "content_type": "text/plain"
                    },
                    {
                        "attachment_type": "configuration",
                        "content": "kind: Pod\n metadata:\n name:    private-reg",
                        "content_type": "application/yaml"
                    },
                    {
                        "attachment_type": "configuration",
                        "content": "foo: bar",
                        "content_type": "application/yaml"
                    }
                ]
            },
            "AuthorizationResponse": {
                "properties": {
                    "user_id": {
                        "type": "string",
                        "title": "User Id"
                    },
                    "username": {
                        "type": "string",
                        "title": "Username"
                    }
                },
                "type": "object",
                "required": [
                    "user_id",
                    "username"
                ],
                "title": "AuthorizationResponse",
                "description": "Model representing a response to an authorization request.\n\nAttributes:\n    user_id: The ID of the logged in user.\n    username: The name of the logged in user.",
                "examples": [
                    {
                        "user_id": "123e4567-e89b-12d3-a456-426614174000",
                        "username": "user1"
                    }
                ]
            },
            "ErrorResponse": {
                "properties": {
                    "detail": {
                        "additionalProperties": {
                            "type": "string"
                        },
                        "type": "object",
                        "title": "Detail"
                    }
                },
                "type": "object",
                "required": [
                    "detail"
                ],
                "title": "ErrorResponse",
                "description": "Model representing error response for query endpoint.",
                "examples": [
                    {
                        "detail": {
                            "cause": "Failed to handle request to https://bam-api.res.ibm.com/v2/text",
                            "response": "Error while validation question"
                        }
                    },
                    {
                        "detail": {
                            "cause": "Invalid conversation ID 1237-e89b-12d3-a456-426614174000",
                            "response": "Error retrieving conversation history"
                        }
                    }
                ]
            },
            "FeedbackRequest": {
                "properties": {
                    "conversation_id": {
                        "type": "string",
                        "title": "Conversation Id"
                    },
                    "user_question": {
                        "type": "string",
                        "title": "User Question"
                    },
                    "llm_response": {
                        "type": "string",
                        "title": "Llm Response"
                    },
                    "sentiment": {
                        "anyOf": [
                            {
                                "type": "integer"
                            },
                            {
                                "type": "null"
                            }
                        ],
                        "title": "Sentiment"
                    },
                    "user_feedback": {
                        "anyOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ],
                        "title": "User Feedback"
                    }
                },
                "type": "object",
                "required": [
                    "conversation_id",
                    "user_question",
                    "llm_response"
                ],
                "title": "FeedbackRequest",
                "description": "Model representing a feedback request.\n\nAttributes:\n    conversation_id: The required conversation ID (UUID).\n    user_question: The required user question.\n    llm_response: The required LLM response.\n    sentiment: The optional sentiment.\n    user_feedback: The optional user feedback.\n\nExample:\n    ```python\n    feedback_request = FeedbackRequest(\n        conversation_id=\"12345678-abcd-0000-0123-456789abcdef\",\n        user_question=\"what are you doing?\",\n        user_feedback=\"Great service!\",\n        llm_response=\"I don't know\",\n        sentiment=-1,\n    )\n    ```",
                "examples": [
                    {
                        "conversation_id": "12345678-abcd-0000-0123-456789abcdef",
                        "llm_response": "bar",
                        "sentiment": 1,
                        "user_feedback": "Great service!",
                        "user_question": "foo"
                    }
                ]
            },
            "FeedbackResponse": {
                "properties": {
                    "response": {
                        "type": "string",
                        "title": "Response"
                    }
                },
                "type": "object",
                "required": [
                    "response"
                ],
                "title": "FeedbackResponse",
                "description": "Model representing a response to a feedback request.\n\nAttributes:\n    response: The response of the feedback request.\n\nExample:\n    ```python\n    feedback_response = FeedbackResponse(response=\"feedback received\")\n    ```",
                "examples": [
                    {
                        "response": "feedback received"
                    }
                ]
            },
            "ForbiddenResponse": {
                "properties": {
                    "detail": {
                        "type": "string",
                        "title": "Detail"
                    }
                },
                "type": "object",
                "required": [
                    "detail"
                ],
                "title": "ForbiddenResponse",
                "description": "Model representing response when client does not have permission to access resource.",
                "examples": [
                    {
                        "detail": "Unable to review token"
                    }
                ]
            },
            "HTTPValidationError": {
                "properties": {
                    "detail": {
                        "items": {
                            "$ref": "#/components/schemas/ValidationError"
                        },
                        "type": "array",
                        "title": "Detail"
                    }
                },
                "type": "object",
                "title": "HTTPValidationError"
            },
            "LLMRequest": {
                "properties": {
                    "query": {
                        "type": "string",
                        "title": "Query"
                    },
                    "conversation_id": {
                        "anyOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ],
                        "title": "Conversation Id"
                    },
                    "provider": {
                        "anyOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ],
                        "title": "Provider"
                    },
                    "model": {
                        "anyOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "null"
                            }
                        ],
                        "title": "Model"
                    },
                    "attachments": {
                        "anyOf": [
                            {
                                "items": {
                                    "$ref": "#/components/schemas/Attachment"
                                },
                                "type": "array"
                            },
                            {
                                "type": "null"
                            }
                        ],
                        "title": "Attachments"
                    }
                },
                "additionalProperties": false,
                "type": "object",
                "required": [
                    "query"
                ],
                "title": "LLMRequest",
                "description": "Model representing a request for the LLM (Language Model) send into OLS service.\n\nAttributes:\n    query: The query string.\n    conversation_id: The optional conversation ID (UUID).\n    provider: The optional provider.\n    model: The optional model.\n    attachments: The optional attachments.\n\nExample:\n    ```python\n    llm_request = LLMRequest(query=\"Tell me about Kubernetes\")\n    ```",
                "examples": [
                    {
                        "attachments": [
                            {
                                "attachment_type": "log",
                                "content": "this is attachment",
                                "content_type": "text/plain"
                            },
                            {
                                "attachment_type": "configuration",
                                "content": "kind: Pod\n metadata:\n    name: private-reg",
                                "content_type": "application/yaml"
                            },
                            {
                                "attachment_type": "configuration",
                                "content": "foo: bar",
                                "content_type": "application/yaml"
                            }
                        ],
                        "conversation_id": "123e4567-e89b-12d3-a456-426614174000",
                        "model": "gpt-3.5-turbo",
                        "provider": "openai",
                        "query": "write a deployment yaml for the mongodb image"
                    }
                ]
            },
            "LLMResponse": {
                "properties": {
                    "conversation_id": {
                        "type": "string",
                        "title": "Conversation Id"
                    },
                    "response": {
                        "type": "string",
                        "title": "Response"
                    },
                    "referenced_documents": {
                        "items": {
                            "$ref": "#/components/schemas/ReferencedDocument"
                        },
                        "type": "array",
                        "title": "Referenced Documents"
                    },
                    "truncated": {
                        "type": "boolean",
                        "title": "Truncated"
                    }
                },
                "type": "object",
                "required": [
                    "conversation_id",
                    "response",
                    "referenced_documents",
                    "truncated"
                ],
                "title": "LLMResponse",
                "description": "Model representing a response from the LLM (Language Model).\n\nAttributes:\n    conversation_id: The optional conversation ID (UUID).\n    response: The optional response.\n    referenced_documents: The optional URLs and titles for the documents used\n                          to generate the response.\n    truncated: Set to True if conversation history was truncated to be within context window.",
                "examples": [
                    {
                        "conversation_id": "123e4567-e89b-12d3-a456-426614174000",
                        "referenced_documents": [
                            {
                                "docs_url": "https://docs.openshift.com/container-platform/4.15/operators/understanding/olm/olm-understanding-olm.html",
                                "title": "Operator Lifecycle Manager concepts and resources"
                            }
                        ],
                        "response": "Operator Lifecycle Manager (OLM) helps users install...",
                        "truncated": false
                    }
                ]
            },
            "LivenessResponse": {
                "properties": {
                    "alive": {
                        "type": "boolean",
                        "title": "Alive"
                    }
                },
                "type": "object",
                "required": [
                    "alive"
                ],
                "title": "LivenessResponse",
                "description": "Model representing a response to a liveness request.\n\nAttributes:\n    alive: If app is alive.\n\nExample:\n    ```python\n    liveness_response = LivenessResponse(alive=True)\n    ```",
                "examples": [
                    {
                        "alive": true
                    }
                ]
            },
            "PromptTooLongResponse": {
                "properties": {
                    "detail": {
                        "additionalProperties": {
                            "type": "string"
                        },
                        "type": "object",
                        "title": "Detail"
                    }
                },
                "type": "object",
                "required": [
                    "detail"
                ],
                "title": "PromptTooLongResponse",
                "description": "Model representing error response when prompt is too long.",
                "examples": [
                    {
                        "detail": {
                            "cause": "Prompt length exceeds LLM context window limit (8000 tokens)",
                            "response": "Prompt is too long"
                        }
                    }
                ]
            },
            "ReadinessResponse": {
                "properties": {
                    "ready": {
                        "type": "boolean",
                        "title": "Ready"
                    },
                    "reason": {
                        "type": "string",
                        "title": "Reason"
                    }
                },
                "type": "object",
                "required": [
                    "ready",
                    "reason"
                ],
                "title": "ReadinessResponse",
                "description": "Model representing a response to a readiness request.\n\nAttributes:\n    ready: The readiness of the service.\n    reason: The reason for the readiness.\n\nExample:\n    ```python\n    readiness_response = ReadinessResponse(ready=True, reason=\"service is ready\")\n    ```",
                "examples": [
                    {
                        "ready": true,
                        "reason": "service is ready"
                    }
                ]
            },
            "ReferencedDocument": {
                "properties": {
                    "docs_url": {
                        "type": "string",
                        "title": "Docs Url"
                    },
                    "title": {
                        "type": "string",
                        "title": "Title"
                    }
                },
                "type": "object",
                "required": [
                    "docs_url",
                    "title"
                ],
                "title": "ReferencedDocument",
                "description": "RAG referenced document.\n\nAttributes:\ndocs_url: URL of the corresponding OCP documentation page\ntitle: Title of the corresponding OCP documentation page"
            },
            "StatusResponse": {
                "properties": {
                    "functionality": {
                        "type": "string",
                        "title": "Functionality"
                    },
                    "status": {
                        "type": "object",
                        "title": "Status"
                    }
                },
                "type": "object",
                "required": [
                    "functionality",
                    "status"
                ],
                "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
                        }
                    }
                ]
            },
            "UnauthorizedResponse": {
                "properties": {
                    "detail": {
                        "type": "string",
                        "title": "Detail"
                    }
                },
                "type": "object",
                "required": [
                    "detail"
                ],
                "title": "UnauthorizedResponse",
                "description": "Model representing response for missing or invalid credentials.",
                "examples": [
                    {
                        "detail": "Unauthorized: No auth header found"
                    }
                ]
            },
            "ValidationError": {
                "properties": {
                    "loc": {
                        "items": {
                            "anyOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "integer"
                                }
                            ]
                        },
                        "type": "array",
                        "title": "Location"
                    },
                    "msg": {
                        "type": "string",
                        "title": "Message"
                    },
                    "type": {
                        "type": "string",
                        "title": "Error Type"
                    }
                },
                "type": "object",
                "required": [
                    "loc",
                    "msg",
                    "type"
                ],
                "title": "ValidationError"
            }
        }
    }
}