@autobe/agent 0.17.1 → 0.18.0

package/src/orchestrate/analyze/orchestrateAnalyzeScenario.ts

@@ -0,0 +1,123 @@
+import {
+  AgenticaAssistantMessageHistory,
+  IAgenticaController,
+} from "@agentica/core";
+import {
+  AutoBeAnalyzeScenarioEvent,
+  AutoBeAssistantMessageHistory,
+} from "@autobe/interface";
+import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
+import { IPointer } from "tstl";
+import typia from "typia";
+import { v4 } from "uuid";
+
+import { AutoBeContext } from "../../context/AutoBeContext";
+import { assertSchemaModel } from "../../context/assertSchemaModel";
+import { transformAnalyzeSceHistories } from "./histories/transformAnalyzeScenarioHistories";
+import { IAutoBeAnalyzeScenarioApplication } from "./structures/IAutoBeAnalyzeScenarioApplication";
+
+export const orchestrateAnalyzeScenario = async <
+  Model extends ILlmSchema.Model,
+>(
+  ctx: AutoBeContext<Model>,
+): Promise<AutoBeAnalyzeScenarioEvent | AutoBeAssistantMessageHistory> => {
+  const start: Date = new Date();
+  const pointer: IPointer<IAutoBeAnalyzeScenarioApplication.IProps | null> = {
+    value: null,
+  };
+  const { histories, tokenUsage } = await ctx.conversate({
+    source: "analyzeScenario",
+    controller: createController<Model>({
+      model: ctx.model,
+      execute: new AutoBeAnalyzeScenarioApplication(),
+      preExecute: (props: IAutoBeAnalyzeScenarioApplication.IProps) =>
+        (pointer.value = props),
+    }),
+    histories: transformAnalyzeSceHistories(ctx),
+    enforceFunctionCall: false,
+    message: [
+      `Design a complete list of documents and user roles for this project.`,
+      `Define user roles that can authenticate via API and create appropriate documentation files.`,
+      `You must respect the number of documents specified by the user.`,
+      `Note that the user's locale is in ${ctx.locale}.`,
+    ].join("\n"),
+  });
+  if (histories.at(-1)?.type === "assistantMessage")
+    return {
+      ...(histories.at(-1)! as AgenticaAssistantMessageHistory),
+      created_at: start.toISOString(),
+      completed_at: new Date().toISOString(),
+      id: v4(),
+    } satisfies AutoBeAssistantMessageHistory;
+  else if (pointer.value === null) {
+    // unreachable
+    throw new Error("Failed to extract files and tables.");
+  }
+  return {
+    type: "analyzeScenario",
+    prefix: pointer.value.prefix,
+    language: pointer.value.language,
+    roles: pointer.value.roles,
+    files: pointer.value.files,
+    tokenUsage,
+    step: (ctx.state().analyze?.step ?? -1) + 1,
+    created_at: start.toISOString(),
+  };
+};
+
+class AutoBeAnalyzeScenarioApplication
+  implements 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 {
+    input;
+    return;
+  }
+}
+
+function createController<Model extends ILlmSchema.Model>(props: {
+  model: Model;
+  execute: AutoBeAnalyzeScenarioApplication;
+  preExecute: (input: IAutoBeAnalyzeScenarioApplication.IProps) => void;
+}): IAgenticaController.IClass<Model> {
+  assertSchemaModel(props.model);
+  const application: ILlmApplication<Model> = collection[
+    props.model
+  ] satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
+  return {
+    protocol: "class",
+    name: "Compose",
+    application,
+    execute: {
+      compose: (input) => {
+        props.preExecute(input);
+        return props.execute.compose(input);
+      },
+    } satisfies IAutoBeAnalyzeScenarioApplication,
+  };
+}
+
+const claude = typia.llm.application<
+  AutoBeAnalyzeScenarioApplication,
+  "claude"
+>();
+const collection = {
+  chatgpt: typia.llm.application<AutoBeAnalyzeScenarioApplication, "chatgpt">(),
+  claude,
+  llama: claude,
+  deepseek: claude,
+  "3.1": claude,
+};

package/src/orchestrate/analyze/orchestrateAnalyzeWrite.ts

@@ -1,86 +1,85 @@
-import { IAgenticaController, MicroAgentica } from "@agentica/core";
-import { AutoBeAnalyzeRole } from "@autobe/interface";
+import { IAgenticaController } from "@agentica/core";
+import {
+  AutoBeAnalyzeScenarioEvent,
+  AutoBeAnalyzeWriteEvent,
+} from "@autobe/interface";
+import { AutoBeAnalyzeFile } from "@autobe/interface/src/histories/contents/AutoBeAnalyzeFile";
 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 { enforceToolCall } from "../../utils/enforceToolCall";
-import {
-  AutoBeAnalyzeFileSystem,
-  IAutoBeAnalyzeFileSystem,
-  IFile,
-} from "./AutoBeAnalyzeFileSystem";
-import { AutoBEAnalyzeFileMap } from "./AutoBeAnalyzePointer";
-import { transformAnalyzeWriteHistories } from "./transformAnalyzeWriteHistories";
+import { transformAnalyzeWriteHistories } from "./histories/transformAnalyzeWriteHistories";
+import { IAutoBeAnalyzeWriteApplication } from "./structures/IAutoBeAnalyzeWriteApplication";
 
-export const orchestrateAnalyzeWrite = <Model extends ILlmSchema.Model>(
+export const orchestrateAnalyzeWrite = async <Model extends ILlmSchema.Model>(
   ctx: AutoBeContext<Model>,
-  input: {
-    /** Total file names */
-    totalFiles: Pick<IFile, "filename" | "reason">[];
-    targetFile: string;
-    roles: AutoBeAnalyzeRole[];
-    review: string | null;
-    setDocument: (v: AutoBEAnalyzeFileMap) => void;
+  scenario: AutoBeAnalyzeScenarioEvent,
+  file: AutoBeAnalyzeFile.Scenario,
+  progress: {
+    total: number;
+    completed: number;
   },
-): MicroAgentica<Model> => {
-  const controller = createController<Model>({
-    model: ctx.model,
-    execute: new AutoBeAnalyzeFileSystem({ [input.targetFile]: "" as const }),
-    setDocument: input.setDocument,
+): Promise<AutoBeAnalyzeWriteEvent> => {
+  const pointer: IPointer<IAutoBeAnalyzeWriteApplication.IProps | null> = {
+    value: null,
+  };
+  const { tokenUsage } = await ctx.conversate({
+    source: "analyzeWrite",
+    controller: createController<Model>({
+      model: ctx.model,
+      pointer,
+    }),
+    histories: transformAnalyzeWriteHistories(scenario, file),
+    enforceFunctionCall: true,
+    message: "Write requirement analysis report.",
   });
+  if (pointer.value === null)
+    throw new Error("The Analyze Agent failed to create the document.");
 
-  const agent = new MicroAgentica({
-    controllers: [controller],
-    model: ctx.model,
-    vendor: ctx.vendor,
-    config: {
-      ...ctx.config,
-      executor: {
-        describe: null,
-      },
+  const event: AutoBeAnalyzeWriteEvent = {
+    type: "analyzeWrite",
+    file: {
+      ...file,
+      content: pointer.value.content,
     },
-    histories: [...transformAnalyzeWriteHistories(ctx, input)],
-  });
-  enforceToolCall(agent);
-  return agent;
+    tokenUsage: tokenUsage,
+    step: (ctx.state().analyze?.step ?? -1) + 1,
+    total: progress.total,
+    completed: ++progress.completed,
+    created_at: new Date().toISOString(),
+  };
+  ctx.dispatch(event);
+  return event;
 };
 
 function createController<Model extends ILlmSchema.Model>(props: {
   model: Model;
-  execute: AutoBeAnalyzeFileSystem;
-  setDocument: (v: AutoBEAnalyzeFileMap) => void;
+  pointer: IPointer<IAutoBeAnalyzeWriteApplication.IProps | null>;
 }): IAgenticaController.IClass<Model> {
   assertSchemaModel(props.model);
   const application: ILlmApplication<Model> = collection[
     props.model
-  ] as unknown as ILlmApplication<Model>;
+  ] satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
   return {
     protocol: "class",
     name: "Planning",
     application,
     execute: {
-      createOrUpdateFiles: async (input) => {
-        const fileMap = await props.execute.createOrUpdateFiles(input);
-        props.setDocument(fileMap);
-        return fileMap;
+      write: async (input) => {
+        props.pointer.value = input;
       },
-    } satisfies IAutoBeAnalyzeFileSystem,
+    } satisfies IAutoBeAnalyzeWriteApplication,
   };
 }
 
 const claude = typia.llm.application<
-  AutoBeAnalyzeFileSystem,
-  "claude",
-  { reference: true }
+  IAutoBeAnalyzeWriteApplication,
+  "claude"
 >();
 const collection = {
-  chatgpt: typia.llm.application<
-    AutoBeAnalyzeFileSystem,
-    "chatgpt",
-    { reference: true }
-  >(),
+  chatgpt: typia.llm.application<IAutoBeAnalyzeWriteApplication, "chatgpt">(),
   claude,
   llama: claude,
   deepseek: claude,

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

@@ -0,0 +1,108 @@
+export interface IAutoBeAnalyzeReviewApplication {
+  /**
+   * Enhances planning documentation to meet all quality standards and requirements.
+   *
+   * This function receives a document and outputs an improved version directly.
+   * The output IS the enhanced document itself, NOT review comments or feedback.
+   *
+   * The enhancement process includes:
+   * - Expanding sections that are too brief
+   * - Converting vague statements to specific EARS format requirements
+   * - Fixing Mermaid diagram syntax errors
+   * - Adding missing business processes and workflows
+   * - Ensuring proper document structure and completeness
+   *
+   * CRITICAL: The function outputs the actual document content that will be saved,
+   * not a review or analysis of the document. Any text output becomes part of
+   * the final document.
+   *
+   * @param props - The properties containing the document to enhance along with
+   *   plan and review criteria for guidance
+   */
+  review(props: IAutoBeAnalyzeReviewApplication.IProps): void;
+}
+
+export namespace IAutoBeAnalyzeReviewApplication {
+  export interface IProps {
+    /**
+     * The enhancement criteria and guidelines that the agent must follow.
+     *
+     * This includes:
+     *
+     * - Minimum document length requirements
+     * - Section completeness checks
+     * - Link validation rules
+     * - Mermaid syntax validation (especially parentheses in labels)
+     * - Content specificity requirements
+     * - EARS format compliance
+     *
+     * The review criteria ensure that documentation is implementation-ready and
+     * removes all ambiguity for backend developers.
+     *
+     * Critical review points:
+     *
+     * - Mermaid diagrams MUST use double quotes for ALL labels
+     * - No spaces allowed between brackets and quotes in Mermaid
+     * - Requirements must be specific and measurable in natural language
+     * - Focus on business requirements and user scenarios
+     * - STRICTLY PROHIBITED: Reject if document contains database schemas or API
+     *   specifications
+     * - Business model and authentication requirements must be described in
+     *   natural language
+     */
+    review: string;
+
+    /**
+     * The document plan that was used to create the content.
+     *
+     * This helps the reviewer understand:
+     *
+     * - What sections should be present
+     * - The intended structure and organization
+     * - The target audience and purpose
+     * - Expected level of detail
+     *
+     * The enhancer uses this to ensure the improved content aligns with the
+     * original plan and covers all required topics comprehensively.
+     */
+    plan: string;
+
+    /**
+     * The actual markdown document content that incorporates review feedback.
+     *
+     * ⚠️ CRITICAL: This field contains a COMPLETE MARKDOWN DOCUMENT that has 
+     * already incorporated the review criteria and plan requirements. This is 
+     * NOT raw input to be reviewed - it is the FINAL, PRODUCTION-READY DOCUMENT
+     * that reflects all review feedback and is immediately usable.
+     * 
+     * This content represents:
+     * - A fully-formed markdown document (.md file)
+     * - The result of applying review criteria to the original plan
+     * - A production-ready document for immediate deployment
+     * - Complete business requirements ready for developers
+     * 
+     * The enhancer should treat this as the actual document content:
+     *
+     * - Length and completeness (minimum 2,000 characters, more for technical
+     *   docs)
+     * - All sections from the plan are fully written
+     * - No vague or abstract statements
+     * - Proper use of EARS format for requirements
+     * - Correct Mermaid diagram syntax (double quotes mandatory)
+     * - Appropriate level of detail for backend implementation
+     * - Proper document linking (descriptive text, not raw filenames)
+     *
+     * IMPORTANT: The enhancer's output IS this document, not comments about it:
+     *
+     * - If content is provided, it represents the actual document
+     * - The enhancer outputs the enhanced version AS the document itself
+     * - No meta-commentary or review feedback should be in the output
+     * - The output becomes the saved .md file directly
+     * 
+     * Example of what this field contains:
+     * "# Service Overview\n## Vision\nThe service provides..." (actual document)
+     * NOT: "This document should cover service overview..." (review comment)
+     */
+    content: string;
+  }
+}

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"),
   },
 ];