LCORE-3229: updated all models documentation - #2290
Conversation
WalkthroughAdds OpenAPI 3.0 model catalogs, Markdown documentation, and PlantUML diagrams for streaming, shared, request, error, and successful response contracts, including saved prompts, vector stores, unified inference, and optional response fields. ChangesStreaming and summary contracts
Shared model contracts
Request contracts
Error and successful response contracts
Estimated code review effort: 4 (Complex) | ~60 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 7✅ Passed checks (7 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify 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. Comment |
![coderabbitai[bot]](https://avatars.github.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 14
🤖 Prompt for all review comments with 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.
Inline comments:
In `@docs/models/agents.json`:
- Around line 12-18: Fix the generator step that serializes reference targets so
it emits plain JSON pointers without Markdown backticks for both $ref values and
discriminator.mapping targets. This root-cause change must correct
docs/models/agents.json lines 12-18 and docs/models/common.json lines 179-199;
regenerate the artifacts so all listed references and mappings become
resolvable, rather than patching the generated files individually.
- Around line 42-51: The event discriminator definitions in EndStreamPayload and
the corresponding SSE payload models use OpenAPI 3.0-incompatible const
keywords. Replace each listed event const with a single-value enum containing
the same literal, preserving the existing defaults and event values; do not
migrate the document to OpenAPI 3.1.
In `@docs/models/common.json`:
- Around line 12-40: Align common.json with the OpenAPI dialect selected by the
generator and used in agents.json. If the document remains OpenAPI 3.0, replace
schema-level examples arrays with singular example values, replace const with
the supported 3.0 equivalent, and remove or adapt nullable consistently;
otherwise declare and use OpenAPI 3.1 semantics throughout.
- Around line 383-389: Update the schema generation logic for optional list
annotations so nullable arrays retain their element `items` schema instead of
being emitted as bare arrays. Ensure fields such as
Message.referenced_documents, logprobs, results, bytes, and top_logprobs
reference their declared item types while preserving nullable and default-null
behavior.
In `@docs/models/common.puml`:
- Around line 17-23: Align the generated PlantUML field optionality with the
Pydantic schemas and common.json, preserving Optional only for genuinely
nullable fields. Update the generator or regenerate common.puml so required
fields in Attachment, ConversationDetails, ConversationTurn, Message, RAGChunk,
ToolCallSummary, ToolResultSummary, MCPServer variants, and ProviderHealthStatus
are no longer marked optional.
In `@docs/models/requests.json`:
- Line 315: Remove the literal backticks from all generated $ref values and
discriminator.mapping entries in docs/models/requests.json, preserving valid
JSON Pointer paths such as `#/components/schemas/ApprovalFilter`. Update the
generator or serialization logic producing these references so every affected
entry is emitted without Markdown escaping.
- Around line 315-330: Update the schema generator to remove literal Markdown
backticks from every generated $ref and discriminator.mapping value, producing
valid JSON Pointers. Regenerate docs/models/requests.json (including all listed
ranges), docs/models/error_responses.json (including all listed DetailModel
references), and docs/models/successful_responses.json (including all listed
references and mappings); no direct manual edits to the generated catalogs are
needed beyond regeneration.
In `@docs/models/requests.md`:
- Around line 5-14: The Markdown generator should omit the Base URL and 🛠️ APIs
sections when the source specification has no servers and an empty paths object,
rather than emitting empty sections. Apply this behavior to
docs/models/requests.md lines 5-14, docs/models/error_responses.md lines 5-14,
and docs/models/successful_responses.md lines 5-14; update the generator logic
so all three catalogs are regenerated without those blocks.
In `@docs/models/requests.puml`:
- Around line 138-141: Fix the diagram generator to infer requiredness from
annotations/defaults rather than Field(...) metadata, then regenerate the
diagrams. In docs/models/requests.puml at lines 138-141 and request fields at 5,
9, 10, 14, 29, 32, 42, 47, 50, 61, 118, 149, and 155, restore required fields
such as StreamingInterruptRequest.request_id to non-Optional types. In
docs/models/responses.puml at lines 9-11, 20-22, 39-53, 64-65, 69, 76-82,
101-104, 118-139, 143, 151-167, 171-180, 183-193, 202-214, 216-223, 262-291,
299-318, and 331-366, restore required annotations while keeping only explicitly
optional fields such as impacts optional; specifically preserve required
status_code, detail, DetailModel.response/cause, ready, reason, overall_status,
and providers.
- Around line 133-137: Add a matching SavedPromptCreateRequest entry to
docs/models/requests.json, aligned with the schema shown in the
SavedPromptCreateRequest PlantUML definition and existing OpenAPI artifacts.
Keep the JSON catalog synchronized with the PlantUML/SVG documentation and
preserve the documented content, model_config, and name fields.
- Around line 123-129: Update the RlsapiV1SystemInfo class diagram field from
system_id to id with type Optional[str], matching the serialized model schema in
requests.json while leaving the Python alias unchanged.
In `@docs/models/responses.puml`:
- Around line 283-288: Add SavedPromptsConfigResponse to
docs/models/successful_responses.json, using the existing schema catalog
conventions and matching the fields exposed by SavedPromptsConfigResponse. Keep
the existing SavedPromptsConfiguration entry unchanged and ensure the
/v1/saved-prompts/config response model is represented directly.
In `@docs/models/successful_responses.json`:
- Line 4928: Rename the custom sse_example field in the relevant OpenAPI Schema
Object to use the x- extension prefix, preserving its existing SSE example value
unchanged.
In `@docs/models/successful_responses.md`:
- Around line 612-632: Update the documentation generation for enum schemas so
the HealthStatus section lists all seven wire values—ok, error, not_implemented,
unknown, healthy, degraded, and unhealthy—instead of relying on the
properties-based field table. Apply the same enum-value rendering to the Action
and JsonPathOperator sections, preserving their existing descriptions.
🪄 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 Plus
Run ID: a377d4e1-127b-4833-bd01-53788bd94c98
⛔ Files ignored due to path filters (3)
docs/models/common.svgis excluded by!**/*.svgdocs/models/requests.svgis excluded by!**/*.svgdocs/models/responses.svgis excluded by!**/*.svg
📒 Files selected for processing (15)
docs/models/agents.jsondocs/models/agents.mddocs/models/common.jsondocs/models/common.mddocs/models/common.pumldocs/models/conversation_summary.jsondocs/models/conversation_summary.mddocs/models/error_responses.jsondocs/models/error_responses.mddocs/models/requests.jsondocs/models/requests.mddocs/models/requests.pumldocs/models/responses.pumldocs/models/successful_responses.jsondocs/models/successful_responses.md
📜 Review details
⏰ Context from checks skipped due to timeout. (8)
- GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-0-7-on-pull-request
- GitHub Check: E2E: library mode / ci / group 2
- GitHub Check: E2E: server mode / ci / group 3
- GitHub Check: E2E: server mode / ci / group 1
- GitHub Check: E2E: library mode / ci / group 3
- GitHub Check: E2E: library mode / ci / group 1
- GitHub Check: E2E: server mode / ci / group 2
- GitHub Check: E2E Tests for Lightspeed Evaluation job
🧰 Additional context used
📓 Path-based instructions (1)
**/*
📄 CodeRabbit inference engine (Custom checks)
**/*: Flag meaningful O(n^2)+ algorithms on non-trivial inputs, including handlers and Kubernetes list operations.
Flag N+1 patterns that list items and then query once per item, including Kubernetes API and database access.
Flag expensive work inside loops, including API calls, JSON parsing, and regex compilation.
Flag unbounded growth in caches, watchers, or buffers when eviction or limits are missing.
Flag missing pagination or limits on list operations and API endpoints.
Flag secrets or tokens logged in plaintext or hardcoded in source.
Flag API endpoints missing authentication or authorization.
Flag injection vulnerabilities, including SQL injection, command injection, and path traversal.
Flag sensitive data leaked in API responses, WebSocket messages, or logs.
Flag Kubernetes Secrets and Red Hat secrets missing OwnerReferences.
Files:
docs/models/conversation_summary.jsondocs/models/error_responses.mddocs/models/conversation_summary.mddocs/models/requests.mddocs/models/common.mddocs/models/error_responses.jsondocs/models/agents.jsondocs/models/agents.mddocs/models/successful_responses.mddocs/models/successful_responses.jsondocs/models/common.pumldocs/models/requests.pumldocs/models/common.jsondocs/models/responses.pumldocs/models/requests.json
🪛 Checkov (3.3.8)
docs/models/conversation_summary.json
[high] 1-52: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
docs/models/error_responses.json
[high] 1-728: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
docs/models/agents.json
[high] 1-402: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
[medium] 12-17: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
docs/models/successful_responses.json
[high] 1-6234: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
[medium] 73-80: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
docs/models/common.json
[high] 1-1709: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
[medium] 179-185: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
docs/models/requests.json
[high] 1-2802: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
[medium] 12-17: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🪛 LanguageTool
docs/models/agents.md
[grammar] ~223-~223: Ensure spelling is correct
Context: ...number or step of tool execution | ## TurnCompleteStreamPayload SSE turn completion (same data shape as ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (14)
docs/models/agents.json (1)
70-93: LGTM!Also applies to: 114-127, 183-201, 229-247, 288-320, 341-379
docs/models/agents.md (1)
20-232: LGTM!docs/models/conversation_summary.json (1)
9-49: LGTM!docs/models/conversation_summary.md (1)
5-16: LGTM!docs/models/common.json (1)
71-95: LGTM!Also applies to: 245-354, 1058-1120, 1300-1361, 1490-1601, 1689-1702
docs/models/common.md (1)
5-16: LGTM!Also applies to: 28-37, 762-763
docs/models/common.puml (1)
13-13: LGTM!Also applies to: 131-136, 217-217, 304-310
docs/models/requests.json (1)
2578-2601: LGTM!docs/models/requests.md (1)
56-65: LGTM!docs/models/requests.puml (1)
164-166: 📐 Maintainability & Code Quality | 💤 Low valueComposition arrows dropped while the referencing fields remain.
RlsapiV1Contextstill declaresattachments : Optional[RlsapiV1Attachment],cla,systeminfo,terminal(109-113), but no relationship edges are emitted, so the diagram no longer shows the containment. Confirm this is an intended generator config change rather than lost output.docs/models/error_responses.json (1)
22-28: LGTM!Also applies to: 72-103, 136-141
docs/models/successful_responses.json (1)
4470-4550: LGTM!Also applies to: 5856-5891
docs/models/successful_responses.md (1)
293-293: LGTM!Also applies to: 304-304, 534-559, 655-657, 1615-1644, 1951-1964, 2141-2215, 2485-2552, 2567-2590
docs/models/responses.puml (1)
98-98: LGTM!Also applies to: 224-255
| "referenced_documents": { | ||
| "items": { | ||
| "$ref": "`#/components/schemas/`ReferencedDocument" | ||
| }, | ||
| "title": "Referenced Documents", | ||
| "type": "array" | ||
| }, |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🔴 Critical | ⚡ Quick win
All $ref values in the generated JSON are Markdown-escaped and unresolvable. Every reference is written as "`#/components/schemas/`X" instead of "#/components/schemas/X", so no validator or client generator can resolve them. Root cause is one generator step that wraps ref targets in backticks before serializing to JSON — fix it there rather than patching files individually.
docs/models/agents.json#L12-L18: strip the backticks from all nine$refvalues (lines 14, 53, 105, 139, 213, 259, 279, 332, 391).docs/models/common.json#L179-L199: strip the backticks from all$refvalues (182, 190, 198, 256, 1019, 1206, 1214, 1276, 1494, 1618-1645) and from thediscriminator.mappingtargets (693-695, 717-718, 799-802, 1652-1658), which otherwise breakoneOfresolution forOpenAIResponseMessage.contentandTurnSummary.output_items.
🧰 Tools
🪛 Checkov (3.3.8)
[medium] 12-17: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
📍 Affects 2 files
docs/models/agents.json#L12-L18(this comment)docs/models/common.json#L179-L199
🤖 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/models/agents.json` around lines 12 - 18, Fix the generator step that
serializes reference targets so it emits plain JSON pointers without Markdown
backticks for both $ref values and discriminator.mapping targets. This
root-cause change must correct docs/models/agents.json lines 12-18 and
docs/models/common.json lines 179-199; regenerate the artifacts so all listed
references and mappings become resolvable, rather than patching the generated
files individually.
| "EndStreamPayload": { | ||
| "additionalProperties": false, | ||
| "description": "SSE end-of-stream body (includes available_quotas beside data).", | ||
| "properties": { | ||
| "event": { | ||
| "const": "end", | ||
| "default": "end", | ||
| "title": "Event", | ||
| "type": "string" | ||
| }, |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🌐 Web query:
OpenAPI 3.0 const keyword supported nullable removed 3.1
💡 Result:
In OpenAPI 3.1, the nullable keyword was removed, and support for the const keyword was added [1][2]. These changes were part of the effort to align the OpenAPI Specification more closely with the JSON Schema standard [3][4][5]. 1. Removal of nullable: In OpenAPI 3.0, the nullable keyword was used to allow a field to accept null values [6]. OpenAPI 3.1 removed this keyword entirely in favor of the standard JSON Schema approach, which uses an array of types for the type keyword [3][2]. To make a field nullable in OpenAPI 3.1, you should specify both the intended type and "null" in an array, for example: type: ["string", "null"] [3][4][5]. 2. Addition of const: OpenAPI 3.1 added support for the const keyword from JSON Schema [2]. This keyword restricts a field to a single, exact value [2]. In OpenAPI 3.0, developers often approximated this behavior by using an enum with a single value [1][2]. The const keyword is considered more semantically precise for defining constant values [2].
Citations:
- 1: https://speakeasy.com/openapi/schemas/enums
- 2: https://openapispec.com/docs/what/what-are-the-key-differences-between-openapi-3-0-and-openapi-3-1/
- 3: https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
- 4: https://learn.openapis.org/upgrading/v3.0-to-v3.1.html
- 5: https://specway.com/blog/openapi-3-1-vs-3-0
- 6: https://swagger.io/docs/specification/v3_0/data-models/data-types/
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Files:"
git ls-files | rg '(^|/)docs/models/(agents|common)\.json$|openapi:|nullable:|const:|enum:|schema:|^docs/' || true
echo
echo "Relevant schema snippets from docs/models/agents.json:"
python3 - <<'PY'
import json
from pathlib import Path
p = Path("docs/models/agents.json")
if not p.exists():
print("missing")
raise SystemExit
for i, line in enumerate(p.read_text().splitlines(), 1):
if 1 <= i <= 12 or (42 <= i <= 52) or (96 <= i <= 104) or (130 <= i <= 136) or (204 <= i <= 210) or (250 <= i <= 256) or (270 <= i <= 276) or (323 <= i <= 329) or (382 <= i <= 388):
print(f"{i:4}: {line}")
PY
echo
echo "Search const/nullable in docs/models:"
rg -n '"const"|"nullable"|openapi:|type: \["boolean","null"\]|enum:' docs/models || true
echo
echo "Validate JSON if no parse error:"
python3 - <<'PY'
import json
from pathlib import Path
for p in [Path("docs/models/agents.json"), Path("docs/models/common.json")]:
if p.exists():
data=json.loads(p.read_text())
print(p, type(data).__name__, "openapi" in data, "components" in data)
PYRepository: lightspeed-core/lightspeed-stack
Length of output: 50388
Use an OpenAPI-compatible constant for the event discriminators.
docs/models/agents.json declares openapi: 3.0.0, but the event fields use JSON Schema-only const keywords (for end, error, interrupted, start, token, tool_call, tool_result, turn_complete). OpenAPI 3.0 tooling can ignore const, so these payloads lose their constrained literal type; replace them with enum: ["<event>"], or migrate both models to OpenAPI 3.1 and replace nullable with type: ["<type>", "null"].
🤖 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/models/agents.json` around lines 42 - 51, The event discriminator
definitions in EndStreamPayload and the corresponding SSE payload models use
OpenAPI 3.0-incompatible const keywords. Replace each listed event const with a
single-value enum containing the same literal, preserving the existing defaults
and event values; do not migrate the document to OpenAPI 3.1.
| "examples": [ | ||
| { | ||
| "attachment_type": "log", | ||
| "content": "this is attachment", | ||
| "content_type": "text/plain" | ||
| }, | ||
| { | ||
| "attachment_type": "configuration", | ||
| "content": "kind: Pod\n metadata:\n name: private-reg", | ||
| "content_type": "application/yaml" | ||
| }, | ||
| { | ||
| "attachment_type": "configuration", | ||
| "content": "foo: bar", | ||
| "content_type": "application/yaml" | ||
| }, | ||
| { | ||
| "attachment_type": "image", | ||
| "content": "<base64-encoded image data>", | ||
| "content_type": "image/png" | ||
| } | ||
| ], | ||
| "properties": { | ||
| "attachment_type": { | ||
| "description": "The attachment type, like 'log', 'configuration', 'image' etc.", | ||
| "examples": [ | ||
| "log", | ||
| "image" | ||
| ], |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Schema-level examples (plural) and const are 3.1 keywords in a 3.0 document.
OpenAPI 3.0 expects singular example; the plural array form (lines 12-33, 37-40, 46-50, 56-58, and throughout) plus const (line 402 onward) come from JSON Schema 2020-12. Combined with nullable (line 80), the file straddles two dialects. Same generator-side dialect decision as flagged in docs/models/agents.json.
🤖 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/models/common.json` around lines 12 - 40, Align common.json with the
OpenAPI dialect selected by the generator and used in agents.json. If the
document remains OpenAPI 3.0, replace schema-level examples arrays with singular
example values, replace const with the supported 3.0 equivalent, and remove or
adapt nullable consistently; otherwise declare and use OpenAPI 3.1 semantics
throughout.
| "referenced_documents": { | ||
| "type": "array", | ||
| "nullable": true, | ||
| "default": null, | ||
| "description": "List of documents referenced in the response (assistant messages only)", | ||
| "title": "Referenced Documents" | ||
| } |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Nullable arrays lose their items schema.
Message.referenced_documents is emitted as a bare array, yet ReferencedDocument is defined at line 1223 and docs/models/common.puml line 105 types it Optional[list[ReferencedDocument]]. Clients generate any[]. The same drop affects every optional list: logprobs (824-829), results (861-866), bytes/top_logprobs (1066-1084) — suggesting the generator skips items for Optional[list[...]] annotations.
🐛 Proposed fix
"referenced_documents": {
"type": "array",
+ "items": {
+ "$ref": "`#/components/schemas/ReferencedDocument`"
+ },
"nullable": true,📝 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.
| "referenced_documents": { | |
| "type": "array", | |
| "nullable": true, | |
| "default": null, | |
| "description": "List of documents referenced in the response (assistant messages only)", | |
| "title": "Referenced Documents" | |
| } | |
| "referenced_documents": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "`#/components/schemas/ReferencedDocument`" | |
| }, | |
| "nullable": true, | |
| "default": null, | |
| "description": "List of documents referenced in the response (assistant messages only)", | |
| "title": "Referenced Documents" | |
| } |
🤖 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/models/common.json` around lines 383 - 389, Update the schema generation
logic for optional list annotations so nullable arrays retain their element
`items` schema instead of being emitted as bare arrays. Ensure fields such as
Message.referenced_documents, logprobs, results, bytes, and top_logprobs
reference their declared item types while preserving nullable and default-null
behavior.
| class "Attachment" as src.models.common.query.Attachment { | ||
| attachment_type : str | ||
| content : str | ||
| content_type : str | ||
| attachment_type : Optional[str] | ||
| content : Optional[str] | ||
| content_type : Optional[str] | ||
| model_config : dict | ||
| validate_image_attachment() -> Self | ||
| } |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Compare declared optionality in the Pydantic sources against the JSON required lists.
fd -t f 'query.py|conversation.py|turn_summary.py' -x rg -n -A2 'attachment_type|content_type\s*:|^\s+content\s*:|provider\s*:|started_at\s*:|class (Attachment|ConversationTurn|Message|ToolCallSummary|ToolResultSummary)\b' {}Repository: lightspeed-core/lightspeed-stack
Length of output: 10337
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== common.json relevant schemas =="
python3 - <<'PY'
import json
from pathlib import Path
p = Path("docs/models/common.json")
data=json.loads(p.read_text())
defs=data.get("$defs", data)
for name in [
"Attachment", "ConversationDetails", "ConversationTurn", "Message",
"ToolCallSummary", "ToolResultSummary"
]:
s=defs[name]
req=s.get("required", [])
props=s.get("properties", {})
nullable_fields=[]
optional_like=[]
for k in sorted(req):
if k not in props:
print(f"{name}: required {k} missing in properties")
item=props.get(k, None)
if item is None:
continue
t=item.get("type")
nullable=(t in (None, ["str"]) or "type" not in item) and k in req
opt_marker="Optional[str], " if "Optional[str]" in props.get(k) else (next((f for f in props.get(k,"")) for f in props.get(k,"")))
print(f"{name}.{k}: required={k in req} pydantic type maybe missing, null? {nullable}, json type {t}")
if nullable:
nullable_fields.append(k)
if f"{name}.{k}" in []:
optional_like.append(k)
print(f"--- {name} required={req}")
PY
echo "== docs/models/common.puml relevant classes =="
sed -n '1,80p;90,130p;220,290p' docs/models/common.puml
echo "== locate model generator/doc generator scripts =="
rg -n "common\.json|common\.puml|Pydantic|model_json_schema|model_fields|docstrings|PlantUML|puml" -S --glob '!docs' --glob '!node_modules' --glob '!dist' --glob '!build' | head -200Repository: lightspeed-core/lightspeed-stack
Length of output: 302
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== repo files around docs/models and models =="
git ls-files | rg '(^|/)(docs/models|src/models|app/models|model|models)' | head -200
echo "== docs/models/common.json top and relevant classes =="
python3 - <<'PY'
import json
from pathlib import Path
p=Path("docs/models/common.json")
data=json.loads(p.read_text())
top=list(data.keys())[:20]
print("top_keys:", top)
if "$defs" in data:
defs=data["$defs"]
names=["Attachment","ConversationDetails","ConversationTurn","Message","ToolCallSummary","ToolResultSummary","Message","MCPServerInfo","MCPServerAuthInfo","ProviderHealthStatus","RAGChunk","ToolInfoSummary","TurnSummary"]
for name in names:
s=defs.get(name)
print(f"\n## {name}")
if not s:
print("missing")
continue
print(json.dumps({"required": s.get("required"), "properties": {k:s.get("properties",{}).get(k) for k in s.get("required",[]) if k in s.get("properties",{})}}, indent=2))
else:
print("has Attachment?", "Attachment" in data)
PY
echo "== docs/models/common.puml relevant classes =="
for start in 10 30 40 90 100 230 250; do
echo "--- lines $((start > 5 ? start-5 : 1))-$((start+25))"
sed -n "$((start > 5 ? start-5 : 1)),$((start+25))p" docs/models/common.puml
done
echo "== locate common.json/common.puml generation references =="
rg -n "common\.json|common\.puml|PlantUML|plantuml|model_json_schema|model_fields|model_dump|json_schema|pydantic_schema|docs/models" -S --glob '!docs' --glob '!node_modules' --glob '!dist' --glob '!build' | head -250Repository: lightspeed-core/lightspeed-stack
Length of output: 14376
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== common model files =="
for f in src/models/common/query.py src/models/common/conversation.py src/models/common/turn_summary.py src/models/common/health.py src/models/common/mcp.py; do
echo "--- $f"
sed -n '1,180p' "$f"
done
echo "== generated docs files size and relevant sections =="
wc -l docs/models/common.json docs/models/common.puml docs/models/common.md src/utils/models_dumper.py
sed -n '1,160p' docs/models/common.json
sed -n '225,260p' docs/models/common.json
sed -n '700,735p' docs/models/common.json
sed -n '1408,1520p' docs/models/common.json
rg -n '"Attachment"|"ConversationDetails"|"ConversationTurn"|"Message"|"ToolCallSummary"|"ToolResultSummary"' docs/models/common.json -A 45 -B 5Repository: lightspeed-core/lightspeed-stack
Length of output: 50390
Align common.puml optionality with the Pydantic schemas.
The generated PlantUML shows many required API fields as Optional[...], while the Pydantic models and common.json mark them required: Attachment.attachment_type/content/content_type, ConversationDetails.conversation_id, ConversationTurn.provider/model/started_at/completed_at, Message.content/type, RAGChunk.content, ToolCallSummary.id/name, ToolResultSummary.id/status/content/round, and MCP/provider fields in MCPServer.../ProviderHealthStatus. Fix the generator or regenerated docs so integrators don’t treat contract-required fields as optional.
🤖 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/models/common.puml` around lines 17 - 23, Align the generated PlantUML
field optionality with the Pydantic schemas and common.json, preserving Optional
only for genuinely nullable fields. Update the generator or regenerate
common.puml so required fields in Attachment, ConversationDetails,
ConversationTurn, Message, RAGChunk, ToolCallSummary, ToolResultSummary,
MCPServer variants, and ProviderHealthStatus are no longer marked optional.
| class "SavedPromptCreateRequest" as src.models.api.requests.saved_prompts.SavedPromptCreateRequest { | ||
| content : Optional[str] | ||
| model_config : dict | ||
| name : Optional[str] | ||
| } |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
fd -t f 'saved_prompts.py' src/models
rg -n 'SavedPromptCreateRequest' -g '!docs/**'
rg -n 'SavedPromptCreateRequest' docs/modelsRepository: lightspeed-core/lightspeed-stack
Length of output: 348
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "## requests.json SavedPrompt entries"
python3 - <<'PY'
import json
from pathlib import Path
p=Path('docs/models/requests.json')
data=json.loads(p.read_text())
print(type(data))
if isinstance(data, dict):
keys=list(data.keys())
print("doc count", len(keys))
hits=[k for k in keys if "SavedPrompt" in k or "Terms" in k or "Rank" in k or "Terminal" in k or "Search" in k]
print("first 20:", hits[:20])
for k in hits:
v=data[k]
print(k, type(v), v.get("title") if isinstance(v, dict) else v)
elif isinstance(data, list):
hits=[(i,x.get("name") or x.get("title") if isinstance(x,dict) else str(x)) for i,x in enumerate(data) if "SavedPrompt" in str(x) or "Terminal" in str(x) or "Search" in str(x) or "Rank" in str(x)]
print(hits[:50])
PY
echo
echo "## requests.puml SavedPrompt refs"
rg -n -C 2 'SavedPromptCreateRequest|SavedPrompt|saved_prompts' docs/models/requests.puml
echo
echo "## saved_prompts.py relevant request model"
sed -n '1,220p' src/models/api/requests/saved_prompts.py
echo
echo "## all request model files mentioning SavedPromptCreateRequest"
rg -n -C 3 'class SavedPromptCreateRequest|SavedPromptCreateRequest' src docs || trueRepository: lightspeed-core/lightspeed-stack
Length of output: 9117
Keep docs/models/requests.json in sync with docs/models/requests.puml
SavedPromptCreateRequest is documented in the PlantUML/SVG pair but has no matching entry in docs/models/requests.json, while the OpenAPI artifacts include the schema. Add the catalog entry or drop the PlantUML/SVG model so consumers don’t treat this API contract as partially documented.
🤖 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/models/requests.puml` around lines 133 - 137, Add a matching
SavedPromptCreateRequest entry to docs/models/requests.json, aligned with the
schema shown in the SavedPromptCreateRequest PlantUML definition and existing
OpenAPI artifacts. Keep the JSON catalog synchronized with the PlantUML/SVG
documentation and preserve the documented content, model_config, and name
fields.
| class "StreamingInterruptRequest" as src.models.api.requests.query.StreamingInterruptRequest { | ||
| model_config : dict | ||
| request_id : str | ||
| request_id : Optional[str] | ||
| check_request_id(value: str) -> str |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Both PlantUML diagrams mark Field(...)-required attributes as Optional[...]. One root cause: the diagram generator appears to infer optionality from the presence of Field(...) metadata rather than from the annotation/default, so required fields are misdrawn — contradicting both the source models and the JSON catalogs regenerated in this same PR. ResponsesResponse (responses.puml 224-255) kept its required annotations, confirming this is an artifact rather than a convention change.
docs/models/requests.puml#L138-L141: restorerequest_id : str(src/models/api/requests/query.py:216-253) and the other required request fields at 5, 9, 10, 14, 29, 32, 42, 47, 50, 61, 118, 149, 155.docs/models/responses.puml#L9-L11: restorestatus_code : int/detail : DetailModelpersrc/models/api/responses/error/bases.py:16-94, andDetailModel.response/causeat 64-65.docs/models/responses.puml#L216-L223: restoreready,reason,overall_status,providersas required perprobes.py:52-123, keeping onlyimpactsoptional; apply the same correction to the other flipped response models (20-22, 39-53, 69, 76-82, 101-104, 118-139, 143, 151-167, 171-180, 183-193, 202-214, 262-291, 299-318, 331-366).
📍 Affects 2 files
docs/models/requests.puml#L138-L141(this comment)docs/models/responses.puml#L9-L11docs/models/responses.puml#L216-L223
🤖 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/models/requests.puml` around lines 138 - 141, Fix the diagram generator
to infer requiredness from annotations/defaults rather than Field(...) metadata,
then regenerate the diagrams. In docs/models/requests.puml at lines 138-141 and
request fields at 5, 9, 10, 14, 29, 32, 42, 47, 50, 61, 118, 149, and 155,
restore required fields such as StreamingInterruptRequest.request_id to
non-Optional types. In docs/models/responses.puml at lines 9-11, 20-22, 39-53,
64-65, 69, 76-82, 101-104, 118-139, 143, 151-167, 171-180, 183-193, 202-214,
216-223, 262-291, 299-318, and 331-366, restore required annotations while
keeping only explicitly optional fields such as impacts optional; specifically
preserve required status_code, detail, DetailModel.response/cause, ready,
reason, overall_status, and providers.
| class "SavedPromptsConfigResponse" as src.models.api.responses.successful.saved_prompts.SavedPromptsConfigResponse { | ||
| max_content_length : int | ||
| max_display_name_length : int | ||
| max_prompts_per_user : int | ||
| max_content_length : Optional[int] | ||
| max_display_name_length : Optional[int] | ||
| max_prompts_per_user : Optional[int] | ||
| model_config : dict | ||
| } |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
rg -n 'SavedPromptsConfigResponse' -g '!docs/**' -C3
rg -n 'SavedPromptsConfigResponse|SavedPromptsConfiguration' docs/modelsRepository: lightspeed-core/lightspeed-stack
Length of output: 245
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== repo files matching responses.puml/successful_responses.json =="
git ls-files | rg '(^|/)docs/models/(responses\.puml|successful_responses\.json)$|src/models/api/responses/'
echo
echo "== repository-wide references to SavedPromptsConfigResponse =="
rg -n 'SavedPromptsConfigResponse'
echo
echo "== repository-wide references to SavedPromptsConfiguration =="
rg -n 'SavedPromptsConfiguration' -C2
echo
echo "== docs/models responsive matching snippets =="
if [ -f docs/models/responses.puml ]; then
rg -n 'SavedPromptsConfigResponse|SavedPromptsConfiguration|saved_prompts' docs/models/responses.puml -C3 || true
fi
if [ -f docs/models/successful_responses.json ]; then
rg -n '"SavedPromptsConfigResponse"|"SavedPromptsConfiguration"|saved_prompts' docs/models/successful_responses.json -C2 || true
fiRepository: lightspeed-core/lightspeed-stack
Length of output: 2069
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== docs/models/responses.puml lines 260-305 =="
sed -n '260,305p' docs/models/responses.puml | nl -ba -v260
echo
echo "== docs/models/successful_responses.json lines 5160-5215 =="
sed -n '5160,5215p' docs/models/successful_responses.json | nl -ba -v5160
echo
echo "== successful responses catalog registration/imports =="
sed -n '1,240p' src/models/api/responses/successful/README.md
sed -n '1,220p' src/models/api/responses/successful/__init__.py
echo
echo "== saved_prompts module =="
sed -n '1,220p' src/models/api/responses/successful/saved_prompts.py
echo
echo "== endpoint references for saved prompts config response/model =="
rg -n 'SavedPromptsConfigResponse|SavedPromptsConfiguration|saved.*prompt|config.*saved|saved.*config' src tests -g '!**/*.pyc' || trueRepository: lightspeed-core/lightspeed-stack
Length of output: 257
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== docs/models/responses.puml lines 260-305 =="
sed -n '260,305p' docs/models/responses.puml
echo
echo "== docs/models/successful_responses.json lines 5160-5215 =="
sed -n '5160,5215p' docs/models/successful_responses.json
echo
echo "== successful responses catalog registration/imports =="
sed -n '1,240p' src/models/api/responses/successful/README.md
sed -n '1,220p' src/models/api/responses/successful/__init__.py
echo
echo "== saved_prompts module =="
sed -n '1,220p' src/models/api/responses/successful/saved_prompts.py
echo
echo "== endpoint references for saved prompts config response/model =="
rg -n 'SavedPromptsConfigResponse|SavedPromptsConfiguration|saved.*prompt|config.*saved|saved.*config' src tests -g '!**/*.pyc' || trueRepository: lightspeed-core/lightspeed-stack
Length of output: 50388
Add SavedPromptsConfigResponse to the successful-response schema catalog.
/v1/saved-prompts/config uses SavedPromptsConfigResponse directly, but docs/models/successful_responses.json only contains the configuration model (SavedPromptsConfiguration). Add a response schema for this endpoint model to keep the docs aligned.
🤖 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/models/responses.puml` around lines 283 - 288, Add
SavedPromptsConfigResponse to docs/models/successful_responses.json, using the
existing schema catalog conventions and matching the fields exposed by
SavedPromptsConfigResponse. Keep the existing SavedPromptsConfiguration entry
unchanged and ensure the /v1/saved-prompts/config response model is represented
directly.
| "available_quotas", | ||
| "output_text" | ||
| ], | ||
| "sse_example": "event: response.created\ndata: {\"type\":\"response.created\",\"sequence_number\":0,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"in_progress\",\"model\":\"openai/gpt-4o-mini\",\"output\":[],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{},\"output_text\":\"\"}}\n\nevent: response.output_item.added\ndata: {\"type\":\"response.output_item.added\",\"sequence_number\":1,\"response_id\":\"resp_abc\",\"output_index\":0,\"item\":{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"in_progress\",\"role\":\"assistant\",\"content\":[]}}\n\n...\n\nevent: response.completed\ndata: {\"type\":\"response.completed\",\"sequence_number\":30,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"completed\",\"model\":\"openai/gpt-4o-mini\",\"output\":[{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello! How can I help?\",\"annotations\":[]}]}],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"usage\":{\"input_tokens\":10,\"output_tokens\":6,\"total_tokens\":16,\"input_tokens_details\":{\"cached_tokens\":0},\"output_tokens_details\":{\"reasoning_tokens\":0}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{\"daily\":1000,\"monthly\":50000},\"output_text\":\"Hello! How can I help?\"}}\n\ndata: [DONE]\n\n", |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🌐 Web query:
Does OpenAPI 3.0 require specification extension keys to start with "x-"?
💡 Result:
Yes, under the OpenAPI 3.0 specification, specification extension keys must begin with the prefix x- [1][2][3]. This requirement is part of the specification's mechanism for allowing custom, vendor-specific, or tool-specific properties that are not part of the standard OpenAPI schema [1][4][2]. Because OpenAPI tools are designed to ignore unknown properties that do not follow this naming convention, using the x- prefix ensures that custom extensions do not conflict with current or future official OpenAPI fields and allows tools to handle them gracefully [1][4]. The OpenAPI Initiative also reserves certain prefixes, such as x-oai- and x-oas-, for its own official use [2]. Note that while the top-level keys of these extensions must start with x-, if the value of an extension is an object, the keys within that nested object do not necessarily need to follow the x- prefix requirement [1].
Citations:
- 1: https://swagger.io/docs/specification/v3_0/openapi-extensions/
- 2: https://redocly.com/learn/openapi/openapi-visual-reference/specification-extensions
- 3: https://blog.yimmo.org/posts/understanding-openapi-3-0-extensions.html
- 4: Clarification on Best Practices for Extending OpenAPI Specification OAI/OpenAPI-Specification#4989
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Repository files matching successful_responses.json:"
fd -a 'successful_responses\.json$' . || true
echo
echo "JSON parsing probe for target document:"
python3 - <<'PY'
import json
from pathlib import Path
paths = list(Path('.').rglob('successful_responses.json'))
for p in paths:
if '.git' in p.parts:
continue
print(f'--- {p} ---')
try:
data = json.loads(p.read_text())
except Exception as e:
print(f'parse error: {e}')
continue
# Try to locate nested dict/object with "sse_example" around the reported line.
for i, obj in enumerate(data if isinstance(data, list) else []):
if isinstance(obj, dict) and 'sse_example' in obj:
print(f'list index {i}: sse_example present -> {repr(obj["sse_example"][:80])}...')
PY
echo
echo "Search for SSE-like OpenAPI extensions in docs:"
rg -n '"sse-example"|"x-sse-example"|"sse_example"' docs || trueRepository: lightspeed-core/lightspeed-stack
Length of output: 3588
🌐 Web query:
OpenAPI 3.0 Schema Object "example" extra fields "additionalProperties" allowed by default strict validators
💡 Result:
In OpenAPI 3.0, the additionalProperties keyword controls whether extra fields (properties not explicitly defined in the properties keyword) are allowed in an object [1][2]. By default, if additionalProperties is not specified, extra fields are allowed [1][2]. Key points regarding additionalProperties and validation in OpenAPI 3.0: 1. Default Behavior: OpenAPI 3.0 follows JSON Schema conventions where schemas are "open" by default [2]. If you do not explicitly set additionalProperties: false, the validator will permit any additional properties [1][2]. 2. Strict Validation: To enforce strict validation and reject any extra fields, you must explicitly set additionalProperties: false in your Schema Object [3][2]. 3. Implementation: Many API frameworks and validators implement this by default as an "open" schema, meaning they will ignore extra fields rather than throwing a validation error unless explicitly configured otherwise [4][3]. If you require strict validation that blocks extra fields, you should use a validator or middleware explicitly configured for strict mode (e.g., OAS30StrictValidator in some Python environments) or ensure your schema definition explicitly forbids them [3]. Example of allowing only defined properties: type: object properties: name: type: string additionalProperties: false In this example, providing any property other than "name" will cause a validation error [2].
Citations:
- 1: https://swagger.io/docs/specification/v3_0/data-models/data-types/
- 2: https://www.learnjsonschema.com/draft3/core/additionalproperties/
- 3: https://openapi-schema-validator.readthedocs.io/en/latest/validation.html
- 4: https://stackoverflow.com/questions/64815690/what-happens-when-we-pass-extra-field-in-request-bodyjson-in-a-openapi-post-en
🌐 Web query:
specman tool openapi json extra fields property name does not match pattern "x-.*"
💡 Result:
The validation error indicating that a property name does not match the pattern ^x-.* typically occurs when an OpenAPI or JSON Schema validator encounters an unsupported keyword (like patternProperties or propertyNames) that has been incorrectly transformed or encountered in a context where only vendor extensions (prefixed with x-) are permitted [1][2][3]. In the OpenAPI specification (versions 2.0 and 3.0), the schema object is restricted to a specific subset of JSON Schema keywords [2]. Because these versions do not natively support keywords like patternProperties, some tooling implementations attempt to preserve this information by renaming them to vendor extensions (e.g., x-patternProperties) [1][2][3]. If a validator or code generator expects standard keywords but receives these renamed extensions, or conversely, if it strictly enforces the x- prefix for all "extra" fields and encounters one that does not follow this pattern, it will trigger a validation error [1][4]. To resolve or mitigate this issue: 1. Check Tooling Configuration: Many generators (such as the OpenAPI Generator for various languages) have configuration options that control how additional or unknown properties are handled [5][6][7]. For example, setting options like disallowAdditionalPropertiesIfNotPresent to false can prevent the generator from strictly validating and failing on unexpected fields [5][6][7]. 2. Validate Schema Compatibility: Ensure your OpenAPI document is compliant with the version you are using (e.g., 3.0 vs. 3.1) [2][3]. OpenAPI 3.1 introduced support for a broader range of JSON Schema keywords, which may eliminate the need for vendor-extension workarounds [3][4]. 3. Review Vendor Extensions: If you are using custom vendor extensions, ensure they are correctly placed in the schema and that the specific tool you are using is configured to process them rather than treating them as standard schema keywords [2][8]. If you are encountering this error specifically within a code generation context, it is often due to the generator's strictness in schema parsing [6][9]. Consult your tool's specific documentation regarding additionalProperties or unknown field handling to loosen these constraints [5][7].
Citations:
- 1: Support
x-propertyNamesin OpenAPI 3.0 koxudaxi/datamodel-code-generator#1584 - 2: OpenAPI 3.0: Preserve PatternProperties via Vendor Extension during Serialization microsoft/OpenAPI.NET#2716
- 3: patternProperties -> x-patternProperties JaredCE/json-schema-to-openAPI-schema-object#22
- 4: Code not generated for patternProperties in JSON Schemas koxudaxi/datamodel-code-generator#1851
- 5: [BUG][JAVA] IllegalArgumentException while parsing responses with unknown fields ❗ OpenAPITools/openapi-generator#12550
- 6: [BUG] [Golang] JSON unmarshal fails on additional properties when additionalProperties is unset OpenAPITools/openapi-generator#21121
- 7: [BUG] [Go] Discriminator unmarshal error & why DisallowUnknownFields() should be removed OpenAPITools/openapi-generator#21164
- 8: Supply custom "property name" for additionalProperties Redocly/redoc#622
- 9: [BUG] [GO] Client does not allow unknown fields in response meaning additions to APIs break clients OpenAPITools/openapi-generator#21446
🌐 Web query:
specman OpenAPI validator "property name does not match pattern" "x-"
💡 Result:
The error message "property name does not match pattern x-" is typically a validation error generated by OpenAPI tooling indicating that a custom field or extension in your OpenAPI specification does not adhere to the required naming convention for specification extensions [1]. In the OpenAPI Specification, any property intended as a custom extension must begin with the prefix x- [1][2]. If a validator flags a property name that does not match this pattern, it means the tool encountered a key that is either: 1. A mistyped or non-standard extension that is missing the required x- prefix [1]. 2. An unrecognized field that the validator incorrectly expects to be an extension because it is not defined in the core OpenAPI standard [1]. To resolve this: - Ensure all custom properties begin with x- (e.g., x-internal-id, x-custom-metadata) [1]. - Check for typos in your extension names [1]. - Verify that the object where the property is defined actually allows extensions; not all objects in the OpenAPI specification support them [1]. - If you are using a tool like the one referenced as "specman" (which is primarily a hardware verification language and associated toolset, not a standard OpenAPI validator [3][4]), ensure you are using the correct configuration or linting rules for that specific tool, as different linters may have different levels of strictness regarding extension naming [5][1]. Note: "Specman" is a well-known hardware verification language [3][4]. While there are various tools for OpenAPI and JSON Schema validation [6], if you are receiving this error from a tool specifically named "specman," ensure it is configured correctly for your OpenAPI version, as confusion may arise if the tool is being applied outside its primary context of hardware verification [3][7].
Citations:
- 1: https://docs.apimatic.io/rulesets/openapi-v3-syntax-validation/specification-extension-name-begin-with-x-dash/
- 2: OpenAPI 3.0: Preserve PatternProperties via Vendor Extension during Serialization microsoft/OpenAPI.NET#2716
- 3: https://github.com/k-sparrow/specman-e-parser/blob/main/README.md
- 4: https://tsvi.mostovi.cz/verification-languages-overview-and-concepts
- 5: https://pb33f.io/libopenapi/validation/
- 6: https://lib.rs/template-engine
- 7: https://dvcon-proceedings.org/wp-content/uploads/taming-the-beast-a-smart-generation-of-design-attributes-parameters-for-verification-closure-using-specman.pdf
Rename the custom schema-field to an x- extension.
docs/models/successful_responses.json:4928 uses sse_example inside an OpenAPI Schema Object. That key isn’t a standard schema keyword; prefix custom extension fields with x- so strict OpenAPI validators don’t reject it.
♻️ Suggested key
- "sse_example": "event: response.created\ndata: ...",
+ "x-sse-example": "event: response.created\ndata: ...",📝 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.
| "sse_example": "event: response.created\ndata: {\"type\":\"response.created\",\"sequence_number\":0,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"in_progress\",\"model\":\"openai/gpt-4o-mini\",\"output\":[],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{},\"output_text\":\"\"}}\n\nevent: response.output_item.added\ndata: {\"type\":\"response.output_item.added\",\"sequence_number\":1,\"response_id\":\"resp_abc\",\"output_index\":0,\"item\":{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"in_progress\",\"role\":\"assistant\",\"content\":[]}}\n\n...\n\nevent: response.completed\ndata: {\"type\":\"response.completed\",\"sequence_number\":30,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"completed\",\"model\":\"openai/gpt-4o-mini\",\"output\":[{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello! How can I help?\",\"annotations\":[]}]}],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"usage\":{\"input_tokens\":10,\"output_tokens\":6,\"total_tokens\":16,\"input_tokens_details\":{\"cached_tokens\":0},\"output_tokens_details\":{\"reasoning_tokens\":0}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{\"daily\":1000,\"monthly\":50000},\"output_text\":\"Hello! How can I help?\"}}\n\ndata: [DONE]\n\n", | |
| "x-sse-example": "event: response.created\ndata: {\"type\":\"response.created\",\"sequence_number\":0,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"in_progress\",\"model\":\"openai/gpt-4o-mini\",\"output\":[],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{},\"output_text\":\"\"}}\n\nevent: response.output_item.added\ndata: {\"type\":\"response.output_item.added\",\"sequence_number\":1,\"response_id\":\"resp_abc\",\"output_index\":0,\"item\":{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"in_progress\",\"role\":\"assistant\",\"content\":[]}}\n\n...\n\nevent: response.completed\ndata: {\"type\":\"response.completed\",\"sequence_number\":30,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"completed\",\"model\":\"openai/gpt-4o-mini\",\"output\":[{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello! How can I help?\",\"annotations\":[]}]}],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"usage\":{\"input_tokens\":10,\"output_tokens\":6,\"total_tokens\":16,\"input_tokens_details\":{\"cached_tokens\":0},\"output_tokens_details\":{\"reasoning_tokens\":0}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{\"daily\":1000,\"monthly\":50000},\"output_text\":\"Hello! How can I help?\"}}\n\ndata: [DONE]\n\n", |
🤖 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/models/successful_responses.json` at line 4928, Rename the custom
sse_example field in the relevant OpenAPI Schema Object to use the x- extension
prefix, preserving its existing SSE example value unchanged.
| ## HealthStatus | ||
|
|
||
|
|
||
| Health status enum for provider and service health checks. | ||
|
|
||
| This enum serves two purposes: | ||
|
|
||
| 1. Provider-level health (returned by Llama Stack providers): | ||
| - OK: Provider is healthy and operational | ||
| - ERROR: Provider is unhealthy or failed health check | ||
| - NOT_IMPLEMENTED: Provider does not implement health checks | ||
| - UNKNOWN: Fallback when provider status cannot be determined | ||
|
|
||
| 2. Service-level health (overall LCORE status): | ||
| - HEALTHY: All systems operational, LLS connected, all providers healthy | ||
| - DEGRADED: Service running with reduced functionality (e.g., LLS unavailable) | ||
| - UNHEALTHY: Service connected but one or more providers are unhealthy | ||
|
|
||
|
|
||
|
|
||
|
|
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
HealthStatus section documents the semantics but lists none of the actual enum values.
docs/models/successful_responses.json lines 1585-1593 define seven members (ok, error, not_implemented, unknown, healthy, degraded, unhealthy); the Markdown renders no table or list after the docstring, so readers can't see the wire values. Enum schemas have no properties, so the generator's field-table path emits nothing — same gap applies to Action and JsonPathOperator.
🤖 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/models/successful_responses.md` around lines 612 - 632, Update the
documentation generation for enum schemas so the HealthStatus section lists all
seven wire values—ok, error, not_implemented, unknown, healthy, degraded, and
unhealthy—instead of relying on the properties-based field table. Apply the same
enum-value rendering to the Action and JsonPathOperator sections, preserving
their existing descriptions.
1 participant
Description
LCORE-3229: updated all models documentation
Type of change
Tools used to create PR
Related Tickets & Documents
Summary by CodeRabbit