llm-advanced-tools 0.1.2 → 0.1.3

package/src/types/index.ts

@@ -1,221 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Represents a tool definition with support for advanced features
- */
-export interface ToolDefinition<TInput = any, TOutput = any> {
-  /** Tool name (must be unique in registry) */
-  name: string;
-
-  /** Human-readable description of what the tool does */
-  description: string;
-
-  /** JSON Schema defining input parameters */
-  inputSchema: z.ZodSchema<TInput> | Record<string, any>;
-
-  /** Example invocations showing proper usage */
-  inputExamples?: TInput[];
-
-  /** Whether to defer loading until explicitly requested (for Tool Search) */
-  deferLoading?: boolean;
-
-  /** Which callers can invoke this tool programmatically */
-  allowedCallers?: string[];
-
-  /** The actual implementation function */
-  handler: (input: TInput) => Promise<TOutput> | TOutput;
-
-  /** Optional metadata */
-  metadata?: Record<string, any>;
-}
-
-/**
- * Represents a tool call from the LLM
- */
-export interface ToolCall {
-  /** Unique identifier for this tool call */
-  id: string;
-
-  /** Name of the tool being called */
-  name: string;
-
-  /** Arguments passed to the tool */
-  input: Record<string, any>;
-
-  /** Optional caller information (for programmatic calling) */
-  caller?: {
-    type: string;
-    toolId: string;
-  };
-}
-
-/**
- * Result of a tool execution
- */
-export interface ToolResult<T = any> {
-  /** ID of the tool call this result corresponds to */
-  toolCallId: string;
-
-  /** The result data */
-  data?: T;
-
-  /** Error if execution failed */
-  error?: {
-    message: string;
-    code?: string;
-    details?: any;
-  };
-}
-
-/**
- * Message format (provider-agnostic)
- */
-export interface Message {
-  role: 'user' | 'assistant' | 'system' | 'tool';
-  content: string | Array<{
-    type: 'text' | 'tool_use' | 'tool_result';
-    [key: string]: any;
-  }>;
-  toolCalls?: ToolCall[];
-  toolResults?: ToolResult[];
-}
-
-/**
- * Chat completion request
- */
-export interface ChatRequest {
-  messages: Message[];
-  tools?: ToolDefinition[];
-  maxTokens?: number;
-  temperature?: number;
-  stream?: boolean;
-  [key: string]: any;
-}
-
-/**
- * Chat completion response
- */
-export interface ChatResponse {
-  message: Message;
-  usage?: {
-    inputTokens: number;
-    outputTokens: number;
-    totalTokens: number;
-  };
-  stopReason?: 'end_turn' | 'max_tokens' | 'tool_use' | 'stop_sequence';
-  toolCalls?: ToolCall[];
-}
-
-/**
- * Search strategy for tool discovery
- * - 'smart': Relevance-based ranking (best for most cases)
- * - 'keyword': Fast keyword matching
- * - 'semantic': Meaning-based search using embeddings
- * - 'custom': Your own search function
- *
- * Legacy names (for backward compatibility):
- * - 'bm25': alias for 'smart'
- * - 'regex': alias for 'keyword'
- */
-export type SearchStrategy =
-  | 'smart' | 'keyword' | 'semantic' | 'custom'
-  | 'bm25' | 'regex'; // backward compatibility
-
-/**
- * Configuration for tool search
- */
-export interface SearchConfig {
-  strategy: SearchStrategy;
-  maxResults?: number;
-  threshold?: number;
-  customSearchFn?: (query: string, tools: ToolDefinition[]) => Promise<ToolDefinition[]>;
-}
-
-/**
- * Code execution result
- */
-export interface ExecutionResult {
-  success: boolean;
-  stdout?: string;
-  stderr?: string;
-  returnValue?: any;
-  error?: {
-    message: string;
-    stack?: string;
-  };
-  toolCalls?: ToolCall[];
-}
-
-/**
- * Code executor configuration
- */
-export interface ExecutorConfig {
-  timeout?: number;
-  memoryLimit?: string;
-  environment?: Record<string, string>;
-  allowedPackages?: string[];
-}
-
-/**
- * Provider capabilities
- */
-export interface ProviderCapabilities {
-  supportsNativeToolSearch: boolean;
-  supportsNativeCodeExecution: boolean;
-  supportsNativeExamples: boolean;
-  supportsStreaming: boolean;
-  supportsParallelToolCalls: boolean;
-  maxToolsPerRequest?: number;
-  maxTokens?: number;
-}
-
-/**
- * Base provider adapter interface
- */
-export interface ProviderAdapter {
-  /** Provider name (e.g., 'openai', 'anthropic') */
-  readonly name: string;
-
-  /** Provider capabilities */
-  readonly capabilities: ProviderCapabilities;
-
-  /**
-   * Format a tool definition for this provider's API
-   */
-  formatTool(tool: ToolDefinition): Record<string, any>;
-
-  /**
-   * Create a chat completion request
-   */
-  chat(request: ChatRequest): Promise<ChatResponse>;
-
-  /**
-   * Parse tool calls from provider response
-   */
-  parseToolCalls(response: any): ToolCall[];
-
-  /**
-   * Format tool results for provider
-   */
-  formatToolResults(results: ToolResult[]): any;
-}
-
-/**
- * Client configuration
- */
-export interface ClientConfig {
-  /** Provider adapter to use */
-  adapter: ProviderAdapter;
-
-  /** Enable tool search feature */
-  enableToolSearch?: boolean;
-
-  /** Enable programmatic tool calling */
-  enableProgrammaticCalling?: boolean;
-
-  /** Search configuration */
-  searchConfig?: SearchConfig;
-
-  /** Code executor configuration */
-  executorConfig?: ExecutorConfig;
-}

package/test-advanced.ts

@@ -1,212 +0,0 @@
-import {
-  Client,
-  ToolRegistry,
-  OpenAIAdapter,
-  ToolDefinition
-} from './src';
-
-async function main() {
-  console.log('🚀 Testing Advanced Features\n');
-  console.log('=' .repeat(60));
-
-  const registry = new ToolRegistry({
-    strategy: 'smart',  // intelligent relevance-based search
-    maxResults: 3
-  });
-
-  // ============================================================
-  // Feature 1: Tool Use Examples
-  // ============================================================
-  console.log('\n📝 Feature 1: Tool Use Examples');
-  console.log('-'.repeat(60));
-
-  const createTicketTool: ToolDefinition = {
-    name: 'create_support_ticket',
-    description: 'Create a customer support ticket',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        title: { type: 'string' },
-        priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
-        customer_email: { type: 'string' }
-      },
-      required: ['title']
-    },
-    // Examples show the LLM how to use the tool properly
-    inputExamples: [
-      {
-        title: 'Cannot login to account',
-        priority: 'critical',
-        customer_email: 'user@example.com'
-      },
-      {
-        title: 'Feature request: Dark mode',
-        priority: 'low'
-      }
-    ],
-    deferLoading: false,
-    handler: async (input: any) => {
-      return {
-        ticket_id: 'TKT-' + Math.floor(Math.random() * 10000),
-        status: 'created',
-        ...input
-      };
-    }
-  };
-
-  registry.register(createTicketTool);
-
-  const client1 = new Client(
-    {
-      adapter: new OpenAIAdapter(process.env.OPENAI_API_KEY!, 'gpt-4o-mini'),
-      enableToolSearch: false,
-      enableProgrammaticCalling: false
-    },
-    registry
-  );
-
-  console.log('\nAsking: "Create a high priority ticket about payment failure for john@example.com"');
-  const response1 = await client1.ask(
-    'Create a high priority ticket about payment failure for john@example.com',
-    'Use the create_support_ticket tool. The examples show you the proper format.'
-  );
-  console.log('✅ Result:', response1);
-
-  // ============================================================
-  // Feature 2: Tool Search Tool
-  // ============================================================
-  console.log('\n\n🔍 Feature 2: Tool Search Tool');
-  console.log('-'.repeat(60));
-
-  const registry2 = new ToolRegistry({ strategy: 'smart', maxResults: 3 });
-
-  // Add multiple deferred tools
-  const tools: ToolDefinition[] = [
-    {
-      name: 'send_email',
-      description: 'Send an email to a customer',
-      inputSchema: { type: 'object', properties: { to: { type: 'string' }, subject: { type: 'string' } }, required: ['to', 'subject'] },
-      deferLoading: true,
-      handler: async (input: any) => ({ sent: true, messageId: 'msg_' + Date.now() })
-    },
-    {
-      name: 'send_sms',
-      description: 'Send an SMS text message',
-      inputSchema: { type: 'object', properties: { phone: { type: 'string' }, message: { type: 'string' } }, required: ['phone', 'message'] },
-      deferLoading: true,
-      handler: async (input: any) => ({ sent: true, messageId: 'sms_' + Date.now() })
-    },
-    {
-      name: 'get_weather',
-      description: 'Get weather information for a location',
-      inputSchema: { type: 'object', properties: { location: { type: 'string' } }, required: ['location'] },
-      deferLoading: true,
-      handler: async (input: any) => ({ temp: 72, conditions: 'sunny' })
-    },
-    {
-      name: 'get_stock_price',
-      description: 'Get current stock price for a ticker symbol',
-      inputSchema: { type: 'object', properties: { symbol: { type: 'string' } }, required: ['symbol'] },
-      deferLoading: true,
-      handler: async (input: any) => ({ symbol: input.symbol, price: 150.25 })
-    },
-    {
-      name: 'database_query',
-      description: 'Query the customer database',
-      inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
-      deferLoading: true,
-      handler: async (input: any) => ({ results: [] })
-    }
-  ];
-
-  registry2.registerMany(tools);
-
-  console.log('\nInitial stats:', registry2.getStats());
-  console.log('- Total tools: 5');
-  console.log('- All tools deferred (not loaded)');
-  console.log('- Saved ~15K tokens by not loading definitions!\n');
-
-  // Test manual search
-  console.log('Manual search for "email":');
-  const emailResults = await registry2.search('email', 2);
-  console.log('✅ Found tools:', emailResults.map(t => t.name));
-
-  console.log('\nManual search for "stock market":');
-  const stockResults = await registry2.search('stock market', 2);
-  console.log('✅ Found tools:', stockResults.map(t => t.name));
-
-  console.log('\nStats after searches:', registry2.getStats());
-  console.log('- Loaded tools increased as they were discovered!');
-
-  // ============================================================
-  // Feature 3: Programmatic Tool Calling (Simulated)
-  // ============================================================
-  console.log('\n\n🚀 Feature 3: Programmatic Tool Calling');
-  console.log('-'.repeat(60));
-
-  const registry3 = new ToolRegistry();
-
-  const getUsersTool: ToolDefinition = {
-    name: 'get_users',
-    description: 'Get list of users',
-    inputSchema: { type: 'object', properties: {} },
-    allowedCallers: ['code_execution'],
-    deferLoading: false,
-    handler: async () => {
-      return [
-        { id: 1, name: 'Alice', age: 30 },
-        { id: 2, name: 'Bob', age: 25 },
-        { id: 3, name: 'Carol', age: 35 }
-      ];
-    }
-  };
-
-  const getUserDetailsTool: ToolDefinition = {
-    name: 'get_user_details',
-    description: 'Get detailed info for a user',
-    inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] },
-    allowedCallers: ['code_execution'],
-    deferLoading: false,
-    handler: async (input: { id: number }) => {
-      return {
-        id: input.id,
-        email: `user${input.id}@example.com`,
-        credits: 100 * input.id
-      };
-    }
-  };
-
-  registry3.registerMany([getUsersTool, getUserDetailsTool]);
-
-  console.log('\nWithout Programmatic Calling:');
-  console.log('- Call get_users → Returns 3 users (enters context)');
-  console.log('- Call get_user_details(1) → Returns details (enters context)');
-  console.log('- Call get_user_details(2) → Returns details (enters context)');
-  console.log('- Call get_user_details(3) → Returns details (enters context)');
-  console.log('- Total: 4 API round-trips, all data in context\n');
-
-  console.log('With Programmatic Calling:');
-  console.log('- LLM writes code to orchestrate all calls');
-  console.log('- Code runs in sandbox, fetches all data');
-  console.log('- Only final result enters context');
-  console.log('- Total: 1 code execution, massive token savings!\n');
-
-  console.log('✅ Tools support programmatic calling:',
-    registry3.getAllTools().filter(t => t.allowedCallers?.includes('code_execution')).map(t => t.name)
-  );
-
-  // ============================================================
-  // Summary
-  // ============================================================
-  console.log('\n\n' + '='.repeat(60));
-  console.log('🎉 ALL FEATURES DEMONSTRATED!');
-  console.log('='.repeat(60));
-  console.log('\n✅ Tool Use Examples: Improved accuracy with example patterns');
-  console.log('✅ Tool Search: Dynamic discovery saves 85%+ tokens');
-  console.log('✅ Programmatic Calling: Code orchestration saves 37%+ tokens\n');
-  console.log('This library brings these features to ANY LLM provider!');
-  console.log('Currently implemented: OpenAI');
-  console.log('Coming soon: Anthropic, Google, Ollama\n');
-}
-
-main().catch(console.error);

package/test-simple.ts

@@ -1,91 +0,0 @@
-import {
-  Client,
-  ToolRegistry,
-  OpenAIAdapter,
-  ToolDefinition
-} from './src';
-
-async function main() {
-  console.log('🚀 Testing Provider-Agnostic Advanced Tools Library\n');
-
-  // 1. Create registry with smart search
-  const registry = new ToolRegistry({
-    strategy: 'smart',  // intelligent relevance-based search
-    maxResults: 5
-  });
-
-  // 2. Define a simple weather tool
-  const weatherTool: ToolDefinition = {
-    name: 'get_weather',
-    description: 'Get current weather for a location',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        location: {
-          type: 'string',
-          description: 'City name'
-        },
-        units: {
-          type: 'string',
-          enum: ['celsius', 'fahrenheit'],
-          description: 'Temperature units'
-        }
-      },
-      required: ['location']
-    },
-    // Tool Use Examples feature
-    inputExamples: [
-      { location: 'San Francisco', units: 'fahrenheit' },
-      { location: 'Tokyo', units: 'celsius' }
-    ],
-    // Defer loading for Tool Search feature
-    deferLoading: false, // Keep it loaded for this simple test
-    handler: async (input: { location: string; units?: string }) => {
-      return {
-        location: input.location,
-        temperature: 72,
-        units: input.units || 'fahrenheit',
-        conditions: 'Sunny'
-      };
-    }
-  };
-
-  registry.register(weatherTool);
-
-  // 3. Create client with OpenAI
-  const client = new Client(
-    {
-      adapter: new OpenAIAdapter(
-        process.env.OPENAI_API_KEY!,
-        'gpt-4o-mini' // Using cheaper model for testing
-      ),
-      enableToolSearch: false, // Disable for simple test
-      enableProgrammaticCalling: false // Disable for simple test
-    },
-    registry
-  );
-
-  console.log('Registry stats:', registry.getStats());
-  console.log('\n--- Test 1: Simple tool call ---\n');
-
-  try {
-    const response = await client.ask(
-      "What's the weather like in San Francisco?",
-      "You have access to a weather tool. Use it to answer the user's question."
-    );
-
-    console.log('✅ Response:', response);
-  } catch (error: any) {
-    console.error('❌ Error:', error.message);
-  }
-
-  console.log('\n--- Test 2: Tool Search ---\n');
-
-  // Test the search functionality
-  const searchResults = await registry.search('weather');
-  console.log('✅ Tools found for "weather":', searchResults.map(t => t.name));
-
-  console.log('\n🎉 Tests complete!');
-}
-
-main().catch(console.error);