@illuma-ai/agents 1.0.81

package/src/llm/openai/utils/isReasoningModel.test.ts

@@ -0,0 +1,90 @@
+import { isReasoningModel } from './index';
+
+describe('isReasoningModel', () => {
+  describe('should return true for reasoning models', () => {
+    test('basic o-series models', () => {
+      expect(isReasoningModel('o1')).toBe(true);
+      expect(isReasoningModel('o2')).toBe(true);
+      expect(isReasoningModel('o9')).toBe(true);
+      expect(isReasoningModel('o1-preview')).toBe(true);
+      expect(isReasoningModel('o1-mini')).toBe(true);
+    });
+
+    test('gpt-5+ models', () => {
+      expect(isReasoningModel('gpt-5')).toBe(true);
+      expect(isReasoningModel('gpt-6')).toBe(true);
+      expect(isReasoningModel('gpt-7')).toBe(true);
+      expect(isReasoningModel('gpt-8')).toBe(true);
+      expect(isReasoningModel('gpt-9')).toBe(true);
+    });
+
+    test('with provider prefixes', () => {
+      expect(isReasoningModel('azure/o1')).toBe(true);
+      expect(isReasoningModel('azure/gpt-5')).toBe(true);
+      expect(isReasoningModel('openai/o1')).toBe(true);
+      expect(isReasoningModel('openai/gpt-5')).toBe(true);
+    });
+
+    test('with custom prefixes', () => {
+      expect(isReasoningModel('custom-provider/o1')).toBe(true);
+      expect(isReasoningModel('my-deployment/gpt-5')).toBe(true);
+      expect(isReasoningModel('company/azure/gpt-5')).toBe(true);
+    });
+
+    test('case insensitive', () => {
+      expect(isReasoningModel('O1')).toBe(true);
+      expect(isReasoningModel('GPT-5')).toBe(true);
+      expect(isReasoningModel('gPt-6')).toBe(true);
+      expect(isReasoningModel('Azure/O1')).toBe(true);
+    });
+  });
+
+  describe('should return false for non-reasoning models', () => {
+    test('older GPT models', () => {
+      expect(isReasoningModel('gpt-3.5-turbo')).toBe(false);
+      expect(isReasoningModel('gpt-4')).toBe(false);
+      expect(isReasoningModel('gpt-4-turbo')).toBe(false);
+      expect(isReasoningModel('gpt-4o')).toBe(false);
+      expect(isReasoningModel('gpt-4o-mini')).toBe(false);
+    });
+
+    test('other model families', () => {
+      expect(isReasoningModel('claude-3')).toBe(false);
+      expect(isReasoningModel('claude-3-opus')).toBe(false);
+      expect(isReasoningModel('llama-2')).toBe(false);
+      expect(isReasoningModel('gemini-pro')).toBe(false);
+    });
+
+    test('partial matches that should not match', () => {
+      expect(isReasoningModel('proto1')).toBe(false);
+      expect(isReasoningModel('version-o1')).toBe(true);
+      expect(isReasoningModel('gpt-40')).toBe(false);
+      expect(isReasoningModel('gpt-3.5')).toBe(false);
+    });
+
+    test('empty, null, and undefined', () => {
+      expect(isReasoningModel('')).toBe(false);
+      expect(isReasoningModel()).toBe(false);
+      expect(isReasoningModel(undefined)).toBe(false);
+    });
+  });
+
+  describe('edge cases', () => {
+    test('with special characters', () => {
+      expect(isReasoningModel('deployment_o1_model')).toBe(false);
+      expect(isReasoningModel('gpt-5-deployment')).toBe(true);
+      expect(isReasoningModel('o1@latest')).toBe(true);
+      expect(isReasoningModel('gpt-5.0')).toBe(true);
+    });
+
+    test('word boundary behavior', () => {
+      // These should match because o1 and gpt-5 are whole words
+      expect(isReasoningModel('use-o1-model')).toBe(true);
+      expect(isReasoningModel('model-gpt-5-latest')).toBe(true);
+
+      // These should not match because o1/gpt-5 are not whole words
+      expect(isReasoningModel('proto1model')).toBe(false);
+      expect(isReasoningModel('supergpt-50')).toBe(false);
+    });
+  });
+});

package/src/llm/openrouter/index.ts

@@ -0,0 +1,291 @@
+import { ChatOpenAI } from '@/llm/openai';
+import { ChatGenerationChunk } from '@langchain/core/outputs';
+import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+import { AIMessageChunk as AIMessageChunkClass } from '@langchain/core/messages';
+import type {
+  FunctionMessageChunk,
+  SystemMessageChunk,
+  HumanMessageChunk,
+  ToolMessageChunk,
+  ChatMessageChunk,
+  AIMessageChunk,
+  BaseMessage,
+} from '@langchain/core/messages';
+import type {
+  ChatOpenAICallOptions,
+  OpenAIChatInput,
+  OpenAIClient,
+} from '@langchain/openai';
+import { _convertMessagesToOpenAIParams } from '@/llm/openai/utils';
+
+type OpenAICompletionParam =
+  OpenAIClient.Chat.Completions.ChatCompletionMessageParam;
+
+type OpenAIRoleEnum =
+  | 'system'
+  | 'developer'
+  | 'assistant'
+  | 'user'
+  | 'function'
+  | 'tool';
+
+export interface ChatOpenRouterCallOptions extends ChatOpenAICallOptions {
+  include_reasoning?: boolean;
+  modelKwargs?: OpenAIChatInput['modelKwargs'];
+}
+export class ChatOpenRouter extends ChatOpenAI {
+  constructor(_fields: Partial<ChatOpenRouterCallOptions>) {
+    const { include_reasoning, modelKwargs = {}, ...fields } = _fields;
+    super({
+      ...fields,
+      modelKwargs: {
+        ...modelKwargs,
+        include_reasoning,
+      },
+    });
+  }
+  static lc_name(): 'IllumaOpenRouter' {
+    return 'IllumaOpenRouter';
+  }
+  protected override _convertOpenAIDeltaToBaseMessageChunk(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    delta: Record<string, any>,
+    rawResponse: OpenAIClient.ChatCompletionChunk,
+    defaultRole?:
+      | 'function'
+      | 'user'
+      | 'system'
+      | 'developer'
+      | 'assistant'
+      | 'tool'
+  ):
+    | AIMessageChunk
+    | HumanMessageChunk
+    | SystemMessageChunk
+    | FunctionMessageChunk
+    | ToolMessageChunk
+    | ChatMessageChunk {
+    const messageChunk = super._convertOpenAIDeltaToBaseMessageChunk(
+      delta,
+      rawResponse,
+      defaultRole
+    );
+    if (delta.reasoning != null) {
+      messageChunk.additional_kwargs.reasoning = delta.reasoning;
+    }
+    if (delta.reasoning_details != null) {
+      messageChunk.additional_kwargs.reasoning_details =
+        delta.reasoning_details;
+    }
+    return messageChunk;
+  }
+
+  async *_streamResponseChunks2(
+    messages: BaseMessage[],
+    options: this['ParsedCallOptions'],
+    runManager?: CallbackManagerForLLMRun
+  ): AsyncGenerator<ChatGenerationChunk> {
+    const messagesMapped: OpenAICompletionParam[] =
+      _convertMessagesToOpenAIParams(messages, this.model, {
+        includeReasoningDetails: true,
+        convertReasoningDetailsToContent: true,
+      });
+
+    const params = {
+      ...this.invocationParams(options, {
+        streaming: true,
+      }),
+      messages: messagesMapped,
+      stream: true as const,
+    };
+    let defaultRole: OpenAIRoleEnum | undefined;
+
+    const streamIterable = await this.completionWithRetry(params, options);
+    let usage: OpenAIClient.Completions.CompletionUsage | undefined;
+
+    // Store reasoning_details keyed by unique identifier to prevent incorrect merging
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const reasoningTextByIndex: Map<number, Record<string, any>> = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const reasoningEncryptedById: Map<string, Record<string, any>> = new Map();
+
+    for await (const data of streamIterable) {
+      const choice = data.choices[0] as
+        | Partial<OpenAIClient.Chat.Completions.ChatCompletionChunk.Choice>
+        | undefined;
+      if (data.usage) {
+        usage = data.usage;
+      }
+      if (!choice) {
+        continue;
+      }
+
+      const { delta } = choice;
+      if (!delta) {
+        continue;
+      }
+
+      // Accumulate reasoning_details from each delta
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const deltaAny = delta as Record<string, any>;
+      // Extract current chunk's reasoning text for streaming (before accumulation)
+      let currentChunkReasoningText = '';
+      if (
+        deltaAny.reasoning_details != null &&
+        Array.isArray(deltaAny.reasoning_details)
+      ) {
+        for (const detail of deltaAny.reasoning_details) {
+          // For encrypted reasoning (thought signatures), store by ID - MUST be separate
+          if (detail.type === 'reasoning.encrypted' && detail.id) {
+            reasoningEncryptedById.set(detail.id, {
+              type: detail.type,
+              id: detail.id,
+              data: detail.data,
+              format: detail.format,
+              index: detail.index,
+            });
+          } else if (detail.type === 'reasoning.text') {
+            // Extract current chunk's text for streaming
+            currentChunkReasoningText += detail.text || '';
+            // For text reasoning, accumulate text by index for final message
+            const idx = detail.index ?? 0;
+            const existing = reasoningTextByIndex.get(idx);
+            if (existing) {
+              // Only append text, keep other fields from first entry
+              existing.text = (existing.text || '') + (detail.text || '');
+            } else {
+              reasoningTextByIndex.set(idx, {
+                type: detail.type,
+                text: detail.text || '',
+                format: detail.format,
+                index: idx,
+              });
+            }
+          }
+        }
+      }
+
+      const chunk = this._convertOpenAIDeltaToBaseMessageChunk(
+        delta,
+        data,
+        defaultRole
+      );
+
+      // For models that send reasoning_details (Gemini style) instead of reasoning (DeepSeek style),
+      // set the current chunk's reasoning text to additional_kwargs.reasoning for streaming
+      if (currentChunkReasoningText && !chunk.additional_kwargs.reasoning) {
+        chunk.additional_kwargs.reasoning = currentChunkReasoningText;
+      }
+
+      // IMPORTANT: Only set reasoning_details on the FINAL chunk to prevent
+      // LangChain's chunk concatenation from corrupting the array
+      // Check if this is the final chunk (has finish_reason)
+      if (choice.finish_reason != null) {
+        // Build properly structured reasoning_details array
+        // Text entries first (but we only need the encrypted ones for thought signatures)
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const finalReasoningDetails: Record<string, any>[] = [
+          ...reasoningTextByIndex.values(),
+          ...reasoningEncryptedById.values(),
+        ];
+
+        if (finalReasoningDetails.length > 0) {
+          chunk.additional_kwargs.reasoning_details = finalReasoningDetails;
+        }
+      } else {
+        // Clear reasoning_details from intermediate chunks to prevent concatenation issues
+        delete chunk.additional_kwargs.reasoning_details;
+      }
+
+      defaultRole = delta.role ?? defaultRole;
+      const newTokenIndices = {
+        prompt: options.promptIndex ?? 0,
+        completion: choice.index ?? 0,
+      };
+      if (typeof chunk.content !== 'string') {
+        // eslint-disable-next-line no-console
+        console.log(
+          '[WARNING]: Received non-string content from OpenAI. This is currently not supported.'
+        );
+        continue;
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const generationInfo: Record<string, any> = { ...newTokenIndices };
+      if (choice.finish_reason != null) {
+        generationInfo.finish_reason = choice.finish_reason;
+        generationInfo.system_fingerprint = data.system_fingerprint;
+        generationInfo.model_name = data.model;
+        generationInfo.service_tier = data.service_tier;
+      }
+      if (this.logprobs == true) {
+        generationInfo.logprobs = choice.logprobs;
+      }
+      const generationChunk = new ChatGenerationChunk({
+        message: chunk,
+        text: chunk.content,
+        generationInfo,
+      });
+      yield generationChunk;
+      if (this._lc_stream_delay != null) {
+        await new Promise((resolve) =>
+          setTimeout(resolve, this._lc_stream_delay)
+        );
+      }
+      await runManager?.handleLLMNewToken(
+        generationChunk.text || '',
+        newTokenIndices,
+        undefined,
+        undefined,
+        undefined,
+        { chunk: generationChunk }
+      );
+    }
+    if (usage) {
+      const inputTokenDetails = {
+        ...(usage.prompt_tokens_details?.audio_tokens != null && {
+          audio: usage.prompt_tokens_details.audio_tokens,
+        }),
+        ...(usage.prompt_tokens_details?.cached_tokens != null && {
+          cache_read: usage.prompt_tokens_details.cached_tokens,
+        }),
+      };
+      const outputTokenDetails = {
+        ...(usage.completion_tokens_details?.audio_tokens != null && {
+          audio: usage.completion_tokens_details.audio_tokens,
+        }),
+        ...(usage.completion_tokens_details?.reasoning_tokens != null && {
+          reasoning: usage.completion_tokens_details.reasoning_tokens,
+        }),
+      };
+      const generationChunk = new ChatGenerationChunk({
+        message: new AIMessageChunkClass({
+          content: '',
+          response_metadata: {
+            usage: { ...usage },
+          },
+          usage_metadata: {
+            input_tokens: usage.prompt_tokens,
+            output_tokens: usage.completion_tokens,
+            total_tokens: usage.total_tokens,
+            ...(Object.keys(inputTokenDetails).length > 0 && {
+              input_token_details: inputTokenDetails,
+            }),
+            ...(Object.keys(outputTokenDetails).length > 0 && {
+              output_token_details: outputTokenDetails,
+            }),
+          },
+        }),
+        text: '',
+      });
+      yield generationChunk;
+      if (this._lc_stream_delay != null) {
+        await new Promise((resolve) =>
+          setTimeout(resolve, this._lc_stream_delay)
+        );
+      }
+    }
+    if (options.signal?.aborted === true) {
+      throw new Error('AbortError');
+    }
+  }
+}

package/src/llm/providers.ts

@@ -0,0 +1,52 @@
+// src/llm/providers.ts
+import { ChatMistralAI } from '@langchain/mistralai';
+import type {
+  ChatModelConstructorMap,
+  ProviderOptionsMap,
+  ChatModelMap,
+} from '@/types';
+import {
+  AzureChatOpenAI,
+  ChatDeepSeek,
+  ChatMoonshot,
+  ChatOpenAI,
+  ChatXAI,
+} from '@/llm/openai';
+import { CustomChatGoogleGenerativeAI } from '@/llm/google';
+import { CustomChatBedrockConverse } from '@/llm/bedrock';
+import { CustomAnthropic } from '@/llm/anthropic';
+import { ChatOpenRouter } from '@/llm/openrouter';
+import { ChatVertexAI } from '@/llm/vertexai';
+import { Providers } from '@/common';
+
+export const llmProviders: Partial<ChatModelConstructorMap> = {
+  [Providers.XAI]: ChatXAI,
+  [Providers.OPENAI]: ChatOpenAI,
+  [Providers.AZURE]: AzureChatOpenAI,
+  [Providers.VERTEXAI]: ChatVertexAI,
+  [Providers.DEEPSEEK]: ChatDeepSeek,
+  [Providers.MISTRALAI]: ChatMistralAI,
+  [Providers.MISTRAL]: ChatMistralAI,
+  [Providers.ANTHROPIC]: CustomAnthropic,
+  [Providers.OPENROUTER]: ChatOpenRouter,
+  [Providers.BEDROCK]: CustomChatBedrockConverse,
+  // [Providers.ANTHROPIC]: ChatAnthropic,
+  [Providers.GOOGLE]: CustomChatGoogleGenerativeAI,
+  [Providers.MOONSHOT]: ChatMoonshot,
+};
+
+export const manualToolStreamProviders = new Set<Providers | string>([
+  Providers.ANTHROPIC,
+  Providers.BEDROCK,
+]);
+
+export const getChatModelClass = <P extends Providers>(
+  provider: P
+): new (config: ProviderOptionsMap[P]) => ChatModelMap[P] => {
+  const ChatModelClass = llmProviders[provider];
+  if (!ChatModelClass) {
+    throw new Error(`Unsupported LLM provider: ${provider}`);
+  }
+
+  return ChatModelClass;
+};

package/src/llm/text.ts

@@ -0,0 +1,94 @@
+export interface TextStreamOptions {
+  minChunkSize?: number;
+  maxChunkSize?: number;
+  delay?: number;
+  firstWordChunk?: boolean;
+}
+
+export type ProgressCallback = (chunk: string) => void;
+export type PostChunkCallback = (chunk: string) => void;
+
+export class TextStream {
+  private text: string;
+  private currentIndex: number;
+  private minChunkSize: number;
+  private maxChunkSize: number;
+  private delay: number;
+  private firstWordChunk: boolean;
+
+  constructor(text: string, options: TextStreamOptions = {}) {
+    this.text = text;
+    this.currentIndex = 0;
+    this.minChunkSize = options.minChunkSize ?? 4;
+    this.maxChunkSize = options.maxChunkSize ?? 8;
+    this.delay = options.delay ?? 20;
+    this.firstWordChunk = options.firstWordChunk ?? true;
+  }
+
+  private randomInt(min: number, max: number): number {
+    return Math.floor(Math.random() * (max - min)) + min;
+  }
+
+  private static readonly BOUNDARIES = new Set([
+    ' ',
+    '.',
+    ',',
+    '!',
+    '?',
+    ';',
+    ':',
+  ]);
+
+  private findFirstWordBoundary(text: string, minSize: number): number {
+    if (minSize >= text.length) return text.length;
+
+    // Ensure we meet the minimum size first
+    let pos = minSize;
+
+    // Look forward until we find a boundary
+    while (pos < text.length) {
+      if (TextStream.BOUNDARIES.has(text[pos])) {
+        return pos + 1; // Include the boundary character
+      }
+      pos++;
+    }
+
+    return text.length; // If no boundary found, return entire remaining text
+  }
+
+  async *generateText(
+    signal?: AbortSignal,
+    progressCallback?: ProgressCallback
+  ): AsyncGenerator<string, void, unknown> {
+    const { delay, minChunkSize, maxChunkSize } = this;
+
+    while (this.currentIndex < this.text.length) {
+      if (signal?.aborted === true) {
+        break;
+      }
+      await new Promise((resolve) => setTimeout(resolve, delay));
+
+      const remainingText = this.text.slice(this.currentIndex);
+      let chunkSize: number;
+
+      if (this.firstWordChunk) {
+        chunkSize = this.findFirstWordBoundary(remainingText, minChunkSize);
+      } else {
+        const remainingChars = remainingText.length;
+        chunkSize = Math.min(
+          this.randomInt(minChunkSize, maxChunkSize + 1),
+          remainingChars
+        );
+      }
+
+      const chunk = this.text.slice(
+        this.currentIndex,
+        this.currentIndex + chunkSize
+      );
+      progressCallback?.(chunk);
+
+      yield chunk;
+      this.currentIndex += chunkSize;
+    }
+  }
+}