@illuma-ai/agents 1.0.81

package/src/utils/llmConfig.ts

@@ -0,0 +1,208 @@
+// src/utils/llmConfig.ts
+import { Providers } from '@/common';
+import type * as or from '@/llm/openrouter';
+import type * as t from '@/types';
+
+export const llmConfigs: Record<string, t.LLMConfig | undefined> = {
+  [Providers.OPENAI]: {
+    provider: Providers.OPENAI,
+    model: 'gpt-4.1',
+    // temperature: 0.7,
+    streaming: true,
+    streamUsage: true,
+    // disableStreaming: true,
+  },
+  anthropicLITELLM: {
+    provider: Providers.OPENAI,
+    streaming: true,
+    streamUsage: false,
+    apiKey: 'sk-1234',
+    model: 'claude-sonnet-4',
+    maxTokens: 8192,
+    modelKwargs: {
+      metadata: {
+        user_id: 'some_user_id',
+      },
+      thinking: {
+        type: 'enabled',
+        budget_tokens: 2000,
+      },
+    },
+    configuration: {
+      baseURL: 'http://host.docker.internal:4000/v1',
+      defaultHeaders: {
+        'anthropic-beta': 'prompt-caching-2024-07-31,context-1m-2025-08-07',
+      },
+    },
+    // disableStreaming: true,
+  },
+  [Providers.XAI]: {
+    provider: Providers.XAI,
+    model: 'grok-2-latest',
+    streaming: true,
+    streamUsage: true,
+  },
+  alibaba: {
+    provider: Providers.OPENAI,
+    streaming: true,
+    streamUsage: true,
+    model: 'qwen-max',
+    openAIApiKey: process.env.ALIBABA_API_KEY,
+    configuration: {
+      baseURL: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1',
+    },
+  },
+  [Providers.OPENROUTER]: {
+    provider: Providers.OPENROUTER,
+    streaming: true,
+    streamUsage: true,
+    // model: 'anthropic/claude-sonnet-4',
+    // model: 'moonshotai/kimi-k2-thinking',
+    model: 'google/gemini-3-pro-preview',
+    apiKey: process.env.OPENROUTER_API_KEY,
+    configuration: {
+      baseURL: process.env.OPENROUTER_BASE_URL,
+      defaultHeaders: {
+        'HTTP-Referer': 'https://illuma.ai',
+        'X-Title': 'Illuma',
+      },
+    },
+    include_reasoning: true,
+    modelKwargs: {
+      reasoning: {
+        max_tokens: 8000,
+      },
+      max_tokens: 10000,
+    },
+  } as or.ChatOpenRouterCallOptions & t.LLMConfig,
+  [Providers.AZURE]: {
+    provider: Providers.AZURE,
+    temperature: 0.7,
+    streaming: true,
+    streamUsage: true,
+    azureOpenAIApiKey: process.env.AZURE_OPENAI_API_KEY,
+    azureOpenAIApiInstanceName: process.env.AZURE_OPENAI_API_INSTANCE,
+    azureOpenAIApiDeploymentName: process.env.AZURE_OPENAI_API_DEPLOYMENT,
+    azureOpenAIApiVersion: process.env.AZURE_OPENAI_API_VERSION,
+    model: process.env.AZURE_MODEL_NAME ?? 'gpt-4o',
+  },
+  ollama: {
+    provider: Providers.OPENAI,
+    model: 'gpt-oss:20b',
+    streaming: true,
+    streamUsage: true,
+    configuration: {
+      baseURL: 'http://localhost:11434/v1',
+    },
+  },
+  lmstudio: {
+    provider: Providers.OPENAI,
+    model: 'gpt-oss-20b',
+    streaming: true,
+    streamUsage: true,
+    configuration: {
+      baseURL: 'http://192.168.254.183:1233/v1',
+    },
+  },
+  zhipu: {
+    provider: Providers.OPENAI,
+    streaming: true,
+    streamUsage: false,
+    model: 'glm-4.5-air',
+    apiKey: process.env.ZHIPU_API_KEY,
+    configuration: {
+      baseURL: 'https://open.bigmodel.cn/api/paas/v4',
+    },
+  },
+  [Providers.DEEPSEEK]: {
+    provider: Providers.DEEPSEEK,
+    model: 'deepseek-reasoner',
+    streaming: true,
+    streamUsage: true,
+  },
+  [Providers.MOONSHOT]: {
+    provider: Providers.MOONSHOT,
+    model: 'kimi-k2.5',
+    streaming: true,
+    streamUsage: true,
+    configuration: {
+      apiKey: process.env.MOONSHOT_API_KEY,
+      baseURL: 'https://api.moonshot.ai/v1',
+    },
+  },
+  [Providers.ANTHROPIC]: {
+    provider: Providers.ANTHROPIC,
+    model: 'claude-sonnet-4-5',
+    streaming: true,
+    streamUsage: true,
+  },
+  // [Providers.MISTRALAI]: {
+  //   provider: Providers.MISTRALAI,
+  //   model: 'mistral-large-latest',
+  //   streaming: true,
+  //   streamUsage: true,
+  // },
+  [Providers.MISTRAL]: {
+    provider: Providers.OPENAI,
+    streaming: true,
+    streamUsage: false,
+    // model: 'codestral-latest',
+    model: 'mistral-large-latest',
+    openAIApiKey: process.env.MISTRAL_API_KEY,
+    configuration: {
+      baseURL: 'https://api.mistral.ai/v1',
+      defaultHeaders: {},
+    },
+  },
+  [Providers.VERTEXAI]: {
+    provider: Providers.VERTEXAI,
+    model: 'gemini-2.5-flash',
+    // model: 'gemini-2.5-pro',
+    streaming: true,
+    streamUsage: true,
+    keyFile: process.env.VERTEXAI_KEY_FILE,
+    // maxRetries: 2,
+    // location: 'global',
+    // thinkingBudget: -1,
+    // includeThoughts: true,
+  } as t.VertexAIClientOptions & t.LLMConfig,
+  [Providers.GOOGLE]: {
+    provider: Providers.GOOGLE,
+    model: 'gemini-2.5-flash',
+    streaming: true,
+    streamUsage: true,
+  },
+  [Providers.BEDROCK]: {
+    provider: Providers.BEDROCK,
+    // model: 'anthropic.claude-3-sonnet-20240229-v1:0',
+    // model: 'us.anthropic.claude-3-5-sonnet-20241022-v2:0',
+    // model: 'us.amazon.nova-pro-v1:0',
+    model: 'us.anthropic.claude-sonnet-4-20250514-v1:0',
+    // additionalModelRequestFields: { thinking: { type: 'enabled', budget_tokens: 2000 } },
+    region: process.env.BEDROCK_AWS_REGION,
+    credentials: {
+      accessKeyId: process.env.BEDROCK_AWS_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.BEDROCK_AWS_SECRET_ACCESS_KEY!,
+    },
+    streaming: true,
+    streamUsage: true,
+  },
+  perplexity: {
+    provider: Providers.OPENAI,
+    model: 'llama-3.1-sonar-small-128k-online',
+    streaming: true,
+    streamUsage: true,
+    apiKey: process.env.PERPLEXITY_API_KEY,
+    configuration: {
+      baseURL: 'https://api.perplexity.ai/',
+    },
+  },
+};
+
+export function getLLMConfig(provider: string): t.LLMConfig {
+  const config = llmConfigs[provider];
+  if (config === undefined) {
+    throw new Error(`Unsupported provider: ${provider}`);
+  }
+  return config;
+}

package/src/utils/logging.ts

@@ -0,0 +1,48 @@
+// src/utils/logging.ts
+import fs from 'fs';
+import util from 'util';
+
+export function setupLogging(logFileName: string): void {
+  const logFile = fs.createWriteStream(logFileName, { flags: 'a' });
+
+  const originalConsoleLog = console.log;
+  const originalConsoleError = console.error;
+  const originalStdoutWrite = process.stdout.write;
+  const originalStderrWrite = process.stderr.write;
+
+  console.log = function(...args): void {
+    logFile.write(util.format.apply(null, args) + ' ');
+    originalConsoleLog.apply(console, args);
+  };
+
+  console.error = function(...args): void {
+    logFile.write(util.format.apply(null, args) + ' ');
+    originalConsoleError.apply(console, args);
+  };
+
+  process.stdout.write = function(
+    buffer: Uint8Array | string,
+    cb?: ((err?: Error) => void) | string,
+    fd?: ((err?: Error) => void)
+  ): boolean {
+    if (typeof buffer === 'string') {
+      logFile.write(buffer);
+    } else {
+      logFile.write(buffer.toString());
+    }
+    return originalStdoutWrite.call(process.stdout, buffer, cb as BufferEncoding | undefined, fd);
+  };
+
+  process.stderr.write = function(
+    buffer: Uint8Array | string,
+    cb?: ((err?: Error) => void) | string,
+    fd?: ((err?: Error) => void)
+  ): boolean {
+    if (typeof buffer === 'string') {
+      logFile.write(buffer);
+    } else {
+      logFile.write(buffer.toString());
+    }
+    return originalStderrWrite.call(process.stderr, buffer, cb as BufferEncoding | undefined, fd);
+  };
+}

package/src/utils/misc.ts

@@ -0,0 +1,57 @@
+export function isPresent(value: string | null | undefined): value is string {
+  return value != null && value !== '';
+}
+
+/**
+ * Unescapes a c-escaped string
+ * @param str The string to unescape
+ * @returns The unescaped string
+ */
+const unescapeString = (string: string): string =>
+  string.replace(/\\(.)/g, (_, char) => {
+    switch (char) {
+    case 'n':
+      return '\n';
+    case 't':
+      return '\t';
+    case 'r':
+      return '\r';
+    case '"':
+      return '"';
+    case '\'':
+      return '\'';
+    case '\\':
+      return '\\';
+    default:
+      return char;
+    }
+  });
+
+/**
+ * Recursively unescapes all string values in an object
+ * @param obj The object to unescape
+ * @returns The unescaped object
+ */
+export function unescapeObject(obj: unknown, key?: string): unknown {
+  if (typeof obj === 'string') {
+    let unescaped = unescapeString(obj);
+    if (key === 'filePath' && unescaped.match(/^"(.+)"$/)) {
+      unescaped = unescaped.substring(1, unescaped.length - 1);
+    }
+    return unescaped;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((value) =>
+      unescapeObject(value, key === 'contextPaths' ? 'filePath' : '')
+    );
+  }
+  if (typeof obj === 'object' && obj !== null) {
+    return Object.fromEntries(
+      Object.entries(obj).map(([key, value]) => [
+        key,
+        unescapeObject(value, key),
+      ])
+    );
+  }
+  return obj;
+}

package/src/utils/run.ts

@@ -0,0 +1,106 @@
+import { CallbackManagerForChainRun } from '@langchain/core/callbacks/manager';
+import {
+  mergeConfigs,
+  patchConfig,
+  Runnable,
+  RunnableConfig,
+} from '@langchain/core/runnables';
+import { AsyncLocalStorageProviderSingleton } from '@langchain/core/singletons';
+
+/**
+ * Delays the execution for a specified number of milliseconds.
+ *
+ * @param {number} ms - The number of milliseconds to delay.
+ * @return {Promise<void>} A promise that resolves after the specified delay.
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface RunnableCallableArgs extends Partial<any> {
+  name?: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  func: (...args: any[]) => any;
+  tags?: string[];
+  trace?: boolean;
+  recurse?: boolean;
+}
+
+export class RunnableCallable<I = unknown, O = unknown> extends Runnable<I, O> {
+  lc_namespace: string[] = ['langgraph'];
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  func: (...args: any[]) => any;
+
+  tags?: string[];
+
+  config?: RunnableConfig;
+
+  trace: boolean = true;
+
+  recurse: boolean = true;
+
+  constructor(fields: RunnableCallableArgs) {
+    super();
+    this.name = fields.name ?? fields.func.name;
+    this.func = fields.func;
+    this.config = fields.tags ? { tags: fields.tags } : undefined;
+    this.trace = fields.trace ?? this.trace;
+    this.recurse = fields.recurse ?? this.recurse;
+  }
+
+  protected async _tracedInvoke(
+    input: I,
+    config?: Partial<RunnableConfig>,
+    runManager?: CallbackManagerForChainRun
+  ): Promise<O> {
+    return new Promise<O>((resolve, reject) => {
+      // Defensive check: ensure runManager has getChild method before calling
+      const childCallbacks =
+        typeof runManager?.getChild === 'function'
+          ? runManager.getChild()
+          : undefined;
+      const childConfig = patchConfig(config, {
+        callbacks: childCallbacks,
+      });
+      void AsyncLocalStorageProviderSingleton.runWithConfig(
+        childConfig,
+        async () => {
+          try {
+            const output = await this.func(input, childConfig);
+            resolve(output);
+          } catch (e) {
+            reject(e);
+          }
+        }
+      );
+    });
+  }
+
+  async invoke(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    input: any,
+    options?: Partial<RunnableConfig> | undefined
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): Promise<any> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let returnValue: any;
+
+    if (this.trace) {
+      returnValue = await this._callWithConfig(
+        this._tracedInvoke,
+        input,
+        mergeConfigs(this.config, options)
+      );
+    } else {
+      returnValue = await this.func(input, mergeConfigs(this.config, options));
+    }
+
+    if (Runnable.isRunnable(returnValue) && this.recurse) {
+      return await returnValue.invoke(input, options);
+    }
+
+    return returnValue;
+  }
+}

package/src/utils/schema.ts

@@ -0,0 +1,35 @@
+// src/utils/schema.ts
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import type { ZodTypeAny } from 'zod';
+
+/** Checks if a schema is a Zod schema by looking for the _def property */
+export function isZodSchema(schema: unknown): schema is ZodTypeAny {
+  return (
+    schema != null && typeof schema === 'object' && '_def' in (schema as object)
+  );
+}
+
+/**
+ * Converts a schema to JSON schema format.
+ * Handles both Zod schemas (converts) and JSON schemas (passthrough).
+ */
+export function toJsonSchema(
+  schema: unknown,
+  name?: string,
+  description?: string
+): Record<string, unknown> {
+  if (isZodSchema(schema)) {
+    const zodSchema = schema as ZodTypeAny & {
+      describe: (desc: string) => ZodTypeAny;
+    };
+    const described =
+      description != null && description !== ''
+        ? zodSchema.describe(description)
+        : schema;
+    return zodToJsonSchema(
+      described as Parameters<typeof zodToJsonSchema>[0],
+      name ?? ''
+    );
+  }
+  return schema as Record<string, unknown>;
+}

package/src/utils/title.ts

@@ -0,0 +1,177 @@
+import { ChatPromptTemplate } from '@langchain/core/prompts';
+import { RunnableLambda, RunnableSequence } from '@langchain/core/runnables';
+import type { Runnable, RunnableConfig } from '@langchain/core/runnables';
+import type { AIMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ContentTypes } from '@/common';
+
+const defaultTitlePrompt = `Analyze this conversation and provide:
+1. The detected language of the conversation
+2. A concise title in the detected language (5 words or less, no punctuation or quotation)
+
+{convo}`;
+
+const titleSchema = {
+  type: 'object',
+  properties: {
+    title: {
+      type: 'string',
+      description:
+        'A concise title for the conversation in 5 words or less, without punctuation or quotation',
+    },
+  },
+  required: ['title'],
+} as const;
+
+const combinedSchema = {
+  type: 'object',
+  properties: {
+    language: {
+      type: 'string',
+      description: 'The detected language of the conversation',
+    },
+    title: {
+      type: 'string',
+      description:
+        'A concise title for the conversation in 5 words or less, without punctuation or quotation',
+    },
+  },
+  required: ['language', 'title'],
+} as const;
+
+export const createTitleRunnable = async (
+  model: t.ChatModelInstance,
+  _titlePrompt?: string
+): Promise<Runnable> => {
+  // Disabled since this works fine
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  /* @ts-ignore */
+  const titleLLM = model.withStructuredOutput(titleSchema);
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  /* @ts-ignore */
+  const combinedLLM = model.withStructuredOutput(combinedSchema);
+
+  const titlePrompt = ChatPromptTemplate.fromTemplate(
+    _titlePrompt ?? defaultTitlePrompt
+  ).withConfig({ runName: 'TitlePrompt' });
+
+  const titleOnlyInnerChain = RunnableSequence.from([titlePrompt, titleLLM]);
+  const combinedInnerChain = RunnableSequence.from([titlePrompt, combinedLLM]);
+
+  /** Wrap titleOnlyChain in RunnableLambda to create parent span */
+  const titleOnlyChain = new RunnableLambda({
+    func: async (
+      input: { convo: string },
+      config?: Partial<RunnableConfig>
+    ): Promise<{ title: string }> => {
+      const result = await titleOnlyInnerChain.invoke(input, config);
+      return result as { title: string };
+    },
+  }).withConfig({ runName: 'TitleOnlyChain' });
+
+  /** Wrap combinedChain in RunnableLambda to create parent span */
+  const combinedChain = new RunnableLambda({
+    func: async (
+      input: { convo: string },
+      config?: Partial<RunnableConfig>
+    ): Promise<{ language: string; title: string }> => {
+      const result = await combinedInnerChain.invoke(input, config);
+      return result as { language: string; title: string };
+    },
+  }).withConfig({ runName: 'TitleLanguageChain' });
+
+  /** Runnable to add default values if needed */
+  const addDefaults = new RunnableLambda({
+    func: (
+      result: { language: string; title: string } | undefined
+    ): { language: string; title: string } => ({
+      language: result?.language ?? 'English',
+      title: result?.title ?? '',
+    }),
+  }).withConfig({ runName: 'AddDefaults' });
+
+  const combinedChainInner = RunnableSequence.from([
+    combinedChain,
+    addDefaults,
+  ]);
+
+  /** Wrap combinedChainWithDefaults in RunnableLambda to create parent span */
+  const combinedChainWithDefaults = new RunnableLambda({
+    func: async (
+      input: { convo: string },
+      config?: Partial<RunnableConfig>
+    ): Promise<{ language: string; title: string }> => {
+      return await combinedChainInner.invoke(input, config);
+    },
+  }).withConfig({ runName: 'CombinedChainWithDefaults' });
+
+  return new RunnableLambda({
+    func: async (
+      input: {
+        convo: string;
+        inputText: string;
+        skipLanguage: boolean;
+      },
+      config?: Partial<RunnableConfig>
+    ): Promise<{ language: string; title: string } | { title: string }> => {
+      const invokeInput = { convo: input.convo };
+
+      if (input.skipLanguage) {
+        return (await titleOnlyChain.invoke(invokeInput, config)) as {
+          title: string;
+        };
+      }
+
+      return await combinedChainWithDefaults.invoke(invokeInput, config);
+    },
+  }).withConfig({ runName: 'TitleGenerator' });
+};
+
+const defaultCompletionPrompt = `Provide a concise, 5-word-or-less title for the conversation, using title case conventions. Only return the title itself.
+
+Conversation:
+{convo}`;
+
+export const createCompletionTitleRunnable = async (
+  model: t.ChatModelInstance,
+  titlePrompt?: string
+): Promise<Runnable> => {
+  const completionPrompt = ChatPromptTemplate.fromTemplate(
+    titlePrompt ?? defaultCompletionPrompt
+  ).withConfig({ runName: 'CompletionTitlePrompt' });
+
+  /** Runnable to extract content from model response */
+  const extractContent = new RunnableLambda({
+    func: (response: AIMessage): { title: string } => {
+      let content = '';
+      if (typeof response.content === 'string') {
+        content = response.content;
+      } else if (Array.isArray(response.content)) {
+        content = response.content
+          .filter(
+            (part): part is { type: ContentTypes.TEXT; text: string } =>
+              part.type === ContentTypes.TEXT
+          )
+          .map((part) => part.text)
+          .join('');
+      }
+      return { title: content.trim() };
+    },
+  }).withConfig({ runName: 'ExtractTitle' });
+
+  const innerChain = RunnableSequence.from([
+    completionPrompt,
+    model,
+    extractContent,
+  ]);
+
+  /** Wrap in RunnableLambda to create a parent span for LangFuse */
+  return new RunnableLambda({
+    func: async (
+      input: { convo: string },
+      config?: Partial<RunnableConfig>
+    ): Promise<{ title: string }> => {
+      return await innerChain.invoke(input, config);
+    },
+  }).withConfig({ runName: 'CompletionTitleChain' });
+};