@autobe/agent 0.28.1 → 0.29.0

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

@@ -1,78 +1,156 @@
+import { IAutoBePreliminaryGetAnalysisFiles } from "../../common/structures/IAutoBePreliminaryGetAnalysisFiles";
+
 export interface IAutoBeAnalyzeReviewApplication {
   /**
-   * Enhances and finalizes planning documentation.
+   * Process document enhancement task or preliminary data requests.
    *
-   * Receives a draft document and outputs the improved version. The output is
-   * the enhanced document itself, not review comments.
+   * Enhances and finalizes planning documentation by retrieving necessary
+   * analysis files via RAG (Retrieval-Augmented Generation) and producing
+   * improved, complete markdown documents ready for production use.
    *
-   * @param props - Document content, plan, and review criteria
+   * @param props Request containing either preliminary data request or complete
+   *   task
    */
-  review(props: IAutoBeAnalyzeReviewApplication.IProps): void;
+  process(props: IAutoBeAnalyzeReviewApplication.IProps): void;
 }
 
 export namespace IAutoBeAnalyzeReviewApplication {
   export interface IProps {
     /**
-     * Step 1 (CoT: Review Phase) - Enhancement Criteria
+     * Think before you act.
      *
-     * The enhancement criteria and guidelines that the agent must follow.
+     * Before requesting preliminary data or completing your task, reflect on your
+     * current state and explain your reasoning:
      *
-     * This includes:
+     * For preliminary requests (getAnalysisFiles, getPrismaSchemas, etc.):
+     * - What critical information is missing that you don't already have?
+     * - Why do you need it specifically right now?
+     * - Be brief - state the gap, don't list everything you have.
      *
-     * - Minimum document length requirements
-     * - Section completeness checks
-     * - Link validation rules
-     * - Mermaid syntax validation (especially parentheses in labels)
-     * - Content specificity requirements
-     * - EARS format compliance
+     * For completion (complete):
+     * - What key assets did you acquire?
+     * - What did you accomplish?
+     * - Why is it sufficient to complete?
+     * - Summarize - don't enumerate every single item.
+     *
+     * This reflection helps you avoid duplicate requests and premature completion.
+     */
+    thinking: string;
+
+    /**
+     * Type discriminator for the request.
+     *
+     * Determines which action to perform: preliminary data retrieval
+     * (getAnalysisFiles) or final document enhancement (complete). When
+     * preliminary returns empty array, that type is removed from the union,
+     * physically preventing repeated calls.
+     */
+    request: IComplete | IAutoBePreliminaryGetAnalysisFiles;
+  }
+
+  /**
+   * Request to enhance and finalize planning documentation.
+   *
+   * Executes document enhancement to produce improved, complete markdown
+   * documentation following quality standards and best practices. The output
+   * is the enhanced document itself, not review comments.
+   */
+  export interface IComplete {
+    /**
+     * Type discriminator for the request.
+     *
+     * Determines which action to perform: preliminary data retrieval or actual
+     * task execution. Value "complete" indicates this is the final task
+     * execution request.
+     */
+    type: "complete";
+
+    /**
+     * Enhancement criteria and quality standards.
      *
-     * The review criteria ensure that documentation is implementation-ready and
-     * removes all ambiguity for backend developers.
+     * Comprehensive guidelines that define document quality requirements and
+     * enhancement strategies. These criteria ensure the final documentation is
+     * implementation-ready and removes all ambiguity for backend developers.
      *
-     * Critical review points:
+     * Key enhancement criteria include:
+     *
+     * - Minimum document length requirements for thoroughness
+     * - Section completeness checks ensuring all required topics are covered
+     * - Link validation rules for internal and external references
+     * - Mermaid syntax validation (especially parentheses in labels)
+     * - Content specificity requirements to avoid vague statements
+     * - EARS format compliance for requirements specification
+     * - Natural language business requirement descriptions
+     *
+     * Critical quality standards:
      *
      * - DO: Use double quotes for ALL labels in Mermaid diagrams
-     * - DO NOT: Use spaces between brackets and quotes in Mermaid
+     * - DO NOT: Use spaces between brackets and quotes in Mermaid syntax
      * - DO: Make requirements specific and measurable in natural language
      * - DO: Focus on business requirements and user scenarios
      * - DO NOT: Accept documents containing database schemas or API
      *   specifications
      * - DO: Describe business model and authentication requirements in natural
      *   language
+     * - DO: Expand brief sections with comprehensive business context
+     * - DO: Convert vague statements to EARS format with clear conditions
+     *
+     * The review criteria guide the enhancement process to ensure production-ready
+     * documentation that serves as a solid foundation for subsequent pipeline
+     * phases.
      */
     review: string;
 
     /**
-     * Step 2 (CoT: Plan Phase) - Original Document Plan
+     * Original document structure plan.
      *
-     * The document plan that was used to create the content.
+     * The document plan that was used to create the initial content draft. This
+     * planning blueprint helps the enhancement agent understand the intended
+     * structure, organization, and coverage expectations.
      *
-     * This helps the reviewer understand:
+     * Understanding from the plan:
      *
-     * - What sections should be present
-     * - The intended structure and organization
-     * - The target audience and purpose
-     * - Expected level of detail
+     * - Required sections and their purposes
+     * - Intended document structure and organization hierarchy
+     * - Target audience and documentation purpose
+     * - Expected level of detail and technical depth
+     * - Content coverage scope and boundaries
      *
-     * The enhancer uses this to ensure the improved content aligns with the
-     * original plan and covers all required topics comprehensively.
+     * The enhancer uses this plan to ensure the improved content aligns with the
+     * original architectural vision while meeting all quality standards and
+     * completeness requirements.
      */
     plan: string;
 
     /**
-     * Step 3 (CoT: Content Phase) - Document Content (INPUT → OUTPUT)
+     * Enhanced, production-ready markdown document.
+     *
+     * INPUT: The document written by Write Agent (may have quality issues)
+     * OUTPUT: The enhanced, complete markdown document ready for production use
+     *
+     * Enhancement transformation requirements:
      *
-     * INPUT: The document written by Write Agent (may have issues) OUTPUT: The
-     * enhanced, complete markdown document to be saved
+     * - Fix all Mermaid syntax errors (add quotes, fix arrows, proper formatting)
+     * - Convert vague statements to EARS format with specific conditions
+     * - Expand sections that are too brief with comprehensive business context
+     * - Add missing business processes and workflow descriptions
+     * - Ensure all sections meet minimum length requirements
+     * - Validate and correct all internal and external links
+     * - Remove any database schema or API specification details
+     * - Enhance business model descriptions with natural language clarity
+     * - Improve requirements specificity and measurability
      *
-     * Enhancement requirements:
+     * Output characteristics:
      *
-     * - Fix Mermaid syntax errors (add quotes, fix arrows)
-     * - Convert vague statements to EARS format
-     * - Expand sections that are too brief
-     * - Add missing business processes
+     * - Must be the actual enhanced document content (not review comments)
+     * - Must be valid markdown with proper formatting
+     * - Must meet all quality criteria specified in review field
+     * - Must align with the original plan structure
+     * - Must be implementation-ready for subsequent pipeline phases
      *
-     * Output must be the actual document content (not review comments).
+     * The enhanced document serves as the authoritative requirements specification
+     * that will guide all downstream generation phases (Prisma, Interface, Test,
+     * Realize).
      */
     content: string;
   }

package/src/orchestrate/common/AutoBePreliminaryController.ts

@@ -0,0 +1,161 @@
+import { IMicroAgenticaHistoryJson } from "@agentica/core";
+import { AutoBeEventSource, AutoBePreliminaryKind } from "@autobe/interface";
+import { ILlmSchema, IValidation, OpenApiTypeChecker } from "@samchon/openapi";
+import { IJsonSchemaApplication } from "typia";
+import { v7 } from "uuid";
+
+import { AutoBeConfigConstant } from "../../constants/AutoBeConfigConstant";
+import { AutoBeContext } from "../../context/AutoBeContext";
+import { AutoBeState } from "../../context/AutoBeState";
+import { transformPreliminaryHistory } from "./histories/transformPreliminaryHistory";
+import { complementPreliminaryCollection } from "./internal/complementPreliminaryCollection";
+import { createPreliminaryCollection } from "./internal/createPreliminaryCollection";
+import { validatePreliminary } from "./internal/validatePreliminary";
+import { orchestratePreliminary } from "./orchestratePreliminary";
+import { IAutoBePreliminaryRequest } from "./structures/AutoBePreliminaryRequest";
+import { IAutoBeOrchestrateResult } from "./structures/IAutoBeOrchestrateResult";
+import { IAutoBePreliminaryCollection } from "./structures/IAutoBePreliminaryCollection";
+
+export class AutoBePreliminaryController<Kind extends AutoBePreliminaryKind> {
+  // METADATA
+  private readonly source: Exclude<AutoBeEventSource, "facade" | "preliminary">;
+  private readonly source_id: string;
+  private readonly kinds: Kind[];
+  private readonly argumentTypeNames: string[];
+
+  // PRELIMINARY DATA
+  private readonly all: Pick<IAutoBePreliminaryCollection, Kind>;
+  private readonly local: Pick<IAutoBePreliminaryCollection, Kind>;
+
+  public constructor(props: AutoBePreliminaryController.IProps<Kind>) {
+    this.source = props.source;
+    this.source_id = v7();
+    this.kinds = props.kinds;
+    this.argumentTypeNames = (() => {
+      const func = props.application.functions.find(
+        (f) => f.name === "process",
+      );
+      if (func === undefined)
+        throw new Error("Unable to find 'process' function in application.");
+
+      const param = func.parameters[0]?.schema;
+      if (
+        param === undefined ||
+        OpenApiTypeChecker.isReference(param) === false
+      )
+        throw new Error(
+          "'process' function parameter is not a reference type.",
+        );
+      const schema =
+        props.application.components.schemas?.[param.$ref.split("/").pop()!];
+      if (schema === undefined || OpenApiTypeChecker.isObject(schema) === false)
+        throw new Error(
+          "'process' function parameter reference is not an object type.",
+        );
+      const request = schema.properties?.request;
+      if (
+        request === undefined ||
+        OpenApiTypeChecker.isOneOf(request) === false
+      )
+        throw new Error(
+          "'process' function parameter.request is not a oneOf type.",
+        );
+      else if (
+        request.oneOf.length === 0 ||
+        request.oneOf.every(
+          (sch) => OpenApiTypeChecker.isReference(sch) === false,
+        )
+      )
+        throw new Error(
+          "'process' function parameter.request oneOf does not contain any reference type.",
+        );
+      return request.oneOf.map((sch) => {
+        const ref = (sch as any).$ref;
+        return ref.split("/").pop()!;
+      });
+    })();
+
+    this.all = createPreliminaryCollection(props.state, props.all);
+    this.local = createPreliminaryCollection(null, props.local);
+
+    complementPreliminaryCollection({
+      kinds: props.kinds,
+      all: this.all as IAutoBePreliminaryCollection,
+      local: this.local as IAutoBePreliminaryCollection,
+    });
+  }
+
+  public validate(
+    input: IAutoBePreliminaryRequest<Kind>,
+  ): IValidation<IAutoBePreliminaryRequest<Kind>> {
+    return validatePreliminary(this, input);
+  }
+
+  public getHistories(): IMicroAgenticaHistoryJson[] {
+    return transformPreliminaryHistory(this);
+  }
+
+  public getSource(): Exclude<AutoBeEventSource, "facade" | "preliminary"> {
+    return this.source;
+  }
+
+  public getKinds(): Kind[] {
+    return this.kinds;
+  }
+
+  public getArgumentTypeNames(): string[] {
+    return this.argumentTypeNames;
+  }
+
+  public getAll(): Pick<IAutoBePreliminaryCollection, Kind> {
+    return this.all;
+  }
+
+  public getLocal(): Pick<IAutoBePreliminaryCollection, Kind> {
+    return this.local;
+  }
+
+  public async orchestrate<Model extends ILlmSchema.Model, T>(
+    ctx: AutoBeContext<Model>,
+    process: (
+      out: (
+        result: AutoBeContext.IResult<Model>,
+      ) => (value: T | null) => IAutoBeOrchestrateResult<Model, T>,
+    ) => Promise<IAutoBeOrchestrateResult<Model, T>>,
+  ): Promise<T | never> {
+    for (let i: number = 0; i < AutoBeConfigConstant.RAG_LIMIT; ++i) {
+      const result: IAutoBeOrchestrateResult<Model, T> = await process(
+        (x) => (value) => ({
+          ...x,
+          value,
+        }),
+      );
+      if (result.value !== null) return result.value;
+
+      await orchestratePreliminary(ctx, {
+        source_id: this.source_id,
+        source: this.source,
+        preliminary: this,
+        trial: i + 1,
+        histories: result.histories,
+      });
+    }
+    throw new Error(
+      "Preliminary process exceeded the maximum number of retries.",
+    );
+  }
+}
+export namespace AutoBePreliminaryController {
+  export interface IProps<Kind extends AutoBePreliminaryKind> {
+    source: Exclude<AutoBeEventSource, "facade" | "preliminary">;
+    application: IJsonSchemaApplication;
+    kinds: Kind[];
+    state: AutoBeState;
+    all?: Partial<Pick<IAutoBePreliminaryCollection, Kind>>;
+    local?: Partial<Pick<IAutoBePreliminaryCollection, Kind>>;
+  }
+  export interface IProcessResult<T> {
+    value: T | undefined;
+    histories: IMicroAgenticaHistoryJson[];
+  }
+}

package/src/orchestrate/common/histories/transformCommonCorrectCastingHistory.ts

@@ -0,0 +1,32 @@
+import { IAutoBeTypeScriptCompileResult } from "@autobe/interface";
+import { StringUtil } from "@autobe/utils";
+import { v7 } from "uuid";
+
+import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromptConstant";
+import { IAutoBeOrchestrateHistory } from "../../../structures/IAutoBeOrchestrateHistory";
+import { transformPreviousAndLatestCorrectHistory } from "./transformPreviousAndLatestCorrectHistory";
+
+export const transformCommonCorrectCastingHistory = (
+  failures: IFailure[],
+): IAutoBeOrchestrateHistory => ({
+  histories: [
+    {
+      id: v7(),
+      created_at: new Date().toISOString(),
+      type: "systemMessage",
+      text: AutoBeSystemPromptConstant.COMMON_CORRECT_CASTING,
+    },
+    ...transformPreviousAndLatestCorrectHistory(failures),
+  ],
+  userMessage: StringUtil.trim`
+    Fix the TypeScript casting problems to resolve the compilation error.
+
+    You don't need to explain me anything, but just fix or give it up
+    immediately without any hesitation, explanation, and questions.
+  `,
+});
+
+interface IFailure {
+  diagnostics: IAutoBeTypeScriptCompileResult.IDiagnostic[];
+  script: string;
+}