@guardaian/sdk/README.md

Zero-friction AI governance and monitoring SDK for Node.js applications

# GuardAIan SDK

[![npm version](https://badge.fury.io/js/@guardaian/sdk.svg)](https://www.npmjs.com/package/@guardaian/sdk)
[![Downloads](https://img.shields.io/npm/dm/@guardaian/sdk.svg)](https://www.npmjs.com/package/@guardaian/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![AI Providers](https://img.shields.io/badge/AI_Providers-7_Supported-purple.svg)](#supported-ai-providers)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)

<div align="center">

## **Monitor ALL your AI usage with one line of code**

**The only SDK that automatically tracks OpenAI, Anthropic, Google, Azure, AWS, Cohere & Hugging Face**

[**🚀 Get Started Free**](https://app.guardaianlabs.com) • [**📚 Documentation**](https://github.com/guardaian-labs/guardaian-platform/wiki) • [**💬 Support**](https://github.com/guardaian-labs/guardaian-platform/discussions)

---

### **✨ One import. Zero code changes. Complete AI governance.**

</div>

---

## 🚀 **Quick Start (30 seconds)**

```bash
npm install @guardaian/sdk
```

```javascript
import '@guardaian/sdk/auto';
import { GuardAIan } from '@guardaian/sdk';

GuardAIan.init({ apiKey: 'gai_your_key' }); // Get free key at app.guardaianlabs.com

// Your existing AI code now tracked automatically! 🛡️
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});
// ✅ Cost, tokens, compliance automatically tracked in dashboard
```

**✅ Zero code changes • ✅ All AI providers • ✅ Free dashboard**

[**🚀 Get Free API Key**](https://app.guardaianlabs.com) • [**📚 Full Documentation**](https://github.com/guardaian-labs/guardaian-platform/wiki)

---

## 🚀 **Production-Ready AI Governance**

<div align="center">

**Enterprise-grade reliability • Developer-friendly integration • Comprehensive monitoring**

Built for companies that need complete AI governance without compromising developer velocity.  
From startups to enterprise, GuardAIan scales with your AI usage.

**✅ Zero-downtime deployment**  
**✅ Enterprise security standards**  
**✅ Comprehensive provider coverage**  
**✅ Real-time monitoring & alerts**

</div>

---

## 💡 **Why GuardAIan SDK?**

### **🎯 Universal Coverage**
- **7 AI providers supported** - OpenAI, Anthropic, Google, Azure, AWS, Cohere, Hugging Face
- **85% market coverage** - Works with all major enterprise AI services
- **One SDK for everything** - No more juggling multiple monitoring tools

### **⚡ Zero Friction**
- **One import line** - `import '@guardaian/sdk/auto'`
- **No code changes** - Works with your existing AI implementations
- **Drop-in replacement** - Transparent interception, identical APIs

### **🛡️ Enterprise Ready**
- **Real-time compliance** - Instant policy enforcement
- **Complete audit trails** - Full regulatory compliance (SOC2, GDPR)
- **Professional dashboards** - Executive-ready reporting

### **💰 Immediate ROI**
- **Cost optimization** - Track spending across all AI services
- **Usage insights** - Optimize AI usage patterns
- **Policy enforcement** - Prevent budget overruns automatically

---

## 🤖 **Supported AI Providers**

| Provider | Models | Package | Status |
|----------|--------|---------|--------|
| **🤖 OpenAI** | GPT-4, GPT-3.5, DALL-E | `openai` | ✅ **Full Support** |
| **🧠 Anthropic** | Claude 3.5 Sonnet, Opus | `@anthropic-ai/sdk` | ✅ **Full Support** |
| **🔍 Google** | Gemini Pro, Flash | `@google/generative-ai` | ✅ **Full Support** |
| **☁️ Azure OpenAI** | Enterprise GPT models | `openai` + Azure | ✅ **Full Support** |
| **🔶 AWS Bedrock** | Claude, Llama, Titan | `@aws-sdk/client-bedrock-runtime` | ✅ **Full Support** |
| **🟦 Cohere** | Command-R, Embeddings | `cohere-ai` | ✅ **Full Support** |
| **🤗 Hugging Face** | Open Source Models | `@huggingface/inference` | ✅ **Full Support** |

**🎯 Covers 85% of enterprise AI usage**

---

## 💻 **Usage Examples**

### **🤖 OpenAI (Most Popular)**
```javascript
import { GuardAIan } from '@guardaian/sdk';
import '@guardaian/sdk/auto';
import OpenAI from 'openai';

GuardAIan.init({ apiKey: 'gai_abc123' });

const openai = new OpenAI({ apiKey: 'sk-...' });

// Automatically tracked: cost, tokens, duration, compliance
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});

// Dashboard shows: $0.006 cost, 150 tokens, 1.2s duration ✅
```

### **🧠 Anthropic Claude**
```javascript
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({ apiKey: 'sk-ant-...' });

// Automatically tracked with GuardAIan
const message = await anthropic.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1000,
  messages: [{ role: 'user', content: 'Analyze this data...' }]
});

// Tracks: Claude-specific pricing, token usage, compliance
```

### **🔍 Google Gemini (Free Testing)**
```javascript
import { GoogleGenerativeAI } from '@google/generative-ai';

const genAI = new GoogleGenerativeAI('your-api-key');
const model = genAI.getGenerativeModel({ model: 'gemini-pro' });

// Automatically tracked with GuardAIan
const result = await model.generateContent('Explain quantum computing');

// Perfect for free testing - no credit card required!
// Get free key: https://makersuite.google.com/app/apikey
```

### **☁️ Azure OpenAI (Enterprise)**
```javascript
import OpenAI from 'openai';

const azure = new OpenAI({
  apiKey: 'your-azure-key',
  baseURL: 'https://your-resource.openai.azure.com/openai/deployments/gpt-4',
  defaultQuery: { 'api-version': '2024-02-01' }
});

// Tracked separately as 'azure-openai' service
const response = await azure.chat.completions.create({...});
```

---

## ⚙️ **Configuration**

### **🔧 Basic Setup**
```javascript
GuardAIan.init({
  apiKey: 'gai_abc123',           // Required: Your GuardAIan API key
  environment: 'production',      // Optional: Environment name
  projectName: 'my-ai-app',       // Optional: Project identifier
  debug: false                    // Optional: Enable debug logging
});
```

### **🚀 Advanced Configuration**
```javascript
GuardAIan.init({
  apiKey: 'gai_abc123',
  baseURL: 'https://api.guardaianlabs.com',     // Optional: Custom API endpoint
  environment: 'production',                    // Optional: Environment name
  projectName: 'my-ai-app',                    // Optional: Project identifier
  debug: false,                                // Optional: Enable debug logging
  batchSize: 10,                               // Optional: Batch size for API calls
  flushInterval: 5000,                         // Optional: Flush interval in ms
  customTags: ['team:ml', 'cost-center:r&d']  // Optional: Custom metadata tags
});
```

### **🏢 Environment-Specific Setup**
```javascript
// Use environment variables for different stages
GuardAIan.init({
  apiKey: process.env.GUARDAIAN_API_KEY,
  environment: process.env.NODE_ENV,
  projectName: 'your-app-name',
  debug: process.env.NODE_ENV !== 'production'
});
```

---

## 📊 **What Gets Tracked Automatically**

### **💰 Complete Cost Analysis**
- **Real-time cost calculation** with provider-specific pricing
- **Token usage breakdown** (input/output tokens)
- **Cost per model** and operation type
- **Budget tracking** with automatic alerts

### **⚡ Performance Monitoring**
- **Response time tracking** for optimization
- **API call success/failure rates**
- **Performance comparisons** between models
- **Usage patterns** and trends

### **🛡️ Compliance & Governance**
- **Automatic policy enforcement** in real-time
- **Usage limit monitoring** (calls, tokens, spend)
- **Model restriction enforcement** 
- **Security scanning** and violation alerts

### **📈 Business Intelligence**
- **Usage analytics** across teams and projects
- **Cost optimization insights** and recommendations
- **Executive reporting** with trends and forecasts
- **ROI analysis** for AI investments

---

## 🛡️ **Compliance & Governance**

GuardAIan automatically enforces your organization's AI policies:

```javascript
// Your dashboard policies are enforced automatically:

// ❌ Usage Limits: Max 1000 API calls per day
// ❌ Budget Controls: Max $500/month across all AI services  
// ❌ Model Restrictions: Only allow GPT-3.5 and Claude-3-haiku
// ❌ Time Restrictions: AI usage only during business hours
// ❌ Content Filtering: Block sensitive data patterns

const response = await openai.chat.completions.create({
  model: 'gpt-4', // Might be blocked by policy
  messages: [{ role: 'user', content: 'Hello!' }]
});

// Policy violations are automatically:
// 🚨 Logged to your dashboard
// 📧 Sent as alerts to admins  
// 📊 Included in compliance reports
// ✅ Your code continues to work normally
```

**🔒 Enterprise Security:**
- **SOC 2 Type II** compliant infrastructure
- **GDPR compliant** data handling
- **No sensitive data stored** - Only metadata tracked
- **API keys encrypted** in transit and at rest

---

## 💻 **TypeScript Support**

Full TypeScript definitions included:

```typescript
import { GuardAIan, TrackingData, GuardAIanOptions } from '@guardaian/sdk';

// Fully typed initialization
const config: GuardAIanOptions = {
  apiKey: 'gai_abc123',
  environment: 'production',
  debug: false
};

GuardAIan.init(config);

// Type-safe manual tracking
const event: TrackingData = {
  service: 'openai',
  model: 'gpt-4',
  operation: 'chat.completion',
  inputTokens: 100,
  outputTokens: 50,
  cost: 0.006
};

await guardaian.track(event);
```

---

## 🔧 **Manual Tracking & Advanced Usage**

### **Manual Event Tracking**
```javascript
import { GuardAIan } from '@guardaian/sdk';

const guardaian = new GuardAIan({ apiKey: 'gai_abc123' });

// Track custom AI usage
await guardaian.track({
  service: 'openai',
  model: 'gpt-4',
  operation: 'chat.completion',
  inputTokens: 100,
  outputTokens: 50,
  cost: 0.006,
  duration: 1200,
  metadata: {
    userId: 'user123',
    feature: 'chat-assistant'
  }
});
```

### **Status Checking & Debugging**
```javascript
// Check if SDK is properly initialized
if (GuardAIan.isInitialized()) {
  console.log('✅ GuardAIan is ready!');
}

// Enable debug logging
GuardAIan.init({ 
  apiKey: 'gai_abc123',
  debug: true 
});

// Console output:
// 🛡️ GuardAIan: Intercepted OpenAI call...
// 💰 Cost: $0.006, Tokens: 150, Duration: 1.2s  
// ✅ Successfully sent to dashboard
```

---

## 🛡️ **Error Handling & Reliability**

GuardAIan is designed to **never break your AI applications**:

### **🔒 Fail-Safe Design**
```javascript
// Even if GuardAIan is completely down, your AI calls work normally
const response = await openai.chat.completions.create({...}); 
// ✅ Always works - tracking is an enhancement, not a dependency
```

### **🔄 Resilient Architecture**
- **Non-blocking tracking** - Network issues don't affect your app
- **Automatic retries** - Failed tracking calls are retried automatically
- **Graceful degradation** - Invalid config disables monitoring silently
- **Error isolation** - GuardAIan errors never bubble up to your code

### **⚡ Performance**
- **< 1ms overhead** per API call
- **Async background processing** - non-blocking
- **Intelligent batching** - efficient network usage
- **Memory efficient** - automatic cleanup

---

## 📖 **Getting Started Guide**

### **Step 1: Get Your API Key** 
1. 🚀 **Sign up** at [app.guardaianlabs.com](https://app.guardaianlabs.com)
2. 📊 **Create a project** for your application
3. 🔑 **Generate API key** from the dashboard
4. 🛡️ **Set up policies** (optional but recommended)

### **Step 2: Install & Initialize**
```bash
npm install @guardaian/sdk
```

```javascript
// Add to your application entry point
import { GuardAIan } from '@guardaian/sdk';
import '@guardaian/sdk/auto';

GuardAIan.init({ 
  apiKey: process.env.GUARDAIAN_API_KEY,
  environment: process.env.NODE_ENV,
  projectName: 'your-app-name'
});
```

### **Step 3: Verify Setup**
```javascript
// Run a test AI call and check your dashboard
const response = await openai.chat.completions.create({
  model: 'gpt-3.5-turbo',
  messages: [{ role: 'user', content: 'Hello GuardAIan!' }]
});

// ✅ Check https://app.guardaianlabs.com for the tracked usage
```

---

## 🧪 **Testing & Development**

### **🔧 Development Setup**
```javascript
// Environment-specific configuration
GuardAIan.init({
  apiKey: process.env.NODE_ENV === 'production' 
    ? process.env.GUARDAIAN_PROD_KEY 
    : process.env.GUARDAIAN_DEV_KEY,
  environment: process.env.NODE_ENV,
  debug: process.env.NODE_ENV === 'development'
});
```

### **🧪 Free Testing with Google Gemini**
```javascript
// Perfect for development - no credit card required
import { GoogleGenerativeAI } from '@google/generative-ai';

const genAI = new GoogleGenerativeAI('your-free-api-key');
const model = genAI.getGenerativeModel({ model: 'gemini-1.5-flash' });

const result = await model.generateContent('Test GuardAIan tracking');
// Get free API key: https://makersuite.google.com/app/apikey
```

---

## 📚 **Documentation & Resources**

### **📖 Documentation**
- **[Complete API Reference](https://github.com/guardaian-labs/guardaian-platform/wiki)** - Full SDK documentation
- **[Quick Start Guide](https://github.com/guardaian-labs/guardaian-platform/wiki/Quick-Start)** - Get running in 5 minutes
- **[Provider Setup Guides](https://github.com/guardaian-labs/guardaian-platform/wiki/Providers)** - Setup for each AI service
- **[Enterprise Features](https://github.com/guardaian-labs/guardaian-platform/wiki/Enterprise)** - Advanced configuration

### **💬 Community & Support**
- **[GitHub Discussions](https://github.com/guardaian-labs/guardaian-platform/discussions)** - Community Q&A
- **[GitHub Issues](https://github.com/guardaian-labs/guardaian-platform/issues)** - Bug reports and feature requests
- **[Support Email](mailto:support@guardaianlabs.com)** - Direct technical support

### **🎥 Learning Resources**
- **[Blog Posts](https://blog.guardaianlabs.com)** - AI governance insights and tips
- **[Case Studies](https://guardaianlabs.com/case-studies)** - Real customer success stories

---


## 📅 **Changelog & Roadmap**

### **🚀 Current Version: 1.0.0**
- ✅ Universal AI provider support (7 providers)
- ✅ Real-time cost calculation
- ✅ Automatic compliance checking
- ✅ TypeScript definitions
- ✅ Enterprise security features

### **🔮 Coming Soon**
- 🔧 **More AI Providers** - Stability AI, AI21 Labs
- 📊 **Advanced Analytics** - Usage forecasting, anomaly detection
- 🔗 **Webhook Support** - Real-time notifications
- 🌐 **Multi-region Support** - Global deployment options

---

## 📄 **License**

MIT License - see [LICENSE](LICENSE) file for details.

**Privacy & Security:**
- [Privacy Policy](https://guardaianlabs.com/privacy)
- [Terms of Service](https://guardaianlabs.com/terms)
- [Security](https://guardaianlabs.com/security)

---

## 🎯 **Ready to Get Started?**

### **🚀 Free Trial - No Credit Card Required**

```bash
# Install and start monitoring in under 2 minutes
npm install @guardaian/sdk

# Sign up and get your API key
# https://app.guardaianlabs.com/signup

# Add these two lines to your app
import { GuardAIan } from '@guardaian/sdk';
import '@guardaian/sdk/auto';

GuardAIan.init({ apiKey: 'your_api_key' });

# Your existing AI code now has complete governance! 🛡️
```

**[🚀 Start Free Trial](https://app.guardaianlabs.com/signup)** • **[📚 Read Full Docs](https://github.com/guardaian-labs/guardaian-platform/wiki)** • **[💬 Get Support](https://github.com/guardaian-labs/guardaian-platform/discussions)**

---

<div align="center">

### **🛡️ The Complete AI Governance Solution**

**Built for developers who use AI responsibly**

[![GitHub stars](https://img.shields.io/github/stars/guardaian-labs/guardaian-platform?style=social)](https://github.com/guardaian-labs/guardaian-platform)
[![npm downloads](https://img.shields.io/npm/dm/@guardaian/sdk.svg)](https://www.npmjs.com/package/@guardaian/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**⭐ Star this repo if GuardAIan is securing your AI usage!**

---

*Made with ❤️ by GuardAIan Labs*

</div>