Skip to content

The open alternative to Salesforce, designed for AI.

Deliver the Claude reasoning config and make effort a first-class model parameter (#25696)

Félix Malfait8fc71f4f545c
diff --git a/packages/twenty-server/scripts/ai-catalog-sync/__tests__/carry-over-committed-fields.spec.ts b/packages/twenty-server/scripts/ai-catalog-sync/__tests__/carry-over-committed-fields.spec.ts
new file mode 100644
index 00000000000..5b4ee8466f9
--- /dev/null
+++ b/packages/twenty-server/scripts/ai-catalog-sync/__tests__/carry-over-committed-fields.spec.ts
@@ -0,0 +1,59 @@
+import { type GeneratedCatalog } from '../types/generated-catalog.type';
+import { type GeneratedModel } from '../types/generated-model.type';
+import { carryOverCommittedFields } from '../utils/carry-over-committed-fields.util';
+
+const openai = (models: GeneratedModel[]): GeneratedCatalog => ({
+ openai: {
+ npm: '@ai-sdk/openai',
+ label: 'OpenAI',
+ apiKey: '{{OPENAI_API_KEY}}',
+ models,
+ },
+});
+
+describe('carryOverCommittedFields', () => {
+ it('restores the fields models.dev does not carry, and only those', () => {
+ const catalog = openai([
+ { name: 'gpt-x', label: 'GPT X', supportsReasoning: true },
+ ]);
+
+ carryOverCommittedFields({
+ catalog,
+ committedCatalog: openai([
+ {
+ name: 'gpt-x',
+ label: 'Old label',
+ inputCostPerMillionTokens: 1,
+ efforts: ['low', 'high'],
+ dataResidency: 'us',
+ zeroDataRetention: true,
+ },
+ ]),
+ });
+
+ expect(catalog.openai.models[0]).toEqual({
+ name: 'gpt-x',
+ label: 'GPT X',
+ supportsReasoning: true,
+ efforts: ['low', 'high'],
+ dataResidency: 'us',
+ zeroDataRetention: true,
+ });
+ });
+
+ it('leaves a model the committed catalog does not know untouched', () => {
+ const catalog = openai([{ name: 'gpt-new', label: 'GPT New' }]);
+
+ carryOverCommittedFields({
+ catalog,
+ committedCatalog: openai([
+ { name: 'gpt-x', label: 'GPT X', efforts: ['low'] },
+ ]),
+ });
+
+ expect(catalog.openai.models[0]).toEqual({
+ name: 'gpt-new',
+ label: 'GPT New',
+ });
+ });
+});
diff --git a/packages/twenty-server/scripts/ai-catalog-sync/index.ts b/packages/twenty-server/scripts/ai-catalog-sync/index.ts
index aedd793ff5d..c667f132e19 100644
--- a/packages/twenty-server/scripts/ai-catalog-sync/index.ts
+++ b/packages/twenty-server/scripts/ai-catalog-sync/index.ts
@@ -9,12 +9,14 @@ import { type ModelsDevData } from 'src/engine/metadata-modules/ai/ai-models/typ
import { assertPayloadIsUsable } from './utils/assert-payload-is-usable.util';
import { buildCatalog } from './utils/build-catalog.util';
+import { carryOverCommittedFields } from './utils/carry-over-committed-fields.util';
import { enrichCatalog } from './utils/enrich-catalog.util';
import { fetchArtificialAnalysisBenchmarks } from './utils/fetch-artificial-analysis-benchmarks.util';
import { readCommittedBenchmarks } from './utils/read-committed-benchmarks.util';
import { buildCoverageReport } from './utils/build-coverage-report.util';
import { renderCoverageReport } from './utils/render-coverage-report.util';
import { type BenchmarkIndex } from './types/benchmark-index.type';
+import { type GeneratedCatalog } from './types/generated-catalog.type';
const AI_MODELS_DIR = path.resolve(
__dirname,
@@ -41,6 +43,11 @@ const readArgument = (flag: string): string | undefined => {
return index === -1 ? undefined : process.argv[index + 1];
};
+const readCommittedCatalog = (filePath: string): GeneratedCatalog =>
+ fs.existsSync(filePath)
+ ? (JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GeneratedCatalog)
+ : {};
+
const fetchModelsDev = async (): Promise<ModelsDevData> => {
const response = await fetch(MODELS_DEV_API_URL, {
signal: AbortSignal.timeout(120000),
@@ -122,6 +129,11 @@ const main = async (): Promise<void> => {
const catalog = buildCatalog(modelsDevData);
+ carryOverCommittedFields({
+ catalog,
+ committedCatalog: readCommittedCatalog(CATALOG_PATH),
+ });
+
const overlay = enrichCatalog({
catalog,
modelsDevData,
diff --git a/packages/twenty-server/scripts/ai-catalog-sync/types/generated-model.type.ts b/packages/twenty-server/scripts/ai-catalog-sync/types/generated-model.type.ts
index 4a216aeb2e4..3709d5e351f 100644
--- a/packages/twenty-server/scripts/ai-catalog-sync/types/generated-model.type.ts
+++ b/packages/twenty-server/scripts/ai-catalog-sync/types/generated-model.type.ts
@@ -1,3 +1,5 @@
+import { type AiModelEffort, type DataResidency } from 'twenty-shared/ai';
+
import { type AiModelBenchmark } from 'src/engine/metadata-modules/ai/ai-models/types/ai-model-benchmark.type';
import { type LongContextCost } from 'src/engine/metadata-modules/ai/ai-models/types/long-context-cost.type';
import { type ModelFamily } from 'src/engine/metadata-modules/ai/ai-models/types/model-family.enum';
@@ -16,6 +18,9 @@ export type GeneratedModel = {
maxOutputTokens?: number;
modalities?: string[];
supportsReasoning?: boolean;
+ efforts?: AiModelEffort[];
+ dataResidency?: DataResidency;
+ zeroDataRetention?: boolean;
benchmark?: AiModelBenchmark;
isDeprecated?: boolean;
};
diff --git a/packages/twenty-server/scripts/ai-catalog-sync/utils/carry-over-committed-fields.util.ts b/packages/twenty-server/scripts/ai-catalog-sync/utils/carry-over-committed-fields.util.ts
new file mode 100644
index 00000000000..32b1a577ad2
--- /dev/null
+++ b/packages/twenty-server/scripts/ai-catalog-sync/utils/carry-over-committed-fields.util.ts
@@ -0,0 +1,43 @@
+import { isDefined } from 'twenty-shared/utils';
+
+import { type GeneratedCatalog } from '../types/generated-catalog.type';
+import { type GeneratedModel } from '../types/generated-model.type';
+
+// models.dev knows neither which effort levels a model takes nor its routing
+// facts, so a rebuild would drop them without this.
+const CARRIED_OVER_FIELDS = [
+ 'efforts',
+ 'dataResidency',
+ 'zeroDataRetention',
+] as const satisfies readonly (keyof GeneratedModel)[];
+
+export const carryOverCommittedFields = ({
+ catalog,
+ committedCatalog,
+}: {
+ catalog: GeneratedCatalog;
+ committedCatalog: GeneratedCatalog;
+}): void => {
+ for (const [providerName, provider] of Object.entries(catalog)) {
+ const committedModels = new Map(
+ (committedCatalog[providerName]?.models ?? []).map((model) => [
+ model.name,
+ model,
+ ]),
+ );
+
+ for (const model of provider.models) {
+ const committedModel = committedModels.get(model.name);
+
+ if (!isDefined(committedModel)) {
+ continue;
+ }
+
+ for (const field of CARRIED_OVER_FIELDS) {
+ if (isDefined(committedModel[field])) {
+ Object.assign(model, { [field]: committedModel[field] });
+ }
+ }
+ }
+ }
+};
diff --git a/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts b/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts
index 3022ce84f3f..6e77e7f5396 100644
--- a/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts
+++ b/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts
@@ -1918,7 +1918,7 @@ export class ConfigVariables {
@ConfigVariablesMetadata({
group: ConfigVariablesGroup.LLM,
description:
- 'Ordered list of fast model IDs to use as defaults. Managed via admin panel or env.',
+ 'Ordered list of fast model IDs to use as defaults; an ID may pin an effort level as provider/model@effort. Managed via admin panel or env.',
type: ConfigVariableType.ARRAY,
})
@IsOptional()
@@ -1927,7 +1927,7 @@ export class ConfigVariables {
@ConfigVariablesMetadata({
group: ConfigVariablesGroup.LLM,
description:
- 'Ordered list of smart model IDs to use as defaults. Managed via admin panel or env.',
+ 'Ordered list of smart model IDs to use as defaults; an ID may pin an effort level as provider/model@effort. Managed via admin panel or env.',
type: ConfigVariableType.ARRAY,
})
@IsOptional()
@@ -1936,7 +1936,7 @@ export class ConfigVariables {
@ConfigVariablesMetadata({
group: ConfigVariablesGroup.LLM,
description:
- 'List of recommended model IDs shown to workspaces using curated model selection. Managed via admin panel or env.',
+ 'List of recommended model IDs shown to workspaces using curated model selection; an ID may pin an effort level as provider/model@effort. Managed via admin panel or env.',
type: ConfigVariableType.ARRAY,
})
@IsOptional()
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts
index d0ed89708d6..5258e5973e1 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent-execution/services/agent-async-executor.service.ts
@@ -307,9 +307,12 @@ export class AgentAsyncExecutorService {
let tools: ToolSet = {};
let toolCatalogSection = '';
- let providerOptions = getCallLevelProviderOptions({
+ const providerOptions = getCallLevelProviderOptions({
sdkPackage: registeredModel.sdkPackage,
- providerOptions: undefined,
+ providerOptions:
+ this.aiModelConfigService.getReasoningProviderOptions(
+ registeredModel,
+ ),
promptCacheKey: agent?.id,
});
@@ -361,15 +364,6 @@ export class AgentAsyncExecutorService {
...registryTools,
...nativeTools,
};
-
- providerOptions = getCallLevelProviderOptions({
- sdkPackage: registeredModel.sdkPackage,
- providerOptions:
- this.aiModelConfigService.getReasoningProviderOptions(
- registeredModel,
- ),
- promptCacheKey: agent?.id,
- });
}
this.logger.log(`Generated ${Object.keys(tools).length} tools for agent`);
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent/constants/agent-config.const.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent/constants/agent-config.const.ts
index 4094cf253a5..c29d098cae0 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent/constants/agent-config.const.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-agent/constants/agent-config.const.ts
@@ -1,4 +1,3 @@
export const AGENT_CONFIG = {
MAX_STEPS: 300,
- REASONING_BUDGET_TOKENS: 12000,
};
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/chat-execution.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/chat-execution.service.ts
index fdffe11644e..dd19c795f4e 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/chat-execution.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/services/chat-execution.service.ts
@@ -83,6 +83,7 @@ import {
import { replaceUnsupportedFileParts } from 'src/engine/metadata-modules/ai/ai-chat/utils/replace-unsupported-file-parts.util';
import { tagAiChatKindScope } from 'src/engine/metadata-modules/ai/ai-chat/utils/tag-ai-chat-kind-scope.util';
import { buildAiTelemetry } from 'src/engine/metadata-modules/ai/ai-models/utils/build-ai-telemetry.util';
+import { AiModelConfigService } from 'src/engine/metadata-modules/ai/ai-models/services/ai-model-config.service';
import { AiModelRegistryService } from 'src/engine/metadata-modules/ai/ai-models/services/ai-model-registry.service';
import { NativeToolBinderService } from 'src/engine/metadata-modules/ai/ai-models/services/native-tool-binder.service';
import { type AiModelConfig } from 'src/engine/metadata-modules/ai/ai-models/types/ai-model-config.type';
@@ -122,6 +123,7 @@ export class ChatExecutionService {
private readonly toolRegistry: ToolRegistryService,
private readonly skillService: SkillService,
private readonly aiModelRegistryService: AiModelRegistryService,
+ private readonly aiModelConfigService: AiModelConfigService,
private readonly aiBillingService: AiBillingService,
private readonly agentActorContextService: AgentActorContextService,
private readonly workspaceDomainsService: WorkspaceDomainsService,
@@ -499,7 +501,10 @@ export class ChatExecutionService {
}),
providerOptions: getCallLevelProviderOptions({
sdkPackage: registeredModel.sdkPackage,
- providerOptions: undefined,
+ providerOptions:
+ this.aiModelConfigService.getReasoningProviderOptions(
+ registeredModel,
+ ),
promptCacheKey: threadId,
}),
prepareStep: ({ messages }) => {
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/__tests__/provider-options.util.spec.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/__tests__/provider-options.util.spec.ts
index 59d0a8dda81..6b0ac46d3a1 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/__tests__/provider-options.util.spec.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/__tests__/provider-options.util.spec.ts
@@ -22,6 +22,47 @@ describe('provider-options.util', () => {
});
});
+ it('keeps the thinking config the executor passes for Anthropic', () => {
+ expect(
+ getCallLevelProviderOptions({
+ sdkPackage: AI_SDK_ANTHROPIC,
+ providerOptions: { anthropic: { thinking: { type: 'adaptive' } } },
+ }),
+ ).toEqual({
+ anthropic: {
+ thinking: { type: 'adaptive' },
+ cacheControl: { type: 'ephemeral' },
+ },
+ });
+ });
+
+ it('keeps existing OpenAI options alongside store false', () => {
+ expect(
+ getCallLevelProviderOptions({
+ sdkPackage: AI_SDK_OPENAI,
+ providerOptions: { openai: { reasoningEffort: 'high' } },
+ promptCacheKey: 'thread-123',
+ }),
+ ).toEqual({
+ openai: {
+ reasoningEffort: 'high',
+ store: false,
+ promptCacheKey: 'thread-123',
+ },
+ });
+ });
+
+ it('keeps existing Azure options alongside store false', () => {
+ expect(
+ getCallLevelProviderOptions({
+ sdkPackage: AI_SDK_AZURE,
+ providerOptions: { azure: { reasoningEffort: 'high' } },
+ }),
+ ).toEqual({
+ azure: { reasoningEffort: 'high', store: false },
+ });
+ });
+
it('merges existing provider options with call-level options', () => {
expect(
getCallLevelProviderOptions({
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/provider-options.util.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/provider-options.util.ts
index 51dd0d4d76d..c4d6650742f 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/provider-options.util.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/utils/provider-options.util.ts
@@ -32,17 +32,24 @@ export const getCallLevelProviderOptions = ({
case AI_SDK_ANTHROPIC:
return {
...(providerOptions ?? {}),
- anthropic: { cacheControl: { type: 'ephemeral' } },
+ anthropic: {
+ ...(providerOptions?.anthropic ?? {}),
+ cacheControl: { type: 'ephemeral' },
+ },
};
case AI_SDK_OPENAI:
return {
...(providerOptions ?? {}),
- openai: { store: false, ...(promptCacheKey ? { promptCacheKey } : {}) },
+ openai: {
+ ...(providerOptions?.openai ?? {}),
+ store: false,
+ ...(promptCacheKey ? { promptCacheKey } : {}),
+ },
};
case AI_SDK_AZURE:
return {
...(providerOptions ?? {}),
- azure: { store: false },
+ azure: { ...(providerOptions?.azure ?? {}), store: false },
};
default:
return providerOptions;
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/__tests__/ai-providers-json.spec.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/__tests__/ai-providers-json.spec.ts
index c542a3e7440..e6e4b21b1fd 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/__tests__/ai-providers-json.spec.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/__tests__/ai-providers-json.spec.ts
@@ -1,3 +1,5 @@
+import { isDefined } from 'twenty-shared/utils';
+
import defaultAiProviders from 'src/engine/metadata-modules/ai/ai-models/ai-providers.json';
import { aiProvidersConfigSchema } from 'src/engine/metadata-modules/ai/ai-models/types/ai-providers-config.schema';
import { type AiProvidersConfig } from 'src/engine/metadata-modules/ai/ai-models/types/ai-providers-config.type';
@@ -43,6 +45,16 @@ describe('ai-providers.json integrity', () => {
});
});
+ it('should declare efforts only on reasoning models', () => {
+ Object.values(PROVIDERS).forEach((config) => {
+ (config.models ?? []).forEach((model) => {
+ if (isDefined(model.efforts)) {
+ expect(model.supportsReasoning).toBe(true);
+ }
+ });
+ });
+ });
+
it('should have unique composite model IDs across all providers', () => {
const allCompositeIds: string[] = [];
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/ai-providers.json b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/ai-providers.json
index 1f1ebcf1334..fc6ce69cb7c 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/ai-providers.json
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/ai-providers.json
@@ -81,6 +81,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["none", "low", "medium", "high", "xhigh", "max"],
"benchmark": {
"intelligenceIndex": 47.1,
"outputTokensPerSecond": 73.005,
@@ -121,6 +122,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["minimal", "low", "medium", "high", "xhigh", "max"],
"benchmark": {
"intelligenceIndex": 52.8,
"outputTokensPerSecond": 60.822,
@@ -182,6 +184,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["none", "low", "medium", "high", "xhigh"],
"benchmark": {
"intelligenceIndex": 39,
"measuredAt": "2026-09-10"
@@ -269,6 +272,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["none", "low", "medium", "high", "xhigh", "max"],
"benchmark": {
"intelligenceIndex": 37.5,
"outputTokensPerSecond": 123.243,
@@ -457,6 +461,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["none", "low", "medium", "high", "xhigh", "max"],
"benchmark": {
"intelligenceIndex": 42.3,
"outputTokensPerSecond": 124.121,
@@ -628,6 +633,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["none", "low", "medium", "high", "xhigh", "max"],
"benchmark": {
"intelligenceIndex": 38.6,
"measuredAt": "2026-09-10"
@@ -667,6 +673,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high", "max"],
"benchmark": {
"intelligenceIndex": 30.5,
"measuredAt": "2026-09-10"
@@ -684,6 +691,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high", "xhigh", "max"],
"benchmark": {
"intelligenceIndex": 50.7,
"outputTokensPerSecond": 55.074,
@@ -702,6 +710,7 @@
"maxOutputTokens": 64000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high"],
"benchmark": {
"intelligenceIndex": 29.1,
"measuredAt": "2026-09-10"
@@ -719,6 +728,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high", "xhigh", "max"],
"benchmark": {
"intelligenceIndex": 53.4,
"outputTokensPerSecond": 69.904,
@@ -737,6 +747,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high", "max"],
"benchmark": {
"intelligenceIndex": 31.9,
"measuredAt": "2026-09-10"
@@ -767,6 +778,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high", "xhigh", "max"],
"benchmark": {
"intelligenceIndex": 40.7,
"measuredAt": "2026-09-10"
@@ -797,6 +809,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high", "xhigh", "max"],
"benchmark": {
"intelligenceIndex": 49.7,
"outputTokensPerSecond": 68.133,
@@ -841,6 +854,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high", "xhigh", "max"],
"benchmark": {
"intelligenceIndex": 42,
"measuredAt": "2026-09-10"
@@ -858,6 +872,7 @@
"maxOutputTokens": 128000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high", "xhigh", "max"],
"benchmark": {
"intelligenceIndex": 38.4,
"outputTokensPerSecond": 83.464,
@@ -876,6 +891,7 @@
"maxOutputTokens": 64000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high"],
"benchmark": {
"intelligenceIndex": 29.1,
"measuredAt": "2026-09-10"
@@ -952,6 +968,7 @@
"maxOutputTokens": 65536,
"modalities": ["image", "video", "audio", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high"],
"benchmark": {
"intelligenceIndex": 30.4,
"outputTokensPerSecond": 127.691,
@@ -1019,6 +1036,7 @@
"maxOutputTokens": 65536,
"modalities": ["image", "video", "audio", "pdf"],
"supportsReasoning": true,
+ "efforts": ["minimal", "low", "medium", "high"],
"benchmark": {
"intelligenceIndex": 34.3,
"outputTokensPerSecond": 184.677,
@@ -1063,6 +1081,7 @@
"maxOutputTokens": 65536,
"modalities": ["image", "video", "audio", "pdf"],
"supportsReasoning": true,
+ "efforts": ["minimal", "low", "medium", "high"],
"benchmark": {
"intelligenceIndex": 33.6,
"outputTokensPerSecond": 239.733,
@@ -1097,6 +1116,7 @@
"maxOutputTokens": 65536,
"modalities": ["image", "video", "audio", "pdf"],
"supportsReasoning": true,
+ "efforts": ["minimal", "low", "medium", "high"],
"benchmark": {
"intelligenceIndex": 22.7,
"outputTokensPerSecond": 365.348,
@@ -1131,6 +1151,7 @@
"maxOutputTokens": 65536,
"modalities": ["image", "video", "audio", "pdf"],
"supportsReasoning": true,
+ "efforts": ["minimal", "low", "medium", "high"],
"benchmark": {
"intelligenceIndex": 26.3,
"measuredAt": "2026-09-10"
@@ -1147,6 +1168,7 @@
"maxOutputTokens": 65536,
"modalities": ["image", "video", "audio", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high"],
"benchmark": {
"intelligenceIndex": 41.2,
"outputTokensPerSecond": 342.779,
@@ -1164,6 +1186,7 @@
"maxOutputTokens": 65536,
"modalities": ["image", "video", "audio", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high"],
"benchmark": {
"intelligenceIndex": 39.6,
"outputTokensPerSecond": 329.345,
@@ -1441,7 +1464,8 @@
"contextWindowTokens": 256000,
"maxOutputTokens": 256000,
"modalities": ["image"],
- "supportsReasoning": true
+ "supportsReasoning": true,
+ "efforts": ["none", "high"]
},
{
"name": "open-mistral-nemo",
@@ -1609,6 +1633,7 @@
"maxOutputTokens": 500000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high"],
"benchmark": {
"intelligenceIndex": 39.1,
"outputTokensPerSecond": 52.947,
@@ -1650,6 +1675,7 @@
"maxOutputTokens": 500000,
"modalities": ["image", "pdf"],
"supportsReasoning": true,
+ "efforts": ["low", "medium", "high", "xhigh"],
"benchmark": {
"intelligenceIndex": 44.4,
"outputTokensPerSecond": 62.454,
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/constants/ai-sdk-package-efforts.const.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/constants/ai-sdk-package-efforts.const.ts
new file mode 100644
index 00000000000..c69a31a76cc
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/constants/ai-sdk-package-efforts.const.ts
@@ -0,0 +1,65 @@
+import { type AmazonBedrockLanguageModelOptions } from '@ai-sdk/amazon-bedrock';
+import { type AnthropicLanguageModelOptions } from '@ai-sdk/anthropic';
+import { type GoogleLanguageModelOptions } from '@ai-sdk/google';
+import { type MistralLanguageModelOptions } from '@ai-sdk/mistral';
+import { type XaiLanguageModelResponsesOptions } from '@ai-sdk/xai';
+import { type AiModelEffort, type AiSdkPackage } from 'twenty-shared/ai';
+
+import {
+ AI_SDK_ANTHROPIC,
+ AI_SDK_AZURE,
+ AI_SDK_BEDROCK,
+ AI_SDK_GOOGLE,
+ AI_SDK_MISTRAL,
+ AI_SDK_OPENAI,
+ AI_SDK_XAI,
+} from 'src/engine/metadata-modules/ai/ai-models/constants/ai-sdk-package.const';
+
+type AnthropicEffort = NonNullable<AnthropicLanguageModelOptions['effort']>;
+type BedrockEffort = NonNullable<
+ NonNullable<
+ AmazonBedrockLanguageModelOptions['reasoningConfig']
+ >['maxReasoningEffort']
+>;
+type GoogleThinkingLevel = NonNullable<
+ NonNullable<GoogleLanguageModelOptions['thinkingConfig']>['thinkingLevel']
+>;
+type MistralEffort = NonNullable<
+ MistralLanguageModelOptions['reasoningEffort']
+>;
+type XaiEffort = NonNullable<
+ XaiLanguageModelResponsesOptions['reasoningEffort']
+>;
+
+// What each SDK package can put on the wire, pinned to the SDK's own option
+// type where it has one; the OpenAI Responses model types it as a plain string.
+// A model's catalog entry lists what the model takes; only the intersection is
+// offered, so a level the SDK would reject is never forwarded.
+export const AI_SDK_PACKAGE_EFFORTS: Partial<
+ Record<AiSdkPackage, readonly AiModelEffort[]>
+> = {
+ [AI_SDK_ANTHROPIC]: [
+ 'low',
+ 'medium',
+ 'high',
+ 'xhigh',
+ 'max',
+ ] satisfies readonly AnthropicEffort[],
+ [AI_SDK_BEDROCK]: [
+ 'low',
+ 'medium',
+ 'high',
+ 'xhigh',
+ 'max',
+ ] satisfies readonly BedrockEffort[],
+ [AI_SDK_OPENAI]: ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'],
+ [AI_SDK_AZURE]: ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'],
+ [AI_SDK_GOOGLE]: [
+ 'minimal',
+ 'low',
+ 'medium',
+ 'high',
+ ] satisfies readonly GoogleThinkingLevel[],
+ [AI_SDK_MISTRAL]: ['none', 'high'] satisfies readonly MistralEffort[],
+ [AI_SDK_XAI]: ['low', 'medium', 'high'] satisfies readonly XaiEffort[],
+};
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/services/ai-model-config.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/services/ai-model-config.service.ts
index 9087d3d0265..116581860f9 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/services/ai-model-config.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/services/ai-model-config.service.ts
@@ -4,10 +4,8 @@ import { type ProviderOptions } from '@ai-sdk/provider-utils';
import { type ToolSet } from 'ai';
import { isDefined } from 'twenty-shared/utils';
-import { AGENT_CONFIG } from 'src/engine/metadata-modules/ai/ai-agent/constants/agent-config.const';
import {
AI_SDK_ANTHROPIC,
- AI_SDK_BEDROCK,
AI_SDK_OPENAI,
AI_SDK_XAI,
} from 'src/engine/metadata-modules/ai/ai-models/constants/ai-sdk-package.const';
@@ -17,6 +15,7 @@ import {
} from 'src/engine/metadata-modules/ai/ai-models/services/ai-model-registry.service';
import { SdkProviderFactoryService } from 'src/engine/metadata-modules/ai/ai-models/services/sdk-provider-factory.service';
import { type NativeModelToolOptions } from 'src/engine/metadata-modules/ai/ai-models/types/native-model-tool-options.type';
+import { buildReasoningProviderOptions } from 'src/engine/metadata-modules/ai/ai-models/utils/build-reasoning-provider-options.util';
import { getNativeModelToolsForSdkPackage } from 'src/engine/metadata-modules/ai/ai-models/utils/get-native-model-tools-for-sdk-package.util';
@Injectable()
@@ -27,14 +26,7 @@ export class AiModelConfigService {
) {}
getReasoningProviderOptions(model: RegisteredAiModel): ProviderOptions {
- switch (model.sdkPackage) {
- case AI_SDK_ANTHROPIC:
- return this.getAnthropicProviderOptions(model);
- case AI_SDK_BEDROCK:
- return this.getBedrockProviderOptions(model);
- default:
- return {};
- }
+ return buildReasoningProviderOptions(model);
}
getNativeModelTools(
@@ -104,36 +96,4 @@ export class AiModelConfigService {
return tools as ToolSet;
}
-
- private getAnthropicProviderOptions(
- model: RegisteredAiModel,
- ): ProviderOptions {
- if (!model.supportsReasoning) {
- return {};
- }
-
- return {
- anthropic: {
- thinking: {
- type: 'enabled',
- budgetTokens: AGENT_CONFIG.REASONING_BUDGET_TOKENS,
- },
- },
- };
- }
-
- private getBedrockProviderOptions(model: RegisteredAiModel): ProviderOptions {
- if (!model.supportsReasoning) {
- return {};
- }
-
- return {
- bedrock: {
- thinking: {
- type: 'enabled',
- budgetTokens: AGENT_CONFIG.REASONING_BUDGET_TOKENS,
- },
- },
- };
- }
}
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/services/ai-model-registry.service.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/services/ai-model-registry.service.ts
index 227d2dc1cf7..fda1a276710 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/services/ai-model-registry.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/services/ai-model-registry.service.ts
@@ -2,7 +2,7 @@ import { Injectable, Logger } from '@nestjs/common';
import { type LanguageModel, type TranscriptionModel } from 'ai';
import { isNonEmptyString } from '@sniptt/guards';
-import { type AiSdkPackage } from 'twenty-shared/ai';
+import { type AiModelEffort, type AiSdkPackage } from 'twenty-shared/ai';
import { MAX_SEATS_WITHOUT_ENTERPRISE_KEY } from 'src/engine/core-modules/enterprise/constants/max-seats-without-enterprise-key.constant';
import { CustomAiProviderAccessService } from 'src/engine/core-modules/enterprise/services/custom-ai-provider-access.service';
@@ -34,9 +34,11 @@ import { isAutoSelectModelId, isDefined } from 'twenty-shared/utils';
import { DEFAULT_MAX_OUTPUT_TOKENS } from 'src/engine/metadata-modules/ai/ai-models/types/default-max-output-tokens.const';
import { buildCompositeModelId } from 'src/engine/metadata-modules/ai/ai-models/utils/composite-model-id.util';
+import { getAvailableEfforts } from 'src/engine/metadata-modules/ai/ai-models/utils/get-available-efforts.util';
import { getPositiveTokenLimitOrDefault } from 'src/engine/metadata-modules/ai/ai-models/utils/get-positive-token-limit-or-default.util';
import { inferModelFamily } from 'src/engine/metadata-modules/ai/ai-models/utils/infer-model-family.util';
import { isProviderConfigured } from 'src/engine/metadata-modules/ai/ai-models/utils/is-provider-configured.util';
+import { parseModelVariantId } from 'src/engine/metadata-modules/ai/ai-models/utils/parse-model-variant-id.util';
import {
isModelAllowedByWorkspace,
type WorkspaceModelAvailabilitySettings,
@@ -48,6 +50,7 @@ export interface RegisteredAiModel {
sdkPackage: AiSdkPackage;
model: LanguageModel;
supportsReasoning?: boolean;
+ effort?: AiModelEffort;
providerName?: string;
modelsDevName?: string;
}
@@ -123,6 +126,7 @@ export class AiModelRegistryService {
});
this.registerModelsFromProviders(providers);
+ this.registerConfiguredVariants();
}
private registerModelsFromProviders(providers: AiProvidersConfig): void {
@@ -183,6 +187,82 @@ export class AiModelRegistryService {
}
}
+ // A variant exists only where an operator listed one, so no caller reaches an
+ // effort the catalog never declared by typing an id.
+ private registerConfiguredVariants(): void {
+ const preferences = this.preferencesService.getPreferences();
+ const listedModelIds = new Set([
+ ...(preferences.recommendedModels ?? []),
+ ...(preferences.defaultFastModels ?? []),
+ ...(preferences.defaultSmartModels ?? []),
+ ]);
+
+ for (const variantId of listedModelIds) {
+ const variant = this.resolveConfiguredVariant(variantId);
+
+ if (!isDefined(variant)) {
+ continue;
+ }
+
+ const { baseConfig, effort } = variant;
+
+ this.modelConfigCache.set(variantId, {
+ ...baseConfig,
+ modelId: variantId,
+ label: `${baseConfig.label} (${effort})`,
+ effort,
+ // A benchmark describes the effort it was measured at, not this one.
+ benchmark: undefined,
+ });
+
+ const baseModelDef = this.providerModelDefCache.get(baseConfig.modelId);
+
+ if (isDefined(baseModelDef)) {
+ this.providerModelDefCache.set(variantId, baseModelDef);
+ }
+
+ const baseModel = this.modelRegistry.get(baseConfig.modelId);
+
+ if (isDefined(baseModel)) {
+ this.modelRegistry.set(variantId, {
+ ...baseModel,
+ modelId: variantId,
+ effort,
+ });
+ }
+ }
+ }
+
+ private resolveConfiguredVariant(
+ variantId: string,
+ ): { baseConfig: AiModelConfig; effort: AiModelEffort } | undefined {
+ if (this.modelConfigCache.has(variantId)) {
+ return undefined;
+ }
+
+ const { modelId, effort } = parseModelVariantId(variantId);
+
+ if (!isDefined(effort)) {
+ return undefined;
+ }
+
+ const baseConfig = this.modelConfigCache.get(modelId);
+
+ if (!isDefined(baseConfig)) {
+ return undefined;
+ }
+
+ if (!getAvailableEfforts(baseConfig).includes(effort)) {
+ this.logger.warn(
+ `Skipping "${variantId}": effort "${effort}" is not available for ${modelId}`,
+ );
+
+ return undefined;
+ }
+
+ return { baseConfig, effort };
+ }
+
private registerTranscriptionModel({
compositeId,
providerKey,
@@ -310,6 +390,7 @@ export class AiModelRegistryService {
),
modalities: modelDef.modalities,
supportsReasoning: modelDef.supportsReasoning,
+ efforts: modelDef.efforts,
benchmark: modelDef.benchmark,
isDeprecated: modelDef.isDeprecated,
};
@@ -563,7 +644,10 @@ export class AiModelRegistryService {
private validateModelInRegistry(modelId: string): void {
this.ensureFresh();
- if (!this.providerModelDefCache.has(modelId)) {
+ if (
+ !this.providerModelDefCache.has(modelId) &&
+ !isDefined(this.resolveConfiguredVariant(modelId))
+ ) {
throw new AiException(
`Cannot update model "${modelId}": not found in registry`,
AiExceptionCode.AGENT_EXECUTION_FAILED,
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/types/ai-model-config.type.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/types/ai-model-config.type.ts
index 5be2607663b..9d2b592d5e5 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/types/ai-model-config.type.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/types/ai-model-config.type.ts
@@ -1,4 +1,8 @@
-import { type AiSdkPackage, type DataResidency } from 'twenty-shared/ai';
+import {
+ type AiModelEffort,
+ type AiSdkPackage,
+ type DataResidency,
+} from 'twenty-shared/ai';
import { type AiModelBenchmark } from 'src/engine/metadata-modules/ai/ai-models/types/ai-model-benchmark.type';
import { type LongContextCost } from 'src/engine/metadata-modules/ai/ai-models/types/long-context-cost.type';
import { type ModelFamily } from 'src/engine/metadata-modules/ai/ai-models/types/model-family.enum';
@@ -21,6 +25,9 @@ export type AiModelConfig = {
longContextCost?: LongContextCost;
modalities?: string[];
supportsReasoning?: boolean;
+ efforts?: AiModelEffort[];
+ // Pinned by a variant id (`model@effort`); unset runs the provider default.
+ effort?: AiModelEffort;
benchmark?: AiModelBenchmark;
isDeprecated?: boolean;
};
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/types/ai-provider-model-config.schema.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/types/ai-provider-model-config.schema.ts
index b28df867527..7ef4352efb6 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/types/ai-provider-model-config.schema.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/types/ai-provider-model-config.schema.ts
@@ -1,6 +1,6 @@
import { z } from 'zod';
-import { DATA_RESIDENCY_KEYS } from 'twenty-shared/ai';
+import { AI_MODEL_EFFORTS, DATA_RESIDENCY_KEYS } from 'twenty-shared/ai';
import { AI_MODEL_KINDS } from 'src/engine/metadata-modules/ai/ai-models/constants/ai-model-kinds.const';
import { aiModelBenchmarkSchema } from 'src/engine/metadata-modules/ai/ai-models/types/ai-model-benchmark.schema';
@@ -24,6 +24,9 @@ export const aiProviderModelConfigSchema = z
maxOutputTokens: z.number().int().positive().optional(),
modalities: z.array(z.string()).optional(),
supportsReasoning: z.boolean().optional(),
+ // In the provider's own vocabulary; a model without a list runs at the
+ // provider default only.
+ efforts: z.array(z.enum(AI_MODEL_EFFORTS)).nonempty().optional(),
// Contractual per route rather than published anywhere, so an operator
// declares them and undefined means unasserted, not false. One Bedrock
// provider serves both eu.* and global.* models, hence per model.
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/__tests__/build-reasoning-provider-options.util.spec.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/__tests__/build-reasoning-provider-options.util.spec.ts
new file mode 100644
index 00000000000..ff7a6023a72
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/__tests__/build-reasoning-provider-options.util.spec.ts
@@ -0,0 +1,156 @@
+import {
+ AI_SDK_ANTHROPIC,
+ AI_SDK_AZURE,
+ AI_SDK_BEDROCK,
+ AI_SDK_GOOGLE,
+ AI_SDK_MISTRAL,
+ AI_SDK_OPENAI,
+ AI_SDK_XAI,
+} from 'src/engine/metadata-modules/ai/ai-models/constants/ai-sdk-package.const';
+import { buildReasoningProviderOptions } from 'src/engine/metadata-modules/ai/ai-models/utils/build-reasoning-provider-options.util';
+
+describe('buildReasoningProviderOptions', () => {
+ it('sends Anthropic adaptive thinking under the key it reads', () => {
+ expect(
+ buildReasoningProviderOptions({
+ modelId: 'anthropic/claude-opus-5',
+ sdkPackage: AI_SDK_ANTHROPIC,
+ supportsReasoning: true,
+ }),
+ ).toEqual({ anthropic: { thinking: { type: 'adaptive' } } });
+ });
+
+ it('adds the pinned effort next to Anthropic thinking', () => {
+ expect(
+ buildReasoningProviderOptions({
+ modelId: 'anthropic/claude-opus-5@low',
+ sdkPackage: AI_SDK_ANTHROPIC,
+ supportsReasoning: true,
+ effort: 'low',
+ }),
+ ).toEqual({
+ anthropic: { thinking: { type: 'adaptive' }, effort: 'low' },
+ });
+ });
+
+ it('sends an Anthropic effort on its own to a model without adaptive thinking', () => {
+ expect(
+ buildReasoningProviderOptions({
+ modelId: 'anthropic/claude-opus-4-5@medium',
+ sdkPackage: AI_SDK_ANTHROPIC,
+ supportsReasoning: true,
+ effort: 'medium',
+ }),
+ ).toEqual({ anthropic: { effort: 'medium' } });
+ });
+
+ it('sends Bedrock adaptive thinking under the key it reads', () => {
+ expect(
+ buildReasoningProviderOptions({
+ modelId: 'amazon-bedrock/eu.anthropic.claude-opus-4-7',
+ sdkPackage: AI_SDK_BEDROCK,
+ supportsReasoning: true,
+ }),
+ ).toEqual({ bedrock: { reasoningConfig: { type: 'adaptive' } } });
+ });
+
+ it('caps Bedrock reasoning at the pinned effort', () => {
+ expect(
+ buildReasoningProviderOptions({
+ modelId: 'amazon-bedrock/eu.anthropic.claude-opus-4-7@high',
+ sdkPackage: AI_SDK_BEDROCK,
+ supportsReasoning: true,
+ effort: 'high',
+ }),
+ ).toEqual({
+ bedrock: {
+ reasoningConfig: { type: 'adaptive', maxReasoningEffort: 'high' },
+ },
+ });
+ });
+
+ it('leaves a Claude model older than 4.6 without thinking', () => {
+ expect(
+ buildReasoningProviderOptions({
+ modelId: 'anthropic/claude-haiku-4-5-20251001',
+ sdkPackage: AI_SDK_ANTHROPIC,
+ supportsReasoning: true,
+ }),
+ ).toEqual({});
+ });
+
+ it('sends nothing to a Bedrock model that is not Claude', () => {
+ expect(
+ buildReasoningProviderOptions({
+ modelId: 'amazon-bedrock/us.deepseek.r1-v1:0',
+ sdkPackage: AI_SDK_BEDROCK,
+ supportsReasoning: true,
+ }),
+ ).toEqual({});
+ });
+
+ it('sends nothing to a model that does not reason', () => {
+ expect(
+ buildReasoningProviderOptions({
+ modelId: 'anthropic/claude-opus-5',
+ sdkPackage: AI_SDK_ANTHROPIC,
+ supportsReasoning: false,
+ }),
+ ).toEqual({});
+ });
+
+ it('sends nothing to a provider without a pinned effort', () => {
+ expect(
+ buildReasoningProviderOptions({
+ modelId: 'openai/gpt-5.6-sol',
+ sdkPackage: AI_SDK_OPENAI,
+ supportsReasoning: true,
+ }),
+ ).toEqual({});
+ });
+
+ it.each([
+ [
+ AI_SDK_OPENAI,
+ 'openai/gpt-5.6-sol@xhigh',
+ 'xhigh',
+ { openai: { reasoningEffort: 'xhigh' } },
+ ],
+ [
+ AI_SDK_AZURE,
+ 'azure/gpt-5.6-sol@none',
+ 'none',
+ { azure: { reasoningEffort: 'none' } },
+ ],
+ [
+ AI_SDK_GOOGLE,
+ 'google/gemini-3.7-flash@low',
+ 'low',
+ { google: { thinkingConfig: { thinkingLevel: 'low' } } },
+ ],
+ [
+ AI_SDK_MISTRAL,
+ 'mistral/mistral-small-latest@none',
+ 'none',
+ { mistral: { reasoningEffort: 'none' } },
+ ],
+ [
+ AI_SDK_XAI,
+ 'xai/grok-4.6@high',
+ 'high',
+ { xai: { reasoningEffort: 'high' } },
+ ],
+ ] as const)(
+ 'sends the pinned effort under the %s key',
+ (sdkPackage, modelId, effort, expected) => {
+ expect(
+ buildReasoningProviderOptions({
+ modelId,
+ sdkPackage,
+ supportsReasoning: true,
+ effort,
+ }),
+ ).toEqual(expected);
+ },
+ );
+});
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/__tests__/get-available-efforts.util.spec.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/__tests__/get-available-efforts.util.spec.ts
new file mode 100644
index 00000000000..5c58ab4e0e2
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/__tests__/get-available-efforts.util.spec.ts
@@ -0,0 +1,29 @@
+import {
+ AI_SDK_OPENAI_COMPATIBLE,
+ AI_SDK_XAI,
+} from 'src/engine/metadata-modules/ai/ai-models/constants/ai-sdk-package.const';
+import { getAvailableEfforts } from 'src/engine/metadata-modules/ai/ai-models/utils/get-available-efforts.util';
+
+describe('getAvailableEfforts', () => {
+ it('keeps only the levels the SDK can forward', () => {
+ expect(
+ getAvailableEfforts({
+ sdkPackage: AI_SDK_XAI,
+ efforts: ['low', 'medium', 'high', 'xhigh'],
+ }),
+ ).toEqual(['low', 'medium', 'high']);
+ });
+
+ it('offers nothing for a model without declared efforts', () => {
+ expect(getAvailableEfforts({ sdkPackage: AI_SDK_XAI })).toEqual([]);
+ });
+
+ it('offers nothing for an SDK without an effort option', () => {
+ expect(
+ getAvailableEfforts({
+ sdkPackage: AI_SDK_OPENAI_COMPATIBLE,
+ efforts: ['low', 'high'],
+ }),
+ ).toEqual([]);
+ });
+});
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/__tests__/is-adaptive-thinking-claude-model.util.spec.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/__tests__/is-adaptive-thinking-claude-model.util.spec.ts
new file mode 100644
index 00000000000..26a2f477a53
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/__tests__/is-adaptive-thinking-claude-model.util.spec.ts
@@ -0,0 +1,32 @@
+import { isAdaptiveThinkingClaudeModel } from 'src/engine/metadata-modules/ai/ai-models/utils/is-adaptive-thinking-claude-model.util';
+
+describe('isAdaptiveThinkingClaudeModel', () => {
+ it.each([
+ 'anthropic/claude-opus-5',
+ 'anthropic/claude-sonnet-5',
+ 'anthropic/claude-fable-5',
+ 'anthropic/claude-fable-5-1',
+ 'anthropic/claude-opus-4-8',
+ 'anthropic/claude-opus-4-7',
+ 'anthropic/claude-opus-4-6',
+ 'anthropic/claude-sonnet-4-6',
+ 'amazon-bedrock/eu.anthropic.claude-opus-4-7',
+ 'amazon-bedrock/global.anthropic.claude-opus-4-6-v1',
+ ])('is true for %s', (modelId) => {
+ expect(isAdaptiveThinkingClaudeModel(modelId)).toBe(true);
+ });
+
+ it.each([
+ 'anthropic/claude-haiku-4-5-20251001',
+ 'anthropic/claude-haiku-4-5',
+ 'anthropic/claude-sonnet-4-5-20250929',
+ 'anthropic/claude-opus-4-5-20251101',
+ 'anthropic/claude-opus-4-1-20250805',
+ 'anthropic/claude-3-7-sonnet-20250219',
+ 'amazon-bedrock/eu.anthropic.claude-haiku-4-5-20251001-v1:0',
+ 'my-provider/claude-custom-alias',
+ 'amazon-bedrock/us.deepseek.r1-v1:0',
+ ])('is false for %s', (modelId) => {
+ expect(isAdaptiveThinkingClaudeModel(modelId)).toBe(false);
+ });
+});
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/__tests__/parse-model-variant-id.util.spec.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/__tests__/parse-model-variant-id.util.spec.ts
new file mode 100644
index 00000000000..3da7f00fb44
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/__tests__/parse-model-variant-id.util.spec.ts
@@ -0,0 +1,31 @@
+import { parseModelVariantId } from 'src/engine/metadata-modules/ai/ai-models/utils/parse-model-variant-id.util';
+
+describe('parseModelVariantId', () => {
+ it('splits a variant id into its model and effort', () => {
+ expect(parseModelVariantId('anthropic/claude-opus-5@xhigh')).toEqual({
+ modelId: 'anthropic/claude-opus-5',
+ effort: 'xhigh',
+ });
+ });
+
+ it('keeps a Bedrock name that carries a colon intact', () => {
+ expect(
+ parseModelVariantId('amazon-bedrock/us.deepseek.r1-v1:0@high'),
+ ).toEqual({
+ modelId: 'amazon-bedrock/us.deepseek.r1-v1:0',
+ effort: 'high',
+ });
+ });
+
+ it('returns a plain id without an effort', () => {
+ expect(parseModelVariantId('openai/gpt-5.6-sol')).toEqual({
+ modelId: 'openai/gpt-5.6-sol',
+ });
+ });
+
+ it('treats a suffix that is not an effort as part of the id', () => {
+ expect(parseModelVariantId('custom/model@v2')).toEqual({
+ modelId: 'custom/model@v2',
+ });
+ });
+});
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/build-reasoning-provider-options.util.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/build-reasoning-provider-options.util.ts
new file mode 100644
index 00000000000..8fb894f3d99
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/build-reasoning-provider-options.util.ts
@@ -0,0 +1,66 @@
+import { type ProviderOptions } from '@ai-sdk/provider-utils';
+import { isDefined } from 'twenty-shared/utils';
+
+import {
+ AI_SDK_ANTHROPIC,
+ AI_SDK_AZURE,
+ AI_SDK_BEDROCK,
+ AI_SDK_GOOGLE,
+ AI_SDK_MISTRAL,
+ AI_SDK_OPENAI,
+ AI_SDK_XAI,
+} from 'src/engine/metadata-modules/ai/ai-models/constants/ai-sdk-package.const';
+import { type RegisteredAiModel } from 'src/engine/metadata-modules/ai/ai-models/services/ai-model-registry.service';
+import { isAdaptiveThinkingClaudeModel } from 'src/engine/metadata-modules/ai/ai-models/utils/is-adaptive-thinking-claude-model.util';
+
+export const buildReasoningProviderOptions = (
+ model: Pick<
+ RegisteredAiModel,
+ 'modelId' | 'sdkPackage' | 'supportsReasoning' | 'effort'
+ >,
+): ProviderOptions => {
+ const { effort } = model;
+ const thinksAdaptively =
+ model.supportsReasoning && isAdaptiveThinkingClaudeModel(model.modelId);
+
+ switch (model.sdkPackage) {
+ case AI_SDK_ANTHROPIC:
+ if (!thinksAdaptively && !isDefined(effort)) {
+ return {};
+ }
+
+ return {
+ anthropic: {
+ ...(thinksAdaptively ? { thinking: { type: 'adaptive' } } : {}),
+ ...(isDefined(effort) ? { effort } : {}),
+ },
+ };
+ case AI_SDK_BEDROCK:
+ if (!thinksAdaptively) {
+ return {};
+ }
+
+ return {
+ bedrock: {
+ reasoningConfig: {
+ type: 'adaptive',
+ ...(isDefined(effort) ? { maxReasoningEffort: effort } : {}),
+ },
+ },
+ };
+ case AI_SDK_OPENAI:
+ return isDefined(effort) ? { openai: { reasoningEffort: effort } } : {};
+ case AI_SDK_AZURE:
+ return isDefined(effort) ? { azure: { reasoningEffort: effort } } : {};
+ case AI_SDK_GOOGLE:
+ return isDefined(effort)
+ ? { google: { thinkingConfig: { thinkingLevel: effort } } }
+ : {};
+ case AI_SDK_MISTRAL:
+ return isDefined(effort) ? { mistral: { reasoningEffort: effort } } : {};
+ case AI_SDK_XAI:
+ return isDefined(effort) ? { xai: { reasoningEffort: effort } } : {};
+ default:
+ return {};
+ }
+};
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/get-available-efforts.util.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/get-available-efforts.util.ts
new file mode 100644
index 00000000000..3b82c479bff
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/get-available-efforts.util.ts
@@ -0,0 +1,12 @@
+import { type AiModelEffort } from 'twenty-shared/ai';
+
+import { AI_SDK_PACKAGE_EFFORTS } from 'src/engine/metadata-modules/ai/ai-models/constants/ai-sdk-package-efforts.const';
+import { type AiModelConfig } from 'src/engine/metadata-modules/ai/ai-models/types/ai-model-config.type';
+
+export const getAvailableEfforts = (
+ model: Pick<AiModelConfig, 'sdkPackage' | 'efforts'>,
+): AiModelEffort[] => {
+ const sdkEfforts = AI_SDK_PACKAGE_EFFORTS[model.sdkPackage] ?? [];
+
+ return (model.efforts ?? []).filter((effort) => sdkEfforts.includes(effort));
+};
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/is-adaptive-thinking-claude-model.util.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/is-adaptive-thinking-claude-model.util.ts
new file mode 100644
index 00000000000..feff0975825
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/is-adaptive-thinking-claude-model.util.ts
@@ -0,0 +1,18 @@
+import { isDefined } from 'twenty-shared/utils';
+
+const CLAUDE_VERSION_PATTERN =
+ /claude-(?:opus|sonnet|haiku|fable|mythos)-(\d+)(?:-(\d+))?/;
+
+// Adaptive thinking is accepted from Claude 4.6 on.
+export const isAdaptiveThinkingClaudeModel = (modelId: string): boolean => {
+ const match = CLAUDE_VERSION_PATTERN.exec(modelId);
+
+ if (!isDefined(match)) {
+ return false;
+ }
+
+ const major = Number(match[1]);
+ const minor = Number(match[2] ?? 0);
+
+ return major > 4 || (major === 4 && minor >= 6);
+};
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/parse-model-variant-id.util.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/parse-model-variant-id.util.ts
new file mode 100644
index 00000000000..5674a3a8688
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-models/utils/parse-model-variant-id.util.ts
@@ -0,0 +1,23 @@
+import { type AiModelEffort, isAiModelEffort } from 'twenty-shared/ai';
+
+const EFFORT_SEPARATOR = '@';
+
+// Catalog model names never contain `@` (Bedrock ids use `:`), so the last one
+// delimits the effort. Any other suffix is part of the id itself.
+export const parseModelVariantId = (
+ modelId: string,
+): { modelId: string; effort?: AiModelEffort } => {
+ const separatorIndex = modelId.lastIndexOf(EFFORT_SEPARATOR);
+
+ if (separatorIndex === -1) {
+ return { modelId };
+ }
+
+ const effort = modelId.slice(separatorIndex + 1);
+
+ if (!isAiModelEffort(effort)) {
+ return { modelId };
+ }
+
+ return { modelId: modelId.slice(0, separatorIndex), effort };
+};
diff --git a/packages/twenty-shared/src/ai/constants/ai-model-effort.const.ts b/packages/twenty-shared/src/ai/constants/ai-model-effort.const.ts
new file mode 100644
index 00000000000..61125bfd6c5
--- /dev/null
+++ b/packages/twenty-shared/src/ai/constants/ai-model-effort.const.ts
@@ -0,0 +1,14 @@
+// Every effort level a supported provider accepts, in ascending order. A model
+// lists the subset it takes in the catalog, since the set differs per model even
+// within one provider.
+export const AI_MODEL_EFFORTS = [
+ 'none',
+ 'minimal',
+ 'low',
+ 'medium',
+ 'high',
+ 'xhigh',
+ 'max',
+] as const;
+
+export type AiModelEffort = (typeof AI_MODEL_EFFORTS)[number];
diff --git a/packages/twenty-shared/src/ai/index.ts b/packages/twenty-shared/src/ai/index.ts
index 8b98c623aa4..4a061787d89 100644
--- a/packages/twenty-shared/src/ai/index.ts
+++ b/packages/twenty-shared/src/ai/index.ts
@@ -7,6 +7,8 @@
* |___/
*/
+export type { AiModelEffort } from './constants/ai-model-effort.const';
+export { AI_MODEL_EFFORTS } from './constants/ai-model-effort.const';
export { AI_SDK_PACKAGE_LABELS } from './constants/ai-sdk-package-labels.const';
export type { AiSdkPackage } from './constants/ai-sdk-packages.const';
export { AI_SDK_PACKAGES } from './constants/ai-sdk-packages.const';
@@ -54,6 +56,7 @@ export type { ModelConfiguration } from './types/model-configuration.type';
export type { NavigateAppToolOutput } from './types/NavigateAppToolOutput';
export { formatRecordReference } from './utils/format-record-reference.util';
export { inferAiSdkPackage } from './utils/infer-ai-sdk-package.util';
+export { isAiModelEffort } from './utils/is-ai-model-effort.util';
export { isAiSdkPackage } from './utils/is-ai-sdk-package.util';
export { isCompleteWorkspaceSetupToolPart } from './utils/is-complete-workspace-setup-tool-part.util';
export { isDataResidency } from './utils/is-data-residency.util';
diff --git a/packages/twenty-shared/src/ai/utils/is-ai-model-effort.util.ts b/packages/twenty-shared/src/ai/utils/is-ai-model-effort.util.ts
new file mode 100644
index 00000000000..97a064ec3f3
--- /dev/null
+++ b/packages/twenty-shared/src/ai/utils/is-ai-model-effort.util.ts
@@ -0,0 +1,7 @@
+import {
+ AI_MODEL_EFFORTS,
+ type AiModelEffort,
+} from '../constants/ai-model-effort.const';
+
+export const isAiModelEffort = (value: string): value is AiModelEffort =>
+ (AI_MODEL_EFFORTS as readonly string[]).includes(value);