LCORE-3229: Updated models docs

[tisnik]

Description

LCORE-3229: Updated models docs

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-3229

Summary by CodeRabbit

• Documentation
  • Updated request, response, and common model diagrams to accurately show required fields, payload structures, and relationships.
  • Added clearer associations for error details, inference data, streaming payloads, transcripts, and RLSAPI contexts.
  • Expanded model documentation coverage to include generated SVG diagrams alongside PlantUML sources.
• Consistency
  • Improved clarity and accuracy across conversation, query, tool, file, provider, prompt, and vector store models.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 6152f79e-3f32-41cb-8e98-26675e8ebd19

📥 Commits

Reviewing files that changed from the base of the PR and between b6c0b73 and e5ec8c6.

⛔ Files ignored due to path filters (3)

• docs/models/common.svg is excluded by !**/*.svg
• docs/models/requests.svg is excluded by !**/*.svg
• docs/models/responses.svg is excluded by !**/*.svg

📒 Files selected for processing (4)

• Makefile
• docs/models/common.puml
• docs/models/requests.puml
• docs/models/responses.puml

📜 Recent review details

⏰ Context from checks skipped due to timeout. (12)

• GitHub Check: spectral
• GitHub Check: integration_tests (3.13)
• GitHub Check: build-pr
• GitHub Check: integration_tests (3.12)
• GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-0-7-on-pull-request
• GitHub Check: E2E Tests for Lightspeed Evaluation job
• GitHub Check: E2E: server mode / ci / group 3
• GitHub Check: E2E: server mode / ci / group 1
• GitHub Check: E2E: library mode / ci / group 1
• GitHub Check: E2E: library mode / ci / group 2
• GitHub Check: E2E: library mode / ci / group 3
• GitHub Check: E2E: server mode / ci / group 2

🧰 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:

• Makefile
• docs/models/requests.puml
• docs/models/common.puml
• docs/models/responses.puml

🔇 Additional comments (5)

Makefile (1)

215-215: LGTM!

docs/models/common.puml (2)

13-30: LGTM!

Also applies to: 39-45, 90-122, 131-136, 145-162, 171-204, 217-217, 232-267, 285-294

---

304-310: 🩺 Stability & Availability

No change needed. TurnCompleteStreamPayload.data is annotated as TokenChunkData in src.models.common.agents.stream_payloads.TurnCompleteStreamPayload.

docs/models/requests.puml (1)

5-32: LGTM!

Also applies to: 42-50, 61-61, 101-135, 144-150, 161-165

docs/models/responses.puml (1)

4-11: LGTM!

Also applies to: 20-30, 39-53, 64-82, 100-103, 117-192, 201-221, 261-272, 281-300, 313-351

---

Walkthrough

PlantUML request, response, and common model diagrams now show more required fields, updated class members, and revised relationships. The docs/models Make target also tracks generated SVG artifacts.

Changes

Model diagram contracts

Layer / File(s)	Summary
Common model contracts docs/models/common.puml	Updates common conversation, response, tool, transcript, and streaming models with required fields, additional members, and revised event relationships.
Request model contracts docs/models/requests.puml	Makes numerous conversation, prompt, query, RLSAPI, interrupt, and vector-store request fields required and adds RLSAPI associations.
Response model contracts docs/models/responses.puml	Makes numerous API response fields required and adds error-detail and RLSAPI inference associations.
Generated model artifact wiring Makefile	Adds request, response, common, and database SVG outputs to the docs/models target prerequisites.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• lightspeed-core/lightspeed-stack#2225: Updates overlapping docs/models Makefile prerequisites and generated artifact behavior.

🚥 Pre-merge checks | ✅ 6 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is relevant, but it is too generic to convey the specific model documentation changes.	Use a more specific title that names the docs model updates, such as the affected model diagrams or the main behavior change.

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Performance And Algorithmic Complexity	✅ Passed	Docs-only changes (Makefile/docs models and generated SVGs); no runtime handlers, loops, N+1s, or unbounded structures were modified.
Security And Secret Handling	✅ Passed	PR only updates model docs/Makefile; no hardcoded secrets, authz code, injections, or leaked runtime data were introduced in the touched files.

✨ 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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}