Skip to content

[Draft] LCORE-390: description for more fields #394

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 5 commits into from
Closed

[Draft] LCORE-390: description for more fields #394

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6e5a1a6
Field description for Authentication configuration
tisnik Aug 13, 2025
ce800e3
Field description for Authorized response
tisnik Aug 13, 2025
39fd655
Field description for TLS configuration
tisnik Aug 13, 2025
53e4c9f
Regenerated OpenAPI documentation
tisnik Aug 13, 2025
a835ceb
Updated unit tests accordingly
tisnik Aug 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 62 additions & 42 deletions docs/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@
"models"
],
"summary": "Models Endpoint Handler",
"description": "Handle requests to the /models endpoint.",
"description": "Handle requests to the /models endpoint.\n\nProcess GET requests to the /models endpoint, returning a list of available\nmodels from the Llama Stack service.\n\nRaises:\n HTTPException: If unable to connect to the Llama Stack server or if\n model retrieval fails for any reason.\n\nReturns:\n ModelsResponse: An object containing the list of available models.",
"operationId": "models_endpoint_handler_v1_models_get",
"responses": {
"200": {
Expand Down Expand Up @@ -300,7 +300,7 @@
"feedback"
],
"summary": "Feedback Endpoint Handler",
"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.",
"description": "Handle feedback requests.\n\nProcesses a user feedback submission, storing the feedback and\nreturning a confirmation response.\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.\n\nRaises:\n HTTPException: Returns HTTP 500 if feedback storage fails.",
"operationId": "feedback_endpoint_handler_v1_feedback_post",
"requestBody": {
"content": {
Expand Down Expand Up @@ -372,7 +372,7 @@
"feedback"
],
"summary": "Feedback Status",
"description": "Handle feedback status requests.\n\nReturns:\n Response indicating the status of the feedback.",
"description": "Handle feedback status requests.\n\nReturn the current enabled status of the feedback\nfunctionality.\n\nReturns:\n StatusResponse: Indicates whether feedback collection is enabled.",
"operationId": "feedback_status_v1_feedback_status_get",
"responses": {
"200": {
Expand Down Expand Up @@ -441,7 +441,7 @@
"conversations"
],
"summary": "Get Conversation Endpoint Handler",
"description": "Handle request to retrieve a conversation by ID.",
"description": "Handle request to retrieve a conversation by ID.\n\nRetrieve a conversation's chat history by its ID. Then fetches\nthe conversation session from the Llama Stack backend,\nsimplifies the session data to essential chat history, and\nreturns it in a structured response. Raises HTTP 400 for\ninvalid IDs, 404 if not found, 503 if the backend is\nunavailable, and 500 for unexpected errors.\n\nParameters:\n conversation_id (str): Unique identifier of the conversation to retrieve.\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": [
{
Expand Down Expand Up @@ -513,7 +513,7 @@
"conversations"
],
"summary": "Delete Conversation Endpoint Handler",
"description": "Handle request to delete a conversation by ID.",
"description": "Handle request to delete a conversation by ID.\n\nValidates the conversation ID format and attempts to delete the\ncorresponding session from the Llama Stack backend. Raises HTTP\nerrors for invalid IDs, not found conversations, connection\nissues, or unexpected failures.\n\nReturns:\n ConversationDeleteResponse: Response indicating the result of the deletion operation.",
"operationId": "delete_conversation_endpoint_handler_v1_conversations__conversation_id__delete",
"parameters": [
{
Expand Down Expand Up @@ -756,12 +756,24 @@
"module": {
"type": "string",
"title": "Module",
"default": "noop"
"description": "Authentication module to be used for REST API",
"default": "noop",
"examples": [
"noop",
"noop-with-token",
"k8s",
"jwk-token"
]
},
"skip_tls_verification": {
"type": "boolean",
"title": "Skip Tls Verification",
"default": false
"description": "If set to true, the service skips TLS certificate verification",
"default": false,
"examples": [
true,
false
]
},
"k8s_cluster_api": {
"anyOf": [
Expand All @@ -774,7 +786,11 @@
"type": "null"
}
],
"title": "K8S Cluster Api"
"title": "K8S Cluster Api",
"description": "The URL of the K8S/OCP API server where tokens are validated",
"examples": [
"http://localhost:8080/api/validation/"
]
},
"k8s_ca_cert_path": {
"anyOf": [
Expand All @@ -786,7 +802,11 @@
"type": "null"
}
],
"title": "K8S Ca Cert Path"
"title": "K8S Ca Cert Path",
"description": "Path to a CA certificate for clusters with self-signed certificates",
"examples": [
"/tmp/certs.crt"
]
},
"jwk_config": {
"anyOf": [
Expand All @@ -796,7 +816,8 @@
{
"type": "null"
}
]
],
"description": "JWK configuration"
}
},
"type": "object",
Expand All @@ -807,11 +828,20 @@
"properties": {
"user_id": {
"type": "string",
"title": "User Id"
"title": "User Id",
"description": "User ID, for example UUID",
"examples": [
"c5260aec-4d82-4370-9fdf-05cf908b3f16"
]
},
"username": {
"type": "string",
"title": "Username"
"title": "Username",
"description": "User name",
"examples": [
"John Doe",
"Adam Smith"
]
}
},
"type": "object",
Expand Down Expand Up @@ -1140,33 +1170,6 @@
"title": "DatabaseConfiguration",
"description": "Database configuration."
},
"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."
},
"ErrorResponse": {
"properties": {
"detail": {
Expand Down Expand Up @@ -2016,7 +2019,11 @@
"type": "null"
}
],
"title": "Tls Certificate Path"
"title": "Tls Certificate Path",
"description": "Path to TLS certificate",
"examples": [
"/etc/certs/certs.pem"
]
},
"tls_key_path": {
"anyOf": [
Expand All @@ -2028,7 +2035,11 @@
"type": "null"
}
],
"title": "Tls Key Path"
"title": "Tls Key Path",
"description": "Path to TLS certificate key",
"examples": [
"/etc/certs/key.pem"
]
},
"tls_key_password": {
"anyOf": [
Expand All @@ -2040,10 +2051,19 @@
"type": "null"
}
],
"title": "Tls Key Password"
"title": "Tls Key Password",
"description": "Path to file containing TLS key passowrd",
"examples": [
"/app-root/certs/password.txt"
]
}
},
"type": "object",
"required": [
"tls_certificate_path",
"tls_key_path",
"tls_key_password"
],
"title": "TLSConfiguration",
"description": "TLS configuration."
},
Expand Down
63 changes: 52 additions & 11 deletions docs/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,16 @@ Returns:

Handle requests to the /models endpoint.

Process GET requests to the /models endpoint, returning a list of available
models from the Llama Stack service.

Raises:
HTTPException: If unable to connect to the Llama Stack server or if
model retrieval fails for any reason.

Returns:
ModelsResponse: An object containing the list of available models.




Expand Down Expand Up @@ -138,6 +148,9 @@ Returns:

Handle feedback requests.

Processes a user feedback submission, storing the feedback and
returning a confirmation response.

Args:
feedback_request: The request containing feedback information.
ensure_feedback_enabled: The feedback handler (FastAPI Depends) that
Expand All @@ -148,6 +161,9 @@ Args:
Returns:
Response indicating the status of the feedback storage request.

Raises:
HTTPException: Returns HTTP 500 if feedback storage fails.




Expand All @@ -171,8 +187,11 @@ Returns:

Handle feedback status requests.

Return the current enabled status of the feedback
functionality.

Returns:
Response indicating the status of the feedback.
StatusResponse: Indicates whether feedback collection is enabled.



Expand Down Expand Up @@ -205,6 +224,20 @@ Handle request to retrieve all conversations for the authenticated user.

Handle request to retrieve a conversation by ID.

Retrieve a conversation's chat history by its ID. Then fetches
the conversation session from the Llama Stack backend,
simplifies the session data to essential chat history, and
returns it in a structured response. Raises HTTP 400 for
invalid IDs, 404 if not found, 503 if the backend is
unavailable, and 500 for unexpected errors.

Parameters:
conversation_id (str): Unique identifier of the conversation to retrieve.

Returns:
ConversationResponse: Structured response containing the conversation
ID and simplified chat history.



### 🔗 Parameters
Expand All @@ -228,6 +261,14 @@ Handle request to retrieve a conversation by ID.

Handle request to delete a conversation by ID.

Validates the conversation ID format and attempts to delete the
corresponding session from the Llama Stack backend. Raises HTTP
errors for invalid IDs, not found conversations, connection
issues, or unexpected failures.

Returns:
ConversationDeleteResponse: Response indicating the result of the deletion operation.



### 🔗 Parameters
Expand Down Expand Up @@ -372,11 +413,11 @@ Authentication configuration.

| Field | Type | Description |
|-------|------|-------------|
| module | string | |
| skip_tls_verification | boolean | |
| k8s_cluster_api | | |
| k8s_ca_cert_path | | |
| jwk_config | | |
| module | string | Authentication module to be used for REST API |
| skip_tls_verification | boolean | If set to true, the service skips TLS certificate verification |
| k8s_cluster_api | | The URL of the K8S/OCP API server where tokens are validated |
| k8s_ca_cert_path | | Path to a CA certificate for clusters with self-signed certificates |
| jwk_config | | JWK configuration |


## AuthorizedResponse
Expand All @@ -391,8 +432,8 @@ Attributes:

| Field | Type | Description |
|-------|------|-------------|
| user_id | string | |
| username | string | |
| user_id | string | User ID, for example UUID |
| username | string | User name |


## Configuration
Expand Down Expand Up @@ -973,9 +1014,9 @@ TLS configuration.

| Field | Type | Description |
|-------|------|-------------|
| tls_certificate_path | | |
| tls_key_path | | |
| tls_key_password | | |
| tls_certificate_path | | Path to TLS certificate |
| tls_key_path | | Path to TLS certificate key |
| tls_key_password | | Path to file containing TLS key passowrd |


## UnauthorizedResponse
Expand Down
Loading
Loading