@usewhisper/sdk 1.1.0 → 2.1.0

package/index.d.mts

@@ -1,3 +1,244 @@
+/**
+ * Whisper - Simple Memory Layer for AI Agents
+ *
+ * Two methods:
+ * - getContext(): Retrieve relevant context before LLM call
+ * - capture(): Extract and store memories after LLM response
+ *
+ * Zero magic - you control when to get context and when to capture
+ */
+
+interface WhisperOptions extends WhisperConfig {
+    /**
+     * Maximum context results to retrieve.
+     * Default: 10
+     */
+    contextLimit?: number;
+    /**
+     * Which memory types to use.
+     * Default: all 7 types
+     */
+    memoryTypes?: Array<"factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction">;
+    /**
+     * Prefix for context injection.
+     * Default: "Relevant context:"
+     */
+    contextPrefix?: string;
+    /**
+     * Extract structured memories before writing.
+     * Default: true
+     */
+    autoExtract?: boolean;
+    /**
+     * Minimum extraction confidence for auto-write.
+     * Default: 0.65
+     */
+    autoExtractMinConfidence?: number;
+    /**
+     * Maximum extracted memories to write per remember/capture call.
+     * Default: 5
+     */
+    maxMemoriesPerCapture?: number;
+}
+interface ContextResult {
+    context: string;
+    results: QueryResult["results"];
+    count: number;
+}
+interface RememberResult {
+    success: boolean;
+    memoryId?: string;
+    memoryIds?: string[];
+    extracted?: number;
+}
+/**
+ * Simple, transparent memory layer
+ *
+ * @example
+ * ```typescript
+ * import { Whisper } from '@usewhisper/sdk';
+ *
+ * const whisper = new Whisper({
+ *   apiKey: process.env.WHISPER_KEY,
+ *   project: 'my-app'
+ * });
+ *
+ * // BEFORE: Get relevant context
+ * const { context, results } = await whisper.getContext("What does user prefer?");
+ *
+ * // Inject context into your LLM prompt
+ * const prompt = `${context}\n\nUser: What does user prefer?`;
+ * const response = await llm.complete(prompt);
+ *
+ * // AFTER: Capture what happened
+ * await whisper.capture(response);
+ * // → Memories extracted & stored (async)
+ * ```
+ */
+declare class Whisper {
+    private client;
+    private options;
+    private sessionId?;
+    private userId?;
+    constructor(options: WhisperOptions);
+    /**
+     * Set session ID for conversation tracking
+     */
+    session(sessionId: string): this;
+    /**
+     * Set user ID for user-specific memories
+     */
+    user(userId: string): 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 }
+     * // ]
+     * ```
+     */
+    getContext(query: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+        limit?: number;
+    }): Promise<ContextResult>;
+    /**
+     * 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
+     * ```
+     */
+    remember(content: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<RememberResult>;
+    /**
+     * Alias for remember() - same thing
+     */
+    capture(content: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<RememberResult>;
+    /**
+     * Capture from multiple messages (e.g., full conversation)
+     */
+    captureSession(messages: Array<{
+        role: string;
+        content: string;
+    }>, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        extracted: number;
+    }>;
+    /**
+     * Run a full agent turn with automatic memory read (before) + write (after).
+     */
+    runTurn(params: {
+        userMessage: string;
+        generate: (prompt: string) => Promise<string>;
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+        limit?: number;
+    }): Promise<{
+        response: string;
+        context: string;
+        count: number;
+        extracted: number;
+    }>;
+    /**
+     * Direct access to WhisperContext for advanced usage
+     */
+    raw(): WhisperContext;
+    private extractMemoryIdsFromBulkResponse;
+}
+
+interface AgentMiddlewareConfig extends WhisperOptions {
+    /**
+     * Build the prompt passed to the model.
+     */
+    promptBuilder?: (params: {
+        context: string;
+        userMessage: string;
+    }) => string;
+}
+interface AgentTurnParams {
+    userMessage: string;
+    userId?: string;
+    sessionId?: string;
+    project?: string;
+    contextLimit?: number;
+}
+interface AgentTurnResult {
+    prompt: string;
+    context: string;
+    contextCount: number;
+}
+interface WrappedGenerateResult {
+    response: string;
+    prompt: string;
+    context: string;
+    contextCount: number;
+    extracted: number;
+}
+/**
+ * Drop-in middleware for existing AI agents.
+ *
+ * Typical flow:
+ * 1) beforeTurn -> retrieve context
+ * 2) call your model
+ * 3) afterTurn -> store memories
+ */
+declare class WhisperAgentMiddleware {
+    private readonly whisper;
+    private readonly promptBuilder;
+    constructor(config: AgentMiddlewareConfig);
+    beforeTurn(params: AgentTurnParams): Promise<AgentTurnResult>;
+    afterTurn(params: {
+        userMessage: string;
+        assistantMessage: string;
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        extracted: number;
+    }>;
+    wrapGenerate(params: AgentTurnParams & {
+        generate: (prompt: string) => Promise<string>;
+    }): Promise<WrappedGenerateResult>;
+    raw(): Whisper;
+}
+declare function createAgentMiddleware(config: AgentMiddlewareConfig): WhisperAgentMiddleware;
+
 /**
  * Whisper Context SDK
  * TypeScript SDK for the Whisper Context API
@@ -6,7 +247,6 @@ interface WhisperConfig {
     apiKey: string;
     baseUrl?: string;
     project?: string;
-    orgId?: string;
     timeoutMs?: number;
     retry?: {
         maxAttempts?: number;
@@ -95,6 +335,23 @@ interface Memory {
     createdAt: string;
     updatedAt: string;
 }
+type MemoryKind = "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
+interface ExtractedMemory {
+    content: string;
+    memoryType: MemoryKind;
+    entityMentions: string[];
+    eventDate: string | null;
+    confidence: number;
+    reasoning?: string;
+    inferred?: boolean;
+}
+interface MemoryExtractionResult {
+    explicit: ExtractedMemory[];
+    implicit: ExtractedMemory[];
+    all: ExtractedMemory[];
+    extractionMethod: "pattern" | "inference" | "hybrid" | "skipped";
+    latencyMs: number;
+}
 type WhisperErrorCode = "INVALID_API_KEY" | "PROJECT_NOT_FOUND" | "PROJECT_AMBIGUOUS" | "RATE_LIMITED" | "TEMPORARY_UNAVAILABLE" | "NETWORK_ERROR" | "TIMEOUT" | "REQUEST_FAILED" | "MISSING_PROJECT";
 declare class WhisperError extends Error {
     code: WhisperErrorCode;
@@ -113,7 +370,6 @@ declare class WhisperContext {
     private apiKey;
     private baseUrl;
     private defaultProject?;
-    private orgId?;
     private timeoutMs;
     private retryConfig;
     private projectRefToId;
@@ -184,6 +440,51 @@ declare class WhisperContext {
         path: "sota" | "legacy";
         fallback_used: boolean;
     }>;
+    addMemoriesBulk(params: {
+        project?: string;
+        memories: Array<{
+            content: string;
+            memory_type?: MemoryKind | "episodic" | "semantic" | "procedural";
+            user_id?: string;
+            session_id?: string;
+            agent_id?: string;
+            importance?: number;
+            confidence?: number;
+            metadata?: Record<string, any>;
+            entity_mentions?: string[];
+            document_date?: string;
+            event_date?: string;
+        }>;
+        namespace?: string;
+        tags?: string[];
+        async?: boolean;
+        webhook_url?: string;
+    }): Promise<any>;
+    extractMemories(params: {
+        project?: string;
+        message: string;
+        context?: string;
+        session_id?: string;
+        user_id?: string;
+        enable_pattern?: boolean;
+        enable_inference?: boolean;
+        min_confidence?: number;
+    }): Promise<MemoryExtractionResult>;
+    extractSessionMemories(params: {
+        project?: string;
+        user_id?: string;
+        messages: Array<{
+            role: "user" | "assistant" | "system";
+            content: string;
+            timestamp?: string;
+        }>;
+        enable_pattern?: boolean;
+        enable_inference?: boolean;
+    }): Promise<{
+        memories: ExtractedMemory[];
+        count: number;
+        latencyMs: number;
+    }>;
     searchMemories(params: {
         project?: string;
         query: string;
@@ -490,6 +791,13 @@ declare class WhisperContext {
             path: "sota" | "legacy";
             fallback_used: boolean;
         }>;
+        addBulk: (params: Parameters<WhisperContext["addMemoriesBulk"]>[0]) => Promise<any>;
+        extract: (params: Parameters<WhisperContext["extractMemories"]>[0]) => Promise<MemoryExtractionResult>;
+        extractSession: (params: Parameters<WhisperContext["extractSessionMemories"]>[0]) => Promise<{
+            memories: ExtractedMemory[];
+            count: number;
+            latencyMs: number;
+        }>;
         search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<any>;
         searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<any>;
         ingestSession: (params: Parameters<WhisperContext["ingestSession"]>[0]) => Promise<{
@@ -611,4 +919,4 @@ declare class WhisperContext {
     };
 }
 
-export { type Memory, type Project, type QueryParams, type QueryResult, type Source, type WhisperConfig, WhisperContext, WhisperError, type WhisperErrorCode, WhisperContext as default };
+export { type ExtractedMemory, type Memory, type MemoryExtractionResult, type MemoryKind, type Project, type QueryParams, type QueryResult, type Source, Whisper, WhisperAgentMiddleware, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, createAgentMiddleware, WhisperContext as default };

package/index.d.ts

@@ -1,3 +1,244 @@
+/**
+ * Whisper - Simple Memory Layer for AI Agents
+ *
+ * Two methods:
+ * - getContext(): Retrieve relevant context before LLM call
+ * - capture(): Extract and store memories after LLM response
+ *
+ * Zero magic - you control when to get context and when to capture
+ */
+
+interface WhisperOptions extends WhisperConfig {
+    /**
+     * Maximum context results to retrieve.
+     * Default: 10
+     */
+    contextLimit?: number;
+    /**
+     * Which memory types to use.
+     * Default: all 7 types
+     */
+    memoryTypes?: Array<"factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction">;
+    /**
+     * Prefix for context injection.
+     * Default: "Relevant context:"
+     */
+    contextPrefix?: string;
+    /**
+     * Extract structured memories before writing.
+     * Default: true
+     */
+    autoExtract?: boolean;
+    /**
+     * Minimum extraction confidence for auto-write.
+     * Default: 0.65
+     */
+    autoExtractMinConfidence?: number;
+    /**
+     * Maximum extracted memories to write per remember/capture call.
+     * Default: 5
+     */
+    maxMemoriesPerCapture?: number;
+}
+interface ContextResult {
+    context: string;
+    results: QueryResult["results"];
+    count: number;
+}
+interface RememberResult {
+    success: boolean;
+    memoryId?: string;
+    memoryIds?: string[];
+    extracted?: number;
+}
+/**
+ * Simple, transparent memory layer
+ *
+ * @example
+ * ```typescript
+ * import { Whisper } from '@usewhisper/sdk';
+ *
+ * const whisper = new Whisper({
+ *   apiKey: process.env.WHISPER_KEY,
+ *   project: 'my-app'
+ * });
+ *
+ * // BEFORE: Get relevant context
+ * const { context, results } = await whisper.getContext("What does user prefer?");
+ *
+ * // Inject context into your LLM prompt
+ * const prompt = `${context}\n\nUser: What does user prefer?`;
+ * const response = await llm.complete(prompt);
+ *
+ * // AFTER: Capture what happened
+ * await whisper.capture(response);
+ * // → Memories extracted & stored (async)
+ * ```
+ */
+declare class Whisper {
+    private client;
+    private options;
+    private sessionId?;
+    private userId?;
+    constructor(options: WhisperOptions);
+    /**
+     * Set session ID for conversation tracking
+     */
+    session(sessionId: string): this;
+    /**
+     * Set user ID for user-specific memories
+     */
+    user(userId: string): 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 }
+     * // ]
+     * ```
+     */
+    getContext(query: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+        limit?: number;
+    }): Promise<ContextResult>;
+    /**
+     * 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
+     * ```
+     */
+    remember(content: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<RememberResult>;
+    /**
+     * Alias for remember() - same thing
+     */
+    capture(content: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<RememberResult>;
+    /**
+     * Capture from multiple messages (e.g., full conversation)
+     */
+    captureSession(messages: Array<{
+        role: string;
+        content: string;
+    }>, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        extracted: number;
+    }>;
+    /**
+     * Run a full agent turn with automatic memory read (before) + write (after).
+     */
+    runTurn(params: {
+        userMessage: string;
+        generate: (prompt: string) => Promise<string>;
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+        limit?: number;
+    }): Promise<{
+        response: string;
+        context: string;
+        count: number;
+        extracted: number;
+    }>;
+    /**
+     * Direct access to WhisperContext for advanced usage
+     */
+    raw(): WhisperContext;
+    private extractMemoryIdsFromBulkResponse;
+}
+
+interface AgentMiddlewareConfig extends WhisperOptions {
+    /**
+     * Build the prompt passed to the model.
+     */
+    promptBuilder?: (params: {
+        context: string;
+        userMessage: string;
+    }) => string;
+}
+interface AgentTurnParams {
+    userMessage: string;
+    userId?: string;
+    sessionId?: string;
+    project?: string;
+    contextLimit?: number;
+}
+interface AgentTurnResult {
+    prompt: string;
+    context: string;
+    contextCount: number;
+}
+interface WrappedGenerateResult {
+    response: string;
+    prompt: string;
+    context: string;
+    contextCount: number;
+    extracted: number;
+}
+/**
+ * Drop-in middleware for existing AI agents.
+ *
+ * Typical flow:
+ * 1) beforeTurn -> retrieve context
+ * 2) call your model
+ * 3) afterTurn -> store memories
+ */
+declare class WhisperAgentMiddleware {
+    private readonly whisper;
+    private readonly promptBuilder;
+    constructor(config: AgentMiddlewareConfig);
+    beforeTurn(params: AgentTurnParams): Promise<AgentTurnResult>;
+    afterTurn(params: {
+        userMessage: string;
+        assistantMessage: string;
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        extracted: number;
+    }>;
+    wrapGenerate(params: AgentTurnParams & {
+        generate: (prompt: string) => Promise<string>;
+    }): Promise<WrappedGenerateResult>;
+    raw(): Whisper;
+}
+declare function createAgentMiddleware(config: AgentMiddlewareConfig): WhisperAgentMiddleware;
+
 /**
  * Whisper Context SDK
  * TypeScript SDK for the Whisper Context API
@@ -6,7 +247,6 @@ interface WhisperConfig {
     apiKey: string;
     baseUrl?: string;
     project?: string;
-    orgId?: string;
     timeoutMs?: number;
     retry?: {
         maxAttempts?: number;
@@ -95,6 +335,23 @@ interface Memory {
     createdAt: string;
     updatedAt: string;
 }
+type MemoryKind = "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
+interface ExtractedMemory {
+    content: string;
+    memoryType: MemoryKind;
+    entityMentions: string[];
+    eventDate: string | null;
+    confidence: number;
+    reasoning?: string;
+    inferred?: boolean;
+}
+interface MemoryExtractionResult {
+    explicit: ExtractedMemory[];
+    implicit: ExtractedMemory[];
+    all: ExtractedMemory[];
+    extractionMethod: "pattern" | "inference" | "hybrid" | "skipped";
+    latencyMs: number;
+}
 type WhisperErrorCode = "INVALID_API_KEY" | "PROJECT_NOT_FOUND" | "PROJECT_AMBIGUOUS" | "RATE_LIMITED" | "TEMPORARY_UNAVAILABLE" | "NETWORK_ERROR" | "TIMEOUT" | "REQUEST_FAILED" | "MISSING_PROJECT";
 declare class WhisperError extends Error {
     code: WhisperErrorCode;
@@ -113,7 +370,6 @@ declare class WhisperContext {
     private apiKey;
     private baseUrl;
     private defaultProject?;
-    private orgId?;
     private timeoutMs;
     private retryConfig;
     private projectRefToId;
@@ -184,6 +440,51 @@ declare class WhisperContext {
         path: "sota" | "legacy";
         fallback_used: boolean;
     }>;
+    addMemoriesBulk(params: {
+        project?: string;
+        memories: Array<{
+            content: string;
+            memory_type?: MemoryKind | "episodic" | "semantic" | "procedural";
+            user_id?: string;
+            session_id?: string;
+            agent_id?: string;
+            importance?: number;
+            confidence?: number;
+            metadata?: Record<string, any>;
+            entity_mentions?: string[];
+            document_date?: string;
+            event_date?: string;
+        }>;
+        namespace?: string;
+        tags?: string[];
+        async?: boolean;
+        webhook_url?: string;
+    }): Promise<any>;
+    extractMemories(params: {
+        project?: string;
+        message: string;
+        context?: string;
+        session_id?: string;
+        user_id?: string;
+        enable_pattern?: boolean;
+        enable_inference?: boolean;
+        min_confidence?: number;
+    }): Promise<MemoryExtractionResult>;
+    extractSessionMemories(params: {
+        project?: string;
+        user_id?: string;
+        messages: Array<{
+            role: "user" | "assistant" | "system";
+            content: string;
+            timestamp?: string;
+        }>;
+        enable_pattern?: boolean;
+        enable_inference?: boolean;
+    }): Promise<{
+        memories: ExtractedMemory[];
+        count: number;
+        latencyMs: number;
+    }>;
     searchMemories(params: {
         project?: string;
         query: string;
@@ -490,6 +791,13 @@ declare class WhisperContext {
             path: "sota" | "legacy";
             fallback_used: boolean;
         }>;
+        addBulk: (params: Parameters<WhisperContext["addMemoriesBulk"]>[0]) => Promise<any>;
+        extract: (params: Parameters<WhisperContext["extractMemories"]>[0]) => Promise<MemoryExtractionResult>;
+        extractSession: (params: Parameters<WhisperContext["extractSessionMemories"]>[0]) => Promise<{
+            memories: ExtractedMemory[];
+            count: number;
+            latencyMs: number;
+        }>;
         search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<any>;
         searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<any>;
         ingestSession: (params: Parameters<WhisperContext["ingestSession"]>[0]) => Promise<{
@@ -611,4 +919,4 @@ declare class WhisperContext {
     };
 }
 
-export { type Memory, type Project, type QueryParams, type QueryResult, type Source, type WhisperConfig, WhisperContext, WhisperError, type WhisperErrorCode, WhisperContext as default };
+export { type ExtractedMemory, type Memory, type MemoryExtractionResult, type MemoryKind, type Project, type QueryParams, type QueryResult, type Source, Whisper, WhisperAgentMiddleware, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, createAgentMiddleware, WhisperContext as default };