import { Agentica, IAgenticaProps, IAgenticaConfig } from "@agentica/core";
import { AgenticaPgVectorSelector } from "@agentica/pg-vector-selector";
import OpenAI from "openai";
 
const agent = new Agentica({
  vendor: {
    api: new OpenAI({ apiKey: "********" }),
    model: "gpt-4o",
  },
  controllers: [...],
  config: {
    executor: {
      initialize: null,
      select: AgenticaPgVectorSelector.boot(
        "https://your-connector-hive-server.com",
      ),
    },
    systemPrompt: {
      common: () => [
        "You are a counselor of the shopping mall.",
        "",
        "Be kind and polite to the customer.",
      ].join("\n"),
    },
    locale: "ko-KR",
    timezone: "Asia/Seoul",
    retry: 3,
  },
});
await agent.conversate("Hello, I want to refund my shoes.");

import type { AgenticaTokenUsage } from "../context/AgenticaTokenUsage";
import type { IAgenticaHistoryJson } from "../json/IAgenticaHistoryJson";
import type { IAgenticaTokenUsageJson } from "../json/IAgenticaTokenUsageJson";
 
import type { IAgenticaConfig } from "./IAgenticaConfig";
import type { IAgenticaController } from "./IAgenticaController";
import type { IAgenticaVendor } from "./IAgenticaVendor";
 
/**
 * Properties of the Agentica Agent.
 *
 * `IAgenticaProps` is an interface that defines the properties
 * of the {@link Agentica.constructor}. In the `IAgenticaProps`,
 * there're everything to prepare to create a Super A.I. chatbot
 * performing the LLM (Large Language Model) function calling.
 *
 * At first, you have to specify the LLM service {@link vendor} like
 * OpenAI with its API key and client API. And then, you have to define
 * the {@link controllers} serving the functions to call. The controllers
 * are separated by two protocols; HTTP API and TypeScript class. At last,
 * you can {@link config configure} the agent by setting the locale, timezone,
 * and some of system prompts.
 *
 * Additionally, if you want to start from the previous A.I. chatbot
 * session, you can accomplish it by assigning the previous prompt
 * histories to the {@link histories} property.
 *
 * @author Samchon
 */
export interface IAgenticaProps {
  /**
   * LLM service vendor.
   */
  vendor: IAgenticaVendor;
 
  /**
   * Controllers serving functions to call.
   */
  controllers: IAgenticaController[];
 
  /**
   * Configuration of agent.
   *
   * Configuration of A.I. chatbot agent including the user's locale,
   * timezone, and some of system prompts. Also, you can affect to the
   * LLM function selecting/calling logic by configuring additional
   * properties.
   *
   * If you don't configure this property, these values would be default.
   *
   * - `locale`: your system's locale and timezone
   * - `timezone`: your system's timezone
   * - `systemPrompt`: default prompts written in markdown
   *   - https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts
   */
  config?: IAgenticaConfig;
 
  /**
   * Prompt histories.
   *
   * If you're starting the conversation from an existing session,
   * assign the previouis prompt histories to this property.
   */
  histories?: IAgenticaHistoryJson[];
 
  /**
   * Token usage information.
   *
   * You can start token usage tracing by assigning this property.
   *
   * If you assign {@link IAgenticaTokenUsageJson} value, the
   * token usage tracing would be from the value. Otherwise you
   * assign the {@link AgenticaTokenUsage} typed instance, the
   * tracing would be binded to the instance.
   */
  tokenUsage?: IAgenticaTokenUsageJson | AgenticaTokenUsage | undefined;
 
}

import type { AgenticaContext } from "../context/AgenticaContext";
 
import type { IAgenticaConfigBase } from "./IAgenticaConfigBase";
import type { IAgenticaExecutor } from "./IAgenticaExecutor";
import type { IAgenticaSystemPrompt } from "./IAgenticaSystemPrompt";
 
/**
 * Configuration for Agentic Agent.
 *
 * `IAgenticaConfig` is an interface that defines the configuration
 * properties of the {@link Agentica}. With this configuration, you
 * can set the user's {@link locale}, {@link timezone}, and some of
 * {@link systemPrompt system prompts}.
 *
 * Also, you can affect to the LLM function selecing/calling logic by
 * configuring additional properties. For an example, if you configure the
 * {@link capacity} property, the AI chatbot will divide the functions
 * into the several groups with the configured capacity and select proper
 * functions to call by operating the multiple LLM function selecting
 * agents parallelly.
 *
 * @author Samchon
 */
export interface IAgenticaConfig extends IAgenticaConfigBase {
  /**
   * Agent executor.
   *
   * Executor function of Agentic AI's iteration plan to internal agents
   * running by the {@link Agentica.conversate} function.
   *
   * If you want to customize the agent execution plan, you can do it
   * by assigning you logic function of entire or partial to this property.
   * When customizing it, it would better to reference the
   * {@link ChatGptAgent.execute} function.
   *
   * @param ctx Context of the agent
   * @default ChatGptAgent.execute
   */
  executor?:
    | Partial<IAgenticaExecutor>
    | ((ctx: AgenticaContext) => Promise<void>);
 
  /**
   * System prompt messages.
   *
   * System prompt messages if you want to customize the system prompt
   * messages for each situation.
   */
  systemPrompt?: IAgenticaSystemPrompt;
 
  /**
   * Capacity of the LLM function selecting.
   *
   * When the A.I. chatbot selects a proper function to call, if the
   * number of functions registered in the
   * {@link IAgenticaProps.applications} is too much greater,
   * the A.I. chatbot often fallen into the hallucination.
   *
   * In that case, if you configure this property value, `Agentica`
   * will divide the functions into the several groups with the configured
   * capacity and select proper functions to call by operating the multiple
   * LLM function selecting agents parallelly.
   *
   * @default 100
   */
  capacity?: number;
 
  /**
   * Eliticism for the LLM function selecting.
   *
   * If you configure {@link capacity}, the A.I. chatbot will complete
   * the candidate functions to call which are selected by the multiple
   * LLM function selecting agents.
   *
   * Otherwise you configure this property as `false`, the A.I. chatbot
   * will not complete the candidate functions to call and just accept
   * every candidate functions to call which are selected by the multiple
   * LLM function selecting agents.
   *
   * @default true
   */
  eliticism?: boolean;
}

import type { AgenticaContext } from "../context/AgenticaContext";
import type { AgenticaOperation } from "../context/AgenticaOperation";
import type { AgenticaExecuteEvent } from "../events/AgenticaExecuteEvent";
 
/**
 * Executor of the Agentic AI.
 *
 * `IAgenticaExecutor` represents an executor of the {@link Agentica},
 * composing its internal agents to accomplish the Agentic AI through
 * the LLM (Large Language Model) function calling.
 *
 * You can customize one of these internal agents by configuring
 * properties of the `IAgenticaExecutor` type, and assigning it to the
 * {@link IAgenticaConfig.executor} property. If you set the
 * {@link initialize} as `null` value, the {@link Agentica} will skip
 * the initialize process and directly go to the {@link select} process.
 *
 * By the way, when customizing the executor member, it would better to
 * reference the guide documents of `@agentica/core`, and internal
 * agents' implementation code. It's because if you take some mistake on
 * the executor logic, it can entirely break the {@link Agentica}'s
 * operation.
 *
 * @reference https://wrtnlabs.io/agentica/docs/concepts/function-calling/#orchestration-strategy
 * @reference https://github.com/wrtnlabs/agentica/blob/main/packages/core/src/orchestrate/execute.ts
 * @author Samchon
 */
export interface IAgenticaExecutor {
  /**
   * Initializer agent listing up functions.
   *
   * `initialize` agent is the first agent that {@link Agentica}
   * would meet  which judges whether the user's conversation implies
   * to call some function or not.
   *
   * And if the `initialize` agent judges the user's conversation
   * implies to call some function, the `initialize` agent will
   * call the {@link AgenticaContext.initialize} function, and
   * inform every functions enrolled in the {@link IAgenticaController}
   * to the AI agent. And then, the `initialize` agent will not never
   * be called again, and let {@link Agentica} to go to the next
   * {@link select} agent.
   *
   * Otherwise the user's conversation does not imply the request of
   * function calling, it would just work like plain chatbot, and just
   * conversate with the user.
   *
   * By the way, if you wanna skip the `initialize` agent, you can
   * do it by configuring the {@link IAgenticaExecutor.initialize} as
   * `undefined`, `false` or `null` value. In that case, the `initialize`
   * agent will never be called, and {@link Agentica} just starts from the
   * {@link select} agent.
   *
   * @param ctx Context of the agent
   * @returns List of prompts generated by the initializer
   * @default false
   */
  initialize:
    | boolean
    | null
    | ((ctx: AgenticaContext) => Promise<void>);
 
  /**
   * Function selector agent.
   *
   * `Select` agent finds candidate functions to call from the
   * conversation context with the user. And the candidate functions
   * would be enrolled to the {@link AgenticaContext.stack}, and the
   * next {@link call} agent will perform the LLM (Large Language Model)
   * function calling.
   *
   * Note that, the `select` agent does not perform the LLM function
   * calling. It ends with just finding the candidate functions to call.
   *
   * By the way, if the `select` agent can't specify a certain function
   * to call due to lack of conversation context or homogeneity between
   * heterogeneous functions, how `select` agent works? In that case,
   * `select` agent it will just enroll every candidate functions to
   * the stack, and let the next {@link call} agent to determine the
   * proper function to call. And then let {@link cancel} agent to erase
   * the other candidate functions from the stack.
   *
   * Additionally, if `select` agent could not find any candidate
   * function from the conversation context with user, it would just
   * act like plain chatbot conversating with the user.
   *
   * @param ctx Context of the agent
   * @returns List of prompts generated by the selector
   */
  select: (ctx: AgenticaContext) => Promise<void>;
 
  /**
   * Function caller agent.
   *
   * `Call` agent performs the LLM (Large Language Model) function
   * calling from the candidate functions enrolled in the
   * {@link AgenticaContext.stack}. And the scope of function calling
   * is, not only just arguments filling, but also actual executing
   * the function and returning the result.
   *
   * By the way, conversation context with user can be not enough to
   * filling the arguments of the candidate functions. In that case,
   * the `call` agent will ask the user to fill the missing arguments.
   *
   * Otherwise the cpnversation context is enough, so that succeeded
   * to call some candidate functions, the `call` agent will step to
   * the {@link describe} agent to explain the result of the function
   * calling to the user as markdown content.
   *
   * @param ctx Context of the agent
   * @param operation Lit of candidate operations to call
   * @returns List of prompts generated by the caller
   * @warning Recommend not to customize, due to its validation
   *          feedback strategy is working very well, and the `call`
   *          agent is the most general topic which can be universally
   *          applied to all domain fields.
   */
  call: (
    ctx: AgenticaContext,
    operations: AgenticaOperation[],
  ) => Promise<AgenticaExecuteEvent[]>;
 
  /**
   * Describer agent of the function calling result.
   *
   * `Describe` agent explains the results of the function callings
   * to the user as markdown content.
   *
   * If you configure this property as `false` or `null`, the describer
   * agent will never be used.
   *
   * @param ctx Context of the agent
   * @param executes List of function calling results
   * @returns List of prompts generated by the describer
   */
  describe:
    | boolean
    | null
    | ((
      ctx: AgenticaContext,
      executes: AgenticaExecuteEvent[],
    ) => Promise<void>);
 
  /**
   * Function canceler agent.
   *
   * `Cancel` agent erases the candidate functions from the
   * {@link AgenticaContext.stack} by analyzing the conversation
   * context with the user.
   *
   * For reference, the first reason of the cancelation is explicit
   * order from user to the previous requested function. For example,
   * user had requested to send an email to the agent, but suddenly
   * user says to cancel the email sending.
   *
   * The seconod reason n of the cancelation is the multiple candidate
   * functions had been selected at once by the {@link select} agent
   * due to lack of conversation context or homogeneity between the
   * heterogeneous functions. And in the multiple candidate functions,
   * one thing is clearly determined by the {@link call} agent, so that
   * drop the other candidate functions.
   *
   * @param ctx Context of the agent
   * @returns List of prompts generated by the canceler
   */
  cancel: (ctx: AgenticaContext) => Promise<void>;
}

import type { AgenticaJsonParseErrorEvent } from "../events";
import type { AgenticaValidateEvent } from "../events/AgenticaValidateEvent";
import type { AgenticaExecuteHistory } from "../histories/AgenticaExecuteHistory";
import type { AgenticaHistory } from "../histories/AgenticaHistory";
 
import type { IAgenticaConfig } from "./IAgenticaConfig";
 
/**
 * System prompt collection of the Agentic AI.
 *
 * `IAgenticaSystemPrompt` is a type represents a collection of system
 * prompts that would be used by the A.I. chatbot of {@link Agentica}.
 *
 * You can customize the system prompt by configuring the
 * {@link IAgenticaConfig.systemPrompt} property when creating a new
 * {@link Agentica} instance.
 *
 * If you don't configure any system prompts, the default system prompts
 * would be used which are written in the below directory as markdown
 * documents.
 *
 * - https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts
 *
 * @author Samchon
 */
export interface IAgenticaSystemPrompt {
  /**
   * Common system prompt that would be used in every situation.
   *
   * This prompt establishes the foundational behavior and personality of
   * the AI agent across all interaction phases. It defines the agent's
   * core identity, communication style, and general operating principles
   * that remain consistent throughout the conversation flow.
   *
   * @param config Configuration of the agent
   * @returns The common system prompt
   * @default https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts/common.md
   */
  common?: (config?: IAgenticaConfig | undefined) => string;
 
  /**
   * Initialize system prompt.
   *
   * When the A.I. chatbot has not informed any functions to the agent
   * yet because the user has not implied any function calling request yet,
   * {@link Agentica} says that it is a circumstance that nothing has
   * been initialized yet.
   *
   * In that case, the `initialize` system prompt would be used. This is
   * the most basic prompt that simply establishes the AI as a helpful
   * assistant with access to supplied tools. It provides minimal guidance,
   * allowing the AI to respond naturally to user requests and automatically
   * identify when function calls are appropriate based on the available
   * tools and user context.
   *
   * The initialize prompt is intentionally simple and generic, serving as
   * a foundation for general conversation and tool usage without specific
   * constraints or specialized behaviors.
   *
   * @param histories Histories of the previous prompts
   * @returns initialize system prompt
   * @default https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts/initialize.md
   */
  initialize?: (histories: AgenticaHistory[]) => string;
 
  /**
   * Select system prompt.
   *
   * The {@link Agentica} has a process selecting some candidate
   * functions to call by asking to the A.I. agent with the previous
   * prompt histories.
   *
   * In that case, this `select` system prompt would be used. This prompt
   * specifically instructs the AI to use the `getApiFunctions()` tool to
   * select appropriate functions for the user's request. It emphasizes
   * the importance of analyzing function relationships and prerequisites
   * between functions to ensure proper execution order.
   *
   * The select prompt includes internationalization support, instructing
   * the AI to consider the user's language locale and translate responses
   * accordingly. If no suitable functions are found, the AI is allowed to
   * respond with its own message rather than forcing a function selection.
   *
   * Note that, the `"select"` means only the function selection. It does
   * not contain the filling argument or executing the function. It
   * literally contains only the selection process.
   *
   * @param histories Histories of the previous prompts
   * @returns select system prompt
   * @default https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts/select.md
   */
  select?: (histories: AgenticaHistory[]) => string;
 
  /**
   * Cancel system prompt.
   *
   * The {@link Agentica} has a process canceling some candidate
   * functions to call by asking to the A.I. agent with the previous
   * prompt histories.
   *
   * In that case, this `cancel` system prompt would be used. This prompt
   * provides very specific instructions for the AI to use the
   * `getApiFunctions()` tool to select functions that should be cancelled.
   *
   * The cancel prompt is notably strict - if the AI cannot find any
   * proper functions to cancel, it is explicitly instructed to remain
   * silent and take no action whatsoever ("don't talk, don't do anything").
   * This prevents unnecessary responses when cancellation is not applicable.
   *
   * @param histories Histories of the previous prompts
   * @returns cancel system prompt
   * @default https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts/cancel.md
   */
  cancel?: (histories: AgenticaHistory[]) => string;
 
  /**
   * Execute system prompt.
   *
   * The {@link Agentica} has a process filling the arguments of some
   * selected candidate functions by the LLM (Large Language Model)
   * function calling feature with the previous prompt histories, and
   * executing the arguments filled function with validation feedback.
   *
   * In that case, this `execute` system prompt would be used. This prompt
   * instructs the AI to use the supplied tools to assist the user, with
   * specific guidance on handling insufficient information scenarios.
   * When the AI lacks enough context to compose proper function arguments,
   * it is instructed to ask the user for additional information in a
   * concise and clear manner.
   *
   * The execute prompt also provides important context about the "tool"
   * role message structure, explaining that the `function` property
   * contains API operation metadata (schema, purpose, parameters, return
   * types) while the `data` property contains the actual return values
   * from function executions.
   *
   * @param histories Histories of the previous prompts
   * @returns execute system prompt
   * @default https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts/execute.md
   */
  execute?: (histories: AgenticaHistory[]) => string;
 
  /**
   * Validation feedback system prompt.
   *
   * When the AI generates function arguments that fail type validation
   * during the execution phase, this prompt provides the system instructions
   * for analyzing {@link IValidation.IFailure} results and generating
   * corrective feedback.
   *
   * This specialized prompt enables the AI to:
   * - Parse detailed validation error information from typia validation results
   * - Identify specific type mismatches, missing properties, and format violations
   * - Handle complex union type failures with discriminator property analysis
   * - Generate actionable correction guidance for parameter regeneration
   * - Distinguish between partial fixes and complete reconstruction scenarios
   *
   * The validation feedback agent acts as an intermediary between the main
   * AI agent and the function execution system, providing structured feedback
   * that helps improve function calling accuracy through iterative correction.
   * This is particularly valuable for complex function schemas where precise
   * type conformance is critical.
   *
   * Key capabilities include:
   * - Union type analysis with discriminator property detection
   * - Granular error path reporting (e.g., "input.user.profile.age")
   * - Format-specific guidance (UUID, email, numeric constraints)
   * - Complete reconstruction recommendations for incompatible values
   *
   * @props events The previous validation events containing the IValidation.IFailure
   * @returns validation feedback system prompt
   * @default Built-in validation feedback prompt optimized for typia IValidation.IFailure processing
   */
  validate?: (events: AgenticaValidateEvent[]) => string;
 
  /**
   * JSON parsing error system prompt.
   *
   * When the AI generates function arguments with invalid JSON syntax
   * that cannot be parsed by `JSON.parse()`, this prompt provides system
   * instructions for handling the parsing error and requesting corrected
   * function calls.
   *
   * This specialized prompt enables the AI to:
   * - Understand that the function call arguments contained malformed JSON
   * - Receive the specific error message from `JSON.parse()`
   * - Get guidance on common JSON syntax issues (trailing commas, quote problems, etc.)
   * - Retry the function call with properly formatted JSON arguments
   *
   * The JSON parse error prompt acts as an immediate correction mechanism
   * when function calling fails at the JSON parsing stage, before any
   * schema validation occurs. This ensures that basic JSON syntax compliance
   * is maintained for all function calls.
   *
   * Key features include:
   * - Direct error message reporting from `JSON.parse()`
   * - Clear identification of the problematic function call
   * - Specific guidance on JSON syntax requirements
   * - Immediate retry instruction without additional processing
   *
   * @param event The JSON parse error event containing the malformed arguments and error details
   * @returns JSON parse error system prompt
   * @default Built-in JSON parse error prompt optimized for syntax correction
   */
  jsonParseError?: (event: AgenticaJsonParseErrorEvent) => string;
 
  /**
   * Describe system prompt.
   *
   * The {@link Agentica} has a process describing the return values of
   * the executed functions by requesting to the A.I. agent with the
   * previous prompt histories.
   *
   * In that case, this `describe` system prompt would be used. This prompt
   * instructs the AI to provide detailed descriptions of function call
   * return values rather than brief summaries. It emphasizes comprehensive
   * reporting to ensure users receive thorough information about the
   * function execution results.
   *
   * The describe prompt specifies several formatting requirements:
   * - Content must be formatted in markdown
   * - Mermaid syntax should be utilized for diagrams when appropriate
   * - Images should be included using markdown image syntax
   * - Internationalization support with translation to user's language
   *   locale when the description language differs from the user's language
   *
   * The prompt receives execution histories specifically, allowing the AI
   * to access both the function metadata and actual execution results
   * for comprehensive reporting.
   *
   * @param histories Histories of the previous prompts and their execution results
   * @returns describe system prompt
   * @default https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts/describe.md
   */
  describe?: (histories: AgenticaExecuteHistory[]) => string;
}

import { Agentica, IAgenticaProps, IAgenticaConfig } from "@agentica/core";
import { AgenticaPgVectorSelector } from "@agentica/pg-vector-selector";
import OpenAI from "openai";
 
const agent = new Agentica({
  vendor: {
    api: new OpenAI({ apiKey: "********" }),
    model: "gpt-4o",
  },
  controllers: [...],
  config: {
    executor: {
      initialize: null,
      select: AgenticaPgVectorSelector.boot(
        "https://your-connector-hive-server.com",
      ),
    },
  },
});
await agent.conversate("Hello, I want to refund my shoes.");

import type { AgenticaContext } from "../context/AgenticaContext";
import type { AgenticaOperation } from "../context/AgenticaOperation";
import type { AgenticaExecuteEvent } from "../events/AgenticaExecuteEvent";
 
/**
 * Executor of the Agentic AI.
 *
 * `IAgenticaExecutor` represents an executor of the {@link Agentica},
 * composing its internal agents to accomplish the Agentic AI through
 * the LLM (Large Language Model) function calling.
 *
 * You can customize one of these internal agents by configuring
 * properties of the `IAgenticaExecutor` type, and assigning it to the
 * {@link IAgenticaConfig.executor} property. If you set the
 * {@link initialize} as `null` value, the {@link Agentica} will skip
 * the initialize process and directly go to the {@link select} process.
 *
 * By the way, when customizing the executor member, it would better to
 * reference the guide documents of `@agentica/core`, and internal
 * agents' implementation code. It's because if you take some mistake on
 * the executor logic, it can entirely break the {@link Agentica}'s
 * operation.
 *
 * @reference https://wrtnlabs.io/agentica/docs/concepts/function-calling/#orchestration-strategy
 * @reference https://github.com/wrtnlabs/agentica/blob/main/packages/core/src/orchestrate/execute.ts
 * @author Samchon
 */
export interface IAgenticaExecutor {
  /**
   * Initializer agent listing up functions.
   *
   * `initialize` agent is the first agent that {@link Agentica}
   * would meet  which judges whether the user's conversation implies
   * to call some function or not.
   *
   * And if the `initialize` agent judges the user's conversation
   * implies to call some function, the `initialize` agent will
   * call the {@link AgenticaContext.initialize} function, and
   * inform every functions enrolled in the {@link IAgenticaController}
   * to the AI agent. And then, the `initialize` agent will not never
   * be called again, and let {@link Agentica} to go to the next
   * {@link select} agent.
   *
   * Otherwise the user's conversation does not imply the request of
   * function calling, it would just work like plain chatbot, and just
   * conversate with the user.
   *
   * By the way, if you wanna skip the `initialize` agent, you can
   * do it by configuring the {@link IAgenticaExecutor.initialize} as
   * `undefined`, `false` or `null` value. In that case, the `initialize`
   * agent will never be called, and {@link Agentica} just starts from the
   * {@link select} agent.
   *
   * @param ctx Context of the agent
   * @returns List of prompts generated by the initializer
   * @default false
   */
  initialize:
    | boolean
    | null
    | ((ctx: AgenticaContext) => Promise<void>);
 
  /**
   * Function selector agent.
   *
   * `Select` agent finds candidate functions to call from the
   * conversation context with the user. And the candidate functions
   * would be enrolled to the {@link AgenticaContext.stack}, and the
   * next {@link call} agent will perform the LLM (Large Language Model)
   * function calling.
   *
   * Note that, the `select` agent does not perform the LLM function
   * calling. It ends with just finding the candidate functions to call.
   *
   * By the way, if the `select` agent can't specify a certain function
   * to call due to lack of conversation context or homogeneity between
   * heterogeneous functions, how `select` agent works? In that case,
   * `select` agent it will just enroll every candidate functions to
   * the stack, and let the next {@link call} agent to determine the
   * proper function to call. And then let {@link cancel} agent to erase
   * the other candidate functions from the stack.
   *
   * Additionally, if `select` agent could not find any candidate
   * function from the conversation context with user, it would just
   * act like plain chatbot conversating with the user.
   *
   * @param ctx Context of the agent
   * @returns List of prompts generated by the selector
   */
  select: (ctx: AgenticaContext) => Promise<void>;
 
  /**
   * Function caller agent.
   *
   * `Call` agent performs the LLM (Large Language Model) function
   * calling from the candidate functions enrolled in the
   * {@link AgenticaContext.stack}. And the scope of function calling
   * is, not only just arguments filling, but also actual executing
   * the function and returning the result.
   *
   * By the way, conversation context with user can be not enough to
   * filling the arguments of the candidate functions. In that case,
   * the `call` agent will ask the user to fill the missing arguments.
   *
   * Otherwise the cpnversation context is enough, so that succeeded
   * to call some candidate functions, the `call` agent will step to
   * the {@link describe} agent to explain the result of the function
   * calling to the user as markdown content.
   *
   * @param ctx Context of the agent
   * @param operation Lit of candidate operations to call
   * @returns List of prompts generated by the caller
   * @warning Recommend not to customize, due to its validation
   *          feedback strategy is working very well, and the `call`
   *          agent is the most general topic which can be universally
   *          applied to all domain fields.
   */
  call: (
    ctx: AgenticaContext,
    operations: AgenticaOperation[],
  ) => Promise<AgenticaExecuteEvent[]>;
 
  /**
   * Describer agent of the function calling result.
   *
   * `Describe` agent explains the results of the function callings
   * to the user as markdown content.
   *
   * If you configure this property as `false` or `null`, the describer
   * agent will never be used.
   *
   * @param ctx Context of the agent
   * @param executes List of function calling results
   * @returns List of prompts generated by the describer
   */
  describe:
    | boolean
    | null
    | ((
      ctx: AgenticaContext,
      executes: AgenticaExecuteEvent[],
    ) => Promise<void>);
 
  /**
   * Function canceler agent.
   *
   * `Cancel` agent erases the candidate functions from the
   * {@link AgenticaContext.stack} by analyzing the conversation
   * context with the user.
   *
   * For reference, the first reason of the cancelation is explicit
   * order from user to the previous requested function. For example,
   * user had requested to send an email to the agent, but suddenly
   * user says to cancel the email sending.
   *
   * The seconod reason n of the cancelation is the multiple candidate
   * functions had been selected at once by the {@link select} agent
   * due to lack of conversation context or homogeneity between the
   * heterogeneous functions. And in the multiple candidate functions,
   * one thing is clearly determined by the {@link call} agent, so that
   * drop the other candidate functions.
   *
   * @param ctx Context of the agent
   * @returns List of prompts generated by the canceler
   */
  cancel: (ctx: AgenticaContext) => Promise<void>;
}

import type OpenAI from "openai";
 
import type { AgenticaEvent } from "../events/AgenticaEvent";
import type { AgenticaEventSource } from "../events/AgenticaEventSource";
import type { AgenticaHistory } from "../histories/AgenticaHistory";
import type { AgenticaUserMessageHistory } from "../histories/AgenticaUserMessageHistory";
import type { IAgenticaConfig } from "../structures/IAgenticaConfig";
 
import type { AgenticaContextRequestResult } from "./AgenticaContextRequestResult";
import type { AgenticaOperationCollection } from "./AgenticaOperationCollection";
import type { AgenticaOperationSelection } from "./AgenticaOperationSelection";
 
/**
 * Context of the Agentic AI agent.
 *
 * `AgenticaContext` is a structure defining the context of the
 * internal agents composing the {@link Agentica}, like function
 * selector, executor, and describer, and so on. For example, if an
 * agent has been configured to utilize the OpenAI, the context will
 * be delivered to the below components.
 *
 * - {@link orchestrate.execute}
 *   - {@link orchestrate.initialize}
 *   - {@link orchestrate.select}
 *   - {@link orchestrate.call}
 *   - {@link orchestrate.describe}
 *   - {@link orchestrate.cancel}
 *
 * Also, as its name is context, it contains every information that
 * is required to interact with the AI vendor like OpenAI. It
 * contains every operations for LLM function calling, and
 * configuration used for the agent construction. And it contains
 * the prompt histories, and facade controller functions for
 * interacting with the {@link Agentica} like {@link dispatch}.
 *
 * In such reasons, if you're planning to customize some internal
 * agents, or add new agents with new process routine, you have to
 * understand this context structure. Otherwise you don't have any
 * plan to customize the internal agents, this context information is
 * not important for you.
 *
 * @author Samchon
 */
export interface AgenticaContext {
  // ----
  // APPLICATION
  // ----
  /**
   * Collection of operations.
   *
   * Collection of operations from every controllers, and their
   * groups composed by the divide and conquer rule for the
   * efficient operation selection if configured.
   */
  operations: AgenticaOperationCollection;
 
  /**
   * Configuration of the agent.
   *
   * Configuration of the agent, that is used when constructing the
   * {@link Agentica} instance.
   *
   * @todo Write detaily after supporting the agent customization feature
   */
  config: IAgenticaConfig | undefined;
 
  // ----
  // STATES
  // ----
  /**
   * Prompt histories.
   */
  histories: AgenticaHistory[];
 
  /**
   * Stacked operations.
   *
   * In other words, list of candidate operations for the LLM function calling.
   */
  stack: AgenticaOperationSelection[];
 
  /**
   * The user input history.
   *
   * The user input history written by the user through the
   * {@link Agentica.conversate} function.
   */
  prompt: AgenticaUserMessageHistory;
 
  /**
   * Abort signal.
   */
  abortSignal?: AbortSignal;
 
  /**
   * Whether the agent is ready.
   *
   * Returns a boolean value indicates whether the agent is ready to
   * perform the function calling.
   *
   * If the agent has called the {@link AgenticaContext.initialize},
   * it returns `true`. Otherwise the {@link initialize} has never been
   * called, returns `false`.
   */
  ready: () => boolean;
 
  // ----
  // HANDLERS
  // ----
  /**
   * Dispatch event.
   *
   * Dispatch event so that the agent can be handle the event
   * through the {@link Agentica.on} function.
   *
   * @param event Event to deliver
   */
  dispatch: (event: AgenticaEvent) => Promise<void>;
 
  /**
   * Request to the OpenAI server.
   *
   * @param source The source agent of the agent
   * @param body The request body to the OpenAI server
   * @returns Response from the OpenAI server
   */
  request: (
    source: AgenticaEventSource,
    body: Omit<OpenAI.ChatCompletionCreateParamsStreaming, "model" | "stream">,
  ) => Promise<AgenticaContextRequestResult>;
 
  /**
   * Initialize the agent.
   */
  initialize: () => Promise<void>;
}

import { Agentica, IAgenticaProps, IAgenticaConfig } from "@agentica/core";
import OpenAI from "openai";
 
const agent = new Agentica({
  vendor: {
    api: new OpenAI({ apiKey: "********" }),
    model: "gpt-4o",
  },
  controllers: [...],
  config: {
    systemPrompt: {
      common: () => [
        "You are a counselor of the shopping mall.",
        "",
        "Be kind and polite to the customer.",
      ].join("\n"),
    },
  },
});
await agent.conversate("Hello, I want to refund my shoes.");

import type { AgenticaJsonParseErrorEvent } from "../events";
import type { AgenticaValidateEvent } from "../events/AgenticaValidateEvent";
import type { AgenticaExecuteHistory } from "../histories/AgenticaExecuteHistory";
import type { AgenticaHistory } from "../histories/AgenticaHistory";
 
import type { IAgenticaConfig } from "./IAgenticaConfig";
 
/**
 * System prompt collection of the Agentic AI.
 *
 * `IAgenticaSystemPrompt` is a type represents a collection of system
 * prompts that would be used by the A.I. chatbot of {@link Agentica}.
 *
 * You can customize the system prompt by configuring the
 * {@link IAgenticaConfig.systemPrompt} property when creating a new
 * {@link Agentica} instance.
 *
 * If you don't configure any system prompts, the default system prompts
 * would be used which are written in the below directory as markdown
 * documents.
 *
 * - https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts
 *
 * @author Samchon
 */
export interface IAgenticaSystemPrompt {
  /**
   * Common system prompt that would be used in every situation.
   *
   * This prompt establishes the foundational behavior and personality of
   * the AI agent across all interaction phases. It defines the agent's
   * core identity, communication style, and general operating principles
   * that remain consistent throughout the conversation flow.
   *
   * @param config Configuration of the agent
   * @returns The common system prompt
   * @default https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts/common.md
   */
  common?: (config?: IAgenticaConfig | undefined) => string;
 
  /**
   * Initialize system prompt.
   *
   * When the A.I. chatbot has not informed any functions to the agent
   * yet because the user has not implied any function calling request yet,
   * {@link Agentica} says that it is a circumstance that nothing has
   * been initialized yet.
   *
   * In that case, the `initialize` system prompt would be used. This is
   * the most basic prompt that simply establishes the AI as a helpful
   * assistant with access to supplied tools. It provides minimal guidance,
   * allowing the AI to respond naturally to user requests and automatically
   * identify when function calls are appropriate based on the available
   * tools and user context.
   *
   * The initialize prompt is intentionally simple and generic, serving as
   * a foundation for general conversation and tool usage without specific
   * constraints or specialized behaviors.
   *
   * @param histories Histories of the previous prompts
   * @returns initialize system prompt
   * @default https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts/initialize.md
   */
  initialize?: (histories: AgenticaHistory[]) => string;
 
  /**
   * Select system prompt.
   *
   * The {@link Agentica} has a process selecting some candidate
   * functions to call by asking to the A.I. agent with the previous
   * prompt histories.
   *
   * In that case, this `select` system prompt would be used. This prompt
   * specifically instructs the AI to use the `getApiFunctions()` tool to
   * select appropriate functions for the user's request. It emphasizes
   * the importance of analyzing function relationships and prerequisites
   * between functions to ensure proper execution order.
   *
   * The select prompt includes internationalization support, instructing
   * the AI to consider the user's language locale and translate responses
   * accordingly. If no suitable functions are found, the AI is allowed to
   * respond with its own message rather than forcing a function selection.
   *
   * Note that, the `"select"` means only the function selection. It does
   * not contain the filling argument or executing the function. It
   * literally contains only the selection process.
   *
   * @param histories Histories of the previous prompts
   * @returns select system prompt
   * @default https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts/select.md
   */
  select?: (histories: AgenticaHistory[]) => string;
 
  /**
   * Cancel system prompt.
   *
   * The {@link Agentica} has a process canceling some candidate
   * functions to call by asking to the A.I. agent with the previous
   * prompt histories.
   *
   * In that case, this `cancel` system prompt would be used. This prompt
   * provides very specific instructions for the AI to use the
   * `getApiFunctions()` tool to select functions that should be cancelled.
   *
   * The cancel prompt is notably strict - if the AI cannot find any
   * proper functions to cancel, it is explicitly instructed to remain
   * silent and take no action whatsoever ("don't talk, don't do anything").
   * This prevents unnecessary responses when cancellation is not applicable.
   *
   * @param histories Histories of the previous prompts
   * @returns cancel system prompt
   * @default https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts/cancel.md
   */
  cancel?: (histories: AgenticaHistory[]) => string;
 
  /**
   * Execute system prompt.
   *
   * The {@link Agentica} has a process filling the arguments of some
   * selected candidate functions by the LLM (Large Language Model)
   * function calling feature with the previous prompt histories, and
   * executing the arguments filled function with validation feedback.
   *
   * In that case, this `execute` system prompt would be used. This prompt
   * instructs the AI to use the supplied tools to assist the user, with
   * specific guidance on handling insufficient information scenarios.
   * When the AI lacks enough context to compose proper function arguments,
   * it is instructed to ask the user for additional information in a
   * concise and clear manner.
   *
   * The execute prompt also provides important context about the "tool"
   * role message structure, explaining that the `function` property
   * contains API operation metadata (schema, purpose, parameters, return
   * types) while the `data` property contains the actual return values
   * from function executions.
   *
   * @param histories Histories of the previous prompts
   * @returns execute system prompt
   * @default https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts/execute.md
   */
  execute?: (histories: AgenticaHistory[]) => string;
 
  /**
   * Validation feedback system prompt.
   *
   * When the AI generates function arguments that fail type validation
   * during the execution phase, this prompt provides the system instructions
   * for analyzing {@link IValidation.IFailure} results and generating
   * corrective feedback.
   *
   * This specialized prompt enables the AI to:
   * - Parse detailed validation error information from typia validation results
   * - Identify specific type mismatches, missing properties, and format violations
   * - Handle complex union type failures with discriminator property analysis
   * - Generate actionable correction guidance for parameter regeneration
   * - Distinguish between partial fixes and complete reconstruction scenarios
   *
   * The validation feedback agent acts as an intermediary between the main
   * AI agent and the function execution system, providing structured feedback
   * that helps improve function calling accuracy through iterative correction.
   * This is particularly valuable for complex function schemas where precise
   * type conformance is critical.
   *
   * Key capabilities include:
   * - Union type analysis with discriminator property detection
   * - Granular error path reporting (e.g., "input.user.profile.age")
   * - Format-specific guidance (UUID, email, numeric constraints)
   * - Complete reconstruction recommendations for incompatible values
   *
   * @props events The previous validation events containing the IValidation.IFailure
   * @returns validation feedback system prompt
   * @default Built-in validation feedback prompt optimized for typia IValidation.IFailure processing
   */
  validate?: (events: AgenticaValidateEvent[]) => string;
 
  /**
   * JSON parsing error system prompt.
   *
   * When the AI generates function arguments with invalid JSON syntax
   * that cannot be parsed by `JSON.parse()`, this prompt provides system
   * instructions for handling the parsing error and requesting corrected
   * function calls.
   *
   * This specialized prompt enables the AI to:
   * - Understand that the function call arguments contained malformed JSON
   * - Receive the specific error message from `JSON.parse()`
   * - Get guidance on common JSON syntax issues (trailing commas, quote problems, etc.)
   * - Retry the function call with properly formatted JSON arguments
   *
   * The JSON parse error prompt acts as an immediate correction mechanism
   * when function calling fails at the JSON parsing stage, before any
   * schema validation occurs. This ensures that basic JSON syntax compliance
   * is maintained for all function calls.
   *
   * Key features include:
   * - Direct error message reporting from `JSON.parse()`
   * - Clear identification of the problematic function call
   * - Specific guidance on JSON syntax requirements
   * - Immediate retry instruction without additional processing
   *
   * @param event The JSON parse error event containing the malformed arguments and error details
   * @returns JSON parse error system prompt
   * @default Built-in JSON parse error prompt optimized for syntax correction
   */
  jsonParseError?: (event: AgenticaJsonParseErrorEvent) => string;
 
  /**
   * Describe system prompt.
   *
   * The {@link Agentica} has a process describing the return values of
   * the executed functions by requesting to the A.I. agent with the
   * previous prompt histories.
   *
   * In that case, this `describe` system prompt would be used. This prompt
   * instructs the AI to provide detailed descriptions of function call
   * return values rather than brief summaries. It emphasizes comprehensive
   * reporting to ensure users receive thorough information about the
   * function execution results.
   *
   * The describe prompt specifies several formatting requirements:
   * - Content must be formatted in markdown
   * - Mermaid syntax should be utilized for diagrams when appropriate
   * - Images should be included using markdown image syntax
   * - Internationalization support with translation to user's language
   *   locale when the description language differs from the user's language
   *
   * The prompt receives execution histories specifically, allowing the AI
   * to access both the function metadata and actual execution results
   * for comprehensive reporting.
   *
   * @param histories Histories of the previous prompts and their execution results
   * @returns describe system prompt
   * @default https://github.com/wrtnlabs/agentica/tree/main/packages/core/prompts/describe.md
   */
  describe?: (histories: AgenticaExecuteHistory[]) => string;
}

import { Agentica } from "@agentica/core";
import OpenAI from "openai";
 
const agent = new Agentica({
  vendor: {
    api: new OpenAI({ apiKey: "********" }),
    model: "gpt-4o",
  },
  controllers: [...],
  config: {
    retry: 3,
  },
});
await agent.conversate("Hello, I want to refund my shoes.");

import type { AgenticaContext } from "../context/AgenticaContext";
 
import type { IAgenticaConfigBase } from "./IAgenticaConfigBase";
import type { IAgenticaExecutor } from "./IAgenticaExecutor";
import type { IAgenticaSystemPrompt } from "./IAgenticaSystemPrompt";
 
/**
 * Configuration for Agentic Agent.
 *
 * `IAgenticaConfig` is an interface that defines the configuration
 * properties of the {@link Agentica}. With this configuration, you
 * can set the user's {@link locale}, {@link timezone}, and some of
 * {@link systemPrompt system prompts}.
 *
 * Also, you can affect to the LLM function selecing/calling logic by
 * configuring additional properties. For an example, if you configure the
 * {@link capacity} property, the AI chatbot will divide the functions
 * into the several groups with the configured capacity and select proper
 * functions to call by operating the multiple LLM function selecting
 * agents parallelly.
 *
 * @author Samchon
 */
export interface IAgenticaConfig extends IAgenticaConfigBase {
  /**
   * Agent executor.
   *
   * Executor function of Agentic AI's iteration plan to internal agents
   * running by the {@link Agentica.conversate} function.
   *
   * If you want to customize the agent execution plan, you can do it
   * by assigning you logic function of entire or partial to this property.
   * When customizing it, it would better to reference the
   * {@link ChatGptAgent.execute} function.
   *
   * @param ctx Context of the agent
   * @default ChatGptAgent.execute
   */
  executor?:
    | Partial<IAgenticaExecutor>
    | ((ctx: AgenticaContext) => Promise<void>);
 
  /**
   * System prompt messages.
   *
   * System prompt messages if you want to customize the system prompt
   * messages for each situation.
   */
  systemPrompt?: IAgenticaSystemPrompt;
 
  /**
   * Capacity of the LLM function selecting.
   *
   * When the A.I. chatbot selects a proper function to call, if the
   * number of functions registered in the
   * {@link IAgenticaProps.applications} is too much greater,
   * the A.I. chatbot often fallen into the hallucination.
   *
   * In that case, if you configure this property value, `Agentica`
   * will divide the functions into the several groups with the configured
   * capacity and select proper functions to call by operating the multiple
   * LLM function selecting agents parallelly.
   *
   * @default 100
   */
  capacity?: number;
 
  /**
   * Eliticism for the LLM function selecting.
   *
   * If you configure {@link capacity}, the A.I. chatbot will complete
   * the candidate functions to call which are selected by the multiple
   * LLM function selecting agents.
   *
   * Otherwise you configure this property as `false`, the A.I. chatbot
   * will not complete the candidate functions to call and just accept
   * every candidate functions to call which are selected by the multiple
   * LLM function selecting agents.
   *
   * @default true
   */
  eliticism?: boolean;
}

import { Agentica } from "@agentica/core";
import OpenAI from "openai";
 
const agent = new Agentica({
  vendor: {
    api: new OpenAI({ apiKey: "********" }),
    model: "gpt-4o",
  },
  controllers: [...],
  config: {
    locale: "ko-KR",
    timezone: "Asia/Seoul",
  },
});
await agent.conversate("Hello, I want to refund my shoes.");

import type { AgenticaContext } from "../context/AgenticaContext";
 
import type { IAgenticaConfigBase } from "./IAgenticaConfigBase";
import type { IAgenticaExecutor } from "./IAgenticaExecutor";
import type { IAgenticaSystemPrompt } from "./IAgenticaSystemPrompt";
 
/**
 * Configuration for Agentic Agent.
 *
 * `IAgenticaConfig` is an interface that defines the configuration
 * properties of the {@link Agentica}. With this configuration, you
 * can set the user's {@link locale}, {@link timezone}, and some of
 * {@link systemPrompt system prompts}.
 *
 * Also, you can affect to the LLM function selecing/calling logic by
 * configuring additional properties. For an example, if you configure the
 * {@link capacity} property, the AI chatbot will divide the functions
 * into the several groups with the configured capacity and select proper
 * functions to call by operating the multiple LLM function selecting
 * agents parallelly.
 *
 * @author Samchon
 */
export interface IAgenticaConfig extends IAgenticaConfigBase {
  /**
   * Agent executor.
   *
   * Executor function of Agentic AI's iteration plan to internal agents
   * running by the {@link Agentica.conversate} function.
   *
   * If you want to customize the agent execution plan, you can do it
   * by assigning you logic function of entire or partial to this property.
   * When customizing it, it would better to reference the
   * {@link ChatGptAgent.execute} function.
   *
   * @param ctx Context of the agent
   * @default ChatGptAgent.execute
   */
  executor?:
    | Partial<IAgenticaExecutor>
    | ((ctx: AgenticaContext) => Promise<void>);
 
  /**
   * System prompt messages.
   *
   * System prompt messages if you want to customize the system prompt
   * messages for each situation.
   */
  systemPrompt?: IAgenticaSystemPrompt;
 
  /**
   * Capacity of the LLM function selecting.
   *
   * When the A.I. chatbot selects a proper function to call, if the
   * number of functions registered in the
   * {@link IAgenticaProps.applications} is too much greater,
   * the A.I. chatbot often fallen into the hallucination.
   *
   * In that case, if you configure this property value, `Agentica`
   * will divide the functions into the several groups with the configured
   * capacity and select proper functions to call by operating the multiple
   * LLM function selecting agents parallelly.
   *
   * @default 100
   */
  capacity?: number;
 
  /**
   * Eliticism for the LLM function selecting.
   *
   * If you configure {@link capacity}, the A.I. chatbot will complete
   * the candidate functions to call which are selected by the multiple
   * LLM function selecting agents.
   *
   * Otherwise you configure this property as `false`, the A.I. chatbot
   * will not complete the candidate functions to call and just accept
   * every candidate functions to call which are selected by the multiple
   * LLM function selecting agents.
   *
   * @default true
   */
  eliticism?: boolean;
}