Skip to content

A self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search

feat: add support for configuring OpenAI reasoning effort (#2718)

Luis G. Zúñigaa075ade06e8d
diff --git a/docs/docs/03-configuration/01-environment-variables.md b/docs/docs/03-configuration/01-environment-variables.md
index 783973e1..a8dc2489 100644
--- a/docs/docs/03-configuration/01-environment-variables.md
+++ b/docs/docs/03-configuration/01-environment-variables.md
@@ -92,11 +92,12 @@ Either `OPENAI_API_KEY` or `OLLAMA_BASE_URL` need to be set for automatic taggin
:::
| Name | Required | Default | Description |
-| ------------------------------------ | -------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ------------------------------------ | -------- |------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OPENAI_API_KEY | No | Not set | The OpenAI key used for automatic tagging. More on that in [here](../06-administration/03-openai.md). |
| OPENAI_BASE_URL | No | Not set | If you just want to use OpenAI you don't need to pass this variable. If, however, you want to use some other openai compatible API (e.g. azure openai service), set this to the url of the API. |
| OPENAI_PROXY_URL | No | Not set | HTTP proxy server URL for OpenAI API requests (e.g., `http://proxy.example.com:8080`). |
| OPENAI_SERVICE_TIER | No | Not set | Set to `auto`, `default`, or `flex`. Flex processing provides lower costs in exchange for slower response times and occasional resource unavailability. See [OpenAI Flex Processing](https://platform.openai.com/docs/guides/flex-processing) and [Chat Service Tier](https://platform.openai.com/docs/api-reference/chat/object#chat-object-service_tier) for more details. |
+| OPENAI_REASONING_EFFORT | No | Not set | Set to `none`, `minimal`, `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). |
| OLLAMA_BASE_URL | No | Not set | If you want to use ollama for local inference, set the address of ollama API here. |
| OLLAMA_KEEP_ALIVE | No | Not set | Controls how long the model will stay loaded into memory following the request (examples: "5m" for 5 minutes, "-1m" to keep the model loaded indefinitely, "0" to unload the model instantly after processing is complete). |
| INFERENCE_TEXT_MODEL | No | gpt-4.1-mini | The model to use for text inference. You'll need to change this to some other model if you're using ollama. |
diff --git a/packages/shared/config.ts b/packages/shared/config.ts
index fa175baf..e2597d1d 100644
--- a/packages/shared/config.ts
+++ b/packages/shared/config.ts
@@ -61,6 +61,9 @@ const allEnv = z.object({
OPENAI_BASE_URL: z.string().url().optional(),
OPENAI_PROXY_URL: z.string().url().optional(),
OPENAI_SERVICE_TIER: z.enum(["auto", "default", "flex"]).optional(),
+ OPENAI_REASONING_EFFORT: z
+ .enum(["none", "minimal", "low", "medium", "high", "xhigh"])
+ .optional(),
OLLAMA_BASE_URL: z.string().url().optional(),
OLLAMA_KEEP_ALIVE: z.string().optional(),
INFERENCE_JOB_TIMEOUT_SEC: z.coerce.number().default(30),
@@ -297,6 +300,7 @@ const serverConfigSchema = allEnv.transform((val, ctx) => {
openAIBaseUrl: val.OPENAI_BASE_URL,
openAIProxyUrl: val.OPENAI_PROXY_URL,
openAIServiceTier: val.OPENAI_SERVICE_TIER,
+ openAIReasoningEffort: val.OPENAI_REASONING_EFFORT,
ollamaBaseUrl: val.OLLAMA_BASE_URL,
ollamaKeepAlive: val.OLLAMA_KEEP_ALIVE,
textModel: val.INFERENCE_TEXT_MODEL,
diff --git a/packages/shared/inference.ts b/packages/shared/inference.ts
index 9ef2f2c1..bb3b2218 100644
--- a/packages/shared/inference.ts
+++ b/packages/shared/inference.ts
@@ -61,6 +61,7 @@ export interface OpenAIInferenceConfig {
contextLength: number;
maxOutputTokens: number;
useMaxCompletionTokens: boolean;
+ reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
outputSchema: "structured" | "json" | "plain";
}
@@ -109,6 +110,7 @@ export class OpenAIInferenceClient implements InferenceClient {
maxOutputTokens: serverConfig.inference.maxOutputTokens,
useMaxCompletionTokens: serverConfig.inference.useMaxCompletionTokens,
outputSchema: serverConfig.inference.outputSchema,
+ reasoningEffort: serverConfig.inference.openAIReasoningEffort,
});
}
@@ -140,6 +142,7 @@ export class OpenAIInferenceClient implements InferenceClient {
},
this.config.outputSchema,
),
+ reasoning_effort: this.config.reasoningEffort,
},
{
signal: optsWithDefaults.abortSignal,
diff --git a/tools/compare-models/src/config.ts b/tools/compare-models/src/config.ts
index 9c8bbbf9..11c465bd 100644
--- a/tools/compare-models/src/config.ts
+++ b/tools/compare-models/src/config.ts
@@ -2,33 +2,34 @@ import { z } from "zod";
// Local config schema for compare-models tool
const envSchema = z.object({
- KARAKEEP_API_KEY: z.string().min(1),
- KARAKEEP_SERVER_ADDR: z.string().url(),
- MODEL1_NAME: z.string().min(1),
- MODEL2_NAME: z.string().min(1).optional(),
- OPENAI_API_KEY: z.string().min(1),
- OPENAI_BASE_URL: z.string().url().optional(),
- OPENAI_SERVICE_TIER: z.enum(["auto", "default", "flex"]).optional(),
- COMPARISON_MODE: z
- .enum(["model-vs-model", "model-vs-existing"])
- .default("model-vs-model"),
- COMPARE_LIMIT: z
- .string()
- .optional()
- .transform((val) => (val ? parseInt(val, 10) : 10)),
- INFERENCE_CONTEXT_LENGTH: z
- .string()
- .optional()
- .transform((val) => (val ? parseInt(val, 10) : 8000)),
- INFERENCE_MAX_OUTPUT_TOKENS: z
- .string()
- .optional()
- .transform((val) => (val ? parseInt(val, 10) : 2048)),
- INFERENCE_USE_MAX_COMPLETION_TOKENS: z
- .string()
- .optional()
- .transform((val) => val === "true")
- .prefault("false"),
+ KARAKEEP_API_KEY: z.string().min(1),
+ KARAKEEP_SERVER_ADDR: z.string().url(),
+ MODEL1_NAME: z.string().min(1),
+ MODEL2_NAME: z.string().min(1).optional(),
+ OPENAI_API_KEY: z.string().min(1),
+ OPENAI_BASE_URL: z.string().url().optional(),
+ OPENAI_SERVICE_TIER: z.enum(["auto", "default", "flex"]).optional(),
+ COMPARISON_MODE: z
+ .enum(["model-vs-model", "model-vs-existing"])
+ .default("model-vs-model"),
+ COMPARE_LIMIT: z
+ .string()
+ .optional()
+ .transform((val) => (val ? parseInt(val, 10) : 10)),
+ INFERENCE_CONTEXT_LENGTH: z
+ .string()
+ .optional()
+ .transform((val) => (val ? parseInt(val, 10) : 8000)),
+ INFERENCE_MAX_OUTPUT_TOKENS: z
+ .string()
+ .optional()
+ .transform((val) => (val ? parseInt(val, 10) : 2048)),
+ INFERENCE_USE_MAX_COMPLETION_TOKENS: z
+ .string()
+ .optional()
+ .transform((val) => val === "true")
+ .prefault("false"),
+ INFERENCE_REASONING_EFFORT: z.enum(["low", "medium", "high", 'none', 'xhigh']).optional()
});
export const config = envSchema.parse(process.env);
diff --git a/tools/compare-models/src/inferenceClient.ts b/tools/compare-models/src/inferenceClient.ts
index 0a5ed8b5..738c80a8 100644
--- a/tools/compare-models/src/inferenceClient.ts
+++ b/tools/compare-models/src/inferenceClient.ts
@@ -18,6 +18,7 @@ export function createInferenceClient(modelName: string): InferenceClient {
maxOutputTokens: config.INFERENCE_MAX_OUTPUT_TOKENS,
useMaxCompletionTokens: config.INFERENCE_USE_MAX_COMPLETION_TOKENS,
outputSchema: "structured",
+ reasoningEffort: config.INFERENCE_REASONING_EFFORT,
};
return new OpenAIInferenceClient(inferenceConfig);