Skip to content

LCORE-2572: Minor fixes #1944

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 3 commits into from
Jun 18, 2026
Merged

LCORE-2572: Minor fixes #1944

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2110351
Updated info about HTTP exceptions
tisnik Jun 18, 2026
be78264
Proper docstring for RAGs handlers
tisnik Jun 18, 2026
00e8eef
Updated OpenAPI documentation
tisnik Jun 18, 2026
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
8 changes: 4 additions & 4 deletions docs/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2728,7 +2728,7 @@
"prompts"
],
"summary": "Update Prompt Handler",
"description": "Handle requests to the PUT /prompts/{prompt_id} endpoint.\n\nProcess requests to update a stored prompt; Llama Stack increments the\nversion. The body includes the new text, the current version being\nreplaced, and optional fields such as ``set_as_default`` and ``variables``.\nFor example:\n\n curl -X PUT http://localhost:8080/v1/prompts/pmpt_abc123 \\\\\n -H 'Content-Type: application/json' \\\\\n -d '{\"prompt\": \"Hi\", \"version\": 1, \"set_as_default\": true}'\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- prompt_id: The Llama Stack prompt identifier.\n- auth: Authentication tuple from the auth dependency (used by middleware).\n- body: Prompt update parameters.\n\n### Raises:\n- HTTPException: If configuration is not loaded, if the prompt is not\n found, if unable to connect to Llama Stack, or if the prompts API returns\n an error response.\n\n### Returns:\n- PromptResourceResponse: The updated prompt object returned by Llama Stack.",
"description": "Handle requests to the PUT /prompts/{prompt_id} endpoint.\n\nProcess requests to update a stored prompt; Llama Stack increments the\nversion. The body includes the new text, the current version being\nreplaced, and optional fields such as ``set_as_default`` and ``variables``.\nFor example:\n\n curl -X PUT http://localhost:8080/v1/prompts/pmpt_abc123 \\\\\n -H 'Content-Type: application/json' \\\\\n -d '{\"prompt\": \"Hi\", \"version\": 1, \"set_as_default\": true}'\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- prompt_id: The Llama Stack prompt identifier.\n- auth: Authentication tuple from the auth dependency (used by middleware).\n- body: Prompt update parameters.\n\n### Raises:\n- HTTPException: with status 400 when request format is not valid.\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 404 if prompt is not found.\n- HTTPException: with status 422 if request payload is corrupted.\n- HTTPException: with status 500 and a detail object containing `response`\n and `cause` when service configuration is wrong or incomplete.\n- HTTPException: with status 503 and a detail object containing `response`\n and `cause` when unable to connect to Llama Stack.\n\n### Returns:\n- PromptResourceResponse: The updated prompt object returned by Llama Stack.",
"operationId": "update_prompt_handler_v1_prompts__prompt_id__put",
Comment on lines 2728 to 2732

@coderabbitai coderabbitai Bot Jun 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

OpenAPI schema is out of date and fails CI validation.

The pipeline has flagged that docs/openapi.json does not match the schema generated by the build process. The diff command shows a mismatch against /tmp/openapi-generated.json. OpenAPI JSON files should be auto-generated from source docstrings rather than manually edited.

You must regenerate the OpenAPI schema using the provided script before this PR can merge.

Regenerate the OpenAPI schema:

uv run scripts/generate_openapi_schema.py docs/openapi.json

Ensure the Python docstrings in src/app/endpoints/prompts.py and src/app/endpoints/rags.py match the description updates shown in these hunks, then commit the regenerated docs/openapi.json.

Also applies to: 2980-2984, 3211-3214, 3384-3387

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/openapi.json` around lines 2728 - 2732, The docs/openapi.json file is
out of date and must be regenerated from source code rather than manually
edited. First, verify that the Python docstrings in src/app/endpoints/prompts.py
and src/app/endpoints/rags.py contain the description updates matching the hunks
shown (specifically for the update_prompt_handler and any related RAG
endpoints). Then run the provided script to regenerate the OpenAPI schema, which
will update docs/openapi.json to match the current docstrings. Finally, commit
the regenerated openapi.json file.

Source: Pipeline failures

"parameters": [
{
Expand Down Expand Up @@ -2980,7 +2980,7 @@
"prompts"
],
"summary": "Delete Prompt Handler",
"description": "Handle requests to the DELETE /prompts/{prompt_id} endpoint.\n\nProcess requests to delete a stored prompt in Llama Stack. The response\nalways uses HTTP 200 with a JSON body indicating whether the deletion\nsucceeded (same pattern as deleting a conversation in ``/v2``). For example:\n\n curl -X DELETE http://localhost:8080/v1/prompts/pmpt_abc123\n\nWhen the prompt does not exist, the response still returns 200 with\n``deleted`` set to false in the body.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- prompt_id: The Llama Stack prompt identifier.\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Raises:\n- HTTPException: If configuration is not loaded, if unable to connect to\n Llama Stack, or if the prompts API returns an error response.\n\n### Returns:\n- PromptDeleteResponse: An object describing whether the prompt was\n deleted and a human-readable message.",
"description": "Handle requests to the DELETE /prompts/{prompt_id} endpoint.\n\nProcess requests to delete a stored prompt in Llama Stack. The response\nalways uses HTTP 200 with a JSON body indicating whether the deletion\nsucceeded (same pattern as deleting a conversation in ``/v2``). For example:\n\n curl -X DELETE http://localhost:8080/v1/prompts/pmpt_abc123\n\nWhen the prompt does not exist, the response still returns 200 with\n``deleted`` set to false in the body.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- prompt_id: The Llama Stack prompt identifier.\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 422 if request payload is corrupted.\n- HTTPException: with status 500 and a detail object containing `response`\n and `cause` when service configuration is wrong or incomplete.\n- HTTPException: with status 503 and a detail object containing `response`\n and `cause` when unable to connect to Llama Stack.\n\n### Returns:\n- PromptDeleteResponse: An object describing whether the prompt was\n deleted and a human-readable message.",
"operationId": "delete_prompt_handler_v1_prompts__prompt_id__delete",
"parameters": [
{
Expand Down Expand Up @@ -3211,7 +3211,7 @@
"rags"
],
"summary": "Rags Endpoint Handler",
"description": "List all available RAGs.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 500 and a detail object containing `response`\n and `cause` when service configuration is wrong or incomplete.\n- HTTPException: with status 503 and a detail object containing `response`\n and `cause` when unable to connect to Llama Stack.\n\n### Returns:\n - RAGListResponse: List of RAG identifiers.",
"description": "List all available RAGs.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 500 and a detail object containing `response`\n and `cause` when service configuration is wrong or incomplete.\n- HTTPException: with status 503 and a detail object containing `response`\n and `cause` when unable to connect to Llama Stack.\n\n### Returns:\n- RAGListResponse: List of RAG identifiers.",
"operationId": "rags_endpoint_handler_v1_rags_get",
"responses": {
"200": {
Expand Down Expand Up @@ -3384,7 +3384,7 @@
"rags"
],
"summary": "Get Rag Endpoint Handler",
"description": "Retrieve a single RAG identified by its unique ID.\n\nAccepts both user-facing rag_id (from LCORE config) and llama-stack\nvector_store_id. If a rag_id from config is provided, it is resolved\nto the underlying vector_store_id for the llama-stack lookup.\n\nReturns:\n RAGInfoResponse: A single RAG's details.\n\nRaises:\n HTTPException:\n - 401: Authentication failed\n - 403: Authorization failed\n - 404: RAG with the given ID not found\n - 500: Lightspeed Stack configuration not loaded\n - 503: Unable to connect to Llama Stack",
"description": "Retrieve a single RAG identified by its unique ID.\n\nAccepts both user-facing rag_id (from LCORE config) and llama-stack\nvector_store_id. If a rag_id from config is provided, it is resolved\nto the underlying vector_store_id for the llama-stack lookup.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- rag_id: rag_id or llama-stack vector_store_id\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 404 if rag_id is not found.\n- HTTPException: with status 422 for incorrect request payload.\n- HTTPException: with status 500 and a detail object containing `response`\n and `cause` when service configuration is wrong or incomplete.\n- HTTPException: with status 503 and a detail object containing `response`\n and `cause` when unable to connect to Llama Stack.\n\n### Returns:\n- RAGInfoResponse: A single RAG's details.",
"operationId": "get_rag_endpoint_handler_v1_rags__rag_id__get",
"parameters": [
{
Expand Down
147 changes: 71 additions & 76 deletions docs/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2616,16 +2616,23 @@ Accepts both user-facing rag_id (from LCORE config) and llama-stack
vector_store_id. If a rag_id from config is provided, it is resolved
to the underlying vector_store_id for the llama-stack lookup.

Returns:
RAGInfoResponse: A single RAG's details.
### Parameters:
- request: The incoming HTTP request (used by middleware).
- rag_id: rag_id or llama-stack vector_store_id
- auth: Authentication tuple from the auth dependency (used by middleware).

Raises:
HTTPException:
- 401: Authentication failed
- 403: Authorization failed
- 404: RAG with the given ID not found
- 500: Lightspeed Stack configuration not loaded
- 503: Unable to connect to Llama Stack
### Raises:
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- HTTPException: with status 404 if rag_id is not found.
- HTTPException: with status 422 for incorrect request payload.
- HTTPException: with status 500 and a detail object containing `response`
and `cause` when service configuration is wrong or incomplete.
- HTTPException: with status 503 and a detail object containing `response`
and `cause` when unable to connect to Llama Stack.

### Returns:
- RAGInfoResponse: A single RAG's details.



Expand Down Expand Up @@ -5461,8 +5468,17 @@ Serve the A2A Agent Card at the well-known location.
This endpoint provides the agent card that describes Lightspeed's
capabilities according to the A2A protocol specification.

Returns:
AgentCard: The agent card describing this agent's capabilities.
### Parameters:
- auth: Authentication tuple from the auth dependency (used by middleware).

### Raises:
- HTTPException: with status 500 and a detail object containing `response`
and `cause` when service configuration is wrong or incomplete.
- HTTPException: with status 503 and a detail object containing `response`
and `cause` when unable to connect to Llama Stack.

### Returns:
- AgentCard: The agent card describing this agent's capabilities.
Comment on lines +5471 to +5481

@coderabbitai coderabbitai Bot Jun 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add blank lines around these headings.

These blocks hit the markdownlint MD022 warning, and the current layout can render inconsistently in Markdown viewers.

🛠️ Suggested fix 
-This endpoint provides the agent card that describes Lightspeed's
-capabilities according to the A2A protocol specification.
-### Parameters:
+This endpoint provides the agent card that describes Lightspeed's
+capabilities according to the A2A protocol specification.
+
+### Parameters:
+
 - auth: Authentication tuple from the auth dependency (used by middleware).

Also applies to: 5502-5512, 5596-5603

🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 5471-5471: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

[warning] 5474-5474: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

[warning] 5480-5480: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/openapi.md` around lines 5471 - 5481, The markdown headings (###
Parameters:, ### Raises:, ### Returns:) are missing blank lines before and after
them, which violates the markdownlint MD022 rule and causes rendering
inconsistencies. Add a blank line before each of these headings and after the
final line of each section to properly space them. This should be applied at the
three locations mentioned: around lines 5471-5481 for the first set of headings,
around lines 5502-5512 for the second set, and around lines 5596-5603 for the
third set.

Source: Linters/SAST tools




Expand All @@ -5483,8 +5499,17 @@ Serve the A2A Agent Card at the well-known location.
This endpoint provides the agent card that describes Lightspeed's
capabilities according to the A2A protocol specification.

Returns:
AgentCard: The agent card describing this agent's capabilities.
### Parameters:
- auth: Authentication tuple from the auth dependency (used by middleware).

### Raises:
- HTTPException: with status 500 and a detail object containing `response`
and `cause` when service configuration is wrong or incomplete.
- HTTPException: with status 503 and a detail object containing `response`
and `cause` when unable to connect to Llama Stack.

### Returns:
- AgentCard: The agent card describing this agent's capabilities.



Expand Down Expand Up @@ -5568,8 +5593,14 @@ Returns:

Health check endpoint for A2A service.

Returns:
Dict with health status information.
### Parameters:
- None

### Raises:
- None

### Returns:
- Dict with health status information.



Expand Down Expand Up @@ -5879,6 +5910,7 @@ Authentication configuration.
| jwk_config | | |
| api_key_config | | |
| rh_identity_config | | |
| trusted_proxy_config | | |


## AuthorizationCodeOAuthFlow
Expand Down Expand Up @@ -5974,6 +6006,11 @@ BYOK (Bring Your Own Knowledge) RAG configuration.
| vector_db_id | string | Vector database identification. |
| db_path | string | Path to RAG database. |
| score_multiplier | number | Multiplier applied to relevance scores from this vector store. Used to weight results when querying multiple knowledge sources. Values > 1 boost this store's results; values < 1 reduce them. |
| host | | PostgreSQL host for remote::pgvector. Defaults to ${env.POSTGRES_HOST} when rag_type is remote::pgvector. |
| port | | PostgreSQL port for remote::pgvector. Defaults to ${env.POSTGRES_PORT} when rag_type is remote::pgvector. |
| db | | PostgreSQL database name for remote::pgvector. Defaults to ${env.POSTGRES_DATABASE} when rag_type is remote::pgvector. |
| user | | PostgreSQL user for remote::pgvector. Defaults to ${env.POSTGRES_USER} when rag_type is remote::pgvector. |
| password | | PostgreSQL password for remote::pgvector. Defaults to ${env.POSTGRES_PASSWORD} when rag_type is remote::pgvector. |


## CORSConfiguration
Expand Down Expand Up @@ -6142,6 +6179,7 @@ Attributes:

| Field | Type | Description |
|-------|------|-------------|
| deleted | boolean | Whether the deletion was successful. |
| conversation_id | string | The conversation ID (UUID) that was deleted. |
| success | boolean | Whether the deletion was successful. |
| response | string | A message about the deletion result. |
Expand Down Expand Up @@ -6250,13 +6288,6 @@ 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 |
|-------|------|-------------|
Expand All @@ -6273,15 +6304,6 @@ Attributes:
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 |
|-------|------|-------------|
Expand Down Expand Up @@ -6397,18 +6419,6 @@ Attributes:
user_feedback: The optional user feedback.
categories: The optional list of feedback categories (multi-select for negative feedback).

Example:
```python
feedback_request = FeedbackRequest(
conversation_id="12345678-abcd-0000-0123-456789abcdef",
user_question="what are you doing?",
user_feedback="This response is not helpful",
llm_response="I don't know",
sentiment=-1,
categories=[FeedbackCategory.INCORRECT, FeedbackCategory.INCOMPLETE]
)
```


| Field | Type | Description |
|-------|------|-------------|
Expand All @@ -6428,11 +6438,6 @@ Model representing a response to a feedback request.
Attributes:
response: The response of the feedback request.

Example:
```python
feedback_response = FeedbackResponse(response="feedback received")
```


| Field | Type | Description |
|-------|------|-------------|
Expand All @@ -6447,13 +6452,6 @@ Model representing a feedback status update request.
Attributes:
status: Value of the desired feedback enabled state.

Example:
```python
feedback_request = FeedbackRequest(
status=false
)
```


| Field | Type | Description |
|-------|------|-------------|
Expand All @@ -6468,18 +6466,6 @@ Model representing a response to a feedback status update request.
Attributes:
status: The previous and current status of the service and who updated it.

Example:
```python
status_response = StatusResponse(
status={
"previous_status": true,
"updated_status": false,
"updated_by": "user/test",
"timestamp": "2023-03-15 12:34:56"
},
)
```


| Field | Type | Description |
|-------|------|-------------|
Expand Down Expand Up @@ -6618,15 +6604,6 @@ Attributes:
service_version: Service version.
llama_stack_version: Llama Stack version.

Example:
```python
info_response = InfoResponse(
name="Lightspeed Stack",
service_version="1.0.0",
llama_stack_version="0.2.22",
)
```


| Field | Type | Description |
|-------|------|-------------|
Expand All @@ -6635,6 +6612,24 @@ Example:
| llama_stack_version | string | Llama Stack version |


## InputToolMCP


MCP input tool with authorization included when serializing request bodies.


| Field | Type | Description |
|-------|------|-------------|
| type | string | |
| server_label | string | |
| connector_id | | |
| server_url | | |
| headers | | |
| authorization | | |
| require_approval | | |
| allowed_tools | | |


## InternalServerErrorResponse


Expand Down
21 changes: 16 additions & 5 deletions src/app/endpoints/prompts.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -291,9 +291,15 @@ async def update_prompt_handler(
- body: Prompt update parameters.

### Raises:
- HTTPException: If configuration is not loaded, if the prompt is not
found, if unable to connect to Llama Stack, or if the prompts API returns
an error response.
- HTTPException: with status 400 when request format is not valid.
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- HTTPException: with status 404 if prompt is not found.
- HTTPException: with status 422 if request payload is corrupted.
- HTTPException: with status 500 and a detail object containing `response`
and `cause` when service configuration is wrong or incomplete.
- HTTPException: with status 503 and a detail object containing `response`
and `cause` when unable to connect to Llama Stack.

### Returns:
- PromptResourceResponse: The updated prompt object returned by Llama Stack.
Expand Down Expand Up @@ -352,8 +358,13 @@ async def delete_prompt_handler(
- auth: Authentication tuple from the auth dependency (used by middleware).

### Raises:
- HTTPException: If configuration is not loaded, if unable to connect to
Llama Stack, or if the prompts API returns an error response.
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- HTTPException: with status 422 if request payload is corrupted.
- HTTPException: with status 500 and a detail object containing `response`
and `cause` when service configuration is wrong or incomplete.
- HTTPException: with status 503 and a detail object containing `response`
and `cause` when unable to connect to Llama Stack.
Comment on lines 360 to +367

@coderabbitai coderabbitai Bot Jun 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Missing HTTP 400 status code in delete_prompt_handler docstring.

The Raises section omits status 400, but the implementation at line 378–381 raises HTTPException with BadRequestResponse (status 400) when check_suid_prompt(prompt_id) fails. Additionally, the response dict prompt_delete_responses (lines 85–94) explicitly includes a 400 response definition, and the decorator @router.delete(..., responses=prompt_delete_responses) at line 336 registers it with FastAPI.

The docstring should document all status codes that the endpoint can return, including 400 for invalid prompt ID format.

📋 Proposed docstring update 
     ### Raises:
+    - HTTPException: with status 400 when request format is not valid.
     - HTTPException: with status 401 for unauthorized access.
     - HTTPException: with status 403 if permission is denied.
     - HTTPException: with status 422 if request payload is corrupted.
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/app/endpoints/prompts.py` around lines 360 - 367, Add HTTPException with
status 400 to the Raises section in the docstring of the delete_prompt_handler
function to document that a 400 response is returned when
check_suid_prompt(prompt_id) fails, indicating an invalid prompt ID format. This
status code is already implemented in the function logic and registered in the
prompt_delete_responses dict, so the docstring must be updated to reflect all
possible HTTP responses the endpoint can return.


### Returns:
- PromptDeleteResponse: An object describing whether the prompt was
Expand Down
Loading
Loading