Skip to content

LCORE-390: fields in response structures #399

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

Merged
tisnik merged 2 commits into from
Aug 14, 2025
Merged

LCORE-390: fields in response structures #399

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
053090b
Fields for ModelResponse, QueryResponse, InfoResponse, and ErrorResponse
tisnik Aug 14, 2025
6421f35
Regenerated OpenAPI specification
tisnik Aug 14, 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
121 changes: 73 additions & 48 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",
Comment on lines +77 to 78
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

OpenAPI responses contain invalid top-level keys (examples placed outside content).

Several path responses (e.g., 200 for /v1/models, /v1/info, /v1/query, /v1/conversations, etc.) include properties like models, conversation_id, response, chat_history, etc., at the same level as description/content. In OpenAPI, examples must be placed under content -> media type -> example or examples. Keeping them at the response root violates the spec and will break validators/clients.

Run this script to detect non-standard keys under response objects:

As a fix pattern, move those objects under content.application/json.example. For instance, for /v1/models 200:

"200": {
  "description": "Successful Response",
  "content": {
    "application/json": {
      "schema": { "$ref": "#/components/schemas/ModelsResponse" },
      "example": {
        "models": [ { "identifier": "...", "type": "model" } ]
      }
    }
  }
}

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

# Finds response objects that contain keys other than the allowed set:
# description, headers, content, links, $ref, and extension keys (x-*)
jq -r '
  .paths
  | to_entries[] as $p
  | $p.value
  | to_entries[] as $m
  | ($m.value.responses // {}) 
  | to_entries[]
  | . as $r
  | ($r.value | keys_unsorted
      | map(select(. as $k | . != "description" and . != "headers" and . != "content" and . != "links" and . != "$ref" and (startswith("x-") | not)))
    ) as $bad
  | select($bad | length > 0)
  | "\($p.key) \($m.key) status \($r.key) invalid keys: \($bad|join(", "))"
' docs/openapi.json

Length of output: 1445

Move non-standard response keys into content (fix required)

The jq check confirms multiple responses in docs/openapi.json contain invalid top-level keys (examples/fields placed outside content), which violates the OpenAPI spec and will break validators/clients.

Locations found (file: docs/openapi.json):

  • /v1/info GET 200 — invalid keys: name, version
  • /v1/models GET 200 — invalid keys: models
  • /v1/query POST 200 — invalid keys: conversation_id, response
  • /v1/query POST 503 — invalid keys: detail
  • /v1/config GET 200 — invalid keys: name, service, llama_stack, user_data_collection, mcp_servers
  • /v1/config GET 503 — invalid keys: detail
  • /v1/conversations GET 200 — invalid keys: conversations
  • /v1/conversations GET 503 — invalid keys: detail
  • /v1/conversations/{conversation_id} GET 200 — invalid keys: conversation_id, chat_history
  • /v1/conversations/{conversation_id} GET 404 — invalid keys: detail
  • /v1/conversations/{conversation_id} GET 503 — invalid keys: detail
  • /v1/conversations/{conversation_id} DELETE 200 — invalid keys: conversation_id, success, message
  • /v1/conversations/{conversation_id} DELETE 404 — invalid keys: detail
  • /v1/conversations/{conversation_id} DELETE 503 — invalid keys: detail

Fix pattern (example) — move these fields under content -> application/json -> example (and include a matching schema):

"200": {
  "description": "Successful Response",
  "content": {
    "application/json": {
      "schema": { "$ref": "#/components/schemas/ModelsResponse" },
      "example": {
        "models": [{ "identifier": "ggml-model", "type": "model" }]
      }
    }
  }
}

Error example (503):

"503": {
  "description": "Service Unavailable",
  "content": {
    "application/json": {
      "schema": { "$ref": "#/components/schemas/ErrorResponse" },
      "example": { "detail": "Llama Stack unreachable" }
    }
  }
}

Notes: allowed response root keys are description, headers, content, links, $ref, and vendor extensions (x-*). Move all other top-level fields (models, conversation_id, response, detail, etc.) into content.application/json.example or content.application/json.examples and ensure corresponding schemas exist under #/components/schemas. Re-run an OpenAPI validator after updating.

🤖 Prompt for AI Agents 
In docs/openapi.json around lines 77-78, multiple response objects include
non-standard top-level keys (e.g., models, conversation_id, response, detail,
name, version, etc.) which violate OpenAPI; move those fields into the
response.content.application/json.example (or examples) and attach a matching
schema under components/schemas (or reference an existing one) for each response
code (e.g., 200 -> ModelsResponse, 503 -> ErrorResponse); ensure each response
object only uses allowed root keys (description, headers, content, links, $ref,
x-*) and then re-run an OpenAPI validator to confirm all invalid top-level keys
are removed.

"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 @@ -807,11 +807,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 @@ -860,14 +869,7 @@
"default": []
},
"authentication": {
"anyOf": [
{
"$ref": "#/components/schemas/AuthenticationConfiguration"
},
{
"type": "null"
}
],
"$ref": "#/components/schemas/AuthenticationConfiguration",
"default": {
"module": "noop",
"skip_tls_verification": false
Expand Down Expand Up @@ -1140,41 +1142,25 @@
"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": {
"additionalProperties": {
"type": "string"
},
"type": "object",
"title": "Detail"
"title": "Detail",
"description": "Error details",
"examples": [
{
"cause": "Failed to handle request to https://bam-api.res.ibm.com/v2/text",
"response": "Error while validation question"
},
{
"cause": "Invalid conversation ID 1237-e89b-12d3-a456-426614174000",
"response": "Error retrieving conversation history"
}
]
}
},
"type": "object",
Expand Down Expand Up @@ -1413,11 +1399,21 @@
"properties": {
"name": {
"type": "string",
"title": "Name"
"title": "Name",
"description": "Service name",
"examples": [
"Lightspeed Stack"
]
},
"version": {
"type": "string",
"title": "Version"
"title": "Version",
"description": "Service version",
"examples": [
"0.1.0",
"0.2.0",
"1.0.0"
]
}
},
"type": "object",
Expand Down Expand Up @@ -1576,7 +1572,28 @@
"type": "object"
},
"type": "array",
"title": "Models"
"title": "Models",
"description": "List of models available",
"examples": [
{
"api_model_type": "llm",
"identifier": "openai/gpt-4-turbo",
"metadata": {},
"model_type": "llm",
"provider_id": "openai",
"provider_resource_id": "gpt-4-turbo",
"type": "model"
},
{
"api_model_type": "llm",
"identifier": "openai/gpt-3.5-turbo-0125",
"metadata": {},
"model_type": "llm",
"provider_id": "openai",
"provider_resource_id": "gpt-3.5-turbo-0125",
"type": "model"
}
]
}
},
"type": "object",
Expand Down Expand Up @@ -1867,11 +1884,19 @@
"type": "null"
}
],
"title": "Conversation Id"
"title": "Conversation Id",
"description": "The optional conversation ID (UUID)",
"examples": [
"c5260aec-4d82-4370-9fdf-05cf908b3f16"
]
},
"response": {
"type": "string",
"title": "Response"
"title": "Response",
"description": "Response from LLM",
"examples": [
"Kubernetes is an open-source container orchestration system for automating ..."
]
}
},
"type": "object",
Expand Down
46 changes: 34 additions & 12 deletions docs/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,8 +171,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 +208,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 +245,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 @@ -391,8 +416,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 @@ -556,8 +581,6 @@ Service customization.
| system_prompt | | |




## DatabaseConfiguration


Expand All @@ -578,7 +601,7 @@ Model representing error response for query endpoint.

| Field | Type | Description |
|-------|------|-------------|
| detail | object | |
| detail | object | Error details |


## FeedbackCategory
Expand Down Expand Up @@ -710,8 +733,8 @@ Example:

| Field | Type | Description |
|-------|------|-------------|
| name | string | |
| version | string | |
| name | string | Service name |
| version | string | Service version |


## JwkConfiguration
Expand Down Expand Up @@ -792,7 +815,7 @@ Model representing a response to models request.

| Field | Type | Description |
|-------|------|-------------|
| models | array | |
| models | array | List of models available |


## PostgreSQLDatabaseConfiguration
Expand Down Expand Up @@ -876,8 +899,8 @@ Attributes:

| Field | Type | Description |
|-------|------|-------------|
| conversation_id | | |
| response | string | |
| conversation_id | | The optional conversation ID (UUID) |
| response | string | Response from LLM |


## ReadinessResponse
Expand Down Expand Up @@ -1012,4 +1035,3 @@ User data collection configuration.
| loc | array | |
| msg | string | |
| type | string | |

Loading