@autobe/agent 0.9.2 → 0.10.0

package/src/orchestrate/realize/orchestrateRealize.ts

@@ -0,0 +1,169 @@
+import {
+  AutoBeAssistantMessageHistory,
+  AutoBeRealizeHistory,
+} from "@autobe/interface";
+import { ILlmSchema } from "@samchon/openapi";
+import { v4 } from "uuid";
+
+import { AutoBeContext } from "../../context/AutoBeContext";
+import { IAutoBeApplicationProps } from "../../context/IAutoBeApplicationProps";
+import { orchestrateRealizeCoder } from "./orchestrateRealizeCoder";
+import { orchestrateRealizeIntegrator } from "./orchestrateRealizeIntegrator";
+import { orchestrateRealizePlanner } from "./orchestrateRealizePlanner";
+import {
+  RealizeValidatorOutput,
+  orchestrateRealizeValidator,
+} from "./orchestrateRealizeValidator";
+import { IAutoBeRealizeCoderApplication } from "./structures/IAutoBeRealizeCoderApplication";
+
+export const orchestrateRealize =
+  <Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>) =>
+  async (
+    props: IAutoBeApplicationProps,
+  ): Promise<AutoBeAssistantMessageHistory | AutoBeRealizeHistory> => {
+    props;
+
+    const ops = ctx.state().interface?.document.operations;
+    if (!ops) {
+      throw new Error();
+    }
+
+    const codes: (
+      | IAutoBeRealizeCoderApplication.RealizeCoderOutput
+      | FAILED
+    )[] = await Promise.all(
+      ops.map(async (op) =>
+        pipe(
+          op,
+          (op) => orchestrateRealizePlanner(ctx, op),
+          (p) => orchestrateRealizeCoder(ctx, op, p),
+        ),
+      ),
+    );
+
+    const vaildates: (RealizeValidatorOutput | FAILED)[] = await Promise.all(
+      codes
+        .filter((el) => el !== FAILED)
+        .map(async (c) =>
+          pipe(
+            c,
+            (c) => orchestrateRealizeIntegrator(ctx, c),
+            (i) => orchestrateRealizeValidator(ctx, i),
+          ),
+        ),
+    );
+
+    if (vaildates.length) {
+      if (vaildates.every((v) => v !== FAILED)) {
+        const files = {
+          ...ctx.state().interface?.files,
+          ...vaildates
+            .map((v) => ({ [v.location]: v.content }))
+            .reduce((acc, cur) => Object.assign(acc, cur), {}),
+        };
+
+        const compiled = await ctx.compiler.typescript.compile({ files });
+
+        const now = new Date().toISOString();
+        ctx.dispatch({
+          type: "realizeComplete",
+          compiled: compiled,
+          created_at: now,
+          files: files,
+          step: ctx.state().analyze?.step ?? 0,
+        });
+
+        return {
+          id: v4(),
+          type: "realize",
+          completed_at: now,
+          created_at: now,
+          compiled,
+          files,
+          reason: props.reason,
+          step: ctx.state().analyze?.step ?? 0,
+        } satisfies AutoBeRealizeHistory;
+      } else {
+        const total = codes.length;
+        const failedCount = codes.filter((code) => code === FAILED).length;
+        const successCount = total - failedCount;
+
+        const now = new Date().toISOString();
+        ctx.dispatch({
+          type: "assistantMessage",
+          text: [
+            `Out of ${total} code blocks, ${successCount} succeeded, but ${failedCount} failed.`,
+            `The process has been stopped due to the failure. Please review the failed steps and try again.`,
+          ].join("\n"),
+          created_at: now,
+        });
+
+        return {
+          id: v4(),
+          type: "assistantMessage",
+          completed_at: now,
+          created_at: now,
+          text: [
+            `Out of ${total} code blocks, ${successCount} succeeded, but ${failedCount} failed.`,
+            `The process has been stopped due to the failure. Please review the failed steps and try again.`,
+          ].join("\n"),
+        } satisfies AutoBeAssistantMessageHistory;
+      }
+    }
+
+    const now = new Date().toISOString();
+    ctx.dispatch({
+      type: "assistantMessage",
+      text: "Any codes can not be generated.",
+      created_at: now,
+    });
+
+    return {
+      id: v4(),
+      type: "assistantMessage",
+      completed_at: now,
+      created_at: now,
+      text: "Any codes can not be generated.",
+    } satisfies AutoBeAssistantMessageHistory;
+  };
+
+export const FAILED = Symbol("FAILED");
+export type FAILED = typeof FAILED;
+
+export function pipe<A, B>(
+  a: A,
+  ab: (a: A) => Promise<B | FAILED>,
+): Promise<B | FAILED>;
+
+export function pipe<A, B, C>(
+  a: A,
+  ab: (a: A) => Promise<B | FAILED>,
+  bc: (b: B) => Promise<C | FAILED>,
+): Promise<C | FAILED>;
+
+export function pipe<A, B, C, D>(
+  a: A,
+  ab: (a: A) => Promise<B | FAILED>,
+  bc: (b: B) => Promise<C | FAILED>,
+  cd: (c: C) => Promise<D | FAILED>,
+): Promise<D | FAILED>;
+
+export function pipe<A, B, C, D, E>(
+  a: A,
+  ab: (a: A) => Promise<B | FAILED>,
+  bc: (b: B) => Promise<C | FAILED>,
+  cd: (c: C) => Promise<D | FAILED>,
+  de: (d: D) => Promise<E | FAILED>,
+): Promise<E | FAILED>;
+
+export function pipe(
+  a: any,
+  ...fns: Array<(arg: any) => Promise<any>>
+): Promise<any> {
+  return fns.reduce((prev, fn) => {
+    return prev.then((result) => {
+      if (result === FAILED) return FAILED;
+      return fn(result);
+    });
+  }, Promise.resolve(a));
+}

package/src/orchestrate/realize/orchestrateRealizeCoder.ts

@@ -0,0 +1,156 @@
+import { IAgenticaController, MicroAgentica } from "@agentica/core";
+import { AutoBeOpenApi } from "@autobe/interface";
+import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
+import sortImport from "@trivago/prettier-plugin-sort-imports";
+import { format } from "prettier";
+import { IPointer } from "tstl";
+import typia from "typia";
+
+import { AutoBeContext } from "../../context/AutoBeContext";
+import { assertSchemaModel } from "../../context/assertSchemaModel";
+import { enforceToolCall } from "../../utils/enforceToolCall";
+import { getTestScenarioArtifacts } from "../test/compile/getTestScenarioArtifacts";
+import { IAutoBeTestScenarioArtifacts } from "../test/structures/IAutoBeTestScenarioArtifacts";
+import { FAILED } from "./orchestrateRealize";
+import { RealizePlannerOutput } from "./orchestrateRealizePlanner";
+import { IAutoBeRealizeCoderApplication } from "./structures/IAutoBeRealizeCoderApplication";
+import { transformRealizeCoderHistories } from "./transformRealizeCoderHistories";
+
+/**
+ * Generates a TypeScript function implementation based on the given plan.
+ *
+ * This function transforms the plan (function name, input/output schema,
+ * constraints, and scenarios) into a complete TypeScript function as a string.
+ * It is responsible only for producing the code logic, and does not handle
+ * imports, exports, or formatting.
+ *
+ * Import statements are handled separately and will be injected automatically.
+ * Any unused imports will be removed by tooling (e.g. eslint).
+ *
+ * Type annotations should be omitted whenever possible to favor TypeScript's
+ * type inference, unless explicit types are critical to correctness.
+ *
+ * @param ctx - AutoBE execution context
+ * @param props - Planning result describing what function to generate
+ * @returns The generated function name and TypeScript code
+ */
+export const orchestrateRealizeCoder = async <Model extends ILlmSchema.Model>(
+  ctx: AutoBeContext<Model>,
+  operation: AutoBeOpenApi.IOperation,
+  props: RealizePlannerOutput,
+): Promise<IAutoBeRealizeCoderApplication.RealizeCoderOutput | FAILED> => {
+  const artifacts: IAutoBeTestScenarioArtifacts =
+    await getTestScenarioArtifacts(ctx, {
+      endpoint: {
+        method: operation.method,
+        path: operation.path,
+      },
+      dependencies: [],
+    });
+
+  const pointer: IPointer<Pick<
+    IAutoBeRealizeCoderApplication.RealizeCoderOutput,
+    "implementationCode"
+  > | null> = {
+    value: null,
+  };
+
+  const controller = createApplication({
+    model: ctx.model,
+    build: (props) => {
+      pointer.value = props.result;
+    },
+  });
+
+  const agent = new MicroAgentica({
+    controllers: [controller],
+    model: ctx.model,
+    vendor: ctx.vendor,
+    config: {
+      ...ctx.config,
+      executor: {
+        describe: null,
+      },
+    },
+    histories: transformRealizeCoderHistories(ctx.state(), props, artifacts),
+  });
+  enforceToolCall(agent);
+
+  await agent.conversate("Write code.");
+  const tokenUsage = agent.getTokenUsage();
+  ctx.usage().record(tokenUsage, ["realize"]);
+
+  if (pointer.value === null) {
+    return FAILED;
+  }
+
+  pointer.value.implementationCode = await format(
+    pointer.value.implementationCode,
+    {
+      parser: "typescript",
+      plugins: [sortImport, await import("prettier-plugin-jsdoc")],
+      importOrder: ["<THIRD_PARTY_MODULES>", "^[./]"],
+      importOrderSeparation: true,
+      importOrderSortSpecifiers: true,
+      importOrderParserPlugins: ["decorators-legacy", "typescript", "jsx"],
+    },
+  );
+
+  pointer.value.implementationCode = pointer.value.implementationCode
+    .replaceAll('import { MyGlobal } from "../MyGlobal";', "")
+    .replaceAll('import typia, { tags } from "typia";', "")
+    .replaceAll('import { Prisma } from "@prisma/client";', "")
+    .replaceAll('import { jwtDecode } from "./jwtDecode"', "");
+
+  pointer.value.implementationCode = [
+    'import { MyGlobal } from "../MyGlobal";',
+    'import typia, { tags } from "typia";',
+    'import { Prisma } from "@prisma/client";',
+    'import { jwtDecode } from "./jwtDecode"',
+    "",
+    pointer.value.implementationCode,
+  ].join("\n");
+
+  return { ...pointer.value, functionName: props.functionName };
+};
+
+function createApplication<Model extends ILlmSchema.Model>(props: {
+  model: Model;
+  build: (next: IAutoBeRealizeCoderApplication.IProps) => void;
+}): IAgenticaController.IClass<Model> {
+  assertSchemaModel(props.model);
+
+  const application: ILlmApplication<Model> = collection[
+    props.model
+  ] as unknown as ILlmApplication<Model>;
+
+  return {
+    protocol: "class",
+    name: "Write code",
+    application,
+    execute: {
+      programing: (next) => {
+        props.build(next);
+      },
+    } satisfies IAutoBeRealizeCoderApplication,
+  };
+}
+
+const claude = typia.llm.application<
+  IAutoBeRealizeCoderApplication,
+  "claude",
+  {
+    reference: true;
+  }
+>();
+const collection = {
+  chatgpt: typia.llm.application<
+    IAutoBeRealizeCoderApplication,
+    "chatgpt",
+    { reference: true }
+  >(),
+  claude,
+  llama: claude,
+  deepseek: claude,
+  "3.1": claude,
+};

package/src/orchestrate/realize/orchestrateRealizeIntegrator.ts

@@ -0,0 +1,75 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { AutoBeContext } from "../../context/AutoBeContext";
+import { IAutoBeRealizeCoderApplication } from "./structures/IAutoBeRealizeCoderApplication";
+
+/**
+ * The result of integrating the generated code into the actual application
+ * files (e.g., controller).
+ */
+export interface RealizeIntegratorOutput {
+  /**
+   * Indicates the result of the integration process.
+   *
+   * - "success": The function was correctly inserted, imported, and passed
+   *   compilation.
+   * - "fail": The integration did not complete (e.g., target controller not
+   *   found, syntax error).
+   * - "exception": An unexpected error occurred (e.g., I/O failure, invalid
+   *   context state).
+   */
+  result: "success" | "fail" | "exception";
+}
+
+/**
+ * Integrates the generated function into an appropriate controller file,
+ * handling insertion, import, and static validation.
+ *
+ * This function performs the following steps:
+ *
+ * 1. **Locate appropriate controller file**
+ *
+ *    - Usually matches `*.controller.ts`
+ *    - May be based on inferred target (e.g., from functionName or folder structure)
+ * 2. **Insert the generated function into the file content**
+ *
+ *    - Ensures proper placement, such as inside a class or export block
+ *    - May replace or append to existing function stubs
+ * 3. **Inject required imports automatically**
+ *
+ *    - Identifies any missing imports (e.g., DTOs, utility functions)
+ *    - Ensures imports are added without duplication
+ * 4. **Check for compile-time safety**
+ *
+ *    - Ensures TypeScript type-checking passes
+ *    - Verifies that Nestia-generated routers still function without error
+ *    - If compilation fails or static types are invalid, marks result as `"fail"`
+ *
+ * ⚠️ Note: This step **must not rely on runtime execution**. It only guarantees
+ * static, structural validity (i.e., valid TypeScript).
+ *
+ * @param ctx - AutoBE context including current source files and settings
+ * @param props - Output from the code generation step to be integrated
+ * @returns Integration status, indicating success or failure of insertion
+ */
+export const orchestrateRealizeIntegrator = async <
+  Model extends ILlmSchema.Model,
+>(
+  ctx: AutoBeContext<Model>,
+  props: IAutoBeRealizeCoderApplication.RealizeCoderOutput,
+): Promise<RealizeIntegratorOutput> => {
+  props;
+
+  const controllers: [string, string][] = Object.entries(
+    ctx.state().interface?.files ?? {},
+  ).filter(([filename]) => {
+    return filename.endsWith("controller.ts");
+  });
+
+  // Placeholder: insert props.implementationCode into selected controller
+  // Inject necessary import statements for used types/functions
+  // Optionally run TypeScript compiler in dry-run mode to validate correctness
+  controllers;
+
+  return null!;
+};

package/src/orchestrate/realize/orchestrateRealizePlanner.ts

@@ -0,0 +1,115 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+import { ILlmSchema } from "@samchon/openapi";
+
+import { AutoBeContext } from "../../context/AutoBeContext";
+
+export interface RealizePlannerOutput {
+  /**
+   * The name of the function to be generated.
+   *
+   * Derived from the Swagger path and method. The function name must be written
+   * in snake_case. It serves as the entry point in both code generation and
+   * test code.
+   *
+   * Once the function is generated, the function name and file name will be the
+   * same. The generated file will be located at
+   * `src/providers/${function_name}.ts`.
+   */
+  functionName: string;
+
+  /**
+   * Definition of path and query parameters extracted from the OpenAPI spec.
+   *
+   * Includes input values passed via URL path or query string. Used for type
+   * definitions, validation, and function signature construction.
+   */
+  parameters: AutoBeOpenApi.IParameter[];
+
+  /**
+   * Schema definition for the request body input.
+   *
+   * Extracted from the requestBody section of Swagger. Represents the input
+   * data passed in the body (e.g., JSON). Used for generating function
+   * arguments or DTOs.
+   */
+  inputSchema: AutoBeOpenApi.IRequestBody | null;
+
+  /**
+   * Schema definition for the response body.
+   *
+   * Extracted from the responses section of Swagger. Used to define the return
+   * type and expected output in test code.
+   */
+  outputSchema: AutoBeOpenApi.IResponseBody | null;
+
+  /**
+   * Natural language description of the function’s purpose.
+   *
+   * Extracted from the summary or description field of Swagger. Used for code
+   * documentation, test scenario generation, and conveying function intent.
+   */
+  description: string;
+
+  /**
+   * HTTP method information.
+   *
+   * Extracted from the Swagger operation method. Used to define the request
+   * type during code and test generation.
+   */
+  operationType: "get" | "post" | "put" | "delete" | "patch";
+
+  /**
+   * List of scenario descriptions for test code generation.
+   *
+   * Each scenario describes the expected behavior of the function under certain
+   * conditions. Used as a basis for TDD-style automated test generation.
+   */
+  testScenarios: string[];
+}
+
+/**
+ * Generates a planning result that defines what kind of function should be
+ * created, based solely on the provided Swagger (OpenAPI) operation — without
+ * using an LLM.
+ *
+ * This function analyzes the structure of the OpenAPI operation (such as the
+ * path, method, parameters, request/response schema, and descriptions) to
+ * determine the appropriate function name, input/output types, and purpose of
+ * the function.
+ *
+ * The result of this function (`RealizePlannerOutput`) will be passed to the
+ * next step in the AutoBE pipeline, which is responsible for generating the
+ * actual implementation code.
+ *
+ * @param ctx - AutoBE context including model and configuration
+ * @param operation - A single OpenAPI operation object to analyze and plan
+ * @returns A planning object containing all structural information needed to
+ *   generate the function
+ */
+export const orchestrateRealizePlanner = async <Model extends ILlmSchema.Model>(
+  ctx: AutoBeContext<Model>,
+  operation: AutoBeOpenApi.IOperation,
+): Promise<RealizePlannerOutput> => {
+  const testScenarios =
+    ctx
+      .state()
+      .test?.files.filter(
+        (el) =>
+          el.scenario.endpoint.method === operation.method &&
+          el.scenario.endpoint.path === operation.path,
+      ) ?? [];
+
+  return {
+    description: operation.description,
+    parameters: operation.parameters,
+    inputSchema: operation.requestBody,
+    outputSchema: operation.responseBody,
+    operationType: operation.method,
+    testScenarios: testScenarios.map((el) => el.scenario.draft),
+    functionName: `${operation.method}_${operation.path
+      .replaceAll("/", "_")
+      .replaceAll("-", "_")
+      .replaceAll("{", "$")
+      .replaceAll("}", "")}`,
+  } satisfies RealizePlannerOutput;
+};

package/src/orchestrate/realize/orchestrateRealizeValidator.ts

@@ -0,0 +1,64 @@
+import { ILlmSchema } from "@samchon/openapi";
+
+import { AutoBeContext } from "../../context/AutoBeContext";
+import { RealizeIntegratorOutput } from "./orchestrateRealizeIntegrator";
+
+/**
+ * The result of validating the integrated code by running tests or static
+ * checks.
+ */
+export interface RealizeValidatorOutput {
+  /** File path or location of the generated provider logic file. */
+  location: string;
+
+  /** The full TypeScript source code content of the generated provider file. */
+  content: string;
+
+  /**
+   * Overall result of the test execution.
+   *
+   * - "success": All tests passed successfully.
+   * - "fail": Some tests failed.
+   * - "exception": An unexpected error occurred during test execution.
+   */
+  result: "success" | "fail" | "exception";
+
+  /** Total number of test cases executed. */
+  total: number;
+
+  /** Number of tests that passed. */
+  success: number;
+
+  /** Number of tests that failed. */
+  fail: number;
+}
+
+/**
+ * Validates the integrated provider logic by returning the generated source
+ * code along with the summary of test execution results.
+ *
+ * This function serves as the final step to:
+ *
+ * - Provide the full TypeScript implementation files created/updated during
+ *   integration.
+ * - Return a detailed summary of the automated test outcomes executed against
+ *   that code.
+ *
+ * It does not throw errors; all failures or exceptions are reported via the
+ * `result` property.
+ *
+ * @param ctx - AutoBE execution context
+ * @param props - Result from the integration step
+ * @returns An object containing provider file content and test results
+ */
+export const orchestrateRealizeValidator = async <
+  Model extends ILlmSchema.Model,
+>(
+  ctx: AutoBeContext<Model>,
+  props: RealizeIntegratorOutput,
+): Promise<RealizeValidatorOutput> => {
+  ctx;
+  props;
+
+  return null!;
+};

package/src/orchestrate/realize/structures/IAutoBeRealizeCoderApplication.ts

@@ -0,0 +1,36 @@
+export interface IAutoBeRealizeCoderApplication {
+  programing: (next: IAutoBeRealizeCoderApplication.IProps) => void;
+}
+
+export namespace IAutoBeRealizeCoderApplication {
+  export interface IProps {
+    result: RealizeCoderOutput;
+  }
+
+  /**
+   * The result of the code generation step, representing a fully generated
+   * TypeScript function.
+   */
+  export interface RealizeCoderOutput {
+    /**
+     * The name of the function to be generated.
+     *
+     * This name will be used as the function's identifier and as the export
+     * name in the provider file.
+     */
+    functionName: string;
+
+    /**
+     * The raw TypeScript code string implementing the function.
+     *
+     * - The implementation must be valid TypeScript code.
+     * - It should focus solely on the logic of the function.
+     * - Import statements do **not** need to be included. They will be
+     *   automatically inserted by the system.
+     * - Any unused imports will be automatically removed by eslint.
+     * - Type annotations (e.g. for parameters and return types) should be omitted
+     *   if they can be inferred.
+     */
+    implementationCode: string;
+  }
+}