Skip to content

Add explicit Python Responses API support - #523

Merged
robgruen merged 2 commits into
mainfrom
dev/robgruen/python-responses-518
Nov 10, 2026
Merged

robgruen merged 2 commits into
mainfrom
dev/robgruen/python-responses-518

Conversation

@robgruen

@robgruen robgruen commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Add backward-compatible, explicitly selected Python Responses API support through the built-in HTTP factories and application-owned asynchronous clients.

  • Add keyword-only use_responses_api=True selection across all four model factories, complete HTTP destination validation, and explicit model/deployment pass-through.
  • Export a structural ResponsesClient protocol without adding SDK dependencies; keep Chat-only clients and existing Chat Completions defaults usable unchanged.
  • Share canonical Responses parsing for HTTP mappings and client objects. Concatenate completed assistant text in order and explicitly reject malformed, refused, blocked, incomplete, nonterminal, or unsupported output, even alongside partial text.
  • Preserve HTTP authentication, per-attempt token providers, retries, timeouts, response-size limits, schema validation, and bounded repair. Keep configured-client transport controls and lifecycle caller-owned.
  • Add deterministic regressions, API documentation, and a minimal runnable HTTP/client example.

Relates to #518. Builds on the merged authentication/client work in #516, with #305 and #519 as TypeScript prior art.

Owner-directed scope

The owner chose to deliver explicit Responses support now and defer automatic Responses-to-Chat fallback. This PR adds no fallback flag, capability inference, endpoint rewriting, or failover requests. It does not claim to satisfy the original P4 fallback discovery/evidence criteria or rewrite the existing acceptance record.

Integration with merged #524

Merged approved main at c2215ed into this branch, preserving both histories, in commit 38a9aa5.

  • The shared public text/image prompt types now work with both HTTP and configured-client Responses paths. User/system text maps to input_text, assistant text to output_text, and image references to flat input_image parts. Exact references, optional detail, ordering, and caller-owned data are preserved.
  • The common prompt checks reject malformed input before authentication or dispatch. Translator image context survives validation and bounded repair, without changing schema placement or result/failure contracts.
  • Preserve Add Python text and image prompt support #524's configurable Chat Completions temperature (0.0 by default, None to omit). Responses continues omitting temperature regardless of that option; no new provider-specific options or SDK dependencies are added.
  • Updated both Python guides and added combined behavior/static-type regressions. Automatic Responses-to-Chat fallback remains deferred.

Verification of the integrated revision

  • Full Python suite on 3.11.18: 740 passed, 3 Python-version-dependent skips, 19 snapshots passed.
  • Strict Pyright on Node 24.22.1 in the Hatch environment: 0 errors, 0 warnings.
  • git diff --check: passed.
  • Live Azure v1 Responses image verification passed through both the built-in HTTP/token-provider factory and an actual AsyncOpenAI 3.42.1 adapter. Both returned HTTP 200 and schema-validated {"color":"red"} from a synthetic 32x32 PNG supplied as data URLs. Covered mixed text/image ordering, omitted and high image detail, tagged system/assistant text, prompt immutability, and client ownership/cleanup.
  • Live testing caught an assistant-text wire-format mismatch: assistant parts require output_text, not input_text. The correction is now covered by explicit role-specific offline regressions. Integration testing used five dispatches total: three rejected diagnostic requests and two successful final requests. Retries and translator repair were disabled, with a 120-second timeout.
  • The committed tree exactly matches the tested tree. Ordinary regression tests remain offline and need no provider SDK or live credentials. No credentials, account details, or private resource addresses are included here.

Initial verification (before integrating #524)

  • Python 3.11: 226 focused tests and 6 snapshots passed, covering new Responses behavior, existing models/authentication, and translator validation/repair.
  • Strict Pyright on Node 24.22.1 using the Hatch environment: 0 errors, 0 warnings.
  • Both new example paths passed with offline mocked responses; CLI help and git diff --check passed.
  • Live Azure v1 Responses verification passed with Microsoft Entra ID via the owner's existing Azure CLI login:
    • Azure HTTP factory: HTTP 200; validated {"ok": true}.
    • Configured asynchronous HTTP-client adapter: HTTP 200; validated {"ok": true}; caller-owned client remained open.
    • Two model requests total, with retries and repair disabled for the smoke test. The live configured-client test used an HTTP-backed structural client, not a provider SDK; SDK-shaped envelopes are covered offline.

Live verification used synthetic input only. No credentials, identity/account details, or private resource addresses are included in this PR.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 6, 2026 01:06

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the addition of explicitly selected Python Responses API support.

No open issues 🎉

What changed in this PR

Adds explicitly selected Python Responses API support alongside the existing Chat Completions integration, addressing #518 while preserving default behavior. Automatic Responses-to-Chat fallback remains deferred.

Changes:

  • Adds keyword-only Responses selection to all four model factories and exports a dependency-free ResponsesClient protocol.
  • Shares canonical output validation across HTTP and configured-client paths while retaining transport safeguards, client ownership, and translator validation/repair.
  • Adds deterministic regression coverage, API documentation, and a minimal HTTP/client example.
File Description
site/​src/​docs/​python/​basic-usage.md Documents selection, endpoints, client ownership, output validation, and limits.
python/​tests/​test_responses_model.py Covers Responses requests, parsing, failures, compatibility, safeguards, and repair.
python/​src/​typechat/​_internal/​model.py Implements explicit Responses mode, client adaptation, and shared parsing.
python/​src/​typechat/​__init__.py Exports the structural ResponsesClient protocol.
python/​README.md Introduces Responses support and links to usage guidance.
python/​examples/​responses/​demo.py Adds a sentiment example for HTTP and application-owned clients.
python/​examples/​README.md Lists the example and documents OpenAI/Azure configuration.

Review effort: Balanced

Integrate merged PR #524 with the explicit Responses API work. Preserve shared prompt validation, image references, repair context, and Chat Completions temperature settings. Map Responses assistant text to output_text, with deterministic and live regression verification.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 6, 2026 21:10

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the addition of explicitly selected Responses API support.

No open issues 🎉

Review effort: Balanced

@robgruen
robgruen merged commit 20613ef into main Nov 10, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants