Chat with PDF Documents¶
Upload PDFs and other files to give the current conversation access to their contents. Numi extracts selectable PDF text directly and automatically runs local OCR on scanned pages when Poppler and Tesseract are installed on the server.
Upload a PDF and ask a question¶
- Open a chat and click Attach files (
+) next to the message input, or drag and drop the PDF into the composer. - Select your PDF file (up to 25 MiB by default).
- A progress bar appears on the attachment chip while the file uploads and its pages are extracted. Once the progress bar clears, the document is ready.
- Ask a question referencing the document:
When working with scanned tables or dense figures, verify critical numbers against the original PDF, as OCR recovers text but does not always preserve complex multi-column table layouts.
Reuse files from your Library (@ mention or + menu)¶
Every file you upload and every file Numi generates in your normal chats is available in your Library:
- From the
+menu or sidebar: Click + beside the composer and choose Add from library, or open Library in the sidebar and click the paperclip (Attach) on any file. - With
@while typing: Type@followed by part of a filename or chat title (for example,@relaunch deck). A filtered popup appears above the composer with image thumbnails; use the arrow keys and Enter/Tab (or click) to attach the file.
Reusing a library file copies it on the server without re-uploading from your browser, and already-indexed PDFs reuse their extracted page text without running OCR again. Files from temporary chats are excluded from the library.
How PDF context fits into the prompt¶
By default, up to PROMPT_MAX_PDF_CONTEXT_CHARS (12,000 characters) of
extracted PDF text is injected into the prompt in upload order and page order.
In addition, the model can inspect specific pages or files on demand using the
view tool.
The text is attached once, to the first message you send after the upload, and stored with that message. Later turns replay it unchanged, so the provider's prompt cache keeps covering the conversation. When older turns are trimmed or compacted during a turn, their stored upload context moves to a retained message in the model request. It is attached again when the PDF text changes or no announcement remains in the loaded history. Chats from before this behaviour attach it once more on their next message.
If you remove a pending attachment chip before sending, note that any PDF already uploaded to the chat remains stored in that chat's workspace; start a new chat if you want a clean slate without earlier documents.
Operator: enable OCR for scanned PDFs¶
The official Docker image includes Poppler, Tesseract, and English/German OCR language packs out of the box. On a native Debian or Ubuntu host, install them with:
Verify that both binaries and at least eng or deu are available:
When a PDF page contains images and fewer than 100 selectable characters, the
extractor renders that page (capped at 2,400 pixels on its longest side) and
runs local Tesseract OCR, keeping the OCR text whenever it recovers more
content. PDFs fetched via fetch_web_page use the same pipeline. No external
OCR cloud service is ever contacted.
Operator: tune PDF and upload limits¶
Configure these settings in .env and restart the server:
| Variable | Default | Description |
|---|---|---|
UPLOAD_MAX_UPLOAD_BYTES |
26214400 |
Maximum size per uploaded file in bytes (25 MiB) |
UPLOAD_MAX_PDF_WORKERS |
2 |
Maximum concurrent PDF extraction worker processes |
UPLOAD_MAX_PDF_PAGES |
500 |
Maximum pages processed per PDF |
UPLOAD_MAX_PDF_TEXT_CHARS |
2000000 |
Maximum total characters extracted per PDF |
UPLOAD_PDF_TIMEOUT_SECONDS |
45 |
Timeout in seconds for extracting and OCR-scanning a single PDF |
UPLOAD_PDF_MEMORY_MEGABYTES |
768 |
Memory cap (MiB) for each isolated PDF extraction worker process |
PROMPT_MAX_PDF_CONTEXT_CHARS |
12000 |
Shared character budget for automatic PDF excerpts per prompt |
Each PDF extraction job runs in an isolated worker process so a timeout or memory spike cleanly terminates the worker and its OCR subprocesses without affecting the web server.
API upload¶
To upload a file programmatically, call the authenticated upload endpoint:
curl -X POST "http://localhost:4567/api/v1/upload?chat_id=YOUR_CHAT_UUID" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file=@report.pdf"
Response:
You can list the files attached to a chat with GET
/api/v1/chats/{chat_id}/files.