@framers/agentos 0.1.0

package/dist/rag/IEmbeddingManager.d.ts

@@ -0,0 +1,277 @@
+/**
+ * @fileoverview Defines the interface for the EmbeddingManager, responsible for
+ * generating vector embeddings for textual content. It outlines the contract for
+ * managing various embedding models, orchestrating embedding generation (potentially
+ * with caching and dynamic model selection), and providing information about
+ * available models.
+ *
+ * The EmbeddingManager relies on configurations defined in
+ * `../config/EmbeddingManagerConfiguration.ts` and interacts with
+ * `../core/llm/providers/AIModelProviderManager` to communicate with actual
+ * Large Language Model (LLM) providers for embedding generation.
+ *
+ * @module backend/agentos/rag/IEmbeddingManager
+ * @see ../config/EmbeddingManagerConfiguration.ts
+ * @see ../core/llm/providers/AIModelProviderManager.ts
+ * @see ./EmbeddingManager.ts for a concrete implementation.
+ */
+import { AIModelProviderManager } from '../core/llm/providers/AIModelProviderManager';
+import { EmbeddingManagerConfig, EmbeddingModelConfig } from '../config/EmbeddingManagerConfiguration.js';
+/**
+ * Represents a request to generate embeddings.
+ * This structure encapsulates the text(s) to be embedded and any parameters
+ * that might influence the embedding process, such as model selection hints
+ * or user context.
+ *
+ * @interface EmbeddingRequest
+ */
+export interface EmbeddingRequest {
+    /**
+     * The text content to be embedded. Can be a single string or an array of strings
+     * for batch processing.
+     * @type {string | string[]}
+     * @example
+     * // Single text
+     * const requestOne: EmbeddingRequest = { texts: "Hello, world!" };
+     * // Batch of texts
+     * const requestBatch: EmbeddingRequest = { texts: ["First document.", "Second document."] };
+     */
+    texts: string | string[];
+    /**
+     * Optional: The explicit ID of the embedding model to use.
+     * If not provided, the EmbeddingManager will select a model based on its
+     * configured strategy (e.g., default model, dynamic selection).
+     * @type {string}
+     * @optional
+     * @example "text-embedding-3-small"
+     */
+    modelId?: string;
+    /**
+     * Optional: The explicit ID of the LLM provider to use.
+     * This is typically used in conjunction with `modelId`. If `modelId` is provided
+     * and has a configured provider, this field might be used for validation or override
+     * if the architecture supports it. Generally, the model's configured provider is preferred.
+     * @type {string}
+     * @optional
+     * @example "openai"
+     */
+    providerId?: string;
+    /**
+     * Optional: Identifier for the user making the request.
+     * This can be used for logging, auditing, or if the underlying LLM provider
+     * requires user-specific API keys or applies user-based rate limits.
+     * @type {string}
+     * @optional
+     * @example "user-12345"
+     */
+    userId?: string;
+    /**
+     * Optional: Identifier for a data collection or namespace.
+     * This can be used by dynamic model selection strategies (e.g.,
+     * 'dynamic_collection_preference') to choose a model best suited
+     * for the content of a specific collection.
+     * @type {string}
+     * @optional
+     * @example "financial_reports_q3_2024"
+     */
+    collectionId?: string;
+    /**
+     * Optional: Custom parameters to pass through to the embedding generation process.
+     * This could include provider-specific options or hints for the EmbeddingManager.
+     * The exact interpretation of these parameters is implementation-dependent.
+     * @type {Record<string, any>}
+     * @optional
+     * @example { "priority": "high", "target_latency_ms": 500 }
+     */
+    customParameters?: Record<string, any>;
+}
+/**
+ * Represents the response from an embedding generation request.
+ * This structure includes the generated embeddings, information about the model
+ * and provider used, token usage details, and any errors encountered during
+ * processing (especially relevant for batch requests).
+ *
+ * @interface EmbeddingResponse
+ */
+export interface EmbeddingResponse {
+    /**
+     * An array of embedding vectors. Each inner array (`number[]`) corresponds
+     * to an input text from the `EmbeddingRequest`. The order is preserved.
+     * If an error occurred for a specific text in a batch, its corresponding
+     * entry might be missing, or represented by a specific error object if partial
+     * results are supported differently. The `errors` array should be checked.
+     * @type {number[][]}
+     * @example [[0.1, 0.2, ...], [0.3, 0.4, ...]]
+     */
+    embeddings: number[][];
+    /**
+     * The ID of the embedding model that was actually used to generate the embeddings.
+     * This is important for consistency, especially if model selection was dynamic.
+     * @type {string}
+     * @example "text-embedding-3-small"
+     */
+    modelId: string;
+    /**
+     * The ID of the LLM provider that was used.
+     * @type {string}
+     * @example "openai"
+     */
+    providerId: string;
+    /**
+     * Information about token usage and cost for the embedding generation.
+     * @type {object}
+     * @property {number} [inputTokens] - The number of tokens in the input text(s).
+     * This corresponds to `prompt_tokens` from the provider.
+     * @property {number} totalTokens - The total number of tokens processed by the model.
+     * For many embedding models, `totalTokens` will be equal to `inputTokens`.
+     * @property {number} [costUSD] - Estimated cost of the embedding operation in USD, if available.
+     */
+    usage: {
+        inputTokens?: number;
+        totalTokens: number;
+        costUSD?: number;
+    };
+    /**
+     * Optional: An array of error objects, relevant if processing a batch of texts
+     * and some individual texts failed. If the entire request failed catastrophically,
+     * the `generateEmbeddings` method itself should throw an error.
+     * @type {Array<{ textIndex: number; message: string; details?: any }>}
+     * @optional
+     * @property {number} textIndex - The original 0-based index of the text in the input `EmbeddingRequest.texts` array that failed.
+     * @property {string} message - A human-readable error message.
+     * @property {any} [details] - Additional error details or the raw error object from the provider.
+     * @example
+     * errors: [{ textIndex: 1, message: "Content policy violation", details: { reason: "unsafe_content" } }]
+     */
+    errors?: Array<{
+        textIndex: number;
+        message: string;
+        details?: any;
+    }>;
+}
+/**
+ * @interface IEmbeddingManager
+ * @description Defines the contract for managing and utilizing embedding models.
+ * Implementations of this interface are responsible for generating vector
+ * embeddings from text, handling different model providers, and potentially
+ * managing caching and model selection strategies.
+ */
+export interface IEmbeddingManager {
+    /**
+     * Initializes the EmbeddingManager with its configuration and necessary dependencies.
+     * This method must be called before any other operations can be performed.
+     * It sets up available embedding models, caching, and selection strategies.
+     *
+     * @async
+     * @param {EmbeddingManagerConfig} config - The configuration object for the EmbeddingManager.
+     * This includes details about available models,
+     * caching, and default settings.
+     * @param {AIModelProviderManager} providerManager - An instance of AIModelProviderManager,
+     * used to interact with the actual LLM providers
+     * that generate embeddings.
+     * @returns {Promise<void>} A promise that resolves when initialization is complete.
+     * @throws {GMIError | Error} If initialization fails due to invalid configuration,
+     * inability to set up providers, or other critical errors.
+     * A `GMIError` with a `code` like 'CONFIG_ERROR' or 'INITIALIZATION_FAILED'
+     * is preferred.
+     * @example
+     * const manager = new EmbeddingManager();
+     * await manager.initialize(embeddingManagerConfig, aiModelProviderManager);
+     */
+    initialize(config: EmbeddingManagerConfig, providerManager: AIModelProviderManager): Promise<void>;
+    /**
+     * Generates embeddings for the provided text(s) using an appropriate model.
+     * This method handles model selection (if not explicitly specified in the request),
+     * interaction with the LLM provider, and caching (if enabled).
+     *
+     * @async
+     * @param {EmbeddingRequest} request - The request object containing the text(s) to embed
+     * and any relevant options.
+     * @returns {Promise<EmbeddingResponse>} A promise that resolves with the generated embeddings,
+     * usage details, and information about the model used.
+     * @throws {GMIError | Error} If the embedding generation process fails critically (e.g.,
+     * provider unavailable, authentication error, invalid request parameters
+     * not caught by initial validation). A `GMIError` with a `code` like
+     * 'PROVIDER_ERROR', 'REQUEST_FAILED', or 'NOT_INITIALIZED' is preferred.
+     * For batch requests, individual text failures might be reported in
+     * `EmbeddingResponse.errors` instead of throwing.
+     * @example
+     * const response = await embeddingManager.generateEmbeddings({
+     * texts: ["What is the capital of France?", "Explain quantum computing."],
+     * userId: "user-xyz"
+     * });
+     * console.log(response.embeddings);
+     */
+    generateEmbeddings(request: EmbeddingRequest): Promise<EmbeddingResponse>;
+    /**
+     * Retrieves configuration information for a specific embedding model.
+     * If no `modelId` is provided, it typically returns information for the
+     * default configured embedding model.
+     *
+     * @async
+     * @param {string} [modelId] - Optional: The ID of the model to get information for.
+     * If omitted, the default model's info is returned.
+     * @returns {Promise<EmbeddingModelConfig | undefined>} A promise that resolves with the
+     * model's configuration object, or
+     * `undefined` if the model is not found.
+     * @throws {GMIError | Error} If the manager is not initialized.
+     * @example
+     * const modelInfo = await embeddingManager.getEmbeddingModelInfo("text-embedding-ada-002");
+     * if (modelInfo) {
+     * console.log(`Model Dimensions: ${modelInfo.dimension}`);
+     * }
+     */
+    getEmbeddingModelInfo(modelId?: string): Promise<EmbeddingModelConfig | undefined>;
+    /**
+     * Gets the embedding dimension for a specific model, or the default system dimension.
+     * This is crucial for configuring vector stores and other components that need to
+     * know the size of the embedding vectors.
+     *
+     * @async
+     * @param {string} [modelId] - Optional: The ID of the model. If omitted, tries to return
+     * the dimension of the default model, or a system-wide default
+     * embedding dimension if configured.
+     * @returns {Promise<number>} A promise that resolves with the embedding dimension.
+     * @throws {GMIError | Error} If the dimension cannot be determined (e.g., model not found
+     * and no default dimension configured). A `GMIError` with code
+     * 'CONFIG_ERROR' or 'NOT_FOUND' is preferred.
+     * @example
+     * const dimension = await embeddingManager.getEmbeddingDimension("text-embedding-3-small");
+     * console.log(`Embeddings will have ${dimension} dimensions.`);
+     */
+    getEmbeddingDimension(modelId?: string): Promise<number>;
+    /**
+     * Checks the operational health of the EmbeddingManager.
+     * This may involve verifying its initialization status and, potentially, the
+     * health of its connections to default or critical LLM providers.
+     *
+     * @async
+     * @returns {Promise<{ isHealthy: boolean; details?: any }>} A promise that resolves with
+     * an object indicating health status
+     * and optionally providing more details
+     * (e.g., status of providers, cache).
+     * @example
+     * const health = await embeddingManager.checkHealth();
+     * if (health.isHealthy) {
+     * console.log("EmbeddingManager is healthy.");
+     * } else {
+     * console.error("EmbeddingManager health check failed:", health.details);
+     * }
+     */
+    checkHealth(): Promise<{
+        isHealthy: boolean;
+        details?: any;
+    }>;
+    /**
+     * Gracefully shuts down the EmbeddingManager, releasing any resources it holds.
+     * This could include clearing caches, closing persistent connections if any were
+     * managed directly (though typically provider connections are managed by AIModelProviderManager).
+     *
+     * @async
+     * @returns {Promise<void>} A promise that resolves when shutdown is complete.
+     * @example
+     * await embeddingManager.shutdown();
+     */
+    shutdown?(): Promise<void>;
+}
+//# sourceMappingURL=IEmbeddingManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IEmbeddingManager.d.ts","sourceRoot":"","sources":["../../src/rag/IEmbeddingManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,8CAA8C,CAAC;AACtF,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,4CAA4C,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEzB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC;IAEvB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;;;;OAQG;IACH,KAAK,EAAE;QACL,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,GAAG,CAAC;KACf,CAAC,CAAC;CACJ;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,UAAU,CACR,MAAM,EAAE,sBAAsB,EAC9B,eAAe,EAAE,sBAAsB,GACtC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE1E;;;;;;;;;;;;;;;;;OAiBG;IACH,qBAAqB,CACnB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAAC;IAE7C;;;;;;;;;;;;;;;;OAgBG;IACH,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzD;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAE9D;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B"}

package/dist/rag/IEmbeddingManager.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Defines the interface for the EmbeddingManager, responsible for
+ * generating vector embeddings for textual content. It outlines the contract for
+ * managing various embedding models, orchestrating embedding generation (potentially
+ * with caching and dynamic model selection), and providing information about
+ * available models.
+ *
+ * The EmbeddingManager relies on configurations defined in
+ * `../config/EmbeddingManagerConfiguration.ts` and interacts with
+ * `../core/llm/providers/AIModelProviderManager` to communicate with actual
+ * Large Language Model (LLM) providers for embedding generation.
+ *
+ * @module backend/agentos/rag/IEmbeddingManager
+ * @see ../config/EmbeddingManagerConfiguration.ts
+ * @see ../core/llm/providers/AIModelProviderManager.ts
+ * @see ./EmbeddingManager.ts for a concrete implementation.
+ */
+export {};
+//# sourceMappingURL=IEmbeddingManager.js.map

package/dist/rag/IEmbeddingManager.js.map

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

package/dist/rag/IRetrievalAugmentor.d.ts

@@ -0,0 +1,208 @@
+/**
+ * @fileoverview Defines the contracts and shared types for the Retrieval Augmented Generation (RAG)
+ * pipeline inside AgentOS.  The RetrievalAugmentor coordinates between embedding managers, vector
+ * store managers, and higher level orchestration (GMI, personas) to ingest knowledge, retrieve
+ * relevant context, and manage document lifecycles.
+ *
+ * @module backend/agentos/rag/IRetrievalAugmentor
+ */
+import { IEmbeddingManager } from './IEmbeddingManager';
+import { MetadataFilter, MetadataValue } from './IVectorStore';
+import { IVectorStoreManager } from './IVectorStoreManager';
+import { RetrievalAugmentorServiceConfig } from '../config/RetrievalAugmentorConfiguration';
+/**
+ * Logical buckets that the RAG system can target.  These allow integrators to map different
+ * document types or knowledge sources to distinct vector store data sources and policies.
+ */
+export declare enum RagMemoryCategory {
+    PERSONAL_LLM_EXPERIENCE = "personal_llm_experience",
+    USER_EXPLICIT_MEMORY = "user_explicit_memory",
+    SHARED_KNOWLEDGE_BASE = "shared_knowledge_base",
+    EPISODIC_CONTEXT = "episodic_context",
+    GOAL_ORIENTED_MEMORY = "goal_oriented_memory"
+}
+/**
+ * Represents raw document content provided for ingestion.
+ */
+export interface RagDocumentInput {
+    /** Stable identifier for the document (chunk IDs will derive from this). */
+    id: string;
+    /** Raw text that will be chunked and embedded. */
+    content: string;
+    /** Optional override for which data source / collection to push this document into. */
+    dataSourceId?: string;
+    /** Original source pointer (URL, file path, API, etc.). */
+    source?: string;
+    /** Arbitrary metadata stored alongside chunks; values must be vector-store friendly. */
+    metadata?: Record<string, MetadataValue>;
+    /** ISO language tag for the content. */
+    language?: string;
+    /** ISO timestamp describing when this content was produced/updated. */
+    timestamp?: string;
+    /** Optional pre-computed embedding vector. */
+    embedding?: number[];
+    /** Identifier of the embedding model used when `embedding` is supplied. */
+    embeddingModelId?: string;
+}
+/**
+ * Chunking options and ingestion-time overrides.
+ */
+export interface RagIngestionOptions {
+    /**
+     * Explicit target data source ID.  If omitted, the augmentor falls back to the document-specified
+     * `dataSourceId`, category behavior defaults, or system defaults.
+     */
+    targetDataSourceId?: string;
+    /**
+     * Behavior when a document ID already exists.
+     * - `overwrite`: replace the existing document/chunks (default).
+     * - `skip`: ignore duplicate IDs.
+     * - `error`: surface a validation error.
+     */
+    duplicateHandling?: 'overwrite' | 'skip' | 'error';
+    /**
+     * Chunking configuration.  `strategySpecificParams` allows pluggable implementations to carry
+     * provider-specific hints without widening the base interface each time.
+     */
+    chunkingStrategy?: {
+        type: 'none' | 'fixed_size' | 'recursive_character' | 'semantic';
+        chunkSize?: number;
+        chunkOverlap?: number;
+        strategySpecificParams?: Record<string, any>;
+    };
+    /**
+     * Embedding model identifier used when generating embeddings for this ingestion request.
+     * When omitted the augmentor consults the service config / category defaults.
+     */
+    embeddingModelId?: string;
+    /** Optional user identifier for auditing and personalization. */
+    userId?: string;
+    /** Optional persona identifier for personalization. */
+    personaId?: string;
+    /** Batch size for large ingestion jobs. */
+    batchSize?: number;
+    /** Whether to schedule ingestion asynchronously (future enhancement hook). */
+    processAsync?: boolean;
+}
+/**
+ * Structure describing a retrieved chunk.
+ */
+export interface RagRetrievedChunk {
+    id: string;
+    content: string;
+    /** Original document ID for traceability. */
+    originalDocumentId: string;
+    /** Data source / collection identifier. */
+    dataSourceId?: string;
+    /** Optional human-friendly source description. */
+    source?: string;
+    /** Metadata that traveled with the chunk. */
+    metadata?: Record<string, MetadataValue>;
+    /** Similarity or relevance score returned by the vector store. */
+    relevanceScore?: number;
+    /** Embedding vector if `includeEmbeddings` was requested. */
+    embedding?: number[];
+}
+/**
+ * Result of an ingestion attempt.
+ */
+export interface RagIngestionResult {
+    processedCount: number;
+    failedCount: number;
+    ingestedIds?: string[];
+    errors?: Array<{
+        documentId?: string;
+        chunkId?: string;
+        message: string;
+        details?: unknown;
+    }>;
+    jobId?: string;
+    effectiveDataSourceIds?: string[];
+}
+/**
+ * Diagnostics emitted by retrieval operations.
+ */
+export interface RagRetrievalDiagnostics {
+    embeddingTimeMs?: number;
+    retrievalTimeMs?: number;
+    rerankingTimeMs?: number;
+    totalTokensInContext?: number;
+    strategyUsed?: RagRetrievalOptions['strategy'];
+    dataSourceHits?: Record<string, number>;
+    effectiveDataSourceIds?: string[];
+    messages?: string[];
+}
+/**
+ * Options controlling retrieval behavior.
+ */
+export interface RagRetrievalOptions {
+    /** Maximum number of chunks per query. */
+    topK?: number;
+    /** Set of explicit data sources to query. */
+    targetDataSourceIds?: string[];
+    /** Memory categories to consult (maps to data sources via config). */
+    targetMemoryCategories?: RagMemoryCategory[];
+    /** Metadata filter applied at the vector-store layer. */
+    metadataFilter?: MetadataFilter;
+    /** Retrieval strategy (defaults to similarity search). */
+    strategy?: 'similarity' | 'mmr' | 'hybrid';
+    /** Strategy-specific parameters (MMR lambda, hybrid alpha, etc.). */
+    strategyParams?: {
+        mmrLambda?: number;
+        hybridAlpha?: number;
+        custom?: Record<string, any>;
+    };
+    /** Reranker configuration stub (future pluggable). */
+    rerankerConfig?: {
+        enabled?: boolean;
+        modelId?: string;
+        providerId?: string;
+        topN?: number;
+        params?: Record<string, any>;
+    };
+    /** Include chunk embeddings in the response. */
+    includeEmbeddings?: boolean;
+    /** Query embedding model override. */
+    queryEmbeddingModelId?: string;
+    /** Advisory token/character budget for final context construction. */
+    tokenBudgetForContext?: number;
+    /** Caller identity for logging/billing. */
+    userId?: string;
+}
+/**
+ * Retrieval result passed back to callers.
+ */
+export interface RagRetrievalResult {
+    queryText: string;
+    retrievedChunks: RagRetrievedChunk[];
+    augmentedContext: string;
+    queryEmbedding?: number[];
+    diagnostics?: RagRetrievalDiagnostics;
+}
+/**
+ * Primary contract for the Retrieval Augmentor implementation.
+ */
+export interface IRetrievalAugmentor {
+    readonly augmenterId: string;
+    initialize(config: RetrievalAugmentorServiceConfig, embeddingManager: IEmbeddingManager, vectorStoreManager: IVectorStoreManager): Promise<void>;
+    ingestDocuments(documents: RagDocumentInput | RagDocumentInput[], options?: RagIngestionOptions): Promise<RagIngestionResult>;
+    retrieveContext(queryText: string, options?: RagRetrievalOptions): Promise<RagRetrievalResult>;
+    deleteDocuments(documentIds: string[], dataSourceId?: string, options?: {
+        ignoreNotFound?: boolean;
+    }): Promise<{
+        successCount: number;
+        failureCount: number;
+        errors?: Array<{
+            documentId: string;
+            message: string;
+            details?: any;
+        }>;
+    }>;
+    updateDocuments(documents: RagDocumentInput | RagDocumentInput[], options?: RagIngestionOptions): Promise<RagIngestionResult>;
+    checkHealth(): Promise<{
+        isHealthy: boolean;
+        details?: Record<string, unknown>;
+    }>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=IRetrievalAugmentor.d.ts.map

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

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

package/dist/rag/IRetrievalAugmentor.js

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Defines the contracts and shared types for the Retrieval Augmented Generation (RAG)
+ * pipeline inside AgentOS.  The RetrievalAugmentor coordinates between embedding managers, vector
+ * store managers, and higher level orchestration (GMI, personas) to ingest knowledge, retrieve
+ * relevant context, and manage document lifecycles.
+ *
+ * @module backend/agentos/rag/IRetrievalAugmentor
+ */
+/**
+ * Logical buckets that the RAG system can target.  These allow integrators to map different
+ * document types or knowledge sources to distinct vector store data sources and policies.
+ */
+export var RagMemoryCategory;
+(function (RagMemoryCategory) {
+    RagMemoryCategory["PERSONAL_LLM_EXPERIENCE"] = "personal_llm_experience";
+    RagMemoryCategory["USER_EXPLICIT_MEMORY"] = "user_explicit_memory";
+    RagMemoryCategory["SHARED_KNOWLEDGE_BASE"] = "shared_knowledge_base";
+    RagMemoryCategory["EPISODIC_CONTEXT"] = "episodic_context";
+    RagMemoryCategory["GOAL_ORIENTED_MEMORY"] = "goal_oriented_memory";
+})(RagMemoryCategory || (RagMemoryCategory = {}));
+//# sourceMappingURL=IRetrievalAugmentor.js.map

package/dist/rag/IRetrievalAugmentor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IRetrievalAugmentor.js","sourceRoot":"","sources":["../../src/rag/IRetrievalAugmentor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH;;;GAGG;AACH,MAAM,CAAN,IAAY,iBAMX;AAND,WAAY,iBAAiB;IAC3B,wEAAmD,CAAA;IACnD,kEAA6C,CAAA;IAC7C,oEAA+C,CAAA;IAC/C,0DAAqC,CAAA;IACrC,kEAA6C,CAAA;AAC/C,CAAC,EANW,iBAAiB,KAAjB,iBAAiB,QAM5B"}