@usewhisper/sdk 2.1.0 → 2.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/index.d.mts +124 -7
  2. package/index.d.ts +124 -7
  3. package/index.js +287 -42
  4. package/index.mjs +285 -41
  5. package/package.json +1 -1
package/index.d.mts CHANGED
@@ -179,6 +179,7 @@ declare class Whisper {
179
179
  */
180
180
  raw(): WhisperContext;
181
181
  private extractMemoryIdsFromBulkResponse;
182
+ private fallbackCaptureViaAddMemory;
182
183
  }
183
184
 
184
185
  interface AgentMiddlewareConfig extends WhisperOptions {
@@ -239,6 +240,26 @@ declare class WhisperAgentMiddleware {
239
240
  }
240
241
  declare function createAgentMiddleware(config: AgentMiddlewareConfig): WhisperAgentMiddleware;
241
242
 
243
+ interface MemoryGraphNode {
244
+ id: string;
245
+ label?: string;
246
+ memory_type?: string;
247
+ }
248
+ interface MemoryGraphEdge {
249
+ source: string;
250
+ target: string;
251
+ type?: string;
252
+ }
253
+ interface MemoryGraphPayload {
254
+ nodes: MemoryGraphNode[];
255
+ edges: MemoryGraphEdge[];
256
+ }
257
+ /**
258
+ * Convert memory graph payload to Mermaid flowchart syntax.
259
+ * Useful for quick visualization in docs/dashboards.
260
+ */
261
+ declare function memoryGraphToMermaid(graph: MemoryGraphPayload): string;
262
+
242
263
  /**
243
264
  * Whisper Context SDK
244
265
  * TypeScript SDK for the Whisper Context API
@@ -295,7 +316,20 @@ interface QueryResult {
295
316
  cache_hit: boolean;
296
317
  tokens_used: number;
297
318
  context_hash: string;
319
+ profile?: string;
298
320
  compression?: any;
321
+ timing?: {
322
+ cache_check_ms?: number;
323
+ embed_ms?: number;
324
+ vector_ms?: number;
325
+ fts_ms?: number;
326
+ rerank_ms?: number;
327
+ enrich_ms?: number;
328
+ pack_ms?: number;
329
+ cache_set_ms?: number;
330
+ total_ms?: number;
331
+ [key: string]: number | undefined;
332
+ };
299
333
  };
300
334
  }
301
335
  interface Project {
@@ -352,6 +386,61 @@ interface MemoryExtractionResult {
352
386
  extractionMethod: "pattern" | "inference" | "hybrid" | "skipped";
353
387
  latencyMs: number;
354
388
  }
389
+ interface MemoryLatencyBreakdown {
390
+ cache_ms: number;
391
+ embed_ms: number;
392
+ vector_ms: number;
393
+ lexical_ms: number;
394
+ merge_ms: number;
395
+ total_ms: number;
396
+ }
397
+ interface MemorySearchResponse {
398
+ results: Array<{
399
+ memory: {
400
+ id: string;
401
+ content: string;
402
+ type: string;
403
+ entities?: string[];
404
+ confidence?: number;
405
+ version?: number;
406
+ temporal?: {
407
+ document_date?: string | null;
408
+ event_date?: string | null;
409
+ valid_from?: string | null;
410
+ valid_until?: string | null;
411
+ };
412
+ };
413
+ chunk?: {
414
+ id: string;
415
+ content: string;
416
+ metadata?: Record<string, any>;
417
+ };
418
+ similarity: number;
419
+ relations?: any[];
420
+ }>;
421
+ count: number;
422
+ query: string;
423
+ trace_id?: string;
424
+ question_date?: string;
425
+ latency_ms?: number;
426
+ latency_breakdown?: MemoryLatencyBreakdown;
427
+ fallback?: "vector" | "lexical";
428
+ mode?: "fast" | "balanced" | "quality";
429
+ profile?: "fast" | "balanced" | "quality";
430
+ include_pending?: boolean;
431
+ pending_overlay_count?: number;
432
+ }
433
+ interface MemoryWriteAck {
434
+ success: boolean;
435
+ mode?: "async" | "sync";
436
+ trace_id?: string;
437
+ job_id?: string;
438
+ status_url?: string;
439
+ accepted_at?: string;
440
+ visibility_sla_ms?: number;
441
+ pending_visibility?: boolean;
442
+ [key: string]: any;
443
+ }
355
444
  type WhisperErrorCode = "INVALID_API_KEY" | "PROJECT_NOT_FOUND" | "PROJECT_AMBIGUOUS" | "RATE_LIMITED" | "TEMPORARY_UNAVAILABLE" | "NETWORK_ERROR" | "TIMEOUT" | "REQUEST_FAILED" | "MISSING_PROJECT";
356
445
  declare class WhisperError extends Error {
357
446
  code: WhisperErrorCode;
@@ -383,6 +472,7 @@ declare class WhisperContext {
383
472
  private getProjectRefCandidates;
384
473
  private withProjectRefFallback;
385
474
  private classifyError;
475
+ private isEndpointNotFoundError;
386
476
  private request;
387
477
  query(params: QueryParams): Promise<QueryResult>;
388
478
  createProject(params: {
@@ -433,6 +523,8 @@ declare class WhisperContext {
433
523
  importance?: number;
434
524
  metadata?: Record<string, any>;
435
525
  expires_in_seconds?: number;
526
+ async?: boolean;
527
+ write_mode?: "async" | "sync";
436
528
  allow_legacy_fallback?: boolean;
437
529
  }): Promise<{
438
530
  id: string;
@@ -458,6 +550,7 @@ declare class WhisperContext {
458
550
  namespace?: string;
459
551
  tags?: string[];
460
552
  async?: boolean;
553
+ write_mode?: "async" | "sync";
461
554
  webhook_url?: string;
462
555
  }): Promise<any>;
463
556
  extractMemories(params: {
@@ -493,7 +586,9 @@ declare class WhisperContext {
493
586
  agent_id?: string;
494
587
  memory_type?: "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
495
588
  top_k?: number;
496
- }): Promise<any>;
589
+ profile?: "fast" | "balanced" | "quality";
590
+ include_pending?: boolean;
591
+ }): Promise<MemorySearchResponse>;
497
592
  createApiKey(params: {
498
593
  name: string;
499
594
  scopes?: string[];
@@ -519,7 +614,10 @@ declare class WhisperContext {
519
614
  include_inactive?: boolean;
520
615
  include_chunks?: boolean;
521
616
  include_relations?: boolean;
522
- }): Promise<any>;
617
+ fast_mode?: boolean;
618
+ profile?: "fast" | "balanced" | "quality";
619
+ include_pending?: boolean;
620
+ }): Promise<MemorySearchResponse>;
523
621
  ingestSession(params: {
524
622
  project?: string;
525
623
  session_id: string;
@@ -529,18 +627,21 @@ declare class WhisperContext {
529
627
  content: string;
530
628
  timestamp: string;
531
629
  }>;
630
+ async?: boolean;
631
+ write_mode?: "async" | "sync";
532
632
  }): Promise<{
533
633
  success: boolean;
534
634
  memories_created: number;
535
635
  relations_created: number;
536
636
  memories_invalidated: number;
537
637
  errors?: string[];
538
- }>;
638
+ } & MemoryWriteAck>;
539
639
  getSessionMemories(params: {
540
640
  session_id: string;
541
641
  project?: string;
542
642
  limit?: number;
543
643
  since_date?: string;
644
+ include_pending?: boolean;
544
645
  }): Promise<{
545
646
  memories: any[];
546
647
  count: number;
@@ -549,6 +650,7 @@ declare class WhisperContext {
549
650
  user_id: string;
550
651
  project?: string;
551
652
  memory_types?: string;
653
+ include_pending?: boolean;
552
654
  }): Promise<{
553
655
  user_id: string;
554
656
  memories: any[];
@@ -576,6 +678,19 @@ declare class WhisperContext {
576
678
  relations: any[];
577
679
  count: number;
578
680
  }>;
681
+ getMemoryGraph(params: {
682
+ project?: string;
683
+ user_id?: string;
684
+ session_id?: string;
685
+ include_inactive?: boolean;
686
+ limit?: number;
687
+ }): Promise<any>;
688
+ getConversationGraph(params: {
689
+ project?: string;
690
+ session_id: string;
691
+ include_inactive?: boolean;
692
+ limit?: number;
693
+ }): Promise<any>;
579
694
  oracleSearch(params: {
580
695
  query: string;
581
696
  project?: string;
@@ -798,15 +913,15 @@ declare class WhisperContext {
798
913
  count: number;
799
914
  latencyMs: number;
800
915
  }>;
801
- search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<any>;
802
- searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<any>;
916
+ search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<MemorySearchResponse>;
917
+ searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<MemorySearchResponse>;
803
918
  ingestSession: (params: Parameters<WhisperContext["ingestSession"]>[0]) => Promise<{
804
919
  success: boolean;
805
920
  memories_created: number;
806
921
  relations_created: number;
807
922
  memories_invalidated: number;
808
923
  errors?: string[];
809
- }>;
924
+ } & MemoryWriteAck>;
810
925
  getSessionMemories: (params: Parameters<WhisperContext["getSessionMemories"]>[0]) => Promise<{
811
926
  memories: any[];
812
927
  count: number;
@@ -835,6 +950,8 @@ declare class WhisperContext {
835
950
  relations: any[];
836
951
  count: number;
837
952
  }>;
953
+ getGraph: (params: Parameters<WhisperContext["getMemoryGraph"]>[0]) => Promise<any>;
954
+ getConversationGraph: (params: Parameters<WhisperContext["getConversationGraph"]>[0]) => Promise<any>;
838
955
  consolidate: (params: Parameters<WhisperContext["consolidateMemories"]>[0]) => Promise<any>;
839
956
  updateDecay: (params: Parameters<WhisperContext["updateImportanceDecay"]>[0]) => Promise<{
840
957
  success: boolean;
@@ -919,4 +1036,4 @@ declare class WhisperContext {
919
1036
  };
920
1037
  }
921
1038
 
922
- 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 };
1039
+ export { type ExtractedMemory, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type Project, type QueryParams, type QueryResult, type Source, Whisper, WhisperAgentMiddleware, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, createAgentMiddleware, WhisperContext as default, memoryGraphToMermaid };
package/index.d.ts CHANGED
@@ -179,6 +179,7 @@ declare class Whisper {
179
179
  */
180
180
  raw(): WhisperContext;
181
181
  private extractMemoryIdsFromBulkResponse;
182
+ private fallbackCaptureViaAddMemory;
182
183
  }
183
184
 
184
185
  interface AgentMiddlewareConfig extends WhisperOptions {
@@ -239,6 +240,26 @@ declare class WhisperAgentMiddleware {
239
240
  }
240
241
  declare function createAgentMiddleware(config: AgentMiddlewareConfig): WhisperAgentMiddleware;
241
242
 
243
+ interface MemoryGraphNode {
244
+ id: string;
245
+ label?: string;
246
+ memory_type?: string;
247
+ }
248
+ interface MemoryGraphEdge {
249
+ source: string;
250
+ target: string;
251
+ type?: string;
252
+ }
253
+ interface MemoryGraphPayload {
254
+ nodes: MemoryGraphNode[];
255
+ edges: MemoryGraphEdge[];
256
+ }
257
+ /**
258
+ * Convert memory graph payload to Mermaid flowchart syntax.
259
+ * Useful for quick visualization in docs/dashboards.
260
+ */
261
+ declare function memoryGraphToMermaid(graph: MemoryGraphPayload): string;
262
+
242
263
  /**
243
264
  * Whisper Context SDK
244
265
  * TypeScript SDK for the Whisper Context API
@@ -295,7 +316,20 @@ interface QueryResult {
295
316
  cache_hit: boolean;
296
317
  tokens_used: number;
297
318
  context_hash: string;
319
+ profile?: string;
298
320
  compression?: any;
321
+ timing?: {
322
+ cache_check_ms?: number;
323
+ embed_ms?: number;
324
+ vector_ms?: number;
325
+ fts_ms?: number;
326
+ rerank_ms?: number;
327
+ enrich_ms?: number;
328
+ pack_ms?: number;
329
+ cache_set_ms?: number;
330
+ total_ms?: number;
331
+ [key: string]: number | undefined;
332
+ };
299
333
  };
300
334
  }
301
335
  interface Project {
@@ -352,6 +386,61 @@ interface MemoryExtractionResult {
352
386
  extractionMethod: "pattern" | "inference" | "hybrid" | "skipped";
353
387
  latencyMs: number;
354
388
  }
389
+ interface MemoryLatencyBreakdown {
390
+ cache_ms: number;
391
+ embed_ms: number;
392
+ vector_ms: number;
393
+ lexical_ms: number;
394
+ merge_ms: number;
395
+ total_ms: number;
396
+ }
397
+ interface MemorySearchResponse {
398
+ results: Array<{
399
+ memory: {
400
+ id: string;
401
+ content: string;
402
+ type: string;
403
+ entities?: string[];
404
+ confidence?: number;
405
+ version?: number;
406
+ temporal?: {
407
+ document_date?: string | null;
408
+ event_date?: string | null;
409
+ valid_from?: string | null;
410
+ valid_until?: string | null;
411
+ };
412
+ };
413
+ chunk?: {
414
+ id: string;
415
+ content: string;
416
+ metadata?: Record<string, any>;
417
+ };
418
+ similarity: number;
419
+ relations?: any[];
420
+ }>;
421
+ count: number;
422
+ query: string;
423
+ trace_id?: string;
424
+ question_date?: string;
425
+ latency_ms?: number;
426
+ latency_breakdown?: MemoryLatencyBreakdown;
427
+ fallback?: "vector" | "lexical";
428
+ mode?: "fast" | "balanced" | "quality";
429
+ profile?: "fast" | "balanced" | "quality";
430
+ include_pending?: boolean;
431
+ pending_overlay_count?: number;
432
+ }
433
+ interface MemoryWriteAck {
434
+ success: boolean;
435
+ mode?: "async" | "sync";
436
+ trace_id?: string;
437
+ job_id?: string;
438
+ status_url?: string;
439
+ accepted_at?: string;
440
+ visibility_sla_ms?: number;
441
+ pending_visibility?: boolean;
442
+ [key: string]: any;
443
+ }
355
444
  type WhisperErrorCode = "INVALID_API_KEY" | "PROJECT_NOT_FOUND" | "PROJECT_AMBIGUOUS" | "RATE_LIMITED" | "TEMPORARY_UNAVAILABLE" | "NETWORK_ERROR" | "TIMEOUT" | "REQUEST_FAILED" | "MISSING_PROJECT";
356
445
  declare class WhisperError extends Error {
357
446
  code: WhisperErrorCode;
@@ -383,6 +472,7 @@ declare class WhisperContext {
383
472
  private getProjectRefCandidates;
384
473
  private withProjectRefFallback;
385
474
  private classifyError;
475
+ private isEndpointNotFoundError;
386
476
  private request;
387
477
  query(params: QueryParams): Promise<QueryResult>;
388
478
  createProject(params: {
@@ -433,6 +523,8 @@ declare class WhisperContext {
433
523
  importance?: number;
434
524
  metadata?: Record<string, any>;
435
525
  expires_in_seconds?: number;
526
+ async?: boolean;
527
+ write_mode?: "async" | "sync";
436
528
  allow_legacy_fallback?: boolean;
437
529
  }): Promise<{
438
530
  id: string;
@@ -458,6 +550,7 @@ declare class WhisperContext {
458
550
  namespace?: string;
459
551
  tags?: string[];
460
552
  async?: boolean;
553
+ write_mode?: "async" | "sync";
461
554
  webhook_url?: string;
462
555
  }): Promise<any>;
463
556
  extractMemories(params: {
@@ -493,7 +586,9 @@ declare class WhisperContext {
493
586
  agent_id?: string;
494
587
  memory_type?: "factual" | "preference" | "event" | "relationship" | "opinion" | "goal" | "instruction";
495
588
  top_k?: number;
496
- }): Promise<any>;
589
+ profile?: "fast" | "balanced" | "quality";
590
+ include_pending?: boolean;
591
+ }): Promise<MemorySearchResponse>;
497
592
  createApiKey(params: {
498
593
  name: string;
499
594
  scopes?: string[];
@@ -519,7 +614,10 @@ declare class WhisperContext {
519
614
  include_inactive?: boolean;
520
615
  include_chunks?: boolean;
521
616
  include_relations?: boolean;
522
- }): Promise<any>;
617
+ fast_mode?: boolean;
618
+ profile?: "fast" | "balanced" | "quality";
619
+ include_pending?: boolean;
620
+ }): Promise<MemorySearchResponse>;
523
621
  ingestSession(params: {
524
622
  project?: string;
525
623
  session_id: string;
@@ -529,18 +627,21 @@ declare class WhisperContext {
529
627
  content: string;
530
628
  timestamp: string;
531
629
  }>;
630
+ async?: boolean;
631
+ write_mode?: "async" | "sync";
532
632
  }): Promise<{
533
633
  success: boolean;
534
634
  memories_created: number;
535
635
  relations_created: number;
536
636
  memories_invalidated: number;
537
637
  errors?: string[];
538
- }>;
638
+ } & MemoryWriteAck>;
539
639
  getSessionMemories(params: {
540
640
  session_id: string;
541
641
  project?: string;
542
642
  limit?: number;
543
643
  since_date?: string;
644
+ include_pending?: boolean;
544
645
  }): Promise<{
545
646
  memories: any[];
546
647
  count: number;
@@ -549,6 +650,7 @@ declare class WhisperContext {
549
650
  user_id: string;
550
651
  project?: string;
551
652
  memory_types?: string;
653
+ include_pending?: boolean;
552
654
  }): Promise<{
553
655
  user_id: string;
554
656
  memories: any[];
@@ -576,6 +678,19 @@ declare class WhisperContext {
576
678
  relations: any[];
577
679
  count: number;
578
680
  }>;
681
+ getMemoryGraph(params: {
682
+ project?: string;
683
+ user_id?: string;
684
+ session_id?: string;
685
+ include_inactive?: boolean;
686
+ limit?: number;
687
+ }): Promise<any>;
688
+ getConversationGraph(params: {
689
+ project?: string;
690
+ session_id: string;
691
+ include_inactive?: boolean;
692
+ limit?: number;
693
+ }): Promise<any>;
579
694
  oracleSearch(params: {
580
695
  query: string;
581
696
  project?: string;
@@ -798,15 +913,15 @@ declare class WhisperContext {
798
913
  count: number;
799
914
  latencyMs: number;
800
915
  }>;
801
- search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<any>;
802
- searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<any>;
916
+ search: (params: Parameters<WhisperContext["searchMemories"]>[0]) => Promise<MemorySearchResponse>;
917
+ searchSOTA: (params: Parameters<WhisperContext["searchMemoriesSOTA"]>[0]) => Promise<MemorySearchResponse>;
803
918
  ingestSession: (params: Parameters<WhisperContext["ingestSession"]>[0]) => Promise<{
804
919
  success: boolean;
805
920
  memories_created: number;
806
921
  relations_created: number;
807
922
  memories_invalidated: number;
808
923
  errors?: string[];
809
- }>;
924
+ } & MemoryWriteAck>;
810
925
  getSessionMemories: (params: Parameters<WhisperContext["getSessionMemories"]>[0]) => Promise<{
811
926
  memories: any[];
812
927
  count: number;
@@ -835,6 +950,8 @@ declare class WhisperContext {
835
950
  relations: any[];
836
951
  count: number;
837
952
  }>;
953
+ getGraph: (params: Parameters<WhisperContext["getMemoryGraph"]>[0]) => Promise<any>;
954
+ getConversationGraph: (params: Parameters<WhisperContext["getConversationGraph"]>[0]) => Promise<any>;
838
955
  consolidate: (params: Parameters<WhisperContext["consolidateMemories"]>[0]) => Promise<any>;
839
956
  updateDecay: (params: Parameters<WhisperContext["updateImportanceDecay"]>[0]) => Promise<{
840
957
  success: boolean;
@@ -919,4 +1036,4 @@ declare class WhisperContext {
919
1036
  };
920
1037
  }
921
1038
 
922
- 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 };
1039
+ export { type ExtractedMemory, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type Project, type QueryParams, type QueryResult, type Source, Whisper, WhisperAgentMiddleware, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, createAgentMiddleware, WhisperContext as default, memoryGraphToMermaid };