genai-lite 0.4.0 → 0.4.2

package/README.md

@@ -295,9 +295,11 @@ if (response.object === 'chat.completion' && response.choices[0].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)
 
-### Automatic Thinking Extraction
+### Thinking Extraction and Enforcement
 
-genai-lite can capture reasoning from any model by automatically extracting content wrapped in XML tags. When models output their thinking process in tags like `<thinking>`, the library automatically moves this content to the standardized `reasoning` field. This works with all models, providing a consistent interface for accessing model reasoning:
+For models without native reasoning, you can prompt them to output reasoning in XML tags like `<thinking>`. The library then extracts these tags and moves the content to the standardized `reasoning` field, providing a consistent interface across all models.
+
+**Key point:** The library doesn't make models think automatically—you must explicitly instruct non-reasoning models to use thinking tags in your prompt. The library then enforces that these tags are present (for non-reasoning models) or accepts native reasoning (for reasoning models).
 
 ```typescript
 // Prompt the model to think step-by-step in a <thinking> tag
@@ -312,7 +314,7 @@ const response = await llmService.sendMessage({
     content: 'Please think through this problem step by step before answering: What is 15% of 240?'
   }],
   settings: {
-    thinkingExtraction: { enabled: true } // Must explicitly enable
+    thinkingTagFallback: { enabled: true } // Must explicitly enable
   }
 });
 
@@ -334,25 +336,25 @@ const response = await llmService.sendMessage({
   modelId: 'claude-3-5-haiku-20241022',
   messages: [{ role: 'user', content: 'Solve this step by step...' }],
   settings: {
-    thinkingExtraction: {
+    thinkingTagFallback: {
       enabled: true,     // Must explicitly enable (default: false)
-      tag: 'scratchpad', // Custom tag name (default: 'thinking')
-      onMissing: 'auto'  // Smart enforcement (see below)
+      tagName: 'scratchpad', // Custom tag name (default: 'thinking')
+      enforce: true  // Smart enforcement (see below)
     }
   }
 });
 ```
 
-**The `onMissing` Property:**
+**The `enforce` Property:**
+
+The `enforce` boolean controls whether thinking tags are required when native reasoning is not active:
 
-The `onMissing` property controls what happens when the expected thinking tag is not found:
+- `enforce: true` - Error if tags missing AND native reasoning not active (smart enforcement)
+- `enforce: false` (default) - Extract tags if present, never error
 
-- `'ignore'`: Silently continue without the tag
-- `'warn'`: Log a warning but continue processing
-- `'error'`: Return an error response with the original response preserved in `partialResponse`
-- `'auto'` (default): Intelligently decide based on the model's native reasoning capabilities
+The enforcement is **always smart** - it automatically checks if native reasoning is active and only enforces when the model needs tags as a fallback.
 
-**How `'auto'` Mode Works:**
+**How Smart Enforcement Works:**
 
 ```typescript
 // With non-native reasoning models (e.g., GPT-4)
@@ -367,10 +369,10 @@ const response = await llmService.sendMessage({
     content: 'What is 15% of 240?'
   }],
   settings: {
-    thinkingExtraction: { enabled: true } // onMissing: 'auto' is default
+    thinkingTagFallback: { enabled: true, enforce: true }
   }
 });
-// Result: ERROR if <thinking> tag is missing (strict enforcement)
+// Result: ERROR if <thinking> tag is missing (native reasoning not active)
 // The response is still accessible via errorResponse.partialResponse
 
 // With native reasoning models (e.g., Claude with reasoning enabled)
@@ -380,10 +382,10 @@ const response = await llmService.sendMessage({
   messages: [/* same prompt */],
   settings: {
     reasoning: { enabled: true },
-    thinkingExtraction: { enabled: true }
+    thinkingTagFallback: { enabled: true, enforce: true }
   }
 });
-// Result: SUCCESS even if <thinking> tag is missing (lenient for native reasoning)
+// Result: SUCCESS even if <thinking> tag is missing (native reasoning is active)
 ```
 
 This intelligent enforcement ensures that:
@@ -510,13 +512,10 @@ The library provides a powerful `createMessages` method that combines template r
 // Basic example: Create model-aware messages
 const { messages, modelContext } = await llmService.createMessages({
   template: `
-    <SYSTEM>
-      You are a {{ thinking_enabled ? "thoughtful" : "helpful" }} assistant.
-      {{ thinking_available && !thinking_enabled ? "Note: Reasoning mode is available for complex problems." : "" }}
-    </SYSTEM>
+    <SYSTEM>You are a helpful assistant.</SYSTEM>
     <USER>{{ question }}</USER>
   `,
-  variables: { 
+  variables: {
     question: 'What is the optimal algorithm for finding the shortest path in a weighted graph?'
   },
   presetId: 'anthropic-claude-3-7-sonnet-20250219-thinking'
@@ -560,14 +559,26 @@ The method provides:
 - **Template Rendering**: Full support for conditionals and variable substitution
 - **Role Tag Parsing**: Converts `<SYSTEM>`, `<USER>`, and `<ASSISTANT>` tags to messages
 
-Available model context variables:
-- `thinking_enabled`: Whether reasoning/thinking is enabled for this request
-- `thinking_available`: Whether the model supports reasoning/thinking
+**Available model context variables:**
+
+- `native_reasoning_active`: Whether native reasoning is **currently active** for this request
+  - `true`: The model is using built-in reasoning (e.g., Claude 4, o4-mini, Gemini 2.5 Pro with reasoning enabled)
+  - `false`: No native reasoning is active (either because the model doesn't support it, or it's been disabled)
+- `native_reasoning_capable`: Whether the model **has the capability** to use native reasoning
+  - `true`: Model supports native reasoning (may or may not be enabled)
+  - `false`: Model does not support native reasoning
 - `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
 
+**Best Practice for Templates:**
+When adding thinking tag instructions to your templates, **always use `requires_tags_for_thinking`** (the NOT operator). This ensures:
+- Models with active native reasoning get clean, direct prompts
+- Models without native reasoning get explicit instructions to use `<thinking>` tags
+
+Example: `{{ requires_tags_for_thinking ? ' Write your reasoning in <thinking> tags first.' : '' }}`
+
 #### Advanced Features
 
 **Dynamic Role Injection:**
@@ -617,7 +628,7 @@ const response = await llmService.sendMessage({
   modelId: 'gpt-4.1',
   messages,
   settings: {
-    thinkingExtraction: { enabled: true } // Default, but shown for clarity
+    thinkingTagFallback: { enabled: true } // Default, but shown for clarity
   }
 });
 
@@ -640,7 +651,7 @@ const creativeWritingTemplate = `
   "settings": {
     "temperature": 0.9,
     "maxTokens": 3000,
-    "thinkingExtraction": { "enabled": true, "tag": "reasoning" }
+    "thinkingTagFallback": { "enabled": true, "tagName": "reasoning" }
   }
 }
 </META>
@@ -1045,14 +1056,14 @@ const llmService = new LLMService(electronKeyProvider);
 genai-lite is written in TypeScript and provides comprehensive type definitions:
 
 ```typescript
-import type { 
+import type {
   LLMChatRequest,
   LLMChatRequestWithPreset,
   LLMResponse,
   LLMFailureResponse,
   LLMSettings,
   LLMReasoningSettings,
-  LLMThinkingExtractionSettings,
+  LLMThinkingTagFallbackSettings,
   ApiKeyProvider,
   ModelPreset,
   LLMServiceOptions,
@@ -1324,24 +1335,23 @@ const { messages } = await llmService.createMessages({
   presetId: 'openai-gpt-4.1-default' // Optional: adds model context
 });
 
-// Advanced: Leverage model context for adaptive prompts
+// Advanced: Adaptive prompts based on model capabilities
 const { messages, modelContext } = await llmService.createMessages({
   template: `
     <SYSTEM>
-      You are a {{ thinking_enabled ? 'analytical problem solver' : 'quick helper' }}.
-      {{ model_id.includes('claude') ? 'Use your advanced reasoning capabilities.' : '' }}
+      You are a problem-solving assistant.
+      {{ requires_tags_for_thinking ? ' For complex problems, write your reasoning in <thinking> tags before answering.' : '' }}
     </SYSTEM>
-    <USER>
-      {{ thinking_enabled ? 'Please solve this step-by-step:' : 'Please answer:' }}
-      {{ question }}
-    </USER>
+    <USER>{{ question }}</USER>
   `,
+  // Note: Use requires_tags_for_thinking (NOT operator) - only instruct models that don't have active native reasoning
   variables: { question: 'What causes the seasons on Earth?' },
   presetId: 'anthropic-claude-3-7-sonnet-20250219-thinking'
 });
 
 console.log('Model context:', modelContext);
-// Output: { thinking_enabled: true, thinking_available: true, model_id: 'claude-3-7-sonnet-20250219', ... }
+// Output: { native_reasoning_active: true, native_reasoning_capable: true, model_id: 'claude-3-7-sonnet-20250219', ... }
+// Note: With a reasoning model, the system prompt won't include thinking tag instructions
 ```
 
 **Low-Level Utilities:**

package/dist/llm/LLMService.d.ts

@@ -75,19 +75,45 @@ export declare class LLMService {
      * injection, and role tag parsing into a single, intuitive API. It replaces the need
      * to chain prepareMessage and buildMessagesFromTemplate for model-aware multi-turn prompts.
      *
+     * **Model Context Injection:**
+     * When a presetId or providerId/modelId is provided, this method automatically injects
+     * model context variables into your templates:
+     * - `native_reasoning_active`: Whether native reasoning is currently active
+     * - `native_reasoning_capable`: Whether the model supports native reasoning
+     * - `requires_tags_for_thinking`: Whether thinking tags are needed (true when native reasoning not active)
+     * - `model_id`, `provider_id`, `reasoning_effort`, `reasoning_max_tokens`
+     *
+     * **Best Practice for Thinking Tags:**
+     * When adding thinking tag instructions, use requires_tags_for_thinking:
+     * `{{ requires_tags_for_thinking ? 'Write your reasoning in <thinking> tags first.' : '' }}`
+     *
      * @param options Options for creating messages
-     * @returns Promise resolving to parsed messages and model context
+     * @returns Promise resolving to parsed messages, model context, and template settings
      *
      * @example
      * ```typescript
+     * // Basic usage
      * const { messages } = await llm.createMessages({
      *   template: `
-     *     <SYSTEM>You are a {{ thinking_enabled ? "thoughtful" : "helpful" }} assistant.</SYSTEM>
+     *     <SYSTEM>You are a helpful assistant.</SYSTEM>
      *     <USER>Help me with {{ task }}</USER>
      *   `,
      *   variables: { task: 'understanding async/await' },
      *   presetId: 'openai-gpt-4.1-default'
      * });
+     *
+     * // Model-aware template with thinking tags
+     * const { messages, modelContext } = await llm.createMessages({
+     *   template: `
+     *     <SYSTEM>
+     *       You are a problem-solving assistant.
+     *       {{ requires_tags_for_thinking ? 'For complex problems, write your reasoning in <thinking> tags first.' : '' }}
+     *     </SYSTEM>
+     *     <USER>{{ question }}</USER>
+     *   `,
+     *   variables: { question: 'Explain recursion' },
+     *   presetId: 'anthropic-claude-3-7-sonnet-20250219-thinking'
+     * });
      * ```
      */
     createMessages(options: {
@@ -96,6 +122,7 @@ export declare class LLMService {
         presetId?: string;
         providerId?: string;
         modelId?: string;
+        settings?: Partial<LLMSettings>;
     }): Promise<CreateMessagesResult>;
     /**
      * Gets information about registered adapters

package/dist/llm/LLMService.js

@@ -143,32 +143,42 @@ class LLMService {
                         object: "error",
                     };
                 }
+                // Validate API key format if adapter supports it
+                if (clientAdapter.validateApiKey && !clientAdapter.validateApiKey(apiKey)) {
+                    return {
+                        provider: providerId,
+                        model: modelId,
+                        error: {
+                            message: `Invalid API key format for provider '${providerId}'. Please check your API key.`,
+                            code: "INVALID_API_KEY",
+                            type: "authentication_error",
+                        },
+                        object: "error",
+                    };
+                }
                 console.log(`Making LLM request with ${clientAdapter.constructor.name} for provider: ${providerId}`);
                 const result = await clientAdapter.sendMessage(internalRequest, apiKey);
-                // Post-process for thinking extraction
-                if (result.object === 'chat.completion' && internalRequest.settings.thinkingExtraction?.enabled) {
-                    const settings = internalRequest.settings.thinkingExtraction;
-                    const tagName = settings.tag || 'thinking';
-                    // Step 1: Resolve the effective onMissing strategy
-                    let effectiveOnMissing = settings.onMissing || 'auto';
-                    if (effectiveOnMissing === 'auto') {
-                        // Check if native reasoning is active
-                        const isNativeReasoningActive = modelInfo.reasoning?.supported === true &&
-                            (internalRequest.settings.reasoning?.enabled === true ||
-                                (modelInfo.reasoning?.enabledByDefault === true &&
-                                    internalRequest.settings.reasoning?.enabled !== false) || // Only if not explicitly disabled
-                                modelInfo.reasoning?.canDisable === false); // Always-on models
-                        effectiveOnMissing = isNativeReasoningActive ? 'ignore' : 'error';
-                    }
-                    // Step 2: Process the response
+                // Post-process for thinking tag fallback
+                // This feature extracts reasoning from XML tags when native reasoning is not active.
+                // It's a fallback mechanism for models without native reasoning or when native is disabled.
+                const fallbackSettings = internalRequest.settings.thinkingTagFallback;
+                if (result.object === 'chat.completion' && fallbackSettings && fallbackSettings.enabled !== false) {
+                    const tagName = fallbackSettings.tagName || 'thinking';
+                    // Check if native reasoning is active for this request
+                    const isNativeReasoningActive = modelInfo.reasoning?.supported === true &&
+                        (internalRequest.settings.reasoning?.enabled === true ||
+                            (modelInfo.reasoning?.enabledByDefault === true &&
+                                internalRequest.settings.reasoning?.enabled !== false) ||
+                            modelInfo.reasoning?.canDisable === false);
+                    // Process the response - extract thinking tags if present
                     const choice = result.choices[0];
                     if (choice?.message?.content) {
                         const { extracted, remaining } = (0, parser_1.extractInitialTaggedContent)(choice.message.content, tagName);
                         if (extracted !== null) {
+                            // Success: thinking tag found
                             console.log(`Extracted <${tagName}> block from response.`);
-                            // Handle the edge case: append to existing reasoning if present.
+                            // Handle the edge case: append to existing reasoning if present (e.g., native reasoning + thinking tags)
                             const existingReasoning = choice.reasoning || '';
-                            // Only add a separator when appending to existing reasoning
                             if (existingReasoning) {
                                 // Use a neutral markdown header that works for any consumer (human or AI)
                                 choice.reasoning = `${existingReasoning}\n\n#### Additional Reasoning\n\n${extracted}`;
@@ -180,17 +190,24 @@ class LLMService {
                             choice.message.content = remaining;
                         }
                         else {
-                            // Tag was not found, enforce the effective strategy
-                            if (effectiveOnMissing === 'error') {
+                            // Tag was not found
+                            // Enforce only if: (1) enforce: true AND (2) native reasoning is NOT active
+                            if (fallbackSettings.enforce === true && !isNativeReasoningActive) {
+                                const nativeReasoningCapable = modelInfo.reasoning?.supported === true;
                                 return {
                                     provider: providerId,
                                     model: modelId,
                                     error: {
-                                        message: `The model (${modelId}) response was expected to start with a <${tagName}> tag but it was not found. ` +
-                                            `This is enforced because the model does not have native reasoning active. ` +
-                                            `Either ensure your prompt instructs the model to use <${tagName}> tags, or enable native reasoning if supported.`,
-                                        code: "MISSING_EXPECTED_TAG",
+                                        message: `Model response missing required <${tagName}> tags.`,
+                                        code: "THINKING_TAGS_MISSING",
                                         type: "validation_error",
+                                        param: nativeReasoningCapable && !isNativeReasoningActive
+                                            ? `You disabled native reasoning for this model (${modelId}). ` +
+                                                `To see its reasoning, you must prompt it to use <${tagName}> tags. ` +
+                                                `Example: "Write your step-by-step reasoning in <${tagName}> tags before answering."`
+                                            : `This model (${modelId}) does not support native reasoning. ` +
+                                                `To get reasoning, you must prompt it to use <${tagName}> tags. ` +
+                                                `Example: "Write your step-by-step reasoning in <${tagName}> tags before answering."`,
                                     },
                                     object: "error",
                                     partialResponse: {
@@ -203,10 +220,7 @@ class LLMService {
                                     }
                                 };
                             }
-                            else if (effectiveOnMissing === 'warn') {
-                                console.warn(`Expected <${tagName}> tag was not found in the response from model ${modelId}.`);
-                            }
-                            // If 'ignore', do nothing
+                            // If enforce: false or native reasoning is active, do nothing
                         }
                     }
                 }
@@ -262,19 +276,45 @@ class LLMService {
      * injection, and role tag parsing into a single, intuitive API. It replaces the need
      * to chain prepareMessage and buildMessagesFromTemplate for model-aware multi-turn prompts.
      *
+     * **Model Context Injection:**
+     * When a presetId or providerId/modelId is provided, this method automatically injects
+     * model context variables into your templates:
+     * - `native_reasoning_active`: Whether native reasoning is currently active
+     * - `native_reasoning_capable`: Whether the model supports native reasoning
+     * - `requires_tags_for_thinking`: Whether thinking tags are needed (true when native reasoning not active)
+     * - `model_id`, `provider_id`, `reasoning_effort`, `reasoning_max_tokens`
+     *
+     * **Best Practice for Thinking Tags:**
+     * When adding thinking tag instructions, use requires_tags_for_thinking:
+     * `{{ requires_tags_for_thinking ? 'Write your reasoning in <thinking> tags first.' : '' }}`
+     *
      * @param options Options for creating messages
-     * @returns Promise resolving to parsed messages and model context
+     * @returns Promise resolving to parsed messages, model context, and template settings
      *
      * @example
      * ```typescript
+     * // Basic usage
      * const { messages } = await llm.createMessages({
      *   template: `
-     *     <SYSTEM>You are a {{ thinking_enabled ? "thoughtful" : "helpful" }} assistant.</SYSTEM>
+     *     <SYSTEM>You are a helpful assistant.</SYSTEM>
      *     <USER>Help me with {{ task }}</USER>
      *   `,
      *   variables: { task: 'understanding async/await' },
      *   presetId: 'openai-gpt-4.1-default'
      * });
+     *
+     * // Model-aware template with thinking tags
+     * const { messages, modelContext } = await llm.createMessages({
+     *   template: `
+     *     <SYSTEM>
+     *       You are a problem-solving assistant.
+     *       {{ requires_tags_for_thinking ? 'For complex problems, write your reasoning in <thinking> tags first.' : '' }}
+     *     </SYSTEM>
+     *     <USER>{{ question }}</USER>
+     *   `,
+     *   variables: { question: 'Explain recursion' },
+     *   presetId: 'anthropic-claude-3-7-sonnet-20250219-thinking'
+     * });
      * ```
      */
     async createMessages(options) {
@@ -290,7 +330,8 @@ class LLMService {
             const resolved = this.modelResolver.resolve({
                 presetId: options.presetId,
                 providerId: options.providerId,
-                modelId: options.modelId
+                modelId: options.modelId,
+                settings: options.settings
             });
             if (resolved.error) {
                 // If resolution fails, proceed without model context
@@ -300,12 +341,15 @@ class LLMService {
                 const { providerId, modelId, modelInfo, settings } = resolved;
                 // Merge settings with model defaults
                 const mergedSettings = this.settingsManager.mergeSettingsForModel(modelId, providerId, settings || {});
-                // Create model context
+                // Calculate native reasoning status
+                const nativeReasoningActive = !!(modelInfo.reasoning?.supported &&
+                    (mergedSettings.reasoning?.enabled === true ||
+                        (modelInfo.reasoning?.enabledByDefault && mergedSettings.reasoning?.enabled !== false)));
+                // Create model context with new property names
                 modelContext = {
-                    thinking_enabled: !!(modelInfo.reasoning?.supported &&
-                        (mergedSettings.reasoning?.enabled === true ||
-                            (modelInfo.reasoning?.enabledByDefault && mergedSettings.reasoning?.enabled !== false))),
-                    thinking_available: !!modelInfo.reasoning?.supported,
+                    native_reasoning_active: nativeReasoningActive,
+                    native_reasoning_capable: !!modelInfo.reasoning?.supported,
+                    requires_tags_for_thinking: !nativeReasoningActive,
                     model_id: modelId,
                     provider_id: providerId,
                     reasoning_effort: mergedSettings.reasoning?.effort,

package/dist/llm/config.js

@@ -69,10 +69,10 @@ exports.DEFAULT_LLM_SETTINGS = {
         maxTokens: undefined,
         exclude: false,
     },
-    thinkingExtraction: {
-        enabled: false, // Now requires explicit opt-in, works with onMissing: 'auto'
-        tag: 'thinking',
-        onMissing: 'auto' // Smart enforcement based on native reasoning status
+    thinkingTagFallback: {
+        enabled: false,
+        tagName: 'thinking',
+        enforce: false
     },
 };
 /**

package/dist/llm/services/SettingsManager.js

@@ -34,9 +34,9 @@ class SettingsManager {
                 ...modelDefaults.reasoning,
                 ...requestSettings?.reasoning,
             },
-            thinkingExtraction: {
-                ...modelDefaults.thinkingExtraction,
-                ...requestSettings?.thinkingExtraction,
+            thinkingTagFallback: {
+                ...modelDefaults.thinkingTagFallback,
+                ...requestSettings?.thinkingTagFallback,
             },
         };
         // Log the final settings for debugging
@@ -115,7 +115,7 @@ class SettingsManager {
             'supportsSystemMessage',
             'geminiSafetySettings',
             'reasoning',
-            'thinkingExtraction'
+            'thinkingTagFallback'
         ];
         // Check each setting field
         for (const [key, value] of Object.entries(settings)) {
@@ -195,22 +195,28 @@ class SettingsManager {
                 }
                 continue;
             }
-            if (key === 'thinkingExtraction' && typeof value === 'object' && value !== null) {
+            if (key === 'thinkingTagFallback' && typeof value === 'object' && value !== null) {
                 const thinkingValidated = {};
                 if ('enabled' in value && typeof value.enabled !== 'boolean') {
-                    console.warn(`Invalid thinkingExtraction.enabled value in template. Must be a boolean.`);
+                    console.warn(`Invalid thinkingTagFallback.enabled value in template. Must be a boolean.`);
                 }
                 else if ('enabled' in value) {
                     thinkingValidated.enabled = value.enabled;
                 }
-                if ('tag' in value && typeof value.tag !== 'string') {
-                    console.warn(`Invalid thinkingExtraction.tag value in template. Must be a string.`);
+                if ('tagName' in value && typeof value.tagName !== 'string') {
+                    console.warn(`Invalid thinkingTagFallback.tagName value in template. Must be a string.`);
                 }
-                else if ('tag' in value) {
-                    thinkingValidated.tag = value.tag;
+                else if ('tagName' in value) {
+                    thinkingValidated.tagName = value.tagName;
+                }
+                if ('enforce' in value && typeof value.enforce !== 'boolean') {
+                    console.warn(`Invalid thinkingTagFallback.enforce value in template. Must be a boolean.`);
+                }
+                else if ('enforce' in value) {
+                    thinkingValidated.enforce = value.enforce;
                 }
                 if (Object.keys(thinkingValidated).length > 0) {
-                    validated.thinkingExtraction = thinkingValidated;
+                    validated.thinkingTagFallback = thinkingValidated;
                 }
                 continue;
             }