@ckeditor/ckeditor5-ai
Version:
AI features for CKEditor 5.
449 lines (448 loc) • 16.4 kB
TypeScript
/**
* @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
*/
/**
* @module ai/aiassistant/aiassistant
* @publicApi
*/
import { type Locale } from 'ckeditor5/src/utils.js';
import { Plugin, type Editor } from 'ckeditor5/src/core.js';
import { AIAssistantUI } from './aiassistantui.js';
import { AIAssistantEditing } from './aiassistantediting.js';
import type { OpenAITextAdapterConfig } from './adapters/openaitextadapter.js';
import type { AIAWSTextAdapterConfig } from './adapters/awstextadapter.js';
/**
* AI assistant plugin that allows you to use external AI models to generate content or improve existing content.
*
* The feature uses following {@link module:ai/aiassistant/adapters/aitextadapter~AITextAdapterRequestData#actionId `actionId`} values:
*
* * `aiAssistant:command:<commandId>` for the predefined commands, where `<commandId>` is the ID of the predefined command,
* * `aiAssistant:custom` for custom queries provided by the user.
*/
export declare class AIAssistant extends Plugin {
/**
* @inheritDoc
*/
static get requires(): readonly [typeof AIAssistantUI, typeof AIAssistantEditing];
/**
* @inheritDoc
*/
static get pluginName(): "AIAssistant";
/**
* @inheritDoc
*/
static get isOfficialPlugin(): true;
/**
* @inheritDoc
*/
static get isPremiumPlugin(): true;
/**
* @inheritDoc
*/
constructor(editor: Editor);
}
/**
* A function that returns the list of the default AI commands definitions in the given localization context.
*/
export declare function getDefaultAICommands(locale: Locale): Array<AIGroupDefinition>;
/**
* The configuration of the AI Assistant feature.
*
* The properties defined in this config are set in the `config.ai.assistant` namespace.
*
* ```ts
* ClassicEditor
* .create( editorElement, {
* ai: {
* assistant: {
* // AI Assistant configuration.
* }
* }
* } )
* .then( ... )
* .catch( ... );
* ```
*
* See {@link module:ai/aiconfig~AIConfig the full AI configuration}.
*
* See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
*/
export interface AIAssistantConfig {
/**
* A list of all AI commands groups definitions to be displayed in the `'aiCommands'` UI dropdown.
*
* Setting this property will overwrite the default list of predefined commands.
*
* You can avoid creating any groups by providing a list of command definitions directly. In this case,
* commands will render as a flat list in the user interface.
*
* The default configuration is as follows. It can be obtained through {@link ~getDefaultAICommands}:
*
* ```json
* [ {
* groupId: 'editOrReview',
* groupLabel: 'Edit or review',
* commands: [
* {
* id: 'improveWriting',
* label: 'Improve writing',
* prompt: 'Fix spelling mistakes, use proper grammar and apply good writing practices. Do not lose the original meaning.'
* },
* {
* id: 'makeShorter',
* label: 'Make shorter',
* prompt: 'Remove any repetitive, redundant, or non-essential writing in this content ' +
* 'without changing the meaning or losing any key information.'
* },
* {
* id: 'makeLonger',
* label: 'Make longer',
* prompt: 'Improve this content by using descriptive language and inserting more information and more detailed explanations.'
* },
* {
* id: 'simplifyLanguage',
* label: 'Simplify language',
* prompt: 'Simplify the writing style of this content ' +
* 'and reduce the complexity, so that the content is easy to understand.'
* }
* ]
* },
* {
* groupId: 'generate',
* groupLabel: 'Generate from selection',
* commands: [
* {
* id: 'summarize',
* label: 'Summarize',
* prompt: 'Summarize this content into one paragraph of text. Include only the key ideas and conclusions. Keep it short. '
* },
* {
* id: 'continue',
* label: 'Continue',
* prompt: 'Start with the provided content and write at the end of it continuing this topic. Keep the added part short.'
* }
* ]
* },
* {
* groupId: 'changeTone',
* groupLabel: 'Change tone',
* commands: [
* {
* id: 'professional',
* label: 'Professional',
* prompt: 'Improve using polished, formal, and respectful language ' +
* 'to convey professional expertise and competence.'
* },
* {
* id: 'casual',
* label: 'Casual',
* prompt: 'Improve using casual, informal language to convey a casual conversation with a real person.'
* },
* {
* id: 'direct',
* label: 'Direct',
* prompt: 'Improve using direct language using only the essential information.'
* },
* {
* id: 'confident',
* label: 'Confident',
* prompt: 'Improve using compelling, optimistic language to convey confidence in the writing.'
* },
* {
* id: 'friendly',
* label: 'Friendly',
* prompt: 'Improve using friendly, comforting language, to convey understanding and empathy.'
* }
* ]
* },
* {
* groupId: 'changeStyle',
* groupLabel: 'Change style',
* commands: [
* {
* id: 'business',
* label: 'Business',
* prompt: 'Rewrite this content as a business professional with formal language.'
* },
* {
* id: 'legal',
* label: 'Legal',
* prompt: 'Rewrite this content as a legal professional using valid legal terminology.'
* },
* {
* id: 'journalism',
* label: 'Journalism',
* prompt: 'Rewrite this content as a journalist using engaging language to convey the importance of the information.'
* },
* {
* id: 'poetic',
* label: 'Poetic',
* prompt: 'Rewrite this content as a poem using poetic techniques without losing the original meaning.'
* }
* ]
* },
* {
* groupId: 'translate',
* groupLabel: 'Translate',
* commands: [
* {
* id: 'translateEnglish',
* label: 'English',
* prompt: 'Translate the content to English language.'
* },
* {
* id: 'translateSpanish',
* label: 'Spanish',
* prompt: 'Translate the content to Spanish language.'
* },
* {
* id: 'translatePortuguese',
* label: 'Portuguese',
* prompt: 'Translate the content to Portuguese language.'
* },
* {
* id: 'translateGerman',
* label: 'German',
* prompt: 'Translate the content to German language.'
* },
* {
* id: 'translateFrench',
* label: 'French',
* prompt: 'Translate the content to French language.'
* },
* {
* id: 'translateChinese',
* label: 'Simplified Chinese',
* prompt: 'Translate the content to Simplified Chinese language.'
* },
* {
* id: 'translateHindi',
* label: 'Hindi',
* prompt: 'Translate the content to Hindi language.'
* },
* {
* id: 'translateArabic',
* label: 'Arabic',
* prompt: 'Translate the content to Arabic language.'
* }
* ]
* } ]
* ```
*/
commands?: Array<AIGroupDefinition> | Array<AICommandDefinition>;
/**
* A list of additional AI commands groups definitions that will extend
* {@link module:ai/aiassistant/aiassistant~AIAssistantConfig#commands default commands}.
*
* You can define new AI commands groups or add new AI commands to existing groups. If you add AI commands to an existing group,
* you do not need to specify `groupLabel` property. Use the (optional) `order` property to control the position of new groups
* and commands.
*
* An example configuration:
*
* ```json
* {
* assistant: {
* extraCommandGroups: [
* // Add an AI command to an existing group:
* {
* groupId: 'changeTone',
* commands: [
* {
* id: 'sad',
* label: 'Sad',
* prompt: 'Rewrite this text to make it sound sad and depressing.',
* // You can specify the position of this command among existing ones. Commands use zero-based numbering.
* order: 2
* }
* ]
* },
* // Create a new AI commands group:
* {
* groupId: 'transformations',
* groupLabel: 'Transformations',
* // You can specify the position of this group among existing ones. Groups use zero-based numbering.
* order: 3,
* commands: [
* {
* id: 'addEmojis',
* label: 'Add emojis',
* prompt: 'Analyze each sentence of this text. After each sentence add an emoji that summarizes the sentence.'
* },
* // ...
* ]
* },
* ],
* // ...
* }
* }
* ```
*/
extraCommandGroups?: Array<AIGroupDefinition>;
/**
* A list of ids of AI commands and ids of commnad groups to be removed.
*
* Learn more about {@link module:ai/aiassistant/aiassistant~AICommandDefinition command definition and its id}.
*
* An example configuration:
*
* ```json
* {
* assistant: {
* removeCommands: [
* 'improveWriting',
* 'changeTone',
* // ...
* ],
* // ...
* }
* }
* ```
*/
removeCommands?: Array<string>;
/**
* An additional CSS class name (or names) added to the AI assistant content area (model response area).
*
* Because the content area is usually detached from the flow of the document, this configuration
* allows for better integration with application's stylesheets and improves the consistency of content
* styles.
*/
contentAreaCssClass?: string;
/**
* The AI assistant feature will be disabled if the document selection includes any of these elements.
*
* Use this property if AI assistant does not work properly with your custom features.
*
* Currently, by default, AI assistant is disabled for following model elements:
*
* * Media embed (`'media'`) -- does not display in response area,
* * HTML embed (`'rawHtml'`) -- sometimes does not display in response area, security uncertainty,
* * Table of contents (`'tableOfContents'`) -- does not display properly in response area, long processing time.
*
* You can set this list to include more model elements or clear it to enable the above features.
*
* Note, that all or some of these features may become enabled in the future.
*
* @default [ 'media', 'rawHtml', 'tableOfContents' ]
*/
disabledElements?: Array<string>;
/**
* Determines whether the comment markers should be preserved when the editor content is processed by the AI Assistant.
*
* Note, that this behavior depends on copy-paste comments functionality setting
* (see {@link module:comments/config~CommentsConfig#copyMarkers `CommentsConfig#copyMarkers`}):
*
* * When set to `'never'`, comment markers will not be preserved.
* * When set to `'default'`, comment markers will be preserved only for "replace" action.
* * When set to `'always'`, comment markers will be preserved both for "replace" and "insert below" actions.
*
* Note, that whether the comment markers will be correctly handled also depends on the AI model response,
* and how it processes the request.
*
* @default true
*/
preserveComments?: boolean;
/**
* Enables or disables the colored UI theme for AI features.
*
* * Leaving this property unset will preserve the default theme on AI features UI elements.
* * Setting this property to **`false`** will remove the default theme from AI features UI elements.
*
* See the AI Assistant integration guide to learn how you can use CSS variables to change the default theme to a different color.
*
* @default true
*/
useTheme?: boolean;
/**
* The configuration for the AI adapter.
*
* This is required only if you connect to an external AI service.
*
* Learn more about available adapters:
*
* * {@link module:ai/aiassistant/adapters/openaitextadapter~OpenAITextAdapterConfig}
* * {@link module:ai/aiassistant/adapters/awstextadapter~AIAWSTextAdapterConfig}
*/
adapter?: {
/**
* The configuration for the {@link module:ai/aiassistant/adapters/openaitextadapter~OpenAITextAdapter `OpenAITextAdapter`}.
*
* This is required only if you connect to OpenAI or Azure OpenAI service.
*
* Read more in {@link module:ai/aiassistant/adapters/openaitextadapter~OpenAITextAdapterConfig}.
*/
openAI?: OpenAITextAdapterConfig;
/**
* The configuration for the {@link module:ai/aiassistant/adapters/awstextadapter~AWSTextAdapter `AWSTextAdapter`}.
*
* This is required only if you connect to Amazon Bedrock service.
*
* Read more in {@link module:ai/aiassistant/adapters/awstextadapter~AIAWSTextAdapterConfig}.
*/
aws?: AIAWSTextAdapterConfig;
};
}
export type AIGroupDefinition = {
/**
* The unique identifier of the group. It can be referenced while extending existing groups
* using {@link module:ai/aiassistant/aiassistant~AIAssistantConfig#extraCommandGroups} or removing command groups using
* {@link module:ai/aiassistant/aiassistant~AIAssistantConfig#removeCommands}.
*/
groupId: string;
/**
* The human-readable label of the group.
*/
groupLabel?: string;
/**
* The array of command definitions that belong to the group.
*/
commands: Array<AICommandDefinition>;
/**
* The order of the group on the list. The lower the number, the higher the group is displayed on the list.
* If not specified, the position of this group will be determined by the order of
* {@link module:ai/aiassistant/aiassistant~AIAssistantConfig#commands configuration}.
*
* If a new group is added without `order` property, it will be added at the end.
*
* The order uses zero-based numbering (the first group's order is `0`).
*/
order?: number;
};
export type AICommandDefinition = {
/**
* The unique identifier of the command. It can be referenced while removing commands. See
* {@link module:ai/aiassistant/aiassistant~AIAssistantConfig#removeCommands} to learn more.
*/
id: string;
/**
* The human-readable label of the command.
*/
label: string;
/**
* The instruction that will be passed to the AI model.
*
* It is wrapped in a "full prompt template" for better results.
*/
prompt: string;
/**
* By default, all commands require a selection for the assistant to work on. If the selection is collapsed,
* it automatically expands to the nearest block boundaries to provide the AI context.
*
* Setting this to `false` allows the command to work on a collapsed selection and prevent selection expansion.
* This is helpful, for instance, for commands that generate content from scratch.
*
* **Note**: If not specified, the default is `true`.
*/
requiresContent?: boolean;
/**
* The order of the command on the list. The lower the number, the higher the command is displayed on the list.
* If not specified, the position of this command will be determined by the order of
* {@link module:ai/aiassistant/aiassistant~AIAssistantConfig#commands configuration}.
*
* If a new command is added without `order` property, it will be added at the end of the group.
*
* The order uses zero-based numbering (the first command's order is `0`).
*/
order?: number;
};