Giles Odigwe
b2a2fcbd87
* Python: Fix reasoning content parsing in OpenAIChatCompletionClient Fix two issues with reasoning content handling in the Chat Completions client: 1. (#6979) reasoning_details plaintext buried as encrypted data: The client dumped the entire reasoning_details array into Content.protected_data without setting Content.text, causing AG-UI to emit ReasoningEncryptedValueEvent instead of visible ReasoningMessageContentEvent for plaintext reasoning providers (e.g. OpenRouter). Now extracts readable text from reasoning_details entries into Content.text while preserving protected_data for round-trip fidelity. 2. (#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 downstream. Now detects list content and parses thinking chunks as Content.from_text_reasoning and text chunks as Content.from_text. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix pyright strict-mode type errors and handle content-as-string shape - Use cast() for proper type narrowing in _extract_reasoning_text and _parse_chunked_content to satisfy pyright strict mode - Handle {"content": "..."} string shape in _extract_reasoning_text (addresses review comment about missing format coverage) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix mypy errors: cast list content to Any in tests model_construct bypasses Pydantic runtime validation but mypy still checks declared types. Use cast(Any, ...) for the list content args. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address review comments: summary field, reasoning field, and round-trip - Add 'summary' field extraction in _extract_reasoning_text for reasoning.summary entries from OpenRouter - Handle message.reasoning and message.reasoning_content top-level fields (plaintext reasoning without reasoning_details) in both streaming and non-streaming paths - reasoning_details takes priority when both fields are present - Preserve original Mistral chunk list in additional_properties ('_source_content_list') so _prepare_message_for_openai can reconstruct the structured list content for multi-turn reasoning - Add 5 new tests covering all new behaviors Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix ruff used-dummy-variable: rename _skip_structured_siblings Remove leading underscore from _skip_structured_siblings variable since it is accessed (not a dummy variable). Ruff's used-dummy-variable rule flags variables with leading underscores that are read. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix missing newline at end of test file Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address review: type-agnostic chunk round-trip and reasoning field echo-back - Honor the _source_content_list marker regardless of the first emitted content's type by handling it before the type match, so a chunk list beginning with a text chunk still round-trips as one structured message (addresses github-actions review comment on results[0]). - Tag every chunked-content item with a shared _structured_content_group id and skip only exact group siblings during serialization, instead of suppressing all later text/reasoning content. - Record provenance of top-level reasoning/reasoning_content fields in _reasoning_source_field and echo the value back under the same key on the next request, which providers such as vLLM require (addresses Kimahriman review comment). Replaces the prior behavior that replayed surfaced reasoning as visible answer text. - Factor the duplicated reasoning parsing into _parse_reasoning_content. - Add tests for provenance capture, reasoning/reasoning_content round-trip, reasoning-only messages, text-first chunk round-trip, and unrelated sibling preservation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5 * Replace provider-specific reasoning logic with configurable parse/prepare hooks Following review feedback (#7028), keep OpenAIChatCompletionClient free of provider-specific quirks for 'almost OpenAI-compatible' endpoints. Instead of branching in core for OpenRouter/vLLM/Mistral, expose two optional callables so callers adapt the client themselves: - response_parser (OpenAIChatResponseContentsParser): post-processes the Content list parsed from each response choice/streaming delta, to surface non-standard fields (e.g. reasoning/reasoning_content/reasoning_details) for display. - message_preparer (OpenAIChatMessagePreparer): post-processes the outgoing request message dicts built from each framework Message, to echo provider-specific fields back on later turns (e.g. vLLM reasoning) for multi-turn continuity. Both default to None (no-op; byte-identical stock OpenAI behavior). This reverts the provider-specific reasoning/chunked-content parsing and round-trip markers previously added to core; Mistral chunked content is now handled by agent-framework-mistral. - Add the two callables to RawOpenAIChatCompletionClient / OpenAIChatCompletionClient constructors and invoke them at the parse and prepare seams. - Export the type aliases from the package and the core lazy openai namespace (+ .pyi). - Replace the removed-behavior tests with tests for the two hooks. - Document the hooks in packages/openai/AGENTS.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5 * Skip non-string content in default text parsing Structured list content (e.g. Mistral reasoning models returning content as a list of chunks) was wrapped verbatim into a text Content, producing a malformed Content whose text is a list that crashes downstream (issue #6978). Default text parsing now skips non-string content so a configured response_parser receives a clean slate to expand it. Applies to both streaming and non-streaming paths. Add tests for the skip and for a response_parser expanding chunked content. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5 * Address review: hook signature, per-role preparer, robust round-trip - response_parser now receives the already-selected ChatCompletionMessage / ChoiceDelta instead of Choice | ChunkChoice, so callers no longer duplicate the streaming dispatch (removes the Any/hasattr pattern from tests). The client owns the dispatch; parsers read provider fields directly. - message_preparer now runs once per Message for every role: the build logic moved to _build_openai_messages and the hook is applied at a single exit point in _prepare_message_for_openai, so system/developer messages no longer bypass it. - Round-trip example/test now correlates surfaced reasoning via an additional_properties marker on message.contents with bounded, order-aware, one-to-one dict removal, instead of fragile request-string matching. Adds a test proving an answer whose text equals the reasoning text is no longer dropped. - Update packages/openai/AGENTS.md for the new parser signature and guidance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5 --------- Co-authored-by: Copilot <copilot@github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5
68 lines
4.0 KiB
Markdown
68 lines
4.0 KiB
Markdown
# AGENTS.md — agent-framework-openai
|
|
|
|
OpenAI integration package for Agent Framework. Contains OpenAI Responses API and Chat Completions API clients.
|
|
|
|
## Package Structure
|
|
|
|
```
|
|
agent_framework_openai/
|
|
├── __init__.py # Public API exports
|
|
├── _chat_client.py # OpenAIChatClient (Responses API) + RawOpenAIChatClient
|
|
├── _chat_completion_client.py # OpenAIChatCompletionClient (Chat Completions API) + RawOpenAIChatCompletionClient
|
|
├── _embedding_client.py # OpenAIEmbeddingClient
|
|
├── _exceptions.py # OpenAI-specific exceptions
|
|
└── _shared.py # OpenAISettings and shared config helpers
|
|
```
|
|
|
|
## Key Classes
|
|
|
|
| Class | API | Status |
|
|
|---|---|---|
|
|
| `OpenAIChatClient` | Responses API | Primary |
|
|
| `OpenAIChatCompletionClient` | Chat Completions API | Primary |
|
|
| `OpenAIEmbeddingClient` | Embeddings API | Primary |
|
|
|
|
All clients follow the Raw + Full-Featured pattern (e.g., `RawOpenAIChatClient` + `OpenAIChatClient`).
|
|
|
|
For Responses API continuation with service-side storage, a prior hosted
|
|
`function_approval_request` is server-issued and must not be replayed inline, while the new hosted
|
|
`function_approval_response` is serialized as `mcp_approval_response` so the user's approved or rejected decision
|
|
reaches the service. Local `FunctionTool` approval controls are resolved in-process and must not be serialized as MCP
|
|
items. An approval is hosted when its function call carries a `server_label` in
|
|
`function_call.additional_properties`; approvals without that metadata are local. Applications that manually replay
|
|
message history must not send that same hosted approval response again on later turns.
|
|
|
|
The generic OpenAI clients support both OpenAI and Azure OpenAI routing. Precedence is:
|
|
explicit Azure inputs (`credential`, `azure_endpoint`, `api_version`) → OpenAI API key
|
|
(`OPENAI_API_KEY`) → Azure environment fallback (`AZURE_OPENAI_*`).
|
|
|
|
## Adapting the Chat Completions client to OpenAI-compatible endpoints
|
|
|
|
`OpenAIChatCompletionClient` targets the OpenAI Chat Completions wire format and is intentionally
|
|
kept free of provider-specific quirks. Many "OpenAI-compatible" providers (OpenRouter, vLLM,
|
|
Mistral, DeepSeek, Ollama, …) diverge on the edges — e.g. returning reasoning under
|
|
`reasoning` / `reasoning_content` / `reasoning_details`, or `content` as a list of chunks. Rather
|
|
than branching in core, the client exposes two optional callables so callers adapt it themselves:
|
|
|
|
- `response_parser: OpenAIChatResponseContentsParser` — `(message_or_delta, default_contents) -> contents`.
|
|
Post-processes the `Content` items parsed from each response choice. Receives the already-selected
|
|
`ChatCompletionMessage` (non-streaming) or `ChoiceDelta` (streaming) — the client resolves the
|
|
dispatch — so a parser reads provider fields directly (e.g. `getattr(msg, "reasoning", None)`) without
|
|
branching. Use it to surface non-standard fields for display. Applied per choice in both paths.
|
|
- `message_preparer: OpenAIChatMessagePreparer` — `(message, default_dicts) -> dicts`. Post-processes
|
|
the outgoing request message dicts built from each framework `Message` (called once per `Message`, for
|
|
every role including `system`/`developer`). Use it to echo provider-specific fields (e.g. vLLM
|
|
`reasoning`) back on later turns for multi-turn continuity. To correlate a surfaced-reasoning `Content`
|
|
with the dict the default serializer emitted for it, tag the `Content` via `additional_properties` in
|
|
the parser and match against `message.contents` rather than raw request-string matching.
|
|
|
|
Both default to `None` (no-op → byte-identical stock OpenAI behavior) and are constructor args on
|
|
`RawOpenAIChatCompletionClient` / `OpenAIChatCompletionClient`. Provider round-trips generally need
|
|
**both**: the parser surfaces the field for display, the preparer sends it back. Prefer a dedicated
|
|
client (e.g. `agent-framework-mistral`) when an endpoint diverges substantially.
|
|
|
|
## Dependencies
|
|
|
|
- `agent-framework-core` — core abstractions
|
|
- `openai` — OpenAI Python SDK
|