genai-lite 0.1.3 → 0.1.4

package/README.md

@@ -11,6 +11,7 @@ A lightweight, portable Node.js/TypeScript library providing a unified interface
 - ⚡ **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
 
@@ -388,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.

package/dist/index.d.ts

@@ -5,3 +5,4 @@ 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/utils/index.d.ts

@@ -1 +1,2 @@
 export * from './prompt';
+export * from './templateEngine';

package/dist/utils/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./prompt"), exports);
+__exportStar(require("./templateEngine"), exports);

package/dist/utils/templateEngine.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Renders a template string by substituting variables and evaluating conditional expressions.
+ *
+ * Supports:
+ * - Simple variable substitution: {{ variableName }}
+ * - Conditional rendering: {{ condition ? `true result` : `false result` }}
+ * - Conditional with only true branch: {{ condition ? `true result` }}
+ * - Multi-line strings in backticks
+ * - Intelligent newline handling (removes empty lines when result is empty)
+ *
+ * @param template The template string containing placeholders
+ * @param variables Object containing variable values
+ * @returns The rendered template string
+ */
+export declare function renderTemplate(template: string, variables: Record<string, any>): string;

package/dist/utils/templateEngine.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTemplate = renderTemplate;
+/**
+ * Renders a template string by substituting variables and evaluating conditional expressions.
+ *
+ * Supports:
+ * - Simple variable substitution: {{ variableName }}
+ * - Conditional rendering: {{ condition ? `true result` : `false result` }}
+ * - Conditional with only true branch: {{ condition ? `true result` }}
+ * - Multi-line strings in backticks
+ * - Intelligent newline handling (removes empty lines when result is empty)
+ *
+ * @param template The template string containing placeholders
+ * @param variables Object containing variable values
+ * @returns The rendered template string
+ */
+function renderTemplate(template, variables) {
+    // We need to handle nested {{ }} properly, so we'll use a custom approach
+    let result = '';
+    let lastIndex = 0;
+    while (lastIndex < template.length) {
+        // Find the next {{
+        const startIndex = template.indexOf('{{', lastIndex);
+        if (startIndex === -1) {
+            // No more placeholders
+            result += template.substring(lastIndex);
+            break;
+        }
+        // Add everything before the placeholder
+        result += template.substring(lastIndex, startIndex);
+        // Check for leading newline
+        const leadingNewline = startIndex > 0 && template[startIndex - 1] === '\n' ? '\n' : '';
+        // Find the matching }}
+        let depth = 1;
+        let i = startIndex + 2;
+        let inBacktick = false;
+        let expression = '';
+        while (i < template.length && depth > 0) {
+            if (template[i] === '`' && (i === startIndex + 2 || template[i - 1] !== '\\')) {
+                inBacktick = !inBacktick;
+            }
+            else if (!inBacktick) {
+                if (template[i] === '{' && i + 1 < template.length && template[i + 1] === '{') {
+                    depth++;
+                    i++; // Skip the second {
+                }
+                else if (template[i] === '}' && i + 1 < template.length && template[i + 1] === '}') {
+                    depth--;
+                    if (depth === 0) {
+                        expression = template.substring(startIndex + 2, i);
+                        i++; // Skip the second }
+                        break;
+                    }
+                    i++; // Skip the second }
+                }
+            }
+            i++;
+        }
+        if (depth > 0) {
+            // Unmatched {{, treat as literal
+            result += template.substring(startIndex, i);
+            lastIndex = i;
+            continue;
+        }
+        // Check for trailing newline
+        const nextCharIndex = i + 1;
+        const trailingNewline = nextCharIndex < template.length && template[nextCharIndex] === '\n' ? '\n' : '';
+        // Process the expression
+        const processedResult = processExpression(expression.trim(), variables, leadingNewline, trailingNewline);
+        // Add the processed result (which already includes newlines when appropriate)
+        result += processedResult;
+        // Update lastIndex, skipping the trailing newline if the result was empty
+        if (processedResult === '' && trailingNewline) {
+            lastIndex = nextCharIndex + 1;
+        }
+        else {
+            lastIndex = nextCharIndex;
+        }
+    }
+    return result;
+}
+function processExpression(expression, variables, leadingNewline, trailingNewline) {
+    const conditionalMarkerIndex = expression.indexOf('?');
+    let result;
+    if (conditionalMarkerIndex === -1) {
+        // --- Simple variable substitution (backward compatible) ---
+        const key = expression;
+        const value = variables[key];
+        // Handle task context specially - only include if it exists
+        if (key === 'task_context' && (!value || (typeof value === 'string' && value.trim() === ''))) {
+            result = '';
+        }
+        else {
+            result = value !== undefined ? String(value) : '';
+        }
+    }
+    else {
+        // --- Conditional 'ternary' substitution ---
+        const conditionKey = expression.substring(0, conditionalMarkerIndex).trim();
+        const rest = expression.substring(conditionalMarkerIndex + 1).trim();
+        // Parse ternary expression with backtick-delimited strings
+        // We need to handle nested {{ }} within backticks
+        let trueText;
+        let falseText = ''; // Default to empty string if no 'else' part
+        // Try to match backtick format with better handling of nested content
+        if (rest.startsWith('`')) {
+            // Find the matching closing backtick, accounting for escaped backticks
+            let i = 1;
+            let depth = 1;
+            while (i < rest.length && depth > 0) {
+                if (rest[i] === '\\' && i + 1 < rest.length && rest[i + 1] === '`') {
+                    i += 2; // Skip escaped backtick
+                }
+                else if (rest[i] === '`') {
+                    depth--;
+                    i++;
+                }
+                else {
+                    i++;
+                }
+            }
+            if (depth === 0) {
+                // Found matching backtick
+                trueText = rest.substring(1, i - 1);
+                const afterTrue = rest.substring(i).trim();
+                // Check for false part
+                if (afterTrue.startsWith(':')) {
+                    const falsePart = afterTrue.substring(1).trim();
+                    if (falsePart.startsWith('`')) {
+                        // Find matching backtick for false part
+                        let j = 1;
+                        let falseDepth = 1;
+                        while (j < falsePart.length && falseDepth > 0) {
+                            if (falsePart[j] === '\\' && j + 1 < falsePart.length && falsePart[j + 1] === '`') {
+                                j += 2;
+                            }
+                            else if (falsePart[j] === '`') {
+                                falseDepth--;
+                                j++;
+                            }
+                            else {
+                                j++;
+                            }
+                        }
+                        if (falseDepth === 0) {
+                            falseText = falsePart.substring(1, j - 1);
+                        }
+                    }
+                }
+                // Unescape any escaped backticks
+                trueText = trueText.replace(/\\`/g, '`');
+                falseText = falseText.replace(/\\`/g, '`');
+            }
+            else {
+                // No matching backtick found
+                trueText = rest;
+            }
+        }
+        else {
+            // Fallback to old quote-based parsing for backward compatibility
+            const elseMarkerIndex = rest.indexOf(':');
+            if (elseMarkerIndex === -1) {
+                trueText = rest;
+            }
+            else {
+                trueText = rest.substring(0, elseMarkerIndex).trim();
+                falseText = rest.substring(elseMarkerIndex + 1).trim();
+            }
+            // Remove quotes from the start and end of the text parts
+            const unquote = (text) => {
+                if ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'"))) {
+                    return text.slice(1, -1);
+                }
+                return text;
+            };
+            trueText = unquote(trueText);
+            falseText = unquote(falseText);
+        }
+        const conditionValue = !!variables[conditionKey]; // Evaluate truthiness
+        result = conditionValue ? trueText : falseText;
+        // Recursively process the result to handle nested variables
+        if (result.includes('{{')) {
+            result = renderTemplate(result, variables);
+        }
+    }
+    // If result is empty, return empty string without newlines
+    if (result === '') {
+        return '';
+    }
+    // If result is not empty, return just the result without the captured newlines
+    // The newlines are already part of the template structure
+    return result;
+}

package/dist/utils/templateEngine.test.d.ts

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

package/dist/utils/templateEngine.test.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const templateEngine_1 = require("./templateEngine");
+describe('renderTemplate', () => {
+    it('should handle simple variable substitution', () => {
+        const template = 'Hello, {{ name }}!';
+        const result = (0, templateEngine_1.renderTemplate)(template, { name: 'World' });
+        expect(result).toBe('Hello, World!');
+    });
+    it('should handle intelligent newline trimming for empty results', () => {
+        const template = 'Start\n{{ showDetails ? `Details here` : `` }}\nEnd';
+        const result = (0, templateEngine_1.renderTemplate)(template, { showDetails: false });
+        expect(result).toBe('Start\nEnd');
+    });
+    it('should preserve newlines for non-empty results', () => {
+        const template = 'Start\n{{ showDetails ? `Details here` : `` }}\nEnd';
+        const result = (0, templateEngine_1.renderTemplate)(template, { showDetails: true });
+        expect(result).toBe('Start\nDetails here\nEnd');
+    });
+    it('should correctly parse ternary logic with backtick-delimited strings', () => {
+        const template = '{{ condition ? `A` : `B` }}';
+        expect((0, templateEngine_1.renderTemplate)(template, { condition: true })).toBe('A');
+        expect((0, templateEngine_1.renderTemplate)(template, { condition: false })).toBe('B');
+    });
+    it('should handle multi-line strings in backticks', () => {
+        const template = '{{ condition ? `Line 1\nLine 2` : `Single Line` }}';
+        const result = (0, templateEngine_1.renderTemplate)(template, { condition: true });
+        expect(result).toBe('Line 1\nLine 2');
+    });
+    it('should handle ternary expressions with only a true part', () => {
+        const template = 'Data: {{ data ? `{{data}}` : `` }}';
+        expect((0, templateEngine_1.renderTemplate)(template, { data: 'Exists' })).toBe('Data: Exists');
+        expect((0, templateEngine_1.renderTemplate)(template, { data: false })).toBe('Data: ');
+    });
+    it('should handle escaped backticks within the template strings', () => {
+        const template = '{{ flag ? `This is a \\`backtick\\`` : `` }}';
+        const result = (0, templateEngine_1.renderTemplate)(template, { flag: true });
+        expect(result).toBe('This is a `backtick`');
+    });
+    it('should handle undefined variables', () => {
+        const template = 'Value: {{ undefinedVar }}';
+        const result = (0, templateEngine_1.renderTemplate)(template, {});
+        expect(result).toBe('Value: ');
+    });
+    it('should handle boolean values', () => {
+        const template = 'Boolean: {{ boolValue }}';
+        expect((0, templateEngine_1.renderTemplate)(template, { boolValue: true })).toBe('Boolean: true');
+        expect((0, templateEngine_1.renderTemplate)(template, { boolValue: false })).toBe('Boolean: false');
+    });
+    it('should handle numeric values', () => {
+        const template = 'Number: {{ numValue }}';
+        expect((0, templateEngine_1.renderTemplate)(template, { numValue: 42 })).toBe('Number: 42');
+        expect((0, templateEngine_1.renderTemplate)(template, { numValue: 0 })).toBe('Number: 0');
+    });
+    it('should handle nested variable substitution in ternary true branch', () => {
+        const template = '{{ showName ? `Hello, {{name}}!` : `Hello, stranger!` }}';
+        const result = (0, templateEngine_1.renderTemplate)(template, { showName: true, name: 'Alice' });
+        expect(result).toBe('Hello, Alice!');
+    });
+    it('should handle nested variable substitution in ternary false branch', () => {
+        const template = '{{ showName ? `Hello, {{name}}!` : `Hello, {{fallback}}!` }}';
+        const result = (0, templateEngine_1.renderTemplate)(template, { showName: false, fallback: 'Guest' });
+        expect(result).toBe('Hello, Guest!');
+    });
+    it('should handle multiple variable substitutions', () => {
+        const template = '{{ greeting }}, {{ name }}! {{ farewell }}';
+        const result = (0, templateEngine_1.renderTemplate)(template, {
+            greeting: 'Hello',
+            name: 'World',
+            farewell: 'Goodbye'
+        });
+        expect(result).toBe('Hello, World! Goodbye');
+    });
+    it('should handle special task_context variable with empty string', () => {
+        const template = 'Context: {{ task_context }}';
+        expect((0, templateEngine_1.renderTemplate)(template, { task_context: '' })).toBe('Context: ');
+        expect((0, templateEngine_1.renderTemplate)(template, { task_context: '  ' })).toBe('Context: ');
+        expect((0, templateEngine_1.renderTemplate)(template, { task_context: 'Some context' })).toBe('Context: Some context');
+    });
+    it('should handle complex nested templates', () => {
+        const template = `
+Project: {{ projectName }}
+{{ hasFiles ? \`## Files
+{{ fileList }}\` : \`No files selected\` }}
+{{ showSummary ? \`
+## Summary
+{{ summary }}\` : \`\` }}
+End
+`;
+        const result = (0, templateEngine_1.renderTemplate)(template, {
+            projectName: 'MyProject',
+            hasFiles: true,
+            fileList: '- file1.js\n- file2.js',
+            showSummary: false,
+            summary: 'This is a summary'
+        });
+        expect(result).toBe(`
+Project: MyProject
+## Files
+- file1.js
+- file2.js
+End
+`);
+    });
+    it('should handle backward compatible quote-based ternary syntax', () => {
+        const template = '{{ condition ? "True value" : "False value" }}';
+        expect((0, templateEngine_1.renderTemplate)(template, { condition: true })).toBe('True value');
+        expect((0, templateEngine_1.renderTemplate)(template, { condition: false })).toBe('False value');
+    });
+    it('should handle single quotes in backward compatible syntax', () => {
+        const template = "{{ condition ? 'True value' : 'False value' }}";
+        expect((0, templateEngine_1.renderTemplate)(template, { condition: true })).toBe('True value');
+        expect((0, templateEngine_1.renderTemplate)(template, { condition: false })).toBe('False value');
+    });
+    it('should handle whitespace around expressions', () => {
+        const template = '{{   name   }}';
+        const result = (0, templateEngine_1.renderTemplate)(template, { name: 'Test' });
+        expect(result).toBe('Test');
+    });
+    it('should handle whitespace in ternary expressions', () => {
+        const template = '{{   condition   ?   `True`   :   `False`   }}';
+        expect((0, templateEngine_1.renderTemplate)(template, { condition: true })).toBe('True');
+    });
+    it('should handle empty template', () => {
+        const template = '';
+        const result = (0, templateEngine_1.renderTemplate)(template, { any: 'value' });
+        expect(result).toBe('');
+    });
+    it('should handle template with no placeholders', () => {
+        const template = 'Just plain text';
+        const result = (0, templateEngine_1.renderTemplate)(template, { any: 'value' });
+        expect(result).toBe('Just plain text');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genai-lite",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "A lightweight, portable toolkit for interacting with various Generative AI APIs.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",