@autobe/agent 0.16.1 → 0.18.0

package/src/orchestrate/interface/orchestrateInterfaceOperations.ts

@@ -1,16 +1,21 @@
-import { IAgenticaController, MicroAgentica } from "@agentica/core";
-import { AutoBeOpenApi } from "@autobe/interface";
+import { IAgenticaController } from "@agentica/core";
+import {
+  AutoBeInterfaceOperationsEvent,
+  AutoBeOpenApi,
+} from "@autobe/interface";
+import { AutoBeEndpointComparator, StringUtil } from "@autobe/utils";
 import { ILlmApplication, ILlmSchema, IValidation } from "@samchon/openapi";
 import { HashMap, HashSet, IPointer } from "tstl";
 import typia from "typia";
+import { Escaper } from "typia/lib/utils/Escaper";
 import { NamingConvention } from "typia/lib/utils/NamingConvention";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { assertSchemaModel } from "../../context/assertSchemaModel";
 import { divideArray } from "../../utils/divideArray";
-import { enforceToolCall } from "../../utils/enforceToolCall";
-import { forceRetry } from "../../utils/forceRetry";
+import { emplaceMap } from "../../utils/emplaceMap";
 import { transformInterfaceOperationHistories } from "./histories/transformInterfaceOperationHistories";
+import { orchestrateInterfaceOperationsReview } from "./orchestrateInterfaceOperationsReview";
 import { IAutoBeInterfaceOperationApplication } from "./structures/IAutoBeInterfaceOperationApplication";
 import { OpenApiEndpointComparator } from "./utils/OpenApiEndpointComparator";
 
@@ -25,59 +30,70 @@ export async function orchestrateInterfaceOperations<
     array: endpoints,
     capacity,
   });
-  const progress: IProgress = {
+  const operationsProgress: IProgress = {
     total: endpoints.length,
     completed: 0,
   };
-  const operations: AutoBeOpenApi.IOperation[][] = await Promise.all(
-    matrix.map(async (it) => {
-      const row: AutoBeOpenApi.IOperation[] = await divideAndConquer(
-        ctx,
-        it,
-        3,
-        progress,
-      );
-      ctx.dispatch({
-        type: "interfaceOperations",
-        operations: row,
-        ...progress,
-        step: ctx.state().analyze?.step ?? 0,
-        created_at: new Date().toISOString(),
-      });
-      return row;
-    }),
-  );
-  return operations.flat();
+
+  const operationsReviewProgress: IProgress = {
+    total: endpoints.length,
+    completed: 0,
+  };
+
+  const operations: AutoBeOpenApi.IOperation[] = (
+    await Promise.all(
+      matrix.map(async (it) => {
+        const row: AutoBeOpenApi.IOperation[] = await divideAndConquer(
+          ctx,
+          it,
+          3,
+          operationsProgress,
+          operationsReviewProgress,
+        );
+        return row;
+      }),
+    )
+  ).flat();
+
+  return operations;
 }
 
 async function divideAndConquer<Model extends ILlmSchema.Model>(
   ctx: AutoBeContext<Model>,
   endpoints: AutoBeOpenApi.IEndpoint[],
   retry: number,
-  progress: IProgress,
+  operationsProgress: IProgress,
+  operationsReviewProgress: IProgress,
 ): Promise<AutoBeOpenApi.IOperation[]> {
   const remained: HashSet<AutoBeOpenApi.IEndpoint> = new HashSet(
     endpoints,
     OpenApiEndpointComparator.hashCode,
     OpenApiEndpointComparator.equals,
   );
-  const operations: HashMap<AutoBeOpenApi.IEndpoint, AutoBeOpenApi.IOperation> =
+  const unique: HashMap<AutoBeOpenApi.IEndpoint, AutoBeOpenApi.IOperation> =
     new HashMap(
       OpenApiEndpointComparator.hashCode,
       OpenApiEndpointComparator.equals,
     );
   for (let i: number = 0; i < retry; ++i) {
-    if (remained.empty() === true || operations.size() >= endpoints.length)
-      break;
-    const newbie: AutoBeOpenApi.IOperation[] = await forceRetry(() =>
-      process(ctx, Array.from(remained), progress),
+    if (remained.empty() === true || unique.size() >= endpoints.length) break;
+    const operations: AutoBeOpenApi.IOperation[] = await process(
+      ctx,
+      Array.from(remained),
+      operationsProgress,
     );
+    const newbie: AutoBeOpenApi.IOperation[] =
+      await orchestrateInterfaceOperationsReview(
+        ctx,
+        operations,
+        operationsReviewProgress,
+      );
     for (const item of newbie) {
-      operations.set(item, item);
+      unique.set(item, item);
       remained.erase(item);
     }
   }
-  return operations.toJSON().map((it) => it.second);
+  return unique.toJSON().map((it) => it.second);
 }
 
 async function process<Model extends ILlmSchema.Model>(
@@ -89,65 +105,62 @@ async function process<Model extends ILlmSchema.Model>(
   const pointer: IPointer<AutoBeOpenApi.IOperation[] | null> = {
     value: null,
   };
-  const agentica: MicroAgentica<Model> = new MicroAgentica({
-    model: ctx.model,
-    vendor: ctx.vendor,
-    config: {
-      ...(ctx.config ?? {}),
-      executor: {
-        describe: null,
-      },
-    },
+  const { tokenUsage } = await ctx.conversate({
+    source: "interfaceOperations",
     histories: transformInterfaceOperationHistories(ctx.state(), endpoints),
-    controllers: [
-      createApplication({
-        model: ctx.model,
-        roles: ctx.state().analyze?.roles.map((it) => it.name) ?? [],
-        build: (operations) => {
-          pointer.value ??= [];
-          const matrix: AutoBeOpenApi.IOperation[][] = operations.map((op) => {
-            if (op.authorizationRoles.length === 0)
-              return [
-                {
-                  ...op,
-                  path:
-                    "/" +
-                    [prefix, ...op.path.split("/")]
-                      .filter((it) => it !== "")
-                      .join("/"),
-                  authorizationRole: null,
-                },
-              ];
-            return op.authorizationRoles.map((role) => ({
-              ...op,
-              path:
-                "/" +
-                [prefix, role, ...op.path.split("/")]
-                  .filter((it) => it !== "")
-                  .join("/"),
-              authorizationRole: role,
-            }));
-          });
-          progress.completed += matrix.flat().length;
-          progress.total += matrix
-            .filter((it) => it.length > 1)
-            .map((it) => it.length - 1)
-            .reduce((a, b) => a + b, 0);
-          pointer.value.push(...matrix.flat());
-        },
-      }),
-    ],
-  });
-  enforceToolCall(agentica);
-  await agentica.conversate("Make API operations").finally(() => {
-    const tokenUsage = agentica.getTokenUsage();
-    ctx.usage().record(tokenUsage, ["interface"]);
+    controller: createController({
+      model: ctx.model,
+      roles: ctx.state().analyze?.roles.map((it) => it.name) ?? [],
+      build: (operations) => {
+        pointer.value ??= [];
+        const matrix: AutoBeOpenApi.IOperation[][] = operations.map((op) => {
+          if (op.authorizationRoles.length === 0)
+            return [
+              {
+                ...op,
+                path:
+                  "/" +
+                  [prefix, ...op.path.split("/")]
+                    .filter((it) => it !== "")
+                    .join("/"),
+                authorizationRole: null,
+              },
+            ];
+
+          return op.authorizationRoles.map((role) => ({
+            ...op,
+            path:
+              "/" +
+              [prefix, role, ...op.path.split("/")]
+                .filter((it) => it !== "")
+                .join("/"),
+            authorizationRole: role,
+          }));
+        });
+        progress.completed += matrix.flat().length;
+        progress.total += matrix
+          .filter((it) => it.length > 1)
+          .map((it) => it.length - 1)
+          .reduce((a, b) => a + b, 0);
+        pointer.value.push(...matrix.flat());
+      },
+    }),
+    enforceFunctionCall: true,
+    message: "Make API operations",
   });
   if (pointer.value === null) throw new Error("Failed to create operations."); // never be happened
+  ctx.dispatch({
+    type: "interfaceOperations",
+    operations: pointer.value,
+    tokenUsage,
+    ...progress,
+    step: ctx.state().analyze?.step ?? 0,
+    created_at: new Date().toISOString(),
+  } satisfies AutoBeInterfaceOperationsEvent);
   return pointer.value;
 }
 
-function createApplication<Model extends ILlmSchema.Model>(props: {
+function createController<Model extends ILlmSchema.Model>(props: {
   model: Model;
   roles: string[];
   build: (
@@ -156,10 +169,9 @@ function createApplication<Model extends ILlmSchema.Model>(props: {
 }): IAgenticaController.IClass<Model> {
   assertSchemaModel(props.model);
 
-  const application: ILlmApplication<Model> = collection[
-    props.model
-  ] as unknown as ILlmApplication<Model>;
-  application.functions[0].validate = (next: unknown) => {
+  const validate = (
+    next: unknown,
+  ): IValidation<IAutoBeInterfaceOperationApplication.IProps> => {
     const result: IValidation<IAutoBeInterfaceOperationApplication.IProps> =
       typia.validate<IAutoBeInterfaceOperationApplication.IProps>(next);
     if (result.success === false) return result;
@@ -168,6 +180,7 @@ function createApplication<Model extends ILlmSchema.Model>(props: {
       result.data.operations;
     const errors: IValidation.IError[] = [];
     operations.forEach((op, i) => {
+      // get method has request body
       if (op.method === "get" && op.requestBody !== null)
         errors.push({
           path: `$input.operations[${i}].requestBody`,
@@ -175,6 +188,23 @@ function createApplication<Model extends ILlmSchema.Model>(props: {
             "GET method should not have request body. Change method, or re-design the operation.",
           value: op.requestBody,
         });
+      // operation name
+      if (Escaper.variable(op.name) === false)
+        errors.push({
+          path: `$input.operations[${i}].name`,
+          expected: "<valid_variable_name>",
+          value: op.name,
+          description: StringUtil.trim`
+            The operation name will be converted to the API controller method
+            (function) name, so the operation.name must be a valid JavaScript 
+            variable/function name.
+
+            However, what you've configured value ${JSON.stringify(op.name)}
+            is not a valid JavaScript variable/function name. Please change
+            it to a valid variable/function name.
+          `,
+        });
+      // validate roles
       if (props.roles.length === 0) op.authorizationRoles = [];
       else if (op.authorizationRoles.length !== 0 && props.roles.length !== 0)
         op.authorizationRoles.forEach((role, j) => {
@@ -193,6 +223,72 @@ function createApplication<Model extends ILlmSchema.Model>(props: {
           });
         });
     });
+
+    // validate duplicated endpoints
+    const endpoints: HashMap<AutoBeOpenApi.IEndpoint, number[]> = new HashMap(
+      AutoBeEndpointComparator.hashCode,
+      AutoBeEndpointComparator.equals,
+    );
+    operations.forEach((op, i) => {
+      const key: AutoBeOpenApi.IEndpoint = {
+        path: op.path,
+        method: op.method,
+      };
+      const it = endpoints.find(key);
+      if (it.equals(endpoints.end()) === false) {
+        const indexes: number[] = it.second;
+        errors.push({
+          path: `$input.operations[${i}].{"path"|"method"}`,
+          expected: "Unique endpoint (path and method)",
+          value: key,
+          description: [
+            `Duplicated endpoint detected (method: ${op.method}, path: ${op.path}).`,
+            "",
+            "The duplicated endpoints of others are located in below accessors.",
+            "Check them, and consider which operation endpoint would be proper to modify.",
+            ...indexes.map(
+              (idx) => `- $input.operations.[${idx}].{"path"|"method"}`,
+            ),
+          ].join("\n"),
+        });
+        indexes.push(i);
+      } else endpoints.emplace(key, [i]);
+    });
+
+    // validate duplicated method names
+    const accessors: Map<string, number[]> = new Map();
+    operations.forEach((op, i) => {
+      const key: string =
+        op.path
+          .split("/")
+          .filter((e) => e[0] !== "{" && e.at(-1) !== "}")
+          .filter((e) => e.length !== 0)
+          .join(".") + `.${op.name}`;
+      const indexes: number[] = emplaceMap(accessors, key, () => []);
+      if (indexes.length !== 0) {
+        errors.push({
+          path: `$input.operations[${i}].name`,
+          expected: "Unique name in the same accessor scope.",
+          value: op.name,
+          description: [
+            `Duplicated operation accessor detected (name: ${op.name}, accessor: ${key}).`,
+            "",
+            "The operation name must be unique within the parent accessor.",
+            "In other worlds, the operation accessor determined by the name",
+            "must be unique in the OpenAPI document.",
+            "",
+            "Here is the list of elements of duplicated operation names.",
+            "Check them, and consider which operation name would be proper to modify.",
+            "",
+            ...indexes
+              .map((idx) => `- ${operations[idx].name} (accessor: ${key})`)
+              .join("\n"),
+          ].join("\n"),
+        });
+      }
+      indexes.push(i);
+    });
+
     if (errors.length !== 0)
       return {
         success: false,
@@ -201,6 +297,12 @@ function createApplication<Model extends ILlmSchema.Model>(props: {
       };
     return result;
   };
+  const application: ILlmApplication<Model> = collection[
+    props.model === "chatgpt" ? "chatgpt" : "claude"
+  ](
+    validate,
+  ) satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
+
   return {
     protocol: "class",
     name: "interface",
@@ -213,24 +315,26 @@ function createApplication<Model extends ILlmSchema.Model>(props: {
   };
 }
 
-const claude = typia.llm.application<
-  IAutoBeInterfaceOperationApplication,
-  "claude",
-  { reference: true }
->();
 const collection = {
-  chatgpt: typia.llm.application<
-    IAutoBeInterfaceOperationApplication,
-    "chatgpt",
-    { reference: true }
-  >(),
-  claude,
-  llama: claude,
-  deepseek: claude,
-  "3.1": claude,
+  chatgpt: (validate: Validator) =>
+    typia.llm.application<IAutoBeInterfaceOperationApplication, "chatgpt">({
+      validate: {
+        makeOperations: validate,
+      },
+    }),
+  claude: (validate: Validator) =>
+    typia.llm.application<IAutoBeInterfaceOperationApplication, "claude">({
+      validate: {
+        makeOperations: validate,
+      },
+    }),
 };
 
 interface IProgress {
   completed: number;
   total: number;
 }
+
+type Validator = (
+  input: unknown,
+) => IValidation<IAutoBeInterfaceOperationApplication.IProps>;

package/src/orchestrate/interface/orchestrateInterfaceOperationsReview.ts

@@ -0,0 +1,84 @@
+import { IAgenticaController } from "@agentica/core";
+import {
+  AutoBeInterfaceOperationsReviewEvent,
+  AutoBeOpenApi,
+} from "@autobe/interface";
+import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
+import { IPointer } from "tstl";
+import typia from "typia";
+
+import { AutoBeContext } from "../../context/AutoBeContext";
+import { IProgress } from "../internal/IProgress";
+import { transformInterfaceOperationsReviewHistories } from "./histories/transformInterfaceOperationsReviewHistories";
+import { IAutoBeInterfaceOperationsReviewApplication } from "./structures/IAutoBeInterfaceOperationsReviewApplication";
+
+export async function orchestrateInterfaceOperationsReview<
+  Model extends ILlmSchema.Model,
+>(
+  ctx: AutoBeContext<Model>,
+  operations: AutoBeOpenApi.IOperation[],
+  progress: IProgress,
+): Promise<AutoBeOpenApi.IOperation[]> {
+  const pointer: IPointer<IAutoBeInterfaceOperationsReviewApplication.IProps | null> =
+    {
+      value: null,
+    };
+  const { tokenUsage } = await ctx.conversate({
+    source: "interfaceOperationsReview",
+    histories: transformInterfaceOperationsReviewHistories(ctx, operations),
+    controller: createReviewController({
+      model: ctx.model,
+      build: (next: IAutoBeInterfaceOperationsReviewApplication.IProps) => {
+        pointer.value = next;
+      },
+    }),
+    enforceFunctionCall: false,
+    message: "Review the operations",
+  });
+  if (pointer.value === null) throw new Error("Failed to review operations.");
+
+  ctx.dispatch({
+    type: "interfaceOperationsReview",
+    operations: pointer.value.content,
+    review: pointer.value.review,
+    plan: pointer.value.plan,
+    content: pointer.value.content,
+    tokenUsage,
+    created_at: new Date().toISOString(),
+    step: ctx.state().analyze?.step ?? 0,
+    total: progress.total,
+    completed: ++progress.completed,
+  } satisfies AutoBeInterfaceOperationsReviewEvent);
+  return pointer.value.content;
+}
+
+function createReviewController<Model extends ILlmSchema.Model>(props: {
+  model: Model;
+  build: (reviews: IAutoBeInterfaceOperationsReviewApplication.IProps) => void;
+}): IAgenticaController.IClass<Model> {
+  const application: ILlmApplication<Model> = collection[
+    props.model === "chatgpt" ? "chatgpt" : "claude"
+  ] satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
+
+  return {
+    protocol: "class",
+    name: "review",
+    application,
+    execute: {
+      reviewOperations: (next) => {
+        props.build(next);
+      },
+    } satisfies IAutoBeInterfaceOperationsReviewApplication,
+  };
+}
+
+const collection = {
+  chatgpt: typia.llm.application<
+    IAutoBeInterfaceOperationsReviewApplication,
+    "chatgpt"
+  >(),
+  claude: typia.llm.application<
+    IAutoBeInterfaceOperationsReviewApplication,
+    "claude"
+  >(),
+};