genai-lite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Luigi Acerbi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# genai-lite
+
+A lightweight, portable Node.js/TypeScript library providing a unified interface for interacting with multiple Generative AI providers (OpenAI, Anthropic, Google Gemini, Mistral, and more).
+
+## Features
+
+- 🔌 **Unified API** - Single interface for multiple AI providers
+- 🔐 **Flexible API Key Management** - Bring your own key storage solution
+- 📦 **Zero Electron Dependencies** - Works in any Node.js environment
+- 🎯 **TypeScript First** - Full type safety and IntelliSense support
+- ⚡ **Lightweight** - Minimal dependencies, focused functionality
+- 🛡️ **Provider Normalization** - Consistent responses across different AI APIs
+
+## Installation
+
+```bash
+npm install genai-lite
+```
+
+## Quick Start
+
+```typescript
+import { LLMService, fromEnvironment } from 'genai-lite';
+
+// Create service with environment variable API key provider
+const llmService = new LLMService(fromEnvironment);
+
+// Send a message to OpenAI
+const response = await llmService.sendMessage({
+  providerId: 'openai',
+  modelId: 'gpt-4.1-mini',
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'Hello, how are you?' }
+  ]
+});
+
+if (response.object === 'chat.completion') {
+  console.log(response.choices[0].message.content);
+} else {
+  console.error('Error:', response.error.message);
+}
+```
+
+## API Key Management
+
+genai-lite uses a flexible API key provider pattern. You can use the built-in environment variable provider or create your own:
+
+### Environment Variables (Built-in)
+
+```typescript
+import { fromEnvironment } from 'genai-lite';
+
+// Expects environment variables like:
+// OPENAI_API_KEY=sk-...
+// ANTHROPIC_API_KEY=sk-ant-...
+// GEMINI_API_KEY=...
+
+const llmService = new LLMService(fromEnvironment);
+```
+
+### Custom API Key Provider
+
+```typescript
+import { ApiKeyProvider, LLMService } from 'genai-lite';
+
+// Create your own provider
+const myKeyProvider: ApiKeyProvider = async (providerId: string) => {
+  // Fetch from your secure storage, vault, etc.
+  const key = await mySecureStorage.getKey(providerId);
+  return key || null;
+};
+
+const llmService = new LLMService(myKeyProvider);
+```
+
+## Supported Providers & Models
+
+**Note:** Model IDs include version dates for precise model selection. Always use the exact model ID as shown below.
+
+### Anthropic (Claude)
+- **Claude 4** (Latest generation):
+  - `claude-sonnet-4-20250514` - Balanced performance model
+  - `claude-opus-4-20250514` - Most powerful for complex tasks
+- **Claude 3.7**: `claude-3-7-sonnet-20250219` - Advanced reasoning
+- **Claude 3.5**:
+  - `claude-3-5-sonnet-20241022` - Best balance of speed and intelligence
+  - `claude-3-5-haiku-20241022` - Fast and cost-effective
+
+### Google Gemini
+- **Gemini 2.5** (Latest generation):
+  - `gemini-2.5-pro` - Most advanced multimodal capabilities
+  - `gemini-2.5-flash` - Fast with large context window
+  - `gemini-2.5-flash-lite-preview-06-17` - Most cost-effective
+- **Gemini 2.0**:
+  - `gemini-2.0-flash` - High performance multimodal
+  - `gemini-2.0-flash-lite` - Lightweight version
+
+### OpenAI
+- **o4 series**: `o4-mini` - Advanced reasoning model
+- **GPT-4.1 series**:
+  - `gpt-4.1` - Latest GPT-4 with enhanced capabilities
+  - `gpt-4.1-mini` - Cost-effective for most tasks
+  - `gpt-4.1-nano` - Ultra-efficient version
+
+### Mistral
+> **Note:** The official Mistral adapter is under development. Requests made to Mistral models will currently be handled by a mock adapter for API compatibility testing.
+
+- `codestral-2501` - Specialized for code generation
+- `devstral-small-2505` - Compact development-focused model
+
+## Advanced Usage
+
+### Custom Settings
+
+```typescript
+const response = await llmService.sendMessage({
+  providerId: 'anthropic',
+  modelId: 'claude-3-5-haiku-20241022',
+  messages: [{ role: 'user', content: 'Write a haiku' }],
+  settings: {
+    temperature: 0.7,
+    maxTokens: 100,
+    topP: 0.9,
+    stopSequences: ['\n\n']
+  }
+});
+```
+
+### Provider Information
+
+```typescript
+// Get list of supported providers
+const providers = await llmService.getProviders();
+
+// Get models for a specific provider
+const models = await llmService.getModels('anthropic');
+```
+
+### Error Handling
+
+```typescript
+const response = await llmService.sendMessage({
+  providerId: 'openai',
+  modelId: 'gpt-4.1-mini',
+  messages: [{ role: 'user', content: 'Hello' }]
+});
+
+if (response.object === 'error') {
+  switch (response.error.type) {
+    case 'authentication_error':
+      console.error('Invalid API key');
+      break;
+    case 'rate_limit_error':
+      console.error('Rate limit exceeded');
+      break;
+    case 'validation_error':
+      console.error('Invalid request:', response.error.message);
+      break;
+    default:
+      console.error('Error:', response.error.message);
+  }
+}
+```
+
+## Using with Electron
+
+`genai-lite` is designed to work seamlessly within an Electron application's main process, especially when paired with a secure storage solution like `genai-key-storage-lite`.
+
+This is the recommended pattern for both new Electron apps and for migrating from older, integrated versions.
+
+### Example with `genai-key-storage-lite`
+
+Here’s how to create a custom `ApiKeyProvider` that uses `genai-key-storage-lite` to securely retrieve API keys.
+
+```typescript
+// In your Electron app's main process (e.g., main.ts)
+import { app } from 'electron';
+import { ApiKeyServiceMain } from 'genai-key-storage-lite';
+import { LLMService, type ApiKeyProvider } from 'genai-lite';
+
+// 1. Initialize Electron's secure key storage service
+const apiKeyService = new ApiKeyServiceMain(app.getPath("userData"));
+
+// 2. Create a custom ApiKeyProvider that uses the secure storage
+const electronKeyProvider: ApiKeyProvider = async (providerId) => {
+  try {
+    // Use withDecryptedKey to securely access the key only when needed.
+    // The key is passed to the callback and its result is returned.
+    return await apiKeyService.withDecryptedKey(providerId, async (key) => key);
+  } catch {
+    // If key is not found or decryption fails, return null.
+    // LLMService will handle this as an authentication error.
+    return null;
+  }
+};
+
+// 3. Initialize the genai-lite service with our custom provider
+const llmService = new LLMService(electronKeyProvider);
+
+// Now you can use llmService anywhere in your main process.
+```
+
+## TypeScript Support
+
+genai-lite is written in TypeScript and provides comprehensive type definitions:
+
+```typescript
+import type { 
+  LLMChatRequest,
+  LLMResponse,
+  LLMFailureResponse,
+  LLMSettings,
+  ApiKeyProvider
+} from 'genai-lite';
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+### Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests (when available)
+npm test
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Acknowledgments
+
+Originally developed as part of the Athanor project, genai-lite has been extracted and made standalone to benefit the wider developer community.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { ApiKeyProvider } from "./types";
+export { LLMService } from "./llm/LLMService";
+export * from "./llm/types";
+export * from "./llm/clients/types";
+export { fromEnvironment } from "./providers/fromEnvironment";

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromEnvironment = exports.LLMService = void 0;
+// --- LLM Service ---
+var LLMService_1 = require("./llm/LLMService");
+Object.defineProperty(exports, "LLMService", { enumerable: true, get: function () { return LLMService_1.LLMService; } });
+// Export all core request/response/config types from the LLM module
+__exportStar(require("./llm/types"), exports);
+// Export all client adapter types
+__exportStar(require("./llm/clients/types"), exports);
+// --- API Key Providers ---
+var fromEnvironment_1 = require("./providers/fromEnvironment");
+Object.defineProperty(exports, "fromEnvironment", { enumerable: true, get: function () { return fromEnvironment_1.fromEnvironment; } });

package/dist/llm/LLMService.d.ts

@@ -0,0 +1,86 @@
+import type { ApiKeyProvider } from '../types';
+import type { LLMChatRequest, LLMResponse, LLMFailureResponse, ProviderInfo, ModelInfo, ApiProviderId } from "./types";
+import type { ILLMClientAdapter } from "./clients/types";
+/**
+ * Main process service for LLM operations
+ *
+ * This service:
+ * - Manages LLM provider client adapters
+ * - Integrates with ApiKeyServiceMain for secure API key access
+ * - Validates requests and applies default settings
+ * - Routes requests to appropriate provider adapters
+ * - Handles errors and provides standardized responses
+ */
+export declare class LLMService {
+    private getApiKey;
+    private clientAdapters;
+    private mockClientAdapter;
+    constructor(getApiKey: ApiKeyProvider);
+    /**
+     * Gets list of supported LLM providers
+     *
+     * @returns Promise resolving to array of provider information
+     */
+    getProviders(): Promise<ProviderInfo[]>;
+    /**
+     * Gets list of supported models for a specific provider
+     *
+     * @param providerId - The provider ID to get models for
+     * @returns Promise resolving to array of model information
+     */
+    getModels(providerId: ApiProviderId): Promise<ModelInfo[]>;
+    /**
+     * Sends a chat message to an LLM provider
+     *
+     * @param request - The LLM chat request
+     * @returns Promise resolving to either success or failure response
+     */
+    sendMessage(request: LLMChatRequest): Promise<LLMResponse | LLMFailureResponse>;
+    /**
+     * Validates basic LLM request structure
+     *
+     * @param request - The request to validate
+     * @returns LLMFailureResponse if validation fails, null if valid
+     */
+    private validateRequestStructure;
+    /**
+     * Merges request settings with model-specific and global defaults
+     *
+     * @param modelId - The model ID to get defaults for
+     * @param providerId - The provider ID to get defaults for
+     * @param requestSettings - Settings from the request
+     * @returns Complete settings object with all required fields
+     */
+    private mergeSettingsForModel;
+    /**
+     * Gets the appropriate client adapter for a provider
+     *
+     * @param providerId - The provider ID
+     * @returns The client adapter to use
+     */
+    private getClientAdapter;
+    /**
+     * Registers a client adapter for a specific provider
+     *
+     * @param providerId - The provider ID
+     * @param adapter - The client adapter implementation
+     */
+    registerClientAdapter(providerId: ApiProviderId, adapter: ILLMClientAdapter): void;
+    /**
+     * Gets information about registered adapters
+     *
+     * @returns Map of provider IDs to adapter info
+     */
+    getRegisteredAdapters(): Map<ApiProviderId, any>;
+    /**
+     * Gets a summary of available providers and their adapter status
+     *
+     * @returns Summary of provider availability
+     */
+    getProviderSummary(): {
+        totalProviders: number;
+        providersWithAdapters: number;
+        availableProviders: string[];
+        unavailableProviders: string[];
+    };
+}