@elqnt/kg

Knowledge graph SDK for the Eloquent platform. Provides TypeScript types, browser and server APIs, React hooks, and query utilities for working with knowledge graphs.

Installation

pnpm add @elqnt/kg

Quick Start

Browser (React)

import { useGraphs, useKGQuery } from "@elqnt/kg/hooks";

function KnowledgeGraphExplorer() {
  const { listGraphs, loading, error } = useGraphs({
    baseUrl: process.env.NEXT_PUBLIC_API_GATEWAY_URL!,
    orgId: currentOrgId,
  });

  const { query } = useKGQuery({
    baseUrl: process.env.NEXT_PUBLIC_API_GATEWAY_URL!,
    orgId: currentOrgId,
    graphId: selectedGraphId,
  });

  // List all graphs
  const graphs = await listGraphs();

  // Query nodes
  const result = await query({
    label: "Person",
    fields: [{ name: "age", operator: "gt", value: 21 }],
    limit: 50,
    depth: 1,
    sortBy: "name",
    sortOrder: "asc",
  });
}

Server Actions

// In a Next.js server action
"use server";

import { listGraphsServer, queryGraphServer } from "@elqnt/kg/api/server";

export async function getGraphs(orgId: string) {
  const response = await listGraphsServer({
    gatewayUrl: process.env.API_GATEWAY_URL!,
    jwtSecret: process.env.JWT_SECRET!,
    orgId,
  });
  return response.data?.graphs || [];
}

export async function searchNodes(orgId: string, graphId: string, label: string) {
  const response = await queryGraphServer(
    { label, fields: [], limit: 100, depth: 1, sortBy: "", sortOrder: "" },
    {
      gatewayUrl: process.env.API_GATEWAY_URL!,
      jwtSecret: process.env.JWT_SECRET!,
      orgId,
      graphId,
    }
  );
  return response.data;
}

Query Builder

import { KGQueryBuilder, createNodeQuery } from "@elqnt/kg/utils";

// Fluent builder API
const query = new KGQueryBuilder()
  .label("Person")
  .field("age", "gt", 21)
  .field("department", "eq", "Engineering")
  .edge("WORKS_AT", "outgoing", "Company")
  .limit(100)
  .sortBy("name", "asc")
  .summaryOnly()
  .build();

// Helper function for simple queries
const simpleQuery = createNodeQuery("Product", { category: "electronics" }, { limit: 50 });

Architecture

Browser/React App                   Server Actions/SSR
       │                                   │
       ▼                                   ▼
  @elqnt/kg/hooks              @elqnt/kg/api/server
       │                                   │
       ▼                                   ▼
  @elqnt/kg/api                  serverApiRequest
       │                         (JWT generation)
       ▼                                   │
  browserApiRequest                        │
       │                                   │
       └───────────────┬───────────────────┘
                       ▼
                 API Gateway
                       │
                       ▼
                 KG Service

Exports

| Import Path | Description | |-------------|-------------| | @elqnt/kg | All exports (types, API, hooks, utils) | | @elqnt/kg/api | Browser API functions | | @elqnt/kg/api/server | Server API functions | | @elqnt/kg/hooks | React hooks | | @elqnt/kg/models | TypeScript types | | @elqnt/kg/utils | Query builders and helpers |

API Reference

Browser API (@elqnt/kg/api)

All functions accept ApiClientOptions or KGApiOptions:

interface ApiClientOptions {
  baseUrl: string;   // API Gateway URL
  orgId: string;     // Organization ID
  userId?: string;   // Optional user ID
  headers?: Record<string, string>;
}

interface KGApiOptions extends ApiClientOptions {
  graphId?: string;  // Graph ID for graph-scoped operations
}

Graph Operations

| Function | Description | |----------|-------------| | listGraphsApi(options) | List all graphs | | getGraphApi(graphId, options) | Get a specific graph | | createGraphApi(graph, options) | Create a new graph | | updateGraphApi(graphId, updates, options) | Update a graph | | deleteGraphApi(graphId, options) | Delete a graph |

Query Operations

| Function | Description | |----------|-------------| | queryGraphApi(query, options) | Query nodes | | getGraphLabelsApi(options) | Get all node labels |

Node Operations

| Function | Description | |----------|-------------| | getKGNodeApi(nodeId, options) | Get a node by ID | | ingestKGNodeApi(node, options) | Ingest a new node | | updateKGNodeApi(nodeId, updates, options) | Update a node |

Designer Operations

| Function | Description | |----------|-------------| | listDesignerNodesApi(options) | List node definitions | | createDesignerNodeApi(node, options) | Create node definition | | listDesignerEdgesApi(options) | List edge definitions | | createDesignerEdgeApi(edge, options) | Create edge definition |

Server API (@elqnt/kg/api/server)

All functions accept ServerApiOptions:

interface ServerApiOptions {
  gatewayUrl: string;  // API Gateway URL
  jwtSecret: string;   // JWT secret for token generation
  orgId: string;       // Organization ID
  userId?: string;     // Optional user ID (default: "system")
  graphId?: string;    // Graph ID for graph-scoped operations
  timeout?: number;    // Request timeout in ms
  cache?: RequestCache;
}

Functions mirror the browser API with Server suffix:

• listGraphsServer, getGraphServer, createGraphServer, etc.
• queryGraphServer, getGraphLabelsServer
• getKGNodeServer, ingestKGNodeServer, updateKGNodeServer
• listDesignerNodesServer, listDesignerEdgesServer, etc.

React Hooks (@elqnt/kg/hooks)

useGraphs(options: ApiClientOptions)

const {
  loading,      // boolean - any operation in progress
  error,        // string | null - last error message
  listGraphs,   // () => Promise<Graph[]>
  getGraph,     // (graphId) => Promise<Graph | null>
  createGraph,  // (graph) => Promise<Graph | null>
  updateGraph,  // (graphId, updates) => Promise<Graph | null>
  deleteGraph,  // (graphId) => Promise<boolean>
} = useGraphs(options);

useKGQuery(options: UseKGOptions)

const {
  loading,
  error,
  query,        // (KGQuery) => Promise<KGQueryResult | null>
  getLabels,    // () => Promise<KGLabelInfo[]>
  getNode,      // (nodeId) => Promise<KGNode | null>
  ingestNode,   // (node) => Promise<string | null>
  updateNode,   // (nodeId, updates) => Promise<boolean>
} = useKGQuery(options);

useKGDesigner(options: UseKGOptions)

const {
  loading,
  error,
  // Node definitions
  listNodes,    // () => Promise<GraphNodeDefinition[]>
  getNode,      // (label) => Promise<GraphNodeDefinition | null>
  createNode,   // (node) => Promise<GraphNodeDefinition | null>
  updateNode,   // (label, updates) => Promise<GraphNodeDefinition | null>
  deleteNode,   // (label) => Promise<boolean>
  // Edge definitions
  listEdges,    // () => Promise<GraphEdgeDefinition[]>
  createEdge,   // (edge) => Promise<GraphEdgeDefinition | null>
  updateEdge,   // (label, updates) => Promise<GraphEdgeDefinition | null>
  deleteEdge,   // (label) => Promise<boolean>
} = useKGDesigner(options);

useCrawlJobs(options: UseKGOptions)

const {
  loading,
  error,
  listJobs,         // (params?) => Promise<{ jobs, total }>
  startJob,         // (params) => Promise<string | null>
  getJobStatus,     // (jobId) => Promise<CrawlJob | null>
  cancelJob,        // (jobId) => Promise<boolean>
  getCrawledPages,  // (jobId) => Promise<Page[]>
} = useCrawlJobs(options);

Query Builder (@elqnt/kg/utils)

KGQueryBuilder

Fluent API for building queries:

const builder = new KGQueryBuilder();

// Methods (all return `this` for chaining)
builder.label(label: string)
builder.field(name: string, operator: KGFieldQueryOperator, value: unknown)
builder.where(name: string, value: unknown)  // Shorthand for equality
builder.whereAll(fields: Record<string, unknown>)
builder.edge(label: string, direction: "incoming" | "outgoing", toLabel?: string)
builder.outgoing(label: string, toLabel?: string)
builder.incoming(label: string, toLabel?: string)
builder.limit(n: number)
builder.depth(n: number)
builder.offset(n: number)
builder.sortBy(field: string, order?: "asc" | "desc")
builder.embeddingsSource(source: string)
builder.skipEmbedding()
builder.summaryOnly()
builder.build(): KGQuery

Helper Functions

// Create a simple query with equality filters
createNodeQuery(
  label: string,
  fields?: Record<string, unknown>,
  options?: { limit?, depth?, sortBy?, sortOrder?, summaryOnly? }
): KGQuery

// Create an edge query object
createEdgeQuery(
  label: string,
  direction?: "incoming" | "outgoing",
  options?: { toLabel?, toFieldKey?, toFieldValue?, fields? }
): KGEdgeQuery

// Create a field query object
createFieldQuery(
  name: string,
  operator: KGFieldQueryOperator,
  value: unknown
): KGFieldQuery

// Create a similarity search query
createSimilarityQuery(
  label: string,
  searchText: string,
  options?: { embeddingsSource?, limit?, summaryOnly? }
): KGQuery

Types (@elqnt/kg/models)

Key types exported:

// Graphs
interface Graph { id, name, description, isDefault, createdAt, updatedAt }
interface CreateGraphRequest { id?, name, description }

// Nodes & Edges
interface KGNode { id, label, fields, relationships?, score? }
interface KGEdge { id, label, fields, from, to }
interface KGNodeIngestRequest { label, fields, edges?, keyField?, ... }

// Queries
interface KGQuery { label, fields, edges?, limit, depth, sortBy, sortOrder, ... }
interface KGFieldQuery { name, operator, value }
interface KGEdgeQuery { label, direction, toLabel, toFieldKey, toFieldValue, fields? }
interface KGQueryResult { nodes, edges }

// Designer
interface GraphNodeDefinition { label, description, schema, createdAt, updatedAt }
interface GraphEdgeDefinition { label, description, fromNode, toNode, schema, ... }

// Labels
interface KGLabelInfo { label, count }

Migration from v2.x

Breaking Changes in v3.0.0

1. graphId handling: Now consistently uses X-Graph-ID header instead of query params for POST/PUT operations

2. New exports:

   • @elqnt/kg/api/server - Server-side API functions
   • @elqnt/kg/utils - Query builder utilities

3. Hook utilities exposed:

   • useApiAsync, useAsync, useOptionsRef now exported from @elqnt/kg/hooks

Migration Steps

1. Update import paths if using internal utilities
2. Server actions can now use @elqnt/kg/api/server instead of manual API calls
3. Consider using KGQueryBuilder for complex queries

Development

# Build the package
pnpm build

# Run type checking
pnpm typecheck

# Watch mode
pnpm dev

License

Private - Eloquent Platform