@elqnt/kg 2.1.0 → 3.0.0

package/README.md

@@ -1,72 +1,390 @@
-# @eloquent/kg
+# @elqnt/kg
 
-This package provides knowledge graph functionality for Eloquent applications.
+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
 
-Since this package is published to GitHub Packages, you'll need to configure npm to use GitHub Packages for the `@eloquent` scope.
+```bash
+pnpm add @elqnt/kg
+```
+
+## Quick Start
+
+### Browser (React)
+
+```tsx
+import { useGraphs, useKGQuery } from "@elqnt/kg/hooks";
 
-1. Create or edit an `.npmrc` file in your project root:
+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",
+  });
+}
 ```
-@eloquent:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+
+### Server Actions
+
+```ts
+// 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;
+}
 ```
 
-2. Set your GitHub token as an environment variable:
+### Query Builder
 
-```bash
-export GITHUB_TOKEN=your_github_token
+```ts
+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 });
 ```
 
-3. Install the package:
+## Architecture
 
-```bash
-npm install @eloquent/kg
+```
+Browser/React App                   Server Actions/SSR
+       │                                   │
+       ▼                                   ▼
+  @elqnt/kg/hooks              @elqnt/kg/api/server
+       │                                   │
+       ▼                                   ▼
+  @elqnt/kg/api                  serverApiRequest
+       │                         (JWT generation)
+       ▼                                   │
+  browserApiRequest                        │
+       │                                   │
+       └───────────────┬───────────────────┘
+                       ▼
+                 API Gateway
+                       │
+                       ▼
+                 KG Service
 ```
 
-## Usage
+## Exports
 
-```typescript
-import {} from /* components or functions */ "@eloquent/kg";
+| 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 |
 
-// Your code here
+## API Reference
+
+### Browser API (`@elqnt/kg/api`)
+
+All functions accept `ApiClientOptions` or `KGApiOptions`:
+
+```ts
+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
+}
 ```
 
-## Development
+#### Graph Operations
 
-To build the package locally:
+| 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 |
 
-```bash
-npm run build
+#### 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`:
+
+```ts
+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;
+}
 ```
 
-## Publishing
+Functions mirror the browser API with `Server` suffix:
 
-This package is automatically published to GitHub Packages when changes are pushed to the main branch that affect files in the `packages/eloquent/kg` directory.
+- `listGraphsServer`, `getGraphServer`, `createGraphServer`, etc.
+- `queryGraphServer`, `getGraphLabelsServer`
+- `getKGNodeServer`, `ingestKGNodeServer`, `updateKGNodeServer`
+- `listDesignerNodesServer`, `listDesignerEdgesServer`, etc.
 
-For manual publishing:
+### React Hooks (`@elqnt/kg/hooks`)
 
-1. Make sure you have the correct GitHub token set up
-2. Update the version in package.json
-3. Run:
+#### `useGraphs(options: ApiClientOptions)`
 
-```bash
-cd packages/eloquent/kg
-npm run build
-npm publish
+```tsx
+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);
 ```
 
-## Monorepo Integration
+#### `useKGQuery(options: UseKGOptions)`
 
-This package is part of the auto-beam-frontend monorepo. When making changes:
+```tsx
+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);
+```
 
-1. The package will be automatically published when changes are pushed to the main branch
-2. The package follows the early return pattern in its build process
-3. To use this package in other packages within the monorepo, add it as a dependency in the package.json file:
+#### `useKGDesigner(options: UseKGOptions)`
 
-```json
-"dependencies": {
-  "@eloquent/kg": "*"
-}
+```tsx
+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)`
+
+```tsx
+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:
+
+```ts
+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
+
+```ts
+// 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:
+
+```ts
+// 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
+
+```bash
+# Build the package
+pnpm build
+
+# Run type checking
+pnpm typecheck
+
+# Watch mode
+pnpm dev
+```
+
+## License
+
+Private - Eloquent Platform