illuma-agents 1.0.16 → 1.0.18

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

@@ -0,0 +1,37 @@
+/**
+ * Context Analytics Utility
+ *
+ * Provides context analytics data for observability/traces.
+ * No console logging - just data structures for event emission.
+ */
+import type { BaseMessage } from '@langchain/core/messages';
+import type { TokenCounter } from '@/types/run';
+/**
+ * Context analytics data for traces
+ */
+export interface ContextAnalytics {
+    /** Total messages in context */
+    messageCount: number;
+    /** Total tokens in context */
+    totalTokens: number;
+    /** Maximum allowed context tokens */
+    maxContextTokens?: number;
+    /** Instruction/system tokens */
+    instructionTokens?: number;
+    /** Context utilization percentage (0-100) */
+    utilizationPercent?: number;
+    /** Breakdown by message type */
+    breakdown?: Record<string, {
+        tokens: number;
+        percent: number;
+    }>;
+}
+/**
+ * Build context analytics for traces (no logging)
+ */
+export declare function buildContextAnalytics(messages: BaseMessage[], options: {
+    tokenCounter?: TokenCounter;
+    maxContextTokens?: number;
+    instructionTokens?: number;
+    indexTokenCountMap?: Record<string, number | undefined>;
+}): ContextAnalytics;

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

@@ -4,3 +4,5 @@ export * from './misc';
 export * from './handlers';
 export * from './run';
 export * from './tokens';
+export * from './toonFormat';
+export * from './contextAnalytics';

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

@@ -0,0 +1,111 @@
+/**
+ * TOON Format Utility
+ *
+ * Provides JSON to TOON conversion for token-efficient encoding.
+ * TOON format can reduce token count by 30-60% for JSON data.
+ *
+ * Uses the official @toon-format/toon library when available.
+ */
+/**
+ * Ensures the TOON library is loaded. Call this before using jsonToToon in tests.
+ */
+export declare function ensureToonLoaded(): Promise<boolean>;
+/**
+ * Check if a string appears to be in TOON format.
+ * TOON format characteristics:
+ * - Uses key: value syntax (like YAML)
+ * - Uses array notation like [3] or {fields}
+ * - Does NOT start with { or [
+ * - Often has patterns like "name[N]:" or "name{fields}:"
+ *
+ * @param str - String to check
+ * @returns true if string appears to be TOON format
+ */
+export declare function isToonFormat(str: string): boolean;
+/**
+ * Extract the first valid JSON object or array from a string.
+ * Handles pure JSON or JSON embedded in text (e.g., tool responses).
+ *
+ * @param str - The string to extract JSON from
+ * @returns Object with found status, parsed JSON, and indices
+ */
+export declare function extractFirstJson(str: string): {
+    found: boolean;
+    parsed: unknown;
+    startIndex: number;
+    endIndex: number;
+};
+/**
+ * Convert JSON content to TOON format for token efficiency.
+ * Extracts JSON from string if embedded, converts to TOON.
+ * Returns original string if:
+ * - Already in TOON format
+ * - Not JSON
+ * - TOON conversion fails or is larger
+ *
+ * @param str - The string containing JSON to convert
+ * @returns Object with conversion status, result, and reduction percentage
+ */
+export declare function jsonToToon(str: string): {
+    converted: boolean;
+    result: string;
+    reduction: number;
+    alreadyToon?: boolean;
+    error?: string;
+};
+/**
+ * Check if TOON library is loaded and available
+ */
+export declare function isToonAvailable(): boolean;
+/**
+ * Result of processing tool output
+ */
+export interface ProcessToolOutputResult {
+    /** The processed content string */
+    content: string;
+    /** Whether TOON conversion was applied */
+    toonConverted: boolean;
+    /** Whether content was truncated */
+    truncated: boolean;
+    /** Percentage reduction from TOON (0 if not converted) */
+    reduction: number;
+    /** Whether input was already in TOON format */
+    alreadyToon: boolean;
+    /** Original content length */
+    originalLength: number;
+    /** Estimated original tokens (~4 chars per token) */
+    originalTokens: number;
+    /** Final content length */
+    finalLength: number;
+    /** Estimated final tokens */
+    finalTokens: number;
+    /** Error message if TOON conversion failed (for debugging) */
+    toonError?: string;
+}
+/**
+ * Options for processing tool output
+ */
+export interface ProcessToolOutputOptions {
+    /** Maximum output length in characters (default: 100000) */
+    maxLength?: number;
+    /** Whether to apply TOON conversion (default: true) */
+    enableToon?: boolean;
+    /** Minimum content size to attempt TOON conversion (default: 1000) */
+    minSizeForToon?: number;
+    /** Minimum reduction % to accept TOON result (default: 10) */
+    minReductionPercent?: number;
+}
+/**
+ * Process tool output: apply TOON conversion if beneficial, then truncate if needed.
+ * This is the main entry point for processing any tool output (regular or MCP).
+ *
+ * Flow:
+ * 1. Check if already TOON format → skip conversion
+ * 2. Try TOON conversion if content is JSON and large enough
+ * 3. Truncate if still exceeds maxLength (with smart break points)
+ *
+ * @param content - The tool output content
+ * @param options - Processing options
+ * @returns Processed content and metadata
+ */
+export declare function processToolOutput(content: string, options?: ProcessToolOutputOptions): ProcessToolOutputResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "illuma-agents",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -41,7 +41,7 @@
     "image": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/image.ts --provider 'google' --name 'Jo' --location 'New York, NY'",
     "code_exec_files": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_files.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
     "code_exec_simple": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_simple.ts --provider 'google' --name 'Jo' --location 'New York, NY'",
-    "simple": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/simple.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "simple": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/simple.ts --provider 'openrouter' --name 'Jo' --location 'New York, NY'",
     "caching": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/caching.ts --name 'Jo' --location 'New York, NY'",
     "thinking": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/thinking.ts --name 'Jo' --location 'New York, NY'",
     "memory": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/memory.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
@@ -111,6 +111,7 @@
     "@langfuse/otel": "^4.3.0",
     "@langfuse/tracing": "^4.3.0",
     "@opentelemetry/sdk-node": "^0.207.0",
+    "@toon-format/toon": "^2.1.0",
     "axios": "^1.12.1",
     "cheerio": "^1.0.0",
     "dotenv": "^16.4.7",

package/src/agents/AgentContext.ts

@@ -166,13 +166,13 @@ export class AgentContext {
     artifacts: number;
     memory: number;
   } = {
-    branding: 0,
-    toolRouting: 0,
-    agentInstructions: 0,
-    mcpInstructions: 0,
-    artifacts: 0,
-    memory: 0,
-  };
+      branding: 0,
+      toolRouting: 0,
+      agentInstructions: 0,
+      mcpInstructions: 0,
+      artifacts: 0,
+      memory: 0,
+    };
 
   constructor({
     agentId,
@@ -403,10 +403,12 @@ export class AgentContext {
         | t.BedrockAnthropicInput
         | undefined;
       const modelId = bedrockOptions?.model?.toLowerCase() ?? '';
-      const supportsCaching = modelId.includes('claude') || modelId.includes('anthropic') || modelId.includes('nova');
+      const supportsCaching =
+        modelId.includes('claude') ||
+        modelId.includes('anthropic') ||
+        modelId.includes('nova');
 
       if (bedrockOptions?.promptCache === true && supportsCaching) {
-        
         finalInstructions = {
           content: [
             {
@@ -485,7 +487,7 @@ export class AgentContext {
   ): Promise<void> {
     let toolTokens = 0;
     this.toolsDetail = []; // Reset per-tool breakdown
-    
+
     if (this.tools && this.tools.length > 0) {
       for (const tool of this.tools) {
         const genericTool = tool as Record<string, unknown>;
@@ -507,7 +509,7 @@ export class AgentContext {
           const tokens = tokenCounter(
             new SystemMessage(JSON.stringify(jsonSchema))
           );
-          
+
           // Track per-tool breakdown
           this.toolsDetail.push({ name: toolName, tokens });
           toolTokens += tokens;
@@ -517,7 +519,7 @@ export class AgentContext {
 
     // Store total tool tokens for breakdown reporting
     this.toolTokensTotal = toolTokens;
-    
+
     // Add tool tokens to existing instruction tokens (which may already include system message tokens)
     this.instructionTokens += toolTokens;
   }
@@ -535,12 +537,18 @@ export class AgentContext {
     artifacts?: number;
     memory?: number;
   }): void {
-    if (breakdown.branding !== undefined) this.promptBreakdown.branding = breakdown.branding;
-    if (breakdown.toolRouting !== undefined) this.promptBreakdown.toolRouting = breakdown.toolRouting;
-    if (breakdown.agentInstructions !== undefined) this.promptBreakdown.agentInstructions = breakdown.agentInstructions;
-    if (breakdown.mcpInstructions !== undefined) this.promptBreakdown.mcpInstructions = breakdown.mcpInstructions;
-    if (breakdown.artifacts !== undefined) this.promptBreakdown.artifacts = breakdown.artifacts;
-    if (breakdown.memory !== undefined) this.promptBreakdown.memory = breakdown.memory;
+    if (breakdown.branding !== undefined)
+      this.promptBreakdown.branding = breakdown.branding;
+    if (breakdown.toolRouting !== undefined)
+      this.promptBreakdown.toolRouting = breakdown.toolRouting;
+    if (breakdown.agentInstructions !== undefined)
+      this.promptBreakdown.agentInstructions = breakdown.agentInstructions;
+    if (breakdown.mcpInstructions !== undefined)
+      this.promptBreakdown.mcpInstructions = breakdown.mcpInstructions;
+    if (breakdown.artifacts !== undefined)
+      this.promptBreakdown.artifacts = breakdown.artifacts;
+    if (breakdown.memory !== undefined)
+      this.promptBreakdown.memory = breakdown.memory;
   }
 
   /**
@@ -565,9 +573,9 @@ export class AgentContext {
       artifacts: number;
       memory: number;
     };
-  } {
+    } {
     // Calculate sum of prompt components
-    const promptsTotal = 
+    const promptsTotal =
       this.promptBreakdown.branding +
       this.promptBreakdown.toolRouting +
       this.promptBreakdown.agentInstructions +

package/src/common/enum.ts

@@ -19,6 +19,8 @@ export enum GraphEvents {
   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',
 
   /* Official Events */
 
@@ -176,3 +178,19 @@ 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',
+}