genai-lite 0.2.0 → 0.2.1

package/README.md

@@ -111,6 +111,16 @@ const llmService = new LLMService(myKeyProvider);
 - `codestral-2501` - Specialized for code generation
 - `devstral-small-2505` - Compact development-focused model
 
+### Models with Reasoning Support
+
+Some models include advanced reasoning/thinking capabilities that enhance their problem-solving abilities:
+
+- **Anthropic**: Claude Sonnet 4, Claude Opus 4, Claude 3.7 Sonnet
+- **Google Gemini**: Gemini 2.5 Pro (always on), Gemini 2.5 Flash, Gemini 2.5 Flash-Lite Preview
+- **OpenAI**: o4-mini (always on)
+
+See the [Reasoning Mode](#reasoning-mode) section for usage details.
+
 ## Advanced Usage
 
 ### Custom Settings
@@ -129,6 +139,68 @@ const response = await llmService.sendMessage({
 });
 ```
 
+### Reasoning Mode
+
+Enable advanced reasoning capabilities for supported models to get step-by-step thinking and improved problem-solving:
+
+```typescript
+// Enable reasoning with automatic token budget
+const response = await llmService.sendMessage({
+  providerId: 'gemini',
+  modelId: 'gemini-2.5-flash',
+  messages: [{ role: 'user', content: 'Solve this step by step: If a train travels 120km in 2 hours, what is its speed in m/s?' }],
+  settings: {
+    reasoning: {
+      enabled: true  // Let the model decide how much thinking to do
+    }
+  }
+});
+
+// Use effort levels for quick control
+const response = await llmService.sendMessage({
+  providerId: 'anthropic',
+  modelId: 'claude-3-7-sonnet-20250219',
+  messages: [{ role: 'user', content: 'Analyze this complex problem...' }],
+  settings: {
+    reasoning: {
+      enabled: true,
+      effort: 'high'  // 'low', 'medium', or 'high'
+    }
+  }
+});
+
+// Set specific token budget for reasoning
+const response = await llmService.sendMessage({
+  providerId: 'gemini',
+  modelId: 'gemini-2.5-flash-lite-preview-06-17',
+  messages: [{ role: 'user', content: 'What is the square root of 144?' }],
+  settings: {
+    reasoning: {
+      enabled: true,
+      maxTokens: 5000  // Specific token budget for reasoning
+    }
+  }
+});
+
+// Access reasoning output (if available)
+if (response.object === 'chat.completion' && response.choices[0].reasoning) {
+  console.log('Model reasoning:', response.choices[0].reasoning);
+  console.log('Final answer:', response.choices[0].message.content);
+}
+```
+
+**Reasoning Options:**
+- `enabled`: Turn reasoning on/off (some models like o4-mini and Gemini 2.5 Pro have it always on)
+- `effort`: Quick presets - 'low' (20% budget), 'medium' (50%), 'high' (80%)
+- `maxTokens`: Specific token budget for reasoning
+- `exclude`: Set to `true` to enable reasoning but exclude it from the response
+
+**Important Notes:**
+- Reasoning tokens are billed separately and may cost more
+- Some models (o4-mini, Gemini 2.5 Pro) cannot disable reasoning
+- Not all models support reasoning - check the [supported models](#models-with-reasoning-support) list
+- The `reasoning` field in the response contains the model's thought process (when available)
+
 ### Provider Information
 
 ```typescript
@@ -144,22 +216,27 @@ 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.
+genai-lite includes a comprehensive 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
 
+The library ships with over 20 pre-configured presets (defined in `src/config/presets.json`), including specialized "thinking" presets for models with reasoning capabilities:
+
 ```typescript
 const llmService = new LLMService(fromEnvironment);
 
 // Get all default presets
 const presets = llmService.getPresets();
 // Returns presets like:
-// - anthropic-claude-3-5-sonnet-20241022-default
+// - anthropic-claude-sonnet-4-20250514-default
+// - anthropic-claude-sonnet-4-20250514-thinking (reasoning enabled)
 // - openai-gpt-4.1-default
-// - google-gemini-2.5-pro
-// ... and more
+// - google-gemini-2.5-flash-thinking (reasoning enabled)
+// ... and many more
 ```
 
+The thinking presets automatically enable reasoning mode for supported models, making it easy to leverage advanced problem-solving capabilities without manual configuration.
+
 #### Extending Default Presets
 
 ```typescript
@@ -213,6 +290,69 @@ const llmService = new LLMService(fromEnvironment, {
 });
 ```
 
+### Using Presets with Messages
+
+You can use presets directly in `sendMessage` calls:
+
+```typescript
+// Send a message using a preset
+const response = await llmService.sendMessage({
+  presetId: 'anthropic-claude-3-7-sonnet-20250219-thinking',
+  messages: [{ role: 'user', content: 'Solve this complex problem...' }]
+});
+
+// Override preset settings
+const response = await llmService.sendMessage({
+  presetId: 'openai-gpt-4.1-default',
+  messages: [{ role: 'user', content: 'Write a story' }],
+  settings: {
+    temperature: 0.9, // Override preset's temperature
+    maxTokens: 3000
+  }
+});
+```
+
+### Model-Aware Template Rendering
+
+The library provides a powerful `prepareMessage` method that renders templates with model context, allowing you to create adaptive prompts based on model capabilities:
+
+```typescript
+// Prepare a message with model-aware template
+const result = await llmService.prepareMessage({
+  template: `
+{{ thinking_enabled ? "Please think step-by-step about this problem:" : "Please analyze this problem:" }}
+
+{{ question }}
+
+{{ thinking_available && !thinking_enabled ? "(Note: This model supports reasoning mode which could help with complex problems)" : "" }}
+  `,
+  variables: { 
+    question: 'What is the optimal algorithm for finding the shortest path in a weighted graph?' 
+  },
+  presetId: 'anthropic-claude-3-7-sonnet-20250219-thinking'
+});
+
+if (result.object !== 'error') {
+  // Access the prepared messages and model context
+  console.log('Messages:', result.messages);
+  console.log('Model context:', result.modelContext);
+  
+  // Send the prepared messages
+  const response = await llmService.sendMessage({
+    presetId: 'anthropic-claude-3-7-sonnet-20250219-thinking',
+    messages: result.messages
+  });
+}
+```
+
+The model context includes:
+- `thinking_enabled`: Whether reasoning/thinking is enabled for this request
+- `thinking_available`: Whether the model supports reasoning/thinking
+- `model_id`: The resolved model ID
+- `provider_id`: The resolved provider ID
+- `reasoning_effort`: The reasoning effort level if specified
+- `reasoning_max_tokens`: The reasoning token budget if specified
+
 ### Error Handling
 
 ```typescript
@@ -284,13 +424,18 @@ genai-lite is written in TypeScript and provides comprehensive type definitions:
 ```typescript
 import type { 
   LLMChatRequest,
+  LLMChatRequestWithPreset,
   LLMResponse,
   LLMFailureResponse,
   LLMSettings,
+  LLMReasoningSettings,
   ApiKeyProvider,
   ModelPreset,
   LLMServiceOptions,
-  PresetMode
+  PresetMode,
+  PrepareMessageOptions,
+  ModelContext,
+  PrepareMessageResult
 } from 'genai-lite';
 ```
 

package/dist/config/presets.json

@@ -6,7 +6,23 @@
         "providerId": "anthropic",
         "modelId": "claude-sonnet-4-20250514",
         "settings": {
-            "temperature": 0.3
+            "temperature": 0.7,
+            "reasoning": {
+                "enabled": false
+            }
+        }
+    },
+    {
+        "id": "anthropic-claude-sonnet-4-20250514-thinking",
+        "displayName": "Anthropic - Claude Sonnet 4 (Thinking)",
+        "description": "Claude Sonnet 4 with reasoning enabled for step-by-step thinking.",
+        "providerId": "anthropic",
+        "modelId": "claude-sonnet-4-20250514",
+        "settings": {
+            "temperature": 0.7,
+            "reasoning": {
+                "enabled": true
+            }
         }
     },
     {
@@ -16,7 +32,23 @@
         "providerId": "anthropic",
         "modelId": "claude-opus-4-20250514",
         "settings": {
-            "temperature": 0.3
+            "temperature": 0.7,
+            "reasoning": {
+                "enabled": false
+            }
+        }
+    },
+    {
+        "id": "anthropic-claude-opus-4-20250514-thinking",
+        "displayName": "Anthropic - Claude Opus 4 (Thinking)",
+        "description": "Claude Opus 4 with reasoning enabled for complex problem solving.",
+        "providerId": "anthropic",
+        "modelId": "claude-opus-4-20250514",
+        "settings": {
+            "temperature": 0.7,
+            "reasoning": {
+                "enabled": true
+            }
         }
     },
     {
@@ -26,7 +58,23 @@
         "providerId": "anthropic",
         "modelId": "claude-3-7-sonnet-20250219",
         "settings": {
-            "temperature": 0.3
+            "temperature": 0.7,
+            "reasoning": {
+                "enabled": false
+            }
+        }
+    },
+    {
+        "id": "anthropic-claude-3-7-sonnet-20250219-thinking",
+        "displayName": "Anthropic - Claude 3.7 Sonnet (Thinking)",
+        "description": "Claude 3.7 Sonnet with full reasoning output for detailed analysis.",
+        "providerId": "anthropic",
+        "modelId": "claude-3-7-sonnet-20250219",
+        "settings": {
+            "temperature": 0.7,
+            "reasoning": {
+                "enabled": true
+            }
         }
     },
     {
@@ -36,7 +84,7 @@
         "providerId": "anthropic",
         "modelId": "claude-3-5-sonnet-20241022",
         "settings": {
-            "temperature": 0.3
+            "temperature": 0.7
         }
     },
     {
@@ -46,7 +94,7 @@
         "providerId": "anthropic",
         "modelId": "claude-3-5-haiku-20241022",
         "settings": {
-            "temperature": 0.3
+            "temperature": 0.7
         }
     },
     {
@@ -56,7 +104,7 @@
         "providerId": "gemini",
         "modelId": "gemini-2.5-pro",
         "settings": {
-            "temperature": 0.3,
+            "temperature": 0.7,
             "geminiSafetySettings": [
                 { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE" },
                 {
@@ -78,7 +126,7 @@
         "providerId": "gemini",
         "modelId": "gemini-2.5-flash",
         "settings": {
-            "temperature": 0.3,
+            "temperature": 0.7,
             "geminiSafetySettings": [
                 { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE" },
                 {
@@ -90,7 +138,35 @@
                     "threshold": "BLOCK_NONE"
                 },
                 { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE" }
-            ]
+            ],
+            "reasoning": {
+                "enabled": false
+            }
+        }
+    },
+    {
+        "id": "google-gemini-2.5-flash-thinking",
+        "displayName": "Google - Gemini 2.5 Flash (Thinking)",
+        "description": "Gemini 2.5 Flash with dynamic reasoning for adaptive problem solving.",
+        "providerId": "gemini",
+        "modelId": "gemini-2.5-flash",
+        "settings": {
+            "temperature": 0.7,
+            "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" }
+            ],
+            "reasoning": {
+                "enabled": true
+            }
         }
     },
     {
@@ -100,7 +176,7 @@
         "providerId": "gemini",
         "modelId": "gemini-2.5-flash-lite-preview-06-17",
         "settings": {
-            "temperature": 0.3,
+            "temperature": 0.7,
             "geminiSafetySettings": [
                 { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE" },
                 {
@@ -112,7 +188,35 @@
                     "threshold": "BLOCK_NONE"
                 },
                 { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE" }
-            ]
+            ],
+            "reasoning": {
+                "enabled": false
+            }
+        }
+    },
+    {
+        "id": "google-gemini-2.5-flash-lite-preview-thinking",
+        "displayName": "Google - Gemini 2.5 Flash-Lite Preview (Thinking)",
+        "description": "Gemini 2.5 Flash-Lite with dynamic reasoning for efficient thinking.",
+        "providerId": "gemini",
+        "modelId": "gemini-2.5-flash-lite-preview-06-17",
+        "settings": {
+            "temperature": 0.7,
+            "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" }
+            ],
+            "reasoning": {
+                "enabled": true
+            }
         }
     },
     {
@@ -122,7 +226,7 @@
         "providerId": "gemini",
         "modelId": "gemini-2.0-flash",
         "settings": {
-            "temperature": 0.3,
+            "temperature": 0.7,
             "geminiSafetySettings": [
                 { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE" },
                 {
@@ -144,7 +248,7 @@
         "providerId": "gemini",
         "modelId": "gemini-2.0-flash-lite",
         "settings": {
-            "temperature": 0.3,
+            "temperature": 0.7,
             "geminiSafetySettings": [
                 { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE" },
                 {
@@ -176,7 +280,7 @@
         "providerId": "openai",
         "modelId": "gpt-4.1",
         "settings": {
-            "temperature": 0.3
+            "temperature": 0.7
         }
     },
     {
@@ -186,7 +290,7 @@
         "providerId": "openai",
         "modelId": "gpt-4.1-mini",
         "settings": {
-            "temperature": 0.3
+            "temperature": 0.7
         }
     },
     {
@@ -196,7 +300,7 @@
         "providerId": "openai",
         "modelId": "gpt-4.1-nano",
         "settings": {
-            "temperature": 0.3
+            "temperature": 0.7
         }
     },
     {
@@ -206,7 +310,7 @@
         "providerId": "mistral",
         "modelId": "codestral-2501",
         "settings": {
-            "temperature": 0.3
+            "temperature": 0.7
         }
     },
     {
@@ -216,7 +320,7 @@
         "providerId": "mistral",
         "modelId": "devstral-small-2505",
         "settings": {
-            "temperature": 0.3
+            "temperature": 0.7
         }
     }
 ]

package/dist/llm/LLMService.d.ts

@@ -1,5 +1,5 @@
 import type { ApiKeyProvider } from '../types';
-import type { LLMChatRequest, LLMResponse, LLMFailureResponse, ProviderInfo, ModelInfo, ApiProviderId } from "./types";
+import type { LLMChatRequest, LLMChatRequestWithPreset, LLMResponse, LLMFailureResponse, ProviderInfo, ModelInfo, ApiProviderId, PrepareMessageOptions, PrepareMessageResult } from "./types";
 import type { ILLMClientAdapter } from "./clients/types";
 import type { ModelPreset } from "../types/presets";
 /**
@@ -53,7 +53,7 @@ export declare class LLMService {
      * @param request - The LLM chat request
      * @returns Promise resolving to either success or failure response
      */
-    sendMessage(request: LLMChatRequest): Promise<LLMResponse | LLMFailureResponse>;
+    sendMessage(request: LLMChatRequest | LLMChatRequestWithPreset): Promise<LLMResponse | LLMFailureResponse>;
     /**
      * Validates basic LLM request structure
      *
@@ -61,6 +61,15 @@ export declare class LLMService {
      * @returns LLMFailureResponse if validation fails, null if valid
      */
     private validateRequestStructure;
+    /**
+     * Validates reasoning settings against model capabilities
+     *
+     * @param modelInfo - The model information
+     * @param reasoning - The reasoning settings to validate
+     * @param request - The original request for error context
+     * @returns LLMFailureResponse if validation fails, null if valid
+     */
+    private validateReasoningSettings;
     /**
      * Merges request settings with model-specific and global defaults
      *
@@ -107,4 +116,32 @@ export declare class LLMService {
      * @returns Array of model presets
      */
     getPresets(): ModelPreset[];
+    /**
+     * Resolves model information from either a preset ID or provider/model IDs
+     *
+     * @private
+     * @param options Options containing either presetId or providerId/modelId
+     * @returns Resolved model info and settings or error response
+     */
+    private resolveModelInfo;
+    /**
+     * Prepares messages with model context for template rendering
+     *
+     * This method resolves model information from either a preset or direct provider/model IDs,
+     * then renders a template with model context variables injected, or returns pre-built messages
+     * with the model context separately.
+     *
+     * @param options Options for preparing messages
+     * @returns Promise resolving to prepared messages and model context
+     *
+     * @example
+     * ```typescript
+     * const { messages } = await llm.prepareMessage({
+     *   template: 'Help me {{ thinking_enabled ? "think through" : "solve" }} this: {{ problem }}',
+     *   variables: { problem: 'complex algorithm' },
+     *   presetId: 'anthropic-claude-3-7-sonnet-20250219-thinking'
+     * });
+     * ```
+     */
+    prepareMessage(options: PrepareMessageOptions): Promise<PrepareMessageResult | LLMFailureResponse>;
 }