@dxpr/ckeditor5-ai-agent

AI Agent for CKEditor 5

🤖 An AI-first user experience for content generation in CKEditor 5

Overview

🚀 Like ChatGPT but faster, and better at creating HTML content.

✍️ AI Agent is a CKEditor 5 plugin designed to integrate AI-assisted text generation within the CKEditor. The plugin allows users to interact with AI models like GPT-4o and many more to generate, modify, or enhance content directly within the editor.

🌐 AI Agent uses retrieval-augmented generation (RAG) and in-context learning to seamlessly integrate external web content into prompts.

🤖 Natively supports 365 models, with additional support for any self-hosted model via Ollama.

Video of AI Agent returning optimal HTML structure based on what is available in the toolbar, when a user prompt is "incorrect". After switching the editor configuration from "Full HTML" to "Basic HTML," an unordered list is generated instead of a table, using bold and normal-weight text to simulate some table-like structure.

Table of Contents

• Installation
• Configuration
• How to Use
• Features
• Usage examples
• Configuration options
• Developing the package
• Available scripts
• License

Installation

To install the AI Agent plugin in your CKEditor 5 setup:

1. Install the plugin via npm:

   npm install @dxpr/ckeditor5-ai-agent

Configuration

The AI Agent plugin can be configured through the EditorConfig interface. Define model behavior, including type, temperature, and tokens.

Example configuration:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ AiAgent, ... ],
        toolbar: [ 'AiAgent', ... ],
        aiAgent: {
            apiKey: 'YOUR_API_KEY' // required
        }
    } )
    .catch( error => {
        console.error( error );
    } );

How to Use

• Start a prompt with a slash command: /write about open source software.
• Create multiline prompts: Use Shift+Enter to break your prompt into lines.
• Add links for reference material: Include links in your prompt, AI fetches and integrates their content (RAG).
• No limit on links: Add as many links as you need; referenced content is automatically trimmed to fit the AI's context window.
• Use mid-sentence prompts: Insert prompts in the middle of a sentence by clicking the AI button in the toolbar.
• Cancel response streams: Press "Cancel" to terminate a response stream immediately, ensuring no tokens are wasted.

Basic Usage

Here are some examples of how to use the AI Agent plugin:

1. Basic Command

   /write about open source software

2. Compile Command with URLs

    /Create a best blog posts of the week blog, summarize each article in 100 words, add one image for every post, include read-more links:
    https://example.com/post-1
    https://example.com/post-2

You use shift+enter to add new line inside a single slash command.

AI Agent understands complex prompts and can handle complex HTML, here we ask for varied content structures with 3 levels of table nesting:

Video of AI Agent rendering complex HTML structures fast, rendering tokens in real-time as they are sent by the model.

Advanced Features

• RAG-enabled retrieval: Integrates web content into prompts dynamically.
• In-context learning: Automatically adapts responses based on surrounding content.
• Context-aware prompts: Auto-incorporates surrounding text for better response accuracy.
• Multilingual-ready: Supports CKEditor 5 language settings.
• Real-time response streaming: View generated content as it arrives.
• Customizable responses: Adjust formatting, HTML, tone, and content rules.
• Dynamic context size: Adapts based on cursor position and context limits.
• Advanced controls: Manage temperature, max tokens, and stop sequences.
• Multiple AI model support: Defaults to GPT-4o but configurable for others.
• Moderation API support: Adds content safety filters and moderation feedback.
• Custom endpoints: Use tailored AI APIs for specific needs.
• Debug mode: Detailed logs for troubleshooting.

Configuration Options

The AiAgent plugin can be configured through the EditorConfig interface. Here are the configuration options available:

General Settings

| Option | Type | Default | Description | |--------|------|---------|-------------| | engine | AiEngine? | 'openai' | AI engine to use: 'anthropic', 'cerebras', 'deepseek', 'google', 'groq', 'mistralai', 'ollama', 'openai', 'openrouter', 'xai' | | model | string? | 'gpt-4o' | The AI model to use | | apiKey | string | - | Your Open_AI key for authenticate | | temperature | number? | 0.7 | Controls the randomness of the AI output. Must be between 0 and 2 | | maxOutputTokens | number? | Model specific default from TOKEN_LIMITS | Maximum number of tokens the AI can generate in its response | | maxInputTokens | number? | Model specific default from TOKEN_LIMITS | Maximum number of tokens allowed in the combined prompt and context | | stopSequences | Array<string>? | [] | An array of stop sequences that will end the generation of content when encountered | | retryAttempts | number? | 1 | The number of times to retry fetching the AI response if the initial request fails | | promptSettings | object? | {} | Customize prompt components through overrides and additions | | promptSettings.overrides | Record<PromptComponentKey, string>? | - | Replace default rules for specific components | | promptSettings.additions | Record<PromptComponentKey, string>? | - | Add additional rules to specific components | | timeOutDuration | number? | 120000 | The duration in milliseconds to wait before timing out the request | | contextSize | number? | 75% of model's maxInputContextTokens | Maximum context window size in tokens | | editorContextRatio | number? | 0.3 | Upper limit of what portion of the context size is allocated for editor content | | endpointUrl | string? | - | The URL of the AI endpoint (only required when using custom engines or proxies) | | debugMode | boolean? | false | Enables debug mode for detailed logging | | streamContent | boolean? | true | Enables streaming mode for responses | | showErrorDuration | number? | 5000 | Duration in milliseconds for error message display | | moderationEnable | boolean? | false | Enables content moderation for AI responses | | moderationKey | string? | - | API key for content moderation service | | moderationDisableFlags | Array<ModerationFlagsTypes>? | - | Array of moderation flags to disable | | commandsDropdown | Array<{ title: string; items: Array<{ title: string; command: string; }>; }>? | Default menu with tone adjustment, content enhancement, and fix/improve commands | Specifies the commands available in the dropdown menu | | contentScope | string? | - | CSS selector that extends context gathering to include content from other CKEditor 5 instances found within the first matching ancestor element | | writesPerSecond | WritesPerSecond? | 10 | Specifies the maximum number of writes the AI Agent can perform per second. This setting helps control the rate of content generation, allowing for smoother performance and better resource management during high-load scenarios. |

Prompt Components

The plugin uses various prompt components to guide AI response generation. You can customize these through the promptSettings configuration.

Component Types

Each component can be customized using either overrides (to replace default rules) or additions (to add new rules):

• htmlFormatting: Rules for HTML generation
• contentStructure: Document structure guidelines
• tone: Language and tone settings
• responseRules: Core response generation rules
• inlineContent: Inline content handling rules
• imageHandling: Image element requirements
• referenceGuidelines: Rules for handling referenced content
• contextRequirements: Rules for context-aware generation

Default Values

Response Rules

Generate a response that addresses the <TASK>
If <SELECTED_CONTENT> exists, use only that content to answer the <TASK>, ignoring additional <CONTEXT>.

HTML Formatting

HTML Requirements:
Use only these tags: {{ALLOWED_HTML_TAGS}}.
Ensure proper tag nesting.
Use semantic HTML.
No inline styles.
First word must be HTML tag.
Output raw HTML without markdown code blocks (no ```html or ``` wrapping).

Content Structure

Organize information logically.
Use paragraphs.
Maintain consistent formatting.

Tone

Professional, Clear

Image Handling

Image Requirements:
Every <img> needs src and alt attributes.
Place images between content blocks, not inline with text.
Format src as: https://promptahuman.com/600x400@2x?bg_color=444444&text_color=ffffff&title=[file_name.png]&prompt=[Creative Brief in plain text, emoji allowed.].
Alt text must be descriptive. Creative brief = 10-20 words. File name respects picture type, image=jpg, animation=gif, video=mp4, etc.

Reference Guidelines

Generate new text that flows naturally with <CONTEXT>.
Ensure requested percentage of new content.

Context Requirements

Replace @@@cursor@@@ with content for <TASK>.
Return ONLY text replacing @@@cursor@@@ - surrounding text is READ-ONLY.
Never copy context text.
Verify zero duplication.
Analyze CONTEXT thoroughly.
Ensure response flows naturally.
Never include the string `@@@cursor@@@` in your response.

Customization Examples

Override default rules:

ClassicEditor.create(document.querySelector('#editor'), {
    plugins: [AiAgent],
    aiAgent: {
        promptSettings: {
            overrides: {
                'htmlFormatting': `HTML Requirements:
Use only <p> and <strong> tags
Always wrap text in paragraphs
No nested elements allowed
Keep HTML structure minimal
Validate all markup`
            }
        }
    }
});

Add additional rules:

ClassicEditor.create(document.querySelector('#editor'), {
    plugins: [AiAgent],
    aiAgent: {
        promptSettings: {
            additions: {
                'contentStructure': `
Keep paragraphs under 100 words
Start each section with a topic sentence
Use descriptive headings`
            }
        }
    }
});