genai-lite 0.1.1 → 0.1.4

package/README.md

@@ -10,6 +10,8 @@ A lightweight, portable Node.js/TypeScript library providing a unified interface
 - 🎯 **TypeScript First** - Full type safety and IntelliSense support
 - ⚡ **Lightweight** - Minimal dependencies, focused functionality
 - 🛡️ **Provider Normalization** - Consistent responses across different AI APIs
+- 🎨 **Configurable Model Presets** - Built-in presets with full customization options
+- 🎭 **Template Engine** - Sophisticated templating with conditionals and variable substitution
 
 ## Installation
 
@@ -135,6 +137,80 @@ const providers = await llmService.getProviders();
 
 // Get models for a specific provider
 const models = await llmService.getModels('anthropic');
+
+// Get configured model presets
+const presets = llmService.getPresets();
+```
+
+### Model Presets
+
+genai-lite includes a built-in set of model presets for common use cases. You can use these defaults, extend them with your own, or replace them entirely.
+
+#### Using Default Presets
+
+```typescript
+const llmService = new LLMService(fromEnvironment);
+
+// Get all default presets
+const presets = llmService.getPresets();
+// Returns presets like:
+// - anthropic-claude-3-5-sonnet-20241022-default
+// - openai-gpt-4.1-default
+// - google-gemini-2.5-pro
+// ... and more
+```
+
+#### Extending Default Presets
+
+```typescript
+import { LLMService, fromEnvironment, ModelPreset } from 'genai-lite';
+
+const customPresets: ModelPreset[] = [
+  {
+    id: 'my-creative-preset',
+    displayName: 'Creative Writing Assistant',
+    providerId: 'openai',
+    modelId: 'gpt-4.1',
+    settings: {
+      temperature: 0.9,
+      maxTokens: 2000,
+      topP: 0.95
+    }
+  }
+];
+
+const llmService = new LLMService(fromEnvironment, {
+  presets: customPresets,
+  presetMode: 'extend' // Default behavior - adds to existing presets
+});
+```
+
+#### Replacing Default Presets
+
+For applications that need full control over available presets:
+
+```typescript
+const applicationPresets: ModelPreset[] = [
+  {
+    id: 'app-gpt4-default',
+    displayName: 'GPT-4 Standard',
+    providerId: 'openai',
+    modelId: 'gpt-4.1',
+    settings: { temperature: 0.7 }
+  },
+  {
+    id: 'app-claude-creative',
+    displayName: 'Claude Creative',
+    providerId: 'anthropic',
+    modelId: 'claude-3-5-sonnet-20241022',
+    settings: { temperature: 0.8, maxTokens: 4000 }
+  }
+];
+
+const llmService = new LLMService(fromEnvironment, {
+  presets: applicationPresets,
+  presetMode: 'replace' // Use ONLY these presets, ignore defaults
+});
 ```
 
 ### Error Handling
@@ -211,7 +287,10 @@ import type {
   LLMResponse,
   LLMFailureResponse,
   LLMSettings,
-  ApiKeyProvider
+  ApiKeyProvider,
+  ModelPreset,
+  LLMServiceOptions,
+  PresetMode
 } from 'genai-lite';
 ```
 
@@ -310,6 +389,108 @@ const response = await llm.sendMessage({
 });
 ```
 
+### Template Engine
+
+Generate dynamic prompts and content using the built-in template engine that supports variable substitution and conditional logic:
+
+```typescript
+import { renderTemplate } from 'genai-lite/utils';
+
+// Simple variable substitution
+const greeting = renderTemplate('Hello, {{ name }}!', { name: 'World' });
+// Result: "Hello, World!"
+
+// Conditional rendering with ternary syntax
+const prompt = renderTemplate(
+  'Analyze this {{ language }} code:\n{{ hasContext ? `Context: {{context}}\n` : `` }}```\n{{ code }}\n```',
+  {
+    language: 'TypeScript',
+    hasContext: true,
+    context: 'React component for user authentication',
+    code: 'export const Login = () => { ... }'
+  }
+);
+// Result includes the context line when hasContext is true
+
+// Complex template with multiple conditionals
+const complexTemplate = `
+System: You are a {{ role }} assistant.
+{{ hasExpertise ? `Expertise: {{expertise}}` : `General knowledge assistant` }}
+
+Task: {{ task }}
+{{ hasFiles ? `
+Files to analyze:
+{{ fileList }}` : `` }}
+{{ requiresOutput ? `
+Expected output format:
+{{ outputFormat }}` : `` }}
+`;
+
+const result = renderTemplate(complexTemplate, {
+  role: 'coding',
+  hasExpertise: true,
+  expertise: 'TypeScript, React, Node.js',
+  task: 'Review the code for best practices',
+  hasFiles: true,
+  fileList: '- src/index.ts\n- src/utils.ts',
+  requiresOutput: false
+});
+```
+
+Template syntax supports:
+- **Simple substitution**: `{{ variableName }}`
+- **Ternary conditionals**: `{{ condition ? `true result` : `false result` }}`
+- **Nested variables**: `{{ show ? `Name: {{name}}` : `Anonymous` }}`
+- **Multi-line strings**: Use backticks to preserve formatting
+- **Intelligent newline handling**: Empty results remove trailing newlines
+
+### Example: Building Dynamic LLM Prompts
+
+Combine the template engine with other utilities for powerful prompt generation:
+
+```typescript
+import { LLMService, fromEnvironment } from 'genai-lite';
+import { renderTemplate, countTokens } from 'genai-lite/utils';
+
+const llm = new LLMService(fromEnvironment);
+
+// Define a reusable prompt template
+const codeReviewTemplate = `
+You are an expert {{ language }} developer.
+
+{{ hasGuidelines ? `Follow these coding guidelines:
+{{ guidelines }}
+
+` : `` }}Review the following code:
+\`\`\`{{ language }}
+{{ code }}
+\`\`\`
+
+{{ hasFocus ? `Focus on: {{ focusAreas }}` : `Provide a comprehensive review covering all aspects.` }}
+`;
+
+// Render the prompt with specific values
+const prompt = renderTemplate(codeReviewTemplate, {
+  language: 'TypeScript',
+  hasGuidelines: true,
+  guidelines: '- Use functional components\n- Prefer composition over inheritance',
+  code: sourceCode,
+  hasFocus: true,
+  focusAreas: 'performance optimizations and error handling'
+});
+
+// Check token count before sending
+const tokenCount = countTokens(prompt, 'gpt-4.1-mini');
+console.log(`Prompt uses ${tokenCount} tokens`);
+
+// Send to LLM
+const response = await llm.sendMessage({
+  providerId: 'openai',
+  modelId: 'gpt-4.1-mini',
+  messages: [{ role: 'user', content: prompt }]
+});
+```
+
 ## 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.
@@ -327,6 +508,26 @@ npm run build
 npm test
 ```
 
+### End-to-End Testing
+
+The project includes an end-to-end test suite that makes real API calls to providers. These tests are separate from the main unit test suite and are not run in CI by default.
+
+To run these tests locally, you must first provide API keys as environment variables with the `E2E_` prefix:
+
+```bash
+export E2E_OPENAI_API_KEY="sk-..."
+export E2E_ANTHROPIC_API_KEY="sk-ant-..."
+export E2E_GEMINI_API_KEY="AIza..."
+```
+
+Then, run the E2E test script:
+
+```bash
+npm run test:e2e
+```
+
+The tests will automatically skip any provider for which an API key is not found.
+
 ## License
 
 This project is licensed under the MIT License - see the LICENSE file for details.

package/dist/config/presets.json

@@ -0,0 +1,222 @@
+[
+    {
+        "id": "anthropic-claude-sonnet-4-20250514-default",
+        "displayName": "Anthropic - Claude Sonnet 4",
+        "description": "Default preset for Claude Sonnet 4.",
+        "providerId": "anthropic",
+        "modelId": "claude-sonnet-4-20250514",
+        "settings": {
+            "temperature": 0.3
+        }
+    },
+    {
+        "id": "anthropic-claude-opus-4-20250514-default",
+        "displayName": "Anthropic - Claude Opus 4",
+        "description": "Default preset for Claude Opus 4.",
+        "providerId": "anthropic",
+        "modelId": "claude-opus-4-20250514",
+        "settings": {
+            "temperature": 0.3
+        }
+    },
+    {
+        "id": "anthropic-claude-3-7-sonnet-20250219-default",
+        "displayName": "Anthropic - Claude 3.7 Sonnet",
+        "description": "Default preset for Claude 3.7 Sonnet.",
+        "providerId": "anthropic",
+        "modelId": "claude-3-7-sonnet-20250219",
+        "settings": {
+            "temperature": 0.3
+        }
+    },
+    {
+        "id": "anthropic-claude-3-5-sonnet-20241022-default",
+        "displayName": "Anthropic - Claude 3.5 Sonnet",
+        "description": "Default preset for Claude 3.5 Sonnet.",
+        "providerId": "anthropic",
+        "modelId": "claude-3-5-sonnet-20241022",
+        "settings": {
+            "temperature": 0.3
+        }
+    },
+    {
+        "id": "anthropic-claude-3-5-haiku-20241022-default",
+        "displayName": "Anthropic - Claude 3.5 Haiku",
+        "description": "Default preset for Claude 3.5 Haiku.",
+        "providerId": "anthropic",
+        "modelId": "claude-3-5-haiku-20241022",
+        "settings": {
+            "temperature": 0.3
+        }
+    },
+    {
+        "id": "google-gemini-2.5-pro",
+        "displayName": "Google - Gemini 2.5 Pro",
+        "description": "Default preset for Gemini 2.5 Pro.",
+        "providerId": "gemini",
+        "modelId": "gemini-2.5-pro",
+        "settings": {
+            "temperature": 0.3,
+            "geminiSafetySettings": [
+                { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE" },
+                {
+                    "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+                    "threshold": "BLOCK_NONE"
+                },
+                {
+                    "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
+                    "threshold": "BLOCK_NONE"
+                },
+                { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE" }
+            ]
+        }
+    },
+    {
+        "id": "google-gemini-2.5-flash",
+        "displayName": "Google - Gemini 2.5 Flash",
+        "description": "Default preset for Gemini 2.5 Flash.",
+        "providerId": "gemini",
+        "modelId": "gemini-2.5-flash",
+        "settings": {
+            "temperature": 0.3,
+            "geminiSafetySettings": [
+                { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE" },
+                {
+                    "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+                    "threshold": "BLOCK_NONE"
+                },
+                {
+                    "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
+                    "threshold": "BLOCK_NONE"
+                },
+                { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE" }
+            ]
+        }
+    },
+    {
+        "id": "google-gemini-2.5-flash-lite-preview",
+        "displayName": "Google - Gemini 2.5 Flash-Lite Preview",
+        "description": "Default preset for Gemini 2.5 Flash-Lite.",
+        "providerId": "gemini",
+        "modelId": "gemini-2.5-flash-lite-preview-06-17",
+        "settings": {
+            "temperature": 0.3,
+            "geminiSafetySettings": [
+                { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE" },
+                {
+                    "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+                    "threshold": "BLOCK_NONE"
+                },
+                {
+                    "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
+                    "threshold": "BLOCK_NONE"
+                },
+                { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE" }
+            ]
+        }
+    },
+    {
+        "id": "google-gemini-2.0-flash-default",
+        "displayName": "Google - Gemini 2.0 Flash",
+        "description": "Default preset for Gemini 2.0 Flash.",
+        "providerId": "gemini",
+        "modelId": "gemini-2.0-flash",
+        "settings": {
+            "temperature": 0.3,
+            "geminiSafetySettings": [
+                { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE" },
+                {
+                    "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+                    "threshold": "BLOCK_NONE"
+                },
+                {
+                    "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
+                    "threshold": "BLOCK_NONE"
+                },
+                { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE" }
+            ]
+        }
+    },
+    {
+        "id": "google-gemini-2.0-flash-lite-default",
+        "displayName": "Google - Gemini 2.0 Flash Lite",
+        "description": "Default preset for Gemini 2.0 Flash Lite.",
+        "providerId": "gemini",
+        "modelId": "gemini-2.0-flash-lite",
+        "settings": {
+            "temperature": 0.3,
+            "geminiSafetySettings": [
+                { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE" },
+                {
+                    "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+                    "threshold": "BLOCK_NONE"
+                },
+                {
+                    "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
+                    "threshold": "BLOCK_NONE"
+                },
+                { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE" }
+            ]
+        }
+    },
+    {
+        "id": "openai-o4-mini-default",
+        "displayName": "OpenAI - o4-mini",
+        "description": "Default preset for o4-mini.",
+        "providerId": "openai",
+        "modelId": "o4-mini",
+        "settings": {
+            "temperature": 1.0
+        }
+    },
+    {
+        "id": "openai-gpt-4.1-default",
+        "displayName": "OpenAI - GPT-4.1",
+        "description": "Default preset for GPT-4.1.",
+        "providerId": "openai",
+        "modelId": "gpt-4.1",
+        "settings": {
+            "temperature": 0.3
+        }
+    },
+    {
+        "id": "openai-gpt-4.1-mini-default",
+        "displayName": "OpenAI - GPT-4.1 Mini",
+        "description": "Default preset for GPT-4.1 Mini.",
+        "providerId": "openai",
+        "modelId": "gpt-4.1-mini",
+        "settings": {
+            "temperature": 0.3
+        }
+    },
+    {
+        "id": "openai-gpt-4.1-nano-default",
+        "displayName": "OpenAI - GPT-4.1 Nano",
+        "description": "Default preset for GPT-4.1 Nano.",
+        "providerId": "openai",
+        "modelId": "gpt-4.1-nano",
+        "settings": {
+            "temperature": 0.3
+        }
+    },
+    {
+        "id": "mistral-codestral-2501-default",
+        "displayName": "Mistral AI - Codestral",
+        "description": "Default preset for Codestral.",
+        "providerId": "mistral",
+        "modelId": "codestral-2501",
+        "settings": {
+            "temperature": 0.3
+        }
+    },
+    {
+        "id": "mistral-devstral-small-2505-default",
+        "displayName": "Mistral AI - Devstral Small",
+        "description": "Default preset for Devstral Small.",
+        "providerId": "mistral",
+        "modelId": "devstral-small-2505",
+        "settings": {
+            "temperature": 0.3
+        }
+    }
+]

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export type { ApiKeyProvider } from "./types";
 export { LLMService } from "./llm/LLMService";
+export type { LLMServiceOptions, PresetMode } from "./llm/LLMService";
+export type { ModelPreset } from "./types/presets";
 export * from "./llm/types";
 export * from "./llm/clients/types";
 export { fromEnvironment } from "./providers/fromEnvironment";
+export { renderTemplate } from "./utils/templateEngine";

package/dist/index.js

@@ -14,7 +14,7 @@ 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;
+exports.renderTemplate = 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; } });
@@ -25,3 +25,6 @@ __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; } });
+// --- Utilities ---
+var templateEngine_1 = require("./utils/templateEngine");
+Object.defineProperty(exports, "renderTemplate", { enumerable: true, get: function () { return templateEngine_1.renderTemplate; } });

package/dist/llm/LLMService.d.ts

@@ -1,6 +1,22 @@
 import type { ApiKeyProvider } from '../types';
 import type { LLMChatRequest, LLMResponse, LLMFailureResponse, ProviderInfo, ModelInfo, ApiProviderId } from "./types";
 import type { ILLMClientAdapter } from "./clients/types";
+import type { ModelPreset } from "../types/presets";
+/**
+ * Defines how custom presets interact with the default presets.
+ * 'replace': Use only the custom presets provided. The default set is ignored.
+ * 'extend': Use the default presets, and add/override them with the custom presets. This is the default behavior.
+ */
+export type PresetMode = 'replace' | 'extend';
+/**
+ * Options for configuring the LLMService
+ */
+export interface LLMServiceOptions {
+    /** An array of custom presets to integrate. */
+    presets?: ModelPreset[];
+    /** The strategy for integrating custom presets. Defaults to 'extend'. */
+    presetMode?: PresetMode;
+}
 /**
  * Main process service for LLM operations
  *
@@ -10,12 +26,14 @@ import type { ILLMClientAdapter } from "./clients/types";
  * - Validates requests and applies default settings
  * - Routes requests to appropriate provider adapters
  * - Handles errors and provides standardized responses
+ * - Provides configurable model presets for common use cases
  */
 export declare class LLMService {
     private getApiKey;
     private clientAdapters;
     private mockClientAdapter;
-    constructor(getApiKey: ApiKeyProvider);
+    private presets;
+    constructor(getApiKey: ApiKeyProvider, options?: LLMServiceOptions);
     /**
      * Gets list of supported LLM providers
      *
@@ -83,4 +101,10 @@ export declare class LLMService {
         availableProviders: string[];
         unavailableProviders: string[];
     };
+    /**
+     * Gets all configured model presets
+     *
+     * @returns Array of model presets
+     */
+    getPresets(): ModelPreset[];
 }

package/dist/llm/LLMService.js

@@ -1,10 +1,14 @@
 "use strict";
 // AI Summary: Main process service for LLM operations, integrating with ApiKeyProvider for secure key access.
 // Orchestrates LLM requests through provider-specific client adapters with proper error handling.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LLMService = void 0;
 const MockClientAdapter_1 = require("./clients/MockClientAdapter");
 const config_1 = require("./config");
+const presets_json_1 = __importDefault(require("../config/presets.json"));
 /**
  * Main process service for LLM operations
  *
@@ -14,12 +18,33 @@ const config_1 = require("./config");
  * - Validates requests and applies default settings
  * - Routes requests to appropriate provider adapters
  * - Handles errors and provides standardized responses
+ * - Provides configurable model presets for common use cases
  */
 class LLMService {
-    constructor(getApiKey) {
+    constructor(getApiKey, options = {}) {
         this.getApiKey = getApiKey;
         this.clientAdapters = new Map();
         this.mockClientAdapter = new MockClientAdapter_1.MockClientAdapter();
+        // Initialize presets based on mode
+        const finalPresets = new Map();
+        const customPresets = options.presets || [];
+        const mode = options.presetMode || 'extend';
+        if (mode === 'replace') {
+            // Replace Mode: Only use custom presets.
+            for (const preset of customPresets) {
+                finalPresets.set(preset.id, preset);
+            }
+        }
+        else {
+            // Extend Mode: Load defaults first, then add/override.
+            for (const preset of presets_json_1.default) {
+                finalPresets.set(preset.id, preset);
+            }
+            for (const preset of customPresets) {
+                finalPresets.set(preset.id, preset);
+            }
+        }
+        this.presets = Array.from(finalPresets.values());
         // Dynamically register client adapters based on configuration
         let registeredCount = 0;
         const successfullyRegisteredProviders = [];
@@ -406,5 +431,13 @@ class LLMService {
             unavailableProviders,
         };
     }
+    /**
+     * Gets all configured model presets
+     *
+     * @returns Array of model presets
+     */
+    getPresets() {
+        return [...this.presets]; // Return a copy to prevent external modification
+    }
 }
 exports.LLMService = LLMService;

package/dist/llm/LLMService.presets.test.d.ts

@@ -0,0 +1 @@
+export {};