🤖 @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:

Start Tracing: Begins when execution starts
Node Tracking: Tracks input/output for each AI call
End Tracing: Completes when execution finishes
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

Fork the repository
Create a feature branch
Make your changes
Add tests
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:

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

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