@hazeljs/ai 0.2.0-beta.1

package/README.md

@@ -0,0 +1,496 @@
+# @hazeljs/ai
+
+**AI Integration Module for HazelJS - OpenAI, Anthropic, Gemini, Cohere, and Ollama Support**
+
+Build AI-powered applications with first-class LLM integration, streaming support, and decorator-based APIs.
+
+[![npm version](https://img.shields.io/npm/v/@hazeljs/ai.svg)](https://www.npmjs.com/package/@hazeljs/ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🤖 **Multiple Providers** - OpenAI, Anthropic, Gemini, Cohere, Ollama
+- 🎨 **Decorator-Based API** - `@AITask` decorator for clean integration
+- 📡 **Streaming Support** - Real-time response streaming
+- 🔄 **Retry Logic** - Automatic retries with exponential backoff
+- 💾 **Response Caching** - Built-in caching with @hazeljs/cache
+- 🎯 **Type Safety** - Full TypeScript support with output types
+- 🔧 **Flexible Configuration** - Per-task or global configuration
+- 📊 **Token Tracking** - Monitor usage and costs
+
+## Installation
+
+```bash
+npm install @hazeljs/ai
+```
+
+### Peer Dependencies
+
+Install the provider(s) you want to use:
+
+```bash
+# OpenAI
+npm install openai
+
+# Anthropic
+npm install @anthropic-ai/sdk
+
+# Google Gemini
+npm install @google/generative-ai
+
+# Cohere
+npm install cohere-ai
+
+# Ollama (local LLMs)
+npm install ollama
+```
+
+## Quick Start
+
+### Basic Usage with Decorator
+
+```typescript
+import { Injectable } from '@hazeljs/core';
+import { AIService, AITask } from '@hazeljs/ai';
+
+@Injectable()
+export class ChatService {
+  constructor(private aiService: AIService) {}
+
+  @AITask({
+    name: 'chat',
+    prompt: 'You are a helpful assistant. Respond to: {{input}}',
+    provider: 'openai',
+    model: 'gpt-4',
+    outputType: 'string',
+  })
+  async chat(message: string): Promise<string> {
+    return message; // Decorator handles AI execution
+  }
+}
+
+// Usage
+const response = await chatService.chat('Hello, how are you?');
+console.log(response);
+```
+
+### Direct AI Service Usage
+
+```typescript
+import { AIEnhancedService } from '@hazeljs/ai';
+
+const aiService = new AIEnhancedService();
+
+const response = await aiService.complete({
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant' },
+    { role: 'user', content: 'What is TypeScript?' }
+  ],
+  model: 'gpt-4',
+  provider: 'openai',
+  temperature: 0.7,
+  maxTokens: 500,
+});
+
+console.log(response.content);
+console.log('Tokens used:', response.usage);
+```
+
+## Providers
+
+### OpenAI
+
+```typescript
+import { AIEnhancedService } from '@hazeljs/ai';
+
+const aiService = new AIEnhancedService();
+
+// GPT-4
+const response = await aiService.complete({
+  messages: [{ role: 'user', content: 'Hello!' }],
+  model: 'gpt-4',
+  provider: 'openai',
+});
+
+// GPT-3.5 Turbo
+const response2 = await aiService.complete({
+  messages: [{ role: 'user', content: 'Hello!' }],
+  model: 'gpt-3.5-turbo',
+  provider: 'openai',
+});
+```
+
+### Anthropic Claude
+
+```typescript
+const response = await aiService.complete({
+  messages: [{ role: 'user', content: 'Explain quantum computing' }],
+  model: 'claude-3-opus-20240229',
+  provider: 'anthropic',
+  maxTokens: 1000,
+});
+```
+
+### Google Gemini
+
+```typescript
+const response = await aiService.complete({
+  messages: [{ role: 'user', content: 'Write a poem' }],
+  model: 'gemini-pro',
+  provider: 'gemini',
+});
+```
+
+### Cohere
+
+```typescript
+const response = await aiService.complete({
+  messages: [{ role: 'user', content: 'Summarize this text' }],
+  model: 'command',
+  provider: 'cohere',
+});
+```
+
+### Ollama (Local LLMs)
+
+```typescript
+const response = await aiService.complete({
+  messages: [{ role: 'user', content: 'Hello!' }],
+  model: 'llama2',
+  provider: 'ollama',
+  baseURL: 'http://localhost:11434',
+});
+```
+
+## Streaming
+
+```typescript
+import { AIEnhancedService } from '@hazeljs/ai';
+
+const aiService = new AIEnhancedService();
+
+// Stream responses in real-time
+for await (const chunk of aiService.streamComplete({
+  messages: [{ role: 'user', content: 'Tell me a long story' }],
+  provider: 'openai',
+  model: 'gpt-4',
+})) {
+  process.stdout.write(chunk.delta);
+}
+```
+
+### Streaming with Decorator
+
+```typescript
+@AITask({
+  name: 'stream-chat',
+  prompt: 'You are a storyteller. Tell a story about: {{topic}}',
+  provider: 'openai',
+  model: 'gpt-4',
+  stream: true,
+})
+async streamStory(topic: string): AsyncGenerator<string> {
+  return topic; // Returns async generator
+}
+
+// Usage
+for await (const chunk of chatService.streamStory('dragons')) {
+  console.log(chunk);
+}
+```
+
+## Advanced Features
+
+### Response Caching
+
+```typescript
+import { AITask } from '@hazeljs/ai';
+
+@AITask({
+  name: 'cached-completion',
+  prompt: 'Explain {{concept}}',
+  provider: 'openai',
+  model: 'gpt-4',
+  cache: {
+    enabled: true,
+    ttl: 3600, // 1 hour
+    key: 'explain-{{concept}}',
+  },
+})
+async explainConcept(concept: string): Promise<string> {
+  return concept;
+}
+```
+
+### Retry Logic
+
+```typescript
+const response = await aiService.complete({
+  messages: [{ role: 'user', content: 'Hello' }],
+  provider: 'openai',
+  model: 'gpt-4',
+  retry: {
+    maxRetries: 3,
+    initialDelay: 1000,
+    maxDelay: 10000,
+    backoffMultiplier: 2,
+  },
+});
+```
+
+### Output Type Validation
+
+```typescript
+interface UserProfile {
+  name: string;
+  age: number;
+  interests: string[];
+}
+
+@AITask({
+  name: 'extract-profile',
+  prompt: 'Extract user profile from: {{text}}',
+  provider: 'openai',
+  model: 'gpt-4',
+  outputType: 'json',
+})
+async extractProfile(text: string): Promise<UserProfile> {
+  return text;
+}
+
+const profile = await service.extractProfile('John is 25 and loves coding');
+console.log(profile.name); // Type-safe!
+```
+
+### Function Calling
+
+```typescript
+const response = await aiService.complete({
+  messages: [{ role: 'user', content: 'What is the weather in NYC?' }],
+  provider: 'openai',
+  model: 'gpt-4',
+  functions: [
+    {
+      name: 'get_weather',
+      description: 'Get the current weather in a location',
+      parameters: {
+        type: 'object',
+        properties: {
+          location: {
+            type: 'string',
+            description: 'The city and state, e.g. San Francisco, CA',
+          },
+          unit: { type: 'string', enum: ['celsius', 'fahrenheit'] },
+        },
+        required: ['location'],
+      },
+    },
+  ],
+  functionCall: 'auto',
+});
+
+if (response.functionCall) {
+  console.log('Function:', response.functionCall.name);
+  console.log('Arguments:', response.functionCall.arguments);
+}
+```
+
+## Configuration
+
+### Global Configuration
+
+```typescript
+import { AIModule } from '@hazeljs/ai';
+
+@HazelModule({
+  imports: [
+    AIModule.forRoot({
+      providers: {
+        openai: {
+          apiKey: process.env.OPENAI_API_KEY,
+          organization: process.env.OPENAI_ORG,
+        },
+        anthropic: {
+          apiKey: process.env.ANTHROPIC_API_KEY,
+        },
+        gemini: {
+          apiKey: process.env.GEMINI_API_KEY,
+        },
+      },
+      defaultProvider: 'openai',
+      defaultModel: 'gpt-4',
+      cache: {
+        enabled: true,
+        ttl: 3600,
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Per-Task Configuration
+
+```typescript
+@AITask({
+  name: 'custom-task',
+  prompt: 'Process: {{input}}',
+  provider: 'openai',
+  model: 'gpt-4',
+  temperature: 0.7,
+  maxTokens: 1000,
+  topP: 0.9,
+  frequencyPenalty: 0.5,
+  presencePenalty: 0.5,
+  stop: ['\n\n'],
+})
+async processInput(input: string): Promise<string> {
+  return input;
+}
+```
+
+## Use Cases
+
+### Chatbot
+
+```typescript
+@Injectable()
+export class ChatbotService {
+  private conversationHistory: Array<{ role: string; content: string }> = [];
+
+  @AITask({
+    name: 'chat',
+    provider: 'openai',
+    model: 'gpt-4',
+  })
+  async chat(message: string): Promise<string> {
+    this.conversationHistory.push({ role: 'user', content: message });
+    
+    const response = await this.aiService.complete({
+      messages: this.conversationHistory,
+      provider: 'openai',
+      model: 'gpt-4',
+    });
+
+    this.conversationHistory.push({ 
+      role: 'assistant', 
+      content: response.content 
+    });
+
+    return response.content;
+  }
+}
+```
+
+### Content Generation
+
+```typescript
+@Injectable()
+export class ContentService {
+  @AITask({
+    name: 'generate-blog',
+    prompt: `Write a blog post about {{topic}}.
+    
+    Requirements:
+    - Length: {{length}} words
+    - Tone: {{tone}}
+    - Include SEO keywords: {{keywords}}`,
+    provider: 'openai',
+    model: 'gpt-4',
+    outputType: 'string',
+  })
+  async generateBlogPost(
+    topic: string,
+    length: number,
+    tone: string,
+    keywords: string[]
+  ): Promise<string> {
+    return topic;
+  }
+}
+```
+
+### Data Extraction
+
+```typescript
+interface ExtractedData {
+  entities: string[];
+  sentiment: 'positive' | 'negative' | 'neutral';
+  summary: string;
+}
+
+@Injectable()
+export class AnalysisService {
+  @AITask({
+    name: 'analyze-text',
+    prompt: `Analyze the following text and extract:
+    1. Named entities (people, places, organizations)
+    2. Overall sentiment
+    3. Brief summary
+    
+    Text: {{text}}
+    
+    Return as JSON.`,
+    provider: 'openai',
+    model: 'gpt-4',
+    outputType: 'json',
+  })
+  async analyzeText(text: string): Promise<ExtractedData> {
+    return text;
+  }
+}
+```
+
+## API Reference
+
+### AIEnhancedService
+
+```typescript
+class AIEnhancedService {
+  complete(options: AICompletionOptions): Promise<AIResponse>;
+  streamComplete(options: AICompletionOptions): AsyncGenerator<AIStreamChunk>;
+  embed(text: string, options?: EmbedOptions): Promise<number[]>;
+}
+```
+
+### @AITask Decorator
+
+```typescript
+@AITask({
+  name: string;
+  prompt?: string;
+  provider: 'openai' | 'anthropic' | 'gemini' | 'cohere' | 'ollama';
+  model: string;
+  outputType?: 'string' | 'json' | 'number' | 'boolean';
+  stream?: boolean;
+  temperature?: number;
+  maxTokens?: number;
+  cache?: CacheOptions;
+  retry?: RetryOptions;
+})
+```
+
+## Examples
+
+See the [examples](../../example/src/ai) directory for complete working examples.
+
+## Testing
+
+```bash
+npm test
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) for details.
+
+## License
+
+MIT © [HazelJS](https://hazeljs.com)
+
+## Links
+
+- [Documentation](https://hazeljs.com/docs/packages/ai)
+- [GitHub](https://github.com/hazel-js/hazeljs)
+- [Issues](https://github.com/hazeljs/hazel-js/issues)
+- [Discord](https://discord.gg/hazeljs)

package/dist/ai-enhanced.service.d.ts

@@ -0,0 +1,108 @@
+import { IAIProvider, AIProvider, AICompletionRequest, AICompletionResponse, AIStreamChunk, AIEmbeddingRequest, AIEmbeddingResponse, AIModelConfig } from './ai-enhanced.types';
+import { AIContextManager } from './context/context.manager';
+import { TokenTracker } from './tracking/token.tracker';
+import { CacheService } from '@hazeljs/cache';
+/**
+ * Enhanced AI Service
+ * Production-ready AI service with provider management, caching, and rate limiting
+ */
+export declare class AIEnhancedService {
+    private providers;
+    private defaultProvider;
+    private contextManager?;
+    private tokenTracker;
+    private cacheService?;
+    private retryAttempts;
+    private retryDelay;
+    constructor(tokenTracker?: TokenTracker, cacheService?: CacheService);
+    /**
+     * Initialize AI providers
+     */
+    private initializeProviders;
+    /**
+     * Register a custom provider
+     */
+    registerProvider(provider: IAIProvider): void;
+    /**
+     * Set default provider
+     */
+    setDefaultProvider(provider: AIProvider): void;
+    /**
+     * Create a context manager for conversation
+     */
+    createContext(maxTokens?: number): AIContextManager;
+    /**
+     * Get current context manager
+     */
+    getContext(): AIContextManager | undefined;
+    /**
+     * Generate completion with retry logic and caching
+     */
+    complete(request: AICompletionRequest, config?: {
+        provider?: AIProvider;
+        userId?: string;
+        cacheKey?: string;
+        cacheTTL?: number;
+    }): Promise<AICompletionResponse>;
+    /**
+     * Generate streaming completion
+     */
+    streamComplete(request: AICompletionRequest, config?: {
+        provider?: AIProvider;
+        userId?: string;
+    }): AsyncGenerator<AIStreamChunk>;
+    /**
+     * Generate embeddings
+     */
+    embed(request: AIEmbeddingRequest, config?: {
+        provider?: AIProvider;
+        userId?: string;
+        cacheKey?: string;
+        cacheTTL?: number;
+    }): Promise<AIEmbeddingResponse>;
+    /**
+     * Check if a provider is available
+     */
+    isProviderAvailable(provider: AIProvider): Promise<boolean>;
+    /**
+     * Get list of available providers
+     */
+    getAvailableProviders(): AIProvider[];
+    /**
+     * Get token usage statistics
+     */
+    getTokenStats(userId?: string, days?: number): unknown;
+    /**
+     * Configure model settings
+     */
+    configureModel(config: AIModelConfig): void;
+    /**
+     * Get provider instance
+     */
+    private getProvider;
+    /**
+     * Execute function with retry logic
+     */
+    private executeWithRetry;
+    /**
+     * Generate cache key for completion request
+     */
+    private generateCacheKey;
+    /**
+     * Generate cache key for embedding request
+     */
+    private generateEmbeddingCacheKey;
+    /**
+     * Simple string hash function
+     */
+    private hashString;
+    /**
+     * Estimate tokens for a request (rough estimation)
+     */
+    private estimateRequestTokens;
+    /**
+     * Set retry configuration
+     */
+    setRetryConfig(attempts: number, delay: number): void;
+}
+//# sourceMappingURL=ai-enhanced.service.d.ts.map

package/dist/ai-enhanced.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-enhanced.service.d.ts","sourceRoot":"","sources":["../src/ai-enhanced.service.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,UAAU,EACV,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,aAAa,EACd,MAAM,qBAAqB,CAAC;AAO7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C;;;GAGG;AACH,qBACa,iBAAiB;IAC5B,OAAO,CAAC,SAAS,CAA2C;IAC5D,OAAO,CAAC,eAAe,CAAwB;IAC/C,OAAO,CAAC,cAAc,CAAC,CAAmB;IAC1C,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,YAAY,CAAC,CAAe;IACpC,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,UAAU,CAAgB;gBAEtB,YAAY,CAAC,EAAE,YAAY,EAAE,YAAY,CAAC,EAAE,YAAY;IAOpE;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA6C3B;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI;IAK7C;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI;IAQ9C;;OAEG;IACH,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,gBAAgB;IAKnD;;OAEG;IACH,UAAU,IAAI,gBAAgB,GAAG,SAAS;IAI1C;;OAEG;IACG,QAAQ,CACZ,OAAO,EAAE,mBAAmB,EAC5B,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE,UAAU,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GACA,OAAO,CAAC,oBAAoB,CAAC;IAgDhC;;OAEG;IACI,cAAc,CACnB,OAAO,EAAE,mBAAmB,EAC5B,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE,UAAU,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GACA,cAAc,CAAC,aAAa,CAAC;IAmChC;;OAEG;IACG,KAAK,CACT,OAAO,EAAE,kBAAkB,EAC3B,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE,UAAU,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GACA,OAAO,CAAC,mBAAmB,CAAC;IAwC/B;;OAEG;IACG,mBAAmB,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAQjE;;OAEG;IACH,qBAAqB,IAAI,UAAU,EAAE;IAIrC;;OAEG;IACH,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAOtD;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAU3C;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;OAEG;YACW,gBAAgB;IAoB9B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAQjC;;OAEG;IACH,OAAO,CAAC,UAAU;IAUlB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAe7B;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CAKtD"}