Formats and Parsing

A knowledge base reads what people keep documents in. Synapse's own readers handle every format below with no extra install; a few formats need one more thing, and PDFs read better with the optional knowledge extra.

What is read

A file that needs something the install lacks is Skipped with Not a file type Synapse reads yet, and read by itself as soon as that thing exists. On SynapseOrch Cloud, what can be uploaded into a base is narrower than what is read — see Uploads; the other formats arrive through web pages, records and agents' Vault tools.

How each is read

• PDF. The built-in reader keeps headings (by font size), ruled tables, and two-column pages in reading order, and leaves page headers and footers out of the index. It flags a page with no text layer. Tables drawn without lines are read as paragraphs. With the knowledge extra, PDFs go through Docling's layout model and TableFormer instead, which find those tables and the reading order of complex pages — at about two seconds a page.
• Word. Headings, lists and tables as written; footnotes after the body; tracked insertions in, deletions out.
• PowerPoint. Each slide is a page and its title a heading; speaker notes are indexed under the slide.
• Excel, OpenDocument sheets and CSV. Each sheet becomes a sheet card — its name, headers, row count and the first 20 rows — so a question about the data finds the right table. A sheet of up to 500 rows is also indexed 25 rows at a time under its headers. A larger sheet is indexed as its card alone, with a warning: a question about one row of it will not find that row.
• Email. The message, then each attachment read as its own format — up to 50 attachments, and messages attached to messages up to three deep. Attachments are never sent to OCR.
• Web pages. The page's main content, as Markdown.

Hidden text is removed

A document can hold text a person never sees, and an agent should not read it either — it is a common way to slip instructions to a model. Before anything is indexed, Synapse leaves out:

• white, sub-1-point and off-page text in PDFs, and white or sub-1-point text in Word files
• hidden runs in Word, hidden slides and shapes in PowerPoint, and hidden sheets in Excel
• HTML elements hidden by hidden, aria-hidden or a style that makes them invisible, and HTML comments
• zero-width, bidirectional and control characters

The report counts what was removed. Retrieved text also reaches the model marked as untrusted content — see Agents, chat and workflows.

Scanned pages and OCR

On a self-hosted install there is no OCR. A PDF page with no text layer is reported rather than skipped silently: the document is Partly indexed, with Some pages have no text layer and the page numbers, and its other pages are searchable. Images are Skipped.

On SynapseOrch Cloud pages with no text layer, and images, are read by Amazon Textract, within AWS. Only those pages are sent; pages with text are never sent. Reading is charged per page read, from your model wallet — see Costs and budgets. If the wallet runs out part-way, the document pauses; topped up, it reads only the pages it has not read.

The knowledge extra (self-hosted)

The extra installs Docling's PDF layout reader (with PyTorch, CPU only) and the HEIC image library. Install it the way Synapse is installed:

# A one-command, npm or pip install
synapse upgrade --with knowledge

# Or with pip by hand — PyTorch's CPU build is all Knowledge needs
pip install 'synapse-orch-ai[knowledge]' --extra-index-url https://download.pytorch.org/whl/cpu

# A source checkout
pip install -r backend/requirements-knowledge.txt --extra-index-url https://download.pytorch.org/whl/cpu

Knowledge runs no model on a GPU, so each way in takes PyTorch's CPU build; without that, Linux gets the CUDA build and several gigabytes of GPU libraries. synapse upgrade --with knowledge keeps the version you run, stays through every later upgrade, and fetches Docling's models (about 670 MB) once.

Docling's models are fetched once — nothing is downloaded while a document is read. After a pip install by hand, or to fetch them again after deleting their folder, run synapse setup --knowledge-models. A source checkout downloads them with Docling's own tool:

docling-tools models download layout tableformer -o "$DOCLING_ARTIFACTS_PATH"

DOCLING_ARTIFACTS_PATH defaults to models/docling under Synapse's state directory. Docling is used only when it imports and its models are there; otherwise the built-in reader runs. On Debian or Ubuntu its image library needs libxcb1 libgl1 libglib2.0-0. Expect about 3 GB on disk and up to 2 GB of memory per document being read.

LibreOffice is separate — a system package, not part of the extra. Install libreoffice-writer-nogui libreoffice-calc-nogui libreoffice-impress-nogui (or your platform's LibreOffice) and legacy .doc, .xls and .ppt files are converted and read; Synapse finds soffice on PATH, or at SYNAPSE_SOFFICE.

The Docker images include neither, so they read every format except images, HEIC photos and legacy Office files.

Limits on one file

Each file is read in a separate process with these limits, so a damaged or hostile file cannot take the server with it; archives inside Office files are checked against zip bombs first. The environment variables are listed in Environment variables. On SynapseOrch Cloud the limits are the same.