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 the default and the better choice for code, math and scanned pages. docling takes heading levels from the PDF's bookmarks and reads tables more cleanly. Left on default, a document converted before keeps the reader it used; choosing another reads the document again. 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. |
| PAGESPEAK_WEB_ALLOWED_HOSTS | (empty) | Extra host names accepted besides loopback and the bind host. |
| PAGESPEAK_WEB_MAX_UPLOAD_BYTES | 536870912 | Largest accepted upload (512 MiB). |
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.