Ai provider update #5254

BoDonkey · 2025-12-26T16:09:19Z

Summary

Summarize the changes briefly, including which issue/ticket this resolves. If it closes an existing Github issue, include "Closes #[issue number]"
This PR refactors the AI helper module to use a provider module structure, rather than being hardcoded for OpenAI. It also creates provider files for OpenAI, Anthropic, and Gemini. Finally, it adds a "skills" file that devs can use to speed their creation of custom provider files.
I will still need help before acceptance with the correct steps for the CHANGELOG in the new mono-repo

What are the specific steps to test this change?

For example:

Run the website and log in as an admin

Open a piece manager modal and select several pieces

Click the "Archive" button on the top left of the manager and confirm that it should proceed

Check that all pieces have been archived properly
I can provide any API keys that are needed for testing purposes.

Install the base module and any desired providers.
Test text generation in rich text - all three providers.
Test image generation and variation - OpenAI and Gemini.

What kind of change does this PR introduce?

(Check at least one)

Make sure the PR fulfills these requirements:

It includes a) the existing issue ID being resolved, b) a convincing reason for adding this feature, or c) a clear description of the bug it resolves
The changelog is updated
Related documentation has been updated
Related tests have been updated

If adding a new feature without an already open issue, it's best to open a feature request issue first and wait for approval before working on it.

Other information:

boutell

This is very cool stuff.

I'm pushing hard to get it right because I can see us pivoting this into core as the way we interface to models in general.

boutell · 2026-01-02T16:18:44Z

packages/ai-helper/index.js

+    // APOS_AI_HELPER_LOG_USAGE env var
+    // When true, usage data is logged to the console
+    // for cost tracking and auditing
+    logUsage: process.env.APOS_AI_HELPER_LOG_USAGE === 'true' || false,


Just check it for truthiness IMHO, but if not we must support 1 in particular for consistency with common practice including our own.

logUsage eliminated.

boutell · 2026-01-02T16:20:10Z

packages/ai-helper/index.js

+      self.aposAiHelperUsage = self.apos.db.collection('aposAiHelperUsage');
+      await self.aposAiHelperUsage.createIndex(
+        { createdAt: -1 },
+        { name: 'createdAt_-1' }


I'd remove this as it's not better than the default convention (I think it might be the default convention).

boutell · 2026-01-02T16:20:23Z

packages/ai-helper/index.js

+          userId: 1,
+          createdAt: -1
+        },
+        { name: 'userId_1_createdAt_-1' }


Same re: not adding name if it's just the same as the default convention, which is fine

Since we are removing the storage, this goes away.

boutell · 2026-01-02T16:20:48Z

packages/ai-helper/index.js

    modules: getBundleModuleNames()
  },
-  options: {
-    textModel: 'gpt-5.1',


We have bc provisions I assume?

Provisions added.

boutell · 2026-01-02T16:22:17Z

packages/ai-helper/index.js

+       * @param {boolean} [config.image] - Supports image generation
+       * @param {boolean} [config.imageVariation] - Supports image variations
+       */
+      registerProvider(provider, config) {


I actually think a full apostrophecms module is overkill for a provider. Not worth the startup overhead. I would go with passing an ordinary object. It's fine if it happens to be an apostrophe module.

I recognize people will want to override options of the individual providers, but they only need to do that for the ones they are actually using. So if you add textProviderOptions and imageProviderOptions to the main module that should address that concern.

Switched to factories.

boutell · 2026-01-02T16:30:12Z

packages/ai-helper/modules/@apostrophecms/ai-helper-anthropic/index.js

@@ -0,0 +1,120 @@
+module.exports = {


I think it should be an object and not a full apos module.

Developers can call registerProvider in project level init of the ai-helper module and pass their own provider objects. The main init would call it once for each of the standard providers.

boutell · 2026-01-02T16:32:46Z

packages/ai-helper/modules/@apostrophecms/ai-helper-anthropic/index.js

+
+        // Retry logic for transient failures
+        let lastError;
+        for (let attempt = 1; attempt <= 3; attempt++) {


Make the number of attempts configurable.

Added and documented as an option.

boutell · 2026-01-02T16:34:33Z

packages/ai-helper/modules/@apostrophecms/ai-helper-anthropic/index.js

+            lastError = e;
+
+            // Log for debugging
+            console.error(`Anthropic request failed (attempt ${attempt}/3):`, e.message);


Providers should be registered as functions that accept a services object with more appropriate logging functions (e.g. access to structured logging).

boutell · 2026-01-02T16:35:36Z

packages/ai-helper/modules/@apostrophecms/ai-helper-gemini/index.js

+        const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`;
+
+        // Gemini returns one image per request,
+        // so make multiple requests for multiple images


Parallel requests?

Refactored for parallel requests.

boutell · 2026-01-02T16:38:34Z

packages/ai-helper/modules/@apostrophecms/ai-helper-openai/index.js

+    // Default text generation settings
+    textMaxTokens: 1000,
+    imageModel: 'gpt-image-1-mini',
+    imageSize: '1024x1024',


I didn't check, but make sure these are standardized across providers whenever it makes sense.

Option names were standardized where possible.

boutell · 2026-01-06T17:01:58Z

packages/ai-helper/modules/@apostrophecms/ai-helper-rich-text-widget/index.js


-              const result = await provider.module.generateText(req, prompt, {
+              const result = await provider.generateText(req, prompt, {
                maxTokens: aiHelper.options.textMaxTokens,


I thought you moved this into a textProviderOptions object.

boutell · 2026-01-06T17:04:59Z

packages/ai-helper/index.js

+    const imageProvider = self.options.imageProvider;
+
+    // Register bundled providers
+    self.registerProvider(openaiProvider(


I think we're trying too hard to provide for multiple text providers, multiple image providers. We don't have a proven need for that yet, so we shouldn't prematurely implement it.

Registering a provider shouldn't immediately instantiate it. It just puts it on the list of candidates that are valid for the textProvider and imageProvider options.

I think this flow makes sense:

In init, call self.registerProviders, which calls registerProvider for the built-in choices, and is intended to be extended via extendMethods to register more providers

Then call activateProviders, which activates only the needed providers (one for text and one for images)

Looking at the providers, it's pretty cheap to instantiate. We basically store a simple object representing the meta AND the interface, it's quite smart. Splitting it to register and activate brings more chore IMO.

I always prefer the idea of explicit registration call (aiHelper.registerProvider(xxx)) vs extending (things can go south much easily).

boutell · 2026-01-06T17:10:41Z

packages/ai-helper/modules/@apostrophecms/ai-helper-rich-text-widget/index.js

    return {
      post: {
        async aiHelper(req) {
+          console.log('req.body', req.body);


myovchev

I'm giving a high level feedback - I like what I see. The provider contract is clean. It's flexible. I can see how even "non-active" providers (not pointed by the respective options) are still available and can be used in different scenarios programmatically (e.g. I can provide a runtime list in my custom project UI).

Few lint issue has to be fixed.

myovchev · 2026-01-07T14:48:41Z

...helper/modules/@apostrophecms/ai-helper-image/ui/apos/components/AposAiHelperImageEditor.vue

      });
+    },
+    createVariant() {
+      if (!this.variantPrompt.trim()) return;


Fixed. (Hate that rule though.)

myovchev · 2026-01-07T14:49:06Z

packages/ai-helper/index.js

+       * @returns {Array} Array of provider info
+       */
+      listProviders() {
+        return Array.from(self.providers.entries()).map(([name, info]) => ({


BoDonkey added 2 commits December 13, 2025 07:59

Modulize ai providers

8f76334

Updates logging and debugging

b601f10

BoDonkey requested a review from boutell December 26, 2025 16:09

BoDonkey marked this pull request as draft December 27, 2025 10:26

BoDonkey and others added 2 commits December 29, 2025 11:05

Update prompt input and corrected usage logging and storage

d3e5932

Merge branch 'main' into ai-provider-update

dead52a

BoDonkey marked this pull request as ready for review December 29, 2025 16:08

boutell requested changes Jan 2, 2026

View reviewed changes

BoDonkey added 3 commits January 5, 2026 14:30

Response to first comments

97d4bec

Error removal

4a69127

Add changeset

ed7e710

BoDonkey requested a review from boutell January 5, 2026 20:07

boutell requested a review from myovchev January 6, 2026 14:23

boutell requested changes Jan 6, 2026

View reviewed changes

myovchev requested changes Jan 7, 2026

View reviewed changes

Refactor to lib files

22d78c8

Ai provider update #5254

Are you sure you want to change the base?

Ai provider update #5254

Conversation

BoDonkey commented Dec 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What are the specific steps to test this change?

What kind of change does this PR introduce?

Make sure the PR fulfills these requirements:

Uh oh!

boutell left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

myovchev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

BoDonkey commented Dec 26, 2025 •

edited

Loading