📖 برای مطالعهٔ نسخهٔ فارسی اینجا کلیک کنید
A quieter place for your books. A clearer path to their answers.
Chat with your own PDF books in English and Persian.
Search their pages, follow the citations, and keep control of your library.
Getting Started · Features · AI Models · Privacy · راهنمای فارسی
Bookly is a local, self-hosted Retrieval-Augmented Generation (RAG) assistant for your own PDF books.
It extracts text, applies OCR when needed, builds a hybrid search index, and retrieves relevant passages to help an AI model answer your questions with page-level source references.
Your library and retrieval pipeline stay local.
Choose a local model for on-device inference, or connect a cloud model through an OpenAI-compatible API.
Built to answer from your books—not to replace them.
Bookly is designed to ground answers in retrieved passages and acknowledge missing information. As with any AI assistant, verify important claims against the cited pages.
| The friction | The Bookly approach |
|---|---|
| You remember an idea, but not its location | Search by meaning and keywords |
| A scanned book has no selectable text | OCR fallback with a scanned-page quality gate |
| Persian text contains inconsistent characters | Arabic-letter and ZWNJ normalization with Persian-aware tokenization |
| An answer is difficult to verify | Numbered sources with page references |
| You want to choose your model | A built-in panel for local and cloud endpoints |
| Your library changes over time | Incremental sync processes new, changed, and removed books |
|
Local PDF storage, text extraction, optional OCR, and incremental indexing. |
Dense embeddings, BM25, and optional sparse retrieval—combined through configurable fusion. |
Streaming chat with numbered citations and links back to source pages. |
| Feature | Details |
|---|---|
| Bilingual web interface | English / فارسی, dark and light themes, chat history, and streaming answers |
| Hybrid retrieval | Dense embeddings ⨁ BM25 ⨁ optional sparse retrieval |
| Configurable fusion | Convex Combination (cc) or weighted Reciprocal Rank Fusion (rrf) |
| Page-level citations | Numbered references such as [1] with source-book and page information |
| Built-in model panel | Add and activate OpenAI-compatible models without editing application code |
| Local or cloud inference | Ollama, LM Studio, vLLM, OpenAI, OpenRouter, and compatible endpoints |
| Persian-aware processing | ZWNJ handling, Arabic-letter normalization, and a Persian BM25 tokenizer |
| Scanned-PDF support | Tesseract OCR fallback with a quality gate |
| Incremental indexing | Detect added, renamed, edited, and removed books |
| Resumable M3 indexing | Built-in checkpointing for the m3 embedding backend |
| Optional reranking | Cross-encoder reranker; disabled by default, GPU recommended |
| Ready-made demo | A small sample book and keyword index for trying the UI before indexing |
| Terminal interface | One-shot questions and an interactive REPL using the same engine |
flowchart TD
A["📚 Your PDF Library"] --> B["Text Extraction"]
B --> C{"OCR Needed?"}
C -->|Yes| D["Tesseract OCR + Quality Gate"]
C -->|No| E["Normalization + Chunking"]
D --> E
E --> F["Dense Embeddings"]
E --> G["BM25 Index"]
E --> H["Optional Sparse Retrieval"]
Q["💬 Your Question"] --> R["Hybrid Retrieval"]
F --> R
G --> R
H --> R
R --> S["CC / Weighted RRF Fusion"]
S --> T{"Reranking Enabled?"}
T -->|Yes| U["Cross-Encoder Reranking"]
T -->|No| V["Retrieved Book Passages"]
U --> V
V --> W["Local or Cloud AI Model"]
W --> X["Answer + Page Citations"]
X --> Y["Web Chat / Terminal"]
classDef source fill:#251A13,stroke:#D4A373,color:#F3E5D0;
classDef process fill:#3A281D,stroke:#A47148,color:#F3E5D0;
classDef output fill:#6F442D,stroke:#D4A373,color:#FFF8EE;
class A,Q source;
class B,C,D,E,F,G,H,R,S,T,U,V,W process;
class X,Y output;
Approximate first-index times for a single ~300-page PDF on a typical laptop CPU, without a GPU:
| Mode | Mostly text PDF | Scanned PDF requiring OCR |
|---|---|---|
backend = "st" — default |
~5–15 minutes | ~15–45 minutes |
backend = "m3" — higher-quality option |
~1–3 hours | ~3–6 hours |
| Re-sync an unchanged library | Usually seconds | Usually seconds |
Actual time depends on your CPU, book length, scan quality, model availability, and configuration. Changed books still require processing.
- Text extraction: approximately 1 ms/page for plain-text PDFs.
- OCR: approximately 1–3 seconds/page; often the main bottleneck for scanned books.
- Keyword-only start:
--no-embedcan produce a text-only index in under a minute for suitable inputs. - M3 checkpointing: interrupted indexing can resume on the next
sync. - Start small: index one book first, then expand your library.
- Python 3.11+ — the project uses standard-library
tomllib. - Your PDF books — text-based or scanned, Persian or English.
- Tesseract OCR — only needed for scanned PDFs.
- An AI endpoint — local or cloud, when you want generated chat answers.
For OCR:
- Windows users can install Tesseract using the UB Mannheim builds.
- Configure the executable path in
booksearch.tomlif necessary. - Download
fas.traineddataandeng.traineddatafrom tessdata_best and place them inapp/tessdata/.
git clone https://github.com/Amin-Moniry/bookly.git
cd bookly
python -m venv .venvWindows — PowerShell
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txtLinux / macOS
source .venv/bin/activate
python -m pip install -r requirements.txtThe commands below assume the virtual environment is active.
Place your PDFs in library/:
library/
├── poetry-collection.pdf
├── ai-handbook.pdf
└── my-notes/
└── another-book.pdf
Use any filenames or subfolders, in Persian or English. Bookly detects library changes during sync.
python app/ingest.py syncThe pipeline processes your books through:
extract → OCR if needed → chunk → embed → merge
Want to try search sooner?
python app/ingest.py sync --no-embedThis builds a keyword-search-capable index without embeddings. Add the semantic layer later:
python app/ingest.py sync --force embedpython app/server.pyOpen http://127.0.0.1:8765.
No indexed books yet?
Bookly includes
demo/sample-book.pdfand a ready-made keyword index inindex/sample/. The app uses this demo until your first real library sync, then switches to your own books.
Use the ✨ AI models button in the header, add an endpoint, and click the model to activate it.
Try a question:
خلاصهٔ فصل سوم چیه؟
Or:
What does this book say about the main causes of this problem?
Bookly is designed to retrieve relevant passages, cite their pages, and indicate when the requested information is not found.
Run this whenever you add, edit, rename, or remove books:
python app/ingest.py syncUnchanged books are skipped.
Open http://127.0.0.1:8765 → ✨ AI models.
| Field | Local examples | Cloud examples |
|---|---|---|
| Base URL | Ollama: http://127.0.0.1:11434/v1LM Studio: http://127.0.0.1:1234/v1 |
OpenAI: https://api.openai.com/v1Or another OpenAI-compatible endpoint |
| API key | Usually empty for a default local setup; endpoint-dependent | Your provider's API key |
| Model ID | mistral / qwen2.5:7b |
For example, gpt-4o-mini, if available from your provider |
Click a model to activate it. The header chip shows the active model.
Bookly can also connect to vLLM, OpenRouter, and other OpenAI-compatible servers.
Model IDs must match models installed locally or offered by your provider. Start your local model server before testing its connection.
Ask one question:
python app/booker.py "یک سؤال دربارهٔ کتابهات"Start an interactive session:
python app/booker.pyTerminal-chat defaults are configured in the [llm] section of booksearch.toml.
The main configuration lives in booksearch.toml, with Persian and English comments.
| Section | Controls |
|---|---|
[paths] |
Library and index locations |
[extract] |
OCR engine, DPI, parallel workers, and scanned-page quality gate |
[chunk] |
Chunk size, sentence overlap, and section headers |
[embed] |
st fast default or m3 higher-quality embedding backend |
[search] |
Fusion mode (cc / rrf), retrieval depth, thresholds, and neighboring chunks |
[rerank] |
Optional cross-encoder reranking; disabled by default |
[llm] |
Terminal-chat model defaults |
Do not put real API keys in tracked configuration files.
Models added through the web panel are stored locally in
app/llm_models.json, which is git-ignored.
Bookly supports Persian and English across its library-search workflow:
- Bilingual interface with English and Persian options.
- Persian text normalization, including Arabic-letter variants and ZWNJ handling.
- Persian-aware BM25 tokenization for keyword retrieval.
- OCR support with
fasandengTesseract language data. - Persian and English filenames, including nested library folders.
OCR quality depends on scan quality and the installed language data. Review extracted text when a scanned book produces poor search results.
- Your PDFs in
library/. - Text extraction, OCR, chunking, and the search index.
- Model-panel credentials in
app/llm_models.json. - Chat history in your browser's
localStorage.
Requests sent to a cloud endpoint can include your question and retrieved book passages needed to answer it. Their handling is subject to that provider's policies.
For on-device inference, use a model server running on your own machine.
| Path | Contents |
|---|---|
library/ |
Your PDF books |
index/ |
Generated library indexes; the tracked demo index is an intentional exception |
app/llm_models.json |
Model-panel configuration and API keys |
eval/questions.jsonl |
Private evaluation questions |
eval/results.jsonl |
Private evaluation results |
| OCR language-data directories | Downloaded Tesseract language files |
Only an anonymized evaluation-format sample is intended to be tracked: eval/questions.sample.jsonl.
Before publishing
Inspect
git statusand staged changes. Git-ignore rules do not remove files already tracked by Git. Confirm that no books, private questions, credentials, or personal indexes are included.
Run the test suite:
python -m pytest tests -qThe documented suite contains 44 tests, covering:
| Area | Coverage |
|---|---|
| Text processing | Normalization and tokenization |
| Retrieval | RRF fusion |
| Index stability | Stable chunk IDs |
| Incremental sync | Add, rename, edit, and delete behavior |
| Evaluation | Evaluation-harness behavior |
| CLI | Command-line behavior |
For the Persian guide, design decisions, benchmark history, and engineering notes, see docs/dev-notes.md.
| Symptom | What to check |
|---|---|
| “No answer found in the books” for every question | Confirm library/ contains PDFs, then run python app/ingest.py sync |
| Garbage text from scanned pages | Install Tesseract, add fas / eng traineddata to app/tessdata/, and check OCR configuration |
| “Server unreachable” in chat | Start the backend with python app/server.py |
| Embeddings are slow on CPU | Keep backend = "st"; reserve m3 for quality-critical use |
| Model connection test fails | Use the API base URL—not a URL ending in /chat/completions; verify the model ID, server, and key |
| Need a clean rebuild | Back up anything you need, remove the generated library index, then run sync again |
The default OCR engine is tesseract. PDFs with usable selectable text skip OCR.
Run the sync command again. The m3 backend supports checkpointing so interrupted work can resume.
bookly/
├── booksearch.toml # Main configuration
├── requirements.txt # Python dependencies
│
├── app/ # Server, retrieval, ingestion, CLI, evaluation
│ ├── server.py # Web application entry point
│ ├── ingest.py # Incremental library indexing
│ ├── booker.py # Terminal chat
│ ├── web/
│ │ └── index.html # Single-file frontend; no build step
│ ├── tessdata/ # Downloaded OCR language files
│ └── llm_models.json # Local model settings + keys; git-ignored
│
├── static/ # README screenshots
│ ├── main.png
│ └── Ai-Part.png
│
├── demo/
│ ├── sample-book.pdf # Small demo book
│ └── make_sample_book.py # Demo-book generator
│
├── library/ # Your PDFs; git-ignored
├── index/ # Generated library indexes
│ └── sample/ # Ready-made demo keyword index
│
├── eval/ # Evaluation data; private files git-ignored
│ └── questions.sample.jsonl
├── tests/ # Pytest suite
├── docs/
│ └── dev-notes.md # Persian guide + engineering notes
│
└── LICENSE # MIT license
| Question | Answer |
|---|---|
| Can I use Bookly without a GPU? | Yes. The default st embedding backend is the faster CPU-oriented starting point. Local chat-model requirements depend on the model you choose. |
| Do I need a cloud API? | No. You can use a local OpenAI-compatible model server. |
| Can I start without embeddings? | Yes. Use sync --no-embed for a keyword-search-capable index. |
| Does it support scanned Persian books? | Yes, through Tesseract OCR with Persian language data; results depend on scan quality. |
| Do I need to rebuild everything after adding a book? | No. Incremental sync skips unchanged books. |
| Is the interface usable before indexing my books? | Yes. A bundled demo book and keyword index provide a starting point. |
| Are AI answers guaranteed to be correct? | No. Bookly is designed for source-grounded answers, but you should verify important claims against the cited pages. |
| Where is chat history stored? | In your browser's localStorage. |
| Is a frontend build step required? | No. The frontend lives in app/web/index.html. |
| Is Persian documentation available? | Yes. Read the Persian guide. |

