@agentica/core 0.10.4 → 0.11.0

package/src/context/AgenticaOperationSelection.ts

@@ -0,0 +1,27 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { IAgenticaOperationSelectionJson } from "../json/IAgenticaOperationSelectionJson";
+import { AgenticaOperation } from "./AgenticaOperation";
+
+export class AgenticaOperationSelection<Model extends ILlmSchema.Model> {
+  public readonly operation: AgenticaOperation<Model>;
+  public readonly reason: string;
+
+  public constructor(props: AgenticaOperationSelection.IProps<Model>) {
+    this.operation = props.operation;
+    this.reason = props.reason;
+  }
+
+  public toJSON(): IAgenticaOperationSelectionJson {
+    return {
+      operation: this.operation.toJSON(),
+      reason: this.reason,
+    };
+  }
+}
+export namespace AgenticaOperationSelection {
+  export interface IProps<Model extends ILlmSchema.Model> {
+    operation: AgenticaOperation<Model>;
+    reason: string;
+  }
+}

package/src/context/AgenticaTokenUsage.ts

@@ -0,0 +1,170 @@
+import typia from "typia";
+
+import { IAgenticaTokenUsageJson } from "../json/IAgenticaTokenUsageJson";
+
+export class AgenticaTokenUsage implements IAgenticaTokenUsageJson {
+  /**
+   * Aggregated token usage.
+   */
+  public readonly aggregate: IAgenticaTokenUsageJson.IComponent;
+
+  /**
+   * Token uasge of initializer agent.
+   */
+  public readonly initialize: IAgenticaTokenUsageJson.IComponent;
+
+  /**
+   * Token usage of function selector agent.
+   */
+  public readonly select: IAgenticaTokenUsageJson.IComponent;
+
+  /**
+   * Token usage of function canceler agent.
+   */
+  public readonly cancel: IAgenticaTokenUsageJson.IComponent;
+
+  /**
+   * Token usage of function caller agent.
+   */
+  public readonly call: IAgenticaTokenUsageJson.IComponent;
+
+  /**
+   * Token usage of function calling describer agent.
+   */
+  public readonly describe: IAgenticaTokenUsageJson.IComponent;
+
+  public constructor(props?: IAgenticaTokenUsageJson) {
+    if (props === undefined) {
+      const zero = AgenticaTokenUsage.zero();
+      this.aggregate = zero.aggregate;
+      this.initialize = zero.initialize;
+      this.select = zero.select;
+      this.cancel = zero.cancel;
+      this.call = zero.call;
+      this.describe = zero.describe;
+    } else {
+      this.aggregate = props.aggregate;
+      this.initialize = props.initialize;
+      this.select = props.select;
+      this.cancel = props.cancel;
+      this.call = props.call;
+      this.describe = props.describe;
+    }
+  }
+
+  public increment(y: IAgenticaTokenUsageJson): void {
+    const increment = (
+      x: IAgenticaTokenUsageJson.IComponent,
+      y: IAgenticaTokenUsageJson.IComponent,
+    ): void => {
+      x.total += y.total;
+      x.input.total += y.input.total;
+      x.input.cached += y.input.cached;
+      x.output.total += y.output.total;
+      x.output.reasoning += y.output.reasoning;
+      x.output.accepted_prediction += y.output.accepted_prediction;
+      x.output.rejected_prediction += y.output.rejected_prediction;
+    };
+    increment(this.aggregate, y.aggregate);
+    increment(this.initialize, y.initialize);
+    increment(this.select, y.select);
+    increment(this.cancel, y.cancel);
+    increment(this.call, y.call);
+    increment(this.describe, y.describe);
+  }
+
+  public toJSON(): IAgenticaTokenUsageJson {
+    return typia.misc.clone<IAgenticaTokenUsageJson>(this);
+  }
+
+  public static zero(): AgenticaTokenUsage {
+    const component = (): IAgenticaTokenUsageJson.IComponent => ({
+      total: 0,
+      input: {
+        total: 0,
+        cached: 0,
+      },
+      output: {
+        total: 0,
+        reasoning: 0,
+        accepted_prediction: 0,
+        rejected_prediction: 0,
+      },
+    });
+    return new AgenticaTokenUsage({
+      aggregate: component(),
+      initialize: component(),
+      select: component(),
+      cancel: component(),
+      call: component(),
+      describe: component(),
+    });
+  }
+
+  public static plus(
+    x: AgenticaTokenUsage,
+    y: AgenticaTokenUsage,
+  ): AgenticaTokenUsage {
+    const z: AgenticaTokenUsage = new AgenticaTokenUsage(x);
+    z.increment(y.toJSON());
+    return z;
+  }
+}
+export namespace AgenticaTokenUsage {
+  export interface IComponent {
+    /**
+     * Total token usage.
+     */
+    total: number;
+
+    /**
+     * Input token usage of detailed.
+     */
+    input: IInput;
+
+    /**
+     * Output token usage of detailed.
+     */
+    output: IOutput;
+  }
+
+  /**
+   * Input token usage of detailed.
+   */
+  export interface IInput {
+    /**
+     * Total amount of input token uasge.
+     */
+    total: number;
+
+    /**
+     * Cached token usage.
+     */
+    cached: number;
+  }
+
+  /**
+   * Output token usage of detailed.
+   */
+  export interface IOutput {
+    /**
+     * Total amount of output token usage.
+     */
+    total: number;
+
+    /**
+     * Reasoning token usage.
+     */
+    reasoning: number;
+
+    /**
+     * Prediction token usage.
+     */
+    accepted_prediction: number;
+
+    /**
+     * Rejected prediction token usage.
+     */
+    rejected_prediction: number;
+  }
+}

package/src/context/internal/AgenticaTokenUsageAggregator.ts

@@ -0,0 +1,66 @@
+import { CompletionUsage } from "openai/resources";
+import { Primitive } from "typia";
+
+import { AgenticaTokenUsage } from "../AgenticaTokenUsage";
+
+export namespace AgenticaTokenUsageAggregator {
+  export const aggregate = (props: {
+    kind: Exclude<keyof Primitive<AgenticaTokenUsage>, "aggregate">;
+    completionUsage: CompletionUsage;
+    usage: AgenticaTokenUsage;
+  }): void => {
+    if (!props.completionUsage) return;
+
+    //----
+    // COMPONENT
+    //----
+    const component: AgenticaTokenUsage.IComponent = props.usage[props.kind];
+
+    // TOTAL
+    component.total += props.completionUsage.total_tokens;
+
+    // PROMPT
+    component.input.total += props.completionUsage.prompt_tokens;
+    component.input.total +=
+      props.completionUsage.prompt_tokens_details?.audio_tokens ?? 0;
+    component.input.cached +=
+      props.completionUsage.prompt_tokens_details?.cached_tokens ?? 0;
+
+    // COMPLETION
+    component.output.total += props.completionUsage.total_tokens;
+    component.output.accepted_prediction +=
+      props.completionUsage.completion_tokens_details
+        ?.accepted_prediction_tokens ?? 0;
+    component.output.reasoning +=
+      props.completionUsage.completion_tokens_details?.reasoning_tokens ?? 0;
+    component.output.rejected_prediction +=
+      props.completionUsage.completion_tokens_details
+        ?.rejected_prediction_tokens ?? 0;
+
+    //----
+    // RE-AGGREGATE
+    //----
+    const sum = (getter: (comp: AgenticaTokenUsage.IComponent) => number) =>
+      (
+        Object.entries(props.usage) as [
+          keyof AgenticaTokenUsage,
+          AgenticaTokenUsage.IComponent,
+        ][]
+      )
+        .filter(([key]) => key !== "aggregate")
+        .map(([, comp]) => getter(comp))
+        .reduce((a, b) => a + b, 0);
+    const aggregate: AgenticaTokenUsage.IComponent = props.usage.aggregate;
+    aggregate.total = sum((comp) => comp.total);
+    aggregate.input.total = sum((comp) => comp.input.total);
+    aggregate.input.cached = sum((comp) => comp.input.cached);
+    aggregate.output.total = sum((comp) => comp.output.total);
+    aggregate.output.reasoning = sum((comp) => comp.output.reasoning);
+    aggregate.output.accepted_prediction = sum(
+      (comp) => comp.output.accepted_prediction,
+    );
+    aggregate.output.rejected_prediction = sum(
+      (comp) => comp.output.rejected_prediction,
+    );
+  };
+}

package/src/events/AgenticaCallEvent.ts

@@ -0,0 +1,36 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { AgenticaOperation } from "../context/AgenticaOperation";
+import { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+import { AgenticaEventBase } from "./AgenticaEventBase";
+
+export class AgenticaCallEvent<
+  Model extends ILlmSchema.Model,
+> extends AgenticaEventBase<"call"> {
+  public readonly id: string;
+  public readonly operation: AgenticaOperation<Model>;
+  public arguments: Record<string, any>;
+
+  public constructor(props: AgenticaCallEvent.IProps<Model>) {
+    super("call");
+    this.id = props.id;
+    this.operation = props.operation;
+    this.arguments = props.arguments;
+  }
+
+  public toJSON(): IAgenticaEventJson.ICall {
+    return {
+      type: "call",
+      id: this.id,
+      operation: this.operation.toJSON(),
+      arguments: this.arguments,
+    };
+  }
+}
+export namespace AgenticaCallEvent {
+  export interface IProps<Model extends ILlmSchema.Model> {
+    id: string;
+    operation: AgenticaOperation<Model>;
+    arguments: Record<string, any>;
+  }
+}

package/src/events/AgenticaCancelEvent.ts

@@ -0,0 +1,28 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
+import { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+import { AgenticaEventBase } from "./AgenticaEventBase";
+
+export class AgenticaCancelEvent<
+  Model extends ILlmSchema.Model,
+> extends AgenticaEventBase<"cancel"> {
+  public readonly selection: AgenticaOperationSelection<Model>;
+
+  public constructor(props: AgenticaCancelEvent.IProps<Model>) {
+    super("cancel");
+    this.selection = props.selection;
+  }
+
+  public toJSON(): IAgenticaEventJson.ICancel {
+    return {
+      type: "cancel",
+      selection: this.selection.toJSON(),
+    };
+  }
+}
+export namespace AgenticaCancelEvent {
+  export interface IProps<Model extends ILlmSchema.Model> {
+    selection: AgenticaOperationSelection<Model>;
+  }
+}

package/src/events/AgenticaDescribeEvent.ts

@@ -0,0 +1,61 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+import { AgenticaDescribePrompt } from "../prompts/AgenticaDescribePrompt";
+import { AgenticaExecutePrompt } from "../prompts/AgenticaExecutePrompt";
+import { AgenticaEventBase } from "./AgenticaEventBase";
+
+export class AgenticaDescribeEvent<
+  Model extends ILlmSchema.Model,
+> extends AgenticaEventBase<"describe"> {
+  public readonly executes: AgenticaExecutePrompt<Model>[];
+  public readonly stream: ReadableStream<string>;
+  public get text(): string {
+    return this.get_();
+  }
+  public get done(): boolean {
+    return this.done_();
+  }
+
+  public constructor(props: AgenticaDescribeEvent.IProps<Model>) {
+    super("describe");
+    this.stream = props.stream;
+    this.executes = props.executes;
+    this.done_ = props.done;
+    this.get_ = props.get;
+    this.join_ = props.join;
+  }
+
+  public join(): Promise<string> {
+    return this.join_();
+  }
+
+  public toJSON(): IAgenticaEventJson.IDescribe {
+    return {
+      type: "describe",
+      executes: this.executes.map((e) => e.toJSON()),
+      text: this.text,
+      done: this.done,
+    };
+  }
+
+  public toPrompt(): AgenticaDescribePrompt<Model> {
+    return new AgenticaDescribePrompt({
+      executes: this.executes,
+      text: this.text,
+    });
+  }
+
+  private readonly done_: () => boolean;
+  private readonly get_: () => string;
+  private readonly join_: () => Promise<string>;
+}
+export namespace AgenticaDescribeEvent {
+  export interface IProps<Model extends ILlmSchema.Model> {
+    executes: AgenticaExecutePrompt<Model>[];
+    stream: ReadableStream<string>;
+    done: () => boolean;
+    get: () => string;
+    join: () => Promise<string>;
+  }
+}

package/src/events/AgenticaEvent.ts

@@ -0,0 +1,36 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { AgenticaCallEvent } from "./AgenticaCallEvent";
+import { AgenticaCancelEvent } from "./AgenticaCancelEvent";
+import { AgenticaDescribeEvent } from "./AgenticaDescribeEvent";
+import { AgenticaExecuteEvent } from "./AgenticaExecuteEvent";
+import { AgenticaInitializeEvent } from "./AgenticaInitializeEvent";
+import { AgenticaRequestEvent } from "./AgenticaRequestEvent";
+import { AgenticaResponseEvent } from "./AgenticaResponseEvent";
+import { AgenticaSelectEvent } from "./AgenticaSelectEvent";
+import { AgenticaTextEvent } from "./AgenticaTextEvent";
+
+export type AgenticaEvent<Model extends ILlmSchema.Model> =
+  | AgenticaCallEvent<Model>
+  | AgenticaCancelEvent<Model>
+  | AgenticaDescribeEvent<Model>
+  | AgenticaExecuteEvent<Model>
+  | AgenticaInitializeEvent
+  | AgenticaRequestEvent
+  | AgenticaResponseEvent
+  | AgenticaSelectEvent<Model>
+  | AgenticaTextEvent;
+export namespace AgenticaEvent {
+  export type Type = AgenticaEvent<any>["type"];
+  export type Mapper<Model extends ILlmSchema.Model> = {
+    call: AgenticaCallEvent<Model>;
+    cancel: AgenticaCancelEvent<Model>;
+    describe: AgenticaDescribeEvent<Model>;
+    execute: AgenticaExecuteEvent<Model>;
+    initialize: AgenticaInitializeEvent;
+    request: AgenticaRequestEvent;
+    response: AgenticaResponseEvent;
+    select: AgenticaSelectEvent<Model>;
+    text: AgenticaTextEvent;
+  };
+}

package/src/events/AgenticaEventBase.ts

@@ -0,0 +1,7 @@
+export abstract class AgenticaEventBase<Type extends string> {
+  public readonly type: Type;
+
+  public constructor(type: Type) {
+    this.type = type;
+  }
+}

package/src/{typings/AgenticaSource.ts → events/AgenticaEventSource.ts}

@@ -1,4 +1,4 @@
-export type AgenticaSource =
+export type AgenticaEventSource =
   | "initialize"
   | "select"
   | "cancel"

package/src/events/AgenticaExecuteEvent.ts

@@ -0,0 +1,50 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { AgenticaOperation } from "../context/AgenticaOperation";
+import { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+import { AgenticaExecutePrompt } from "../prompts/AgenticaExecutePrompt";
+import { AgenticaEventBase } from "./AgenticaEventBase";
+
+export class AgenticaExecuteEvent<
+  Model extends ILlmSchema.Model,
+> extends AgenticaEventBase<"execute"> {
+  public readonly id: string;
+  public readonly operation: AgenticaOperation<Model>;
+  public readonly arguments: Record<string, any>;
+  public readonly value: any;
+
+  public constructor(props: AgenticaExecuteEvent.IProps<Model>) {
+    super("execute");
+    this.id = props.id;
+    this.operation = props.operation;
+    this.arguments = props.arguments;
+    this.value = props.value;
+  }
+
+  public toJSON(): IAgenticaEventJson.IExecute {
+    return {
+      type: "execute",
+      id: this.id,
+      operation: this.operation.toJSON(),
+      arguments: this.arguments,
+      value: this.value,
+    };
+  }
+
+  public toPrompt(): AgenticaExecutePrompt<Model> {
+    return new AgenticaExecutePrompt({
+      id: this.id,
+      operation: this.operation,
+      arguments: this.arguments,
+      value: this.value,
+    });
+  }
+}
+export namespace AgenticaExecuteEvent {
+  export interface IProps<Model extends ILlmSchema.Model> {
+    id: string;
+    operation: AgenticaOperation<Model>;
+    arguments: Record<string, any>;
+    value: any;
+  }
+}

package/src/events/AgenticaInitializeEvent.ts

@@ -0,0 +1,14 @@
+import { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+import { AgenticaEventBase } from "./AgenticaEventBase";
+
+export class AgenticaInitializeEvent extends AgenticaEventBase<"initialize"> {
+  public constructor() {
+    super("initialize");
+  }
+
+  public toJSON(): IAgenticaEventJson.IInitialize {
+    return {
+      type: "initialize",
+    };
+  }
+}

package/src/events/AgenticaRequestEvent.ts

@@ -0,0 +1,45 @@
+import OpenAI from "openai";
+
+import { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+import { AgenticaEventBase } from "./AgenticaEventBase";
+import { AgenticaEventSource } from "./AgenticaEventSource";
+
+export class AgenticaRequestEvent extends AgenticaEventBase<"request"> {
+  public readonly source: AgenticaEventSource;
+  public readonly body: OpenAI.ChatCompletionCreateParamsStreaming;
+  public readonly options?: OpenAI.RequestOptions | undefined;
+
+  public constructor(props: AgenticaRequestEvent.IProps) {
+    super("request");
+    this.source = props.source;
+    this.body = props.body;
+    this.options = props.options;
+  }
+
+  public toJSON(): IAgenticaEventJson.IRequest {
+    return {
+      type: "request",
+      source: this.source,
+      body: this.body,
+      options: this.options,
+    };
+  }
+}
+export namespace AgenticaRequestEvent {
+  export interface IProps {
+    /**
+     * The source agent of the request.
+     */
+    source: AgenticaEventSource;
+
+    /**
+     * Request body.
+     */
+    body: OpenAI.ChatCompletionCreateParamsStreaming;
+
+    /**
+     * Options for the request.
+     */
+    options?: OpenAI.RequestOptions | undefined;
+  }
+}

package/src/events/AgenticaResponseEvent.ts

@@ -0,0 +1,48 @@
+import OpenAI from "openai";
+
+import { AgenticaEventBase } from "./AgenticaEventBase";
+import { AgenticaEventSource } from "./AgenticaEventSource";
+
+export class AgenticaResponseEvent extends AgenticaEventBase<"response"> {
+  public readonly source: AgenticaEventSource;
+  public readonly body: OpenAI.ChatCompletionCreateParamsStreaming;
+  public readonly stream: ReadableStream<OpenAI.ChatCompletionChunk>;
+  public readonly options?: OpenAI.RequestOptions | undefined;
+  public readonly join: () => Promise<OpenAI.ChatCompletion>;
+
+  public constructor(props: AgenticaResponseEvent.IProps) {
+    super("response");
+    this.source = props.source;
+    this.body = props.body;
+    this.stream = props.stream;
+    this.options = props.options;
+    this.join = props.join;
+  }
+}
+export namespace AgenticaResponseEvent {
+  export interface IProps {
+    /**
+     * The source agent of the response.
+     */
+    source: AgenticaEventSource;
+
+    /**
+     * Request body.
+     */
+    body: OpenAI.ChatCompletionCreateParamsStreaming;
+
+    /**
+     * Options for the request.
+     */
+    options?: OpenAI.RequestOptions | undefined;
+    /**
+     * The text content stream.
+     */
+    stream: ReadableStream<OpenAI.ChatCompletionChunk>;
+
+    /**
+     * Get the description text.
+     */
+    join: () => Promise<OpenAI.ChatCompletion>;
+  }
+}

package/src/events/AgenticaSelectEvent.ts

@@ -0,0 +1,37 @@
+import { ILlmSchema } from "@samchon/openapi";
+import { v4 } from "uuid";
+
+import { AgenticaOperationSelection } from "../context/AgenticaOperationSelection";
+import { IAgenticaEventJson } from "../json/IAgenticaEventJson";
+import { AgenticaSelectPrompt } from "../prompts/AgenticaSelectPrompt";
+import { AgenticaEventBase } from "./AgenticaEventBase";
+
+export class AgenticaSelectEvent<
+  Model extends ILlmSchema.Model,
+> extends AgenticaEventBase<"select"> {
+  public readonly selection: AgenticaOperationSelection<Model>;
+
+  public constructor(props: AgenticaSelectEvent.IProps<Model>) {
+    super("select");
+    this.selection = props.selection;
+  }
+
+  public toJSON(): IAgenticaEventJson.ISelect {
+    return {
+      type: "select",
+      selection: this.selection.toJSON(),
+    };
+  }
+
+  public toPrompt(): AgenticaSelectPrompt<Model> {
+    return new AgenticaSelectPrompt({
+      id: v4(),
+      selections: [this.selection],
+    });
+  }
+}
+export namespace AgenticaSelectEvent {
+  export interface IProps<Model extends ILlmSchema.Model> {
+    selection: AgenticaOperationSelection<Model>;
+  }
+}