@massa-ai/core 1.2.1

package/dist/data/symbol/symbol-repository-pg.js

@@ -0,0 +1,81 @@
+/**
+ * Symbol Repository - PostgreSQL Implementation (N31 facade).
+ * Singleton + 1-line delegates to per-domain modules. Barrel re-exports keep
+ * import paths unchanged. See M14 delegate pattern.
+ */
+import { logger } from "@massa-ai/shared";
+export { definitionIdentityColumns, generationDefinitionIdentityColumns, referenceSourceSpan } from "./symbol-repo-identity.js";
+export { mapWs, mapFile, mapDef, mapRef, mapImp } from "./symbol-repo-mappers.js";
+import { copyFileGeneration, writeFileGeneration, deleteFileGeneration, markFileStaleGeneration, updateCentralityGeneration, writeFileSymbols, } from "./symbol-repo-generation.js";
+import * as queries from "./symbol-repo-queries.js";
+import * as graph from "./symbol-repo-graph.js";
+export class SymbolRepositoryPg {
+    static instance = null;
+    constructor() { logger.info("SymbolRepositoryPg initialized (PostgreSQL)"); }
+    static getInstance() {
+        if (!SymbolRepositoryPg.instance)
+            SymbolRepositoryPg.instance = new SymbolRepositoryPg();
+        return SymbolRepositoryPg.instance;
+    }
+    // Workspace
+    async upsertWorkspace(ws) { return queries.upsertWorkspace(ws); }
+    async updateWorkspaceStatus(projectId, status, opts) { return queries.updateWorkspaceStatus(projectId, status, opts); }
+    async getWorkspace(projectId) { return queries.getWorkspace(projectId); }
+    async listWorkspaces() { return queries.listWorkspaces(); }
+    async deleteWorkspace(projectId) { return queries.deleteWorkspace(projectId); }
+    // File
+    async upsertFile(file) { return queries.upsertFile(file); }
+    async getFile(projectId, relativePath) { return queries.getFile(projectId, relativePath); }
+    // Definition
+    async upsertDefinition(def) { return queries.upsertDefinition(def); }
+    async deleteDefinitionsByFile(projectId, filePath) { return queries.deleteDefinitionsByFile(projectId, filePath); }
+    async searchDefinitions(projectId, query, kinds, exportedOnly, limit = 20, filePath) { return queries.searchDefinitions(projectId, query, kinds, exportedOnly, limit, filePath); }
+    async countDefinitions(projectId, query, kinds, exportedOnly, filePath) { return queries.countDefinitions(projectId, query, kinds, exportedOnly, filePath); }
+    async getDefinition(projectId, fqn) { return queries.getDefinition(projectId, fqn); }
+    // Reference
+    async insertReference(ref) { return queries.insertReference(ref); }
+    async deleteReferencesByFile(projectId, filePath) { return queries.deleteReferencesByFile(projectId, filePath); }
+    async getReferences(projectId, symbolName, limit = 50) { return queries.getReferences(projectId, symbolName, limit); }
+    // Import
+    async insertImport(imp) { return queries.insertImport(imp); }
+    async deleteImportsByFile(projectId, filePath) { return queries.deleteImportsByFile(projectId, filePath); }
+    async getImportsFrom(projectId, filePath) { return queries.getImportsFrom(projectId, filePath); }
+    // Centrality
+    async upsertCentrality(entry) { return queries.upsertCentrality(entry); }
+    async getTopCentralFiles(projectId, limit = 20) { return queries.getTopCentralFiles(projectId, limit); }
+    async getCentrality(projectId) { return queries.getCentrality(projectId); }
+    // Batch
+    async batchUpsertDefinitions(defs) { return queries.batchUpsertDefinitions(defs); }
+    async batchInsertReferences(refs) { return queries.batchInsertReferences(refs); }
+    async batchInsertImports(imports) { return queries.batchInsertImports(imports); }
+    // Generation-scoped writes
+    async copyFileGeneration(lease, sourceGenerationId, filePath) { return copyFileGeneration(lease, sourceGenerationId, filePath); }
+    async writeFileGeneration(input) { return writeFileGeneration(input); }
+    async deleteFileGeneration(lease, filePath) { return deleteFileGeneration(lease, filePath); }
+    async markFileStaleGeneration(lease, filePath, input) { return markFileStaleGeneration(lease, filePath, input); }
+    async updateCentralityGeneration(lease, entries) { return updateCentralityGeneration(lease, entries); }
+    async writeFileSymbols(projectId, filePath, defs, refs, imports) { return writeFileSymbols(projectId, filePath, defs, refs, imports); }
+    // Graph queries
+    async getProjectMapAggregates(projectId, recentLimit = 10) { return graph.getProjectMapAggregates(projectId, recentLimit); }
+    async getProjectMapSnapshot(projectId, opts = {}) { return graph.getProjectMapSnapshot(projectId, opts); }
+    async getActiveGraphSnapshot(projectId) { return graph.getActiveGraphSnapshot(projectId); }
+    async resolveDefinitionFqn(projectId, fqn) { return graph.resolveDefinitionFqn(projectId, fqn); }
+    async allFiles(projectId) { return graph.allFiles(projectId); }
+    async allImportEdges(projectId) { return graph.allImportEdges(projectId); }
+    async runBfsCteImpact(projectId, changedFiles, opts) { return graph.runBfsCteImpact(projectId, changedFiles, opts); }
+    async findImporters(projectId, filePath) { return graph.findImporters(projectId, filePath); }
+    async findReferencesByFqn(projectId, fqn) { return graph.findReferencesByFqn(projectId, fqn); }
+    async findReferencesByName(projectId, symbolName) { return graph.findReferencesByName(projectId, symbolName); }
+    async findEdges(projectId, opts = {}) { return graph.findEdges(projectId, opts); }
+    async countEdgesByKind(projectId) { return graph.countEdgesByKind(projectId); }
+    async updateCentrality(projectId, scores) { return graph.updateCentrality(projectId, scores); }
+    // Query helpers + composite
+    async clearProject(projectId) { return queries.clearProject(projectId); }
+    async getActiveGenerationScope(projectId) { return queries.getActiveGenerationScope(projectId); }
+    async findDefinitionsByName(projectId, name) { return queries.findDefinitionsByName(projectId, name); }
+    async findDefinitionByFqn(projectId, fqn) { return queries.findDefinitionByFqn(projectId, fqn); }
+    async findDependencies(projectId, fromFile) { return queries.findDependencies(projectId, fromFile); }
+    async listDefinitions(projectId, opts = {}) { return queries.listDefinitions(projectId, opts); }
+    async listAllDefinitions(projectId, opts = {}) { return queries.listAllDefinitions(projectId, opts); }
+}
+//# sourceMappingURL=symbol-repository-pg.js.map

package/dist/data/symbol/symbol-repository-pg.js.map

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

package/dist/data/vector/base-vector-store.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Base Vector Store
+ *
+ * Abstract base class for vector store implementations.
+ * Provides shared functionality and fixes critical issues:
+ * - Thread-safe lazy loading of embedding provider (fixes race condition)
+ * - Common similarity/distance conversion utilities
+ * - Embedding dimension discovery
+ *
+ * Implementations: PostgresVectorStore, PostgresVectorStore
+ */
+import { IVectorStore, SearchResult, VectorDocument, VectorStoreStats, ProjectInfo } from '@massa-ai/shared';
+import { EmbeddingProvider } from '../../services/embeddings/index.js';
+/**
+ * Base class for all vector store implementations
+ *
+ * Subclasses must implement all abstract methods from IVectorStore.
+ * This base class provides:
+ * 1. Thread-safe embedding provider initialization
+ * 2. Shared similarity calculation utilities
+ * 3. Dimension discovery for dynamic schema creation
+ */
+export declare abstract class BaseVectorStore implements IVectorStore {
+    /**
+     * Shared promise for embedding provider initialization
+     *
+     * CRITICAL: This fixes a race condition where concurrent calls to
+     * getEmbeddingProvider() could create multiple provider instances.
+     * By storing a single promise, all concurrent callers wait for the
+     * same initialization to complete.
+     *
+     * Example race condition (without this fix):
+     * - Thread A calls getEmbeddingProvider() → starts initialization
+     * - Thread B calls getEmbeddingProvider() → starts ANOTHER initialization
+     * - Result: Two provider instances, doubled memory, potential conflicts
+     *
+     * With this fix:
+     * - Thread A calls getEmbeddingProvider() → creates promise, starts init
+     * - Thread B calls getEmbeddingProvider() → returns same promise
+     * - Result: Single provider instance shared by all callers
+     */
+    private embeddingProviderPromise;
+    /**
+     * Get or create the embedding provider (thread-safe lazy loading)
+     *
+     * This method ensures that only one embedding provider is created,
+     * even when called concurrently from multiple contexts.
+     *
+     * @returns Promise that resolves to the shared embedding provider
+     */
+    protected getEmbeddingProvider(): Promise<EmbeddingProvider>;
+    /**
+     * Get embedding dimensions from the current provider
+     *
+     * Used by PostgreSQL implementation to create schema with correct vector size.
+     * Different embedding models have different dimensions:
+     * - text-embedding-ada-002: 1536
+     * - text-embedding-3-small: 1536
+     * - text-embedding-3-large: 3072
+     * - nomic-embed-text: 768
+     * - all-minilm-l6-v2: 384
+     *
+     * @returns Promise that resolves to the embedding dimension
+     */
+    protected getEmbeddingDimensions(): Promise<number>;
+    /**
+     * Calculate cosine similarity between two vectors
+     *
+     * Cosine similarity ranges from -1 to 1:
+     * - 1: Vectors point in same direction (identical semantic meaning)
+     * - 0: Vectors are orthogonal (no semantic relationship)
+     * - -1: Vectors point in opposite directions (opposite meaning)
+     *
+     * Formula: similarity = (a · b) / (||a|| * ||b||)
+     *
+     * @param a First vector
+     * @param b Second vector
+     * @returns Similarity score (0-1 in practice, as embeddings are typically positive)
+     */
+    protected cosineSimilarity(a: number[], b: number[]): number;
+    /**
+     * Convert pgvector cosine distance to similarity score
+     *
+     * pgvector's <=> operator returns cosine distance, not similarity.
+     * Distance = 1 - similarity, so we need to convert:
+     * - distance 0 → similarity 1 (identical)
+     * - distance 1 → similarity 0 (orthogonal)
+     * - distance 2 → similarity -1 (opposite)
+     *
+     * We clamp to [0, 1] for consistency with PostgreSQL implementation.
+     *
+     * @param distance Cosine distance from pgvector (0-2)
+     * @returns Similarity score (0-1)
+     */
+    protected distanceToSimilarity(distance: number): number;
+    /**
+     * Convert similarity score to cosine distance
+     *
+     * Inverse of distanceToSimilarity for when you need to go the other way.
+     *
+     * @param similarity Similarity score (0-1)
+     * @returns Cosine distance (0-2, but typically 0-1)
+     */
+    protected similarityToDistance(similarity: number): number;
+    /**
+     * Generate embedding for text content
+     *
+     * Convenience method that wraps provider.embedQuery() with error handling.
+     *
+     * @param content Text to embed
+     * @returns Promise that resolves to embedding vector
+     */
+    protected embedContent(content: string): Promise<number[]>;
+    /**
+     * Generate embeddings for multiple texts (batched)
+     *
+     * More efficient than calling embedQuery() in a loop.
+     * Uses the provider's batch API if available.
+     *
+     * @param contents Array of texts to embed
+     * @returns Promise that resolves to array of embedding vectors
+     */
+    protected embedBatch(contents: string[]): Promise<number[][]>;
+    abstract addDocument(id: string, content: string, metadata?: Record<string, unknown>): Promise<void>;
+    abstract addDocuments(documents: VectorDocument[]): Promise<void>;
+    abstract search(query: string, limit?: number, projectId?: string): Promise<SearchResult[]>;
+    abstract searchByEmbedding(embedding: number[], limit?: number, projectId?: string): Promise<SearchResult[]>;
+    abstract delete(id: string): Promise<boolean>;
+    abstract deleteByProject(projectId: string): Promise<number>;
+    abstract update(id: string, content: string, metadata?: Record<string, unknown>): Promise<void>;
+    abstract getCollection(name: string): Promise<any>;
+    abstract getStats(projectId?: string): Promise<VectorStoreStats>;
+    abstract listProjects(): Promise<ProjectInfo[]>;
+    abstract healthCheck(): Promise<boolean>;
+    abstract close(): Promise<void>;
+}
+//# sourceMappingURL=base-vector-store.d.ts.map

package/dist/data/vector/base-vector-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-vector-store.d.ts","sourceRoot":"","sources":["../../../src/data/vector/base-vector-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC7G,OAAO,EAA2B,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAGhG;;;;;;;;GAQG;AACH,8BAAsB,eAAgB,YAAW,YAAY;IAC3D;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,wBAAwB,CAA2C;IAE3E;;;;;;;OAOG;IACH,SAAS,CAAC,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAO5D;;;;;;;;;;;;OAYG;cACa,sBAAsB,IAAI,OAAO,CAAC,MAAM,CAAC;IAKzD;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM;IAe5D;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIxD;;;;;;;OAOG;IACH,SAAS,CAAC,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAI1D;;;;;;;OAOG;cACa,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAUhE;;;;;;;;OAQG;cACa,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAYnE,QAAQ,CAAC,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IACpG,QAAQ,CAAC,YAAY,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IACjE,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAC3F,QAAQ,CAAC,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAC5G,QAAQ,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAC7C,QAAQ,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/F,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAClD,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAChE,QAAQ,CAAC,YAAY,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IACxC,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAChC"}

package/dist/data/vector/base-vector-store.js

@@ -0,0 +1,166 @@
+/**
+ * Base Vector Store
+ *
+ * Abstract base class for vector store implementations.
+ * Provides shared functionality and fixes critical issues:
+ * - Thread-safe lazy loading of embedding provider (fixes race condition)
+ * - Common similarity/distance conversion utilities
+ * - Embedding dimension discovery
+ *
+ * Implementations: PostgresVectorStore, PostgresVectorStore
+ */
+import { createEmbeddingProvider } from '../../services/embeddings/index.js';
+import { logger } from '@massa-ai/shared';
+/**
+ * Base class for all vector store implementations
+ *
+ * Subclasses must implement all abstract methods from IVectorStore.
+ * This base class provides:
+ * 1. Thread-safe embedding provider initialization
+ * 2. Shared similarity calculation utilities
+ * 3. Dimension discovery for dynamic schema creation
+ */
+export class BaseVectorStore {
+    /**
+     * Shared promise for embedding provider initialization
+     *
+     * CRITICAL: This fixes a race condition where concurrent calls to
+     * getEmbeddingProvider() could create multiple provider instances.
+     * By storing a single promise, all concurrent callers wait for the
+     * same initialization to complete.
+     *
+     * Example race condition (without this fix):
+     * - Thread A calls getEmbeddingProvider() → starts initialization
+     * - Thread B calls getEmbeddingProvider() → starts ANOTHER initialization
+     * - Result: Two provider instances, doubled memory, potential conflicts
+     *
+     * With this fix:
+     * - Thread A calls getEmbeddingProvider() → creates promise, starts init
+     * - Thread B calls getEmbeddingProvider() → returns same promise
+     * - Result: Single provider instance shared by all callers
+     */
+    embeddingProviderPromise = null;
+    /**
+     * Get or create the embedding provider (thread-safe lazy loading)
+     *
+     * This method ensures that only one embedding provider is created,
+     * even when called concurrently from multiple contexts.
+     *
+     * @returns Promise that resolves to the shared embedding provider
+     */
+    getEmbeddingProvider() {
+        if (!this.embeddingProviderPromise) {
+            this.embeddingProviderPromise = createEmbeddingProvider({ cache: true });
+        }
+        return this.embeddingProviderPromise;
+    }
+    /**
+     * Get embedding dimensions from the current provider
+     *
+     * Used by PostgreSQL implementation to create schema with correct vector size.
+     * Different embedding models have different dimensions:
+     * - text-embedding-ada-002: 1536
+     * - text-embedding-3-small: 1536
+     * - text-embedding-3-large: 3072
+     * - nomic-embed-text: 768
+     * - all-minilm-l6-v2: 384
+     *
+     * @returns Promise that resolves to the embedding dimension
+     */
+    async getEmbeddingDimensions() {
+        const provider = await this.getEmbeddingProvider();
+        return provider.dimensions;
+    }
+    /**
+     * Calculate cosine similarity between two vectors
+     *
+     * Cosine similarity ranges from -1 to 1:
+     * - 1: Vectors point in same direction (identical semantic meaning)
+     * - 0: Vectors are orthogonal (no semantic relationship)
+     * - -1: Vectors point in opposite directions (opposite meaning)
+     *
+     * Formula: similarity = (a · b) / (||a|| * ||b||)
+     *
+     * @param a First vector
+     * @param b Second vector
+     * @returns Similarity score (0-1 in practice, as embeddings are typically positive)
+     */
+    cosineSimilarity(a, b) {
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dotProduct += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+        return denominator === 0 ? 0 : dotProduct / denominator;
+    }
+    /**
+     * Convert pgvector cosine distance to similarity score
+     *
+     * pgvector's <=> operator returns cosine distance, not similarity.
+     * Distance = 1 - similarity, so we need to convert:
+     * - distance 0 → similarity 1 (identical)
+     * - distance 1 → similarity 0 (orthogonal)
+     * - distance 2 → similarity -1 (opposite)
+     *
+     * We clamp to [0, 1] for consistency with PostgreSQL implementation.
+     *
+     * @param distance Cosine distance from pgvector (0-2)
+     * @returns Similarity score (0-1)
+     */
+    distanceToSimilarity(distance) {
+        return Math.max(0, 1 - distance);
+    }
+    /**
+     * Convert similarity score to cosine distance
+     *
+     * Inverse of distanceToSimilarity for when you need to go the other way.
+     *
+     * @param similarity Similarity score (0-1)
+     * @returns Cosine distance (0-2, but typically 0-1)
+     */
+    similarityToDistance(similarity) {
+        return 1 - similarity;
+    }
+    /**
+     * Generate embedding for text content
+     *
+     * Convenience method that wraps provider.embedQuery() with error handling.
+     *
+     * @param content Text to embed
+     * @returns Promise that resolves to embedding vector
+     */
+    async embedContent(content) {
+        try {
+            const provider = await this.getEmbeddingProvider();
+            return await provider.embedQuery(content);
+        }
+        catch (error) {
+            logger.error('Failed to generate embedding', error, { content: content.slice(0, 100) });
+            throw error;
+        }
+    }
+    /**
+     * Generate embeddings for multiple texts (batched)
+     *
+     * More efficient than calling embedQuery() in a loop.
+     * Uses the provider's batch API if available.
+     *
+     * @param contents Array of texts to embed
+     * @returns Promise that resolves to array of embedding vectors
+     */
+    async embedBatch(contents) {
+        try {
+            const provider = await this.getEmbeddingProvider();
+            return await provider.embedBatch(contents);
+        }
+        catch (error) {
+            logger.error('Failed to generate batch embeddings', error, { count: contents.length });
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=base-vector-store.js.map

package/dist/data/vector/base-vector-store.js.map

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

package/dist/data/vector/hybrid-search.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Hybrid Search
+ *
+ * Combines vector search (semantic) with keyword search (lexical)
+ * using Reciprocal Rank Fusion (RRF) for reranking
+ */
+import { IHybridSearch } from '@massa-ai/shared';
+import { SearchResult, RetrievalOptions } from '@massa-ai/shared';
+/**
+ * Hybrid Search implementation
+ */
+export declare class HybridSearch implements IHybridSearch {
+    private vectorStore;
+    private keywordSearch;
+    constructor();
+    /**
+     * Search using both vector and keyword search
+     */
+    search(query: string, options: RetrievalOptions): Promise<SearchResult[]>;
+    /**
+     * Rerank results using Reciprocal Rank Fusion (RRF)
+     *
+     * RRF formula: score(d) = Σ 1 / (k + rank(d))
+     * where k is a constant (typically 60) and rank is the position in each list
+     */
+    rerank(resultSets: SearchResult[][]): SearchResult[];
+    /**
+     * Normalize RRF scores to 0-1 range using the actual max in the result set.
+     *
+     * The theoretical max per result per list is 1/(k+1). With N lists the
+     * absolute ceiling is N/(k+1). But actual maxima vary, so we use the
+     * observed max to give the best-ranked result a score of 1 and scale
+     * everything else relative to it. Falls back to the theoretical ceiling
+     * when all scores are equal (e.g. single-result sets).
+     */
+    private normalizeRRFScores;
+    /**
+     * Calculate average score
+     */
+    private calculateAvgScore;
+    /**
+     * Search with custom weights for vector vs keyword
+     */
+    searchWeighted(query: string, options: RetrievalOptions, weights?: {
+        vector: number;
+        keyword: number;
+    }): Promise<SearchResult[]>;
+    /**
+     * Search with boost for specific sources
+     */
+    searchWithBoost(query: string, options: RetrievalOptions, boosts?: {
+        recency?: number;
+        popularity?: number;
+    }): Promise<SearchResult[]>;
+    /**
+     * Diversify results to reduce redundancy
+     */
+    diversifyResults(results: SearchResult[], maxSimilarityThreshold?: number): SearchResult[];
+    /**
+     * Calculate simple content similarity (Jaccard similarity of words)
+     */
+    private calculateContentSimilarity;
+}
+//# sourceMappingURL=hybrid-search.d.ts.map

package/dist/data/vector/hybrid-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-search.d.ts","sourceRoot":"","sources":["../../../src/data/vector/hybrid-search.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAYlE;;GAEG;AACH,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,aAAa,CAAkB;;IASvC;;OAEG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA0C/E;;;;;OAKG;IACH,MAAM,CAAC,UAAU,EAAE,YAAY,EAAE,EAAE,GAAG,YAAY,EAAE;IA6CpD;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;OAEG;IACG,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAkC,GAC3E,OAAO,CAAC,YAAY,EAAE,CAAC;IAmD1B;;OAEG;IACG,eAAe,CACnB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,gBAAgB,EACzB,MAAM,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,GACrD,OAAO,CAAC,YAAY,EAAE,CAAC;IA8B1B;;OAEG;IACH,gBAAgB,CACd,OAAO,EAAE,YAAY,EAAE,EACvB,sBAAsB,GAAE,MAAa,GACpC,YAAY,EAAE;IA2BjB;;OAEG;IACH,OAAO,CAAC,0BAA0B;CASnC"}