@autobe/agent 0.20.0 → 0.22.0

package/src/orchestrate/interface/orchestrateInterfaceSchemasReview.ts

@@ -12,8 +12,13 @@ import { v7 } from "uuid";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { assertSchemaModel } from "../../context/assertSchemaModel";
+import { divideArray } from "../../utils/divideArray";
+import { executeCachedBatch } from "../../utils/executeCachedBatch";
 import { transformInterfaceSchemasReviewHistories } from "./histories/transformInterfaceSchemasReviewHistories";
 import { IAutoBeInterfaceSchemasReviewApplication } from "./structures/IAutobeInterfaceSchemasReviewApplication";
+import { JsonSchemaFactory } from "./utils/JsonSchemaFactory";
+import { JsonSchemaNamingConvention } from "./utils/JsonSchemaNamingConvention";
+import { fulfillJsonSchemaErrorMessages } from "./utils/fulfillJsonSchemaErrorMessages";
 import { validateAuthorizationSchema } from "./utils/validateAuthorizationSchema";
 
 export async function orchestrateInterfaceSchemasReview<
@@ -21,11 +26,53 @@ export async function orchestrateInterfaceSchemasReview<
 >(
   ctx: AutoBeContext<Model>,
   operations: AutoBeOpenApi.IOperation[],
-  schemas: Record<
-    string,
-    AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>
-  >,
+  schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>,
+): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
+  const a = Object.entries(schemas).map(([key, schema]) => {
+    return { [key]: schema };
+  });
+
+  const matrix: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>[][] =
+    divideArray({
+      array: a,
+      capacity: 8,
+    });
+  const progress: IProgress = {
+    total: matrix.length,
+    completed: 0,
+  };
+
+  const x: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> = {};
+  for (const y of await executeCachedBatch(
+    matrix.map((it) => async (promptCacheKey) => {
+      const row: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
+        await divideAndConquer(ctx, operations, it, progress, promptCacheKey);
+      return row;
+    }),
+  )) {
+    JsonSchemaNamingConvention.schemas(operations, x, y);
+    Object.assign(x, y);
+  }
+  return x;
+}
+
+async function divideAndConquer<Model extends ILlmSchema.Model>(
+  ctx: AutoBeContext<Model>,
+  operations: AutoBeOpenApi.IOperation[],
+  schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>[],
+  progress: AutoBeProgressEventBase,
+  promptCacheKey: string,
+): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
+  const schema = schemas.reduce((acc, cur) => Object.assign(acc, cur), {});
+  return step(ctx, operations, schema, progress, promptCacheKey);
+}
+
+export async function step<Model extends ILlmSchema.Model>(
+  ctx: AutoBeContext<Model>,
+  operations: AutoBeOpenApi.IOperation[],
+  schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>,
   progress: AutoBeProgressEventBase,
+  promptCacheKey: string,
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
   try {
     const pointer: IPointer<IAutoBeInterfaceSchemasReviewApplication.IProps | null> =
@@ -46,6 +93,7 @@ export async function orchestrateInterfaceSchemasReview<
         schemas,
       ),
       enforceFunctionCall: true,
+      promptCacheKey,
       message: "Review type schemas.",
     });
     if (pointer.value === null) {
@@ -54,18 +102,18 @@ export async function orchestrateInterfaceSchemasReview<
       return {};
     }
 
-    const content: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
-      (
-        OpenApiV3_1Emender.convertComponents({
-          schemas: pointer.value.content,
-        }) as AutoBeOpenApi.IComponents
-      ).schemas ?? {};
+    const content: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> = ((
+      OpenApiV3_1Emender.convertComponents({
+        schemas: pointer.value.content,
+      }) as AutoBeOpenApi.IComponents
+    ).schemas ?? {}) as Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
+
     ctx.dispatch({
       type: "interfaceSchemasReview",
       id: v7(),
       schemas: schemas,
-      review: pointer.value.review,
-      plan: pointer.value.plan,
+      review: pointer.value.think.review,
+      plan: pointer.value.think.plan,
       content,
       tokenUsage,
       step: ctx.state().analyze?.step ?? 0,
@@ -85,19 +133,21 @@ function createController<Model extends ILlmSchema.Model>(props: {
   model: Model;
   pointer: IPointer<IAutoBeInterfaceSchemasReviewApplication.IProps | null>;
   operations: AutoBeOpenApi.IOperation[];
-  schemas: Record<
-    string,
-    AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>
-  >;
+  schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
 }): IAgenticaController.IClass<Model> {
   assertSchemaModel(props.model);
 
   const validate = (
     next: unknown,
   ): IValidation<IAutoBeInterfaceSchemasReviewApplication.IProps> => {
+    JsonSchemaFactory.fix("content", next);
+
     const result: IValidation<IAutoBeInterfaceSchemasReviewApplication.IProps> =
       typia.validate<IAutoBeInterfaceSchemasReviewApplication.IProps>(next);
-    if (result.success === false) return result;
+    if (result.success === false) {
+      fulfillJsonSchemaErrorMessages(result.errors);
+      return result;
+    }
 
     const errors: IValidation.IError[] = [];
     validateAuthorizationSchema({
@@ -105,90 +155,12 @@ function createController<Model extends ILlmSchema.Model>(props: {
       schemas: result.data.content,
       path: "$input.content",
     });
-
-    Object.entries(result.data.content).forEach(
-      ([tagName, jsonDescriptive]) => {
-        const index: AutoBeOpenApi.IOperation | undefined =
-          props.operations.find(
-            (op) =>
-              op.responseBody?.typeName === tagName &&
-              op.method === "patch" &&
-              op.name === "index",
-          );
-
-        // The index API should return the `IPage<T>` type.
-        if (index) {
-          // First check if the schema has the correct object structure
-          if (
-            !("type" in jsonDescriptive) ||
-            jsonDescriptive.type !== "object"
-          ) {
-            errors.push({
-              path: `$input.content.${tagName}`,
-              expected: `{ type: "object", properties: { ... } }`,
-              value: jsonDescriptive,
-              description: `IPage schema must have type: "object". Found: ${JSON.stringify(jsonDescriptive)}`,
-            });
-          } else if (!("properties" in jsonDescriptive)) {
-            errors.push({
-              path: `$input.content.${tagName}`,
-              expected: `Schema with "properties" field`,
-              value: jsonDescriptive,
-              description: `IPage schema must have a "properties" field containing "pagination" and "data" properties.`,
-            });
-          } else if (
-            typia.is<AutoBeOpenApi.IJsonSchema.IObject>(jsonDescriptive)
-          ) {
-            jsonDescriptive.properties ??= {};
-
-            // Check pagination property
-            const pagination = jsonDescriptive.properties["pagination"];
-            if (!pagination || !("$ref" in pagination)) {
-              errors.push({
-                path: `$input.content.${tagName}.properties.pagination`,
-                expected: `{ $ref: "#/components/schemas/IPage.IPagination" }`,
-                value: pagination,
-                description: `IPage must have a "pagination" property with $ref to IPage.IPagination.`,
-              });
-            }
-
-            // Check data property
-            const data = jsonDescriptive.properties["data"];
-            if (!typia.is<AutoBeOpenApi.IJsonSchema.IArray>(data)) {
-              errors.push({
-                path: `$input.content.${tagName}.properties.data`,
-                expected: `AutoBeOpenApi.IJsonSchema.IArray`,
-                value: data,
-                description: `The 'data' property must be an array for the index operation.`,
-              });
-            } else {
-              // Check if array items have proper type reference (not 'any')
-              const arraySchema: AutoBeOpenApi.IJsonSchema.IArray = data;
-              if (
-                !arraySchema.items ||
-                !("$ref" in arraySchema.items) ||
-                arraySchema.items.$ref === "#/components/schemas/any"
-              ) {
-                errors.push({
-                  path: `$input.content.${tagName}.properties.data.items`,
-                  expected: `Reference to a specific type (e.g., $ref to ISummary type)`,
-                  value: arraySchema.items,
-                  description: `The 'data' array must have a specific item type, not 'any[]'. Use a proper type reference like '{Entity}.ISummary' for paginated results.`,
-                });
-              }
-            }
-          }
-        }
-      },
-    );
-
     if (errors.length !== 0)
       return {
         success: false,
         errors,
         data: next,
       };
-
     return result;
   };
 
@@ -227,3 +199,8 @@ const collection = {
 type Validator = (
   input: unknown,
 ) => IValidation<IAutoBeInterfaceSchemasReviewApplication.IProps>;
+
+export interface IProgress {
+  total: number;
+  completed: number;
+}

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

@@ -0,0 +1,65 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+
+/**
+ * Interface for reviewing and refining API endpoints through holistic analysis.
+ * 
+ * This application performs comprehensive review of all endpoints generated
+ * through divide-and-conquer strategy, ensuring consistency, eliminating
+ * redundancy, and preventing over-engineering across the entire API surface.
+ */
+export interface IAutoBeInterfaceEndpointsReviewApplication {
+  /**
+   * Reviews and refines the complete collection of API endpoints.
+   * 
+   * This method consolidates all endpoints generated independently by different
+   * groups and performs holistic review to:
+   * - Ensure naming consistency across all endpoints
+   * - Remove duplicate or overlapping endpoints
+   * - Eliminate over-engineered solutions
+   * - Standardize path structures and HTTP methods
+   * - Verify REST API design principles
+   * 
+   * The review process examines the entire API as a cohesive system rather
+   * than individual endpoints, ensuring the final API is intuitive, maintainable,
+   * and follows best practices.
+   * 
+   * @param next - The review results and refined endpoint collection
+   */
+  reviewEndpoints(
+    next: IAutoBeInterfaceEndpointsReviewApplication.IProps,
+  ): void;
+}
+
+export namespace IAutoBeInterfaceEndpointsReviewApplication {
+  export interface IProps {
+    /**
+     * Comprehensive review analysis of all collected endpoints.
+     * 
+     * Contains detailed findings from the holistic review including:
+     * - Identified inconsistencies in naming conventions
+     * - Duplicate endpoints that serve the same purpose
+     * - Over-engineered solutions that add unnecessary complexity
+     * - Violations of REST API design principles
+     * - Recommendations for improvement and standardization
+     * 
+     * The review provides actionable feedback for creating a clean,
+     * consistent, and maintainable API structure.
+     */
+    review: string;
+
+    /**
+     * Refined collection of API endpoints after review and cleanup.
+     * 
+     * The final optimized set of endpoints after:
+     * - Removing duplicates and redundant endpoints
+     * - Standardizing naming conventions across all paths
+     * - Simplifying over-engineered solutions
+     * - Ensuring consistent REST patterns
+     * - Aligning HTTP methods with their semantic meanings
+     * 
+     * This collection represents the production-ready API structure
+     * that balances functionality with simplicity and maintainability.
+     */
+    endpoints: AutoBeOpenApi.IEndpoint[];
+  }
+}

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

@@ -91,45 +91,6 @@ export namespace IAutoBeInterfaceOperationApplication {
       AutoBeOpenApi.IOperation,
       "authorizationRole" | "authorizationType"
     > {
-    /**
-     * Prisma schema models relevant to this operation.
-     *
-     * Contains the complete Prisma schema definitions for all entities involved
-     * in this operation, including their fields, relations, and database
-     * constraints. This enables comprehensive validation and schema-aware
-     * operation design.
-     *
-     * The schema information serves multiple critical purposes:
-     *
-     * - **Field Verification**: Ensures all referenced fields actually exist in
-     *   the database schema and have the correct types
-     * - **Relationship Validation**: Confirms that entity relationships are
-     *   properly defined and can support the operation's data access patterns
-     * - **Soft-Delete Detection**: For DELETE operations, identifies whether
-     *   entities have soft-delete fields (deleted_at, is_deleted, etc.) to
-     *   determine if the operation should perform logical deletion instead of
-     *   physical removal
-     * - **Constraint Awareness**: Understands unique constraints, required
-     *   fields, and default values to generate accurate request/response
-     *   schemas
-     *
-     * Example content might include:
-     *
-     * ```prisma
-     * model User {
-     *   id         String    @id @default(uuid())
-     *   email      String    @unique
-     *   name       String
-     *   deleted_at DateTime? // Indicates soft-delete capability
-     *   posts      Post[]
-     * }
-     * ```
-     *
-     * This schema context ensures operations are fully aligned with the actual
-     * database structure and business logic requirements.
-     */
-    prisma_schemas: string;
-
     /**
      * Authorization roles required to access this API operation.
      *

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

@@ -5,19 +5,21 @@ import { AutoBeOpenApi } from "@autobe/interface";
  *
  * Provides functionality to systematically review generated API operations
  * against business requirements, technical specifications, and OpenAPI
- * standards. The review process ensures each operation meets quality criteria
- * before proceeding to implementation.
+ * standards. The review process outputs a structured thinking process with
+ * analytical findings and actionable improvements, along with the final
+ * enhanced operations ready for implementation.
  */
 export interface IAutoBeInterfaceOperationsReviewApplication {
   /**
    * Reviews a batch of API operations for quality and correctness.
    *
-   * Validates each operation's request/response schemas, authentication
-   * handling, error responses, and documentation completeness. Operations are
-   * marked as passed or failed based on compliance with enterprise standards.
+   * Analyzes operations for security vulnerabilities, schema compliance,
+   * logical consistency, and standard adherence. Outputs a structured thinking
+   * process containing review findings and improvement plans, plus the final
+   * production-ready operations with all critical issues resolved.
    *
-   * @param input Collection of operations to review with their validation
-   *   results
+   * @param input Properties containing the thinking process (review & plan)
+   *   and the enhanced operations content
    */
   reviewOperations(
     input: IAutoBeInterfaceOperationsReviewApplication.IProps,
@@ -33,6 +35,47 @@ export namespace IAutoBeInterfaceOperationsReviewApplication {
    * of the AutoBeInterfaceOperationsReviewEvent.
    */
   export interface IProps {
+    /**
+     * Comprehensive thinking process for API operation review.
+     *
+     * Encapsulates the agent's analytical review findings and actionable
+     * improvement plan. This structured thinking process ensures systematic
+     * evaluation of API operations against AutoBE's quality standards before
+     * generating the final enhanced operations.
+     */
+    think: IThink;
+
+    /**
+     * Production-ready operations with all critical issues resolved.
+     *
+     * Final API operations after systematic enhancement:
+     *
+     * - **Security Fixes Applied**: All authentication boundaries enforced,
+     *   sensitive data removed from responses, proper authorization
+     *   implemented
+     * - **Logic Corrections Made**: Return types match operation intent, HTTP
+     *   methods align with semantics, parameters properly utilized
+     * - **Schema Alignment Verified**: All fields exist in Prisma schema, types
+     *   correctly mapped, relationships properly defined
+     * - **Quality Improvements Added**: Enhanced documentation, format
+     *   specifications, validation rules, consistent naming patterns
+     *
+     * If no issues were found during review, this contains the exact original
+     * operations unchanged. These operations are validated and ready for schema
+     * generation and subsequent implementation phases.
+     */
+    content: AutoBeOpenApi.IOperation[];
+  }
+
+  /**
+   * Structured thinking process for comprehensive API operation review.
+   *
+   * Combines analytical review findings with actionable improvement planning
+   * to guide the systematic enhancement of API operations. This thinking
+   * structure ensures all aspects of API quality are evaluated and addressed
+   * before producing the final operations.
+   */
+  export interface IThink {
     /**
      * Comprehensive review analysis with prioritized findings.
      *
@@ -77,102 +120,5 @@ export namespace IAutoBeInterfaceOperationsReviewApplication {
      * needed, and the rationale for the modification.
      */
     plan: string;
-
-    /**
-     * Production-ready operations with all critical issues resolved.
-     *
-     * Final API operations after systematic enhancement:
-     *
-     * - **Security Fixes Applied**: All authentication boundaries enforced,
-     *   sensitive data removed from responses, proper authorization
-     *   implemented
-     * - **Logic Corrections Made**: Return types match operation intent, HTTP
-     *   methods align with semantics, parameters properly utilized
-     * - **Schema Alignment Verified**: All fields exist in Prisma schema, types
-     *   correctly mapped, relationships properly defined
-     * - **Quality Improvements Added**: Enhanced documentation, format
-     *   specifications, validation rules, consistent naming patterns
-     *
-     * If no issues were found during review, this contains the exact original
-     * operations unchanged. These operations are validated and ready for schema
-     * generation and subsequent implementation phases.
-     */
-    content: IOperation[];
-  }
-
-  /**
-   * Operation of the Restful API.
-   *
-   * This interface defines a single API endpoint with its HTTP {@link method},
-   * {@link path}, {@link parameters path parameters},
-   * {@link requestBody request body}, and {@link responseBody} structure. It
-   * corresponds to an individual operation in the paths section of an OpenAPI
-   * document.
-   *
-   * Each operation requires a detailed explanation of its purpose through the
-   * reason and description fields, making it clear why the API was designed and
-   * how it should be used.
-   *
-   * All request bodies and responses for this operation must be object types
-   * and must reference named types defined in the components section. The
-   * content-type is always `application/json`. For file upload/download
-   * operations, use `string & tags.Format<"uri">` in the appropriate schema
-   * instead of binary data formats.
-   *
-   * In OpenAPI, this might represent:
-   *
-   * ```json
-   * {
-   *   "/shoppings/customers/orders": {
-   *     "post": {
-   *       "description": "Create a new order application from shopping cart...",
-   *       "parameters": [...],
-   *       "requestBody": {...},
-   *       "responses": {...}
-   *     }
-   *   }
-   * }
-   * ```
-   */
-  export interface IOperation
-    extends Omit<AutoBeOpenApi.IOperation, "authorizationType"> {
-    /**
-     * Prisma schema models relevant to this operation.
-     *
-     * Contains the complete Prisma schema definitions for all entities involved
-     * in this operation, including their fields, relations, and database
-     * constraints. This enables comprehensive validation and schema-aware
-     * operation design.
-     *
-     * The schema information serves multiple critical purposes:
-     *
-     * - **Field Verification**: Ensures all referenced fields actually exist in
-     *   the database schema and have the correct types
-     * - **Relationship Validation**: Confirms that entity relationships are
-     *   properly defined and can support the operation's data access patterns
-     * - **Soft-Delete Detection**: For DELETE operations, identifies whether
-     *   entities have soft-delete fields (deleted_at, is_deleted, etc.) to
-     *   determine if the operation should perform logical deletion instead of
-     *   physical removal
-     * - **Constraint Awareness**: Understands unique constraints, required
-     *   fields, and default values to generate accurate request/response
-     *   schemas
-     *
-     * Example content might include:
-     *
-     * ```prisma
-     * model User {
-     *   id         String    @id @default(uuid())
-     *   email      String    @unique
-     *   name       String
-     *   deleted_at DateTime? // Indicates soft-delete capability
-     *   posts      Post[]
-     * }
-     * ```
-     *
-     * This schema context ensures operations are fully aligned with the actual
-     * database structure and business logic requirements.
-     */
-    prisma_schemas: string;
   }
 }

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

@@ -29,15 +29,44 @@ export namespace IAutoBeInterfaceSchemasReviewApplication {
    * interface to understand what outputs are required.
    */
   export interface IProps {
+    think: IThink;
+
+    /**
+     * Final validated and enhanced schemas ready for production use.
+     *
+     * DO:
+     *
+     * - Include valid OpenAPI schema definitions
+     * - Include all entities that were in the original input
+     * - Provide fixed versions if original schemas have issues
+     * - Rename entities correctly if names are wrong
+     * - Include created variants if schemas are missing them
+     *
+     * DO NOT:
+     *
+     * - Return an empty object {} (this will delete all schemas)
+     * - Return undefined or null
+     * - Include explanations or excuses in schema descriptions
+     * - Leave broken schemas unfixed
+     *
+     * When original schemas are beyond repair, recreate them properly based on
+     * entity names and context. This field becomes the final schemas used by
+     * the system, so it must always contain complete, valid schemas.
+     */
+    content: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
+  }
+
+  export interface IThink {
     /**
      * Issues and problems found during schema analysis.
      *
-     * DO: Document only problems that need fixing.
-     * DO NOT: Include positive feedback, compliments, or confirmations
+     * DO: Document only problems that need fixing. DO NOT: Include positive
+     * feedback, compliments, or confirmations
      *
      * Focus exclusively on issues organized by severity:
      *
      * Severity levels:
+     *
      * - Security vulnerabilities (exposed passwords, missing auth boundaries)
      * - Missing required variants, incorrect type mappings
      * - Missing format specifications, incomplete relationships
@@ -63,30 +92,5 @@ export namespace IAutoBeInterfaceSchemasReviewApplication {
      * field.
      */
     plan: string;
-
-    /**
-     * Final validated and enhanced schemas ready for production use.
-     *
-     * DO:
-     * - Include valid OpenAPI schema definitions
-     * - Include all entities that were in the original input
-     * - Provide fixed versions if original schemas have issues
-     * - Rename entities correctly if names are wrong
-     * - Include created variants if schemas are missing them
-     *
-     * DO NOT:
-     * - Return an empty object {} (this will delete all schemas)
-     * - Return undefined or null
-     * - Include explanations or excuses in schema descriptions
-     * - Leave broken schemas unfixed
-     *
-     * When original schemas are beyond repair, recreate them properly based on
-     * entity names and context. This field becomes the final schemas used by
-     * the system, so it must always contain complete, valid schemas.
-     */
-    content: Record<
-      string,
-      AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>
-    >;
   }
 }