Document reasoning controls and current model support - #215
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
…ng-level-docs # Conflicts: # docs/cloud/agent/models.mdx
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 98b0d3088b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 13 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/cloud/agent/thinking-levels.mdx">
<violation number="1" location="docs/cloud/agent/thinking-levels.mdx:198">
P2: This new guidance tells users to fall back to the REST examples with `thinkingLevel` in the body, but the linked OpenAPI contracts (v2/v3/v4) don't yet define `thinkingLevel` in their create-request schemas, and V4's `RunCreateRequest` schema sets `additionalProperties: false`. If that's accurate, a schema-validating V4 client would reject this documented request with a 422 before it's even processed. Update the OpenAPI specs/snapshots to include `thinkingLevel` before directing users to REST as the fallback.</violation>
</file>
Tip: instead of fixing issues one by one fix them all with cubic
Re-trigger cubic
sauravpanda
changed the title
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 31b7030282
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
All reported issues were addressed across 20 files (changes from recent commits).
Tip: instead of fixing issues one by one fix them all with cubic
Re-trigger cubic
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6c1b281ca0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "type": "null" | ||
| } | ||
| ], | ||
| "description": "Optional model reasoning depth. Omit this field to preserve the provider default. V3 accepts disabled/low/medium/high for bu-mini, bu-max, bu-ultra, gemini-3-flash, gemini-3.5-flash, claude-sonnet-4.6, claude-opus-4.6, claude-opus-4.7, claude-sonnet-5, claude-opus-4.8, claude-haiku-4.5, gpt-5.2, gpt-5.4-mini, gpt-5.5, gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna; low/medium/high for gpt-5-mini; low/high for gemini-3-pro and gemini-3.1-pro; and disabled/high for glm-5.2. MiniMax M3 rejects an explicit level." |
There was a problem hiding this comment.
When this request dispatches a follow-up by supplying sessionId, omitting thinkingLevel retains the session's previously configured value rather than preserving the provider default; the new guide confirms that only an explicit null clears the setting. This description, duplicated in docs/openapi/v3.json, can therefore cause API-reference users to unintentionally continue using a higher or lower reasoning level. Distinguish new-session omission from follow-up omission here.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
5 issues found across 16 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="snapshots/v4.json">
<violation number="1">
P2: snapshots/v4.json is not synced with the OpenAPI source it mirrors. docs/openapi/v4.json and docs/cloud/openapi/v4.json RunCreateRequest both expose modelParams, default gpt-5.6-luna, and an 18-model enum, while this snapshot omits modelParams, reverts the default to minimax-m3, and drops claude-opus-5, gpt-5.6-sol/terra/luna, and gemini-3.6-flash. This contradicts the PR's stated goal and validation that all OpenAPI snapshot/reference copies are semantically identical, and would regenerate SDK types that disagree with the API contract. Please regenerate the snapshot from the updated openapi so the copies stay in sync.</violation>
</file>
<file name="snapshots/v3.json">
<violation number="1">
P2: This change trims the V3 snapshot's BuModel enum from 22 models to 8 and deletes the thinkingLevel field from SessionResponse/RunTaskRequest and the ThinkingLevel schema, which leaves snapshots/v3.json out of sync with the reference docs/cloud/openapi/v3.json and docs/openapi/v3.json that this same PR updates (those keep all 22 models and expose camelCase thinkingLevel for V3). Since the PR claims snapshot/reference copies are semantically identical and aims to document normalized V2/V3 thinkingLevel support, the V3 snapshot dropping thinkingLevel contradicts the stated goal; confirm whether the snapshot was meant to reflect a frozen SDK generation, and if not, keep the enumeration and thinkingLevel aligned with the reference V3 contract.</violation>
</file>
<file name="snapshots/v2.json">
<violation number="1">
P2: The SupportedLLMs enum update in snapshots/v2.json was not applied to the published reference copies (docs/openapi/v2.json, docs/cloud/openapi/v2.json), which still list the removed models (gpt-5.5/gpt-5.6-*, gemini-3.5-flash, claude-sonnet-5, claude-opus-4-8/5, glm-5.2, minimax-m3) and lack claude-sonnet-4-6. This contradicts the claimed snapshot/reference sync; regenerate or hand-sync the reference copies so the enums match.</violation>
<violation number="2">
P2: Removing thinkingLevel from snapshots/v2.json breaks sync with the published references and contradicts the PR's own assertion that V2 exposes ThinkingLevel. Since the v2 SDK is generated 1:1 from this snapshot, the generated client would silently drop the thinkingLevel field/type while the docs still advertise it. Restore the field and ThinkingLevel schema in the snapshot to match docs/openapi/v2.json.</violation>
</file>
<file name="docs/cloud/openapi/v3.json">
<violation number="1" location="docs/cloud/openapi/v3.json:5365">
P2: The updated `thinkingLevel` description states that omitting the field 'preserves the provider default,' but this is only true for a new session. When `sessionId` is supplied to continue an existing session, omitting `thinkingLevel` actually retains the session's previously configured reasoning level, not the provider default; only an explicit `null` clears it. Consider clarifying this distinction so API-reference users don't unintentionally keep a previously set high/low reasoning level on follow-up requests.</violation>
</file>
Tip: instead of fixing issues one by one fix them all with cubic
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
| "type": "null" | ||
| } | ||
| ], | ||
| "description": "Optional model reasoning depth. Omit this field to preserve the provider default. V3 accepts disabled/low/medium/high for bu-mini, bu-max, bu-ultra, gemini-3-flash, gemini-3.5-flash, claude-sonnet-4.6, claude-opus-4.6, claude-opus-4.7, claude-sonnet-5, claude-opus-4.8, claude-haiku-4.5, gpt-5.2, gpt-5.4-mini, gpt-5.5, gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna; low/medium/high for gpt-5-mini; low/high for gemini-3-pro and gemini-3.1-pro; and disabled/high for glm-5.2. MiniMax M3 rejects an explicit level." |
There was a problem hiding this comment.
P2: The updated thinkingLevel description states that omitting the field 'preserves the provider default,' but this is only true for a new session. When sessionId is supplied to continue an existing session, omitting thinkingLevel actually retains the session's previously configured reasoning level, not the provider default; only an explicit null clears it. Consider clarifying this distinction so API-reference users don't unintentionally keep a previously set high/low reasoning level on follow-up requests.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/cloud/openapi/v3.json, line 5365:
<comment>The updated `thinkingLevel` description states that omitting the field 'preserves the provider default,' but this is only true for a new session. When `sessionId` is supplied to continue an existing session, omitting `thinkingLevel` actually retains the session's previously configured reasoning level, not the provider default; only an explicit `null` clears it. Consider clarifying this distinction so API-reference users don't unintentionally keep a previously set high/low reasoning level on follow-up requests.</comment>
<file context>
@@ -5362,7 +5362,7 @@
}
],
- "description": "Optional model reasoning depth. Omit this field to preserve the model provider default. Supported values depend on the selected model: most supported Claude models and GPT-5.1+ models support disabled/low/medium/high; Gemini Flash models support all four (disabled maps to Gemini's minimal level); Claude Fable 5, earlier GPT-5 models, Gemini 2.5 Pro, o3/o4, and Grok support low/medium/high; Gemini 3.1 Pro supports low/high; GLM supports disabled/high. Unsupported model/level combinations are rejected."
+ "description": "Optional model reasoning depth. Omit this field to preserve the provider default. V3 accepts disabled/low/medium/high for bu-mini, bu-max, bu-ultra, gemini-3-flash, gemini-3.5-flash, claude-sonnet-4.6, claude-opus-4.6, claude-opus-4.7, claude-sonnet-5, claude-opus-4.8, claude-haiku-4.5, gpt-5.2, gpt-5.4-mini, gpt-5.5, gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna; low/medium/high for gpt-5-mini; low/high for gemini-3-pro and gemini-3.1-pro; and disabled/high for glm-5.2. MiniMax M3 rejects an explicit level."
},
"sessionId": {
</file context>
1 participant
Summary
modelParamsthinkingLevelsupport and wire namingllms-full.txtWhy
The model picker and generated API references were behind the current backend contracts. The first version of this PR also treated
thinkingLevelas a V4 field, but V4 intentionally uses provider-nativemodelParams; this update makes the guide, published schemas, and examples agree with the production API.SDK status
The generated TypeScript and Python clients are not regenerated in this PR. Their snapshots remain at the last generated baseline so the separate SDK PR will detect the pending V2/V3
thinkingLevel, V4modelParams, model-enum, and default changes. The docs explicitly direct users to REST where current generated types lag.Validation
jqThinkingLeveland V4 exposesmodelParamsorigin/mainllms.txtandllms-full.txtbash -n docs/generate-llms-txt.shgit diff --checkSummary by cubic
Documents configurable reasoning across V2/V3/V4 and sets
gpt-5.6-lunaas the V4 default. Updates OpenAPI schemas, examples, and LLM context files, and clarifies SDK typing limits and BYOK behavior.Documentation
modelParams(defaults and opt‑out), normalized V2/V3thinkingLevelmatrices, provider mappings, follow‑up behavior, BYOK, validation errors, and REST examples.gpt-5.6-luna, add “All supported V4 model IDs,” link to Thinking levels from V2/V3/V4 overviews and API reference, update FAQ to recommendgpt-5.6-luna, and clarify legacythinkingvsthinkingLeveland BYOK plans.llms.txt/llms-full.txtwith new links and examples; update the generator to convert Card components to links; add SDK caveat that some models and V4modelParamsmay require callingPOST /api/v4/runsdirectly until the SDK is regenerated.OpenAPI
gpt-5.6-luna, addmodelParamspassthrough, and expand model enum.thinkingLevelto request/response schemas and expand model enums.Written for commit 6c1b281. Summary will update on new commits.