@usewhisper/sdk 3.8.0 → 3.9.0

package/index.d.mts

@@ -1,3 +1,163 @@
+type MemoryKind$1 = "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction" | "episodic" | "semantic" | "procedural";
+interface MemoryLatencyBreakdown$1 {
+    cache_ms: number;
+    embed_ms: number;
+    vector_ms: number;
+    lexical_ms: number;
+    merge_ms: number;
+    total_ms: number;
+}
+interface MemorySearchResult {
+    memory: {
+        id: string;
+        content: string;
+        type: string;
+        entities?: string[];
+        confidence?: number;
+        version?: number;
+        temporal?: {
+            document_date?: string | null;
+            event_date?: string | null;
+            valid_from?: string | null;
+            valid_until?: string | null;
+        };
+    };
+    similarity: number;
+    relations?: Array<Record<string, unknown>>;
+    chunk?: {
+        id: string;
+        content: string;
+        metadata?: Record<string, unknown>;
+    };
+}
+interface MemorySearchResponse$1 {
+    results: MemorySearchResult[];
+    count: number;
+    query: string;
+    trace_id?: string;
+    latency_ms?: number;
+    latency_breakdown?: MemoryLatencyBreakdown$1;
+    fallback?: "vector" | "lexical";
+    mode?: "fast" | "balanced" | "quality";
+    profile?: "fast" | "balanced" | "quality";
+    include_pending?: boolean;
+    pending_overlay_count?: number;
+    cache_hit?: boolean;
+}
+interface MemoryWriteAck$1 {
+    success: boolean;
+    mode?: "async" | "sync";
+    trace_id?: string;
+    memory_id?: string;
+    job_id?: string;
+    status_url?: string;
+    accepted_at?: string;
+    visibility_sla_ms?: number;
+    pending_visibility?: boolean;
+    semantic_status?: "pending" | "ready";
+    queued?: boolean;
+    event_id?: string;
+    created?: number;
+    errors?: string[];
+}
+type LearnIngestionProfile = "auto" | "repo" | "web_docs" | "pdf_layout" | "video_transcript" | "plain_text";
+type LearnStrategyOverride = "fixed" | "recursive" | "semantic" | "hierarchical" | "adaptive";
+type LearnSourceType = "github" | "web" | "playwright" | "pdf" | "local" | "slack" | "video";
+interface LearnConversationInput {
+    mode: "conversation";
+    project?: string;
+    user_id?: string;
+    session_id: string;
+    messages: Array<{
+        role: string;
+        content: string;
+        timestamp?: string;
+    }>;
+}
+interface LearnTextInput {
+    mode: "text";
+    project?: string;
+    title: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+    tags?: string[];
+    namespace?: string;
+    options?: {
+        async?: boolean;
+        ingestion_profile?: LearnIngestionProfile;
+        strategy_override?: LearnStrategyOverride;
+        profile_config?: Record<string, unknown>;
+    };
+}
+interface LearnSourceInput {
+    mode: "source";
+    project?: string;
+    type: LearnSourceType;
+    name?: string;
+    metadata?: Record<string, string>;
+    owner?: string;
+    repo?: string;
+    branch?: string;
+    paths?: string[];
+    url?: string;
+    file_path?: string;
+    path?: string;
+    channel_ids?: string[];
+    since?: string;
+    token?: string;
+    auth_ref?: string;
+    platform?: "youtube" | "loom" | "generic";
+    language?: string;
+    options?: {
+        async?: boolean;
+        auto_index?: boolean;
+        ingestion_profile?: LearnIngestionProfile;
+        strategy_override?: LearnStrategyOverride;
+        profile_config?: Record<string, unknown>;
+        crawl_depth?: number;
+        include_paths?: string[];
+        exclude_paths?: string[];
+        glob?: string;
+        max_files?: number;
+        max_pages?: number;
+        extract_mode?: "text" | "structured" | "markdown";
+        workspace_id?: string;
+        allow_stt_fallback?: boolean;
+        max_duration_minutes?: number;
+        max_chunks?: number;
+    };
+}
+type LearnInput = LearnConversationInput | LearnTextInput | LearnSourceInput;
+interface LearnConversationResult {
+    success: true;
+    mode: "conversation";
+    project: string;
+    scope_mode: "user_session" | "session_only";
+    memories_created: number;
+    relations_created: number;
+    memories_invalidated: number;
+    errors?: string[];
+}
+interface LearnTextResult {
+    success: true;
+    mode: "text";
+    project: string;
+    status: "processing" | "completed";
+    job_id?: string | null;
+    chunks_indexed?: number;
+    source_id?: string | null;
+}
+interface LearnSourceResult {
+    success: true;
+    mode: "source";
+    project: string;
+    source_id: string;
+    status: string;
+    job_id?: string | null;
+    index_started: boolean;
+}
+type LearnResult = LearnConversationResult | LearnTextResult | LearnSourceResult;
+
 /**
  * Whisper - Simple Memory Layer for AI Agents
  *
@@ -155,6 +315,7 @@ declare class Whisper {
         userId?: string;
         sessionId?: string;
         project?: string;
+        auto_learn?: boolean;
     }): Promise<{
         success: boolean;
         extracted: number;
@@ -169,12 +330,14 @@ declare class Whisper {
         sessionId?: string;
         project?: string;
         limit?: number;
+        auto_learn?: boolean;
     }): Promise<{
         response: string;
         context: string;
         count: number;
         extracted: number;
     }>;
+    learn(input: LearnInput): Promise<LearnResult>;
     /**
      * Direct access to WhisperContext for advanced usage
      */
@@ -367,69 +530,6 @@ declare class SearchResponseCache<T = unknown> {
     private deleteByKey;
 }
 
-type MemoryKind$1 = "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction" | "episodic" | "semantic" | "procedural";
-interface MemoryLatencyBreakdown$1 {
-    cache_ms: number;
-    embed_ms: number;
-    vector_ms: number;
-    lexical_ms: number;
-    merge_ms: number;
-    total_ms: number;
-}
-interface MemorySearchResult {
-    memory: {
-        id: string;
-        content: string;
-        type: string;
-        entities?: string[];
-        confidence?: number;
-        version?: number;
-        temporal?: {
-            document_date?: string | null;
-            event_date?: string | null;
-            valid_from?: string | null;
-            valid_until?: string | null;
-        };
-    };
-    similarity: number;
-    relations?: Array<Record<string, unknown>>;
-    chunk?: {
-        id: string;
-        content: string;
-        metadata?: Record<string, unknown>;
-    };
-}
-interface MemorySearchResponse$1 {
-    results: MemorySearchResult[];
-    count: number;
-    query: string;
-    trace_id?: string;
-    latency_ms?: number;
-    latency_breakdown?: MemoryLatencyBreakdown$1;
-    fallback?: "vector" | "lexical";
-    mode?: "fast" | "balanced" | "quality";
-    profile?: "fast" | "balanced" | "quality";
-    include_pending?: boolean;
-    pending_overlay_count?: number;
-    cache_hit?: boolean;
-}
-interface MemoryWriteAck$1 {
-    success: boolean;
-    mode?: "async" | "sync";
-    trace_id?: string;
-    memory_id?: string;
-    job_id?: string;
-    status_url?: string;
-    accepted_at?: string;
-    visibility_sla_ms?: number;
-    pending_visibility?: boolean;
-    semantic_status?: "pending" | "ready";
-    queued?: boolean;
-    event_id?: string;
-    created?: number;
-    errors?: string[];
-}
-
 interface MemoryModuleOptions {
     defaultProject?: string;
     cacheEnabled?: boolean;
@@ -896,8 +996,10 @@ declare class WhisperAgentRuntime {
         success: true;
         buffered: true;
     }>;
+    private resolveLearningScope;
     afterTurn(input: TurnInput & {
         assistantMessage: string;
+        auto_learn?: boolean;
     }, context?: Partial<AgentRunContext>): Promise<TurnCaptureResult>;
     flush(reason?: string, context?: Partial<AgentRunContext>): Promise<AgentRuntimeStatus>;
     status(): AgentRuntimeStatus;
@@ -1027,6 +1129,7 @@ declare class WhisperClient {
         memories_invalidated: number;
         errors?: string[];
     } & MemoryWriteAck$1>;
+    learn(params: LearnInput): Promise<LearnResult>;
     createAgentRuntime(options?: AgentRuntimeOptions): WhisperAgentRuntime;
     withRunContext(context: RunContext): {
         memory: {
@@ -1051,6 +1154,7 @@ declare class WhisperClient {
                 sequence: number;
             }>;
         };
+        learn: (params: LearnInput) => Promise<LearnResult>;
         queue: {
             flush: () => Promise<void>;
             status: () => ReturnType<WriteQueue["status"]>;
@@ -1079,6 +1183,7 @@ interface AgentTurnParams {
     sessionId?: string;
     project?: string;
     contextLimit?: number;
+    auto_learn?: boolean;
 }
 interface AgentTurnResult {
     prompt: string;
@@ -1111,6 +1216,7 @@ declare class WhisperAgentMiddleware {
         userId?: string;
         sessionId?: string;
         project?: string;
+        auto_learn?: boolean;
     }): Promise<{
         success: boolean;
         extracted: number;
@@ -1357,7 +1463,7 @@ interface VideoIngestionStatus {
     last_error?: string | null;
     updated_at?: string;
 }
-type CanonicalSourceType = "github" | "web" | "pdf" | "local" | "slack";
+type CanonicalSourceType = "github" | "web" | "playwright" | "pdf" | "local" | "slack" | "video";
 interface CanonicalSourceCreateParams {
     type: CanonicalSourceType;
     name?: string;
@@ -1378,11 +1484,18 @@ interface CanonicalSourceCreateParams {
     path?: string;
     glob?: string;
     max_files?: number;
+    max_pages?: number;
+    extract_mode?: "text" | "structured" | "markdown";
     workspace_id?: string;
     channel_ids?: string[];
     since?: string;
     token?: string;
     auth_ref?: string;
+    platform?: "youtube" | "loom" | "generic";
+    language?: string;
+    allow_stt_fallback?: boolean;
+    max_duration_minutes?: number;
+    max_chunks?: number;
 }
 interface CanonicalSourceCreateResult {
     source_id: string;
@@ -1600,6 +1713,7 @@ declare class WhisperContext {
     }): Promise<{
         ingested: number;
     }>;
+    learn(params: LearnInput): Promise<LearnResult>;
     listMemories(params: {
         project?: string;
         user_id?: string;
@@ -2145,4 +2259,4 @@ declare class WhisperContext {
     };
 }
 
-export { type AgentRunContext, type AgentRuntimeOptions, type AgentRuntimeRankWeights, type AgentRuntimeRetrievalOptions, type AgentRuntimeSourceActivityOptions, type AgentRuntimeStatus, type CanonicalSourceCreateParams, type CanonicalSourceCreateResult, type CanonicalSourceType, type ExtractedMemory, LangChainMemoryAdapter, LangGraphCheckpointAdapter, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type MemoryWriteResult, type PreparedTurn, type Project, type QueryParams, type QueryResult, type Source, type TurnCaptureResult, type TurnInput, type VideoIngestionStatus, type VideoSourceMetadata, Whisper, WhisperAgentMiddleware, WhisperClient, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperClient as WhisperRuntimeClient, type WorkEvent, type WorkEventKind, type WorkEventSalience, createAgentMiddleware, createLangChainMemoryAdapter, createLangGraphCheckpointAdapter, WhisperContext as default, memoryGraphToMermaid };
+export { type AgentRunContext, type AgentRuntimeOptions, type AgentRuntimeRankWeights, type AgentRuntimeRetrievalOptions, type AgentRuntimeSourceActivityOptions, type AgentRuntimeStatus, type CanonicalSourceCreateParams, type CanonicalSourceCreateResult, type CanonicalSourceType, type ExtractedMemory, LangChainMemoryAdapter, LangGraphCheckpointAdapter, type LearnConversationInput, type LearnConversationResult, type LearnInput, type LearnResult, type LearnSourceInput, type LearnSourceResult, type LearnSourceType, type LearnTextInput, type LearnTextResult, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type MemoryWriteResult, type PreparedTurn, type Project, type QueryParams, type QueryResult, type Source, type TurnCaptureResult, type TurnInput, type VideoIngestionStatus, type VideoSourceMetadata, Whisper, WhisperAgentMiddleware, WhisperClient, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperClient as WhisperRuntimeClient, type WorkEvent, type WorkEventKind, type WorkEventSalience, createAgentMiddleware, createLangChainMemoryAdapter, createLangGraphCheckpointAdapter, WhisperContext as default, memoryGraphToMermaid };

package/index.d.ts

@@ -1,3 +1,163 @@
+type MemoryKind$1 = "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction" | "episodic" | "semantic" | "procedural";
+interface MemoryLatencyBreakdown$1 {
+    cache_ms: number;
+    embed_ms: number;
+    vector_ms: number;
+    lexical_ms: number;
+    merge_ms: number;
+    total_ms: number;
+}
+interface MemorySearchResult {
+    memory: {
+        id: string;
+        content: string;
+        type: string;
+        entities?: string[];
+        confidence?: number;
+        version?: number;
+        temporal?: {
+            document_date?: string | null;
+            event_date?: string | null;
+            valid_from?: string | null;
+            valid_until?: string | null;
+        };
+    };
+    similarity: number;
+    relations?: Array<Record<string, unknown>>;
+    chunk?: {
+        id: string;
+        content: string;
+        metadata?: Record<string, unknown>;
+    };
+}
+interface MemorySearchResponse$1 {
+    results: MemorySearchResult[];
+    count: number;
+    query: string;
+    trace_id?: string;
+    latency_ms?: number;
+    latency_breakdown?: MemoryLatencyBreakdown$1;
+    fallback?: "vector" | "lexical";
+    mode?: "fast" | "balanced" | "quality";
+    profile?: "fast" | "balanced" | "quality";
+    include_pending?: boolean;
+    pending_overlay_count?: number;
+    cache_hit?: boolean;
+}
+interface MemoryWriteAck$1 {
+    success: boolean;
+    mode?: "async" | "sync";
+    trace_id?: string;
+    memory_id?: string;
+    job_id?: string;
+    status_url?: string;
+    accepted_at?: string;
+    visibility_sla_ms?: number;
+    pending_visibility?: boolean;
+    semantic_status?: "pending" | "ready";
+    queued?: boolean;
+    event_id?: string;
+    created?: number;
+    errors?: string[];
+}
+type LearnIngestionProfile = "auto" | "repo" | "web_docs" | "pdf_layout" | "video_transcript" | "plain_text";
+type LearnStrategyOverride = "fixed" | "recursive" | "semantic" | "hierarchical" | "adaptive";
+type LearnSourceType = "github" | "web" | "playwright" | "pdf" | "local" | "slack" | "video";
+interface LearnConversationInput {
+    mode: "conversation";
+    project?: string;
+    user_id?: string;
+    session_id: string;
+    messages: Array<{
+        role: string;
+        content: string;
+        timestamp?: string;
+    }>;
+}
+interface LearnTextInput {
+    mode: "text";
+    project?: string;
+    title: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+    tags?: string[];
+    namespace?: string;
+    options?: {
+        async?: boolean;
+        ingestion_profile?: LearnIngestionProfile;
+        strategy_override?: LearnStrategyOverride;
+        profile_config?: Record<string, unknown>;
+    };
+}
+interface LearnSourceInput {
+    mode: "source";
+    project?: string;
+    type: LearnSourceType;
+    name?: string;
+    metadata?: Record<string, string>;
+    owner?: string;
+    repo?: string;
+    branch?: string;
+    paths?: string[];
+    url?: string;
+    file_path?: string;
+    path?: string;
+    channel_ids?: string[];
+    since?: string;
+    token?: string;
+    auth_ref?: string;
+    platform?: "youtube" | "loom" | "generic";
+    language?: string;
+    options?: {
+        async?: boolean;
+        auto_index?: boolean;
+        ingestion_profile?: LearnIngestionProfile;
+        strategy_override?: LearnStrategyOverride;
+        profile_config?: Record<string, unknown>;
+        crawl_depth?: number;
+        include_paths?: string[];
+        exclude_paths?: string[];
+        glob?: string;
+        max_files?: number;
+        max_pages?: number;
+        extract_mode?: "text" | "structured" | "markdown";
+        workspace_id?: string;
+        allow_stt_fallback?: boolean;
+        max_duration_minutes?: number;
+        max_chunks?: number;
+    };
+}
+type LearnInput = LearnConversationInput | LearnTextInput | LearnSourceInput;
+interface LearnConversationResult {
+    success: true;
+    mode: "conversation";
+    project: string;
+    scope_mode: "user_session" | "session_only";
+    memories_created: number;
+    relations_created: number;
+    memories_invalidated: number;
+    errors?: string[];
+}
+interface LearnTextResult {
+    success: true;
+    mode: "text";
+    project: string;
+    status: "processing" | "completed";
+    job_id?: string | null;
+    chunks_indexed?: number;
+    source_id?: string | null;
+}
+interface LearnSourceResult {
+    success: true;
+    mode: "source";
+    project: string;
+    source_id: string;
+    status: string;
+    job_id?: string | null;
+    index_started: boolean;
+}
+type LearnResult = LearnConversationResult | LearnTextResult | LearnSourceResult;
+
 /**
  * Whisper - Simple Memory Layer for AI Agents
  *
@@ -155,6 +315,7 @@ declare class Whisper {
         userId?: string;
         sessionId?: string;
         project?: string;
+        auto_learn?: boolean;
     }): Promise<{
         success: boolean;
         extracted: number;
@@ -169,12 +330,14 @@ declare class Whisper {
         sessionId?: string;
         project?: string;
         limit?: number;
+        auto_learn?: boolean;
     }): Promise<{
         response: string;
         context: string;
         count: number;
         extracted: number;
     }>;
+    learn(input: LearnInput): Promise<LearnResult>;
     /**
      * Direct access to WhisperContext for advanced usage
      */
@@ -367,69 +530,6 @@ declare class SearchResponseCache<T = unknown> {
     private deleteByKey;
 }
 
-type MemoryKind$1 = "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction" | "episodic" | "semantic" | "procedural";
-interface MemoryLatencyBreakdown$1 {
-    cache_ms: number;
-    embed_ms: number;
-    vector_ms: number;
-    lexical_ms: number;
-    merge_ms: number;
-    total_ms: number;
-}
-interface MemorySearchResult {
-    memory: {
-        id: string;
-        content: string;
-        type: string;
-        entities?: string[];
-        confidence?: number;
-        version?: number;
-        temporal?: {
-            document_date?: string | null;
-            event_date?: string | null;
-            valid_from?: string | null;
-            valid_until?: string | null;
-        };
-    };
-    similarity: number;
-    relations?: Array<Record<string, unknown>>;
-    chunk?: {
-        id: string;
-        content: string;
-        metadata?: Record<string, unknown>;
-    };
-}
-interface MemorySearchResponse$1 {
-    results: MemorySearchResult[];
-    count: number;
-    query: string;
-    trace_id?: string;
-    latency_ms?: number;
-    latency_breakdown?: MemoryLatencyBreakdown$1;
-    fallback?: "vector" | "lexical";
-    mode?: "fast" | "balanced" | "quality";
-    profile?: "fast" | "balanced" | "quality";
-    include_pending?: boolean;
-    pending_overlay_count?: number;
-    cache_hit?: boolean;
-}
-interface MemoryWriteAck$1 {
-    success: boolean;
-    mode?: "async" | "sync";
-    trace_id?: string;
-    memory_id?: string;
-    job_id?: string;
-    status_url?: string;
-    accepted_at?: string;
-    visibility_sla_ms?: number;
-    pending_visibility?: boolean;
-    semantic_status?: "pending" | "ready";
-    queued?: boolean;
-    event_id?: string;
-    created?: number;
-    errors?: string[];
-}
-
 interface MemoryModuleOptions {
     defaultProject?: string;
     cacheEnabled?: boolean;
@@ -896,8 +996,10 @@ declare class WhisperAgentRuntime {
         success: true;
         buffered: true;
     }>;
+    private resolveLearningScope;
     afterTurn(input: TurnInput & {
         assistantMessage: string;
+        auto_learn?: boolean;
     }, context?: Partial<AgentRunContext>): Promise<TurnCaptureResult>;
     flush(reason?: string, context?: Partial<AgentRunContext>): Promise<AgentRuntimeStatus>;
     status(): AgentRuntimeStatus;
@@ -1027,6 +1129,7 @@ declare class WhisperClient {
         memories_invalidated: number;
         errors?: string[];
     } & MemoryWriteAck$1>;
+    learn(params: LearnInput): Promise<LearnResult>;
     createAgentRuntime(options?: AgentRuntimeOptions): WhisperAgentRuntime;
     withRunContext(context: RunContext): {
         memory: {
@@ -1051,6 +1154,7 @@ declare class WhisperClient {
                 sequence: number;
             }>;
         };
+        learn: (params: LearnInput) => Promise<LearnResult>;
         queue: {
             flush: () => Promise<void>;
             status: () => ReturnType<WriteQueue["status"]>;
@@ -1079,6 +1183,7 @@ interface AgentTurnParams {
     sessionId?: string;
     project?: string;
     contextLimit?: number;
+    auto_learn?: boolean;
 }
 interface AgentTurnResult {
     prompt: string;
@@ -1111,6 +1216,7 @@ declare class WhisperAgentMiddleware {
         userId?: string;
         sessionId?: string;
         project?: string;
+        auto_learn?: boolean;
     }): Promise<{
         success: boolean;
         extracted: number;
@@ -1357,7 +1463,7 @@ interface VideoIngestionStatus {
     last_error?: string | null;
     updated_at?: string;
 }
-type CanonicalSourceType = "github" | "web" | "pdf" | "local" | "slack";
+type CanonicalSourceType = "github" | "web" | "playwright" | "pdf" | "local" | "slack" | "video";
 interface CanonicalSourceCreateParams {
     type: CanonicalSourceType;
     name?: string;
@@ -1378,11 +1484,18 @@ interface CanonicalSourceCreateParams {
     path?: string;
     glob?: string;
     max_files?: number;
+    max_pages?: number;
+    extract_mode?: "text" | "structured" | "markdown";
     workspace_id?: string;
     channel_ids?: string[];
     since?: string;
     token?: string;
     auth_ref?: string;
+    platform?: "youtube" | "loom" | "generic";
+    language?: string;
+    allow_stt_fallback?: boolean;
+    max_duration_minutes?: number;
+    max_chunks?: number;
 }
 interface CanonicalSourceCreateResult {
     source_id: string;
@@ -1600,6 +1713,7 @@ declare class WhisperContext {
     }): Promise<{
         ingested: number;
     }>;
+    learn(params: LearnInput): Promise<LearnResult>;
     listMemories(params: {
         project?: string;
         user_id?: string;
@@ -2145,4 +2259,4 @@ declare class WhisperContext {
     };
 }
 
-export { type AgentRunContext, type AgentRuntimeOptions, type AgentRuntimeRankWeights, type AgentRuntimeRetrievalOptions, type AgentRuntimeSourceActivityOptions, type AgentRuntimeStatus, type CanonicalSourceCreateParams, type CanonicalSourceCreateResult, type CanonicalSourceType, type ExtractedMemory, LangChainMemoryAdapter, LangGraphCheckpointAdapter, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type MemoryWriteResult, type PreparedTurn, type Project, type QueryParams, type QueryResult, type Source, type TurnCaptureResult, type TurnInput, type VideoIngestionStatus, type VideoSourceMetadata, Whisper, WhisperAgentMiddleware, WhisperClient, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperClient as WhisperRuntimeClient, type WorkEvent, type WorkEventKind, type WorkEventSalience, createAgentMiddleware, createLangChainMemoryAdapter, createLangGraphCheckpointAdapter, WhisperContext as default, memoryGraphToMermaid };
+export { type AgentRunContext, type AgentRuntimeOptions, type AgentRuntimeRankWeights, type AgentRuntimeRetrievalOptions, type AgentRuntimeSourceActivityOptions, type AgentRuntimeStatus, type CanonicalSourceCreateParams, type CanonicalSourceCreateResult, type CanonicalSourceType, type ExtractedMemory, LangChainMemoryAdapter, LangGraphCheckpointAdapter, type LearnConversationInput, type LearnConversationResult, type LearnInput, type LearnResult, type LearnSourceInput, type LearnSourceResult, type LearnSourceType, type LearnTextInput, type LearnTextResult, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type MemoryWriteResult, type PreparedTurn, type Project, type QueryParams, type QueryResult, type Source, type TurnCaptureResult, type TurnInput, type VideoIngestionStatus, type VideoSourceMetadata, Whisper, WhisperAgentMiddleware, WhisperClient, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperClient as WhisperRuntimeClient, type WorkEvent, type WorkEventKind, type WorkEventSalience, createAgentMiddleware, createLangChainMemoryAdapter, createLangGraphCheckpointAdapter, WhisperContext as default, memoryGraphToMermaid };

package/index.js

@@ -2126,9 +2126,33 @@ ${lines.join("\n")}`;
       }
     });
   }
+  async resolveLearningScope(overrides) {
+    const merged = {
+      ...this.baseContext,
+      ...overrides
+    };
+    const { scope } = await this.resolveScope(overrides);
+    return {
+      project: scope.project,
+      sessionId: merged.sessionId || scope.sessionId,
+      userId: merged.userId
+    };
+  }
   async afterTurn(input, context = {}) {
     this.pushTouchedFiles(input.touchedFiles);
-    const { scope } = await this.resolveScope(context);
+    if (input.auto_learn === false) {
+      return {
+        success: true,
+        sessionIngested: false,
+        memoriesCreated: 0,
+        relationsCreated: 0,
+        invalidatedCount: 0,
+        mergedCount: 0,
+        droppedCount: 0,
+        warnings: []
+      };
+    }
+    const scope = await this.resolveLearningScope(context);
     const result = await this.args.adapter.ingestSession({
       project: scope.project,
       session_id: scope.sessionId,
@@ -2511,6 +2535,19 @@ var WhisperClient = class _WhisperClient {
     });
     return response.data;
   }
+  async learn(params) {
+    const project = (await this.resolveProject(params.project)).id;
+    const response = await this.runtimeClient.request({
+      endpoint: "/v1/learn",
+      method: "POST",
+      operation: params.mode === "conversation" ? "session" : "bulk",
+      body: {
+        ...params,
+        project
+      }
+    });
+    return response.data;
+  }
   createAgentRuntime(options = {}) {
     const baseContext = {
       workspacePath: options.workspacePath,
@@ -2559,6 +2596,14 @@ var WhisperClient = class _WhisperClient {
           sessionId: params.sessionId || context.sessionId || ""
         })
       },
+      learn: (params) => base.learn({
+        ...params,
+        project: params.project || context.project || base.config.project,
+        ...params.mode === "conversation" ? {
+          user_id: params.user_id ?? context.userId,
+          session_id: params.session_id || context.sessionId || ""
+        } : {}
+      }),
       queue: base.queue,
       diagnostics: base.diagnostics
     };
@@ -2770,6 +2815,9 @@ ${context}` : "",
    * Capture from multiple messages (e.g., full conversation)
    */
   async captureSession(messages, options) {
+    if (options?.auto_learn === false) {
+      return { success: true, extracted: 0 };
+    }
     try {
       const filteredMessages = messages.filter((m) => m.role !== "system");
       const runtime = this.runtimeClient.createAgentRuntime({
@@ -2780,7 +2828,8 @@ ${context}` : "",
       });
       const result = await runtime.afterTurn({
         userMessage: [...filteredMessages].reverse().find((m) => m.role === "user")?.content || "",
-        assistantMessage: [...filteredMessages].reverse().find((m) => m.role === "assistant")?.content || ""
+        assistantMessage: [...filteredMessages].reverse().find((m) => m.role === "assistant")?.content || "",
+        auto_learn: options?.auto_learn
       });
       return {
         success: true,
@@ -2817,7 +2866,8 @@ User: ${params.userMessage}` : params.userMessage;
       {
         userId: params.userId,
         sessionId: params.sessionId,
-        project: params.project
+        project: params.project,
+        auto_learn: params.auto_learn
       }
     );
     return {
@@ -2827,6 +2877,18 @@ User: ${params.userMessage}` : params.userMessage;
       extracted: captureResult.extracted
     };
   }
+  async learn(input) {
+    const params = input.mode === "conversation" ? {
+      ...input,
+      project: input.project ?? this.options.project,
+      user_id: input.user_id ?? this.userId,
+      session_id: input.session_id || this.sessionId || "default"
+    } : {
+      ...input,
+      project: input.project ?? this.options.project
+    };
+    return this.runtimeClient.learn(params);
+  }
   /**
    * Direct access to WhisperContext for advanced usage
    */
@@ -2912,7 +2974,8 @@ User: ${userMessage}`;
       {
         userId: params.userId,
         sessionId: params.sessionId,
-        project: params.project
+        project: params.project,
+        auto_learn: params.auto_learn
       }
     );
   }
@@ -2924,7 +2987,8 @@ User: ${userMessage}`;
       assistantMessage: response,
       userId: params.userId,
       sessionId: params.sessionId,
-      project: params.project
+      project: params.project,
+      auto_learn: params.auto_learn
     });
     return {
       response,
@@ -3814,91 +3878,125 @@ var WhisperContext = class _WhisperContext {
     return this.request(`/v1/sources/${sourceId}/sync`, { method: "POST" });
   }
   async addSourceByType(projectId, params) {
-    return this.withProjectPathFallback(
-      this.getRequiredProject(projectId),
-      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}/add_source`, {
-        method: "POST",
-        body: JSON.stringify(params)
-      })
-    );
+    const result = await this.learn({
+      mode: "source",
+      project: projectId,
+      type: "video",
+      name: params.name,
+      url: params.url,
+      platform: params.platform,
+      language: params.language,
+      options: {
+        async: true,
+        auto_index: params.auto_sync ?? true,
+        ingestion_profile: params.ingestion_profile,
+        strategy_override: params.strategy_override,
+        profile_config: params.profile_config,
+        allow_stt_fallback: params.allow_stt_fallback,
+        max_duration_minutes: params.max_duration_minutes
+      }
+    });
+    return {
+      source_id: result.source_id,
+      sync_job_id: result.job_id ?? null,
+      status: result.status === "processing" || result.status === "queued" ? result.status : "created"
+    };
   }
   async getSourceStatus(sourceId) {
     return this.request(`/v1/sources/${sourceId}/status`, { method: "GET" });
   }
   async createCanonicalSource(project, params) {
-    const connector_type = params.type === "github" ? "github" : params.type === "web" ? "website" : params.type === "pdf" ? "pdf" : params.type === "local" ? "local-folder" : "slack";
-    const config = {};
-    if (params.type === "github") {
-      if (!params.owner || !params.repo) throw new WhisperError({ code: "REQUEST_FAILED", message: "github source requires owner and repo" });
-      config.owner = params.owner;
-      config.repo = params.repo;
-      if (params.branch) config.branch = params.branch;
-      if (params.paths) config.paths = params.paths;
-    } else if (params.type === "web") {
-      if (!params.url) throw new WhisperError({ code: "REQUEST_FAILED", message: "web source requires url" });
-      config.url = params.url;
-      if (params.crawl_depth !== void 0) config.crawl_depth = params.crawl_depth;
-      if (params.include_paths) config.include_paths = params.include_paths;
-      if (params.exclude_paths) config.exclude_paths = params.exclude_paths;
-    } else if (params.type === "pdf") {
-      if (!params.url && !params.file_path) throw new WhisperError({ code: "REQUEST_FAILED", message: "pdf source requires url or file_path" });
-      if (params.url) config.url = params.url;
-      if (params.file_path) config.file_path = params.file_path;
-    } else if (params.type === "local") {
-      if (!params.path) throw new WhisperError({ code: "REQUEST_FAILED", message: "local source requires path" });
-      config.path = params.path;
-      if (params.glob) config.glob = params.glob;
-      if (params.max_files !== void 0) config.max_files = params.max_files;
-    } else {
-      config.channel_ids = params.channel_ids || [];
-      if (params.since) config.since = params.since;
-      if (params.workspace_id) config.workspace_id = params.workspace_id;
-      if (params.token) config.token = params.token;
-      if (params.auth_ref) config.auth_ref = params.auth_ref;
-    }
-    if (params.metadata) config.metadata = params.metadata;
-    if (params.ingestion_profile) config.ingestion_profile = params.ingestion_profile;
-    if (params.strategy_override) config.strategy_override = params.strategy_override;
-    if (params.profile_config) config.profile_config = params.profile_config;
-    config.auto_index = params.auto_index ?? true;
-    const created = await this.addSource(project, {
-      name: params.name || `${params.type}-source-${Date.now()}`,
-      connector_type,
-      config
+    const result = await this.learn({
+      mode: "source",
+      project,
+      type: params.type,
+      name: params.name,
+      metadata: params.metadata,
+      owner: params.owner,
+      repo: params.repo,
+      branch: params.branch,
+      paths: params.paths,
+      url: params.url,
+      file_path: params.file_path,
+      path: params.path,
+      channel_ids: params.channel_ids,
+      since: params.since,
+      token: params.token,
+      auth_ref: params.auth_ref,
+      platform: params.platform,
+      language: params.language,
+      options: {
+        async: true,
+        auto_index: params.auto_index ?? true,
+        ingestion_profile: params.ingestion_profile,
+        strategy_override: params.strategy_override,
+        profile_config: params.profile_config,
+        crawl_depth: params.crawl_depth,
+        include_paths: params.include_paths,
+        exclude_paths: params.exclude_paths,
+        glob: params.glob,
+        max_files: params.max_files,
+        max_pages: params.max_pages,
+        extract_mode: params.extract_mode,
+        workspace_id: params.workspace_id,
+        allow_stt_fallback: params.allow_stt_fallback,
+        max_duration_minutes: params.max_duration_minutes,
+        max_chunks: params.max_chunks
+      }
     });
-    let status = "queued";
-    let jobId = null;
-    if (params.auto_index ?? true) {
-      const syncRes = await this.syncSource(created.id);
-      status = "indexing";
-      jobId = String(syncRes?.id || syncRes?.job_id || "");
-    }
     return {
-      source_id: created.id,
-      status,
-      job_id: jobId,
-      index_started: params.auto_index ?? true,
+      source_id: result.source_id,
+      status: result.status === "processing" ? "indexing" : result.status === "created" ? "queued" : result.status,
+      job_id: result.job_id ?? null,
+      index_started: result.index_started,
       warnings: []
     };
   }
   async ingest(projectId, documents) {
-    return this.withProjectPathFallback(
-      this.getRequiredProject(projectId),
-      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}/ingest`, {
-        method: "POST",
-        body: JSON.stringify({ documents })
-      })
+    await Promise.all(
+      documents.map(
+        (doc) => this.learn({
+          mode: "text",
+          project: projectId,
+          title: doc.title,
+          content: doc.content,
+          metadata: {
+            ...doc.metadata || {},
+            ...doc.file_path ? { file_path: doc.file_path } : {}
+          },
+          options: {
+            async: true,
+            ingestion_profile: doc.ingestion_profile,
+            strategy_override: doc.strategy_override,
+            profile_config: doc.profile_config
+          }
+        })
+      )
     );
+    return { ingested: documents.length };
   }
   async addContext(params) {
-    const projectId = (await this.resolveProject(this.getRequiredProject(params.project))).id;
-    return this.ingest(projectId, [
-      {
-        title: params.title || "Context",
-        content: params.content,
-        metadata: params.metadata || { source: "addContext" }
+    await this.learn({
+      mode: "text",
+      project: this.getRequiredProject(params.project),
+      title: params.title || "Context",
+      content: params.content,
+      metadata: params.metadata || { source: "addContext" },
+      options: {
+        async: true
       }
-    ]);
+    });
+    return { ingested: 1 };
+  }
+  async learn(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/learn", {
+      method: "POST",
+      body: JSON.stringify({
+        ...params,
+        project
+      })
+    }));
   }
   async listMemories(params) {
     const projectRef = this.getRequiredProject(params.project);

package/index.mjs

@@ -2077,9 +2077,33 @@ ${lines.join("\n")}`;
       }
     });
   }
+  async resolveLearningScope(overrides) {
+    const merged = {
+      ...this.baseContext,
+      ...overrides
+    };
+    const { scope } = await this.resolveScope(overrides);
+    return {
+      project: scope.project,
+      sessionId: merged.sessionId || scope.sessionId,
+      userId: merged.userId
+    };
+  }
   async afterTurn(input, context = {}) {
     this.pushTouchedFiles(input.touchedFiles);
-    const { scope } = await this.resolveScope(context);
+    if (input.auto_learn === false) {
+      return {
+        success: true,
+        sessionIngested: false,
+        memoriesCreated: 0,
+        relationsCreated: 0,
+        invalidatedCount: 0,
+        mergedCount: 0,
+        droppedCount: 0,
+        warnings: []
+      };
+    }
+    const scope = await this.resolveLearningScope(context);
     const result = await this.args.adapter.ingestSession({
       project: scope.project,
       session_id: scope.sessionId,
@@ -2462,6 +2486,19 @@ var WhisperClient = class _WhisperClient {
     });
     return response.data;
   }
+  async learn(params) {
+    const project = (await this.resolveProject(params.project)).id;
+    const response = await this.runtimeClient.request({
+      endpoint: "/v1/learn",
+      method: "POST",
+      operation: params.mode === "conversation" ? "session" : "bulk",
+      body: {
+        ...params,
+        project
+      }
+    });
+    return response.data;
+  }
   createAgentRuntime(options = {}) {
     const baseContext = {
       workspacePath: options.workspacePath,
@@ -2510,6 +2547,14 @@ var WhisperClient = class _WhisperClient {
           sessionId: params.sessionId || context.sessionId || ""
         })
       },
+      learn: (params) => base.learn({
+        ...params,
+        project: params.project || context.project || base.config.project,
+        ...params.mode === "conversation" ? {
+          user_id: params.user_id ?? context.userId,
+          session_id: params.session_id || context.sessionId || ""
+        } : {}
+      }),
       queue: base.queue,
       diagnostics: base.diagnostics
     };
@@ -2721,6 +2766,9 @@ ${context}` : "",
    * Capture from multiple messages (e.g., full conversation)
    */
   async captureSession(messages, options) {
+    if (options?.auto_learn === false) {
+      return { success: true, extracted: 0 };
+    }
     try {
       const filteredMessages = messages.filter((m) => m.role !== "system");
       const runtime = this.runtimeClient.createAgentRuntime({
@@ -2731,7 +2779,8 @@ ${context}` : "",
       });
       const result = await runtime.afterTurn({
         userMessage: [...filteredMessages].reverse().find((m) => m.role === "user")?.content || "",
-        assistantMessage: [...filteredMessages].reverse().find((m) => m.role === "assistant")?.content || ""
+        assistantMessage: [...filteredMessages].reverse().find((m) => m.role === "assistant")?.content || "",
+        auto_learn: options?.auto_learn
       });
       return {
         success: true,
@@ -2768,7 +2817,8 @@ User: ${params.userMessage}` : params.userMessage;
       {
         userId: params.userId,
         sessionId: params.sessionId,
-        project: params.project
+        project: params.project,
+        auto_learn: params.auto_learn
       }
     );
     return {
@@ -2778,6 +2828,18 @@ User: ${params.userMessage}` : params.userMessage;
       extracted: captureResult.extracted
     };
   }
+  async learn(input) {
+    const params = input.mode === "conversation" ? {
+      ...input,
+      project: input.project ?? this.options.project,
+      user_id: input.user_id ?? this.userId,
+      session_id: input.session_id || this.sessionId || "default"
+    } : {
+      ...input,
+      project: input.project ?? this.options.project
+    };
+    return this.runtimeClient.learn(params);
+  }
   /**
    * Direct access to WhisperContext for advanced usage
    */
@@ -2863,7 +2925,8 @@ User: ${userMessage}`;
       {
         userId: params.userId,
         sessionId: params.sessionId,
-        project: params.project
+        project: params.project,
+        auto_learn: params.auto_learn
       }
     );
   }
@@ -2875,7 +2938,8 @@ User: ${userMessage}`;
       assistantMessage: response,
       userId: params.userId,
       sessionId: params.sessionId,
-      project: params.project
+      project: params.project,
+      auto_learn: params.auto_learn
     });
     return {
       response,
@@ -3765,91 +3829,125 @@ var WhisperContext = class _WhisperContext {
     return this.request(`/v1/sources/${sourceId}/sync`, { method: "POST" });
   }
   async addSourceByType(projectId, params) {
-    return this.withProjectPathFallback(
-      this.getRequiredProject(projectId),
-      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}/add_source`, {
-        method: "POST",
-        body: JSON.stringify(params)
-      })
-    );
+    const result = await this.learn({
+      mode: "source",
+      project: projectId,
+      type: "video",
+      name: params.name,
+      url: params.url,
+      platform: params.platform,
+      language: params.language,
+      options: {
+        async: true,
+        auto_index: params.auto_sync ?? true,
+        ingestion_profile: params.ingestion_profile,
+        strategy_override: params.strategy_override,
+        profile_config: params.profile_config,
+        allow_stt_fallback: params.allow_stt_fallback,
+        max_duration_minutes: params.max_duration_minutes
+      }
+    });
+    return {
+      source_id: result.source_id,
+      sync_job_id: result.job_id ?? null,
+      status: result.status === "processing" || result.status === "queued" ? result.status : "created"
+    };
   }
   async getSourceStatus(sourceId) {
     return this.request(`/v1/sources/${sourceId}/status`, { method: "GET" });
   }
   async createCanonicalSource(project, params) {
-    const connector_type = params.type === "github" ? "github" : params.type === "web" ? "website" : params.type === "pdf" ? "pdf" : params.type === "local" ? "local-folder" : "slack";
-    const config = {};
-    if (params.type === "github") {
-      if (!params.owner || !params.repo) throw new WhisperError({ code: "REQUEST_FAILED", message: "github source requires owner and repo" });
-      config.owner = params.owner;
-      config.repo = params.repo;
-      if (params.branch) config.branch = params.branch;
-      if (params.paths) config.paths = params.paths;
-    } else if (params.type === "web") {
-      if (!params.url) throw new WhisperError({ code: "REQUEST_FAILED", message: "web source requires url" });
-      config.url = params.url;
-      if (params.crawl_depth !== void 0) config.crawl_depth = params.crawl_depth;
-      if (params.include_paths) config.include_paths = params.include_paths;
-      if (params.exclude_paths) config.exclude_paths = params.exclude_paths;
-    } else if (params.type === "pdf") {
-      if (!params.url && !params.file_path) throw new WhisperError({ code: "REQUEST_FAILED", message: "pdf source requires url or file_path" });
-      if (params.url) config.url = params.url;
-      if (params.file_path) config.file_path = params.file_path;
-    } else if (params.type === "local") {
-      if (!params.path) throw new WhisperError({ code: "REQUEST_FAILED", message: "local source requires path" });
-      config.path = params.path;
-      if (params.glob) config.glob = params.glob;
-      if (params.max_files !== void 0) config.max_files = params.max_files;
-    } else {
-      config.channel_ids = params.channel_ids || [];
-      if (params.since) config.since = params.since;
-      if (params.workspace_id) config.workspace_id = params.workspace_id;
-      if (params.token) config.token = params.token;
-      if (params.auth_ref) config.auth_ref = params.auth_ref;
-    }
-    if (params.metadata) config.metadata = params.metadata;
-    if (params.ingestion_profile) config.ingestion_profile = params.ingestion_profile;
-    if (params.strategy_override) config.strategy_override = params.strategy_override;
-    if (params.profile_config) config.profile_config = params.profile_config;
-    config.auto_index = params.auto_index ?? true;
-    const created = await this.addSource(project, {
-      name: params.name || `${params.type}-source-${Date.now()}`,
-      connector_type,
-      config
+    const result = await this.learn({
+      mode: "source",
+      project,
+      type: params.type,
+      name: params.name,
+      metadata: params.metadata,
+      owner: params.owner,
+      repo: params.repo,
+      branch: params.branch,
+      paths: params.paths,
+      url: params.url,
+      file_path: params.file_path,
+      path: params.path,
+      channel_ids: params.channel_ids,
+      since: params.since,
+      token: params.token,
+      auth_ref: params.auth_ref,
+      platform: params.platform,
+      language: params.language,
+      options: {
+        async: true,
+        auto_index: params.auto_index ?? true,
+        ingestion_profile: params.ingestion_profile,
+        strategy_override: params.strategy_override,
+        profile_config: params.profile_config,
+        crawl_depth: params.crawl_depth,
+        include_paths: params.include_paths,
+        exclude_paths: params.exclude_paths,
+        glob: params.glob,
+        max_files: params.max_files,
+        max_pages: params.max_pages,
+        extract_mode: params.extract_mode,
+        workspace_id: params.workspace_id,
+        allow_stt_fallback: params.allow_stt_fallback,
+        max_duration_minutes: params.max_duration_minutes,
+        max_chunks: params.max_chunks
+      }
     });
-    let status = "queued";
-    let jobId = null;
-    if (params.auto_index ?? true) {
-      const syncRes = await this.syncSource(created.id);
-      status = "indexing";
-      jobId = String(syncRes?.id || syncRes?.job_id || "");
-    }
     return {
-      source_id: created.id,
-      status,
-      job_id: jobId,
-      index_started: params.auto_index ?? true,
+      source_id: result.source_id,
+      status: result.status === "processing" ? "indexing" : result.status === "created" ? "queued" : result.status,
+      job_id: result.job_id ?? null,
+      index_started: result.index_started,
       warnings: []
     };
   }
   async ingest(projectId, documents) {
-    return this.withProjectPathFallback(
-      this.getRequiredProject(projectId),
-      (projectPathRef) => this.request(`/v1/projects/${encodeURIComponent(projectPathRef)}/ingest`, {
-        method: "POST",
-        body: JSON.stringify({ documents })
-      })
+    await Promise.all(
+      documents.map(
+        (doc) => this.learn({
+          mode: "text",
+          project: projectId,
+          title: doc.title,
+          content: doc.content,
+          metadata: {
+            ...doc.metadata || {},
+            ...doc.file_path ? { file_path: doc.file_path } : {}
+          },
+          options: {
+            async: true,
+            ingestion_profile: doc.ingestion_profile,
+            strategy_override: doc.strategy_override,
+            profile_config: doc.profile_config
+          }
+        })
+      )
     );
+    return { ingested: documents.length };
   }
   async addContext(params) {
-    const projectId = (await this.resolveProject(this.getRequiredProject(params.project))).id;
-    return this.ingest(projectId, [
-      {
-        title: params.title || "Context",
-        content: params.content,
-        metadata: params.metadata || { source: "addContext" }
+    await this.learn({
+      mode: "text",
+      project: this.getRequiredProject(params.project),
+      title: params.title || "Context",
+      content: params.content,
+      metadata: params.metadata || { source: "addContext" },
+      options: {
+        async: true
       }
-    ]);
+    });
+    return { ingested: 1 };
+  }
+  async learn(params) {
+    const projectRef = this.getRequiredProject(params.project);
+    return this.withProjectRefFallback(projectRef, (project) => this.request("/v1/learn", {
+      method: "POST",
+      body: JSON.stringify({
+        ...params,
+        project
+      })
+    }));
   }
   async listMemories(params) {
     const projectRef = this.getRequiredProject(params.project);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usewhisper/sdk",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "whisperContractVersion": "2026.03.10",
   "scripts": {
     "build": "tsup ../src/sdk/index.ts --format esm,cjs --dts --out-dir .",