@autobe/agent 0.24.2 → 0.25.1

package/src/orchestrate/interface/histories/transformInterfaceComplementHistories.ts

@@ -7,11 +7,12 @@ import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromp
 import { AutoBeState } from "../../../context/AutoBeState";
 import { transformInterfaceAssetHistories } from "./transformInterfaceAssetHistories";
 
-export const transformInterfaceComplementHistories = (
-  state: AutoBeState,
-  document: AutoBeOpenApi.IDocument,
-  missed: string[],
-): Array<
+export const transformInterfaceComplementHistories = (props: {
+  state: AutoBeState;
+  instruction: string;
+  missed: string[];
+  document: AutoBeOpenApi.IDocument;
+}): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => [
   {
@@ -20,7 +21,7 @@ export const transformInterfaceComplementHistories = (
     created_at: new Date().toISOString(),
     text: AutoBeSystemPromptConstant.INTERFACE_OPERATION,
   },
-  ...transformInterfaceAssetHistories(state),
+  ...transformInterfaceAssetHistories(props.state),
   {
     type: "systemMessage",
     id: v7(),
@@ -38,33 +39,41 @@ export const transformInterfaceComplementHistories = (
     id: v7(),
     created_at: new Date().toISOString(),
     text: StringUtil.trim`
+      ## API Design Instructions
+
+      The following API-specific instructions were extracted by AI from
+      the user's utterances. These focus ONLY on API interface design aspects
+      such as endpoint patterns, request/response formats, DTO schemas,
+      and operation specifications.
+
+      Apply these instructions when completing the missing schema types.
+      Focus on ensuring the schemas align with the overall API design patterns
+      and data structure requirements. If the instructions are not relevant
+      to the specific schemas you need to create, you may ignore them.
+
+      ${props.instruction}
+
+      ## Operations
+
       Here is the OpenAPI operations what you AI have made:
 
       \`\`\`json
-      ${JSON.stringify(document.operations)}
+      ${JSON.stringify(props.document.operations)}
       \`\`\`
-    `,
-  },
-  {
-    type: "assistantMessage",
-    id: v7(),
-    created_at: new Date().toISOString(),
-    text: StringUtil.trim`
+
+      ## Schemas
+
       Here is the OpenAPI schemas what you AI have made:
 
       \`\`\`json
-      ${JSON.stringify(document.components.schemas)}
+      ${JSON.stringify(props.document.components.schemas)}
       \`\`\`
-    `,
-  },
-  {
-    type: "assistantMessage",
-    id: v7(),
-    created_at: new Date().toISOString(),
-    text: StringUtil.trim`
-      You AI have missed below schema types:
 
-      ${missed.map((s) => `- ${s}`).join("\n")}
+      ## Missed Types
+
+      However, you AI have missed below schema types:
+
+      ${props.missed.map((s) => `- ${s}`).join("\n")}
     `,
   },
 ];

package/src/orchestrate/interface/histories/transformInterfaceEndpointHistories.ts

@@ -8,11 +8,12 @@ import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromp
 import { AutoBeState } from "../../../context/AutoBeState";
 import { transformInterfaceAssetHistories } from "./transformInterfaceAssetHistories";
 
-export const transformInterfaceEndpointHistories = (
-  state: AutoBeState,
-  group: AutoBeInterfaceGroup,
-  authorizations: AutoBeOpenApi.IOperation[],
-): Array<
+export const transformInterfaceEndpointHistories = (props: {
+  state: AutoBeState;
+  group: AutoBeInterfaceGroup;
+  authorizations: AutoBeOpenApi.IOperation[];
+  instruction: string;
+}): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => [
   {
@@ -21,25 +22,41 @@ export const transformInterfaceEndpointHistories = (
     created_at: new Date().toISOString(),
     text: AutoBeSystemPromptConstant.INTERFACE_ENDPOINT,
   },
-  ...transformInterfaceAssetHistories(state),
+  ...transformInterfaceAssetHistories(props.state),
   {
     type: "assistantMessage",
     id: v7(),
     created_at: new Date().toISOString(),
     text: StringUtil.trim`
+      ## API Design Instructions
+
+      The following API-specific instructions were extracted by AI from
+      the user's utterances. These focus ONLY on API interface design aspects
+      such as endpoint patterns, request/response formats, DTO schemas,
+      and operation specifications.
+
+      Apply these instructions when designing endpoints for the ${props.group.name} group.
+      Consider the specified URL patterns, HTTP methods, parameter structures,
+      and response formats. If the instructions are not relevant to this specific
+      endpoint group, you may ignore them.
+
+      ${props.instruction}
+
+      ## Group Information
+
       Here is the target group for the endpoints:
 
       \`\`\`json
-      ${JSON.stringify(group)}
+      ${JSON.stringify(props.group)}
       \`\`\`
 
-      **IMPORTANT: DO NOT DUPLICATE EXISTING OPERATIONS**
+      ## Already Existing Operations
 
       These operations already exist. Do NOT create similar endpoints:
 
       \`\`\`json
       ${JSON.stringify(
-        authorizations.map((op) => ({
+        props.authorizations.map((op) => ({
           path: op.path,
           method: op.method,
           name: op.name,

package/src/orchestrate/interface/histories/transformInterfaceGroupHistories.ts

@@ -1,17 +1,21 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
+import { StringUtil } from "@autobe/utils";
 import { v7 } from "uuid";
 
 import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromptConstant";
 import { AutoBeState } from "../../../context/AutoBeState";
 import { transformInterfaceAssetHistories } from "./transformInterfaceAssetHistories";
-import { transformInterfacePrerequisiteHistories } from "./transformInterfacePrerequisiteHistories";
+import { transformInterfaceCommonPrerequisiteHistories } from "./transformInterfaceCommonPrerequisiteHistories";
 
-export const transformInterfaceGroupHistories = (
-  state: AutoBeState,
-): Array<
+export const transformInterfaceGroupHistories = (props: {
+  state: AutoBeState;
+  instruction: string;
+}): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => {
-  const prerequisite = transformInterfacePrerequisiteHistories(state);
+  const prerequisite = transformInterfaceCommonPrerequisiteHistories(
+    props.state,
+  );
   if (prerequisite !== null) return prerequisite;
 
   return [
@@ -21,12 +25,32 @@ export const transformInterfaceGroupHistories = (
       type: "systemMessage",
       text: AutoBeSystemPromptConstant.INTERFACE_ENDPOINT,
     },
-    ...transformInterfaceAssetHistories(state),
+    ...transformInterfaceAssetHistories(props.state),
     {
       id: v7(),
       created_at: new Date().toISOString(),
       type: "systemMessage",
       text: AutoBeSystemPromptConstant.INTERFACE_GROUP,
     },
+    {
+      id: v7(),
+      created_at: new Date().toISOString(),
+      type: "assistantMessage",
+      text: StringUtil.trim`
+        ## API Design Instructions
+
+        The following API-specific instructions were extracted by AI from
+        the user's utterances. These focus ONLY on API interface design aspects
+        such as endpoint patterns, request/response formats, DTO schemas,
+        and operation specifications.
+
+        Apply these instructions when organizing API endpoints into logical groups.
+        Consider how to structure and categorize endpoints based on business domains,
+        resource types, or functional areas. If the instructions are not relevant
+        to endpoint grouping and organization, you may ignore them.
+
+        ${props.instruction}
+      `,
+    },
   ];
 };

package/src/orchestrate/interface/histories/transformInterfaceOperationHistories.ts

@@ -7,13 +7,14 @@ import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromp
 import { AutoBeState } from "../../../context/AutoBeState";
 import { transformInterfaceAssetHistories } from "./transformInterfaceAssetHistories";
 
-export const transformInterfaceOperationHistories = (
-  state: AutoBeState,
-  endpoints: AutoBeOpenApi.IEndpoint[],
-): Array<
+export const transformInterfaceOperationHistories = (props: {
+  state: AutoBeState;
+  endpoints: AutoBeOpenApi.IEndpoint[];
+  instruction: string;
+}): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => {
-  const analyze: AutoBeAnalyzeHistory = state.analyze!;
+  const analyze: AutoBeAnalyzeHistory = props.state.analyze!;
   return [
     {
       type: "systemMessage",
@@ -21,7 +22,7 @@ export const transformInterfaceOperationHistories = (
       created_at: new Date().toISOString(),
       text: AutoBeSystemPromptConstant.INTERFACE_OPERATION,
     },
-    ...transformInterfaceAssetHistories(state),
+    ...transformInterfaceAssetHistories(props.state),
     {
       type: "systemMessage",
       id: v7(),
@@ -44,10 +45,26 @@ export const transformInterfaceOperationHistories = (
       id: v7(),
       created_at: new Date().toISOString(),
       text: StringUtil.trim`
+        ## API Design Instructions
+
+        The following API-specific instructions were extracted by AI from
+        the user's utterances. These focus ONLY on API interface design aspects
+        such as endpoint patterns, request/response formats, DTO schemas,
+        and operation specifications.
+
+        Apply these instructions when designing the detailed operation specifications
+        for each endpoint. Consider parameter types, request/response structures,
+        error handling, and API behavior patterns. If the instructions are not
+        relevant to the operations you need to implement, you may ignore them.
+
+        ${props.instruction}
+
+        ## Operations
+
         You have to make API operations for the given endpoints:
 
         \`\`\`json
-        ${JSON.stringify(endpoints)}
+        ${JSON.stringify(props.endpoints)}
         \`\`\`
 
         If there is a content in the failure, it is to explain why it failed before.

package/src/orchestrate/interface/histories/transformInterfacePrerequisitesHistories.ts

@@ -0,0 +1,118 @@
+import { IAgenticaHistoryJson } from "@agentica/core";
+import { AutoBeOpenApi } from "@autobe/interface";
+import { StringUtil } from "@autobe/utils";
+import { OpenApiTypeChecker } from "@samchon/openapi";
+import { v7 } from "uuid";
+
+import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromptConstant";
+import { getReferenceIds } from "../../test/utils/getReferenceIds";
+
+export const transformInterfacePrerequisitesHistories = (
+  document: AutoBeOpenApi.IDocument,
+  include: AutoBeOpenApi.IOperation[],
+): Array<
+  IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
+> => {
+  const domainSchemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
+    {};
+  const visit = (key: string) =>
+    OpenApiTypeChecker.visit({
+      schema: {
+        $ref: `#/components/schemas/${key}`,
+      },
+      components: document.components,
+      closure: (next) => {
+        if (OpenApiTypeChecker.isReference(next))
+          domainSchemas[next.$ref.split("/").pop()!] =
+            document.components.schemas[next.$ref.split("/").pop()!];
+      },
+    });
+  for (const op of include) {
+    if (op.requestBody) visit(op.requestBody.typeName);
+    if (op.responseBody) visit(op.responseBody.typeName);
+  }
+
+  return [
+    {
+      type: "systemMessage",
+      id: v7(),
+      created_at: new Date().toISOString(),
+      text: AutoBeSystemPromptConstant.INTERFACE_PREREQUISITE,
+    },
+    {
+      type: "assistantMessage",
+      id: v7(),
+      created_at: new Date().toISOString(),
+      text: StringUtil.trim`
+        ## Document Overview
+
+        ### Entire API Operations
+        
+        All operations in this project for prerequisite references.
+
+        These are the complete list of API endpoints that can be used 
+        as prerequisites. You should select appropriate operations from 
+        this list when establishing dependency chains.
+
+        \`\`\`json
+        ${JSON.stringify({
+          operations: document.operations
+            .filter(
+              (op) => op.authorizationType === null && op.method === "post",
+            )
+            .map((op) => {
+              return {
+                ...op,
+                prerequisites: undefined,
+              };
+            }),
+        })}
+        \`\`\`
+
+        ### Entire Schema Definitions
+
+        Data structure definitions to understand entity relationships.
+
+        Use these schemas to identify parent-child relationships and 
+        data dependencies between operations.
+
+        \`\`\`json
+        ${JSON.stringify({
+          components: {
+            schemas: document.components.schemas,
+          },
+        })}
+        \`\`\`
+            
+        ## Target Operations and Schemas
+
+        ### Target Operations
+
+        Operations requiring prerequisite analysis.
+        
+        For each of these operations, analyze if they need any prerequisites 
+        from the available operations above. Add prerequisites only when there 
+        are genuine dependencies like resource existence checks or state validations.
+
+        \`\`\`json
+        ${JSON.stringify(
+          include.map((op) => {
+            return {
+              ...op,
+              requiredIds: getReferenceIds({ document, operation: op }),
+            };
+          }),
+        )}
+        \`\`\`
+
+        ### Domain Schemas
+
+        Schema definitions for the target operations.
+
+        \`\`\`json
+        ${JSON.stringify(domainSchemas)}
+        \`\`\`
+      `,
+    },
+  ];
+};

package/src/orchestrate/interface/histories/transformInterfaceSchemaHistories.ts

@@ -7,10 +7,11 @@ import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromp
 import { AutoBeState } from "../../../context/AutoBeState";
 import { transformInterfaceAssetHistories } from "./transformInterfaceAssetHistories";
 
-export const transformInterfaceSchemaHistories = (
-  state: AutoBeState,
-  operations: AutoBeOpenApi.IOperation[],
-): Array<
+export const transformInterfaceSchemaHistories = (props: {
+  state: AutoBeState;
+  operations: AutoBeOpenApi.IOperation[];
+  instruction: string;
+}): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => [
   {
@@ -19,16 +20,32 @@ export const transformInterfaceSchemaHistories = (
     created_at: new Date().toISOString(),
     text: AutoBeSystemPromptConstant.INTERFACE_SCHEMA,
   },
-  ...transformInterfaceAssetHistories(state),
+  ...transformInterfaceAssetHistories(props.state),
   {
     type: "assistantMessage",
     id: v7(),
     created_at: new Date().toISOString(),
     text: StringUtil.trim`
+      ## API Design Instructions
+
+      The following API-specific instructions were extracted by AI from
+      the user's utterances. These focus ONLY on API interface design aspects
+      such as endpoint patterns, request/response formats, DTO schemas,
+      and operation specifications.
+
+      Apply these instructions when creating JSON schema components for the operations.
+      Focus on data structure design, field naming conventions, validation rules,
+      and type definitions. If the instructions are not relevant to the schema
+      components you need to create, you may ignore them.
+
+      ${props.instruction}
+
+      ## Operations
+
       Here is the list of API operations you have to implement its types:
 
       \`\`\`json
-      ${JSON.stringify(operations)}
+      ${JSON.stringify(props.operations)}
       \`\`\`
     `,
   },

package/src/orchestrate/interface/orchestrateInterface.ts

@@ -6,7 +6,12 @@ import {
   AutoBeInterfaceHistory,
   AutoBeOpenApi,
 } from "@autobe/interface";
-import { AutoBeEndpointComparator } from "@autobe/utils";
+import { AutoBeInterfacePrerequisite } from "@autobe/interface/src/histories/contents/AutoBeInterfacePrerequisite";
+import {
+  AutoBeOpenApiEndpointComparator,
+  missedOpenApiSchemas,
+  revertOpenApiAccessor,
+} from "@autobe/utils";
 import { ILlmSchema } from "@samchon/openapi";
 import { HashMap, Pair } from "tstl";
 import { v7 } from "uuid";
@@ -19,8 +24,10 @@ import { orchestrateInterfaceComplement } from "./orchestrateInterfaceComplement
 import { orchestrateInterfaceEndpoints } from "./orchestrateInterfaceEndpoints";
 import { orchestrateInterfaceGroups } from "./orchestrateInterfaceGroups";
 import { orchestrateInterfaceOperations } from "./orchestrateInterfaceOperations";
+import { orchestrateInterfacePrerequisites } from "./orchestrateInterfacePrerequisites";
 import { orchestrateInterfaceSchemas } from "./orchestrateInterfaceSchemas";
 import { orchestrateInterfaceSchemasReview } from "./orchestrateInterfaceSchemasReview";
+import { JsonSchemaFactory } from "./utils/JsonSchemaFactory";
 
 export const orchestrateInterface =
   <Model extends ILlmSchema.Model>(ctx: AutoBeContext<Model>) =>
@@ -45,28 +52,38 @@ export const orchestrateInterface =
       type: "interfaceStart",
       id: v7(),
       created_at: start.toISOString(),
-      reason: props.reason,
+      reason: props.instruction,
       step: ctx.state().analyze?.step ?? 0,
     });
 
     // ENDPOINTS
-    const init: AutoBeInterfaceGroupsEvent =
-      await orchestrateInterfaceGroups(ctx);
+    const init: AutoBeInterfaceGroupsEvent = await orchestrateInterfaceGroups(
+      ctx,
+      {
+        instruction: props.instruction,
+      },
+    );
     ctx.dispatch(init);
 
     // AUTHORIZATION
     const authorizations: AutoBeInterfaceAuthorization[] =
-      await orchestrateInterfaceAuthorizations(ctx);
-
-    const authOperations = authorizations
+      await orchestrateInterfaceAuthorizations(ctx, props.instruction);
+    const authOperations: AutoBeOpenApi.IOperation[] = authorizations
       .map((authorization) => authorization.operations)
       .flat();
 
     // ENDPOINTS & OPERATIONS
     const endpoints: AutoBeOpenApi.IEndpoint[] =
-      await orchestrateInterfaceEndpoints(ctx, init.groups, authOperations);
+      await orchestrateInterfaceEndpoints(ctx, {
+        groups: init.groups,
+        authorizations: authOperations,
+        instruction: props.instruction,
+      });
     const firstOperations: AutoBeOpenApi.IOperation[] =
-      await orchestrateInterfaceOperations(ctx, endpoints);
+      await orchestrateInterfaceOperations(ctx, {
+        endpoints,
+        instruction: props.instruction,
+      });
     const operations: AutoBeOpenApi.IOperation[] = new HashMap<
       AutoBeOpenApi.IEndpoint,
       AutoBeOpenApi.IOperation
@@ -81,8 +98,8 @@ export const orchestrateInterface =
             o, // early inserted be kept
           ),
       ),
-      AutoBeEndpointComparator.hashCode,
-      AutoBeEndpointComparator.equals,
+      AutoBeOpenApiEndpointComparator.hashCode,
+      AutoBeOpenApiEndpointComparator.equals,
     )
       .toJSON()
       .map((it) => it.second);
@@ -92,29 +109,57 @@ export const orchestrateInterface =
       operations,
       components: {
         authorization: ctx.state().analyze?.roles ?? [],
-        schemas: await orchestrateInterfaceSchemas(ctx, operations),
+        schemas: await orchestrateInterfaceSchemas(ctx, {
+          instruction: props.instruction,
+          operations,
+        }),
       },
     };
 
-    const complementedSchemas: Record<
-      string,
-      AutoBeOpenApi.IJsonSchemaDescriptive
-    > = await orchestrateInterfaceComplement(ctx, document);
-    Object.assign(document.components.schemas, complementedSchemas);
+    const complement = async () =>
+      Object.assign(
+        document.components.schemas,
+        await orchestrateInterfaceComplement(ctx, {
+          instruction: props.instruction,
+          document,
+        }),
+      );
+    await complement();
 
-    const schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
+    Object.assign(
+      document.components.schemas,
       await orchestrateInterfaceSchemasReview(
         ctx,
         operations,
         document.components.schemas,
-      );
-    Object.assign(document.components.schemas, schemas);
+      ),
+    );
+    if (missedOpenApiSchemas(document).length !== 0) await complement();
+
+    JsonSchemaFactory.finalize({
+      document,
+      application: ctx.state().prisma!.result.data,
+    });
+
+    // CONNECT PRE-REQUISITES
+    const prerequisites: AutoBeInterfacePrerequisite[] =
+      await orchestrateInterfacePrerequisites(ctx, document);
+    document.operations.forEach((op) => {
+      op.prerequisites =
+        prerequisites.find(
+          (p) => p.endpoint.method === op.method && p.endpoint.path === op.path,
+        )?.prerequisites ?? [];
+    });
+
+    // NORMALIZE ACCESSORS
+    revertOpenApiAccessor(document);
 
     // DO COMPILE
     return ctx.dispatch({
       type: "interfaceComplete",
       id: v7(),
       document,
+      missed: missedOpenApiSchemas(document),
       authorizations,
       created_at: new Date().toISOString(),
       elapsed: new Date().getTime() - start.getTime(),

package/src/orchestrate/interface/orchestrateInterfaceAuthorizations.ts

@@ -20,7 +20,10 @@ import { IAutoBeInterfaceAuthorizationsApplication } from "./structures/IAutoBeI
 
 export async function orchestrateInterfaceAuthorizations<
   Model extends ILlmSchema.Model,
->(ctx: AutoBeContext<Model>): Promise<AutoBeInterfaceAuthorization[]> {
+>(
+  ctx: AutoBeContext<Model>,
+  instruction: string,
+): Promise<AutoBeInterfaceAuthorization[]> {
   const roles: AutoBeAnalyzeRole[] = ctx.state().analyze?.roles ?? [];
   const progress: AutoBeProgressEventBase = {
     total: roles.length,
@@ -29,12 +32,12 @@ export async function orchestrateInterfaceAuthorizations<
   const authorizations: AutoBeInterfaceAuthorization[] =
     await executeCachedBatch(
       roles.map((role) => async (promptCacheKey) => {
-        const event: AutoBeInterfaceAuthorizationEvent = await process(
-          ctx,
+        const event: AutoBeInterfaceAuthorizationEvent = await process(ctx, {
           role,
           progress,
           promptCacheKey,
-        );
+          instruction,
+        });
         ctx.dispatch(event);
         return {
           role: role.name,
@@ -48,9 +51,12 @@ export async function orchestrateInterfaceAuthorizations<
 
 async function process<Model extends ILlmSchema.Model>(
   ctx: AutoBeContext<Model>,
-  role: AutoBeAnalyzeRole,
-  progress: AutoBeProgressEventBase,
-  promptCacheKey: string,
+  props: {
+    instruction: string;
+    role: AutoBeAnalyzeRole;
+    progress: AutoBeProgressEventBase;
+    promptCacheKey: string;
+  },
 ): Promise<AutoBeInterfaceAuthorizationEvent> {
   const pointer: IPointer<IAutoBeInterfaceAuthorizationsApplication.IProps | null> =
     {
@@ -58,16 +64,20 @@ async function process<Model extends ILlmSchema.Model>(
     };
   const { tokenUsage } = await ctx.conversate({
     source: "interfaceAuthorization",
-    histories: transformInterfaceAuthorizationsHistories(ctx.state(), role),
+    histories: transformInterfaceAuthorizationsHistories({
+      state: ctx.state(),
+      instruction: props.instruction,
+      role: props.role,
+    }),
     controller: createController({
       model: ctx.model,
-      role,
+      role: props.role,
       build: (next) => {
         pointer.value = next;
       },
     }),
     enforceFunctionCall: true,
-    promptCacheKey,
+    promptCacheKey: props.promptCacheKey,
     message: "Create Authorization Operation for the given roles",
   });
   if (pointer.value === null)
@@ -77,11 +87,11 @@ async function process<Model extends ILlmSchema.Model>(
     type: "interfaceAuthorization",
     id: v7(),
     operations: pointer.value.operations,
-    completed: ++progress.completed,
+    completed: ++props.progress.completed,
     tokenUsage,
     created_at: new Date().toISOString(),
     step: ctx.state().analyze?.step ?? 0,
-    total: progress.total,
+    total: props.progress.total,
   } satisfies AutoBeInterfaceAuthorizationEvent;
 }