\n\n**Bring AI-powered content generation directly into your ApostropheCMS editing workflow.** Generate compelling text and stunning images from simple prompts, all without leaving the CMS. Choose your preferred AI provider (OpenAI, Anthropic Claude, or Google Gemini) or connect to enterprise AI services.\n\n## ⚠️ Beta / Experimental Module \n\n**This module is experimental and will remain in beta status.** It provides early access to AI-powered content generation features in ApostropheCMS, but you should expect:\n\n- **Functional but evolving**: Core features work well and are production-ready, but the UI/UX may not have the polish of finished ApostropheCMS modules\n- **Active development**: Features and APIs may change as we refine the AI integration experience\n- **Future migration**: Much of this functionality will eventually move into ApostropheCMS core as part of a comprehensive AI coordination system\n\n**Who should use this module:**\n- Developers comfortable with experimental features who want early access to AI capabilities\n- Teams willing to provide feedback to help shape ApostropheCMS AI features\n- Projects that can adapt to potential UI/API changes in future updates\n\n**Stability note:** While the module is marked as beta, it is used in production environments. The \"experimental\" designation reflects ongoing UI refinement rather than fundamental instability.\n\n## Why AI Helper? \n\n- **⚡ Accelerate Content Creation**: Generate high-quality text and images in seconds, not hours\n- **🎯 Stay in Your Workflow**: AI generation built directly into the rich text editor and media manager\n- **🔌 Your Choice of AI Provider**: Use OpenAI, Anthropic Claude, or Google Gemini - switch anytime\n\n### **Table of Contents**\n- [Installation](#installation)\n- [Configuration](#configuration)\n - [Enable AI Text Generation](#enable-ai-text-generation)\n - [(Optional) Customize System Prompt](#optional-customize-system-prompt)\n - [(Optional) Configure Security Headers](#optional-configure-security-headers)\n - [Mock Mode for Testing](#mock-mode-for-testing)\n- [Usage](#usage)\n - [Generating Images](#generating-images)\n - [Generating Text](#generating-text)\n- [Provider Configuration Options](#provider-configuration-options)\n - [OpenAI Provider](#openai-provider)\n - [Anthropic Provider](#anthropic-provider)\n - [Gemini Provider](#gemini-provider)\n- [Mix and Match Providers](#mix-and-match-providers)\n- [Bundled Providers](#bundled-providers)\n- [Provider Metadata](#provider-metadata)\n- [Custom AI Providers](#custom-ai-providers)\n - [Provider Architecture](#provider-architecture)\n - [Provider Registration](#provider-registration)\n - [Custom Provider Contract](#custom-provider-contract)\n - [Error Handling](#error-handling)\n - [Metadata](#metadata)\n - [Implementation Guidance](#implementation-guidance)\n- [API Endpoints](#api-endpoints)\n - [List Registered Providers](#list-registered-providers)\n- [💎 Ready for Enterprise AI Features?](#-ready-for-enterprise-ai-features)\n - [🚀 Pro AI Features](#-pro-ai-features)\n- [Need Help?](#need-help)\n- [License](#license)\n\n\n## Installation\nTo install the module, use the command line to run this command in an Apostrophe project's root directory:\n\n```bash\nnpm install @apostrophecms/ai-helper\n```\n\nAll providers (OpenAI, Anthropic, Gemini) are bundled with the main package - no separate installation needed.\n\n## Configuration\n\nConfigure the AI helper module in your `app.js` file:\n\n```javascript\nimport apostrophe from 'apostrophe';\n\napostrophe({\n root: import.meta,\n shortName: 'my-project',\n modules: {\n '@apostrophecms/ai-helper': {\n options: {\n // Choose which providers to use\n textProvider: 'openai', // 'openai', 'anthropic', or 'gemini'\n imageProvider: 'openai', // 'openai' or 'gemini'\n\n // Configure your text provider\n textProviderOptions: {\n apiKey: process.env.APOS_OPENAI_KEY, // or export APOS_OPENAI_KEY\n textModel: 'gpt-5.1',\n textMaxTokens: 1000\n },\n\n // Configure your image provider\n imageProviderOptions: {\n apiKey: process.env.APOS_OPENAI_KEY, // or export APOS_OPENAI_KEY\n imageModel: 'gpt-image-1-mini',\n imageSize: '1024x1024',\n imageQuality: 'medium',\n imageCount: 1\n }\n }\n }\n }\n});\n```\n> **Note:** Providers are selected at application startup via `app.js` configuration.\n> Switching providers at runtime via an admin UI is not currently supported.\n\n\n**API Keys:**\nEach provider requires its own API key. You can set them via:\n- Environment variables: `APOS_OPENAI_KEY`, `APOS_ANTHROPIC_KEY`, `APOS_GEMINI_KEY`\n- Configuration options: `textProviderOptions.apiKey` or `imageProviderOptions.apiKey`\n\n> Note:\n> You only need to provide keys for the services you will be using.\n\n### Enable AI Text Generation\n\nAdd the AI option to your rich text widget toolbar in any area configuration:\n\n```javascript\n// modules/article/index.js\nexport default {\n extend: '@apostrophecms/piece-type',\n fields: {\n add: {\n main: {\n type: 'area',\n options: {\n widgets: {\n '@apostrophecms/rich-text': {\n toolbar: [ 'styles', 'bold', 'italic', 'bulletList', 'orderedList' ],\n insert: [ 'ai' ], // Enable AI text generation\n styles: [\n { name: 'Heading', tag: 'h2' },\n { name: 'Subheading', tag: 'h3' },\n { name: 'Paragraph', tag: 'p' }\n ]\n }\n }\n }\n }\n }\n }\n};\n```\n\n### (Optional) Customize System Prompt\n\n>**Default System Prompt (with guardrails):**\n>```\n>You are a helpful text-generation assistant for CMS content. You generate text in Markdown format based on the given prompt. Do not include any meta-commentary, explanations, or offers to create additional versions. Output the content directly without preamble or postamble.\n>```\n\nCustomize how the AI generates text by modifying the system prompt. This can be configured **globally** (affects all rich text widgets) or **per-area** (specific areas only). Note that any prompt passed to a widget in an area will override the prompt set globally.\n\n**Precedence order:**\n1. Per-area prompt\n2. Global prompt\n3. Default guardrails\n\n**Global Configuration (in app.js):**\n```javascript\nimport apostrophe from 'apostrophe';\n\napostrophe({\n root: import.meta,\n modules: {\n '@apostrophecms/rich-text-widget': {\n options: {\n customSystemPrompt: 'Write in a professional, technical tone suitable for enterprise documentation.',\n appendSystemPrompt: true // Append to default guardrails instead of replacing\n }\n }\n }\n});\n```\n\n**Per-Area Configuration:**\n```javascript\n// modules/article/index.js\nexport default {\n extend: '@apostrophecms/piece-type',\n fields: {\n add: {\n main: {\n type: 'area',\n options: {\n widgets: {\n '@apostrophecms/rich-text': {\n toolbar: [ 'styles', 'bold', 'italic', 'bulletList', 'orderedList' ],\n insert: [ 'ai' ],\n // Customize AI behavior for this specific area\n customSystemPrompt: 'Write in a casual, conversational tone for blog content.',\n appendSystemPrompt: true\n }\n }\n }\n }\n }\n }\n};\n```\n\n**Options:**\n- `customSystemPrompt` - Your custom instructions for the AI\n- `appendSystemPrompt` - When `true`, appends your prompt to the default guardrails. When `false`, replaces them entirely.\n\n> **Tip:** Set `appendSystemPrompt: true` to keep the default guardrails (Markdown formatting, no meta-commentary) while adding your brand voice or style requirements. Per-area configuration overrides global settings.\n\n### (Optional) Configure Security Headers\n\nIf using the `@apostrophecms/security-headers` module, add AI image sources:\n\n```javascript\n// modules/@apostrophecms/security-headers/index.js\nexport default {\n options: {\n policies: {\n ai: {\n 'img-src': '*.blob.core.windows.net' // OpenAI image URLs\n }\n }\n }\n};\n```\n**Note:** This is an example only. The exact `img-src` value depends on the AI provider and region you are using.\n\n### Mock Mode for Testing\n\nFor offline development and testing without API calls or costs:\n\n```bash\nexport APOS_AI_HELPER_MOCK=true\n```\n\nWhen enabled:\n- Text generation returns pre-defined sample content\n- Image generation returns placeholder images\n- No API keys required\n- No external network calls made\n- Instant responses for rapid iteration\n\n> **Note:** Mock mode metadata may not match actual provider responses exactly.\n\n## Usage\n\n### Generating Images\n\n1. Add an image widget to your page\n2. Click \"Browse\" to open the media manager\n3. Click the 🤖 robot button in the upper right\n4. Enter a description and click \"Generate\"\n5. Review the generated image(s) (1 is the default)\n6. Click \"Select\" to import to media library, \"Variants\" for variations, or \"Delete\"\n\n**Note:** Generated images expire after 1 hour if not imported to your media library.\n\n### Generating Text\n\n> **Note:** Generated content may include headings, bullet lists, bold, italic, and other formatting. Make sure your rich text widget toolbar includes the formatting options you want to preserve (e.g., `toolbar: [ 'styles', 'bold', 'italic', 'bulletList', 'orderedList' ]`). Unsupported formatting will be stripped when inserted.\n\n1. In a rich text widget, press `/` at the start of a line\n2. Choose \"Generate Text\"\n3. Enter your prompt (be specific!)\n4. Click \"Generate\"\n\n**Prompt Tips:**\n- Specify a word count: \"Write 200 words about sustainable packaging\"\n- Request specific formats: \"Write a bulleted list of 5 benefits of...\"\n- Ask for structure: \"Write an article with 3 sections about cloud migration\"\n- Include tone: \"Write a friendly, conversational guide to...\"\n\n## Provider Configuration Options\n\nEach provider supports specific configuration parameters through `textProviderOptions` and `imageProviderOptions`:\n\n### OpenAI Provider\n```javascript\n'@apostrophecms/ai-helper': {\n options: {\n textProvider: 'openai',\n imageProvider: 'openai',\n\n textProviderOptions: {\n apiKey: process.env.APOS_OPENAI_KEY,\n textModel: 'gpt-5.1', // Text model to use\n textMaxTokens: 1000, // Max tokens for text generation\n textRetries: 3 // Times to reattempt generation on timeout\n },\n\n imageProviderOptions: {\n apiKey: process.env.APOS_OPENAI_KEY,\n imageModel: 'gpt-image-1-mini', // Image model to use\n imageSize: '1024x1024', // Image dimensions\n imageQuality: 'medium', // 'low', 'medium', or 'high'\n imageCount: 1 // Number of images to generate\n }\n }\n}\n```\n\n### Anthropic Provider\n```javascript\n'@apostrophecms/ai-helper': {\n options: {\n textProvider: 'anthropic',\n\n textProviderOptions: {\n apiKey: process.env.APOS_ANTHROPIC_KEY,\n textModel: 'claude-sonnet-4-20250514', // Claude model to use\n textMaxTokens: 1000, // Max tokens for text generation\n textRetries: 3 // Times to reattempt generation on timeout\n }\n }\n}\n```\n\n**Note:** Anthropic does not support image generation. Use OpenAI or Gemini for images.\n\n### Gemini Provider\n```javascript\n'@apostrophecms/ai-helper': {\n options: {\n textProvider: 'gemini',\n imageProvider: 'gemini',\n\n textProviderOptions: {\n apiKey: process.env.APOS_GEMINI_KEY,\n textModel: 'gemini-2.5-flash-lite', // Text model to use\n textMaxTokens: 1000, // Max tokens for text generation\n textRetries: 3 // Times to reattempt generation on timeout\n },\n\n imageProviderOptions: {\n apiKey: process.env.APOS_GEMINI_KEY,\n imageModel: 'gemini-2.5-flash-image', // Image model to use\n imageAspectRatio: '1:1', // '1:1', '16:9', or '9:16'\n imageCount: 1 // Number of images to generate\n }\n }\n}\n```\n\n**Note:** Gemini uses `imageAspectRatio` instead of `imageSize`.\n\n> The values shown are default values used for all generations. Future versions may support per-request options through the UI.\n\n## Mix and Match Providers\n\nUse different providers for text and images to optimize for cost, quality, or capability:\n\n```javascript\nimport apostrophe from 'apostrophe';\n\napostrophe({\n root: import.meta,\n modules: {\n '@apostrophecms/ai-helper': {\n options: {\n textProvider: 'anthropic', // Use Claude for text generation\n imageProvider: 'gemini', // Use Gemini for image generation\n\n textProviderOptions: {\n apiKey: process.env.APOS_ANTHROPIC_KEY,\n textModel: 'claude-sonnet-4-20250514'\n },\n\n imageProviderOptions: {\n apiKey: process.env.APOS_GEMINI_KEY,\n imageModel: 'gemini-2.5-flash-image',\n imageAspectRatio: '16:9'\n }\n }\n }\n }\n});\n```\n\n**Note:** Provider switching is currently configured in `app.js`. A future admin UI may allow switching providers without code changes.\n\n## Bundled Providers\n\nAll providers are included with `@apostrophecms/ai-helper` - no separate installation needed. They are implemented as lightweight factory functions and configured through `textProviderOptions` and `imageProviderOptions`.\n\n**OpenAI** (`textProvider: 'openai'` / `imageProvider: 'openai'`)\n- Text generation (GPT models)\n- Image generation (GPT Image models)\n- Image variations\n- Uses `imageSize` parameter (e.g., '1024x1024')\n\n**Anthropic** (`textProvider: 'anthropic'`)\n- Text generation (Claude models)\n- No image generation support\n\n**Gemini** (`textProvider: 'gemini'` / `imageProvider: 'gemini'`)\n- Text generation (Gemini models)\n- Image generation (Gemini Image models)\n- Image variations\n- Uses `imageAspectRatio` parameter (e.g., '1:1', '16:9', '9:16')\n\n## Provider Metadata\n\nAll providers return metadata with each generation, including:\n- Model used\n- Token counts and usage statistics\n- Provider-specific details (stop reasons, timestamps, etc.)\n\n**For text generation**, metadata is returned alongside the generated content in the API response. This allows you to capture usage information if needed for custom auditing or analytics at the project level.\n\n**For image generation**, metadata is stored temporarily in the `aposAiHelperImages` collection as `providerMetadata` on each generated image. This data persists for 1 hour (until cleanup) or until the image is imported to your media library.\n\nThe module does not automatically log or persist this metadata beyond what's needed for operation. If you need detailed auditing, cost tracking, or analytics, you can extend the relevant modules to capture and process this data according to your requirements.\n\n## Custom AI Providers\n\nIn addition to the bundled OpenAI, Anthropic, and Gemini providers, `@apostrophecms/ai-helper` supports **custom AI providers** for organizations that need to integrate enterprise platforms or internal AI services\n(e.g. AWS Bedrock, Azure OpenAI, self-hosted models).\n\n### Provider Architecture\n\nThe AI Helper uses a two-phase provider system:\n\n1. **Registration** - Providers register their factory function and metadata (capabilities, label)\n2. **Activation** - The core module instantiates only the providers actually configured for use\n\nThis means you can register multiple providers without the overhead of instantiating unused services.\n\n### Provider Registration\n\nCustom providers register a **factory function** along with metadata. The factory function\nwill be called by the core module during activation if the provider is configured for use.\n\nProviders can be implemented either:\n\n- As a **dedicated ApostropheCMS module**, or\n- As a **factory function** registered during another module's initialization\n\nBoth patterns must register a factory function - the AI Helper core handles instantiation.\n\n---\n\n### Custom Provider Contract\n\nCustom providers must implement a well-defined contract so the AI Helper can normalize behavior across different AI services.\n\n> **Streaming responses are not currently supported.**\n> Providers must return complete results for text and image generation.\n> Partial or incremental responses will be ignored.\n\n---\n\n#### Provider Registration API\n\nProviders register using `registerProvider(name, factoryInfo)`:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `name` | `string` | Unique provider identifier (e.g. `\"bedrock\"`) |\n| `factoryInfo.factory` | `function` | Factory function `(apos, textOpts, imageOpts) => provider` |\n| `factoryInfo.label` | `string` | Human-readable name for admin UI |\n| `factoryInfo.capabilities` | `object` | Declares supported features |\n\nExample:\n```javascript\naiHelper.registerProvider('bedrock', {\n factory: bedrockFactory,\n label: 'AWS Bedrock',\n capabilities: {\n text: true,\n image: false,\n imageVariation: false\n }\n});\n```\n\nThe factory function will be called with:\n- `apos` - ApostropheCMS instance\n- `textOpts` - Options from `textProviderOptions`\n- `imageOpts` - Options from `imageProviderOptions`\n\nIf a custom provider registers using the same name as a bundled provider, it will override the bundled implementation.\n\n---\n\n#### Required Provider Properties\n\nThe provider object **returned by the factory** must include:\n\n| Property | Type | Description |\n|--------|------|-------------|\n| `name` | `string` | Provider identifier (should match registration name) |\n| `label` | `string` | Human-readable name |\n| `capabilities` | `object` | Supported features |\n| `validate` | `function` | Configuration validation method |\n\nPlus methods for each declared capability (see below).\n\n---\n\n#### Required Methods\n\nProviders must implement methods that correspond to their declared capabilities.\n\n---\n\n##### `validate()`\n\n* Called during provider activation (after factory instantiation)\n* Must throw an error if required configuration is missing\n* Should be a no-op when `APOS_AI_HELPER_MOCK` is enabled\n\nUsed to:\n\n* Verify API keys or credentials\n* Validate required options\n* Fail fast on misconfiguration\n\n---\n\n##### `generateText(req, prompt, options)`\n\n**Required if `capabilities.text === true`**\n\n* Generates text content from a prompt\n* Must return the full generated result\n\nExpected return shape:\n```ts\n{\n content: string, // Markdown or HTML\n metadata?: object // Usage, model, provider-specific data\n}\n```\n\n---\n\n##### `generateImage(req, prompt, options)`\n\n**Required if `capabilities.image === true`**\n\n* Generates one or more images from a prompt\n* Must return complete image data\n\nExpected return shape:\n```ts\n[\n {\n type: 'url' | 'base64',\n data: string,\n metadata?: object\n }\n]\n```\n\n---\n\n##### `generateImageVariation(req, image, prompt, options)`\n\n**Required if `capabilities.imageVariation === true`**\n\n* Generates a variant of an existing image based on an additional prompt or default\n\nExpected return shape is the same as `generateImage`.\n\n---\n\n### Error Handling\n\n* Providers should throw standard JavaScript `Error` objects\n* The AI Helper will normalize errors into user-facing messages\n* Provider-specific error details may be included in metadata when available\n\n---\n\n### Metadata\n\nProviders may return provider-specific metadata, such as:\n\n* Model name\n* Token usage\n* Stop reasons\n* Timestamps or request IDs\n\nMetadata is:\n\n* Returned with text generation responses\n* Temporarily stored for image generation (until import or cleanup)\n\n---\n\n### Implementation Guidance\n\nDetailed implementation examples, testing guidance, and edge-case handling\nare intentionally excluded from this README.\n\nFor full implementation details, see:\n\n* **`provider-creator.md`** in this repository\n\nThis file can also be added to AI-assisted development tools\n(e.g. Claude Projects, Cursor workspaces) to help generate\nprovider implementations safely and consistently.\n\n## API Endpoints\n\n### List Registered Providers\n\nQuery which AI providers are available for registration (whether currently active or not):\n```javascript\nconst aiHelper = apos.modules['@apostrophecms/ai-helper'];\nconst providers = aiHelper.listRegisteredProviders();\n\nconsole.log(providers);\n// [\n// {\n// name: 'openai',\n// label: 'OpenAI',\n// capabilities: { text: true, image: true, imageVariation: true }\n// },\n// {\n// name: 'anthropic',\n// label: 'Anthropic (Claude)',\n// capabilities: { text: true, image: false, imageVariation: false }\n// },\n// {\n// name: 'gemini',\n// label: 'Google Gemini',\n// capabilities: { text: true, image: true, imageVariation: true }\n// }\n// ]\n```\n\nThis is useful for debugging provider registration, building admin UIs, or when creating custom providers that need to check what's already available.\n\n## 💎 Ready for Enterprise AI Features?\n\n**Love AI Helper but need advanced capabilities?** Upgrade to **ApostropheCMS Pro** to unlock AI-powered features that transform your content workflow:\n\n### 🚀 Pro AI Features\n- **🌍 AI-Powered Translation** - Automatically translate content into 100+ languages using DeepL, Google Translate, or Azure\n- **🔍 AI SEO Assistant** - Generate optimized meta descriptions, titles, and content recommendations\n\n**[Contact our team](https://apostrophecms.com/contact-us)** to learn about Pro licensing and enterprise AI capabilities.\n\n---\n\n## Need Help?\n\n- **Documentation**: [ApostropheCMS Documentation](https://apostrophecms.com/docs/)\n- **Community Support**: [Join our Discord](https://discord.com/invite/HwntQpADJr)\n- **Professional Support**: [Contact us](https://apostrophecms.com/contact-us) for dedicated support packages\n- **Issues & Feedback**: [GitHub Issues](https://github.com/apostrophecms/apostrophe/issues) - Your feedback helps shape future AI features!\n\n## License\n\nMIT\n\n---\n\n
![\"ApostropheCMS](\"https://raw.githubusercontent.com/apostrophecms/apostrophe/main/logo.svg\"){kind=logo}
\n\n ![](\"https://img.shields.io/badge/MADE%20FOR%20ApostropheCMS-000000.svg?style=for-the-badge&logo=Apostrophe&labelColor=6516dd\"){kind=icon}
\n ![\"\"](\"https://img.shields.io/discord/517772094482677790?color=5865f2&label=Join%20the%20Discord&logo=discord&logoColor=fff&labelColor=000&style=for-the-badge&logoWidth=20\")
\n ![\"\"](\"https://img.shields.io/static/v1?style=for-the-badge&labelColor=000000&label=License&message=MIT&color=3DA639\")
\n