illuma-agents 1.0.2

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,60 @@
+import { ChatOpenAI } from '@/llm/openai';
+import type {
+  FunctionMessageChunk,
+  SystemMessageChunk,
+  HumanMessageChunk,
+  ToolMessageChunk,
+  ChatMessageChunk,
+  AIMessageChunk,
+} from '@langchain/core/messages';
+import type {
+  ChatOpenAICallOptions,
+  OpenAIChatInput,
+  OpenAIClient,
+} from '@langchain/openai';
+
+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
+    );
+    messageChunk.additional_kwargs.reasoning = delta.reasoning;
+    return messageChunk;
+  }
+}

package/src/llm/providers.ts

@@ -0,0 +1,57 @@
+// src/llm/providers.ts
+import { ChatMistralAI } from '@langchain/mistralai';
+import { ChatBedrockConverse } from '@langchain/aws';
+// import { ChatAnthropic } from '@langchain/anthropic';
+// import { ChatVertexAI } from '@langchain/google-vertexai';
+import { BedrockChat } from '@langchain/community/chat_models/bedrock/web';
+import type {
+  ChatModelConstructorMap,
+  ProviderOptionsMap,
+  ChatModelMap,
+} from '@/types';
+import {
+  AzureChatOpenAI,
+  ChatDeepSeek,
+  ChatOpenAI,
+  ChatXAI,
+} from '@/llm/openai';
+import { CustomChatGoogleGenerativeAI } from '@/llm/google';
+import { CustomAnthropic } from '@/llm/anthropic';
+import { ChatOpenRouter } from '@/llm/openrouter';
+import { ChatVertexAI } from '@/llm/vertexai';
+import { ChatOllama } from '@/llm/ollama';
+import { Providers } from '@/common';
+
+export const llmProviders: Partial<ChatModelConstructorMap> = {
+  [Providers.XAI]: ChatXAI,
+  [Providers.OPENAI]: ChatOpenAI,
+  [Providers.OLLAMA]: ChatOllama,
+  [Providers.AZURE]: AzureChatOpenAI,
+  [Providers.VERTEXAI]: ChatVertexAI,
+  [Providers.DEEPSEEK]: ChatDeepSeek,
+  [Providers.MISTRALAI]: ChatMistralAI,
+  [Providers.MISTRAL]: ChatMistralAI,
+  [Providers.ANTHROPIC]: CustomAnthropic,
+  [Providers.OPENROUTER]: ChatOpenRouter,
+  [Providers.BEDROCK_LEGACY]: BedrockChat,
+  [Providers.BEDROCK]: ChatBedrockConverse,
+  // [Providers.ANTHROPIC]: ChatAnthropic,
+  [Providers.GOOGLE]: CustomChatGoogleGenerativeAI,
+};
+
+export const manualToolStreamProviders = new Set<Providers | string>([
+  Providers.ANTHROPIC,
+  Providers.BEDROCK,
+  Providers.OLLAMA,
+]);
+
+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;
+    }
+  }
+}

package/src/llm/vertexai/index.ts

@@ -0,0 +1,360 @@
+import { ChatGoogle } from '@langchain/google-gauth';
+import { ChatConnection } from '@langchain/google-common';
+import type {
+  GeminiRequest,
+  GoogleAIModelRequestParams,
+  GoogleAbstractedClient,
+} from '@langchain/google-common';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { VertexAIClientOptions } from '@/types';
+
+class CustomChatConnection extends ChatConnection<VertexAIClientOptions> {
+  async formatData(
+    input: BaseMessage[],
+    parameters: GoogleAIModelRequestParams
+  ): Promise<unknown> {
+    const formattedData = (await super.formatData(
+      input,
+      parameters
+    )) as GeminiRequest;
+    if (
+      formattedData.generationConfig?.thinkingConfig?.thinkingBudget === -1 &&
+      formattedData.generationConfig.thinkingConfig.includeThoughts === false
+    ) {
+      formattedData.generationConfig.thinkingConfig.includeThoughts = true;
+    }
+    return formattedData;
+  }
+}
+
+/**
+ * Integration with Google Vertex AI chat models.
+ *
+ * Setup:
+ * Install `@langchain/google-vertexai` and set your stringified
+ * Vertex AI credentials as an environment variable named `GOOGLE_APPLICATION_CREDENTIALS`.
+ *
+ * ```bash
+ * npm install @langchain/google-vertexai
+ * export GOOGLE_APPLICATION_CREDENTIALS="path/to/credentials"
+ * ```
+ *
+ * ## [Constructor args](https://api.js.langchain.com/classes/_langchain_google_vertexai.index.ChatVertexAI.html#constructor.new_ChatVertexAI)
+ *
+ * ## [Runtime args](https://api.js.langchain.com/interfaces/langchain_google_common_types.GoogleAIBaseLanguageModelCallOptions.html)
+ *
+ * Runtime args can be passed as the second argument to any of the base runnable methods `.invoke`. `.stream`, `.batch`, etc.
+ * They can also be passed via `.withConfig`, or the second arg in `.bindTools`, like shown in the examples below:
+ *
+ * ```typescript
+ * // When calling `.withConfig`, call options should be passed via the first argument
+ * const llmWithArgsBound = llm.withConfig({
+ *   stop: ["\n"],
+ *   tools: [...],
+ * });
+ *
+ * // When calling `.bindTools`, call options should be passed via the second argument
+ * const llmWithTools = llm.bindTools(
+ *   [...],
+ *   {
+ *     tool_choice: "auto",
+ *   }
+ * );
+ * ```
+ *
+ * ## Examples
+ *
+ * <details open>
+ * <summary><strong>Instantiate</strong></summary>
+ *
+ * ```typescript
+ * import { ChatVertexAI } from '@langchain/google-vertexai';
+ *
+ * const llm = new ChatVertexAI({
+ *   model: "gemini-1.5-pro",
+ *   temperature: 0,
+ *   // other params...
+ * });
+ * ```
+ * </details>
+ *
+ * <br />
+ *
+ * <details>
+ * <summary><strong>Invoking</strong></summary>
+ *
+ * ```typescript
+ * const input = `Translate "I love programming" into French.`;
+ *
+ * // Models also accept a list of chat messages or a formatted prompt
+ * const result = await llm.invoke(input);
+ * console.log(result);
+ * ```
+ *
+ * ```txt
+ * AIMessageChunk {
+ *   "content": "\"J'adore programmer\" \n\nHere's why this is the best translation:\n\n* **J'adore** means \"I love\" and conveys a strong passion.\n* **Programmer** is the French verb for \"to program.\"\n\nThis translation is natural and idiomatic in French. \n",
+ *   "additional_kwargs": {},
+ *   "response_metadata": {},
+ *   "tool_calls": [],
+ *   "tool_call_chunks": [],
+ *   "invalid_tool_calls": [],
+ *   "usage_metadata": {
+ *     "input_tokens": 9,
+ *     "output_tokens": 63,
+ *     "total_tokens": 72
+ *   }
+ * }
+ * ```
+ * </details>
+ *
+ * <br />
+ *
+ * <details>
+ * <summary><strong>Streaming Chunks</strong></summary>
+ *
+ * ```typescript
+ * for await (const chunk of await llm.stream(input)) {
+ *   console.log(chunk);
+ * }
+ * ```
+ *
+ * ```txt
+ * AIMessageChunk {
+ *   "content": "\"",
+ *   "additional_kwargs": {},
+ *   "response_metadata": {},
+ *   "tool_calls": [],
+ *   "tool_call_chunks": [],
+ *   "invalid_tool_calls": []
+ * }
+ * AIMessageChunk {
+ *   "content": "J'adore programmer\" \n",
+ *   "additional_kwargs": {},
+ *   "response_metadata": {},
+ *   "tool_calls": [],
+ *   "tool_call_chunks": [],
+ *   "invalid_tool_calls": []
+ * }
+ * AIMessageChunk {
+ *   "content": "",
+ *   "additional_kwargs": {},
+ *   "response_metadata": {},
+ *   "tool_calls": [],
+ *   "tool_call_chunks": [],
+ *   "invalid_tool_calls": []
+ * }
+ * AIMessageChunk {
+ *   "content": "",
+ *   "additional_kwargs": {},
+ *   "response_metadata": {
+ *     "finishReason": "stop"
+ *   },
+ *   "tool_calls": [],
+ *   "tool_call_chunks": [],
+ *   "invalid_tool_calls": [],
+ *   "usage_metadata": {
+ *     "input_tokens": 9,
+ *     "output_tokens": 8,
+ *     "total_tokens": 17
+ *   }
+ * }
+ * ```
+ * </details>
+ *
+ * <br />
+ *
+ * <details>
+ * <summary><strong>Aggregate Streamed Chunks</strong></summary>
+ *
+ * ```typescript
+ * import { AIMessageChunk } from '@langchain/core/messages';
+ * import { concat } from '@langchain/core/utils/stream';
+ *
+ * const stream = await llm.stream(input);
+ * let full: AIMessageChunk | undefined;
+ * for await (const chunk of stream) {
+ *   full = !full ? chunk : concat(full, chunk);
+ * }
+ * console.log(full);
+ * ```
+ *
+ * ```txt
+ * AIMessageChunk {
+ *   "content": "\"J'adore programmer\" \n",
+ *   "additional_kwargs": {},
+ *   "response_metadata": {
+ *     "finishReason": "stop"
+ *   },
+ *   "tool_calls": [],
+ *   "tool_call_chunks": [],
+ *   "invalid_tool_calls": [],
+ *   "usage_metadata": {
+ *     "input_tokens": 9,
+ *     "output_tokens": 8,
+ *     "total_tokens": 17
+ *   }
+ * }
+ * ```
+ * </details>
+ *
+ * <br />
+ *
+ * <details>
+ * <summary><strong>Bind tools</strong></summary>
+ *
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const GetWeather = {
+ *   name: "GetWeather",
+ *   description: "Get the current weather in a given location",
+ *   schema: z.object({
+ *     location: z.string().describe("The city and state, e.g. San Francisco, CA")
+ *   }),
+ * }
+ *
+ * const GetPopulation = {
+ *   name: "GetPopulation",
+ *   description: "Get the current population in a given location",
+ *   schema: z.object({
+ *     location: z.string().describe("The city and state, e.g. San Francisco, CA")
+ *   }),
+ * }
+ *
+ * const llmWithTools = llm.bindTools([GetWeather, GetPopulation]);
+ * const aiMsg = await llmWithTools.invoke(
+ *   "Which city is hotter today and which is bigger: LA or NY?"
+ * );
+ * console.log(aiMsg.tool_calls);
+ * ```
+ *
+ * ```txt
+ * [
+ *   {
+ *     name: 'GetPopulation',
+ *     args: { location: 'New York City, NY' },
+ *     id: '33c1c1f47e2f492799c77d2800a43912',
+ *     type: 'tool_call'
+ *   }
+ * ]
+ * ```
+ * </details>
+ *
+ * <br />
+ *
+ * <details>
+ * <summary><strong>Structured Output</strong></summary>
+ *
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const Joke = z.object({
+ *   setup: z.string().describe("The setup of the joke"),
+ *   punchline: z.string().describe("The punchline to the joke"),
+ *   rating: z.number().optional().describe("How funny the joke is, from 1 to 10")
+ * }).describe('Joke to tell user.');
+ *
+ * const structuredLlm = llm.withStructuredOutput(Joke, { name: "Joke" });
+ * const jokeResult = await structuredLlm.invoke("Tell me a joke about cats");
+ * console.log(jokeResult);
+ * ```
+ *
+ * ```txt
+ * {
+ *   setup: 'What do you call a cat that loves to bowl?',
+ *   punchline: 'An alley cat!'
+ * }
+ * ```
+ * </details>
+ *
+ * <br />
+ *
+ * <details>
+ * <summary><strong>Usage Metadata</strong></summary>
+ *
+ * ```typescript
+ * const aiMsgForMetadata = await llm.invoke(input);
+ * console.log(aiMsgForMetadata.usage_metadata);
+ * ```
+ *
+ * ```txt
+ * { input_tokens: 9, output_tokens: 8, total_tokens: 17 }
+ * ```
+ * </details>
+ *
+ * <br />
+ *
+ * <details>
+ * <summary><strong>Stream Usage Metadata</strong></summary>
+ *
+ * ```typescript
+ * const streamForMetadata = await llm.stream(
+ *   input,
+ *   {
+ *     streamUsage: true
+ *   }
+ * );
+ * let fullForMetadata: AIMessageChunk | undefined;
+ * for await (const chunk of streamForMetadata) {
+ *   fullForMetadata = !fullForMetadata ? chunk : concat(fullForMetadata, chunk);
+ * }
+ * console.log(fullForMetadata?.usage_metadata);
+ * ```
+ *
+ * ```txt
+ * { input_tokens: 9, output_tokens: 8, total_tokens: 17 }
+ * ```
+ * </details>
+ *
+ * <br />
+ */
+export class ChatVertexAI extends ChatGoogle {
+  lc_namespace = ['langchain', 'chat_models', 'vertexai'];
+  dynamicThinkingBudget = false;
+
+  static lc_name(): 'IllumaVertexAI' {
+    return 'IllumaVertexAI';
+  }
+
+  constructor(fields?: VertexAIClientOptions) {
+    let dynamicThinkingBudget = false;
+    if (fields?.thinkingBudget === -1) {
+      dynamicThinkingBudget = true;
+      fields.thinkingBudget = 1;
+    }
+    super({
+      ...fields,
+      platformType: 'gcp',
+    });
+    this.dynamicThinkingBudget = dynamicThinkingBudget;
+  }
+  invocationParams(
+    options?: this['ParsedCallOptions'] | undefined
+  ): GoogleAIModelRequestParams {
+    const params = super.invocationParams(options);
+    if (this.dynamicThinkingBudget) {
+      params.maxReasoningTokens = -1;
+    }
+    return params;
+  }
+
+  buildConnection(
+    fields: VertexAIClientOptions,
+    client: GoogleAbstractedClient
+  ): void {
+    this.connection = new CustomChatConnection(
+      { ...fields, ...this },
+      this.caller,
+      client,
+      false
+    );
+
+    this.streamedConnection = new CustomChatConnection(
+      { ...fields, ...this },
+      this.caller,
+      client,
+      true
+    );
+  }
+}