@autobe/agent 0.7.3 → 0.9.0

package/src/orchestrate/test/structures/IAutoBeTestScenarioApplication.ts

@@ -0,0 +1,132 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+
+export interface IAutoBeTestScenarioApplication {
+  /**
+   * Make test scenarios for the given endpoints.
+   *
+   * @param props Properties containing the endpoints and test scenarios.
+   */
+  makeScenario(props: IAutoBeTestScenarioApplication.IProps): void;
+}
+
+export namespace IAutoBeTestScenarioApplication {
+  export interface IProps {
+    /** Array of test scenario groups. */
+    scenarioGroups: IAutoBeTestScenarioApplication.IScenarioGroup[];
+  }
+
+  export interface IScenarioGroup {
+    /** Target API endpoint to test. */
+    endpoint: AutoBeOpenApi.IEndpoint;
+
+    /** Array of test scenarios. */
+    scenarios: IScenario[];
+  }
+
+  /**
+   * Represents a test scenario for a single API operation.
+   *
+   * This interface extends `AutoBeOpenApi.IEndpoint`, inheriting its HTTP
+   * method and path information, and adds two key properties:
+   *
+   * - `draft`: A free-form, human-readable test scenario description for the API
+   *   endpoint.
+   * - `dependsOn`: A list of other API endpoints that must be invoked beforehand
+   *   in order to prepare the context for this test. Each dependency includes
+   *   the purpose of the dependency.
+   *
+   * This structure is intended to help organize test specifications for complex
+   * workflows and ensure that all prerequisites are explicitly declared.
+   */
+  export interface IScenario {
+    /**
+     * A detailed natural language description of how this API endpoint should
+     * be tested. This should include both successful and failure scenarios,
+     * business rule validations, edge cases, and any sequence of steps
+     * necessary to perform the test. A subsequent agent will use this draft to
+     * generate multiple test scenarios.
+     */
+    draft: string;
+
+    /**
+     * Descriptive function name derived from the user scenario.
+     *
+     * The function name serves as a concise, technical identifier that clearly
+     * represents the specific user scenario being described. It should be
+     * immediately understandable and directly correspond to the user situation
+     * without requiring additional context.
+     *
+     * ## Naming Convention
+     *
+     * - Must start with `test_` prefix (mandatory requirement)
+     * - Use snake_case formatting throughout
+     * - Include the primary user action (create, get, update, delete, list, etc.)
+     * - Specify the target resource (user, product, order, profile, etc.)
+     * - Add scenario-specific context (valid_data, invalid_email, not_found,
+     *   etc.)
+     *
+     * ## Content Structure
+     *
+     * Function names should follow this pattern:
+     * `test_[user_action]_[resource]_[scenario_context]`
+     *
+     * Where:
+     *
+     * - `user_action`: What the user is trying to do
+     * - `resource`: What the user is interacting with
+     * - `scenario_context`: The specific situation or condition
+     *
+     * ## User-Focused Examples
+     *
+     * - `test_create_user_profile_with_complete_information` - User providing all
+     *   available profile data
+     * - `test_retrieve_user_profile_when_profile_exists` - User accessing their
+     *   existing profile
+     * - `test_update_user_email_with_valid_new_address` - User changing their
+     *   email to a valid new one
+     * - `test_delete_user_account_when_user_lacks_permission` - User attempting
+     *   account deletion without authorization
+     * - `test_search_user_profiles_with_pagination_preferences` - User browsing
+     *   profiles with specific pagination
+     *
+     * ## Clarity Guidelines
+     *
+     * - Prioritize clarity over brevity
+     * - Avoid technical jargon or implementation terms
+     * - Use terminology that reflects user perspective
+     * - Ensure the name alone conveys the user's intent
+     * - Make it understandable to non-technical stakeholders
+     * - Keep consistent with user scenario description
+     *
+     * ## Single Endpoint Alignment
+     *
+     * Function names must reflect scenarios that:
+     *
+     * - Accomplish user goals through this single endpoint only
+     * - Don't imply dependency on other API operations
+     * - Represent complete user interactions
+     */
+    functionName: string;
+
+    /**
+     * A list of other API endpoints that must be executed before this test
+     * scenario. This helps express dependencies such as data creation or
+     * authentication steps required to reach the intended test state.
+     */
+    dependsOn: IDependsOn[];
+  }
+
+  export interface IDependsOn {
+    /** Target API endpoint that must be executed before the main operation. */
+    endpoint: AutoBeOpenApi.IEndpoint;
+
+    /**
+     * A concise exscenarioation of why this API call is required before
+     * executing the test for the main operation.
+     *
+     * Example: "Creates a category so that a product can be linked to it during
+     * creation."
+     */
+    purpose: string;
+  }
+}

package/src/orchestrate/test/transformTestCorrectHistories.ts

@@ -1,11 +1,11 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
+import { AutoBeOpenApi } from "@autobe/interface";
 import { v4 } from "uuid";
 
 import { AutoBeSystemPromptConstant } from "../../constants/AutoBeSystemPromptConstant";
 
 export const transformTestCorrectHistories = (
-  apiFiles: Record<string, string>,
-  dtoFiles: Record<string, string>,
+  document: AutoBeOpenApi.IDocument | null,
 ): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => {
@@ -33,15 +33,19 @@ export const transformTestCorrectHistories = (
         "- Keep all tests deterministic and reliable.",
         "",
         "## File References",
-        "### API Files",
-        "```typescript",
-        JSON.stringify(apiFiles, null, 2),
-        "```",
-        "",
-        "### DTO Files",
-        "```typescript",
-        JSON.stringify(dtoFiles, null, 2),
+        "### OpenAPI Like Document",
+        "```json",
+        JSON.stringify(document),
         "```",
+        // "### API Files",
+        // "```typescript",
+        // JSON.stringify(apiFiles, null, 2),
+        // "```",
+        // "",
+        // "### DTO Files",
+        // "```typescript",
+        // JSON.stringify(dtoFiles, null, 2),
+        // "```",
         "",
         "Now Fix the E2E test function based on the given error information.",
         "Only output a single `async function` named `test_api_{...}`. No explanation, no commentary.",

package/src/orchestrate/test/transformTestProgressHistories.ts

@@ -1,12 +1,15 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
+import { AutoBeTestScenarioEvent } from "@autobe/interface";
 import { v4 } from "uuid";
 
 import { AutoBeSystemPromptConstant } from "../../constants/AutoBeSystemPromptConstant";
 
-export const transformTestProgressHistories = (
-  apiFiles: Record<string, string>,
-  dtoFiles: Record<string, string>,
-): Array<
+export const transformTestProgressHistories = (props: {
+  scenario: AutoBeTestScenarioEvent.IScenario;
+  dto: Record<string, string>;
+  sdk: Record<string, string>;
+  e2e: Record<string, string>;
+}): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => {
   return [
@@ -21,30 +24,30 @@ export const transformTestProgressHistories = (
       created_at: new Date().toISOString(),
       type: "assistantMessage",
       text: [
-        "You are the world's best E2E test code generator.",
-        "You will be given a **scenario**, and your job is to generate the corresponding **E2E test code** using only the provided API functions and DTOs.",
+        "Here is the list of input material composition.",
         "",
-        "## Rules",
-        "- Follow the base E2E test style strictly. Never use other frameworks like Jest or Mocha.",
-        "- Use `TestValidator.equals(...)` and `typia.assert(...)` to verify results.",
-        "- Use `HubApi.functional.XXX` for all API calls. These are defined in API Files.",
-        "- Use helper functions like `generate_random_xxx(...)` **only if** they already exist in the base test imports.",
-        "- Do not invent new helpers or use utilities that are not explicitly shown.",
-        "- Keep all tests deterministic and reliable.",
+        "Make e2e test functions based on the following information.",
         "",
-        "## File References",
-        "### API Files",
-        "```typescript",
-        JSON.stringify(apiFiles, null, 2),
+        "## Secnario Plan",
+        "```json",
+        JSON.stringify(props.scenario),
         "```",
         "",
-        "### DTO Files",
-        "```typescript",
-        JSON.stringify(dtoFiles, null, 2),
+        "## DTO Definitions",
+        "```json",
+        JSON.stringify(props.dto),
+        "```",
+        "",
+        "## API (SDK) Functions",
+        "```json",
+        JSON.stringify(props.sdk),
+        "```",
+        "",
+        "## E2E Mockup Functions",
+        "```json",
+        JSON.stringify(props.e2e),
         "```",
         "",
-        "Now generate the E2E test function based on the given scenario.",
-        "Only output a single `async function` named `test_api_{...}`. No explanation, no commentary.",
       ].join("\n"),
     },
   ];

package/src/orchestrate/test/transformTestScenarioHistories.ts

@@ -1,5 +1,4 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
-import { AutoBeOpenApi } from "@autobe/interface";
 import { v4 } from "uuid";
 
 import { AutoBeSystemPromptConstant } from "../../constants/AutoBeSystemPromptConstant";
@@ -7,8 +6,6 @@ import { AutoBeState } from "../../context/AutoBeState";
 
 export const transformTestScenarioHistories = (
   state: AutoBeState,
-  endponits: AutoBeOpenApi.IEndpoint[],
-  files: Record<string, string>,
 ): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => {
@@ -87,47 +84,6 @@ export const transformTestScenarioHistories = (
       type: "systemMessage",
       text: AutoBeSystemPromptConstant.TEST,
     },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: [
-        "# Result of Analyze Agent",
-        "- The following document contains the user requirements that were extracted through conversations with the user by the Analyze Agent.",
-        "- The database schema was designed based on these requirements, so you may refer to this document when writing test code or reviewing the schema.",
-        "",
-        `## User Request`,
-        "",
-        `- ${state.analyze.reason}`,
-        "",
-        `## Requirement Analysis Report`,
-        "",
-        "```json",
-        JSON.stringify(state.analyze.files),
-        "```",
-      ].join("\n"),
-    },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: [
-        "# Result of Prisma Agent",
-        "- Given the following database schema and entity-relationship diagram, write appropriate test code to validate the constraints and relationships defined in the schema. For example, if there is a unique column, include a test that ensures its uniqueness.",
-        "- The test code should strictly adhere to the schema and relationships—no violations of constraints should occur.",
-        "- Use the information from the schema and diagram to design meaningful and accurate test cases.",
-        "",
-        "## Prisma DB Schema",
-        "```json",
-        JSON.stringify(state.prisma.schemas),
-        "```",
-        "",
-        "## Entity Relationship Diagrams",
-        "```json",
-        JSON.stringify(state.prisma.compiled.diagrams),
-        "```",
-      ].join("\n"),
-    },
     {
       id: v4(),
       created_at: new Date().toISOString(),
@@ -145,40 +101,5 @@ export const transformTestScenarioHistories = (
         "```",
       ].join("\n"),
     },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: AutoBeSystemPromptConstant.TEST,
-    },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: [
-        `This is a description of different APIs.`,
-        `Different APIs may have to be called to create one.`,
-        `Check which functions have been developed.`,
-        "```json",
-        JSON.stringify(endponits, null, 2),
-        "```",
-      ].join("\n"),
-    },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: [
-        "Below is basically the generated test code,",
-        "which is a test to verify that the API is simply called and successful.",
-        "Since there is already an automatically generated API,",
-        "when a user requests to create a test scenario, two or more APIs must be combined,",
-        "but a test in which the currently given endpoint is the main must be created.",
-        '"Input Test Files" should be selected from the list of files here.',
-        "```json",
-        JSON.stringify(files, null, 2),
-        "```",
-      ].join("\n"),
-    },
   ];
 };

package/src/structures/IAutoBeConfig.ts

@@ -1,25 +1,63 @@
+/**
+ * Interface defining behavioral configuration for AutoBeAgent localization and
+ * context.
+ *
+ * This interface customizes the agent's communication style, language
+ * preferences, and geographical context to provide personalized vibe coding
+ * experiences. The configuration enables culturally appropriate interactions
+ * and regionally aware development decisions throughout the automated
+ * development pipeline.
+ *
+ * Locale and timezone settings influence not only the language of communication
+ * but also contextual understanding of regulatory requirements, business
+ * practices, and temporal considerations that may affect requirements analysis,
+ * database design, API specifications, and implementation approaches.
+ *
+ * @author Samchon
+ */
 export interface IAutoBeConfig {
   /**
-   * Locale of the A.I. chatbot.
+   * Language and cultural locale preference for AI agent communication.
    *
-   * If you configure this property, the A.I. chatbot will conversate with the
-   * given locale. You can get the locale value by
+   * Configures the language and cultural context for all AI assistant responses
+   * throughout the vibe coding process. When specified, the agent will
+   * communicate in the preferred language while respecting cultural conventions
+   * and linguistic nuances during requirements gathering, progress updates, and
+   * guidance provision.
+   *
+   * The locale setting also influences the agent's understanding of regional
+   * business practices, regulatory considerations, and cultural expectations
+   * that may impact software design decisions and implementation approaches.
+   *
+   * Common formats follow BCP 47 language tags such as "en-US", "ko-KR",
+   * "ja-JP", "zh-CN", "de-DE", etc. Platform-specific detection methods:
    *
    * - Browser: `navigator.language`
-   * - NodeJS: `process.env.LANG.split(".")[0]`
+   * - Node.js: `process.env.LANG.split(".")[0]`
    *
-   * @default your_locale
+   * @default System locale or "en" if unavailable
    */
   locale?: string;
 
   /**
-   * Timezone of the A.I. chatbot.
+   * Geographic timezone for temporal context and time-sensitive operations.
+   *
+   * Provides timezone awareness for proper handling of time-related
+   * considerations during the vibe coding process. This includes scheduling
+   * references, temporal business logic requirements, timestamp handling in
+   * generated code, and time-based communications that need to be
+   * contextualized for the user's local time.
+   *
+   * Timezone awareness ensures that generated applications properly handle time
+   * zones, that scheduling-related requirements are interpreted correctly, and
+   * that temporal references in documentation and code comments reflect the
+   * user's geographical context.
    *
-   * If you configure this property, the A.I. chatbot will consider the given
-   * timezone. You can get the timezone value by
-   * `Intl.DateTimeFormat().resolvedOptions().timeZone`.
+   * Format follows IANA Time Zone Database identifiers such as
+   * "America/New_York", "Asia/Seoul", "Europe/London", "Pacific/Auckland", etc.
+   * Platform detection: `Intl.DateTimeFormat().resolvedOptions().timeZone`
    *
-   * @default your_timezone
+   * @default System timezone or "UTC" if unavailable
    */
   timezone?: string;
 }

package/src/structures/IAutoBeProps.ts

@@ -4,10 +4,101 @@ import { ILlmSchema } from "@samchon/openapi";
 import { IAutoBeConfig } from "./IAutoBeConfig";
 import { IAutoBeVendor } from "./IAutoBeVendor";
 
+/**
+ * Configuration properties for initializing an AutoBeAgent instance.
+ *
+ * This interface defines all the essential parameters required to create and
+ * configure an AutoBeAgent for vibe coding operations. The properties establish
+ * the AI model capabilities, vendor connectivity, compilation infrastructure,
+ * behavioral context, and optional session continuity through conversation
+ * histories.
+ *
+ * The configuration enables type-safe AI function calling through
+ * model-specific schema generation, ensures compatibility with various AI
+ * service providers, and provides the compilation tools necessary for the
+ * sophisticated AST-based development pipeline that transforms conversations
+ * into working software.
+ *
+ * @author Samchon
+ */
 export interface IAutoBeProps<Model extends ILlmSchema.Model> {
+  /**
+   * AI model type specification for type-safe function calling schema
+   * generation.
+   *
+   * Determines the specific AI model schema used for generating function
+   * calling interfaces through
+   * [`typia.llm.application()`](https://typia.io/docs/llm/application). This
+   * type parameter ensures compile-time type safety and enables model-specific
+   * optimizations in the AI function calling interface generation process.
+   *
+   * Common values include "chatgpt" for OpenAI models, "claude" for Anthropic
+   * models, "deepseek" for DeepSeek models, and "llama" for Meta Llama models.
+   * The choice affects function calling capabilities, parameter limitations,
+   * and schema requirements throughout the vibe coding pipeline.
+   *
+   * Note that Google Gemini ("gemini") is not supported due to its lack of
+   * reference types and union types support required for OpenAPI document
+   * composition in the vibe coding process.
+   */
   model: Model;
+
+  /**
+   * AI vendor configuration for service provider integration.
+   *
+   * Defines the complete AI service connection including the OpenAI SDK
+   * instance, model identifier, request options, and concurrency controls. This
+   * configuration enables the AutoBeAgent to connect with various AI providers
+   * while maintaining consistent functionality across the entire automated
+   * development workflow.
+   *
+   * The vendor settings determine the AI capabilities available for
+   * requirements analysis, database design, API specification, testing, and
+   * implementation phases of the vibe coding process.
+   */
   vendor: IAutoBeVendor;
+
+  /**
+   * Compilation infrastructure for TypeScript, Prisma, and OpenAPI operations.
+   *
+   * Provides the essential compilation tools required for the sophisticated
+   * AST-based development pipeline. The compiler handles validation,
+   * transformation, and code generation across all development phases including
+   * Prisma schema compilation, OpenAPI document validation, and TypeScript code
+   * compilation.
+   *
+   * For high-performance scenarios with multiple concurrent users, the compiler
+   * can be separated into dedicated worker processes to prevent blocking the
+   * main agent during computationally intensive compilation operations.
+   */
   compiler: IAutoBeCompiler;
+
+  /**
+   * Optional conversation and development histories for session continuation.
+   *
+   * Enables resuming previous vibe coding sessions by providing the
+   * chronological record of past conversations, development activities, and
+   * generated artifacts. When provided, the agent reconstructs its internal
+   * state from these histories, allowing seamless continuation of development
+   * work.
+   *
+   * This capability supports iterative development workflows where users can
+   * return to modify, enhance, or extend previously generated applications
+   * while maintaining full context of earlier decisions and implementations.
+   */
   histories?: AutoBeHistory[] | undefined;
+
+  /**
+   * Optional behavioral configuration for localization and context.
+   *
+   * Customizes the agent's communication style, language preferences, and
+   * geographical context to provide personalized vibe coding experiences.
+   * Configuration includes locale settings for internationalized responses and
+   * timezone information for temporal context awareness.
+   *
+   * These settings influence how the agent communicates with users, interprets
+   * regional requirements (such as regulatory considerations), and handles
+   * time-sensitive operations throughout the development process.
+   */
   config?: IAutoBeConfig | undefined;
 }

package/src/structures/IAutoBeVendor.ts

@@ -1,47 +1,89 @@
 import OpenAI from "openai";
 
 /**
- * LLM service vendor for Agentica Chat.
+ * Interface representing AI vendor configuration for the AutoBeAgent.
  *
- * `IAgenticaVendor` is a type represents an LLM (Large Language Model) vendor
- * of the {@link AutoBeAgent}.
+ * Defines the connection parameters and settings required to integrate with AI
+ * service providers that power the vibe coding pipeline. While utilizing the
+ * OpenAI SDK as the connection interface, this configuration supports various
+ * LLM vendors beyond OpenAI through flexible endpoint and authentication
+ * configuration, enabling integration with Claude, DeepSeek, Meta Llama, and
+ * other providers that follow OpenAI-compatible API patterns.
  *
- * Currently, {@link AutoBeAgent} supports OpenAI SDK. However, it does not mean
- * that you can use only OpenAI's GPT model in the {@link AutoBeAgent}. The
- * OpenAI SDK is just a connection tool to the LLM vendor's API, and you can use
- * other LLM vendors by configuring its `baseURL` and API key.
+ * The vendor configuration determines the AI capabilities available throughout
+ * the entire automated development workflow, from requirements analysis and
+ * database design through API specification, testing, and final implementation.
+ * Different vendors may offer varying performance characteristics, cost
+ * structures, and feature support that can be optimized for specific vibe
+ * coding needs.
  *
- * Therefore, if you want to use another LLM vendor like Claude or Gemini,
- * please configure the `baseURL` to the {@link api}, and set
- * {@link IAutoBeProps.model schema model} as "cluade" or "gemini".
+ * Concurrent request management is built-in to prevent API rate limiting and
+ * optimize resource utilization across multiple development phases and parallel
+ * operations within the vibe coding pipeline.
  *
  * @author Samchon
  */
 export interface IAutoBeVendor {
-  /** OpenAI API instance. */
+  /**
+   * OpenAI SDK instance configured for the target AI vendor.
+   *
+   * Provides the API connection interface used by the AutoBeAgent to
+   * communicate with AI services. While this uses the OpenAI SDK, it can be
+   * configured to connect with various LLM providers by setting the appropriate
+   * `baseURL` and authentication credentials. The SDK serves as a universal
+   * connector that abstracts the underlying API communication protocols.
+   *
+   * For non-OpenAI vendors, configure the SDK with the vendor's API endpoint
+   * and authentication requirements to enable seamless integration with the
+   * vibe coding system.
+   */
   api: OpenAI;
 
   /**
-   * Chat model to be used.
+   * Specific model identifier to use for AI operations.
+   *
+   * Specifies the exact model name or identifier that should be used for vibe
+   * coding tasks. Supports both official OpenAI chat models and custom model
+   * identifiers for third-party hosting services, cloud providers, or
+   * alternative LLM vendors. The model choice significantly impacts the
+   * quality, performance, and cost of the automated development process.
    *
-   * `({}) & string` means to support third party hosting cloud(eg. openRouter,
-   * aws)
+   * Examples include "gpt-4", "gpt-3.5-turbo" for OpenAI, or vendor-specific
+   * identifiers like "claude-3-sonnet", "deepseek-chat-v3", "llama3.3-70b" when
+   * using alternative providers through compatible APIs.
    */
   model: OpenAI.ChatModel | ({} & string);
 
-  /** Options for the request. */
+  /**
+   * Optional request configuration for API calls.
+   *
+   * Additional request options that will be applied to all API calls made
+   * through the OpenAI SDK. This can include custom headers, timeouts, retry
+   * policies, or other HTTP client configuration that may be required for
+   * specific vendor integrations or enterprise environments.
+   *
+   * These options provide fine-grained control over the API communication
+   * behavior and can be used to optimize performance or meet specific
+   * infrastructure requirements.
+   */
   options?: OpenAI.RequestOptions | undefined;
 
   /**
-   * Number of concurrent requests allowed.
+   * Maximum number of concurrent API requests allowed.
+   *
+   * Controls the concurrency level for AI API calls to prevent rate limiting,
+   * manage resource consumption, and optimize system performance. The vibe
+   * coding pipeline may make multiple parallel requests during development
+   * phases, and this setting ensures controlled resource utilization.
    *
-   * If you configure this property, {@link AutoBeAgent} will constrain the
-   * number of concurrent requests to the LLM vendor. If you want to share the
-   * semaphore instance with other agents, you can directly assign the
-   * {@link Semaphore} instance to this property.
+   * A reasonable default provides balanced performance while respecting typical
+   * API rate limits. Lower values reduce resource consumption but may slow
+   * development progress, while higher values can improve performance but risk
+   * hitting rate limits or overwhelming the AI service.
    *
-   * Otherwise, it will not limit the number of concurrent requests, and the
-   * {@link AutoBeAgent} will send requests asynchronously without any limit.
+   * Set to undefined to disable concurrency limiting, allowing unlimited
+   * parallel requests (use with caution based on your API limits and
+   * infrastructure capacity).
    *
    * @default 16
    */