@utaba/deep-memory 0.15.0 → 0.17.0

package/LICENSE

@@ -175,7 +175,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2024 Utaba AI Ltd
+   Copyright 2024 Tim Wheeler
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/dist/{StorageProvider-BGtKZZt4.d.cts → StorageProvider-DDTLUcuj.d.ts}

@@ -1,4 +1,4 @@
-import { S as StorageRepositoryConfig, c as StoredRepository, d as RepositoryFilter, e as PaginatedResult, f as StoredRepositorySummary, g as RepositoryUpdate, h as DeleteProgressCallback, i as RepositoryStats, M as MemoryVocabulary, j as PaginationOptions, V as VocabularyChangeRecord, k as StoredEntity, l as StoredEntityUpdate, m as StorageFindQuery, n as StoredRelationship, o as RelationshipQueryOptions, p as StorageExploreOptions, q as StorageNeighborhood, r as StoragePathOptions, s as StoragePathResult, t as StorageTimelineOptions, u as StorageTimelineResult, v as ExportChunk, I as ImportChunk, B as BulkImportOptions, w as BulkImportResult } from './portability-P1hL-bOa.cjs';
+import { au as StorageRepositoryConfig, aB as StoredRepository, ad as RepositoryFilter, T as PaginatedResult, aC as StoredRepositorySummary, ah as RepositoryUpdate, g as DeleteProgressCallback, af as RepositoryStats, O as MemoryVocabulary, U as PaginationOptions, aM as VocabularyChangeRecord, ay as StoredEntity, az as StoredEntityUpdate, an as StorageFindQuery, aA as StoredRelationship, a5 as RelationshipQueryOptions, am as StorageExploreOptions, ao as StorageNeighborhood, as as StoragePathOptions, at as StoragePathResult, aw as StorageTimelineOptions, ax as StorageTimelineResult, s as ExportChunk, J as ImportChunk, B as BulkImportOptions, d as BulkImportResult } from './portability-Dbm6vCdD.js';
 
 /** Result returned by ensureSchema describing what actions were taken. */
 interface EnsureSchemaResult {
@@ -11,6 +11,22 @@ interface EnsureSchemaResult {
     /** Schema version after the operation */
     schemaVersion: number;
 }
+/**
+ * Internal entity-read options shared by `getEntity`, `getEntityBySlug`,
+ * `getEntities`, and `findEntities`.
+ *
+ * `loadEmbeddings` defaults to `false`. When `false`, providers must not ship
+ * the stored embedding over the wire — this is the AI-agent hot-path
+ * contract. When `true`, providers populate `StoredEntity.embedding` from the
+ * underlying store. The only legitimate caller is the vector-search path in
+ * `SearchOrchestrator.searchByConcept`.
+ *
+ * Providers that do not separate light/full reads (e.g. the in-memory
+ * provider, which always carries the full entity) may ignore this option.
+ */
+interface EntityReadOptions {
+    loadEmbeddings?: boolean;
+}
 /**
  * StorageProvider — the primary persistence interface.
  *
@@ -43,9 +59,9 @@ interface StorageProvider {
     saveVocabulary(repositoryId: string, vocabulary: MemoryVocabulary): Promise<void>;
     getVocabularyChangeLog(repositoryId: string, options?: PaginationOptions): Promise<PaginatedResult<VocabularyChangeRecord>>;
     createEntity(repositoryId: string, entity: StoredEntity): Promise<StoredEntity>;
-    getEntity(repositoryId: string, entityId: string): Promise<StoredEntity | null>;
-    getEntityBySlug(repositoryId: string, slug: string): Promise<StoredEntity | null>;
-    getEntities(repositoryId: string, entityIds: string[]): Promise<Map<string, StoredEntity>>;
+    getEntity(repositoryId: string, entityId: string, options?: EntityReadOptions): Promise<StoredEntity | null>;
+    getEntityBySlug(repositoryId: string, slug: string, options?: EntityReadOptions): Promise<StoredEntity | null>;
+    getEntities(repositoryId: string, entityIds: string[], options?: EntityReadOptions): Promise<Map<string, StoredEntity>>;
     updateEntity(repositoryId: string, entityId: string, updates: StoredEntityUpdate): Promise<StoredEntity>;
     deleteEntity(repositoryId: string, entityId: string): Promise<void>;
     /** Delete multiple entities and their associated relationships in a single batch operation */
@@ -53,12 +69,20 @@ interface StorageProvider {
         deleted: string[];
         notFound: string[];
     }>;
-    /** Delete all entities of a given type and their associated relationships */
+    /**
+     * Delete all entities of a given type and their associated relationships.
+     *
+     * `deletedRelationships` may be `undefined` when the provider does not count
+     * cascaded edges. The CosmosDB provider skips the edge-count fan-out
+     * (a `bothE()` walk across every partition the type touches) because the
+     * count itself is rarely consumed — vocabulary cascade-delete discards it.
+     * SQL Server and in-memory providers continue to return the exact number.
+     */
     deleteEntitiesByType(repositoryId: string, entityType: string): Promise<{
         deletedEntities: number;
-        deletedRelationships: number;
+        deletedRelationships: number | undefined;
     }>;
-    findEntities(repositoryId: string, query: StorageFindQuery): Promise<PaginatedResult<StoredEntity>>;
+    findEntities(repositoryId: string, query: StorageFindQuery, options?: EntityReadOptions): Promise<PaginatedResult<StoredEntity>>;
     createRelationship(repositoryId: string, relationship: StoredRelationship): Promise<StoredRelationship>;
     getRelationship(repositoryId: string, relationshipId: string): Promise<StoredRelationship | null>;
     getEntityRelationships(repositoryId: string, entityId: string, options?: RelationshipQueryOptions): Promise<PaginatedResult<StoredRelationship>>;
@@ -79,4 +103,4 @@ interface StorageProvider {
     importBulk(repositoryId: string, data: ImportChunk[], options?: BulkImportOptions): Promise<BulkImportResult>;
 }
 
-export type { EnsureSchemaResult as E, StorageProvider as S };
+export type { EnsureSchemaResult as E, StorageProvider as S, EntityReadOptions as a };

package/dist/{StorageProvider-D_o2Hksf.d.ts → StorageProvider-DGH7bVuK.d.cts}

@@ -1,4 +1,4 @@
-import { S as StorageRepositoryConfig, c as StoredRepository, d as RepositoryFilter, e as PaginatedResult, f as StoredRepositorySummary, g as RepositoryUpdate, h as DeleteProgressCallback, i as RepositoryStats, M as MemoryVocabulary, j as PaginationOptions, V as VocabularyChangeRecord, k as StoredEntity, l as StoredEntityUpdate, m as StorageFindQuery, n as StoredRelationship, o as RelationshipQueryOptions, p as StorageExploreOptions, q as StorageNeighborhood, r as StoragePathOptions, s as StoragePathResult, t as StorageTimelineOptions, u as StorageTimelineResult, v as ExportChunk, I as ImportChunk, B as BulkImportOptions, w as BulkImportResult } from './portability-P1hL-bOa.js';
+import { au as StorageRepositoryConfig, aB as StoredRepository, ad as RepositoryFilter, T as PaginatedResult, aC as StoredRepositorySummary, ah as RepositoryUpdate, g as DeleteProgressCallback, af as RepositoryStats, O as MemoryVocabulary, U as PaginationOptions, aM as VocabularyChangeRecord, ay as StoredEntity, az as StoredEntityUpdate, an as StorageFindQuery, aA as StoredRelationship, a5 as RelationshipQueryOptions, am as StorageExploreOptions, ao as StorageNeighborhood, as as StoragePathOptions, at as StoragePathResult, aw as StorageTimelineOptions, ax as StorageTimelineResult, s as ExportChunk, J as ImportChunk, B as BulkImportOptions, d as BulkImportResult } from './portability-Dbm6vCdD.cjs';
 
 /** Result returned by ensureSchema describing what actions were taken. */
 interface EnsureSchemaResult {
@@ -11,6 +11,22 @@ interface EnsureSchemaResult {
     /** Schema version after the operation */
     schemaVersion: number;
 }
+/**
+ * Internal entity-read options shared by `getEntity`, `getEntityBySlug`,
+ * `getEntities`, and `findEntities`.
+ *
+ * `loadEmbeddings` defaults to `false`. When `false`, providers must not ship
+ * the stored embedding over the wire — this is the AI-agent hot-path
+ * contract. When `true`, providers populate `StoredEntity.embedding` from the
+ * underlying store. The only legitimate caller is the vector-search path in
+ * `SearchOrchestrator.searchByConcept`.
+ *
+ * Providers that do not separate light/full reads (e.g. the in-memory
+ * provider, which always carries the full entity) may ignore this option.
+ */
+interface EntityReadOptions {
+    loadEmbeddings?: boolean;
+}
 /**
  * StorageProvider — the primary persistence interface.
  *
@@ -43,9 +59,9 @@ interface StorageProvider {
     saveVocabulary(repositoryId: string, vocabulary: MemoryVocabulary): Promise<void>;
     getVocabularyChangeLog(repositoryId: string, options?: PaginationOptions): Promise<PaginatedResult<VocabularyChangeRecord>>;
     createEntity(repositoryId: string, entity: StoredEntity): Promise<StoredEntity>;
-    getEntity(repositoryId: string, entityId: string): Promise<StoredEntity | null>;
-    getEntityBySlug(repositoryId: string, slug: string): Promise<StoredEntity | null>;
-    getEntities(repositoryId: string, entityIds: string[]): Promise<Map<string, StoredEntity>>;
+    getEntity(repositoryId: string, entityId: string, options?: EntityReadOptions): Promise<StoredEntity | null>;
+    getEntityBySlug(repositoryId: string, slug: string, options?: EntityReadOptions): Promise<StoredEntity | null>;
+    getEntities(repositoryId: string, entityIds: string[], options?: EntityReadOptions): Promise<Map<string, StoredEntity>>;
     updateEntity(repositoryId: string, entityId: string, updates: StoredEntityUpdate): Promise<StoredEntity>;
     deleteEntity(repositoryId: string, entityId: string): Promise<void>;
     /** Delete multiple entities and their associated relationships in a single batch operation */
@@ -53,12 +69,20 @@ interface StorageProvider {
         deleted: string[];
         notFound: string[];
     }>;
-    /** Delete all entities of a given type and their associated relationships */
+    /**
+     * Delete all entities of a given type and their associated relationships.
+     *
+     * `deletedRelationships` may be `undefined` when the provider does not count
+     * cascaded edges. The CosmosDB provider skips the edge-count fan-out
+     * (a `bothE()` walk across every partition the type touches) because the
+     * count itself is rarely consumed — vocabulary cascade-delete discards it.
+     * SQL Server and in-memory providers continue to return the exact number.
+     */
     deleteEntitiesByType(repositoryId: string, entityType: string): Promise<{
         deletedEntities: number;
-        deletedRelationships: number;
+        deletedRelationships: number | undefined;
     }>;
-    findEntities(repositoryId: string, query: StorageFindQuery): Promise<PaginatedResult<StoredEntity>>;
+    findEntities(repositoryId: string, query: StorageFindQuery, options?: EntityReadOptions): Promise<PaginatedResult<StoredEntity>>;
     createRelationship(repositoryId: string, relationship: StoredRelationship): Promise<StoredRelationship>;
     getRelationship(repositoryId: string, relationshipId: string): Promise<StoredRelationship | null>;
     getEntityRelationships(repositoryId: string, entityId: string, options?: RelationshipQueryOptions): Promise<PaginatedResult<StoredRelationship>>;
@@ -79,4 +103,4 @@ interface StorageProvider {
     importBulk(repositoryId: string, data: ImportChunk[], options?: BulkImportOptions): Promise<BulkImportResult>;
 }
 
-export type { EnsureSchemaResult as E, StorageProvider as S };
+export type { EnsureSchemaResult as E, StorageProvider as S, EntityReadOptions as a };