@autobe/agent 0.16.1 → 0.18.0

package/src/orchestrate/analyze/structures/IAutoBeAnalyzeScenarioApplication.ts

@@ -0,0 +1,85 @@
+import { AutoBeAnalyzeRole, CamelPattern } from "@autobe/interface";
+import { AutoBeAnalyzeFile } from "@autobe/interface/src/histories/contents/AutoBeAnalyzeFile";
+
+export interface IAutoBeAnalyzeScenarioApplication {
+  /**
+   * Compose project structure with roles and files.
+   *
+   * Design a list of roles and initial documents that you need to create for
+   * that requirement. Roles define team member responsibilities, while files
+   * define the documentation structure. These are managed separately. If you
+   * determine from the conversation that the user's requirements have not been
+   * fully gathered, you must stop the analysis and continue collecting the
+   * remaining requirements. In this case, you do not need to generate any files
+   * or roles. Simply pass an empty array to `input.files` and `input.roles`.
+   *
+   * @param input Prefix, roles, and files
+   * @returns
+   */
+  compose(input: IAutoBeAnalyzeScenarioApplication.IProps): void;
+}
+
+export namespace IAutoBeAnalyzeScenarioApplication {
+  export interface IProps {
+    /** Reason for the analysis and composition of the project structure. */
+    reason: string;
+
+    /**
+     * Prefix for file names and variable names. This will be used for
+     * organizing documentation files.
+     *
+     * MUST use camelCase naming convention.
+     */
+    prefix: string & CamelPattern;
+
+    /** Roles to be assigned for the project */
+    roles: AutoBeAnalyzeRole[];
+
+    /**
+     * Language for document content. When specified by the user, this takes
+     * precedence over the locale setting for determining document language.
+     */
+    language?: string;
+
+    /**
+     * If the user has requested a specific number of pages, enter that number.
+     * Otherwise, provide an appropriate number of documents needed to meet the
+     * user's requirements. This number must always match the length of the
+     * files property, must be greater than 1, and must include the table of
+     * contents. For example, if the user requests 3 pages, the total should be
+     * 4, including the table of contents.
+     */
+    page: number;
+
+    /**
+     * # Document files to be generated
+     *
+     * File name must be English and it must contain the numbering and prefix.
+     *
+     * These files represent business documentation that may include:
+     *
+     * - Business requirements and functional specifications in natural language
+     * - User journey mapping and use case scenarios
+     * - Business rules and workflow definitions
+     * - Service overview and business model description
+     * - User roles and permission requirements (described in natural language)
+     * - Business logic and validation rules
+     * - STRICTLY PROHIBITED: Do NOT include database schemas, ERD, or API
+     *   specifications
+     * - All requirements must be written in natural language for clarity
+     *
+     * Generate files based on actual requirements gathered from conversation.
+     * Do not create unnecessary documentation - only generate what is needed to
+     * properly define the business requirements and system specifications.
+     *
+     * # Page Length Rules
+     *
+     * The number of documents must match the user's request, excluding the
+     * table of contents. For example, if the user requests 3 pages, a total of
+     * 4 documents should be generated, including the table of contents. If the
+     * user does not specify a number, generate a sufficient number of documents
+     * to adequately support the service.
+     */
+    files: Array<AutoBeAnalyzeFile.Scenario>;
+  }
+}

package/src/orchestrate/analyze/structures/IAutoBeAnalyzeWriteApplication.ts

@@ -0,0 +1,71 @@
+export interface IAutoBeAnalyzeWriteApplication {
+  /**
+   * Creates or updates planning documentation based on the provided plan and
+   * content structure.
+   *
+   * This function is called by the AI agent to write detailed planning
+   * documents that will be used by backend developers to understand what needs
+   * to be built, why it's being built, and how it should function.
+   *
+   * @param props - The properties containing the document plan and initial
+   *   content
+   */
+  write(props: IAutoBeAnalyzeWriteApplication.IProps): void;
+}
+export namespace IAutoBeAnalyzeWriteApplication {
+  export interface IProps {
+    /**
+     * The document planning structure that outlines what needs to be written.
+     *
+     * This includes:
+     *
+     * - Document title and purpose
+     * - Table of contents structure
+     * - Key sections to be covered
+     * - Relationships with other documents
+     * - Target audience (backend developers)
+     *
+     * The plan serves as a roadmap for the AI agent to ensure all necessary
+     * topics are covered in the documentation process.
+     *
+     * Example plan structure:
+     *
+     * - Service overview with business model
+     * - User roles and authentication requirements
+     * - Functional requirements with EARS format
+     * - Non-functional requirements
+     * - Business requirements in natural language
+     * - User scenarios and use cases
+     */
+    plan: string;
+
+    /**
+     * The initial content or context for the document being written.
+     *
+     * This may include:
+     *
+     * - User requirements and business goals
+     * - Existing documentation to build upon
+     * - Specific scenarios or use cases to document
+     * - Technical constraints or preferences
+     * - Related documents for reference
+     *
+     * The content provides the raw material that the AI agent will transform
+     * into structured, developer-ready documentation following the planning
+     * guidelines.
+     *
+     * The AI agent will expand this content into comprehensive documentation
+     * that:
+     *
+     * - Removes all ambiguity for backend developers
+     * - Provides specific, measurable requirements in natural language
+     * - Focuses on business logic and requirements, NOT technical implementation
+     * - STRICTLY PROHIBITED: Do NOT write database schemas, ERD, or API
+     *   specifications
+     * - Uses EARS format for all applicable requirements
+     * - Follows proper document linking conventions
+     * - Includes Mermaid diagrams with proper syntax (double quotes mandatory)
+     */
+    content: string;
+  }
+}

package/src/orchestrate/interface/histories/transformInterfaceAuthorizationsHistories.ts

@@ -0,0 +1,40 @@
+import { IAgenticaHistoryJson } from "@agentica/core";
+import { AutoBeAnalyzeRole } from "@autobe/interface";
+import { v4 } from "uuid";
+
+import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromptConstant";
+import { AutoBeState } from "../../../context/AutoBeState";
+import { transformInterfaceAssetHistories } from "./transformInterfaceAssetHistories";
+
+export const transformInterfaceAuthorizationsHistories = (
+  state: AutoBeState,
+  role: AutoBeAnalyzeRole,
+): Array<
+  IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
+> => {
+  return [
+    {
+      type: "systemMessage",
+      id: v4(),
+      created_at: new Date().toISOString(),
+      text: AutoBeSystemPromptConstant.INTERFACE_AUTHORIZATION,
+    },
+    ...transformInterfaceAssetHistories(state),
+    {
+      type: "assistantMessage",
+      id: v4(),
+      created_at: new Date().toISOString(),
+      text: [
+        "You have to make API operations for the given role:",
+        "",
+        "## Role",
+        "",
+        "```json",
+        JSON.stringify(role),
+        "```",
+        "",
+        "",
+      ].join("\n"),
+    },
+  ];
+};

package/src/orchestrate/interface/histories/transformInterfaceEndpointHistories.ts

@@ -1,4 +1,5 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
+import { AutoBeOpenApi } from "@autobe/interface";
 import { AutoBeInterfaceGroup } from "@autobe/interface/src/histories/contents/AutoBeInterfaceGroup";
 import { v4 } from "uuid";
 
@@ -9,6 +10,7 @@ import { transformInterfaceAssetHistories } from "./transformInterfaceAssetHisto
 export const transformInterfaceEndpointHistories = (
   state: AutoBeState,
   group: AutoBeInterfaceGroup,
+  authorizations: AutoBeOpenApi.IOperation[],
 ): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => [
@@ -29,6 +31,31 @@ export const transformInterfaceEndpointHistories = (
       "```json",
       JSON.stringify(group),
       "```",
+      "",
+      "**IMPORTANT: DO NOT DUPLICATE EXISTING OPERATIONS**",
+      "",
+      "These operations already exist. Do NOT create similar endpoints:",
+      "",
+      "```json",
+      JSON.stringify(
+        authorizations.map((op) => ({
+          path: op.path,
+          method: op.method,
+          name: op.name,
+          summary: op.summary,
+        })),
+        null,
+        2,
+      ),
+      "```",
+      "",
+      "**DO NOT CREATE:**",
+      "- User creation endpoints (POST /users, POST /admins)",
+      "- Authentication endpoints (handled separately)",
+      "- Focus only on business data operations",
+      "",
+      "Create operations for DIFFERENT paths and DIFFERENT purposes only.",
+      "",
     ].join("\n"),
   },
 ];

package/src/orchestrate/interface/histories/transformInterfaceOperationHistories.ts

@@ -1,5 +1,5 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
-import { AutoBeOpenApi } from "@autobe/interface";
+import { AutoBeAnalyzeHistory, AutoBeOpenApi } from "@autobe/interface";
 import { v4 } from "uuid";
 
 import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromptConstant";
@@ -11,24 +11,47 @@ export const transformInterfaceOperationHistories = (
   endpoints: AutoBeOpenApi.IEndpoint[],
 ): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
-> => [
-  {
-    type: "systemMessage",
-    id: v4(),
-    created_at: new Date().toISOString(),
-    text: AutoBeSystemPromptConstant.INTERFACE_OPERATION,
-  },
-  ...transformInterfaceAssetHistories(state),
-  {
-    type: "assistantMessage",
-    id: v4(),
-    created_at: new Date().toISOString(),
-    text: [
-      "You have to make API operations for the given endpoints:",
-      "",
-      "```json",
-      JSON.stringify(endpoints),
-      "```",
-    ].join("\n"),
-  },
-];
+> => {
+  const analyze: AutoBeAnalyzeHistory = state.analyze!;
+  return [
+    {
+      type: "systemMessage",
+      id: v4(),
+      created_at: new Date().toISOString(),
+      text: AutoBeSystemPromptConstant.INTERFACE_OPERATION,
+    },
+    ...transformInterfaceAssetHistories(state),
+    {
+      type: "systemMessage",
+      id: v4(),
+      created_at: new Date().toISOString(),
+      text: [
+        `## Service Prefix`,
+        `- Original: ${analyze.prefix}`,
+        `- PascalCase for DTOs: ${analyze.prefix
+          .split(/[-_]/)
+          .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+          .join("")}`,
+        `- Expected DTO pattern: I${analyze.prefix
+          .split(/[-_]/)
+          .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+          .join("")}{EntityName}`,
+      ].join("\n"),
+    },
+    {
+      type: "assistantMessage",
+      id: v4(),
+      created_at: new Date().toISOString(),
+      text: [
+        "You have to make API operations for the given endpoints:",
+        "",
+        "```json",
+        JSON.stringify(endpoints),
+        "```",
+        "",
+        "If there is a content in the failure, it is to explain why it failed before.",
+        "Please supplement or modify the Operation accordingly.",
+      ].join("\n"),
+    },
+  ];
+};

package/src/orchestrate/interface/histories/transformInterfaceOperationsReviewHistories.ts

@@ -0,0 +1,43 @@
+import { IMicroAgenticaHistoryJson } from "@agentica/core";
+import { AutoBeOpenApi } from "@autobe/interface";
+import { ILlmSchema } from "@samchon/openapi";
+import { v4 } from "uuid";
+
+import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromptConstant";
+import { AutoBeContext } from "../../../context/AutoBeContext";
+import { transformInterfaceAssetHistories } from "./transformInterfaceAssetHistories";
+
+export function transformInterfaceOperationsReviewHistories<
+  Model extends ILlmSchema.Model,
+>(
+  ctx: AutoBeContext<Model>,
+  operations: AutoBeOpenApi.IOperation[],
+): Array<IMicroAgenticaHistoryJson> {
+  return [
+    {
+      type: "systemMessage",
+      id: v4(),
+      created_at: new Date().toISOString(),
+      text: AutoBeSystemPromptConstant.INTERFACE_OPERATION,
+    },
+    ...transformInterfaceAssetHistories(ctx.state()),
+    {
+      type: "systemMessage",
+      id: v4(),
+      created_at: new Date().toISOString(),
+      text: AutoBeSystemPromptConstant.INTERFACE_OPERATION_REVIEW,
+    },
+    {
+      type: "assistantMessage",
+      id: v4(),
+      created_at: new Date().toISOString(),
+      text: [
+        "Review the following API operations:",
+        "",
+        "```json",
+        JSON.stringify(operations, null, 2),
+        "```",
+      ].join("\n"),
+    },
+  ];
+}

package/src/orchestrate/interface/histories/transformInterfaceSchemasReviewHistories.ts

@@ -0,0 +1,63 @@
+import { IAgenticaHistoryJson } from "@agentica/core";
+import { AutoBeOpenApi } from "@autobe/interface";
+import { v4 } from "uuid";
+
+import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromptConstant";
+import { AutoBeState } from "../../../context/AutoBeState";
+import { transformInterfaceAssetHistories } from "./transformInterfaceAssetHistories";
+
+export const transformInterfaceSchemasReviewHistories = (
+  state: AutoBeState,
+  operations: AutoBeOpenApi.IOperation[],
+  schemaDescriptive: Record<
+    string,
+    AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>
+  >,
+): Array<
+  IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
+> => {
+  return [
+    {
+      type: "systemMessage",
+      id: v4(),
+      created_at: new Date().toISOString(),
+      text: AutoBeSystemPromptConstant.INTERFACE_SCHEMA_REVIEW,
+    },
+    ...transformInterfaceAssetHistories(state),
+    {
+      type: "assistantMessage",
+      id: v4(),
+      created_at: new Date().toISOString(),
+      text: [
+        "The Schema Agent has generated schemas for the following API operations.",
+        "These operations define what endpoints exist and what request/response types they use:",
+        "",
+        "```json",
+        JSON.stringify(operations, null, 2),
+        "```",
+        "",
+        "All schema types referenced in these operations (in requestBody and responses) must exist in the schemas.",
+      ].join("\n"),
+    },
+    {
+      id: v4(),
+      type: "assistantMessage",
+      created_at: new Date().toISOString(),
+      text: [
+        "Here are the schemas generated by the Schema Agent that need your review:",
+        "",
+        "```json",
+        JSON.stringify(schemaDescriptive, null, 2),
+        "```",
+        "",
+        "Please review these schemas for:",
+        "1. Security vulnerabilities (passwords in responses, actor IDs in requests)",
+        "2. Missing entities or variants referenced by the operations",
+        "3. Type accuracy and format specifications",
+        "4. Alignment with Prisma schema and business requirements",
+        "",
+        "Fix all critical issues and return the enhanced schemas in the content field.",
+      ].join("\n"),
+    },
+  ];
+};

package/src/orchestrate/interface/orchestrateInterface.ts

@@ -6,10 +6,10 @@ import {
   AutoBeOpenApi,
 } from "@autobe/interface";
 import { ILlmSchema } from "@samchon/openapi";
-import { v4 } from "uuid";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { IAutoBeApplicationProps } from "../../context/IAutoBeApplicationProps";
+import { orchestrateInterfaceAuthorizations } from "./orchestrateInterfaceAuthorizations";
 import { orchestrateInterfaceComplement } from "./orchestrateInterfaceComplement";
 import { orchestrateInterfaceEndpoints } from "./orchestrateInterfaceEndpoints";
 import { orchestrateInterfaceGroups } from "./orchestrateInterfaceGroups";
@@ -32,18 +32,21 @@ export const orchestrateInterface =
 
     const init: AutoBeAssistantMessageHistory | AutoBeInterfaceGroupsEvent =
       await orchestrateInterfaceGroups(ctx);
-    if (init.type === "assistantMessage") {
-      ctx.dispatch(init);
-      ctx.histories().push(init);
-      return init;
-    } else ctx.dispatch(init);
+    if (init.type === "assistantMessage") return ctx.assistantMessage(init);
+    else ctx.dispatch(init);
+
+    // AUTHORIZATION
+    const authorizations: AutoBeOpenApi.IOperation[] =
+      await orchestrateInterfaceAuthorizations(ctx);
 
     // ENDPOINTS & OPERATIONS
     const endpoints: AutoBeOpenApi.IEndpoint[] =
-      await orchestrateInterfaceEndpoints(ctx, init.groups);
+      await orchestrateInterfaceEndpoints(ctx, init.groups, authorizations);
     const operations: AutoBeOpenApi.IOperation[] =
       await orchestrateInterfaceOperations(ctx, endpoints);
 
+    operations.push(...authorizations);
+
     // TYPE SCHEMAS
     const document: AutoBeOpenApi.IDocument = {
       operations,
@@ -58,23 +61,11 @@ export const orchestrateInterface =
     );
 
     // DO COMPILE
-    const result: AutoBeInterfaceHistory = {
-      type: "interface",
-      id: v4(),
-      document,
-      reason: props.reason,
-      step: ctx.state().analyze?.step ?? 0,
-      created_at: start.toISOString(),
-      completed_at: new Date().toISOString(),
-    };
-    ctx.state().interface = result;
-    ctx.histories().push(result);
-    ctx.dispatch({
+    return ctx.dispatch({
       type: "interfaceComplete",
-      document: result.document,
-      created_at: start.toISOString(),
-      reason: props.reason,
+      document,
+      created_at: new Date().toISOString(),
+      elapsed: new Date().getTime() - start.getTime(),
       step: ctx.state().analyze?.step ?? 0,
     } satisfies AutoBeInterfaceCompleteEvent);
-    return result;
   };

package/src/orchestrate/interface/orchestrateInterfaceAuthorizations.ts

@@ -0,0 +1,106 @@
+import { IAgenticaController } from "@agentica/core";
+import { AutoBeAnalyzeRole, AutoBeOpenApi } from "@autobe/interface";
+import { AutoBeInterfaceAuthorizationEvent } from "@autobe/interface/src/events/AutoBeInterfaceAuthorizationEvent";
+import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
+import { IPointer } from "tstl";
+import typia from "typia";
+
+import { AutoBeContext } from "../../context/AutoBeContext";
+import { assertSchemaModel } from "../../context/assertSchemaModel";
+import { IProgress } from "../internal/IProgress";
+import { transformInterfaceAuthorizationsHistories } from "./histories/transformInterfaceAuthorizationsHistories";
+import { IAutoBeInterfaceAuthorizationsApplication } from "./structures/IAutoBeInterfaceAuthorizationsApplication";
+
+export async function orchestrateInterfaceAuthorizations<
+  Model extends ILlmSchema.Model,
+>(ctx: AutoBeContext<Model>): Promise<AutoBeOpenApi.IOperation[]> {
+  const roles: AutoBeAnalyzeRole[] = ctx.state().analyze?.roles ?? [];
+  const progress: IProgress = {
+    total: roles.length,
+    completed: 0,
+  };
+  const operations: AutoBeOpenApi.IOperation[][] = await Promise.all(
+    roles.map(async (role) => {
+      const event: AutoBeInterfaceAuthorizationEvent = await process(
+        ctx,
+        role,
+        progress,
+      );
+      ctx.dispatch(event);
+      return event.operations;
+    }),
+  );
+  return operations.flat();
+}
+
+async function process<Model extends ILlmSchema.Model>(
+  ctx: AutoBeContext<Model>,
+  role: AutoBeAnalyzeRole,
+  progress: IProgress,
+): Promise<AutoBeInterfaceAuthorizationEvent> {
+  const pointer: IPointer<IAutoBeInterfaceAuthorizationsApplication.IProps | null> =
+    {
+      value: null,
+    };
+  const { tokenUsage } = await ctx.conversate({
+    source: "interfaceAuthorization",
+    histories: transformInterfaceAuthorizationsHistories(ctx.state(), role),
+    controller: createController({
+      model: ctx.model,
+      build: (next) => {
+        pointer.value = next;
+      },
+    }),
+    enforceFunctionCall: true,
+    message: "Create Authorization Operation for the given roles",
+  });
+  if (pointer.value === null)
+    throw new Error("Failed to generate authorization operation.");
+
+  return {
+    type: "interfaceAuthorization",
+    operations: pointer.value.operations,
+    completed: ++progress.completed,
+    tokenUsage,
+    created_at: new Date().toISOString(),
+    step: ctx.state().analyze?.step ?? 0,
+    total: progress.total,
+  } satisfies AutoBeInterfaceAuthorizationEvent;
+}
+
+function createController<Model extends ILlmSchema.Model>(props: {
+  model: Model;
+  build: (next: IAutoBeInterfaceAuthorizationsApplication.IProps) => void;
+}): IAgenticaController.IClass<Model> {
+  assertSchemaModel(props.model);
+
+  const application: ILlmApplication<Model> = collection[
+    props.model
+  ] as unknown as ILlmApplication<Model>;
+
+  return {
+    protocol: "class",
+    name: "Create Authorization Interface",
+    application,
+    execute: {
+      makeOperations: (next) => {
+        props.build(next);
+      },
+    } satisfies IAutoBeInterfaceAuthorizationsApplication,
+  };
+}
+
+const claude = typia.llm.application<
+  IAutoBeInterfaceAuthorizationsApplication,
+  "claude"
+>();
+const collection = {
+  chatgpt: typia.llm.application<
+    IAutoBeInterfaceAuthorizationsApplication,
+    "chatgpt"
+  >(),
+  claude,
+  llama: claude,
+  deepseek: claude,
+  "3.1": claude,
+};