@ckeditor/ckeditor5-ai/src/aiassistant/adapters/openaitextadapter.d.ts

AI features for CKEditor 5.

/**
 * @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/adapters/openaitextadapter
 * @publicApi
 */
import { type Editor } from 'ckeditor5/src/core.js';
import { AITextAdapter, type AITextAdapterRequestData, type AIRequestHeaders, type AIRequestParameters } from './aitextadapter.js';
/**
 * Adapter for AI text-related requests that supports OpenAI and Azure OpenAI services.
 *
 * See also {@link module:ai/aiassistant/adapters/aitextadapter~AITextAdapter}.
 */
export declare class OpenAITextAdapter extends AITextAdapter {
    /**
     * @inheritDoc
     */
    static get pluginName(): "OpenAITextAdapter";
    /**
     * @inheritDoc
     */
    constructor(editor: Editor);
    /**
     * Performs the request to the OpenAI service, Azure OpenAI service, or to the endpoint provided in the editor configuration.
     *
     * If you want to extend this adapter, you can overload this method to do some additional processing or make an external call.
     */
    sendRequest({ query, context, onData, actionId }: AITextAdapterRequestData): Promise<void>;
    /**
     * Prepares the actual request messages to be sent as a part of the request to the AI service.
     *
     * See [OpenAI API reference](https://platform.openai.com/docs/api-reference/chat/create) to learn more.
     *
     * This method returns two messages, one "system message" with general instructions for the model and one "user message"
     * with the actual instruction to perform.
     *
     * The messages are different, based on whether there is any `context` provided. If no `context` is provided, it is assumed that
     * the user wants to generate new content. If `context` is provided, it is assumed that the user wants to process this `context`
     * (e.g. translate) or generate something based on `context` (e.g. summary).
     *
     * You can overload this method to customize the messages that are sent to the AI service.
     *
     * @param query The user's query. The instruction which the model should perform.
     * @param context The context for the instruction. Usually this will be a part of the editor content. Can be empty.
     * @param actionId ID of the performed action.
     * See {@link module:ai/aiassistant/adapters/aitextadapter~AITextAdapterRequestData#actionId}.
     */
    prepareMessages(query: string, context: string, actionId: string): Promise<Array<AIRequestMessageItem>>;
}
/**
 * The configuration for the OpenAI adapter.
 *
 * The properties defined in this config are set in the `config.ai.assistant.adapter.openAI` namespace.
 *
 * ```ts
 * ClassicEditor
 * 	.create( editorElement, {
 * 		ai: {
 * 			assistant: {
 * 				adapter: {
 * 					openAI: {
 * 						requestHeaders: {
 * 							Authorization: 'Bearer OPENAI_API_KEY'
 * 						}
 * 					}
 * 				}
 * 			}
 * 		}
 * 	} )
 * 	.then( ... )
 * 	.catch( ... );
 * ```
 *
 * See {@link module:ai/aiconfig~AIConfig the full AI configuration}.
 *
 * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
 */
export interface OpenAITextAdapterConfig {
    /**
     * The URL to which the AI service request will be sent.
     *
     * By default, requests are sent to the OpenAI API service. Change this value to make requests to Azure OpenAI API or use proxy endpoint
     * in your application instead.
     *
     * Defaults to `'https://api.openai.com/v1/chat/completions'`.
     */
    apiUrl?: string;
    /**
     * Object with headers to set in the request to the AI service API.
     *
     * If the provided value is an `object`, it is simply used as provided.
     *
     * If you are connecting directly to the OpenAI API, use your OpenAI API key in the following way:
     *
     * ```js
     * {
     * 	ai: {
     * 		assistant: {
     * 			adapter: {
     * 				openAI: {
     * 					requestHeaders: {
     * 				 		'Authorization': 'Bearer YOUR_API_KEY'
     * 					}
     * 					// ...
     * 				}
     * 			}
     * 		}
     * 	// ..
     * 	}
     * }
     * ```
     *
     * **Important: use your API key ONLY in a development environment or for testing purposes!**
     * In the production environment, pass your request through a proxy endpoint.
     *
     * If you are using a proxy service to send requests to the OpenAI API, `requestHeaders` can be used to implement authorization for your
     * requests.
     *
     * If the provided value is a function, it should be a function that returns a `Promise` which resolves with the headers object.
     * This way, you can perform an authorization request to your application and receive the authorization token (and also implement
     * any custom logic on the back-end side). The headers object is then used to make the actual call to the AI service.
     *
     * The function is passed {@link module:ai/aiassistant/adapters/aitextadapter~AITextAdapterRequestData#actionId `actionId`}
     * parameter to make it possible to further customize the headers.
     *
     * ```js
     * {
     * 	ai: {
     * 		assistant: {
     * 			adapter: {
     * 				openAI: {
     * 					requestHeaders: async () => {
     * 						const jwt = await fetch( 'https://example.com/jwt-endpoint' );
     *
     * 						return {
     * 							'Authorization': 'Bearer ' + jwt
     * 						};
     * 					}
     * 					// ...
     * 				}
     * 			}
     * 		}
     * 	}
     * }
     * ```
     *
     * If the function fails for any reason, the promise should be rejected. In this case, a feature that made the request should display
     * an error notification.
     */
    requestHeaders?: AIRequestHeaders;
    /**
     * Additional configuration parameters for the AI service request. Use it to customize how the AI service generates responses.
     * Note that the value you will set here will fully overwrite the default value.
     *
     * See [OpenAI API reference](https://platform.openai.com/docs/api-reference/chat/create) to learn more about available parameters.
     *
     * If the provided value is an `object`, it is passed to the request as provided.
     *
     * If the provided value is a function, it should be a function that returns a `Promise` which resolves with the request parameters
     * object. This gives you more flexibility to provide parameters for the AI model.
     *
     * The function is passed {@link module:ai/aiassistant/adapters/aitextadapter~AITextAdapterRequestData#actionId `actionId`}
     * parameter to make it possible to further customize the parameters.
     *
     * If the function fails for any reason, the promise should be rejected. In this case, the feature that made the request should display
     * an error notification.
     *
     * Defaults to:
     *
     * ```json
     * {
     * 	model: 'gpt-4o',
     * 	temperature: 1,
     * 	top_p: 1,
     * 	stream: true
     * }
     * ```
     */
    requestParameters?: AIRequestParameters;
}
/**
 * Single message item, in the format required for the OpenAI request.
 *
 * Example:
 *
 * ```json
 * { role: 'system', content: 'You are a helpful assistant.' }
 * ```
 *
 * See [OpenAI API reference](https://platform.openai.com/docs/api-reference/chat/create) to learn more.
 */
export type AIRequestMessageItem = Record<string, string>;