illuma-agents 1.0.2 → 1.0.4

package/dist/types/types/graph.d.ts

@@ -1,23 +1,89 @@
-import type { StateGraphArgs, StateGraph, CompiledStateGraph } from '@langchain/langgraph';
+import type { START, StateType, UpdateType, StateGraph, StateGraphArgs, StateDefinition, CompiledStateGraph, BinaryOperatorAggregate } from '@langchain/langgraph';
 import type { BindToolsInput } from '@langchain/core/language_models/chat_models';
-import type { BaseMessage, AIMessageChunk } from '@langchain/core/messages';
+import type { BaseMessage, AIMessageChunk, SystemMessage } from '@langchain/core/messages';
+import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 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 { ToolMap, ToolEndEvent, GenericTool } from '@/types/tools';
+import type { Providers, Callback, GraphNodeKeys } from '@/common';
+import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
-import type { Providers } from '@/common';
-import type { Graph } from '@/graphs';
+import type { RunStep, RunStepDeltaEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
+import type { TokenCounter } from '@/types/run';
+/** Interface for bound model with stream and invoke methods */
+export interface ChatModel {
+    stream?: (messages: BaseMessage[], config?: RunnableConfig) => Promise<AsyncIterable<AIMessageChunk>>;
+    invoke: (messages: BaseMessage[], config?: RunnableConfig) => Promise<AIMessageChunk>;
+}
+export type GraphNode = GraphNodeKeys | typeof START;
+export type ClientCallback<T extends unknown[]> = (graph: StandardGraph, ...args: T) => void;
+export type ClientCallbacks = {
+    [Callback.TOOL_ERROR]?: ClientCallback<[Error, string]>;
+    [Callback.TOOL_START]?: ClientCallback<unknown[]>;
+    [Callback.TOOL_END]?: ClientCallback<unknown[]>;
+};
+export type SystemCallbacks = {
+    [K in keyof ClientCallbacks]: ClientCallbacks[K] extends ClientCallback<infer Args> ? (...args: Args) => void : never;
+};
 export type BaseGraphState = {
     messages: BaseMessage[];
 };
+export type MultiAgentGraphState = BaseGraphState & {
+    agentMessages?: BaseMessage[];
+};
 export type IState = BaseGraphState;
 export interface EventHandler {
-    handle(event: string, data: StreamEventData | ModelEndData, metadata?: Record<string, unknown>, graph?: Graph): void;
+    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | MessageDeltaEvent | ReasoningDeltaEvent | {
+        result: ToolEndEvent;
+    }, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): void | Promise<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 CompiledStateWorkflow = CompiledStateGraph<StateType<{
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}>, UpdateType<{
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}>, string, {
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}, {
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}, StateDefinition>;
+export type CompiledMultiAgentWorkflow = CompiledStateGraph<StateType<{
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}>, UpdateType<{
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}>, string, {
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}, {
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}, StateDefinition>;
+export type CompiledAgentWorfklow = CompiledStateGraph<{
+    messages: BaseMessage[];
+}, {
+    messages?: BaseMessage[] | undefined;
+}, '__start__' | `agent=${string}` | `tools=${string}`, {
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}, {
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}, StateDefinition, {
+    [x: `agent=${string}`]: Partial<BaseGraphState>;
+    [x: `tools=${string}`]: any;
+}>;
+export type SystemRunnable = Runnable<BaseMessage[], (BaseMessage | SystemMessage)[], RunnableConfig<Record<string, unknown>>> | undefined;
+/**
+ * Optional compile options passed to workflow.compile().
+ * These are intentionally untyped to avoid coupling to library internals.
+ */
+export type CompileOptions = {
+    checkpointer?: any;
+    interruptBefore?: string[];
+    interruptAfter?: string[];
+};
 export type EventStreamCallbackHandlerInput = Parameters<CompiledWorkflow['streamEvents']>[2] extends Omit<infer T, 'autoClose'> ? T : never;
 export type StreamChunk = (ChatGenerationChunk & {
     message: AIMessageChunk;
@@ -57,6 +123,10 @@ export type StreamEventData = {
      * Custom result from the runnable that generated the event.
      */
     result?: unknown;
+    /**
+     * Custom field to indicate the event was manually emitted, and may have been handled already
+     */
+    emitted?: boolean;
 };
 /**
  * A streaming event.
@@ -125,14 +195,57 @@ export type ModelEndData = (StreamEventData & {
 export type GraphTools = GenericTool[] | BindToolsInput[] | GoogleAIToolType[];
 export type StandardGraphInput = {
     runId?: string;
+    signal?: AbortSignal;
+    agents: AgentInputs[];
+    tokenCounter?: TokenCounter;
+    indexTokenCountMap?: Record<string, number>;
+};
+export type GraphEdge = {
+    /** Agent ID, use a list for multiple sources */
+    from: string | string[];
+    /** Agent ID, use a list for multiple destinations */
+    to: string | string[];
+    description?: string;
+    /** Can return boolean or specific destination(s) */
+    condition?: (state: BaseGraphState) => boolean | string | string[];
+    /** 'handoff' creates tools for dynamic routing, 'direct' creates direct edges, which also allow parallel execution */
+    edgeType?: 'handoff' | 'direct';
+    /**
+     * For direct edges: Optional prompt to add when transitioning through this edge.
+     * String prompts can include variables like {results} which will be replaced with
+     * messages from startIndex onwards. When {results} is used, excludeResults defaults to true.
+     *
+     * For handoff edges: Description for the input parameter that the handoff tool accepts,
+     * allowing the supervisor to pass specific instructions/context to the transferred agent.
+     */
+    prompt?: string | ((messages: BaseMessage[], runStartIndex: number) => string | Promise<string> | undefined);
+    /**
+     * When true, excludes messages from startIndex when adding prompt.
+     * Automatically set to true when {results} variable is used in prompt.
+     */
+    excludeResults?: boolean;
+    /**
+     * For handoff edges: Customizes the parameter name for the handoff input.
+     * Defaults to "instructions" if not specified.
+     * Only applies when prompt is provided for handoff edges.
+     */
+    promptKey?: string;
+};
+export type MultiAgentGraphInput = StandardGraphInput & {
+    edges: GraphEdge[];
+};
+export interface AgentInputs {
+    agentId: string;
     toolEnd?: boolean;
     toolMap?: ToolMap;
+    tools?: GraphTools;
     provider: Providers;
-    signal?: AbortSignal;
     instructions?: string;
     streamBuffer?: number;
-    clientOptions: ClientOptions;
+    maxContextTokens?: number;
+    clientOptions?: ClientOptions;
     additional_instructions?: string;
     reasoningKey?: 'reasoning_content' | 'reasoning';
-    tools?: GraphTools;
-};
+    /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */
+    useLegacyContent?: boolean;
+}

package/dist/types/types/llm.d.ts

@@ -1,11 +1,8 @@
 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';
@@ -22,6 +19,7 @@ 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 { CustomAnthropic } from '@/llm/anthropic';
 import { ChatOpenRouter } from '@/llm/openrouter';
 import { ChatVertexAI } from '@/llm/vertexai';
 import { Providers } from '@/common';
@@ -47,22 +45,30 @@ export type MistralAIClientOptions = ChatMistralAIInput;
 export type VertexAIClientOptions = ChatVertexAIInput & {
     includeThoughts?: boolean;
 };
-export type BedrockClientOptions = BedrockChatFields;
 export type BedrockAnthropicInput = ChatBedrockConverseInput & {
     additionalModelRequestFields?: ChatBedrockConverseInput['additionalModelRequestFields'] & AnthropicReasoning;
+    promptCache?: boolean;
 };
 export type BedrockConverseClientOptions = ChatBedrockConverseInput;
+export type BedrockAnthropicClientOptions = BedrockAnthropicInput;
 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 ClientOptions = OpenAIClientOptions | AzureClientOptions | OllamaClientOptions | AnthropicClientOptions | MistralAIClientOptions | VertexAIClientOptions | BedrockConverseClientOptions | GoogleClientOptions | DeepSeekClientOptions | XAIClientOptions;
 export type SharedLLMConfig = {
     provider: Providers;
+    _lc_stream_delay?: number;
+};
+export type LLMConfig = SharedLLMConfig & ClientOptions & {
+    /** Optional provider fallbacks in order of attempt */
+    fallbacks?: Array<{
+        provider: Providers;
+        clientOptions?: ClientOptions;
+    }>;
 };
-export type LLMConfig = SharedLLMConfig & ClientOptions;
 export type ProviderOptionsMap = {
     [Providers.AZURE]: AzureClientOptions;
     [Providers.OPENAI]: OpenAIClientOptions;
@@ -74,7 +80,6 @@ export type ProviderOptionsMap = {
     [Providers.MISTRALAI]: MistralAIClientOptions;
     [Providers.MISTRAL]: MistralAIClientOptions;
     [Providers.OPENROUTER]: ChatOpenRouterCallOptions;
-    [Providers.BEDROCK_LEGACY]: BedrockClientOptions;
     [Providers.BEDROCK]: BedrockConverseClientOptions;
     [Providers.XAI]: XAIClientOptions;
 };
@@ -85,11 +90,10 @@ export type ChatModelMap = {
     [Providers.AZURE]: AzureChatOpenAI;
     [Providers.DEEPSEEK]: ChatDeepSeek;
     [Providers.VERTEXAI]: ChatVertexAI;
-    [Providers.ANTHROPIC]: ChatAnthropic;
+    [Providers.ANTHROPIC]: CustomAnthropic;
     [Providers.MISTRALAI]: ChatMistralAI;
     [Providers.MISTRAL]: ChatMistralAI;
     [Providers.OPENROUTER]: ChatOpenRouter;
-    [Providers.BEDROCK_LEGACY]: BedrockChat;
     [Providers.BEDROCK]: ChatBedrockConverse;
     [Providers.GOOGLE]: CustomChatGoogleGenerativeAI;
 };

package/dist/types/types/messages.d.ts

@@ -0,0 +1,4 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import type { BaseMessage } from '@langchain/core/messages';
+export type AnthropicMessages = Array<AnthropicMessage | BaseMessage>;
+export type AnthropicMessage = Anthropic.MessageParam;

package/dist/types/types/run.d.ts

@@ -3,19 +3,48 @@ 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';
 export type ZodObjectAny = z.ZodObject<any, any, any, any>;
 export type BaseGraphConfig = {
-    type?: 'standard';
     llmConfig: l.LLMConfig;
     provider?: e.Providers;
     clientOptions?: l.ClientOptions;
+    /** Optional compile options for workflow.compile() */
+    compileOptions?: g.CompileOptions;
 };
-export type StandardGraphConfig = BaseGraphConfig & Omit<g.StandardGraphInput, 'provider' | 'clientOptions'>;
+export type LegacyGraphConfig = BaseGraphConfig & {
+    type?: 'standard';
+} & Omit<g.StandardGraphInput, 'provider' | 'clientOptions' | 'agents'> & Omit<g.AgentInputs, 'provider' | 'clientOptions' | 'agentId'>;
+export type SupervisedGraphConfig = BaseGraphConfig & {
+    type: 'supervised';
+    /** Enable supervised router; when false, fall back to standard loop */
+    routerEnabled?: boolean;
+    /** Table-driven routing policy per stage */
+    routingPolicies?: Array<{
+        stage: string;
+        agents?: string[];
+        model?: e.Providers;
+        parallel?: boolean;
+        /** Optional simple condition on content/tools */
+        when?: 'always' | 'has_tools' | 'no_tools' | {
+            includes?: string[];
+            excludes?: string[];
+        };
+    }>;
+    /** Opt-in feature flags */
+    featureFlags?: {
+        multi_model_routing?: boolean;
+        fan_out?: boolean;
+        fan_out_retries?: number;
+        fan_out_backoff_ms?: number;
+        fan_out_concurrency?: number;
+    };
+    /** Optional per-stage model configs */
+    models?: Record<string, l.LLMConfig>;
+} & Omit<g.StandardGraphInput, 'provider' | 'clientOptions'>;
 export type RunTitleOptions = {
     inputText: string;
     provider: e.Providers;
@@ -57,18 +86,27 @@ export type TaskManagerGraphConfig = {
         llmConfig: l.LLMConfig;
     };
 };
+export type MultiAgentGraphConfig = {
+    type: 'multi-agent';
+    compileOptions?: g.CompileOptions;
+    agents: g.AgentInputs[];
+    edges: g.GraphEdge[];
+};
+export type StandardGraphConfig = Omit<MultiAgentGraphConfig, 'edges' | 'type'> & {
+    type?: 'standard';
+    signal?: AbortSignal;
+};
 export type RunConfig = {
     runId: string;
-    graphConfig: StandardGraphConfig | CollaborativeGraphConfig | TaskManagerGraphConfig;
+    graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
     customHandlers?: Record<string, g.EventHandler>;
     returnContent?: boolean;
+    tokenCounter?: TokenCounter;
+    indexTokenCountMap?: Record<string, number>;
 };
 export type ProvidedCallbacks = (BaseCallbackHandler | CallbackHandlerMethods)[] | undefined;
 export type TokenCounter = (message: BaseMessage) => number;
 export type EventStreamOptions = {
-    callbacks?: graph.ClientCallbacks;
+    callbacks?: g.ClientCallbacks;
     keepContent?: boolean;
-    maxContextTokens?: number;
-    tokenCounter?: TokenCounter;
-    indexTokenCountMap?: Record<string, number>;
 };

package/dist/types/types/stream.d.ts

@@ -3,6 +3,7 @@ import type { MessageContentImageUrl, MessageContentText, ToolMessage, BaseMessa
 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 { Command } from '@langchain/langgraph';
 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;
@@ -65,7 +66,7 @@ export type MessageCreationDetails = {
 };
 export type ToolEndData = {
     input: string | Record<string, unknown>;
-    output?: ToolMessage;
+    output?: ToolMessage | Command;
 };
 export type ToolErrorData = {
     id: string;
@@ -220,7 +221,7 @@ 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;
+    name?: string;
     /** The arguments to the tool call */
     args?: string | Record<string, any>;
     /** If provided, an identifier associated with the tool call */

package/dist/types/utils/events.d.ts

@@ -0,0 +1,6 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+/**
+ * Safely dispatches a custom event and properly awaits it to avoid
+ * race conditions where events are dispatched after run cleanup.
+ */
+export declare function safeDispatchCustomEvent(event: string, payload: unknown, config?: RunnableConfig): Promise<void>;

package/dist/types/utils/handlers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Multi-Agent Handler Utilities
+ *
+ * Provides a simple helper to create handlers with content aggregation for multi-agent scripts.
+ *
+ * Usage:
+ * ```typescript
+ * const { contentParts, aggregateContent, handlers } = createHandlers();
+ *
+ * // With callbacks
+ * const { contentParts, aggregateContent, handlers } = createHandlers({
+ *   onRunStep: (event, data) => console.log('Step:', data),
+ *   onRunStepCompleted: (event, data) => console.log('Completed:', data)
+ * });
+ * ```
+ */
+import { GraphEvents } from '@/common';
+import { createContentAggregator } from '@/stream';
+import type * as t from '@/types';
+interface HandlerCallbacks {
+    onRunStep?: (event: GraphEvents.ON_RUN_STEP, data: t.StreamEventData) => void;
+    onRunStepCompleted?: (event: GraphEvents.ON_RUN_STEP_COMPLETED, data: t.StreamEventData) => void;
+    onRunStepDelta?: (event: GraphEvents.ON_RUN_STEP_DELTA, data: t.StreamEventData) => void;
+    onMessageDelta?: (event: GraphEvents.ON_MESSAGE_DELTA, data: t.StreamEventData) => void;
+}
+/**
+ * Creates handlers with content aggregation for multi-agent scripts
+ */
+export declare function createHandlers(callbacks?: HandlerCallbacks): {
+    contentParts: Array<t.MessageContentComplex | undefined>;
+    aggregateContent: ReturnType<typeof createContentAggregator>['aggregateContent'];
+    handlers: Record<string, t.EventHandler>;
+};
+export {};

package/dist/types/utils/index.d.ts

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

package/dist/types/utils/tokens.d.ts

@@ -1,3 +1,27 @@
 import type { BaseMessage } from '@langchain/core/messages';
 export declare function getTokenCountForMessage(message: BaseMessage, getTokenCount: (text: string) => number): number;
+/**
+ * Creates a singleton token counter function that reuses the same encoder instance.
+ * This avoids creating multiple function closures and prevents potential memory issues.
+ */
 export declare const createTokenCounter: () => Promise<(message: BaseMessage) => number>;
+/**
+ * Utility to manage the token encoder lifecycle explicitly.
+ * Useful for applications that need fine-grained control over resource management.
+ */
+export declare const TokenEncoderManager: {
+    /**
+     * Pre-initializes the encoder. This can be called during app startup
+     * to avoid lazy loading delays later.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Clears the cached encoder and token counter.
+     * Useful for testing or when you need to force a fresh reload.
+     */
+    reset(): void;
+    /**
+     * Checks if the encoder has been initialized.
+     */
+    isInitialized(): boolean;
+};