illuma-agents 1.0.2

package/src/tools/search/utils.ts

@@ -0,0 +1,79 @@
+/* eslint-disable no-console */
+
+import type * as t from './types';
+
+/**
+ * Singleton instance of the default logger
+ */
+let defaultLoggerInstance: t.Logger | null = null;
+
+/**
+ * Creates a default logger that maps to console methods
+ * Uses a singleton pattern to avoid creating multiple instances
+ * @returns A default logger that implements the Logger interface
+ */
+export const createDefaultLogger = (): t.Logger => {
+  if (!defaultLoggerInstance) {
+    defaultLoggerInstance = {
+      error: console.error,
+      warn: console.warn,
+      info: console.info,
+      debug: console.debug,
+    } as t.Logger;
+  }
+  return defaultLoggerInstance;
+};
+
+export const fileExtRegex =
+  /\.(pdf|jpe?g|png|gif|svg|webp|bmp|ico|tiff?|avif|heic|doc[xm]?|xls[xm]?|ppt[xm]?|zip|rar|mp[34]|mov|avi|wav)(?:\?.*)?$/i;
+
+export const getDomainName = (
+  link: string,
+  metadata?: t.ScrapeMetadata,
+  logger?: t.Logger
+): string | undefined => {
+  try {
+    const url = metadata?.sourceURL ?? metadata?.url ?? (link || '');
+    const domain = new URL(url).hostname.replace(/^www\./, '');
+    if (domain) {
+      return domain;
+    }
+  } catch (e) {
+    // URL parsing failed
+    if (logger) {
+      logger.error('Error parsing URL:', e);
+    } else {
+      console.error('Error parsing URL:', e);
+    }
+  }
+
+  return;
+};
+
+export function getAttribution(
+  link: string,
+  metadata?: t.ScrapeMetadata,
+  logger?: t.Logger
+): string | undefined {
+  if (!metadata) return getDomainName(link, metadata, logger);
+
+  const twitterSite = metadata['twitter:site'];
+  const twitterSiteFormatted =
+    typeof twitterSite === 'string' ? twitterSite.replace(/^@/, '') : undefined;
+
+  const possibleAttributions = [
+    metadata.ogSiteName,
+    metadata['og:site_name'],
+    metadata.title?.split('|').pop()?.trim(),
+    twitterSiteFormatted,
+  ];
+
+  const attribution = possibleAttributions.find(
+    (attr) => attr != null && typeof attr === 'string' && attr.trim() !== ''
+  );
+  if (attribution != null) {
+    return attribution;
+  }
+
+  return getDomainName(link, metadata, logger);
+}

package/src/types/graph.ts

@@ -0,0 +1,185 @@
+// src/types/graph.ts
+import type {
+  StateGraphArgs,
+  StateGraph,
+  CompiledStateGraph,
+} from '@langchain/langgraph';
+import type { BindToolsInput } from '@langchain/core/language_models/chat_models';
+import type { BaseMessage, AIMessageChunk } from '@langchain/core/messages';
+import type { ChatGenerationChunk } from '@langchain/core/outputs';
+import type { GoogleAIToolType } from '@langchain/google-common';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ToolMap, GenericTool } from '@/types/tools';
+import type { ClientOptions } from '@/types/llm';
+import type { Providers } from '@/common';
+import type { Graph } from '@/graphs';
+// import type { RunnableConfig } from '@langchain/core/runnables';
+
+export type BaseGraphState = {
+  messages: BaseMessage[];
+  // [key: string]: unknown;
+};
+
+export type IState = BaseGraphState;
+
+// export interface IState extends BaseGraphState {
+//   instructions?: string;
+//   additional_instructions?: string;
+// }
+
+export interface EventHandler {
+  handle(
+    event: string,
+    data: StreamEventData | ModelEndData,
+    metadata?: Record<string, unknown>,
+    graph?: Graph
+  ): void;
+}
+
+export type GraphStateChannels<T extends BaseGraphState> =
+  StateGraphArgs<T>['channels'];
+
+export type Workflow<
+  T extends BaseGraphState = BaseGraphState,
+  U extends Partial<T> = Partial<T>,
+  N extends string = string,
+> = StateGraph<T, U, N>;
+
+export type CompiledWorkflow<
+  T extends BaseGraphState = BaseGraphState,
+  U extends Partial<T> = Partial<T>,
+  N extends string = string,
+> = CompiledStateGraph<T, U, N>;
+
+export type EventStreamCallbackHandlerInput =
+  Parameters<CompiledWorkflow['streamEvents']>[2] extends Omit<
+    infer T,
+    'autoClose'
+  >
+    ? T
+    : never;
+
+export type StreamChunk =
+  | (ChatGenerationChunk & {
+      message: AIMessageChunk;
+    })
+  | AIMessageChunk;
+
+/**
+ * Data associated with a StreamEvent.
+ */
+export type StreamEventData = {
+  /**
+   * The input passed to the runnable that generated the event.
+   * Inputs will sometimes be available at the *START* of the runnable, and
+   * sometimes at the *END* of the runnable.
+   * If a runnable is able to stream its inputs, then its input by definition
+   * won't be known until the *END* of the runnable when it has finished streaming
+   * its inputs.
+   */
+  input?: unknown;
+  /**
+   * The output of the runnable that generated the event.
+   * Outputs will only be available at the *END* of the runnable.
+   * For most runnables, this field can be inferred from the `chunk` field,
+   * though there might be some exceptions for special cased runnables (e.g., like
+   * chat models), which may return more information.
+   */
+  output?: unknown;
+  /**
+   * A streaming chunk from the output that generated the event.
+   * chunks support addition in general, and adding them up should result
+   * in the output of the runnable that generated the event.
+   */
+  chunk?: StreamChunk;
+  /**
+   * Runnable config for invoking other runnables within handlers.
+   */
+  config?: RunnableConfig;
+  /**
+   * Custom result from the runnable that generated the event.
+   */
+  result?: unknown;
+};
+
+/**
+ * A streaming event.
+ *
+ * Schema of a streaming event which is produced from the streamEvents method.
+ */
+export type StreamEvent = {
+  /**
+   * Event names are of the format: on_[runnable_type]_(start|stream|end).
+   *
+   * Runnable types are one of:
+   * - llm - used by non chat models
+   * - chat_model - used by chat models
+   * - prompt --  e.g., ChatPromptTemplate
+   * - tool -- LangChain tools
+   * - chain - most Runnables are of this type
+   *
+   * Further, the events are categorized as one of:
+   * - start - when the runnable starts
+   * - stream - when the runnable is streaming
+   * - end - when the runnable ends
+   *
+   * start, stream and end are associated with slightly different `data` payload.
+   *
+   * Please see the documentation for `EventData` for more details.
+   */
+  event: string;
+  /** The name of the runnable that generated the event. */
+  name: string;
+  /**
+   * An randomly generated ID to keep track of the execution of the given runnable.
+   *
+   * Each child runnable that gets invoked as part of the execution of a parent runnable
+   * is assigned its own unique ID.
+   */
+  run_id: string;
+  /**
+   * Tags associated with the runnable that generated this event.
+   * Tags are always inherited from parent runnables.
+   */
+  tags?: string[];
+  /** Metadata associated with the runnable that generated this event. */
+  metadata: Record<string, unknown>;
+  /**
+   * Event data.
+   *
+   * The contents of the event data depend on the event type.
+   */
+  data: StreamEventData;
+};
+
+export type GraphConfig = {
+  provider: string;
+  thread_id?: string;
+  run_id?: string;
+};
+
+export type PartMetadata = {
+  progress?: number;
+  asset_pointer?: string;
+  status?: string;
+  action?: boolean;
+  output?: string;
+};
+
+export type ModelEndData =
+  | (StreamEventData & { output: AIMessageChunk | undefined })
+  | undefined;
+export type GraphTools = GenericTool[] | BindToolsInput[] | GoogleAIToolType[];
+export type StandardGraphInput = {
+  runId?: string;
+  toolEnd?: boolean;
+  toolMap?: ToolMap;
+  provider: Providers;
+  signal?: AbortSignal;
+  instructions?: string;
+  streamBuffer?: number;
+  clientOptions: ClientOptions;
+  additional_instructions?: string;
+  reasoningKey?: 'reasoning_content' | 'reasoning';
+  tools?: GraphTools;
+};

package/src/types/index.ts

@@ -0,0 +1,6 @@
+// src/types/index.ts
+export * from './graph';
+export * from './llm';
+export * from './run';
+export * from './stream';
+export * from './tools';

package/src/types/llm.ts

@@ -0,0 +1,140 @@
+// src/types/llm.ts
+import { ChatOllama } from '@langchain/ollama';
+import { ChatAnthropic } from '@langchain/anthropic';
+import { ChatMistralAI } from '@langchain/mistralai';
+import { ChatBedrockConverse } from '@langchain/aws';
+import { BedrockChat } from '@langchain/community/chat_models/bedrock/web';
+import type {
+  BindToolsInput,
+  BaseChatModelParams,
+} from '@langchain/core/language_models/chat_models';
+import type {
+  OpenAIChatInput,
+  ChatOpenAIFields,
+  AzureOpenAIInput,
+  ClientOptions as OAIClientOptions,
+} from '@langchain/openai';
+import type { BedrockChatFields } from '@langchain/community/chat_models/bedrock/web';
+import type { GoogleGenerativeAIChatInput } from '@langchain/google-genai';
+import type { GeminiGenerationConfig } from '@langchain/google-common';
+import type { ChatVertexAIInput } from '@langchain/google-vertexai';
+import type { ChatDeepSeekCallOptions } from '@langchain/deepseek';
+import type { ChatOpenRouterCallOptions } from '@/llm/openrouter';
+import type { ChatBedrockConverseInput } from '@langchain/aws';
+import type { ChatMistralAIInput } from '@langchain/mistralai';
+import type { RequestOptions } from '@google/generative-ai';
+import type { StructuredTool } from '@langchain/core/tools';
+import type { AnthropicInput } from '@langchain/anthropic';
+import type { Runnable } from '@langchain/core/runnables';
+import type { ChatOllamaInput } from '@langchain/ollama';
+import type { OpenAI as OpenAIClient } from 'openai';
+import type { ChatXAIInput } from '@langchain/xai';
+import {
+  AzureChatOpenAI,
+  ChatDeepSeek,
+  ChatOpenAI,
+  ChatXAI,
+} from '@/llm/openai';
+import { CustomChatGoogleGenerativeAI } from '@/llm/google';
+import { ChatOpenRouter } from '@/llm/openrouter';
+import { ChatVertexAI } from '@/llm/vertexai';
+import { Providers } from '@/common';
+
+export type AzureClientOptions = Partial<OpenAIChatInput> &
+  Partial<AzureOpenAIInput> & {
+    openAIApiKey?: string;
+    openAIApiVersion?: string;
+    openAIBasePath?: string;
+    deploymentName?: string;
+  } & BaseChatModelParams & {
+    configuration?: OAIClientOptions;
+  };
+export type ThinkingConfig = AnthropicInput['thinking'];
+export type ChatOpenAIToolType =
+  | BindToolsInput
+  | OpenAIClient.ChatCompletionTool;
+export type CommonToolType = StructuredTool | ChatOpenAIToolType;
+export type AnthropicReasoning = {
+  thinking?: ThinkingConfig | boolean;
+  thinkingBudget?: number;
+};
+export type OpenAIClientOptions = ChatOpenAIFields;
+export type OllamaClientOptions = ChatOllamaInput;
+export type AnthropicClientOptions = AnthropicInput;
+export type MistralAIClientOptions = ChatMistralAIInput;
+export type VertexAIClientOptions = ChatVertexAIInput & {
+  includeThoughts?: boolean;
+};
+export type BedrockClientOptions = BedrockChatFields;
+export type BedrockAnthropicInput = ChatBedrockConverseInput & {
+  additionalModelRequestFields?: ChatBedrockConverseInput['additionalModelRequestFields'] &
+    AnthropicReasoning;
+};
+export type BedrockConverseClientOptions = ChatBedrockConverseInput;
+export type GoogleClientOptions = GoogleGenerativeAIChatInput & {
+  customHeaders?: RequestOptions['customHeaders'];
+  thinkingConfig?: GeminiGenerationConfig['thinkingConfig'];
+};
+export type DeepSeekClientOptions = ChatDeepSeekCallOptions;
+export type XAIClientOptions = ChatXAIInput;
+
+export type ClientOptions =
+  | OpenAIClientOptions
+  | AzureClientOptions
+  | OllamaClientOptions
+  | AnthropicClientOptions
+  | MistralAIClientOptions
+  | VertexAIClientOptions
+  | BedrockClientOptions
+  | BedrockConverseClientOptions
+  | GoogleClientOptions
+  | DeepSeekClientOptions
+  | XAIClientOptions;
+
+export type SharedLLMConfig = {
+  provider: Providers;
+};
+
+export type LLMConfig = SharedLLMConfig & ClientOptions;
+
+export type ProviderOptionsMap = {
+  [Providers.AZURE]: AzureClientOptions;
+  [Providers.OPENAI]: OpenAIClientOptions;
+  [Providers.OLLAMA]: OllamaClientOptions;
+  [Providers.GOOGLE]: GoogleClientOptions;
+  [Providers.VERTEXAI]: VertexAIClientOptions;
+  [Providers.DEEPSEEK]: DeepSeekClientOptions;
+  [Providers.ANTHROPIC]: AnthropicClientOptions;
+  [Providers.MISTRALAI]: MistralAIClientOptions;
+  [Providers.MISTRAL]: MistralAIClientOptions;
+  [Providers.OPENROUTER]: ChatOpenRouterCallOptions;
+  [Providers.BEDROCK_LEGACY]: BedrockClientOptions;
+  [Providers.BEDROCK]: BedrockConverseClientOptions;
+  [Providers.XAI]: XAIClientOptions;
+};
+
+export type ChatModelMap = {
+  [Providers.XAI]: ChatXAI;
+  [Providers.OPENAI]: ChatOpenAI;
+  [Providers.OLLAMA]: ChatOllama;
+  [Providers.AZURE]: AzureChatOpenAI;
+  [Providers.DEEPSEEK]: ChatDeepSeek;
+  [Providers.VERTEXAI]: ChatVertexAI;
+  [Providers.ANTHROPIC]: ChatAnthropic;
+  [Providers.MISTRALAI]: ChatMistralAI;
+  [Providers.MISTRAL]: ChatMistralAI;
+  [Providers.OPENROUTER]: ChatOpenRouter;
+  [Providers.BEDROCK_LEGACY]: BedrockChat;
+  [Providers.BEDROCK]: ChatBedrockConverse;
+  [Providers.GOOGLE]: CustomChatGoogleGenerativeAI;
+};
+
+export type ChatModelConstructorMap = {
+  [P in Providers]: new (config: ProviderOptionsMap[P]) => ChatModelMap[P];
+};
+
+export type ChatModelInstance = ChatModelMap[Providers];
+
+export type ModelWithTools = ChatModelInstance & {
+  bindTools(tools: CommonToolType[]): Runnable;
+};

package/src/types/run.ts

@@ -0,0 +1,89 @@
+// src/types/run.ts
+import type * as z from 'zod';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { StructuredTool } from '@langchain/core/tools';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type {
+  BaseCallbackHandler,
+  CallbackHandlerMethods,
+} from '@langchain/core/callbacks/base';
+import type * as graph from '@/graphs/Graph';
+import type * as s from '@/types/stream';
+import type * as e from '@/common/enum';
+import type * as g from '@/types/graph';
+import type * as l from '@/types/llm';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ZodObjectAny = z.ZodObject<any, any, any, any>;
+export type BaseGraphConfig = {
+  type?: 'standard';
+  llmConfig: l.LLMConfig;
+  provider?: e.Providers;
+  clientOptions?: l.ClientOptions;
+};
+export type StandardGraphConfig = BaseGraphConfig &
+  Omit<g.StandardGraphInput, 'provider' | 'clientOptions'>;
+
+export type RunTitleOptions = {
+  inputText: string;
+  provider: e.Providers;
+  contentParts: (s.MessageContentComplex | undefined)[];
+  titlePrompt?: string;
+  skipLanguage?: boolean;
+  clientOptions?: l.ClientOptions;
+  chainOptions?: Partial<RunnableConfig> | undefined;
+  omitOptions?: Set<string>;
+  titleMethod?: e.TitleMethod;
+  titlePromptTemplate?: string;
+};
+
+export interface AgentStateChannels {
+  messages: BaseMessage[];
+  next: string;
+  [key: string]: unknown;
+  instructions?: string;
+  additional_instructions?: string;
+}
+
+export interface Member {
+  name: string;
+  systemPrompt: string;
+  tools: StructuredTool[];
+  llmConfig: l.LLMConfig;
+}
+
+export type CollaborativeGraphConfig = {
+  type: 'collaborative';
+  members: Member[];
+  supervisorConfig: { systemPrompt?: string; llmConfig: l.LLMConfig };
+};
+
+export type TaskManagerGraphConfig = {
+  type: 'taskmanager';
+  members: Member[];
+  supervisorConfig: { systemPrompt?: string; llmConfig: l.LLMConfig };
+};
+
+export type RunConfig = {
+  runId: string;
+  graphConfig:
+    | StandardGraphConfig
+    | CollaborativeGraphConfig
+    | TaskManagerGraphConfig;
+  customHandlers?: Record<string, g.EventHandler>;
+  returnContent?: boolean;
+};
+
+export type ProvidedCallbacks =
+  | (BaseCallbackHandler | CallbackHandlerMethods)[]
+  | undefined;
+
+export type TokenCounter = (message: BaseMessage) => number;
+export type EventStreamOptions = {
+  callbacks?: graph.ClientCallbacks;
+  keepContent?: boolean;
+  /* Context Management */
+  maxContextTokens?: number;
+  tokenCounter?: TokenCounter;
+  indexTokenCountMap?: Record<string, number>;
+};