@utaba/deep-memory 0.8.1 → 0.9.0

package/dist/types/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/index.ts"],"sourcesContent":["// Type re-exports — @utaba/deep-memory/types\n\nexport type {\n  ProvenanceContext,\n  Provenance,\n} from './provenance.js';\n\nexport type {\n  PropertyType,\n  PropertySchema,\n  EntityTypeDefinition,\n  RelationshipTypeDefinition,\n  MemoryVocabulary,\n  GovernanceMode,\n  GovernanceConfig,\n  VocabularyProposal,\n  VocabularyProposalResult,\n  VocabularyChangeRecord,\n  ResolvedVocabulary,\n  EntityTypeInput,\n  RelationshipTypeInput,\n  VocabularyInput,\n} from './vocabulary.js';\n\nexport type {\n  DetailLevel,\n  Entity,\n  EntitySummary,\n  EntityBrief,\n  CreateEntityInput,\n  UpdateEntityInput,\n  StoredEntity,\n  StoredEntityUpdate,\n  GetEntityOptions,\n  GetEntitiesOptions,\n  DeleteEntitiesResult,\n} from './entities.js';\n\nexport type {\n  RelationshipDirection,\n  Relationship,\n  EnrichedRelationship,\n  CreateRelationshipInput,\n  StoredRelationship,\n  RelationshipQueryOptions,\n  RelationshipSummary,\n  RemoveRelationshipsResult,\n} from './relationships.js';\n\nexport type {\n  RepositoryConfig,\n  RepositoryMetadata,\n  RepositoryUpdate,\n  RepositorySummary,\n  RepositoryStats,\n  StoredRepository,\n  StoredRepositorySummary,\n  RepositoryFilter,\n  StorageRepositoryConfig,\n} from './repositories.js';\n\nexport type {\n  PaginationOptions,\n  FindEntitiesQuery,\n  ExploreOptions,\n  PathOptions,\n  ConceptSearchOptions,\n  TimelineOptions,\n  StorageFindQuery,\n  StorageExploreOptions,\n  StoragePathOptions,\n  StorageTimelineOptions,\n  SearchOptions,\n  PropertyFilter,\n  ProvenanceFilter,\n} from './queries.js';\n\nexport type {\n  PaginatedResult,\n  NeighborhoodCenter,\n  NeighborhoodGroup,\n  NeighborhoodLayer,\n  Neighborhood,\n  Path,\n  PathResult,\n  ScoredEntity,\n  TimelineEntityRef,\n  TimelineRelationshipDetail,\n  TimelineEvent,\n  TimelineResult,\n  GraphResult,\n  EntityMap,\n  StorageNeighborhoodGroup,\n  StorageNeighborhoodLayer,\n  StorageNeighborhood,\n  StoragePath,\n  StoragePathResult,\n  StorageTimelineEvent,\n  StorageTimelineResult,\n  SearchHit,\n  BulkImportResult,\n  ReembedResult,\n  EntityValidationIssue,\n  RelationshipValidationIssue,\n  EntityValidationPage,\n  RelationshipValidationPage,\n  ValidateEntitiesOptions,\n  ValidateRelationshipsOptions,\n} from './results.js';\n\nexport type {\n  DeepMemoryEventType,\n  EventPayload,\n  DeepMemoryEvent,\n  EventHandler,\n  Unsubscribe,\n  HookResult,\n} from './events.js';\n\nexport type {\n  TraversalSpec,\n  TraversalStart,\n  TraversalStep,\n  TraversalProjection,\n  TraversalReturnMode,\n  TraversalResult,\n  TraversalAggregation,\n  TraversalRelationship,\n  TraversalPath,\n  QueryMetadata,\n} from './traversal.js';\n\nexport type {\n  ExportManifest,\n  ExportLegalMetadata,\n  ExportPipelineMetadata,\n  ExportOptions,\n  ExportArchive,\n  ExportChunk,\n  ExportStreamItem,\n  ImportOptions,\n  ImportChunk,\n  BulkImportOptions,\n  DeleteProgressCallback,\n  ImportStreamHeader,\n  ImportWarning,\n  ImportResult,\n} from './portability.js';\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/types/index.ts"],"sourcesContent":["// Type re-exports — @utaba/deep-memory/types\n\nexport type {\n  ProvenanceContext,\n  Provenance,\n} from './provenance.js';\n\nexport type {\n  PropertyType,\n  PropertySchema,\n  EntityTypeDefinition,\n  RelationshipTypeDefinition,\n  MemoryVocabulary,\n  GovernanceMode,\n  GovernanceConfig,\n  VocabularyProposal,\n  VocabularyProposalResult,\n  VocabularyChangeRecord,\n  ResolvedVocabulary,\n  EntityTypeInput,\n  RelationshipTypeInput,\n  VocabularyInput,\n} from './vocabulary.js';\n\nexport type {\n  DetailLevel,\n  Entity,\n  EntitySummary,\n  EntityBrief,\n  CreateEntityInput,\n  UpdateEntityInput,\n  StoredEntity,\n  StoredEntityUpdate,\n  GetEntityOptions,\n  GetEntitiesOptions,\n  DeleteEntitiesResult,\n} from './entities.js';\n\nexport type {\n  RelationshipDirection,\n  Relationship,\n  EnrichedRelationship,\n  CreateRelationshipInput,\n  StoredRelationship,\n  RelationshipQueryOptions,\n  RelationshipSummary,\n  RemoveRelationshipsResult,\n} from './relationships.js';\n\nexport type {\n  RepositoryConfig,\n  RepositoryMetadata,\n  RepositoryUpdate,\n  RepositorySummary,\n  RepositoryStats,\n  StoredRepository,\n  StoredRepositorySummary,\n  RepositoryFilter,\n  StorageRepositoryConfig,\n} from './repositories.js';\n\nexport type {\n  PaginationOptions,\n  FindEntitiesQuery,\n  ExploreOptions,\n  PathOptions,\n  ConceptSearchOptions,\n  TimelineOptions,\n  StorageFindQuery,\n  StorageExploreOptions,\n  StoragePathOptions,\n  StorageTimelineOptions,\n  SearchOptions,\n  PropertyFilter,\n  ProvenanceFilter,\n} from './queries.js';\n\nexport type {\n  PaginatedResult,\n  NeighborhoodCenter,\n  NeighborhoodGroup,\n  NeighborhoodLayer,\n  Neighborhood,\n  Path,\n  PathResult,\n  ScoredEntity,\n  TimelineEntityRef,\n  TimelineRelationshipDetail,\n  TimelineEvent,\n  TimelineResult,\n  GraphResult,\n  EntityMap,\n  StorageNeighborhoodGroup,\n  StorageNeighborhoodLayer,\n  StorageNeighborhood,\n  StoragePath,\n  StoragePathResult,\n  StorageTimelineEvent,\n  StorageTimelineResult,\n  SearchHit,\n  BulkImportResult,\n  ReembedResult,\n  EntityValidationIssue,\n  RelationshipValidationIssue,\n  EntityValidationPage,\n  RelationshipValidationPage,\n  ValidateEntitiesOptions,\n  ValidateRelationshipsOptions,\n} from './results.js';\n\nexport type {\n  DeepMemoryEventType,\n  EventPayload,\n  DeepMemoryEvent,\n  EventHandler,\n  Unsubscribe,\n  HookResult,\n} from './events.js';\n\nexport type {\n  TraversalSpec,\n  TraversalStart,\n  TraversalStep,\n  TraversalProjection,\n  TraversalReturnMode,\n  TraversalResult,\n  TraversalAggregation,\n  TraversalRelationship,\n  TraversalPath,\n  QueryMetadata,\n} from './traversal.js';\n\nexport type {\n  OperationUsage,\n  UsageSink,\n} from './usage.js';\n\nexport type {\n  ExportManifest,\n  ExportLegalMetadata,\n  ExportPipelineMetadata,\n  ExportOptions,\n  ExportArchive,\n  ExportChunk,\n  ExportStreamItem,\n  ImportOptions,\n  ImportChunk,\n  BulkImportOptions,\n  DeleteProgressCallback,\n  ImportStreamHeader,\n  ImportWarning,\n  ImportResult,\n} from './portability.js';\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types/index.d.cts

@@ -143,4 +143,57 @@ interface HookResult {
     reason?: string;
 }
 
-export { CreateEntityInput, CreateRelationshipInput, type DeepMemoryEvent, type DeepMemoryEventType, Entity, type EventHandler, type EventPayload, type HookResult, ProvenanceContext, Relationship, type Unsubscribe, UpdateEntityInput, VocabularyChangeRecord };
+/**
+ * Cost/usage record for a single public provider operation.
+ *
+ * Emitted once per top-level call (e.g. `createEntity`, `findEntities`,
+ * `traverse`, `embedBatch`, `chatCompletion`). If the operation internally
+ * issues multiple database round-trips, the provider aggregates their costs
+ * into a single record.
+ */
+interface OperationUsage {
+    /**
+     * Provider identifier. Canonical values used by the built-in providers:
+     * `'cosmosdb'`, `'sqlserver'`, `'openai'`, `'anthropic'`.
+     * Custom providers should use their own stable identifier.
+     */
+    provider: string;
+    /**
+     * Name of the public provider method that produced this usage, e.g.
+     * `'createEntity'`, `'findEntities'`, `'traverse'`, `'embedBatch'`,
+     * `'chatCompletion'`.
+     */
+    operation: string;
+    /**
+     * Unit of the `value` field. Canonical values:
+     *   `'RU'`       — CosmosDB request units
+     *   `'ms'`       — wall-clock execution time (SQL Server, generic)
+     *   `'tokens'`   — total tokens (embeddings, LLM completions)
+     */
+    unit: string;
+    /** Magnitude of the cost in the stated unit. Always non-negative. */
+    value: number;
+    /**
+     * Repository the operation was scoped to, if applicable. Absent for
+     * cross-repository operations (e.g. `listRepositories`) and for providers
+     * that operate outside a repository context (e.g. the embeddings provider
+     * during indexer extraction, before the data is imported into a repo).
+     */
+    repositoryId?: string;
+    /** When the operation completed. */
+    timestamp: Date;
+    /**
+     * Optional provider-specific breakdown. Examples:
+     *   CosmosDB: `{ calls: 3, retries: 0 }`
+     *   LLM:      `{ inputTokens: 1200, outputTokens: 340, cacheReadTokens: 800 }`
+     */
+    details?: Record<string, number>;
+}
+/**
+ * Callback that receives usage records. Providers invoke this once per public
+ * operation when configured. The sink must not throw — providers wrap it
+ * defensively, but a well-behaved implementation swallows its own errors.
+ */
+type UsageSink = (usage: OperationUsage) => void;
+
+export { CreateEntityInput, CreateRelationshipInput, type DeepMemoryEvent, type DeepMemoryEventType, Entity, type EventHandler, type EventPayload, type HookResult, type OperationUsage, ProvenanceContext, Relationship, type Unsubscribe, UpdateEntityInput, type UsageSink, VocabularyChangeRecord };

package/dist/types/index.d.ts

@@ -143,4 +143,57 @@ interface HookResult {
     reason?: string;
 }
 
-export { CreateEntityInput, CreateRelationshipInput, type DeepMemoryEvent, type DeepMemoryEventType, Entity, type EventHandler, type EventPayload, type HookResult, ProvenanceContext, Relationship, type Unsubscribe, UpdateEntityInput, VocabularyChangeRecord };
+/**
+ * Cost/usage record for a single public provider operation.
+ *
+ * Emitted once per top-level call (e.g. `createEntity`, `findEntities`,
+ * `traverse`, `embedBatch`, `chatCompletion`). If the operation internally
+ * issues multiple database round-trips, the provider aggregates their costs
+ * into a single record.
+ */
+interface OperationUsage {
+    /**
+     * Provider identifier. Canonical values used by the built-in providers:
+     * `'cosmosdb'`, `'sqlserver'`, `'openai'`, `'anthropic'`.
+     * Custom providers should use their own stable identifier.
+     */
+    provider: string;
+    /**
+     * Name of the public provider method that produced this usage, e.g.
+     * `'createEntity'`, `'findEntities'`, `'traverse'`, `'embedBatch'`,
+     * `'chatCompletion'`.
+     */
+    operation: string;
+    /**
+     * Unit of the `value` field. Canonical values:
+     *   `'RU'`       — CosmosDB request units
+     *   `'ms'`       — wall-clock execution time (SQL Server, generic)
+     *   `'tokens'`   — total tokens (embeddings, LLM completions)
+     */
+    unit: string;
+    /** Magnitude of the cost in the stated unit. Always non-negative. */
+    value: number;
+    /**
+     * Repository the operation was scoped to, if applicable. Absent for
+     * cross-repository operations (e.g. `listRepositories`) and for providers
+     * that operate outside a repository context (e.g. the embeddings provider
+     * during indexer extraction, before the data is imported into a repo).
+     */
+    repositoryId?: string;
+    /** When the operation completed. */
+    timestamp: Date;
+    /**
+     * Optional provider-specific breakdown. Examples:
+     *   CosmosDB: `{ calls: 3, retries: 0 }`
+     *   LLM:      `{ inputTokens: 1200, outputTokens: 340, cacheReadTokens: 800 }`
+     */
+    details?: Record<string, number>;
+}
+/**
+ * Callback that receives usage records. Providers invoke this once per public
+ * operation when configured. The sink must not throw — providers wrap it
+ * defensively, but a well-behaved implementation swallows its own errors.
+ */
+type UsageSink = (usage: OperationUsage) => void;
+
+export { CreateEntityInput, CreateRelationshipInput, type DeepMemoryEvent, type DeepMemoryEventType, Entity, type EventHandler, type EventPayload, type HookResult, type OperationUsage, ProvenanceContext, Relationship, type Unsubscribe, UpdateEntityInput, type UsageSink, VocabularyChangeRecord };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utaba/deep-memory",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Vocabulary-driven graph memory for AI agents",
   "type": "module",
   "main": "./dist/index.cjs",