Inside ParsRAG

The release at a glance

Version

1.1.2, released October 24, 2026

License

Source-available, not open source

Runs on

Windows, macOS and Linux with Docker Compose; natively with Python 3.12 and Node.js 22

Backend

Python, FastAPI, LlamaIndex, Qdrant, sentence-transformers, PyMuPDF, Tesseract OCR

Frontend

React 19, TypeScript 7, Vite, KaTeX

Recommended model setup

The Ollama already installed on your computer, with its models and GPU; .env.example names qwen2.5:7b

Settings

27 options change in the app without a restart; each can be reset to its .env value

What you need

• Docker Desktop on Windows or macOS, or Docker Engine with Compose on Linux, and 8–16 GB of RAM.2
• Ollama installed on the computer, for the recommended setup. Without it, run Ollama inside Docker or use an API model.
• Disk space for the images and model weights.

The complete setup

The recommended setup uses the Ollama already installed on your computer, with the models you already have and its GPU.3 The app reaches it at host.docker.internal, so no Compose profile or override file is needed and the app container needs no GPU.4 On a Mac this is the way to generate on the GPU, because Docker can't pass a Mac's GPU to a container.

• Install Ollama and pull a model. On a GPU with about 6 GB of memory, a 3–4B model runs fully on the GPU.
• Copy .env.example to .env and set LLM_MODEL_NAME to the model you pulled. Its defaults already point the app at the Ollama on this computer: OLLAMA_DOCKER_BASE_URL=http://host.docker.internal:11434.
• Linux only: Ollama listens on 127.0.0.1 by default, where containers can't reach it. Make the Ollama service listen on the Docker bridge address, for example OLLAMA_HOST=172.17.0.1:11434. Windows and macOS need nothing.
• Start ParsRAG, open http://127.0.0.1:8000 (or the port in PARSRAG_PORT), upload documents and ask.

ollama pull qwen2.5:7b
Copy-Item .env.example .env
docker compose up -d --build
ollama ps

On macOS or Linux, copy the settings file with cp .env.example .env. While an answer is being written, ollama ps shows where the model runs; 100% GPU means it runs entirely on the GPU. The port is bound to 127.0.0.1 unless you change PARSRAG_BIND_HOST.

Ollama has no authentication. On Linux, prefer the bridge address: OLLAMA_HOST=0.0.0.0 opens Ollama to every network the computer is on, so if you use it, allow port 11434 only from Docker's networks.

Other ways to run

docker compose --profile local-model up -d qdrant ollama
docker compose --profile local-model run --rm ollama-init
docker compose --profile local-model up -d --build app

The first start

• The embedding model (intfloat/multilingual-e5-base) and the Hybrid reranker (about 100 MB) download into the model cache.
• With the computer's own Ollama, ParsRAG never pulls models. With Ollama in Docker, ollama-init pulls the configured model once into its own volume.
• Until everything is ready, /health/ready answers 503 with status preparing, and the interface shows that it is preparing the model and document store.
• If Ollama is off when the app starts, the app still becomes ready. Questions report that the model service is unreachable until Ollama starts, then work without a restart.
• After the first downloads, a local Ollama setup can run offline.5

Without Docker

Native development needs Python 3.12, Node.js 22, a running Qdrant, Ollama or an OpenAI-compatible endpoint, and Tesseract with Persian and English data for OCR. Copy .env.example to .env and remove the # from the lines under “Running without Docker” at its end: the Qdrant address, the Ollama URL, the settings file and OCR_ENABLED=1.

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-runtime.txt -c requirements.lock
Set-Location frontend
npm ci
npm run build
Set-Location ..
.\.venv\Scripts\python.exe -m uvicorn backend.main:app --host 127.0.0.1 --port 8000

In a native run, OCR stays off until OCR_ENABLED=1 is set; the Docker setup turns it on.

Day-to-day

docker compose ps
docker compose logs -f app
docker compose down

docker compose down keeps your data. docker compose down -v permanently removes vectors, settings saved in the app, caches and the weights of Ollama in Docker.

Settings: Model & connection

• Model runtime: OpenAI-compatible API or Local Ollama. A change applies to the next question without a restart.
• For Ollama, the address defaults to http://host.docker.internal:11434, and Find installed models offers the installed models in a menu with their sizes.7
• API key: held only in the service's memory, never in the browser or the configuration file. After a restart, enter it again or provide it as an environment variable.
• API privacy boundary: before an external API can be used, you confirm that your question and relevant passages will be sent to it.
• The connection is checked before the non-secret settings are saved. When Ollama fails, Settings says why (the address isn't allowed, or Ollama didn't answer), and when an API is active it offers the server's own Ollama URL.
• Advanced model settings hold the context sizes, thinking, retries and timeouts.

Safety rules for endpoints

• Public API endpoints must use HTTPS; HTTP is allowed only for loopback and private-network addresses.
• Link-local, multicast and reserved addresses are refused.
• Ollama URLs must be plain http://host:port on localhost, 127.0.0.1, ::1, ollama, host.docker.internal or a host listed in OLLAMA_ALLOWED_HOSTS, such as a GPU server on your LAN. Credentials, paths, query strings and HTTPS are rejected.8
• Private OpenAI-compatible services can run without a key.

Thinking models and API quirks

• ParsRAG asks Ollama not to think before answering (OLLAMA_THINK=0). Otherwise models such as qwen3, qwen3.5 or deepseek-r1 can spend the whole answer budget on reasoning and return an empty answer. Set OLLAMA_THINK=1 only with a larger OLLAMA_CONTEXT_LENGTH.9
• Reasoning that some APIs put inside answers (<thought> or <think> blocks) is removed from answers, streams, conversation titles and suggested questions.
• Temporary API failures (HTTP 5xx and 429) are retried with growing delays, up to MODEL_API_MAX_RETRIES times.10
• Google AI Studio works through its OpenAI-compatible endpoint, and the models/ prefix it requires is added automatically. A provider that is out of credit (HTTP 402) is reported as such.

Model in .env.example

qwen2.5:7b on the Ollama installed on the computer

Default API endpoint

https://openrouter.ai/api/v1

Answer timeout

120 seconds by default; a timed-out API request is retried once

API retries

4 by default, for HTTP 5xx and 429

Context window

8,192 tokens for Ollama, 32,768 for APIs, both configurable

Upload

• Drop files or choose them. Each file shows three steps: Transfer file, Extract and index, Ready to ask, followed by the number of passages indexed.
• Default capacity: 10 files per conversation, 100 MiB per file, 500 MiB per upload. The interface reads the real limits from the service, and you can change them in Settings → Documents & speed.11
• A batch is all or nothing: if one file fails, nothing from that request is left half-indexed.12

Supported files

Checks before reading

• File names must be plain names up to 255 characters, without paths.
• A PDF must really be a PDF, and a Word or PowerPoint file a real Office archive. Password-protected files are named as such.
• Office archives are limited to 10,000 entries, 200 MiB expanded and a compression ratio of 200 per entry.13
• A file with the same content as one already in the conversation is recognized and not added twice.14

When a file is only partly read

Managing documents

• Use in answers: tick or clear each document; you can clear every selection.
• From earlier conversations: add an indexed file without uploading it again. The copy becomes independent once it finishes.15
• Delete a document with a two-step confirmation; its passages and image previews are removed from the index.

Documents indexed by 1.0.0 keep working. Upload Word and PowerPoint files again to gain image and table citations, image previews next to sources, images past the 30th and better OCR of screenshots.16

PDF

• Each page becomes its own section, so citations can name the page.
• Persian pages are rebuilt in reading order from glyph positions: right-to-left lines, embedded Latin and digits, mirrored brackets and the ezafe mark on its letter.18
• A page goes to OCR when it has no text, when its text layer is garbled, or when it has under 40 characters and contains images.

OCR

• Tesseract with Persian and English data, on grayscale pages rendered at 200 dpi, without contrast stretching.
• A second, single-block pass runs when the first reading is weak (mean confidence below 75), and the more confident reading wins.
• Pages turned 90, 180 or 270 degrees, and pages skewed by 2 degrees or more, are detected and read again.19
• Pictures and screenshots also get a sparse-text pass on an enlarged black-and-white copy. It adds text the page layout pass skipped, such as status panels, dark toolbars and text on tinted panels.20
• Pictures in Word and PowerPoint are read several at a time (OCR_WORKERS: every CPU core, at most 8, by default), with the same text as reading them one by one.
• Limits: 30 scanned pages per PDF and 200 images per Word or PowerPoint file, 45 seconds per page and 40 million pixels per image by default. Images under 10,000 pixels, such as icons, are skipped.

Word, PowerPoint and other files

• Word: paragraphs are grouped under their headings, up to 180 words, and each passage carries its heading path.21 Commands and code in one-cell boxes stay with the sentence that introduces them.
• Word tables become Markdown tables with row records, cited by number and the paragraph they follow, for example “paragraph 120 · table 3”.22
• Images in Word and PowerPoint: the text read from each image is its own passage with the image's caption, cited as “paragraph 120 · image 7” or “slide 25 · image 9”. It also carries the text that introduces the image, and answers say when a fact comes from an image.23
• PowerPoint: one section per slide, including its tables.
• HTML and XML keep only visible text; JSON is validated and re-written readably.

Passages

• Text is split into passages of about 512 tokens with a 50-token overlap, and each document is embedded in batches sorted by length.
• For consecutive PDF pages, an extra passage joins the last 90 words of one page with the first 90 of the next, so a fact split by a page turn is cited as a page range.
• Persian spelling is normalized in passages and questions: Arabic Yeh and Kaf, presentation forms, diacritics and digits. The ezafe hamza is kept.24
• For every image read with OCR, a WebP copy at most 1280 px wide is kept so the source can show it.25

Two kinds of search

• Meaning: each passage has a 768-dimension vector from intfloat/multilingual-e5-base, stored in Qdrant with cosine distance.
• Keywords: a BM25 index (k1 1.2, b 0.75) over the same passages catches exact names, numbers and codes.
• The two rankings are merged with reciprocal rank fusion (k = 60).26
• Every search is filtered to the conversation, and to the mentioned file when you use @.

How many passages

• Depth adapts to the question, between 8 and 30 passages: more for summaries, comparisons, lists and tables, fewer for short factual questions.
• With several files, broad questions spread retrieval across them so one large document can't crowd out the rest. Specific questions search all files together, so the file that holds the answer can provide most passages; every other file still contributes its best match, and passages repeated across files are kept once.27
• You can fix the number yourself in Settings → Answers, from 1 to 50, or leave it empty so it is chosen per question.

Questions with several parts

• A question that asks several things, such as “which key opens Edit mode, and which fields did the example add?”, is also searched part by part. Each part keeps its best passages, and the model is asked to answer every part and say which one the documents don't cover.28
• When part of a table is retrieved, the rest of the table comes with it, so questions about the largest or smallest value see every row.29

Per mode

The evidence gate

Documents only refuses only when three things are true: the best passage scores below the threshold (0.75 by default, adjustable in Settings → Answers), the question isn't about the whole document, and the passages don't contain enough of the question's distinctive words. With @ mentions, every mentioned file must have its own evidence.30

The gate is an application safeguard, not a guarantee. Check important answers against their sources.

The composer

• Enter sends; Shift+Enter adds a line. Up to 30,000 characters.
• Type @ to mention an indexed document. The question is split into clauses, and each clause is searched in its file.31
• Without @, naming a file in the question narrows the search to it, but sharing an ordinary word with a file name no longer does.
• Type / at the start of a line for quick commands.
• While an answer streams, the send button becomes Stop; what was already written is kept.

Quick commands

Starting points

• An empty conversation with documents suggests three questions written from those documents.32
• Three starter cards: Find the essentials, Look a little closer, Unpack an idea.
• Hybrid is the default mode; you can change the default for new conversations in Settings.

While it works

The real processing stages appear in order: Understanding the question and conversation, Finding relevant evidence in documents, and Writing the final answer. Then the answer streams in word by word.33 Every prompt names the answer language, detected from your question, so English questions get English answers in Hybrid and Open conversation too.34

Citations and sources

• The model cites passages as [n]; the interface turns them into numbered chips that open the passage.36
• The Sources list shows each cited passage with a short preview, file name and location, such as “paragraph 812 · table 6” or “paragraph 845 · image 15”. Expanded, it shows up to 1,600 characters with the question's words highlighted.
• Table passages render as tables, and a passage read from a picture shows the picture itself next to the text.37
• Passages that were consulted but not cited fold under “more passages consulted”.

Where the answer came from

When there's no answer

Working with answers

• Copy, Try again, Copy prompt and Edit prompt. Retrying or editing adds a new version you can page through; editing a prompt starts a branch that keeps its own continuation.
• Math is rendered with KaTeX. Persian words are never typeset as math, unclosed delimiters are removed, and the math markup some Gemini models leak into answers is shown as math.
• External images in answers are not loaded.
• Errors are explained by their code, for example a password-protected PDF, a rejected API key, a model that isn't installed or an API account that is out of credit.

What is never stored by the service

• Uploaded files: they exist in memory and a RAM-backed temporary folder only while they are processed. What stays is the extracted text, its vectors and a small copy of each image read with OCR, all in Qdrant; SOURCE_IMAGE_PREVIEWS=0 stops keeping the images.
• Prompts and retrieved excerpts: they are not logged.
• Conversations: they live in your browser's IndexedDB, not on the server.
• API keys: process memory or environment variables only.6

Network protections

• Only requests addressed to localhost, 127.0.0.1 or ::1 are accepted, which blocks DNS rebinding. PARSRAG_ALLOWED_HOSTS adds names for LAN use.38
• Requests that change data must come from the app's own address or an allowed origin.
• Ollama URLs are limited to loopback, the ollama service, host.docker.internal and hosts listed in OLLAMA_ALLOWED_HOSTS. The browser can't widen this list.39
• Settings changed in the app can't touch what guards the trust boundary: ports, allowed hosts and origins, OLLAMA_ALLOWED_HOSTS, the request ceiling, memory limits and model downloads.40
• The app listens on 127.0.0.1 by default, and Qdrant sits on an internal network with no outside access.

Container hardening

• Read-only file system, a RAM-backed /tmp, no new privileges and every Linux capability dropped.
• Runs as a non-root user, and pip is removed from the runtime image.
• Memory ceilings: 6 GB for the app, 2 GB for Qdrant and 12 GB for Ollama in Docker by default.

Putting ParsRAG on a shared or untrusted network needs an authenticated reverse proxy. Ollama itself has no authentication, so keep the computer's Ollama off public networks. Vulnerabilities are reported privately through GitHub's security tab.

Conversations

• History is grouped into Today, Yesterday and Earlier, and search looks through titles and message text.
• Each conversation can be renamed, downloaded as Markdown or deleted.
• Back up every conversation and preference to a JSON file and restore it on another machine; documents are uploaded again there.41
• Clear all local data removes every conversation and indexed document, and keeps browser data if the service can't confirm the deletion.

Settings

• Four tabs: Appearance, Answers, Model & connection, and Documents & speed.
• Changes to the model, retrieval, uploads, OCR and indexing speed apply while ParsRAG runs, without a restart. Each setting shows its .env value and can be reset to it.

Appearance and language

• Light and dark themes, switched with a circular reveal from where you click.
• Four color palettes: ParsRAG green, Ocean blue, Quiet indigo and Warm sienna.
• Persian is the default language. Switching flips the whole layout between right-to-left and left-to-right, and each answer follows its own language.
• On narrow screens the conversation list becomes a panel you open.

Keyboard shortcuts

Guided tour and app install

• A 33-step tour opens on first visit, walks through every control in place, and never changes your settings or data. Replay it any time from Settings → Appearance → Workspace tour.
• Install ParsRAG as an app. The interface opens offline, but answers still need the service; model requests and document data are never cached.42
• If something fails while drawing the page, a recovery screen replaces the blank page and your data stays saved.

Compose defines three containers: the app, Qdrant and Ollama, which runs only with the local-model profile. Instead of the Ollama container, the app can use the Ollama installed on the host, reached at host.docker.internal; the host's models and GPU are then used directly. Failures are reported as ollama_url_not_allowed or ollama_unreachable.

HTTP API

A streamed answer

POST /query/stream sends server-sent events in order: stage (understanding, retrieving, generating), sources, token for each piece of text, then done with the full answer, its outcome and the cited passage numbers. Errors arrive as an error event with a stable code.

Every error response has a stable code next to its message, so the interface can explain it in your language.

On every change

• Backend: formatting and lint with Ruff, strict type checking with mypy, and pytest with branch coverage of at least 85 percent.43
• Frontend: dependency audit, unit tests, type-checked build, and Playwright browser and app-install tests.
• Both run on Linux, Windows and macOS.44
• End to end: real parsing, embeddings, Qdrant, reranking and streaming, with a stand-in model. At least 7 of 8 paraphrased Persian questions must cite their own section first.45
• Locally, every backend test runs without skips and without Docker: PARSRAG_E2E=1 runs the end-to-end tests against an in-memory Qdrant unless QDRANT_HOST names a server.46
• Packaging: the Docker image is built and the app imported inside it.

Supply chain

• Dependency review on pull requests and a Python vulnerability audit.
• A software bill of materials is generated, and the image is scanned; fixable high or critical findings block the build.
• Dependabot proposes weekly dependency updates.

Measured improvements in 1.0

• Keyword plus vector search: mean reciprocal rank 0.748 → 0.823 on 127 keyword-style queries.47
• OCR on Persian pages turned 90 degrees: character error 0.85 → 0.09.48
• OCR overall: mean character error 0.225 → 0.133.49

Measured improvements in 1.1

• Questions with several parts: 5 of the 6 answers that missed a part became complete, with no regressions.50
• Pictures read several at a time: a report with 96 images parsed in 33 s instead of 121 s, with identical text.51 Indexing the whole report went from about 4.5 minutes to about 3.52
• Screenshot OCR: facts read from 33 to 37 of 40, for about a third more time per image.20
• Thinking models: on a 6 GB GPU with qwen3.5:4b, an empty reply after 59 s became a cited answer in 7 s.53

These measurements were made on document sets that aren't published, so they can't be reproduced from the public repository.

In the app

• Settings changes 27 options in four groups: model (context sizes, thinking, retries, timeouts), retrieval (threshold, depths, keyword search), documents (upload limits, OCR, image previews) and indexing speed (OCR workers, CPU threads, batches).54
• Each option shows its .env value and can be reset to it, one at a time or with Reset all to .env. Values saved in the app take precedence over .env and survive restarts; they live in the app_config volume.55
• Ports, allowed addresses, Qdrant, memory limits, the largest upload request and the embedding model stay in .env and apply after a restart.56
• .env.example has only the model choice active. Every other line shows its default, grouped by whether Settings can also change it.

Model

Search

Documents and OCR

Indexing speed

Service and memory

You may

• Download and copy an unmodified official release.
• Install and run it for personal, academic, research, educational or internal organizational use.
• Read and study the source code.
• Prepare a change only to contribute it back to the official repository.

You may not, without written permission

• Modify it or make derivative works, other than to prepare a contribution.
• Publish, redistribute, sell or rent it, or offer it to others as a hosted or managed service.
• Rebrand it or use the ParsRAG name and mark except to identify an official copy.

Cite it

Publications that use ParsRAG must cite it. The citation in APA and BibTeX is generated from the repository's CITATION.cff.

How to cite ParsRAGLicenseContributingSecurity policy