@kognitivedev/vercel-ai-provider 0.1.9 → 0.2.0

package/README.md

@@ -151,7 +151,7 @@ Used with `cl.streamText()` and `cl.generateText()` to reference a managed promp
 ```typescript
 interface PromptConfig {
     slug: string;
-    variables?: Record<string, string>;
+    variables?: Record<string, string | boolean>;
 }
 ```
 
@@ -265,7 +265,69 @@ const { text } = await generateText({
 
 Use `cl.streamText()` and `cl.generateText()` to resolve prompts by slug from the backend. Prompts are fetched from the `/api/cognitive/prompt` endpoint and cached for 60 seconds.
 
-Template variables use `{{variable}}` syntax and are interpolated before the prompt is sent to the model.
+Prompt templates use [Handlebars](https://handlebarsjs.com/) syntax, giving you variable interpolation and conditional blocks. This means prompts can be fully managed from the dashboard without any string concatenation in application code.
+
+#### Template Syntax
+
+**Variable interpolation** — insert a value by name:
+
+```handlebars
+Hello {{userName}}, welcome to {{companyName}}.
+```
+
+**Conditional blocks** — include content only when a variable is truthy:
+
+```handlebars
+{{#if hasImages}}
+The user has attached images. Please analyze them.
+{{/if}}
+```
+
+**If / else** — provide a fallback when the condition is falsy:
+
+```handlebars
+{{#if isPremium}}
+You have access to all features.
+{{else}}
+Upgrade to premium for full access.
+{{/if}}
+```
+
+**Unless** — inverse of `if`, includes the block when the variable is falsy:
+
+```handlebars
+{{#unless hasHistory}}
+This is a new user. Introduce yourself.
+{{/unless}}
+```
+
+**Nesting** — conditionals can be nested arbitrarily:
+
+```handlebars
+{{#if hasAttachments}}
+  Attachments provided.
+  {{#if hasImages}}
+    Includes images for visual analysis.
+  {{/if}}
+{{/if}}
+```
+
+#### Variable Types
+
+Variables can be `string` or `boolean`:
+
+| Type | Truthy | Falsy |
+|------|--------|-------|
+| `string` | Any non-empty string | `""` (empty string) |
+| `boolean` | `true` | `false` |
+
+Undefined variables render as empty string in interpolation and are treated as falsy in conditionals.
+
+> **Note:** Content is not HTML-escaped — prompt text passes through as-is, which is the correct behavior for LLM prompts.
+
+#### Usage with `cl.streamText()` / `cl.generateText()`
+
+Pass variables in the `prompt.variables` field:
 
 ```typescript
 // Stream with a managed prompt
@@ -275,13 +337,15 @@ const result = await cl.streamText({
         sessionId: "session-abc"
     }),
     prompt: {
-        slug: "customer-support",
+        slug: "fitness-coach",
         variables: {
-            companyName: "Acme Corp",
-            language: "English"
+            userName: "Sarah",
+            fitnessGoal: "Build muscle",
+            hasImages: true,
+            hasAttachments: false
         }
     },
-    messages: [{ role: "user", content: "I need help with my order" }]
+    messages: [{ role: "user", content: "Check my squat form" }]
 });
 
 for await (const chunk of result.textStream) {
@@ -290,19 +354,59 @@ for await (const chunk of result.textStream) {
 ```
 
 ```typescript
-// Generate with a managed prompt
+// Generate with a managed prompt (string-only variables work too)
 const { text } = await cl.generateText({
     model: cl("gpt-4o", {
         userId: "user-123",
         sessionId: "session-abc"
     }),
     prompt: {
-        slug: "summarizer"
+        slug: "summarizer",
+        variables: {
+            language: "English"
+        }
     },
     messages: [{ role: "user", content: "Summarize this document..." }]
 });
 ```
 
+#### Standalone `renderTemplate()`
+
+The template engine is also exported directly for use outside of prompt management:
+
+```typescript
+import { renderTemplate } from "@kognitivedev/vercel-ai-provider";
+
+const result = renderTemplate(
+    "Hello {{name}}! {{#if isVip}}Welcome back, VIP.{{/if}}",
+    { name: "Alice", isVip: true }
+);
+// → "Hello Alice! Welcome back, VIP."
+```
+
+#### Full Example Template
+
+A prompt template stored in the dashboard might look like:
+
+```handlebars
+You are a fitness coach AI assistant.
+
+User: {{userName}}
+Goal: {{fitnessGoal}}
+
+{{#if hasImages}}
+The user has attached images for form analysis. Please review them carefully.
+{{/if}}
+{{#if hasAttachments}}
+Additional documents have been provided for context.
+{{/if}}
+{{#unless hasHistory}}
+This is a new user with no prior conversation history. Introduce yourself.
+{{/unless}}
+
+Please provide personalized advice.
+```
+
 ### Gateway Routing
 
 When a prompt has a `gatewaySlug` configured on the backend, requests are automatically routed through the gateway endpoint at `{baseUrl}/api/cognitive/gateway/{gatewaySlug}`.

package/dist/__tests__/template.test.d.ts

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

package/dist/__tests__/template.test.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const template_1 = require("../template");
+(0, vitest_1.describe)("renderTemplate", () => {
+    (0, vitest_1.describe)("variable interpolation", () => {
+        (0, vitest_1.it)("replaces a single variable", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("Hello {{name}}", { name: "Alice" })).toBe("Hello Alice");
+        });
+        (0, vitest_1.it)("replaces multiple variables", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("{{greeting}}, {{name}}!", { greeting: "Hi", name: "Bob" })).toBe("Hi, Bob!");
+        });
+        (0, vitest_1.it)("renders undefined variables as empty string", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("Hello {{name}}", {})).toBe("Hello ");
+        });
+        (0, vitest_1.it)("does not HTML-escape content", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("{{content}}", { content: "<b>bold</b> & \"quoted\"" })).toBe("<b>bold</b> & \"quoted\"");
+        });
+    });
+    (0, vitest_1.describe)("{{#if}} / {{/if}}", () => {
+        (0, vitest_1.it)("includes block when variable is truthy string", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("start{{#if show}} visible{{/if}} end", { show: "yes" })).toBe("start visible end");
+        });
+        (0, vitest_1.it)("includes block when variable is true", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("start{{#if show}} visible{{/if}} end", { show: true })).toBe("start visible end");
+        });
+        (0, vitest_1.it)("excludes block when variable is false", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("start{{#if show}} visible{{/if}} end", { show: false })).toBe("start end");
+        });
+        (0, vitest_1.it)("excludes block when variable is undefined", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("start{{#if show}} visible{{/if}} end", {})).toBe("start end");
+        });
+        (0, vitest_1.it)("excludes block when variable is empty string", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("start{{#if show}} visible{{/if}} end", { show: "" })).toBe("start end");
+        });
+    });
+    (0, vitest_1.describe)("{{#unless}} / {{/unless}}", () => {
+        (0, vitest_1.it)("includes block when variable is falsy", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("{{#unless premium}}Free tier{{/unless}}", { premium: false })).toBe("Free tier");
+        });
+        (0, vitest_1.it)("excludes block when variable is truthy", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("{{#unless premium}}Free tier{{/unless}}", { premium: true })).toBe("");
+        });
+    });
+    (0, vitest_1.describe)("{{else}} branches", () => {
+        (0, vitest_1.it)("renders else branch when if condition is false", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("{{#if vip}}VIP access{{else}}Standard access{{/if}}", { vip: false })).toBe("Standard access");
+        });
+        (0, vitest_1.it)("renders if branch when condition is true", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("{{#if vip}}VIP access{{else}}Standard access{{/if}}", { vip: true })).toBe("VIP access");
+        });
+    });
+    (0, vitest_1.describe)("nested conditionals", () => {
+        (0, vitest_1.it)("handles nested if blocks", () => {
+            const template = "{{#if a}}A{{#if b}}-B{{/if}}{{/if}}";
+            (0, vitest_1.expect)((0, template_1.renderTemplate)(template, { a: true, b: true })).toBe("A-B");
+            (0, vitest_1.expect)((0, template_1.renderTemplate)(template, { a: true, b: false })).toBe("A");
+            (0, vitest_1.expect)((0, template_1.renderTemplate)(template, { a: false, b: true })).toBe("");
+        });
+    });
+    (0, vitest_1.describe)("variables inside conditionals", () => {
+        (0, vitest_1.it)("interpolates variables within conditional blocks", () => {
+            (0, vitest_1.expect)((0, template_1.renderTemplate)("{{#if hasName}}Name: {{name}}{{/if}}", { hasName: true, name: "Alice" })).toBe("Name: Alice");
+        });
+    });
+    (0, vitest_1.describe)("real-world fitness app template", () => {
+        const template = `You are a fitness coach AI assistant.
+
+User: {{userName}}
+Goal: {{fitnessGoal}}
+
+{{#if hasImages}}
+The user has attached images for form analysis. Please review them carefully.
+{{/if}}
+{{#if hasAttachments}}
+Additional documents have been provided for context.
+{{/if}}
+{{#unless hasHistory}}
+This is a new user with no prior conversation history. Introduce yourself.
+{{/unless}}
+
+Please provide personalized advice.`;
+        (0, vitest_1.it)("renders with all flags true", () => {
+            const result = (0, template_1.renderTemplate)(template, {
+                userName: "Sarah",
+                fitnessGoal: "Build muscle",
+                hasImages: true,
+                hasAttachments: true,
+                hasHistory: true,
+            });
+            (0, vitest_1.expect)(result).toContain("User: Sarah");
+            (0, vitest_1.expect)(result).toContain("Goal: Build muscle");
+            (0, vitest_1.expect)(result).toContain("attached images for form analysis");
+            (0, vitest_1.expect)(result).toContain("Additional documents");
+            (0, vitest_1.expect)(result).not.toContain("new user with no prior");
+        });
+        (0, vitest_1.it)("renders with all flags false", () => {
+            const result = (0, template_1.renderTemplate)(template, {
+                userName: "Tom",
+                fitnessGoal: "Lose weight",
+                hasImages: false,
+                hasAttachments: false,
+                hasHistory: false,
+            });
+            (0, vitest_1.expect)(result).toContain("User: Tom");
+            (0, vitest_1.expect)(result).toContain("Goal: Lose weight");
+            (0, vitest_1.expect)(result).not.toContain("attached images");
+            (0, vitest_1.expect)(result).not.toContain("Additional documents");
+            (0, vitest_1.expect)(result).toContain("new user with no prior");
+        });
+    });
+});

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { streamText as aiStreamText, generateText as aiGenerateText, type LanguageModel } from "ai";
+export { renderTemplate, type TemplateVariables } from "./template";
 /**
  * Log levels for controlling verbosity of CognitiveLayer logging.
  * - 'none': No logging
@@ -36,7 +37,7 @@ export type CLModelWrapper = (modelId: string, settings?: {
 }, providerOptions?: Record<string, unknown>) => LanguageModel;
 export interface PromptConfig {
     slug: string;
-    variables?: Record<string, string>;
+    variables?: Record<string, string | boolean>;
 }
 export type CLStreamTextOptions = Omit<Parameters<typeof aiStreamText>[0], 'system' | 'prompt'> & {
     prompt: PromptConfig;

package/dist/index.js

@@ -11,9 +11,13 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTemplate = void 0;
 exports.createCognitiveLayer = createCognitiveLayer;
 const ai_1 = require("ai");
 const crypto_1 = require("crypto");
+var template_1 = require("./template");
+Object.defineProperty(exports, "renderTemplate", { enumerable: true, get: function () { return template_1.renderTemplate; } });
+const template_2 = require("./template");
 function isValidId(value) {
     if (value == null || typeof value !== "string")
         return false;
@@ -154,13 +158,6 @@ function buildTraceSpansFromMessages(messages) {
     }
     return spans;
 }
-/**
- * Interpolate {{variable}} placeholders in a template string.
- * Unmatched variables are left as-is.
- */
-function interpolateTemplate(content, variables) {
-    return content.replace(/\{\{(\w+)\}\}/g, (_, key) => { var _a; return (_a = variables[key]) !== null && _a !== void 0 ? _a : `{{${key}}}`; });
-}
 // Session-scoped snapshot cache: sessionKey → formatted memory block
 const sessionSnapshots = new Map();
 // Regex to detect if memory has already been injected
@@ -640,7 +637,7 @@ ${userContextBlock || "None"}
         let system;
         if (resolved) {
             system = promptConfig.variables
-                ? interpolateTemplate(resolved.content, promptConfig.variables)
+                ? (0, template_2.renderTemplate)(resolved.content, promptConfig.variables)
                 : resolved.content;
             // Store prompt metadata for the session (read by middleware during logging)
             if (session === null || session === void 0 ? void 0 : session.sessionId) {
@@ -679,7 +676,7 @@ ${userContextBlock || "None"}
         let system;
         if (resolved) {
             system = promptConfig.variables
-                ? interpolateTemplate(resolved.content, promptConfig.variables)
+                ? (0, template_2.renderTemplate)(resolved.content, promptConfig.variables)
                 : resolved.content;
             // Store prompt metadata for the session (read by middleware during logging)
             if (session === null || session === void 0 ? void 0 : session.sessionId) {

package/dist/template.d.ts

@@ -0,0 +1,2 @@
+export type TemplateVariables = Record<string, string | boolean>;
+export declare function renderTemplate(template: string, variables: TemplateVariables): string;

package/dist/template.js

@@ -0,0 +1,13 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTemplate = renderTemplate;
+// Use the pre-built dist to avoid `require.extensions` warning in webpack/Next.js
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const handlebars_1 = __importDefault(require("handlebars/dist/cjs/handlebars"));
+function renderTemplate(template, variables) {
+    const compiled = handlebars_1.default.compile(template, { noEscape: true });
+    return compiled(variables);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kognitivedev/vercel-ai-provider",
-    "version": "0.1.9",
+    "version": "0.2.0",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "publishConfig": {
@@ -12,6 +12,9 @@
         "test": "vitest run",
         "prepublishOnly": "npm run build"
     },
+    "dependencies": {
+        "handlebars": "^4.7.8"
+    },
     "peerDependencies": {
         "ai": "^5.0.0 || ^6.0.0"
     },

package/src/__tests__/template.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect } from "vitest";
+import { renderTemplate } from "../template";
+
+describe("renderTemplate", () => {
+    describe("variable interpolation", () => {
+        it("replaces a single variable", () => {
+            expect(renderTemplate("Hello {{name}}", { name: "Alice" })).toBe("Hello Alice");
+        });
+
+        it("replaces multiple variables", () => {
+            expect(
+                renderTemplate("{{greeting}}, {{name}}!", { greeting: "Hi", name: "Bob" })
+            ).toBe("Hi, Bob!");
+        });
+
+        it("renders undefined variables as empty string", () => {
+            expect(renderTemplate("Hello {{name}}", {})).toBe("Hello ");
+        });
+
+        it("does not HTML-escape content", () => {
+            expect(renderTemplate("{{content}}", { content: "<b>bold</b> & \"quoted\"" })).toBe(
+                "<b>bold</b> & \"quoted\""
+            );
+        });
+    });
+
+    describe("{{#if}} / {{/if}}", () => {
+        it("includes block when variable is truthy string", () => {
+            expect(
+                renderTemplate("start{{#if show}} visible{{/if}} end", { show: "yes" })
+            ).toBe("start visible end");
+        });
+
+        it("includes block when variable is true", () => {
+            expect(
+                renderTemplate("start{{#if show}} visible{{/if}} end", { show: true })
+            ).toBe("start visible end");
+        });
+
+        it("excludes block when variable is false", () => {
+            expect(
+                renderTemplate("start{{#if show}} visible{{/if}} end", { show: false })
+            ).toBe("start end");
+        });
+
+        it("excludes block when variable is undefined", () => {
+            expect(
+                renderTemplate("start{{#if show}} visible{{/if}} end", {})
+            ).toBe("start end");
+        });
+
+        it("excludes block when variable is empty string", () => {
+            expect(
+                renderTemplate("start{{#if show}} visible{{/if}} end", { show: "" })
+            ).toBe("start end");
+        });
+    });
+
+    describe("{{#unless}} / {{/unless}}", () => {
+        it("includes block when variable is falsy", () => {
+            expect(
+                renderTemplate("{{#unless premium}}Free tier{{/unless}}", { premium: false })
+            ).toBe("Free tier");
+        });
+
+        it("excludes block when variable is truthy", () => {
+            expect(
+                renderTemplate("{{#unless premium}}Free tier{{/unless}}", { premium: true })
+            ).toBe("");
+        });
+    });
+
+    describe("{{else}} branches", () => {
+        it("renders else branch when if condition is false", () => {
+            expect(
+                renderTemplate(
+                    "{{#if vip}}VIP access{{else}}Standard access{{/if}}",
+                    { vip: false }
+                )
+            ).toBe("Standard access");
+        });
+
+        it("renders if branch when condition is true", () => {
+            expect(
+                renderTemplate(
+                    "{{#if vip}}VIP access{{else}}Standard access{{/if}}",
+                    { vip: true }
+                )
+            ).toBe("VIP access");
+        });
+    });
+
+    describe("nested conditionals", () => {
+        it("handles nested if blocks", () => {
+            const template = "{{#if a}}A{{#if b}}-B{{/if}}{{/if}}";
+            expect(renderTemplate(template, { a: true, b: true })).toBe("A-B");
+            expect(renderTemplate(template, { a: true, b: false })).toBe("A");
+            expect(renderTemplate(template, { a: false, b: true })).toBe("");
+        });
+    });
+
+    describe("variables inside conditionals", () => {
+        it("interpolates variables within conditional blocks", () => {
+            expect(
+                renderTemplate(
+                    "{{#if hasName}}Name: {{name}}{{/if}}",
+                    { hasName: true, name: "Alice" }
+                )
+            ).toBe("Name: Alice");
+        });
+    });
+
+    describe("real-world fitness app template", () => {
+        const template = `You are a fitness coach AI assistant.
+
+User: {{userName}}
+Goal: {{fitnessGoal}}
+
+{{#if hasImages}}
+The user has attached images for form analysis. Please review them carefully.
+{{/if}}
+{{#if hasAttachments}}
+Additional documents have been provided for context.
+{{/if}}
+{{#unless hasHistory}}
+This is a new user with no prior conversation history. Introduce yourself.
+{{/unless}}
+
+Please provide personalized advice.`;
+
+        it("renders with all flags true", () => {
+            const result = renderTemplate(template, {
+                userName: "Sarah",
+                fitnessGoal: "Build muscle",
+                hasImages: true,
+                hasAttachments: true,
+                hasHistory: true,
+            });
+            expect(result).toContain("User: Sarah");
+            expect(result).toContain("Goal: Build muscle");
+            expect(result).toContain("attached images for form analysis");
+            expect(result).toContain("Additional documents");
+            expect(result).not.toContain("new user with no prior");
+        });
+
+        it("renders with all flags false", () => {
+            const result = renderTemplate(template, {
+                userName: "Tom",
+                fitnessGoal: "Lose weight",
+                hasImages: false,
+                hasAttachments: false,
+                hasHistory: false,
+            });
+            expect(result).toContain("User: Tom");
+            expect(result).toContain("Goal: Lose weight");
+            expect(result).not.toContain("attached images");
+            expect(result).not.toContain("Additional documents");
+            expect(result).toContain("new user with no prior");
+        });
+    });
+});

package/src/handlebars.d.ts

@@ -0,0 +1,4 @@
+declare module "handlebars/dist/cjs/handlebars" {
+    import Handlebars from "handlebars";
+    export default Handlebars;
+}

package/src/index.ts

@@ -5,6 +5,8 @@ import {
     type LanguageModel,
 } from "ai";
 import { randomUUID } from "crypto";
+export { renderTemplate, type TemplateVariables } from "./template";
+import { renderTemplate } from "./template";
 
 /**
  * Log levels for controlling verbosity of CognitiveLayer logging.
@@ -101,7 +103,7 @@ export type CLModelWrapper = (
 
 export interface PromptConfig {
     slug: string;
-    variables?: Record<string, string>;
+    variables?: Record<string, string | boolean>;
 }
 
 export type CLStreamTextOptions = Omit<Parameters<typeof aiStreamText>[0], 'system' | 'prompt'> & {
@@ -274,14 +276,6 @@ function buildTraceSpansFromMessages(messages: any[]): Array<{
     return spans;
 }
 
-/**
- * Interpolate {{variable}} placeholders in a template string.
- * Unmatched variables are left as-is.
- */
-function interpolateTemplate(content: string, variables: Record<string, string>): string {
-    return content.replace(/\{\{(\w+)\}\}/g, (_, key) => variables[key] ?? `{{${key}}}`);
-}
-
 // Session-scoped snapshot cache: sessionKey → formatted memory block
 const sessionSnapshots = new Map<string, string>();
 
@@ -851,7 +845,7 @@ ${userContextBlock || "None"}
         let system: string | undefined;
         if (resolved) {
             system = promptConfig.variables
-                ? interpolateTemplate(resolved.content, promptConfig.variables)
+                ? renderTemplate(resolved.content, promptConfig.variables)
                 : resolved.content;
 
             // Store prompt metadata for the session (read by middleware during logging)
@@ -895,7 +889,7 @@ ${userContextBlock || "None"}
         let system: string | undefined;
         if (resolved) {
             system = promptConfig.variables
-                ? interpolateTemplate(resolved.content, promptConfig.variables)
+                ? renderTemplate(resolved.content, promptConfig.variables)
                 : resolved.content;
 
             // Store prompt metadata for the session (read by middleware during logging)

package/src/template.ts

@@ -0,0 +1,10 @@
+// Use the pre-built dist to avoid `require.extensions` warning in webpack/Next.js
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+import Handlebars from "handlebars/dist/cjs/handlebars";
+
+export type TemplateVariables = Record<string, string | boolean>;
+
+export function renderTemplate(template: string, variables: TemplateVariables): string {
+    const compiled = Handlebars.compile(template, { noEscape: true });
+    return compiled(variables);
+}