@framers/agentos 0.1.0

package/dist/rag/IVectorStore.d.ts

@@ -0,0 +1,351 @@
+/**
+ * @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/rag/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>;
+    /**
+     * 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/rag/IVectorStore.d.ts.map

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

package/dist/rag/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/rag/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/rag/IVectorStore.js.map

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

package/dist/rag/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/rag/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/rag/IVectorStoreManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IVectorStoreManager.d.ts","sourceRoot":"","sources":["../../src/rag/IVectorStoreManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAEnG;;;;;;;;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/rag/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/rag/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/rag/IVectorStoreManager.js.map

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

package/dist/rag/RetrievalAugmentor.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview Implements the RetrievalAugmentor, the core orchestrator for the
+ * AgentOS Retrieval Augmented Generation (RAG) system. It adheres to the
+ * `IRetrievalAugmentor` interface.
+ *
+ * This class is responsible for:
+ * - Ingesting documents: Involves chunking, embedding generation via `IEmbeddingManager`,
+ * and storage into vector databases via `IVectorStoreManager`.
+ * - Retrieving context: Embeds queries, searches relevant vector stores for similar
+ * chunks, optionally re-ranks, and formats the results into a context string suitable
+ * for augmenting LLM prompts.
+ * - Managing document lifecycle (delete, update).
+ * - Providing health checks and graceful shutdown.
+ *
+ * @module backend/agentos/rag/RetrievalAugmentor
+ * @see ./IRetrievalAugmentor.ts for the interface definition.
+ * @see ../config/RetrievalAugmentorConfiguration.ts for `RetrievalAugmentorServiceConfig`.
+ * @see ./IEmbeddingManager.ts
+ * @see ./IVectorStoreManager.ts
+ */
+import { IRetrievalAugmentor, RagDocumentInput, RagIngestionOptions, RagIngestionResult, RagRetrievalOptions, RagRetrievalResult } from './IRetrievalAugmentor';
+import { RetrievalAugmentorServiceConfig } from '../config/RetrievalAugmentorConfiguration';
+import { IEmbeddingManager } from './IEmbeddingManager';
+import { IVectorStoreManager } from './IVectorStoreManager';
+/**
+ * @class RetrievalAugmentor
+ * @implements {IRetrievalAugmentor}
+ * Orchestrates the RAG pipeline including ingestion, retrieval, and document management.
+ */
+export declare class RetrievalAugmentor implements IRetrievalAugmentor {
+    readonly augmenterId: string;
+    private config;
+    private embeddingManager;
+    private vectorStoreManager;
+    private isInitialized;
+    /**
+     * Constructs a RetrievalAugmentor instance.
+     * It is not operational until `initialize` is successfully called.
+     */
+    constructor();
+    /**
+     * @inheritdoc
+     */
+    initialize(config: RetrievalAugmentorServiceConfig, embeddingManager: IEmbeddingManager, vectorStoreManager: IVectorStoreManager): Promise<void>;
+    /**
+     * Ensures that the augmenter has been initialized.
+     * @private
+     * @throws {GMIError} If not initialized.
+     */
+    private ensureInitialized;
+    /**
+     * @inheritdoc
+     */
+    ingestDocuments(documents: RagDocumentInput | RagDocumentInput[], options?: RagIngestionOptions): Promise<RagIngestionResult>;
+    /**
+     * Processes a batch of documents for ingestion.
+     * @private
+     */
+    private processDocumentBatch;
+    /**
+     * Chunks a single document based on the provided or default strategy.
+     * @private
+     */
+    private chunkDocument;
+    /**
+     * @inheritdoc
+     */
+    retrieveContext(queryText: string, options?: RagRetrievalOptions): Promise<RagRetrievalResult>;
+    /**
+     * @inheritdoc
+     */
+    deleteDocuments(documentIds: string[], dataSourceId?: string, _options?: {
+        ignoreNotFound?: boolean;
+    }): Promise<{
+        successCount: number;
+        failureCount: number;
+        errors?: Array<{
+            documentId: string;
+            message: string;
+            details?: any;
+        }>;
+    }>;
+    /**
+     * @inheritdoc
+     */
+    updateDocuments(documents: RagDocumentInput | RagDocumentInput[], options?: RagIngestionOptions): Promise<RagIngestionResult>;
+    /**
+     * @inheritdoc
+     */
+    checkHealth(): Promise<{
+        isHealthy: boolean;
+        details?: Record<string, unknown>;
+    }>;
+    /**
+     * @inheritdoc
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=RetrievalAugmentor.d.ts.map

package/dist/rag/RetrievalAugmentor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetrievalAugmentor.d.ts","sourceRoot":"","sources":["../../src/rag/RetrievalAugmentor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,+BAA+B,EAAE,MAAM,2CAA2C,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAU5D;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,mBAAmB;IAC5D,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,kBAAkB,CAAuB;IACjD,OAAO,CAAC,aAAa,CAAkB;IAEvC;;;OAGG;;IAKH;;OAEG;IACU,UAAU,CACrB,MAAM,EAAE,+BAA+B,EACvC,gBAAgB,EAAE,iBAAiB,EACnC,kBAAkB,EAAE,mBAAmB,GACtC,OAAO,CAAC,IAAI,CAAC;IA0ChB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IASzB;;OAEG;IACU,eAAe,CAC1B,SAAS,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,EAChD,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC;IA6C9B;;;OAGG;YACW,oBAAoB;IAoOlC;;;OAGG;IACH,OAAO,CAAC,aAAa;IAuCrB;;OAEG;IACU,eAAe,CAC1B,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC;IA8K9B;;OAEG;IACU,eAAe,CAC1B,WAAW,EAAE,MAAM,EAAE,EACrB,YAAY,CAAC,EAAE,MAAM,EACrB,QAAQ,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,GACtC,OAAO,CAAC;QACT,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,KAAK,CAAC;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,GAAG,CAAA;SAAE,CAAC,CAAC;KACxE,CAAC;IAyDF;;OAEG;IACU,eAAe,CAC1B,SAAS,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,EAChD,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC;IA+B9B;;OAEG;IACU,WAAW,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IA0B9F;;OAEG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAevC"}