@agentica/core 0.32.1 → 0.32.3-dev.1

package/src/orchestrate/select.ts

@@ -17,9 +17,10 @@ import { AgenticaDefaultPrompt } from "../constants/AgenticaDefaultPrompt";
 import { AgenticaSystemPrompt } from "../constants/AgenticaSystemPrompt";
 import { createAssistantMessageEvent } from "../factory/events";
 import { decodeHistory, decodeUserMessageContent } from "../factory/histories";
-import { MPSC } from "../utils";
-import { ChatGptCompletionMessageUtil } from "../utils/ChatGptCompletionMessageUtil";
-import { streamDefaultReaderToAsyncGenerator, StreamUtil, toAsyncGenerator } from "../utils/StreamUtil";
+import { __get_retry } from "../utils/__retry";
+import { AssistantMessageEmptyError, AssistantMessageEmptyWithReasoningError } from "../utils/AssistantMessageEmptyError";
+import { reduceStreamingWithDispatch } from "../utils/ChatGptCompletionStreamingUtil";
+import { toAsyncGenerator } from "../utils/StreamUtil";
 
 import { selectFunctionFromContext } from "./internal/selectFunctionFromContext";
 
@@ -93,154 +94,126 @@ async function step<Model extends ILlmSchema.Model>(
   retry: number,
   failures?: IFailure[],
 ): Promise<void> {
+  const _retryFn = __get_retry(ctx.config?.retry ?? AgenticaConstant.RETRY);
+  const retryFn = async (fn: (prevError?: unknown) => Promise<OpenAI.ChatCompletion>) => {
+    return _retryFn(fn).catch((e) => {
+      if (e instanceof AssistantMessageEmptyError) {
+        return Symbol("emptyAssistantMessage");
+      }
+      throw e;
+    });
+  };
   // ----
   // EXECUTE CHATGPT API
   // ----
-  const completionStream = await ctx.request("select", {
-    messages: [
-      // COMMON SYSTEM PROMPT
-      {
-        role: "system",
-        content: AgenticaDefaultPrompt.write(ctx.config),
-      } satisfies OpenAI.ChatCompletionSystemMessageParam,
-      // CANDIDATE FUNCTIONS
-      {
-        role: "assistant",
-        tool_calls: [
-          {
-            type: "function",
-            id: "getApiFunctions",
-            function: {
-              name: "getApiFunctions",
-              arguments: JSON.stringify({}),
+  const completion = await retryFn(async (prevError) => {
+    const stream = await ctx.request("select", {
+      messages: [
+        // COMMON SYSTEM PROMPT
+        {
+          role: "system",
+          content: AgenticaDefaultPrompt.write(ctx.config),
+        } satisfies OpenAI.ChatCompletionSystemMessageParam,
+        // CANDIDATE FUNCTIONS
+        {
+          role: "assistant",
+          tool_calls: [
+            {
+              type: "function",
+              id: "getApiFunctions",
+              function: {
+                name: "getApiFunctions",
+                arguments: JSON.stringify({}),
+              },
             },
-          },
-        ],
-      },
-      {
-        role: "tool",
-        tool_call_id: "getApiFunctions",
-        content: JSON.stringify(
-          operations.map(op => ({
-            name: op.name,
-            description: op.function.description,
-            ...(op.protocol === "http"
-              ? {
-                  method: op.function.method,
-                  path: op.function.path,
-                  tags: op.function.tags,
-                }
-              : {}),
-          })),
-        ),
-      },
-      // PREVIOUS HISTORIES
-      ...ctx.histories.map(decodeHistory).flat(),
-      // USER INPUT
-      {
-        role: "user",
-        content: ctx.prompt.contents.map(decodeUserMessageContent),
-      },
-      // SYSTEM PROMPT
-      {
-        role: "system",
-        content:
-          ctx.config?.systemPrompt?.select?.(ctx.histories)
-          ?? AgenticaSystemPrompt.SELECT,
-      },
-      // TYPE CORRECTIONS
-      ...emendMessages(failures ?? []),
-    ],
-    // STACK FUNCTIONS
-    tools: [{
-      type: "function",
-      function: {
-        name: CONTAINER.functions[0]!.name,
-        description: CONTAINER.functions[0]!.description,
-        /**
-         * @TODO fix it
-         * The property and value have a type mismatch, but it works.
-         */
-        parameters: CONTAINER.functions[0]!.parameters as unknown as Record<string, unknown>,
-      },
-    } satisfies OpenAI.ChatCompletionTool],
-    tool_choice: retry === 0
-      ? "auto"
-      : "required",
-    // parallel_tool_calls: false,
-  });
-
-  const selectContext: ({
-    content: string;
-    mpsc: MPSC<string>;
-  })[] = [];
-  const nullableCompletion = await StreamUtil.reduce<OpenAI.ChatCompletionChunk, Promise<OpenAI.ChatCompletion>>(completionStream, async (accPromise, chunk) => {
-    const acc = await accPromise;
-
-    const registerContext = (
-      choices: OpenAI.ChatCompletionChunk.Choice[],
-    ) => {
-      for (const choice of choices) {
-        /**
-         * @TODO fix it
-         * Sometimes, the complete message arrives along with a finish reason.
-         */
-        if (choice.finish_reason != null) {
-          selectContext[choice.index]?.mpsc.close();
-          continue;
-        }
-
-        if (choice.delta.content == null || choice.delta.content === "") {
-          continue;
-        }
-
-        if (selectContext[choice.index] != null) {
-          selectContext[choice.index]!.content += choice.delta.content;
-          selectContext[choice.index]!.mpsc.produce(choice.delta.content);
-          continue;
-        }
-
-        const mpsc = new MPSC<string>();
-
-        selectContext[choice.index] = {
-          content: choice.delta.content,
-          mpsc,
-        };
-        mpsc.produce(choice.delta.content);
+          ],
+        },
+        {
+          role: "tool",
+          tool_call_id: "getApiFunctions",
+          content: JSON.stringify(
+            operations.map(op => ({
+              name: op.name,
+              description: op.function.description,
+              ...(op.protocol === "http"
+                ? {
+                    method: op.function.method,
+                    path: op.function.path,
+                    tags: op.function.tags,
+                  }
+                : {}),
+            })),
+          ),
+        },
+        // PREVIOUS HISTORIES
+        ...ctx.histories.map(decodeHistory).flat(),
+        // USER INPUT
+        {
+          role: "user",
+          content: ctx.prompt.contents.map(decodeUserMessageContent),
+        },
+        // PREVIOUS ERROR
+        ...(prevError instanceof AssistantMessageEmptyWithReasoningError ? [
+          {
+            role: "assistant",
+            content: prevError.reasoning,
+          } satisfies OpenAI.ChatCompletionMessageParam,
+        ] : []),
+        // SYSTEM PROMPT
+        {
+          role: "system",
+          content:
+            ctx.config?.systemPrompt?.select?.(ctx.histories)
+            ?? AgenticaSystemPrompt.SELECT,
+        },
+        // TYPE CORRECTIONS
+        ...emendMessages(failures ?? []),
+      ],
+      // STACK FUNCTIONS
+      tools: [{
+        type: "function",
+        function: {
+          name: CONTAINER.functions[0]!.name,
+          description: CONTAINER.functions[0]!.description,
+          /**
+           * @TODO fix it
+           * The property and value have a type mismatch, but it works.
+           */
+          parameters: CONTAINER.functions[0]!.parameters as unknown as Record<string, unknown>,
+        },
+      } satisfies OpenAI.ChatCompletionTool],
+      tool_choice: retry === 0
+        ? "auto"
+        : "required",
+      // parallel_tool_calls: false,
+    });
 
-        const event: AgenticaAssistantMessageEvent = createAssistantMessageEvent({
-          stream: streamDefaultReaderToAsyncGenerator(mpsc.consumer.getReader()),
-          done: () => mpsc.done(),
-          get: () => selectContext[choice.index]?.content ?? "",
-          join: async () => {
-            await mpsc.waitClosed();
-            return selectContext[choice.index]!.content;
-          },
-        });
-        ctx.dispatch(event);
+    const completion = await reduceStreamingWithDispatch(stream, (props) => {
+      const event: AgenticaAssistantMessageEvent = createAssistantMessageEvent(props);
+      ctx.dispatch(event);
+    });
+    const allAssistantMessagesEmpty = completion.choices.every(v => v.message.tool_calls == null && v.message.content === "");
+    if (allAssistantMessagesEmpty) {
+      const firstChoice = completion.choices.at(0);
+      if ((firstChoice?.message as { reasoning?: string })?.reasoning != null) {
+        throw new AssistantMessageEmptyWithReasoningError((firstChoice?.message as { reasoning?: string })?.reasoning ?? "");
       }
-    };
-    if (acc.object === "chat.completion.chunk") {
-      registerContext([acc, chunk].flatMap(v => v.choices));
-      return ChatGptCompletionMessageUtil.merge([acc, chunk]);
+      throw new AssistantMessageEmptyError();
     }
-    registerContext(chunk.choices);
-    return ChatGptCompletionMessageUtil.accumulate(acc, chunk);
+    return completion;
   });
-  const completion = nullableCompletion!;
-  const emptyAssistantMessages = completion.choices.filter(v => v.message.tool_calls == null && v.message.content === "");
-  if(emptyAssistantMessages.length > 0) {
-    emptyAssistantMessages.forEach(v => {
+
+  if (typeof completion === "symbol") {
     const event: AgenticaAssistantMessageEvent = createAssistantMessageEvent({
-      stream: toAsyncGenerator(v.message.content ?? ""),
+      stream: toAsyncGenerator(""),
       done: () => true,
-      get: () => v.message.content ?? "",
+      get: () => "",
       join: async () => {
-        return v.message.content ?? "";
+        return "";
       },
-      });
-      ctx.dispatch(event);
     });
+    ctx.dispatch(event);
+    return;
   }
   // ----
   // VALIDATION

package/src/utils/AssistantMessageEmptyError.ts

@@ -0,0 +1,13 @@
+export class AssistantMessageEmptyError extends Error {
+  constructor() {
+    super();
+  }
+}
+
+export class AssistantMessageEmptyWithReasoningError extends AssistantMessageEmptyError {
+  public readonly reasoning: string;
+  constructor(reasoning: string) {
+    super();
+    this.reasoning = reasoning;
+  }
+}

package/src/utils/ChatGptCompletionMessageUtil.ts

@@ -54,6 +54,10 @@ function accumulate(origin: ChatCompletion, chunk: ChatCompletionChunk): ChatCom
         content: choice.delta.content ?? null,
         refusal: choice.delta.refusal ?? null,
         role: "assistant",
+        ...({
+          // for open router
+          reasoning: (choice.delta as { reasoning?: string }).reasoning ?? null,
+        }),
       } satisfies ChatCompletionMessage,
     };
   });
@@ -133,6 +137,16 @@ function mergeChoice(acc: ChatCompletion.Choice, cur: ChatCompletionChunk.Choice
     }
   }
 
+  // for open router
+  if ((cur.delta as { reasoning?: string }).reasoning != null) {
+    if ((acc.message as { reasoning?: string }).reasoning == null) {
+      (acc.message as { reasoning?: string }).reasoning = (cur.delta as { reasoning?: string }).reasoning;
+    }
+    else {
+      (acc.message as unknown as { reasoning: string }).reasoning += (cur.delta as { reasoning: string }).reasoning;
+    }
+  }
+
   if (cur.delta.tool_calls != null) {
     acc.message.tool_calls ??= [];
     const toolCalls = acc.message.tool_calls;

package/src/utils/ChatGptCompletionStreamingUtil.ts

@@ -0,0 +1,81 @@
+import type { ChatCompletion, ChatCompletionChunk } from "openai/resources";
+
+import { ChatGptCompletionMessageUtil, MPSC, streamDefaultReaderToAsyncGenerator, StreamUtil } from ".";
+
+async function reduceStreamingWithDispatch(stream: ReadableStream<ChatCompletionChunk>, eventProcessor: (props: {
+  stream: AsyncGenerator<string, undefined, undefined>;
+  done: () => boolean;
+  get: () => string;
+  join: () => Promise<string>;
+}) => void) {
+  const streamContext = new Map<number, { content: string; mpsc: MPSC<string> }>();
+
+  const nullableCompletion = await StreamUtil.reduce<ChatCompletionChunk, Promise<ChatCompletion>>(stream, async (accPromise, chunk) => {
+    const acc = await accPromise;
+
+    const registerContext = (
+      choices: ChatCompletionChunk.Choice[],
+    ) => {
+      for (const choice of choices) {
+        /**
+         * @TODO fix it
+         * Sometimes, the complete message arrives along with a finish reason.
+         */
+        if (choice.finish_reason != null) {
+          const context = streamContext.get(choice.index);
+          if (context != null) {
+            context.mpsc.close();
+          }
+          continue;
+        }
+
+        if (choice.delta.content == null || choice.delta.content === "") {
+          continue;
+        }
+
+        if (streamContext.has(choice.index)) {
+          const context = streamContext.get(choice.index)!;
+          context.content += choice.delta.content;
+          context.mpsc.produce(choice.delta.content);
+          continue;
+        }
+
+        const mpsc = new MPSC<string>();
+
+        streamContext.set(choice.index, {
+          content: choice.delta.content,
+          mpsc,
+        });
+        mpsc.produce(choice.delta.content);
+
+        eventProcessor({
+          stream: streamDefaultReaderToAsyncGenerator(mpsc.consumer.getReader()),
+          done: () => mpsc.done(),
+          get: () => streamContext.get(choice.index)?.content ?? "",
+          join: async () => {
+            await mpsc.waitClosed();
+            return streamContext.get(choice.index)!.content;
+          },
+        });
+      }
+    };
+    if (acc.object === "chat.completion.chunk") {
+      registerContext([acc, chunk].flatMap(v => v.choices));
+      return ChatGptCompletionMessageUtil.merge([acc, chunk]);
+    }
+    registerContext(chunk.choices);
+    return ChatGptCompletionMessageUtil.accumulate(acc, chunk);
+  });
+
+  if (nullableCompletion == null) {
+    throw new Error(
+      "StreamUtil.reduce did not produce a ChatCompletion. Possible causes: the input stream was empty, invalid, or closed prematurely. "
+      + "To debug: check that the stream is properly initialized and contains valid ChatCompletionChunk data. "
+      + "You may also enable verbose logging upstream to inspect the stream contents. "
+      + `Stream locked: ${stream.locked}.`,
+    );
+  }
+  return nullableCompletion;
+}
+
+export { reduceStreamingWithDispatch };

package/src/utils/__retry.spec.ts

@@ -0,0 +1,198 @@
+import { __get_retry } from "./__retry";
+
+describe("__get_retry", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("success cases", () => {
+    it("should not retry when successful on first attempt", async () => {
+      const mockFn = vi.fn().mockResolvedValue("success");
+      const retryFn = __get_retry(3);
+
+      const result = await retryFn(mockFn);
+
+      expect(result).toBe("success");
+      expect(mockFn).toHaveBeenCalledTimes(1);
+      expect(mockFn).toHaveBeenCalledWith(undefined);
+    });
+
+    it("should call exactly 2 times when successful on second attempt", async () => {
+      const mockFn = vi.fn()
+        .mockRejectedValueOnce(new Error("First failure"))
+        .mockResolvedValue("success");
+      const retryFn = __get_retry(3);
+
+      const result = await retryFn(mockFn);
+
+      expect(result).toBe("success");
+      expect(mockFn).toHaveBeenCalledTimes(2);
+      expect(mockFn).toHaveBeenNthCalledWith(1, undefined);
+      expect(mockFn).toHaveBeenNthCalledWith(2, new Error("First failure"));
+    });
+
+    it("should call limit times when successful on last attempt", async () => {
+      const mockFn = vi.fn()
+        .mockRejectedValueOnce(new Error("First failure"))
+        .mockRejectedValueOnce(new Error("Second failure"))
+        .mockResolvedValue("success");
+      const retryFn = __get_retry(3);
+
+      const result = await retryFn(mockFn);
+
+      expect(result).toBe("success");
+      expect(mockFn).toHaveBeenCalledTimes(3);
+      expect(mockFn).toHaveBeenNthCalledWith(1, undefined);
+      expect(mockFn).toHaveBeenNthCalledWith(2, new Error("First failure"));
+      expect(mockFn).toHaveBeenNthCalledWith(3, new Error("Second failure"));
+    });
+  });
+
+  describe("failure cases", () => {
+    it("should throw last error after limit attempts", async () => {
+      const error1 = new Error("First failure");
+      const error2 = new Error("Second failure");
+      const error3 = new Error("Third failure");
+
+      const mockFn = vi.fn()
+        .mockRejectedValueOnce(error1)
+        .mockRejectedValueOnce(error2)
+        .mockRejectedValueOnce(error3);
+      const retryFn = __get_retry(3);
+
+      await expect(retryFn(mockFn)).rejects.toThrow("Third failure");
+      expect(mockFn).toHaveBeenCalledTimes(3);
+      expect(mockFn).toHaveBeenNthCalledWith(1, undefined);
+      expect(mockFn).toHaveBeenNthCalledWith(2, error1);
+      expect(mockFn).toHaveBeenNthCalledWith(3, error2);
+    });
+
+    it("should throw error immediately when limit is 1", async () => {
+      const error = new Error("Immediate failure");
+      const mockFn = vi.fn().mockRejectedValue(error);
+      const retryFn = __get_retry(1);
+
+      await expect(retryFn(mockFn)).rejects.toThrow("Immediate failure");
+      expect(mockFn).toHaveBeenCalledTimes(1);
+      expect(mockFn).toHaveBeenCalledWith(undefined);
+    });
+  });
+
+  describe("prevError propagation", () => {
+    it("should pass previous error as prevError correctly", async () => {
+      const error1 = new Error("First error");
+      const error2 = new Error("Second error");
+
+      const mockFn = vi.fn()
+        .mockRejectedValueOnce(error1)
+        .mockRejectedValueOnce(error2)
+        .mockResolvedValue("success");
+      const retryFn = __get_retry(3);
+
+      const result = await retryFn(mockFn);
+
+      expect(result).toBe("success");
+      expect(mockFn).toHaveBeenCalledTimes(3);
+      expect(mockFn).toHaveBeenNthCalledWith(1, undefined);
+      expect(mockFn).toHaveBeenNthCalledWith(2, error1);
+      expect(mockFn).toHaveBeenNthCalledWith(3, error2);
+    });
+
+    it("should use initial prevError in first call when provided", async () => {
+      const initialError = new Error("Initial error");
+      const mockFn = vi.fn().mockResolvedValue("success");
+      const retryFn = __get_retry(3);
+
+      const result = await retryFn(mockFn, initialError);
+
+      expect(result).toBe("success");
+      expect(mockFn).toHaveBeenCalledTimes(1);
+      expect(mockFn).toHaveBeenCalledWith(initialError);
+    });
+  });
+
+  describe("different error types", () => {
+    it("should handle string errors correctly", async () => {
+      const mockFn = vi.fn()
+        .mockRejectedValueOnce("String error")
+        .mockResolvedValue("success");
+      const retryFn = __get_retry(2);
+
+      const result = await retryFn(mockFn);
+
+      expect(result).toBe("success");
+      expect(mockFn).toHaveBeenCalledTimes(2);
+      expect(mockFn).toHaveBeenNthCalledWith(2, "String error");
+    });
+
+    it("should handle null errors correctly", async () => {
+      const mockFn = vi.fn()
+        .mockRejectedValueOnce(null)
+        .mockResolvedValue("success");
+      const retryFn = __get_retry(2);
+
+      const result = await retryFn(mockFn);
+
+      expect(result).toBe("success");
+      expect(mockFn).toHaveBeenCalledTimes(2);
+      expect(mockFn).toHaveBeenNthCalledWith(2, null);
+    });
+
+    it("should handle undefined errors correctly", async () => {
+      const mockFn = vi.fn()
+        .mockRejectedValueOnce(undefined)
+        .mockResolvedValue("success");
+      const retryFn = __get_retry(2);
+
+      const result = await retryFn(mockFn);
+
+      expect(result).toBe("success");
+      expect(mockFn).toHaveBeenCalledTimes(2);
+      expect(mockFn).toHaveBeenNthCalledWith(2, undefined);
+    });
+  });
+
+  describe("recursive call verification", () => {
+    it("should occur recursive calls in correct order", async () => {
+      const callOrder: string[] = [];
+      const mockFn = vi.fn()
+        .mockImplementationOnce(() => {
+          callOrder.push("first call");
+          throw new Error("First failure");
+        })
+        .mockImplementationOnce(() => {
+          callOrder.push("second call");
+          throw new Error("Second failure");
+        })
+        .mockImplementationOnce(async () => {
+          callOrder.push("third call");
+          return Promise.resolve("success");
+        });
+
+      const retryFn = __get_retry(3);
+      const result = await retryFn(mockFn);
+
+      expect(result).toBe("success");
+      expect(callOrder).toEqual(["first call", "second call", "third call"]);
+      expect(mockFn).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe("type safety", () => {
+    it("should handle different return types correctly", async () => {
+      const stringFn = vi.fn().mockResolvedValue("string result");
+      const numberFn = vi.fn().mockResolvedValue(42);
+      const objectFn = vi.fn().mockResolvedValue({ key: "value" });
+
+      const retryFn = __get_retry(3);
+
+      const stringResult = await retryFn(stringFn);
+      const numberResult = await retryFn(numberFn);
+      const objectResult = await retryFn(objectFn);
+
+      expect(stringResult).toBe("string result");
+      expect(numberResult).toBe(42);
+      expect(objectResult).toEqual({ key: "value" });
+    });
+  });
+});

package/src/utils/__retry.ts

@@ -0,0 +1,18 @@
+/**
+ * @internal
+ */
+export function __get_retry(limit: number) {
+  const retryFn = async <T>(fn: (prevError?: unknown) => Promise<T>, prevError?: unknown, attempt: number = 0): Promise<T> => {
+    try {
+      return await fn(prevError);
+    }
+    catch (error) {
+      if (attempt >= limit - 1) {
+        throw error;
+      }
+      return retryFn(fn, error, attempt + 1);
+    }
+  };
+
+  return retryFn;
+}