illuma-agents 1.0.2

package/src/types/stream.ts

@@ -0,0 +1,400 @@
+// src/types/stream.ts
+import type OpenAITypes from 'openai';
+import type {
+  MessageContentImageUrl,
+  MessageContentText,
+  ToolMessage,
+  BaseMessage,
+} from '@langchain/core/messages';
+import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
+import type { LLMResult, Generation } from '@langchain/core/outputs';
+import type { AnthropicContentBlock } from '@/llm/anthropic/types';
+import type { ToolEndEvent } from '@/types/tools';
+import { StepTypes, ContentTypes, GraphEvents } from '@/common/enum';
+
+export type HandleLLMEnd = (
+  output: LLMResult,
+  runId: string,
+  parentRunId?: string,
+  tags?: string[]
+) => void;
+
+export type MetadataAggregatorResult = {
+  handleLLMEnd: HandleLLMEnd;
+  collected: Record<string, unknown>[];
+};
+
+export type StreamGeneration = Generation & {
+  text?: string;
+  message?: BaseMessage;
+};
+
+/** 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. */
+export type EventName = string;
+
+export type RunStep = {
+  // id: string;
+  // object: 'thread.run.step'; // Updated from 'run.step' # missing
+  // created_at: number;
+  // run_id: string;
+  // assistant_id: string;
+  // thread_id: string;
+  type: StepTypes;
+  // status: 'in_progress' | 'completed' | 'failed' | 'cancelled'; // Add other possible status values if needed
+  // cancelled_at: number | null;
+  // completed_at: number | null;
+  // expires_at: number;
+  // failed_at: number | null;
+  // last_error: string | null;
+  id: string; // #new
+  runId?: string; // #new
+  index: number; // #new
+  stepIndex?: number; // #new
+  stepDetails: StepDetails;
+  usage?: null | object;
+  // {
+  // Define usage structure if it's ever non-null
+  // prompt_tokens: number; // #new
+  // completion_tokens: number; // #new
+  // total_tokens: number; // #new
+  // };
+};
+
+/**
+ * Represents a run step delta i.e. any changed fields on a run step during
+ * streaming.
+ */
+export interface RunStepDeltaEvent {
+  /**
+   * The identifier of the run step, which can be referenced in API endpoints.
+   */
+  id: string;
+  /**
+   * The delta containing the fields that have changed on the run step.
+   */
+  delta: ToolCallDelta;
+}
+
+export type StepDetails = MessageCreationDetails | ToolCallsDetails;
+
+export type StepCompleted = ToolCallCompleted;
+
+export type MessageCreationDetails = {
+  type: StepTypes.MESSAGE_CREATION;
+  message_creation: {
+    message_id: string;
+  };
+};
+
+export type ToolEndData = {
+  input: string | Record<string, unknown>;
+  output?: ToolMessage;
+};
+export type ToolErrorData = {
+  id: string;
+  name: string;
+  error?: Error;
+} & Pick<ToolEndData, 'input'>;
+export type ToolEndCallback = (
+  data: ToolEndData,
+  metadata?: Record<string, unknown>
+) => void;
+
+export type ProcessedToolCall = {
+  name: string;
+  args: string | Record<string, unknown>;
+  id: string;
+  output: string;
+  progress: number;
+};
+
+export type ProcessedContent = {
+  type: ContentType;
+  text?: string;
+  tool_call?: ProcessedToolCall;
+};
+
+export type ToolCallCompleted = {
+  type: 'tool_call';
+  tool_call: ProcessedToolCall;
+};
+
+export type ToolCompleteEvent = ToolCallCompleted & {
+  /** The Step Id of the Tool Call */
+  id: string;
+  /** The content index of the tool call */
+  index: number;
+  type: 'tool_call';
+};
+
+export type ToolCallsDetails = {
+  type: StepTypes.TOOL_CALLS;
+  tool_calls?: AgentToolCall[]; // #new
+};
+
+export type ToolCallDelta = {
+  type: StepTypes;
+  tool_calls?: ToolCallChunk[]; // #new
+};
+
+export type AgentToolCall =
+  | {
+      id: string; // #new
+      type: 'function'; // #new
+      function: {
+        name: string; // #new
+        arguments: string | object; // JSON string // #new
+      };
+    }
+  | ToolCall;
+
+export interface ExtendedMessageContent {
+  type?: string;
+  text?: string;
+  input?: string;
+  index?: number;
+  id?: string;
+  name?: string;
+}
+
+export type AgentUpdate = {
+  type: ContentTypes.AGENT_UPDATE;
+  agent_update: {
+    index: number;
+    runId: string;
+    agentId: string;
+  };
+};
+
+/**
+ * Represents a message delta i.e. any changed fields on a message during
+ * streaming.
+ */
+export interface MessageDeltaEvent {
+  /**
+   * The identifier of the message, which can be referenced in API endpoints.
+   */
+  id: string;
+
+  /**
+   * The delta containing the fields that have changed on the Message.
+   */
+  delta: MessageDelta;
+}
+
+/**
+ * The delta containing the fields that have changed on the Message.
+ */
+export interface MessageDelta {
+  /**
+   * The content of the message in array of text and/or images.
+   */
+  content?: MessageContentComplex[];
+  /**
+   * The tool call ids associated with the message.
+   */
+  tool_call_ids?: string[];
+}
+
+/**
+ * Represents a reasoning delta i.e. any changed fields on a message during
+ * streaming.
+ */
+export interface ReasoningDeltaEvent {
+  /**
+   * The identifier of the message, which can be referenced in API endpoints.
+   */
+  id: string;
+
+  /**
+   * The delta containing the fields that have changed.
+   */
+  delta: ReasoningDelta;
+}
+
+/**
+ * The reasoning delta containing the fields that have changed on the Message.
+ */
+export interface ReasoningDelta {
+  /**
+   * The content of the message in array of text and/or images.
+   */
+  content?: MessageContentComplex[];
+}
+
+export type MessageDeltaUpdate = {
+  type: ContentTypes.TEXT;
+  text: string;
+  tool_call_ids?: string[];
+};
+export type ReasoningDeltaUpdate = { type: ContentTypes.THINK; think: string };
+
+export type ContentType = 'text' | 'image_url' | 'tool_call' | 'think' | string;
+
+export type ReasoningContentText = {
+  type: ContentTypes.THINK;
+  think: string;
+};
+
+/** Vertex AI / Google Common - Reasoning Content Block Format */
+export type GoogleReasoningContentText = {
+  type: ContentTypes.REASONING;
+  reasoning: string;
+};
+
+/** Anthropic's Reasoning Content Block Format */
+export type ThinkingContentText = {
+  type: ContentTypes.THINKING;
+  index?: number;
+  signature?: string;
+  thinking?: string;
+};
+
+/** Bedrock's Reasoning Content Block Format */
+export type BedrockReasoningContentText = {
+  type: ContentTypes.REASONING_CONTENT;
+  index?: number;
+  reasoningText: { text?: string; signature?: string };
+};
+
+/**
+ * A call to a tool.
+ */
+export type ToolCallPart = {
+  /** Type ("tool_call") according to Assistants Tool Call Structure */
+  type: ContentTypes.TOOL_CALL;
+  /** The name of the tool to be called */
+  name: string;
+  /** The arguments to the tool call */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  args?: string | Record<string, any>;
+
+  /** If provided, an identifier associated with the tool call */
+  id?: string;
+  /** If provided, the output of the tool call */
+  output?: string;
+  /** Auth URL */
+  auth?: string;
+  /** Expiration time */
+  expires_at?: number;
+};
+
+export type ToolCallContent = {
+  type: ContentTypes.TOOL_CALL;
+  tool_call?: ToolCallPart;
+};
+
+export type ToolResultContent = {
+  content:
+    | string
+    | Record<string, unknown>
+    | Array<string | Record<string, unknown>>
+    | AnthropicContentBlock[];
+  type: 'tool_result' | 'web_search_result' | 'web_search_tool_result';
+  tool_use_id?: string;
+  input?: string | Record<string, unknown>;
+  index?: number;
+};
+
+export type MessageContentComplex = (
+  | ToolResultContent
+  | ThinkingContentText
+  | AgentUpdate
+  | ToolCallContent
+  | ReasoningContentText
+  | MessageContentText
+  | MessageContentImageUrl
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  | (Record<string, any> & {
+      type?: 'text' | 'image_url' | 'think' | 'thinking' | string;
+    })
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  | (Record<string, any> & {
+      type?: never;
+    })
+) & {
+  tool_call_ids?: string[];
+};
+
+export interface TMessage {
+  role?: string;
+  content?: MessageContentComplex[] | string;
+  [key: string]: unknown;
+}
+
+export type TPayload = Array<Partial<TMessage>>;
+
+export type CustomChunkDelta =
+  | null
+  | undefined
+  | (Partial<OpenAITypes.Chat.Completions.ChatCompletionChunk.Choice.Delta> & {
+      reasoning?: string | null;
+      reasoning_content?: string | null;
+    });
+export type CustomChunkChoice = Partial<
+  Omit<OpenAITypes.Chat.Completions.ChatCompletionChunk.Choice, 'delta'> & {
+    delta?: CustomChunkDelta;
+  }
+>;
+export type CustomChunk = Partial<OpenAITypes.ChatCompletionChunk> & {
+  choices?: Partial<Array<CustomChunkChoice>>;
+};
+
+export type SplitStreamHandlers = Partial<{
+  [GraphEvents.ON_RUN_STEP]: ({
+    event,
+    data,
+  }: {
+    event: GraphEvents;
+    data: RunStep;
+  }) => void;
+  [GraphEvents.ON_MESSAGE_DELTA]: ({
+    event,
+    data,
+  }: {
+    event: GraphEvents;
+    data: MessageDeltaEvent;
+  }) => void;
+  [GraphEvents.ON_REASONING_DELTA]: ({
+    event,
+    data,
+  }: {
+    event: GraphEvents;
+    data: ReasoningDeltaEvent;
+  }) => void;
+}>;
+
+export type ContentAggregator = ({
+  event,
+  data,
+}: {
+  event: GraphEvents;
+  data:
+    | RunStep
+    | MessageDeltaEvent
+    | RunStepDeltaEvent
+    | {
+        result: ToolEndEvent;
+      };
+}) => void;
+export type ContentAggregatorResult = {
+  stepMap: Map<string, RunStep | undefined>;
+  contentParts: Array<MessageContentComplex | undefined>;
+  aggregateContent: ContentAggregator;
+};

package/src/types/tools.ts

@@ -0,0 +1,80 @@
+// src/types/tools.ts
+import type { StructuredToolInterface } from '@langchain/core/tools';
+import type { RunnableToolLike } from '@langchain/core/runnables';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { ToolErrorData } from './stream';
+import { EnvVar } from '@/common';
+
+/** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
+export type CustomToolCall = {
+  name: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  args: string | Record<string, any>;
+  id?: string;
+  type?: 'tool_call';
+  output?: string;
+};
+
+export type GenericTool = StructuredToolInterface | RunnableToolLike;
+
+export type ToolMap = Map<string, GenericTool>;
+export type ToolRefs = {
+  tools: GenericTool[];
+  toolMap?: ToolMap;
+};
+
+export type ToolRefGenerator = (tool_calls: ToolCall[]) => ToolRefs;
+
+export type ToolNodeOptions = {
+  name?: string;
+  tags?: string[];
+  handleToolErrors?: boolean;
+  loadRuntimeTools?: ToolRefGenerator;
+  toolCallStepIds?: Map<string, string>;
+  errorHandler?: (
+    data: ToolErrorData,
+    metadata?: Record<string, unknown>
+  ) => void;
+};
+
+export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
+
+export type ToolEndEvent = {
+  /** The Step Id of the Tool Call */
+  id: string;
+  /** The Completed Tool Call */
+  tool_call: ToolCall;
+  /** The content index of the tool call */
+  index: number;
+};
+
+export type CodeEnvFile = {
+  id: string;
+  name: string;
+  session_id: string;
+};
+
+export type CodeExecutionToolParams =
+  | undefined
+  | {
+      session_id?: string;
+      user_id?: string;
+      apiKey?: string;
+      files?: CodeEnvFile[];
+      [EnvVar.CODE_API_KEY]?: string;
+    };
+
+export type FileRef = {
+  id: string;
+  name: string;
+  path?: string;
+};
+
+export type FileRefs = FileRef[];
+
+export type ExecuteResult = {
+  session_id: string;
+  stdout: string;
+  stderr: string;
+  files?: FileRefs;
+};

package/src/utils/graph.ts

@@ -0,0 +1,11 @@
+export const resetIfNotEmpty = <T>(value: T, resetValue: T): T => {
+  if (Array.isArray(value)) {
+    return value.length > 0 ? resetValue : value;
+  }
+  if (value instanceof Set || value instanceof Map) {
+    return value.size > 0 ? resetValue : value;
+  }
+  return value !== undefined ? resetValue : value;
+};
+
+export const joinKeys = (args: (string | number | undefined)[]): string => args.join('_');

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+export * from './graph';
+export * from './llm';
+export * from './misc';
+export * from './run';
+export * from './tokens';

package/src/utils/llm.ts

@@ -0,0 +1,27 @@
+// src/utils/llm.ts
+import { Providers } from '@/common';
+
+export function isOpenAILike(provider?: string | Providers): boolean {
+  if (provider == null) {
+    return false;
+  }
+  return (
+    [
+      Providers.OPENAI,
+      Providers.AZURE,
+      Providers.OPENROUTER,
+      Providers.XAI,
+      Providers.DEEPSEEK,
+      Providers.OLLAMA,
+    ] as string[]
+  ).includes(provider);
+}
+
+export function isGoogleLike(provider?: string | Providers): boolean {
+  if (provider == null) {
+    return false;
+  }
+  return ([Providers.GOOGLE, Providers.VERTEXAI] as string[]).includes(
+    provider
+  );
+}

package/src/utils/llmConfig.ts

@@ -0,0 +1,183 @@
+// 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: 'deepseek/deepseek-r1',
+    openAIApiKey: process.env.OPENROUTER_API_KEY,
+    configuration: {
+      baseURL: process.env.OPENROUTER_BASE_URL,
+      defaultHeaders: {
+        'HTTP-Referer': 'https://gaavi.ai',
+        'X-Title': 'Illuma',
+      },
+    },
+    include_reasoning: true,
+  } 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',
+  },
+  [Providers.OLLAMA]: {
+    provider: Providers.OLLAMA,
+    model: 'gpt-oss:20b',
+    streaming: true,
+    streamUsage: true,
+    baseUrl: 'http://localhost:11434',
+  },
+  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.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',
+    streaming: true,
+    streamUsage: true,
+    keyFile: process.env.VERTEXAI_KEY_FILE,
+  } 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;
+}