David Snelling
f8c45f2d8d
Open source vector database with HNSW indexing, graph relationships, and metadata facets. Features CLI with professional augmentation registry integration for discovering extensions and capabilities.
267 lines
9.4 KiB
TypeScript
267 lines
9.4 KiB
TypeScript
/**
|
|
* Base Storage Adapter
|
|
* Provides common functionality for all storage adapters
|
|
*/
|
|
import { GraphVerb, HNSWNoun, HNSWVerb, StatisticsData } from '../coreTypes.js';
|
|
import { BaseStorageAdapter } from './adapters/baseStorageAdapter.js';
|
|
export declare const ENTITIES_DIR = "entities";
|
|
export declare const NOUNS_VECTOR_DIR = "entities/nouns/vectors";
|
|
export declare const NOUNS_METADATA_DIR = "entities/nouns/metadata";
|
|
export declare const VERBS_VECTOR_DIR = "entities/verbs/vectors";
|
|
export declare const VERBS_METADATA_DIR = "entities/verbs/metadata";
|
|
export declare const INDEXES_DIR = "indexes";
|
|
export declare const METADATA_INDEX_DIR = "indexes/metadata";
|
|
export declare const NOUNS_DIR = "nouns";
|
|
export declare const VERBS_DIR = "verbs";
|
|
export declare const METADATA_DIR = "metadata";
|
|
export declare const NOUN_METADATA_DIR = "noun-metadata";
|
|
export declare const VERB_METADATA_DIR = "verb-metadata";
|
|
export declare const INDEX_DIR = "index";
|
|
export declare const SYSTEM_DIR = "_system";
|
|
export declare const STATISTICS_KEY = "statistics";
|
|
export declare const STORAGE_SCHEMA_VERSION = 3;
|
|
export declare const USE_ENTITY_BASED_STRUCTURE = true;
|
|
/**
|
|
* Get the appropriate directory path based on configuration
|
|
*/
|
|
export declare function getDirectoryPath(entityType: 'noun' | 'verb', dataType: 'vector' | 'metadata'): string;
|
|
/**
|
|
* Base storage adapter that implements common functionality
|
|
* This is an abstract class that should be extended by specific storage adapters
|
|
*/
|
|
export declare abstract class BaseStorage extends BaseStorageAdapter {
|
|
protected isInitialized: boolean;
|
|
protected readOnly: boolean;
|
|
/**
|
|
* Initialize the storage adapter
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
abstract init(): Promise<void>;
|
|
/**
|
|
* Ensure the storage adapter is initialized
|
|
*/
|
|
protected ensureInitialized(): Promise<void>;
|
|
/**
|
|
* Save a noun to storage
|
|
*/
|
|
saveNoun(noun: HNSWNoun): Promise<void>;
|
|
/**
|
|
* Get a noun from storage
|
|
*/
|
|
getNoun(id: string): Promise<HNSWNoun | null>;
|
|
/**
|
|
* Get nouns by noun type
|
|
* @param nounType The noun type to filter by
|
|
* @returns Promise that resolves to an array of nouns of the specified noun type
|
|
*/
|
|
getNounsByNounType(nounType: string): Promise<HNSWNoun[]>;
|
|
/**
|
|
* Delete a noun from storage
|
|
*/
|
|
deleteNoun(id: string): Promise<void>;
|
|
/**
|
|
* Save a verb to storage
|
|
*/
|
|
saveVerb(verb: GraphVerb): Promise<void>;
|
|
/**
|
|
* Get a verb from storage
|
|
*/
|
|
getVerb(id: string): Promise<GraphVerb | null>;
|
|
/**
|
|
* Convert HNSWVerb to GraphVerb by combining with metadata
|
|
*/
|
|
protected convertHNSWVerbToGraphVerb(hnswVerb: HNSWVerb): Promise<GraphVerb | null>;
|
|
/**
|
|
* Internal method for loading all verbs - used by performance optimizations
|
|
* @internal - Do not use directly, use getVerbs() with pagination instead
|
|
*/
|
|
protected _loadAllVerbsForOptimization(): Promise<HNSWVerb[]>;
|
|
/**
|
|
* Get verbs by source
|
|
*/
|
|
getVerbsBySource(sourceId: string): Promise<GraphVerb[]>;
|
|
/**
|
|
* Get verbs by target
|
|
*/
|
|
getVerbsByTarget(targetId: string): Promise<GraphVerb[]>;
|
|
/**
|
|
* Get verbs by type
|
|
*/
|
|
getVerbsByType(type: string): Promise<GraphVerb[]>;
|
|
/**
|
|
* Internal method for loading all nouns - used by performance optimizations
|
|
* @internal - Do not use directly, use getNouns() with pagination instead
|
|
*/
|
|
protected _loadAllNounsForOptimization(): Promise<HNSWNoun[]>;
|
|
/**
|
|
* Get nouns with pagination and filtering
|
|
* @param options Pagination and filtering options
|
|
* @returns Promise that resolves to a paginated result of nouns
|
|
*/
|
|
getNouns(options?: {
|
|
pagination?: {
|
|
offset?: number;
|
|
limit?: number;
|
|
cursor?: string;
|
|
};
|
|
filter?: {
|
|
nounType?: string | string[];
|
|
service?: string | string[];
|
|
metadata?: Record<string, any>;
|
|
};
|
|
}): Promise<{
|
|
items: HNSWNoun[];
|
|
totalCount?: number;
|
|
hasMore: boolean;
|
|
nextCursor?: string;
|
|
}>;
|
|
/**
|
|
* Get verbs with pagination and filtering
|
|
* @param options Pagination and filtering options
|
|
* @returns Promise that resolves to a paginated result of verbs
|
|
*/
|
|
getVerbs(options?: {
|
|
pagination?: {
|
|
offset?: number;
|
|
limit?: number;
|
|
cursor?: string;
|
|
};
|
|
filter?: {
|
|
verbType?: string | string[];
|
|
sourceId?: string | string[];
|
|
targetId?: string | string[];
|
|
service?: string | string[];
|
|
metadata?: Record<string, any>;
|
|
};
|
|
}): Promise<{
|
|
items: GraphVerb[];
|
|
totalCount?: number;
|
|
hasMore: boolean;
|
|
nextCursor?: string;
|
|
}>;
|
|
/**
|
|
* Delete a verb from storage
|
|
*/
|
|
deleteVerb(id: string): Promise<void>;
|
|
/**
|
|
* Clear all data from storage
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
abstract clear(): Promise<void>;
|
|
/**
|
|
* Get information about storage usage and capacity
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
abstract getStorageStatus(): Promise<{
|
|
type: string;
|
|
used: number;
|
|
quota: number | null;
|
|
details?: Record<string, any>;
|
|
}>;
|
|
/**
|
|
* Save metadata to storage
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
abstract saveMetadata(id: string, metadata: any): Promise<void>;
|
|
/**
|
|
* Get metadata from storage
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
abstract getMetadata(id: string): Promise<any | null>;
|
|
/**
|
|
* Save noun metadata to storage
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
abstract saveNounMetadata(id: string, metadata: any): Promise<void>;
|
|
/**
|
|
* Get noun metadata from storage
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
abstract getNounMetadata(id: string): Promise<any | null>;
|
|
/**
|
|
* Save verb metadata to storage
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
abstract saveVerbMetadata(id: string, metadata: any): Promise<void>;
|
|
/**
|
|
* Get verb metadata from storage
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
abstract getVerbMetadata(id: string): Promise<any | null>;
|
|
/**
|
|
* Save a noun to storage
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
protected abstract saveNoun_internal(noun: HNSWNoun): Promise<void>;
|
|
/**
|
|
* Get a noun from storage
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
protected abstract getNoun_internal(id: string): Promise<HNSWNoun | null>;
|
|
/**
|
|
* Get nouns by noun type
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
protected abstract getNounsByNounType_internal(nounType: string): Promise<HNSWNoun[]>;
|
|
/**
|
|
* Delete a noun from storage
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
protected abstract deleteNoun_internal(id: string): Promise<void>;
|
|
/**
|
|
* Save a verb to storage
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
protected abstract saveVerb_internal(verb: HNSWVerb): Promise<void>;
|
|
/**
|
|
* Get a verb from storage
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
protected abstract getVerb_internal(id: string): Promise<HNSWVerb | null>;
|
|
/**
|
|
* Get verbs by source
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
protected abstract getVerbsBySource_internal(sourceId: string): Promise<GraphVerb[]>;
|
|
/**
|
|
* Get verbs by target
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
protected abstract getVerbsByTarget_internal(targetId: string): Promise<GraphVerb[]>;
|
|
/**
|
|
* Get verbs by type
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
protected abstract getVerbsByType_internal(type: string): Promise<GraphVerb[]>;
|
|
/**
|
|
* Delete a verb from storage
|
|
* This method should be implemented by each specific adapter
|
|
*/
|
|
protected abstract deleteVerb_internal(id: string): Promise<void>;
|
|
/**
|
|
* Helper method to convert a Map to a plain object for serialization
|
|
*/
|
|
protected mapToObject<K extends string | number, V>(map: Map<K, V>, valueTransformer?: (value: V) => any): Record<string, any>;
|
|
/**
|
|
* Save statistics data to storage (public interface)
|
|
* @param statistics The statistics data to save
|
|
*/
|
|
saveStatistics(statistics: StatisticsData): Promise<void>;
|
|
/**
|
|
* Get statistics data from storage (public interface)
|
|
* @returns Promise that resolves to the statistics data or null if not found
|
|
*/
|
|
getStatistics(): Promise<StatisticsData | null>;
|
|
/**
|
|
* Save statistics data to storage
|
|
* This method should be implemented by each specific adapter
|
|
* @param statistics The statistics data to save
|
|
*/
|
|
protected abstract saveStatisticsData(statistics: StatisticsData): Promise<void>;
|
|
/**
|
|
* Get statistics data from storage
|
|
* This method should be implemented by each specific adapter
|
|
* @returns Promise that resolves to the statistics data or null if not found
|
|
*/
|
|
protected abstract getStatisticsData(): Promise<StatisticsData | null>;
|
|
}
|