🤖 @handit.ai/ai-wrapper

Intelligent AI Execution System with Built-in Tracking & Self-Improvement

This isn't just a wrapper - it's a complete AI intelligence platform that learns, improves, and provides valuable insights for enterprise applications.

📚 Documentation • 🚀 Quick Start • 🔧 Examples • 🐛 Issues • 💬 Discussions

🧠 Key Features

• 🤖 Smart AI Execution: Intelligent execution with automatic optimization
• 📊 Complete Tracking: Every interaction tracked for insights and improvement
• 🔄 Self-Improving: Learns from every execution to get better over time
• 📈 Performance Analytics: Detailed metrics and quality assessment
• 🎯 Multi-Provider Intelligence: OpenAI, Google AI, and Anthropic Claude
• 🛡️ Safety & Compliance: Enhanced tracking for sensitive operations
• 💰 Cost Optimization: Smart model selection for budget efficiency

Installation

npm install @handit.ai/ai-wrapper
# Install peer dependencies
npm install @handit.ai/node openai @google/generative-ai @anthropic-ai/sdk axios

🚀 Quick Start

const { AIWrapper } = require('@handit.ai/ai-wrapper');

// Initialize the intelligent AI system
const aiWrapper = new AIWrapper({
  handitApiKey: 'your-handit-api-key',
  openaiApiKey: 'your-openai-api-key',
  googleApiKey: 'your-google-api-key',
  anthropicApiKey: 'your-anthropic-api-key'
});

// Run a smart AI agent (with tracking, evaluation & self-improvement)
const result = await aiWrapper.runSmartAgent({
  agentName: 'customer-support',
  input: 'Hello, I need help with my order',
  model: 'gpt-4'
});

console.log(result.output);
// The system automatically tracks this execution, learns from it,
// and uses the data to improve future interactions!

Configuration

Constructor Options

const aiWrapper = new AIWrapper({
  handitApiKey: 'required-handit-api-key',    // Required
  openaiApiKey: 'your-openai-key',            // Optional
  googleApiKey: 'your-google-key',            // Optional
  anthropicApiKey: 'your-anthropic-key',      // Optional
  trackingUrl: 'custom-tracking-url',         // Optional
  performanceUrl: 'custom-performance-url',   // Optional
  ssoTrackingUrl: 'custom-sso-tracking-url'   // Optional
});

💡 Core Methods

1. Smart AI Execution (Recommended)

// The flagship method - includes full intelligence, tracking & optimization
const result = await aiWrapper.runSmartAgent({
  agentName: 'customer-support',
  input: 'User question or input',
  model: 'gpt-4',
  additionalOptions: {
    temperature: 0.7,
    max_tokens: 1000
  }
});
// ✅ Automatically fetches optimized prompts
// ✅ Tracks execution metrics
// ✅ Learns from the interaction
// ✅ Contributes to self-improvement

2. Optimized AI Execution

// Google AI with optimization focus
const result = await aiWrapper.runOptimizedAgent({
  agentName: 'content-writer',
  input: 'Write about AI trends',
  model: 'gemini-pro',
  additionalOptions: {
    temperature: 0.8
  }
});
// ✅ Optimizes for performance and quality
// ✅ Tracks optimization metrics

3. Tracked AI Execution

// Anthropic Claude with enhanced safety tracking
const result = await aiWrapper.runTrackedAgent({
  agentName: 'code-reviewer',
  input: 'Review this code for security issues',
  model: 'claude-3-sonnet-20240229',
  additionalOptions: {
    max_tokens: 2000
  }
});
// ✅ Enhanced tracking for sensitive operations
// ✅ Safety and compliance monitoring

4. Provider-Specific Execution

// Direct provider execution with tracking
const result = await aiWrapper.runWithOpenAI({
  agentName: 'data-analyst',
  input: 'Analyze quarterly sales data',
  model: 'gpt-3.5-turbo'
});

API Reference

AIWrapper Class

Constructor

• new AIWrapper(options) - Initialize the wrapper with configuration

Methods

executeAgent(options)

Generic method to execute an AI agent with any provider.

Parameters:

• agentName (string) - Name of the agent in handit
• input (string) - User input/question
• provider (string) - AI provider ('openai', 'google', 'anthropic')
• model (string, optional) - Specific model to use
• nodeName (string, optional) - Name for tracking purposes
• additionalOptions (object, optional) - Provider-specific options

Returns:

{
  success: boolean,
  output: string,        // AI response
  executionId: string,   // Tracking ID
  prompts: array        // Prompts used
}

runSmartAgent(options)

Smart AI execution with full intelligence and optimization.

runOptimizedAgent(options)

Google AI execution with optimization focus.

runTrackedAgent(options)

Anthropic Claude execution with enhanced safety tracking.

runWithOpenAI(options), runWithGoogle(options), runWithAnthropic(options)

Provider-specific execution methods.

getPrompts({ agentName })

Fetch available prompts for an agent.

track(options)

Manually track a node execution.

Parameters:

• input - Input data
• output - Output data
• nodeName - Node name
• agentName - Agent name
• nodeType - Type of node ('llm', 'custom', etc.)
• executionId - Execution ID

Prompt Management

The wrapper automatically fetches prompts from handit based on the agent name. Prompts should be structured as:

• System Prompt: Sets the AI's behavior and context
• User Prompt: Template for user input (can include {{input}} or {{user_input}} placeholders)

Example prompt structure:

[
  {
    type: 'system',
    content: 'You are a helpful customer support agent...'
  },
  {
    type: 'user', 
    content: 'Customer question: {{input}}'
  }
]

Error Handling

The wrapper includes comprehensive error handling:

const result = await aiWrapper.executeWithOpenAI({
  agentName: 'test-agent',
  input: 'test input'
});

if (!result.success) {
  console.error('Execution failed:', result.error);
  // Error is automatically tracked in handit
}

Tracking

All executions are automatically tracked using handit's tracking system:

1. Start Tracing: Begins when execution starts
2. Node Tracking: Tracks input/output for each AI call
3. End Tracing: Completes when execution finishes
4. Error Tracking: Captures and tracks any errors

Supported Models

OpenAI

• gpt-4
• gpt-4-turbo
• gpt-3.5-turbo
• Any other OpenAI model

Google AI

• gemini-pro
• gemini-pro-vision
• Other Gemini models

Anthropic

• claude-3-opus-20240229
• claude-3-sonnet-20240229
• claude-3-haiku-20240307

Examples

See example.js for comprehensive usage examples including:

• Multi-provider execution
• Prompt management
• Manual tracking
• Error handling

Environment Variables

You can also configure API keys using environment variables:

HANDIT_API_KEY=your-handit-key
OPENAI_API_KEY=your-openai-key  
GOOGLE_API_KEY=your-google-key
ANTHROPIC_API_KEY=your-anthropic-key

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📚 Documentation

🚀 Quick Start Guide

Perfect for getting started quickly with the most important methods and examples.

📖 Complete Documentation

Comprehensive documentation including advanced features, best practices, and detailed examples.

The complete documentation covers:

• 🧠 Advanced AI Intelligence Features
• 📊 Analytics & Performance Monitoring
• 🔄 Self-Improvement Capabilities
• 🎯 Multi-Agent Workflows
• 📈 A/B Testing & Optimization
• 🛠️ Advanced Configuration
• 💡 Best Practices & Patterns

Support

For issues and questions:

• Read the Complete Documentation
• Check the handit documentation
• Review the example usage
• Open an issue on GitHub

What Makes This Special

This isn't just an AI wrapper - it's an intelligent AI system that:

1. 🔄 Learns from every interaction
2. 📈 Improves automatically over time
3. 💰 Optimizes for performance and cost
4. 📊 Tracks everything for insights
5. 🚀 Scales with your needs

Start simple with runSmartAgent(), then explore the advanced features as your AI system evolves!