@autobe/agent 0.16.1 → 0.18.0

package/src/orchestrate/analyze/orchestrateAnalyze.ts

@@ -1,137 +1,89 @@
 import {
   AutoBeAnalyzeHistory,
+  AutoBeAnalyzeReviewEvent,
+  AutoBeAnalyzeScenarioEvent,
+  AutoBeAnalyzeWriteEvent,
   AutoBeAssistantMessageHistory,
 } from "@autobe/interface";
+import { AutoBeAnalyzeFile } from "@autobe/interface/src/histories/contents/AutoBeAnalyzeFile";
 import { ILlmSchema } from "@samchon/openapi";
-import { IPointer } from "tstl";
-import { v4 } from "uuid";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { IAutoBeApplicationProps } from "../../context/IAutoBeApplicationProps";
-import { orchestrateAnalyzeComposer } from "./orchestrateAnalyzeComposer";
-import { IComposeInput } from "./structures/IAutoBeAnalyzeComposerApplication";
-import { writeDocumentUntilReviewPassed } from "./writeDocumentUntilReviewPassed";
+import { IProgress } from "../internal/IProgress";
+import { orchestrateAnalyzeReview } from "./orchestrateAnalyzeReview";
+import { orchestrateAnalyzeScenario } from "./orchestrateAnalyzeScenario";
+import { orchestrateAnalyzeWrite } from "./orchestrateAnalyzeWrite";
 
-/** @todo Kakasoo */
 export const orchestrateAnalyze =
   <Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>) =>
   async (
     props: IAutoBeApplicationProps,
   ): Promise<AutoBeAssistantMessageHistory | AutoBeAnalyzeHistory> => {
-    const step: number = ctx.state().analyze?.step ?? 0;
-    const created_at: string = new Date().toISOString();
+    // Initialize analysis state
+    const step: number = (ctx.state().analyze?.step ?? -1) + 1;
+    const startTime: Date = new Date();
+
     ctx.dispatch({
       type: "analyzeStart",
       reason: props.reason,
       step,
-      created_at,
-    });
-
-    const composeInputPointer: IPointer<IComposeInput | null> = { value: null };
-    const agentica = orchestrateAnalyzeComposer(ctx, (v) => {
-      composeInputPointer.value = v;
+      created_at: startTime.toISOString(),
     });
 
-    const determined = await agentica
-      .conversate(
-        [
-          `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.`,
-        ].join("\n"),
-      )
-      .finally(() => {
-        const tokenUsage = agentica.getTokenUsage();
-        ctx.usage().record(tokenUsage, ["analyze"]);
-      });
-
-    const composeInput = composeInputPointer.value;
-    if (composeInput === null) {
-      return {
-        id: v4(),
-        text: "Failed to analyze your request. please request again.",
-        type: "assistantMessage",
-        completed_at: new Date().toISOString(),
-        created_at: new Date().toISOString(),
-      };
-    }
+    // Generate analysis scenario
+    const scenario: AutoBeAnalyzeScenarioEvent | AutoBeAssistantMessageHistory =
+      await orchestrateAnalyzeScenario(ctx);
+    if (scenario.type === "assistantMessage")
+      return ctx.assistantMessage(scenario);
+    else ctx.dispatch(scenario);
 
-    const { files: tableOfContents, prefix, roles } = composeInput;
-
-    if (tableOfContents.length === 0) {
-      const history: AutoBeAssistantMessageHistory = {
-        id: v4(),
-        type: "assistantMessage",
-        text: "The current requirements are insufficient, so file generation will be suspended. It would be better to continue the conversation.",
-        created_at,
-        completed_at: new Date().toISOString(),
-      };
-      ctx.dispatch({
-        type: "assistantMessage",
-        text: "The current requirements are insufficient, so file generation will be suspended. It would be better to continue the conversation.",
-        created_at,
-      });
-      return history;
-    }
-
-    const retryCount = 3 as const;
-    const progress = {
-      total: tableOfContents.length * retryCount,
+    // write documents
+    const writeProgress: IProgress = {
+      total: scenario.files.length,
       completed: 0,
     };
-    const pointers = await Promise.all(
-      tableOfContents.map(async ({ filename }) => {
-        return await writeDocumentUntilReviewPassed(ctx, {
-          totalFiles: tableOfContents,
-          filename,
-          roles,
-          progress,
-          retry: retryCount,
-        });
+    const fileList: AutoBeAnalyzeFile[] = await Promise.all(
+      scenario.files.map(async (file) => {
+        const event: AutoBeAnalyzeWriteEvent = await orchestrateAnalyzeWrite(
+          ctx,
+          scenario,
+          file,
+          writeProgress,
+        );
+        return event.file;
       }),
     );
 
-    const files = pointers
-      .map((pointer) => {
-        return pointer.value?.files ?? {};
-      })
-      .reduce((acc, cur) => Object.assign(acc, cur));
-
-    if (Object.keys(files).length) {
-      const history: AutoBeAnalyzeHistory = {
-        id: v4(),
-        type: "analyze",
-        reason: props.reason,
-        prefix,
-        roles: roles,
-        files: files,
-        step,
-        created_at,
-        completed_at: new Date().toISOString(),
-      };
-      ctx.state().analyze = history;
-      ctx.histories().push(history);
-      ctx.dispatch({
-        type: "analyzeComplete",
-        prefix,
-        files,
-        step,
-        created_at,
-      });
-      return history;
-    }
-
-    const history: AutoBeAssistantMessageHistory = {
-      id: v4(),
-      type: "assistantMessage",
-      text: determined.find((el) => el.type === "assistantMessage")?.text ?? "",
-      created_at,
-      completed_at: new Date().toISOString(),
+    // review documents
+    const reviewProgress: IProgress = {
+      total: fileList.length,
+      completed: 0,
     };
-    ctx.dispatch({
-      type: history.type,
-      text: history.text,
-      created_at: history.created_at,
-    });
-    return history;
+    const newFiles: AutoBeAnalyzeFile[] = await Promise.all(
+      fileList.map(async (file, i) => {
+        const event: AutoBeAnalyzeReviewEvent = await orchestrateAnalyzeReview(
+          ctx,
+          scenario,
+          fileList.filter((_, j) => j !== i), // other files
+          file,
+          reviewProgress,
+        );
+        return {
+          ...event.file,
+          content: event.content,
+        };
+      }),
+    );
+
+    // Complete the analysis
+    return ctx.dispatch({
+      type: "analyzeComplete",
+      roles: scenario.roles,
+      prefix: scenario.prefix,
+      files: newFiles,
+      step,
+      elapsed: new Date().getTime() - startTime.getTime(),
+      created_at: new Date().toISOString(),
+    }) satisfies AutoBeAnalyzeHistory;
   };

package/src/orchestrate/analyze/orchestrateAnalyzeReview.ts

@@ -0,0 +1,89 @@
+import { IAgenticaController } from "@agentica/core";
+import {
+  AutoBeAnalyzeReviewEvent,
+  AutoBeAnalyzeScenarioEvent,
+} 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 { IProgress } from "../internal/IProgress";
+import { transformAnalyzeReviewerHistories } from "./histories/transformAnalyzeReviewerHistories";
+import { IAutoBeAnalyzeReviewApplication } from "./structures/IAutoBeAnalyzeReviewApplication";
+
+export const orchestrateAnalyzeReview = async <Model extends ILlmSchema.Model>(
+  ctx: AutoBeContext<Model>,
+  scenario: AutoBeAnalyzeScenarioEvent,
+  otherFiles: AutoBeAnalyzeFile[],
+  myFile: AutoBeAnalyzeFile,
+  progress: IProgress,
+): Promise<AutoBeAnalyzeReviewEvent> => {
+  const pointer: IPointer<IAutoBeAnalyzeReviewApplication.IProps | null> = {
+    value: null,
+  };
+  const { tokenUsage } = await ctx.conversate({
+    source: "analyzeReview",
+    controller: createController({
+      model: ctx.model,
+      pointer,
+    }),
+    histories: [
+      ...transformAnalyzeReviewerHistories(scenario, otherFiles, myFile),
+    ],
+    enforceFunctionCall: true,
+    message: "Review the requirement document",
+  });
+  if (pointer.value === null)
+    throw new Error("Failed to extract review information.");
+
+  const event: AutoBeAnalyzeReviewEvent = {
+    type: "analyzeReview",
+    file: myFile,
+    plan: pointer.value.plan,
+    review: pointer.value.review,
+    content: pointer.value.content,
+    tokenUsage,
+    total: progress.total,
+    completed: ++progress.completed,
+    step: (ctx.state().analyze?.step ?? -1) + 1,
+    created_at: new Date().toISOString(),
+  };
+  ctx.dispatch(event);
+  return event;
+};
+
+function createController<Model extends ILlmSchema.Model>(props: {
+  model: Model;
+  pointer: IPointer<IAutoBeAnalyzeReviewApplication.IProps | null>;
+}): IAgenticaController.IClass<Model> {
+  assertSchemaModel(props.model);
+
+  const application: ILlmApplication<Model> = collection[
+    props.model === "chatgpt" ? "chatgpt" : "claude"
+  ] satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
+  return {
+    protocol: "class",
+    name: "Reviewer",
+    application,
+    execute: {
+      review: (input) => {
+        props.pointer.value = input;
+      },
+    } satisfies IAutoBeAnalyzeReviewApplication,
+  };
+}
+
+const claude = typia.llm.application<
+  IAutoBeAnalyzeReviewApplication,
+  "claude"
+>();
+const collection = {
+  chatgpt: typia.llm.application<IAutoBeAnalyzeReviewApplication, "chatgpt">(),
+  claude,
+  llama: claude,
+  deepseek: claude,
+  "3.1": claude,
+};

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;
+  }
+}