Skip to content

README.md

Latest commit

 

History

History
120 lines (95 loc) · 3.84 KB

README.md

File metadata and controls

120 lines (95 loc) · 3.84 KB

tutorial-gen

LangGraph multi-agent pipeline that monitors Claude Code's CHANGELOG.md and generates validated tutorials for new features.

Architecture

A supervisor-subagent pattern built on LangGraph:

fetch_changelog → diff_features → [feature loop]
                                       │
                                   supervisor
                                   ╱   │   ╲
                          researcher  writer  script_generator
                                              │
                                          validator ↔ script_fixer
                                              │
                                         save_tutorial → next feature

Components

Layer Files Purpose
State state.py PipelineState TypedDict with reducer annotations
Graph graph.py StateGraph assembly, routing helpers, conditional edges
Agents agents/supervisor.py Routes work via structured output (RouteDecision)
agents/researcher.py Classifies feature type, gathers context
agents/writer.py Generates tutorial markdown
agents/script_generator.py Creates executable demo scripts
agents/validator.py Runs scripts in sandboxed subprocess
agents/script_fixer.py Repairs scripts that fail validation
Nodes nodes/fetch.py Fetches CHANGELOG.md from GitHub
nodes/diff.py Parses changelog, filters already-processed features
nodes/save.py Writes tutorial files, updates DB
DB db.py SQLite tracking for processed features
CLI cli.py Click-based CLI (tutgen run/status/list)

Setup

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Required environment variables (.env or exported):

ANTHROPIC_API_KEY=sk-ant-...

Usage

# Full pipeline — fetch changelog, generate tutorials for all new features
tutgen run

# Limit to N features
tutgen run --limit 3

# Preview what would be generated (no LLM calls)
tutgen run --dry-run

# Check processing status
tutgen status

# List generated tutorials
tutgen list

Output is written to tutorials/<date>-<slug>/ with tutorial.md and demo.sh.

Generated Script Patterns

The pipeline generates scripts that mirror realistic Claude Code usage:

  • Session chaining (primary) — captures session_id via --output-format json, then uses --resume for multi-step workflows
  • Slash commands (/simplify, /cost, etc.) — demonstrated via session chaining since they are interactive commands used inside Claude sessions, not standalone CLI args
  • File-based workflows — creates project files, then uses session chaining for iterative work
  • Simple one-shots — claude -p for standalone demos only

Testing

pytest tests/ -v

42 tests covering all agents (mocked LLM), nodes, graph construction, routing, and save logic.

Project Structure

src/tutorial_gen/
├── agents/           # LLM-powered subagents
│   ├── __init__.py   # Shared extract_script utility
│   ├── supervisor.py
│   ├── researcher.py
│   ├── writer.py
│   ├── script_generator.py
│   ├── script_fixer.py
│   └── validator.py
├── nodes/            # Non-LLM processing nodes
│   ├── fetch.py
│   ├── diff.py
│   └── save.py
├── prompts/          # Prompt templates per agent
├── state.py          # PipelineState schema
├── graph.py          # StateGraph construction
├── db.py             # SQLite feature tracking
└── cli.py            # CLI entry point
tests/
├── test_agents.py
├── test_diff.py
├── test_fetch.py
├── test_graph.py
├── test_save.py
├── test_supervisor.py
└── test_validate.py