Weave your lecture slides into comprehensive, structured Markdown handouts with AI.
Never miss a detail from your lecture slides again.
Weave is an AI-powered tool that transforms PDF slides into structured Markdown study guides. It offers a modern web interface for point-and-click usage, a FastAPI backend for job orchestration, and a CLI for scripting and automation.
- Modern Web UI — Upload PDFs, choose an AI provider/model, track progress, preview Markdown, and download results
- Multi-provider AI — Use Google Gemini, OpenAI, or Anthropic Claude from the web UI or CLI
- Two-Pass AI Analysis — First generates a structured outline, then expands each chapter with full context
- PDF to Handout — Converts multi-page PDF slides into a single, well-organized Markdown document
- Smart Image Embedding — Automatically identifies and embeds important charts, diagrams, and formulas
- Coverage Verification — Ensures every single slide page is referenced in the final handout
- Multi-language Output — Generate handouts in any language (default: Traditional Chinese)
- Zero Content Loss — Preserves ALL information from slides, including footnotes and small annotations
- Rendered Markdown Preview — View the generated handout in the browser with images, tables, code blocks, and headings
- PDF Export — Export generated handouts to styled PDFs from the web UI or CLI
| Provider | API key environment variable | Example models |
|---|---|---|
| Google Gemini | GEMINI_API_KEY |
gemini-2.5-flash, gemini-2.5-pro, gemini-3-flash-preview |
| OpenAI | OPENAI_API_KEY |
gpt-5.4-pro, gpt-5.4, gpt-5-mini, gpt-4.1 |
| Anthropic Claude | ANTHROPIC_API_KEY |
claude-sonnet-4-5, claude-opus-4-7 |
Gemini remains the default provider, but you can switch providers in the web UI or with --provider in the CLI.
- Python 3.10+ and Node.js 18+
- Poppler — required for PDF rendering
- Pango — required for PDF export
- An API key for at least one supported provider: Google AI Studio, OpenAI Platform, or Anthropic Console
# macOS
brew install poppler pango
# Ubuntu / Debian
sudo apt-get install poppler-utils libpango-1.0-0 libpangoft2-1.0-0git clone https://github.com/ReeveWu/weave.git
cd weaveRun this once to set up the Python virtual environment and install all dependencies:
npm run setupThis command:
- Creates a Python virtual environment at
.venv/ - Installs the
weavePython package and all server dependencies - Installs frontend (
client/) npm packages
npm run startThis launches both servers concurrently:
- Backend API at
http://localhost:8000 - Web UI at
http://localhost:3000
Open http://localhost:3000 in your browser.
- Upload PDFs — Drag and drop (or click to browse) one or more PDF slide files
- Configure — Choose Gemini, OpenAI, or Claude; enter the matching API key; pick a model and output language; optionally enable PDF export
- Run — Click Start and watch real-time progress across each pipeline stage
- Get results — View the rendered Markdown handout, then copy, download, or export as PDF
The CLI is ideal for scripting, automation, or batch processing. It requires the Python environment to be set up (see above).
Activate the virtual environment first:
source .venv/bin/activatePlace your PDF slides in ./data/, then:
# Full pipeline — PDF slides → Markdown handout
weave
# Specify custom input/output directories
weave -i ./my-slides -o ./my-notes
# Use a specific model
weave -m gemini-2.5-pro
# Use OpenAI
weave --provider openai -m gpt-5.4-mini -k "your-openai-api-key"
# Use Claude
weave --provider claude -m claude-sonnet-4-5 -k "your-anthropic-api-key"
# Generate outline only (preview the structure before full expansion)
weave --outline-only
# Generate in English
weave --language English
# Full pipeline + PDF export
weave --pdf
# Pass API key directly (no .env file needed)
weave -k "your-api-key" -i ./slides
# If Gemini returns 503 / high demand, increase retry patience
weave --unavailable-retry-delay 60 --max-retries 6
# Convert an existing Markdown file to PDF standalone
weave-pdf output/20260325_160828/handout.md
weave-pdf handout.md -o my_handout.pdfFor the CLI, you can set your API key via .env instead of passing -k each time:
cp .env.example .env
# Edit .env and set one or more provider keys:
GEMINI_API_KEY=your_gemini_key
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
# Optional defaults
WEAVE_PROVIDER=gemini
WEAVE_MODEL=gemini-2.5-flashSee docs/cli-reference.md for the full list of options.
-
Pass 1 — Outline Generation: All slide images are sent to the AI to produce a tree-structured chapter outline with page references. This gives the AI a bird's-eye view of the entire lecture.
-
Pass 2 — Chapter Expansion: Each chapter is expanded individually with its corresponding slide images and the full outline as context. This ensures detailed, contextually-aware content while preserving every detail.
-
Post-processing: Referenced images are copied to the output folder, coverage is verified (ensuring no slide is missed), and temporary files are cleaned up.
Each run creates a timestamped subfolder under the output directory:
output/
└── 20260325_160828/ # Timestamped folder (YYYYMMDD_HHMMSS)
├── handout.md # The complete Markdown handout
├── handout.pdf # PDF version (when PDF export is enabled)
└── images/ # Embedded slide images (charts, diagrams, etc.)
├── slide_01_page_005.jpg
├── slide_01_page_012.jpg
└── ...
Weave can also be used as a Python library. See docs/programmatic-usage.md for details.
from pathlib import Path
from weave import PipelineConfig, run_pipeline
config = PipelineConfig(
input_dir=Path("./my-slides"),
output_dir=Path("./my-notes"),
temp_dir=Path("./tmp"),
provider="gemini",
api_key="your-api-key",
model="gemini-2.5-flash",
language="English",
)
run_pipeline(config)See docs/troubleshooting.md for common issues and solutions.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
This project is licensed under the MIT License — see LICENSE for details.
