@autobe/agent 0.24.1 → 0.25.0

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,4 +1,5 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
+import { StringUtil } from "@autobe/utils";
 import { v7 } from "uuid";
 
 import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromptConstant";
@@ -6,12 +7,13 @@ import { AutoBeState } from "../../../context/AutoBeState";
 import { transformInterfaceAssetHistories } from "./transformInterfaceAssetHistories";
 import { transformInterfacePrerequisiteHistories } from "./transformInterfacePrerequisiteHistories";
 
-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 = transformInterfacePrerequisiteHistories(props.state);
   if (prerequisite !== null) return prerequisite;
 
   return [
@@ -21,12 +23,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/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

@@ -45,28 +45,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
@@ -92,14 +102,20 @@ 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);
+    > = await orchestrateInterfaceComplement(ctx, {
+      instruction: props.instruction,
+      document,
+    });
     Object.assign(document.components.schemas, complementedSchemas);
 
     const schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
@@ -109,6 +125,9 @@ export const orchestrateInterface =
         document.components.schemas,
       );
     Object.assign(document.components.schemas, schemas);
+    for (const key of Object.keys(document.components.schemas))
+      if (key === "IPageI" || key.startsWith("IPageI."))
+        delete document.components.schemas[key];
 
     // DO COMPILE
     return ctx.dispatch({

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;
 }
 

package/src/orchestrate/interface/orchestrateInterfaceComplement.ts

@@ -22,20 +22,24 @@ import { fulfillJsonSchemaErrorMessages } from "./utils/fulfillJsonSchemaErrorMe
 
 export function orchestrateInterfaceComplement<Model extends ILlmSchema.Model>(
   ctx: AutoBeContext<Model>,
-  document: AutoBeOpenApi.IDocument,
+  props: {
+    instruction: string;
+    document: AutoBeOpenApi.IDocument;
+  },
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
-  return step(ctx, document, 8);
+  return step(ctx, props, 8);
 }
 
 async function step<Model extends ILlmSchema.Model>(
   ctx: AutoBeContext<Model>,
-  document: AutoBeOpenApi.IDocument,
+  props: {
+    instruction: string;
+    document: AutoBeOpenApi.IDocument;
+  },
   life: number,
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
-  const missed: string[] = getMissed(document);
-  if (missed.length === 0 || life < 0) {
-    return document.components.schemas;
-  }
+  const missed: string[] = getMissed(props.document);
+  if (missed.length === 0 || life < 0) return props.document.components.schemas;
 
   const pointer: IPointer<Record<
     string,
@@ -45,11 +49,12 @@ async function step<Model extends ILlmSchema.Model>(
   };
   const { tokenUsage } = await ctx.conversate({
     source: "interfaceComplement",
-    histories: transformInterfaceComplementHistories(
-      ctx.state(),
-      document,
+    histories: transformInterfaceComplementHistories({
+      state: ctx.state(),
+      instruction: props.instruction,
+      document: props.document,
       missed,
-    ),
+    }),
     controller: createController({
       model: ctx.model,
       build: (next) => {
@@ -85,16 +90,19 @@ async function step<Model extends ILlmSchema.Model>(
 
   const newSchemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> = {
     ...pointer.value,
-    ...document.components.schemas,
+    ...props.document.components.schemas,
   };
-  JsonSchemaNamingConvention.schemas(document.operations, newSchemas);
+  JsonSchemaNamingConvention.schemas(props.document.operations, newSchemas);
   return step(
     ctx,
     {
-      ...document,
-      components: {
-        ...document.components,
-        schemas: newSchemas,
+      instruction: props.instruction,
+      document: {
+        ...props.document,
+        components: {
+          ...props.document.components,
+          schemas: newSchemas,
+        },
       },
     },
     life - 1,

package/src/orchestrate/interface/orchestrateInterfaceEndpoints.ts

@@ -22,39 +22,50 @@ export async function orchestrateInterfaceEndpoints<
   Model extends ILlmSchema.Model,
 >(
   ctx: AutoBeContext<Model>,
-  groups: AutoBeInterfaceGroup[],
-  authorizations: AutoBeOpenApi.IOperation[],
-  content: string = `Make endpoints for the given assets`,
+  props: {
+    groups: AutoBeInterfaceGroup[];
+    authorizations: AutoBeOpenApi.IOperation[];
+    instruction: string;
+    message?: string;
+  },
 ): Promise<AutoBeOpenApi.IEndpoint[]> {
   const progress: AutoBeProgressEventBase = {
-    total: groups.length,
+    total: props.groups.length,
     completed: 0,
   };
   const endpoints: AutoBeOpenApi.IEndpoint[] = (
     await executeCachedBatch(
-      groups.map(
-        (g) => (promptCacheKey) =>
-          process(ctx, g, content, progress, authorizations, promptCacheKey),
+      props.groups.map(
+        (group) => (promptCacheKey) =>
+          process(ctx, {
+            group,
+            authorizations: props.authorizations,
+            instruction: props.instruction,
+            message: props.message ?? "Make endpoints for the given assets.",
+            progress,
+            promptCacheKey,
+          }),
       ),
     )
   ).flat();
-
   const deduplicated: AutoBeOpenApi.IEndpoint[] = new HashSet(
     endpoints,
     OpenApiEndpointComparator.hashCode,
     OpenApiEndpointComparator.equals,
   ).toJSON();
-
   return orchestrateInterfaceEndpointsReview(ctx, deduplicated);
 }
 
 async function process<Model extends ILlmSchema.Model>(
   ctx: AutoBeContext<Model>,
-  group: AutoBeInterfaceGroup,
-  message: string,
-  progress: AutoBeProgressEventBase,
-  authorizations: AutoBeOpenApi.IOperation[],
-  promptCacheKey: string,
+  props: {
+    group: AutoBeInterfaceGroup;
+    message: string;
+    progress: AutoBeProgressEventBase;
+    authorizations: AutoBeOpenApi.IOperation[];
+    promptCacheKey: string;
+    instruction: string;
+  },
 ): Promise<AutoBeOpenApi.IEndpoint[]> {
   const start: Date = new Date();
   const pointer: IPointer<AutoBeOpenApi.IEndpoint[] | null> = {
@@ -62,11 +73,12 @@ async function process<Model extends ILlmSchema.Model>(
   };
   const { tokenUsage } = await ctx.conversate({
     source: "interfaceEndpoints",
-    histories: transformInterfaceEndpointHistories(
-      ctx.state(),
-      group,
-      authorizations,
-    ),
+    histories: transformInterfaceEndpointHistories({
+      state: ctx.state(),
+      group: props.group,
+      authorizations: props.authorizations,
+      instruction: props.instruction,
+    }),
     controller: createController({
       model: ctx.model,
       build: (endpoints) => {
@@ -75,8 +87,8 @@ async function process<Model extends ILlmSchema.Model>(
       },
     }),
     enforceFunctionCall: true,
-    promptCacheKey,
-    message,
+    promptCacheKey: props.promptCacheKey,
+    message: props.message,
   });
   if (pointer.value === null) throw new Error("Failed to generate endpoints."); // unreachable
 
@@ -91,8 +103,8 @@ async function process<Model extends ILlmSchema.Model>(
     tokenUsage,
     created_at: start.toISOString(),
     step: ctx.state().analyze?.step ?? 0,
-    completed: ++progress.completed,
-    total: progress.total,
+    completed: ++props.progress.completed,
+    total: props.progress.total,
   };
   ctx.dispatch(event);
   return pointer.value;

package/src/orchestrate/interface/orchestrateInterfaceGroups.ts

@@ -14,7 +14,10 @@ export async function orchestrateInterfaceGroups<
   Model extends ILlmSchema.Model,
 >(
   ctx: AutoBeContext<Model>,
-  message: string = "Design API operations for the given assets.",
+  props: {
+    instruction: string;
+    message?: string;
+  },
 ): Promise<AutoBeInterfaceGroupsEvent> {
   const start: Date = new Date();
   const pointer: IPointer<IAutoBeInterfaceGroupApplication.IProps | null> = {
@@ -22,7 +25,10 @@ export async function orchestrateInterfaceGroups<
   };
   const { tokenUsage } = await ctx.conversate({
     source: "interfaceGroups",
-    histories: transformInterfaceGroupHistories(ctx.state()),
+    histories: transformInterfaceGroupHistories({
+      state: ctx.state(),
+      instruction: props.instruction,
+    }),
     controller: createController({
       model: ctx.model,
       build: (next) => {
@@ -30,7 +36,7 @@ export async function orchestrateInterfaceGroups<
       },
     }),
     enforceFunctionCall: true,
-    message,
+    message: props.message ?? "Design API operations for the given assets.",
   });
   if (pointer.value === null) throw new Error("Failed to generate groups."); // unreachable
   return {