# LearnGraph

**The world's first AI-powered learning path generator.**

Transform any syllabus into personalized mastery paths with learning science built in. Every student's path to mastery, powered by decades of educational research.

[![npm version](https://img.shields.io/npm/v/learngraph.svg)](https://www.npmjs.com/package/learngraph)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Why LearnGraph?

**The Problem**: Traditional curricula treat all learners the same. They present content linearly, ignore prerequisite gaps, and fail to adapt to individual progress.

**The Solution**: LearnGraph decomposes curricula into skill graphs, automatically identifies each learner's Zone of Proximal Development (ZPD), and generates personalized learning paths that respect cognitive load limits.

### Key Features

- **Zone of Proximal Development (ZPD)** - Identifies skills that are challenging but achievable
- **Bloom's Taxonomy Integration** - Automatic detection and progression through cognitive levels
- **Bayesian Knowledge Tracing (BKT)** - Probabilistic mastery estimation from performance data
- **Spaced Repetition** - Optimal review scheduling based on memory science
- **Prerequisite Mapping** - Hard, soft, and recommended dependency relationships
- **Threshold Concepts** - Identifies transformative "gateway" skills that unlock understanding
- **Cognitive Load Management** - Respects working memory limits in session planning

## Installation

```bash
npm install learngraph
```

## Quick Start

```typescript
import {
  createSkillId,
  detectBloomLevel,
  hasMastery,
  type SkillNode
} from 'learngraph';

// Detect Bloom's level from a learning objective
const level = detectBloomLevel('Calculate the derivative of a polynomial');
console.log(level); // 'apply'

// Define a skill in the knowledge graph
const skill: SkillNode = {
  id: createSkillId('derivatives-polynomials'),
  name: 'Polynomial Derivatives',
  description: 'Calculate derivatives of polynomial functions using power rule',
  bloomLevel: 'apply',
  difficulty: 0.4,
  isThresholdConcept: false,
  masteryThreshold: 0.8,
  estimatedMinutes: 30,
  tags: ['calculus', 'derivatives'],
  metadata: {},
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString(),
};

// Check if learner has mastered a skill
const mastered = hasMastery(0.85); // true (above 0.8 threshold)
```

## Educational Research Foundations

LearnGraph is built on decades of peer-reviewed educational psychology research:

| Framework | Purpose | Key Benefit |
|-----------|---------|-------------|
| **Zone of Proximal Development** | Vygotsky's theory of optimal learning challenge | Keeps learners in the "sweet spot" |
| **Bloom's Taxonomy** | Cognitive complexity hierarchy | Ensures proper skill progression |
| **Bayesian Knowledge Tracing** | Probabilistic mastery modeling | Accurate knowledge state estimation |
| **Item Response Theory** | Skill difficulty calibration | Fair assessment across items |
| **Spaced Repetition** | Memory consolidation optimization | Long-term retention |
| **Cognitive Load Theory** | Working memory management | Prevents overwhelm |

## Storage Adapters

LearnGraph supports multiple storage backends. Use the one that fits your needs:

### In-Memory Storage (Built-in)

Perfect for testing, prototyping, and serverless functions:

```typescript
import { MemoryStorage } from 'learngraph/storage';

const storage = new MemoryStorage();
await storage.connect({ backend: 'memory' });

// 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: {}
});

// Create prerequisite relationships
await storage.createPrerequisite({
  sourceId: basicMathSkill.id,
  targetId: skill.id,
  strength: 0.9,
  type: 'hard',
  metadata: {}
});

// Query the graph
const prerequisites = await storage.getPrerequisitesOf(skill.id);
const stats = await storage.getStats();
```

### LevelGraph Storage (Embedded)

For persistent, file-based storage without external databases:

```bash
npm install level levelgraph
```

```typescript
import { LevelGraphStorage } from 'learngraph/storage';

const storage = new LevelGraphStorage();
await storage.connect({
  backend: 'levelgraph',
  path: './data/learngraph'
});
```

### Neo4j Storage (Production)

For production deployments with full graph database capabilities:

```bash
npm install neo4j-driver
```

```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'
});
```

## LLM-Powered Curriculum Decomposition

LearnGraph can automatically decompose curriculum content into skill graphs using LLMs:

```typescript
import { createOpenAIAdapter, createOrchestrator } from 'learngraph/llm';

// Create an adapter (OpenAI, Anthropic, or Ollama)
const adapter = createOpenAIAdapter('gpt-4o');
const orchestrator = createOrchestrator(adapter);

// Extract skills from curriculum content
const extraction = await orchestrator.extractSkills({
  content: `
    Chapter 1: Introduction to Calculus
    - Understand the concept of limits
    - Calculate derivatives using the power rule
    - Apply differentiation to real-world problems
  `,
  domain: 'Mathematics',
  gradeLevel: 'College',
});

console.log(extraction.skills);
// [{ name: 'Limits', bloomLevel: 'understand', ... }, ...]

// Infer prerequisites between skills
const prerequisites = await orchestrator.inferPrerequisites({
  skills: extraction.skills,
  domain: 'Mathematics',
});

// Full decomposition: skills + prerequisites in one call
const decomposition = await orchestrator.decompose({
  content: 'Full calculus syllabus here...',
  title: 'Calculus I',
  domain: 'Mathematics',
});

// Returns: { title, skills, prerequisites, skillInputs }
// skillInputs are ready to insert into storage
```

### Supported LLM Providers

```typescript
import {
  createOpenAIAdapter,    // GPT-4o, GPT-4, GPT-3.5
  createAnthropicAdapter, // Claude 3.5, Claude 3
  createOllamaAdapter,    // Llama, Mistral, etc.
} from 'learngraph/llm';

// OpenAI (set OPENAI_API_KEY env var)
const openai = createOpenAIAdapter('gpt-4o');

// Anthropic (set ANTHROPIC_API_KEY env var)
const anthropic = createAnthropicAdapter('claude-3-5-sonnet-20241022');

// Ollama (local models, no API key needed)
const ollama = createOllamaAdapter('llama3.2');
```

### Bloom's Taxonomy Analysis

Analyze the cognitive level of learning objectives:

```typescript
const analysis = await orchestrator.analyzeBloomLevel({
  text: 'Compare and contrast mitosis and meiosis',
});

console.log(analysis);
// { level: 'analyze', confidence: 0.9, indicators: ['compare', 'contrast'] }
```

## Submodule Exports

```typescript
// Core types and utilities
import { SkillNode, SkillEdge } from 'learngraph';

// Storage adapters (Memory, LevelGraph, Neo4j)
import { MemoryStorage, LevelGraphStorage, Neo4jStorage } from 'learngraph/storage';

// LLM integration for curriculum decomposition
import {
  createOpenAIAdapter,
  createAnthropicAdapter,
  createOllamaAdapter,
  createOrchestrator,
  LLMOrchestrator,
} from 'learngraph/llm';

// Query builders and ZPD calculation
import { ZPDResult, LearningPath } from 'learngraph/query';

// Educational utilities (Bloom's, mastery, etc.)
import { detectBloomLevel, hasMastery } from 'learngraph/education';
```

## Use Cases

- **Intelligent Tutoring Systems (ITS)** - Build adaptive learning platforms
- **Curriculum Decomposition** - Transform syllabi into skill graphs
- **Learning Path Generation** - Personalized routes to mastery
- **Prerequisite Analysis** - Identify and fill knowledge gaps
- **Competency-Based Education** - Track and verify skill mastery
- **Corporate Training** - Personalized upskilling programs

## Author

**Dr. Ernesto Lee** - Educational technologist and learning scientist

- Website: [https://DrLee.ai](https://DrLee.ai)
- Email: dr.ernesto.lee@gmail.com
- GitHub: [@fenago](https://github.com/fenago)

## Contributing

Contributions are welcome! Please see the [main repository](https://github.com/fenago/Jali) for guidelines.

## License

MIT - See [LICENSE](./LICENSE) for details.

## Links

- [GitHub Repository](https://github.com/fenago/Jali)
- [Issue Tracker](https://github.com/fenago/Jali/issues)
- [Sponsor](https://github.com/sponsors/fenago)