@hazeljs/ai 0.2.0-alpha.1

package/dist/providers/cohere.provider.js

@@ -0,0 +1,230 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CohereProvider = void 0;
+const core_1 = __importDefault(require("@hazeljs/core"));
+const cohere_ai_1 = require("cohere-ai");
+/**
+ * Cohere AI Provider
+ *
+ * Production-ready implementation using Cohere AI SDK.
+ *
+ * Setup:
+ * 1. Install the SDK: `npm install cohere-ai`
+ * 2. Set COHERE_API_KEY environment variable
+ * 3. Use the provider in your application
+ *
+ * Supported models:
+ * - command-r-plus: Most powerful model for complex tasks
+ * - command-r: Balanced performance and cost
+ * - command: Standard text generation
+ * - command-light: Fast, cost-effective model
+ * - embed-english-v3.0: English text embeddings
+ * - embed-multilingual-v3.0: Multilingual embeddings
+ * - rerank-english-v3.0: Document reranking
+ */
+class CohereProvider {
+    constructor(apiKey, endpoint) {
+        this.name = 'cohere';
+        this.apiKey = apiKey || process.env.COHERE_API_KEY || '';
+        this.endpoint = endpoint || 'https://api.cohere.ai/v1';
+        if (!this.apiKey) {
+            core_1.default.warn('Cohere API key not provided. Set COHERE_API_KEY environment variable.');
+        }
+        this.cohere = new cohere_ai_1.CohereClient({ token: this.apiKey });
+        core_1.default.info('Cohere provider initialized');
+    }
+    /**
+     * Generate completion
+     */
+    async complete(request) {
+        const modelName = request.model || 'command';
+        core_1.default.debug(`Cohere completion request for model: ${modelName}`);
+        try {
+            // Convert messages to prompt format
+            const prompt = request.messages.map((m) => `${m.role}: ${m.content}`).join('\n\n');
+            // Generate completion
+            const response = await this.cohere.generate({
+                model: modelName,
+                prompt,
+                temperature: request.temperature,
+                maxTokens: request.maxTokens,
+                p: request.topP,
+            });
+            return {
+                id: response.id || `cohere-${Date.now()}`,
+                content: response.generations[0].text,
+                role: 'assistant',
+                model: modelName,
+                usage: {
+                    promptTokens: response.meta?.billedUnits?.inputTokens || 0,
+                    completionTokens: response.meta?.billedUnits?.outputTokens || 0,
+                    totalTokens: (response.meta?.billedUnits?.inputTokens || 0) +
+                        (response.meta?.billedUnits?.outputTokens || 0),
+                },
+                finishReason: 'COMPLETE',
+            };
+        }
+        catch (error) {
+            core_1.default.error('Cohere completion error:', error);
+            throw new Error(`Cohere API error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Generate streaming completion
+     */
+    async *streamComplete(request) {
+        const modelName = request.model || 'command';
+        core_1.default.debug('Cohere streaming completion started');
+        try {
+            // Convert messages to prompt format
+            const prompt = request.messages.map((m) => `${m.role}: ${m.content}`).join('\n\n');
+            // Generate streaming completion
+            const stream = await this.cohere.generateStream({
+                model: modelName,
+                prompt,
+                temperature: request.temperature,
+                maxTokens: request.maxTokens,
+                p: request.topP,
+            });
+            let fullContent = '';
+            const streamId = `cohere-stream-${Date.now()}`;
+            for await (const chunk of stream) {
+                if (chunk.eventType === 'text-generation') {
+                    const text = chunk.text || '';
+                    fullContent += text;
+                    yield {
+                        id: streamId,
+                        content: fullContent,
+                        delta: text,
+                        done: false,
+                    };
+                }
+                else if (chunk.eventType === 'stream-end') {
+                    const response = chunk;
+                    yield {
+                        id: streamId,
+                        content: fullContent,
+                        delta: '',
+                        done: true,
+                        usage: response.response?.meta?.billedUnits
+                            ? {
+                                promptTokens: response.response.meta.billedUnits.inputTokens || 0,
+                                completionTokens: response.response.meta.billedUnits.outputTokens || 0,
+                                totalTokens: (response.response.meta.billedUnits.inputTokens || 0) +
+                                    (response.response.meta.billedUnits.outputTokens || 0),
+                            }
+                            : undefined,
+                    };
+                }
+            }
+            core_1.default.debug('Cohere streaming completed');
+        }
+        catch (error) {
+            core_1.default.error('Cohere streaming error:', error);
+            throw new Error(`Cohere streaming error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Generate embeddings
+     */
+    async embed(request) {
+        const modelName = request.model || 'embed-english-v3.0';
+        core_1.default.debug(`Cohere embedding request for model: ${modelName}`);
+        try {
+            const inputs = Array.isArray(request.input) ? request.input : [request.input];
+            // Generate embeddings
+            const response = await this.cohere.embed({
+                texts: inputs,
+                model: modelName,
+                inputType: 'search_document',
+            });
+            // Estimate token usage (Cohere doesn't provide exact counts for embeddings)
+            const estimatedTokens = inputs.reduce((sum, text) => sum + Math.ceil(text.length / 4), 0);
+            // Handle different response formats
+            const embeddings = Array.isArray(response.embeddings)
+                ? response.embeddings
+                : response.embeddings.float || [];
+            return {
+                embeddings,
+                model: modelName,
+                usage: {
+                    promptTokens: estimatedTokens,
+                    totalTokens: estimatedTokens,
+                },
+            };
+        }
+        catch (error) {
+            core_1.default.error('Cohere embedding error:', error);
+            throw new Error(`Cohere embedding error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Check if provider is available
+     */
+    async isAvailable() {
+        if (!this.apiKey) {
+            core_1.default.warn('Cohere API key not configured');
+            return false;
+        }
+        try {
+            // Test with a minimal request
+            await this.cohere.generate({
+                model: 'command-light',
+                prompt: 'test',
+                maxTokens: 10,
+            });
+            return true;
+        }
+        catch (error) {
+            core_1.default.error('Cohere availability check failed:', error);
+            return false;
+        }
+    }
+    /**
+     * Get supported models
+     */
+    getSupportedModels() {
+        return [
+            'command-r-plus',
+            'command-r',
+            'command',
+            'command-light',
+            'command-nightly',
+            'embed-english-v3.0',
+            'embed-multilingual-v3.0',
+            'embed-english-light-v3.0',
+            'embed-multilingual-light-v3.0',
+            'rerank-english-v3.0',
+            'rerank-multilingual-v3.0',
+        ];
+    }
+    /**
+     * Rerank documents (Cohere-specific feature)
+     * Useful for RAG applications to improve retrieval quality
+     */
+    async rerank(query, documents, topN, model) {
+        const modelName = model || 'rerank-english-v3.0';
+        core_1.default.debug(`Cohere rerank request for model: ${modelName}`);
+        try {
+            const response = await this.cohere.rerank({
+                query,
+                documents,
+                topN,
+                model: modelName,
+            });
+            return response.results.map((r) => ({
+                index: r.index,
+                score: r.relevanceScore,
+                document: documents[r.index],
+            }));
+        }
+        catch (error) {
+            core_1.default.error('Cohere rerank error:', error);
+            throw new Error(`Cohere rerank error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+}
+exports.CohereProvider = CohereProvider;

package/dist/providers/cohere.provider.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cohere.provider.test.d.ts.map

package/dist/providers/cohere.provider.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cohere.provider.test.d.ts","sourceRoot":"","sources":["../../src/providers/cohere.provider.test.ts"],"names":[],"mappings":""}

package/dist/providers/cohere.provider.test.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+jest.mock('@hazeljs/core', () => ({
+    __esModule: true,
+    default: { info: jest.fn(), debug: jest.fn(), warn: jest.fn(), error: jest.fn() },
+}));
+const mockGenerate = jest.fn();
+const mockGenerateStream = jest.fn();
+const mockEmbed = jest.fn();
+const mockRerank = jest.fn();
+jest.mock('cohere-ai', () => ({
+    CohereClient: jest.fn().mockImplementation(() => ({
+        generate: mockGenerate,
+        generateStream: mockGenerateStream,
+        embed: mockEmbed,
+        rerank: mockRerank,
+    })),
+}));
+const cohere_provider_1 = require("./cohere.provider");
+const BASE_REQUEST = {
+    messages: [{ role: 'user', content: 'Hello Cohere' }],
+    model: 'command',
+};
+const MOCK_GENERATE_RESPONSE = {
+    id: 'cohere-123',
+    generations: [{ text: 'Cohere response' }],
+    meta: { billedUnits: { inputTokens: 10, outputTokens: 20 } },
+};
+describe('CohereProvider', () => {
+    let provider;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        provider = new cohere_provider_1.CohereProvider('test-api-key');
+    });
+    describe('constructor', () => {
+        it('sets name to cohere', () => {
+            expect(provider.name).toBe('cohere');
+        });
+        it('warns when no API key', () => {
+            new cohere_provider_1.CohereProvider(); // Should not throw
+        });
+        it('uses COHERE_API_KEY env var', () => {
+            process.env.COHERE_API_KEY = 'env-key';
+            const p = new cohere_provider_1.CohereProvider();
+            expect(p).toBeDefined();
+            delete process.env.COHERE_API_KEY;
+        });
+    });
+    describe('getSupportedModels()', () => {
+        it('returns list of cohere models', () => {
+            const models = provider.getSupportedModels();
+            expect(models).toContain('command');
+            expect(models.length).toBeGreaterThan(0);
+        });
+    });
+    describe('complete()', () => {
+        it('returns a completion response', async () => {
+            mockGenerate.mockResolvedValue(MOCK_GENERATE_RESPONSE);
+            const result = await provider.complete(BASE_REQUEST);
+            expect(result.content).toBe('Cohere response');
+            expect(result.role).toBe('assistant');
+            expect(result.usage?.promptTokens).toBe(10);
+            expect(result.usage?.completionTokens).toBe(20);
+            expect(result.usage?.totalTokens).toBe(30);
+            expect(result.finishReason).toBe('COMPLETE');
+        });
+        it('uses default model when not specified', async () => {
+            mockGenerate.mockResolvedValue(MOCK_GENERATE_RESPONSE);
+            await provider.complete({ messages: [{ role: 'user', content: 'hi' }] });
+            expect(mockGenerate).toHaveBeenCalledWith(expect.objectContaining({ model: 'command' }));
+        });
+        it('passes temperature and maxTokens to API', async () => {
+            mockGenerate.mockResolvedValue(MOCK_GENERATE_RESPONSE);
+            await provider.complete({ ...BASE_REQUEST, temperature: 0.5, maxTokens: 200, topP: 0.9 });
+            expect(mockGenerate).toHaveBeenCalledWith(expect.objectContaining({ temperature: 0.5, maxTokens: 200, p: 0.9 }));
+        });
+        it('handles missing meta/billedUnits gracefully', async () => {
+            mockGenerate.mockResolvedValue({
+                generations: [{ text: 'ok' }],
+                meta: undefined,
+            });
+            const result = await provider.complete(BASE_REQUEST);
+            expect(result.usage?.totalTokens).toBe(0);
+        });
+        it('uses generated id when response has one', async () => {
+            mockGenerate.mockResolvedValue(MOCK_GENERATE_RESPONSE);
+            const result = await provider.complete(BASE_REQUEST);
+            expect(result.id).toBe('cohere-123');
+        });
+        it('generates a fallback id when response has no id', async () => {
+            mockGenerate.mockResolvedValue({ ...MOCK_GENERATE_RESPONSE, id: undefined });
+            const result = await provider.complete(BASE_REQUEST);
+            expect(result.id).toMatch(/^cohere-\d+$/);
+        });
+        it('converts messages to prompt format', async () => {
+            mockGenerate.mockResolvedValue(MOCK_GENERATE_RESPONSE);
+            await provider.complete({
+                messages: [
+                    { role: 'user', content: 'User msg' },
+                    { role: 'assistant', content: 'Asst msg' },
+                ],
+            });
+            const callArg = mockGenerate.mock.calls[0][0];
+            expect(callArg.prompt).toContain('user: User msg');
+            expect(callArg.prompt).toContain('assistant: Asst msg');
+        });
+        it('throws wrapped error on API failure', async () => {
+            mockGenerate.mockRejectedValue(new Error('Quota exceeded'));
+            await expect(provider.complete(BASE_REQUEST)).rejects.toThrow('Cohere API error: Quota exceeded');
+        });
+        it('wraps non-Error thrown values', async () => {
+            mockGenerate.mockRejectedValue('string error');
+            await expect(provider.complete(BASE_REQUEST)).rejects.toThrow('Cohere API error: Unknown error');
+        });
+    });
+    describe('streamComplete()', () => {
+        it('yields text-generation chunks', async () => {
+            async function* mockStream() {
+                yield { eventType: 'text-generation', text: 'Hello ' };
+                yield { eventType: 'text-generation', text: 'world' };
+                yield {
+                    eventType: 'stream-end',
+                    response: {
+                        meta: { billedUnits: { inputTokens: 5, outputTokens: 10 } },
+                    },
+                };
+            }
+            mockGenerateStream.mockReturnValue(mockStream());
+            const results = [];
+            for await (const chunk of provider.streamComplete(BASE_REQUEST)) {
+                results.push(chunk);
+            }
+            // 2 text chunks + 1 stream-end
+            expect(results.length).toBe(3);
+        });
+        it('yields done=true chunk on stream-end with usage', async () => {
+            async function* mockStream() {
+                yield {
+                    eventType: 'stream-end',
+                    response: { meta: { billedUnits: { inputTokens: 5, outputTokens: 3 } } },
+                };
+            }
+            mockGenerateStream.mockReturnValue(mockStream());
+            const results = [];
+            for await (const chunk of provider.streamComplete(BASE_REQUEST)) {
+                results.push(chunk);
+            }
+            const last = results[results.length - 1];
+            expect(last.done).toBe(true);
+            expect(last.usage).toBeDefined();
+        });
+        it('yields stream-end with undefined usage when no billedUnits', async () => {
+            async function* mockStream() {
+                yield { eventType: 'stream-end', response: { meta: {} } };
+            }
+            mockGenerateStream.mockReturnValue(mockStream());
+            const results = [];
+            for await (const chunk of provider.streamComplete(BASE_REQUEST)) {
+                results.push(chunk);
+            }
+            expect(results[0].usage).toBeUndefined();
+        });
+        it('ignores unknown event types', async () => {
+            async function* mockStream() {
+                yield { eventType: 'unknown-event' };
+                yield { eventType: 'stream-end', response: {} };
+            }
+            mockGenerateStream.mockReturnValue(mockStream());
+            const results = [];
+            for await (const chunk of provider.streamComplete(BASE_REQUEST)) {
+                results.push(chunk);
+            }
+            expect(results.length).toBe(1); // only stream-end
+        });
+        it('throws wrapped error on streaming failure', async () => {
+            mockGenerateStream.mockImplementation(async function* () {
+                throw new Error('Stream crashed');
+                yield { eventType: 'stream-end' };
+            });
+            await expect(async () => {
+                for await (const _chunk of provider.streamComplete(BASE_REQUEST)) {
+                    // consume
+                }
+            }).rejects.toThrow('Cohere streaming error: Stream crashed');
+        });
+    });
+    describe('embed()', () => {
+        it('returns embeddings for string array', async () => {
+            mockEmbed.mockResolvedValue({
+                embeddings: [
+                    [0.1, 0.2],
+                    [0.3, 0.4],
+                ],
+            });
+            const result = await provider.embed({ input: ['first', 'second'] });
+            expect(result.embeddings).toHaveLength(2);
+            expect(result.model).toBe('embed-english-v3.0');
+        });
+        it('handles single string input', async () => {
+            mockEmbed.mockResolvedValue({ embeddings: [[0.5, 0.6]] });
+            const result = await provider.embed({ input: 'single' });
+            expect(result.embeddings).toHaveLength(1);
+        });
+        it('handles { float: number[][] } response format', async () => {
+            mockEmbed.mockResolvedValue({ embeddings: { float: [[0.7, 0.8]] } });
+            const result = await provider.embed({ input: 'test' });
+            expect(result.embeddings).toEqual([[0.7, 0.8]]);
+        });
+        it('uses custom model when specified', async () => {
+            mockEmbed.mockResolvedValue({ embeddings: [[0.1]] });
+            const result = await provider.embed({ input: 'test', model: 'embed-multilingual-v3.0' });
+            expect(result.model).toBe('embed-multilingual-v3.0');
+        });
+        it('estimates token usage from input length', async () => {
+            mockEmbed.mockResolvedValue({ embeddings: [[0.1]] });
+            const result = await provider.embed({ input: 'hello world' }); // 11 chars → ~3 tokens
+            expect(result.usage?.promptTokens).toBeGreaterThan(0);
+        });
+        it('throws wrapped error on failure', async () => {
+            mockEmbed.mockRejectedValue(new Error('Embedding failed'));
+            await expect(provider.embed({ input: 'test' })).rejects.toThrow('Cohere embedding error: Embedding failed');
+        });
+    });
+    describe('isAvailable()', () => {
+        it('returns false when no API key', async () => {
+            const p = new cohere_provider_1.CohereProvider('');
+            expect(await p.isAvailable()).toBe(false);
+        });
+        it('returns true when API responds', async () => {
+            mockGenerate.mockResolvedValue(MOCK_GENERATE_RESPONSE);
+            expect(await provider.isAvailable()).toBe(true);
+        });
+        it('returns false on API error', async () => {
+            mockGenerate.mockRejectedValue(new Error('Unauthorized'));
+            expect(await provider.isAvailable()).toBe(false);
+        });
+    });
+    describe('rerank()', () => {
+        it('returns ranked documents', async () => {
+            mockRerank.mockResolvedValue({
+                results: [
+                    { index: 1, relevanceScore: 0.9 },
+                    { index: 0, relevanceScore: 0.7 },
+                ],
+            });
+            const result = await provider.rerank('query', ['doc0', 'doc1'], 2);
+            expect(result).toHaveLength(2);
+            expect(result[0].score).toBe(0.9);
+            expect(result[0].index).toBe(1);
+            expect(result[0].document).toBe('doc1');
+        });
+        it('uses default rerank model', async () => {
+            mockRerank.mockResolvedValue({ results: [] });
+            await provider.rerank('query', ['doc1']);
+            expect(mockRerank).toHaveBeenCalledWith(expect.objectContaining({ model: 'rerank-english-v3.0' }));
+        });
+        it('uses custom model when specified', async () => {
+            mockRerank.mockResolvedValue({ results: [] });
+            await provider.rerank('query', ['doc'], undefined, 'rerank-multilingual-v3.0');
+            expect(mockRerank).toHaveBeenCalledWith(expect.objectContaining({ model: 'rerank-multilingual-v3.0' }));
+        });
+        it('throws wrapped error on rerank failure', async () => {
+            mockRerank.mockRejectedValue(new Error('Rerank failed'));
+            await expect(provider.rerank('q', ['d'])).rejects.toThrow('Cohere rerank error: Rerank failed');
+        });
+    });
+});

package/dist/providers/gemini.provider.d.ts

@@ -0,0 +1,45 @@
+import { IAIProvider, AIProvider, AICompletionRequest, AICompletionResponse, AIStreamChunk, AIEmbeddingRequest, AIEmbeddingResponse } from '../ai-enhanced.types';
+/**
+ * Google Gemini AI Provider
+ *
+ * Production-ready implementation using Google Generative AI SDK.
+ *
+ * Setup:
+ * 1. Install the SDK: `npm install @google/generative-ai`
+ * 2. Set GEMINI_API_KEY environment variable
+ * 3. Use the provider in your application
+ *
+ * Supported models:
+ * - gemini-pro: Text generation
+ * - gemini-pro-vision: Multimodal (text + images)
+ * - gemini-1.5-pro: Latest model with extended context
+ * - text-embedding-004: Text embeddings
+ */
+export declare class GeminiProvider implements IAIProvider {
+    readonly name: AIProvider;
+    private apiKey;
+    private genAI;
+    private endpoint;
+    constructor(apiKey?: string, endpoint?: string);
+    /**
+     * Generate completion
+     */
+    complete(request: AICompletionRequest): Promise<AICompletionResponse>;
+    /**
+     * Generate streaming completion
+     */
+    streamComplete(request: AICompletionRequest): AsyncGenerator<AIStreamChunk>;
+    /**
+     * Generate embeddings
+     */
+    embed(request: AIEmbeddingRequest): Promise<AIEmbeddingResponse>;
+    /**
+     * Check if provider is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get supported models
+     */
+    getSupportedModels(): string[];
+}
+//# sourceMappingURL=gemini.provider.d.ts.map

package/dist/providers/gemini.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.provider.d.ts","sourceRoot":"","sources":["../../src/providers/gemini.provider.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,UAAU,EACV,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAI9B;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAe,YAAW,WAAW;IAChD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAY;IACrC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;IAY9C;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAwC3E;;OAEG;IACI,cAAc,CAAC,OAAO,EAAE,mBAAmB,GAAG,cAAc,CAAC,aAAa,CAAC;IAoDlF;;OAEG;IACG,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAmCtE;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAiBrC;;OAEG;IACH,kBAAkB,IAAI,MAAM,EAAE;CAS/B"}