Skip to content

LCORE-2572: Updated description for /providers, /shields and /rags endpoints. #1927

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 4 commits into from
Jun 15, 2026
Merged

LCORE-2572: Updated description for /providers, /shields and /rags endpoints. #1927

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
811dca6
Updated description for /providers endpoint
tisnik Jun 15, 2026
5bb465b
Updated description for /rags endpoint
tisnik Jun 15, 2026
e11e56c
Updated description for /shields endpoint
tisnik Jun 15, 2026
15939db
Generaded OpenAPI specification
tisnik Jun 15, 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
6 changes: 3 additions & 3 deletions docs/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1500,7 +1500,7 @@
"shields"
],
"summary": "Shields Endpoint Handler",
"description": "Handle requests to the /shields endpoint.\n\nProcess GET requests to the /shields endpoint, returning a list of available\nshields from the Llama Stack service.\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### Returns:\n- ShieldsResponse: An object containing the list of available shields.\n\n### Raises:\n- HTTPException: If unable to connect to the Llama Stack server or if\n shield retrieval fails for any reason.",
"description": "Handle requests to the /shields endpoint.\n\nProcess GET requests to the /shields endpoint, returning a list of available\nshields from the Llama Stack service.\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- ShieldsResponse: An object containing the list of available shields.",

@coderabbitai coderabbitai Bot Jun 15, 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 | 🟠 Major | ⚡ Quick win

Regenerate and commit docs/openapi.json from source routes/docstrings before merge.

docs/openapi.json is currently out of sync with generated output, and CI already fails on this exact diff check. Please regenerate with uv run python scripts/generate_openapi_schema.py docs/openapi.json and commit the updated artifact so the OpenAPI contract stays consistent across layers. Based on pipeline failures and the generation script contract, this is a deterministic mismatch, not a speculative warning.

🤖 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` at line 1503, The docs/openapi.json file is out of sync
with the generated OpenAPI schema from the source routes and docstrings, causing
CI checks to fail. Regenerate the file by running the command: uv run python
scripts/generate_openapi_schema.py docs/openapi.json, which will update
docs/openapi.json to match the current source definitions. After regeneration,
commit the updated docs/openapi.json artifact to ensure the OpenAPI contract
stays consistent across all layers and passes CI validation.

Source: Pipeline failures

"operationId": "shields_endpoint_handler_v1_shields_get",
"responses": {
"200": {
Expand Down Expand Up @@ -1677,7 +1677,7 @@
"providers"
],
"summary": "Providers Endpoint Handler",
"description": "List all available providers grouped by API type.\n\n### Parameters:\n- request: The incoming HTTP request.\n- auth: Authentication tuple from the auth dependency.\n\n### Returns:\n- ProvidersListResponse: Mapping from API type to list of providers.\n\n### Raises:\n- HTTPException:\n- 401: Authentication failed\n- 403: Authorization failed\n- 500: Lightspeed Stack configuration not loaded\n- 503: Unable to connect to Llama Stack",
"description": "List all available providers grouped by API type.\n\n### Parameters:\n- request: The incoming HTTP request.\n- auth: Authentication tuple from the auth dependency.\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- ProvidersListResponse: Mapping from API type to list of providers.",
"operationId": "providers_endpoint_handler_v1_providers_get",
"responses": {
"200": {
Expand Down Expand Up @@ -3211,7 +3211,7 @@
"rags"
],
"summary": "Rags Endpoint Handler",
"description": "List all available RAGs.\n\nReturns:\n RAGListResponse: List of RAG identifiers.\n\nRaises:\n HTTPException:\n - 401: Authentication failed\n - 403: Authorization failed\n - 500: Lightspeed Stack configuration not loaded\n - 503: Unable to connect to Llama Stack",
"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
56 changes: 33 additions & 23 deletions docs/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Lightspeed Core Service (LCS) service - OpenAPI
# Lightspeed Core Stack (LCS) service - OpenAPI

Lightspeed Core Service (LCS) service API specification.
Lightspeed Core Stack (LCS) service API specification.


<!-- vim-markdown-toc GFM -->

* [🛠️ APIs](#-apis)
* [🛠️ APIs](#apis)

@coderabbitai coderabbitai Bot Jun 15, 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

Fix the top-level TOC link.

#apis likely does not match the slug for the 🛠️ APIs heading, so this navigation link will not resolve correctly.

🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 8-8: Link fragments should be valid

(MD051, link-fragments)

🤖 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` at line 8, The table of contents link on line 8 references
the anchor `#apis`, but the heading `🛠️ APIs` will likely generate a different
slug because the emoji is included in the heading text. Update the TOC link to
match the actual slug that will be generated from the `🛠️ APIs` heading, or
verify and use the correct anchor reference that corresponds to how the markdown
processor handles the emoji in the heading slug.

* [List of REST API endpoints](#list-of-rest-api-endpoints)
* [GET `/`](#get-)
* [Parameters:](#parameters)
Expand Down Expand Up @@ -192,7 +192,6 @@ Lightspeed Core Service (LCS) service API specification.
* [✅ Responses](#-responses-42)
* [GET `/a2a/health`](#get-a2ahealth)
* [✅ Responses](#-responses-43)
* [| 200 | Successful Response | object |](#-200--successful-response--object-)
* [📋 Components](#-components)
* [A2AStateConfiguration](#a2astateconfiguration)
* [APIKeySecurityScheme](#apikeysecurityscheme)
Expand Down Expand Up @@ -398,7 +397,7 @@ Lightspeed Core Service (LCS) service API specification.

| URL | Description |
|-----|-------------|
| http://localhost:8080/ | Locally running service |
| http://localhost:8080 | Locally running service |


# 🛠️ APIs
Expand Down Expand Up @@ -1248,13 +1247,17 @@ shields from the Llama Stack service.
- request: The incoming HTTP request (used by middleware).
- auth: Authentication tuple from the auth dependency (used by middleware).

### Raises:
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- 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 +1250 to +1256

@coderabbitai coderabbitai Bot Jun 15, 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

Normalize the markdown structure in the updated endpoint sections.

These blocks are missing the blank-line spacing Markdownlint expects, and the GET /v1/rags Returns item is indented like a code block. That will keep the docs lint-failing and can render the sections incorrectly.

  • docs/openapi.md#L1250-L1256: add blank lines around ### Raises / ### Returns.
  • docs/openapi.md#L1349-L1356: add blank lines around ### Raises / ### Returns.
  • docs/openapi.md#L2182-L2195: add the missing blank lines and outdent the Returns bullet.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

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

(MD022, blanks-around-headings)

📍 Affects 1 file
  • docs/openapi.md#L1250-L1256 (this comment)
  • docs/openapi.md#L1349-L1356
  • docs/openapi.md#L2182-L2195
🤖 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 1250 - 1256, The markdown structure in the
docs/openapi.md file has formatting issues that violate Markdownlint rules. At
docs/openapi.md lines 1250-1256, add blank lines before and after the ### Raises
section to properly separate it from surrounding content. At docs/openapi.md
lines 1349-1356, similarly add blank lines before and after the ### Raises
section for proper markdown spacing. At docs/openapi.md lines 2182-2195, add the
missing blank lines around the ### Returns and ### Raises sections, and outdent
the Returns bullet point items that are currently indented as if they were code
blocks—ensure they align with standard bullet point indentation. These changes
will resolve the Markdownlint failures and ensure correct rendering of the
documentation sections.


### Returns:
- ShieldsResponse: An object containing the list of available shields.

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




Expand Down Expand Up @@ -1343,15 +1346,17 @@ List all available providers grouped by API type.
- request: The incoming HTTP request.
- auth: Authentication tuple from the auth dependency.

### Raises:
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- 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:
- ProvidersListResponse: Mapping from API type to list of providers.

### Raises:
- HTTPException:
- 401: Authentication failed
- 403: Authorization failed
- 500: Lightspeed Stack configuration not loaded
- 503: Unable to connect to Llama Stack



Expand Down Expand Up @@ -2174,15 +2179,20 @@ Examples

List all available RAGs.

Returns:
RAGListResponse: List of RAG identifiers.
### Parameters:
- request: The incoming HTTP request (used by middleware).
- auth: Authentication tuple from the auth dependency (used by middleware).

Raises:
HTTPException:
- 401: Authentication failed
- 403: Authorization failed
- 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 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:
- RAGListResponse: List of RAG identifiers.



Expand Down
15 changes: 8 additions & 7 deletions src/app/endpoints/providers.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,15 +67,16 @@ async def providers_endpoint_handler(
- request: The incoming HTTP request.
- auth: Authentication tuple from the auth dependency.

### Raises:
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- 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:
- ProvidersListResponse: Mapping from API type to list of providers.

### Raises:
- HTTPException:
- 401: Authentication failed
- 403: Authorization failed
- 500: Lightspeed Stack configuration not loaded
- 503: Unable to connect to Llama Stack
"""
# Used only by the middleware
_ = auth
Expand Down
23 changes: 14 additions & 9 deletions src/app/endpoints/rags.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,15 +62,20 @@ async def rags_endpoint_handler(
"""
List all available RAGs.

Returns:
RAGListResponse: List of RAG identifiers.

Raises:
HTTPException:
- 401: Authentication failed
- 403: Authorization failed
- 500: Lightspeed Stack configuration not loaded
- 503: Unable to connect to Llama Stack
### Parameters:
- request: The incoming HTTP request (used by middleware).
- auth: Authentication tuple from the auth dependency (used by middleware).

### Raises:
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- 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:
- RAGListResponse: List of RAG identifiers.
Comment on lines +77 to +78

@coderabbitai coderabbitai Bot Jun 15, 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

Fix indentation inconsistency in the Returns section.

The Returns section has extra indentation that breaks consistency with shields.py and providers.py. The list item should use 4 spaces of indentation (one level), not 8 spaces (two levels).

    ### Returns:
-        - RAGListResponse: List of RAG identifiers.
+    - RAGListResponse: List of RAG identifiers.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
### Returns:
- RAGListResponse: List of RAG identifiers.
### Returns:
- RAGListResponse: List of RAG identifiers.
🤖 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/rags.py` around lines 77 - 78, Fix the indentation
inconsistency in the Returns section of the docstring around lines 77-78. The
list item "- RAGListResponse: List of RAG identifiers." currently has 8 spaces
of indentation but should have only 4 spaces to match the consistent style used
in shields.py and providers.py. Reduce the indentation by removing 4 spaces from
the beginning of the list item line.

"""
# Used only by the middleware
_ = auth
Expand Down
12 changes: 8 additions & 4 deletions src/app/endpoints/shields.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,12 +54,16 @@ async def shields_endpoint_handler(
- request: The incoming HTTP request (used by middleware).
- auth: Authentication tuple from the auth dependency (used by middleware).

### Raises:
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- 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:
- ShieldsResponse: An object containing the list of available shields.

### Raises:
- HTTPException: If unable to connect to the Llama Stack server or if
shield retrieval fails for any reason.
"""
# Used only by the middleware
_ = auth
Expand Down
Loading