agentdb 1.0.0

package/dist/cli/query/query-builder.js

@@ -0,0 +1,600 @@
+"use strict";
+/**
+ * VectorQueryBuilder - Fluent API for building complex vector search queries
+ * Provides type-safe filtering, sorting, and pagination with SQL injection protection
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VectorQueryBuilder = void 0;
+/**
+ * VectorQueryBuilder - Fluent API for complex vector queries
+ *
+ * @template T - Type of metadata object
+ *
+ * @example
+ * ```typescript
+ * const results = await db.query()
+ *   .similarTo(queryVector)
+ *   .where('metadata.category', '=', 'tech')
+ *   .whereBetween('metadata.year', 2020, 2024)
+ *   .orderBySimilarity('asc')
+ *   .limit(10)
+ *   .execute();
+ * ```
+ */
+var VectorQueryBuilder = /** @class */ (function () {
+    function VectorQueryBuilder(db) {
+        this.k = 10;
+        this.filters = [];
+        this.orders = [];
+        this.offsetValue = 0;
+        this.metric = 'cosine';
+        this.threshold = 0.0;
+        this.db = db;
+    }
+    /**
+     * Search for vectors similar to the given vector
+     *
+     * @param vector - Query vector
+     * @param k - Number of results to retrieve (default: 10)
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query().similarTo([0.1, 0.2, 0.3], 5)
+     * ```
+     */
+    VectorQueryBuilder.prototype.similarTo = function (vector, k) {
+        this.queryVector = vector;
+        if (k !== undefined) {
+            this.k = k;
+        }
+        return this;
+    };
+    /**
+     * Search for vectors similar to a vector already in the database
+     *
+     * @param id - ID of the reference vector
+     * @param k - Number of results to retrieve (default: 10)
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query().similarToId('vector-123', 5)
+     * ```
+     */
+    VectorQueryBuilder.prototype.similarToId = function (id, k) {
+        this.queryId = id;
+        if (k !== undefined) {
+            this.k = k;
+        }
+        return this;
+    };
+    /**
+     * Add a filter condition
+     *
+     * @param field - Field name (use 'metadata.field' for metadata)
+     * @param op - Comparison operator
+     * @param value - Value to compare against
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .similarTo(vector)
+     *   .where('metadata.category', '=', 'tech')
+     *   .where('metadata.year', '>', 2020)
+     * ```
+     */
+    VectorQueryBuilder.prototype.where = function (field, op, value) {
+        var isMetadata = field.startsWith('metadata.');
+        this.filters.push({
+            field: isMetadata ? field.substring(9) : field, // Remove 'metadata.' prefix
+            operator: op,
+            value: value,
+            isMetadata: isMetadata
+        });
+        return this;
+    };
+    /**
+     * Filter where field is IN a set of values
+     *
+     * @param field - Field name
+     * @param values - Array of values
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .similarTo(vector)
+     *   .whereIn('metadata.tags', ['typescript', 'javascript'])
+     * ```
+     */
+    VectorQueryBuilder.prototype.whereIn = function (field, values) {
+        return this.where(field, 'IN', values);
+    };
+    /**
+     * Filter where field is between min and max (inclusive)
+     *
+     * @param field - Field name
+     * @param min - Minimum value
+     * @param max - Maximum value
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .similarTo(vector)
+     *   .whereBetween('metadata.year', 2020, 2024)
+     * ```
+     */
+    VectorQueryBuilder.prototype.whereBetween = function (field, min, max) {
+        this.where(field, '>=', min);
+        this.where(field, '<=', max);
+        return this;
+    };
+    /**
+     * Filter metadata field (alias for where with 'metadata.' prefix)
+     *
+     * @param path - Metadata field path
+     * @param op - Comparison operator
+     * @param value - Value to compare against
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .similarTo(vector)
+     *   .whereMetadata('author.verified', '=', true)
+     * ```
+     */
+    VectorQueryBuilder.prototype.whereMetadata = function (path, op, value) {
+        return this.where("metadata.".concat(path), op, value);
+    };
+    /**
+     * Set similarity metric
+     *
+     * @param metric - Similarity metric ('cosine', 'euclidean', 'dot')
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query().similarTo(vector).useSimilarityMetric('euclidean')
+     * ```
+     */
+    VectorQueryBuilder.prototype.useSimilarityMetric = function (metric) {
+        this.metric = metric;
+        return this;
+    };
+    /**
+     * Set minimum similarity threshold
+     *
+     * @param threshold - Minimum score threshold
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query().similarTo(vector).withThreshold(0.7)
+     * ```
+     */
+    VectorQueryBuilder.prototype.withThreshold = function (threshold) {
+        this.threshold = threshold;
+        return this;
+    };
+    /**
+     * Order results by a field
+     *
+     * @param field - Field name
+     * @param direction - Sort direction ('asc' or 'desc')
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .similarTo(vector)
+     *   .orderBy('metadata.timestamp', 'desc')
+     * ```
+     */
+    VectorQueryBuilder.prototype.orderBy = function (field, direction) {
+        if (direction === void 0) { direction = 'asc'; }
+        this.orders.push({
+            field: field,
+            direction: direction,
+            bySimilarity: false
+        });
+        return this;
+    };
+    /**
+     * Order results by similarity score
+     *
+     * @param direction - Sort direction ('asc' or 'desc', default: 'desc')
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .similarTo(vector)
+     *   .orderBySimilarity('asc') // Least similar first
+     * ```
+     */
+    VectorQueryBuilder.prototype.orderBySimilarity = function (direction) {
+        if (direction === void 0) { direction = 'desc'; }
+        this.orders.push({
+            field: 'score',
+            direction: direction,
+            bySimilarity: true
+        });
+        return this;
+    };
+    /**
+     * Limit number of results
+     *
+     * @param n - Maximum number of results
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query().similarTo(vector).limit(10)
+     * ```
+     */
+    VectorQueryBuilder.prototype.limit = function (n) {
+        if (n < 0) {
+            throw new Error('Limit must be non-negative');
+        }
+        this.limitValue = n;
+        return this;
+    };
+    /**
+     * Skip first n results
+     *
+     * @param n - Number of results to skip
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query().similarTo(vector).offset(20).limit(10) // Get results 21-30
+     * ```
+     */
+    VectorQueryBuilder.prototype.offset = function (n) {
+        if (n < 0) {
+            throw new Error('Offset must be non-negative');
+        }
+        this.offsetValue = n;
+        return this;
+    };
+    /**
+     * Alias for offset
+     */
+    VectorQueryBuilder.prototype.skip = function (n) {
+        return this.offset(n);
+    };
+    /**
+     * Alias for limit
+     */
+    VectorQueryBuilder.prototype.take = function (n) {
+        return this.limit(n);
+    };
+    /**
+     * Execute raw SQL query (advanced usage)
+     *
+     * @param sql - Raw SQL query
+     * @param params - Query parameters
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * db.query()
+     *   .raw('SELECT * FROM vectors WHERE metadata->>"$.category" = ?', ['tech'])
+     *   .execute()
+     * ```
+     */
+    VectorQueryBuilder.prototype.raw = function (sql, params) {
+        this.rawSQL = sql;
+        this.rawParams = params;
+        return this;
+    };
+    /**
+     * Type-safe metadata wrapper
+     *
+     * @returns QueryBuilder with typed metadata
+     *
+     * @example
+     * ```typescript
+     * interface BlogPost {
+     *   title: string;
+     *   author: string;
+     * }
+     *
+     * const posts = await db.query()
+     *   .withMetadata<BlogPost>()
+     *   .similarTo(vector)
+     *   .execute();
+     *
+     * // posts[0].metadata.title is typed as string
+     * ```
+     */
+    VectorQueryBuilder.prototype.withMetadata = function () {
+        return this;
+    };
+    /**
+     * Execute the query and return all results
+     *
+     * @returns Promise resolving to array of search results
+     *
+     * @example
+     * ```typescript
+     * const results = await db.query()
+     *   .similarTo(vector)
+     *   .where('metadata.category', '=', 'tech')
+     *   .limit(10)
+     *   .execute();
+     * ```
+     */
+    VectorQueryBuilder.prototype.execute = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var vector, refVector, results;
+            return __generator(this, function (_a) {
+                // If raw SQL is provided, use it (advanced usage)
+                if (this.rawSQL) {
+                    return [2 /*return*/, this.executeRaw()];
+                }
+                vector = this.queryVector;
+                if (this.queryId) {
+                    refVector = this.db.get(this.queryId);
+                    if (!refVector) {
+                        throw new Error("Vector with ID ".concat(this.queryId, " not found"));
+                    }
+                    vector = refVector.embedding;
+                }
+                if (!vector) {
+                    throw new Error('Must specify query vector using similarTo() or similarToId()');
+                }
+                results = this.db.search(vector, this.k, this.metric, this.threshold);
+                // Apply filters
+                results = this.applyFilters(results);
+                // Apply sorting
+                results = this.applySorting(results);
+                // Apply pagination
+                results = this.applyPagination(results);
+                return [2 /*return*/, results];
+            });
+        });
+    };
+    /**
+     * Execute query and return first result
+     *
+     * @returns Promise resolving to first result or null
+     *
+     * @example
+     * ```typescript
+     * const best = await db.query()
+     *   .similarTo(vector)
+     *   .first();
+     * ```
+     */
+    VectorQueryBuilder.prototype.first = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var results;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.limit(1).execute()];
+                    case 1:
+                        results = _a.sent();
+                        return [2 /*return*/, results.length > 0 ? results[0] : null];
+                }
+            });
+        });
+    };
+    /**
+     * Count results without retrieving them
+     *
+     * @returns Promise resolving to count
+     *
+     * @example
+     * ```typescript
+     * const count = await db.query()
+     *   .similarTo(vector)
+     *   .where('metadata.category', '=', 'tech')
+     *   .count();
+     * ```
+     */
+    VectorQueryBuilder.prototype.count = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var results;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.execute()];
+                    case 1:
+                        results = _a.sent();
+                        return [2 /*return*/, results.length];
+                }
+            });
+        });
+    };
+    /**
+     * Apply filters to results
+     */
+    VectorQueryBuilder.prototype.applyFilters = function (results) {
+        var _this = this;
+        if (this.filters.length === 0) {
+            return results;
+        }
+        return results.filter(function (result) {
+            return _this.filters.every(function (filter) {
+                var value = filter.isMetadata
+                    ? _this.getNestedValue(result.metadata, filter.field)
+                    : result[filter.field];
+                return _this.matchesCondition(value, filter.operator, filter.value);
+            });
+        });
+    };
+    /**
+     * Get nested object value by path
+     */
+    VectorQueryBuilder.prototype.getNestedValue = function (obj, path) {
+        if (!obj)
+            return undefined;
+        var parts = path.split('.');
+        var current = obj;
+        for (var _i = 0, parts_1 = parts; _i < parts_1.length; _i++) {
+            var part = parts_1[_i];
+            if (current === undefined || current === null) {
+                return undefined;
+            }
+            current = current[part];
+        }
+        return current;
+    };
+    /**
+     * Check if value matches condition
+     */
+    VectorQueryBuilder.prototype.matchesCondition = function (value, operator, target) {
+        if (value === undefined || value === null) {
+            return operator === '!=' && target !== undefined && target !== null;
+        }
+        switch (operator) {
+            case '=':
+                return value === target;
+            case '!=':
+                return value !== target;
+            case '>':
+                return value > target;
+            case '>=':
+                return value >= target;
+            case '<':
+                return value < target;
+            case '<=':
+                return value <= target;
+            case 'LIKE':
+                if (typeof value !== 'string' || typeof target !== 'string') {
+                    return false;
+                }
+                var pattern = target.replace(/%/g, '.*').replace(/_/g, '.');
+                return new RegExp("^".concat(pattern, "$"), 'i').test(value);
+            case 'IN':
+                if (!Array.isArray(target)) {
+                    throw new Error('IN operator requires array value');
+                }
+                return target.includes(value);
+            default:
+                return false;
+        }
+    };
+    /**
+     * Apply sorting to results
+     */
+    VectorQueryBuilder.prototype.applySorting = function (results) {
+        var _this = this;
+        if (this.orders.length === 0) {
+            return results;
+        }
+        return __spreadArray([], results, true).sort(function (a, b) {
+            for (var _i = 0, _a = _this.orders; _i < _a.length; _i++) {
+                var order = _a[_i];
+                var aVal = void 0;
+                var bVal = void 0;
+                if (order.bySimilarity) {
+                    aVal = a.score;
+                    bVal = b.score;
+                }
+                else if (order.field.startsWith('metadata.')) {
+                    var field = order.field.substring(9);
+                    aVal = _this.getNestedValue(a.metadata, field);
+                    bVal = _this.getNestedValue(b.metadata, field);
+                }
+                else {
+                    aVal = a[order.field];
+                    bVal = b[order.field];
+                }
+                // Handle null/undefined
+                if (aVal === undefined || aVal === null) {
+                    return order.direction === 'asc' ? 1 : -1;
+                }
+                if (bVal === undefined || bVal === null) {
+                    return order.direction === 'asc' ? -1 : 1;
+                }
+                // Compare values
+                var comparison = 0;
+                if (aVal < bVal)
+                    comparison = -1;
+                else if (aVal > bVal)
+                    comparison = 1;
+                if (comparison !== 0) {
+                    return order.direction === 'asc' ? comparison : -comparison;
+                }
+            }
+            return 0;
+        });
+    };
+    /**
+     * Apply pagination to results
+     */
+    VectorQueryBuilder.prototype.applyPagination = function (results) {
+        var paginated = results;
+        if (this.offsetValue > 0) {
+            paginated = paginated.slice(this.offsetValue);
+        }
+        if (this.limitValue !== undefined) {
+            paginated = paginated.slice(0, this.limitValue);
+        }
+        return paginated;
+    };
+    /**
+     * Execute raw SQL query (advanced)
+     */
+    VectorQueryBuilder.prototype.executeRaw = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                // This would require direct database access
+                // For now, throw an error - can be implemented later with backend support
+                throw new Error('Raw SQL queries not yet implemented. Use standard query methods.');
+            });
+        });
+    };
+    return VectorQueryBuilder;
+}());
+exports.VectorQueryBuilder = VectorQueryBuilder;

package/dist/cli/templates.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Template library for common learning algorithms
+ */
+export interface Template {
+    name: string;
+    description: string;
+    algorithm: string;
+    useCase: string;
+    config: any;
+}
+export declare function getAvailableTemplates(): Promise<Template[]>;
+export declare function getTemplateConfig(name: string): Promise<any>;
+export declare function getTemplate(name: string): Promise<Template | undefined>;
+//# sourceMappingURL=templates.d.ts.map

package/dist/cli/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/cli/templates.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,GAAG,CAAC;CACb;AAmKD,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAEjE;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAMlE;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAE7E"}