@illuma-ai/agents 1.1.20 → 1.1.22

package/src/scripts/programmatic_exec.js

@@ -1,277 +0,0 @@
-// src/scripts/programmatic_exec.ts
-/**
- * Test script for Programmatic Tool Calling (PTC).
- * Run with: npm run programmatic_exec
- *
- * Demonstrates:
- * 1. Runtime toolMap injection - the tool map is passed at invocation time
- * 2. Tool classification with allowed_callers (inspired by Anthropic's API)
- *    - 'direct': Tool can only be called directly by the LLM (default)
- *    - 'code_execution': Tool can only be called from within PTC
- *    - Both: Tool can be called either way
- *
- * IMPORTANT: The Python code passed to PTC should NOT define the tool functions.
- * The Code API automatically generates async function stubs from the tool definitions.
- * The code should just CALL the tools as if they're already available:
- *   - result = await get_weather(city="SF")
- *   - results = await asyncio.gather(tool1(), tool2())
- */
-import { config } from 'dotenv';
-config();
-import { createProgrammaticToolCallingTool } from '@/tools/ProgrammaticToolCalling';
-import { createGetTeamMembersTool, createGetExpensesTool, createGetWeatherTool, createCalculatorTool, createProgrammaticToolRegistry, } from '@/test/mockTools';
-async function runTest(ptcTool, testName, code, options) {
-    console.log(`\n${'='.repeat(70)}`);
-    console.log(`TEST: ${testName}`);
-    console.log('='.repeat(70));
-    console.log('\nCode:');
-    console.log('```python');
-    console.log(code.trim());
-    console.log('```\n');
-    try {
-        const startTime = Date.now();
-        // Manual testing: schema params + extras (LangChain moves extras to config.toolCall)
-        const result = await ptcTool.invoke({
-            code,
-            tools: options.tools,
-            session_id: options.session_id,
-            timeout: options.timeout,
-            toolMap: options.toolMap, // Non-schema field → config.toolCall.toolMap
-        });
-        const duration = Date.now() - startTime;
-        console.log(`Result (${duration}ms):`);
-        if (Array.isArray(result)) {
-            console.log(result[0]);
-            if (options.showArtifact) {
-                console.log('\n--- Artifact ---');
-                console.dir(result[1], { depth: null });
-            }
-        }
-        else {
-            console.log(result);
-        }
-    }
-    catch (error) {
-        console.error('Error:', error instanceof Error ? error.message : error);
-    }
-}
-// ============================================================================
-// Main
-// ============================================================================
-async function main() {
-    console.log('Programmatic Tool Calling (PTC) - Test Script');
-    console.log('==============================================');
-    console.log('Demonstrating runtime toolMap injection\n');
-    const apiKey = process.env.CODE_EXECUTOR_API_KEY;
-    if (!apiKey) {
-        console.error('Error: CODE_EXECUTOR_API_KEY environment variable is not set.');
-        console.log('Please set it in your .env file or environment.');
-        process.exit(1);
-    }
-    console.log('Creating mock tools...');
-    const mockTools = [
-        createGetTeamMembersTool(),
-        createGetExpensesTool(),
-        createGetWeatherTool(),
-        createCalculatorTool(),
-    ];
-    const toolMap = new Map(mockTools.map((t) => [t.name, t]));
-    const toolDefinitions = Array.from(createProgrammaticToolRegistry().values());
-    console.log(`ToolMap contains ${toolMap.size} tools: ${Array.from(toolMap.keys()).join(', ')}`);
-    console.log('\nCreating PTC tool (without toolMap)...');
-    const ptcTool = createProgrammaticToolCallingTool({ apiKey });
-    console.log('PTC tool created successfully!');
-    console.log('Note: toolMap will be passed at runtime with each invocation.\n');
-    const baseOptions = { toolMap, tools: toolDefinitions };
-    // =========================================================================
-    // Test 1: Simple async tool call
-    // =========================================================================
-    await runTest(ptcTool, 'Simple async tool call', `
-# Tools are auto-generated as async functions - just await them
-result = await get_weather(city="San Francisco")
-print(f"Weather in SF: {result['temperature']}°F, {result['condition']}")
-    `, { ...baseOptions, showArtifact: true });
-    // =========================================================================
-    // Test 2: Sequential loop with await
-    // =========================================================================
-    await runTest(ptcTool, 'Sequential loop - Process team expenses', `
-# Each tool call uses await
-team = await get_team_members()
-print("Team expense report:")
-print("-" * 30)
-total = 0
-for member in team:
-    expenses = await get_expenses(user_id=member['id'])
-    member_total = sum(e['amount'] for e in expenses)
-    total += member_total
-    print(f"{member['name']}: \${member_total:.2f}")
-print("-" * 30)
-print(f"Total: \${total:.2f}")
-    `, baseOptions);
-    // =========================================================================
-    // Test 3: Parallel execution with asyncio.gather
-    // =========================================================================
-    await runTest(ptcTool, 'Parallel execution - Weather for multiple cities', `
-# Use asyncio.gather for parallel tool calls - single round-trip!
-import asyncio
-
-cities = ["San Francisco", "New York", "London"]
-results = await asyncio.gather(*[
-    get_weather(city=city)
-    for city in cities
-])
-
-print("Weather report:")
-for city, weather in zip(cities, results):
-    print(f"  {city}: {weather['temperature']}°F, {weather['condition']}")
-    `, baseOptions);
-    // =========================================================================
-    // Test 4: Chained dependencies
-    // =========================================================================
-    await runTest(ptcTool, 'Chained dependencies - Get team then process each', `
-# Get team first, then fetch expenses for each
-team = await get_team_members()
-engineering = [m for m in team if m['department'] == 'Engineering']
-
-print(f"Engineering team ({len(engineering)} members):")
-for member in engineering:
-    expenses = await get_expenses(user_id=member['id'])
-    equipment = sum(e['amount'] for e in expenses if e['category'] == 'equipment')
-    print(f"  {member['name']}: \${equipment:.2f} on equipment")
-    `, baseOptions);
-    // =========================================================================
-    // Test 5: Conditional logic
-    // =========================================================================
-    await runTest(ptcTool, 'Conditional logic - Find high spenders', `
-team = await get_team_members()
-high_spenders = []
-
-for member in team:
-    expenses = await get_expenses(user_id=member['id'])
-    total = sum(e['amount'] for e in expenses)
-    if total > 300:
-        high_spenders.append((member['name'], total))
-
-if high_spenders:
-    print("High spenders (over $300):")
-    for name, amount in sorted(high_spenders, key=lambda x: x[1], reverse=True):
-        print(f"  {name}: \${amount:.2f}")
-else:
-    print("No high spenders found.")
-    `, baseOptions);
-    // =========================================================================
-    // Test 6: Mixed parallel and sequential
-    // =========================================================================
-    await runTest(ptcTool, 'Mixed - Parallel expense fetch after sequential team fetch', `
-import asyncio
-
-# Step 1: Get team (one tool call)
-team = await get_team_members()
-print(f"Fetched {len(team)} team members")
-
-# Step 2: Get all expenses in parallel (single round-trip for all!)
-all_expenses = await asyncio.gather(*[
-    get_expenses(user_id=member['id'])
-    for member in team
-])
-
-# Step 3: Process and output
-print("\\nExpense summary:")
-for member, expenses in zip(team, all_expenses):
-    total = sum(e['amount'] for e in expenses)
-    print(f"  {member['name']}: \${total:.2f} ({len(expenses)} items)")
-    `, baseOptions);
-    // =========================================================================
-    // Test 7: Calculator usage
-    // =========================================================================
-    await runTest(ptcTool, 'Calculator tool usage', `
-# All tools are async - use await
-result1 = await calculator(expression="2 + 2 * 3")
-result2 = await calculator(expression="(10 + 5) / 3")
-
-print(f"2 + 2 * 3 = {result1['result']}")
-print(f"(10 + 5) / 3 = {result2['result']:.2f}")
-    `, baseOptions);
-    // =========================================================================
-    // Test 8: Error handling in code
-    // =========================================================================
-    await runTest(ptcTool, 'Error handling - Invalid city', `
-# Tool errors become Python exceptions - handle with try/except
-cities = ["San Francisco", "InvalidCity", "New York"]
-
-for city in cities:
-    try:
-        weather = await get_weather(city=city)
-        print(f"{city}: {weather['temperature']}°F")
-    except Exception as e:
-        print(f"{city}: Error - {e}")
-    `, baseOptions);
-    // =========================================================================
-    // Test 9: Early termination
-    // =========================================================================
-    await runTest(ptcTool, 'Early termination - Stop when condition met', `
-# Stop as soon as we find what we need - no wasted tool calls
-team = await get_team_members()
-
-for member in team:
-    expenses = await get_expenses(user_id=member['id'])
-    if any(e['category'] == 'equipment' for e in expenses):
-        print(f"First team member with equipment expense: {member['name']}")
-        equipment_total = sum(e['amount'] for e in expenses if e['category'] == 'equipment')
-        print(f"Equipment total: \${equipment_total:.2f}")
-        break
-else:
-    print("No team member has equipment expenses")
-    `, baseOptions);
-    // =========================================================================
-    // Test 10: Subset of tools
-    // =========================================================================
-    await runTest(ptcTool, 'Subset of tools - Only weather', `
-# Only the weather tool is available in this execution
-import asyncio
-
-sf, nyc = await asyncio.gather(
-    get_weather(city="San Francisco"),
-    get_weather(city="New York")
-)
-print(f"SF: {sf['temperature']}°F vs NYC: {nyc['temperature']}°F")
-difference = abs(sf['temperature'] - nyc['temperature'])
-print(f"Temperature difference: {difference}°F")
-    `, {
-        ...baseOptions,
-        tools: [toolDefinitions.find((t) => t.name === 'get_weather')],
-    });
-    // =========================================================================
-    // Test 11: Note about ToolNode injection
-    // =========================================================================
-    console.log(`\n${'='.repeat(70)}`);
-    console.log('NOTE: ToolNode Runtime Injection');
-    console.log('='.repeat(70));
-    console.log('\nWhen PTC is invoked through ToolNode in a real agent:\n' +
-        '- ToolNode detects call.name === "run_tools_with_code"\n' +
-        '- ToolNode injects: { ...invokeParams, toolMap, toolDefs }\n' +
-        '- PTC tool extracts these from params (not from config)\n' +
-        '- No explicit tools parameter needed in schema\n\n' +
-        'This test demonstrates param injection with explicit tools:\n');
-    await runTest(ptcTool, 'Runtime injection with explicit tools', `
-# ToolNode would inject toolMap+toolDefs
-# For this test, we pass tools explicitly (same effect)
-team = await get_team_members()
-print(f"Team size: {len(team)}")
-for member in team:
-    print(f"- {member['name']} ({member['department']})")
-    `, baseOptions);
-    console.log('\n' + '='.repeat(70));
-    console.log('All tests completed!');
-    console.log('='.repeat(70) + '\n');
-    console.log('Summary of allowed_callers patterns:');
-    console.log('- get_team_members, get_expenses, calculator: code_execution only');
-    console.log('- get_weather: both direct and code_execution');
-    console.log('\nIn a real agent setup, the LLM would only see tools with allowed_callers');
-    console.log('including "direct", while PTC can call any tool with "code_execution".\n');
-}
-main().catch((err) => {
-    console.error('Fatal error:', err);
-    process.exit(1);
-});
-//# sourceMappingURL=programmatic_exec.js.map

package/src/scripts/programmatic_exec_agent.js

@@ -1,168 +0,0 @@
-// src/scripts/programmatic_exec_agent.ts
-/**
- * Test script for Programmatic Tool Calling (PTC) with agent integration.
- * Run with: npm run programmatic_exec_agent
- *
- * Demonstrates:
- * 1. Tool classification with allowed_callers:
- *    - direct: Tool bound to LLM (can be called directly)
- *    - code_execution: Tool available for PTC (not bound to LLM)
- *    - Both: Tool bound to LLM AND available for PTC
- * 2. Deferred loading with defer_loading: true (for tool search)
- * 3. Agent-level tool configuration via toolRegistry
- * 4. ToolNode runtime injection of programmatic tools
- *
- * This shows the real-world integration pattern with agents.
- */
-import { config } from 'dotenv';
-config();
-import { HumanMessage } from '@langchain/core/messages';
-import { createCodeExecutionTool } from '@/tools/CodeExecutor';
-import { createProgrammaticToolCallingTool } from '@/tools/ProgrammaticToolCalling';
-import { createToolSearch } from '@/tools/ToolSearch';
-import { getLLMConfig } from '@/utils/llmConfig';
-import { getArgs } from '@/scripts/args';
-import { Run } from '@/run';
-import { createGetTeamMembersTool, createGetExpensesTool, createGetWeatherTool, createProgrammaticToolRegistry, } from '@/test/mockTools';
-// ============================================================================
-// Tool Registry (Metadata)
-// ============================================================================
-/**
- * Tool registry only needs business logic tools that require filtering.
- * Special tools (execute_code, run_tools_with_code, tool_search)
- * are always bound directly to the LLM and don't need registry entries.
- */
-function createAgentToolRegistry() {
-    // Use shared programmatic tool registry (get_team_members, get_expenses, etc.)
-    return createProgrammaticToolRegistry();
-}
-// ============================================================================
-// Main
-// ============================================================================
-const conversationHistory = [];
-async function main() {
-    console.log('Programmatic Tool Calling - Agent Integration Test');
-    console.log('===================================================\n');
-    const { userName, location, provider } = await getArgs();
-    const llmConfig = getLLMConfig(provider);
-    // Create all tool instances
-    const mockTools = [
-        createGetTeamMembersTool(),
-        createGetExpensesTool(),
-        createGetWeatherTool(),
-    ];
-    const toolMap = new Map(mockTools.map((t) => [t.name, t]));
-    // Create special tools (PTC, code execution, tool search)
-    const codeExecTool = createCodeExecutionTool();
-    const ptcTool = createProgrammaticToolCallingTool();
-    const toolSearchTool = createToolSearch();
-    // Build complete tool list and map
-    const allTools = [...mockTools, codeExecTool, ptcTool, toolSearchTool];
-    const completeToolMap = new Map(allTools.map((t) => [t.name, t]));
-    // Create tool registry with allowed_callers configuration
-    // Only includes business logic tools (not special tools like execute_code, PTC, tool_search)
-    const toolRegistry = createAgentToolRegistry();
-    console.log('Tool configuration:');
-    console.log('- Total tools:', allTools.length);
-    console.log('- Programmatic-allowed:', Array.from(toolRegistry.values())
-        .filter((t) => t.allowed_callers?.includes('code_execution'))
-        .map((t) => t.name)
-        .join(', '));
-    console.log('- Direct-only:', Array.from(toolRegistry.values())
-        .filter((t) => !t.allowed_callers ||
-        (t.allowed_callers.includes('direct') &&
-            !t.allowed_callers.includes('code_execution')))
-        .map((t) => t.name)
-        .join(', '));
-    console.log('- Both:', Array.from(toolRegistry.values())
-        .filter((t) => t.allowed_callers?.includes('direct') &&
-        t.allowed_callers?.includes('code_execution'))
-        .map((t) => t.name)
-        .join(', '));
-    // Create run with toolRegistry configuration
-    const run = await Run.create({
-        runId: 'ptc-agent-test',
-        graphConfig: {
-            type: 'standard',
-            llmConfig,
-            agents: [
-                {
-                    agentId: 'default',
-                    provider: llmConfig.provider,
-                    clientOptions: llmConfig,
-                    tools: allTools,
-                    toolMap: completeToolMap,
-                    toolRegistry, // Pass tool registry for programmatic/deferred tool config
-                    instructions: 'You are an AI assistant with access to programmatic tool calling. ' +
-                        'When you need to process multiple items or perform complex data operations, ' +
-                        'use the run_tools_with_code tool to write Python code that calls tools efficiently.',
-                },
-            ],
-        },
-        returnContent: true,
-        skipCleanup: true,
-    });
-    const config = {
-        configurable: {
-            provider,
-            thread_id: 'ptc-test-conversation',
-        },
-        streamMode: 'values',
-        version: 'v2',
-    };
-    console.log('\n' + '='.repeat(70));
-    console.log('Test: Process team expenses using PTC');
-    console.log('='.repeat(70) + '\n');
-    const userMessage = new HumanMessage(`Hi! I need you to analyze our team's expenses. Please:
-1. Get the list of team members
-2. For each member, get their expense records
-3. Calculate the total expenses per member
-4. Identify anyone who spent more than $300
-5. Show me the results in a nice format
-
-Use the run_tools_with_code tool to do this efficiently - don't call each tool separately!`);
-    conversationHistory.push(userMessage);
-    const inputs = {
-        messages: conversationHistory,
-    };
-    console.log('Running agent with PTC capability...\n');
-    const finalContentParts = await run.processStream(inputs, config);
-    const finalMessages = run.getRunMessages();
-    if (finalMessages) {
-        conversationHistory.push(...finalMessages);
-    }
-    console.log('\n' + '='.repeat(70));
-    console.log('Agent Response:');
-    console.log('='.repeat(70));
-    if (finalContentParts) {
-        for (const part of finalContentParts) {
-            if (part?.type === 'text' && part.text) {
-                console.log(part.text);
-            }
-        }
-    }
-    console.log('\n' + '='.repeat(70));
-    console.log('Test completed successfully!');
-    console.log('='.repeat(70));
-    console.log('\nKey observations:');
-    console.log('1. LLM only sees tools with allowed_callers including "direct" (get_weather, execute_code, run_tools_with_code, tool_search)');
-    console.log('2. When PTC is invoked, ToolNode automatically injects programmatic tools (get_team_members, get_expenses, get_weather)');
-    console.log('3. No need to manually configure runtime toolMap - handled by agent context');
-    console.log('4. Tool filtering based on allowed_callers happens automatically\n');
-}
-process.on('unhandledRejection', (reason, promise) => {
-    console.error('Unhandled Rejection at:', promise, 'reason:', reason);
-    console.log('Conversation history:');
-    console.dir(conversationHistory, { depth: null });
-    process.exit(1);
-});
-process.on('uncaughtException', (err) => {
-    console.error('Uncaught Exception:', err);
-});
-main().catch((err) => {
-    console.error('Fatal error:', err);
-    console.log('Conversation history:');
-    console.dir(conversationHistory, { depth: null });
-    process.exit(1);
-});
-//# sourceMappingURL=programmatic_exec_agent.js.map

package/src/scripts/search.js

@@ -1,118 +0,0 @@
-/* eslint-disable no-console */
-// src/scripts/cli.ts
-import { config } from 'dotenv';
-config();
-import { HumanMessage } from '@langchain/core/messages';
-import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
-import { ToolEndHandler, ModelEndHandler } from '@/events';
-import { createSearchTool } from '@/tools/search';
-import { getArgs } from '@/scripts/args';
-import { Run } from '@/run';
-import { GraphEvents, Providers } from '@/common';
-import { getLLMConfig } from '@/utils/llmConfig';
-const conversationHistory = [];
-async function testStandardStreaming() {
-    const { userName, location, provider, currentDate } = await getArgs();
-    const { contentParts, aggregateContent } = createContentAggregator();
-    const customHandlers = {
-        [GraphEvents.TOOL_END]: new ToolEndHandler(),
-        [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
-        [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
-        [GraphEvents.ON_RUN_STEP_COMPLETED]: {
-            handle: (event, data) => {
-                console.log('====== ON_RUN_STEP_COMPLETED ======');
-                // console.dir(data, { depth: null });
-                aggregateContent({
-                    event,
-                    data: data,
-                });
-            },
-        },
-        [GraphEvents.ON_RUN_STEP]: {
-            handle: (event, data) => {
-                aggregateContent({ event, data: data });
-            },
-        },
-        [GraphEvents.ON_RUN_STEP_DELTA]: {
-            handle: (event, data) => {
-                aggregateContent({ event, data: data });
-            },
-        },
-        [GraphEvents.ON_MESSAGE_DELTA]: {
-            handle: (event, data) => {
-                aggregateContent({ event, data: data });
-            },
-        },
-        [GraphEvents.TOOL_START]: {
-            handle: (_event, data, metadata) => {
-                console.log('====== TOOL_START ======');
-                // console.dir(data, { depth: null });
-            },
-        },
-    };
-    const llmConfig = getLLMConfig(provider);
-    if (llmConfig.provider === Providers.BEDROCK) {
-        llmConfig.promptCache = true;
-    }
-    const run = await Run.create({
-        runId: 'test-run-id',
-        graphConfig: {
-            type: 'standard',
-            llmConfig,
-            tools: [
-                createSearchTool({
-                    scraperProvider: 'serper',
-                }),
-            ],
-            instructions: 'You are a friendly AI assistant. Always address the user by their name.',
-            // additional_instructions: `The user's name is ${userName} and they are located in ${location}.`,
-        },
-        returnContent: true,
-        skipCleanup: true,
-        customHandlers,
-    });
-    const config = {
-        configurable: {
-            provider,
-            thread_id: 'conversation-num-1',
-        },
-        streamMode: 'values',
-        version: 'v2',
-    };
-    console.log('Test 1: Search query (search tool test)');
-    // const userMessage = `
-    // Make a search for the weather in ${location} today, which is ${currentDate}.
-    // Before making the search, please let me know what you're about to do, then immediately start searching without hesitation.
-    // Make sure to always refer to me by name, which is ${userName}.
-    // After giving me a thorough summary, tell me a joke about the weather forecast we went over.
-    // `;
-    // const userMessage = 'Are massage guns good?';
-    // const userMessage = 'What is functional programming?';
-    const userMessage = "Get me today's trending news.";
-    // const userMessage = "search recent italy earthquake volcano activity";
-    // const userMessage =
-    //   "use 'Trump' as the exact search query and tell me what you find.";
-    conversationHistory.push(new HumanMessage(userMessage));
-    const inputs = {
-        messages: conversationHistory,
-    };
-    const finalContentParts = await run.processStream(inputs, config);
-    const finalMessages = run.getRunMessages();
-    if (finalMessages) {
-        conversationHistory.push(...finalMessages);
-        console.dir(conversationHistory, { depth: null });
-    }
-    // console.dir(finalContentParts, { depth: null });
-    console.log('\n\n====================\n\n');
-    // console.dir(contentParts, { depth: null });
-}
-process.on('unhandledRejection', (reason, promise) => {
-    console.warn('Unhandled Rejection (non-fatal):', reason);
-});
-testStandardStreaming().catch((err) => {
-    console.error(err);
-    console.log('Conversation history:');
-    console.dir(conversationHistory, { depth: null });
-    process.exit(1);
-});
-//# sourceMappingURL=search.js.map