@framers/agentos 0.1.125 → 0.1.127

package/dist/core/utils/usage/UsageLedger.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Aggregates model usage (tokens, cost) across sessions, personas, and providers.
+ * Serves as a foundational accounting component for later billing, analytics, and dynamic routing decisions.
+ *
+ * Design Goals:
+ * 1. Low Overhead: Pure in-memory by default; pluggable persistence adapter for durability.
+ * 2. Incremental Updates: Accept partial usage metrics from streaming chunks; finalize on terminal chunk.
+ * 3. Query Flexibility: Summaries per session, persona, provider, model.
+ * 4. Cost Normalization: Uses `ModelUsage.costUSD` when present; can apply fallback pricing from a model catalog.
+ */
+import { ModelCompletionResponse, ModelUsage } from '../../llm/providers/IProvider';
+/** Canonical key dimensions tracked for each usage record. */
+export interface UsageDimensions {
+    sessionId: string;
+    personaId?: string;
+    providerId?: string;
+    modelId?: string;
+}
+/** Internal mutable aggregation bucket. */
+interface UsageBucket extends UsageDimensions {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    costUSD: number;
+    calls: number;
+}
+/** Result returned by summary queries. */
+export type UsageSummary = UsageBucket;
+/** Persistence adapter contract enabling storage engines. */
+export interface IUsageLedgerPersistence {
+    save(bucket: UsageBucket): Promise<void>;
+    loadAll(): Promise<UsageBucket[]>;
+}
+/** Options for UsageLedger behavior. */
+export interface UsageLedgerOptions {
+    /** When true, interim streaming usage (non-final chunks) will contribute estimated tokens. */
+    includeInterimStreamingUsage?: boolean;
+    /** Optional pricing fallback map: modelId -> { inputPer1M, outputPer1M }. */
+    pricingFallbacks?: Record<string, {
+        inputPer1M?: number;
+        outputPer1M?: number;
+        totalPer1M?: number;
+    }>;
+    /** Persistence adapter for durability (undefined => in-memory only). */
+    persistenceAdapter?: IUsageLedgerPersistence;
+}
+/**
+ * UsageLedger accumulates usage metrics from provider responses.
+ * Usage ingestion MUST be called for final streaming chunks or any non-streaming responses.
+ */
+export declare class UsageLedger {
+    private buckets;
+    private options;
+    constructor(options?: UsageLedgerOptions);
+    /** Compose a stable bucket key from dimensions. */
+    private bucketKey;
+    /** Ensure bucket exists. */
+    private getOrCreateBucket;
+    /**
+     * Ingest a completion response chunk (streaming final or single shot) updating usage aggregates.
+     * Non-final streaming chunks are ignored unless includeInterimStreamingUsage=true.
+     */
+    ingestCompletionChunk(dim: UsageDimensions, chunk: ModelCompletionResponse): void;
+    /** Manual ingestion for custom usage objects (e.g. embeddings). */
+    ingestUsage(dim: UsageDimensions, usage: ModelUsage & {
+        modelId?: string;
+        isFinal?: boolean;
+    }): void;
+    /** Return all summaries. */
+    listAllSummaries(): UsageSummary[];
+    /** Query by session id. */
+    getSummariesBySession(sessionId: string): UsageSummary[];
+    /** Aggregate totals across all buckets for a session. */
+    getSessionAggregate(sessionId: string): UsageSummary | undefined;
+    /** Persist current buckets if an adapter is configured. */
+    flush(): Promise<void>;
+    /** Load all buckets from persistence (merging into existing). */
+    bootstrapFromPersistence(): Promise<void>;
+}
+export default UsageLedger;
+//# sourceMappingURL=UsageLedger.d.ts.map

package/dist/core/utils/usage/UsageLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UsageLedger.d.ts","sourceRoot":"","sources":["../../../../src/core/utils/usage/UsageLedger.ts"],"names":[],"mappings":"AACA;;;;;;;;;GASG;AACH,OAAO,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAEpF,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,2CAA2C;AAC3C,UAAU,WAAY,SAAQ,eAAe;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,0CAA0C;AAC1C,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC;AAEvC,6DAA6D;AAC7D,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CACnC;AAED,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtG,wEAAwE;IACxE,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,OAAO,CAAqB;gBAExB,OAAO,GAAE,kBAAuB;IAI5C,mDAAmD;IACnD,OAAO,CAAC,SAAS;IAIjB,4BAA4B;IAC5B,OAAO,CAAC,iBAAiB;IAUzB;;;OAGG;IACH,qBAAqB,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,uBAAuB,GAAG,IAAI;IA+BjF,mEAAmE;IACnE,WAAW,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAsBpG,4BAA4B;IAC5B,gBAAgB,IAAI,YAAY,EAAE;IAIlC,2BAA2B;IAC3B,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE;IAIxD,yDAAyD;IACzD,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAgBhE,2DAA2D;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B,iEAAiE;IAC3D,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC;CAYhD;AAED,eAAe,WAAW,CAAC"}

package/dist/core/utils/usage/UsageLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UsageLedger.js","sourceRoot":"","sources":["../../../../src/core/utils/usage/UsageLedger.ts"],"names":[],"mappings":"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"}

package/dist/core/utils/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../../../src/core/utils/uuid.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,YAAY,IAAI,MAAM,CA6DrC;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,qBAAe,CAAC;AACnC,eAAO,MAAM,gBAAgB,qBAAe,CAAC"}

package/dist/core/utils/uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.js","sourceRoot":"","sources":["../../../src/core/utils/uuid.ts"],"names":[],"mappings":"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"}

package/dist/core/vector-store/IVectorStore.d.ts

@@ -0,0 +1,369 @@
+/**
+ * @fileoverview Defines the IVectorStore interface, representing the contract
+ * for interacting with a specific vector database or storage backend. This
+ * interface abstracts the common operations such as upserting, querying, and
+ * deleting vector documents, along with managing collections/indexes.
+ *
+ * It also defines core data structures used in these operations, including
+ * configurations for providers, document formats, query options, and metadata filters.
+ *
+ * @module backend/agentos/core/vector-store/IVectorStore
+ * @see ../../config/VectorStoreConfiguration.ts for specific provider configurations.
+ * @see ./IVectorStoreManager.ts for the interface that manages multiple IVectorStore instances.
+ */
+/**
+ * Base configuration for any vector store provider.
+ * Specific provider configurations (e.g., for Pinecone, Weaviate) should extend this.
+ *
+ * @interface VectorStoreProviderConfig
+ * @property {string} id - A unique identifier for this specific provider instance
+ * (e.g., "pinecone-main-prod", "weaviate-dev-local"). This ID is used by the
+ * VectorStoreManager to retrieve this provider.
+ * @property {string} type - The type of the vector store provider
+ * (e.g., "pinecone", "weaviate", "in_memory", "lancedb"). This helps in
+ * selecting the correct implementation.
+ * @property {Record<string, any>} [customProps] - Any other custom properties or
+ * configurations specific to this provider instance not covered by standard fields.
+ */
+export interface VectorStoreProviderConfig {
+    id: string;
+    type: string;
+    customProps?: Record<string, any>;
+}
+/**
+ * Represents a scalar value allowed in document metadata.
+ * @typedef {string | number | boolean} MetadataScalarValue
+ */
+export type MetadataScalarValue = string | number | boolean;
+/**
+ * Represents a value in document metadata, which can be a scalar or an array of scalars.
+ * @typedef {MetadataScalarValue | MetadataScalarValue[]} MetadataValue
+ */
+export type MetadataValue = MetadataScalarValue | MetadataScalarValue[];
+/**
+ * Defines conditions for filtering metadata fields during a query.
+ * Each property represents a comparison operator.
+ *
+ * @interface MetadataFieldCondition
+ * @example
+ * // Find documents where 'year' >= 2022
+ * { year: { $gte: 2022 } }
+ * // Find documents where 'tags' array contains 'typescript'
+ * { tags: { $contains: 'typescript' } }
+ * // Find documents where 'status' is 'published'
+ * { status: { $eq: 'published' } } // or simply { status: 'published' }
+ */
+export interface MetadataFieldCondition {
+    $eq?: MetadataScalarValue;
+    $ne?: MetadataScalarValue;
+    $gt?: number;
+    $gte?: number;
+    $lt?: number;
+    $lte?: number;
+    $in?: MetadataScalarValue[];
+    $nin?: MetadataScalarValue[];
+    $exists?: boolean;
+    $contains?: MetadataScalarValue;
+    $all?: MetadataScalarValue[];
+    $textSearch?: string;
+}
+/**
+ * Defines a filter for document metadata. All top-level key-value pairs are implicitly ANDed.
+ * The value for a field can be a direct scalar match (implicit equality) or a `MetadataFieldCondition` object
+ * for more complex comparisons.
+ *
+ * @typedef {Object.<string, MetadataScalarValue | MetadataFieldCondition>} MetadataFilter
+ * @example
+ * const filter: MetadataFilter = {
+ * category: "technology", // Implicit $eq
+ * year: { $gte: 2023 },
+ * tags: { $all: ["typescript", "AI"] },
+ * isPublished: true
+ * };
+ */
+export type MetadataFilter = {
+    [key: string]: MetadataScalarValue | MetadataFieldCondition;
+};
+/**
+ * Represents a document to be stored or retrieved from a vector store.
+ *
+ * @interface VectorDocument
+ * @property {string} id - A unique identifier for the document.
+ * @property {number[]} embedding - The vector embedding of the document's content.
+ * @property {Record<string, MetadataValue>} [metadata] - A flexible key-value store for document metadata.
+ * Values can be scalars or arrays of scalars. Used for filtering and providing context.
+ * @property {string} [textContent] - Optional: The raw text content of the document.
+ * Some use cases might store this alongside the embedding, while others might fetch it from a primary store using the ID.
+ */
+export interface VectorDocument {
+    id: string;
+    embedding: number[];
+    metadata?: Record<string, MetadataValue>;
+    textContent?: string;
+}
+/**
+ * Options for a vector store query operation.
+ *
+ * @interface QueryOptions
+ * @property {number} [topK=10] - The number of most similar documents to retrieve.
+ * @property {MetadataFilter} [filter] - Metadata filter to apply to the search. Only documents matching
+ * the filter will be considered.
+ * @property {boolean} [includeEmbedding=false] - Whether to include the embedding vector in the retrieved documents.
+ * @property {boolean} [includeMetadata=true] - Whether to include metadata in the retrieved documents.
+ * @property {boolean} [includeTextContent=false] - Whether to include the `textContent` in the retrieved documents.
+ * @property {number} [minSimilarityScore] - Optional minimum similarity score (0-1, or specific to metric)
+ * for a document to be included in the results. Interpretation depends on the store's similarity metric.
+ * @property {string} [userId] - Optional user ID, which might be used for multi-tenancy filters if the store supports it.
+ * @property {Record<string, any>} [customParams] - Provider-specific parameters for the query.
+ */
+export interface QueryOptions {
+    topK?: number;
+    filter?: MetadataFilter;
+    includeEmbedding?: boolean;
+    includeMetadata?: boolean;
+    includeTextContent?: boolean;
+    minSimilarityScore?: number;
+    userId?: string;
+    customParams?: Record<string, any>;
+}
+/**
+ * Represents a single document retrieved from a query, including its similarity score.
+ *
+ * @interface RetrievedVectorDocument
+ * @extends VectorDocument
+ * @property {number} similarityScore - The similarity score of this document with respect to the query vector.
+ * The meaning of this score depends on the similarity metric used by the vector store (e.g., cosine similarity, Euclidean distance).
+ */
+export interface RetrievedVectorDocument extends VectorDocument {
+    similarityScore: number;
+}
+/**
+ * The result of a vector store query operation.
+ *
+ * @interface QueryResult
+ * @property {RetrievedVectorDocument[]} documents - An array of retrieved documents, typically sorted by relevance (similarity score).
+ * @property {string} [queryId] - An optional identifier for the query, useful for logging or diagnostics.
+ * @property {Record<string, any>} [stats] - Optional statistics about the query execution (e.g., latency).
+ */
+export interface QueryResult {
+    documents: RetrievedVectorDocument[];
+    queryId?: string;
+    stats?: Record<string, any>;
+}
+/**
+ * Options for a vector store upsert (insert or update) operation.
+ *
+ * @interface UpsertOptions
+ * @property {number} [batchSize] - Preferred batch size for upserting multiple documents, if the provider supports batching.
+ * @property {boolean} [overwrite=true] - Whether to overwrite existing documents with the same ID.
+ * @property {Record<string, any>} [customParams] - Provider-specific parameters for the upsert operation.
+ */
+export interface UpsertOptions {
+    batchSize?: number;
+    overwrite?: boolean;
+    customParams?: Record<string, any>;
+}
+/**
+ * The result of a vector store upsert operation.
+ *
+ * @interface UpsertResult
+ * @property {number} upsertedCount - The number of documents successfully upserted.
+ * @property {string[]} [upsertedIds] - Optional array of IDs of the upserted documents.
+ * @property {number} [failedCount=0] - The number of documents that failed to upsert.
+ * @property {Array<{ id: string; error: string; details?: any }>} [errors] - Detailed information about any failures.
+ */
+export interface UpsertResult {
+    upsertedCount: number;
+    upsertedIds?: string[];
+    failedCount?: number;
+    errors?: Array<{
+        id: string;
+        message: string;
+        details?: any;
+    }>;
+}
+/**
+ * Options for a vector store delete operation.
+ *
+ * @interface DeleteOptions
+ * @property {MetadataFilter} [filter] - Optional: Delete documents matching this metadata filter.
+ * If `ids` are also provided, the behavior (AND/OR) might be store-specific or could be an error.
+ * Typically, deletion is by IDs OR by filter.
+ * @property {boolean} [deleteAll=false] - If true (and `ids` and `filter` are empty), attempt to delete all documents
+ * in the specified collection. This is a destructive operation and should be used with extreme caution.
+ * @property {Record<string, any>} [customParams] - Provider-specific parameters for the delete operation.
+ */
+export interface DeleteOptions {
+    filter?: MetadataFilter;
+    deleteAll?: boolean;
+    customParams?: Record<string, any>;
+}
+/**
+ * The result of a vector store delete operation.
+ *
+ * @interface DeleteResult
+ * @property {number} deletedCount - The number of documents successfully deleted.
+ * @property {number} [failedCount=0] - The number of documents/operations that failed.
+ * @property {Array<{ id?: string; error: string; details?: any }>} [errors] - Detailed information about any failures.
+ */
+export interface DeleteResult {
+    deletedCount: number;
+    failedCount?: number;
+    errors?: Array<{
+        id?: string;
+        message: string;
+        details?: any;
+    }>;
+}
+/**
+ * Options for creating a new collection/index in the vector store.
+ * @interface CreateCollectionOptions
+ * @property {'cosine' | 'euclidean' | 'dotproduct'} [similarityMetric='cosine'] - The similarity metric for the collection.
+ * @property {boolean} [overwriteIfExists=false] - If a collection with the same name exists, should it be overwritten?
+ * @property {number} [replicas] - Number of replicas for the collection (if supported).
+ * @property {number} [shards] - Number of shards for the collection (if supported).
+ * @property {Record<string, any>} [providerSpecificParams] - Any other parameters specific to the vector store provider
+ * for collection creation (e.g., indexing options, cloud region).
+ */
+export interface CreateCollectionOptions {
+    similarityMetric?: 'cosine' | 'euclidean' | 'dotproduct';
+    overwriteIfExists?: boolean;
+    replicas?: number;
+    shards?: number;
+    providerSpecificParams?: Record<string, any>;
+}
+/**
+ * @interface IVectorStore
+ * @description Defines the contract for interacting with a specific vector database or storage backend.
+ * Implementations will wrap specific clients (e.g., Pinecone client, Weaviate client, in-memory store logic).
+ */
+export interface IVectorStore {
+    /**
+     * Initializes the vector store provider with its specific configuration.
+     * This method must be called before any other operations can be performed.
+     * It sets up connections, authenticates, and prepares the store for use.
+     *
+     * @async
+     * @param {VectorStoreProviderConfig} config - The configuration object specific to this vector store provider.
+     * This is typically a more specific type that extends `VectorStoreProviderConfig`.
+     * @returns {Promise<void>} A promise that resolves when initialization is complete.
+     * @throws {Error} If initialization fails (e.g., invalid configuration, connection error, authentication failure).
+     */
+    initialize(config: VectorStoreProviderConfig): Promise<void>;
+    /**
+     * Upserts (inserts or updates) a batch of documents into a specified collection.
+     * If a document with the same ID already exists, it is typically updated; otherwise, it's inserted.
+     *
+     * @async
+     * @param {string} collectionName - The name of the collection (or index, class, etc.) to upsert documents into.
+     * @param {VectorDocument[]} documents - An array of documents to upsert.
+     * @param {UpsertOptions} [options] - Optional parameters for the upsert operation.
+     * @returns {Promise<UpsertResult>} A promise that resolves with the result of the upsert operation.
+     * @throws {Error} If the upsert operation fails critically.
+     */
+    upsert(collectionName: string, documents: VectorDocument[], options?: UpsertOptions): Promise<UpsertResult>;
+    /**
+     * Queries a specified collection for documents similar to the provided query embedding.
+     *
+     * @async
+     * @param {string} collectionName - The name of the collection to query.
+     * @param {number[]} queryEmbedding - The query vector embedding.
+     * @param {QueryOptions} [options] - Optional parameters for the query operation, including filters and topK.
+     * @returns {Promise<QueryResult>} A promise that resolves with the query results.
+     * @throws {Error} If the query operation fails.
+     */
+    query(collectionName: string, queryEmbedding: number[], options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Optional: Hybrid retrieval combining dense vector similarity with lexical search.
+     *
+     * This is typically implemented using a store-native full-text index (e.g., SQLite FTS5),
+     * or a store-side BM25 implementation, then fusing dense and lexical rankings (e.g., RRF).
+     *
+     * If not implemented, callers should fall back to `query()` (dense similarity).
+     */
+    hybridSearch?(collectionName: string, queryEmbedding: number[], queryText: string, options?: QueryOptions & {
+        /** Weight of dense retrieval (0..1). Default: implementation-defined. */
+        alpha?: number;
+        /** Fusion method used to combine rankings. Default: implementation-defined. */
+        fusion?: 'rrf' | 'weighted';
+        /** RRF k constant when `fusion='rrf'`. Default: implementation-defined. */
+        rrfK?: number;
+        /** Number of lexical candidates to consider before fusion. Default: implementation-defined. */
+        lexicalTopK?: number;
+    }): Promise<QueryResult>;
+    /**
+     * Deletes documents from a specified collection by their IDs or by a metadata filter.
+     *
+     * @async
+     * @param {string} collectionName - The name of the collection to delete documents from.
+     * @param {string[]} [ids] - An array of document IDs to delete.
+     * @param {DeleteOptions} [options] - Optional parameters, including metadata filters or a deleteAll flag.
+     * If `ids` are provided, `options.filter` might be ignored or combined,
+     * depending on store behavior. Use with caution.
+     * @returns {Promise<DeleteResult>} A promise that resolves with the result of the delete operation.
+     * @throws {Error} If the delete operation fails.
+     */
+    delete(collectionName: string, ids?: string[], options?: DeleteOptions): Promise<DeleteResult>;
+    /**
+     * Creates a new collection (or index, class, etc.) in the vector store.
+     * This is often necessary before documents can be upserted into it, depending on the provider.
+     *
+     * @async
+     * @param {string} collectionName - The name of the collection to create.
+     * @param {number} dimension - The dimensionality of the vector embeddings that will be stored in this collection.
+     * @param {CreateCollectionOptions} [options] - Optional parameters for collection creation, such as similarity metric or provider-specific settings.
+     * @returns {Promise<void>} A promise that resolves when the collection is successfully created.
+     * @throws {Error} If collection creation fails (e.g., name conflict and not overwriting, invalid parameters).
+     */
+    createCollection?(collectionName: string, dimension: number, options?: CreateCollectionOptions): Promise<void>;
+    /**
+     * Deletes an entire collection from the vector store. This is a destructive operation.
+     *
+     * @async
+     * @param {string} collectionName - The name of the collection to delete.
+     * @returns {Promise<void>} A promise that resolves when the collection is successfully deleted.
+     * @throws {Error} If collection deletion fails.
+     */
+    deleteCollection?(collectionName: string): Promise<void>;
+    /**
+     * Checks if a collection with the given name exists in the vector store.
+     *
+     * @async
+     * @param {string} collectionName - The name of the collection to check.
+     * @returns {Promise<boolean>} A promise that resolves with `true` if the collection exists, `false` otherwise.
+     * @throws {Error} If the check fails for reasons other than existence (e.g., connection issue).
+     */
+    collectionExists?(collectionName: string): Promise<boolean>;
+    /**
+     * Checks the operational health of the vector store provider.
+     * This might involve pinging the service, checking connection status, or verifying authentication.
+     *
+     * @async
+     * @returns {Promise<{ isHealthy: boolean; details?: any }>} A promise that resolves with the health status.
+     * `details` can include specific error messages or status information.
+     */
+    checkHealth(): Promise<{
+        isHealthy: boolean;
+        details?: any;
+    }>;
+    /**
+     * Gracefully shuts down the vector store provider, releasing any resources
+     * such as database connections or client instances.
+     *
+     * @async
+     * @returns {Promise<void>} A promise that resolves when shutdown is complete.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Optional: Retrieves statistics about a specific collection or the store itself.
+     * The structure of the returned statistics is provider-dependent.
+     *
+     * @async
+     * @param {string} [collectionName] - Optional: The name of the collection to get stats for.
+     * If omitted, may return store-wide stats if supported.
+     * @returns {Promise<Record<string, any>>} A promise that resolves with a statistics object.
+     * @throws {Error} If fetching statistics fails.
+     */
+    getStats?(collectionName?: string): Promise<Record<string, any>>;
+}
+//# sourceMappingURL=IVectorStore.d.ts.map

package/dist/core/vector-store/IVectorStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IVectorStore.d.ts","sourceRoot":"","sources":["../../../src/core/vector-store/IVectorStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE5D;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,mBAAmB,EAAE,CAAC;AAExE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,sBAAsB;IACrC,GAAG,CAAC,EAAE,mBAAmB,CAAC;IAC1B,GAAG,CAAC,EAAE,mBAAmB,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,IAAI,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;CAC7D,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAwB,SAAQ,cAAc;IAC7D,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,uBAAuB,EAAE,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;CAChE;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;CACjE;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAuB;IACtC,gBAAgB,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,YAAY,CAAC;IACzD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sBAAsB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9C;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;OAUG;IACH,UAAU,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7D;;;;;;;;;;OAUG;IACH,MAAM,CACJ,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,cAAc,EAAE,EAC3B,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;;;;;OASG;IACH,KAAK,CACH,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EAAE,EACxB,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;;;;;OAOG;IACH,YAAY,CAAC,CACX,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EAAE,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,YAAY,GAAG;QACvB,yEAAyE;QACzE,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,+EAA+E;QAC/E,MAAM,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;QAC5B,2EAA2E;QAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,+FAA+F;QAC/F,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GACA,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;;;;;;;;;OAWG;IACH,MAAM,CACJ,cAAc,EAAE,MAAM,EACtB,GAAG,CAAC,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,CACf,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;OAOG;IACH,gBAAgB,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzD;;;;;;;OAOG;IACH,gBAAgB,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE5D;;;;;;;OAOG;IACH,WAAW,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAE9D;;;;;;OAMG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;;;;;;;OASG;IACH,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;CAClE"}

package/dist/core/vector-store/IVectorStore.js

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Defines the IVectorStore interface, representing the contract
+ * for interacting with a specific vector database or storage backend. This
+ * interface abstracts the common operations such as upserting, querying, and
+ * deleting vector documents, along with managing collections/indexes.
+ *
+ * It also defines core data structures used in these operations, including
+ * configurations for providers, document formats, query options, and metadata filters.
+ *
+ * @module backend/agentos/core/vector-store/IVectorStore
+ * @see ../../config/VectorStoreConfiguration.ts for specific provider configurations.
+ * @see ./IVectorStoreManager.ts for the interface that manages multiple IVectorStore instances.
+ */
+export {};
+//# sourceMappingURL=IVectorStore.js.map

package/dist/core/vector-store/IVectorStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IVectorStore.js","sourceRoot":"","sources":["../../../src/core/vector-store/IVectorStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/core/vector-store/IVectorStoreManager.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview Defines the interface for the VectorStoreManager.
+ * The VectorStoreManager is responsible for initializing, configuring, and providing
+ * access to multiple IVectorStore provider instances. It acts as a central point
+ * of contact for the RetrievalAugmentor to obtain specific vector store connections
+ * based on configuration, abstracting away the direct management of individual store clients.
+ *
+ * @module backend/agentos/core/vector-store/IVectorStoreManager
+ * @see ./IVectorStore.ts for the underlying vector store interface.
+ * @see ../../config/VectorStoreConfiguration.ts for the `VectorStoreManagerConfig` structure.
+ */
+import { IVectorStore } from './IVectorStore';
+import { VectorStoreManagerConfig, RagDataSourceConfig } from '../../config/VectorStoreConfiguration';
+/**
+ * Represents the health status of managed vector store providers.
+ *
+ * @interface VectorStoreManagerHealthReport
+ * @property {boolean} isOverallHealthy - True if all critical providers are healthy or if the manager itself is operational.
+ * @property {Record<string, { isHealthy: boolean; details?: any }>} [providerStatus] -
+ * An object detailing the health status of each individual managed provider, keyed by provider ID.
+ * @property {any} [managerDetails] - Additional details about the manager's operational status.
+ */
+export interface VectorStoreManagerHealthReport {
+    isOverallHealthy: boolean;
+    providerStatus?: Record<string, {
+        isHealthy: boolean;
+        details?: any;
+    }>;
+    managerDetails?: any;
+}
+/**
+ * @interface IVectorStoreManager
+ * @description Manages and provides access to various configured IVectorStore instances.
+ * It allows higher-level services like the RetrievalAugmentor to be agnostic of the
+ * specific vector database being used for a particular data source or category,
+ * based on the provided `VectorStoreManagerConfig` and `RagDataSourceConfig`.
+ */
+export interface IVectorStoreManager {
+    /**
+     * Initializes the VectorStoreManager with configurations for all its managed providers
+     * and data sources. This involves instantiating and initializing each configured
+     * `IVectorStore` provider.
+     *
+     * @async
+     * @param {VectorStoreManagerConfig} managerConfig - The manager's configuration, including an array of
+     * individual vector store provider configurations.
+     * @param {RagDataSourceConfig[]} dataSourceConfigs - An array of configurations for all logical data sources,
+     * which map to specific providers and collections/indexes within them.
+     * @returns {Promise<void>} A promise that resolves when the manager and all its
+     * essential providers are successfully initialized.
+     * @throws {Error} If initialization fails due to invalid configuration, inability to connect
+     * to a critical provider, or other setup errors.
+     */
+    initialize(managerConfig: VectorStoreManagerConfig, dataSourceConfigs: RagDataSourceConfig[]): Promise<void>;
+    /**
+     * Retrieves a specific, initialized IVectorStore provider instance by its configured ID.
+     * The provider ID corresponds to `VectorStoreProviderConfig.id`.
+     *
+     * @param {string} providerId - The unique ID of the vector store provider instance.
+     * @returns {IVectorStore} The IVectorStore instance.
+     * @throws {Error} If the providerId is not configured, not found, or the provider
+     * failed to initialize.
+     */
+    getProvider(providerId: string): IVectorStore;
+    /**
+     * Retrieves the default IVectorStore provider instance as configured in `VectorStoreManagerConfig.defaultProviderId`.
+     *
+     * @returns {IVectorStore} The default IVectorStore instance.
+     * @throws {Error} If no default provider is configured, the configured default provider is not found,
+     * or it failed to initialize.
+     */
+    getDefaultProvider(): IVectorStore;
+    /**
+     * Retrieves an IVectorStore instance and the specific collection name within that store
+     * associated with a given logical RAG Data Source ID.
+     * This is a convenience method for services like RetrievalAugmentor that operate on
+     * logical `dataSourceId`s.
+     *
+     * @param {string} dataSourceId - The logical RAG Data Source ID (from `RagDataSourceConfig.dataSourceId`).
+     * @returns {Promise<{ store: IVectorStore; collectionName: string; dimension?: number }>} A promise that resolves with the
+     * IVectorStore instance, the actual collection name to use with that store for this data source,
+     * and the expected embedding dimension.
+     * @throws {Error} If the `dataSourceId` is not configured, or its associated provider is unavailable.
+     */
+    getStoreForDataSource(dataSourceId: string): Promise<{
+        store: IVectorStore;
+        collectionName: string;
+        dimension?: number;
+    }>;
+    /**
+     * Lists the unique IDs of all vector store providers configured and managed by this manager.
+     *
+     * @returns {string[]} An array of provider IDs.
+     */
+    listProviderIds(): string[];
+    /**
+     * Lists the unique IDs of all logical RAG Data Sources configured.
+     *
+     * @returns {string[]} An array of RAG Data Source IDs.
+     */
+    listDataSourceIds(): string[];
+    /**
+     * Checks the health of all managed vector store providers or a specific one.
+     * This aggregates health information from individual `IVectorStore.checkHealth()` calls.
+     *
+     * @async
+     * @param {string} [providerId] - Optional: If provided, checks only this specific provider.
+     * If omitted, checks all configured providers.
+     * @returns {Promise<VectorStoreManagerHealthReport>} A promise that resolves with a comprehensive health report.
+     */
+    checkHealth(providerId?: string): Promise<VectorStoreManagerHealthReport>;
+    /**
+     * Gracefully shuts down all managed vector store providers.
+     * This calls the `shutdown()` method on each initialized `IVectorStore` instance.
+     *
+     * @async
+     * @returns {Promise<void>} A promise that resolves when all providers have been shut down.
+     */
+    shutdownAllProviders(): Promise<void>;
+}
+//# sourceMappingURL=IVectorStoreManager.d.ts.map

package/dist/core/vector-store/IVectorStoreManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IVectorStoreManager.d.ts","sourceRoot":"","sources":["../../../src/core/vector-store/IVectorStoreManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAEtG;;;;;;;;GAQG;AACH,MAAM,WAAW,8BAA8B;IAC7C,gBAAgB,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IACvE,cAAc,CAAC,EAAE,GAAG,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;OAcG;IACH,UAAU,CACR,aAAa,EAAE,wBAAwB,EACvC,iBAAiB,EAAE,mBAAmB,EAAE,GACvC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;OAQG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAAC;IAE9C;;;;;;OAMG;IACH,kBAAkB,IAAI,YAAY,CAAC;IAEnC;;;;;;;;;;;OAWG;IACH,qBAAqB,CACnB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;QAAE,KAAK,EAAE,YAAY,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAGhF;;;;OAIG;IACH,eAAe,IAAI,MAAM,EAAE,CAAC;IAE5B;;;;OAIG;IACH,iBAAiB,IAAI,MAAM,EAAE,CAAC;IAG9B;;;;;;;;OAQG;IACH,WAAW,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAE1E;;;;;;OAMG;IACH,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC"}

package/dist/core/vector-store/IVectorStoreManager.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Defines the interface for the VectorStoreManager.
+ * The VectorStoreManager is responsible for initializing, configuring, and providing
+ * access to multiple IVectorStore provider instances. It acts as a central point
+ * of contact for the RetrievalAugmentor to obtain specific vector store connections
+ * based on configuration, abstracting away the direct management of individual store clients.
+ *
+ * @module backend/agentos/core/vector-store/IVectorStoreManager
+ * @see ./IVectorStore.ts for the underlying vector store interface.
+ * @see ../../config/VectorStoreConfiguration.ts for the `VectorStoreManagerConfig` structure.
+ */
+export {};
+//# sourceMappingURL=IVectorStoreManager.js.map

package/dist/core/vector-store/IVectorStoreManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IVectorStoreManager.js","sourceRoot":"","sources":["../../../src/core/vector-store/IVectorStoreManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}