@dxpr/ckeditor5-ai-agent v1.0.0-beta62

note: This project is not part of CKEditor premium, it is a free plugin created by DXPR

@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 478 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' ), {
        licenseKey: 'GPL',
        plugins: [ AiAgent, ... ],
        toolbar: [ 'aiAgentButton', 'aiAgentToneButton', ... ],
        aiAgent: {
            apiKey: 'YOUR_API_KEY',
            tonesDropdown: [
                {
                    label: 'Technical',
                    tone: 'Use technical language with precise terminology and detailed explanations.'
                },
                {
                    label: 'Casual',
                    tone: 'Write in a relaxed, conversational style using everyday language.'
                },
                {
                    label: 'Academic',
                    tone: 'Use formal academic language with proper citations and structured arguments.'
                }
            ]
        }
    } )
    .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

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:
<ALLOWED_TAGS>Use only these tags: a, blockquote, code, em, figcaption, h1, h2, h3, img, li, ol, p, pre, strong, table, td, tr, ul.</ALLOWED_TAGS>
<ALLOWED_CLASSES>Use only these classes: alert, alert-primary, card, badge, bg-primary.</ALLOWED_CLASSES>
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).

The <ALLOWED_TAGS> section is automatically populated with the list of HTML tags allowed in the editor, based on the editor's schema and the GeneralHtmlSupport configuration.

The <ALLOWED_CLASSES> section is automatically populated with either:

• A list of allowed CSS classes from the GeneralHtmlSupport configuration if any are defined
• Or a message indicating that no CSS classes should be used

These XML-like tags make it easier for the AI model to clearly identify the allowed elements and apply them correctly in the generated content.

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`
            }
        }
    }
});

Configuring Tone Options

The tonesDropdown configuration option allows you to customize the available tones in the AI Agent tone dropdown menu. When configured, your custom tones will be added to the default "Default values" option.

Example configuration:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        licenseKey: 'GPL',
        plugins: [ AiAgent, ... ],
        toolbar: [ 'aiAgentButton', 'aiAgentToneButton', ... ],
        aiAgent: {
            apiKey: 'YOUR_API_KEY',
            tonesDropdown: [
                {
                    label: 'Technical',
                    tone: 'Use technical language with precise terminology and detailed explanations.'
                },
                {
                    label: 'Casual',
                    tone: 'Write in a relaxed, conversational style using everyday language.'
                },
                {
                    label: 'Academic',
                    tone: 'Use formal academic language with proper citations and structured arguments.'
                }
            ]
        }
    } )
    .catch( error => {
        console.error( error );
    } );

Configuring Command Dropdown

The commandsDropdown configuration option allows you to define preset commands for transforming selected content. These commands are primarily designed to edit, enhance, or reformat existing content rather than generating new content from scratch.

Example configuration:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ AiAgent, ... ],
        toolbar: [ 'aiAgentButton', ... ],
        aiAgent: {
            apiKey: 'YOUR_API_KEY',
            commandsDropdown: [
                {
                    title: 'Transform Content',
                    items: [
                        {
                            title: 'Summarize',
                            command: 'Summarize this text in 3 bullet points'
                        },
                        {
                            title: 'Simplify',
                            command: 'Rewrite this to be more concise and easier to understand'
                        }
                    ]
                }
            ]
        }
    } )
    .catch( error => {
        console.error( error );
    } );

Development

This package uses Yarn as the package manager. Here are the main commands available for development:

Building

# Build the distribution files
yarn build:dist

# Build TypeScript files
yarn ts:build

# Build DLL files
yarn dll:build

# Clear TypeScript generated files
yarn ts:clear

Development Server

# Start development server
yarn start

# Serve DLL sample
yarn dll:serve