@autobe/agent 0.30.0-dev.20260315 → 0.30.0

package/src/structures/IAutoBeVendor.ts

@@ -1,113 +1,113 @@
-import OpenAI from "openai";
-
-/**
- * Interface representing AI vendor configuration for the 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.
- *
- * 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.
- *
- * 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 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;
-
-  /**
-   * 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.
-   *
-   * 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);
-
-  /**
-   * 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;
-
-  /**
-   * 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.
-   *
-   * 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.
-   *
-   * Set to undefined to disable concurrency limiting, allowing unlimited
-   * parallel requests (use with caution based on your API limits and
-   * infrastructure capacity).
-   *
-   * @default 16
-   */
-  semaphore?: number | undefined;
-
-  /**
-   * Indicates whether this vendor/model supports explicit tool choice control.
-   *
-   * When set to `true`, the agent may pass the `tool_choice` parameter with a
-   * value of `"required"` (or other explicit values) for models that implement
-   * OpenAI-style tool calling. This allows the agent to force the model to call
-   * one of the provided tools when appropriate.
-   *
-   * When set to `false`, the agent will avoid sending `tool_choice` in a way
-   * that forces tool invocation, and will instead rely on the model's default
-   * behavior or omit tool-choice configuration entirely. This should be used
-   * for vendors or models that do not understand, partially implement, or are
-   * unstable with the `tool_choice` parameter.
-   *
-   * This flag is necessary so that a single agent implementation can work
-   * across multiple vendors and models with differing levels of tool-calling
-   * support, without causing API errors or unexpected behavior.
-   *
-   * @default true
-   */
-  useToolChoice?: boolean;
-}
+import OpenAI from "openai";
+
+/**
+ * Interface representing AI vendor configuration for the 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.
+ *
+ * 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.
+ *
+ * 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 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;
+
+  /**
+   * 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.
+   *
+   * 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);
+
+  /**
+   * 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;
+
+  /**
+   * 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.
+   *
+   * 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.
+   *
+   * Set to undefined to disable concurrency limiting, allowing unlimited
+   * parallel requests (use with caution based on your API limits and
+   * infrastructure capacity).
+   *
+   * @default 16
+   */
+  semaphore?: number | undefined;
+
+  /**
+   * Indicates whether this vendor/model supports explicit tool choice control.
+   *
+   * When set to `true`, the agent may pass the `tool_choice` parameter with a
+   * value of `"required"` (or other explicit values) for models that implement
+   * OpenAI-style tool calling. This allows the agent to force the model to call
+   * one of the provided tools when appropriate.
+   *
+   * When set to `false`, the agent will avoid sending `tool_choice` in a way
+   * that forces tool invocation, and will instead rely on the model's default
+   * behavior or omit tool-choice configuration entirely. This should be used
+   * for vendors or models that do not understand, partially implement, or are
+   * unstable with the `tool_choice` parameter.
+   *
+   * This flag is necessary so that a single agent implementation can work
+   * across multiple vendors and models with differing levels of tool-calling
+   * support, without causing API errors or unexpected behavior.
+   *
+   * @default true
+   */
+  useToolChoice?: boolean;
+}

package/src/utils/AutoBePreliminaryExhaustedError.ts

@@ -1,30 +1,30 @@
-/**
- * Custom error indicating RAG loop exhausted all retry attempts.
- *
- * Thrown by `AutoBePreliminaryController.orchestrate()` when the LLM repeatedly
- * requests more data without ever calling `complete`, exceeding
- * `AutoBeConfigConstant.RAG_LIMIT` iterations.
- *
- * Caught alongside `AutoBeTimeoutError` in orchestration pipelines to trigger
- * force-pass behavior instead of crashing the entire process.
- *
- * @author Samchon
- */
-export class AutoBePreliminaryExhaustedError extends Error {
-  public constructor(message?: string) {
-    super(
-      message ?? "Preliminary process exceeded the maximum number of retries.",
-    );
-
-    const proto = new.target.prototype;
-    if (Object.setPrototypeOf) Object.setPrototypeOf(this, proto);
-    else {
-      // biome-ignore lint: intended
-      (this as any).__proto__ = proto;
-    }
-  }
-
-  public get name(): string {
-    return this.constructor.name;
-  }
-}
+/**
+ * Custom error indicating RAG loop exhausted all retry attempts.
+ *
+ * Thrown by `AutoBePreliminaryController.orchestrate()` when the LLM repeatedly
+ * requests more data without ever calling `complete`, exceeding
+ * `AutoBeConfigConstant.RAG_LIMIT` iterations.
+ *
+ * Caught alongside `AutoBeTimeoutError` in orchestration pipelines to trigger
+ * force-pass behavior instead of crashing the entire process.
+ *
+ * @author Samchon
+ */
+export class AutoBePreliminaryExhaustedError extends Error {
+  public constructor(message?: string) {
+    super(
+      message ?? "Preliminary process exceeded the maximum number of retries.",
+    );
+
+    const proto = new.target.prototype;
+    if (Object.setPrototypeOf) Object.setPrototypeOf(this, proto);
+    else {
+      // biome-ignore lint: intended
+      (this as any).__proto__ = proto;
+    }
+  }
+
+  public get name(): string {
+    return this.constructor.name;
+  }
+}

package/src/utils/AutoBeTimeoutError.ts

@@ -1,35 +1,35 @@
-/**
- * Custom error indicating LLM conversation exceeded configured timeout limit.
- *
- * Used by `TimedConversation` to wrap conversation operations with timeout
- * enforcement. When LLM response takes too long, this error is thrown to
- * distinguish timeout failures from other error types.
- *
- * The distinction is critical for retry logic: timeout errors are NOT retried
- * (immediate failure) while other errors can be retried. This prevents wasting
- * resources on conversations that are fundamentally too slow.
- *
- * @author Samchon
- */
-export class AutoBeTimeoutError extends Error {
-  /**
-   * Creates timeout error with descriptive message.
-   *
-   * @param message Error description including timeout duration
-   */
-  public constructor(message: string) {
-    super(message);
-
-    const proto = new.target.prototype;
-    if (Object.setPrototypeOf) Object.setPrototypeOf(this, proto);
-    else {
-      // biome-ignore lint: intended
-      (this as any).__proto__ = proto;
-    }
-  }
-
-  /** Returns error class name for identification. */
-  public get name(): string {
-    return this.constructor.name;
-  }
-}
+/**
+ * Custom error indicating LLM conversation exceeded configured timeout limit.
+ *
+ * Used by `TimedConversation` to wrap conversation operations with timeout
+ * enforcement. When LLM response takes too long, this error is thrown to
+ * distinguish timeout failures from other error types.
+ *
+ * The distinction is critical for retry logic: timeout errors are NOT retried
+ * (immediate failure) while other errors can be retried. This prevents wasting
+ * resources on conversations that are fundamentally too slow.
+ *
+ * @author Samchon
+ */
+export class AutoBeTimeoutError extends Error {
+  /**
+   * Creates timeout error with descriptive message.
+   *
+   * @param message Error description including timeout duration
+   */
+  public constructor(message: string) {
+    super(message);
+
+    const proto = new.target.prototype;
+    if (Object.setPrototypeOf) Object.setPrototypeOf(this, proto);
+    else {
+      // biome-ignore lint: intended
+      (this as any).__proto__ = proto;
+    }
+  }
+
+  /** Returns error class name for identification. */
+  public get name(): string {
+    return this.constructor.name;
+  }
+}

package/src/utils/EmbeddingProvider.ts

@@ -1,4 +1,4 @@
-export interface EmbeddingProvider {
-  embed(texts: string[]): Promise<number[][]>;
-  dim?: number;
-}
+export interface EmbeddingProvider {
+  embed(texts: string[]): Promise<number[][]>;
+  dim?: number;
+}

package/src/utils/LocalEmbeddingProvider.ts

@@ -1,145 +1,145 @@
-import { TransformersEnvironment } from "@huggingface/transformers/types/env";
-import { createHash } from "node:crypto";
-import typia from "typia";
-
-import type { EmbeddingProvider } from "./EmbeddingProvider";
-
-interface TensorLike {
-  tolist?: () => unknown;
-  data?: ArrayLike<number>;
-  dims?: number[];
-  shape?: number[];
-}
-
-type FeatureExtractionPipeline = (
-  inputs: string[] | string,
-  options?: {
-    pooling?: "none" | "mean" | "max";
-    normalize?: boolean;
-  },
-) => Promise<unknown>;
-
-export class LocalEmbeddingProvider implements EmbeddingProvider {
-  public dim?: number;
-
-  private extractorPromise: Promise<FeatureExtractionPipeline>;
-  private cache = new Map<string, number[]>();
-
-  constructor(
-    private readonly options: {
-      modelIdOrPath: string;
-
-      cacheDir?: string;
-
-      quantized?: boolean;
-
-      batchSize?: number;
-
-      enableCache?: boolean;
-    },
-  ) {
-    this.extractorPromise = this.init();
-  }
-
-  async embed(texts: string[]): Promise<number[][]> {
-    if (texts.length === 0) return [];
-
-    const extractor = await this.extractorPromise;
-    const batchSize = this.options.batchSize ?? 32;
-    const useCache = this.options.enableCache ?? true;
-
-    const out: number[][] = new Array(texts.length);
-    const misses: { idx: number; text: string; key: string }[] = [];
-
-    for (let i = 0; i < texts.length; i++) {
-      const t = texts[i] ?? "";
-      const key = hashText(t);
-      const hit = useCache ? this.cache.get(key) : undefined;
-      if (hit) out[i] = hit;
-      else misses.push({ idx: i, text: t, key });
-    }
-
-    for (let i = 0; i < misses.length; i += batchSize) {
-      const chunk = misses.slice(i, i + batchSize);
-      const chunkTexts = chunk.map((c) => c.text);
-
-      const result = await extractor(chunkTexts, {
-        pooling: "mean",
-        normalize: true,
-      });
-      const vecs = toVectors(result);
-
-      if (vecs.length !== chunk.length) {
-        throw new Error(
-          `[LocalEmbeddingProvider] batch mismatch: in=${chunk.length}, out=${vecs.length}`,
-        );
-      }
-
-      if (!this.dim && vecs[0]) this.dim = vecs[0].length;
-
-      for (let j = 0; j < chunk.length; j++) {
-        const v = vecs[j]!;
-        const { idx, key } = chunk[j]!;
-        out[idx] = v;
-        if (useCache) this.cache.set(key, v);
-      }
-    }
-
-    for (let i = 0; i < out.length; i++) {
-      if (!out[i])
-        throw new Error(`[LocalEmbeddingProvider] missing vector at i=${i}`);
-    }
-
-    return out;
-  }
-
-  private async init(): Promise<FeatureExtractionPipeline> {
-    const t = await import("@huggingface/transformers");
-    const env: TransformersEnvironment = t.env;
-    if (env && this.options.cacheDir) env.cacheDir = this.options.cacheDir;
-
-    const pipeline = await t.pipeline(
-      "feature-extraction",
-      this.options.modelIdOrPath,
-      {
-        dtype: this.options.quantized === false ? "fp32" : "q8",
-      },
-    );
-
-    return pipeline as FeatureExtractionPipeline;
-  }
-}
-
-function hashText(text: string): string {
-  return createHash("sha256").update(text).digest("hex");
-}
-
-function toVectors(result: unknown): number[][] {
-  if (typia.is<number[][]>(result)) {
-    return result;
-  }
-  if (typia.is<number[]>(result)) {
-    return [result];
-  }
-
-  if (typia.is<TensorLike>(result)) {
-    if (typeof result.tolist === "function") {
-      const arr = result.tolist();
-      if (typia.is<number[][]>(arr)) return arr;
-      if (typia.is<number[]>(arr)) return [arr];
-    }
-
-    const data: number[] = Array.from(result.data ?? []);
-    const dims: number[] = Array.from(result.dims ?? result.shape ?? []);
-
-    if (dims.length === 2) {
-      const [B, D] = dims;
-      const out: number[][] = [];
-      for (let b = 0; b < B; b++) out.push(data.slice(b * D, (b + 1) * D));
-      return out;
-    }
-    if (dims.length === 1) return [data];
-  }
-
-  throw new Error("[LocalEmbeddingProvider] unsupported embedding output");
-}
+import { TransformersEnvironment } from "@huggingface/transformers/types/env";
+import { createHash } from "node:crypto";
+import typia from "typia";
+
+import type { EmbeddingProvider } from "./EmbeddingProvider";
+
+interface TensorLike {
+  tolist?: () => unknown;
+  data?: ArrayLike<number>;
+  dims?: number[];
+  shape?: number[];
+}
+
+type FeatureExtractionPipeline = (
+  inputs: string[] | string,
+  options?: {
+    pooling?: "none" | "mean" | "max";
+    normalize?: boolean;
+  },
+) => Promise<unknown>;
+
+export class LocalEmbeddingProvider implements EmbeddingProvider {
+  public dim?: number;
+
+  private extractorPromise: Promise<FeatureExtractionPipeline>;
+  private cache = new Map<string, number[]>();
+
+  constructor(
+    private readonly options: {
+      modelIdOrPath: string;
+
+      cacheDir?: string;
+
+      quantized?: boolean;
+
+      batchSize?: number;
+
+      enableCache?: boolean;
+    },
+  ) {
+    this.extractorPromise = this.init();
+  }
+
+  async embed(texts: string[]): Promise<number[][]> {
+    if (texts.length === 0) return [];
+
+    const extractor = await this.extractorPromise;
+    const batchSize = this.options.batchSize ?? 32;
+    const useCache = this.options.enableCache ?? true;
+
+    const out: number[][] = new Array(texts.length);
+    const misses: { idx: number; text: string; key: string }[] = [];
+
+    for (let i = 0; i < texts.length; i++) {
+      const t = texts[i] ?? "";
+      const key = hashText(t);
+      const hit = useCache ? this.cache.get(key) : undefined;
+      if (hit) out[i] = hit;
+      else misses.push({ idx: i, text: t, key });
+    }
+
+    for (let i = 0; i < misses.length; i += batchSize) {
+      const chunk = misses.slice(i, i + batchSize);
+      const chunkTexts = chunk.map((c) => c.text);
+
+      const result = await extractor(chunkTexts, {
+        pooling: "mean",
+        normalize: true,
+      });
+      const vecs = toVectors(result);
+
+      if (vecs.length !== chunk.length) {
+        throw new Error(
+          `[LocalEmbeddingProvider] batch mismatch: in=${chunk.length}, out=${vecs.length}`,
+        );
+      }
+
+      if (!this.dim && vecs[0]) this.dim = vecs[0].length;
+
+      for (let j = 0; j < chunk.length; j++) {
+        const v = vecs[j]!;
+        const { idx, key } = chunk[j]!;
+        out[idx] = v;
+        if (useCache) this.cache.set(key, v);
+      }
+    }
+
+    for (let i = 0; i < out.length; i++) {
+      if (!out[i])
+        throw new Error(`[LocalEmbeddingProvider] missing vector at i=${i}`);
+    }
+
+    return out;
+  }
+
+  private async init(): Promise<FeatureExtractionPipeline> {
+    const t = await import("@huggingface/transformers");
+    const env: TransformersEnvironment = t.env;
+    if (env && this.options.cacheDir) env.cacheDir = this.options.cacheDir;
+
+    const pipeline = await t.pipeline(
+      "feature-extraction",
+      this.options.modelIdOrPath,
+      {
+        dtype: this.options.quantized === false ? "fp32" : "q8",
+      },
+    );
+
+    return pipeline as FeatureExtractionPipeline;
+  }
+}
+
+function hashText(text: string): string {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+function toVectors(result: unknown): number[][] {
+  if (typia.is<number[][]>(result)) {
+    return result;
+  }
+  if (typia.is<number[]>(result)) {
+    return [result];
+  }
+
+  if (typia.is<TensorLike>(result)) {
+    if (typeof result.tolist === "function") {
+      const arr = result.tolist();
+      if (typia.is<number[][]>(arr)) return arr;
+      if (typia.is<number[]>(arr)) return [arr];
+    }
+
+    const data: number[] = Array.from(result.data ?? []);
+    const dims: number[] = Array.from(result.dims ?? result.shape ?? []);
+
+    if (dims.length === 2) {
+      const [B, D] = dims;
+      const out: number[][] = [];
+      for (let b = 0; b < B; b++) out.push(data.slice(b * D, (b + 1) * D));
+      return out;
+    }
+    if (dims.length === 1) return [data];
+  }
+
+  throw new Error("[LocalEmbeddingProvider] unsupported embedding output");
+}