@rudderjs/ai 1.18.2 → 1.18.4

package/dist/conversation-orm/index.js

@@ -1,5 +1,215 @@
-// @rudderjs/ai is deprecated. The AI engine now lives in @gemstack/ai-sdk.
-// This module re-exports it for backwards compatibility; import from
-// '@gemstack/ai-sdk/conversation-orm' directly in new code.
-export * from '@gemstack/ai-sdk/conversation-orm';
+/**
+ * `@rudderjs/ai/conversation-orm` - ORM-backed {@link ConversationStore}.
+ *
+ * Production-grade replacement for `MemoryConversationStore` (which is
+ * single-process, in-memory, and loses every thread on restart). Persists
+ * conversation threads and their messages via the registered `@rudderjs/orm`
+ * adapter - works across web processes, queue workers, and horizontally
+ * scaled deployments. Mirrors the `@rudderjs/ai/memory-orm` /
+ * `@rudderjs/ai/budget-orm` pattern.
+ *
+ * Wire it as the conversation store:
+ *
+ * ```ts
+ * import { setConversationStore } from '@gemstack/ai-sdk'
+ * import { OrmConversationStore } from '@rudderjs/ai/conversation-orm'
+ *
+ * setConversationStore(new OrmConversationStore())
+ * ```
+ *
+ * The schema lives at {@link conversationOrmPrismaSchema} - copy it into your
+ * Prisma schema (or a new `prisma/schema/<file>.prisma` if you use the
+ * multi-file setup). On the native engine, add an equivalent migration; on
+ * Drizzle, define matching tables and register them via `tables: { ... }`.
+ *
+ * # Adapter coverage
+ *
+ * - Prisma - works out of the box; copy {@link conversationOrmPrismaSchema}.
+ * - Native - add a migration with the same columns.
+ * - Drizzle - define the two tables and register them on the `drizzle()`
+ *   config.
+ *
+ * # Ordering & concurrency
+ *
+ * Messages carry a monotonic per-thread `position` so `load()` returns them
+ * in append order regardless of timestamp granularity. `append()` reads the
+ * current max position and assigns the next slots; like
+ * `OrmBudgetStorage.checkAndDebit`, the read-then-write is not isolated, so
+ * two concurrent appends to the SAME thread could collide on a position.
+ * Conversation threads are single-writer in practice (one user, one turn at
+ * a time), so this is a non-issue for typical apps. File an issue if you hit
+ * it; strict ordering needs a serializable transaction or a DB sequence.
+ */
+import { Model } from '@rudderjs/orm';
+import { sanitizeConversation } from '@gemstack/ai-sdk';
+// ─── ORM Models ───────────────────────────────────────────
+/**
+ * The thread row backing {@link OrmConversationStore}. Exposed so apps that
+ * want their own queries (admin views, analytics) can use
+ * `AiConversationRecord.where(...).get()` directly.
+ *
+ * `userId` / `agent` mirror {@link ConversationStoreMeta} - `userId` scopes
+ * `list()`, `agent` carries the thread-segregation key the auto-persist
+ * machinery uses to keep one user's threads per agent class apart.
+ */
+export class AiConversationRecord extends Model {
+    static table = 'aiConversation';
+    static fillable = ['title', 'userId', 'agent', 'updatedAt'];
+}
+/**
+ * One message row in a thread. `content` and `toolCalls` are JSON-encoded
+ * strings (so a `string` content and a `ContentPart[]` content both
+ * round-trip through a portable `text` column); `position` orders them.
+ */
+export class AiConversationMessageRecord extends Model {
+    static table = 'aiConversationMessage';
+    static fillable = ['conversationId', 'position', 'role', 'content', 'toolCallId', 'toolCalls'];
+}
+// ─── ConversationStore adapter ────────────────────────────
+/**
+ * {@link ConversationStore} implementation that persists rows to the
+ * registered ORM adapter. Designed for production use - the in-process
+ * `MemoryConversationStore` is for tests and dev.
+ */
+export class OrmConversationStore {
+    async create(title, meta) {
+        const data = { title: title ?? 'New conversation' };
+        if (meta?.userId !== undefined)
+            data['userId'] = meta.userId;
+        if (meta?.agent !== undefined)
+            data['agent'] = meta.agent;
+        const created = await AiConversationRecord.create(data);
+        return created.id;
+    }
+    async load(conversationId) {
+        await this.requireThread(conversationId);
+        const rows = await AiConversationMessageRecord
+            .where('conversationId', conversationId)
+            .orderBy('position', 'ASC')
+            .get();
+        // A thread persisted mid-turn (crash between the assistant row and its
+        // tool-result rows) would otherwise replay into a provider 400. Drop the
+        // incomplete turns at the load boundary so the history is replay-safe.
+        return sanitizeConversation(rows.map(rowToMessage));
+    }
+    async append(conversationId, messages) {
+        await this.requireThread(conversationId);
+        if (messages.length === 0)
+            return;
+        let position = await this.nextPosition(conversationId);
+        for (const message of messages) {
+            await AiConversationMessageRecord.create(messageToRow(conversationId, position, message));
+            position++;
+        }
+        await AiConversationRecord.where('id', conversationId).updateAll({ updatedAt: new Date() });
+    }
+    async setTitle(conversationId, title) {
+        const updated = await AiConversationRecord
+            .where('id', conversationId)
+            .updateAll({ title, updatedAt: new Date() });
+        if (!updated)
+            throw notFound(conversationId);
+    }
+    async list(userId) {
+        let q = AiConversationRecord.query();
+        if (userId != null)
+            q = q.where('userId', userId);
+        const rows = await q.orderBy('updatedAt', 'DESC').get();
+        return rows.map(rowToListEntry);
+    }
+    async delete(conversationId) {
+        await AiConversationMessageRecord.where('conversationId', conversationId).deleteAll();
+        await AiConversationRecord.where('id', conversationId).deleteAll();
+    }
+    /** Throw the same not-found error shape as `MemoryConversationStore`. */
+    async requireThread(conversationId) {
+        const thread = await AiConversationRecord.where('id', conversationId).first();
+        if (!thread)
+            throw notFound(conversationId);
+    }
+    /** Next monotonic position for the thread (0 when empty). */
+    async nextPosition(conversationId) {
+        const last = await AiConversationMessageRecord
+            .where('conversationId', conversationId)
+            .orderBy('position', 'DESC')
+            .first();
+        return last ? last.position + 1 : 0;
+    }
+}
+/** Convenience factory mirroring `ormBudgetStorage()` / `OrmUserMemory`. */
+export function ormConversationStore() {
+    return new OrmConversationStore();
+}
+// ─── Schema reference ─────────────────────────────────────
+/**
+ * Reference Prisma schema for `OrmConversationStore`. Copy into your
+ * `prisma/schema/<file>.prisma`. SQLite stores the `text` content as TEXT;
+ * Postgres as `text`. The `@@index` keeps `list()` (by user) and `load()`
+ * (by thread, ordered) cheap.
+ */
+export const conversationOrmPrismaSchema = `model AiConversation {
+  id        String   @id @default(cuid())
+  title     String
+  userId    String?
+  /// Thread-segregation key - the agent class name by default
+  agent     String?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([userId])
+}
+
+model AiConversationMessage {
+  id             String   @id @default(cuid())
+  conversationId String
+  /// Monotonic per-thread ordering
+  position       Int
+  role           String
+  /// JSON-encoded \`string | ContentPart[]\`
+  content        String
+  toolCallId     String?
+  /// JSON-encoded \`ToolCall[]\` or null
+  toolCalls      String?
+  createdAt      DateTime @default(now())
+
+  @@index([conversationId, position])
+}
+`;
+// ─── Helpers ──────────────────────────────────────────────
+function notFound(conversationId) {
+    return new Error(`[ai-sdk] Conversation "${conversationId}" not found.`);
+}
+function messageToRow(conversationId, position, m) {
+    return {
+        conversationId,
+        position,
+        role: m.role,
+        content: JSON.stringify(m.content),
+        toolCallId: m.toolCallId ?? null,
+        toolCalls: m.toolCalls ? JSON.stringify(m.toolCalls) : null,
+    };
+}
+function rowToMessage(row) {
+    const out = {
+        role: row.role,
+        content: JSON.parse(row.content),
+    };
+    if (row.toolCallId != null)
+        out.toolCallId = row.toolCallId;
+    if (row.toolCalls != null)
+        out.toolCalls = JSON.parse(row.toolCalls);
+    return out;
+}
+function rowToListEntry(row) {
+    const out = {
+        id: row.id,
+        title: row.title,
+        createdAt: row.createdAt,
+    };
+    if (row.updatedAt != null)
+        out.updatedAt = row.updatedAt;
+    if (row.agent != null)
+        out.agent = row.agent;
+    return out;
+}
 //# sourceMappingURL=index.js.map

package/dist/conversation-orm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/conversation-orm/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,qEAAqE;AACrE,4DAA4D;AAC5D,cAAc,mCAAmC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/conversation-orm/index.ts"],"names":[],"mappings":"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"}

package/dist/doctor.d.ts

@@ -1,2 +1,2 @@
-export * from '@gemstack/ai-sdk/doctor';
+export {};
 //# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAGA,cAAc,yBAAyB,CAAA"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":""}

package/dist/doctor.js

@@ -1,5 +1,68 @@
-// @rudderjs/ai is deprecated. The AI engine now lives in @gemstack/ai-sdk.
-// This module re-exports it for backwards compatibility; import from
-// '@gemstack/ai-sdk/doctor' directly in new code.
-export * from '@gemstack/ai-sdk/doctor';
+// AI doctor checks contributed by @rudderjs/ai. This is a Rudder binding: it
+// registers into @rudderjs/console's doctor registry, so it lives here rather
+// than in the agnostic @gemstack/ai-sdk engine.
+import fs from 'node:fs';
+import path from 'node:path';
+import { registerDoctorCheck } from '@rudderjs/console';
+function readFileSafe(rel) {
+    try {
+        return fs.readFileSync(path.join(process.cwd(), rel), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+// Maps provider driver name → env var the user must set. Mirrors the
+// driver names listed in @gemstack/ai-sdk's provider implementations.
+const PROVIDER_ENV = {
+    anthropic: 'ANTHROPIC_API_KEY',
+    openai: 'OPENAI_API_KEY',
+    google: 'GOOGLE_AI_API_KEY',
+    bedrock: 'AWS_ACCESS_KEY_ID',
+    groq: 'GROQ_API_KEY',
+    openrouter: 'OPENROUTER_API_KEY',
+    // ollama, lmstudio: local — no key needed.
+};
+// Extracts driver names referenced by config/ai.ts WITHOUT importing the
+// module. We grep for `driver: '<name>'` literals — covers the scaffolded
+// shape.
+function declaredProviders() {
+    const text = readFileSafe('config/ai.ts') ??
+        readFileSafe('config/ai.js') ??
+        readFileSafe('config/ai.mjs') ?? '';
+    const matches = [...text.matchAll(/driver\s*:\s*['"]([^'"]+)['"]/g)];
+    return [...new Set(matches.map(m => m[1]).filter(Boolean))];
+}
+registerDoctorCheck({
+    id: 'ai:provider-keys',
+    category: 'ai',
+    title: 'AI provider API keys',
+    run() {
+        const providers = declaredProviders();
+        if (providers.length === 0) {
+            return { status: 'ok', message: 'no config/ai.ts or no providers declared — skip' };
+        }
+        const needsKey = providers.filter(p => p in PROVIDER_ENV);
+        if (needsKey.length === 0) {
+            return { status: 'ok', message: `${providers.length} provider(s) — all local (no keys required)` };
+        }
+        const missing = needsKey.filter(p => !process.env[PROVIDER_ENV[p]]);
+        if (missing.length === needsKey.length) {
+            return {
+                status: 'warn',
+                message: `none of ${needsKey.length} cloud provider(s) have an API key set`,
+                fix: `Set at least one of: ${needsKey.map(p => PROVIDER_ENV[p]).join(', ')} (or remove the providers from config/ai.ts if unused)`,
+                detail: `Declared providers: ${needsKey.join(', ')}`,
+            };
+        }
+        if (missing.length > 0) {
+            return {
+                status: 'warn',
+                message: `${needsKey.length - missing.length}/${needsKey.length} cloud provider(s) have keys`,
+                fix: `Set missing keys: ${missing.map(p => PROVIDER_ENV[p]).join(', ')} (or remove the providers from config/ai.ts if unused)`,
+            };
+        }
+        return { status: 'ok', message: `${needsKey.length} cloud provider(s), all keys present` };
+    },
+});
 //# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,qEAAqE;AACrE,kDAAkD;AAClD,cAAc,yBAAyB,CAAA"}
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"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"}

package/dist/memory-embedding/index.d.ts

@@ -1,2 +1,121 @@
-export * from '@gemstack/ai-sdk/memory-embedding';
+/**
+ * `@rudderjs/ai/memory-embedding` — embedding-backed {@link UserMemory}
+ * for #A4 Phase 5.
+ *
+ * Composes Phase 4's {@link OrmUserMemory} with the embedding
+ * provider registered on {@link AiRegistry}: `remember()` embeds the
+ * fact and writes the Float32-packed vector into the row's
+ * `embedding` column; `recall()` embeds the query and ranks by
+ * cosine similarity. `forget()` / `forgetAll()` delegate to the
+ * inner store — the embedding lives in the same row, so deleting
+ * the row deletes the vector. GDPR right-to-be-forgotten cascades
+ * automatically.
+ *
+ * v1 is **pure-JS cosine over the user's full set** — fine up to
+ * a few thousand facts per user. For larger workloads, B7 lands a
+ * pgvector-backed `EmbeddingUserMemory` that pushes the dot-product
+ * into the database.
+ *
+ * @example
+ * ```ts
+ * import { OrmUserMemory } from '@rudderjs/ai/memory-orm'
+ * import { EmbeddingUserMemory } from '@rudderjs/ai/memory-embedding'
+ *
+ * const memory = new EmbeddingUserMemory({
+ *   inner: new OrmUserMemory(),
+ *   model: 'openai/text-embedding-3-small',
+ *   threshold: 0.5,    // cosine floor; matches below are dropped
+ * })
+ * ```
+ *
+ * **Pre-Phase-5 facts** (rows with `embedding === null`) fall back to
+ * token-overlap matching against the `fact` column — same shape as
+ * `MemoryUserMemory.recall()`. So upgrading from `OrmUserMemory` to
+ * `EmbeddingUserMemory` doesn't lose recall on existing rows; new
+ * `remember()` calls populate the embedding column going forward.
+ */
+import { OrmUserMemory } from '../memory-orm/index.js';
+import type { MemoryEntry, UserMemory } from '@gemstack/ai-sdk';
+export interface EmbeddingUserMemoryOptions {
+    /**
+     * The composed inner store. Must be {@link OrmUserMemory} for v1
+     * — the composer reads/writes the `embedding Bytes?` column on
+     * the same row. Other backends (Pinecone, Weaviate) implement
+     * their own.
+     */
+    inner: OrmUserMemory;
+    /**
+     * Embedding model id (`'<provider>/<model>'`). Used for both
+     * fact embedding on `remember()` and query embedding on
+     * `recall()`. Default: whatever `AI.embed()` picks (`AiRegistry`
+     * default).
+     */
+    model?: string;
+    /**
+     * Cosine-similarity floor in `[-1, 1]`. Matches below the
+     * threshold are dropped before sorting. Default `0` — return
+     * everything ranked. Tighten for higher precision; loosen for
+     * higher recall.
+     */
+    threshold?: number;
+    /**
+     * Optional fallback for rows whose `embedding` column is `null`
+     * (rows persisted without the embedding composer wired in).
+     *
+     * - `'token-overlap'` (default) — score 0 if any ≥3-char token
+     *   from the query appears in the row's `fact`. Lets you
+     *   upgrade `OrmUserMemory` → `EmbeddingUserMemory` without
+     *   losing recall on existing rows.
+     * - `'skip'` — drop null-embedding rows entirely.
+     */
+    nullEmbeddingFallback?: 'token-overlap' | 'skip';
+}
+export declare class EmbeddingUserMemory implements UserMemory {
+    private readonly inner;
+    private readonly model;
+    private readonly threshold;
+    private readonly fallback;
+    constructor(opts: EmbeddingUserMemoryOptions);
+    remember(userId: string, fact: string, opts?: {
+        tags?: string[];
+        score?: number;
+    }): Promise<MemoryEntry>;
+    recall(userId: string, query: string, opts?: {
+        limit?: number;
+        tags?: string[];
+    }): Promise<MemoryEntry[]>;
+    forget(userId: string, factId: string): Promise<void>;
+    list(userId: string, opts?: {
+        tags?: string[];
+        limit?: number;
+    }): Promise<MemoryEntry[]>;
+    forgetAll(userId: string): Promise<void>;
+    /**
+     * Single-string embedding via the {@link AI} facade. Returns the
+     * first (and only) embedding vector. Throws on provider/network
+     * failure; callers route through try/catch and degrade.
+     */
+    private embed;
+}
+/**
+ * Pack a `number[]` into a Float32 byte buffer. 4 bytes per dim;
+ * a 1536-dim OpenAI embedding compresses to 6144 bytes.
+ *
+ * Uses `ArrayBuffer` + `Float32Array` so the output is a portable
+ * `Uint8Array` (works in Node, browser, RN). Prisma's `Bytes`
+ * column accepts both `Uint8Array` and `Buffer`.
+ */
+export declare function serializeVector(v: number[]): Uint8Array;
+/**
+ * Reverse of {@link serializeVector}. Reads the underlying byte
+ * buffer as Float32 and returns a fresh `number[]` so callers can
+ * mutate without affecting the source row.
+ */
+export declare function deserializeVector(bytes: Uint8Array): number[];
+/**
+ * Cosine similarity in `[-1, 1]`. Returns `0` when either vector
+ * has zero magnitude, or when lengths don't match (defensive — should
+ * never happen if remember/recall use the same embedding model).
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
 //# sourceMappingURL=index.d.ts.map

package/dist/memory-embedding/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory-embedding/index.ts"],"names":[],"mappings":"AAGA,cAAc,mCAAmC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory-embedding/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,EAAE,aAAa,EAAoB,MAAM,wBAAwB,CAAA;AACxE,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACX,MAAM,kBAAkB,CAAA;AAEzB,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAA;IACpB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;;OASG;IACH,qBAAqB,CAAC,EAAE,eAAe,GAAG,MAAM,CAAA;CACjD;AAED,qBAAa,mBAAoB,YAAW,UAAU;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;gBAEvC,IAAI,EAAE,0BAA0B;IAOtC,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAI,MAAM,EACd,IAAI,CAAC,EAAG;QAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1C,OAAO,CAAC,WAAW,CAAC;IAkBjB,MAAM,CACV,MAAM,EAAE,MAAM,EACd,KAAK,EAAG,MAAM,EACd,IAAI,CAAC,EAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC1C,OAAO,CAAC,WAAW,EAAE,CAAC;IA4CnB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrD,IAAI,CACR,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAG;QAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1C,OAAO,CAAC,WAAW,EAAE,CAAC;IAInB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK9C;;;;OAIG;YACW,KAAK;CAMpB;AAID;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,UAAU,CAKvD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE,CAK7D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAcjE"}