Skip to content

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.

Attach a document, extract its text, and compare the answer with the original pages.

Upload a PDF and ask a question

  1. Open a chat and click Attach files (+) next to the message input, or drag and drop the PDF into the composer.
  2. Select your PDF file (up to 25 MiB by default).
  3. 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.
  4. Ask a question referencing the document:
Summarize the main findings in report.pdf and include the page numbers for each point.

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:

sudo apt-get install poppler-utils tesseract-ocr tesseract-ocr-eng tesseract-ocr-deu

Verify that both binaries and at least eng or deu are available:

pdftoppm -v
tesseract --list-langs

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:

{"status": "success", "filename": "report.pdf"}

You can list the files attached to a chat with GET /api/v1/chats/{chat_id}/files.