@microsoft/teams-ai/lib/planners/ActionPlanner.d.ts

SDK focused on building AI based applications for Microsoft Teams.

/**
 * @module teams-ai
 */
/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */
import { TurnContext } from 'botbuilder';
import { AI } from '../AI';
import { Memory } from '../MemoryFork';
import { PromptCompletionModel, PromptCompletionModelResponseReceivedEvent } from '../models';
import { PromptTemplate, PromptManager } from '../prompts';
import { Tokenizer } from '../tokenizers';
import { TurnState } from '../TurnState';
import { PromptResponse } from '../types';
import { PromptResponseValidator } from '../validators';
import { Planner, Plan } from './Planner';
/**
 * Factory function used to create a prompt template.
 * @template TState Optional. Type of application state.
 * @param context Context for the current turn of conversation.
 * @param state Application state for the current turn of conversation.
 * @param planner The action planner that is generating the prompt.
 * @returns A promise that resolves to the prompt template to use.
 */
export type ActionPlannerPromptFactory<TState extends TurnState = TurnState> = (context: TurnContext, state: TState, planner: ActionPlanner<TState>) => Promise<PromptTemplate>;
/**
 * Options used to configure an `ActionPlanner` instance.
 * @template TState Optional. Type of application state.
 */
export interface ActionPlannerOptions<TState extends TurnState = TurnState> {
    /**
     * Model instance to use.
     */
    model: PromptCompletionModel;
    /**
     * Prompt manager used to manage prompts.
     */
    prompts: PromptManager;
    /**
     * The default prompt to use.
     * @remarks
     * This can either be the name of a prompt template or a function that returns a prompt template.
     */
    defaultPrompt: string | ActionPlannerPromptFactory<TState>;
    /**
     * Maximum number of repair attempts to make.
     * @remarks
     * The ActionPlanner uses validators and a feedback loop to repair invalid responses returned
     * by the model. This value controls the maximum number of repair attempts that will be made
     * before returning an error. The default value is 3.
     */
    max_repair_attempts?: number;
    /**
     * Optional tokenizer to use.
     * @remarks
     * If not specified, a new `GPTTokenizer` instance will be created.
     */
    tokenizer?: Tokenizer;
    /**
     * If true, repair attempts will be logged to the console.
     * @remarks
     * The default value is false.
     */
    logRepairs?: boolean;
    /**
     * Optional message to send a client at the start of a streaming response.
     */
    startStreamingMessage?: string;
    /**
     * Optional handler to run when a stream is about to conclude.
     */
    endStreamHandler?: PromptCompletionModelResponseReceivedEvent;
    /**
     * If true, the feedback loop will be enabled for streaming responses.
     */
    enableFeedbackLoop?: boolean;
    /**
     * The feedback loop type.
     */
    feedbackLoopType?: 'default' | 'custom';
}
/**
 * A planner that uses a Large Language Model (LLM) to generate plans.
 * @remarks
 * The ActionPlanner is a powerful planner that uses a LLM to generate plans. The planner can
 * trigger parameterized actions and send text based responses to the user. The ActionPlanner
 * supports the following advanced features:
 * - **Augmentations:** Augmentations virtually eliminate the need for prompt engineering. Prompts
 *   can be configured to use a named augmentation which will be automatically appended to the outgoing
 *   prompt. Augmentations let the developer specify whether they want to support multi-step plans (sequence),
 *   use OpenAI's functions support (functions), or create an AutoGPT style agent (monologue).
 * - **Validations:** Validators are used to validate the response returned by the LLM and can guarantee
 *   that the parameters passed to an action mach a supplied schema. The validator used is automatically
 *   selected based on the augmentation being used. Validators also prevent hallucinated action names
 *   making it impossible for the LLM to trigger an action that doesn't exist.
 * - **Repair:** The ActionPlanner will automatically attempt to repair invalid responses returned by the
 *   LLM using a feedback loop. When a validation fails, the ActionPlanner sends the error back to the
 *   model, along with an instruction asking it to fix its mistake. This feedback technique leads to a
 *   dramatic reduction in the number of invalid responses returned by the model.
 * @template TState Optional. Type of application state.
 */
export declare class ActionPlanner<TState extends TurnState = TurnState> implements Planner<TState> {
    private readonly _options;
    private readonly _promptFactory;
    private readonly _defaultPrompt?;
    private _enableFeedbackLoop;
    private _feedbackLoopType?;
    /**
     * Creates a new `ActionPlanner` instance.
     * @param {ActionPlannerOptions<TState>} options Options used to configure the planner.
     */
    constructor(options: ActionPlannerOptions<TState>);
    get model(): PromptCompletionModel;
    get prompts(): PromptManager;
    get defaultPrompt(): string | undefined;
    /**
     * Starts a new task.
     * @remarks
     * This method is called when the AI system is ready to start a new task. The planner should
     * generate a plan that the AI system will execute. Returning an empty plan signals that
     * there is no work to be performed.
     *
     * The planner should take the users input from `state.temp.input`.
     * @param {TurnContext} context Context for the current turn of conversation.
     * @param {TState} state Application state for the current turn of conversation.
     * @param {AI<TState>} ai The AI system that is generating the plan.
     * @returns {Promise<Plan>} The plan that was generated.
     */
    beginTask(context: TurnContext, state: TState, ai: AI<TState>): Promise<Plan>;
    /**
     * Continues the current task.
     * @remarks
     * This method is called when the AI system has finished executing the previous plan and is
     * ready to continue the current task. The planner should generate a plan that the AI system
     * will execute. Returning an empty plan signals that the task is completed and there is no work
     * to be performed.
     *
     * The output from the last plan step that was executed is passed to the planner via `state.temp.input`.
     * @param {TurnContext} context - Context for the current turn of conversation.
     * @param {TState} state - Application state for the current turn of conversation.
     * @param {AI<TState>} ai - The AI system that is generating the plan.
     * @returns {Promise<Plan>} The plan that was generated.
     */
    continueTask(context: TurnContext, state: TState, ai: AI<TState>): Promise<Plan>;
    /**
     * Completes a prompt using an optional validator.
     * @remarks
     * This method allows the developer to manually complete a prompt and access the models
     * response. If a validator is specified, the response will be validated and repaired if
     * necessary. If no validator is specified, the response will be returned as-is.
     *
     * If a validator like the `JSONResponseValidator` is used, the response returned will be
     * a message containing a JSON object. If no validator is used, the response will be a
     * message containing the response text as a string.
     * @template TContent Optional. Type of message content returned for a 'success' response. The `response.message.content` field will be of type TContent. Defaults to `string`.     * @param context Context for the current turn of conversation.
     * @param {TurnContext} context - Context for the current turn of conversation.
     * @param {Memory} memory A memory interface used to access state variables (the turn state object implements this interface.)
     * @param {string | PromptTemplate} prompt - Name of the prompt to use or a prompt template.
     * @param {PromptResponseValidator<TContent>} validator - Optional. A validator to use to validate the response returned by the model.
     * @returns {Promise<PromptResponse<TContent>>} The result of the LLM call.
     */
    completePrompt<TContent = string>(context: TurnContext, memory: Memory, prompt: string | PromptTemplate, validator?: PromptResponseValidator<TContent>): Promise<PromptResponse<TContent>>;
    /**
     * Creates a semantic function that can be registered with the apps prompt manager.
     * @param {string | PromptTemplate} prompt - The name of the prompt to use.
     * @param {PromptResponseValidator<any>} validator - Optional. A validator to use to validate the response returned by the model.
     * @remarks
     * Semantic functions are functions that make model calls and return their results as template
     * parameters to other prompts. For example, you could define a semantic function called
     * 'translator' that first translates the user's input to English before calling your main prompt:
     *
     * ```JavaScript
     * app.ai.prompts.addFunction('translator', app.ai.createSemanticFunction('translator-prompt'));
     * ```
     *
     * You would then create a prompt called "translator-prompt" that does the translation and then in
     * your main prompt you can call it using the template expression `{{translator}}`.
     * @returns {Promise<any>} A promise that resolves to the result of the semantic function.
     */
    addSemanticFunction(prompt: string | PromptTemplate, validator?: PromptResponseValidator<any>): this;
}
//# sourceMappingURL=ActionPlanner.d.ts.map