@autobe/agent 0.17.1 → 0.19.1

package/src/orchestrate/interface/orchestrateInterfaceSchemas.ts

@@ -1,24 +1,28 @@
-import { IAgenticaController, MicroAgentica } from "@agentica/core";
-import { AutoBeOpenApi } from "@autobe/interface";
-import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
+import { IAgenticaController } from "@agentica/core";
+import {
+  AutoBeInterfaceSchemasEvent,
+  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 typia, { tags } 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 { orchestrateInterfaceSchemasReview } from "./orchestrateInterfaceSchemasReview";
 import { IAutoBeInterfaceSchemaApplication } from "./structures/IAutoBeInterfaceSchemaApplication";
+import { validateAuthorizationSchema } from "./utils/validateAuthorizationSchema";
 
 export async function orchestrateInterfaceSchemas<
   Model extends ILlmSchema.Model,
 >(
   ctx: AutoBeContext<Model>,
   operations: AutoBeOpenApi.IOperation[],
-  capacity: number = 12,
+  capacity: number = 8,
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
   const typeNames: Set<string> = new Set();
   for (const op of operations) {
@@ -29,28 +33,40 @@ export async function orchestrateInterfaceSchemas<
     array: Array.from(typeNames),
     capacity,
   });
-  let progress: number = 0;
+  const progress: AutoBeProgressEventBase = {
+    total: typeNames.size,
+    completed: 0,
+  };
+  const reviewProgress: AutoBeProgressEventBase = {
+    total: matrix.length,
+    completed: 0,
+  };
+  const roles: string[] =
+    ctx.state().analyze?.roles.map((role) => role.name) ?? [];
 
-  const x: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> = {};
+  const x: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
+    roles.length > 0
+      ? {
+          IAuthorizationToken: authTokenSchema,
+        }
+      : {};
   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;
+        await divideAndConquer(ctx, operations, it, 3, progress);
+      const newbie: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
+        await orchestrateInterfaceSchemasReview(
+          ctx,
+          operations,
+          row,
+          reviewProgress,
+        );
+      return { ...row, ...newbie };
     }),
   )) {
     Object.assign(x, y);
   }
+  if (x.IAuthorizationToken) x.IAuthorizationToken = authTokenSchema;
   return x;
 }
 
@@ -59,20 +75,18 @@ async function divideAndConquer<Model extends ILlmSchema.Model>(
   operations: AutoBeOpenApi.IOperation[],
   typeNames: string[],
   retry: number,
-  progress: (completed: number) => void,
+  progress: AutoBeProgressEventBase,
 ): 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));
+      await process(ctx, operations, schemas, remained, progress);
     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;
 }
@@ -82,77 +96,70 @@ async function process<Model extends ILlmSchema.Model>(
   operations: AutoBeOpenApi.IOperation[],
   oldbie: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>,
   remained: Set<string>,
+  progress: AutoBeProgressEventBase,
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
+  const already: string[] = Object.keys(oldbie);
   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,
-      },
-    },
+  const { tokenUsage } = await ctx.conversate({
+    source: "interfaceSchemas",
     histories: transformInterfaceSchemaHistories(ctx.state(), operations),
-    controllers: [
-      createApplication({
-        model: ctx.model,
-        build: async (next) => {
-          pointer.value ??= {};
-          Object.assign(pointer.value, next);
-        },
-        pointer,
-      }),
-    ],
+    controller: createController({
+      model: ctx.model,
+      build: async (next) => {
+        pointer.value ??= {};
+        Object.assign(pointer.value, next);
+      },
+      pointer,
+    }),
+    enforceFunctionCall: true,
+    message: [
+      "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"),
   });
-  enforceToolCall(agentica);
+  if (pointer.value === null) throw new Error("Failed to create components.");
 
-  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().aggregate;
-      ctx.usage().record(tokenUsage, ["interface"]);
-    });
-  if (pointer.value === null) {
-    // never be happened
-    throw new Error("Failed to create components.");
-  }
-  return (
+  const schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
     (
       OpenApiV3_1Emender.convertComponents({
         schemas: pointer.value,
       }) as AutoBeOpenApi.IComponents
-    ).schemas ?? {}
-  );
+    ).schemas ?? {};
+  ctx.dispatch({
+    type: "interfaceSchemas",
+    schemas,
+    tokenUsage,
+    completed: (progress.completed += Object.keys(schemas).length),
+    total: (progress.total += Object.keys(schemas).filter(
+      (k) => remained.has(k) === false,
+    ).length),
+    step: ctx.state().prisma?.step ?? 0,
+    created_at: new Date().toISOString(),
+  } satisfies AutoBeInterfaceSchemasEvent);
+  return schemas;
 }
 
-function createApplication<Model extends ILlmSchema.Model>(props: {
+function createController<Model extends ILlmSchema.Model>(props: {
   model: Model;
   build: (
     next: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>,
@@ -164,9 +171,34 @@ function createApplication<Model extends ILlmSchema.Model>(props: {
 }): IAgenticaController.IClass<Model> {
   assertSchemaModel(props.model);
 
+  const validate = (
+    next: unknown,
+  ): IValidation<IAutoBeInterfaceSchemaApplication.IProps> => {
+    const result: IValidation<IAutoBeInterfaceSchemaApplication.IProps> =
+      typia.validate<IAutoBeInterfaceSchemaApplication.IProps>(next);
+    if (result.success === false) return result;
+
+    // Check all IAuthorized types
+    const errors: IValidation.IError[] = [];
+    validateAuthorizationSchema({
+      errors,
+      schemas: result.data.schemas,
+      path: "$input.schemas",
+    });
+    if (errors.length !== 0)
+      return {
+        success: false,
+        errors,
+        data: next,
+      };
+    return result;
+  };
+
   const application: ILlmApplication<Model> = collection[
-    props.model
-  ] as unknown as ILlmApplication<Model>;
+    props.model === "chatgpt" ? "chatgpt" : "claude"
+  ](
+    validate,
+  ) satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
   return {
     protocol: "class",
     name: "interface",
@@ -179,19 +211,71 @@ function createApplication<Model extends ILlmSchema.Model>(props: {
   };
 }
 
-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,
+  chatgpt: (validate: Validator) =>
+    typia.llm.application<IAutoBeInterfaceSchemaApplication, "chatgpt">({
+      validate: {
+        makeComponents: validate,
+      },
+    }),
+  claude: (validate: Validator) =>
+    typia.llm.application<IAutoBeInterfaceSchemaApplication, "claude">({
+      validate: {
+        makeComponents: validate,
+      },
+    }),
 };
+
+type Validator = (
+  input: unknown,
+) => IValidation<IAutoBeInterfaceSchemaApplication.IProps>;
+
+/**
+ * Authorization token response structure.
+ *
+ * This interface defines the structure of the authorization token response
+ * returned after successful user authentication. It contains both access and
+ * refresh tokens along with their expiration information.
+ *
+ * This token structure is automatically included in API schemas when the system
+ * detects authorization roles in the requirements analysis phase. It provides a
+ * standard format for JWT-based authentication across the generated backend
+ * applications.
+ */
+interface IAuthorizationToken {
+  /**
+   * JWT access token for authenticated requests.
+   *
+   * This token should be included in the Authorization header for subsequent
+   * authenticated API requests as `Bearer {token}`.
+   */
+  access: string;
+
+  /**
+   * Refresh token for obtaining new access tokens.
+   *
+   * This token can be used to request new access tokens when the current access
+   * token expires, extending the user's session.
+   */
+  refresh: string;
+
+  /**
+   * Access token expiration timestamp.
+   *
+   * ISO 8601 date-time string indicating when the access token will expire and
+   * can no longer be used for authentication.
+   */
+  expired_at: string & tags.Format<"date-time">;
+
+  /**
+   * Refresh token expiration timestamp.
+   *
+   * ISO 8601 date-time string indicating the latest time until which the
+   * refresh token can be used to obtain new access tokens.
+   */
+  refreshable_until: string & tags.Format<"date-time">;
+}
+
+const authTokenSchema: AutoBeOpenApi.IJsonSchemaDescriptive =
+  typia.json.schema<IAuthorizationToken>().components.schemas!
+    .IAuthorizationToken as AutoBeOpenApi.IJsonSchemaDescriptive;

package/src/orchestrate/interface/orchestrateInterfaceSchemasReview.ts

@@ -0,0 +1,145 @@
+import { IAgenticaController } from "@agentica/core";
+import {
+  AutoBeInterfaceSchemasReviewEvent,
+  AutoBeOpenApi,
+} 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 { AutoBeContext } from "../../context/AutoBeContext";
+import { assertSchemaModel } from "../../context/assertSchemaModel";
+import { transformInterfaceSchemasReviewHistories } from "./histories/transformInterfaceSchemasReviewHistories";
+import { IAutoBeInterfaceSchemasReviewApplication } from "./structures/IAutobeInterfaceSchemasReviewApplication";
+import { validateAuthorizationSchema } from "./utils/validateAuthorizationSchema";
+
+export async function orchestrateInterfaceSchemasReview<
+  Model extends ILlmSchema.Model,
+>(
+  ctx: AutoBeContext<Model>,
+  operations: AutoBeOpenApi.IOperation[],
+  schemas: Record<
+    string,
+    AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>
+  >,
+  progress: { total: number; completed: number },
+): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
+  try {
+    const pointer: IPointer<IAutoBeInterfaceSchemasReviewApplication.IProps | null> =
+      {
+        value: null,
+      };
+    const { tokenUsage } = await ctx.conversate({
+      source: "interfaceSchemasReview",
+      controller: createController({
+        model: ctx.model,
+        pointer,
+        schemas,
+      }),
+      histories: transformInterfaceSchemasReviewHistories(
+        ctx.state(),
+        operations,
+        schemas,
+      ),
+      enforceFunctionCall: true,
+      message: "Review type schemas.",
+    });
+    if (pointer.value === null) {
+      console.error("Failed to extract review information.");
+      ++progress.completed;
+      return {};
+    }
+
+    const content: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
+      (
+        OpenApiV3_1Emender.convertComponents({
+          schemas: pointer.value.content,
+        }) as AutoBeOpenApi.IComponents
+      ).schemas ?? {};
+    ctx.dispatch({
+      type: "interfaceSchemasReview",
+      schemas: schemas,
+      review: pointer.value.review,
+      plan: pointer.value.plan,
+      content,
+      tokenUsage,
+      step: ctx.state().analyze?.step ?? 0,
+      total: progress.total,
+      completed: ++progress.completed,
+      created_at: new Date().toISOString(),
+    } satisfies AutoBeInterfaceSchemasReviewEvent);
+    return content;
+  } catch (error) {
+    console.error("Error occurred during interface schemas review:", error);
+    ++progress.completed;
+    return {};
+  }
+}
+
+function createController<Model extends ILlmSchema.Model>(props: {
+  model: Model;
+  pointer: IPointer<IAutoBeInterfaceSchemasReviewApplication.IProps | null>;
+  schemas: Record<
+    string,
+    AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>
+  >;
+}): IAgenticaController.IClass<Model> {
+  assertSchemaModel(props.model);
+
+  const validate = (
+    next: unknown,
+  ): IValidation<IAutoBeInterfaceSchemasReviewApplication.IProps> => {
+    const result: IValidation<IAutoBeInterfaceSchemasReviewApplication.IProps> =
+      typia.validate<IAutoBeInterfaceSchemasReviewApplication.IProps>(next);
+    if (result.success === false) return result;
+
+    const errors: IValidation.IError[] = [];
+    validateAuthorizationSchema({
+      errors,
+      schemas: result.data.content,
+      path: "$input.content",
+    });
+    if (errors.length !== 0)
+      return {
+        success: false,
+        errors,
+        data: next,
+      };
+    return result;
+  };
+  const application: ILlmApplication<Model> = collection[
+    props.model === "chatgpt" ? "chatgpt" : "claude"
+  ](
+    validate,
+  ) satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
+  return {
+    protocol: "class",
+    name: "Reviewer",
+    application,
+    execute: {
+      review: (input) => {
+        props.pointer.value = input;
+      },
+    } satisfies IAutoBeInterfaceSchemasReviewApplication,
+  };
+}
+
+const collection = {
+  chatgpt: (validate: Validator) =>
+    typia.llm.application<IAutoBeInterfaceSchemasReviewApplication, "chatgpt">({
+      validate: {
+        review: validate,
+      },
+    }),
+  claude: (validate: Validator) =>
+    typia.llm.application<IAutoBeInterfaceSchemasReviewApplication, "claude">({
+      validate: {
+        review: validate,
+      },
+    }),
+};
+
+type Validator = (
+  input: unknown,
+) => IValidation<IAutoBeInterfaceSchemasReviewApplication.IProps>;

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

@@ -0,0 +1,49 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+import { tags } from "typia";
+
+export interface IAutoBeInterfaceAuthorizationsApplication {
+  /**
+   * Creates an authorization Operations for the given roles
+   *
+   * This method generates an OpenAPI interface that defines the authorization
+   * requirements for the given roles. It ensures that the interface reflects
+   * the correct permissions and access levels for each role.
+   */
+  makeOperations(props: IAutoBeInterfaceAuthorizationsApplication.IProps): void;
+}
+
+export namespace IAutoBeInterfaceAuthorizationsApplication {
+  export interface IProps {
+    /**
+     * Array of API operations to generate authorization operation for.
+     *
+     * 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: AutoBeOpenApi.IOperation[] & tags.MinItems<1>;
+  }
+}

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

@@ -20,6 +20,45 @@ 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/IAutoBeInterfaceEndpointApplication.ts

@@ -1,4 +1,5 @@
 import { AutoBeOpenApi } from "@autobe/interface";
+import { tags } from "typia";
 
 export interface IAutoBeInterfaceEndpointApplication {
   /**
@@ -19,6 +20,6 @@ export interface IAutoBeInterfaceEndpointApplication {
 export namespace IAutoBeInterfaceEndpointApplication {
   export interface IProps {
     /** The endpoints to generate. */
-    endpoints: AutoBeOpenApi.IEndpoint[];
+    endpoints: AutoBeOpenApi.IEndpoint[] & tags.MinItems<1>;
   }
 }