Streaming: introduce opt-in unified StreamEvent (+ adapters, example, tests)

[lucasalencarxisto-stack]

Summary
This PR introduces an opt-in unified streaming event shape for both responses.stream() and chat.completions.stream():

• Added internal StreamEvent + extract_text helper for consistent DX.
• Created adapters for Responses and Chat Completions (map text deltas + completion events).
• Added a minimal async example under examples/async_stream_unified.py.
• Added basic unit tests for mapping and helper behavior.

Why
Currently the two streaming APIs emit different shapes. A unified, typed surface:

• Simplifies printing incremental text (output_text.delta)
• Standardizes completion signaling (response.completed)
• Sets a foundation to later add tool-calling / error events without changing usage pattern.

Notes

• Backward compatible: existing .stream() behavior is unchanged.
• Example requires a valid API key to run; unit tests run offline.

Follow-ups (planned)

• Wire-in: unified=True flag in .stream() to yield StreamEvent directly.
• Add tool-calling and error events.
• Improve retry/timeout semantics for streaming in a separate PR.

[lucasalencarxisto-stack]

Hi team 👋

I believe this PR is valuable because it addresses a real developer experience gap: today responses.stream() and chat.completions.stream() emit different event shapes, which makes code harder to reuse.

By introducing a unified StreamEvent with a simple helper (extract_text), we get:

• Consistent handling of text deltas and completion signals
• A foundation to later support tool-calling and error events
• A smoother DX without breaking existing behavior

This is opt-in and fully backward-compatible, with basic tests and an example included. I think it can really help developers adopt streaming more easily. 🚀

[RobertCraigie]

Thanks for the PR but this is not something we want to do. The APIs are sufficiently different that it does not make sense to coalesce them.

[lucasalencarxisto-stack]

Thanks for taking the time to review this, Robert — I completely understand your reasoning here.

When you have a chance, could you also take a look at my other open PRs (#2596, #2597, #2615, #2616, #2645)? They’re smaller in scope and more focused on tests/examples. I’d really appreciate your feedback on those.

Thanks again for your guidance!