CoolFace
Apppublic

joemartis/AccessibilityToolkit

sourceHugging Faceupdated 3mo agoView on Hugging Face
0likes
App README

PPTX / PDF Accessibility Tools

![CI](https://github.com/joemartis/thingz/actions/workflows/ci.yml)

Tools for remediating PowerPoint and PDF files (caps, language tags, math variables, reading order, footers, metadata, HTML export). Usable both as command-line scripts and through an internal web app.

The YAML block above configures a Hugging Face Space (Docker SDK, served on port 8000). See Deploy to Hugging Face Spaces below.

Web app

A FastAPI backend wraps each tool's existing core function (in tools/) and a single-page frontend lets you upload a file, pick a tool, set options, and download the result.

bash
# Docker (recommended — bakes in QPDF for pikepdf):
docker compose up --build      # then open http://localhost:8000

# Or run directly:
pip install -r requirements.txt
uvicorn backend.app.main:app --reload   # then open http://localhost:8000

API: GET /api/tools (list + option schemas), POST /api/run/{tool} (multipart upload + options → report and/or downloadable file), and GET /api/result/{id} (download a produced file). Tools with a "Preview only" option (PDF/PPTX language tags, footer removal) return a report without writing a file. Uploads are written to a temp working dir and cleaned up after download — originals are never modified.

Batch: upload multiple files in one run (the files field accepts many). A single file returns that file; multiple files are processed independently and returned as a zip, with a combined per-file report.

Upload limit: each file is capped (default 100 MB, set MAX_UPLOAD_MB to change). Oversized uploads are rejected mid-stream with HTTP 413, so they never fill the disk; the UI shows the limit and pre-checks before uploading.

Smoke tests

bash
scripts/smoke_test.sh http://localhost:8000   # HTTP checks against a running server
scripts/docker_smoke.sh                        # build image, run container, smoke test, tear down

Deploy to Hugging Face Spaces

This repo is a ready-to-run Docker Space. The README.md YAML header sets sdk: docker and app_port: 8000; the Dockerfile builds the FastAPI app (with QPDF baked in) and serves the same web UI.

  1. 1.Create a new Space: https://huggingface.co/new-space → SDK: Docker (blank template).
  2. 2.Push this repository to the Space's git remote:
bash
   git remote add space https://huggingface.co/spaces/<user>/<space-name>
   git push space <your-branch>:main

(Spaces build from the main branch.)

  1. 1.The Space builds the image and serves the app on port 8000 — open the Space URL and the tool UI loads.

Notes:

  • —No persistent storage is needed: uploads and results live in /tmp and are cleaned up after download (and swept after an hour).
  • —There's no auth — keep the Space private if the files aren't public. (A clean seam to add token/SSO auth later is described in the project notes.)
Automatic sync via GitHub Actions

.github/workflows/sync-to-hf.yml mirrors this repo to the Space on every push to main (and on manual dispatch), so the live app rebuilds automatically. Configure it once in the GitHub repo settings:

  • —Secret HF_TOKEN — a Hugging Face access token with write scope (Settings → Access Tokens on huggingface.co).
  • —Variable HF_USERNAME — the Space owner (user or org).
  • —Variable HF_SPACE — the Space name.

The workflow force-pushes the current ref to the Space's main, so the Space stays an exact mirror. (Create the Space first, as above.)

Command-line setup (once)

bash
python -m venv .venv
# Windows:        .venv\Scripts\activate
# macOS / Linux:  source .venv/bin/activate
pip install -r requirements.txt

Usage

One launcher drives everything. List the tools:

bash
python run.py

Run a tool — anything after the name passes straight through to that script:

bash
python run.py convert_caps deck.pptx --keep AI API
python run.py clear_pdf_metadata *.pdf
python run.py fix_pdf_lang_tags in.pdf out.pdf --to en-US

See a tool's own options:

bash
python run.py convert_caps -h

You can still run any script directly (e.g. python tools/pptx/convert_caps.py ...); the launcher is just a convenience so you don't have to remember paths.

Tools

PowerPoint (tools/pptx/)

NameWhat it does
convert_capsAll-caps / small-caps formatting → mixed case (batch + --keep acronyms; built-in list in `tools/pptx/acronyms.txt`)
replace_allcaps_pptxRewrites literal ALL-CAPS text to title/sentence case
fix_math_italicsInline OMML math variables → plain italic runs (fixes screen-reader "equation" tags)
fix_slide_number_orderMoves slide-number placeholder last in reading order
fix_pptx_lang_tagsSets every language attribute in the deck to a target language
remove_footer_textRemoves a specific string from slide/master/layout footers
report_alt_textReports each image's alt-text status (OK / weak / decorative / missing) — read-only
check_slide_titlesReports slides with missing or duplicated titles — read-only
check_hyperlinksReports non-descriptive link text ("click here", bare URLs, empty) — read-only
check_font_sizeReports text runs below a minimum point size — read-only
pptx_to_accessible_htmlExports to accessible HTML (headings, alt text, notes, tables, MathJax)

PDF (tools/pdf/)

NameWhat it does
clear_pdf_metadataStrips title/author/subject/creator/producer metadata
set_pdf_titleSets the document title and enables "Display document title" (PDF/UA)
fix_pdf_lang_tagsRewrites /Lang entries throughout the file to a target language

Notes

  • —convert_caps is the batch-capable version (the older single-file variant was dropped). replace_allcaps_pptx is a separate tool: it changes the actual text, not just caps formatting.
  • —Removed one duplicate copy of clear_pdf_metadata.py.
  • —Several tools default to overwriting in place or writing <name>_mixed_case.pptx — check each tool's -h before a batch run, and keep originals backed up.