learngraph 0.1.0 → 0.2.0

package/dist/esm/storage/neo4j.js

@@ -0,0 +1,829 @@
+/**
+ * Neo4j storage adapter
+ *
+ * Production-ready graph storage using Neo4j graph database
+ * with full Cypher query support and connection pooling.
+ *
+ * @packageDocumentation
+ */
+import { GRAPH_VERSION, createSkillId, createEdgeId } from '../types/index.js';
+import { NotFoundError, DuplicateError, ReferenceError as StorageReferenceError, ConnectionError, } from './errors.js';
+import { nowISO, inputToSkillNode, inputToEdge, validateSkillInput, validateEdgeInput, requireConnection, calculateStats, } from './base.js';
+/**
+ * Neo4j storage adapter.
+ *
+ * Production-ready graph storage with full CRUD operations,
+ * connection pooling, and optimized Cypher queries.
+ *
+ * @example
+ * ```typescript
+ * import { Neo4jStorage } from 'learngraph/storage';
+ *
+ * const storage = new Neo4jStorage();
+ * await storage.connect({
+ *   backend: 'neo4j',
+ *   uri: 'bolt://localhost:7687',
+ *   username: 'neo4j',
+ *   password: 'password',
+ *   database: 'learngraph',
+ * });
+ *
+ * // Create a skill
+ * const skill = await storage.createSkill({
+ *   name: 'Add Fractions',
+ *   description: 'Add fractions with like denominators',
+ *   bloomLevel: 'apply',
+ *   difficulty: 0.4,
+ *   isThresholdConcept: false,
+ *   masteryThreshold: 0.8,
+ *   estimatedMinutes: 30,
+ *   tags: ['math', 'fractions'],
+ *   metadata: {},
+ * });
+ *
+ * // Query the graph
+ * const prerequisites = await storage.getPrerequisitesOf(skill.id);
+ * ```
+ */
+export class Neo4jStorage {
+    driver = null;
+    config = null;
+    _connected = false;
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Session Management
+    // ─────────────────────────────────────────────────────────────────────────────
+    getSession() {
+        if (!this.driver || !this._connected) {
+            throw new ConnectionError('Not connected to Neo4j');
+        }
+        return this.driver.session({
+            database: this.config?.database || 'neo4j',
+        });
+    }
+    async runQuery(query, params) {
+        const session = this.getSession();
+        try {
+            return await session.run(query, params);
+        }
+        finally {
+            await session.close();
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Record Conversion
+    // ─────────────────────────────────────────────────────────────────────────────
+    recordToSkill(record) {
+        const s = record;
+        const node = {
+            id: createSkillId(s.id),
+            name: s.name,
+            description: s.description,
+            bloomLevel: s.bloomLevel,
+            difficulty: s.difficulty,
+            isThresholdConcept: s.isThresholdConcept,
+            masteryThreshold: s.masteryThreshold,
+            estimatedMinutes: s.estimatedMinutes,
+            tags: s.tags,
+            metadata: typeof s.metadata === 'string' ? JSON.parse(s.metadata) : s.metadata || {},
+            createdAt: s.createdAt,
+            updatedAt: s.updatedAt,
+        };
+        // Only add optional fields if they have values
+        if (s.standardAlignment) {
+            node.standardAlignment = s.standardAlignment;
+        }
+        if (s.domain) {
+            node.domain = s.domain;
+        }
+        if (s.gradeLevel) {
+            node.gradeLevel = s.gradeLevel;
+        }
+        return node;
+    }
+    recordToEdge(record) {
+        const e = record;
+        const edge = {
+            id: createEdgeId(e.id),
+            sourceId: createSkillId(e.sourceId),
+            targetId: createSkillId(e.targetId),
+            strength: e.strength,
+            type: e.type,
+            metadata: typeof e.metadata === 'string' ? JSON.parse(e.metadata) : e.metadata || {},
+            createdAt: e.createdAt,
+        };
+        // Only add optional fields if they have values
+        if (e.reasoning) {
+            edge.reasoning = e.reasoning;
+        }
+        return edge;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Connection Management
+    // ─────────────────────────────────────────────────────────────────────────────
+    async connect(config) {
+        if (config.backend !== 'neo4j') {
+            throw new Error('Neo4jStorage only supports "neo4j" backend');
+        }
+        this.config = config;
+        try {
+            // Dynamic import of neo4j-driver
+            const neo4j = (await import('neo4j-driver'));
+            this.driver = neo4j.default.driver(this.config.uri, neo4j.default.auth.basic(this.config.username, this.config.password), {
+                maxConnectionPoolSize: this.config.maxConnectionPoolSize || 50,
+                connectionTimeout: this.config.connectionTimeout || 30000,
+            });
+            // Verify connectivity
+            await this.driver.verifyConnectivity();
+            // Initialize schema (constraints and indexes)
+            await this.initializeSchema();
+            this._connected = true;
+        }
+        catch (error) {
+            throw new ConnectionError(`Failed to connect to Neo4j: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
+        }
+    }
+    async initializeSchema() {
+        const queries = [
+            // Skill node uniqueness constraint
+            `CREATE CONSTRAINT skill_id IF NOT EXISTS FOR (s:Skill) REQUIRE s.id IS UNIQUE`,
+            // Indexes for common queries
+            `CREATE INDEX skill_bloom_level IF NOT EXISTS FOR (s:Skill) ON (s.bloomLevel)`,
+            `CREATE INDEX skill_difficulty IF NOT EXISTS FOR (s:Skill) ON (s.difficulty)`,
+            `CREATE INDEX skill_threshold IF NOT EXISTS FOR (s:Skill) ON (s.isThresholdConcept)`,
+            `CREATE INDEX skill_domain IF NOT EXISTS FOR (s:Skill) ON (s.domain)`,
+        ];
+        for (const query of queries) {
+            try {
+                await this.runQuery(query);
+            }
+            catch {
+                // Ignore errors for already existing constraints/indexes
+            }
+        }
+    }
+    async disconnect() {
+        if (this.driver) {
+            await this.driver.close();
+            this.driver = null;
+        }
+        this._connected = false;
+    }
+    isConnected() {
+        return this._connected;
+    }
+    async getStatus() {
+        const startTime = Date.now();
+        if (!this._connected || !this.driver) {
+            return {
+                connected: false,
+                backend: 'neo4j',
+                lastChecked: new Date(),
+                error: 'Not connected',
+            };
+        }
+        try {
+            await this.driver.verifyConnectivity();
+            return {
+                connected: true,
+                backend: 'neo4j',
+                latencyMs: Date.now() - startTime,
+                lastChecked: new Date(),
+            };
+        }
+        catch (error) {
+            return {
+                connected: false,
+                backend: 'neo4j',
+                lastChecked: new Date(),
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Skill Node CRUD
+    // ─────────────────────────────────────────────────────────────────────────────
+    async createSkill(input) {
+        requireConnection(this._connected);
+        validateSkillInput(input);
+        const skill = inputToSkillNode(input);
+        const query = `
+      CREATE (s:Skill {
+        id: $id,
+        name: $name,
+        description: $description,
+        bloomLevel: $bloomLevel,
+        difficulty: $difficulty,
+        isThresholdConcept: $isThresholdConcept,
+        masteryThreshold: $masteryThreshold,
+        estimatedMinutes: $estimatedMinutes,
+        tags: $tags,
+        standardAlignment: $standardAlignment,
+        domain: $domain,
+        gradeLevel: $gradeLevel,
+        metadata: $metadata,
+        createdAt: $createdAt,
+        updatedAt: $updatedAt
+      })
+      RETURN s {.*} as skill
+    `;
+        try {
+            const result = await this.runQuery(query, {
+                id: skill.id,
+                name: skill.name,
+                description: skill.description,
+                bloomLevel: skill.bloomLevel,
+                difficulty: skill.difficulty,
+                isThresholdConcept: skill.isThresholdConcept,
+                masteryThreshold: skill.masteryThreshold,
+                estimatedMinutes: skill.estimatedMinutes,
+                tags: skill.tags,
+                standardAlignment: skill.standardAlignment || null,
+                domain: skill.domain || null,
+                gradeLevel: skill.gradeLevel || null,
+                metadata: JSON.stringify(skill.metadata),
+                createdAt: skill.createdAt,
+                updatedAt: skill.updatedAt,
+            });
+            if (result.records.length === 0) {
+                throw new Error('Failed to create skill');
+            }
+            return skill;
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                error.message.includes('already exists')) {
+                throw new DuplicateError('skill', skill.id);
+            }
+            throw error;
+        }
+    }
+    async getSkill(id) {
+        requireConnection(this._connected);
+        const query = `
+      MATCH (s:Skill {id: $id})
+      RETURN s {.*} as skill
+    `;
+        const result = await this.runQuery(query, { id: id });
+        const firstRecord = result.records[0];
+        if (!firstRecord) {
+            return null;
+        }
+        return this.recordToSkill(firstRecord.get('skill'));
+    }
+    async getSkills(ids) {
+        requireConnection(this._connected);
+        if (ids.length === 0)
+            return [];
+        const query = `
+      MATCH (s:Skill)
+      WHERE s.id IN $ids
+      RETURN s {.*} as skill
+    `;
+        const result = await this.runQuery(query, {
+            ids: ids.map((id) => id),
+        });
+        return result.records.map((record) => this.recordToSkill(record.get('skill')));
+    }
+    async updateSkill(id, updates) {
+        requireConnection(this._connected);
+        const existing = await this.getSkill(id);
+        if (!existing) {
+            throw new NotFoundError('skill', id);
+        }
+        const updated = {
+            ...existing,
+            ...updates,
+            id: existing.id,
+            createdAt: existing.createdAt,
+            updatedAt: nowISO(),
+        };
+        const query = `
+      MATCH (s:Skill {id: $id})
+      SET s.name = $name,
+          s.description = $description,
+          s.bloomLevel = $bloomLevel,
+          s.difficulty = $difficulty,
+          s.isThresholdConcept = $isThresholdConcept,
+          s.masteryThreshold = $masteryThreshold,
+          s.estimatedMinutes = $estimatedMinutes,
+          s.tags = $tags,
+          s.standardAlignment = $standardAlignment,
+          s.domain = $domain,
+          s.gradeLevel = $gradeLevel,
+          s.metadata = $metadata,
+          s.updatedAt = $updatedAt
+      RETURN s {.*} as skill
+    `;
+        await this.runQuery(query, {
+            id: updated.id,
+            name: updated.name,
+            description: updated.description,
+            bloomLevel: updated.bloomLevel,
+            difficulty: updated.difficulty,
+            isThresholdConcept: updated.isThresholdConcept,
+            masteryThreshold: updated.masteryThreshold,
+            estimatedMinutes: updated.estimatedMinutes,
+            tags: updated.tags,
+            standardAlignment: updated.standardAlignment || null,
+            domain: updated.domain || null,
+            gradeLevel: updated.gradeLevel || null,
+            metadata: JSON.stringify(updated.metadata),
+            updatedAt: updated.updatedAt,
+        });
+        return updated;
+    }
+    async deleteSkill(id) {
+        requireConnection(this._connected);
+        const query = `
+      MATCH (s:Skill {id: $id})
+      DETACH DELETE s
+    `;
+        await this.runQuery(query, { id: id });
+    }
+    async findSkills(query) {
+        requireConnection(this._connected);
+        let cypher = 'MATCH (s:Skill)';
+        const params = {};
+        const whereClauses = [];
+        // Build WHERE clauses from filters
+        if (query.filters) {
+            const filters = query.filters;
+            for (let i = 0; i < filters.length; i++) {
+                const filter = filters[i];
+                const paramName = `filter${i}`;
+                switch (filter.operator) {
+                    case 'eq':
+                        whereClauses.push(`s.${filter.field} = $${paramName}`);
+                        params[paramName] = filter.value;
+                        break;
+                    case 'neq':
+                        whereClauses.push(`s.${filter.field} <> $${paramName}`);
+                        params[paramName] = filter.value;
+                        break;
+                    case 'gt':
+                        whereClauses.push(`s.${filter.field} > $${paramName}`);
+                        params[paramName] = filter.value;
+                        break;
+                    case 'gte':
+                        whereClauses.push(`s.${filter.field} >= $${paramName}`);
+                        params[paramName] = filter.value;
+                        break;
+                    case 'lt':
+                        whereClauses.push(`s.${filter.field} < $${paramName}`);
+                        params[paramName] = filter.value;
+                        break;
+                    case 'lte':
+                        whereClauses.push(`s.${filter.field} <= $${paramName}`);
+                        params[paramName] = filter.value;
+                        break;
+                    case 'in':
+                        whereClauses.push(`s.${filter.field} IN $${paramName}`);
+                        params[paramName] = filter.value;
+                        break;
+                    case 'contains':
+                        if (filter.field === 'tags') {
+                            whereClauses.push(`$${paramName} IN s.tags`);
+                        }
+                        else {
+                            whereClauses.push(`s.${filter.field} CONTAINS $${paramName}`);
+                        }
+                        params[paramName] = filter.value;
+                        break;
+                }
+            }
+        }
+        if (whereClauses.length > 0) {
+            cypher += ' WHERE ' + whereClauses.join(' AND ');
+        }
+        cypher += ' RETURN s {.*} as skill';
+        // Add ORDER BY
+        if (query.sorting && query.sorting.length > 0) {
+            const orderClauses = query.sorting.map((sortItem) => `s.${sortItem.field} ${sortItem.direction.toUpperCase()}`);
+            cypher += ' ORDER BY ' + orderClauses.join(', ');
+        }
+        // Add pagination
+        if (query.pagination) {
+            if (query.pagination.offset) {
+                cypher += ` SKIP ${query.pagination.offset}`;
+            }
+            cypher += ` LIMIT ${query.pagination.limit || 100}`;
+        }
+        const result = await this.runQuery(cypher, params);
+        return result.records.map((record) => this.recordToSkill(record.get('skill')));
+    }
+    async countSkills(query) {
+        requireConnection(this._connected);
+        if (!query || !query.filters || query.filters.length === 0) {
+            const result = await this.runQuery('MATCH (s:Skill) RETURN count(s) as count');
+            const firstRecord = result.records[0];
+            return firstRecord ? firstRecord.get('count').low : 0;
+        }
+        const { pagination, ...queryWithoutPagination } = query;
+        const skills = await this.findSkills(queryWithoutPagination);
+        return skills.length;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Prerequisite Edge CRUD
+    // ─────────────────────────────────────────────────────────────────────────────
+    async createPrerequisite(input) {
+        requireConnection(this._connected);
+        validateEdgeInput(input);
+        // Verify source exists
+        const source = await this.getSkill(input.sourceId);
+        if (!source) {
+            throw new StorageReferenceError(input.id || 'new', input.sourceId, 'source');
+        }
+        // Verify target exists
+        const target = await this.getSkill(input.targetId);
+        if (!target) {
+            throw new StorageReferenceError(input.id || 'new', input.targetId, 'target');
+        }
+        const edge = inputToEdge(input);
+        const query = `
+      MATCH (source:Skill {id: $sourceId})
+      MATCH (target:Skill {id: $targetId})
+      CREATE (source)-[r:PREREQUISITE_OF {
+        id: $id,
+        strength: $strength,
+        type: $type,
+        reasoning: $reasoning,
+        metadata: $metadata,
+        createdAt: $createdAt
+      }]->(target)
+      RETURN r {.*, sourceId: source.id, targetId: target.id} as edge
+    `;
+        try {
+            await this.runQuery(query, {
+                id: edge.id,
+                sourceId: edge.sourceId,
+                targetId: edge.targetId,
+                strength: edge.strength,
+                type: edge.type,
+                reasoning: edge.reasoning || null,
+                metadata: JSON.stringify(edge.metadata),
+                createdAt: edge.createdAt,
+            });
+            return edge;
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                error.message.includes('already exists')) {
+                throw new DuplicateError('edge', edge.id);
+            }
+            throw error;
+        }
+    }
+    async getPrerequisite(id) {
+        requireConnection(this._connected);
+        const query = `
+      MATCH (source:Skill)-[r:PREREQUISITE_OF {id: $id}]->(target:Skill)
+      RETURN r {.*, sourceId: source.id, targetId: target.id} as edge
+    `;
+        const result = await this.runQuery(query, { id: id });
+        const firstRecord = result.records[0];
+        if (!firstRecord) {
+            return null;
+        }
+        return this.recordToEdge(firstRecord.get('edge'));
+    }
+    async deletePrerequisite(id) {
+        requireConnection(this._connected);
+        const query = `
+      MATCH ()-[r:PREREQUISITE_OF {id: $id}]->()
+      DELETE r
+    `;
+        await this.runQuery(query, { id: id });
+    }
+    async findPrerequisites(criteria) {
+        requireConnection(this._connected);
+        let query = 'MATCH (source:Skill)-[r:PREREQUISITE_OF]->(target:Skill)';
+        const whereClauses = [];
+        const params = {};
+        if (criteria.sourceId) {
+            whereClauses.push('source.id = $sourceId');
+            params.sourceId = criteria.sourceId;
+        }
+        if (criteria.targetId) {
+            whereClauses.push('target.id = $targetId');
+            params.targetId = criteria.targetId;
+        }
+        if (criteria.type) {
+            whereClauses.push('r.type = $type');
+            params.type = criteria.type;
+        }
+        if (criteria.minStrength !== undefined) {
+            whereClauses.push('r.strength >= $minStrength');
+            params.minStrength = criteria.minStrength;
+        }
+        if (whereClauses.length > 0) {
+            query += ' WHERE ' + whereClauses.join(' AND ');
+        }
+        query += ' RETURN r {.*, sourceId: source.id, targetId: target.id} as edge';
+        const result = await this.runQuery(query, params);
+        return result.records.map((record) => this.recordToEdge(record.get('edge')));
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Graph Traversal
+    // ─────────────────────────────────────────────────────────────────────────────
+    async getPrerequisitesOf(skillId) {
+        requireConnection(this._connected);
+        const query = `
+      MATCH (prereq:Skill)-[:PREREQUISITE_OF]->(s:Skill {id: $id})
+      RETURN prereq {.*} as skill
+    `;
+        const result = await this.runQuery(query, { id: skillId });
+        return result.records.map((record) => this.recordToSkill(record.get('skill')));
+    }
+    async getDependentsOf(skillId) {
+        requireConnection(this._connected);
+        const query = `
+      MATCH (s:Skill {id: $id})-[:PREREQUISITE_OF]->(dependent:Skill)
+      RETURN dependent {.*} as skill
+    `;
+        const result = await this.runQuery(query, { id: skillId });
+        return result.records.map((record) => this.recordToSkill(record.get('skill')));
+    }
+    async getSubgraph(rootId, depth) {
+        requireConnection(this._connected);
+        // Get all nodes within depth
+        const nodeQuery = `
+      MATCH path = (prereq:Skill)-[:PREREQUISITE_OF*0..${depth}]->(root:Skill {id: $id})
+      UNWIND nodes(path) as n
+      WITH DISTINCT n
+      RETURN n {.*} as skill
+    `;
+        const nodeResult = await this.runQuery(nodeQuery, { id: rootId });
+        const nodes = nodeResult.records.map((record) => this.recordToSkill(record.get('skill')));
+        const nodeIds = new Set(nodes.map((n) => n.id));
+        // Get edges between these nodes
+        const edgeQuery = `
+      MATCH (source:Skill)-[r:PREREQUISITE_OF]->(target:Skill)
+      WHERE source.id IN $nodeIds AND target.id IN $nodeIds
+      RETURN r {.*, sourceId: source.id, targetId: target.id} as edge
+    `;
+        const edgeResult = await this.runQuery(edgeQuery, {
+            nodeIds: Array.from(nodeIds),
+        });
+        const edges = edgeResult.records.map((record) => this.recordToEdge(record.get('edge')));
+        return {
+            rootId,
+            depth,
+            nodes,
+            edges,
+        };
+    }
+    async getRootSkills() {
+        requireConnection(this._connected);
+        const query = `
+      MATCH (s:Skill)
+      WHERE NOT (:Skill)-[:PREREQUISITE_OF]->(s)
+      RETURN s {.*} as skill
+    `;
+        const result = await this.runQuery(query);
+        return result.records.map((record) => this.recordToSkill(record.get('skill')));
+    }
+    async getLeafSkills() {
+        requireConnection(this._connected);
+        const query = `
+      MATCH (s:Skill)
+      WHERE NOT (s)-[:PREREQUISITE_OF]->(:Skill)
+      RETURN s {.*} as skill
+    `;
+        const result = await this.runQuery(query);
+        return result.records.map((record) => this.recordToSkill(record.get('skill')));
+    }
+    async getPath(fromId, toId) {
+        requireConnection(this._connected);
+        const query = `
+      MATCH path = shortestPath(
+        (from:Skill {id: $fromId})-[:PREREQUISITE_OF*]->(to:Skill {id: $toId})
+      )
+      UNWIND nodes(path) as n
+      RETURN n {.*} as skill
+    `;
+        try {
+            const result = await this.runQuery(query, {
+                fromId: fromId,
+                toId: toId,
+            });
+            if (result.records.length === 0) {
+                return null;
+            }
+            return result.records.map((record) => this.recordToSkill(record.get('skill')));
+        }
+        catch {
+            return null;
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Bulk Operations
+    // ─────────────────────────────────────────────────────────────────────────────
+    async importGraph(nodes, edges, options) {
+        requireConnection(this._connected);
+        const startTime = Date.now();
+        const result = {
+            nodesCreated: 0,
+            edgesCreated: 0,
+            nodesSkipped: 0,
+            edgesSkipped: 0,
+            errors: [],
+            durationMs: 0,
+        };
+        if (options?.clearExisting) {
+            await this.clearAll();
+        }
+        // Batch import nodes using UNWIND for efficiency
+        const batchSize = 1000;
+        for (let i = 0; i < nodes.length; i += batchSize) {
+            const batch = nodes.slice(i, i + batchSize);
+            const skills = batch.map((input) => inputToSkillNode(input));
+            const query = `
+        UNWIND $skills as skill
+        MERGE (s:Skill {id: skill.id})
+        ON CREATE SET
+          s.name = skill.name,
+          s.description = skill.description,
+          s.bloomLevel = skill.bloomLevel,
+          s.difficulty = skill.difficulty,
+          s.isThresholdConcept = skill.isThresholdConcept,
+          s.masteryThreshold = skill.masteryThreshold,
+          s.estimatedMinutes = skill.estimatedMinutes,
+          s.tags = skill.tags,
+          s.standardAlignment = skill.standardAlignment,
+          s.domain = skill.domain,
+          s.gradeLevel = skill.gradeLevel,
+          s.metadata = skill.metadata,
+          s.createdAt = skill.createdAt,
+          s.updatedAt = skill.updatedAt
+        RETURN count(s) as count
+      `;
+            try {
+                const importResult = await this.runQuery(query, {
+                    skills: skills.map((s) => ({
+                        id: s.id,
+                        name: s.name,
+                        description: s.description,
+                        bloomLevel: s.bloomLevel,
+                        difficulty: s.difficulty,
+                        isThresholdConcept: s.isThresholdConcept,
+                        masteryThreshold: s.masteryThreshold,
+                        estimatedMinutes: s.estimatedMinutes,
+                        tags: s.tags,
+                        standardAlignment: s.standardAlignment || null,
+                        domain: s.domain || null,
+                        gradeLevel: s.gradeLevel || null,
+                        metadata: JSON.stringify(s.metadata),
+                        createdAt: s.createdAt,
+                        updatedAt: s.updatedAt,
+                    })),
+                });
+                result.nodesCreated += importResult.summary.counters.nodesCreated();
+                result.nodesSkipped += batch.length - importResult.summary.counters.nodesCreated();
+            }
+            catch (error) {
+                for (const input of batch) {
+                    result.errors.push({
+                        type: 'node',
+                        id: input.id || 'unknown',
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }
+        // Batch import edges
+        for (let i = 0; i < edges.length; i += batchSize) {
+            const batch = edges.slice(i, i + batchSize);
+            const edgeData = batch.map((input) => inputToEdge(input));
+            const query = `
+        UNWIND $edges as edge
+        MATCH (source:Skill {id: edge.sourceId})
+        MATCH (target:Skill {id: edge.targetId})
+        MERGE (source)-[r:PREREQUISITE_OF {id: edge.id}]->(target)
+        ON CREATE SET
+          r.strength = edge.strength,
+          r.type = edge.type,
+          r.reasoning = edge.reasoning,
+          r.metadata = edge.metadata,
+          r.createdAt = edge.createdAt
+        RETURN count(r) as count
+      `;
+            try {
+                const importResult = await this.runQuery(query, {
+                    edges: edgeData.map((e) => ({
+                        id: e.id,
+                        sourceId: e.sourceId,
+                        targetId: e.targetId,
+                        strength: e.strength,
+                        type: e.type,
+                        reasoning: e.reasoning || null,
+                        metadata: JSON.stringify(e.metadata),
+                        createdAt: e.createdAt,
+                    })),
+                });
+                result.edgesCreated += importResult.summary.counters.relationshipsCreated();
+                result.edgesSkipped += batch.length - importResult.summary.counters.relationshipsCreated();
+            }
+            catch (error) {
+                for (const input of batch) {
+                    result.errors.push({
+                        type: 'edge',
+                        id: input.id || 'unknown',
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }
+        result.durationMs = Date.now() - startTime;
+        return result;
+    }
+    async exportGraph() {
+        requireConnection(this._connected);
+        const nodes = await this.findSkills({});
+        const edges = await this.findPrerequisites({});
+        return {
+            version: GRAPH_VERSION,
+            exportedAt: nowISO(),
+            nodes,
+            edges,
+        };
+    }
+    async clearAll() {
+        requireConnection(this._connected);
+        const query = `
+      MATCH (s:Skill)
+      DETACH DELETE s
+    `;
+        await this.runQuery(query);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Analytics
+    // ─────────────────────────────────────────────────────────────────────────────
+    async getStats() {
+        requireConnection(this._connected);
+        // Get basic counts
+        const countQuery = `
+      MATCH (s:Skill)
+      OPTIONAL MATCH ()-[r:PREREQUISITE_OF]->()
+      WITH
+        count(DISTINCT s) as nodeCount,
+        count(DISTINCT r) as edgeCount,
+        count(DISTINCT CASE WHEN s.isThresholdConcept = true THEN s END) as thresholdCount
+      RETURN nodeCount, edgeCount, thresholdCount
+    `;
+        const countResult = await this.runQuery(countQuery);
+        const countsRecord = countResult.records[0];
+        // Get root and leaf counts
+        const rootQuery = `
+      MATCH (s:Skill)
+      WHERE NOT (:Skill)-[:PREREQUISITE_OF]->(s)
+      RETURN count(s) as count
+    `;
+        const rootResult = await this.runQuery(rootQuery);
+        const rootRecord = rootResult.records[0];
+        const leafQuery = `
+      MATCH (s:Skill)
+      WHERE NOT (s)-[:PREREQUISITE_OF]->(:Skill)
+      RETURN count(s) as count
+    `;
+        const leafResult = await this.runQuery(leafQuery);
+        const leafRecord = leafResult.records[0];
+        // Get bloom distribution
+        const bloomQuery = `
+      MATCH (s:Skill)
+      RETURN s.bloomLevel as level, count(s) as count
+    `;
+        const bloomResult = await this.runQuery(bloomQuery);
+        const bloomDistribution = {
+            remember: 0,
+            understand: 0,
+            apply: 0,
+            analyze: 0,
+            evaluate: 0,
+            create: 0,
+        };
+        for (const record of bloomResult.records) {
+            const level = record.get('level');
+            const count = record.get('count').low;
+            if (level && bloomDistribution.hasOwnProperty(level)) {
+                bloomDistribution[level] = count;
+            }
+        }
+        // Calculate from actual data for remaining stats
+        const nodes = await this.findSkills({});
+        const edges = await this.findPrerequisites({});
+        const fullStats = calculateStats(nodes, edges);
+        return {
+            nodeCount: countsRecord ? countsRecord.get('nodeCount').low : 0,
+            edgeCount: countsRecord ? countsRecord.get('edgeCount').low : 0,
+            thresholdConceptCount: countsRecord ? countsRecord.get('thresholdCount').low : 0,
+            rootNodeCount: rootRecord ? rootRecord.get('count').low : 0,
+            leafNodeCount: leafRecord ? leafRecord.get('count').low : 0,
+            maxDepth: fullStats.maxDepth,
+            avgPrerequisites: fullStats.avgPrerequisites,
+            avgDependents: fullStats.avgDependents,
+            bloomDistribution,
+            difficultyDistribution: fullStats.difficultyDistribution,
+        };
+    }
+}
+//# sourceMappingURL=neo4j.js.map