@autobe/agent 0.0.0 → 0.3.9

package/src/context/AutoBeContext.ts

@@ -1,15 +1,19 @@
-import { AutoBeHistory, IAutoBeCompiler } from "@autobe/interface";
-import { ILlmSchema } from "@samchon/openapi";
-
-import { IAutoBeVendor } from "../structures/IAutoBeVendor";
-import { AutoBeState } from "./AutoBeState";
-import { AutoBeTokenUsage } from "./AutoBeTokenUsage";
-
-export interface AutoBeContext<Model extends ILlmSchema.Model> {
-  model: Model;
-  vendor: IAutoBeVendor;
-  compiler: IAutoBeCompiler;
-  histories: AutoBeHistory[];
-  usage: () => AutoBeTokenUsage;
-  state: () => AutoBeState;
-}
+import { AutoBeEvent, AutoBeHistory, IAutoBeCompiler } from "@autobe/interface";
+import { ILlmSchema } from "@samchon/openapi";
+
+import { IAutoBeConfig } from "../structures/IAutoBeConfig";
+import { IAutoBeVendor } from "../structures/IAutoBeVendor";
+import { AutoBeState } from "./AutoBeState";
+import { AutoBeTokenUsage } from "./AutoBeTokenUsage";
+
+export interface AutoBeContext<Model extends ILlmSchema.Model> {
+  model: Model;
+  vendor: IAutoBeVendor;
+  config: IAutoBeConfig | undefined;
+  compiler: IAutoBeCompiler;
+  files: () => Record<string, string>;
+  histories: () => AutoBeHistory[];
+  state: () => AutoBeState;
+  usage: () => AutoBeTokenUsage;
+  dispatch: (event: AutoBeEvent) => void;
+}

package/src/context/AutoBeState.ts

@@ -1,15 +1,15 @@
-import {
-  AutoBeAnalyzeHistory,
-  AutoBeInterfaceHistory,
-  AutoBePrismaHistory,
-  AutoBeRealizeHistory,
-  AutoBeTestHistory,
-} from "@autobe/interface";
-
-export interface AutoBeState {
-  analyze: AutoBeAnalyzeHistory | null;
-  prisma: AutoBePrismaHistory | null;
-  interface: AutoBeInterfaceHistory | null;
-  test: AutoBeTestHistory | null;
-  realize: AutoBeRealizeHistory | null;
-}
+import {
+  AutoBeAnalyzeHistory,
+  AutoBeInterfaceHistory,
+  AutoBePrismaHistory,
+  AutoBeRealizeHistory,
+  AutoBeTestHistory,
+} from "@autobe/interface";
+
+export interface AutoBeState {
+  analyze: AutoBeAnalyzeHistory | null;
+  prisma: AutoBePrismaHistory | null;
+  interface: AutoBeInterfaceHistory | null;
+  test: AutoBeTestHistory | null;
+  realize: AutoBeRealizeHistory | null;
+}

package/src/context/AutoBeTokenUsage.ts

@@ -1,3 +1,3 @@
-import { AgenticaTokenUsage } from "@agentica/core";
-
-export import AutoBeTokenUsage = AgenticaTokenUsage;
+import { AgenticaTokenUsage } from "@agentica/core";
+
+export import AutoBeTokenUsage = AgenticaTokenUsage;

package/src/context/IAutoBeApplication.ts

@@ -1,72 +1,112 @@
-import { IAutoBeApplicationProps } from "./IAutoBeApplicationProps";
-import { IAutoBeApplicationResult } from "./IAutoBeApplicationResult";
-
-/**
- * Application for AutoBE function calling.
- *
- * @author Samchon
- */
-export interface IAutoBeApplication {
-  /**
-   * Run Analyze Agent.
-   *
-   * Analyze agent analyzes requirements and creates specification
-   * documents.
-   *
-   * The Analyze agent serves as the foundation of the entire development
-   * process. It not only captures initial requirements but also
-   * continuously refines understanding through iterative conversation
-   * with users. When requirements are ambiguous or incomplete, it
-   * proactively formulates targeted questions to elicit necessary
-   * information before proceeding with development.
-   *
-   * Additionally, once other agents have generated code, the Analyze
-   * agent can interpret change requests in the context of existing
-   * implementations, assessing the impact and feasibility of modifications
-   * while maintaining system integrity. This comprehensive approach
-   * ensures that all subsequent development stages work from a clear,
-   * complete, and consistent specification.
-   */
-  analyze(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
-
-  /**
-   * Run prisma agent.
-   *
-   * Prisma agent analyzes requirements specifications to generate
-   * database schemas in Prisma format.
-   *
-   * The Prisma agent references the requirements specification document
-   * created by the {@link analyze} function to craft the `prisma.schema`
-   * file. For each entity and attribute in the database schema, it
-   * provides comprehensive documentation including the rationale behind
-   * its creation, its purpose, and conceptual explanations. The agent
-   * employs normalization techniques to ensure high-quality database
-   * design.
-   *
-   * Once the DB schema file is written, the Prisma agent compiles it using
-   * the built-in Prisma compiler. If compilation errors occur, these are
-   * fed back to the AI agent, enabling a self-correction process through
-   * compiler feedback. After successful compilation, this schema file is
-   * then subjected to a quality assurance process through an internal
-   * review agent that verifies and refines the schema.
-   *
-   * Note that, never use this function without calling the
-   * {@link analyze} function at least once.
-   */
-  prisma(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
-
-  /**
-   * Run interface agent.
-   */
-  interface(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
-
-  /**
-   * Run test program agent.
-   */
-  test(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
-
-  /**
-   * Run realize agent.
-   */
-  realize(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
-}
+import { IAutoBeApplicationProps } from "./IAutoBeApplicationProps";
+import { IAutoBeApplicationResult } from "./IAutoBeApplicationResult";
+
+/**
+ * Application for AutoBE function calling.
+ *
+ * @author Samchon
+ */
+export interface IAutoBeApplication {
+  /**
+   * Run Analyze Agent.
+   *
+   * Executes the Analyze agent to process user requirements and generate a
+   * structured specification document. This agent analyzes all conversation
+   * history between users and AI, separates business logic from technical
+   * requirements, and establishes development priorities and scope.
+   *
+   * **IMPORTANT**: Only call this function when sufficient requirements have
+   * been discussed to generate a comprehensive specification. The context must
+   * contain enough detail about the system's purpose, core features, data
+   * models, and business rules. If requirements are unclear or incomplete,
+   * continue gathering information through conversation instead.
+   *
+   * The agent will automatically generate follow-up questions for any ambiguous
+   * requirements and continuously refine its understanding through iterative
+   * conversation. When executed after other agents have generated code, it can
+   * also interpret change requests in the context of existing implementations.
+   */
+  analyze(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
+
+  /**
+   * Run prisma agent.
+   *
+   * Executes the Prisma agent to generate database schema files and ERD
+   * documentation. This agent reads the requirements specification created by
+   * the {@link analyze Analyze agent} and produces a complete Prisma schema with
+   * comprehensive documentation for each entity and attribute.
+   *
+   * **PREREQUISITE**: Only call this function after the {@link analyze} function
+   * has been successfully executed and a requirements specification document
+   * has been generated. The Prisma agent depends on the structured requirements
+   * analysis to design the database schema properly. Without a completed
+   * requirements specification, this function should NOT be called.
+   *
+   * The agent will automatically validate the generated schema using the Prisma
+   * compiler, self-correct any compilation errors through feedback loops, and
+   * generate ERD documentation using prisma-markdown. An internal review
+   * process ensures schema quality and optimization.
+   */
+  prisma(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
+
+  /**
+   * Run interface agent.
+   *
+   * Executes the Interface agent to design and generate API interfaces. This
+   * agent creates OpenAPI schemas and TypeScript/NestJS code based on the
+   * requirements specification and ERD documentation from previous agents.
+   *
+   * The agent follows a sophisticated pipeline: first constructing formal
+   * OpenAPI Operation Schemas and JSON Schemas, then validating these schemas,
+   * and finally transforming them into NestJS controllers and DTOs. Each
+   * generated interface includes comprehensive JSDoc comments and undergoes
+   * internal review for consistency.
+   */
+  interface(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
+
+  /**
+   * Run test program agent.
+   *
+   * Executes the Test agent to generate comprehensive E2E test suites for all
+   * {@link interface API interfaces}. This agent synthesizes outputs from
+   * previous agents to create tests that validate both individual endpoints and
+   * their interactions.
+   *
+   * **PREREQUISITE**: Only call this function after the {@link interface}
+   * function has been successfully executed and API interfaces have been
+   * generated. The Test agent requires the completed API interface definitions,
+   * OpenAPI schemas, and TypeScript code to generate appropriate test
+   * scenarios. Without completed interface design, this function should NOT be
+   * called.
+   *
+   * The agent will analyze dependency relationships between API functions,
+   * structure integrated test scenarios with correct execution sequences, and
+   * enhance pre-generated test scaffolds with business logic validation.
+   * TypeScript compiler validation and internal review ensure test quality and
+   * optimal coverage.
+   */
+  test(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
+
+  /**
+   * Run realize agent.
+   *
+   * Executes the Realize agent to implement the actual business logic for each
+   * API endpoint. This agent synthesizes all outputs from previous agents to
+   * generate fully functional service provider code.
+   *
+   * **PREREQUISITE**: Only call this function after the {@link interface}
+   * function has been successfully executed and API interfaces have been
+   * generated. The Realize agent requires the completed API interface
+   * definitions to implement the corresponding service logic. It also benefits
+   * from having test code available for validation. Without completed interface
+   * design, this function should NOT be called.
+   *
+   * The agent will create service implementations with multiple validation
+   * layers: TypeScript compiler feedback, runtime validation through test
+   * execution, and quality optimization through internal review. The generated
+   * code handles database interactions through Prisma, implements security and
+   * validation checks, and processes business rules according to
+   * specifications.
+   */
+  realize(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
+}

package/src/context/IAutoBeApplicationProps.ts

@@ -1,6 +1,27 @@
-export interface IAutoBeApplicationProps {
-  /**
-   * The reason of the function call.
-   */
-  reason: string;
-}
+export interface IAutoBeApplicationProps {
+  /** The reason of the function call. */
+  reason: string;
+
+  /**
+   * This prompt defines how to convert a user's planning-oriented requirements into a structured message for an internal agent.
+   *
+   * All content the user provides must be included in the message. However, if some parts of the user's input are inappropriate or insufficient from a planning standpoint, you are allowed to add **supplementary remarks**—but only under strict rules.
+   *
+   * <Supplementary Remark Rules>
+   *
+   * 1. **Definition**
+   * A supplementary remark is additional information that may differ from the user's original intent. Because of this, **you must clearly indicate that it is *not* part of the user’s thinking**.
+   *
+   * 2. **When to Supplement**
+   * - If the user's input reveals a lack of technical understanding (e.g., suggesting "put all data into one table"), and the plan is not an MVP or PoC, it's encouraged to make reasonable additions for a more scalable or robust structure.
+   * - If there are clear gaps in the user's planning logic, you may supplement the content to ensure completeness.
+   *
+   * 3. **When Not to Supplement**
+   * - If the user's input is vague or ambiguous, **do not assume or add extra details**. Instead, it’s better to ask the user follow-up questions to clarify their intent.
+   * - If the user has made no comment on design, **do not impose design-related decisions** (e.g., colors, fonts, tone). However, you may state explicitly that no design requirements were provided.
+   * - Generic advice like "UX should be good" can be omitted unless it adds value, as such goals are assumed in all services.
+   *
+   * </Supplementary Remark Rules>
+   */
+  userPlanningRequirements?: string;
+}

package/src/context/IAutoBeApplicationResult.ts

@@ -1,4 +1,3 @@
-export interface IAutoBeApplicationResult {
-  success: boolean;
-  description: string;
-}
+export interface IAutoBeApplicationResult {
+  success: boolean;
+}

package/src/context/assertSchemaModel.ts

@@ -0,0 +1,17 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+export function assertSchemaModel<Model extends ILlmSchema.Model>(
+  model: Model,
+): asserts model is Exclude<Model, "gemini" | "3.0"> {
+  if (model === "gemini")
+    throw new Error(
+      [
+        "Error on AutoBeAgent.constructor(): gemini is not supported",
+        "because it does not follow standard JSON schema specification.",
+        "@autobe requires union type (`oneOf` or `anyOf`) for backend code generation,",
+        "but gemini has banned them. Please wait until when `@agentica`",
+        "supports prompt based function calling which can detour gemini's",
+        "restriction of JSON schema specification.",
+      ].join(" "),
+    );
+}

package/src/{internal/transformAgenticaHistory.ts → factory/createAgenticaHistory.ts}

@@ -1,54 +1,51 @@
-import { AgenticaOperation, MicroAgenticaHistory } from "@agentica/core";
-import {
-  AutoBeAssistantMessageHistory,
-  AutoBeHistory,
-  AutoBeUserMessageHistory,
-} from "@autobe/interface";
-import { ILlmSchema } from "@samchon/openapi";
-
-export function transformAgenticaHistory<
-  Model extends ILlmSchema.Model,
->(props: {
-  operations: readonly AgenticaOperation<Model>[];
-  history: AutoBeHistory;
-}): MicroAgenticaHistory<Model> | null {
-  if (props.history.type === "userMessage")
-    return {
-      ...props.history,
-      toJSON: () => props.history as AutoBeUserMessageHistory,
-    };
-  else if (props.history.type === "assistantMessage")
-    return {
-      ...props.history,
-      toJSON: () => props.history as AutoBeAssistantMessageHistory,
-    };
-
-  const operation: AgenticaOperation<Model> | undefined = props.operations.find(
-    (op) => op.function.name === props.history.type,
-  );
-  if (operation === undefined) return null;
-  const partial = {
-    id: props.history.id,
-    type: "execute" as const,
-    arguments: {
-      reason: props.history.reason,
-    },
-    value: {
-      success:
-        props.history.type === "analyze" || props.history.type === "interface"
-          ? true
-          : props.history.result.type === "success",
-      description: props.history.description,
-    },
-  };
-  return {
-    ...partial,
-    protocol: operation.protocol as "class",
-    operation: operation as AgenticaOperation.Class<Model>,
-    toJSON: () => ({
-      ...partial,
-      protocol: operation.protocol as "class",
-      operation: operation.toJSON(),
-    }),
-  };
-}
+import { AgenticaOperation, MicroAgenticaHistory } from "@agentica/core";
+import {
+  AutoBeAssistantMessageHistory,
+  AutoBeHistory,
+  AutoBeUserMessageHistory,
+} from "@autobe/interface";
+import { ILlmSchema } from "@samchon/openapi";
+
+export function createAgenticaHistory<Model extends ILlmSchema.Model>(props: {
+  operations: readonly AgenticaOperation<Model>[];
+  history: AutoBeHistory;
+}): MicroAgenticaHistory<Model> | null {
+  if (props.history.type === "userMessage")
+    return {
+      ...props.history,
+      toJSON: () => props.history as AutoBeUserMessageHistory,
+    };
+  else if (props.history.type === "assistantMessage")
+    return {
+      ...props.history,
+      toJSON: () => props.history as AutoBeAssistantMessageHistory,
+    };
+
+  const operation: AgenticaOperation<Model> | undefined = props.operations.find(
+    (op) => op.function.name === props.history.type,
+  );
+  if (operation === undefined) return null;
+  const partial = {
+    id: props.history.id,
+    type: "execute" as const,
+    arguments: {
+      reason: props.history.reason,
+    },
+    value: {
+      success:
+        props.history.type === "analyze" || props.history.type === "interface"
+          ? true
+          : props.history.result.type === "success",
+    },
+  };
+  return {
+    ...partial,
+    protocol: operation.protocol as "class",
+    operation: operation as AgenticaOperation.Class<Model>,
+    toJSON: () => ({
+      ...partial,
+      protocol: operation.protocol as "class",
+      operation: operation.toJSON(),
+    }),
+  };
+}

package/src/{internal → factory}/createAutoBeApplication.ts

@@ -1,47 +1,52 @@
-import { IAgenticaController } from "@agentica/core";
-import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
-import typia from "typia";
-
-import { AutoBeContext } from "../context/AutoBeContext";
-import { IAutoBeApplication } from "../context/IAutoBeApplication";
-import { orchestrateAnalyze } from "../orchestrate/orchestrateAnalyze";
-import { orchestrateInterface } from "../orchestrate/orchestrateInterface";
-import { orchestratePrisma } from "../orchestrate/orchestratePrisma";
-import { orchestrateRealize } from "../orchestrate/orchestrateRealize";
-import { orchestrateTest } from "../orchestrate/orchestrateTest";
-
-export const createAutoBeController = <Model extends ILlmSchema.Model>(props: {
-  model: Model;
-  context: AutoBeContext<Model>;
-}): IAgenticaController.IClass<Model> => {
-  const application: ILlmApplication<Model> = collection[
-    props.model
-  ] as unknown as ILlmApplication<Model>;
-  return {
-    protocol: "class",
-    name: "autobe",
-    application,
-    execute: {
-      analyze: orchestrateAnalyze(props.context),
-      prisma: orchestratePrisma(props.context),
-      interface: orchestrateInterface(props.context),
-      test: orchestrateTest(props.context),
-      realize: orchestrateRealize(props.context),
-    },
-  };
-};
-
-const claude = typia.llm.application<IAutoBeApplication, "claude">();
-const collection = {
-  chatgpt: typia.llm.application<
-    IAutoBeApplication,
-    "chatgpt",
-    { reference: true }
-  >(),
-  gemini: typia.llm.application<IAutoBeApplication, "gemini">(),
-  claude,
-  llama: claude,
-  deepseek: claude,
-  "3.1": claude,
-  "3.0": typia.llm.application<IAutoBeApplication, "3.0">(),
-};
+import { IAgenticaController } from "@agentica/core";
+import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
+import typia from "typia";
+
+import { AutoBeContext } from "../context/AutoBeContext";
+import { IAutoBeApplication } from "../context/IAutoBeApplication";
+import { assertSchemaModel } from "../context/assertSchemaModel";
+import { orchestrateInterface } from "../orchestrate/interface/orchestrateInterface";
+import { orchestrateAnalyze } from "../orchestrate/orchestrateAnalyze";
+import { orchestrateRealize } from "../orchestrate/orchestrateRealize";
+import { orchestrateTest } from "../orchestrate/orchestrateTest";
+import { orchestratePrisma } from "../orchestrate/prisma/orchestratePrisma";
+
+export const createAutoBeController = <Model extends ILlmSchema.Model>(props: {
+  model: Model;
+  context: AutoBeContext<Model>;
+}): IAgenticaController.IClass<Model> => {
+  assertSchemaModel(props.model);
+  const application: ILlmApplication<Model> = collection[
+    props.model
+  ] as unknown as ILlmApplication<Model>;
+  return {
+    protocol: "class",
+    name: "autobe",
+    application,
+    execute: {
+      analyze: orchestrateAnalyze(props.context),
+      prisma: orchestratePrisma(props.context),
+      interface: orchestrateInterface(props.context),
+      test: orchestrateTest(props.context),
+      realize: orchestrateRealize(props.context),
+    },
+  };
+};
+
+const claude = typia.llm.application<
+  IAutoBeApplication,
+  "claude",
+  { reference: true }
+>();
+const collection = {
+  chatgpt: typia.llm.application<
+    IAutoBeApplication,
+    "chatgpt",
+    { reference: true }
+  >(),
+  claude,
+  llama: claude,
+  deepseek: claude,
+  "3.1": claude,
+  "3.0": typia.llm.application<IAutoBeApplication, "3.0">(),
+};

package/src/{internal → factory}/createAutoBeState.ts

@@ -1,14 +1,14 @@
-import { AutoBeHistory } from "@autobe/interface";
-
-import { AutoBeState } from "../context/AutoBeState";
-
-export const createAutoBeState = (histories: AutoBeHistory[]): AutoBeState => {
-  const reversed = histories.slice().reverse();
-  return {
-    analyze: reversed.find((h) => h.type === "analyze") ?? null,
-    prisma: reversed.find((h) => h.type === "prisma") ?? null,
-    interface: reversed.find((h) => h.type === "interface") ?? null,
-    test: reversed.find((h) => h.type === "test") ?? null,
-    realize: reversed.find((h) => h.type === "realize") ?? null,
-  };
-};
+import { AutoBeHistory } from "@autobe/interface";
+
+import { AutoBeState } from "../context/AutoBeState";
+
+export const createAutoBeState = (histories: AutoBeHistory[]): AutoBeState => {
+  const reversed = histories.slice().reverse();
+  return {
+    analyze: reversed.find((h) => h.type === "analyze") ?? null,
+    prisma: reversed.find((h) => h.type === "prisma") ?? null,
+    interface: reversed.find((h) => h.type === "interface") ?? null,
+    test: reversed.find((h) => h.type === "test") ?? null,
+    realize: reversed.find((h) => h.type === "realize") ?? null,
+  };
+};

package/src/factory/index.ts

@@ -0,0 +1,2 @@
+export * from "./createAgenticaHistory";
+export * from "./invertOpenApiDocument";

package/src/factory/invertOpenApiDocument.ts

@@ -0,0 +1,63 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+import {
+  HttpMigration,
+  IHttpMigrateApplication,
+  OpenApi,
+  OpenApiTypeChecker,
+} from "@samchon/openapi";
+
+export function invertOpenApiDocument(
+  document: OpenApi.IDocument,
+): AutoBeOpenApi.IDocument {
+  const app: IHttpMigrateApplication = HttpMigration.application(document);
+  return {
+    operations: app.routes
+      .filter((r) => r.query === null)
+      .map(
+        (r) =>
+          ({
+            specification: empty("specification"),
+            method: r.method as "post",
+            path: r.path,
+            summary: r.operation().summary ?? empty("summary"),
+            description: r.operation().description ?? empty("description"),
+            parameters: r.parameters.map(
+              (p) =>
+                ({
+                  name: p.name,
+                  description:
+                    p.parameter().description ?? empty("description"),
+                  schema: p.schema as any,
+                }) satisfies AutoBeOpenApi.IParameter,
+            ),
+            requestBody:
+              r.body?.type === "application/json" &&
+              OpenApiTypeChecker.isReference(r.body.schema)
+                ? {
+                    description: r.body.description() ?? empty("description"),
+                    typeName: r.body.schema.$ref.split("/").pop()!,
+                  }
+                : null,
+            responseBody:
+              r.success?.type === "application/json" &&
+              OpenApiTypeChecker.isReference(r.success.schema)
+                ? {
+                    description:
+                      r.success.description() ?? empty("description"),
+                    typeName: r.success.schema.$ref.split("/").pop()!,
+                  }
+                : null,
+          }) satisfies AutoBeOpenApi.IOperation,
+      ),
+    components: {
+      schemas: (document.components?.schemas ?? {}) as Record<
+        string,
+        AutoBeOpenApi.IJsonSchemaDescriptive
+      >,
+    },
+  };
+}
+
+function empty(key: string): string {
+  return `Describe ${key} as much as possible with clear and concise words.`;
+}