[cinconueves]

• Addresses Feature Request: Allow configuring reasoning behavior (e.g. disable reasoning) for LLM calls #2612
• Adds a reasoning effort config var support, passes that along to the OpenAI call.
• Add edge case handling for reasoning models that might return the response in the reasoning field.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d77a5839-96bd-4497-8084-79f0c29f8333

📥 Commits

Reviewing files that changed from the base of the PR and between 8ca2e8d and cc30f24.

📒 Files selected for processing (1)

• packages/shared/inference.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/shared/inference.ts

---

Walkthrough

Adds an OpenAI reasoning-effort option end-to-end: documents a new env var, extends shared config parsing, forwards the value into the OpenAI inference client and request payload, and surfaces the option in the compare-models tool. (<=50 words)

Changes

Cohort / File(s)	Summary
Documentation docs/docs/03-configuration/01-environment-variables.md	Added OPENAI_REASONING_EFFORT row with allowed values (none, minimal, low, medium, high, xhigh) and default shown as "Not set". Cosmetic spacing adjustment in table header.
Shared config packages/shared/config.ts	Added parsing/validation for OPENAI_REASONING_EFFORT and propagated it into the transformed serverConfigSchema as inference.openAIReasoningEffort.
Inference client / types packages/shared/inference.ts	Extended OpenAIInferenceConfig with optional reasoningEffort; forwarded serverConfig.inference.openAIReasoningEffort when constructing the client; included reasoning_effort in the chat.completions.create payload; adjusted response extraction to use message.content or fall back to message.reasoning.
Compare-models tool tools/compare-models/src/config.ts, tools/compare-models/src/inferenceClient.ts	Added INFERENCE_REASONING_EFFORT to env schema/validation and passed it into createInferenceClient as reasoningEffort. Minor reindent/transform tweaks in envSchema (including INFERENCE_USE_MAX_COMPLETION_TOKENS and INFERENCE_CONTEXT_LENGTH).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: add openai service tier configuration option #2339: Adds a new OpenAI inference config/env var and wires it through the same shared config and inference client code paths.

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is incomplete. It addresses the issue and describes the feature, but lacks the required sections: 'How Has This Been Tested?', checklist items, and explanation of LLM usage.	Add the 'How Has This Been Tested?' section with test details, complete the checklist, and explain any LLM involvement in creating the PR.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding support for configuring OpenAI reasoning effort, which is directly reflected in the changeset across configuration, documentation, and implementation files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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 and usage tips.}

[greptile-apps]

Greptile Summary

This PR adds support for configuring OPENAI_REASONING_EFFORT and handles the edge case where some OpenRouter-compatible reasoning models return their answer in a reasoning field rather than content. There are two P1 issues that need to be resolved before merging:

• OPENAI_REASONING_EFFORT in packages/shared/config.ts has no .default("none"), making it a required env var and silently breaking all existing deployments on startup.
• The OpenAIInferenceConfig interface defines "minimum" as a valid effort level, but that value is absent from both the Zod enum and the docs (which list "minimal" instead), creating an unreachable and misleading type.

Confidence Score: 3/5

Not safe to merge — missing default will break all existing deployments on startup.

Two P1 defects: a missing .default("none") that makes OPENAI_REASONING_EFFORT required (causing immediate startup failures for any deployment not yet setting the var), and a type inconsistency where "minimum" in the interface can never be reached from config.

packages/shared/config.ts and packages/shared/inference.ts require fixes before merging.

Important Files Changed

Filename	Overview
packages/shared/config.ts	Adds OPENAI_REASONING_EFFORT to the env schema but omits .default("none"), making it a required field that will break existing deployments missing the env var.
packages/shared/inference.ts	Wires reasoning_effort into inferFromText; contains an unreachable "minimum" value in the interface that doesn't exist in the config enum, and unconditionally sends reasoning_effort (including the invalid "none" value) to every model.
docs/docs/03-configuration/01-environment-variables.md	Documents OPENAI_REASONING_EFFORT but lists "minimal" as a valid option that doesn't exist in the config enum, causing a misleading user-facing error.
tools/compare-models/src/config.ts	Adds INFERENCE_REASONING_EFFORT with default "none"; incidentally changes .prefault to .default for INFERENCE_USE_MAX_COMPLETION_TOKENS (functionally equivalent here).
tools/compare-models/src/inferenceClient.ts	Passes reasoningEffort from local config into the OpenAIInferenceClient constructor; straightforward and correct.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: packages/shared/config.ts
Line: 64

Comment:
**Missing default breaks existing deployments**

`OPENAI_REASONING_EFFORT` has no `.default("none")` and is not `.optional()`, making it a required env var. Any existing deployment that hasn't set this variable will fail to start with a Zod validation error. The docs say the default is `none`, but the schema doesn't reflect that.

```suggestion
  OPENAI_REASONING_EFFORT: z.enum(["none", "low", "medium", "high", "xhigh"]).default("none"),
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: packages/shared/inference.ts
Line: 65

Comment:
**`"minimum"` is unreachable and inconsistent with docs**

The interface includes `"minimum"` as a valid value, but `config.ts` only accepts `["none", "low", "medium", "high", "xhigh"]`. `"minimum"` can never arrive here from config. Additionally, the documentation entry lists `minimal` (not `minimum`), introducing a three-way inconsistency. Either `"minimal"` should be added to the config enum and docs corrected to match, or `"minimum"` should be dropped from the interface.

```suggestion
  reasoningEffort: "none" | "low" | "medium" | "high" | "xhigh";
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: packages/shared/inference.ts
Line: 129-130

Comment:
**`reasoning_effort` sent unconditionally to all models**

`reasoning_effort` is always included in every `inferFromText` request, even when the model doesn't support it. Many third-party OpenAI-compatible providers will return a 400 on an unknown field. Additionally, `"none"` is not a valid `ReasoningEffort` value per the OpenAI SDK — the `as ReasoningEffort` cast silently bypasses that constraint. Consider omitting the parameter when effort is `"none"`:

```ts
...(this.config.reasoningEffort && this.config.reasoningEffort !== "none"
  ? { reasoning_effort: this.config.reasoningEffort as ReasoningEffort }
  : {}),
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: docs/docs/03-configuration/01-environment-variables.md
Line: 100

Comment:
**Docs list `minimal` but config enum doesn't include it**

The documentation lists `minimal` as a valid option, but the Zod enum in `config.ts` only accepts `["none", "low", "medium", "high", "xhigh"]`. Users setting `OPENAI_REASONING_EFFORT=minimal` will get a startup validation error.

```suggestion
| OPENAI_REASONING_EFFORT              | No       | none                   | Set to `none`, `low`, `medium`, `high` or `xhigh`. Controls the reasoning effort in reasoning models. See [OpenAI: How Reasoning Works](https://developers.openai.com/api/docs/guides/reasoning#how-reasoning-works)                                                                                                                                                       |
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "Add support for configuring OpenAI reaso..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 6

🧹 Nitpick comments (1)

packages/shared/inference.ts (1)

154-162: Reasoning-field fallback: consider guarding against non-string values.

The fallback to message.reasoning is a pragmatic workaround for OpenRouter models, but since this is a non-standard field, some providers return it as an object (e.g., { content, summary }) rather than a string. If that happens, response would flow through as a non-string and the caller (JSON.parse(response.response)) would throw a confusing error. Consider coercing/validating to string before returning.

-    const response =
-      chatCompletion.choices[0].message.content ||
-      // `@ts-expect-error`: important: Some OpenRouter models might return the response in reasoning field yet the OpenAI API ChatCompletion type doesn't have this as a valid field.
-      chatCompletion.choices[0].message.reasoning;
+    const msg = chatCompletion.choices[0].message;
+    // `@ts-expect-error`: Some OpenRouter models return the answer in a non-standard `reasoning` field.
+    const reasoningField: unknown = msg.reasoning;
+    const response =
+      msg.content ||
+      (typeof reasoningField === "string" ? reasoningField : undefined);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/shared/inference.ts` around lines 154 - 162, The fallback that
assigns chatCompletion.choices[0].message.reasoning to response can yield
non-string values (e.g., objects), causing downstream JSON.parse calls to fail;
update the logic around the response variable in this module to validate and
coerce to a string: if message.content is not present, check message.reasoning
and if it's a string use it, if it's an object prefer reasoning.content or
reasoning.response fields, else JSON.stringify(reasoning) before assigning to
response (and keep the existing error throw if no usable value found). Ensure
you update references to chatCompletion, choices, message.reasoning and the
response variable accordingly so callers (e.g., the
JSON.parse(response.response) usage) always receive a string.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/docs/03-configuration/01-environment-variables.md`:
- Line 100: The docs, Zod enum and TS type disagree on the reasoning-effort
values: align OPENAI_REASONING_EFFORT (docs), the Zod enum in
packages/shared/config.ts, and OpenAIInferenceConfig.reasoningEffort in
packages/shared/inference.ts to the same canonical set of strings (choose either
OpenAI's ReasoningEffort values or your internal expanded set), and update the
docs to match that chosen spelling (e.g., "minimum" vs "minimal"). If you keep
internal-only values like "none" or "xhigh", add explicit mapping in
inference.ts (the request preparation / mapping logic around the existing
mapping comments) to convert them to the OpenAI ReasoningEffort values (or omit
the field when "none") before sending to the API so runtime validation and the
API client agree. Ensure the Zod enum, OpenAIInferenceConfig.reasoningEffort
type, and the README entry for OPENAI_REASONING_EFFORT all use the exact same
strings.

In `@packages/shared/config.ts`:
- Line 64: OPENAI_REASONING_EFFORT is currently required and missing
documented/typed values; make it optional with a default of "none" and reconcile
the allowed literals across schema, type, and docs: update the z.enum for
OPENAI_REASONING_EFFORT to include the full agreed set of literals (add the
missing reasoning value(s) documented/typed — e.g., "minimal" vs "minimum") and
call .optional().default("none") on it, then change
OpenAIInferenceConfig.reasoningEffort in packages/shared/inference.ts to use the
exact same literal set, and update the docs table to match that same set so all
three sources agree.

In `@packages/shared/inference.ts`:
- Line 65: The union type for reasoningEffort in the inference type definition
is using "minimum" but the rest of the codebase and docs use "minimal"; change
the union in the reasoningEffort declaration to "minimal" (i.e.,
reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh") and
update any code that sets or validates this value (e.g., the config validation
and the assignment that references reasoningEffort) to use "minimal" so types
and runtime validation match.
- Around line 129-130: The code currently always injects reasoning_effort
(this.config.reasoningEffort) into the request payload which breaks
non-reasoning models; change it to conditionally include reasoning_effort only
for models that support reasoning following the same pattern used for
service_tier: add a predicate (e.g., modelSupportsReasoning(model) or check the
model id against the reasoning-model set) and only set reasoning_effort when
that predicate is true, leaving it out for standard models like "gpt-4.1-mini";
update the payload construction around reasoning_effort to mirror how
service_tier is handled so the field is omitted for unsupported models.

In `@tools/compare-models/src/config.ts`:
- Line 32: The INFERENCE_REASONING_EFFORT z.enum in
tools/compare-models/src/config.ts diverges from the canonical set used by
OpenAIInferenceConfig.reasoningEffort and packages/shared/config.ts (missing the
"minimal"/"minimum" literal and mixing single/double quotes); update
INFERENCE_REASONING_EFFORT to exactly match the canonical literal list from
packages/shared/config.ts/OpenAIInferenceConfig.reasoningEffort (use the same
ordering and the same spelling for the minimal variant), use consistent
double-quote string literals, and keep the same .optional().default(...) value
consistent with the shared config.
- Around line 27-31: INFERENCE_USE_MAX_COMPLETION_TOKENS schema is setting a
string default after a transform to boolean which yields incorrect
types/behavior; update the schema for INFERENCE_USE_MAX_COMPLETION_TOKENS to
apply the default to the input before the transform (use .prefault("false")
prior to .transform((val) => val === "true")) and remove the post-transform
.default so the schema output is a proper boolean.

---

Nitpick comments:
In `@packages/shared/inference.ts`:
- Around line 154-162: The fallback that assigns
chatCompletion.choices[0].message.reasoning to response can yield non-string
values (e.g., objects), causing downstream JSON.parse calls to fail; update the
logic around the response variable in this module to validate and coerce to a
string: if message.content is not present, check message.reasoning and if it's a
string use it, if it's an object prefer reasoning.content or reasoning.response
fields, else JSON.stringify(reasoning) before assigning to response (and keep
the existing error throw if no usable value found). Ensure you update references
to chatCompletion, choices, message.reasoning and the response variable
accordingly so callers (e.g., the JSON.parse(response.response) usage) always
receive a string.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cfae97f7-f010-4f6e-ae6e-e2af566c1af3

📥 Commits

Reviewing files that changed from the base of the PR and between f67f184 and 2a13b0b.

📒 Files selected for processing (5)

• docs/docs/03-configuration/01-environment-variables.md
• packages/shared/config.ts
• packages/shared/inference.ts
• tools/compare-models/src/config.ts
• tools/compare-models/src/inferenceClient.ts

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/docs/03-configuration/01-environment-variables.md`:
- Line 100: Update the OPENAI_REASONING_EFFORT table row so the inline code list
is formatted with a space after the comma (change "`none`,`minimal`" to "`none`,
`minimal`") and add a trailing period to the sentence describing the setting;
edit the row containing the OPENAI_REASONING_EFFORT entry in the Markdown table
to apply these two small punctuation fixes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 09da3bab-2870-41c2-a792-290f93736876

📥 Commits

Reviewing files that changed from the base of the PR and between 2a13b0b and 6154e38.

📒 Files selected for processing (5)

• docs/docs/03-configuration/01-environment-variables.md
• packages/shared/config.ts
• packages/shared/inference.ts
• tools/compare-models/src/config.ts
• tools/compare-models/src/inferenceClient.ts

✅ Files skipped from review due to trivial changes (2)

• packages/shared/config.ts
• tools/compare-models/src/inferenceClient.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/shared/inference.ts

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/docs/03-configuration/01-environment-variables.md`:
- Line 96: The table row for OPENAI_API_KEY uses the ambiguous link text
"[here]"; update that Markdown link on the OPENAI_API_KEY line to use
descriptive link text (e.g., "OpenAI administration guide" or "OpenAI setup and
usage") instead of "here" so readers and screen readers can understand the
target without context, keeping the existing target URL
../06-administration/03-openai.md unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d01a6c8e-010c-4306-a787-5d843292154b

📥 Commits

Reviewing files that changed from the base of the PR and between 6154e38 and 8ca2e8d.

📒 Files selected for processing (1)

• docs/docs/03-configuration/01-environment-variables.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Use descriptive link text instead of “here”.

[here] is ambiguous and hurts scanability/accessibility in docs.

✏️ Suggested doc tweak

-| OPENAI_API_KEY                       | No       | Not set                | The OpenAI key used for automatic tagging. More on that in [here](../06-administration/03-openai.md).                                                                                                                                                                                                                                                                                            |
+| OPENAI_API_KEY                       | No       | Not set                | The OpenAI key used for automatic tagging. More details in the [OpenAI administration guide](../06-administration/03-openai.md).                                                                                                                                                                                                                                                                 |

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	| OPENAI_API_KEY | No | Not set | The OpenAI key used for automatic tagging. More on that in [here](../06-administration/03-openai.md). |
	| OPENAI_API_KEY | No | Not set | The OpenAI key used for automatic tagging. More details in the [OpenAI administration guide](../06-administration/03-openai.md). |

🧰 Tools

🪛 markdownlint-cli2 (0.22.0)

[warning] 96-96: Link text should be descriptive

(MD059, descriptive-link-text)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/docs/03-configuration/01-environment-variables.md` at line 96, The table
row for OPENAI_API_KEY uses the ambiguous link text "[here]"; update that
Markdown link on the OPENAI_API_KEY line to use descriptive link text (e.g.,
"OpenAI administration guide" or "OpenAI setup and usage") instead of "here" so
readers and screen readers can understand the target without context, keeping
the existing target URL ../06-administration/03-openai.md unchanged.

[cinconueves]

@MohamedBassem q: on your changes to the branch, having reasoning passed in always, even if undefined, makes it possible to pass an undefined value field to the request, doesn't it? Which might lead to errors, depending on how strict the end APIs are. This for Open router/non OpenAI yet OpenAI compatible endpoints.

Similarly, still, some reasoning models might return their response in the reasoning field. I think it's a fair edge case.

Is within the real of possibility making the LLM integration more flexible in terms of provider support? i.e openRouter has a sdk which might be more flexible than the Open AI one. Maybe adding a conditional branch for Open router requests to better support these edge cases.

[MohamedBassem]

@cinconueves typically, passing undefined to such APIs are equivalent to not passing the value at all. So I think semantically, it'll end up being the same.

As for the model reasoning field, I'd consider this to be an edge case, that I'm not comfortable supporting generically, specially with the typescript error silencing.

As for the LLM integration, I'm trying to keep that slim as much as possible given that our needs are minimal. I already regret having ollama as a separate SDK versus using the openai compatible API that they have. Each new branch adds maintenance burden for me. That's why I'd rather only have the openai compatible API. I might in the future consider using something like the AI SDK from vercel to abstract that up, but for now, I'd like to keep it minimal.

[cinconueves]

@cinconueves typically, passing undefined to such APIs are equivalent to not passing the value at all. So I think semantically, it'll end up being the same.

As for the model reasoning field, I'd consider this to be an edge case, that I'm not comfortable supporting generically, specially with the typescript error silencing.

As for the LLM integration, I'm trying to keep that slim as much as possible given that our needs are minimal. I already regret having ollama as a separate SDK versus using the openai compatible API that they have. Each new branch adds maintenance burden for me. That's why I'd rather only have the openai compatible API. I might in the future consider using something like the AI SDK from vercel to abstract that up, but for now, I'd like to keep it minimal.

Thanks, that makes sense.