illuma-agents 1.0.2

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,101 @@
+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) => {
+      const childConfig = patchConfig(config, {
+        callbacks: runManager?.getChild(),
+      });
+      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/title.ts

@@ -0,0 +1,165 @@
+import { z } from 'zod';
+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 = z.object({
+  title: z
+    .string()
+    .describe(
+      'A concise title for the conversation in 5 words or less, without punctuation or quotation'
+    ),
+});
+
+const combinedSchema = z.object({
+  language: z.string().describe('The detected language of the conversation'),
+  title: z
+    .string()
+    .describe(
+      'A concise title for the conversation in 5 words or less, without punctuation or quotation'
+    ),
+});
+
+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 }> => {
+      return await titleOnlyInnerChain.invoke(input, config);
+    },
+  }).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 }> => {
+      return await combinedInnerChain.invoke(input, config);
+    },
+  }).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' });
+};

package/src/utils/tokens.ts

@@ -0,0 +1,70 @@
+import { Tiktoken } from 'js-tiktoken/lite';
+import type { BaseMessage } from '@langchain/core/messages';
+import { ContentTypes } from '@/common/enum';
+
+export function getTokenCountForMessage(message: BaseMessage, getTokenCount: (text: string) => number): number {
+  const tokensPerMessage = 3;
+
+  const processValue = (value: unknown): void => {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (
+          !item ||
+          !item.type ||
+          item.type === ContentTypes.ERROR ||
+          item.type === ContentTypes.IMAGE_URL
+        ) {
+          continue;
+        }
+
+        if (item.type === ContentTypes.TOOL_CALL && item.tool_call != null) {
+          const toolName = item.tool_call?.name || '';
+          if (toolName != null && toolName && typeof toolName === 'string') {
+            numTokens += getTokenCount(toolName);
+          }
+
+          const args = item.tool_call?.args || '';
+          if (args != null && args && typeof args === 'string') {
+            numTokens += getTokenCount(args);
+          }
+
+          const output = item.tool_call?.output || '';
+          if (output != null && output && typeof output === 'string') {
+            numTokens += getTokenCount(output);
+          }
+          continue;
+        }
+
+        const nestedValue = item[item.type];
+
+        if (!nestedValue) {
+          continue;
+        }
+
+        processValue(nestedValue);
+      }
+    } else if (typeof value === 'string') {
+      numTokens += getTokenCount(value);
+    } else if (typeof value === 'number') {
+      numTokens += getTokenCount(value.toString());
+    } else if (typeof value === 'boolean') {
+      numTokens += getTokenCount(value.toString());
+    }
+  };
+
+  let numTokens = tokensPerMessage;
+  processValue(message.content);
+  return numTokens;
+}
+
+export const createTokenCounter = async () => {
+  const res = await fetch('https://tiktoken.pages.dev/js/o200k_base.json');
+  const o200k_base = await res.json();
+
+  const countTokens = (text: string): number => {
+    const enc = new Tiktoken(o200k_base);
+    return enc.encode(text).length;
+  };
+
+  return (message: BaseMessage): number => getTokenCountForMessage(message, countTokens);
+};