Python: Fix reasoning content parsing in OpenAIChatCompletionClient

[giles17]

Motivation and Context

Fixes #6978 and #6979.

Two related bugs in OpenAIChatCompletionClient prevent reasoning content from being displayed correctly:

1. Python: [Bug]: OpenAI Chat Completions client buries plaintext reasoning_details as encrypted data #6979 - Plaintext reasoning buried as encrypted data: The client dumps the entire reasoning_details array into Content.protected_data without setting Content.text. Downstream, AG-UI emits ReasoningEncryptedValueEvent (opaque) instead of visible ReasoningMessageContentEvent for providers like OpenRouter that send plaintext reasoning.

2. Python: [Bug]: OpenAI Chat Completions client crashes on (and drops) Mistral reasoning content chunks #6978 - Mistral list content causes crash: Mistral reasoning models return content as a list of typed chunks ([{"type": "thinking", ...}, {"type": "text", ...}]) instead of a plain string. _parse_text_from_openai assumed content was always a string, causing a Pydantic ValidationError crash in AG-UI.

Changes

_chat_completion_client.py

• _extract_reasoning_text() helper (module-level): Extracts readable text from various reasoning_details formats (list of dicts with text keys, dict with content list, plain strings). Returns None for genuinely encrypted/opaque data.
• Updated reasoning_details handling (lines 753-757, 799-803): Now passes extracted plaintext as Content.text while preserving the full JSON in protected_data for round-trip fidelity.
• Refactored _parse_text_from_openai(): Returns list[Content] instead of Content | None. Detects when message.content is a list and delegates to _parse_chunked_content().
• _parse_chunked_content() static method: Parses Mistral-style thinking chunks → Content.from_text_reasoning and text chunks → Content.from_text.

Tests

• test_parse_reasoning_details_extracts_plaintext — verifies plaintext extraction from OpenRouter-style reasoning_details
• test_parse_reasoning_details_extracts_plaintext_streaming — same for streaming path
• test_parse_mistral_chunked_content_from_response — verifies Mistral list content parsing (non-streaming)
• test_parse_mistral_chunked_content_streaming — verifies Mistral list content parsing (streaming)
• test_parse_plain_string_content_still_works — regression test for normal string content

Validation

• All 79 tests in test_openai_chat_completion_client.py pass (including 6 new tests)
• All pre-existing reasoning round-trip tests continue to pass
• No changes to the Responses API client (_chat_client.py) which already handles reasoning correctly

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 75% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Failure Modes, Design Approach

---

Automated review by giles17's agents

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/openai/agent_framework_openai
_chat_completion_client.py	428	25	94%	113, 119, 131, 140, 147, 488, 584–585, 589, 834, 836, 841, 844, 879, 893, 978, 980, 997, 1018, 1026, 1050, 1063, 1087, 1107, 1422
TOTAL	44153	5277	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
8838	33 💤	0 ❌	0 🔥	2m 23s ⏱️

[Copilot]

Pull request overview

This PR fixes parsing of “reasoning” outputs in the Python OpenAIChatCompletionClient so downstream consumers (notably AG-UI) can display plaintext reasoning correctly and avoid crashes when providers return structured chunked content.

Changes:

• Add _extract_reasoning_text() and use it to populate Content.text for plaintext reasoning_details while preserving full payload round-tripped in protected_data.
• Refactor _parse_text_from_openai() to return list[Content] and introduce _parse_chunked_content() to handle Mistral-style content: [...] chunks (thinking + text).
• Add regression tests covering plaintext reasoning_details extraction and chunked list-content parsing in both streaming and non-streaming paths.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
python/packages/openai/agent_framework_openai/_chat_completion_client.py	Adds plaintext reasoning extraction + chunked content parsing; updates response parsing to emit correct Content items.
python/packages/openai/tests/openai/test_openai_chat_completion_client.py	Adds tests for plaintext reasoning extraction and Mistral chunked content in both streaming and non-streaming modes.

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 70% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Failure Modes, Design Approach

---

Automated review by giles17's agents

[moonbox3]

Should visible reasoning normalization cover the other documented OpenRouter plaintext forms here? reasoning.summary entries put the displayable value under summary, while raw-reasoning models return message.reasoning (or reasoning_content) without reasoning_details; on this head the first becomes text=None and the second is discarded entirely. Could we normalize those fields in both streaming and non-streaming paths so the fix covers the provider's supported response shapes?

[moonbox3]

Should we preserve the original structured assistant content for the next turn? Converting the ThinkChunk here and the text chunk below into separate framework contents makes _prepare_message_for_openai() replay them as two plain assistant messages, so the original [{"type":"thinking", ...}, {"type":"text", ...}] is lost. Mistral requires the complete assistant message, including the ThinkChunk, for multi-turn reasoning and tool continuation; could we retain or reconstruct that list so it round-trips as one message?