Lerna

A domain-agnostic Curriculum Architect AI that creates structured, prerequisite-aware course outlines for any subject.

---

What is Lerna?

Lerna is a multi-model AI pipeline designed to generate comprehensive learning curricula. Given a subject, duration, and learner preferences, it produces week-by-week course outlines with embedded resources—ready for a human learner to follow.

Core Principles

Principle	Description
Prerequisites First	Foundational topics always appear before dependent ones
Text-First Resources	Prioritizes textbooks, lecture notes, essays, blogs, and papers over videos
Integrated Resources	Resources are embedded directly in each week, not listed separately
Conceptual Depth	Explains why each topic matters—avoids buzzwords and shallow checklists
Domain-Agnostic	Works for mathematics, philosophy, programming, music theory, or any learnable subject

---

Installation

1. Clone the repository:

   git clone https://github.com/danielkestrel/lerna.git
   cd lerna

2. Set up a virtual environment (recommended):

   python3 -m venv venv
   source venv/bin/activate

3. Install dependencies:

   pip install -e .

4. Configure API Keys: Copy the example configuration and add your API keys:

   cp .env.example .env

   Edit .env and add your key (OpenAI, Anthropic, or Groq).

---

Usage

Lerna provides a simple command-line interface.

Generate a Course

Run the interactive generator:

lerna generate

Or provide arguments directly:

lerna generate --subject "Quantum Physics" --duration "1 month"

Options

Flag	Description
-s, --subject	Subject to learn
-d, --duration	Duration (e.g., "1 week", "3 months")
-p, --preferences	Learning preferences (default: "text-first")
-b, --background	Your prior knowledge
--save	Save output to ./output/ directory
-o, --output	Save to a specific file path
--raw	Output raw markdown without formatting
-v, --verbose	Show progress logs

Example Command

lerna generate \
  --subject "Machine Learning" \
  --duration "6 weeks" \
  --preferences "code-heavy, project-based" \
  --background "Python developer" \
  --verbose

---

Architecture

Lerna uses a staged pipeline to minimize cost while maximizing output quality:

┌─────────────────────────────────────────────────────────┐
│                         User                            │
│   (Subject, Duration, Preferences, Background)          │
└───────────────────────────┬─────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────┐
│                    Parser Model                         │
│            (small/free — extracts intent)               │
└───────────────────────────┬─────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────┐
│                    Planner Model                        │
│     (small/free — generates prerequisite-ordered        │
│              weekly topic sequence)                     │
└───────────────────────────┬─────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────┐
│                    Writer Model                         │
│   (best free-tier — expands plan into full outline)     │
└───────────────────────────┬─────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────┐
│               Local Validator (optional)                │
│        (checks structure and completeness)              │
└───────────────────────────┬─────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────┐
│                     Final Output                        │
│           (Complete course outline in Markdown)         │
└─────────────────────────────────────────────────────────┘

Why This Design?

• Cost-efficient: Only the Writer model performs long-form generation
• Free-tier friendly: Single-pass generation avoids token-heavy iterations
• Modular: Each stage can be swapped or upgraded independently

---

Output Format

Lerna produces structured Markdown with the following format:

# Course Title

## Course Goals
- Goal 1
- Goal 2
- ...

## Assumed Background
[Prerequisites the learner should have]

## Course Duration: <duration>
## Total Units: <number>

---

## Week-by-Week Breakdown

### Week 1 — <Topic>
- **Core concepts**: [What you'll learn]
- **Why this matters**: [1–2 sentences on importance]
- **Primary texts**: [Books, papers, lecture notes]
- **Optional readings**: [Supplementary materials]
- **Optional videos**: [If applicable]

### Week 2 — <Topic>
...

---

Example

Input

Field	Value
Subject	1-year mathematics course
Duration	52 weeks
Preferences	Emphasize fundamentals, prefer texts, videos optional
Background	High school math

Planner Output (abbreviated)

Week 1: Mathematical Thinking and Proof
Week 2: Sets, Relations, and Functions
Week 3: Number Theory Basics
Week 4: Linear Algebra Fundamentals
...
Week 52: Synthesis and Mathematical Maturity

Writer Output (excerpt)

### Week 1 — Mathematical Thinking and Proof

- **Core concepts**: Logic, propositions, direct and indirect proofs, 
  mathematical induction
- **Why this matters**: Proof is the language of mathematics. Without it, 
  results are just conjectures. This week builds the mental toolkit you'll 
  use for everything that follows.
- **Primary texts**: 
  - *How to Prove It* by Daniel Velleman (Chapters 1–2)
  - *Book of Proof* by Richard Hammack (free PDF) — Chapters 1–4
- **Optional readings**: 
  - Terence Tao's blog post on "What is good mathematics?"
- **Optional videos**: 
  - 3Blue1Brown: "Lockdown Math" series (first 2 episodes)

---

Design Constraints

Constraint	Rationale
Single-pass generation	Avoids expensive iterative refinement; keeps within free-tier limits
No persistent storage	Stateless by design—each request is independent
No real-time resource verification	Resources are recommended based on training data, not live availability
Depth-coherence tradeoff	Very long courses (52+ weeks) may sacrifice depth to maintain structural coherence

---

Writer Model Prompt Rules

The Writer model follows strict rules to ensure consistent, high-quality output:

1. Follow the weekly plan exactly — No adding, removing, or reordering weeks
2. Prerequisites first — Foundational topics must precede dependent ones
3. Text-first resources — Textbooks > papers > essays > blogs > videos
4. Conceptual depth — Each topic includes 1–2 lines on why it matters
5. Embedded resources — No separate resource lists; everything is inline
6. Single-pass only — No self-correction or iterative refinement

---

Roadmap

• Implement Parser Model
• Implement Planner Model
• Implement Writer Model
• Add optional Local Validator
• Create CLI interface
• Add support for custom resource databases

---

License

MIT

---

Name Origin

Named after the Lernaean Hydra's domain—but instead of growing heads, Lerna grows knowledge trees.