@grackle-ai/knowledge 0.58.0 → 0.59.0

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://localhost: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://localhost: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/index.d.ts

@@ -1,16 +1,23 @@
 /**
  * Knowledge graph subsystem for Grackle.
  *
- * Provides pluggable text embedding, content chunking, and an ingestion
- * pipeline so that agents can share and reuse contextual information
- * across sessions.
+ * Provides pluggable text embedding, content chunking, an ingestion
+ * pipeline, and structured knowledge storage and retrieval via Neo4j,
+ * so that agents can share and reuse contextual information across sessions.
  *
  * @packageDocumentation
  */
+export { openNeo4j, closeNeo4j, healthCheck, getSession, getDriver } from "./client.js";
+export type { Neo4jClientConfig } from "./client.js";
+export { initSchema, SCHEMA_STATEMENTS } from "./schema.js";
+export * from "./types.js";
+export { DEFAULT_NEO4J_URL, DEFAULT_NEO4J_USER, DEFAULT_NEO4J_DATABASE, NEO4J_MAX_POOL_SIZE, NEO4J_CONNECTION_ACQUISITION_TIMEOUT, NODE_LABEL, VECTOR_INDEX_NAME, EMBEDDING_DIMENSIONS, VECTOR_SIMILARITY_FUNCTION, } from "./constants.js";
 export type { Embedder, EmbedderOptions, EmbeddingResult } from "./embedder.js";
 export { createLocalEmbedder } from "./local-embedder.js";
 export type { Chunk, Chunker } from "./chunker.js";
 export { createPassThroughChunker } from "./pass-through-chunker.js";
 export type { EmbeddedChunk } from "./ingest.js";
 export { ingest } from "./ingest.js";
+export type { TranscriptChunkerOptions } from "./transcript-chunker.js";
+export { createTranscriptChunker } from "./transcript-chunker.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxF,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC5D,cAAc,YAAY,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,oCAAoC,EACpC,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -1,13 +1,18 @@
 /**
  * Knowledge graph subsystem for Grackle.
  *
- * Provides pluggable text embedding, content chunking, and an ingestion
- * pipeline so that agents can share and reuse contextual information
- * across sessions.
+ * Provides pluggable text embedding, content chunking, an ingestion
+ * pipeline, and structured knowledge storage and retrieval via Neo4j,
+ * so that agents can share and reuse contextual information across sessions.
  *
  * @packageDocumentation
  */
+export { openNeo4j, closeNeo4j, healthCheck, getSession, getDriver } from "./client.js";
+export { initSchema, SCHEMA_STATEMENTS } from "./schema.js";
+export * from "./types.js";
+export { DEFAULT_NEO4J_URL, DEFAULT_NEO4J_USER, DEFAULT_NEO4J_DATABASE, NEO4J_MAX_POOL_SIZE, NEO4J_CONNECTION_ACQUISITION_TIMEOUT, NODE_LABEL, VECTOR_INDEX_NAME, EMBEDDING_DIMENSIONS, VECTOR_SIMILARITY_FUNCTION, } from "./constants.js";
 export { createLocalEmbedder } from "./local-embedder.js";
 export { createPassThroughChunker } from "./pass-through-chunker.js";
 export { ingest } from "./ingest.js";
+export { createTranscriptChunker } from "./transcript-chunker.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAErE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExF,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC5D,cAAc,YAAY,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,oCAAoC,EACpC,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAErE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Structured logger for the knowledge graph subsystem.
+ *
+ * @module
+ */
+import { type Logger } from "pino";
+/** Pino logger instance for the knowledge package. */
+export declare const logger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAa,EAAE,KAAK,MAAM,EAAE,MAAM,MAAM,CAAC;AAEzC,sDAAsD;AACtD,eAAO,MAAM,MAAM,EAAE,MAOnB,CAAC"}

package/dist/logger.js

@@ -0,0 +1,15 @@
+/**
+ * Structured logger for the knowledge graph subsystem.
+ *
+ * @module
+ */
+import pino from "pino";
+/** Pino logger instance for the knowledge package. */
+export const logger = pino({
+    name: "grackle-knowledge",
+    level: process.env.LOG_LEVEL || "info",
+    transport: process.env.NODE_ENV !== "production"
+        ? { target: "pino/file", options: { destination: 1 } }
+        : undefined,
+});
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,IAAqB,MAAM,MAAM,CAAC;AAEzC,sDAAsD;AACtD,MAAM,CAAC,MAAM,MAAM,GAAW,IAAI,CAAC;IACjC,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM;IACtC,SAAS,EACP,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;QACnC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,EAAE;QACtD,CAAC,CAAC,SAAS;CAChB,CAAC,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Neo4j schema initialization — constraints, indexes, and vector index.
+ *
+ * All statements use `IF NOT EXISTS` for idempotency and are safe to run
+ * on every application startup.
+ *
+ * @module
+ */
+/**
+ * Cypher statements for schema initialization.
+ *
+ * Exported so tests can verify the exact statements that will be executed.
+ */
+export declare const SCHEMA_STATEMENTS: Record<string, string>;
+/**
+ * Initialize the Neo4j schema: constraints, property indexes, and the
+ * vector index.
+ *
+ * All statements are idempotent (`IF NOT EXISTS`). Call once at startup
+ * after {@link openNeo4j}.
+ */
+export declare function initSchema(): Promise<void>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA4BpD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAuBhD"}

package/dist/schema.js

@@ -0,0 +1,73 @@
+/**
+ * Neo4j schema initialization — constraints, indexes, and vector index.
+ *
+ * All statements use `IF NOT EXISTS` for idempotency and are safe to run
+ * on every application startup.
+ *
+ * @module
+ */
+import { getSession } from "./client.js";
+import { logger } from "./logger.js";
+import { NODE_LABEL, VECTOR_INDEX_NAME, EMBEDDING_DIMENSIONS, VECTOR_SIMILARITY_FUNCTION, } from "./constants.js";
+/**
+ * Cypher statements for schema initialization.
+ *
+ * Exported so tests can verify the exact statements that will be executed.
+ */
+export const SCHEMA_STATEMENTS = {
+    /** Uniqueness constraint on node ID. */
+    UNIQUE_NODE_ID: `CREATE CONSTRAINT knowledge_node_id_unique IF NOT EXISTS
+    FOR (n:${NODE_LABEL}) REQUIRE n.id IS UNIQUE`,
+    /** Index on the kind property for efficient filtering. */
+    INDEX_KIND: `CREATE INDEX knowledge_node_kind IF NOT EXISTS
+    FOR (n:${NODE_LABEL}) ON (n.kind)`,
+    /** Index on workspaceId for scoped queries. */
+    INDEX_WORKSPACE: `CREATE INDEX knowledge_node_workspace IF NOT EXISTS
+    FOR (n:${NODE_LABEL}) ON (n.workspaceId)`,
+    /** Composite index for reference node lookups by source. */
+    INDEX_SOURCE: `CREATE INDEX knowledge_node_source IF NOT EXISTS
+    FOR (n:${NODE_LABEL}) ON (n.sourceType, n.sourceId)`,
+    /** Vector index for embedding similarity search. */
+    VECTOR_INDEX: [
+        `CREATE VECTOR INDEX ${VECTOR_INDEX_NAME} IF NOT EXISTS`,
+        `FOR (n:${NODE_LABEL}) ON (n.embedding)`,
+        `OPTIONS {`,
+        `  indexConfig: {`,
+        `    \`vector.dimensions\`: ${EMBEDDING_DIMENSIONS},`,
+        `    \`vector.similarity_function\`: '${VECTOR_SIMILARITY_FUNCTION}'`,
+        `  }`,
+        `}`,
+    ].join("\n"),
+};
+/**
+ * Initialize the Neo4j schema: constraints, property indexes, and the
+ * vector index.
+ *
+ * All statements are idempotent (`IF NOT EXISTS`). Call once at startup
+ * after {@link openNeo4j}.
+ */
+export async function initSchema() {
+    const session = getSession();
+    try {
+        for (const [name, cypher] of Object.entries(SCHEMA_STATEMENTS)) {
+            logger.debug({ statement: name }, "Running schema statement");
+            try {
+                await session.run(cypher);
+            }
+            catch (error) {
+                logger.error({ err: error, statement: name }, "Schema statement failed");
+                throw new Error(`Schema statement "${name}" failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+            }
+        }
+        logger.info("Knowledge graph schema initialized");
+    }
+    finally {
+        try {
+            await session.close();
+        }
+        catch (closeError) {
+            logger.warn({ err: closeError }, "Failed to close Neo4j session after schema initialization");
+        }
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA2B;IACvD,wCAAwC;IACxC,cAAc,EAAE;aACL,UAAU,0BAA0B;IAE/C,0DAA0D;IAC1D,UAAU,EAAE;aACD,UAAU,eAAe;IAEpC,+CAA+C;IAC/C,eAAe,EAAE;aACN,UAAU,sBAAsB;IAE3C,4DAA4D;IAC5D,YAAY,EAAE;aACH,UAAU,iCAAiC;IAEtD,oDAAoD;IACpD,YAAY,EAAE;QACZ,uBAAuB,iBAAiB,gBAAgB;QACxD,UAAU,UAAU,oBAAoB;QACxC,WAAW;QACX,kBAAkB;QAClB,8BAA8B,oBAAoB,GAAG;QACrD,wCAAwC,0BAA0B,GAAG;QACrE,KAAK;QACL,GAAG;KACJ,CAAC,IAAI,CAAC,IAAI,CAAC;CACb,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,IAAI,CAAC;QACH,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,CAAC;YAC/D,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,0BAA0B,CAAC,CAAC;YAC9D,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC5B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,yBAAyB,CAAC,CAAC;gBACzE,MAAM,IAAI,KAAK,CACb,qBAAqB,IAAI,aAAa,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAC9F,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;YACJ,CAAC;QACH,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;IACpD,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;QAAC,OAAO,UAAU,EAAE,CAAC;YACpB,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,2DAA2D,CAAC,CAAC;QAChG,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/transcript-chunker.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Session transcript chunker that splits JSONL session logs by conversation turn.
+ *
+ * Accepts the raw JSONL content of a session's `stream.jsonl` file and groups
+ * events into semantic turns (user input → agent response) for embedding.
+ *
+ * @module
+ */
+import type { Chunker } from "./chunker.js";
+/** Options for the session transcript chunker. */
+export interface TranscriptChunkerOptions {
+    /** Max characters per chunk before splitting (default 4000). */
+    maxChunkSize?: number;
+    /** Event types to skip (default: status, signal, usage, system). */
+    skipEventTypes?: string[];
+}
+/**
+ * Create a chunker that splits JSONL session transcripts by conversation turn.
+ *
+ * A "turn" starts at a `user_input` event and includes all subsequent events
+ * until the next `user_input`. Events before the first `user_input` are grouped
+ * into an initial turn (turn 0). Turns exceeding {@link TranscriptChunkerOptions.maxChunkSize}
+ * are split into sub-chunks.
+ *
+ * @param options - Optional chunker configuration.
+ * @returns A {@link Chunker} for session transcript JSONL content.
+ */
+export declare function createTranscriptChunker(options?: TranscriptChunkerOptions): Chunker;
+//# sourceMappingURL=transcript-chunker.d.ts.map

package/dist/transcript-chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript-chunker.d.ts","sourceRoot":"","sources":["../src/transcript-chunker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAS,OAAO,EAAE,MAAM,cAAc,CAAC;AAgBnD,kDAAkD;AAClD,MAAM,WAAW,wBAAwB;IACvC,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAmBD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAkDnF"}

package/dist/transcript-chunker.js

@@ -0,0 +1,142 @@
+/**
+ * Session transcript chunker that splits JSONL session logs by conversation turn.
+ *
+ * Accepts the raw JSONL content of a session's `stream.jsonl` file and groups
+ * events into semantic turns (user input → agent response) for embedding.
+ *
+ * @module
+ */
+/** Default event types that are excluded from chunks. */
+const DEFAULT_SKIP_TYPES = ["status", "signal", "usage", "system"];
+/** Default maximum characters per chunk. */
+const DEFAULT_MAX_CHUNK_SIZE = 4000;
+/** Labels used when rendering events into readable text. */
+const EVENT_LABELS = {
+    user_input: "User",
+    text: "Assistant",
+    tool_use: "Tool",
+    tool_result: "Result",
+    error: "Error",
+    finding: "Finding",
+    subtask_create: "Subtask",
+};
+/**
+ * Create a chunker that splits JSONL session transcripts by conversation turn.
+ *
+ * A "turn" starts at a `user_input` event and includes all subsequent events
+ * until the next `user_input`. Events before the first `user_input` are grouped
+ * into an initial turn (turn 0). Turns exceeding {@link TranscriptChunkerOptions.maxChunkSize}
+ * are split into sub-chunks.
+ *
+ * @param options - Optional chunker configuration.
+ * @returns A {@link Chunker} for session transcript JSONL content.
+ */
+export function createTranscriptChunker(options) {
+    const maxChunkSize = options?.maxChunkSize ?? DEFAULT_MAX_CHUNK_SIZE;
+    const skipTypes = new Set(options?.skipEventTypes ?? DEFAULT_SKIP_TYPES);
+    return {
+        chunk(content, metadata) {
+            const entries = parseJsonl(content);
+            if (entries.length === 0) {
+                return [];
+            }
+            // Group on all entries first so user_input boundaries are preserved
+            // even if user_input is in skipTypes. Filter when rendering.
+            const turns = groupByTurn(entries);
+            const chunks = [];
+            for (let turnIndex = 0; turnIndex < turns.length; turnIndex++) {
+                const turnEntries = turns[turnIndex];
+                const visible = turnEntries.filter((e) => !skipTypes.has(e.type));
+                if (visible.length === 0) {
+                    continue;
+                }
+                const text = renderTurn(visible);
+                const timestamps = visible.map((e) => e.timestamp);
+                const eventTypes = [...new Set(visible.map((e) => e.type))];
+                const turnMetadata = {
+                    ...metadata,
+                    turnIndex,
+                    timestampStart: timestamps[0],
+                    timestampEnd: timestamps[timestamps.length - 1],
+                    eventTypes,
+                };
+                if (text.length <= maxChunkSize) {
+                    chunks.push({ text, index: chunks.length, metadata: turnMetadata });
+                }
+                else {
+                    const subChunks = splitText(text, maxChunkSize);
+                    for (const subChunk of subChunks) {
+                        chunks.push({ text: subChunk, index: chunks.length, metadata: turnMetadata });
+                    }
+                }
+            }
+            return chunks;
+        },
+    };
+}
+/** Parse a JSONL string into an array of log entries, skipping malformed lines. */
+function parseJsonl(content) {
+    const entries = [];
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        try {
+            entries.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return entries;
+}
+/** Group log entries into turns, splitting on `user_input` events. */
+function groupByTurn(entries) {
+    const turns = [];
+    let current = [];
+    for (const entry of entries) {
+        if (entry.type === "user_input" && current.length > 0) {
+            turns.push(current);
+            current = [];
+        }
+        current.push(entry);
+    }
+    if (current.length > 0) {
+        turns.push(current);
+    }
+    return turns;
+}
+/** Render a turn's events into human-readable text. */
+function renderTurn(entries) {
+    return entries
+        .map((e) => {
+        const label = EVENT_LABELS[e.type] ?? e.type;
+        return `${label}: ${e.content}`;
+    })
+        .join("\n");
+}
+/**
+ * Split text into sub-chunks at line boundaries, targeting at most maxSize characters.
+ * A single line longer than maxSize will be emitted as-is (not split mid-line).
+ */
+function splitText(text, maxSize) {
+    const lines = text.split("\n");
+    const subChunks = [];
+    let current = "";
+    for (const line of lines) {
+        const candidate = current ? current + "\n" + line : line;
+        if (candidate.length > maxSize && current) {
+            subChunks.push(current);
+            current = line;
+        }
+        else {
+            current = candidate;
+        }
+    }
+    if (current) {
+        subChunks.push(current);
+    }
+    return subChunks;
+}
+//# sourceMappingURL=transcript-chunker.js.map

package/dist/transcript-chunker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript-chunker.js","sourceRoot":"","sources":["../src/transcript-chunker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0BH,yDAAyD;AACzD,MAAM,kBAAkB,GAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AAE7E,4CAA4C;AAC5C,MAAM,sBAAsB,GAAW,IAAI,CAAC;AAE5C,4DAA4D;AAC5D,MAAM,YAAY,GAA2B;IAC3C,UAAU,EAAE,MAAM;IAClB,IAAI,EAAE,WAAW;IACjB,QAAQ,EAAE,MAAM;IAChB,WAAW,EAAE,QAAQ;IACrB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,cAAc,EAAE,SAAS;CAC1B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAkC;IACxE,MAAM,YAAY,GAAW,OAAO,EAAE,YAAY,IAAI,sBAAsB,CAAC;IAC7E,MAAM,SAAS,GAAgB,IAAI,GAAG,CAAC,OAAO,EAAE,cAAc,IAAI,kBAAkB,CAAC,CAAC;IAEtF,OAAO;QACL,KAAK,CAAC,OAAe,EAAE,QAAkC;YACvD,MAAM,OAAO,GAAe,UAAU,CAAC,OAAO,CAAC,CAAC;YAEhD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,OAAO,EAAE,CAAC;YACZ,CAAC;YAED,oEAAoE;YACpE,6DAA6D;YAC7D,MAAM,KAAK,GAAiB,WAAW,CAAC,OAAO,CAAC,CAAC;YACjD,MAAM,MAAM,GAAY,EAAE,CAAC;YAE3B,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC;gBAC9D,MAAM,WAAW,GAAe,KAAK,CAAC,SAAS,CAAC,CAAC;gBACjD,MAAM,OAAO,GAAe,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;gBAE9E,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACzB,SAAS;gBACX,CAAC;gBAED,MAAM,IAAI,GAAW,UAAU,CAAC,OAAO,CAAC,CAAC;gBACzC,MAAM,UAAU,GAAa,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;gBAC7D,MAAM,UAAU,GAAa,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAEtE,MAAM,YAAY,GAA4B;oBAC5C,GAAG,QAAQ;oBACX,SAAS;oBACT,cAAc,EAAE,UAAU,CAAC,CAAC,CAAC;oBAC7B,YAAY,EAAE,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;oBAC/C,UAAU;iBACX,CAAC;gBAEF,IAAI,IAAI,CAAC,MAAM,IAAI,YAAY,EAAE,CAAC;oBAChC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC,CAAC;gBACtE,CAAC;qBAAM,CAAC;oBACN,MAAM,SAAS,GAAa,SAAS,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;oBAC1D,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;wBACjC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC,CAAC;oBAChF,CAAC;gBACH,CAAC;YACH,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,SAAS,UAAU,CAAC,OAAe;IACjC,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,OAAO,GAAW,IAAI,CAAC,IAAI,EAAE,CAAC;QACpC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,SAAS;QACX,CAAC;QACD,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAa,CAAC,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;QACzB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,sEAAsE;AACtE,SAAS,WAAW,CAAC,OAAmB;IACtC,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,IAAI,OAAO,GAAe,EAAE,CAAC;IAE7B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtD,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACpB,OAAO,GAAG,EAAE,CAAC;QACf,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,uDAAuD;AACvD,SAAS,UAAU,CAAC,OAAmB;IACrC,OAAO,OAAO;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACT,MAAM,KAAK,GAAW,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;QACrD,OAAO,GAAG,KAAK,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;IAClC,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAS,SAAS,CAAC,IAAY,EAAE,OAAe;IAC9C,MAAM,KAAK,GAAa,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,IAAI,OAAO,GAAW,EAAE,CAAC;IAEzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,SAAS,GAAW,OAAO,CAAC,CAAC,CAAC,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QACjE,IAAI,SAAS,CAAC,MAAM,GAAG,OAAO,IAAI,OAAO,EAAE,CAAC;YAC1C,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACxB,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,SAAS,CAAC;QACtB,CAAC;IACH,CAAC;IAED,IAAI,OAAO,EAAE,CAAC;QACZ,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Core domain types for the knowledge graph.
+ *
+ * Defines the two node kinds (reference and native), edge types, and
+ * runtime type guards for discriminating between node variants.
+ *
+ * @module
+ */
+/** Discriminator for knowledge graph node kinds. */
+export declare const NODE_KIND: {
+    /** Points to an entity in Grackle's relational DB. No duplicated content. */
+    readonly REFERENCE: "reference";
+    /** Exists only in the graph. Owns its content. */
+    readonly NATIVE: "native";
+};
+/** Union of all node kind values. */
+export type NodeKind = (typeof NODE_KIND)[keyof typeof NODE_KIND];
+/** Entity types that a reference node can point to. */
+export declare const REFERENCE_SOURCE: {
+    readonly TASK: "task";
+    readonly SESSION: "session";
+    readonly FINDING: "finding";
+    readonly WORKSPACE: "workspace";
+};
+/** Union of all reference source values. */
+export type ReferenceSource = (typeof REFERENCE_SOURCE)[keyof typeof REFERENCE_SOURCE];
+/** Categories for native nodes that exist only in the knowledge graph. */
+export declare const NATIVE_CATEGORY: {
+    readonly DECISION: "decision";
+    readonly INSIGHT: "insight";
+    readonly CONCEPT: "concept";
+    readonly SNIPPET: "snippet";
+};
+/** Union of all native category values. */
+export type NativeCategory = (typeof NATIVE_CATEGORY)[keyof typeof NATIVE_CATEGORY];
+/** Relationship types between knowledge graph nodes. */
+export declare const EDGE_TYPE: {
+    readonly RELATES_TO: "RELATES_TO";
+    readonly DEPENDS_ON: "DEPENDS_ON";
+    readonly DERIVED_FROM: "DERIVED_FROM";
+    readonly MENTIONS: "MENTIONS";
+    readonly PART_OF: "PART_OF";
+};
+/** Union of all edge type values. */
+export type EdgeType = (typeof EDGE_TYPE)[keyof typeof EDGE_TYPE];
+/** Properties common to all knowledge graph nodes. */
+export interface KnowledgeNodeBase {
+    /** Unique node identifier (UUID). */
+    id: string;
+    /** Which kind of node this is. */
+    kind: NodeKind;
+    /** Dense vector embedding for similarity search. */
+    embedding: number[];
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+    /** Workspace scope (empty string = global). */
+    workspaceId: string;
+}
+/** A reference node — points to an entity in Grackle's relational DB. */
+export interface ReferenceNode extends KnowledgeNodeBase {
+    kind: typeof NODE_KIND.REFERENCE;
+    /** Which entity type this refers to. */
+    sourceType: ReferenceSource;
+    /** The ID of the entity in Grackle's relational DB. */
+    sourceId: string;
+    /** Human-readable label derived from the source (e.g., task title). */
+    label: string;
+}
+/** A native node — owns its content directly. */
+export interface NativeNode extends KnowledgeNodeBase {
+    kind: typeof NODE_KIND.NATIVE;
+    /** Subcategory of the native node. */
+    category: NativeCategory;
+    /** Title or summary. */
+    title: string;
+    /** Full content owned by this node. */
+    content: string;
+    /** Free-form tags for categorization. */
+    tags: string[];
+}
+/** Discriminated union of all knowledge graph node types. */
+export type KnowledgeNode = ReferenceNode | NativeNode;
+/** An edge (relationship) in the knowledge graph. */
+export interface KnowledgeEdge {
+    /** Source node ID. */
+    fromId: string;
+    /** Target node ID. */
+    toId: string;
+    /** Relationship type. */
+    type: EdgeType;
+    /** Optional metadata (e.g., confidence score, context snippet). */
+    metadata?: Record<string, unknown>;
+    /** ISO 8601 timestamp when the edge was created. */
+    createdAt: string;
+}
+/** Returns true if the node is a {@link ReferenceNode}. */
+export declare function isReferenceNode(node: KnowledgeNode): node is ReferenceNode;
+/** Returns true if the node is a {@link NativeNode}. */
+export declare function isNativeNode(node: KnowledgeNode): node is NativeNode;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,oDAAoD;AACpD,eAAO,MAAM,SAAS;IACpB,6EAA6E;;IAE7E,kDAAkD;;CAE1C,CAAC;AAEX,qCAAqC;AACrC,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAMlE,uDAAuD;AACvD,eAAO,MAAM,gBAAgB;;;;;CAKnB,CAAC;AAEX,4CAA4C;AAC5C,MAAM,MAAM,eAAe,GACzB,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAM3D,0EAA0E;AAC1E,eAAO,MAAM,eAAe;;;;;CAKlB,CAAC;AAEX,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GACxB,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAMzD,wDAAwD;AACxD,eAAO,MAAM,SAAS;;;;;;CAMZ,CAAC;AAEX,qCAAqC;AACrC,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAMlE,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,IAAI,EAAE,QAAQ,CAAC;IACf,oDAAoD;IACpD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,IAAI,EAAE,OAAO,SAAS,CAAC,SAAS,CAAC;IACjC,wCAAwC;IACxC,UAAU,EAAE,eAAe,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;CACf;AAED,iDAAiD;AACjD,MAAM,WAAW,UAAW,SAAQ,iBAAiB;IACnD,IAAI,EAAE,OAAO,SAAS,CAAC,MAAM,CAAC;IAC9B,sCAAsC;IACtC,QAAQ,EAAE,cAAc,CAAC;IACzB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,UAAU,CAAC;AAMvD,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,IAAI,aAAa,CAE1E;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,IAAI,UAAU,CAEpE"}

package/dist/types.js

@@ -0,0 +1,61 @@
+/**
+ * Core domain types for the knowledge graph.
+ *
+ * Defines the two node kinds (reference and native), edge types, and
+ * runtime type guards for discriminating between node variants.
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Node kind discriminator
+// ---------------------------------------------------------------------------
+/** Discriminator for knowledge graph node kinds. */
+export const NODE_KIND = {
+    /** Points to an entity in Grackle's relational DB. No duplicated content. */
+    REFERENCE: "reference",
+    /** Exists only in the graph. Owns its content. */
+    NATIVE: "native",
+};
+// ---------------------------------------------------------------------------
+// Reference node source types
+// ---------------------------------------------------------------------------
+/** Entity types that a reference node can point to. */
+export const REFERENCE_SOURCE = {
+    TASK: "task",
+    SESSION: "session",
+    FINDING: "finding",
+    WORKSPACE: "workspace",
+};
+// ---------------------------------------------------------------------------
+// Native node categories
+// ---------------------------------------------------------------------------
+/** Categories for native nodes that exist only in the knowledge graph. */
+export const NATIVE_CATEGORY = {
+    DECISION: "decision",
+    INSIGHT: "insight",
+    CONCEPT: "concept",
+    SNIPPET: "snippet",
+};
+// ---------------------------------------------------------------------------
+// Edge types
+// ---------------------------------------------------------------------------
+/** Relationship types between knowledge graph nodes. */
+export const EDGE_TYPE = {
+    RELATES_TO: "RELATES_TO",
+    DEPENDS_ON: "DEPENDS_ON",
+    DERIVED_FROM: "DERIVED_FROM",
+    MENTIONS: "MENTIONS",
+    PART_OF: "PART_OF",
+};
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+/** Returns true if the node is a {@link ReferenceNode}. */
+export function isReferenceNode(node) {
+    return node.kind === NODE_KIND.REFERENCE;
+}
+/** Returns true if the node is a {@link NativeNode}. */
+export function isNativeNode(node) {
+    return node.kind === NODE_KIND.NATIVE;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E,oDAAoD;AACpD,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,6EAA6E;IAC7E,SAAS,EAAE,WAAW;IACtB,kDAAkD;IAClD,MAAM,EAAE,QAAQ;CACR,CAAC;AAKX,8EAA8E;AAC9E,8BAA8B;AAC9B,8EAA8E;AAE9E,uDAAuD;AACvD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,WAAW;CACd,CAAC;AAMX,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;CACV,CAAC;AAMX,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,wDAAwD;AACxD,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,UAAU,EAAE,YAAY;IACxB,UAAU,EAAE,YAAY;IACxB,YAAY,EAAE,cAAc;IAC5B,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;CACV,CAAC;AAsEX,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E,2DAA2D;AAC3D,MAAM,UAAU,eAAe,CAAC,IAAmB;IACjD,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,SAAS,CAAC;AAC3C,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,YAAY,CAAC,IAAmB;IAC9C,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,MAAM,CAAC;AACxC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@grackle-ai/knowledge",
-  "version": "0.58.0",
-  "description": "Scaffold for the Knowledge Graph subsystem for Grackle",
+  "version": "0.59.0",
+  "description": "Knowledge graph subsystem for Grackle (Neo4j + vector search)",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,7 +25,9 @@
   ],
   "dependencies": {
     "@huggingface/transformers": "^3.4.0",
-    "@grackle-ai/common": "0.58.0"
+    "neo4j-driver": "^6.0.1",
+    "pino": "^10.3.1",
+    "@grackle-ai/common": "0.59.0"
   },
   "devDependencies": {
     "@rushstack/heft": "1.2.4",