@usewhisper/sdk 1.1.0 → 2.1.0

package/index.js

@@ -20,11 +20,333 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // ../src/sdk/index.ts
 var index_exports = {};
 __export(index_exports, {
+  Whisper: () => Whisper,
+  WhisperAgentMiddleware: () => WhisperAgentMiddleware,
   WhisperContext: () => WhisperContext,
+  WhisperDefault: () => whisper_agent_default,
   WhisperError: () => WhisperError,
+  createAgentMiddleware: () => createAgentMiddleware,
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
+
+// ../src/sdk/whisper-agent.ts
+var Whisper = class {
+  client;
+  options;
+  sessionId;
+  userId;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("API key is required");
+    }
+    const clientConfig = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl,
+      project: options.project || "default"
+    };
+    if (options.timeoutMs) clientConfig.timeoutMs = options.timeoutMs;
+    if (options.retry) clientConfig.retry = options.retry;
+    this.client = new WhisperContext(clientConfig);
+    const finalRetry = options.retry || { maxAttempts: 3, baseDelayMs: 250, maxDelayMs: 2e3 };
+    this.options = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl || "https://context.usewhisper.dev",
+      project: options.project || "default",
+      timeoutMs: options.timeoutMs || 15e3,
+      retry: finalRetry,
+      contextLimit: options.contextLimit ?? 10,
+      memoryTypes: options.memoryTypes ?? ["factual", "preference", "event", "goal", "relationship", "opinion", "instruction"],
+      contextPrefix: options.contextPrefix ?? "Relevant context:",
+      autoExtract: options.autoExtract ?? true,
+      autoExtractMinConfidence: options.autoExtractMinConfidence ?? 0.65,
+      maxMemoriesPerCapture: options.maxMemoriesPerCapture ?? 5
+    };
+  }
+  /**
+   * Set session ID for conversation tracking
+   */
+  session(sessionId) {
+    this.sessionId = sessionId;
+    return this;
+  }
+  /**
+   * Set user ID for user-specific memories
+   */
+  user(userId) {
+    this.userId = userId;
+    return this;
+  }
+  /**
+   * Get relevant context BEFORE your LLM call
+   * 
+   * @param query - What you want to know / user question
+   * @returns Context string and raw results
+   * 
+   * @example
+   * ```typescript
+   * const { context, results, count } = await whisper.getContext(
+   *   "What are user's preferences?",
+   *   { userId: "user-123" }
+   * );
+   * 
+   * // Results: [
+   * //   { content: "User prefers dark mode", type: "preference", score: 0.95 },
+   * //   { content: "Allergic to nuts", type: "factual", score: 0.89 }
+   * // ]
+   * ```
+   */
+  async getContext(query, options) {
+    const result = await this.client.query({
+      project: options?.project ?? this.options.project,
+      query,
+      top_k: options?.limit ?? this.options.contextLimit,
+      include_memories: true,
+      user_id: options?.userId ?? this.userId,
+      session_id: options?.sessionId ?? this.sessionId
+    });
+    const context = result.results.map((r, i) => `[${i + 1}] ${r.content}`).join("\n");
+    return {
+      context: context ? `${this.options.contextPrefix}
+${context}` : "",
+      results: result.results,
+      count: result.meta.total
+    };
+  }
+  /**
+   * Remember what happened AFTER your LLM response
+   * 
+   * Fire-and-forget - doesn't block your response
+   * 
+   * @param content - What your LLM responded with
+   * @returns Promise that resolves when stored (or fails silently)
+   * 
+   * @example
+   * ```typescript
+   * const llmResponse = "I've set your theme to dark mode and removed nuts from recommendations.";
+   * 
+   * await whisper.remember(llmResponse, { userId: "user-123" });
+   * // → Auto-extracts: "theme set to dark mode", "nut allergy"
+   * // → Stored as preferences
+   * ```
+   */
+  async remember(content, options) {
+    if (!content || content.length < 5) {
+      return { success: false };
+    }
+    try {
+      if (this.options.autoExtract) {
+        const extraction = await this.client.extractMemories({
+          project: options?.project ?? this.options.project,
+          message: content,
+          user_id: options?.userId ?? this.userId,
+          session_id: options?.sessionId ?? this.sessionId,
+          enable_pattern: true,
+          enable_inference: true,
+          min_confidence: this.options.autoExtractMinConfidence
+        });
+        const extractedMemories = (extraction.all || []).filter((m) => (m.confidence || 0) >= this.options.autoExtractMinConfidence).slice(0, this.options.maxMemoriesPerCapture);
+        if (extractedMemories.length > 0) {
+          const bulk = await this.client.addMemoriesBulk({
+            project: options?.project ?? this.options.project,
+            async: false,
+            memories: extractedMemories.map((m) => ({
+              content: m.content,
+              memory_type: m.memoryType,
+              user_id: options?.userId ?? this.userId,
+              session_id: options?.sessionId ?? this.sessionId,
+              importance: Math.max(0.5, Math.min(1, m.confidence || 0.7)),
+              confidence: m.confidence || 0.7,
+              entity_mentions: m.entityMentions || [],
+              event_date: m.eventDate || void 0,
+              metadata: {
+                extracted: true,
+                extraction_method: extraction.extractionMethod,
+                extraction_reasoning: m.reasoning,
+                inferred: Boolean(m.inferred)
+              }
+            }))
+          });
+          const memoryIds = this.extractMemoryIdsFromBulkResponse(bulk);
+          return {
+            success: true,
+            memoryId: memoryIds[0],
+            memoryIds: memoryIds.length > 0 ? memoryIds : void 0,
+            extracted: extractedMemories.length
+          };
+        }
+      }
+      const result = await this.client.addMemory({
+        project: options?.project ?? this.options.project,
+        content,
+        user_id: options?.userId ?? this.userId,
+        session_id: options?.sessionId ?? this.sessionId
+      });
+      return {
+        success: true,
+        memoryId: result?.id
+      };
+    } catch (error) {
+      console.error("[Whisper] Remember failed:", error);
+      return { success: false };
+    }
+  }
+  /**
+   * Alias for remember() - same thing
+   */
+  async capture(content, options) {
+    return this.remember(content, options);
+  }
+  /**
+   * Capture from multiple messages (e.g., full conversation)
+   */
+  async captureSession(messages, options) {
+    try {
+      const result = await this.client.ingestSession({
+        project: options?.project ?? this.options.project,
+        session_id: options?.sessionId ?? this.sessionId ?? "default",
+        user_id: options?.userId ?? this.userId,
+        messages: messages.filter((m) => m.role !== "system").map((m) => ({
+          role: m.role,
+          content: m.content,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }))
+      });
+      return {
+        success: true,
+        extracted: result?.memories_created ?? 0
+      };
+    } catch (error) {
+      console.error("[Whisper] Session capture failed:", error);
+      return { success: false, extracted: 0 };
+    }
+  }
+  /**
+   * Run a full agent turn with automatic memory read (before) + write (after).
+   */
+  async runTurn(params) {
+    const contextResult = await this.getContext(params.userMessage, {
+      userId: params.userId,
+      sessionId: params.sessionId,
+      project: params.project,
+      limit: params.limit
+    });
+    const prompt = contextResult.context ? `${contextResult.context}
+
+User: ${params.userMessage}` : params.userMessage;
+    const response = await params.generate(prompt);
+    const captureResult = await this.captureSession(
+      [
+        { role: "user", content: params.userMessage },
+        { role: "assistant", content: response }
+      ],
+      {
+        userId: params.userId,
+        sessionId: params.sessionId,
+        project: params.project
+      }
+    );
+    return {
+      response,
+      context: contextResult.context,
+      count: contextResult.count,
+      extracted: captureResult.extracted
+    };
+  }
+  /**
+   * Direct access to WhisperContext for advanced usage
+   */
+  raw() {
+    return this.client;
+  }
+  extractMemoryIdsFromBulkResponse(bulkResponse) {
+    const ids = [];
+    if (Array.isArray(bulkResponse?.memories)) {
+      for (const memory of bulkResponse.memories) {
+        if (memory?.id) ids.push(memory.id);
+      }
+    }
+    if (bulkResponse?.memory?.id) {
+      ids.push(bulkResponse.memory.id);
+    }
+    if (bulkResponse?.id) {
+      ids.push(bulkResponse.id);
+    }
+    return Array.from(new Set(ids));
+  }
+};
+var whisper_agent_default = Whisper;
+
+// ../src/sdk/middleware.ts
+var WhisperAgentMiddleware = class {
+  whisper;
+  promptBuilder;
+  constructor(config) {
+    this.whisper = new Whisper(config);
+    this.promptBuilder = config.promptBuilder || (({ context, userMessage }) => {
+      if (!context) return userMessage;
+      return `${context}
+
+User: ${userMessage}`;
+    });
+  }
+  async beforeTurn(params) {
+    const contextResult = await this.whisper.getContext(params.userMessage, {
+      userId: params.userId,
+      sessionId: params.sessionId,
+      project: params.project,
+      limit: params.contextLimit
+    });
+    const prompt = this.promptBuilder({
+      context: contextResult.context,
+      userMessage: params.userMessage
+    });
+    return {
+      prompt,
+      context: contextResult.context,
+      contextCount: contextResult.count
+    };
+  }
+  async afterTurn(params) {
+    return this.whisper.captureSession(
+      [
+        { role: "user", content: params.userMessage },
+        { role: "assistant", content: params.assistantMessage }
+      ],
+      {
+        userId: params.userId,
+        sessionId: params.sessionId,
+        project: params.project
+      }
+    );
+  }
+  async wrapGenerate(params) {
+    const before = await this.beforeTurn(params);
+    const response = await params.generate(before.prompt);
+    const after = await this.afterTurn({
+      userMessage: params.userMessage,
+      assistantMessage: response,
+      userId: params.userId,
+      sessionId: params.sessionId,
+      project: params.project
+    });
+    return {
+      response,
+      prompt: before.prompt,
+      context: before.context,
+      contextCount: before.contextCount,
+      extracted: after.extracted
+    };
+  }
+  raw() {
+    return this.whisper;
+  }
+};
+function createAgentMiddleware(config) {
+  return new WhisperAgentMiddleware(config);
+}
+
+// ../src/sdk/index.ts
 var WhisperError = class extends Error {
   code;
   status;
@@ -54,11 +376,24 @@ function getBackoffDelay(attempt, base, max) {
 function isLikelyProjectId(projectRef) {
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(projectRef);
 }
+function normalizeBaseUrl(url) {
+  let normalized = url.trim().replace(/\/+$/, "");
+  normalized = normalized.replace(/\/api\/v1$/i, "");
+  normalized = normalized.replace(/\/v1$/i, "");
+  normalized = normalized.replace(/\/api$/i, "");
+  return normalized;
+}
+function normalizeEndpoint(endpoint) {
+  const withLeadingSlash = endpoint.startsWith("/") ? endpoint : `/${endpoint}`;
+  if (/^\/api\/v1(\/|$)/i.test(withLeadingSlash)) {
+    return withLeadingSlash.replace(/^\/api/i, "");
+  }
+  return withLeadingSlash;
+}
 var WhisperContext = class _WhisperContext {
   apiKey;
   baseUrl;
   defaultProject;
-  orgId;
   timeoutMs;
   retryConfig;
   projectRefToId = /* @__PURE__ */ new Map();
@@ -72,9 +407,8 @@ var WhisperContext = class _WhisperContext {
       });
     }
     this.apiKey = config.apiKey;
-    this.baseUrl = config.baseUrl || "https://context.usewhisper.dev";
+    this.baseUrl = normalizeBaseUrl(config.baseUrl || "https://context.usewhisper.dev");
     this.defaultProject = config.project;
-    this.orgId = config.orgId;
     this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.retryConfig = {
       maxAttempts: config.retry?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
@@ -87,7 +421,6 @@ var WhisperContext = class _WhisperContext {
       apiKey: this.apiKey,
       baseUrl: this.baseUrl,
       project,
-      orgId: this.orgId,
       timeoutMs: this.timeoutMs,
       retry: this.retryConfig
     });
@@ -204,20 +537,28 @@ var WhisperContext = class _WhisperContext {
   }
   async request(endpoint, options = {}) {
     const maxAttempts = Math.max(1, this.retryConfig.maxAttempts);
+    const normalizedEndpoint = normalizeEndpoint(endpoint);
     let lastError;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
       try {
-        const response = await fetch(`${this.baseUrl}${endpoint}`, {
+        const headers = {
+          "Content-Type": "application/json",
+          ...options.headers
+        };
+        const hasAuthHeader = Object.keys(headers).some((k) => k.toLowerCase() === "authorization");
+        const hasApiKeyHeader = Object.keys(headers).some((k) => k.toLowerCase() === "x-api-key");
+        if (!hasAuthHeader) {
+          headers.Authorization = `Bearer ${this.apiKey}`;
+        }
+        if (!hasApiKeyHeader) {
+          headers["X-API-Key"] = this.apiKey;
+        }
+        const response = await fetch(`${this.baseUrl}${normalizedEndpoint}`, {
           ...options,
           signal: controller.signal,
-          headers: {
-            Authorization: `Bearer ${this.apiKey}`,
-            "Content-Type": "application/json",
-            ...this.orgId ? { "X-Whisper-Org-Id": this.orgId } : {},
-            ...options.headers
-          }
+          headers
         });
         clearTimeout(timeout);
         if (!response.ok) {
@@ -406,6 +747,34 @@ var WhisperContext = class _WhisperContext {
       return { id, success: true, path: "legacy", fallback_used: true };
     });
   }
+  async addMemoriesBulk(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/bulk", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    }));
+  }
+  async extractMemories(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/extract", {
+      method: "POST",
+      body: JSON.stringify({ ...params, project })
+    }));
+  }
+  async extractSessionMemories(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/extract/session", {
+      method: "POST",
+      body: JSON.stringify({
+        ...params,
+        project,
+        messages: params.messages.map((m) => ({
+          ...m,
+          timestamp: m.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+        }))
+      })
+    }));
+  }
   async searchMemories(params) {
     const projectRef = this.getRequiredProject(params.project);
     return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/memory/search", {
@@ -602,6 +971,9 @@ var WhisperContext = class _WhisperContext {
   };
   memory = {
     add: (params) => this.addMemory(params),
+    addBulk: (params) => this.addMemoriesBulk(params),
+    extract: (params) => this.extractMemories(params),
+    extractSession: (params) => this.extractSessionMemories(params),
     search: (params) => this.searchMemories(params),
     searchSOTA: (params) => this.searchMemoriesSOTA(params),
     ingestSession: (params) => this.ingestSession(params),
@@ -640,6 +1012,10 @@ var WhisperContext = class _WhisperContext {
 var index_default = WhisperContext;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Whisper,
+  WhisperAgentMiddleware,
   WhisperContext,
-  WhisperError
+  WhisperDefault,
+  WhisperError,
+  createAgentMiddleware
 });