md2pptx — Markdown → PowerPoint Pipeline

Hackathon submission — Converts any .md file into a structured, visually polished .pptx presentation that loads the provided Slide Master and generates all visuals programmatically.

---

Quick Start

# 1. Install dependencies
pip install -r requirements.txt

# 2. Run
python main.py \
  --input  "path/to/report.md" \
  --master "path/to/slide_master.pptx" \
  --output "path/to/output.pptx"

Optional flags

Flag	Default	Description
--target-slides N	auto	Preferred slide count (10–15)
--min-slides N	10	Hard minimum
--max-slides N	15	Hard maximum
--plan-output path	—	Write slide plan as JSON
--report-output path	—	Write run-metadata report as JSON
--theme-override HEX	—	Override primary accent colour (e.g. FF5733)
--version	—	Print version and exit

Example commands

# 12-slide deck + debug artefacts
python main.py \
  --input   "Code EZ_ Master of Agents _ Files/Test Cases/Accenture Tech Acquisition Analysis.md" \
  --master  "Code EZ_ Master of Agents _ Files/Slide Master/Template_Accenture Tech Acquisition Analysis.pptx" \
  --output  "generated_pptx/Accenture Tech Acquisition Analysis/output.pptx" \
  --target-slides 12 \
  --plan-output  "generated_pptx/Accenture Tech Acquisition Analysis/slide_plan.json" \
  --report-output "generated_pptx/Accenture Tech Acquisition Analysis/run_report.json"

# 10-slide deck
python main.py \
  --input  "Code EZ_ Master of Agents _ Files/Test Cases/AI Bubble_ Detection, Prevention, and Investment Strategies.md" \
  --master "Code EZ_ Master of Agents _ Files/Slide Master/Template_AI Bubble_ Detection, Prevention, and Investment Strategies.pptx" \
  --output "generated_pptx/AI Bubble/output.pptx" \
  --target-slides 10

---

System Architecture

Markdown (.md)  [≤ 5 MB]
      │
      ▼
┌─────────────┐
│  parser.py  │  Extracts: title · sections · bullets · tables · blockquotes
│             │            ordered-lists · numeric snippets · code blocks
└──────┬──────┘
       │  structured content dict
       ▼
┌─────────────┐
│  planner.py │  Builds 10-15 slide story-line:
│             │  slide types · layout choices · budget control
└──────┬──────┘
       │  slide_plan  (list of slide spec dicts)
       ▼
┌──────────────────────────────────────────────────────────┐
│                      renderer.py                         │
│  ┌─────────────┐  ┌────────────────┐  ┌───────────────┐ │
│  │  charts.py  │  │infographics.py │  │layout_builder │ │
│  │  native PPT │  │shapes only:    │  │dynamic layout │ │
│  │  chart objs │  │process/timeline│  │cloning if     │ │
│  │  4 types    │  │comparison/cycle│  │layout missing │ │
│  │  + colours  │  │pyramid/icons   │  │in master      │ │
│  └─────────────┘  └────────────────┘  └───────────────┘ │
└──────────────────────────────────────────────────────────┘
       │
       ▼
PowerPoint (.pptx) — loaded from provided master, never blank

---

Slide Type Catalog

Type	Description	Layout
title	Opening slide + subtitle	1_Cover
agenda	Numbered card row of section names	Title only
summary	Metric cards + key-points callout	2_Cover
bullets	2×2 card grid	Title only
two_column	Side-by-side coloured panels	Blank
visual_bullets	Metric row + bullet callout	Blank
stats	Large-number metric cards with icons	Blank
table	Styled table + Highlights column	Title only
chart	Native editable chart + Insights box	Blank
infographic	Process / Timeline / Comparison / Cycle / Pyramid / Icon strip	Blank
quote	Full-bleed italic blockquote panel	Blank
divider	Section transition slide	Divider
conclusion	Key Takeaways card grid	Thank You

---

Visual Design System

Every slide is constructed from programmatic shapes only — no downloaded images, no copyrighted assets.

Element	Detail
Accent bar	0.12 in coloured left-edge rectangle on every content slide
Section strip	Coloured rounded-rectangle label beneath title
Footer bar	Full-width coloured band at slide bottom with N / Total counter
Card shadows	Grey offset rectangle behind each card (simulated depth)
Background tint	Light #F4F7FC full-bleed tint on title, summary, divider, conclusion
Colour	Extracted from the provided master's <a:clrScheme> XML
Typography	Inherits master fonts; sizes from Pt(10) body → Pt(26) title → Pt(36) metric value

---

Key Design Decisions

1. Master-first loading — Presentation(master_path) loads the provided .pptx instead of creating a blank deck, so every theme, layout, and color palette is inherited automatically.

2. Editable native charts — charts.py uses python-pptx's add_chart() API to create proper OLE chart objects. These stay editable in Microsoft 365, Google Slides, and LibreOffice (unlike PNG images).

3. Modular pipeline — parser → planner → renderer are independent. Parsing can be upgraded (e.g. AST-based) without touching rendering, and new slide types can be added to the planner/renderer without changing parsing logic.

4. Infographic variety — infographics.py dispatches to 6 diagram types based on heading keywords: process, timeline, comparison, cycle, pyramid, and icon_strip. All rendered as shapes.

5. Dynamic layout fallback — layout_builder.py clones the Blank layout XML if a requested layout is missing from the master, so the pipeline never crashes due to a missing layout.

6. Graceful degradation — Missing numeric data → chart slides silently skipped. Un-structured markdown → paragraph-only fallback sections. Malformed tables → skipped with no crash.

---

Known Limitations & Graceful Fallbacks

Scenario	Behaviour
No ## headings	Paragraphs split into pseudo-sections
No numeric data	Chart slides omitted; no empty chart frames
Master missing a layout	layout_builder.py clones Blank; visual coherence preserved
Input > 5 MB	Rejected immediately with a clear error message
Extremely sparse markdown	Divider slides backfill to reach min_slides
Malformed table	Skipped, surrounding text still parsed
Code blocks	Captured but not rendered (avoids walls of monospace text)

---

Scoring Alignment

Criterion (weight)	Where addressed
Visual Quality (30%)	renderer.py — accent bars, footer, shadows, card grid, 13 slide types
Code Quality (30%)	Modular 5-module pipeline; docstrings; typed signatures throughout
Chart & Table Generation (15%)	charts.py — 4 chart types, palette colours, data labels, 4 candidates
Content Coverage (15%)	parser.py + planner.py — sub-bullets, blockquotes, ordered lists, smart merge
Innovation (10%)	layout_builder.py (dynamic layouts) · --theme-override flag · icon-strip infographic

---

Repository Structure

EZ/
├── main.py                     # Root entry point (thin shim)
├── requirements.txt
├── README.md
├── SUBMISSION_CHECKLIST.md
├── LOOM_SCRIPT.md
├── demo_commands.txt
├── src/
│   ├── __init__.py
│   ├── main.py                 # CLI arg parsing + pipeline orchestration
│   ├── parser.py               # Markdown → structured content dict
│   ├── planner.py              # Content → 10-15 slide plan
│   ├── renderer.py             # Slide plan → .pptx (shapes + charts)
│   ├── charts.py               # Native editable PowerPoint chart generation
│   ├── infographics.py         # Programmatic infographic shapes (6 types)
│   └── layout_builder.py       # Dynamic layout cloning for missing layouts
└── generated_pptx/
    ├── Accenture Tech Acquisition Analysis/
    │   ├── source.md
    │   ├── output.pptx
    │   ├── slide_plan.json
    │   └── run_report.json
    ├── AI Bubble/
    │   ├── source.md
    │   └── output.pptx
    └── UAE Solar/
        ├── source.md
        └── output.pptx

---

Compliance

• [PASSED] Output is a valid .pptx (tested in Microsoft 365, Google Slides, LibreOffice Impress)
• [PASSED] Slide count always 10–15
• [PASSED] No copyrighted images (all shapes + Unicode symbols)
• [PASSED] Slide Master loaded, never bypassed
• [PASSED] Input size limit enforced (5 MB)
• [PASSED] Charts are editable native PowerPoint objects