genai-lite 0.1.4 → 0.2.0

package/README.md

@@ -296,14 +296,14 @@ import type {
 
 ## Utilities
 
-genai-lite includes useful utilities for working with LLMs, available through the `genai-lite/utils` subpath:
+genai-lite includes useful utilities for working with LLMs, available through the `genai-lite/prompting` subpath:
 
 ### Token Counting
 
 Count the number of tokens in a string using OpenAI's tiktoken library:
 
 ```typescript
-import { countTokens } from 'genai-lite/utils';
+import { countTokens } from 'genai-lite/prompting';
 
 const text = 'Hello, this is a sample text for token counting.';
 const tokenCount = countTokens(text); // Uses gpt-4 tokenizer by default
@@ -320,7 +320,7 @@ const gpt35Tokens = countTokens(text, 'gpt-3.5-turbo');
 Generate intelligent previews of large text blocks that preserve context:
 
 ```typescript
-import { getSmartPreview } from 'genai-lite/utils';
+import { getSmartPreview } from 'genai-lite/prompting';
 
 const largeCodeFile = `
 function calculateTotal(items) {
@@ -359,7 +359,7 @@ Combine these utilities to build prompts that fit within model context windows:
 
 ```typescript
 import { LLMService, fromEnvironment } from 'genai-lite';
-import { countTokens, getSmartPreview } from 'genai-lite/utils';
+import { countTokens, getSmartPreview } from 'genai-lite/prompting';
 
 const llm = new LLMService(fromEnvironment);
 
@@ -394,7 +394,7 @@ const response = await llm.sendMessage({
 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';
+import { renderTemplate } from 'genai-lite/prompting';
 
 // Simple variable substitution
 const greeting = renderTemplate('Hello, {{ name }}!', { name: 'World' });
@@ -432,7 +432,7 @@ const result = renderTemplate(complexTemplate, {
   expertise: 'TypeScript, React, Node.js',
   task: 'Review the code for best practices',
   hasFiles: true,
-  fileList: '- src/index.ts\n- src/utils.ts',
+  fileList: '- src/index.ts\n- src/prompting/template.ts',
   requiresOutput: false
 });
 ```
@@ -450,7 +450,7 @@ 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';
+import { renderTemplate, countTokens } from 'genai-lite/prompting';
 
 const llm = new LLMService(fromEnvironment);
 
@@ -491,6 +491,138 @@ const response = await llm.sendMessage({
 });
 ```
 
+### Prompt Builder Utilities
+
+genai-lite provides powerful utilities for building and parsing structured prompts:
+
+#### Parsing Messages from Templates
+
+Convert template strings with role tags into LLM message arrays:
+
+```typescript
+import { buildMessagesFromTemplate } from 'genai-lite/prompting';
+
+const template = `
+<SYSTEM>You are a helpful assistant specialized in {{expertise}}.</SYSTEM>
+<USER>Help me with {{task}}</USER>
+<ASSISTANT>I'll help you with {{task}}. Let me analyze the requirements...</ASSISTANT>
+<USER>Can you provide more details?</USER>
+`;
+
+const messages = buildMessagesFromTemplate(template, {
+  expertise: 'TypeScript and React',
+  task: 'building a custom hook'
+});
+
+// Result: Array of LLMMessage objects ready for the API
+// [
+//   { role: 'system', content: 'You are a helpful assistant specialized in TypeScript and React.' },
+//   { role: 'user', content: 'Help me with building a custom hook' },
+//   { role: 'assistant', content: "I'll help you with building a custom hook. Let me analyze..." },
+//   { role: 'user', content: 'Can you provide more details?' }
+// ]
+```
+
+#### Extracting Random Variables for Few-Shot Learning
+
+Implement few-shot prompting by extracting and shuffling examples:
+
+```typescript
+import { extractRandomVariables, renderTemplate } from 'genai-lite/prompting';
+
+// Define examples in your template
+const examplesTemplate = `
+<RANDOM_INPUT>User: Translate "hello" to Spanish</RANDOM_INPUT>
+<RANDOM_OUTPUT>Assistant: The translation of "hello" to Spanish is "hola".</RANDOM_OUTPUT>
+
+<RANDOM_INPUT>User: Translate "goodbye" to French</RANDOM_INPUT>
+<RANDOM_OUTPUT>Assistant: The translation of "goodbye" to French is "au revoir".</RANDOM_OUTPUT>
+
+<RANDOM_INPUT>User: Translate "thank you" to German</RANDOM_INPUT>
+<RANDOM_OUTPUT>Assistant: The translation of "thank you" to German is "danke".</RANDOM_OUTPUT>
+`;
+
+// Extract random variables (shuffled each time)
+const variables = extractRandomVariables(examplesTemplate, { maxPerTag: 2 });
+
+// Use in a prompt template
+const promptTemplate = `
+You are a translation assistant. Here are some examples:
+
+{{ random_input_1 }}
+{{ random_output_1 }}
+
+{{ random_input_2 }}
+{{ random_output_2 }}
+
+Now translate: "{{word}}" to {{language}}
+`;
+
+const prompt = renderTemplate(promptTemplate, {
+  ...variables,
+  word: 'please',
+  language: 'Italian'
+});
+```
+
+#### Parsing Structured LLM Responses
+
+Extract structured data from LLM responses using custom tags:
+
+```typescript
+import { parseStructuredContent } from 'genai-lite/prompting';
+
+// Example LLM response with structured output
+const llmResponse = `
+Let me analyze this code for you.
+
+<ANALYSIS>
+The code has good structure but could benefit from:
+1. Better error handling in the API calls
+2. Memoization for expensive computations
+3. More descriptive variable names
+</ANALYSIS>
+
+<SUGGESTIONS>
+- Add try-catch blocks around async operations
+- Use React.memo() for the expensive component
+- Rename 'data' to 'userData' for clarity
+</SUGGESTIONS>
+
+<REFACTORED_CODE>
+const UserProfile = React.memo(({ userId }) => {
+  const [userData, setUserData] = useState(null);
+  
+  useEffect(() => {
+    fetchUserData(userId)
+      .then(setUserData)
+      .catch(error => console.error('Failed to load user:', error));
+  }, [userId]);
+  
+  return userData ? <Profile data={userData} /> : <Loading />;
+});
+</REFACTORED_CODE>
+`;
+
+// Parse the structured content
+const parsed = parseStructuredContent(llmResponse, [
+  'ANALYSIS',
+  'SUGGESTIONS',
+  'REFACTORED_CODE'
+]);
+
+console.log(parsed.ANALYSIS);     // The analysis text
+console.log(parsed.SUGGESTIONS);  // The suggestions text
+console.log(parsed.REFACTORED_CODE); // The refactored code
+```
+
+These prompt builder utilities enable:
+- **Structured Conversations**: Build multi-turn conversations from templates
+- **Few-Shot Learning**: Randomly sample examples to improve AI responses
+- **Reliable Output Parsing**: Extract specific sections from AI responses
+- **Template Reusability**: Define templates once, use with different variables
+- **Type Safety**: Full TypeScript support with LLMMessage types
+
 ## 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,4 +5,7 @@ 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";
+export { renderTemplate } from "./prompting/template";
+export { countTokens, getSmartPreview, extractRandomVariables } from "./prompting/content";
+export { buildMessagesFromTemplate } from "./prompting/builder";
+export { parseStructuredContent } from "./prompting/parser";

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.renderTemplate = exports.fromEnvironment = exports.LLMService = void 0;
+exports.parseStructuredContent = exports.buildMessagesFromTemplate = exports.extractRandomVariables = exports.getSmartPreview = exports.countTokens = 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; } });
@@ -26,5 +26,13 @@ __exportStar(require("./llm/clients/types"), exports);
 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; } });
+var template_1 = require("./prompting/template");
+Object.defineProperty(exports, "renderTemplate", { enumerable: true, get: function () { return template_1.renderTemplate; } });
+var content_1 = require("./prompting/content");
+Object.defineProperty(exports, "countTokens", { enumerable: true, get: function () { return content_1.countTokens; } });
+Object.defineProperty(exports, "getSmartPreview", { enumerable: true, get: function () { return content_1.getSmartPreview; } });
+Object.defineProperty(exports, "extractRandomVariables", { enumerable: true, get: function () { return content_1.extractRandomVariables; } });
+var builder_1 = require("./prompting/builder");
+Object.defineProperty(exports, "buildMessagesFromTemplate", { enumerable: true, get: function () { return builder_1.buildMessagesFromTemplate; } });
+var parser_1 = require("./prompting/parser");
+Object.defineProperty(exports, "parseStructuredContent", { enumerable: true, get: function () { return parser_1.parseStructuredContent; } });

package/dist/prompting/builder.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Prompt builder utilities for constructing structured LLM messages
+ *
+ * This module provides functions to construct the final, structured prompts
+ * that will be sent to the LLM service. This is the assembly step that turns
+ * templates and content into the format required by the LLMService.
+ */
+import type { LLMMessage } from '../llm/types';
+/**
+ * Builds an array of LLM messages from a template string with role tags.
+ *
+ * This function takes a template with <SYSTEM>, <USER>, and <ASSISTANT> tags
+ * and constructs a properly formatted array of LLMMessage objects ready to be
+ * sent to an LLM service.
+ *
+ * @param template The template string with {{variables}} and <ROLE> tags.
+ * @param variables An object with values to substitute into the template.
+ * @returns An array of LLMMessage objects.
+ *
+ * @example
+ * const template = `
+ * <SYSTEM>You are a helpful assistant specialized in {{expertise}}.</SYSTEM>
+ * <USER>Help me with {{task}}</USER>
+ * <ASSISTANT>I'll help you with {{task}}. Let me explain...</ASSISTANT>
+ * <USER>Can you provide more details?</USER>
+ * `;
+ *
+ * const messages = buildMessagesFromTemplate(template, {
+ *   expertise: 'TypeScript',
+ *   task: 'understanding generics'
+ * });
+ * // Returns an array of LLMMessage objects with roles and content
+ */
+export declare function buildMessagesFromTemplate(template: string, variables?: Record<string, any>): LLMMessage[];

package/dist/prompting/builder.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Prompt builder utilities for constructing structured LLM messages
+ *
+ * This module provides functions to construct the final, structured prompts
+ * that will be sent to the LLM service. This is the assembly step that turns
+ * templates and content into the format required by the LLMService.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMessagesFromTemplate = buildMessagesFromTemplate;
+const template_1 = require("./template");
+/**
+ * Extracts text content from XML-style tags and returns both the extracted content
+ * and the original string with those sections removed. Handles multiple occurrences
+ * of the same tag.
+ *
+ * @param xmlString String containing XML-style tags to process
+ * @param tagName Name of the tag to extract (without angle brackets)
+ * @returns Tuple containing:
+ *          - Array of extracted content strings, or null if no matches
+ *          - Original string with matched tags and content removed
+ */
+function extractTextAndClean(xmlString, tagName) {
+    if (typeof xmlString !== 'string' || typeof tagName !== 'string') {
+        return [null, xmlString];
+    }
+    const matches = [];
+    const pattern = new RegExp(`<${tagName}>([\\s\\S]*?)<\/${tagName}>`, 'g');
+    let match;
+    let lastIndex = 0;
+    const segments = [];
+    while ((match = pattern.exec(xmlString)) !== null) {
+        if (lastIndex < match.index) {
+            segments.push(xmlString.slice(lastIndex, match.index));
+        }
+        matches.push(match[1]);
+        lastIndex = pattern.lastIndex;
+    }
+    if (lastIndex < xmlString.length) {
+        segments.push(xmlString.slice(lastIndex));
+    }
+    return matches.length > 0 ? [matches, segments.join('')] : [null, xmlString];
+}
+/**
+ * Builds an array of LLM messages from a template string with role tags.
+ *
+ * This function takes a template with <SYSTEM>, <USER>, and <ASSISTANT> tags
+ * and constructs a properly formatted array of LLMMessage objects ready to be
+ * sent to an LLM service.
+ *
+ * @param template The template string with {{variables}} and <ROLE> tags.
+ * @param variables An object with values to substitute into the template.
+ * @returns An array of LLMMessage objects.
+ *
+ * @example
+ * const template = `
+ * <SYSTEM>You are a helpful assistant specialized in {{expertise}}.</SYSTEM>
+ * <USER>Help me with {{task}}</USER>
+ * <ASSISTANT>I'll help you with {{task}}. Let me explain...</ASSISTANT>
+ * <USER>Can you provide more details?</USER>
+ * `;
+ *
+ * const messages = buildMessagesFromTemplate(template, {
+ *   expertise: 'TypeScript',
+ *   task: 'understanding generics'
+ * });
+ * // Returns an array of LLMMessage objects with roles and content
+ */
+function buildMessagesFromTemplate(template, variables) {
+    try {
+        if (typeof template !== 'string') {
+            throw new Error('Template must be a string');
+        }
+        // First, render variables using the existing template engine
+        let processedContent = template;
+        if (variables) {
+            processedContent = (0, template_1.renderTemplate)(template, variables);
+        }
+        // Extract sections for each role
+        const [systemContent, afterSystem] = extractTextAndClean(processedContent, 'SYSTEM');
+        const [userContent, afterUser] = extractTextAndClean(afterSystem, 'USER');
+        const [assistantContent] = extractTextAndClean(afterUser, 'ASSISTANT');
+        const messages = [];
+        // Add system message if present
+        if (systemContent && systemContent.length > 0 && systemContent[0].trim()) {
+            messages.push({
+                role: 'system',
+                content: systemContent[0].trim()
+            });
+        }
+        // Interleave user and assistant messages
+        const maxLength = Math.max(userContent?.length ?? 0, assistantContent?.length ?? 0);
+        for (let i = 0; i < maxLength; i++) {
+            if (userContent && i < userContent.length && userContent[i].trim()) {
+                messages.push({
+                    role: 'user',
+                    content: userContent[i].trim()
+                });
+            }
+            if (assistantContent && i < assistantContent.length && assistantContent[i].trim()) {
+                messages.push({
+                    role: 'assistant',
+                    content: assistantContent[i].trim()
+                });
+            }
+        }
+        return messages;
+    }
+    catch (error) {
+        throw new Error(`Failed to build messages from template: ${error.message}`);
+    }
+}

package/dist/prompting/builder.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for prompt builder utilities
+ */
+export {};

package/dist/prompting/builder.test.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Tests for prompt builder utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const builder_1 = require("./builder");
+describe('buildMessagesFromTemplate', () => {
+    it('should parse a simple template with one of each tag', () => {
+        const template = `
+      <SYSTEM>You are a helpful assistant.</SYSTEM>
+      <USER>Hello!</USER>
+      <ASSISTANT>Hi there! How can I help you?</ASSISTANT>
+    `;
+        const messages = (0, builder_1.buildMessagesFromTemplate)(template);
+        expect(messages).toHaveLength(3);
+        expect(messages[0]).toEqual({
+            role: 'system',
+            content: 'You are a helpful assistant.'
+        });
+        expect(messages[1]).toEqual({
+            role: 'user',
+            content: 'Hello!'
+        });
+        expect(messages[2]).toEqual({
+            role: 'assistant',
+            content: 'Hi there! How can I help you?'
+        });
+    });
+    it('should handle multiple USER and ASSISTANT tags in order', () => {
+        const template = `
+      <SYSTEM>System message</SYSTEM>
+      <USER>First user message</USER>
+      <ASSISTANT>First assistant response</ASSISTANT>
+      <USER>Second user message</USER>
+      <ASSISTANT>Second assistant response</ASSISTANT>
+    `;
+        const messages = (0, builder_1.buildMessagesFromTemplate)(template);
+        expect(messages).toHaveLength(5);
+        expect(messages[0].role).toBe('system');
+        expect(messages[1].role).toBe('user');
+        expect(messages[1].content).toBe('First user message');
+        expect(messages[2].role).toBe('assistant');
+        expect(messages[2].content).toBe('First assistant response');
+        expect(messages[3].role).toBe('user');
+        expect(messages[3].content).toBe('Second user message');
+        expect(messages[4].role).toBe('assistant');
+        expect(messages[4].content).toBe('Second assistant response');
+    });
+    it('should handle template with missing SYSTEM tag', () => {
+        const template = `
+      <USER>Hello</USER>
+      <ASSISTANT>Hi!</ASSISTANT>
+    `;
+        const messages = (0, builder_1.buildMessagesFromTemplate)(template);
+        expect(messages).toHaveLength(2);
+        expect(messages[0].role).toBe('user');
+        expect(messages[1].role).toBe('assistant');
+    });
+    it('should substitute variables inside tags', () => {
+        const template = `
+      <SYSTEM>You are an expert in {{expertise}}.</SYSTEM>
+      <USER>Can you help me with {{topic}}?</USER>
+      <ASSISTANT>I'd be happy to help with {{topic}}!</ASSISTANT>
+    `;
+        const variables = {
+            expertise: 'TypeScript',
+            topic: 'generics'
+        };
+        const messages = (0, builder_1.buildMessagesFromTemplate)(template, variables);
+        expect(messages[0].content).toBe('You are an expert in TypeScript.');
+        expect(messages[1].content).toBe('Can you help me with generics?');
+        expect(messages[2].content).toBe("I'd be happy to help with generics!");
+    });
+    it('should handle empty template string', () => {
+        const messages = (0, builder_1.buildMessagesFromTemplate)('');
+        expect(messages).toEqual([]);
+    });
+    it('should handle template with only whitespace in tags', () => {
+        const template = `
+      <SYSTEM>   </SYSTEM>
+      <USER>Valid message</USER>
+      <ASSISTANT>    </ASSISTANT>
+    `;
+        const messages = (0, builder_1.buildMessagesFromTemplate)(template);
+        expect(messages).toHaveLength(1);
+        expect(messages[0].role).toBe('user');
+        expect(messages[0].content).toBe('Valid message');
+    });
+    it('should throw error for non-string template', () => {
+        expect(() => {
+            (0, builder_1.buildMessagesFromTemplate)(123);
+        }).toThrow('Template must be a string');
+    });
+    it('should handle complex nested variables with conditionals', () => {
+        const template = `
+      <SYSTEM>You are a {{role}}{{ specialized ? \` specialized in {{specialty}}\` : \`\` }}.</SYSTEM>
+      <USER>{{greeting}}</USER>
+    `;
+        const variables = {
+            role: 'assistant',
+            specialized: true,
+            specialty: 'code review',
+            greeting: 'Hello!'
+        };
+        const messages = (0, builder_1.buildMessagesFromTemplate)(template, variables);
+        expect(messages[0].content).toBe('You are a assistant specialized in code review.');
+        expect(messages[1].content).toBe('Hello!');
+    });
+});

package/dist/prompting/content.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Content preparation utilities for prompt engineering
+ *
+ * This module provides utilities that analyze, manipulate, and prepare raw text
+ * content before it's assembled into a final prompt structure. These functions
+ * help prepare the "ingredients" that will be used in prompt construction.
+ */
+import { TiktokenModel } from 'js-tiktoken';
+/**
+ * Counts the number of tokens in a text string using the specified model's tokenizer.
+ *
+ * @param text The text to count tokens for
+ * @param model The model whose tokenizer to use (defaults to 'gpt-4')
+ * @returns The number of tokens in the text
+ */
+export declare function countTokens(text: string, model?: TiktokenModel): number;
+/**
+ * Generates an intelligent preview of content that respects logical boundaries.
+ *
+ * This function truncates content while trying to break at natural points
+ * (empty lines) rather than in the middle of a section.
+ *
+ * @param content The content to preview
+ * @param config Configuration with minLines and maxLines
+ * @returns A truncated preview of the content
+ */
+export declare function getSmartPreview(content: string, config: {
+    minLines: number;
+    maxLines: number;
+}): string;
+/**
+ * Extracts content from <RANDOM_...> tags into a flattened variable object.
+ * This is useful for preparing few-shot examples in prompts.
+ *
+ * @param content The string content containing the random tags.
+ * @param options Configuration options, like the max number of examples per tag.
+ * @returns A record of variables for use in a template engine.
+ *
+ * @example
+ * const content = `
+ * <RANDOM_GREETING>Hello</RANDOM_GREETING>
+ * <RANDOM_GREETING>Hi</RANDOM_GREETING>
+ * <RANDOM_FAREWELL>Goodbye</RANDOM_FAREWELL>
+ * `;
+ *
+ * const result = extractRandomVariables(content, { maxPerTag: 2 });
+ * // Might return:
+ * // {
+ * //   random_greeting_1: "Hi",
+ * //   random_greeting_2: "Hello",
+ * //   random_farewell_1: "Goodbye",
+ * //   random_farewell_2: ""
+ * // }
+ */
+export declare function extractRandomVariables(content: string, options?: {
+    maxPerTag?: number;
+}): Record<string, any>;