@ductape/sdk 0.0.4-v9 → 0.0.4-v90

package/dist/warehouse/executor/joins/semantic-join.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Semantic Join Executor
+ *
+ * Performs joins based on vector similarity (semantic matching).
+ * Uses embeddings to find similar items across data sources.
+ */
+import { VectorDatabaseService } from '../../../vector/vector-database.service';
+import { IJoinClause, IJoinResult } from '../../types';
+/**
+ * Options for semantic join
+ */
+export interface ISemanticJoinOptions {
+    /** Environment */
+    env: string;
+    /** Product */
+    product: string;
+    /** Embedding function for text fields */
+    embedFn?: (text: string) => Promise<number[]>;
+}
+/**
+ * Semantic match result
+ */
+export interface ISemanticMatch {
+    /** Source row */
+    sourceRow: Record<string, any>;
+    /** Matched vector row */
+    matchedRow: Record<string, any>;
+    /** Similarity score */
+    score: number;
+}
+/**
+ * Semantic Join Executor
+ *
+ * Joins data based on vector similarity rather than exact key matches.
+ */
+export declare class SemanticJoinExecutor {
+    private readonly vectorService;
+    constructor(vectorService: VectorDatabaseService);
+    /**
+     * Execute a semantic join
+     *
+     * For each row in the left dataset:
+     * 1. Extract or compute embedding from the embed field
+     * 2. Query vector store for similar items
+     * 3. Join matching items based on similarity threshold
+     */
+    execute<T = Record<string, any>>(left: Record<string, any>[], join: IJoinClause, leftAlias: string, options: ISemanticJoinOptions): Promise<IJoinResult<T>>;
+    /**
+     * Find semantic matches for a single row
+     */
+    private findSemanticMatches;
+    /**
+     * Execute batch semantic join (more efficient for large datasets)
+     */
+    executeBatch<T = Record<string, any>>(left: Record<string, any>[], join: IJoinClause, leftAlias: string, options: ISemanticJoinOptions, batchSize?: number): Promise<IJoinResult<T>>;
+    /**
+     * Get nested value from object using dot notation
+     */
+    private getNestedValue;
+    /**
+     * Merge rows with similarity score
+     */
+    private mergeRows;
+}

package/dist/warehouse/executor/joins/semantic-join.js

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * Semantic Join Executor
+ *
+ * Performs joins based on vector similarity (semantic matching).
+ * Uses embeddings to find similar items across data sources.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SemanticJoinExecutor = void 0;
+// ==================== SEMANTIC JOIN EXECUTOR ====================
+/**
+ * Semantic Join Executor
+ *
+ * Joins data based on vector similarity rather than exact key matches.
+ */
+class SemanticJoinExecutor {
+    constructor(vectorService) {
+        this.vectorService = vectorService;
+    }
+    /**
+     * Execute a semantic join
+     *
+     * For each row in the left dataset:
+     * 1. Extract or compute embedding from the embed field
+     * 2. Query vector store for similar items
+     * 3. Join matching items based on similarity threshold
+     */
+    async execute(left, join, leftAlias, options) {
+        const startTime = Date.now();
+        const rightAlias = join.source.alias || 'vector';
+        if (!join.semantic) {
+            throw new Error('Semantic join requires semantic configuration');
+        }
+        const config = join.semantic;
+        const result = [];
+        let matchedPairs = 0;
+        // Process each left row
+        for (const leftRow of left) {
+            const matches = await this.findSemanticMatches(leftRow, join.source.tag, config, options);
+            if (matches.length > 0) {
+                for (const match of matches) {
+                    matchedPairs++;
+                    result.push(this.mergeRows(leftRow, match.matchedRow, match.score, leftAlias, rightAlias));
+                }
+            }
+            else if (join.type === 'left') {
+                // Left join - include unmatched rows
+                result.push(this.mergeRows(leftRow, null, 0, leftAlias, rightAlias));
+            }
+        }
+        return {
+            data: result,
+            stats: {
+                leftRows: left.length,
+                rightRows: matchedPairs, // Approximation
+                matchedPairs,
+                resultRows: result.length,
+                strategy: 'semantic',
+                executionTime: Date.now() - startTime,
+            },
+        };
+    }
+    /**
+     * Find semantic matches for a single row
+     */
+    async findSemanticMatches(row, vectorTag, config, options) {
+        // Extract the embed field value
+        const embedValue = this.getNestedValue(row, config.embedField);
+        if (embedValue === null || embedValue === undefined) {
+            return [];
+        }
+        // Get or compute embedding
+        let embedding;
+        if (Array.isArray(embedValue) && typeof embedValue[0] === 'number') {
+            // Already an embedding
+            embedding = embedValue;
+        }
+        else if (typeof embedValue === 'string') {
+            // Text - need to embed
+            if (!options.embedFn) {
+                throw new Error(`Semantic join field "${config.embedField}" contains text but no embedding function provided`);
+            }
+            embedding = await options.embedFn(embedValue);
+        }
+        else {
+            throw new Error(`Semantic join field "${config.embedField}" must be a vector or string`);
+        }
+        // Query vector store
+        const queryResult = await this.vectorService.query({
+            env: options.env,
+            product: options.product,
+            tag: vectorTag,
+            vector: embedding,
+            topK: config.topK || 10,
+            minScore: config.similarityThreshold || 0.7,
+            includeMetadata: true,
+            includeValues: false,
+        });
+        // Convert to semantic matches
+        return queryResult.matches.map(match => ({
+            sourceRow: row,
+            matchedRow: Object.assign({ id: match.id, score: match.score }, match.metadata),
+            score: match.score,
+        }));
+    }
+    /**
+     * Execute batch semantic join (more efficient for large datasets)
+     */
+    async executeBatch(left, join, leftAlias, options, batchSize = 100) {
+        const startTime = Date.now();
+        const rightAlias = join.source.alias || 'vector';
+        if (!join.semantic) {
+            throw new Error('Semantic join requires semantic configuration');
+        }
+        const config = join.semantic;
+        const result = [];
+        let matchedPairs = 0;
+        // Process in batches
+        for (let i = 0; i < left.length; i += batchSize) {
+            const batch = left.slice(i, i + batchSize);
+            // Get embeddings for batch
+            const embeddings = await Promise.all(batch.map(async (row) => {
+                const embedValue = this.getNestedValue(row, config.embedField);
+                if (embedValue === null || embedValue === undefined) {
+                    return null;
+                }
+                if (Array.isArray(embedValue) && typeof embedValue[0] === 'number') {
+                    return embedValue;
+                }
+                if (typeof embedValue === 'string' && options.embedFn) {
+                    return options.embedFn(embedValue);
+                }
+                return null;
+            }));
+            // Query for each embedding
+            const matchPromises = embeddings.map(async (embedding, idx) => {
+                if (!embedding) {
+                    return { row: batch[idx], matches: [] };
+                }
+                const queryResult = await this.vectorService.query({
+                    env: options.env,
+                    product: options.product,
+                    tag: join.source.tag,
+                    vector: embedding,
+                    topK: config.topK || 10,
+                    minScore: config.similarityThreshold || 0.7,
+                    includeMetadata: true,
+                    includeValues: false,
+                });
+                return {
+                    row: batch[idx],
+                    matches: queryResult.matches.map(m => ({
+                        sourceRow: batch[idx],
+                        matchedRow: Object.assign({ id: m.id, score: m.score }, m.metadata),
+                        score: m.score,
+                    })),
+                };
+            });
+            const batchResults = await Promise.all(matchPromises);
+            // Merge results
+            for (const { row, matches } of batchResults) {
+                if (matches.length > 0) {
+                    for (const match of matches) {
+                        matchedPairs++;
+                        result.push(this.mergeRows(row, match.matchedRow, match.score, leftAlias, rightAlias));
+                    }
+                }
+                else if (join.type === 'left') {
+                    result.push(this.mergeRows(row, null, 0, leftAlias, rightAlias));
+                }
+            }
+        }
+        return {
+            data: result,
+            stats: {
+                leftRows: left.length,
+                rightRows: matchedPairs,
+                matchedPairs,
+                resultRows: result.length,
+                strategy: 'semantic',
+                executionTime: Date.now() - startTime,
+            },
+        };
+    }
+    // ==================== HELPER METHODS ====================
+    /**
+     * Get nested value from object using dot notation
+     */
+    getNestedValue(obj, path) {
+        // Handle alias.field format
+        const parts = path.split('.');
+        // If first part is an alias (not in object), skip it
+        let current = obj;
+        for (const part of parts) {
+            if (current === null || current === undefined) {
+                return null;
+            }
+            if (part in current) {
+                current = current[part];
+            }
+            else if (parts.length > 1 && parts[0] !== part) {
+                // Skip alias prefix
+                continue;
+            }
+            else {
+                return null;
+            }
+        }
+        return current;
+    }
+    /**
+     * Merge rows with similarity score
+     */
+    mergeRows(left, right, score, leftAlias, rightAlias) {
+        const result = {};
+        // Add left row fields
+        for (const [key, value] of Object.entries(left)) {
+            if (!key.startsWith('_')) {
+                result[`${leftAlias}.${key}`] = value;
+                result[key] = value;
+            }
+        }
+        // Add right row fields (if matched)
+        if (right) {
+            for (const [key, value] of Object.entries(right)) {
+                if (!key.startsWith('_')) {
+                    result[`${rightAlias}.${key}`] = value;
+                    if (!(key in result)) {
+                        result[key] = value;
+                    }
+                }
+            }
+            // Add similarity score
+            result[`${rightAlias}._score`] = score;
+            result['_similarity_score'] = score;
+        }
+        return result;
+    }
+}
+exports.SemanticJoinExecutor = SemanticJoinExecutor;
+//# sourceMappingURL=semantic-join.js.map

package/dist/warehouse/executor/joins/semantic-join.js.map

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

package/dist/warehouse/executor/single-source-executor.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Single Source Executor
+ *
+ * Executes queries against a single data source by routing to the appropriate
+ * underlying service (DatabaseService, GraphService, or VectorService).
+ */
+import { DatabaseService } from '../../database/databases.service';
+import { GraphService } from '../../graph/graphs.service';
+import { VectorDatabaseService } from '../../vector/vector-database.service';
+import { IWarehouseQuery, IDataSource, IUnifiedWhereClause, ISourceStats } from '../types';
+import { DataSourceRegistry } from '../registry';
+/**
+ * Options for single-source execution
+ */
+export interface ISingleSourceOptions {
+    /** Environment override */
+    env?: string;
+    /** Product override */
+    product?: string;
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Result from single-source execution
+ */
+export interface ISingleSourceResult<T = Record<string, any>> {
+    /** Result data */
+    data: T[];
+    /** Row count */
+    count?: number;
+    /** Affected rows (for writes) */
+    affectedRows?: number;
+    /** Source statistics */
+    stats: ISourceStats;
+}
+/**
+ * Single Source Executor
+ *
+ * Routes warehouse queries to the appropriate underlying service and
+ * normalizes the results.
+ */
+export declare class SingleSourceExecutor {
+    private readonly registry;
+    private readonly databaseService;
+    private readonly graphService;
+    private readonly vectorService;
+    constructor(registry: DataSourceRegistry, databaseService: DatabaseService, graphService: GraphService, vectorService: VectorDatabaseService);
+    /**
+     * Execute a query against a single data source
+     */
+    execute<T = Record<string, any>>(query: IWarehouseQuery, source: IDataSource, options?: ISingleSourceOptions): Promise<ISingleSourceResult<T>>;
+    /**
+     * Execute a select query and return just the data
+     */
+    select<T = Record<string, any>>(source: IDataSource, options: {
+        fields?: string[];
+        where?: IUnifiedWhereClause;
+        orderBy?: {
+            field: string;
+            order: 'ASC' | 'DESC';
+        }[];
+        limit?: number;
+        offset?: number;
+        env?: string;
+        product?: string;
+    }): Promise<T[]>;
+    /**
+     * Execute query against a database
+     */
+    private executeDatabase;
+    /**
+     * Execute database SELECT
+     */
+    private executeDatabaseSelect;
+    /**
+     * Execute database INSERT
+     */
+    private executeDatabaseInsert;
+    /**
+     * Execute database UPDATE
+     */
+    private executeDatabaseUpdate;
+    /**
+     * Execute database DELETE
+     */
+    private executeDatabaseDelete;
+    /**
+     * Execute database UPSERT
+     */
+    private executeDatabaseUpsert;
+    /**
+     * Execute query against a graph database
+     */
+    private executeGraph;
+    /**
+     * Execute graph SELECT (find nodes)
+     */
+    private executeGraphSelect;
+    /**
+     * Execute graph INSERT (create node)
+     */
+    private executeGraphInsert;
+    /**
+     * Execute graph UPDATE
+     */
+    private executeGraphUpdate;
+    /**
+     * Execute graph DELETE
+     */
+    private executeGraphDelete;
+    /**
+     * Execute query against a vector store
+     */
+    private executeVector;
+    /**
+     * Execute vector SELECT (similarity search or fetch)
+     */
+    private executeVectorSelect;
+    /**
+     * Execute vector UPSERT
+     */
+    private executeVectorUpsert;
+    /**
+     * Execute vector DELETE
+     */
+    private executeVectorDelete;
+    /**
+     * Strip alias prefix from a field path
+     */
+    private stripAliasPrefix;
+    /**
+     * Convert unified where clause to database format
+     */
+    private convertWhereForDatabase;
+    /**
+     * Convert unified where clause to graph format
+     */
+    private convertWhereForGraph;
+    /**
+     * Convert unified where clause to vector metadata filter
+     */
+    private convertWhereForVectorMetadata;
+    /**
+     * Extract vector similarity condition from where clause
+     */
+    private extractVectorCondition;
+    /**
+     * Extract IDs condition from where clause
+     */
+    private extractIdsCondition;
+    /**
+     * Extract metadata from a data object (exclude known vector fields)
+     */
+    private extractMetadata;
+}