feat(gateway): add verbosity param for gpt-5.6 models

[steebchen]

Summary

Adds support for OpenAI's new verbosity parameter (low / medium / high) for the GPT-5.6 model family (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna), controlling how detailed model responses are.

Changes

• Request schemas: accept top-level verbosity on /v1/chat/completions and text.verbosity on /v1/responses (mirroring OpenAI's shapes for each API).
• Capability gating: new verbosity?: boolean flag on provider mappings; validateModelCapabilities returns a 400 when verbosity is sent to a model without support (skipped for auto/custom, matching reasoning_effort behavior).
• Forwarding (prepareRequestBody): sent as text.verbosity on the Responses API (merged with text.format when response_format is also set) and as top-level verbosity on Chat Completions. Stripped when auto routing or retry fallback lands on a mapping without support, so an unknown param is never forwarded upstream.
• Model catalog: verbosity: true + "verbosity" in supportedParameters on all three gpt-5.6 OpenAI mappings.

Testing

• Unit tests: forwarding for both API shapes, coexistence with response_format, stripping for unsupported models, and capability validation (139 tests pass across the two touched spec files; full pnpm test:unit has one pre-existing, unrelated google-vertex routing failure that also fails on a clean tree).
• Scoped e2e: TEST_MODELS="openai/gpt-5.6-luna" pnpm test:e2e — 85 passed.
• Live verification through a local gateway against the real OpenAI API:
  • verbosity: "low" vs "high" on the same prompt produced 299 vs 20,069 chars of output, confirming upstream honors the forwarded value.
  • gpt-4o + verbosity → clean 400 with actionable message.
  • /v1/responses with text.verbosity → works.
• pnpm format and full pnpm build pass.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added optional low, medium, or high verbosity controls to Chat Completions and Responses API requests.
  • Forwarded verbosity settings for supported GPT-5.6 models across chat and Responses API requests.
  • Added validation with clear errors when verbosity is requested for unsupported models.
  • Preserved verbosity alongside response formatting options.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: de9e1041-7ecc-472e-9199-617ce8a1be03

📥 Commits

Reviewing files that changed from the base of the PR and between 2c63fea and ae181fe.

📒 Files selected for processing (11)

• apps/gateway/src/chat/chat.ts
• apps/gateway/src/chat/schemas/completions.ts
• apps/gateway/src/chat/tools/resolve-provider-context.ts
• apps/gateway/src/chat/tools/validate-model-capabilities.spec.ts
• apps/gateway/src/chat/tools/validate-model-capabilities.ts
• apps/gateway/src/responses/responses.ts
• packages/actions/src/prepare-request-body.spec.ts
• packages/actions/src/prepare-request-body.ts
• packages/models/src/models.ts
• packages/models/src/models/openai.ts
• packages/models/src/types.ts

---

Walkthrough

The gateway accepts an optional verbosity setting, validates model support, propagates it through chat and Responses API flows, and includes it in supported OpenAI request formats. GPT-5.6 model mappings declare support, while unsupported models omit the parameter.

Changes

Verbosity support

Layer / File(s)	Summary
Request and model contracts apps/gateway/src/chat/schemas/completions.ts, packages/models/src/types.ts, packages/models/src/models.ts, packages/models/src/models/openai.ts	Request and provider types define verbosity values, and the GPT-5.6 model mappings declare verbosity support.
Capability validation and chat ingress apps/gateway/src/chat/tools/validate-model-capabilities.ts, apps/gateway/src/chat/tools/validate-model-capabilities.spec.ts, apps/gateway/src/chat/chat.ts	Chat requests extract and validate verbosity, rejecting unsupported fixed models while skipping checks for automatic and custom models.
API and provider-context propagation apps/gateway/src/responses/responses.ts, apps/gateway/src/chat/tools/resolve-provider-context.ts, apps/gateway/src/chat/chat.ts, packages/actions/src/prepare-request-body.spec.ts	Responses requests and retry/provider-context processing forward verbosity into request preparation.
Provider request construction and coverage packages/actions/src/prepare-request-body.ts, packages/actions/src/prepare-request-body.spec.ts	Supported providers receive verbosity in chat or Responses payloads; unsupported models have it removed, with tests covering formatting combinations.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant ResponsesAPI
  participant ChatCompletions
  participant CapabilityValidator
  participant RequestPreparer
  participant OpenAI
  Client->>ResponsesAPI: send text.verbosity
  ResponsesAPI->>ChatCompletions: set chatRequest.verbosity
  ChatCompletions->>CapabilityValidator: validate model capability
  CapabilityValidator-->>ChatCompletions: accept or HTTP 400
  ChatCompletions->>RequestPreparer: prepare verbosity request
  RequestPreparer->>OpenAI: send supported verbosity payload

Loading

Possibly related PRs

• theopenco/llmgateway#1571: Updates the same centralized model capability validation used by this change.
• theopenco/llmgateway#1651: Modifies shared provider-context and retry plumbing extended here for verbosity.
• theopenco/llmgateway#2433: Extends the same shared chat request and request-body propagation path.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding the verbosity parameter support for GPT-5.6 models in the gateway.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch gpt-5-6-verbosity-field

---

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.}