@handit.ai/ai-wrapper
Version:
🤖 Intelligent AI execution system with built-in tracking, evaluation, and self-improvement capabilities. The complete AI intelligence platform for enterprise applications.
335 lines (258 loc) • 9.74 kB
Markdown
<div align="center">
# 🤖 @handit.ai/ai-wrapper
**Intelligent AI Execution System with Built-in Tracking & Self-Improvement**
[](https://badge.fury.io/js/%40handit.ai%2Fai-wrapper)
[](https://opensource.org/licenses/MIT)
[](https://github.com/handit-ai/ai-wrapper/actions)
[](https://codecov.io/gh/handit-ai/ai-wrapper)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://openai.com/)
[](https://ai.google/)
[](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!