@kognitivedev/vercel-ai-provider 0.1.5 → 0.1.7

package/README.md

@@ -24,7 +24,7 @@ import { openai } from "@ai-sdk/openai";
 import { generateText } from "ai";
 
 // 1. Create the cognitive layer
-const clModel = createCognitiveLayer({
+const cl = createCognitiveLayer({
     provider: openai,
     clConfig: {
         appId: "my-app",
@@ -35,7 +35,7 @@ const clModel = createCognitiveLayer({
 
 // 2. Use it with Vercel AI SDK
 const { text } = await generateText({
-    model: clModel("gpt-4o", {
+    model: cl("gpt-4o", {
         userId: "user-123",
         sessionId: "session-abc"
     }),
@@ -49,17 +49,41 @@ const { text } = await generateText({
 
 | Option | Type | Required | Default | Description |
 |--------|------|----------|---------|-------------|
-| `appId` | `string` | ✓ | - | Unique identifier for your application |
+| `appId` | `string` | Yes | - | Unique identifier for your application |
 | `defaultAgentId` | `string` | - | `"default"` | Default agent ID when not specified per-request |
 | `baseUrl` | `string` | - | `"http://localhost:3001"` | Kognitive backend API URL |
 | `apiKey` | `string` | - | - | API key for authentication (if required) |
 | `processDelayMs` | `number` | - | `500` | Delay before triggering memory processing (set to 0 to disable) |
+| `logLevel` | `LogLevel` | - | `'info'` | Controls console logging verbosity |
+| `providerFactory` | `(baseURL: string, apiKey: string) => (modelId: string) => LanguageModel` | - | - | Factory for creating a provider that routes through a gateway URL |
+
+### `LogLevel`
+
+Controls verbosity of console output from the provider.
+
+| Level | Description |
+|-------|-------------|
+| `'none'` | No logging |
+| `'error'` | Only errors |
+| `'warn'` | Errors and warnings |
+| `'info'` | Errors, warnings, and info messages (default) |
+| `'debug'` | All messages including detailed snapshot data |
+
+```typescript
+const cl = createCognitiveLayer({
+    provider: openai,
+    clConfig: {
+        appId: "my-app",
+        logLevel: "debug" // see full snapshot data in console
+    }
+});
+```
 
 ## API Reference
 
 ### `createCognitiveLayer(config)`
 
-Creates a model wrapper function that adds memory capabilities to any Vercel AI SDK provider.
+Creates a cognitive layer that adds memory capabilities to any Vercel AI SDK provider.
 
 **Parameters:**
 
@@ -67,16 +91,34 @@ Creates a model wrapper function that adds memory capabilities to any Vercel AI
 createCognitiveLayer({
     provider: any,        // Vercel AI SDK provider (e.g., openai, anthropic)
     clConfig: CognitiveLayerConfig
-}): CLModelWrapper
+}): CognitiveLayer
 ```
 
-**Returns:** `CLModelWrapper` - A function to wrap models with memory capabilities.
+**Returns:** `CognitiveLayer` - A callable model wrapper with `.streamText()` and `.generateText()` methods attached.
+
+---
+
+### `CognitiveLayer`
+
+The return type of `createCognitiveLayer`. It is callable as a model wrapper and also exposes prompt-driven helpers.
+
+```typescript
+type CognitiveLayer = CLModelWrapper & {
+    streamText: (options: CLStreamTextOptions) => Promise<ReturnType<typeof streamText>>;
+    generateText: (options: CLGenerateTextOptions) => ReturnType<typeof generateText>;
+    resolvePrompt: (slug: string) => Promise<CachedPrompt>;
+    logConversation: (payload: LogConversationPayload) => Promise<void>;
+    triggerProcessing: (userId: string, projectId: string, sessionId: string) => void;
+    clearPromptCache: () => void;
+    clearSessionCache: (sessionKey?: string) => void;
+};
+```
 
 ---
 
 ### `CLModelWrapper`
 
-The function returned by `createCognitiveLayer`.
+The callable signature of `CognitiveLayer`.
 
 ```typescript
 type CLModelWrapper = (
@@ -87,19 +129,32 @@ type CLModelWrapper = (
         sessionId?: string;
     },
     providerOptions?: Record<string, unknown>
-) => LanguageModelV2;
+) => LanguageModel;
 ```
 
 **Parameters:**
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `modelId` | `string` | ✓ | Model identifier (e.g., `"gpt-4o"`, `"claude-3-opus"`) |
+| `modelId` | `string` | Yes | Model identifier (e.g., `"gpt-4o"`, `"claude-3-opus"`) |
 | `settings.userId` | `string` | - | User identifier (required for memory features) |
 | `settings.agentId` | `string` | - | Override default agent ID |
 | `settings.sessionId` | `string` | - | Session identifier (required for logging) |
 | `providerOptions` | `Record<string, unknown>` | - | Provider-specific options passed directly to the underlying provider |
 
+---
+
+### `PromptConfig`
+
+Used with `cl.streamText()` and `cl.generateText()` to reference a managed prompt.
+
+```typescript
+interface PromptConfig {
+    slug: string;
+    variables?: Record<string, string>;
+}
+```
+
 ## Usage Examples
 
 ### With OpenAI
@@ -109,7 +164,7 @@ import { createCognitiveLayer } from "@kognitivedev/vercel-ai-provider";
 import { openai } from "@ai-sdk/openai";
 import { generateText } from "ai";
 
-const clModel = createCognitiveLayer({
+const cl = createCognitiveLayer({
     provider: openai,
     clConfig: {
         appId: "my-app",
@@ -118,7 +173,7 @@ const clModel = createCognitiveLayer({
 });
 
 const { text } = await generateText({
-    model: clModel("gpt-4o", {
+    model: cl("gpt-4o", {
         userId: "user-123",
         sessionId: "session-abc"
     }),
@@ -139,7 +194,7 @@ const openrouter = createOpenRouter({
     apiKey: process.env.OPENROUTER_API_KEY
 });
 
-const clModel = createCognitiveLayer({
+const cl = createCognitiveLayer({
     provider: openrouter.chat,
     clConfig: {
         appId: "my-app",
@@ -149,7 +204,7 @@ const clModel = createCognitiveLayer({
 
 // Pass provider-specific options as the third parameter
 const { text } = await generateText({
-    model: clModel("moonshotai/kimi-k2-0905", {
+    model: cl("moonshotai/kimi-k2-0905", {
         userId: "user-123",
         sessionId: "session-abc"
     }, {
@@ -168,7 +223,7 @@ import { createCognitiveLayer } from "@kognitivedev/vercel-ai-provider";
 import { anthropic } from "@ai-sdk/anthropic";
 import { streamText } from "ai";
 
-const clModel = createCognitiveLayer({
+const cl = createCognitiveLayer({
     provider: anthropic,
     clConfig: {
         appId: "my-app",
@@ -177,7 +232,7 @@ const clModel = createCognitiveLayer({
 });
 
 const result = await streamText({
-    model: clModel("claude-3-5-sonnet-latest", {
+    model: cl("claude-3-5-sonnet-latest", {
         userId: "user-456",
         sessionId: "chat-xyz"
     }),
@@ -195,7 +250,7 @@ The provider automatically injects memory context into your system prompts:
 
 ```typescript
 const { text } = await generateText({
-    model: clModel("gpt-4o", {
+    model: cl("gpt-4o", {
         userId: "user-123",
         sessionId: "session-abc"
     }),
@@ -206,13 +261,175 @@ const { text } = await generateText({
 // Memory context is automatically appended to system prompt
 ```
 
+### Prompt Management
+
+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.
+
+```typescript
+// Stream with a managed prompt
+const result = await cl.streamText({
+    model: cl("gpt-4o", {
+        userId: "user-123",
+        sessionId: "session-abc"
+    }),
+    prompt: {
+        slug: "customer-support",
+        variables: {
+            companyName: "Acme Corp",
+            language: "English"
+        }
+    },
+    messages: [{ role: "user", content: "I need help with my order" }]
+});
+
+for await (const chunk of result.textStream) {
+    process.stdout.write(chunk);
+}
+```
+
+```typescript
+// Generate with a managed prompt
+const { text } = await cl.generateText({
+    model: cl("gpt-4o", {
+        userId: "user-123",
+        sessionId: "session-abc"
+    }),
+    prompt: {
+        slug: "summarizer"
+    },
+    messages: [{ role: "user", content: "Summarize this document..." }]
+});
+```
+
+### 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}`.
+
+To enable gateway routing, provide a `providerFactory` in your config:
+
+```typescript
+import { createOpenAI } from "@ai-sdk/openai";
+
+const cl = createCognitiveLayer({
+    provider: openai,
+    clConfig: {
+        appId: "my-app",
+        baseUrl: "https://api.kognitive.dev",
+        providerFactory: (baseURL, apiKey) => {
+            const gatewayProvider = createOpenAI({ baseURL, apiKey });
+            return (modelId) => gatewayProvider(modelId);
+        }
+    }
+});
+```
+
+Without `providerFactory`, the provider will log a warning and skip gateway routing, sending requests directly to the original provider.
+
+### `cl.resolvePrompt(slug)`
+
+Fetches and caches a prompt by slug from the backend. Prompts are cached for 60 seconds.
+
+```typescript
+const prompt = await cl.resolvePrompt("customer-support");
+console.log(prompt.content);   // The prompt template text
+console.log(prompt.version);   // Prompt version number
+console.log(prompt.promptId);  // Unique prompt ID
+```
+
+**Returns:** `Promise<CachedPrompt>`
+
+```typescript
+interface CachedPrompt {
+    promptId: string;
+    slug: string;
+    version: number;
+    content: string;
+    fetchedAt: number;
+    gatewaySlug?: string;
+}
+```
+
+---
+
+### `cl.logConversation(payload)`
+
+Manually logs a conversation to the backend for memory processing.
+
+```typescript
+await cl.logConversation({
+    userId: "user-123",
+    projectId: "my-project",
+    sessionId: "session-abc",
+    messages: [
+        { role: "user", content: "Hello" },
+        { role: "assistant", content: "Hi there!" }
+    ],
+    modelId: "gpt-4o",
+});
+```
+
+**Parameters:** `LogConversationPayload`
+
+```typescript
+interface LogConversationPayload {
+    userId: string;
+    projectId: string;
+    sessionId: string;
+    messages: any[];
+    memorySystemPrompt?: string;
+    modelId?: string;
+    usage?: Record<string, unknown>;
+    promptSlug?: string;
+    promptVersion?: number;
+    promptId?: string;
+}
+```
+
+---
+
+### `cl.triggerProcessing(userId, projectId, sessionId)`
+
+Manually triggers memory processing for a given session. This is normally called automatically after logging, but can be invoked independently.
+
+```typescript
+cl.triggerProcessing("user-123", "my-project", "session-abc");
+```
+
+---
+
+### `cl.clearPromptCache()`
+
+Clears all cached prompts, forcing the next `resolvePrompt` call to fetch fresh data from the backend.
+
+```typescript
+cl.clearPromptCache();
+```
+
+---
+
+### `cl.clearSessionCache(sessionKey?)`
+
+Clears cached memory snapshots. Pass a specific session key (`"userId:projectId:sessionId"`) to clear one session, or omit to clear all.
+
+```typescript
+// Clear a specific session
+cl.clearSessionCache("user-123:my-project:session-abc");
+
+// Clear all cached sessions
+cl.clearSessionCache();
+```
+
+---
+
 ### Without Memory (Anonymous Users)
 
 Skip memory features by omitting `userId`:
 
 ```typescript
 const { text } = await generateText({
-    model: clModel("gpt-4o"),
+    model: cl("gpt-4o"),
     prompt: "General question without memory"
 });
 ```
@@ -258,6 +475,8 @@ The provider communicates with your Kognitive backend via these endpoints:
 | `/api/cognitive/snapshot` | GET | Fetches user's memory snapshot |
 | `/api/cognitive/log` | POST | Logs conversation for processing |
 | `/api/cognitive/process` | POST | Triggers memory extraction/management |
+| `/api/cognitive/prompt` | GET | Resolves a managed prompt by slug |
+| `/api/cognitive/gateway/{slug}` | * | Gateway proxy endpoint for routed requests |
 
 ### Query Parameters for Snapshot
 
@@ -292,6 +511,14 @@ clConfig: {
 }
 ```
 
+### Gateway not routing
+
+If requests are not being routed through the gateway:
+
+1. Ensure `providerFactory` is set in your `clConfig`
+2. Verify the prompt has a `gatewaySlug` configured on the backend
+3. Set `logLevel: 'debug'` to inspect gateway resolution logs
+
 ## License
 
 MIT

package/dist/__tests__/wrap-stream-logging.test.d.ts

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

package/dist/__tests__/wrap-stream-logging.test.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const index_1 = require("../index");
+const ai_1 = require("ai");
+const test_1 = require("ai/test");
+(0, vitest_1.describe)("wrapStream logging", () => {
+    let fetchCalls;
+    (0, vitest_1.beforeEach)(() => {
+        fetchCalls = [];
+        vitest_1.vi.stubGlobal("fetch", vitest_1.vi.fn(async (url, init) => {
+            const urlStr = typeof url === "string" ? url : url.toString();
+            if (urlStr.includes("/api/cognitive/snapshot")) {
+                return new Response(JSON.stringify({ systemBlock: "", userContextBlock: "" }), { status: 200, headers: { "Content-Type": "application/json" } });
+            }
+            if (urlStr.includes("/api/cognitive/log")) {
+                const body = JSON.parse(init === null || init === void 0 ? void 0 : init.body);
+                fetchCalls.push({ url: urlStr, body });
+                return new Response(JSON.stringify({ ok: true }), { status: 200 });
+            }
+            if (urlStr.includes("/api/cognitive/process")) {
+                return new Response(JSON.stringify({ ok: true }), { status: 200 });
+            }
+            return new Response("not found", { status: 404 });
+        }));
+    });
+    (0, vitest_1.it)("should include assistant message in logged conversation after streaming", 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: "Hello" },
+                    { type: "text-delta", id: "t1", delta: " world" },
+                    { type: "text-end", id: "t1" },
+                    {
+                        type: "finish",
+                        finishReason: {
+                            unified: "stop",
+                            raw: undefined,
+                        },
+                        usage: {
+                            inputTokens: { total: 10, noCache: undefined, cacheRead: undefined, cacheWrite: undefined },
+                            outputTokens: { total: 5, 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: "Hi" }],
+        });
+        // Fully consume the stream
+        const text = await result.text;
+        (0, vitest_1.expect)(text).toBe("Hello world");
+        // 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;
+        const assistantMsg = messages.find((m) => m.role === "assistant");
+        (0, vitest_1.expect)(assistantMsg).toBeDefined();
+        (0, vitest_1.expect)(assistantMsg.content).toEqual([
+            { type: "text", text: "Hello world" },
+        ]);
+    });
+});

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LanguageModelV2 } from "@ai-sdk/provider";
+import { streamText as aiStreamText, generateText as aiGenerateText, type LanguageModel } from "ai";
 /**
  * Log levels for controlling verbosity of CognitiveLayer logging.
  * - 'none': No logging
@@ -9,10 +9,10 @@ import { LanguageModelV2 } from "@ai-sdk/provider";
  */
 export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
 export interface CognitiveLayerConfig {
-    appId: string;
-    defaultAgentId?: string;
+    apiKey: string;
+    appId?: string;
+    projectId?: string;
     baseUrl?: string;
-    apiKey?: string;
     /**
      * Delay in milliseconds before triggering memory processing after a response.
      * Set to 0 to disable automatic processing.
@@ -21,21 +21,59 @@ export interface CognitiveLayerConfig {
     processDelayMs?: number;
     /**
      * Log level for controlling verbosity of CognitiveLayer logging.
-     * - 'none': No logging
-     * - 'error': Only errors
-     * - 'warn': Errors and warnings
-     * - 'info': Errors, warnings, and info messages
-     * - 'debug': All messages including detailed snapshot data
      * Default: 'info'
      */
     logLevel?: LogLevel;
+    /**
+     * Factory for creating a provider that routes through a gateway URL.
+     */
+    providerFactory?: (baseURL: string, apiKey: string) => (modelId: string) => LanguageModel;
 }
 export type CLModelWrapper = (modelId: string, settings?: {
     userId?: string;
-    agentId?: string;
+    projectId?: string;
     sessionId?: string;
-}, providerOptions?: Record<string, unknown>) => LanguageModelV2;
+}, providerOptions?: Record<string, unknown>) => LanguageModel;
+export interface PromptConfig {
+    slug: string;
+    variables?: Record<string, string>;
+}
+export type CLStreamTextOptions = Omit<Parameters<typeof aiStreamText>[0], 'system' | 'prompt'> & {
+    prompt: PromptConfig;
+};
+export type CLGenerateTextOptions = Omit<Parameters<typeof aiGenerateText>[0], 'system' | 'prompt'> & {
+    prompt: PromptConfig;
+};
+export interface LogConversationPayload {
+    userId: string;
+    projectId: string;
+    sessionId: string;
+    messages: any[];
+    memorySystemPrompt?: string;
+    modelId?: string;
+    usage?: Record<string, unknown>;
+    promptSlug?: string;
+    promptVersion?: number;
+    promptId?: string;
+}
+export type CognitiveLayer = CLModelWrapper & {
+    streamText: (options: CLStreamTextOptions) => Promise<ReturnType<typeof aiStreamText>>;
+    generateText: (options: CLGenerateTextOptions) => ReturnType<typeof aiGenerateText>;
+    resolvePrompt: (slug: string) => Promise<CachedPrompt>;
+    logConversation: (payload: LogConversationPayload) => Promise<void>;
+    triggerProcessing: (userId: string, projectId: string, sessionId: string) => void;
+    clearPromptCache: () => void;
+    clearSessionCache: (sessionKey?: string) => void;
+};
+export interface CachedPrompt {
+    promptId: string;
+    slug: string;
+    version: number;
+    content: string;
+    fetchedAt: number;
+    gatewaySlug?: string;
+}
 export declare function createCognitiveLayer(config: {
     provider: any;
     clConfig: CognitiveLayerConfig;
-}): CLModelWrapper;
+}): CognitiveLayer;