@autobe/agent 0.25.0 → 0.25.1

package/src/orchestrate/interface/orchestrateInterfacePrerequisites.ts

@@ -0,0 +1,274 @@
+import { IAgenticaController } from "@agentica/core";
+import { AutoBeOpenApi, AutoBeProgressEventBase } from "@autobe/interface";
+import { AutoBeInterfacePrerequisite } from "@autobe/interface/src/histories/contents/AutoBeInterfacePrerequisite";
+import { AutoBeOpenApiEndpointComparator } from "@autobe/utils";
+import { ILlmApplication, ILlmSchema, IValidation } from "@samchon/openapi";
+import { HashMap, IPointer, Pair } from "tstl";
+import typia from "typia";
+import { v7 } from "uuid";
+
+import { AutoBeConfigConstant } from "../../constants/AutoBeConfigConstant";
+import { AutoBeContext } from "../../context/AutoBeContext";
+import { assertSchemaModel } from "../../context/assertSchemaModel";
+import { divideArray } from "../../utils/divideArray";
+import { executeCachedBatch } from "../../utils/executeCachedBatch";
+import { transformInterfacePrerequisitesHistories } from "./histories/transformInterfacePrerequisitesHistories";
+import { IAutoBeInterfacePrerequisitesApplication } from "./structures/IAutoBeInterfacePrerequisitesApplication";
+
+export async function orchestrateInterfacePrerequisites<
+  Model extends ILlmSchema.Model,
+>(
+  ctx: AutoBeContext<Model>,
+  document: AutoBeOpenApi.IDocument,
+  capacity: number = AutoBeConfigConstant.INTERFACE_CAPACITY,
+): Promise<AutoBeInterfacePrerequisite[]> {
+  const operations: AutoBeOpenApi.IOperation[] =
+    document.operations.filter((op) => op.authorizationType === null) ?? [];
+  const progress: AutoBeProgressEventBase = {
+    total: operations.length,
+    completed: 0,
+  };
+  const prerequisiteOperations: AutoBeOpenApi.IOperation[] =
+    document.operations.filter(
+      (op) => op.authorizationType === null && op.method === "post",
+    );
+
+  const dict: HashMap<AutoBeOpenApi.IEndpoint, AutoBeOpenApi.IOperation> =
+    new HashMap<AutoBeOpenApi.IEndpoint, AutoBeOpenApi.IOperation>(
+      prerequisiteOperations.map(
+        (op) => new Pair({ path: op.path, method: op.method }, op),
+      ),
+      AutoBeOpenApiEndpointComparator.hashCode,
+      AutoBeOpenApiEndpointComparator.equals,
+    );
+
+  const prerequisitesNotFound: string = [
+    `You have to select one of the endpoints below`,
+    "",
+    " method | path ",
+    "--------|------",
+    ...prerequisiteOperations
+      .map((op) => `\`${op.method}\` | \`${op.path}\``)
+      .join("\n"),
+  ].join("\n");
+
+  const exclude: AutoBeInterfacePrerequisite[] = [];
+  let include: AutoBeOpenApi.IOperation[] = [...operations];
+  let trial: number = 0;
+
+  do {
+    const matrix: AutoBeOpenApi.IOperation[][] = divideArray({
+      array: include,
+      capacity: capacity ?? AutoBeConfigConstant.INTERFACE_CAPACITY,
+    });
+
+    await executeCachedBatch(
+      matrix.map((ops) => async (promptCacheKey) => {
+        const row: AutoBeInterfacePrerequisite[] = await divideAndConquer(ctx, {
+          dict: dict,
+          document,
+          includes: ops,
+          progress,
+          promptCacheKey,
+          prerequisitesNotFound,
+        });
+        exclude.push(...row);
+        return row;
+      }),
+    );
+    include = include.filter((op) => {
+      if (
+        exclude.some(
+          (el) =>
+            el.endpoint.method === op.method && el.endpoint.path === op.path,
+        )
+      ) {
+        return false;
+      }
+      return true;
+    });
+  } while (include.length > 0 && ++trial < ctx.retry);
+  return exclude;
+}
+
+async function divideAndConquer<Model extends ILlmSchema.Model>(
+  ctx: AutoBeContext<Model>,
+  props: {
+    dict: HashMap<AutoBeOpenApi.IEndpoint, AutoBeOpenApi.IOperation>;
+    document: AutoBeOpenApi.IDocument;
+    includes: AutoBeOpenApi.IOperation[];
+    progress: AutoBeProgressEventBase;
+    promptCacheKey: string;
+    prerequisitesNotFound: string;
+  },
+): Promise<AutoBeInterfacePrerequisite[]> {
+  const pointer: IPointer<AutoBeInterfacePrerequisite[] | null> = {
+    value: null,
+  };
+
+  try {
+    const { tokenUsage } = await ctx.conversate({
+      source: "interfacePrerequisites",
+      controller: createController({
+        model: ctx.model,
+        document: props.document,
+        dict: props.dict,
+        includes: props.includes,
+        prerequisitesNotFound: props.prerequisitesNotFound,
+        build: (next) => {
+          pointer.value = next;
+        },
+      }),
+      histories: transformInterfacePrerequisitesHistories(
+        props.document,
+        props.includes,
+      ),
+      enforceFunctionCall: true,
+      promptCacheKey: props.promptCacheKey,
+      message: "Create prerequisite for the given operations",
+    });
+    if (pointer.value === null) return [];
+
+    props.progress.completed += pointer.value.length;
+    ctx.dispatch({
+      type: "interfacePrerequisites",
+      id: v7(),
+      created_at: new Date().toISOString(),
+      tokenUsage,
+      operations: pointer.value,
+      total: props.progress.total,
+      completed: props.progress.completed,
+      step: ctx.state().prisma?.step ?? 0,
+    });
+    return pointer.value;
+  } catch {
+    props.progress.completed += props.includes.length;
+    return [];
+  }
+}
+
+function createController<Model extends ILlmSchema.Model>(props: {
+  model: Model;
+  document: AutoBeOpenApi.IDocument;
+  dict: HashMap<AutoBeOpenApi.IEndpoint, AutoBeOpenApi.IOperation>;
+  includes: AutoBeOpenApi.IOperation[];
+  prerequisitesNotFound: string;
+  build: (next: AutoBeInterfacePrerequisite[]) => void;
+}): IAgenticaController.IClass<Model> {
+  assertSchemaModel(props.model);
+
+  const validate = (
+    next: unknown,
+  ): IValidation<IAutoBeInterfacePrerequisitesApplication.IProps> => {
+    const result: IValidation<IAutoBeInterfacePrerequisitesApplication.IProps> =
+      typia.validate<IAutoBeInterfacePrerequisitesApplication.IProps>(next);
+    if (result.success === false) return result;
+
+    const operations: AutoBeInterfacePrerequisite[] = result.data.operations;
+    const filteredOperations: AutoBeInterfacePrerequisite[] = [];
+    const errors: IValidation.IError[] = [];
+
+    props.includes.forEach((el) => {
+      // Find the matched operation in the includes
+      const matched: AutoBeInterfacePrerequisite | undefined = operations.find(
+        (op) =>
+          op.endpoint.method === el.method && op.endpoint.path === el.path,
+      );
+
+      // Remove duplicate operations in Prerequisites
+      if (matched) {
+        const prerequisites: Map<string, AutoBeOpenApi.IPrerequisite> =
+          new Map();
+        matched.prerequisites.forEach((op) => {
+          if (
+            prerequisites.get(op.endpoint.method + op.endpoint.path) !==
+            undefined
+          ) {
+            return;
+          }
+          prerequisites.set(op.endpoint.method + op.endpoint.path, op);
+        });
+        matched.prerequisites = Array.from(prerequisites.values());
+        filteredOperations.push(matched);
+      }
+    });
+
+    filteredOperations.forEach((op, i) => {
+      op.prerequisites.forEach((p, j) => {
+        if (props.dict.has(p.endpoint) === false) {
+          errors.push({
+            value: p.endpoint,
+            path: `$input.operations[${i}].prerequisites[${j}].endpoint`,
+            expected: "AutoBeOpenApi.IEndpoint",
+            description: props.prerequisitesNotFound,
+          });
+        }
+
+        if (
+          p.endpoint.method === op.endpoint.method &&
+          p.endpoint.path === op.endpoint.path
+        ) {
+          errors.push({
+            value: p.endpoint,
+            path: `$input.operations[${i}].prerequisites[${j}].endpoint`,
+            expected: "AutoBeOpenApi.IEndpoint",
+            description: "Self-reference is not allowed.",
+          });
+        }
+      });
+    });
+
+    return errors.length === 0
+      ? {
+          ...result,
+          data: {
+            ...result.data,
+            operations: filteredOperations,
+          },
+        }
+      : {
+          success: false,
+          data: {
+            ...result.data,
+            operations: filteredOperations,
+          },
+          errors,
+        };
+  };
+
+  const application: ILlmApplication<Model> = collection[
+    props.model === "chatgpt" ? "chatgpt" : "claude"
+  ](
+    validate,
+  ) satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
+
+  return {
+    protocol: "class",
+    name: "interface",
+    application,
+    execute: {
+      makePrerequisite: (next) => {
+        props.build(next.operations);
+      },
+    } satisfies IAutoBeInterfacePrerequisitesApplication,
+  };
+}
+
+const collection = {
+  chatgpt: (validate: Validator) =>
+    typia.llm.application<IAutoBeInterfacePrerequisitesApplication, "chatgpt">({
+      validate: {
+        makePrerequisite: validate,
+      },
+    }),
+  claude: (validate: Validator) =>
+    typia.llm.application<IAutoBeInterfacePrerequisitesApplication, "claude">({
+      validate: {
+        makePrerequisite: validate,
+      },
+    }),
+};
+
+type Validator = (
+  input: unknown,
+) => IValidation<IAutoBeInterfacePrerequisitesApplication.IProps>;

package/src/orchestrate/interface/orchestrateInterfaceSchemas.ts

@@ -205,7 +205,7 @@ function createController<Model extends ILlmSchema.Model>(props: {
   const validate = (
     next: unknown,
   ): IValidation<IAutoBeInterfaceSchemaApplication.IProps> => {
-    JsonSchemaFactory.fix("schemas", next);
+    JsonSchemaFactory.fixPage("schemas", next);
 
     const result: IValidation<IAutoBeInterfaceSchemaApplication.IProps> =
       typia.validate<IAutoBeInterfaceSchemaApplication.IProps>(next);

package/src/orchestrate/interface/orchestrateInterfaceSchemasReview.ts

@@ -140,7 +140,7 @@ function createController<Model extends ILlmSchema.Model>(props: {
   const validate = (
     next: unknown,
   ): IValidation<IAutoBeInterfaceSchemasReviewApplication.IProps> => {
-    JsonSchemaFactory.fix("content", next);
+    JsonSchemaFactory.fixPage("content", next);
 
     const result: IValidation<IAutoBeInterfaceSchemasReviewApplication.IProps> =
       typia.validate<IAutoBeInterfaceSchemasReviewApplication.IProps>(next);

package/src/orchestrate/interface/structures/IAutoBeInterfaceComplementApplication.ts

@@ -20,45 +20,6 @@ export interface IAutoBeInterfaceComplementApplication {
 }
 export namespace IAutoBeInterfaceComplementApplication {
   export interface IProps {
-    /**
-     * TypeScript draft code for complement schema definitions.
-     *
-     * This property contains TypeScript interface definitions for missing schema
-     * types that were referenced but not defined in the initial schema generation.
-     * Similar to the main schema draft, this serves as a preliminary TypeScript
-     * representation before converting to JSON Schema format.
-     *
-     * The draft helps ensure that complementary schemas maintain consistency with
-     * the existing type system and follow the same conventions as the primary schemas.
-     * 
-     * This draft typically includes:
-     * - Missing entity interfaces referenced via $ref
-     * - Nested object types used within other schemas
-     * - Shared utility types or enumerations
-     * - Any transitively referenced types
-     *
-     * The final schemas in the `schemas` property should be validated against and
-     * derived from this TypeScript draft to ensure type safety and consistency
-     * across the entire API specification.
-     *
-     * Example complement draft:
-     * ```typescript
-     * interface IUserProfile {
-     *   id: string;
-     *   userId: string;
-     *   displayName: string;
-     *   avatarUrl?: string;
-     * }
-     * 
-     * interface IAddress {
-     *   street: string;
-     *   city: string;
-     *   postalCode: string;
-     * }
-     * ```
-     */
-    draft: string;
-
     /**
      * A collection of missing schema definitions that need to be added to the
      * OpenAPI document's `components.schemas` section.

package/src/orchestrate/interface/structures/IAutoBeInterfaceGroupApplication.ts

@@ -94,18 +94,14 @@ export namespace IAutoBeInterfaceGroupApplication {
     name: string & tags.MinLength<1>;
 
     /**
-     * Comprehensive description of the group's scope, schema foundation, and
-     * purpose.
+     * Concise description of the group's core purpose.
      *
-     * **Required Content:**
+     * **Requirements:**
+     * - Keep it brief and focused (50-200 characters)
+     * - State the main purpose and key entities
+     * - Avoid detailed explanations or mappings
      *
-     * 1. Schema Foundation: Identify the Prisma schema elements defining this
-     *    group
-     * 2. Database Entities: List specific tables and entities from the schema
-     * 3. Functional Scope: Detail operations and workflows for schema entities
-     * 4. Schema Relationships: Describe table relationships and dependencies
-     * 5. Key Operations: Outline main operation types (CRUD, business processes)
-     * 6. Requirements Mapping: Explain how requirements map to schema entities
+     * Example: "Handles shopping-related entities and operations"
      */
     description: string & tags.MinLength<1>;
   }

package/src/orchestrate/interface/structures/IAutoBeInterfacePrerequisitesApplication.ts

@@ -0,0 +1,58 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+
+/**
+ * Interface Prerequisite Agent application for analyzing and generating API
+ * operation dependencies.
+ *
+ * Analyzes Target Operations to determine which Available API Operations must
+ * be executed as prerequisites based on resource creation dependencies and
+ * existence validations.
+ */
+export interface IAutoBeInterfacePrerequisitesApplication {
+  /**
+   * Generate prerequisites for the provided operations.
+   *
+   * Analyzes each operation's dependencies and returns the complete list with
+   * their required prerequisite chains based on resource relationships.
+   */
+  makePrerequisite(
+    props: IAutoBeInterfacePrerequisitesApplication.IProps,
+  ): void;
+}
+
+export namespace IAutoBeInterfacePrerequisitesApplication {
+  export interface IProps {
+    /**
+     * Target operations requiring prerequisite analysis.
+     *
+     * Each operation will be analyzed for dependency requirements and returned
+     * with appropriate prerequisites from Available API Operations.
+     */
+    operations: IOperation[];
+  }
+
+  /**
+   * Operation with its analyzed prerequisite dependencies.
+   *
+   * Represents a single API operation and its complete prerequisite chain
+   * needed for successful execution.
+   */
+  export interface IOperation {
+    /**
+     * The API endpoint being analyzed.
+     *
+     * Identifies the specific operation (method + path) that needs
+     * prerequisites.
+     */
+    endpoint: AutoBeOpenApi.IEndpoint;
+
+    /**
+     * Required prerequisite operations.
+     *
+     * List of API operations that must be successfully executed before this
+     * operation can be performed. Based on resource creation dependencies and
+     * existence validations from the analysis.
+     */
+    prerequisites: AutoBeOpenApi.IPrerequisite[];
+  }
+}

package/src/orchestrate/interface/structures/IAutoBeInterfaceSchemaApplication.ts

@@ -24,40 +24,6 @@ export interface IAutoBeInterfaceSchemaApplication {
 }
 export namespace IAutoBeInterfaceSchemaApplication {
   export interface IProps {
-    /**
-     * TypeScript draft code for schema definitions.
-     *
-     * This property contains TypeScript interface definitions that serve as a
-     * preliminary draft before generating the final JSON schema components.
-     * The draft allows for initial design and validation of the schema structure
-     * using TypeScript's type system before converting to OpenAPI/JSON Schema format.
-     *
-     * The draft typically includes:
-     * - Entity interfaces matching the Prisma models
-     * - Operation-specific variants (ICreate, IUpdate, etc.)
-     * - Utility types and enumerations
-     * - Type relationships and constraints
-     *
-     * This TypeScript draft serves as the foundation for the subsequent schema
-     * generation, ensuring type safety and consistency. The final schemas in the
-     * `schemas` property should be derived from and validated against this draft.
-     *
-     * Example draft structure:
-     * ```typescript
-     * interface IUser {
-     *   id: string;
-     *   email: string;
-     *   profile: IUserProfile;
-     * }
-     * 
-     * namespace IUser {
-     *   interface ICreate extends Omit<IUser, "id"> {}
-     *   interface IUpdate extends Partial<ICreate> {}
-     * }
-     * ```
-     */
-    draft: string;
-
     /**
      * Complete set of schema components for the OpenAPI specification.
      *

package/src/orchestrate/interface/utils/JsonSchemaFactory.ts

@@ -1,8 +1,12 @@
-import { AutoBeOpenApi } from "@autobe/interface";
+import { AutoBeOpenApi, AutoBePrisma } from "@autobe/interface";
 import { AutoBeOpenApiTypeChecker, StringUtil } from "@autobe/utils";
+import { OpenApiTypeChecker } from "@samchon/openapi";
 import typia, { tags } from "typia";
 
 export namespace JsonSchemaFactory {
+  /* -----------------------------------------------------------
+    ASSIGNMENTS
+  ----------------------------------------------------------- */
   export const presets = (
     typeNames: Set<string>,
   ): Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> => {
@@ -44,6 +48,77 @@ export namespace JsonSchemaFactory {
     }
   };
 
+  export const finalize = (props: {
+    document: AutoBeOpenApi.IDocument;
+    application: AutoBePrisma.IApplication;
+  }): void => {
+    removeUnused(props.document);
+    fixTimestamps(props);
+  };
+
+  const removeUnused = (document: AutoBeOpenApi.IDocument): void => {
+    const used: Set<string> = new Set();
+    const visit = (schema: AutoBeOpenApi.IJsonSchema): void =>
+      OpenApiTypeChecker.visit({
+        components: { schemas: document.components.schemas },
+        schema,
+        closure: (next) => {
+          if (OpenApiTypeChecker.isReference(next)) {
+            const key: string = next.$ref.split("/").pop()!;
+            used.add(key);
+          }
+        },
+      });
+
+    for (const op of document.operations) {
+      if (op.requestBody !== null)
+        visit({
+          $ref: `#/components/schemas/${op.requestBody.typeName}`,
+        });
+      if (op.responseBody !== null)
+        visit({
+          $ref: `#/components/schemas/${op.responseBody.typeName}`,
+        });
+    }
+    for (const key of Object.keys(document.components.schemas))
+      if (used.has(key) === false) delete document.components.schemas[key];
+  };
+
+  const fixTimestamps = (props: {
+    document: AutoBeOpenApi.IDocument;
+    application: AutoBePrisma.IApplication;
+  }): void => {
+    const entireModels: AutoBePrisma.IModel[] = props.application.files
+      .map((f) => f.models)
+      .flat();
+    for (const value of Object.values(props.document.components.schemas)) {
+      if (AutoBeOpenApiTypeChecker.isObject(value) === false) continue;
+
+      const model: AutoBePrisma.IModel | undefined = value[
+        "x-autobe-prisma-schema"
+      ]
+        ? entireModels.find((m) => m.name === value["x-autobe-prisma-schema"])
+        : undefined;
+      if (model === undefined) continue;
+
+      const properties: string[] = Object.keys(value.properties);
+      for (const key of properties) {
+        if (
+          key !== "created_at" &&
+          key !== "updated_at" &&
+          key !== "deleted_at"
+        )
+          continue;
+        const column: AutoBePrisma.IPlainField | undefined =
+          model.plainFields.find((c) => c.name === key);
+        if (column === undefined) delete value.properties[key];
+      }
+    }
+  };
+
+  /* -----------------------------------------------------------
+    PAGINATION
+  ----------------------------------------------------------- */
   export const page = (
     key: string,
   ): AutoBeOpenApi.IJsonSchemaDescriptive.IObject => ({
@@ -69,7 +144,7 @@ export namespace JsonSchemaFactory {
     `,
   });
 
-  export const fix = (path: string, input: unknown): void => {
+  export const fixPage = (path: string, input: unknown): void => {
     if (isRecord(input) === false || isRecord(input[path]) === false) return;
 
     if (input[path].description) delete input[path].description;
@@ -99,8 +174,8 @@ export namespace JsonSchemaFactory {
 const DEFAULT_SCHEMAS = typia.assertEquals<
   Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>
 >(
-  typia.json.schemas<[IPage.IPagination, IAuthorizationToken]>().components
-    ?.schemas,
+  typia.json.schemas<[IPage.IPagination, IPage.IRequest, IAuthorizationToken]>()
+    .components?.schemas,
 );
 
 namespace IPage {
@@ -122,6 +197,19 @@ namespace IPage {
      */
     pages: number & tags.Type<"uint32">;
   }
+
+  /** Page request data */
+  export interface IRequest {
+    /** Page number. */
+    page?: null | (number & tags.Type<"uint32">);
+
+    /**
+     * Limitation of records per a page.
+     *
+     * @default 100
+     */
+    limit?: null | (number & tags.Type<"uint32">);
+  }
 }
 
 /**

package/src/orchestrate/interface/utils/JsonSchemaValidator.ts

@@ -41,7 +41,25 @@ export namespace JsonSchemaValidator {
           it to a valid variable name at the next time.
         `,
       });
-    if (props.key === "IPageIRequest")
+    if (props.key.endsWith(".IPage")) {
+      const expected: string = `IPage${props.key.substring(0, props.key.length - 6)}`;
+      props.errors.push({
+        path: `${props.path}[${JSON.stringify(props.key)}]`,
+        expected: `"IPage" must be followed by another interface name. Use ${JSON.stringify(expected)} instead.`,
+        value: props.key,
+        description: StringUtil.trim`
+          "IPage" is a reserved type name for pagination response.
+          The pagination data type name must be post-fixed after "IPage".
+          
+          However, you've defined ${JSON.stringify(props.key)}, 
+          post-fixing ".IPage" after the pagination data type name.
+
+          Change it to a valid pagination type name to be
+          ${JSON.stringify(expected)} at the next time. Note that,
+          this is not a recommendation, but an instruction you must follow.
+        `,
+      });
+    } else if (props.key === "IPageIRequest")
       props.errors.push({
         path: `${props.path}[${JSON.stringify(props.key)}]`,
         expected: `"IPageIRequest" is a mistake. Use "IPage.IRequest" instead.`,

package/src/orchestrate/interface/utils/OperationValidator.ts

@@ -1,5 +1,5 @@
 import { AutoBeOpenApi } from "@autobe/interface";
-import { AutoBeEndpointComparator, StringUtil } from "@autobe/utils";
+import { AutoBeOpenApiEndpointComparator, StringUtil } from "@autobe/utils";
 import { HashMap } from "tstl";
 import { IValidation } from "typia";
 import { Escaper } from "typia/lib/utils/Escaper";
@@ -8,14 +8,16 @@ import { emplaceMap } from "../../../utils/emplaceMap";
 import { JsonSchemaValidator } from "./JsonSchemaValidator";
 
 export namespace OperationValidator {
-  export interface IProps {
+  export const validate = (props: {
     errors: IValidation.IError[];
     path: string;
     operations: Array<
-      Omit<AutoBeOpenApi.IOperation, "authorizationRole" | "authorizationType">
+      Omit<
+        AutoBeOpenApi.IOperation,
+        "authorizationRole" | "authorizationType" | "prerequisites"
+      >
     >;
-  }
-  export const validate = (props: IProps): void => {
+  }): void => {
     props.operations.forEach((op, i) => {
       // get method has request body
       if (op.method === "get" && op.requestBody !== null)
@@ -59,8 +61,8 @@ export namespace OperationValidator {
 
     // validate duplicated endpoints
     const endpoints: HashMap<AutoBeOpenApi.IEndpoint, number[]> = new HashMap(
-      AutoBeEndpointComparator.hashCode,
-      AutoBeEndpointComparator.equals,
+      AutoBeOpenApiEndpointComparator.hashCode,
+      AutoBeOpenApiEndpointComparator.equals,
     );
     props.operations.forEach((op, i) => {
       const key: AutoBeOpenApi.IEndpoint = {