@grackle-ai/knowledge-core 0.63.0

package/dist/chunker.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pluggable chunker interface for splitting content into embeddable pieces.
+ *
+ * @module
+ */
+/** A chunk of content produced by a {@link Chunker}. */
+export interface Chunk {
+    /** The text content of this chunk. */
+    text: string;
+    /** Zero-based index of this chunk within the source content. */
+    index: number;
+    /** Optional metadata carried through from the source or added by the chunker. */
+    metadata?: Record<string, unknown>;
+}
+/** Splits content into chunks suitable for embedding. */
+export interface Chunker {
+    /** Split content into one or more chunks. */
+    chunk(content: string, metadata?: Record<string, unknown>): Chunk[];
+}
+//# sourceMappingURL=chunker.d.ts.map

package/dist/chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.d.ts","sourceRoot":"","sources":["../src/chunker.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wDAAwD;AACxD,MAAM,WAAW,KAAK;IACpB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,yDAAyD;AACzD,MAAM,WAAW,OAAO;IACtB,6CAA6C;IAC7C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,EAAE,CAAC;CACrE"}

package/dist/chunker.js

@@ -0,0 +1,7 @@
+/**
+ * Pluggable chunker interface for splitting content into embeddable pieces.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=chunker.js.map

package/dist/chunker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.js","sourceRoot":"","sources":["../src/chunker.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/client.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Neo4j driver singleton — connection management, health checks, and shutdown.
+ *
+ * Follows the same singleton pattern as `packages/server/src/db.ts`.
+ * Call {@link openNeo4j} once at startup, then use {@link getDriver} or
+ * {@link getSession} for queries, and {@link closeNeo4j} on shutdown.
+ *
+ * @module
+ */
+import { type Driver, type Session } from "neo4j-driver";
+/** Configuration for the Neo4j connection. */
+export interface Neo4jClientConfig {
+    /** Bolt URL (default: bolt://127.0.0.1:7687). */
+    url?: string;
+    /** Username (default: neo4j). */
+    username?: string;
+    /** Password (default: grackle-dev). */
+    password?: string;
+    /** Neo4j database name (default: neo4j). */
+    database?: string;
+}
+/**
+ * Open a connection to Neo4j.
+ *
+ * Reads configuration from environment variables first, then from the
+ * provided {@link Neo4jClientConfig}, then from built-in defaults.
+ *
+ * Idempotent — returns silently if a connection is already open.
+ *
+ * | Env Variable             | Fallback            |
+ * |--------------------------|---------------------|
+ * | `GRACKLE_NEO4J_URL`      | `config.url`        |
+ * | `GRACKLE_NEO4J_USER`     | `config.username`   |
+ * | `GRACKLE_NEO4J_PASSWORD`  | `config.password`   |
+ * | `GRACKLE_NEO4J_DATABASE` | `config.database`   |
+ */
+export declare function openNeo4j(config?: Neo4jClientConfig): Promise<void>;
+/**
+ * Get a Neo4j session for running queries.
+ *
+ * Sessions are lightweight and should be short-lived — open one per
+ * logical unit of work and close it when done.
+ *
+ * @throws If {@link openNeo4j} has not been called.
+ */
+export declare function getSession(): Session;
+/**
+ * Get the raw Neo4j driver instance.
+ *
+ * Prefer {@link getSession} for most use cases. Use the driver directly
+ * only when you need `driver.executeQuery()` for simple one-shot queries.
+ *
+ * @throws If {@link openNeo4j} has not been called.
+ */
+export declare function getDriver(): Driver;
+/**
+ * Check Neo4j connectivity.
+ *
+ * @returns `true` if the connection is healthy, `false` otherwise.
+ */
+export declare function healthCheck(): Promise<boolean>;
+/**
+ * Gracefully close the Neo4j connection and release resources.
+ *
+ * Safe to call multiple times or when no connection is open.
+ */
+export declare function closeNeo4j(): Promise<void>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAc,EAAE,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAehE,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAmBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBnE;AAgDD;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAKpC;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAKlC;AAED;;;;GAIG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAUpD;AAED;;;;GAIG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAYhD"}

package/dist/client.js

@@ -0,0 +1,150 @@
+/**
+ * Neo4j driver singleton — connection management, health checks, and shutdown.
+ *
+ * Follows the same singleton pattern as `packages/server/src/db.ts`.
+ * Call {@link openNeo4j} once at startup, then use {@link getDriver} or
+ * {@link getSession} for queries, and {@link closeNeo4j} on shutdown.
+ *
+ * @module
+ */
+import neo4j from "neo4j-driver";
+import { logger } from "./logger.js";
+import { DEFAULT_NEO4J_URL, DEFAULT_NEO4J_USER, DEFAULT_NEO4J_PASSWORD, DEFAULT_NEO4J_DATABASE, NEO4J_MAX_POOL_SIZE, NEO4J_CONNECTION_ACQUISITION_TIMEOUT, } from "./constants.js";
+// ---------------------------------------------------------------------------
+// Singleton state
+// ---------------------------------------------------------------------------
+/** Module-level singleton driver instance. */
+let driver;
+/** Promise that resolves when initialization is complete (guards concurrent calls). */
+let initPromise;
+/** The database name used when creating sessions. */
+let databaseName = DEFAULT_NEO4J_DATABASE;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Open a connection to Neo4j.
+ *
+ * Reads configuration from environment variables first, then from the
+ * provided {@link Neo4jClientConfig}, then from built-in defaults.
+ *
+ * Idempotent — returns silently if a connection is already open.
+ *
+ * | Env Variable             | Fallback            |
+ * |--------------------------|---------------------|
+ * | `GRACKLE_NEO4J_URL`      | `config.url`        |
+ * | `GRACKLE_NEO4J_USER`     | `config.username`   |
+ * | `GRACKLE_NEO4J_PASSWORD`  | `config.password`   |
+ * | `GRACKLE_NEO4J_DATABASE` | `config.database`   |
+ */
+export function openNeo4j(config) {
+    if (driver) {
+        return Promise.resolve();
+    }
+    // Guard against concurrent calls: if an init is already in flight, await it.
+    if (initPromise) {
+        return initPromise;
+    }
+    // Wrap the async work so initPromise is cleared synchronously after settlement.
+    initPromise = doOpen(config).finally(() => {
+        initPromise = undefined;
+    });
+    return initPromise;
+}
+/**
+ * Internal init logic — separated so {@link openNeo4j} can guard concurrency
+ * with a shared promise.
+ */
+async function doOpen(config) {
+    const url = process.env.GRACKLE_NEO4J_URL || config?.url || DEFAULT_NEO4J_URL;
+    const username = process.env.GRACKLE_NEO4J_USER || config?.username || DEFAULT_NEO4J_USER;
+    const explicitPassword = process.env.GRACKLE_NEO4J_PASSWORD || config?.password;
+    if (!explicitPassword && process.env.NODE_ENV === "production") {
+        throw new Error("GRACKLE_NEO4J_PASSWORD must be set in production. " +
+            "Refusing to use the default development password.");
+    }
+    const password = explicitPassword || DEFAULT_NEO4J_PASSWORD;
+    databaseName =
+        process.env.GRACKLE_NEO4J_DATABASE ||
+            config?.database ||
+            DEFAULT_NEO4J_DATABASE;
+    logger.info({ url, database: databaseName }, "Connecting to Neo4j");
+    const newDriver = neo4j.driver(url, neo4j.auth.basic(username, password), {
+        disableLosslessIntegers: true,
+        maxConnectionPoolSize: NEO4J_MAX_POOL_SIZE,
+        connectionAcquisitionTimeout: NEO4J_CONNECTION_ACQUISITION_TIMEOUT,
+    });
+    try {
+        await newDriver.verifyConnectivity({ database: databaseName });
+        logger.info("Neo4j connectivity verified");
+    }
+    catch (error) {
+        await newDriver.close().catch(() => { });
+        throw new Error(`Failed to connect to Neo4j at ${url}: ${error instanceof Error ? error.message : String(error)}. ` +
+            "Ensure Neo4j is running and the credentials are correct.", { cause: error });
+    }
+    driver = newDriver;
+}
+/**
+ * Get a Neo4j session for running queries.
+ *
+ * Sessions are lightweight and should be short-lived — open one per
+ * logical unit of work and close it when done.
+ *
+ * @throws If {@link openNeo4j} has not been called.
+ */
+export function getSession() {
+    if (!driver) {
+        throw new Error("Neo4j not initialized. Call openNeo4j() first.");
+    }
+    return driver.session({ database: databaseName });
+}
+/**
+ * Get the raw Neo4j driver instance.
+ *
+ * Prefer {@link getSession} for most use cases. Use the driver directly
+ * only when you need `driver.executeQuery()` for simple one-shot queries.
+ *
+ * @throws If {@link openNeo4j} has not been called.
+ */
+export function getDriver() {
+    if (!driver) {
+        throw new Error("Neo4j not initialized. Call openNeo4j() first.");
+    }
+    return driver;
+}
+/**
+ * Check Neo4j connectivity.
+ *
+ * @returns `true` if the connection is healthy, `false` otherwise.
+ */
+export async function healthCheck() {
+    if (!driver) {
+        return false;
+    }
+    try {
+        await driver.verifyConnectivity({ database: databaseName });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Gracefully close the Neo4j connection and release resources.
+ *
+ * Safe to call multiple times or when no connection is open.
+ */
+export async function closeNeo4j() {
+    // Wait for any in-flight initialization to settle before closing.
+    if (initPromise) {
+        await initPromise.catch(() => { });
+    }
+    const current = driver;
+    if (current) {
+        driver = undefined;
+        logger.info("Closing Neo4j connection");
+        await current.close();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/constants.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Constants for the Neo4j knowledge graph subsystem.
+ *
+ * @module
+ */
+/** Default Neo4j Bolt connection URL. */
+export declare const DEFAULT_NEO4J_URL: string;
+/** Default Neo4j username. */
+export declare const DEFAULT_NEO4J_USER: string;
+/**
+ * Default Neo4j password (development only; production should always override).
+ *
+ * Not re-exported from the package barrel to avoid leaking a credential
+ * constant in the public API.
+ *
+ * @internal
+ */
+export declare const DEFAULT_NEO4J_PASSWORD: string;
+/** Default Neo4j database name. */
+export declare const DEFAULT_NEO4J_DATABASE: string;
+/** Maximum number of connections in the Neo4j driver pool. */
+export declare const NEO4J_MAX_POOL_SIZE: number;
+/** Timeout (ms) for acquiring a connection from the Neo4j pool. */
+export declare const NEO4J_CONNECTION_ACQUISITION_TIMEOUT: number;
+/** Neo4j node label applied to all knowledge graph nodes. */
+export declare const NODE_LABEL: string;
+/** Name of the vector index on knowledge node embeddings. */
+export declare const VECTOR_INDEX_NAME: string;
+/** Dimensionality of the embedding vectors (OpenAI text-embedding-3-small). */
+export declare const EMBEDDING_DIMENSIONS: number;
+/** Similarity function used by the vector index. */
+export declare const VECTOR_SIMILARITY_FUNCTION: string;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yCAAyC;AACzC,eAAO,MAAM,iBAAiB,EAAE,MAAgC,CAAC;AAEjE,8BAA8B;AAC9B,eAAO,MAAM,kBAAkB,EAAE,MAAgB,CAAC;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAsB,CAAC;AAE5D,mCAAmC;AACnC,eAAO,MAAM,sBAAsB,EAAE,MAAgB,CAAC;AAEtD,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,EAAE,MAAW,CAAC;AAE9C,mEAAmE;AACnE,eAAO,MAAM,oCAAoC,EAAE,MAAe,CAAC;AAEnE,6DAA6D;AAC7D,eAAO,MAAM,UAAU,EAAE,MAAwB,CAAC;AAElD,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB,EAAE,MAAoC,CAAC;AAErE,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,EAAE,MAAa,CAAC;AAEjD,oDAAoD;AACpD,eAAO,MAAM,0BAA0B,EAAE,MAAiB,CAAC"}

package/dist/constants.js

@@ -0,0 +1,33 @@
+/**
+ * Constants for the Neo4j knowledge graph subsystem.
+ *
+ * @module
+ */
+/** Default Neo4j Bolt connection URL. */
+export const DEFAULT_NEO4J_URL = "bolt://127.0.0.1:7687";
+/** Default Neo4j username. */
+export const DEFAULT_NEO4J_USER = "neo4j";
+/**
+ * Default Neo4j password (development only; production should always override).
+ *
+ * Not re-exported from the package barrel to avoid leaking a credential
+ * constant in the public API.
+ *
+ * @internal
+ */
+export const DEFAULT_NEO4J_PASSWORD = "grackle-dev";
+/** Default Neo4j database name. */
+export const DEFAULT_NEO4J_DATABASE = "neo4j";
+/** Maximum number of connections in the Neo4j driver pool. */
+export const NEO4J_MAX_POOL_SIZE = 50;
+/** Timeout (ms) for acquiring a connection from the Neo4j pool. */
+export const NEO4J_CONNECTION_ACQUISITION_TIMEOUT = 30_000;
+/** Neo4j node label applied to all knowledge graph nodes. */
+export const NODE_LABEL = "KnowledgeNode";
+/** Name of the vector index on knowledge node embeddings. */
+export const VECTOR_INDEX_NAME = "knowledge_embedding_index";
+/** Dimensionality of the embedding vectors (OpenAI text-embedding-3-small). */
+export const EMBEDDING_DIMENSIONS = 1536;
+/** Similarity function used by the vector index. */
+export const VECTOR_SIMILARITY_FUNCTION = "cosine";
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yCAAyC;AACzC,MAAM,CAAC,MAAM,iBAAiB,GAAW,uBAAuB,CAAC;AAEjE,8BAA8B;AAC9B,MAAM,CAAC,MAAM,kBAAkB,GAAW,OAAO,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAW,aAAa,CAAC;AAE5D,mCAAmC;AACnC,MAAM,CAAC,MAAM,sBAAsB,GAAW,OAAO,CAAC;AAEtD,8DAA8D;AAC9D,MAAM,CAAC,MAAM,mBAAmB,GAAW,EAAE,CAAC;AAE9C,mEAAmE;AACnE,MAAM,CAAC,MAAM,oCAAoC,GAAW,MAAM,CAAC;AAEnE,6DAA6D;AAC7D,MAAM,CAAC,MAAM,UAAU,GAAW,eAAe,CAAC;AAElD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,iBAAiB,GAAW,2BAA2B,CAAC;AAErE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAW,IAAI,CAAC;AAEjD,oDAAoD;AACpD,MAAM,CAAC,MAAM,0BAA0B,GAAW,QAAQ,CAAC"}

package/dist/edge-store.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Edge CRUD operations for the knowledge graph.
+ *
+ * Provides create and remove operations for typed relationships between
+ * {@link KnowledgeNode} instances, backed by Neo4j.
+ *
+ * @module
+ */
+import { type EdgeType, type KnowledgeEdge } from "./types.js";
+/**
+ * Create a typed edge between two nodes.
+ *
+ * @param fromId - Source node ID.
+ * @param toId - Target node ID.
+ * @param type - Relationship type (must be a valid {@link EdgeType}).
+ * @param metadata - Optional metadata to attach to the edge.
+ * @returns The created edge.
+ * @throws If either node does not exist.
+ * @throws If the edge type is invalid.
+ */
+export declare function createEdge(fromId: string, toId: string, type: EdgeType, metadata?: Record<string, unknown>): Promise<KnowledgeEdge>;
+/**
+ * Remove an edge between two nodes.
+ *
+ * @param fromId - Source node ID.
+ * @param toId - Target node ID.
+ * @param type - Relationship type to remove.
+ * @returns `true` if an edge was removed, `false` if no matching edge existed.
+ * @throws If the edge type is invalid.
+ */
+export declare function removeEdge(fromId: string, toId: string, type: EdgeType): Promise<boolean>;
+//# sourceMappingURL=edge-store.d.ts.map

package/dist/edge-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-store.d.ts","sourceRoot":"","sources":["../src/edge-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAa,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAwD1E;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,EACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,aAAa,CAAC,CAiDxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,OAAO,CAAC,CAsBlB"}

package/dist/edge-store.js

@@ -0,0 +1,145 @@
+/**
+ * Edge CRUD operations for the knowledge graph.
+ *
+ * Provides create and remove operations for typed relationships between
+ * {@link KnowledgeNode} instances, backed by Neo4j.
+ *
+ * @module
+ */
+import { getSession } from "./client.js";
+import { logger } from "./logger.js";
+import { NODE_LABEL } from "./constants.js";
+import { EDGE_TYPE } from "./types.js";
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/** Known edge type values for runtime validation. */
+const VALID_EDGE_TYPES = new Set(Object.values(EDGE_TYPE));
+/**
+ * Assert that a string is a valid {@link EdgeType}.
+ *
+ * @throws If the value is not a known edge type.
+ */
+function assertValidEdgeType(type) {
+    if (!VALID_EDGE_TYPES.has(type)) {
+        throw new Error(`Invalid edge type: "${type}". Must be one of: ${[...VALID_EDGE_TYPES].join(", ")}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Cypher builders
+// ---------------------------------------------------------------------------
+/**
+ * Build the Cypher query for creating an edge of a given type.
+ *
+ * Relationship types cannot be parameterized in Cypher, so the type is
+ * interpolated directly. This is safe because {@link assertValidEdgeType}
+ * ensures the value comes from the closed {@link EdgeType} union.
+ */
+function buildCreateEdgeCypher(edgeType) {
+    return [
+        `MATCH (a:${NODE_LABEL} {id: $fromId}), (b:${NODE_LABEL} {id: $toId})`,
+        `CREATE (a)-[r:${edgeType} {metadata: $metadata, createdAt: $createdAt}]->(b)`,
+        `RETURN a.id AS fromId, b.id AS toId, type(r) AS type, r.metadata AS metadata, r.createdAt AS createdAt`,
+    ].join("\n");
+}
+/**
+ * Build the Cypher query for removing an edge of a given type.
+ */
+function buildRemoveEdgeCypher(edgeType) {
+    return [
+        `MATCH (a:${NODE_LABEL} {id: $fromId})-[r:${edgeType}]->(b:${NODE_LABEL} {id: $toId})`,
+        `DELETE r`,
+        `RETURN count(r) AS deleted`,
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Create a typed edge between two nodes.
+ *
+ * @param fromId - Source node ID.
+ * @param toId - Target node ID.
+ * @param type - Relationship type (must be a valid {@link EdgeType}).
+ * @param metadata - Optional metadata to attach to the edge.
+ * @returns The created edge.
+ * @throws If either node does not exist.
+ * @throws If the edge type is invalid.
+ */
+export async function createEdge(fromId, toId, type, metadata) {
+    assertValidEdgeType(type);
+    const createdAt = new Date().toISOString();
+    const metadataStr = metadata !== undefined ? JSON.stringify(metadata) : null;
+    const session = getSession();
+    try {
+        const result = await session.run(buildCreateEdgeCypher(type), {
+            fromId,
+            toId,
+            metadata: metadataStr,
+            createdAt,
+        });
+        if (result.records.length === 0) {
+            throw new Error(`Cannot create edge: one or both nodes not found (fromId=${fromId}, toId=${toId})`);
+        }
+        const record = result.records[0];
+        let parsedMetadata;
+        const rawMetadata = record.get("metadata");
+        if (rawMetadata !== null) {
+            try {
+                parsedMetadata = JSON.parse(rawMetadata);
+            }
+            catch {
+                parsedMetadata = undefined;
+            }
+        }
+        logger.debug({ fromId, toId, type }, "Created edge");
+        return {
+            fromId: record.get("fromId"),
+            toId: record.get("toId"),
+            type: record.get("type"),
+            metadata: parsedMetadata,
+            createdAt: record.get("createdAt"),
+        };
+    }
+    finally {
+        try {
+            await session.close();
+        }
+        catch (closeError) {
+            logger.warn({ err: closeError }, "Failed to close session after createEdge");
+        }
+    }
+}
+/**
+ * Remove an edge between two nodes.
+ *
+ * @param fromId - Source node ID.
+ * @param toId - Target node ID.
+ * @param type - Relationship type to remove.
+ * @returns `true` if an edge was removed, `false` if no matching edge existed.
+ * @throws If the edge type is invalid.
+ */
+export async function removeEdge(fromId, toId, type) {
+    assertValidEdgeType(type);
+    const session = getSession();
+    try {
+        const result = await session.run(buildRemoveEdgeCypher(type), {
+            fromId,
+            toId,
+        });
+        const deleted = result.records[0]?.get("deleted");
+        if (deleted > 0) {
+            logger.debug({ fromId, toId, type }, "Removed edge");
+        }
+        return deleted > 0;
+    }
+    finally {
+        try {
+            await session.close();
+        }
+        catch (closeError) {
+            logger.warn({ err: closeError }, "Failed to close session after removeEdge");
+        }
+    }
+}
+//# sourceMappingURL=edge-store.js.map

package/dist/edge-store.js.map

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

package/dist/embedder.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pluggable embedder interface for converting text into vector embeddings.
+ *
+ * @module
+ */
+/** A single embedding result pairing input text with its vector. */
+export interface EmbeddingResult {
+    /** The input text that was embedded. */
+    text: string;
+    /** The embedding vector (array of floats). */
+    vector: number[];
+}
+/** Configuration for creating an {@link Embedder}. */
+export interface EmbedderOptions {
+    /** HuggingFace model ID (e.g., `"Xenova/all-MiniLM-L6-v2"`). */
+    modelId?: string;
+    /** Expected embedding dimensions. Used for validation when set. */
+    dimensions?: number;
+}
+/** Converts text into embedding vectors for semantic search and similarity. */
+export interface Embedder {
+    /** Embed a single text string. */
+    embed(text: string): Promise<EmbeddingResult>;
+    /** Embed multiple texts in batch. */
+    embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+    /**
+     * The dimensionality of vectors produced by this embedder.
+     *
+     * When using a custom model without specifying `dimensions` in options,
+     * this value is `0` until the first embedding is computed. A value of `0`
+     * means the true dimensions are not yet known.
+     */
+    readonly dimensions: number;
+}
+//# sourceMappingURL=embedder.d.ts.map

package/dist/embedder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.d.ts","sourceRoot":"","sources":["../src/embedder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+EAA+E;AAC/E,MAAM,WAAW,QAAQ;IACvB,kCAAkC;IAClC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9C,qCAAqC;IACrC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IACxD;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B"}

package/dist/embedder.js

@@ -0,0 +1,7 @@
+/**
+ * Pluggable embedder interface for converting text into vector embeddings.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=embedder.js.map

package/dist/embedder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.js","sourceRoot":"","sources":["../src/embedder.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/expand.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Graph expansion — traverse the knowledge graph from a starting node
+ * to discover connected nodes within N hops.
+ *
+ * @module
+ */
+import type { KnowledgeNode, KnowledgeEdge, EdgeType } from "./types.js";
+import type { SearchResult } from "./search.js";
+/** Options for graph expansion. */
+export interface ExpandOptions {
+    /** Max traversal depth (default 1). */
+    depth?: number;
+    /** Only follow edges of these types. If empty/undefined, follow all. */
+    edgeTypes?: EdgeType[];
+}
+/** Result of a graph expansion: the subgraph reachable from the starting node(s). */
+export interface ExpansionResult {
+    /** All neighbor nodes found (deduplicated), excluding the start node(s). */
+    nodes: KnowledgeNode[];
+    /** All edges traversed. */
+    edges: KnowledgeEdge[];
+}
+/**
+ * Expand a single node: return its neighbors within N hops.
+ *
+ * @param nodeId - The starting node ID.
+ * @param options - Traversal depth and optional edge type filter.
+ * @returns Neighbor nodes and traversed edges (deduplicated).
+ */
+export declare function expandNode(nodeId: string, options?: ExpandOptions): Promise<ExpansionResult>;
+/**
+ * Expand search results: return neighbors of all result nodes, deduplicated.
+ *
+ * Runs {@link expandNode} for each search result and merges the subgraphs,
+ * excluding the original search result nodes from the neighbor list.
+ *
+ * @param results - Search results from {@link knowledgeSearch}.
+ * @param options - Traversal depth and optional edge type filter.
+ * @returns Combined neighbor nodes and edges from all start nodes.
+ */
+export declare function expandResults(results: SearchResult[], options?: ExpandOptions): Promise<ExpansionResult>;
+//# sourceMappingURL=expand.d.ts.map

package/dist/expand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expand.d.ts","sourceRoot":"","sources":["../src/expand.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,2BAA2B;IAC3B,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAiFD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,eAAe,CAAC,CA8C1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,eAAe,CAAC,CAiB1B"}