@usewhisper/sdk 1.0.1 → 2.0.0

package/index.d.mts

@@ -1,3 +1,154 @@
+/**
+ * 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;
+}
+interface ContextResult {
+    context: string;
+    results: QueryResult["results"];
+    count: 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<{
+        success: boolean;
+        memoryId?: string;
+    }>;
+    /**
+     * Alias for remember() - same thing
+     */
+    capture(content: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        memoryId?: string;
+    }>;
+    /**
+     * 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;
+    }>;
+    /**
+     * Direct access to WhisperContext for advanced usage
+     */
+    raw(): WhisperContext;
+}
+
 /**
  * Whisper Context SDK
  * TypeScript SDK for the Whisper Context API
@@ -170,16 +321,19 @@ declare class WhisperContext {
     addMemory(params: {
         project?: string;
         content: string;
-        memory_type?: "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
+        memory_type?: "factual" | "episodic" | "semantic" | "procedural" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
         user_id?: string;
         session_id?: string;
         agent_id?: string;
         importance?: number;
         metadata?: Record<string, any>;
         expires_in_seconds?: number;
+        allow_legacy_fallback?: boolean;
     }): Promise<{
         id: string;
         success: boolean;
+        path: "sota" | "legacy";
+        fallback_used: boolean;
     }>;
     searchMemories(params: {
         project?: string;
@@ -399,6 +553,56 @@ declare class WhisperContext {
         start_date?: string;
         end_date?: string;
     }): Promise<any>;
+    /**
+     * Semantic search over raw documents without pre-indexing.
+     * Send file contents/summaries directly — the API embeds them in-memory and ranks by similarity.
+     * Perfect for AI agents to semantically explore a codebase on-the-fly.
+     */
+    semanticSearch(params: {
+        query: string;
+        documents: Array<{
+            id: string;
+            content: string;
+        }>;
+        top_k?: number;
+        threshold?: number;
+    }): Promise<{
+        results: Array<{
+            id: string;
+            score: number;
+            content: string;
+            snippet: string;
+        }>;
+        total_searched: number;
+        total_returned: number;
+        query: string;
+        latency_ms: number;
+    }>;
+    searchFiles(params: {
+        query: string;
+        path?: string;
+        mode?: "content" | "filename" | "both";
+        file_types?: string[];
+        max_results?: number;
+        context_lines?: number;
+        case_sensitive?: boolean;
+    }): Promise<{
+        results: Array<{
+            file: string;
+            matches: Array<{
+                line: number;
+                content: string;
+                context_before: string[];
+                context_after: string[];
+            }>;
+        }>;
+        total_files: number;
+        total_matches: number;
+        search_path: string;
+        mode: string;
+        latency_ms: number;
+        engine: "ripgrep" | "node";
+    }>;
     getCostSavings(params?: {
         project?: string;
         start_date?: string;
@@ -434,6 +638,8 @@ declare class WhisperContext {
         add: (params: Parameters<WhisperContext["addMemory"]>[0]) => Promise<{
             id: string;
             success: boolean;
+            path: "sota" | "legacy";
+            fallback_used: boolean;
         }>;
         search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<any>;
         searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<any>;
@@ -556,4 +762,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 Memory, type Project, type QueryParams, type QueryResult, type Source, Whisper, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperContext as default };

package/index.d.ts

@@ -1,3 +1,154 @@
+/**
+ * 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;
+}
+interface ContextResult {
+    context: string;
+    results: QueryResult["results"];
+    count: 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<{
+        success: boolean;
+        memoryId?: string;
+    }>;
+    /**
+     * Alias for remember() - same thing
+     */
+    capture(content: string, options?: {
+        userId?: string;
+        sessionId?: string;
+        project?: string;
+    }): Promise<{
+        success: boolean;
+        memoryId?: string;
+    }>;
+    /**
+     * 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;
+    }>;
+    /**
+     * Direct access to WhisperContext for advanced usage
+     */
+    raw(): WhisperContext;
+}
+
 /**
  * Whisper Context SDK
  * TypeScript SDK for the Whisper Context API
@@ -170,16 +321,19 @@ declare class WhisperContext {
     addMemory(params: {
         project?: string;
         content: string;
-        memory_type?: "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
+        memory_type?: "factual" | "episodic" | "semantic" | "procedural" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
         user_id?: string;
         session_id?: string;
         agent_id?: string;
         importance?: number;
         metadata?: Record<string, any>;
         expires_in_seconds?: number;
+        allow_legacy_fallback?: boolean;
     }): Promise<{
         id: string;
         success: boolean;
+        path: "sota" | "legacy";
+        fallback_used: boolean;
     }>;
     searchMemories(params: {
         project?: string;
@@ -399,6 +553,56 @@ declare class WhisperContext {
         start_date?: string;
         end_date?: string;
     }): Promise<any>;
+    /**
+     * Semantic search over raw documents without pre-indexing.
+     * Send file contents/summaries directly — the API embeds them in-memory and ranks by similarity.
+     * Perfect for AI agents to semantically explore a codebase on-the-fly.
+     */
+    semanticSearch(params: {
+        query: string;
+        documents: Array<{
+            id: string;
+            content: string;
+        }>;
+        top_k?: number;
+        threshold?: number;
+    }): Promise<{
+        results: Array<{
+            id: string;
+            score: number;
+            content: string;
+            snippet: string;
+        }>;
+        total_searched: number;
+        total_returned: number;
+        query: string;
+        latency_ms: number;
+    }>;
+    searchFiles(params: {
+        query: string;
+        path?: string;
+        mode?: "content" | "filename" | "both";
+        file_types?: string[];
+        max_results?: number;
+        context_lines?: number;
+        case_sensitive?: boolean;
+    }): Promise<{
+        results: Array<{
+            file: string;
+            matches: Array<{
+                line: number;
+                content: string;
+                context_before: string[];
+                context_after: string[];
+            }>;
+        }>;
+        total_files: number;
+        total_matches: number;
+        search_path: string;
+        mode: string;
+        latency_ms: number;
+        engine: "ripgrep" | "node";
+    }>;
     getCostSavings(params?: {
         project?: string;
         start_date?: string;
@@ -434,6 +638,8 @@ declare class WhisperContext {
         add: (params: Parameters<WhisperContext["addMemory"]>[0]) => Promise<{
             id: string;
             success: boolean;
+            path: "sota" | "legacy";
+            fallback_used: boolean;
         }>;
         search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<any>;
         searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<any>;
@@ -556,4 +762,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 Memory, type Project, type QueryParams, type QueryResult, type Source, Whisper, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperContext as default };