@digilogiclabs/saas-factory-ai/README.md

Next.js 15 Compatible AI Integration Platform - Drop-in ready with server/client separation for seamless React Server Components support.

# 🤖 @digilogiclabs/saas-factory-ai

**The Ultimate AI Integration Platform - From Simple to Enterprise**

[![npm version](https://badge.fury.io/js/@digilogiclabs/saas-factory-ai.svg)](https://www.npmjs.com/package/@digilogiclabs/saas-factory-ai)
[![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The most comprehensive AI integration library that provides **robust and configurable ways to connect any project to all sorts of AI** with both **custom and turnkey solutions for all sorts of projects**.

## ✨ **Why SaaS Factory AI?**

### 🎯 **4 Integration Levels - Choose Your Style**

```typescript
// 1. 🚀 Ultra-Simple (1 line)
const response = await simpleChat('Hello!', process.env.OPENAI_API_KEY);

// 2. ⚡ Quick Start (Project-specific)
const ai = quickStartAI({ 
  apiKey: 'your-key', 
  projectType: 'ecommerce' 
});

// 3. 🎯 Turnkey Solutions (Drop-in)
const chatbot = new AITurnkeyChatbot({
  personality: 'helpful and professional'
});

// 4. 🏢 Enterprise (Full control)
const enterpriseAI = createAIHub({
  providers: { /* multi-provider setup */ },
  routing: { strategy: 'quality' }
});
```

### 🌟 **Key Features**

- **🎛️ Flexible Integration** - From 1-line setup to enterprise configuration
- **🤖 Multi-Provider AI** - OpenAI, Anthropic, Google Gemini (Veo-3), custom providers
- **📱 Cross-Platform** - React, Next.js, React Native, Vue, Angular, Express, WordPress
- **🎬 Video Generation** - Veo-3 integration for realistic video creation
- **🏭 Industry Presets** - E-commerce, Healthcare, Education, Gaming, and more
- **🔄 Intelligent Routing** - Automatic provider selection by cost, speed, quality
- **🛡️ Security First** - No API keys in client code, JWT authentication
- **📈 Production Ready** - Usage quotas, rate limiting, monitoring, analytics

## 🚀 **Quick Start**

### Installation

```bash
npm install @digilogiclabs/saas-factory-ai
```

### Basic Usage

```typescript
import { quickStartAI } from '@digilogiclabs/saas-factory-ai';

// Initialize AI for your project type
const ai = quickStartAI({
  apiKey: process.env.OPENAI_API_KEY,
  projectType: 'ecommerce' // Auto-configured for e-commerce
});

// Start chatting
const response = await ai.chat([
  { role: 'user', content: 'I need help finding a laptop for gaming' }
]);
```

### React Integration

```typescript
import { 
  AIProvider, 
  AIChat, 
  AITextGenerator, 
  AISetupStatus,
  getAIConfigFromEnv 
} from '@digilogiclabs/saas-factory-ai';

function MyApp() {
  const config = getAIConfigFromEnv();

  return (
    <AIProvider config={config}>
      <div className="p-6">
        <AISetupStatus />
        <AIChat placeholder="Ask me anything..." />
        <AITextGenerator 
          templates={['Blog post about', 'Email for']}
          maxLength={1000}
        />
      </div>
    </AIProvider>
  );
}
```

### Environment Setup

Create a `.env.local` file with your AI provider keys:

```env
# Choose one or more providers
NEXT_PUBLIC_OPENAI_API_KEY=sk-your-openai-key
NEXT_PUBLIC_ANTHROPIC_API_KEY=sk-ant-your-claude-key
NEXT_PUBLIC_GOOGLE_AI_API_KEY=your-gemini-key

# Optional gateway URL
NEXT_PUBLIC_AI_GATEWAY_URL=https://your-gateway.com
```

## 🧩 **React Components**

Ready-to-use UI components for common AI interactions:

### AIChat - Complete Chat Interface
```typescript
import { AIChat } from '@digilogiclabs/saas-factory-ai';

<AIChat 
  placeholder="Ask me anything..."
  showTypingIndicator={true}
  enableFileUpload={false}
  maxMessages={50}
  onMessageSent={(message) => console.log('Sent:', message)}
  onResponse={(response) => console.log('Received:', response)}
/>
```

### AITextGenerator - Content Generation
```typescript
import { AITextGenerator } from '@digilogiclabs/saas-factory-ai';

<AITextGenerator
  templates={['Blog post about', 'Product description for']}
  maxLength={1000}
  showWordCount={true}
  onGenerated={(text) => console.log('Generated:', text)}
/>
```

### AIAudioGenerator - Audio Creation
```typescript
import { AIAudioGenerator } from '@digilogiclabs/saas-factory-ai';

<AIAudioGenerator
  supportedFormats={['mp3', 'wav']}
  maxDuration={60}
  showWaveform={true}
  onGenerated={(audioUrl) => console.log('Audio:', audioUrl)}
/>
```

### AIVideoGenerator - Video Creation
```typescript
import { AIVideoGenerator } from '@digilogiclabs/saas-factory-ai';

<AIVideoGenerator
  resolution="1280x720"
  maxDuration={30}
  showPreview={true}
  onGenerated={(videoUrl) => console.log('Video:', videoUrl)}
/>
```

### AISetupStatus - Configuration Status
```typescript
import { AISetupStatus } from '@digilogiclabs/saas-factory-ai';

<AISetupStatus 
  showDetails={true}
  className="mb-4"
/>
```

## 📖 **Documentation**

### **Integration Guides**
- **[React & Next.js](https://github.com/digilogiclabs/saas-factory-ai/blob/main/docs/integrations/react.md)** - Web applications
- **[React Native](https://github.com/digilogiclabs/saas-factory-ai/blob/main/docs/integrations/react-native.md)** - Mobile apps
- **[Express.js](https://github.com/digilogiclabs/saas-factory-ai/blob/main/docs/integrations/express.md)** - Backend APIs
- **[Vue & Angular](https://github.com/digilogiclabs/saas-factory-ai/blob/main/docs/integrations/vue-angular.md)** - Frontend frameworks

### **AI Capabilities**
- **[Text Generation](https://github.com/digilogiclabs/saas-factory-ai/blob/main/docs/capabilities/text.md)** - Chat, completion, analysis
- **[Video Generation](https://github.com/digilogiclabs/saas-factory-ai/blob/main/docs/capabilities/video.md)** - Veo-3 integration
- **[Audio Generation](https://github.com/digilogiclabs/saas-factory-ai/blob/main/docs/capabilities/audio.md)** - Music and speech
- **[Image Processing](https://github.com/digilogiclabs/saas-factory-ai/blob/main/docs/capabilities/images.md)** - Generation and analysis

## 🎯 **Industry Presets**

Ready-to-use configurations for different sectors:

```typescript
// E-commerce with product recommendations
const ecommerce = quickStartAI({ 
  projectType: 'ecommerce',
  capabilities: ['chat', 'embeddings', 'analysis']
});

// Healthcare with HIPAA compliance
const healthcare = quickStartAI({ 
  projectType: 'healthcare',
  environment: 'production',
  enableMonitoring: true
});

// Gaming with dynamic content
const gaming = quickStartAI({ 
  projectType: 'gaming',
  capabilities: ['chat', 'video', 'audio']
});
```

**Available Presets**: E-commerce, Healthcare, Education, Financial, Gaming, Content Creation, Customer Service, Developer Tools, Research

## 🤖 **Turnkey Solutions**

Drop-in AI features for immediate value:

```typescript
import { 
  AITurnkeyChatbot, 
  AITurnkeyContentGenerator,
  AITurnkeyAnalyst 
} from '@digilogiclabs/saas-factory-ai';

// Smart customer service chatbot
const chatbot = new AITurnkeyChatbot({
  apiKey: process.env.OPENAI_API_KEY,
  personality: 'helpful and professional',
  features: ['sentiment-analysis', 'escalation-detection']
});

// Marketing content generator
const contentGen = new AITurnkeyContentGenerator({
  apiKey: process.env.OPENAI_API_KEY,
  contentTypes: ['blog', 'social', 'email'],
  brandVoice: 'friendly and informative'
});

// Business intelligence analyst
const analyst = new AITurnkeyAnalyst({
  apiKey: process.env.OPENAI_API_KEY,
  analysisTypes: ['sentiment', 'trends', 'predictions'],
  reportFormats: ['summary', 'detailed', 'executive']
});
```

## 🏢 **Enterprise Features**

Advanced capabilities for production deployments:

```typescript
import { createAIHub } from '@digilogiclabs/saas-factory-ai';

const enterpriseAI = createAIHub({
  // Multi-provider configuration
  providers: {
    openai: { 
      capabilities: ['text.chat', 'embeddings'], 
      priority: 1,
      costWeight: 0.7
    },
    anthropic: { 
      capabilities: ['text.chat'], 
      priority: 2,
      costWeight: 0.8 
    },
    gemini: { 
      capabilities: ['video.generation'], 
      priority: 1
    }
  },

  // Intelligent routing
  routing: {
    strategy: 'quality', // or 'cost', 'speed'
    fallback: true,
    loadBalancing: true
  },

  // Production features
  features: {
    caching: { enabled: true, ttl: 1800 },
    rateLimiting: { enabled: true, requests: 10000 },
    monitoring: { enabled: true, metrics: ['cost', 'usage'] },
    security: { encryption: true, auditLogging: true }
  }
});
```

## 🎬 **Video Generation (Veo-3)**

Create realistic videos for training and content:

```typescript
import { quickStartAI } from '@digilogiclabs/saas-factory-ai';

const ai = quickStartAI({
  apiKey: process.env.GOOGLE_API_KEY,
  primaryProvider: 'gemini' // For Veo-3 access
});

// Generate 8-second video
const videoJob = await ai.generateVideo(
  'A news anchor reporting on breaking technology news',
  {
    duration: 8, // Veo-3 limit
    resolution: '720p',
    style: 'news-broadcast'
  }
);

// Monitor progress
const { status, progress, result } = await ai.getJobStatus(videoJob.jobId);
```

## 🔧 **Framework Integrations**

### Next.js App Router

```typescript
// app/api/ai/chat/route.ts
import { createAIRoute } from '@digilogiclabs/saas-factory-ai/adapters';

export const { POST } = createAIRoute({
  apiKey: process.env.OPENAI_API_KEY,
  projectType: 'developer'
});
```

### Express.js Middleware

```typescript
import { aiMiddleware } from '@digilogiclabs/saas-factory-ai/adapters';

app.use(aiMiddleware({
  apiKey: process.env.OPENAI_API_KEY,
  projectType: 'customer-service'
}));

app.post('/chat', (req, res) => {
  const response = await req.ai.chat([
    { role: 'user', content: req.body.message }
  ]);
  res.json({ response });
});
```

### React Native

```typescript
import { quickStartAI } from '@digilogiclabs/saas-factory-ai/react-native';

const ai = quickStartAI({
  apiKey: process.env.OPENAI_API_KEY,
  projectType: 'content-creator'
});

// Mobile-optimized with polling instead of SSE
const response = await ai.chat([
  { role: 'user', content: 'Generate social media caption' }
]);
```

## 📊 **Real-Time Usage**

### Streaming Responses

```typescript
const stream = await ai.chat([
  { role: 'user', content: 'Write a detailed analysis' }
], { stream: true });

for await (const chunk of stream) {
  console.log(chunk); // Real-time output
}
```

### Progress Tracking

```typescript
import { useJobStatus } from '@digilogiclabs/saas-factory-ai';

function VideoGenerator() {
  const [jobId, setJobId] = useState(null);
  const { status, progress, isComplete } = useJobStatus(jobId);

  return (
    <div>
      {status === 'running' && <Progress value={progress} />}
      {isComplete && <VideoPlayer url={status.result.url} />}
    </div>
  );
}
```

## 🛡️ **Security & Privacy**

- **🔐 No API Keys in Client**: All AI providers accessed through secure gateway
- **🔑 JWT Authentication**: Secure token-based authentication
- **📊 Usage Tracking**: Monitor and control AI usage and costs  
- **🚨 Rate Limiting**: Prevent abuse and unexpected charges
- **🔍 Audit Logging**: Complete audit trail of AI operations
- **🛡️ Content Filtering**: Built-in safety and content moderation

## 💰 **Cost Management**

```typescript
// Real-time cost estimation
const estimate = await ai.estimateCost([
  { capability: 'text.chat', input: 'Long article generation' },
  { capability: 'video.generation', input: '8-second demo video' }
]);

console.log(`Estimated cost: $${estimate.totalEstimated}`);

// Budget controls
if (estimate.totalEstimated > 5.00) {
  console.log('Operation exceeds budget');
  return;
}

// Proceed with operations
const results = await ai.batch(operations);
```

## 🌍 **Community & Examples**

### Real-World Applications
- **[Fake News Detection Platform](https://github.com/digilogiclabs/saas-factory-ai/tree/main/examples/fake-news)** - Community-driven video generation
- **[E-commerce AI Assistant](https://github.com/digilogiclabs/saas-factory-ai/tree/main/examples/ecommerce)** - Product recommendations and support
- **[Content Creation Suite](https://github.com/digilogiclabs/saas-factory-ai/tree/main/examples/content-creator)** - Blog, social, video generation

### Templates
- **[Next.js + AI Template](https://github.com/digilogiclabs/saas-factory-ai/tree/main/templates/nextjs-ai)** - Complete web application
- **[React Native + AI Template](https://github.com/digilogiclabs/saas-factory-ai/tree/main/templates/react-native-ai)** - Mobile application
- **[Express + AI API Template](https://github.com/digilogiclabs/saas-factory-ai/tree/main/templates/api-ai)** - Backend service

## 📝 **License**

MIT License - see the [LICENSE](https://github.com/digilogiclabs/saas-factory-ai/blob/main/LICENSE) file for details.

## 🤝 **Support & Community**

- **📖 Documentation**: [GitHub Wiki](https://github.com/digilogiclabs/saas-factory-ai/wiki)
- **💬 Discussions**: [GitHub Discussions](https://github.com/digilogiclabs/saas-factory-ai/discussions)
- **🐛 Issues**: [GitHub Issues](https://github.com/digilogiclabs/saas-factory-ai/issues)
- **💼 Enterprise**: enterprise@digilogiclabs.com

---

**Part of the SaaS Factory Ecosystem:**
- [saas-factory-auth](https://www.npmjs.com/package/@digilogiclabs/saas-factory-auth) - Authentication & user management
- [saas-factory-payments](https://www.npmjs.com/package/@digilogiclabs/saas-factory-payments) - Subscription billing
- [saas-factory-ui](https://www.npmjs.com/package/@digilogiclabs/saas-factory-ui) - React component library
- **@digilogiclabs/saas-factory-ai** - AI integration (this package)