Expose adapter reasoning, public metadata getter for all active providers

myovchev · myovchev · commit 78a34854d236 · 2026-08-04T19:05:22.000+03:00
diff --git a/packages/apostrophe/modules/@apostrophecms/ai-adapter-anthropic/index.js b/packages/apostrophe/modules/@apostrophecms/ai-adapter-anthropic/index.js
@@ -85,19 +85,28 @@ module.exports = {
           // model's ceiling: this adapter posts and waits for a whole
           // answer, so the default stays where one response comfortably
           // completes inside the timeout. The published ceilings are
-          // 128k for the Claude 5 models and 64k for Haiku 4.5
+          // 128k for the Claude 5 models and 64k for Haiku 4.5.
+          // `reasoning` declares what a call may pass, in this dialect's
+          // own vocabulary: effort levels on the adaptive models, the
+          // configured budget names on the budgeted ones.
           models: {
             'claude-haiku-4-5': {
+              label: 'Haiku 4.5',
               contextWindow: 200000,
-              maxOutputTokens: 32000
+              maxOutputTokens: 32000,
+              reasoning: reasoningValues('claude-haiku-4-5')
             },
             'claude-sonnet-5': {
+              label: 'Sonnet 5',
               contextWindow: 1000000,
-              maxOutputTokens: 64000
+              maxOutputTokens: 64000,
+              reasoning: reasoningValues('claude-sonnet-5')
             },
             'claude-opus-5': {
+              label: 'Opus 5',
               contextWindow: 1000000,
-              maxOutputTokens: 64000
+              maxOutputTokens: 64000,
+              reasoning: reasoningValues('claude-opus-5')
             }
           },
           validate() {
@@ -119,6 +128,11 @@ module.exports = {
             return self.normalizeError(error);
           }
         };
+        function reasoningValues(model) {
+          return self.options.adaptiveModels.includes(model)
+            ? [ ...EFFORT_LEVELS ]
+            : Object.keys(self.options.thinkingBudgets);
+        }
       },
       // Translate a normalized adapter request (see the engine's
       // buildRequest) to an Anthropic Messages API body: content parts
diff --git a/packages/apostrophe/modules/@apostrophecms/ai-adapter-google/index.js b/packages/apostrophe/modules/@apostrophecms/ai-adapter-google/index.js
@@ -41,6 +41,10 @@ const FINISH_REASONS = {
 const ASPECTS = [
   '1:1', '3:2', '2:3', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9'
 ];
+// The `thinkingLevel` values every current text model accepts
+const THINKING_LEVELS = Object.freeze([
+  'minimal', 'low', 'medium', 'high'
+]);
 // The normalized quality tiers → the dialect's output resolution
 // (the uppercase K is required)
 const IMAGE_SIZES = {
@@ -93,22 +97,31 @@ module.exports = {
               reasoning: 'high'
             }
           },
+          // `reasoning` is the dialect's `thinkingLevel` vocabulary,
+          // shared by both current text models
           models: {
             'gemini-3.1-flash-lite': {
+              label: 'Gemini 3.1 Flash-Lite',
               contextWindow: 1048576,
-              maxOutputTokens: 65536
+              maxOutputTokens: 65536,
+              reasoning: THINKING_LEVELS
             },
             'gemini-3.5-flash': {
+              label: 'Gemini 3.5 Flash',
               contextWindow: 1048576,
-              maxOutputTokens: 65536
+              maxOutputTokens: 65536,
+              reasoning: THINKING_LEVELS
             },
             'gemini-3.1-flash-image': {
+              label: 'Gemini 3.1 Flash Image',
               aspects: ASPECTS
             },
             'gemini-3-pro-image': {
+              label: 'Gemini 3 Pro Image',
               aspects: ASPECTS
             },
             'gemini-3.1-flash-lite-image': {
+              label: 'Gemini 3.1 Flash-Lite Image',
               aspects: ASPECTS
             }
           },
diff --git a/packages/apostrophe/modules/@apostrophecms/ai-adapter-openai-compatible/index.js b/packages/apostrophe/modules/@apostrophecms/ai-adapter-openai-compatible/index.js
@@ -22,6 +22,14 @@
 
 const image = require('../ai-adapter-openai/lib/image');
 
+// The `reasoning_effort` values the native service accepts on every
+// current text model. The native tools-request degrade drops reasoning
+// as behavior; the vocabulary itself is unchanged by it. Aliased
+// entries describe other services and declare their own.
+const REASONING_EFFORTS = Object.freeze([
+  'none', 'low', 'medium', 'high', 'xhigh', 'max'
+]);
+
 module.exports = {
   options: {
     // Per-request timeout in milliseconds; a timed-out call is a
@@ -66,16 +74,22 @@ module.exports = {
           },
           models: {
             'gpt-5.6-luna': {
+              label: 'GPT-5.6 Luna',
               contextWindow: 1050000,
-              maxOutputTokens: 128000
+              maxOutputTokens: 128000,
+              reasoning: REASONING_EFFORTS
             },
             'gpt-5.6-terra': {
+              label: 'GPT-5.6 Terra',
               contextWindow: 1050000,
-              maxOutputTokens: 128000
+              maxOutputTokens: 128000,
+              reasoning: REASONING_EFFORTS
             },
             'gpt-5.6-sol': {
+              label: 'GPT-5.6 Sol',
               contextWindow: 1050000,
-              maxOutputTokens: 128000
+              maxOutputTokens: 128000,
+              reasoning: REASONING_EFFORTS
             },
             ...image.models
           },
diff --git a/packages/apostrophe/modules/@apostrophecms/ai-adapter-openai/index.js b/packages/apostrophe/modules/@apostrophecms/ai-adapter-openai/index.js
@@ -19,6 +19,12 @@
 
 const image = require('./lib/image');
 
+// The `reasoning.effort` values every current text model accepts —
+// the whole GPT-5.6 tier shares one vocabulary
+const REASONING_EFFORTS = Object.freeze([
+  'none', 'low', 'medium', 'high', 'xhigh', 'max'
+]);
+
 module.exports = {
   options: {
     // Per-request timeout in milliseconds; a timed-out call is a
@@ -60,16 +66,22 @@ module.exports = {
           },
           models: {
             'gpt-5.6-luna': {
+              label: 'GPT-5.6 Luna',
               contextWindow: 1050000,
-              maxOutputTokens: 128000
+              maxOutputTokens: 128000,
+              reasoning: REASONING_EFFORTS
             },
             'gpt-5.6-terra': {
+              label: 'GPT-5.6 Terra',
               contextWindow: 1050000,
-              maxOutputTokens: 128000
+              maxOutputTokens: 128000,
+              reasoning: REASONING_EFFORTS
             },
             'gpt-5.6-sol': {
+              label: 'GPT-5.6 Sol',
               contextWindow: 1050000,
-              maxOutputTokens: 128000
+              maxOutputTokens: 128000,
+              reasoning: REASONING_EFFORTS
             },
             ...image.models
           },
diff --git a/packages/apostrophe/modules/@apostrophecms/ai-adapter-openai/lib/image.js b/packages/apostrophe/modules/@apostrophecms/ai-adapter-openai/lib/image.js
@@ -50,9 +50,11 @@ module.exports = async function image(deps, request) {
 // fixed to its three.
 module.exports.models = {
   'gpt-image-2': {
+    label: 'GPT Image 2',
     aspects: Object.keys(SIZES)
   },
   'gpt-image-1': {
+    label: 'GPT Image 1',
     aspects: [ '1:1', '3:2', '2:3' ]
   }
 };
diff --git a/packages/apostrophe/modules/@apostrophecms/ai/index.js b/packages/apostrophe/modules/@apostrophecms/ai/index.js
@@ -311,6 +311,53 @@ module.exports = {
         return info;
       },
 
+      /**
+       * Synchronous introspection of the whole routing configuration, shaped
+       * for building pickers: the resolved effort table with its default
+       * level, and every configured provider with its adapter's label,
+       * capabilities and merged per-model metadata. A model's optional
+       * `reasoning` array lists the values a call may pass as `reasoning`
+       * for it, in the provider's own vocabulary — declared by the adapter,
+       * extendable per model on the provider entry, and never enforced: the
+       * adapter keeps its own rejections, and a model without a declaration
+       * still answers. Everything returned is a copy, safe to serialize or
+       * amend, and nothing here reaches the browser unless the caller sends
+       * it there. Under mock mode with no providers the catalog is empty —
+       * `self.active` answers "is AI usable", this method answers "what is
+       * configured".
+       *
+       * @returns {AiModelCatalog}
+       */
+      modelCatalog() {
+        const providers = {};
+        for (const [ name, record ] of Object.entries(self.providers)) {
+          const models = {};
+          for (const [ id, meta ] of Object.entries(record.models)) {
+            models[id] = {
+              ...meta,
+              ...(meta.reasoning && { reasoning: [ ...meta.reasoning ] }),
+              ...(meta.aspects && { aspects: [ ...meta.aspects ] })
+            };
+          }
+          providers[name] = {
+            label: record.adapter.label,
+            capabilities: { ...record.capabilities },
+            models
+          };
+        }
+        const levels = {};
+        for (const [ level, row ] of Object.entries(self.effortTable)) {
+          levels[level] = { ...row };
+        }
+        return {
+          effort: {
+            default: self.effortDefault,
+            levels
+          },
+          providers
+        };
+      },
+
       /**
        * The AI permission seam: whether this AI action is permitted for `req`.
        * Same signature and semantics as
diff --git a/packages/apostrophe/modules/@apostrophecms/ai/lib/types.js b/packages/apostrophe/modules/@apostrophecms/ai/lib/types.js
@@ -246,8 +246,14 @@
  * provider entry's, merged, the entry winning.
  *
  * @typedef {object} AiModelMeta
+ * @property {string} [label] The model's human name, for pickers and
+ * receipts ("Opus 5"); the id stays the wire truth.
  * @property {number} [contextWindow]
  * @property {number} [maxOutputTokens]
+ * @property {string[]} [reasoning] The values a call may pass as its
+ * `reasoning` for this model, in the provider's own vocabulary.
+ * Informational: read back by modelCatalog, never enforced by the engine —
+ * the adapter keeps its own rejections.
  * @property {string[]} [aspects] The image ratios the model supports, as 'W:H'.
  */
 
@@ -265,6 +271,20 @@
  * @property {string[]} [aspects] Present for an image resolution.
  */
 
+/**
+ * What modelCatalog reports: the whole routing configuration, shaped for
+ * building pickers. Every object is a copy, safe to serialize or amend.
+ *
+ * @typedef {object} AiModelCatalog
+ * @property {{ default: string, levels: Object<string, { provider: string,
+ * model: string, reasoning?: string }> }} effort The resolved routing
+ * table and the level an effortless call lands on.
+ * @property {Object<string, { label: string,
+ * capabilities: Object<string, boolean>,
+ * models: Object<string, AiModelMeta> }>} providers Configured providers
+ * by name, each with its adapter's label and merged model metadata.
+ */
+
 /**
  * A provider adapter: the translation between the normalized protocol above and
  * one service's dialect. Registered with addAdapter and instantiated per
@@ -274,6 +294,7 @@
  * @typedef {object} AiAdapter
  * @property {string} name The registry name. A provider entry names it with
  *   `adapter`, or shares its own key with it.
+ * @property {string} label The service's human name ("Anthropic (Claude)").
  * @property {string} [envKey] The environment variable the key is read from
  *   unless the entry names its own.
  * @property {string} [baseUrl]
diff --git a/packages/apostrophe/test/ai-adapter-anthropic.js b/packages/apostrophe/test/ai-adapter-anthropic.js
@@ -1041,6 +1041,49 @@ describe('AI adapter: anthropic', function() {
     });
   });
 
+  describe('model metadata', function() {
+    it('labels every model', function() {
+      const { models } = adapter.adapter();
+      const labels = Object.fromEntries(
+        Object.entries(models).map(([ id, meta ]) => [ id, meta.label ])
+      );
+      assert.deepEqual(labels, {
+        'claude-haiku-4-5': 'Haiku 4.5',
+        'claude-sonnet-5': 'Sonnet 5',
+        'claude-opus-5': 'Opus 5'
+      });
+    });
+
+    it('declares effort levels as the reasoning of an adaptive model', function() {
+      const { models } = adapter.adapter();
+      const levels = [ 'low', 'medium', 'high', 'xhigh', 'max' ];
+      assert.deepEqual(models['claude-sonnet-5'].reasoning, levels);
+      assert.deepEqual(models['claude-opus-5'].reasoning, levels);
+    });
+
+    it('declares the configured budget names as the reasoning of a budgeted model', function() {
+      assert.deepEqual(
+        adapter.adapter().models['claude-haiku-4-5'].reasoning,
+        [ 'low', 'medium', 'high' ]
+      );
+      // The definition is built from the options, so an extended budget
+      // table reaches a declaration built afterwards
+      const saved = adapter.options.thinkingBudgets;
+      try {
+        adapter.options.thinkingBudgets = {
+          ...saved,
+          xhigh: 32768
+        };
+        assert.deepEqual(
+          adapter.adapter().models['claude-haiku-4-5'].reasoning,
+          [ 'low', 'medium', 'high', 'xhigh' ]
+        );
+      } finally {
+        adapter.options.thinkingBudgets = saved;
+      }
+    });
+  });
+
   describe('environment key', function() {
     before(async function() {
       process.env.APOS_ANTHROPIC_KEY = 'sk-env';
diff --git a/packages/apostrophe/test/ai-providers.js b/packages/apostrophe/test/ai-providers.js
diff --git a/packages/apostrophe/test/ai.js b/packages/apostrophe/test/ai.js
