npm package: @handit.ai/ai-wrapper
Description: 🤖 Intelligent AI execution system with built-in tracking, evaluation, and self-improvement capabilities. The complete AI intelligence platform for enterprise applications.
Author: Handit AI
Latest version: 1.0.0

<div align="center">

# 🤖 @handit.ai/ai-wrapper

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

[![npm version](https://badge.fury.io/js/%40handit.ai%2Fai-wrapper.svg)](https://badge.fury.io/js/%40handit.ai%2Fai-wrapper)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI/CD Pipeline](https://github.com/handit-ai/ai-wrapper/workflows/CI%2FCD%20Pipeline/badge.svg)](https://github.com/handit-ai/ai-wrapper/actions)
[![codecov](https://codecov.io/gh/handit-ai/ai-wrapper/branch/main/graph/badge.svg)](https://codecov.io/gh/handit-ai/ai-wrapper)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)

[![OpenAI](https://img.shields.io/badge/OpenAI-GPT--4%20Ready-00A67E.svg)](https://openai.com/)
[![Google AI](https://img.shields.io/badge/Google-Gemini%20Ready-4285F4.svg)](https://ai.google/)
[![Anthropic](https://img.shields.io/badge/Anthropic-Claude%20Ready-8A2BE2.svg)](https://www.anthropic.com/)

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

[📚 **Documentation**](./DOCUMENTATION.md) • [🚀 **Quick Start**](./QUICK_START.md) • [🔧 **Examples**](./examples/) • [🐛 **Issues**](https://github.com/handit-ai/ai-wrapper/issues) • [💬 **Discussions**](https://github.com/handit-ai/ai-wrapper/discussions)

</div>

---

## 🧠 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

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

## 🚀 Quick Start

```javascript
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

```javascript
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)

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
// 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:**
```javascript
{
  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:
```javascript
[
  {
    type: 'system',
    content: 'You are a helpful customer support agent...'
  },
  {
    type: 'user', 
    content: 'Customer question: {{input}}'
  }
]
```

## Error Handling

The wrapper includes comprehensive error handling:

```javascript
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:

```bash
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](./QUICK_START.md)
Perfect for getting started quickly with the most important methods and examples.

### 📖 [Complete Documentation](./DOCUMENTATION.md)
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](./DOCUMENTATION.md)
- Check the handit documentation
- Review the [example usage](./example.js)
- 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!