@autobe/agent 0.17.1 → 0.19.1

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";
+import { tags } from "typia";
+
+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.
+     *
+     * DO: 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
+     * - DO NOT: Include database schemas, ERD, or API specifications
+     * - DO: Write all requirements 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> & tags.MinItems<1>;
+  }
+}

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/transformInterfaceAssetHistories.ts

@@ -59,6 +59,7 @@ export const transformInterfaceAssetHistories = (
         "4. Verify EVERY field reference against the actual schema before including in descriptions",
         "",
         "## Prisma DB Schema",
+        "",
         "```json",
         JSON.stringify(prisma.schemas),
         "```",

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,21 @@ 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,
+        })),
+      ),
+      "```",
     ].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),
+        "```",
+      ].join("\n"),
+    },
+  ];
+}

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

@@ -0,0 +1,69 @@
+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,
+    },
+    ...transformInterfaceAssetHistories(state),
+    {
+      type: "systemMessage",
+      id: v4(),
+      created_at: new Date().toISOString(),
+      text: AutoBeSystemPromptConstant.INTERFACE_SCHEMA_REVIEW,
+    },
+    {
+      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),
+        "```",
+        "",
+        "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),
+        "```",
+        "",
+        "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

@@ -1,14 +1,20 @@
 import {
   AutoBeAssistantMessageHistory,
+  AutoBeInterfaceAuthorization,
   AutoBeInterfaceCompleteEvent,
   AutoBeInterfaceGroupsEvent,
   AutoBeInterfaceHistory,
   AutoBeOpenApi,
 } from "@autobe/interface";
+import { AutoBeEndpointComparator } from "@autobe/utils";
 import { ILlmSchema } from "@samchon/openapi";
+import { HashMap, Pair } from "tstl";
+import { v4 } from "uuid";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { IAutoBeApplicationProps } from "../../context/IAutoBeApplicationProps";
+import { predicateStateMessage } from "../../utils/predicateStateMessage";
+import { orchestrateInterfaceAuthorizations } from "./orchestrateInterfaceAuthorizations";
 import { orchestrateInterfaceComplement } from "./orchestrateInterfaceComplement";
 import { orchestrateInterfaceEndpoints } from "./orchestrateInterfaceEndpoints";
 import { orchestrateInterfaceGroups } from "./orchestrateInterfaceGroups";
@@ -20,8 +26,20 @@ export const orchestrateInterface =
   async (
     props: IAutoBeApplicationProps,
   ): Promise<AutoBeAssistantMessageHistory | AutoBeInterfaceHistory> => {
-    // ENDPOINTS
+    // PREDICATION
     const start: Date = new Date();
+    const predicate: string | null = predicateStateMessage(
+      ctx.state(),
+      "interface",
+    );
+    if (predicate !== null)
+      return ctx.assistantMessage({
+        type: "assistantMessage",
+        id: v4(),
+        created_at: start.toISOString(),
+        text: predicate,
+        completed_at: new Date().toISOString(),
+      });
     ctx.dispatch({
       type: "interfaceStart",
       created_at: start.toISOString(),
@@ -29,16 +47,43 @@ export const orchestrateInterface =
       step: ctx.state().analyze?.step ?? 0,
     });
 
-    const init: AutoBeAssistantMessageHistory | AutoBeInterfaceGroupsEvent =
+    // ENDPOINTS
+    const init: AutoBeInterfaceGroupsEvent =
       await orchestrateInterfaceGroups(ctx);
-    if (init.type === "assistantMessage") return ctx.assistantMessage(init);
-    else ctx.dispatch(init);
+    ctx.dispatch(init);
+
+    // AUTHORIZATION
+    const authorizations: AutoBeInterfaceAuthorization[] =
+      await orchestrateInterfaceAuthorizations(ctx);
+
+    const authOperations = authorizations
+      .map((authorization) => authorization.operations)
+      .flat();
 
     // ENDPOINTS & OPERATIONS
     const endpoints: AutoBeOpenApi.IEndpoint[] =
-      await orchestrateInterfaceEndpoints(ctx, init.groups);
-    const operations: AutoBeOpenApi.IOperation[] =
+      await orchestrateInterfaceEndpoints(ctx, init.groups, authOperations);
+    const firstOperations: AutoBeOpenApi.IOperation[] =
       await orchestrateInterfaceOperations(ctx, endpoints);
+    const operations: AutoBeOpenApi.IOperation[] = new HashMap<
+      AutoBeOpenApi.IEndpoint,
+      AutoBeOpenApi.IOperation
+    >(
+      [...authOperations, ...firstOperations].map(
+        (o) =>
+          new Pair(
+            {
+              path: o.path,
+              method: o.method,
+            },
+            o, // early inserted be kept
+          ),
+      ),
+      AutoBeEndpointComparator.hashCode,
+      AutoBeEndpointComparator.equals,
+    )
+      .toJSON()
+      .map((it) => it.second);
 
     // TYPE SCHEMAS
     const document: AutoBeOpenApi.IDocument = {
@@ -48,16 +93,18 @@ export const orchestrateInterface =
         schemas: await orchestrateInterfaceSchemas(ctx, operations),
       },
     };
-    document.components.schemas = await orchestrateInterfaceComplement(
-      ctx,
-      document,
+    Object.assign(
+      document.components.schemas,
+      await orchestrateInterfaceComplement(ctx, document),
     );
 
     // DO COMPILE
     return ctx.dispatch({
       type: "interfaceComplete",
       document,
-      created_at: start.toISOString(),
+      authorizations,
+      created_at: new Date().toISOString(),
+      elapsed: new Date().getTime() - start.getTime(),
       step: ctx.state().analyze?.step ?? 0,
     } satisfies AutoBeInterfaceCompleteEvent);
   };