@autobe/agent 0.14.6 → 0.15.0

package/src/orchestrate/interface/orchestrateInterfaceSchemas.ts

@@ -0,0 +1,197 @@
+import { IAgenticaController, MicroAgentica } from "@agentica/core";
+import { AutoBeOpenApi } from "@autobe/interface";
+import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
+import { OpenApiV3_1Emender } from "@samchon/openapi/lib/converters/OpenApiV3_1Emender";
+import { IPointer } from "tstl";
+import typia from "typia";
+
+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 { transformInterfaceSchemaHistories } from "./histories/transformInterfaceSchemaHistories";
+import { IAutoBeInterfaceSchemaApplication } from "./structures/IAutoBeInterfaceSchemaApplication";
+
+export async function orchestrateInterfaceSchemas<
+  Model extends ILlmSchema.Model,
+>(
+  ctx: AutoBeContext<Model>,
+  operations: AutoBeOpenApi.IOperation[],
+  capacity: number = 12,
+): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
+  const typeNames: Set<string> = new Set();
+  for (const op of operations) {
+    if (op.requestBody !== null) typeNames.add(op.requestBody.typeName);
+    if (op.responseBody !== null) typeNames.add(op.responseBody.typeName);
+  }
+  const matrix: string[][] = divideArray({
+    array: Array.from(typeNames),
+    capacity,
+  });
+  let progress: number = 0;
+
+  const x: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> = {};
+  for (const y of await Promise.all(
+    matrix.map(async (it) => {
+      const row: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
+        await divideAndConquer(ctx, operations, it, 3, (count) => {
+          progress += count;
+        });
+      ctx.dispatch({
+        type: "interfaceSchemas",
+        schemas: row,
+        completed: progress,
+        total: typeNames.size,
+        step: ctx.state().analyze?.step ?? 0,
+        created_at: new Date().toISOString(),
+      });
+      return row;
+    }),
+  )) {
+    Object.assign(x, y);
+  }
+  return x;
+}
+
+async function divideAndConquer<Model extends ILlmSchema.Model>(
+  ctx: AutoBeContext<Model>,
+  operations: AutoBeOpenApi.IOperation[],
+  typeNames: string[],
+  retry: number,
+  progress: (completed: number) => void,
+): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
+  const remained: Set<string> = new Set(typeNames);
+  const schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> = {};
+  for (let i: number = 0; i < retry; ++i) {
+    if (remained.size === 0) break;
+    const before: number = remained.size;
+    const newbie: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
+      await forceRetry(() => process(ctx, operations, schemas, remained));
+    for (const key of Object.keys(newbie)) {
+      schemas[key] = newbie[key];
+      remained.delete(key);
+    }
+    if (before - remained.size !== 0) progress(before - remained.size);
+  }
+  return schemas;
+}
+
+async function process<Model extends ILlmSchema.Model>(
+  ctx: AutoBeContext<Model>,
+  operations: AutoBeOpenApi.IOperation[],
+  oldbie: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>,
+  remained: Set<string>,
+): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
+  const pointer: IPointer<Record<
+    string,
+    AutoBeOpenApi.IJsonSchemaDescriptive
+  > | null> = {
+    value: null,
+  };
+  const agentica: MicroAgentica<Model> = new MicroAgentica({
+    model: ctx.model,
+    vendor: ctx.vendor,
+    config: {
+      ...(ctx.config ?? {}),
+      executor: {
+        describe: null,
+      },
+    },
+    histories: transformInterfaceSchemaHistories(ctx.state(), operations),
+    controllers: [
+      createApplication({
+        model: ctx.model,
+        build: async (next) => {
+          pointer.value ??= {};
+          Object.assign(pointer.value, next);
+        },
+        pointer,
+      }),
+    ],
+  });
+  enforceToolCall(agentica);
+
+  const already: string[] = Object.keys(oldbie);
+  await agentica
+    .conversate(
+      [
+        "Make type components please.",
+        "",
+        "Here is the list of request/response bodies' type names from",
+        "OpenAPI operations. Make type components of them. If more object",
+        "types are required during making the components, please make them",
+        "too.",
+        "",
+        ...Array.from(remained).map((k) => `- \`${k}\``),
+        ...(already.length !== 0
+          ? [
+              "",
+              "> By the way, here is the list of components schemas what you've",
+              "> already made. So, you don't need to make them again.",
+              ">",
+              ...already.map((k) => `> - \`${k}\``),
+            ]
+          : []),
+      ].join("\n"),
+    )
+    .finally(() => {
+      const tokenUsage = agentica.getTokenUsage();
+      ctx.usage().record(tokenUsage, ["interface"]);
+    });
+  if (pointer.value === null) {
+    // never be happened
+    throw new Error("Failed to create components.");
+  }
+  return (
+    (
+      OpenApiV3_1Emender.convertComponents({
+        schemas: pointer.value,
+      }) as AutoBeOpenApi.IComponents
+    ).schemas ?? {}
+  );
+}
+
+function createApplication<Model extends ILlmSchema.Model>(props: {
+  model: Model;
+  build: (
+    next: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>,
+  ) => Promise<void>;
+  pointer: IPointer<Record<
+    string,
+    AutoBeOpenApi.IJsonSchemaDescriptive
+  > | null>;
+}): IAgenticaController.IClass<Model> {
+  assertSchemaModel(props.model);
+
+  const application: ILlmApplication<Model> = collection[
+    props.model
+  ] as unknown as ILlmApplication<Model>;
+  return {
+    protocol: "class",
+    name: "interface",
+    application,
+    execute: {
+      makeComponents: async (next) => {
+        await props.build(next.schemas);
+      },
+    } satisfies IAutoBeInterfaceSchemaApplication,
+  };
+}
+
+const claude = typia.llm.application<
+  IAutoBeInterfaceSchemaApplication,
+  "claude",
+  { reference: true }
+>();
+const collection = {
+  chatgpt: typia.llm.application<
+    IAutoBeInterfaceSchemaApplication,
+    "chatgpt",
+    { reference: true }
+  >(),
+  claude,
+  llama: claude,
+  deepseek: claude,
+  "3.1": claude,
+};

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

@@ -0,0 +1,58 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+
+export interface IAutoBeInterfaceComplementApplication {
+  /**
+   * Complements missing schema types
+   *
+   * This method fills in schema definitions that are referenced via $ref but
+   * not yet defined in the `components.schemas` section. For example, if an API
+   * operation references `{ "$ref": "#/components/schemas/UserProfile" }` but
+   * `UserProfile` type is not defined in `components.schemas`, this method will
+   * add the missing schema definition.
+   *
+   * This function is designed to be called via AI function calling mechanism to
+   * ensure the OpenAPI document is complete and all referenced schemas are
+   * properly defined.
+   */
+  complementComponents(
+    props: IAutoBeInterfaceComplementApplication.IProps,
+  ): void;
+}
+export namespace IAutoBeInterfaceComplementApplication {
+  export interface IProps {
+    /**
+     * A collection of missing schema definitions that need to be added to the
+     * OpenAPI document's `components.schemas` section.
+     *
+     * This object contains schema definitions for types that are referenced but
+     * not yet defined:
+     *
+     * - Key: Schema name (`string`): The name of the schema type that will be
+     *   referenced in $ref statements
+     * - Value: `AutoBeOpenApi.IJsonSchema` - The complete JSON Schema definition
+     *   for that type
+     *
+     * Example structure:
+     *
+     * ```typescript
+     * {
+     *   "UserProfile": {
+     *     "type": "object",
+     *     "properties": {
+     *       "id": { "type": "string" },
+     *       "name": { "type": "string" },
+     *       "email": { "type": "string", "format": "email" }
+     *     },
+     *     "required": ["id", "name", "email"]
+     *   }
+     * }
+     * ```
+     *
+     * Each schema definition follows the JSON Schema specification and will be
+     * directly inserted into the OpenAPI document's components.schemas section,
+     * making them available for $ref references throughout the API
+     * specification.
+     */
+    schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
+  }
+}

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

@@ -0,0 +1,24 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+
+export interface IAutoBeInterfaceEndpointApplication {
+  /**
+   * Create Restful API endpoints.
+   *
+   * Create Restful API endpoints referencing the given documents; requirement
+   * analysis documents, and Prisma schema files with ERD descriptions. The API
+   * endpoints must cover every requirements and every entities in the ERD.
+   *
+   * Also, each combination of {@link AutoBeOpenApi.IEndpoint.path} and
+   * {@link AutoBeOpenApi.IEndpoint.method} must be unique to avoid duplicates.
+   * Please don't make any duplicates.
+   *
+   * @param props Properties containing the endpoints
+   */
+  makeEndpoints(props: IAutoBeInterfaceEndpointApplication.IProps): void;
+}
+export namespace IAutoBeInterfaceEndpointApplication {
+  export interface IProps {
+    /** The endpoints to generate. */
+    endpoints: AutoBeOpenApi.IEndpoint[];
+  }
+}

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

@@ -0,0 +1,112 @@
+import { tags } from "typia";
+
+export interface IAutoBeInterfaceGroupApplication {
+  /**
+   * Generate logical groups for organizing API endpoint creation based on
+   * Prisma schema structure.
+   *
+   * Groups MUST be derived from Prisma schema organization (namespaces, file
+   * structure, table prefixes) rather than arbitrary business domains. Only
+   * create new groups when existing schema structure cannot adequately cover
+   * all requirements.
+   *
+   * @param props Properties containing the groups to be created for API
+   *   organization
+   */
+  makeGroups(props: IAutoBeInterfaceGroupApplication.IProps): void;
+}
+
+export namespace IAutoBeInterfaceGroupApplication {
+  export interface IProps {
+    /**
+     * Array of API endpoint groups for organizing development.
+     *
+     * Groups MUST be organized around existing Prisma schema structure and
+     * provide complete coverage of all entities and requirements without
+     * overlap.
+     */
+    groups: IGroup[] & tags.MinItems<1>;
+  }
+
+  /**
+   * Definition of a logical API endpoint group based on Prisma schema
+   * organization.
+   *
+   * **SCHEMA-BASED GROUP REQUIREMENTS:**
+   *
+   * Groups MUST be derived from the Prisma schema structure rather than
+   * arbitrary business domain names. This ensures consistency with the
+   * underlying data model and prevents misalignment between API organization
+   * and database structure.
+   *
+   * **Primary Group Sources (in order of priority):**
+   *
+   * 1. **Prisma Schema Namespaces**: Use namespace names (e.g., `namespace
+   *    Shopping` → "Shopping")
+   * 2. **Schema File Names**: Derive from file names (e.g., `shopping.prisma` →
+   *    "Shopping")
+   * 3. **Table Prefix Patterns**: Use consistent prefixes (e.g., `shopping_orders`
+   *    → "Shopping")
+   * 4. **Schema Comments/Annotations**: Follow organizational comments in schema
+   *
+   * **Group Creation Guidelines:**
+   *
+   * - Each group must cover specific Prisma schema entities without overlap
+   * - Size groups appropriately for manageable endpoint generation cycles
+   * - Maintain clear boundaries based on schema organization
+   * - Ensure complete coverage of all database entities and requirements
+   * - Related database tables within the same schema area should be grouped
+   *   together
+   *
+   * **When to Create Schema-Independent Groups:**
+   *
+   * Only create groups that don't correspond to Prisma schema organization
+   * when:
+   *
+   * - Requirements include functionality not represented in any schema entity
+   * - Cross-cutting concerns span multiple schema areas
+   * - Integration operations don't map to specific database entities
+   * - System-level functionality requires dedicated API operations
+   *
+   * **Naming Standards:**
+   *
+   * - Use PascalCase format (e.g., "Shopping", "BBS", "UserManagement")
+   * - Names MUST directly reflect Prisma schema structure
+   * - Keep names concise and schema-derived
+   * - Avoid arbitrary business domain names
+   * - Maintain consistency with schema organization
+   *
+   * **Quality Requirements:**
+   *
+   * - Groups collectively must cover ALL entities and requirements
+   * - Each database entity belongs to exactly one group
+   * - Clear mapping to specific Prisma schema elements
+   * - Balance group sizes within schema constraints
+   * - Follow existing schema namespace or file structure patterns
+   */
+  export interface IGroup {
+    /**
+     * Unique identifier name derived from Prisma schema structure.
+     *
+     * Must correspond to schema namespaces, file names, table prefixes, or
+     * organizational annotations rather than arbitrary business domain names.
+     */
+    name: string & tags.MinLength<1>;
+
+    /**
+     * Comprehensive description of the group's scope, schema foundation, and
+     * purpose.
+     *
+     * **Required Content:**
+     *
+     * 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
+     */
+    description: string & tags.MinLength<1>;
+  }
+}

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

@@ -0,0 +1,125 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+import { tags } from "typia";
+
+export interface IAutoBeInterfaceOperationApplication {
+  /**
+   * Generate detailed API operations from path/method combinations.
+   *
+   * This function creates complete API operations following REST principles and
+   * quality standards. Each generated operation includes specification, path,
+   * method, detailed multi-paragraph description, concise summary, parameters,
+   * and appropriate request/response bodies.
+   *
+   * The function processes as many operations as possible in a single call,
+   * with progress tracking to ensure iterative completion of all required
+   * endpoints.
+   *
+   * @param props Properties containing the operations to generate.
+   */
+  makeOperations(props: IAutoBeInterfaceOperationApplication.IProps): void;
+}
+export namespace IAutoBeInterfaceOperationApplication {
+  export interface IProps {
+    /**
+     * Array of API operations to generate.
+     *
+     * Each operation in this array must include:
+     *
+     * - Specification: Detailed API specification with clear purpose and
+     *   functionality
+     * - Path: Resource-centric URL path (e.g., "/resources/{resourceId}")
+     * - Method: HTTP method (get, post, put, delete, patch)
+     * - Description: Extremely detailed multi-paragraph description referencing
+     *   Prisma schema comments
+     * - Summary: Concise one-sentence summary of the endpoint
+     * - Parameters: Array of all necessary parameters with descriptions and
+     *   schema definitions
+     * - RequestBody: For POST/PUT/PATCH methods, with typeName referencing
+     *   components.schemas
+     * - ResponseBody: With typeName referencing appropriate response type
+     *
+     * All operations must follow strict quality standards:
+     *
+     * 1. Detailed descriptions referencing Prisma schema comments
+     * 2. Accurate parameter definitions matching path parameters
+     * 3. Appropriate request/response body type references
+     * 4. Consistent patterns for CRUD operations
+     *
+     * For list retrievals (typically PATCH), include pagination, search, and
+     * sorting. For detail retrieval (GET), return a single resource. For
+     * creation (POST), use .ICreate request body. For modification (PUT), use
+     * .IUpdate request body.
+     */
+    operations: 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, "authorizationRole"> {
+    /**
+     * Authorization roles required to access this API operation.
+     *
+     * This field specifies which user roles are allowed to access this
+     * endpoint. Multiple roles can be specified to allow different types of
+     * users to access the same endpoint.
+     *
+     * ## Important Guidelines
+     *
+     * - Set to empty array `[]` for public endpoints that require no
+     *   authentication
+     * - Set to array with role strings for role-restricted endpoints
+     * - The role names MUST match exactly with the user type/role defined in the
+     *   database
+     * - This will be used by the Realize Agent to generate appropriate decorator
+     *   and authorization logic in the provider functions
+     * - The controller will apply the corresponding authentication decorator
+     *   based on these roles
+     *
+     * ## Examples
+     *
+     * - `[]` - Public endpoint, no authentication required
+     * - `["user"]` - Any authenticated user can access
+     * - `["admin"]` - Only admin users can access
+     * - `["admin", "moderator"]` - Both admin and moderator users can access
+     * - `["seller"]` - Only seller users can access
+     *
+     * Note: The actual authentication/authorization implementation will be
+     * handled by decorators at the controller level, and the provider function
+     * will receive the authenticated user object with the appropriate type.
+     */
+    authorizationRoles: Array<string & tags.MinLength<1>>;
+  }
+}

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

@@ -0,0 +1,76 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+
+export interface IAutoBeInterfaceSchemaApplication {
+  /**
+   * Generate OpenAPI components containing named schema types.
+   *
+   * This method receives a complete set of schema components and integrates
+   * them into the final OpenAPI specification. It processes all entity schemas,
+   * their variants, and related type definitions to ensure a comprehensive and
+   * consistent API design.
+   *
+   * The provided components should include schemas for all entities identified
+   * in the previous phases of API path/method definition and operation
+   * creation. This ensures that the final OpenAPI document has complete type
+   * coverage for all operations.
+   *
+   * CRITICAL: All schema definitions must follow the established naming
+   * conventions (IEntityName, IEntityName.ICreate, etc.) and must be thoroughly
+   * documented with descriptions that reference the original Prisma schema
+   * comments.
+   *
+   * @param props Properties containing components to generate.
+   */
+  makeComponents(props: IAutoBeInterfaceSchemaApplication.IProps): void;
+}
+export namespace IAutoBeInterfaceSchemaApplication {
+  export interface IProps {
+    /**
+     * Complete set of schema components for the OpenAPI specification.
+     *
+     * This property contains comprehensive type definitions for all entities in
+     * the system. It is the central repository of all named schema types that
+     * will be used throughout the API specification.
+     *
+     * CRITICAL REQUIREMENT: All object types MUST be defined as named types in
+     * the components.schemas section. Inline anonymous object definitions are
+     * strictly prohibited.
+     *
+     * This components object should include:
+     *
+     * - Main entity types (IEntityName)
+     * - Operation-specific variants (.ICreate, .IUpdate, .ISummary, etc.)
+     * - Container types (IPage<T> for pagination)
+     * - Enumeration types
+     *
+     * All schema definitions must include detailed descriptions that reference
+     * the original Prisma schema comments and thoroughly document each
+     * property. Every property that references an object must use a $ref to a
+     * named type in the components.schemas section. This applies to all objects
+     * in request bodies, response bodies, and properties that are objects or
+     * arrays of objects.
+     *
+     * Example structure:
+     *
+     * ```typescript
+     * {
+     *   schemas: {
+     *     IUser: {
+     *       type: "object",
+     *       properties: {
+     *         id: { type: "string", format: "uuid" },
+     *         email: { type: "string", format: "email" },
+     *         profile: { "$ref": "#/components/schemas/IUserProfile" }
+     *       },
+     *       required: ["id", "email"],
+     *       description: "User entity representing system account holders..."
+     *     },
+     *     "IUser.ICreate": { ... },
+     *     // Additional schemas
+     *   }
+     * }
+     * ```
+     */
+    schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
+  }
+}

package/src/orchestrate/interface/{OpenApiEndpointComparator.ts → utils/OpenApiEndpointComparator.ts}

@@ -12,4 +12,12 @@ export namespace OpenApiEndpointComparator {
   ): boolean {
     return x.path === y.path && x.method === y.method;
   }
+
+  export function compare(
+    x: AutoBeOpenApi.IEndpoint,
+    y: AutoBeOpenApi.IEndpoint,
+  ): number {
+    if (x.path !== y.path) return x.path.localeCompare(y.path);
+    return x.method.localeCompare(y.method);
+  }
 }

package/src/orchestrate/realize/orchestrateRealize.ts

@@ -35,7 +35,7 @@ export const orchestrateRealize =
       ctx,
       ops,
       authorizations,
-      2,
+      3,
     );
 
     const now = new Date().toISOString();
@@ -48,7 +48,24 @@ export const orchestrateRealize =
         compiled: {
           type: "success",
         },
-        functions: files,
+        functions: {
+          ...files,
+          ...authorizations
+            .flatMap((el) => {
+              return [
+                {
+                  [el.decorator.location]: el.decorator.content,
+                },
+                {
+                  [el.payload.location]: el.payload.content,
+                },
+                {
+                  [el.payload.location]: el.payload.content,
+                },
+              ];
+            })
+            .reduce((acc, cur) => Object.assign(acc, cur)),
+        },
         completed_at: now,
         created_at: now,
         id: v4(),