Getting Started

Getting Started

This page takes a stranger from a clean machine to a finished review pack made from a synthetic deck. The tests and the first three stages need only Python; the render stage, and therefore the full run command, needs LibreOffice.

What it needs

• Python 3.11 or later; the checks recorded on this wiki ran on 3.12 under Windows.
• Git, to clone the repository.
• LibreOffice, for the render stage and for run. The tool looks for soffice on the PATH, then in the SOFFICE_PATH environment variable, then in the standard install folders for Windows, Linux, and macOS, and it raises an error that names the problem when none of them answers.
• Nothing else. No account, no API key, and no network access after the install.

extract, reconcile, audit, align, inspect, and validate do not call LibreOffice, and neither do 44 of the 45 tests. build-docx does not call it either, though it needs the slide images that the render stage produces.

Install and test

git clone https://github.com/dboles99/SlideBridge.git
cd SlideBridge
python -m venv .venv
.venv/bin/pip install -e ".[dev]"      # Windows: .venv\Scripts\pip install -e ".[dev]"
.venv/bin/python -m pytest             # Windows: .venv\Scripts\python -m pytest

Expected output without LibreOffice on the PATH:

........................s....................                            [100%]
44 passed, 1 skipped in 6.62s

With soffice on the PATH, the skipped test runs as well and the last line reads 45 passed, with one warning from PyMuPDF about its older fitz import name. The repository also ships a uv.lock, and uv sync --group dev produces the same environment.

First run: a synthetic deck

The example script writes a 17-slide deck from code, with a table on every third slide and speaker notes on every fourth. Run both commands from the repository root:

.venv/bin/python -m examples.make_sample_deck
.venv/bin/slidebridge run input/sample.pptx --workdir work --out output/review_pack.docx --dpi 100

The first command prints wrote input/sample.pptx. The second prints a progress line for each stage and ends with this summary, which took about 5 seconds on the machine used here:

────────────────────────────── Pipeline complete ───────────────────────────────
[DONE] extract -> work\json
[DONE] render -> work\images
[DONE] reconcile -> work\reconciled\manifest.json
[DONE] build-docx -> output\review_pack.docx
[DONE] audit -> output

Output: output\review_pack.docx

Four files appear in output/: review_pack.docx, slides.csv, warnings.csv, and run_report.json. The report reads:

{"total_files": 1, "total_slides": 17, "total_images": 17, "low_confidence_slides": 0, "warnings": 5}

Open review_pack.docx in Word. Each slide has a heading such as Slide 1 - Example Deck 2025, a line of metadata with the source file, slide number, confidence, and warning count, the screenshot, and a four-column table with the headings Order, Original Extracted Text, Edited Text, and Notes. The Edited Text column is empty, ready for the reviewer.

The commands, one at a time

Each stage is also a command, so a run can stop where the user wants it to.

.venv/bin/slidebridge inspect input/sample.pptx            # slide count, notes present
.venv/bin/slidebridge extract input/sample.pptx --out work/json --pretty
.venv/bin/slidebridge validate work/reconciled/manifest.json

inspect prints a small table with the file name, 17 slides, and Yes under Has Notes. validate prints Manifest is valid. and exits with code 0 when the manifest passes its JSON Schema. docs/cli.md in the repository lists every command and option, including init, clean, and --resume, which skips decks whose JSON already exists and renders that already validate.

Aligning an edited document

align takes the review pack and a separately edited DOCX, and fills the Edited Text column by matching text:

.venv/bin/slidebridge align output/review_pack.docx edited.docx --out output/aligned.docx

It prints an alignment summary by change type and writes the new file. Check its output by eye, and read the two reproduced failures on Evidence before relying on it. The desktop interface, slidebridge-gui, wraps the same pipeline in a Tkinter window.