@illuma-ai/agents 1.0.81

package/src/agents/__tests__/resolveStructuredOutputMode.test.ts

@@ -0,0 +1,137 @@
+// src/agents/__tests__/resolveStructuredOutputMode.test.ts
+import { AgentContext } from '../AgentContext';
+import { Providers } from '@/common';
+import type * as t from '@/types';
+
+describe('resolveStructuredOutputMode', () => {
+  const createContext = (
+    provider: Providers,
+    mode?: t.StructuredOutputMode,
+  ): AgentContext => {
+    return AgentContext.fromConfig({
+      agentId: 'test-agent',
+      provider,
+      instructions: 'Test',
+      structuredOutput: {
+        schema: { type: 'object', properties: { name: { type: 'string' } } },
+        mode,
+      },
+    });
+  };
+
+  describe('auto mode resolution', () => {
+    it('resolves to jsonSchema for Anthropic', () => {
+      const ctx = createContext(Providers.ANTHROPIC, 'auto');
+      const { method, warnings } = ctx.resolveStructuredOutputMode();
+      expect(method).toBe('jsonSchema');
+      expect(warnings).toEqual([]);
+    });
+
+    it('resolves to jsonSchema for OpenAI', () => {
+      const ctx = createContext(Providers.OPENAI, 'auto');
+      const { method, warnings } = ctx.resolveStructuredOutputMode();
+      expect(method).toBe('jsonSchema');
+      expect(warnings).toEqual([]);
+    });
+
+    it('resolves to jsonSchema for Azure', () => {
+      const ctx = createContext(Providers.AZURE, 'auto');
+      const { method, warnings } = ctx.resolveStructuredOutputMode();
+      expect(method).toBe('jsonSchema');
+      expect(warnings).toEqual([]);
+    });
+
+    it('resolves to undefined (LangChain default) for Bedrock', () => {
+      const ctx = createContext(Providers.BEDROCK, 'auto');
+      const { method } = ctx.resolveStructuredOutputMode();
+      expect(method).toBeUndefined();
+    });
+
+    it('resolves to undefined for Google', () => {
+      const ctx = createContext(Providers.GOOGLE, 'auto');
+      const { method } = ctx.resolveStructuredOutputMode();
+      expect(method).toBeUndefined();
+    });
+
+    it('resolves to undefined for OpenRouter', () => {
+      const ctx = createContext(Providers.OPENROUTER, 'auto');
+      const { method } = ctx.resolveStructuredOutputMode();
+      expect(method).toBeUndefined();
+    });
+
+    it('defaults to auto when mode is undefined', () => {
+      const ctx = createContext(Providers.OPENAI, undefined);
+      const { method } = ctx.resolveStructuredOutputMode();
+      expect(method).toBe('jsonSchema');
+    });
+  });
+
+  describe('native mode resolution', () => {
+    it('resolves to jsonSchema for Anthropic', () => {
+      const ctx = createContext(Providers.ANTHROPIC, 'native');
+      const { method, warnings } = ctx.resolveStructuredOutputMode();
+      expect(method).toBe('jsonSchema');
+      expect(warnings).toEqual([]);
+    });
+
+    it('resolves to jsonSchema for OpenAI', () => {
+      const ctx = createContext(Providers.OPENAI, 'native');
+      const { method } = ctx.resolveStructuredOutputMode();
+      expect(method).toBe('jsonSchema');
+    });
+
+    it('falls back to functionCalling for Bedrock with warning', () => {
+      const ctx = createContext(Providers.BEDROCK, 'native');
+      const { method, warnings } = ctx.resolveStructuredOutputMode();
+      expect(method).toBe('functionCalling');
+      expect(warnings.length).toBe(1);
+      expect(warnings[0]).toContain('not supported');
+      expect(warnings[0]).toContain('Falling back');
+    });
+
+    it('falls back to functionCalling for Google with warning', () => {
+      const ctx = createContext(Providers.GOOGLE, 'native');
+      const { method, warnings } = ctx.resolveStructuredOutputMode();
+      expect(method).toBe('functionCalling');
+      expect(warnings.length).toBe(1);
+    });
+  });
+
+  describe('tool mode resolution', () => {
+    it('always resolves to functionCalling regardless of provider', () => {
+      const providers = [
+        Providers.ANTHROPIC,
+        Providers.OPENAI,
+        Providers.AZURE,
+        Providers.BEDROCK,
+        Providers.GOOGLE,
+      ];
+
+      for (const provider of providers) {
+        const ctx = createContext(provider, 'tool');
+        const { method } = ctx.resolveStructuredOutputMode();
+        expect(method).toBe('functionCalling');
+      }
+    });
+  });
+
+  describe('provider mode resolution', () => {
+    it('resolves to jsonMode for Anthropic', () => {
+      const ctx = createContext(Providers.ANTHROPIC, 'provider');
+      const { method } = ctx.resolveStructuredOutputMode();
+      expect(method).toBe('jsonMode');
+    });
+
+    it('resolves to jsonMode for OpenAI', () => {
+      const ctx = createContext(Providers.OPENAI, 'provider');
+      const { method } = ctx.resolveStructuredOutputMode();
+      expect(method).toBe('jsonMode');
+    });
+
+    it('resolves to functionCalling for Bedrock (no jsonMode support)', () => {
+      const ctx = createContext(Providers.BEDROCK, 'provider');
+      const { method } = ctx.resolveStructuredOutputMode();
+      expect(method).toBe('functionCalling');
+    });
+  });
+});

package/src/common/enum.ts

@@ -0,0 +1,203 @@
+/**
+ * Enum representing the various event types emitted during the execution of runnables.
+ * These events provide real-time information about the progress and state of different components.
+ *
+ * @enum {string}
+ */
+export enum GraphEvents {
+  /* Custom Events */
+
+  /** [Custom] Agent update event in multi-agent graph/workflow */
+  ON_AGENT_UPDATE = 'on_agent_update',
+  /** [Custom] Delta event for run steps (message creation and tool calls) */
+  ON_RUN_STEP = 'on_run_step',
+  /** [Custom] Delta event for run steps (tool calls) */
+  ON_RUN_STEP_DELTA = 'on_run_step_delta',
+  /** [Custom] Completed event for run steps (tool calls) */
+  ON_RUN_STEP_COMPLETED = 'on_run_step_completed',
+  /** [Custom] Delta events for messages */
+  ON_MESSAGE_DELTA = 'on_message_delta',
+  /** [Custom] Reasoning Delta events for messages */
+  ON_REASONING_DELTA = 'on_reasoning_delta',
+  /** [Custom] Context analytics event for traces */
+  ON_CONTEXT_ANALYTICS = 'on_context_analytics',
+  /** [Custom] Structured output event - emitted when agent returns structured JSON */
+  ON_STRUCTURED_OUTPUT = 'on_structured_output',
+  /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */
+  ON_TOOL_EXECUTE = 'on_tool_execute',
+
+  /* Official Events */
+
+  /** Custom event, emitted by system */
+  ON_CUSTOM_EVENT = 'on_custom_event',
+  /** Emitted when a chat model starts processing. */
+  CHAT_MODEL_START = 'on_chat_model_start',
+
+  /** Emitted when a chat model streams a chunk of its response. */
+  CHAT_MODEL_STREAM = 'on_chat_model_stream',
+
+  /** Emitted when a chat model completes its processing. */
+  CHAT_MODEL_END = 'on_chat_model_end',
+
+  /** Emitted when a language model starts processing. */
+  LLM_START = 'on_llm_start',
+
+  /** Emitted when a language model streams a chunk of its response. */
+  LLM_STREAM = 'on_llm_stream',
+
+  /** Emitted when a language model completes its processing. */
+  LLM_END = 'on_llm_end',
+
+  /** Emitted when a chain starts processing. */
+  CHAIN_START = 'on_chain_start',
+
+  /** Emitted when a chain streams a chunk of its output. */
+  CHAIN_STREAM = 'on_chain_stream',
+
+  /** Emitted when a chain completes its processing. */
+  CHAIN_END = 'on_chain_end',
+
+  /** Emitted when a tool starts its operation. */
+  TOOL_START = 'on_tool_start',
+
+  /** Emitted when a tool completes its operation. */
+  TOOL_END = 'on_tool_end',
+
+  /** Emitted when a retriever starts its operation. */
+  RETRIEVER_START = 'on_retriever_start',
+
+  /** Emitted when a retriever completes its operation. */
+  RETRIEVER_END = 'on_retriever_end',
+
+  /** Emitted when a prompt starts processing. */
+  PROMPT_START = 'on_prompt_start',
+
+  /** Emitted when a prompt completes its processing. */
+  PROMPT_END = 'on_prompt_end',
+}
+
+export enum Providers {
+  OPENAI = 'openAI',
+  VERTEXAI = 'vertexai',
+  BEDROCK = 'bedrock',
+  ANTHROPIC = 'anthropic',
+  MISTRALAI = 'mistralai',
+  MISTRAL = 'mistral',
+  GOOGLE = 'google',
+  AZURE = 'azureOpenAI',
+  DEEPSEEK = 'deepseek',
+  OPENROUTER = 'openrouter',
+  XAI = 'xai',
+  MOONSHOT = 'moonshot',
+}
+
+export enum GraphNodeKeys {
+  TOOLS = 'tools=',
+  AGENT = 'agent=',
+  ROUTER = 'router',
+  PRE_TOOLS = 'pre_tools',
+  POST_TOOLS = 'post_tools',
+}
+
+export enum GraphNodeActions {
+  TOOL_NODE = 'tool_node',
+  CALL_MODEL = 'call_model',
+  ROUTE_MESSAGE = 'route_message',
+}
+
+export enum CommonEvents {
+  LANGGRAPH = 'LangGraph',
+}
+
+export enum StepTypes {
+  TOOL_CALLS = 'tool_calls',
+  MESSAGE_CREATION = 'message_creation',
+}
+
+export enum ContentTypes {
+  TEXT = 'text',
+  ERROR = 'error',
+  THINK = 'think',
+  TOOL_CALL = 'tool_call',
+  IMAGE_URL = 'image_url',
+  IMAGE_FILE = 'image_file',
+  /** Anthropic */
+  THINKING = 'thinking',
+  /** Vertex AI / Google Common */
+  REASONING = 'reasoning',
+  /** Multi-Agent Switch */
+  AGENT_UPDATE = 'agent_update',
+  /** Bedrock */
+  REASONING_CONTENT = 'reasoning_content',
+}
+
+export enum ToolCallTypes {
+  FUNCTION = 'function',
+  RETRIEVAL = 'retrieval',
+  FILE_SEARCH = 'file_search',
+  CODE_INTERPRETER = 'code_interpreter',
+  /* Agents Tool Call */
+  TOOL_CALL = 'tool_call',
+}
+
+export enum Callback {
+  TOOL_ERROR = 'handleToolError',
+  TOOL_START = 'handleToolStart',
+  TOOL_END = 'handleToolEnd',
+  CUSTOM_EVENT = 'handleCustomEvent',
+  /*
+  LLM_START = 'handleLLMStart',
+  LLM_NEW_TOKEN = 'handleLLMNewToken',
+  LLM_ERROR = 'handleLLMError',
+  LLM_END = 'handleLLMEnd',
+  CHAT_MODEL_START = 'handleChatModelStart',
+  CHAIN_START = 'handleChainStart',
+  CHAIN_ERROR = 'handleChainError',
+  CHAIN_END = 'handleChainEnd',
+  TEXT = 'handleText',
+  AGENT_ACTION = 'handleAgentAction',
+  AGENT_END = 'handleAgentEnd',
+  RETRIEVER_START = 'handleRetrieverStart',
+  RETRIEVER_END = 'handleRetrieverEnd',
+  RETRIEVER_ERROR = 'handleRetrieverError',
+  */
+}
+
+export enum Constants {
+  OFFICIAL_CODE_BASEURL = 'https://api.illuma.ai/v1',
+  EXECUTE_CODE = 'execute_code',
+  TOOL_SEARCH = 'tool_search',
+  PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_code',
+  WEB_SEARCH = 'web_search',
+  CONTENT_AND_ARTIFACT = 'content_and_artifact',
+  LC_TRANSFER_TO_ = 'lc_transfer_to_',
+  /** Delimiter for MCP tools: toolName_mcp_serverName */
+  MCP_DELIMITER = '_mcp_',
+}
+
+export enum TitleMethod {
+  STRUCTURED = 'structured',
+  FUNCTIONS = 'functions',
+  COMPLETION = 'completion',
+}
+
+export enum EnvVar {
+  CODE_API_KEY = 'CODE_EXECUTOR_API_KEY',
+  CODE_BASEURL = 'CODE_EXECUTOR_BASEURL',
+}
+
+/**
+ * Message type identifiers used by LangChain's BaseMessage.getType().
+ * Use these constants instead of instanceof checks to avoid module mismatch issues
+ * when different copies of @langchain/core/messages are loaded.
+ */
+export enum MessageTypes {
+  HUMAN = 'human',
+  AI = 'ai',
+  SYSTEM = 'system',
+  TOOL = 'tool',
+  FUNCTION = 'function',
+  GENERIC = 'generic',
+  DEVELOPER = 'developer',
+  REMOVE = 'remove',
+}

package/src/common/index.ts

@@ -0,0 +1,2 @@
+// src/common/index.ts
+export * from './enum';

package/src/events.ts

@@ -0,0 +1,223 @@
+/* eslint-disable no-console */
+// src/events.ts
+import type {
+  ToolMessage,
+  UsageMetadata,
+  BaseMessageFields,
+} from '@langchain/core/messages';
+import type { MultiAgentGraph, StandardGraph } from '@/graphs';
+import type { Logger } from 'winston';
+import type * as t from '@/types';
+import { handleToolCalls } from '@/tools/handlers';
+import { Constants, Providers } from '@/common';
+
+export class HandlerRegistry {
+  private handlers: Map<string, t.EventHandler> = new Map();
+
+  register(eventType: string, handler: t.EventHandler): void {
+    this.handlers.set(eventType, handler);
+  }
+
+  getHandler(eventType: string): t.EventHandler | undefined {
+    return this.handlers.get(eventType);
+  }
+}
+
+export class ModelEndHandler implements t.EventHandler {
+  collectedUsage?: UsageMetadata[];
+  constructor(collectedUsage?: UsageMetadata[]) {
+    if (collectedUsage && !Array.isArray(collectedUsage)) {
+      throw new Error('collectedUsage must be an array');
+    }
+    this.collectedUsage = collectedUsage;
+  }
+
+  async handle(
+    event: string,
+    data: t.ModelEndData,
+    metadata?: Record<string, unknown>,
+    graph?: StandardGraph | MultiAgentGraph
+  ): Promise<void> {
+    if (!graph || !metadata) {
+      console.warn(`Graph or metadata not found in ${event} event`);
+      return;
+    }
+
+    const usage = data?.output?.usage_metadata;
+    if (usage != null && this.collectedUsage != null) {
+      this.collectedUsage.push(usage);
+    }
+
+    if (metadata.ls_provider === 'FakeListChatModel') {
+      return handleToolCalls(data?.output?.tool_calls, metadata, graph);
+    }
+
+    console.log(`====== ${event.toUpperCase()} ======`);
+    console.dir(
+      {
+        usage,
+      },
+      { depth: null }
+    );
+
+    const agentContext = graph.getAgentContext(metadata);
+
+    if (
+      agentContext.provider !== Providers.GOOGLE &&
+      agentContext.provider !== Providers.BEDROCK
+    ) {
+      return;
+    }
+
+    await handleToolCalls(data?.output?.tool_calls, metadata, graph);
+  }
+}
+
+export class ToolEndHandler implements t.EventHandler {
+  private callback?: t.ToolEndCallback;
+  private logger?: Logger;
+  private omitOutput?: (name?: string) => boolean;
+  constructor(
+    callback?: t.ToolEndCallback,
+    logger?: Logger,
+    omitOutput?: (name?: string) => boolean
+  ) {
+    this.callback = callback;
+    this.logger = logger;
+    this.omitOutput = omitOutput;
+  }
+  async handle(
+    event: string,
+    data: t.StreamEventData | undefined,
+    metadata?: Record<string, unknown>,
+    graph?: StandardGraph | MultiAgentGraph
+  ): Promise<void> {
+    try {
+      if (!graph || !metadata) {
+        if (this.logger) {
+          this.logger.warn(`Graph or metadata not found in ${event} event`);
+        } else {
+          console.warn(`Graph or metadata not found in ${event} event`);
+        }
+        return;
+      }
+
+      const toolEndData = data as t.ToolEndData | undefined;
+      if (!toolEndData?.output) {
+        if (this.logger) {
+          this.logger.warn('No output found in tool_end event');
+        } else {
+          console.warn('No output found in tool_end event');
+        }
+        return;
+      }
+
+      if (metadata[Constants.PROGRAMMATIC_TOOL_CALLING] === true) {
+        return;
+      }
+
+      if (this.callback) {
+        await this.callback(toolEndData, metadata);
+      }
+      await graph.handleToolCallCompleted(
+        { input: toolEndData.input, output: toolEndData.output },
+        metadata,
+        this.omitOutput?.((toolEndData.output as ToolMessage | undefined)?.name)
+      );
+    } catch (error) {
+      if (this.logger) {
+        this.logger.error('Error handling tool_end event:', error);
+      } else {
+        console.error('Error handling tool_end event:', error);
+      }
+    }
+  }
+}
+
+export class TestLLMStreamHandler implements t.EventHandler {
+  handle(event: string, data: t.StreamEventData | undefined): void {
+    const chunk = data?.chunk;
+    const isMessageChunk = !!(chunk && 'message' in chunk);
+    const msg = isMessageChunk ? chunk.message : undefined;
+    if (msg && msg.tool_call_chunks && msg.tool_call_chunks.length > 0) {
+      console.log(msg.tool_call_chunks);
+    } else if (msg && msg.content) {
+      if (typeof msg.content === 'string') {
+        process.stdout.write(msg.content);
+      }
+    }
+  }
+}
+
+export class TestChatStreamHandler implements t.EventHandler {
+  handle(event: string, data: t.StreamEventData | undefined): void {
+    const chunk = data?.chunk;
+    const isContentChunk = !!(chunk && 'content' in chunk);
+    const content = isContentChunk && chunk.content;
+
+    if (!content || !isContentChunk) {
+      return;
+    }
+
+    if (chunk.tool_call_chunks && chunk.tool_call_chunks.length > 0) {
+      console.dir(chunk.tool_call_chunks, { depth: null });
+    }
+
+    if (typeof content === 'string') {
+      process.stdout.write(content);
+    } else {
+      console.dir(content, { depth: null });
+    }
+  }
+}
+
+export class LLMStreamHandler implements t.EventHandler {
+  handle(
+    event: string,
+    data: t.StreamEventData | undefined,
+    metadata?: Record<string, unknown>
+  ): void {
+    const chunk = data?.chunk;
+    const isMessageChunk = !!(chunk && 'message' in chunk);
+    const msg = isMessageChunk && chunk.message;
+    if (metadata) {
+      console.log(metadata);
+    }
+    if (msg && msg.tool_call_chunks && msg.tool_call_chunks.length > 0) {
+      console.log(msg.tool_call_chunks);
+    } else if (msg && msg.content) {
+      if (typeof msg.content === 'string') {
+        // const text_delta = msg.content;
+        // dispatchCustomEvent(GraphEvents.CHAT_MODEL_STREAM, { chunk }, config);
+        process.stdout.write(msg.content);
+      }
+    }
+  }
+}
+
+export const createMetadataAggregator = (
+  _collected?: Record<
+    string,
+    NonNullable<BaseMessageFields['response_metadata']>
+  >[]
+): t.MetadataAggregatorResult => {
+  const collected = _collected || [];
+
+  const handleLLMEnd: t.HandleLLMEnd = (output) => {
+    const { generations } = output;
+    const lastMessageOutput = (
+      generations[generations.length - 1] as
+        | (t.StreamGeneration | undefined)[]
+        | undefined
+    )?.[0];
+    if (!lastMessageOutput) {
+      return;
+    }
+    const { message } = lastMessageOutput;
+    if (message?.response_metadata) {
+      collected.push(message.response_metadata);
+    }
+  };
+
+  return { handleLLMEnd, collected };
+};