LCORE-1262: Updated responses examples

[asimurka]

Description

This PR updates examples for v1/responses endpoint. Namely enriches non-streaming example by adding additional fields and fixes rendering of streaming example.

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

Identify any AI code assistants used in this PR (for transparency and review context)

• Assisted-by: N/A

Related Tickets & Documents

• Related Issue # LCORE-1262
• Closes #

Checklist before requesting a review

• I have performed a self-review of my code.
• PR has passed all pre-merge test jobs.
• If it is a core feature, I have added thorough tests.

Testing

• Please provide detailed steps to perform tests related to this code change.
• How were the fix/results from this change verified? Please provide relevant screenshots or results.

Summary by CodeRabbit

• Documentation
  • Token usage now shows detailed breakdowns, including cached and reasoning token counts alongside existing input/output/total metrics.
  • Streaming responses examples updated to a new event schema with revised event types, clearer sequence tracking, and reorganized response/item fields.
  • API docs/examples modernized to use the new example format and reflect the updated response and streaming payload structures.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d4a1368a-6d64-4392-98aa-740e81813993

📥 Commits

Reviewing files that changed from the base of the PR and between e2c3035 and a3f6235.

📒 Files selected for processing (2)

• docs/openapi.json
• src/models/responses.py

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/openapi.json
• src/models/responses.py

---

Walkthrough

Added token-detail fields to example usage objects and revised streaming SSE examples: replaced the prior nested examples.stream.value with a single example string and updated event payload shapes (changed response.created, replaced intermediate output events, removed response.output_item.done, and updated response.completed).

Changes

Cohort / File(s)	Summary
OpenAPI examples docs/openapi.json	Added input_tokens_details.cached_tokens and output_tokens_details.reasoning_tokens to two usage example payloads. Replaced examples.stream.value streaming example with a single example string and updated SSE event sequence: response.created payload fields extended (object, model, store, text.format), intermediate events reshaped to response.output_item.added (new type, response_id, item structure), removed response.output_item.done, and response.completed updated to include new usage details and the revised response/item structure (ellipsis used to elide middle).
Response model examples src/models/responses.py	Updated ResponsesResponse JSON examples to include input_tokens_details.cached_tokens and output_tokens_details.reasoning_tokens. Rewrote the sse_example string to match the new streaming event schema and changed the OpenAPI text/event-stream entry to use example instead of the previous examples: { stream: { value: ... } } wrapper.

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 primary change: updating response examples in the API documentation for the v1/responses endpoint.
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

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

src/models/responses.py (1)

1646-1646: Prefer an SSE-valid placeholder for omitted events.

Using raw ... is not a valid SSE line format. Consider an SSE comment line (e.g., : ...) or a data: placeholder to keep the sample syntactically consistent.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/models/responses.py` at line 1646, The placeholder string "...\n\n" is
not valid SSE; replace that literal with an SSE-valid placeholder such as a
comment line ": ...\n\n" or a data field "data: ...\n\n" wherever the "...\n\n"
token appears (search for the exact string "...\n\n" in the responses
definitions) so emitted samples are syntactically valid SSE.

🤖 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 4290: The SSE example mixes event: "response.created" with a payload
whose "type" is "response.in_progress"; update the SSE frames so the event name
matches the payload type (change the first frame's event from "response.created"
to "response.in_progress") in both occurrences (the example block containing the
string "event: response.created" and the JSON payload with
"\"type\":\"response.in_progress\""); ensure the corresponding later example
stays consistent as well (the final "response.completed" frame already matches
"type":"response.completed").
- Line 4290: The SSE transcript example in the "example" string includes a
literal "...\n\n" placeholder which breaks parseability; replace that
placeholder with a valid SSE-safe omission (for example a comment line starting
with ":" like ": omitted events\n\n") or remove the placeholder entirely so the
stream remains valid, ensuring the example still flows from the earlier events
(e.g., the block containing "event: response.in_progress" and "event:
response.output_item.added") to the later "event: response.completed" entry;
apply the same replacement for the other occurrence referenced in this file.

In `@src/models/responses.py`:
- Around line 1634-1640: The SSE example's event header "event:
response.created" is inconsistent with the JSON payload field
`"type":"response.in_progress"`; update the payload `type` to
`"response.created"` to match the event and the producer behavior (see the
emitter in endpoints/responses.py), i.e., change the `"type"` value in the JSON
block that currently reads `"response.in_progress"` to `"response.created"` so
the event name and payload are consistent.

---

Nitpick comments:
In `@src/models/responses.py`:
- Line 1646: The placeholder string "...\n\n" is not valid SSE; replace that
literal with an SSE-valid placeholder such as a comment line ": ...\n\n" or a
data field "data: ...\n\n" wherever the "...\n\n" token appears (search for the
exact string "...\n\n" in the responses definitions) so emitted samples are
syntactically valid SSE.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f7417fba-7ce8-4a71-8fe1-b75fee5ecb91

📥 Commits

Reviewing files that changed from the base of the PR and between 3049234 and e2c3035.

📒 Files selected for processing (2)

• docs/openapi.json
• src/models/responses.py

[tisnik]

LGTM