A local web UI over the pagespeak pipeline. Drop a document, run the full conversion or any single phase, watch progress, and read the output — markdown, extracted images, and LLM cost — without touching the CLI.
The console reads a conversions/ directory with two folders:
Add a document two interchangeable ways: drop a file into conversions/in/ in Finder, or use the Upload button on the home page. Either way it appears in the list, ready to convert. A document with no output yet shows as not converted.
A conversion runs in ordered phases. Each writes a checkpoint file you can inspect, and you can run the whole chain or stop/start at any phase.
| Phase | What it does | Checkpoint |
|---|---|---|
| ingest | Convert the source to markdown via the backend (Marker/Docling for PDF, MarkItDown/python-docx for Office), extracting images. | .raw.md |
| cleanup | Tidy markdown: dedup repeated page decorations, strip converter artifacts, normalize whitespace. | .cleaned.md |
| normalize | Optional: fix flattened heading levels (textbook-style docs where everything is one depth). Off unless enabled. | .normalized.md |
| repair | Deterministic ($0) post-normalize heading fixes. | .repaired.md |
| structure | Deterministic ($0) whole-document heading restructuring (demote flat sources, rebalance stray top-level headings); no-op when the hierarchy is already healthy. | .structured.md |
| vision | Run the vision LLM on each extracted image; embed a Mermaid diagram + caption for diagrams, caption-only for photos/screenshots. This is the LLM-spending phase. | .visioned.md → <stem>.md |
| split | Optional: also write one file per section under sections/. | sections/ |
These are the controls in the run form, in plain English.
| Option | What it does |
|---|---|
| images | One choice (the three modes can't be combined into an invalid state): Describe & redraw with AI — the AI looks at every picture and makes a clean diagram + description (uses your Claude plan, or money on a paid engine); Reuse cached results only — free, only reuses results from an earlier run, never looks again; Skip images — ignore pictures (fastest). |
| which AI looks at images | The default is free — it uses your Claude plan. The other two (openrouter, anthropic) charge real money for every image. |
| preset | Start from a ready-made bundle of settings for a common goal: rag-default (tuned for feeding an AI/search database), textbook, flat, archival. Anything you change yourself still wins. |
| tidy the text | How much to clean up the converted text. off = leave as-is; basic = light tidy; aggressive = also remove more leftover clutter from the original file. |
| PDF reader | Which engine reads PDF files. marker is fast; docling is slower but more accurate. Only matters for PDFs. |
| save each section separately | Besides the one combined file, also save each section of the document as its own file. |
| group sections in folders | When saving sections separately, organize them into numbered folders that mirror the document's structure. (Available only when "save each section separately" is on.) |
| rebuild heading structure | If a document came out with every heading the same size (common with textbook PDFs), restore the real chapter / sub-section nesting so the structure is correct. |
| how to rebuild headings | Only used if "rebuild heading structure" is on. Automatic rules = fast and free. The AI options do a better job (the "reads the whole doc" one is most accurate but costs money). Decide per document picks automatically. |
Vision is the only phase that spends anything — one LLM call per uncached image. The console guards it:
A conversion's detail page has three tabs:
The LLM summary bar (above the tabs) shows how many vision calls this conversion made and their cost, linking into the admin for per-call detail.
A converted output dir holds the deliverables (the master .md, sections/, images/) and all the working files — stage checkpoints, run record, caches. Deliver copies just the finished files to a parallel conversions/delivery/<dir>/ dir, ready to hand off or feed into a RAG index.
/admin/llm is a built-in dashboard for every LLM call across all conversions: runs, cost by model and by agent, per-job detail, cache hit rate, and budgets.
Set via environment variables (or .env):
| Variable | Default | Purpose |
|---|---|---|
| PAGESPEAK_CONVERSIONS_DIR | ./conversions | Root holding in/ + out/. |
| PAGESPEAK_WEB_HOST | 127.0.0.1 | Bind host. |
| PAGESPEAK_WEB_PORT | 8810 | Bind port. |
| PAGESPEAK_WEB_CONCURRENCY | 1 | Concurrent conversion jobs. |
Start in the background with bin/start, stop with bin/stop, restart with bin/restart. Restart after upgrading pagespeak — the server doesn't hot-reload code.
Full project docs: docs/web.md and docs/pipeline.md in the repo.