Spaces:
Sleeping
Sleeping
| # hb-pdf engine | |
| An authenticated FastAPI/PyMuPDF service deployed as a Hugging Face Docker Space. | |
| Source PDF bodies and chapter results remain in memory. Annotation JSON may be cached | |
| by hash. A completed Professor's Pass book is encrypted with its access key and kept | |
| on engine disk for at most 24 hours as delivery insurance. | |
| ## Local container | |
| Build from the repository root so the unchanged Track A `app/` package is included: | |
| ```powershell | |
| docker build -f engine/Dockerfile -t hb-pdf-engine . | |
| docker run --rm -p 8080:8080 ` | |
| -e OPENAI_API_KEY=replace-later ` | |
| -e HB_MODEL=replace-later ` | |
| -e HB_SHARED_SECRET=local-secret ` | |
| hb-pdf-engine | |
| ``` | |
| Health check: | |
| ```powershell | |
| curl.exe http://localhost:8080/healthz | |
| ``` | |
| Plain PDF response: | |
| ```powershell | |
| curl.exe -X POST http://localhost:8080/annotate ` | |
| -H "X-HB-Auth: local-secret" ` | |
| -H "Content-Type: application/pdf" ` | |
| --data-binary "@samples/Ch1 - Introductions.pdf" ` | |
| --output outputs/annotated-service.pdf | |
| ``` | |
| Add `?stream=1` for SSE progress. The final `done` event contains the result in | |
| `pdf_base64` plus content-free processing metadata. Page progress identifies | |
| `success`, `valid_empty`, `skipped`, `failed`, and `timed_out` results. Plain PDF | |
| responses expose the compact form of the same data in `X-HB-Metadata`. | |
| Operational failures are never cached. A document may finish with a small number | |
| of failed pages (reported in metadata), but fails clearly instead of returning a | |
| misleading partial result when more than 20% of readable pages fail. Inference is | |
| deadline-aware; set `HB_DOCUMENT_DEADLINE_SECONDS` to override the 55-second | |
| default. | |
| ## Whole-book route | |
| `POST /annotate-book` accepts up to 1,000 pages / 150 MB and requires | |
| `X-HB-Access-Key` plus a short-lived `X-HB-Book-Token` minted by the site. It emits an | |
| SSE plan and chapter start/done events, processes chapter-aware chunks sequentially, | |
| and returns a `result_id`. Download with `GET /book-result/{result_id}` and the same | |
| access-key header. Set: | |
| - `HB_BOOK_CALLBACK_URL=https://hb-pdf.higgsfield.app/api/book/complete` | |
| - `HB_BOOK_STORAGE_SECRET` to a separate random 32-byte value (recommended; the | |
| shared secret is used as a fallback) | |
| - `HB_BOOK_RESULT_DIR` only when overriding the default `/tmp/hb-book-results` | |
| ## Cloudflare setup | |
| From `engine/`, install the Worker dependencies, create `HB_CACHE`, and replace the | |
| zero placeholder ID in `wrangler.jsonc` with the returned namespace ID: | |
| ```powershell | |
| npm install | |
| npx.cmd wrangler kv namespace create HB_CACHE | |
| ``` | |
| Provide runtime values only when you are ready to deploy: | |
| ```powershell | |
| npx.cmd wrangler secret put OPENAI_API_KEY | |
| npx.cmd wrangler secret put HB_MODEL | |
| npx.cmd wrangler secret put HB_SHARED_SECRET | |
| npm run deploy | |
| ``` | |
| Set `HB_MODEL` to `gpt-5.4-mini`. It is a model name, not a key. Use a long random | |
| value for `HB_SHARED_SECRET`; the site server must receive the exact same value. | |