How jwtor7/deck-builder works
Project Type & Purpose
• Decker is a CLI-based developer tool written in Python that transforms plain-text outlines into well-structured Markdown slide decks (Marp/Reveal.js), handouts, run-of-show timelines, and metadata.
• It’s not a web app or microservice; it’s a command-line pipeline tool with pluggable templates and an offline LLM (Ollama) integration.
File Structure Analysis
• Top-level:
• decker.py — executable entrypoint
• decker/ — core package
• templates/ — sample YAML templates
• examples/ — sample outlines
• decker.config.yml.example — default configuration schema
• tests — test_decker.py, test_v2.py
• Inside decker/:
• cli.py — argument parsing & command dispatcher
• pipeline.py — orchestrates the end-to-end process
• parser.py — reads & tokenizes outline text
• llm.py — calls the Ollama API for content generation
• formatter.py — applies Marp or Reveal formatting rules
• writers.py — writes Markdown, JSON outputs
• validator.py — runs post-generation quality checks
• templates.py — loads built-in & custom template definitions
• utils.py — helper functions
README Insights
• Describes a clear step-by-step build → preview → ros workflow.
• Emphasizes configuration via decker.config.yml.
• Lists output artifacts (deck.md, handout.md, run_of_show.md, meta.json).
• Shows a minimal “Architecture” section mapping modules.
Components
a. CLI Layer
• decker.py
• cli.py
b. Orchestration Layer
• pipeline.py
c. Processing Modules
• Parser (parser.py)
• Template Loader (templates.py)
• LLM Client (llm.py)
• Formatter (formatter.py)
• Validator (validator.py)
• Writers (writers.py)
• Utils (utils.py)
d. Configuration
• decker.config.yml (defaults + overrides)
e. External Dependencies
• Ollama (local LLM service)
• Marp CLI (optional PDF/preview)
f. I/O
• Input: outline file or inline text + templates/*.yml
• Output: outputs/<timestamp>/{deck.md, handout.md, run_of_show.md, meta.json}
Relationships & Data Flows
1. User invokes decker.py → CLI parses flags (cli.py).
2. CLI calls pipeline.build() in pipeline.py.
3. Pipeline loads configuration.
4. Pipeline calls parser.parse() → returns structured outline.
5. Pipeline calls templates.load() → selects template spec.
6. Pipeline sends outline + template to llm.generate() → receives raw slide content.
7. Pipeline passes raw content through validator.validate().
8. Pipeline hands validated content to formatter.format() → applies Marp/Reveal syntax.
9. Pipeline triggers writers.write_all() → writes deck.md, handout.md, run_of_show.md, meta.json.
10. CLI returns success or error (with trace logs if requested).
Architectural Patterns & Design Principles
• Modular pipeline (each stage is a separate module).
• Single-responsibility principle (parser, llm, formatter, writer are decoupled).
• Plugin/extensibility via templates.py (YAML-driven templates).
• Deterministic output via seed parameter.
• Offline-first design (local Ollama service with fallback models).
• Clear separation of concerns: CLI vs orchestration vs processing vs I/O.
Technologies & Frameworks
• Python 3.11+
• Ollama LLM API
• Marp Markdown & Reveal.js syntax
• YAML for template definitions
• pytest for tests (test_decker.py, test_v2.py)
Essential Elements Checklist
• [ ] External service: Ollama
• [ ] Inputs: outline file, YAML templates, config file
• [ ] Outputs: deck.md, handout.md, run_of_show.md, meta.json