@illuma-ai/agents 1.1.28 → 1.3.1

package/src/graphs/__tests__/structured-output.integration.test.ts

@@ -8,7 +8,8 @@
  * the required environment variables are not set.
  *
  * To run:
- *   1. Copy ranger/.env credentials to agents/.env (or set env vars directly)
+ *   1. Set env vars directly, or set AGENTS_TEST_ENV_PATH to point at
+ *      a host .env file containing the required credentials.
  *   2. npm test -- --testPathPattern=structured-output.integration
  *
  * Environment variables needed:
@@ -19,14 +20,23 @@
 import { config } from 'dotenv';
 import { resolve } from 'path';
 
-// Load from ranger/.env if agents/.env doesn't exist
-config(); // Try local first
-config({ path: resolve(__dirname, '../../../../ranger/.env') }); // Then ranger
-
-import { HumanMessage, SystemMessage, AIMessageChunk } from '@langchain/core/messages';
+// Load local .env first; optionally fall back to a host-provided env file.
+config();
+if (process.env.AGENTS_TEST_ENV_PATH) {
+  config({ path: resolve(process.env.AGENTS_TEST_ENV_PATH) });
+}
+
+import {
+  HumanMessage,
+  SystemMessage,
+  AIMessageChunk,
+} from '@langchain/core/messages';
 import { CustomChatBedrockConverse } from '@/llm/bedrock';
 import { Providers } from '@/common';
-import { validateStructuredOutput, prepareSchemaForProvider } from '@/schemas/validate';
+import {
+  validateStructuredOutput,
+  prepareSchemaForProvider,
+} from '@/schemas/validate';
 
 jest.setTimeout(120000);
 
@@ -114,10 +124,15 @@ describe('Bedrock structured output integration', () => {
 
       const result = await structuredModel.invoke([
         new SystemMessage('Extract person information from the text.'),
-        new HumanMessage('John Smith is a 35 year old software engineer from Seattle.'),
+        new HumanMessage(
+          'John Smith is a 35 year old software engineer from Seattle.'
+        ),
       ]);
 
-      console.log('[Integration] Bedrock functionCalling result:', JSON.stringify(result.parsed ?? result, null, 2));
+      console.log(
+        '[Integration] Bedrock functionCalling result:',
+        JSON.stringify(result.parsed ?? result, null, 2)
+      );
 
       const parsed = result.parsed ?? result;
       expect(parsed).toBeDefined();
@@ -128,7 +143,7 @@ describe('Bedrock structured output integration', () => {
       // Validate against schema
       const validation = validateStructuredOutput(parsed, personSchema);
       expect(validation.success).toBe(true);
-    },
+    }
   );
 
   conditionalTest(
@@ -144,75 +159,87 @@ describe('Bedrock structured output integration', () => {
 
       const result = await structuredModel.invoke([
         new SystemMessage('Classify the sentiment of the following text.'),
-        new HumanMessage('I absolutely love this product! It exceeded all my expectations.'),
+        new HumanMessage(
+          'I absolutely love this product! It exceeded all my expectations.'
+        ),
       ]);
 
       const parsed = result.parsed ?? result;
-      console.log('[Integration] Bedrock classification result:', JSON.stringify(parsed, null, 2));
+      console.log(
+        '[Integration] Bedrock classification result:',
+        JSON.stringify(parsed, null, 2)
+      );
 
       expect(parsed).toBeDefined();
       expect(['positive', 'negative', 'neutral']).toContain(parsed.category);
       expect(typeof parsed.confidence).toBe('number');
       expect(typeof parsed.reasoning).toBe('string');
-    },
+    }
   );
 
-  conditionalTest(
-    'withStructuredOutput with prepared schema',
-    async () => {
-      const rawSchema = {
-        type: 'object',
-        properties: {
-          summary: { type: 'string', maxLength: 500 },
-          topics: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 5 },
-          wordCount: { type: 'number', minimum: 0 },
+  conditionalTest('withStructuredOutput with prepared schema', async () => {
+    const rawSchema = {
+      type: 'object',
+      properties: {
+        summary: { type: 'string', maxLength: 500 },
+        topics: {
+          type: 'array',
+          items: { type: 'string' },
+          minItems: 1,
+          maxItems: 5,
         },
-      };
-
-      // Prepare schema for Bedrock
-      const { schema: prepared, warnings } = prepareSchemaForProvider(
-        rawSchema,
-        Providers.BEDROCK,
-      );
+        wordCount: { type: 'number', minimum: 0 },
+      },
+    };
 
-      console.log('[Integration] Schema preparation warnings:', warnings);
+    // Prepare schema for Bedrock
+    const { schema: prepared, warnings } = prepareSchemaForProvider(
+      rawSchema,
+      Providers.BEDROCK
+    );
 
-      // Verify preparation worked
-      expect(prepared.additionalProperties).toBe(false);
-      expect(prepared.required).toEqual(
-        expect.arrayContaining(['summary', 'topics', 'wordCount']),
-      );
-      const summaryProp = (prepared.properties as any).summary;
-      expect(summaryProp.maxLength).toBeUndefined();
-      expect(summaryProp.description).toContain('maxLength');
+    console.log('[Integration] Schema preparation warnings:', warnings);
 
-      // Now use the prepared schema with the model
-      const model = createBedrockModel();
-      const structuredModel = model.withStructuredOutput(prepared, {
-        name: 'Analysis',
-        method: 'functionCalling' as any,
-        includeRaw: true,
-        strict: true,
-      });
+    // Verify preparation worked
+    expect(prepared.additionalProperties).toBe(false);
+    expect(prepared.required).toEqual(
+      expect.arrayContaining(['summary', 'topics', 'wordCount'])
+    );
+    const summaryProp = (prepared.properties as any).summary;
+    expect(summaryProp.maxLength).toBeUndefined();
+    expect(summaryProp.description).toContain('maxLength');
+
+    // Now use the prepared schema with the model
+    const model = createBedrockModel();
+    const structuredModel = model.withStructuredOutput(prepared, {
+      name: 'Analysis',
+      method: 'functionCalling' as any,
+      includeRaw: true,
+      strict: true,
+    });
 
-      const result = await structuredModel.invoke([
-        new SystemMessage('Analyze the following text and provide a summary, key topics, and word count.'),
-        new HumanMessage(
-          'Artificial intelligence has transformed the technology industry in recent years. ' +
+    const result = await structuredModel.invoke([
+      new SystemMessage(
+        'Analyze the following text and provide a summary, key topics, and word count.'
+      ),
+      new HumanMessage(
+        'Artificial intelligence has transformed the technology industry in recent years. ' +
           'Machine learning models are now capable of generating text, images, and even code. ' +
-          'Companies are investing heavily in AI research and development.',
-        ),
-      ]);
-
-      const parsed = result.parsed ?? result;
-      console.log('[Integration] Bedrock analysis result:', JSON.stringify(parsed, null, 2));
+          'Companies are investing heavily in AI research and development.'
+      ),
+    ]);
+
+    const parsed = result.parsed ?? result;
+    console.log(
+      '[Integration] Bedrock analysis result:',
+      JSON.stringify(parsed, null, 2)
+    );
 
-      expect(parsed).toBeDefined();
-      expect(typeof parsed.summary).toBe('string');
-      expect(Array.isArray(parsed.topics)).toBe(true);
-      expect(typeof parsed.wordCount).toBe('number');
-    },
-  );
+    expect(parsed).toBeDefined();
+    expect(typeof parsed.summary).toBe('string');
+    expect(Array.isArray(parsed.topics)).toBe(true);
+    expect(typeof parsed.wordCount).toBe('number');
+  });
 
   conditionalTest(
     'withStructuredOutput with tools - deferred structured output pattern',
@@ -222,10 +249,10 @@ describe('Bedrock structured output integration', () => {
       // Step 1: Regular invocation with tools (simulate tool use)
       const messages = [
         new SystemMessage(
-          'You are a helpful assistant. When asked to analyze text, provide a structured analysis.',
+          'You are a helpful assistant. When asked to analyze text, provide a structured analysis.'
         ),
         new HumanMessage(
-          'Analyze the sentiment: "This movie was absolutely terrible, worst I have ever seen."',
+          'Analyze the sentiment: "This movie was absolutely terrible, worst I have ever seen."'
         ),
       ];
 
@@ -240,14 +267,17 @@ describe('Bedrock structured output integration', () => {
       const result = await structuredModel.invoke(messages);
 
       const parsed = result.parsed ?? result;
-      console.log('[Integration] Bedrock deferred structured result:', JSON.stringify(parsed, null, 2));
+      console.log(
+        '[Integration] Bedrock deferred structured result:',
+        JSON.stringify(parsed, null, 2)
+      );
 
       expect(parsed).toBeDefined();
       expect(['positive', 'negative', 'neutral']).toContain(parsed.category);
       // The movie review is clearly negative
       expect(parsed.category).toBe('negative');
       expect(typeof parsed.confidence).toBe('number');
-    },
+    }
   );
 
   conditionalTest(
@@ -272,7 +302,7 @@ describe('Bedrock structured output integration', () => {
       const badResult = validateStructuredOutput(badResponse, personSchema);
       expect(badResult.success).toBe(false);
       expect(badResult.error).toBeDefined();
-    },
+    }
   );
 });
 
@@ -309,7 +339,13 @@ describe('Bedrock complex tool + structured output integration', () => {
             properties: {
               overall_sentiment: {
                 type: 'string',
-                enum: ['very_positive', 'positive', 'neutral', 'negative', 'very_negative'],
+                enum: [
+                  'very_positive',
+                  'positive',
+                  'neutral',
+                  'negative',
+                  'very_negative',
+                ],
               },
               confidence: { type: 'number' },
               key_themes: {
@@ -318,7 +354,10 @@ describe('Bedrock complex tool + structured output integration', () => {
                   type: 'object',
                   properties: {
                     theme: { type: 'string' },
-                    sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
+                    sentiment: {
+                      type: 'string',
+                      enum: ['positive', 'negative', 'neutral'],
+                    },
                     evidence: { type: 'string' },
                   },
                   required: ['theme', 'sentiment', 'evidence'],
@@ -335,7 +374,10 @@ describe('Bedrock complex tool + structured output integration', () => {
               type: 'object',
               properties: {
                 name: { type: 'string' },
-                type: { type: 'string', enum: ['person', 'organization', 'location', 'product'] },
+                type: {
+                  type: 'string',
+                  enum: ['person', 'organization', 'location', 'product'],
+                },
                 role: { type: 'string' },
               },
               required: ['name', 'type', 'role'],
@@ -362,22 +404,25 @@ describe('Bedrock complex tool + structured output integration', () => {
 
       const result = await structuredModel.invoke([
         new SystemMessage(
-          'You are an expert analyst. Analyze the following business communication and extract detailed structured information.',
+          'You are an expert analyst. Analyze the following business communication and extract detailed structured information.'
         ),
         new HumanMessage(
           'From: Sarah Johnson, VP of Engineering at TechCorp\n' +
-          'To: All Engineering Teams\n\n' +
-          'I am pleased to announce that our new AI platform, CodeAssist, has exceeded Q3 targets by 45%. ' +
-          'The Seattle development team, led by Marcus Chen, deserves special recognition for their outstanding work. ' +
-          'However, we need to address the performance issues reported by our European clients. ' +
-          'The London office has flagged latency problems that must be resolved before the Q4 launch. ' +
-          'Action items: 1) Marcus to lead a performance task force. 2) Schedule a meeting with the London team. ' +
-          '3) Update the deployment pipeline for EU regions.',
+            'To: All Engineering Teams\n\n' +
+            'I am pleased to announce that our new AI platform, CodeAssist, has exceeded Q3 targets by 45%. ' +
+            'The Seattle development team, led by Marcus Chen, deserves special recognition for their outstanding work. ' +
+            'However, we need to address the performance issues reported by our European clients. ' +
+            'The London office has flagged latency problems that must be resolved before the Q4 launch. ' +
+            'Action items: 1) Marcus to lead a performance task force. 2) Schedule a meeting with the London team. ' +
+            '3) Update the deployment pipeline for EU regions.'
         ),
       ]);
 
       const parsed = result.parsed ?? result;
-      console.log('[Integration] Complex analysis result:', JSON.stringify(parsed, null, 2));
+      console.log(
+        '[Integration] Complex analysis result:',
+        JSON.stringify(parsed, null, 2)
+      );
 
       // Verify top-level structure
       // Note: functionCalling mode is best-effort, so some fields may be missing.
@@ -387,15 +432,21 @@ describe('Bedrock complex tool + structured output integration', () => {
 
       // Analysis is the most complex nested field — verify if present
       if (parsed.analysis) {
-        expect(['very_positive', 'positive', 'neutral', 'negative', 'very_negative']).toContain(
-          parsed.analysis.overall_sentiment,
-        );
+        expect([
+          'very_positive',
+          'positive',
+          'neutral',
+          'negative',
+          'very_negative',
+        ]).toContain(parsed.analysis.overall_sentiment);
         expect(typeof parsed.analysis.confidence).toBe('number');
         if (Array.isArray(parsed.analysis.key_themes)) {
           expect(parsed.analysis.key_themes.length).toBeGreaterThan(0);
           for (const theme of parsed.analysis.key_themes) {
             expect(typeof theme.theme).toBe('string');
-            expect(['positive', 'negative', 'neutral']).toContain(theme.sentiment);
+            expect(['positive', 'negative', 'neutral']).toContain(
+              theme.sentiment
+            );
             expect(typeof theme.evidence).toBe('string');
           }
         }
@@ -406,7 +457,9 @@ describe('Bedrock complex tool + structured output integration', () => {
         expect(parsed.entities.length).toBeGreaterThan(0);
         for (const entity of parsed.entities) {
           expect(typeof entity.name).toBe('string');
-          expect(['person', 'organization', 'location', 'product']).toContain(entity.type);
+          expect(['person', 'organization', 'location', 'product']).toContain(
+            entity.type
+          );
         }
       }
 
@@ -417,7 +470,7 @@ describe('Bedrock complex tool + structured output integration', () => {
 
       // At minimum, we expect the model returned something parseable with the key fields
       expect(parsed.summary.length).toBeGreaterThan(0);
-    },
+    }
   );
 
   conditionalTest(
@@ -436,10 +489,18 @@ describe('Bedrock complex tool + structured output integration', () => {
               properties: {
                 category: { type: 'string' },
                 description: { type: 'string' },
-                severity: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
+                severity: {
+                  type: 'string',
+                  enum: ['low', 'medium', 'high', 'critical'],
+                },
                 recommendation: { type: 'string' },
               },
-              required: ['category', 'description', 'severity', 'recommendation'],
+              required: [
+                'category',
+                'description',
+                'severity',
+                'recommendation',
+              ],
               additionalProperties: false,
             },
           },
@@ -452,7 +513,12 @@ describe('Bedrock complex tool + structured output integration', () => {
             items: { type: 'string' },
           },
         },
-        required: ['report_title', 'findings', 'overall_risk_level', 'next_steps'],
+        required: [
+          'report_title',
+          'findings',
+          'overall_risk_level',
+          'next_steps',
+        ],
         additionalProperties: false,
       };
 
@@ -462,16 +528,16 @@ describe('Bedrock complex tool + structured output integration', () => {
       const messages = [
         new SystemMessage(
           'You are a security analyst. You have performed a security audit and gathered the following data from various scans. ' +
-          'Produce a structured security report.',
+            'Produce a structured security report.'
         ),
         new HumanMessage(
           'Here are the scan results:\n\n' +
-          'Port Scan: Ports 22, 80, 443, 8080 are open. Port 8080 is running an outdated Apache Tomcat 8.5.\n\n' +
-          'Vulnerability Scan: Found SQL injection in /api/users endpoint. XSS vulnerability in search form. ' +
-          'Outdated OpenSSL 1.1.1 (should be 3.x). No rate limiting on login endpoint.\n\n' +
-          'Configuration Review: Default admin credentials found on Tomcat manager. ' +
-          'CORS is set to wildcard (*). No CSP headers. Cookies without HttpOnly flag.\n\n' +
-          'Provide your structured security report.',
+            'Port Scan: Ports 22, 80, 443, 8080 are open. Port 8080 is running an outdated Apache Tomcat 8.5.\n\n' +
+            'Vulnerability Scan: Found SQL injection in /api/users endpoint. XSS vulnerability in search form. ' +
+            'Outdated OpenSSL 1.1.1 (should be 3.x). No rate limiting on login endpoint.\n\n' +
+            'Configuration Review: Default admin credentials found on Tomcat manager. ' +
+            'CORS is set to wildcard (*). No CSP headers. Cookies without HttpOnly flag.\n\n' +
+            'Provide your structured security report.'
         ),
       ];
 
@@ -485,13 +551,18 @@ describe('Bedrock complex tool + structured output integration', () => {
       const result = await structuredModel.invoke(messages);
 
       const parsed = result.parsed ?? result;
-      console.log('[Integration] Security report result:', JSON.stringify(parsed, null, 2));
+      console.log(
+        '[Integration] Security report result:',
+        JSON.stringify(parsed, null, 2)
+      );
 
       // Verify structure
       expect(typeof parsed.report_title).toBe('string');
       expect(Array.isArray(parsed.findings)).toBe(true);
       expect(parsed.findings.length).toBeGreaterThanOrEqual(3); // At least SQL injection, XSS, outdated software
-      expect(['low', 'medium', 'high', 'critical']).toContain(parsed.overall_risk_level);
+      expect(['low', 'medium', 'high', 'critical']).toContain(
+        parsed.overall_risk_level
+      );
       expect(Array.isArray(parsed.next_steps)).toBe(true);
       expect(parsed.next_steps.length).toBeGreaterThan(0);
 
@@ -499,7 +570,9 @@ describe('Bedrock complex tool + structured output integration', () => {
       for (const finding of parsed.findings) {
         expect(typeof finding.category).toBe('string');
         expect(typeof finding.description).toBe('string');
-        expect(['low', 'medium', 'high', 'critical']).toContain(finding.severity);
+        expect(['low', 'medium', 'high', 'critical']).toContain(
+          finding.severity
+        );
         expect(typeof finding.recommendation).toBe('string');
       }
 
@@ -509,7 +582,7 @@ describe('Bedrock complex tool + structured output integration', () => {
       // Validate entire response
       const validation = validateStructuredOutput(parsed, reportSchema);
       expect(validation.success).toBe(true);
-    },
+    }
   );
 
   conditionalTest(
@@ -542,10 +615,13 @@ describe('Bedrock complex tool + structured output integration', () => {
       // Prepare for Bedrock
       const { schema: prepared, warnings } = prepareSchemaForProvider(
         rawSchema,
-        Providers.BEDROCK,
+        Providers.BEDROCK
       );
 
-      console.log('[Integration] Complex schema warnings count:', warnings.length);
+      console.log(
+        '[Integration] Complex schema warnings count:',
+        warnings.length
+      );
       expect(warnings.length).toBeGreaterThan(5); // Should have many warnings
 
       // Verify ALL constraints were stripped
@@ -573,22 +649,27 @@ describe('Bedrock complex tool + structured output integration', () => {
       });
 
       const result = await structuredModel.invoke([
-        new SystemMessage('You are a book reviewer. Review the book described below.'),
+        new SystemMessage(
+          'You are a book reviewer. Review the book described below.'
+        ),
         new HumanMessage(
           'Review "The Great Gatsby" by F. Scott Fitzgerald. ' +
-          'It is a classic American novel written in English about the decline of the American Dream.',
+            'It is a classic American novel written in English about the decline of the American Dream.'
         ),
       ]);
 
       const parsed = result.parsed ?? result;
-      console.log('[Integration] Book review result:', JSON.stringify(parsed, null, 2));
+      console.log(
+        '[Integration] Book review result:',
+        JSON.stringify(parsed, null, 2)
+      );
 
       expect(typeof parsed.title).toBe('string');
       expect(typeof parsed.rating).toBe('number');
       expect(Array.isArray(parsed.tags)).toBe(true);
       expect(parsed.metadata).toBeDefined();
       expect(['en', 'es', 'fr', 'de']).toContain(parsed.metadata.language);
-    },
+    }
   );
 });
 
@@ -620,11 +701,16 @@ describe('Anthropic direct structured output integration', () => {
 
       const result = await structuredModel.invoke([
         new SystemMessage('Extract person information from the text.'),
-        new HumanMessage('Marie Curie was a 66 year old physicist and chemist.'),
+        new HumanMessage(
+          'Marie Curie was a 66 year old physicist and chemist.'
+        ),
       ]);
 
       const parsed = result.parsed ?? result;
-      console.log('[Integration] Anthropic native result:', JSON.stringify(parsed, null, 2));
+      console.log(
+        '[Integration] Anthropic native result:',
+        JSON.stringify(parsed, null, 2)
+      );
 
       expect(parsed).toBeDefined();
       expect(typeof parsed.name).toBe('string');
@@ -633,7 +719,7 @@ describe('Anthropic direct structured output integration', () => {
 
       const validation = validateStructuredOutput(parsed, personSchema);
       expect(validation.success).toBe(true);
-    },
+    }
   );
 
   conditionalTest(
@@ -660,11 +746,14 @@ describe('Anthropic direct structured output integration', () => {
       ]);
 
       const parsed = result.parsed ?? result;
-      console.log('[Integration] Anthropic classification:', JSON.stringify(parsed, null, 2));
+      console.log(
+        '[Integration] Anthropic classification:',
+        JSON.stringify(parsed, null, 2)
+      );
 
       expect(['positive', 'negative', 'neutral']).toContain(parsed.category);
       expect(parsed.category).toBe('positive');
-    },
+    }
   );
 });
 
@@ -695,11 +784,16 @@ describe('OpenAI structured output integration', () => {
 
       const result = await structuredModel.invoke([
         new SystemMessage('Extract person information from the text.'),
-        new HumanMessage('Albert Einstein was a 76 year old theoretical physicist.'),
+        new HumanMessage(
+          'Albert Einstein was a 76 year old theoretical physicist.'
+        ),
       ]);
 
       const parsed = result.parsed ?? result;
-      console.log('[Integration] OpenAI native result:', JSON.stringify(parsed, null, 2));
+      console.log(
+        '[Integration] OpenAI native result:',
+        JSON.stringify(parsed, null, 2)
+      );
 
       expect(parsed).toBeDefined();
       expect(typeof parsed.name).toBe('string');
@@ -707,7 +801,7 @@ describe('OpenAI structured output integration', () => {
 
       const validation = validateStructuredOutput(parsed, personSchema);
       expect(validation.success).toBe(true);
-    },
+    }
   );
 });
 
@@ -746,20 +840,20 @@ describe('Schema preparation produces valid schemas for all providers', () => {
   test('prepares valid schema for Anthropic', () => {
     const { schema, warnings } = prepareSchemaForProvider(
       complexSchema,
-      Providers.ANTHROPIC,
+      Providers.ANTHROPIC
     );
 
     // Root object
     expect(schema.additionalProperties).toBe(false);
     expect(schema.required).toEqual(
-      expect.arrayContaining(['analysis', 'tags', 'metadata']),
+      expect.arrayContaining(['analysis', 'tags', 'metadata'])
     );
 
     // Nested object: analysis
     const analysis = (schema.properties as any).analysis;
     expect(analysis.additionalProperties).toBe(false);
     expect(analysis.required).toEqual(
-      expect.arrayContaining(['score', 'label', 'details']),
+      expect.arrayContaining(['score', 'label', 'details'])
     );
 
     // Numeric constraints stripped
@@ -788,7 +882,7 @@ describe('Schema preparation produces valid schemas for all providers', () => {
   test('prepares valid schema for OpenAI', () => {
     const { schema } = prepareSchemaForProvider(
       complexSchema,
-      Providers.OPENAI,
+      Providers.OPENAI
     );
 
     expect(schema.additionalProperties).toBe(false);
@@ -799,7 +893,7 @@ describe('Schema preparation produces valid schemas for all providers', () => {
   test('prepares valid schema for Bedrock', () => {
     const { schema } = prepareSchemaForProvider(
       complexSchema,
-      Providers.BEDROCK,
+      Providers.BEDROCK
     );
 
     expect(schema.additionalProperties).toBe(false);

package/src/graphs/contextManagement.e2e.test.ts

@@ -874,7 +874,7 @@ describe('summaryModel dedicated cheap model usage', () => {
     const endpointConfig = {
       titleModel: 'us.amazon.nova-micro-v1:0',
       summaryModel: 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
-      modelDisplayLabel: 'Ranger',
+      modelDisplayLabel: 'Test',
     };
 
     // summaryModel should be a different, cheaper model than the main model