learngraph 0.1.0

package/dist/types/types/storage.d.ts

@@ -0,0 +1,214 @@
+import type { SkillNode, SkillId, SkillNodeInput, SkillNodeUpdate } from './skill.js';
+import type { PrerequisiteEdge, EdgeId, PrerequisiteEdgeInput } from './edge.js';
+import type { Subgraph, GraphExport, GraphStats } from './graph.js';
+import type { SkillQuery } from './query.js';
+/**
+ * Storage backend types
+ */
+export type StorageBackend = 'neo4j' | 'levelgraph' | 'memory';
+/**
+ * Base configuration for all storage adapters
+ */
+export interface StorageConfigBase {
+    /** Storage backend type */
+    backend: StorageBackend;
+}
+/**
+ * Neo4j connection configuration
+ */
+export interface Neo4jConfig extends StorageConfigBase {
+    backend: 'neo4j';
+    /** Neo4j connection URI (e.g., "bolt://localhost:7687") */
+    uri: string;
+    /** Username for authentication */
+    username: string;
+    /** Password for authentication */
+    password: string;
+    /** Database name (default: "neo4j") */
+    database?: string;
+    /** Connection pool size (default: 50) */
+    maxConnectionPoolSize?: number;
+    /** Connection timeout in milliseconds (default: 30000) */
+    connectionTimeout?: number;
+}
+/**
+ * LevelGraph configuration
+ */
+export interface LevelGraphConfig extends StorageConfigBase {
+    backend: 'levelgraph';
+    /** Path to the database directory (for Node.js) */
+    path?: string;
+    /** Database name for browser IndexedDB */
+    dbName?: string;
+}
+/**
+ * In-memory storage configuration (for testing)
+ */
+export interface MemoryConfig extends StorageConfigBase {
+    backend: 'memory';
+    /** Optional initial data */
+    initialData?: GraphExport;
+}
+/**
+ * Union of all storage configurations
+ */
+export type StorageConfig = Neo4jConfig | LevelGraphConfig | MemoryConfig;
+/**
+ * Connection status
+ */
+export interface ConnectionStatus {
+    connected: boolean;
+    backend: StorageBackend;
+    latencyMs?: number;
+    lastChecked: Date;
+    error?: string;
+}
+/**
+ * Result of bulk import operation
+ */
+export interface ImportResult {
+    nodesCreated: number;
+    edgesCreated: number;
+    nodesSkipped: number;
+    edgesSkipped: number;
+    errors: Array<{
+        type: 'node' | 'edge';
+        id: string;
+        error: string;
+    }>;
+    durationMs: number;
+}
+/**
+ * Abstract interface for graph storage backends.
+ *
+ * This is the primary abstraction that allows swapping between
+ * Neo4j (production) and LevelGraph (browser/local development).
+ *
+ * All methods return Promises for async operation.
+ */
+export interface GraphStorage {
+    /**
+     * Connect to the storage backend
+     */
+    connect(config: StorageConfig): Promise<void>;
+    /**
+     * Disconnect from the storage backend
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if connected to the storage backend
+     */
+    isConnected(): boolean;
+    /**
+     * Get connection status with health check
+     */
+    getStatus(): Promise<ConnectionStatus>;
+    /**
+     * Create a new skill node
+     */
+    createSkill(skill: SkillNodeInput): Promise<SkillNode>;
+    /**
+     * Get a skill by ID
+     * Returns null if not found
+     */
+    getSkill(id: SkillId): Promise<SkillNode | null>;
+    /**
+     * Get multiple skills by ID
+     * Returns found skills (missing IDs are not included)
+     */
+    getSkills(ids: SkillId[]): Promise<SkillNode[]>;
+    /**
+     * Update an existing skill
+     * Throws if skill not found
+     */
+    updateSkill(id: SkillId, updates: SkillNodeUpdate): Promise<SkillNode>;
+    /**
+     * Delete a skill and all its edges
+     * No-op if skill not found
+     */
+    deleteSkill(id: SkillId): Promise<void>;
+    /**
+     * Find skills matching query criteria
+     */
+    findSkills(query: Partial<SkillQuery>): Promise<SkillNode[]>;
+    /**
+     * Count skills matching query criteria
+     */
+    countSkills(query?: Partial<SkillQuery>): Promise<number>;
+    /**
+     * Create a prerequisite edge
+     * Throws if source or target skill not found
+     */
+    createPrerequisite(edge: PrerequisiteEdgeInput): Promise<PrerequisiteEdge>;
+    /**
+     * Get a prerequisite edge by ID
+     * Returns null if not found
+     */
+    getPrerequisite(id: EdgeId): Promise<PrerequisiteEdge | null>;
+    /**
+     * Delete a prerequisite edge
+     * No-op if edge not found
+     */
+    deletePrerequisite(id: EdgeId): Promise<void>;
+    /**
+     * Find edges matching criteria
+     */
+    findPrerequisites(criteria: {
+        sourceId?: SkillId;
+        targetId?: SkillId;
+        type?: string;
+        minStrength?: number;
+    }): Promise<PrerequisiteEdge[]>;
+    /**
+     * Get all prerequisite skills for a given skill
+     * (skills that should be learned before this one)
+     */
+    getPrerequisitesOf(skillId: SkillId): Promise<SkillNode[]>;
+    /**
+     * Get all dependent skills for a given skill
+     * (skills that require this one as a prerequisite)
+     */
+    getDependentsOf(skillId: SkillId): Promise<SkillNode[]>;
+    /**
+     * Get a subgraph rooted at a skill
+     * Includes all ancestors up to specified depth
+     */
+    getSubgraph(rootId: SkillId, depth: number): Promise<Subgraph>;
+    /**
+     * Get all root skills (skills with no prerequisites)
+     */
+    getRootSkills(): Promise<SkillNode[]>;
+    /**
+     * Get all leaf skills (skills with no dependents)
+     */
+    getLeafSkills(): Promise<SkillNode[]>;
+    /**
+     * Get the shortest path between two skills
+     * Returns null if no path exists
+     */
+    getPath(fromId: SkillId, toId: SkillId): Promise<SkillNode[] | null>;
+    /**
+     * Import a complete graph (nodes and edges)
+     * Optionally clears existing data first
+     */
+    importGraph(nodes: SkillNodeInput[], edges: PrerequisiteEdgeInput[], options?: {
+        clearExisting?: boolean;
+    }): Promise<ImportResult>;
+    /**
+     * Export the complete graph
+     */
+    exportGraph(): Promise<GraphExport>;
+    /**
+     * Clear all data in the graph
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Get graph statistics
+     */
+    getStats(): Promise<GraphStats>;
+}
+/**
+ * Factory function type for creating storage instances
+ */
+export type StorageFactory = (config: StorageConfig) => GraphStorage;
+//# sourceMappingURL=storage.d.ts.map

package/dist/types/types/storage.d.ts.map

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

package/package.json

@@ -0,0 +1,149 @@
+{
+  "name": "learngraph",
+  "version": "0.1.0",
+  "description": "AI-powered educational knowledge graph infrastructure - decompose curricula into skill graphs with learning science built in",
+  "author": "LearnGraph Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fenago/Jali.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "education",
+    "knowledge-graph",
+    "learning",
+    "curriculum",
+    "neo4j",
+    "levelgraph",
+    "ai",
+    "llm",
+    "mastery-learning",
+    "zpd",
+    "blooms-taxonomy",
+    "adaptive-learning",
+    "edtech"
+  ],
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./storage": {
+      "import": {
+        "types": "./dist/types/storage/index.d.ts",
+        "default": "./dist/esm/storage/index.js"
+      },
+      "require": {
+        "types": "./dist/types/storage/index.d.ts",
+        "default": "./dist/cjs/storage/index.js"
+      }
+    },
+    "./parsers": {
+      "import": {
+        "types": "./dist/types/parsers/index.d.ts",
+        "default": "./dist/esm/parsers/index.js"
+      },
+      "require": {
+        "types": "./dist/types/parsers/index.d.ts",
+        "default": "./dist/cjs/parsers/index.js"
+      }
+    },
+    "./llm": {
+      "import": {
+        "types": "./dist/types/llm/index.d.ts",
+        "default": "./dist/esm/llm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/llm/index.d.ts",
+        "default": "./dist/cjs/llm/index.js"
+      }
+    },
+    "./graph": {
+      "import": {
+        "types": "./dist/types/graph/index.d.ts",
+        "default": "./dist/esm/graph/index.js"
+      },
+      "require": {
+        "types": "./dist/types/graph/index.d.ts",
+        "default": "./dist/cjs/graph/index.js"
+      }
+    },
+    "./query": {
+      "import": {
+        "types": "./dist/types/query/index.d.ts",
+        "default": "./dist/esm/query/index.js"
+      },
+      "require": {
+        "types": "./dist/types/query/index.d.ts",
+        "default": "./dist/cjs/query/index.js"
+      }
+    },
+    "./education": {
+      "import": {
+        "types": "./dist/types/education/index.d.ts",
+        "default": "./dist/esm/education/index.js"
+      },
+      "require": {
+        "types": "./dist/types/education/index.d.ts",
+        "default": "./dist/cjs/education/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist coverage"
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "@vitest/coverage-v8": "^1.6.0",
+    "eslint": "^8.57.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "peerDependencies": {
+    "neo4j-driver": "^5.0.0",
+    "level": "^8.0.0",
+    "levelgraph": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "neo4j-driver": {
+      "optional": true
+    },
+    "level": {
+      "optional": true
+    },
+    "levelgraph": {
+      "optional": true
+    }
+  }
+}