Thanks to visit codestin.com
Credit goes to github.com

Skip to content

LCORE-1348: field description for models#1493

Merged
tisnik merged 3 commits into
lightspeed-core:mainfrom
tisnik:lcore-1348-field-description-for-models
Apr 13, 2026
Merged

LCORE-1348: field description for models#1493
tisnik merged 3 commits into
lightspeed-core:mainfrom
tisnik:lcore-1348-field-description-for-models

Conversation

@tisnik

@tisnik tisnik commented Apr 13, 2026

Copy link
Copy Markdown
Contributor

Description

LCORE-1348: field description for models

Type of change

  • Refactor
  • New feature
  • Bug fix
  • CVE fix
  • Optimization
  • Documentation Update
  • Configuration Update
  • Bump-up service version
  • Bump-up dependent library
  • Bump-up library or tool used for development (does not change the final image)
  • CI configuration change
  • Konflux configuration change
  • Unit tests improvement
  • Integration tests improvement
  • End to end tests improvement
  • Benchmarks improvement

Tools used to create PR

  • Assisted-by: N/A
  • Generated by: N/A

Related Tickets & Documents

  • Related Issue #LCORE-1348

Summary by CodeRabbit

  • Documentation
    • Added clear descriptions for error response fields (HTTP status code and error detail) across API docs.
    • Clarified parameter descriptions for several API endpoints to improve request/response readability.
    • Enhanced OpenAPI docs and reference tables for more consistent, user-friendly error and parameter information.

@coderabbitai

coderabbitai Bot commented Apr 13, 2026

Copy link
Copy Markdown
Contributor

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: e3a547ca-51ed-4797-8552-77f4f84892a0

📥 Commits

Reviewing files that changed from the base of the PR and between 906c4b1 and ef5e47c.

📒 Files selected for processing (2)
  • src/app/main.py
  • tests/unit/models/responses/test_error_responses.py
📜 Recent review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (12)
  • GitHub Check: list_outdated_dependencies
  • GitHub Check: integration_tests (3.13)
  • GitHub Check: integration_tests (3.12)
  • GitHub Check: mypy
  • GitHub Check: unit_tests (3.12)
  • GitHub Check: Pylinter
  • GitHub Check: unit_tests (3.13)
  • GitHub Check: build-pr
  • GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request
  • GitHub Check: E2E Tests for Lightspeed Evaluation job
  • GitHub Check: E2E: server mode / ci
  • GitHub Check: E2E: library mode / ci
🧰 Additional context used
📓 Path-based instructions (4)
src/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

src/**/*.py: Use absolute imports for internal modules (e.g., from authentication import get_auth_dependency)
Use from llama_stack_client import AsyncLlamaStackClient for Llama Stack imports
Check constants.py for shared constants before defining new ones
All modules start with descriptive docstrings explaining purpose
Use logger = get_logger(__name__) from log.py for module logging
Type aliases defined at module level for clarity
All functions require docstrings with brief descriptions
Use complete type annotations for function parameters and return types
Use union types with modern syntax: str | int instead of Union[str, int]
Use Optional[Type] for optional types in type annotations
Use snake_case with descriptive, action-oriented names for functions (get_, validate_, check_)
Avoid in-place parameter modification anti-patterns: return new data structures instead of modifying parameters
Use async def for I/O operations and external API calls
Handle APIConnectionError from Llama Stack in error handling
Use logger.debug() for detailed diagnostic information
Use logger.info() for general information about program execution
Use logger.warning() for unexpected events or potential problems
Use logger.error() for serious problems that prevented function execution
All classes require descriptive docstrings explaining purpose
Use PascalCase for class names with descriptive names and standard suffixes: Configuration, Error/Exception, Resolver, Interface
Use complete type annotations for all class attributes; avoid using Any
Follow Google Python docstring conventions for all modules, classes, and functions
Include Parameters:, Returns:, Raises: sections in function docstrings as needed

Files:

  • src/app/main.py
src/app/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

src/app/**/*.py: Use from fastapi import APIRouter, HTTPException, Request, status, Depends for FastAPI dependencies
Use FastAPI HTTPException with appropriate status codes for API endpoint error handling

Files:

  • src/app/main.py
tests/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

tests/**/*.py: Use pytest for all unit and integration tests; do not use unittest
Use pytest.mark.asyncio marker for async unit tests

Files:

  • tests/unit/models/responses/test_error_responses.py
tests/unit/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

Use pytest-mock for AsyncMock objects in unit tests

Files:

  • tests/unit/models/responses/test_error_responses.py
🔇 Additional comments (2)
src/app/main.py (1)

213-216: Good micro-refactor with preserved response behavior.

Caching the serialized detail in a local variable improves readability without changing payload shape or error handling flow.

tests/unit/models/responses/test_error_responses.py (1)

1-1: No functional concerns in this lint-directive update.

This change is isolated to static-analysis suppression and does not alter test behavior.


Walkthrough

The pull request updates OpenAPI documentation text and Pydantic schema metadata: it adds and revises description strings for error response fields and endpoint parameter docs, and annotates AbstractErrorResponse fields with Pydantic Field(...) descriptions. One minor refactor caches a model_dump in middleware.

Changes

Cohort / File(s) Summary
OpenAPI docs
docs/openapi.json, docs/openapi.md
Added/updated description strings for error response component properties (status_code, detail) and adjusted endpoint parameter descriptions for /v1/tools (adds mcp_headers), /v1/mcp-servers/{name} (clarifies request), and /v1/streaming_query (wording change for mcp_headers).
Error response model
src/models/responses.py
AbstractErrorResponse fields status_code and detail changed from bare annotations to Field(..., description=...), preserving required status and types.
Middleware minor refactor
src/app/main.py
Cached error_response.detail.model_dump() into model_dump and used it in the JSON response; added a pylint disable comment. No behavior change.
Tests lint directive
tests/unit/models/responses/test_error_responses.py
Added no-member to the file-level pylint disable list (no test logic changes).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main change: adding field descriptions to model definitions across the codebase.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
✨ Simplify code
  • Create PR with simplified code

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

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.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/openapi.json`:
- Line 6439: Update the repeated description string "HTTP status code for the
errors response" in the OpenAPI schema description fields to "HTTP status code
for the error response" (or "for this error response") wherever it appears;
locate the description properties matching that exact text (e.g., the
"description" field shown in the diff) and replace the value consistently across
all occurrences listed (lines around 6439, 6836, 7758, 8023, 8829, 10982, 11602,
13492, 13895, 13973) so the grammar is corrected uniformly.

In `@docs/openapi.md`:
- Around line 4464-4465: Update the Pydantic Field descriptions in
src/models/responses.py for the error response models: change the description
for the status_code field from "HTTP status code for the errors response" to
"HTTP status code for the error response" and change the description for the
detail field from "The detail model containing error summary and cause" to "The
error detail model containing an error summary and cause"; apply these edits to
each error response model where the status_code and detail Field(...)
descriptions appear (fields named status_code and detail).
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 41cf2620-5594-4b90-ad09-97daa16252c2

📥 Commits

Reviewing files that changed from the base of the PR and between 54c2df0 and 906c4b1.

📒 Files selected for processing (3)
  • docs/openapi.json
  • docs/openapi.md
  • src/models/responses.py
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)
  • GitHub Check: build-pr
  • GitHub Check: E2E: server mode / ci
  • GitHub Check: E2E Tests for Lightspeed Evaluation job
  • GitHub Check: E2E: library mode / ci
  • GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request
🧰 Additional context used
📓 Path-based instructions (2)
src/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

src/**/*.py: Use absolute imports for internal modules (e.g., from authentication import get_auth_dependency)
Use from llama_stack_client import AsyncLlamaStackClient for Llama Stack imports
Check constants.py for shared constants before defining new ones
All modules start with descriptive docstrings explaining purpose
Use logger = get_logger(__name__) from log.py for module logging
Type aliases defined at module level for clarity
All functions require docstrings with brief descriptions
Use complete type annotations for function parameters and return types
Use union types with modern syntax: str | int instead of Union[str, int]
Use Optional[Type] for optional types in type annotations
Use snake_case with descriptive, action-oriented names for functions (get_, validate_, check_)
Avoid in-place parameter modification anti-patterns: return new data structures instead of modifying parameters
Use async def for I/O operations and external API calls
Handle APIConnectionError from Llama Stack in error handling
Use logger.debug() for detailed diagnostic information
Use logger.info() for general information about program execution
Use logger.warning() for unexpected events or potential problems
Use logger.error() for serious problems that prevented function execution
All classes require descriptive docstrings explaining purpose
Use PascalCase for class names with descriptive names and standard suffixes: Configuration, Error/Exception, Resolver, Interface
Use complete type annotations for all class attributes; avoid using Any
Follow Google Python docstring conventions for all modules, classes, and functions
Include Parameters:, Returns:, Raises: sections in function docstrings as needed

Files:

  • src/models/responses.py
src/models/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

src/models/**/*.py: Use @field_validator and @model_validator for custom validation in Pydantic models
Use typing_extensions.Self for model validators in type annotations
Pydantic data models should extend BaseModel
Include Attributes: section in Pydantic model docstrings

Files:

  • src/models/responses.py
🧠 Learnings (3)
📚 Learning: 2026-01-12T10:58:40.230Z
Learnt from: blublinsky
Repo: lightspeed-core/lightspeed-stack PR: 972
File: src/models/config.py:459-513
Timestamp: 2026-01-12T10:58:40.230Z
Learning: In lightspeed-core/lightspeed-stack, for Python files under src/models, when a user claims a fix is done but the issue persists, verify the current code state before accepting the fix. Steps: review the diff, fetch the latest changes, run relevant tests, reproduce the issue, search the codebase for lingering references to the original problem, confirm the fix is applied and not undone by subsequent commits, and validate with local checks to ensure the issue is resolved.

Applied to files:

  • src/models/responses.py
📚 Learning: 2026-02-25T07:46:33.545Z
Learnt from: asimurka
Repo: lightspeed-core/lightspeed-stack PR: 1211
File: src/models/responses.py:8-16
Timestamp: 2026-02-25T07:46:33.545Z
Learning: In the Python codebase, requests.py should use OpenAIResponseInputTool as Tool while responses.py uses OpenAIResponseTool as Tool. This difference is intentional due to differing schemas for input vs output tools in llama-stack-api. Apply this distinction consistently to other models under src/models (e.g., ensure request-related tools use the InputTool variant and response-related tools use the ResponseTool variant). If adding new tools, choose the corresponding InputTool or Tool class based on whether the tool represents input or output, and document the rationale in code comments.

Applied to files:

  • src/models/responses.py
📚 Learning: 2026-04-06T20:18:11.336Z
Learnt from: major
Repo: lightspeed-core/lightspeed-stack PR: 1463
File: src/app/endpoints/rlsapi_v1.py:266-271
Timestamp: 2026-04-06T20:18:11.336Z
Learning: In the lightspeed-stack codebase (src/app/endpoints/), `tools: Optional[list[Any]]` for MCP tool definitions is an intentional, consistent pattern used across all inference endpoints (query, responses, streaming_query, rlsapi_v1). Do not flag this as a typing issue — changing it in isolation would break consistency.

Applied to files:

  • docs/openapi.json
🔇 Additional comments (2)
src/models/responses.py (1)

1716-1721: Good OpenAPI metadata update.

This keeps both fields required while improving schema documentation for clients.

docs/openapi.json (1)

421-421: Good documentation updates for endpoint parameter clarity.

These description changes are clear and consistent with the endpoint behavior, especially the explicit mcp_headers mention and middleware-related parameter wording.

Also applies to: 934-934, 2146-2146

Comment thread docs/openapi.json
"type": "integer",
"title": "Status Code"
"title": "Status Code",
"description": "HTTP status code for the errors response"

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

Fix repeated grammar issue in error schema field descriptions.

"HTTP status code for the errors response" should be "HTTP status code for the error response" (or "for this error response"). The current string is repeated across multiple schemas.

Also applies to: 6836-6836, 7758-7758, 8023-8023, 8829-8829, 10982-10982, 11602-11602, 13492-13492, 13895-13895, 13973-13973

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/openapi.json` at line 6439, Update the repeated description string "HTTP
status code for the errors response" in the OpenAPI schema description fields to
"HTTP status code for the error response" (or "for this error response")
wherever it appears; locate the description properties matching that exact text
(e.g., the "description" field shown in the diff) and replace the value
consistently across all occurrences listed (lines around 6439, 6836, 7758, 8023,
8829, 10982, 11602, 13492, 13895, 13973) so the grammar is corrected uniformly.

Comment thread docs/openapi.md
Comment on lines +4464 to +4465
| status_code | integer | HTTP status code for the errors response |
| detail | | The detail model containing error summary and cause |

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.

🧹 Nitpick | 🔵 Trivial

Minor grammar improvements for error field descriptions.

The added field descriptions contain minor grammatical issues:

  1. Line 4464 (and similar lines): "HTTP status code for the errors response" should be "HTTP status code for the error response" (singular).
  2. Line 4465 (and similar lines): "The detail model containing error summary and cause" could be clearer as "The error detail model containing an error summary and cause."

Since this is auto-generated documentation from src/models/responses.py (per the AI summary), these improvements should be made in the source Pydantic Field descriptions in that file.

Also applies to: 4571-4572, 4958-4959, 5070-5071, 5397-5398, 6228-6229, 6357-6358, 6994-6995, 7173-7174, 7185-7186

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/openapi.md` around lines 4464 - 4465, Update the Pydantic Field
descriptions in src/models/responses.py for the error response models: change
the description for the status_code field from "HTTP status code for the errors
response" to "HTTP status code for the error response" and change the
description for the detail field from "The detail model containing error summary
and cause" to "The error detail model containing an error summary and cause";
apply these edits to each error response model where the status_code and detail
Field(...) descriptions appear (fields named status_code and detail).

@tisnik tisnik merged commit d37148d into lightspeed-core:main Apr 13, 2026
25 of 26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant