DHIVA LABS · LEARN

Appearance

Add documents ​

LocalRAG answers only from documents you have added. You can add them in the browser, in bulk from the command line, or with the API.

Supported files ​

TypeExtensionNotes
PDF.pdfUses the text layer inside the PDF. Each PDF page is tracked, so citations name the page.
Plain text.txtRead as UTF-8. Counted as one page.
Markdown.mdRead as UTF-8 text. Counted as one page.

Scanned PDFs and PDFs made only of images have no text layer, and LocalRAG has no OCR (text recognition) step. They are rejected with no extractable text. Word documents are not supported.

Add files in the browser ​

  1. Open http://localhost:8090.

  2. Drag one or more files onto Drop files or click to browse, or click it and choose the files.

  3. Wait for them to appear under Documents, with their number of pages and chunks.

An upload is all or nothing. If one of the files is unsupported or has no text, nothing in that upload is added, and a message under the upload area names the file. Remove that file and upload the others again.

Add a folder from the command line ​

With a pip install, the localrag ingest command adds one file or a whole folder, including its subfolders. It picks up every .pdf, .txt and .md file.

bash
localrag ingest ~/Documents/manuals

It prints one line per file and a summary:

text
pump-guide.pdf -> 3f9a1c2b7d10 (14 pages, 38 chunks)
notes.md -> 8b02e4f1a9c3 (1 pages, 2 chunks)
old-scan.pdf: skipped (no extractable text in old-scan.pdf)
ingested 2/3 files

Unlike the browser, the command skips bad files and carries on. It exits with status 1 if nothing was added.

Good to know

The command writes to the same data folder as the server only if it runs with the same settings. Run it from the folder where you start localrag serve, or set the same LOCALRAG_DATA_DIR.

Add files with the API ​

bash
curl -F "files=@pump-guide.pdf" -F "files=@notes.md" http://localhost:8090/api/ingest

This works for Docker installs too. See Use the API.

Duplicates ​

LocalRAG recognises a file by a fingerprint of its contents (a SHA-256 hash), not by its name. Adding the same file again does nothing and reports it as a duplicate. A file with the same name but changed contents is a new document; delete the old version yourself if you no longer want it.

Pages and chunks ​

LocalRAG cuts each page into chunks of up to 500 tokens (a token is a word or part of a word), with about 50 tokens of overlap between neighbouring chunks so a sentence at the edge is not lost. A chunk never spans two pages, which is what lets citations name an exact page. You can change both numbers; see Configuration.

Delete a document ​

In the browser, select the × next to the document, then select sure? to confirm. With the API, send DELETE /api/docs/{doc_id}.

Deleting removes the document and all its chunks from LocalRAG. Your original file on disk is not touched.

Tips for better answers ​

  • Prefer PDFs that were made from a word processor over scans.
  • Split very large collections by topic and run separate LocalRAG data folders, so unrelated documents do not compete in search.
  • Give files clear names. The name appears in every citation.

Next steps ​