@mate-academy/llm-gateway 2.1.4 → 2.1.5

package/README.md

@@ -424,12 +424,14 @@ Interface for converting text to speech audio.
 
 ### Prompt Builder
 
-The LLM Gateway includes a powerful prompt template system that provides type-safe string templates with dynamic replacements. This allows you to create reusable prompt templates with placeholders that can be replaced with actual values at runtime.
+The LLM Gateway includes a powerful prompt template system that provides type-safe string templates with dynamic replacements and conditional sections. This allows you to create reusable prompt templates with placeholders that can be replaced with actual values at runtime.
 
 #### Features
 
 - **Type Safety**: Automatic extraction and validation of placeholder keys from template strings
 - **Dynamic Replacements**: Replace placeholders like `{{variableName}}` with actual values
+- **Conditional Sections**: Show or hide content based on variable values using `{{#condition}}...{{/condition}}` syntax
+- **Nested Conditionals**: Support for nested conditional sections for complex logic
 - **Template Reusability**: Create templates once and use them multiple times with different values
 - **Zero Runtime Dependencies**: Pure TypeScript utility functions
 
@@ -454,6 +456,74 @@ const instruction = welcomePrompt({
 // Result: "Generate a welcome message for a user who has just started their auto tech check attempt on JavaScript Basics. The user's experience level is beginner and they prefer hands-on learning."
 ```
 
+#### Conditional Sections
+
+Conditional sections allow you to show or hide parts of the template based on variable values:
+
+```typescript
+// Template with conditional sections
+const coursePrompt = createPromptTemplate(`
+  Generate a lesson plan for {{topicTitle}}.
+  {{#hasPrerequisites}}
+  Prerequisites: {{prerequisites}}
+  {{/hasPrerequisites}}
+
+  {{#includeExercises}}
+  Include practical exercises and code examples.
+  {{/includeExercises}}
+
+  {{#difficultyLevel}}
+  Adjust content for {{difficultyLevel}} level students.
+  {{/difficultyLevel}}
+`);
+
+// Usage with all sections visible
+const fullLesson = coursePrompt({
+  topicTitle: 'React Hooks',
+  hasPrerequisites: true,
+  prerequisites: 'Basic React knowledge',
+  includeExercises: true,
+  difficultyLevel: 'intermediate'
+});
+
+// Usage with some sections hidden
+const basicLesson = coursePrompt({
+  topicTitle: 'React Hooks',
+  hasPrerequisites: false,
+  includeExercises: false,
+  difficultyLevel: 'beginner'
+});
+```
+
+#### Nested Conditional Sections
+
+You can nest conditional sections for more complex logic:
+
+```typescript
+const reviewPrompt = createPromptTemplate(`
+  Review the {{language}} code for {{focusArea}}.
+  {{#includeMetrics}}
+  Provide performance metrics.
+  {{#includeDetailed}}
+  Include detailed benchmark analysis and memory usage patterns.
+  {{/includeDetailed}}
+  {{/includeMetrics}}
+
+  {{#suggestImprovements}}
+  Suggest specific improvements for better {{improvementFocus}}.
+  {{/suggestImprovements}}
+`);
+
+const detailedReview = reviewPrompt({
+  language: 'TypeScript',
+  focusArea: 'performance',
+  includeMetrics: true,
+  includeDetailed: true,
+  suggestImprovements: true,
+  improvementFocus: 'scalability'
+});
+```
+
 #### Advanced Usage
 
 ```typescript
@@ -463,21 +533,32 @@ const staticPrompt = createPromptTemplate(`
 `);
 const staticInstruction = staticPrompt(); // No parameters needed
 
-// Template with multiple placeholders
+// Template with multiple placeholders and conditional sections
 const codeReviewPrompt = createPromptTemplate(`
   Review the {{language}} code below for {{focusArea}}.
+  {{#includeCriteria}}
   Pay special attention to {{criteria}} and provide {{outputFormat}} feedback.
+  {{/includeCriteria}}
 
+  {{#includeCode}}
   Code:
   {{codeSnippet}}
+  {{/includeCode}}
+
+  {{#provideExamples}}
+  Include examples of best practices for {{language}}.
+  {{/provideExamples}}
 `);
 
 const reviewInstruction = codeReviewPrompt({
   language: 'TypeScript',
   focusArea: 'performance optimization',
+  includeCriteria: true,
   criteria: 'algorithmic efficiency and memory usage',
   outputFormat: 'structured',
+  includeCode: true,
   codeSnippet: 'function example() { /* code here */ }',
+  provideExamples: false
 });
 ```
 
@@ -495,32 +576,58 @@ import {
 const PROMPTS = {
   codeExplanation: createPromptTemplate(`
     Explain the following {{language}} code in simple terms for a {{level}} developer:
+    {{#includeContext}}
+    Context: {{context}}
+    {{/includeContext}}
+
     {{code}}
+
+    {{#includeExamples}}
+    Provide practical examples of how this code would be used.
+    {{/includeExamples}}
   `),
 
   bugFinding: createPromptTemplate(`
     Find potential bugs in this {{language}} code and suggest fixes:
+    {{#focusArea}}
+    Focus specifically on {{focusArea}} issues.
+    {{/focusArea}}
+
     {{code}}
+
+    {{#includeSeverity}}
+    Rate the severity of each issue from 1-5.
+    {{/includeSeverity}}
   `),
 
   optimization: createPromptTemplate(`
     Optimize the following code for {{optimizationType}}:
     {{code}}
+
+    {{#includeMetrics}}
+    Provide before/after performance metrics.
+    {{/includeMetrics}}
+
+    {{#includeAlternatives}}
+    Suggest alternative approaches and explain trade-offs.
+    {{/includeAlternatives}}
   `),
 };
 
 // Use with completion service
-async function explainCode(code: string, language: string, level: string) {
+async function explainCode(code: string, language: string, level: string, includeExamples = false) {
   const prompt = PROMPTS.codeExplanation({
     code,
     language,
     level,
+    includeContext: false,
+    includeExamples,
   });
 
   return await completionService.sendMessage({
     message: {
       role: LLMRoles.User,
-      content: [prompt],
+      content: [{ type: LLMMessageContentType.TEXT, text: prompt }],
     },
     model: preferredModel,
   });
@@ -529,20 +636,41 @@ async function explainCode(code: string, language: string, level: string) {
 
 #### Type Safety Features
 
-The prompt builder provides compile-time type checking for template placeholders:
+The prompt builder provides compile-time type checking for template placeholders and conditional sections:
 
 ```typescript
 // This will show TypeScript errors for missing or incorrect parameters
-const template = createPromptTemplate(`Hello {{name}}, welcome to {{platform}}!`);
+const template = createPromptTemplate(`
+  Hello {{name}}, welcome to {{platform}}!
+  {{#showBonus}}You have a bonus: {{bonusAmount}}{{/showBonus}}
+`);
 
-// ✅ Correct usage
-template({ name: 'John', platform: 'LLM Gateway' });
+// ✅ Correct usage with all required variables
+template({
+  name: 'John',
+  platform: 'LLM Gateway',
+  showBonus: true,
+  bonusAmount: '$50'
+});
+
+// ✅ Correct usage with conditional section hidden
+template({
+  name: 'John',
+  platform: 'LLM Gateway',
+  showBonus: false
+  // bonusAmount is not required when showBonus is false
+});
 
 // ❌ TypeScript error: missing required parameter 'platform'
-template({ name: 'John' });
+template({ name: 'John', showBonus: false });
 
 // ❌ TypeScript error: unknown parameter 'age'
-template({ name: 'John', platform: 'LLM Gateway', age: 25 });
+template({
+  name: 'John',
+  platform: 'LLM Gateway',
+  showBonus: false,
+  age: 25
+});
 ```
 
 #### API Reference
@@ -552,16 +680,30 @@ template({ name: 'John', platform: 'LLM Gateway', age: 25 });
 Creates a prompt template function from a template string.
 
 - **Parameters:**
-  - `template: T` - The template string with placeholders in `{{variableName}}` format
+  - `template: T` - The template string with placeholders and conditional sections
 - **Returns:** A function that accepts replacement values and returns the processed string
-- **Type Safety:** Automatically extracts placeholder names from the template string for type checking
+- **Type Safety:** Automatically extracts placeholder names and conditional section names from the template string for type checking
 
-**Template Placeholder Format**
+**Template Syntax**
 
+**Variable Placeholders:**
 - Placeholders must be enclosed in double curly braces: `{{variableName}}`
 - Whitespace around variable names is ignored: `{{ variableName }}` works the same as `{{variableName}}`
 - Variable names can contain letters, numbers, and underscores
-- Replacement values can be strings or numbers (automatically converted to strings)
+- Replacement values can be strings, numbers, or booleans (automatically converted to strings)
+
+**Conditional Sections:**
+- Conditional sections use the syntax: `{{#conditionName}}content{{/conditionName}}`
+- The section content is included only if the condition variable is truthy
+- Truthy values: `true`, non-empty strings, non-zero numbers
+- Falsy values: `false`, empty strings, `0`, `null`, `undefined`
+- Conditional variables are optional in the type system when used only as conditions
+- Variables used both as conditions and values are required in the type system
+
+**Nested Conditionals:**
+- Conditional sections can be nested for complex logic
+- Inner sections are processed only if outer sections are visible
+- Variables inside nested sections follow the same truthy/falsy rules
 
 ## Supported Providers
 

package/dist/promptBuilder.d.ts

@@ -1,5 +1,5 @@
 /**
- * Utility types and functions for handling prompts with dynamic replacements.
+ * Utility types and functions for handling prompts with dynamic replacements and conditional sections.
  * This allows for type-safe string templates with placeholders that can be replaced with actual values.
  * The `createPromptTemplate` function helps create typed prompts with automatic extraction of replacement keys.
  *
@@ -9,20 +9,41 @@
  * const PROMPTS = {
  *   welcomeMessage: createPromptTemplate(`
  *     Generate a welcome message for a user who has just started their auto tech check attempt on {{topicTitle}}.
+ *     {{#hasBonus}}
+ *       This topic includes bonus content: {{bonusContent}}
+ *     {{/hasBonus}}
+ *
+ *     {{#valueAsCondition}}
+ *       This is a conditional section that will only appear if the value is truthy.
+ *       Value can be used inside the section: {{valueAsCondition}}
+ *     {{/valueAsCondition}}
  *  `),
  * };
  *
- * const instruction = PROMPTS.welcomeMessage({ topicTitle: 'JavaScript Basics' });
+ * const instruction = PROMPTS.welcomeMessage({
+ *   topicTitle: 'JavaScript Basics',
+ *   hasBonus: true,
+ *   bonusContent: 'Advanced debugging techniques',
+ * });
  *
  * // This will generate a prompt:
- * // "Generate a welcome message for a user who has just started their auto tech check attempt on JavaScript Basics."
+ * // "Generate a welcome message for a user who has just started their auto tech check attempt on JavaScript Basics.
+ * //  This topic includes bonus content: Advanced debugging techniques"
  */
-type ExtractReplacements<T extends string> = T extends `${string}{{${infer Key}}}${infer Rest}` ? Key extends `${infer CleanKey}` ? CleanKey | ExtractReplacements<Rest> : never : never;
+type Value = string | number | boolean;
+type ExtractAllVariables<T extends string> = T extends `${string}{{${infer Key}}}${infer Rest}` ? Key extends `${infer CleanKey}` ? CleanKey | ExtractAllVariables<Rest> : never : never;
+type ExtractSectionVariables<T extends string> = T extends `${string}{{#${infer Key}}}${infer Rest}` ? Key | ExtractSectionVariables<Rest> : T extends `${string}{{/${infer Key}}}${infer Rest}` ? Key | ExtractSectionVariables<Rest> : never;
+type ExtractRegularVariables<T extends string> = ExtractAllVariables<T> extends infer All ? All extends string ? All extends `#${string}` | `/${string}` ? never : All : never : never;
+type CreateVariableRecord<T extends string> = ExtractRegularVariables<T> extends never ? ExtractSectionVariables<T> extends never ? Record<string, never> : Record<ExtractSectionVariables<T>, Value> : ExtractSectionVariables<T> extends never ? Record<ExtractRegularVariables<T>, Value> : Omit<Record<ExtractRegularVariables<T>, Value>, ExtractSectionVariables<T>> & Partial<Record<ExtractSectionVariables<T>, Value>>;
+type HasVariables<T extends string> = ExtractAllVariables<T> extends never ? false : true;
 /**
- * Creates a prompt template function that can be used to generate prompts with dynamic replacements.
+ * Creates a prompt template function that can be used to generate prompts with dynamic replacements and conditional sections.
  * @template T The type of the template string. Inferred from the provided template.
- * @param {T} template The template string with placeholders for dynamic values (e.g., `{{topicTitle}}`).
+ * @param {T} template The template string with placeholders:
+ * - for dynamic values (e.g., `{{topicTitle}}`)
+ * - for conditional sections (e.g., `{{#section}}...{{/section}}`)
+ * - for sections that use conditional variables as values (e.g., `{{#bonus}}...{{bonus}}...{{/bonus}}`)
  * @returns A function that takes the dynamic values and returns the generated prompt.
  */
-export declare function createPromptTemplate<T extends string>(template: T): (...args: ExtractReplacements<T> extends never ? [] : [variables: Record<ExtractReplacements<T>, string | number>]) => string;
+export declare function createPromptTemplate<T extends string>(template: T): (...args: HasVariables<T> extends false ? [] : [variables: CreateVariableRecord<T>]) => string;
 export {};

package/dist/promptBuilder.js

@@ -1 +1 @@
-"use strict";function promptBuilder(e,t){return t?Object.entries(t).reduce((e,[t,r])=>e.replace(new RegExp(`{{\\s*${t}\\s*}}`,"g"),String(r)),e):e}function createPromptTemplate(e){const t=e.trim();return(...e)=>promptBuilder(t,...e)}Object.defineProperty(exports,"__esModule",{value:!0}),exports.createPromptTemplate=createPromptTemplate;
+"use strict";function promptBuilder(e,t){if(!t)return e;const r=e=>Object.entries(t).reduce((e,[t,r])=>e.replace(new RegExp(`{{\\s*${t}\\s*}}`,"g"),String(r)),e),n=e=>e.replace(/{{#(\w+)}}([\s\S]*?){{\/\1}}/g,(e,p,c)=>{if(t[p]){const e=n(c);return r(e)}return""});let p=e;return p=n(p),p=r(p),p}function createPromptTemplate(e){const t=e.trim();return(...e)=>promptBuilder(t,...e)}Object.defineProperty(exports,"__esModule",{value:!0}),exports.createPromptTemplate=createPromptTemplate;

package/dist/promptBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"promptBuilder.js","sourceRoot":"","sources":["../src/promptBuilder.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;AA2CH,oDAQC;AA1BD,SAAS,aAAa,CACpB,MAAc,EACd,SAA2C;IAE3C,OAAO,SAAS;QACd,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,MAAM,CAChC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,SAAS,GAAG,QAAQ,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EACxF,MAAM,CACP;QACD,CAAC,CAAC,MAAM,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAmB,QAAW;IAChE,MAAM,eAAe,GAAG,QAAQ,CAAC,IAAI,EAAO,CAAC;IAE7C,OAAO,CACL,GAAG,IAE6D,EACxD,EAAE,CAAC,aAAa,CAAC,eAAe,EAAE,GAAG,IAAI,CAAC,CAAC;AACvD,CAAC"}
+{"version":3,"file":"promptBuilder.js","sourceRoot":"","sources":["../src/promptBuilder.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;AAoHH,oDAQC;AA1DD,SAAS,aAAa,CACpB,MAAc,EACd,SAAiC;IAEjC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,gBAAgB,GAAG,CAAC,MAAc,EAAU,EAAE,CAAC;IACnD,+DAA+D;IAC/D,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CACtD,GAAG,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,SAAS,GAAG,QAAQ,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAClE,EAAE,MAAM,CAAC,CACX,CAAC;IAEF,MAAM,0BAA0B,GAAG,CAAC,MAAc,EAAU,EAAE;QAC5D,qEAAqE;QACrE,OAAO,MAAM,CAAC,OAAO,CAAC,+BAA+B,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE;YACjF,MAAM,KAAK,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;YAErC,IAAI,KAAK,EAAE,CAAC;gBACV,6EAA6E;gBAC7E,MAAM,gBAAgB,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC;gBAC7D,OAAO,gBAAgB,CAAC,gBAAgB,CAAC,CAAC;YAC5C,CAAC;YAED,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,IAAI,MAAM,GAAG,MAAM,CAAC;IAEpB,mFAAmF;IACnF,MAAM,GAAG,0BAA0B,CAAC,MAAM,CAAC,CAAC;IAE5C,6CAA6C;IAC7C,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAElC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,oBAAoB,CAAmB,QAAW;IAChE,MAAM,eAAe,GAAG,QAAQ,CAAC,IAAI,EAAO,CAAC;IAE7C,OAAO,CACL,GAAG,IAEqC,EAChC,EAAE,CAAC,aAAa,CAAC,eAAe,EAAE,GAAG,IAAI,CAAC,CAAC;AACvD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mate-academy/llm-gateway",
-  "version": "2.1.4",
+  "version": "2.1.5",
   "description": "A gateway package for LLM services.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",