@ariaflowagents/rag 0.7.0 → 0.9.0

package/dist/retrievers/VectorRetriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VectorRetriever.js","sourceRoot":"","sources":["../../src/retrievers/VectorRetriever.ts"],"names":[],"mappings":"AAmBA;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IACT,WAAW,CAAc;IACzB,QAAQ,CAAW;IACnB,SAAS,CAAS;IAClB,WAAW,CAAS;IAErC,YAAY,OAA+B;QACzC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,KAAa,EACb,OAA0B;QAE1B,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC;QAE/C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE;YAC3D,WAAW;YACX,IAAI;YACJ,MAAM,EAAE,OAAO,EAAE,MAAM;YACvB,gBAAgB,EAAE,IAAI;SACvB,CAAC,CAAC;QAEH,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACvB,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,QAAQ,IAAI,EAAE;YACtB,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,QAAQ,EAAE,IAAI,CAAC,SAAS;SACzB,CAAC,CAAC,CAAC;IACN,CAAC;CACF"}

package/dist/retrievers/index.d.ts

@@ -0,0 +1,5 @@
+export { VectorRetriever } from './VectorRetriever.js';
+export type { VectorRetrieverOptions } from './VectorRetriever.js';
+export { HybridRetriever } from './HybridRetriever.js';
+export type { HybridRetrieverSource, HybridRetrieverOptions } from './HybridRetriever.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/retrievers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrievers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/retrievers/index.js

@@ -0,0 +1,3 @@
+export { VectorRetriever } from './VectorRetriever.js';
+export { HybridRetriever } from './HybridRetriever.js';
+//# sourceMappingURL=index.js.map

package/dist/retrievers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrievers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/tools/createVectorRetrievalTool.d.ts

@@ -0,0 +1,69 @@
+import type { Retriever, VectorFilter } from '../types.js';
+/**
+ * Description of a filterable metadata field, provided to the LLM
+ * so it knows which fields exist and what values they accept.
+ */
+export interface FilterableFieldDescriptor {
+    /** The metadata field name as stored in the vector index. */
+    field: string;
+    /** Human-readable description of what this field represents. */
+    description: string;
+    /** The value type. Helps the LLM construct valid filter values. */
+    type: 'string' | 'number' | 'boolean' | 'string[]';
+    /** Example values, if useful for guiding the LLM. */
+    examples?: (string | number | boolean)[];
+}
+export interface VectorRetrievalToolOptions {
+    /** The retriever to use (VectorRetriever, HybridRetriever, RagPipeline, etc.). */
+    retriever: Retriever;
+    /** Default number of results. Default: 10. */
+    topK?: number;
+    /** Custom tool description. */
+    description?: string;
+    /**
+     * Enable agentic metadata filtering. When true, the tool schema includes
+     * a `filter` parameter that allows the LLM to construct metadata filters
+     * dynamically at query time.
+     *
+     * Default: false.
+     */
+    enableAgenticFilters?: boolean;
+    /**
+     * Descriptions of filterable metadata fields. Included in the tool
+     * description so the LLM knows which fields exist.
+     *
+     * Only relevant when enableAgenticFilters is true.
+     */
+    filterableFields?: FilterableFieldDescriptor[];
+    /**
+     * A static filter applied to every query, merged with any agentic filter
+     * via $and. Use this for tenant isolation or access control.
+     */
+    staticFilter?: VectorFilter;
+}
+export interface VectorRetrievalToolOutput {
+    results: {
+        id: string;
+        text: string;
+        score?: number;
+        sourceId?: string;
+        reason?: string;
+    }[];
+}
+export type VectorRetrievalToolInput = {
+    query: string;
+    topK?: number;
+    filter?: Record<string, unknown>;
+};
+/**
+ * Creates a retrieval tool that can be added to any AriaFlow agent.
+ *
+ * The tool wraps any Retriever implementation, allowing the LLM to
+ * decide when to search for relevant knowledge. Uses the Vercel AI SDK
+ * `tool()` directly so this package has no dependency on @ariaflowagents/core.
+ */
+export declare function createVectorRetrievalTool(options: VectorRetrievalToolOptions): import("ai").Tool<{
+    query: string;
+    topK?: number | undefined;
+}, VectorRetrievalToolOutput>;
+//# sourceMappingURL=createVectorRetrievalTool.d.ts.map

package/dist/tools/createVectorRetrievalTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createVectorRetrievalTool.d.ts","sourceRoot":"","sources":["../../src/tools/createVectorRetrievalTool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;IACnD,qDAAqD;IACrD,QAAQ,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,0BAA0B;IACzC,kFAAkF;IAClF,SAAS,EAAE,SAAS,CAAC;IACrB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,yBAAyB,EAAE,CAAC;IAC/C;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,EAAE,CAAC;CACL;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B;;;8BAwF5E"}

package/dist/tools/createVectorRetrievalTool.js

@@ -0,0 +1,81 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+/**
+ * Creates a retrieval tool that can be added to any AriaFlow agent.
+ *
+ * The tool wraps any Retriever implementation, allowing the LLM to
+ * decide when to search for relevant knowledge. Uses the Vercel AI SDK
+ * `tool()` directly so this package has no dependency on @ariaflowagents/core.
+ */
+export function createVectorRetrievalTool(options) {
+    const { retriever, topK: defaultTopK = 10, enableAgenticFilters = false, filterableFields, staticFilter, } = options;
+    // Build tool description, including filterable field metadata when enabled
+    let toolDescription = options.description ??
+        'Search the knowledge base for relevant information. Use this when ' +
+            'you need to find specific facts, policies, or context to answer ' +
+            'the user\'s question accurately.';
+    if (enableAgenticFilters && filterableFields?.length) {
+        const fieldDescriptions = filterableFields
+            .map(f => {
+            let desc = `  - "${f.field}" (${f.type}): ${f.description}`;
+            if (f.examples?.length) {
+                desc += ` [examples: ${f.examples.map(e => JSON.stringify(e)).join(', ')}]`;
+            }
+            return desc;
+        })
+            .join('\n');
+        toolDescription +=
+            '\n\nYou can optionally filter results by metadata. Available filter fields:\n' +
+                fieldDescriptions +
+                '\n\nFilter syntax: { "fieldName": "value" } for equality, ' +
+                '{ "fieldName": { "$in": ["a", "b"] } } for set membership, ' +
+                '{ "fieldName": { "$gt": 5 } } for comparison.';
+    }
+    // Build zod schema -- conditionally include filter param
+    const baseParams = {
+        query: z.string().describe('The search query to find relevant information.'),
+        topK: z
+            .number()
+            .optional()
+            .describe('Number of results to return. Default: ' + defaultTopK),
+    };
+    const parameters = enableAgenticFilters
+        ? z.object({
+            ...baseParams,
+            filter: z
+                .record(z.unknown())
+                .optional()
+                .describe('Optional metadata filter to narrow results. ' +
+                'Use field names from the available filter fields.'),
+        })
+        : z.object(baseParams);
+    return tool({
+        description: toolDescription,
+        inputSchema: parameters,
+        execute: async (input) => {
+            // Merge static filter (invariant) with agentic filter (LLM-constructed)
+            const agenticFilter = input.filter;
+            let mergedFilter;
+            if (staticFilter && agenticFilter) {
+                mergedFilter = { $and: [staticFilter, agenticFilter] };
+            }
+            else {
+                mergedFilter = staticFilter ?? agenticFilter;
+            }
+            const results = await retriever.retrieve(input.query, {
+                topK: input.topK ?? defaultTopK,
+                filter: mergedFilter,
+            });
+            return {
+                results: results.map(r => ({
+                    id: r.id,
+                    text: r.text,
+                    score: r.score,
+                    sourceId: r.sourceId,
+                    reason: r.reason,
+                })),
+            };
+        },
+    });
+}
+//# sourceMappingURL=createVectorRetrievalTool.js.map

package/dist/tools/createVectorRetrievalTool.js.map

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

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+export { createVectorRetrievalTool } from './createVectorRetrievalTool.js';
+export type { VectorRetrievalToolOptions, VectorRetrievalToolOutput, VectorRetrievalToolInput, FilterableFieldDescriptor, } from './createVectorRetrievalTool.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,gCAAgC,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,2 @@
+export { createVectorRetrievalTool } from './createVectorRetrievalTool.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/types.d.ts

@@ -11,6 +11,11 @@ export interface KnowledgeSource {
     getChunks(): KnowledgeChunk[];
     dumpContent?(): string;
 }
+/**
+ * Chunker interface for the CAG pattern. Returns KnowledgeChunk[].
+ * Used by createStaticKnowledgeSource, createMarkdownChunker,
+ * createRecursiveChunker.
+ */
 export interface Chunker {
     chunk(text: string, options?: ChunkOptions): KnowledgeChunk[];
 }
@@ -37,4 +42,259 @@ export type LLMRetrieverOptions = {
     includeReasons?: boolean;
     candidateMaxChars?: number;
 };
+/**
+ * Extended chunk type with positional and token metadata.
+ * KnowledgeChunk is a subset of this (id + text + meta).
+ */
+export interface Chunk {
+    /** Unique identifier for this chunk within its source. */
+    id: string;
+    /** The chunk text content. */
+    text: string;
+    /** Arbitrary metadata (heading, section name, source path, etc.). */
+    metadata?: Record<string, unknown>;
+    /** Character offset of the chunk start in the original text. */
+    startIndex?: number;
+    /** Character offset of the chunk end in the original text. */
+    endIndex?: number;
+    /** Estimated token count for this chunk. */
+    tokens?: number;
+}
+/**
+ * A document loaded from an external source.
+ * Documents are the input to the chunking stage of the RAG pipeline.
+ */
+export interface Document {
+    /** Unique identifier for this document. */
+    id: string;
+    /** The document's text content. */
+    text: string;
+    /** Source metadata (file path, URL, content type, title, etc.). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Contract for loading documents from external sources.
+ */
+export interface DocumentLoader {
+    /**
+     * Load documents from the configured source.
+     *
+     * @returns Array of documents. A single source may produce multiple
+     *   documents (e.g., a directory loader produces one per file).
+     */
+    load(): Promise<Document[]>;
+}
+/**
+ * Contract for embedding text into dense vector representations.
+ *
+ * Implementations may wrap any embedding provider: Vercel AI SDK models,
+ * OpenAI API directly, local models (Ollama, transformers.js), or
+ * third-party services (Cohere, Voyage, Jina).
+ */
+export interface Embedder {
+    /**
+     * Embed a single text string into a dense vector.
+     */
+    embed(text: string): Promise<readonly number[]>;
+    /**
+     * Embed multiple text strings into dense vectors.
+     * Implementations SHOULD batch the underlying API calls where the
+     * provider supports it, rather than calling embed() in a loop.
+     */
+    embedMany(texts: string[]): Promise<readonly (readonly number[])[]>;
+    /**
+     * The dimensionality of the embedding vectors produced by this embedder.
+     * May be undefined if the dimension is not known until the first embed() call.
+     */
+    readonly dimension?: number;
+}
+/**
+ * A single entry to upsert into a vector index.
+ */
+export interface VectorEntry {
+    /** Unique identifier for this vector. Overwrites if exists. */
+    id: string;
+    /** Dense vector representation. */
+    vector: readonly number[];
+    /** Arbitrary key-value metadata for filtering. */
+    metadata?: Record<string, unknown>;
+    /** Original text content. Stored alongside the vector for retrieval. */
+    document?: string;
+}
+/**
+ * Result of a vector similarity query.
+ */
+export interface VectorQueryResult {
+    /** The vector entry's unique identifier. */
+    id: string;
+    /** Similarity score. Higher values indicate greater similarity. */
+    score: number;
+    /** Metadata associated with the vector entry. */
+    metadata?: Record<string, unknown>;
+    /** Original text content, if stored and requested. */
+    document?: string;
+    /** The raw vector, if includeVectors was true. */
+    vector?: readonly number[];
+}
+/**
+ * Parameters for querying a vector index.
+ */
+export interface VectorQueryParams {
+    /** The query vector to find similar entries for. */
+    queryVector: readonly number[];
+    /** Maximum number of results to return. Default: 10. */
+    topK?: number;
+    /** Metadata filter in MongoDB-style operator syntax. */
+    filter?: VectorFilter;
+    /** Whether to include the raw vectors in results. Default: false. */
+    includeVectors?: boolean;
+    /** Whether to include the stored document text. Default: true. */
+    includeDocuments?: boolean;
+}
+/**
+ * Parameters for creating a vector index.
+ */
+export interface CreateIndexParams {
+    /** Name of the index to create. */
+    indexName: string;
+    /** Dimensionality of the vectors. Must match the embedder's output. */
+    dimension: number;
+    /** Distance metric for similarity computation. Default: 'cosine'. */
+    metric?: 'cosine' | 'euclidean' | 'dotproduct';
+}
+/**
+ * Statistics about a vector index.
+ */
+export interface IndexStats {
+    /** Dimensionality of stored vectors. */
+    dimension: number;
+    /** Total number of vectors in the index. */
+    count: number;
+    /** Distance metric configured for this index. */
+    metric: 'cosine' | 'euclidean' | 'dotproduct';
+}
+/**
+ * MongoDB-style filter operators for vector metadata queries.
+ */
+export type VectorFilter = VectorFilterCondition | {
+    $and: VectorFilter[];
+} | {
+    $or: VectorFilter[];
+} | {
+    $not: VectorFilter;
+};
+export type VectorFilterCondition = Record<string, unknown | {
+    $eq?: unknown;
+} | {
+    $ne?: unknown;
+} | {
+    $gt?: number;
+} | {
+    $gte?: number;
+} | {
+    $lt?: number;
+} | {
+    $lte?: number;
+} | {
+    $in?: unknown[];
+} | {
+    $nin?: unknown[];
+} | {
+    $exists?: boolean;
+}>;
+/**
+ * Contract for persistent vector storage and similarity search.
+ *
+ * This is the primary extension point for third-party vector database
+ * integrations. Each provider implements this interface in a separate
+ * npm package (e.g., @ariaflowagents/vector-pg).
+ */
+export interface VectorStore {
+    /**
+     * Insert or update vector entries in an index.
+     * If an entry with the same ID exists, it is overwritten.
+     */
+    upsert(indexName: string, entries: VectorEntry[]): Promise<void>;
+    /**
+     * Query an index for vectors similar to the given query vector.
+     */
+    query(indexName: string, params: VectorQueryParams): Promise<VectorQueryResult[]>;
+    /**
+     * Create a new vector index with the specified configuration.
+     * Implementations SHOULD be idempotent.
+     */
+    createIndex(params: CreateIndexParams): Promise<void>;
+    /**
+     * List all index names in this vector store.
+     */
+    listIndexes(): Promise<string[]>;
+    /**
+     * Delete an index and all its vectors.
+     */
+    deleteIndex(indexName: string): Promise<void>;
+    /**
+     * Delete specific vectors from an index.
+     */
+    deleteVectors?(indexName: string, params: {
+        ids?: string[];
+        filter?: VectorFilter;
+    }): Promise<void>;
+    /**
+     * Get statistics about an index.
+     */
+    describeIndex?(indexName: string): Promise<IndexStats>;
+}
+/**
+ * A single result from a retrieval operation.
+ */
+export interface RetrievalResult {
+    /** Identifier of the retrieved chunk or document. */
+    id: string;
+    /** The retrieved text content. */
+    text: string;
+    /** Relevance score. Higher is more relevant. */
+    score?: number;
+    /** Metadata associated with the retrieved item. */
+    metadata?: Record<string, unknown>;
+    /** Identifier of the source index or knowledge source. */
+    sourceId?: string;
+    /** Human-readable reason for selection. */
+    reason?: string;
+}
+/**
+ * Options for retrieval operations.
+ */
+export interface RetrievalOptions {
+    /** Maximum number of results to return. */
+    topK?: number;
+    /** Metadata filter (for vector-backed retrievers). */
+    filter?: VectorFilter;
+    /** Optional hint or context to guide the retriever. */
+    hint?: string;
+}
+/**
+ * Contract for retrieving relevant content given a query.
+ */
+export interface Retriever {
+    /**
+     * Retrieve relevant content for a query.
+     */
+    retrieve(query: string, options?: RetrievalOptions): Promise<RetrievalResult[]>;
+}
+/**
+ * Options for reranking operations.
+ */
+export interface RerankerOptions {
+    /** Maximum number of results to return after reranking. */
+    topK?: number;
+}
+/**
+ * Contract for post-retrieval result reranking.
+ */
+export interface Reranker {
+    /**
+     * Rerank retrieval results by relevance to the query.
+     */
+    rerank(query: string, results: RetrievalResult[], options?: RerankerOptions): Promise<RetrievalResult[]>;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAExC,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,IAAI,cAAc,EAAE,CAAC;IAC9B,WAAW,CAAC,IAAI,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,cAAc,EAAE,CAAC;CAC/D;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CACN,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,eAAe,EAAE,EAC1B,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GACzC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAC5B;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/vectorStores/InMemoryVectorStore.d.ts

@@ -0,0 +1,21 @@
+import type { VectorStore, VectorEntry, VectorQueryParams, VectorQueryResult, CreateIndexParams, IndexStats, VectorFilter } from '../types.js';
+/**
+ * In-memory vector store for development and testing.
+ * Uses brute-force similarity search (O(n) per query).
+ * Not suitable for production workloads.
+ */
+export declare class InMemoryVectorStore implements VectorStore {
+    private indexes;
+    createIndex(params: CreateIndexParams): Promise<void>;
+    upsert(indexName: string, entries: VectorEntry[]): Promise<void>;
+    query(indexName: string, params: VectorQueryParams): Promise<VectorQueryResult[]>;
+    listIndexes(): Promise<string[]>;
+    deleteIndex(indexName: string): Promise<void>;
+    deleteVectors(indexName: string, params: {
+        ids?: string[];
+        filter?: VectorFilter;
+    }): Promise<void>;
+    describeIndex(indexName: string): Promise<IndexStats>;
+    private getIndex;
+}
+//# sourceMappingURL=InMemoryVectorStore.d.ts.map

package/dist/vectorStores/InMemoryVectorStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryVectorStore.d.ts","sourceRoot":"","sources":["../../src/vectorStores/InMemoryVectorStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,YAAY,EACb,MAAM,aAAa,CAAC;AAQrB;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,OAAO,CAAgC;IAEzC,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IASrD,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAahE,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA2BzB,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIhC,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,aAAa,CACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,YAAY,CAAA;KAAE,GAChD,OAAO,CAAC,IAAI,CAAC;IAgBV,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAS3D,OAAO,CAAC,QAAQ;CAKjB"}

package/dist/vectorStores/InMemoryVectorStore.js

@@ -0,0 +1,158 @@
+/**
+ * In-memory vector store for development and testing.
+ * Uses brute-force similarity search (O(n) per query).
+ * Not suitable for production workloads.
+ */
+export class InMemoryVectorStore {
+    indexes = new Map();
+    async createIndex(params) {
+        if (this.indexes.has(params.indexName))
+            return;
+        this.indexes.set(params.indexName, {
+            dimension: params.dimension,
+            metric: params.metric ?? 'cosine',
+            entries: new Map(),
+        });
+    }
+    async upsert(indexName, entries) {
+        const index = this.getIndex(indexName);
+        for (const entry of entries) {
+            if (entry.vector.length !== index.dimension) {
+                throw new Error(`Vector dimension mismatch: expected ${index.dimension}, ` +
+                    `got ${entry.vector.length} for entry "${entry.id}"`);
+            }
+            index.entries.set(entry.id, { ...entry });
+        }
+    }
+    async query(indexName, params) {
+        const index = this.getIndex(indexName);
+        const topK = params.topK ?? 10;
+        const scored = [];
+        for (const [id, entry] of index.entries) {
+            if (params.filter && !matchesFilter(entry.metadata ?? {}, params.filter)) {
+                continue;
+            }
+            const score = computeSimilarity(params.queryVector, entry.vector, index.metric);
+            scored.push({
+                id,
+                score,
+                metadata: entry.metadata,
+                document: params.includeDocuments !== false ? entry.document : undefined,
+                vector: params.includeVectors ? [...entry.vector] : undefined,
+            });
+        }
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, topK);
+    }
+    async listIndexes() {
+        return Array.from(this.indexes.keys());
+    }
+    async deleteIndex(indexName) {
+        this.indexes.delete(indexName);
+    }
+    async deleteVectors(indexName, params) {
+        const index = this.getIndex(indexName);
+        if (params.ids) {
+            for (const id of params.ids) {
+                index.entries.delete(id);
+            }
+        }
+        if (params.filter) {
+            for (const [id, entry] of index.entries) {
+                if (matchesFilter(entry.metadata ?? {}, params.filter)) {
+                    index.entries.delete(id);
+                }
+            }
+        }
+    }
+    async describeIndex(indexName) {
+        const index = this.getIndex(indexName);
+        return {
+            dimension: index.dimension,
+            count: index.entries.size,
+            metric: index.metric,
+        };
+    }
+    getIndex(name) {
+        const index = this.indexes.get(name);
+        if (!index)
+            throw new Error(`Index "${name}" does not exist.`);
+        return index;
+    }
+}
+// -- Similarity computation -------------------------------------------------
+function computeSimilarity(a, b, metric) {
+    let dotProduct = 0;
+    let magnitudeA = 0;
+    let magnitudeB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        magnitudeA += a[i] * a[i];
+        magnitudeB += b[i] * b[i];
+    }
+    if (metric === 'dotproduct')
+        return dotProduct;
+    if (metric === 'euclidean') {
+        let sumSqDiff = 0;
+        for (let i = 0; i < a.length; i++) {
+            const diff = a[i] - b[i];
+            sumSqDiff += diff * diff;
+        }
+        return 1 / (1 + Math.sqrt(sumSqDiff));
+    }
+    // cosine
+    const magA = Math.sqrt(magnitudeA);
+    const magB = Math.sqrt(magnitudeB);
+    if (magA === 0 || magB === 0)
+        return 0;
+    return dotProduct / (magA * magB);
+}
+// -- Filter matching --------------------------------------------------------
+function matchesFilter(metadata, filter) {
+    if ('$and' in filter) {
+        return filter.$and.every(f => matchesFilter(metadata, f));
+    }
+    if ('$or' in filter) {
+        return filter.$or.some(f => matchesFilter(metadata, f));
+    }
+    if ('$not' in filter) {
+        return !matchesFilter(metadata, filter.$not);
+    }
+    for (const [field, condition] of Object.entries(filter)) {
+        const value = metadata[field];
+        if (condition === null || condition === undefined) {
+            if (value !== condition)
+                return false;
+        }
+        else if (typeof condition === 'object' && !Array.isArray(condition)) {
+            const ops = condition;
+            if ('$eq' in ops && value !== ops.$eq)
+                return false;
+            if ('$ne' in ops && value === ops.$ne)
+                return false;
+            if ('$gt' in ops && (typeof value !== 'number' || value <= ops.$gt))
+                return false;
+            if ('$gte' in ops && (typeof value !== 'number' || value < ops.$gte))
+                return false;
+            if ('$lt' in ops && (typeof value !== 'number' || value >= ops.$lt))
+                return false;
+            if ('$lte' in ops && (typeof value !== 'number' || value > ops.$lte))
+                return false;
+            if ('$in' in ops && !ops.$in.includes(value))
+                return false;
+            if ('$nin' in ops && ops.$nin.includes(value))
+                return false;
+            if ('$exists' in ops) {
+                const exists = value !== undefined;
+                if (ops.$exists !== exists)
+                    return false;
+            }
+        }
+        else {
+            if (value !== condition)
+                return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=InMemoryVectorStore.js.map