@autobe/agent 0.19.1 → 0.20.0

package/src/orchestrate/interface/orchestrateInterfaceSchemasReview.ts

@@ -2,11 +2,13 @@ import { IAgenticaController } from "@agentica/core";
 import {
   AutoBeInterfaceSchemasReviewEvent,
   AutoBeOpenApi,
+  AutoBeProgressEventBase,
 } from "@autobe/interface";
 import { ILlmApplication, ILlmSchema, IValidation } from "@samchon/openapi";
 import { OpenApiV3_1Emender } from "@samchon/openapi/lib/converters/OpenApiV3_1Emender";
 import { IPointer } from "tstl";
 import typia from "typia";
+import { v7 } from "uuid";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { assertSchemaModel } from "../../context/assertSchemaModel";
@@ -23,7 +25,7 @@ export async function orchestrateInterfaceSchemasReview<
     string,
     AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>
   >,
-  progress: { total: number; completed: number },
+  progress: AutoBeProgressEventBase,
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
   try {
     const pointer: IPointer<IAutoBeInterfaceSchemasReviewApplication.IProps | null> =
@@ -35,6 +37,7 @@ export async function orchestrateInterfaceSchemasReview<
       controller: createController({
         model: ctx.model,
         pointer,
+        operations,
         schemas,
       }),
       histories: transformInterfaceSchemasReviewHistories(
@@ -59,6 +62,7 @@ export async function orchestrateInterfaceSchemasReview<
       ).schemas ?? {};
     ctx.dispatch({
       type: "interfaceSchemasReview",
+      id: v7(),
       schemas: schemas,
       review: pointer.value.review,
       plan: pointer.value.plan,
@@ -80,6 +84,7 @@ export async function orchestrateInterfaceSchemasReview<
 function createController<Model extends ILlmSchema.Model>(props: {
   model: Model;
   pointer: IPointer<IAutoBeInterfaceSchemasReviewApplication.IProps | null>;
+  operations: AutoBeOpenApi.IOperation[];
   schemas: Record<
     string,
     AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>
@@ -100,14 +105,93 @@ 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;
   };
+
   const application: ILlmApplication<Model> = collection[
     props.model === "chatgpt" ? "chatgpt" : "claude"
   ](

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

@@ -91,6 +91,45 @@ 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

@@ -135,5 +135,44 @@ export namespace IAutoBeInterfaceOperationsReviewApplication {
    * ```
    */
   export interface IOperation
-    extends Omit<AutoBeOpenApi.IOperation, "authorizationType"> {}
+    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/prisma/histories/transformPrismaComponentsHistories.ts

@@ -1,6 +1,7 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
+import { StringUtil } from "@autobe/utils";
 import { NamingConvention } from "typia/lib/utils/NamingConvention";
-import { v4 } from "uuid";
+import { v7 } from "uuid";
 
 import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromptConstant";
 import { AutoBeState } from "../../../context/AutoBeState";
@@ -17,67 +18,68 @@ export const transformPrismaComponentsHistories = (
   if (prefix) prefix = NamingConvention.snake(prefix);
   return [
     {
-      id: v4(),
+      id: v7(),
       created_at: new Date().toISOString(),
       type: "systemMessage",
       text: AutoBeSystemPromptConstant.PRISMA_COMPONENT,
     },
     {
-      id: v4(),
+      id: v7(),
       created_at: new Date().toISOString(),
       type: "assistantMessage",
-      text: [
-        "Here is the requirement analysis report.",
-        "",
-        "Call the provided tool function to generate Prisma DB schema",
-        "referencing below requirement analysis report.",
-        "",
-        `## Requirement Analysis Report`,
-        "",
-        "```json",
-        JSON.stringify(state.analyze.files),
-        "```",
-        "## Prefix",
-        "",
-        `* Prefix provided by the user: ${prefix}`,
-        "",
-        "The user wants all database schema (table) names to start with the prefix provided below.",
-        "",
-        "DO: Use the provided prefix for all table names",
-        "DO: Place special-purpose prefixes like `mv` (for materialized views) before the given prefix",
-        "DO NOT: Apply prefix if it is `null`",
-        "",
-        "## Prefix Example",
-        "",
-        "If the prefix is `shopping`, then table names are like:",
-        "",
-        "* `shopping_sales`",
-        "* `shopping_sale_options`",
-        "",
-        "In cases where a table is created for performance optimization purposes (e.g., materialized views), the `mv_` prefix must come first.",
-        "For example:",
-        "",
-        "* `mv_shopping_daily_stats`",
-        "",
-        "",
-        state.analyze.roles.length > 0
-          ? [
-              "## User Role Handling",
-              "",
-              `The Requirement Analysis Report contains the following user roles: ${state.analyze.roles.join(", ")}.`,
-              "",
-              "**Do not normalize** user roles into a single table.",
-              "Instead, create separate tables for each distinct role mentioned in the requirements.",
-              "",
-              "Create separate tables for each role:",
-              "",
-              state.analyze.roles
-                .map((role) => `* ${prefix}_${role.name.toLowerCase()}`)
-                .join("\n"),
-              "",
-            ].join("\n")
-          : "",
-      ].join("\n"),
+      text: StringUtil.trim`
+        Here is the requirement analysis report.
+        
+        Call the provided tool function to generate Prisma DB schema
+        referencing below requirement analysis report.
+        
+        ## Requirement Analysis Report
+        
+        \`\`\`json
+        ${JSON.stringify(state.analyze.files)}
+        \`\`\`
+        
+        ## Prefix
+        
+        - Prefix provided by the user: ${prefix}
+        
+        The user wants all database schema (table) names to start with the prefix provided below.
+        
+        - DO: Use the provided prefix for all table names
+        - DO: Place special-purpose prefixes like \`mv\` (for materialized views) before the given prefix
+        - DO NOT: Apply prefix if it is \`null\`
+        
+        ## Prefix Example
+        
+        If the prefix is \`shopping\`, then table names are like:
+        
+        - \`shopping_sales\`
+        - \`shopping_sale_options\`
+        
+        In cases where a table is created for performance optimization purposes 
+        (e.g., materialized views), the \`mv_\` prefix must come first. For example:
+        
+        - \`mv_shopping_daily_stats\`
+        
+        ${
+          state.analyze.roles.length > 0
+            ? StringUtil.trim`
+                ## User Role Handling
+                
+                The Requirement Analysis Report contains the following user roles: ${state.analyze.roles.join(", ")}
+                
+                **Do not normalize** user roles into a single table.
+                Instead, create separate tables for each distinct role mentioned in the requirements.
+                
+                Create separate tables for each role:
+                
+                ${state.analyze.roles
+                  .map((role) => `- ${prefix}_${role.name.toLowerCase()}`)
+                  .join("\n")}
+              `
+            : ""
+        }
+      `,
     },
   ];
 };

package/src/orchestrate/prisma/histories/transformPrismaCorrectHistories.ts

@@ -1,6 +1,7 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
 import { IAutoBePrismaValidation } from "@autobe/interface";
-import { v4 } from "uuid";
+import { StringUtil } from "@autobe/utils";
+import { v7 } from "uuid";
 
 import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromptConstant";
 
@@ -11,46 +12,34 @@ export const transformPrismaCorrectHistories = (
 > => {
   return [
     {
-      id: v4(),
+      id: v7(),
       created_at: new Date().toISOString(),
       type: "systemMessage",
       text: AutoBeSystemPromptConstant.PRISMA_CORRECT,
     },
     {
-      id: v4(),
+      id: v7(),
       created_at: new Date().toISOString(),
       type: "assistantMessage",
-      text: [
-        "Here is the Prisma application data what you made:",
-        "",
-        "```json",
-        JSON.stringify(result.data),
-        "```",
-      ].join("\n"),
+      text: StringUtil.trim`
+        Here is the Prisma application data what you made:
+        
+        \`\`\`json
+        ${JSON.stringify(result.data)}
+        \`\`\`
+      `,
     },
     {
-      id: v4(),
+      id: v7(),
       created_at: new Date().toISOString(),
       type: "assistantMessage",
-      text: [
-        "Below are the list of errors what you have to fix:",
-        "",
-        "```json",
-        JSON.stringify(result.errors),
-        "```",
-      ].join("\n"),
-    },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: [
-        "Before fixing the schema files,",
-        "study about Prisma schema language",
-        "from the best practices and examples",
-        "",
-        AutoBeSystemPromptConstant.PRISMA_EXAMPLE,
-      ].join("\n"),
+      text: StringUtil.trim`
+        Below are the list of errors what you have to fix:
+        
+        \`\`\`json
+        ${JSON.stringify(result.errors)}
+        \`\`\`
+      `,
     },
   ];
 };

package/src/orchestrate/prisma/histories/transformPrismaReviewHistories.ts

@@ -1,6 +1,7 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
 import { AutoBePrisma } from "@autobe/interface";
-import { v4 } from "uuid";
+import { StringUtil } from "@autobe/utils";
+import { v7 } from "uuid";
 
 import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromptConstant";
 
@@ -14,53 +15,55 @@ export const transformPrismaReviewHistories = (props: {
 > => {
   return [
     {
-      id: v4(),
+      id: v7(),
       created_at: new Date().toISOString(),
       type: "systemMessage",
       text: AutoBeSystemPromptConstant.PRISMA_SCHEMA,
     },
     {
-      id: v4(),
+      id: v7(),
       created_at: new Date().toISOString(),
-      type: "assistantMessage",
-      text: [
-        "Here is the requirement analysis report given by the user:",
-        "",
-        "```json",
-        JSON.stringify(props.analysis),
-        "```",
-        "",
-        "Reading the requirement analysis report, you AI made below AST definition for the database design:",
-        "",
-        "```json",
-        JSON.stringify(props.application),
-        "```",
-        "",
-        "And here are the Prisma schema files generated (compiled) from the above AST:",
-        "",
-        "```prisma",
-        JSON.stringify(props.schemas),
-        "```",
-      ].join("\n"),
+      type: "systemMessage",
+      text: AutoBeSystemPromptConstant.PRISMA_REVIEW,
     },
     {
-      id: v4(),
+      id: v7(),
       created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: AutoBeSystemPromptConstant.PRISMA_REVIEW,
+      type: "assistantMessage",
+      text: StringUtil.trim`
+        Here is the requirement analysis report given by the user:
+        
+        \`\`\`json
+        ${JSON.stringify(props.analysis)}
+        \`\`\`
+        
+        Reading the requirement analysis report, you AI made 
+        below AST definition for the database design:
+        
+        \`\`\`json
+        ${JSON.stringify(props.application)}
+        \`\`\`
+        
+        And here are the Prisma schema files generated (compiled) 
+        from the above AST:
+        
+        \`\`\`json
+        ${JSON.stringify(props.schemas)}
+        \`\`\`
+      `,
     },
     {
-      id: v4(),
+      id: v7(),
       created_at: new Date().toISOString(),
       type: "assistantMessage",
-      text: [
-        `Now, please review the tables in the "${props.component.namespace}" namespace.`,
-        "",
-        "Focus your review exclusively on these tables.",
-        "",
-        "**Tables in this namespace:**",
-        ...props.component.tables.map((table) => `- ${table}`),
-      ].join("\n"),
+      text: StringUtil.trim`
+        Now, please review the tables in the "${props.component.namespace}" namespace.
+        
+        Focus your review exclusively on these tables.
+        
+        **Tables in this namespace:**
+        ${props.component.tables.map((table) => `- ${table}`).join("\n")}
+      `,
     },
   ];
 };

package/src/orchestrate/prisma/histories/transformPrismaSchemaHistories.ts

@@ -1,6 +1,7 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
 import { AutoBePrisma } from "@autobe/interface";
-import { v4 } from "uuid";
+import { StringUtil } from "@autobe/utils";
+import { v7 } from "uuid";
 
 import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromptConstant";
 
@@ -13,42 +14,54 @@ export const transformPrismaSchemaHistories = (
 > => {
   return [
     {
-      id: v4(),
+      id: v7(),
       created_at: new Date().toISOString(),
       type: "systemMessage",
       text: AutoBeSystemPromptConstant.PRISMA_SCHEMA,
     },
     {
-      id: v4(),
+      id: v7(),
       created_at: new Date().toISOString(),
       type: "assistantMessage",
-      text: [
-        "Here is the input data for generating Prisma DB schema.",
-        "",
-        "```",
-        JSON.stringify({
-          requirementAnalysisReport,
+      text: StringUtil.trim`
+        Here is the requirement analysis report:
+
+        \`\`\`json
+        ${JSON.stringify(requirementAnalysisReport)}
+        \`\`\`
+      `,
+    },
+    {
+      id: v7(),
+      created_at: new Date().toISOString(),
+      type: "assistantMessage",
+      text: StringUtil.trim`
+        Here is the input data for generating Prisma DB schema.
+        
+        \`\`\`json
+        ${JSON.stringify({
           targetComponent,
           otherTables,
-        }),
-        "```",
-      ].join("\n"),
+        })}
+        \`\`\`
+      `,
     },
     {
-      id: v4(),
+      id: v7(),
       created_at: new Date().toISOString(),
       type: "systemMessage",
-      text: [
-        "You've already taken a mistake that creating models from the other components.",
-        "Note that, you have to make models from the target component only. Never make",
-        "models from the other components. The other components' models are already made.",
-        "",
-        "```json",
-        JSON.stringify({
+      text: StringUtil.trim`
+        You've already taken a mistake that creating models from the other components.
+
+        Note that, you have to make models from the target component only. Never make
+        models from the other components. The other components' models are already made.
+        
+        \`\`\`json
+        ${JSON.stringify({
           targetComponent,
-        }),
-        "```",
-      ].join("\n"),
+        })}
+        \`\`\`
+      `,
     },
   ];
 };

package/src/orchestrate/prisma/orchestratePrisma.ts

@@ -10,7 +10,7 @@ import {
 } from "@autobe/interface";
 import { AutoBePrismaSchemasEvent } from "@autobe/interface/src/events/AutoBePrismaSchemasEvent";
 import { ILlmSchema } from "@samchon/openapi";
-import { v4 } from "uuid";
+import { v7 } from "uuid";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { IAutoBeApplicationProps } from "../../context/IAutoBeApplicationProps";
@@ -30,13 +30,14 @@ export const orchestratePrisma = async <Model extends ILlmSchema.Model>(
   if (predicate !== null)
     return ctx.assistantMessage({
       type: "assistantMessage",
-      id: v4(),
+      id: v7(),
       created_at: start.toISOString(),
       text: predicate,
       completed_at: new Date().toISOString(),
     });
   ctx.dispatch({
     type: "prismaStart",
+    id: v7(),
     created_at: start.toISOString(),
     reason: props.reason,
     step: ctx.state().analyze?.step ?? 0,
@@ -93,6 +94,7 @@ export const orchestratePrisma = async <Model extends ILlmSchema.Model>(
   // PROPAGATE
   return ctx.dispatch({
     type: "prismaComplete",
+    id: v7(),
     result,
     schemas: finalSchemas,
     compiled: await compiler.prisma.compile({

package/src/orchestrate/prisma/orchestratePrismaComponent.ts

@@ -3,6 +3,7 @@ import { AutoBePrismaComponentsEvent } from "@autobe/interface/src/events/AutoBe
 import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
 import { IPointer } from "tstl";
 import typia from "typia";
+import { v7 } from "uuid";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { assertSchemaModel } from "../../context/assertSchemaModel";
@@ -36,6 +37,7 @@ export async function orchestratePrismaComponents<
     throw new Error("Failed to extract files and tables."); // unreachable
   return {
     type: "prismaComponents",
+    id: v7(),
     created_at: start.toISOString(),
     thinking: pointer.value.thinking,
     review: pointer.value.review,