How shuchi111/lessonforge works
LessonForge turns a topic into a beginner lesson, evaluates it against deterministic and model-judged rubric checks, revises failed attempts, and publishes the best result. Its principal workflow is orchestrated by the LangGraph pipeline; persistent memory and reflection create a second, cross-run learning loop. The README documents the main stage connections and capabilities. Some modules are indexed but not excerpted, so edges below rely on those documented relationships rather than claiming their unsampled internals were inspected.
Main entry points: graph.py Workflow graph · memory.py SQLite run memory · evaluate.py Evaluation coordinator · deterministic.py Code checks
Components 24
User entry points
- Command interface
src/lessonforge/cli.py - Run visualizer
app.py
Lesson workflow
- Dependency factory
src/lessonforge/factory.py - Workflow graph
src/lessonforge/graph.py - Plan and revise
src/lessonforge/prompts.py - Lesson structure
src/lessonforge/lesson_format.py - Error injection
src/lessonforge/inject.py - Run artifacts
src/lessonforge/render.py - Groq model access
src/lessonforge/llm.py - Runtime settings
src/lessonforge/config.py
Quality evaluation
- Evaluation coordinator
src/lessonforge/evaluator/evaluate.py - Code checks
src/lessonforge/evaluator/deterministic.py - Text analysis
src/lessonforge/evaluator/text.py - LLM judges
src/lessonforge/evaluator/judges.py - Run and verdict schemas
src/lessonforge/schemas.py
Knowledge and prompts
- Topic and rules loader
src/lessonforge/knowledge.py - Topic facts
data/topics/rag/topic.yaml - Fact sheet
data/topics/rag/fact_sheet.md - Quality rubric
data/rubric.yaml - Jargon rules
data/jargon.yaml
Memory and learning
- SQLite run memory
src/lessonforge/memory.py - Cross-run reflection
src/lessonforge/reflection.py
Other components
- Topic author
- Human reviewer
Connections 32
- Topic author → Command interface: starts run
README.md - Command interface → Dependency factory: builds dependencies
README.md - Dependency factory → Workflow graph: creates workflow
README.md - Workflow graph → Topic and rules loader: loads topic pack
README.md - Topic and rules loader → Topic facts: reads topic data
README.md - Topic and rules loader → Fact sheet: reads facts
README.md - Workflow graph → SQLite run memory: loads learned rules
README.md - Workflow graph → Plan and revise: plans and revises
README.md - Plan and revise → Groq model access: requests writing
README.md - Plan and revise → Lesson structure: uses structure
README.md - Workflow graph → Error injection: injects errors
README.md - Workflow graph → Evaluation coordinator: evaluates attempts
README.md - Evaluation coordinator → Code checks: runs code checks
README.md - Evaluation coordinator → LLM judges: runs model checks
README.md - Code checks → Text analysis: analyzes text
src/lessonforge/evaluator/deterministic.py - Code checks → Quality rubric: applies checks
README.md - Code checks → Jargon rules: checks jargon
README.md - LLM judges → Groq model access: requests verdicts
README.md - LLM judges → Fact sheet: grounds accuracy
README.md - Workflow graph → Run artifacts: writes outputs
README.md - Workflow graph → SQLite run memory: persists run
README.md - Workflow graph → Cross-run reflection: triggers learning
README.md - Cross-run reflection → SQLite run memory: reads failures
src/lessonforge/reflection.py - Cross-run reflection → Groq model access: proposes rules
src/lessonforge/reflection.py - Cross-run reflection → Plan and revise: informs future writing
README.md - Command interface → SQLite run memory: manages feedback
README.md - Human reviewer → Command interface: submits feedback
README.md - Workflow graph → Human reviewer: flags failed result
README.md - Topic author → Run visualizer: opens walkthrough
README.md - Run visualizer → SQLite run memory: shows run history
app.py - Dependency factory → Runtime settings: loads settings
README.md - Evaluation coordinator → Run and verdict schemas: returns evaluations
src/lessonforge/evaluator/evaluate.py