@elqnt/kg 2.1.1 → 3.0.0

package/dist/utils/index.d.mts

@@ -0,0 +1,277 @@
+import { KGFieldQueryOperator, KGQuery, KGEdgeQuery, KGFieldQuery } from '../models/kg.mjs';
+export { KGFieldQueryOperatorArrayContains, KGFieldQueryOperatorEqual, KGFieldQueryOperatorGreater, KGFieldQueryOperatorGreaterOrEqual, KGFieldQueryOperatorIn, KGFieldQueryOperatorLess, KGFieldQueryOperatorLessOrEqual, KGFieldQueryOperatorLike, KGFieldQueryOperatorNotEqual, KGFieldQueryOperatorSimilar, KGRelationshipDirectionIncoming, KGRelationshipDirectionOutgoing } from '../models/kg.mjs';
+import '@elqnt/types';
+
+/**
+ * Knowledge Graph Query Builder
+ *
+ * Fluent API for building KGQuery objects programmatically.
+ *
+ * @example
+ * ```ts
+ * import { KGQueryBuilder, createNodeQuery } from "@elqnt/kg/utils";
+ *
+ * // Using the builder
+ * const query = new KGQueryBuilder()
+ *   .label("Person")
+ *   .field("age", "gt", 21)
+ *   .field("status", "eq", "active")
+ *   .edge("WORKS_AT", "outgoing", "Company")
+ *   .limit(50)
+ *   .sortBy("name", "asc")
+ *   .build();
+ *
+ * // Using helper functions
+ * const simpleQuery = createNodeQuery("Product", { category: "electronics" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Fluent builder for KGQuery objects
+ *
+ * Provides a chainable API for constructing knowledge graph queries.
+ * All methods return `this` to allow chaining.
+ *
+ * @example
+ * ```ts
+ * const query = new KGQueryBuilder()
+ *   .label("Person")
+ *   .field("age", "gt", 21)
+ *   .field("department", "eq", "Engineering")
+ *   .edge("REPORTS_TO", "outgoing", "Person")
+ *   .limit(100)
+ *   .offset(0)
+ *   .sortBy("name", "asc")
+ *   .summaryOnly()
+ *   .build();
+ * ```
+ */
+declare class KGQueryBuilder {
+    private _label;
+    private _fields;
+    private _edges;
+    private _limit;
+    private _depth;
+    private _offset;
+    private _sortBy;
+    private _sortOrder;
+    private _embeddingsSource?;
+    private _skipEmbedding;
+    private _summaryOnly;
+    /**
+     * Set the node label to query
+     *
+     * @param label - The node label (e.g., "Person", "Product")
+     */
+    label(label: string): this;
+    /**
+     * Add a field filter to the query
+     *
+     * @param name - Field name
+     * @param operator - Comparison operator (eq, neq, gt, lt, gte, lte, like, similar, in, arrayContains)
+     * @param value - Value to compare against
+     *
+     * @example
+     * ```ts
+     * builder.field("age", "gt", 21);
+     * builder.field("status", "in", ["active", "pending"]);
+     * builder.field("name", "like", "John%");
+     * ```
+     */
+    field(name: string, operator: KGFieldQueryOperator, value: unknown): this;
+    /**
+     * Add an equality field filter (shorthand for field(name, "eq", value))
+     *
+     * @param name - Field name
+     * @param value - Value to match
+     */
+    where(name: string, value: unknown): this;
+    /**
+     * Add multiple equality filters at once
+     *
+     * @param fields - Object with field names as keys and values to match
+     *
+     * @example
+     * ```ts
+     * builder.whereAll({ status: "active", type: "premium" });
+     * ```
+     */
+    whereAll(fields: Record<string, unknown>): this;
+    /**
+     * Add an edge traversal to the query
+     *
+     * @param label - Edge label (e.g., "WORKS_AT", "REPORTS_TO")
+     * @param direction - Traversal direction ("incoming" or "outgoing")
+     * @param toLabel - Target node label (optional)
+     * @param options - Additional edge query options
+     *
+     * @example
+     * ```ts
+     * builder.edge("WORKS_AT", "outgoing", "Company");
+     * builder.edge("REPORTS_TO", "incoming", "Person", {
+     *   toFieldKey: "id",
+     *   toFieldValue: "manager-123"
+     * });
+     * ```
+     */
+    edge(label: string, direction: "incoming" | "outgoing", toLabel?: string, options?: {
+        toFieldKey?: string;
+        toFieldValue?: unknown;
+        fields?: Record<string, unknown>;
+    }): this;
+    /**
+     * Add an outgoing edge traversal
+     *
+     * @param label - Edge label
+     * @param toLabel - Target node label
+     */
+    outgoing(label: string, toLabel?: string): this;
+    /**
+     * Add an incoming edge traversal
+     *
+     * @param label - Edge label
+     * @param toLabel - Source node label
+     */
+    incoming(label: string, toLabel?: string): this;
+    /**
+     * Set the maximum number of results
+     *
+     * @param n - Maximum number of results (default: 100)
+     */
+    limit(n: number): this;
+    /**
+     * Set the traversal depth
+     *
+     * @param n - Depth of edge traversal (default: 1)
+     */
+    depth(n: number): this;
+    /**
+     * Set the result offset for pagination
+     *
+     * @param n - Number of results to skip
+     */
+    offset(n: number): this;
+    /**
+     * Set the sort field and order
+     *
+     * @param field - Field name to sort by
+     * @param order - Sort order ("asc" or "desc")
+     */
+    sortBy(field: string, order?: "asc" | "desc"): this;
+    /**
+     * Set the embeddings source for similarity search
+     *
+     * @param source - Embeddings source identifier
+     */
+    embeddingsSource(source: string): this;
+    /**
+     * Skip embedding generation for this query
+     */
+    skipEmbedding(): this;
+    /**
+     * Return only summary fields (excludes heavy fields like text, embeddings)
+     */
+    summaryOnly(): this;
+    /**
+     * Build the final KGQuery object
+     *
+     * @returns The constructed KGQuery
+     * @throws Error if no label is set
+     */
+    build(): KGQuery;
+}
+/**
+ * Create a simple node query with equality filters
+ *
+ * @param label - Node label to query
+ * @param fields - Optional field equality filters
+ * @param options - Additional query options
+ * @returns KGQuery object
+ *
+ * @example
+ * ```ts
+ * // Query all Person nodes
+ * const allPeople = createNodeQuery("Person");
+ *
+ * // Query with filters
+ * const activeUsers = createNodeQuery("User", { status: "active", role: "admin" });
+ *
+ * // With options
+ * const recentProducts = createNodeQuery(
+ *   "Product",
+ *   { inStock: true },
+ *   { limit: 10, sortBy: "createdAt", sortOrder: "desc" }
+ * );
+ * ```
+ */
+declare function createNodeQuery(label: string, fields?: Record<string, unknown>, options?: {
+    limit?: number;
+    depth?: number;
+    sortBy?: string;
+    sortOrder?: "asc" | "desc";
+    summaryOnly?: boolean;
+}): KGQuery;
+/**
+ * Create an edge query object
+ *
+ * @param label - Edge label
+ * @param direction - Traversal direction
+ * @param options - Additional edge options
+ * @returns KGEdgeQuery object
+ *
+ * @example
+ * ```ts
+ * const worksAtEdge = createEdgeQuery("WORKS_AT", "outgoing", {
+ *   toLabel: "Company",
+ *   toFieldKey: "name",
+ *   toFieldValue: "Acme Corp"
+ * });
+ * ```
+ */
+declare function createEdgeQuery(label: string, direction?: "incoming" | "outgoing", options?: {
+    toLabel?: string;
+    toFieldKey?: string;
+    toFieldValue?: unknown;
+    fields?: Record<string, unknown>;
+}): KGEdgeQuery;
+/**
+ * Create a field query object
+ *
+ * @param name - Field name
+ * @param operator - Comparison operator
+ * @param value - Value to compare against
+ * @returns KGFieldQuery object
+ *
+ * @example
+ * ```ts
+ * const ageFilter = createFieldQuery("age", "gt", 21);
+ * const statusFilter = createFieldQuery("status", "in", ["active", "pending"]);
+ * ```
+ */
+declare function createFieldQuery(name: string, operator: KGFieldQueryOperator, value: unknown): KGFieldQuery;
+/**
+ * Create a similarity search query
+ *
+ * @param label - Node label to search
+ * @param searchText - Text to find similar nodes for
+ * @param options - Additional query options
+ * @returns KGQuery object configured for similarity search
+ *
+ * @example
+ * ```ts
+ * const similarDocs = createSimilarityQuery(
+ *   "Document",
+ *   "machine learning algorithms",
+ *   { limit: 10, embeddingsSource: "openai" }
+ * );
+ * ```
+ */
+declare function createSimilarityQuery(label: string, searchText: string, options?: {
+    embeddingsSource?: string;
+    limit?: number;
+    summaryOnly?: boolean;
+}): KGQuery;
+
+export { KGQueryBuilder, createEdgeQuery, createFieldQuery, createNodeQuery, createSimilarityQuery };

package/dist/utils/index.d.ts

@@ -0,0 +1,277 @@
+import { KGFieldQueryOperator, KGQuery, KGEdgeQuery, KGFieldQuery } from '../models/kg.js';
+export { KGFieldQueryOperatorArrayContains, KGFieldQueryOperatorEqual, KGFieldQueryOperatorGreater, KGFieldQueryOperatorGreaterOrEqual, KGFieldQueryOperatorIn, KGFieldQueryOperatorLess, KGFieldQueryOperatorLessOrEqual, KGFieldQueryOperatorLike, KGFieldQueryOperatorNotEqual, KGFieldQueryOperatorSimilar, KGRelationshipDirectionIncoming, KGRelationshipDirectionOutgoing } from '../models/kg.js';
+import '@elqnt/types';
+
+/**
+ * Knowledge Graph Query Builder
+ *
+ * Fluent API for building KGQuery objects programmatically.
+ *
+ * @example
+ * ```ts
+ * import { KGQueryBuilder, createNodeQuery } from "@elqnt/kg/utils";
+ *
+ * // Using the builder
+ * const query = new KGQueryBuilder()
+ *   .label("Person")
+ *   .field("age", "gt", 21)
+ *   .field("status", "eq", "active")
+ *   .edge("WORKS_AT", "outgoing", "Company")
+ *   .limit(50)
+ *   .sortBy("name", "asc")
+ *   .build();
+ *
+ * // Using helper functions
+ * const simpleQuery = createNodeQuery("Product", { category: "electronics" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Fluent builder for KGQuery objects
+ *
+ * Provides a chainable API for constructing knowledge graph queries.
+ * All methods return `this` to allow chaining.
+ *
+ * @example
+ * ```ts
+ * const query = new KGQueryBuilder()
+ *   .label("Person")
+ *   .field("age", "gt", 21)
+ *   .field("department", "eq", "Engineering")
+ *   .edge("REPORTS_TO", "outgoing", "Person")
+ *   .limit(100)
+ *   .offset(0)
+ *   .sortBy("name", "asc")
+ *   .summaryOnly()
+ *   .build();
+ * ```
+ */
+declare class KGQueryBuilder {
+    private _label;
+    private _fields;
+    private _edges;
+    private _limit;
+    private _depth;
+    private _offset;
+    private _sortBy;
+    private _sortOrder;
+    private _embeddingsSource?;
+    private _skipEmbedding;
+    private _summaryOnly;
+    /**
+     * Set the node label to query
+     *
+     * @param label - The node label (e.g., "Person", "Product")
+     */
+    label(label: string): this;
+    /**
+     * Add a field filter to the query
+     *
+     * @param name - Field name
+     * @param operator - Comparison operator (eq, neq, gt, lt, gte, lte, like, similar, in, arrayContains)
+     * @param value - Value to compare against
+     *
+     * @example
+     * ```ts
+     * builder.field("age", "gt", 21);
+     * builder.field("status", "in", ["active", "pending"]);
+     * builder.field("name", "like", "John%");
+     * ```
+     */
+    field(name: string, operator: KGFieldQueryOperator, value: unknown): this;
+    /**
+     * Add an equality field filter (shorthand for field(name, "eq", value))
+     *
+     * @param name - Field name
+     * @param value - Value to match
+     */
+    where(name: string, value: unknown): this;
+    /**
+     * Add multiple equality filters at once
+     *
+     * @param fields - Object with field names as keys and values to match
+     *
+     * @example
+     * ```ts
+     * builder.whereAll({ status: "active", type: "premium" });
+     * ```
+     */
+    whereAll(fields: Record<string, unknown>): this;
+    /**
+     * Add an edge traversal to the query
+     *
+     * @param label - Edge label (e.g., "WORKS_AT", "REPORTS_TO")
+     * @param direction - Traversal direction ("incoming" or "outgoing")
+     * @param toLabel - Target node label (optional)
+     * @param options - Additional edge query options
+     *
+     * @example
+     * ```ts
+     * builder.edge("WORKS_AT", "outgoing", "Company");
+     * builder.edge("REPORTS_TO", "incoming", "Person", {
+     *   toFieldKey: "id",
+     *   toFieldValue: "manager-123"
+     * });
+     * ```
+     */
+    edge(label: string, direction: "incoming" | "outgoing", toLabel?: string, options?: {
+        toFieldKey?: string;
+        toFieldValue?: unknown;
+        fields?: Record<string, unknown>;
+    }): this;
+    /**
+     * Add an outgoing edge traversal
+     *
+     * @param label - Edge label
+     * @param toLabel - Target node label
+     */
+    outgoing(label: string, toLabel?: string): this;
+    /**
+     * Add an incoming edge traversal
+     *
+     * @param label - Edge label
+     * @param toLabel - Source node label
+     */
+    incoming(label: string, toLabel?: string): this;
+    /**
+     * Set the maximum number of results
+     *
+     * @param n - Maximum number of results (default: 100)
+     */
+    limit(n: number): this;
+    /**
+     * Set the traversal depth
+     *
+     * @param n - Depth of edge traversal (default: 1)
+     */
+    depth(n: number): this;
+    /**
+     * Set the result offset for pagination
+     *
+     * @param n - Number of results to skip
+     */
+    offset(n: number): this;
+    /**
+     * Set the sort field and order
+     *
+     * @param field - Field name to sort by
+     * @param order - Sort order ("asc" or "desc")
+     */
+    sortBy(field: string, order?: "asc" | "desc"): this;
+    /**
+     * Set the embeddings source for similarity search
+     *
+     * @param source - Embeddings source identifier
+     */
+    embeddingsSource(source: string): this;
+    /**
+     * Skip embedding generation for this query
+     */
+    skipEmbedding(): this;
+    /**
+     * Return only summary fields (excludes heavy fields like text, embeddings)
+     */
+    summaryOnly(): this;
+    /**
+     * Build the final KGQuery object
+     *
+     * @returns The constructed KGQuery
+     * @throws Error if no label is set
+     */
+    build(): KGQuery;
+}
+/**
+ * Create a simple node query with equality filters
+ *
+ * @param label - Node label to query
+ * @param fields - Optional field equality filters
+ * @param options - Additional query options
+ * @returns KGQuery object
+ *
+ * @example
+ * ```ts
+ * // Query all Person nodes
+ * const allPeople = createNodeQuery("Person");
+ *
+ * // Query with filters
+ * const activeUsers = createNodeQuery("User", { status: "active", role: "admin" });
+ *
+ * // With options
+ * const recentProducts = createNodeQuery(
+ *   "Product",
+ *   { inStock: true },
+ *   { limit: 10, sortBy: "createdAt", sortOrder: "desc" }
+ * );
+ * ```
+ */
+declare function createNodeQuery(label: string, fields?: Record<string, unknown>, options?: {
+    limit?: number;
+    depth?: number;
+    sortBy?: string;
+    sortOrder?: "asc" | "desc";
+    summaryOnly?: boolean;
+}): KGQuery;
+/**
+ * Create an edge query object
+ *
+ * @param label - Edge label
+ * @param direction - Traversal direction
+ * @param options - Additional edge options
+ * @returns KGEdgeQuery object
+ *
+ * @example
+ * ```ts
+ * const worksAtEdge = createEdgeQuery("WORKS_AT", "outgoing", {
+ *   toLabel: "Company",
+ *   toFieldKey: "name",
+ *   toFieldValue: "Acme Corp"
+ * });
+ * ```
+ */
+declare function createEdgeQuery(label: string, direction?: "incoming" | "outgoing", options?: {
+    toLabel?: string;
+    toFieldKey?: string;
+    toFieldValue?: unknown;
+    fields?: Record<string, unknown>;
+}): KGEdgeQuery;
+/**
+ * Create a field query object
+ *
+ * @param name - Field name
+ * @param operator - Comparison operator
+ * @param value - Value to compare against
+ * @returns KGFieldQuery object
+ *
+ * @example
+ * ```ts
+ * const ageFilter = createFieldQuery("age", "gt", 21);
+ * const statusFilter = createFieldQuery("status", "in", ["active", "pending"]);
+ * ```
+ */
+declare function createFieldQuery(name: string, operator: KGFieldQueryOperator, value: unknown): KGFieldQuery;
+/**
+ * Create a similarity search query
+ *
+ * @param label - Node label to search
+ * @param searchText - Text to find similar nodes for
+ * @param options - Additional query options
+ * @returns KGQuery object configured for similarity search
+ *
+ * @example
+ * ```ts
+ * const similarDocs = createSimilarityQuery(
+ *   "Document",
+ *   "machine learning algorithms",
+ *   { limit: 10, embeddingsSource: "openai" }
+ * );
+ * ```
+ */
+declare function createSimilarityQuery(label: string, searchText: string, options?: {
+    embeddingsSource?: string;
+    limit?: number;
+    summaryOnly?: boolean;
+}): KGQuery;
+
+export { KGQueryBuilder, createEdgeQuery, createFieldQuery, createNodeQuery, createSimilarityQuery };

package/dist/utils/index.js

@@ -0,0 +1,44 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";
+
+
+
+
+
+
+var _chunkADIKUMMIjs = require('../chunk-ADIKUMMI.js');
+require('../chunk-W4XVBGE7.js');
+require('../chunk-67SUELDR.js');
+
+
+
+
+
+
+
+
+
+
+
+
+
+var _chunkUCKE66GBjs = require('../chunk-UCKE66GB.js');
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+exports.KGFieldQueryOperatorArrayContains = _chunkUCKE66GBjs.KGFieldQueryOperatorArrayContains; exports.KGFieldQueryOperatorEqual = _chunkUCKE66GBjs.KGFieldQueryOperatorEqual; exports.KGFieldQueryOperatorGreater = _chunkUCKE66GBjs.KGFieldQueryOperatorGreater; exports.KGFieldQueryOperatorGreaterOrEqual = _chunkUCKE66GBjs.KGFieldQueryOperatorGreaterOrEqual; exports.KGFieldQueryOperatorIn = _chunkUCKE66GBjs.KGFieldQueryOperatorIn; exports.KGFieldQueryOperatorLess = _chunkUCKE66GBjs.KGFieldQueryOperatorLess; exports.KGFieldQueryOperatorLessOrEqual = _chunkUCKE66GBjs.KGFieldQueryOperatorLessOrEqual; exports.KGFieldQueryOperatorLike = _chunkUCKE66GBjs.KGFieldQueryOperatorLike; exports.KGFieldQueryOperatorNotEqual = _chunkUCKE66GBjs.KGFieldQueryOperatorNotEqual; exports.KGFieldQueryOperatorSimilar = _chunkUCKE66GBjs.KGFieldQueryOperatorSimilar; exports.KGQueryBuilder = _chunkADIKUMMIjs.KGQueryBuilder; exports.KGRelationshipDirectionIncoming = _chunkUCKE66GBjs.KGRelationshipDirectionIncoming; exports.KGRelationshipDirectionOutgoing = _chunkUCKE66GBjs.KGRelationshipDirectionOutgoing; exports.createEdgeQuery = _chunkADIKUMMIjs.createEdgeQuery; exports.createFieldQuery = _chunkADIKUMMIjs.createFieldQuery; exports.createNodeQuery = _chunkADIKUMMIjs.createNodeQuery; exports.createSimilarityQuery = _chunkADIKUMMIjs.createSimilarityQuery;
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/eloquent-packages/eloquent-packages/packages/kg/dist/utils/index.js"],"names":[],"mappings":"AAAA,qFAAY;AACZ;AACE;AACA;AACA;AACA;AACA;AACF,uDAA6B;AAC7B,gCAA6B;AAC7B,gCAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,uDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,i0CAAC","file":"/home/runner/work/eloquent-packages/eloquent-packages/packages/kg/dist/utils/index.js"}

package/dist/utils/index.mjs

@@ -0,0 +1,44 @@
+"use client";
+import {
+  KGQueryBuilder,
+  createEdgeQuery,
+  createFieldQuery,
+  createNodeQuery,
+  createSimilarityQuery
+} from "../chunk-CAXPQTKI.mjs";
+import "../chunk-NJNBEGDB.mjs";
+import "../chunk-RDIQ7HTM.mjs";
+import {
+  KGFieldQueryOperatorArrayContains,
+  KGFieldQueryOperatorEqual,
+  KGFieldQueryOperatorGreater,
+  KGFieldQueryOperatorGreaterOrEqual,
+  KGFieldQueryOperatorIn,
+  KGFieldQueryOperatorLess,
+  KGFieldQueryOperatorLessOrEqual,
+  KGFieldQueryOperatorLike,
+  KGFieldQueryOperatorNotEqual,
+  KGFieldQueryOperatorSimilar,
+  KGRelationshipDirectionIncoming,
+  KGRelationshipDirectionOutgoing
+} from "../chunk-VUSVP6OI.mjs";
+export {
+  KGFieldQueryOperatorArrayContains,
+  KGFieldQueryOperatorEqual,
+  KGFieldQueryOperatorGreater,
+  KGFieldQueryOperatorGreaterOrEqual,
+  KGFieldQueryOperatorIn,
+  KGFieldQueryOperatorLess,
+  KGFieldQueryOperatorLessOrEqual,
+  KGFieldQueryOperatorLike,
+  KGFieldQueryOperatorNotEqual,
+  KGFieldQueryOperatorSimilar,
+  KGQueryBuilder,
+  KGRelationshipDirectionIncoming,
+  KGRelationshipDirectionOutgoing,
+  createEdgeQuery,
+  createFieldQuery,
+  createNodeQuery,
+  createSimilarityQuery
+};
+//# sourceMappingURL=index.mjs.map

package/dist/utils/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}