@kognitivedev/vercel-ai-provider 0.1.8 → 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/__tests__/wrap-stream-logging.test.js

@@ -24,6 +24,98 @@ const test_1 = require("ai/test");
             return new Response("not found", { status: 404 });
         }));
     });
+    (0, vitest_1.it)("should capture tool-call chunks and include them in logged conversation", async () => {
+        const mockModel = new test_1.MockLanguageModelV3({
+            doStream: async () => ({
+                stream: (0, test_1.convertArrayToReadableStream)([
+                    { type: "text-start", id: "t1" },
+                    { type: "text-delta", id: "t1", delta: "Let me check" },
+                    { type: "text-end", id: "t1" },
+                    {
+                        type: "tool-call",
+                        toolCallId: "call-1",
+                        toolName: "get_weather",
+                        input: '{"city":"London"}',
+                    },
+                    {
+                        type: "tool-result",
+                        toolCallId: "call-1",
+                        toolName: "get_weather",
+                        result: { temperature: 15, unit: "celsius" },
+                    },
+                    {
+                        type: "finish",
+                        finishReason: {
+                            unified: "tool-calls",
+                            raw: undefined,
+                        },
+                        usage: {
+                            inputTokens: { total: 20, noCache: undefined, cacheRead: undefined, cacheWrite: undefined },
+                            outputTokens: { total: 15, text: undefined, reasoning: undefined },
+                        },
+                    },
+                ]),
+            }),
+        });
+        const mockProvider = () => mockModel;
+        const cl = (0, index_1.createCognitiveLayer)({
+            provider: mockProvider,
+            clConfig: {
+                apiKey: "test-api-key",
+                appId: "test-app",
+                projectId: "test-project",
+                processDelayMs: 0,
+                logLevel: "none",
+            },
+        });
+        const model = cl("mock-model", {
+            userId: "user-1",
+            projectId: "project-1",
+            sessionId: "session-1",
+        });
+        const result = (0, ai_1.streamText)({
+            model,
+            messages: [{ role: "user", content: "What's the weather in London?" }],
+        });
+        // Fully consume the stream
+        await result.text;
+        // Wait for async logConversation to complete
+        await new Promise((r) => setTimeout(r, 100));
+        // Find the log call
+        const logCall = fetchCalls.find((c) => c.url.includes("/api/cognitive/log"));
+        (0, vitest_1.expect)(logCall).toBeDefined();
+        const messages = logCall.body.messages;
+        // Assistant message should contain text + tool-call parts
+        const assistantMsg = messages.find((m) => m.role === "assistant");
+        (0, vitest_1.expect)(assistantMsg).toBeDefined();
+        (0, vitest_1.expect)(assistantMsg.content).toEqual([
+            { type: "text", text: "Let me check" },
+            {
+                type: "tool-call",
+                toolCallId: "call-1",
+                toolName: "get_weather",
+                input: '{"city":"London"}',
+            },
+        ]);
+        // Tool results should be in a separate tool message
+        const toolMsg = messages.find((m) => m.role === "tool");
+        (0, vitest_1.expect)(toolMsg).toBeDefined();
+        (0, vitest_1.expect)(toolMsg.content).toEqual([
+            {
+                type: "tool-result",
+                toolCallId: "call-1",
+                toolName: "get_weather",
+                result: { temperature: 15, unit: "celsius" },
+            },
+        ]);
+        // Spans should include the tool call with populated previews
+        const spans = logCall.body.spans;
+        const toolSpan = spans === null || spans === void 0 ? void 0 : spans.find((s) => s.spanType === "tool");
+        (0, vitest_1.expect)(toolSpan).toBeDefined();
+        (0, vitest_1.expect)(toolSpan.toolName).toBe("get_weather");
+        (0, vitest_1.expect)(toolSpan.inputPreview).toContain("London");
+        (0, vitest_1.expect)(toolSpan.outputPreview).toContain("15");
+    });
     (0, vitest_1.it)("should include assistant message in logged conversation after streaming", async () => {
         const mockModel = new test_1.MockLanguageModelV3({
             doStream: async () => ({

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;
@@ -55,6 +56,27 @@ export interface LogConversationPayload {
     promptSlug?: string;
     promptVersion?: number;
     promptId?: string;
+    traceId?: string;
+    parentSpanId?: string;
+    requestPreview?: string;
+    responsePreview?: string;
+    state?: "active" | "completed" | "error";
+    startedAt?: string;
+    endedAt?: string;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+    spans?: Array<{
+        spanKey: string;
+        parentSpanKey?: string;
+        name: string;
+        spanType: string;
+        status?: "active" | "completed" | "error";
+        inputPreview?: string;
+        outputPreview?: string;
+        toolName?: string;
+        errorMessage?: string;
+        metadata?: Record<string, unknown>;
+    }>;
 }
 export type CognitiveLayer = CLModelWrapper & {
     streamText: (options: CLStreamTextOptions) => Promise<ReturnType<typeof aiStreamText>>;