DEV Community: Kavindu Kavishka Premarathna

Building a Custom AI PDF Reader in Python: From a Jupyter Prototype to Tested Modules

Kavindu Kavishka Premarathna — Fri, 14 Aug 2026 16:11:33 +0000

Research papers are much easier to read when the reader fits the way you work. I wanted a PDF reader that could eventually support bookmarks, notes, annotations, summaries, question answering, text-to-speech, and voice commands.

Rather than trying to write a complete PDF engine from scratch, I started with a small Python prototype. The goal was simple: learn each layer of the application properly, build a working foundation, and only then move toward a desktop application.

This article documents the first stage of that journey: an interactive PDF reader in Jupyter, local persistence for bookmarks and notes, a cleaner module structure, automated tests, and the lessons learned along the way.

The project goal

The long-term goal is a customizable desktop PDF reader for research reading. The eventual application may include:

PDF navigation and zoom
Text search with highlighted matches
Bookmarks and reading progress
Page-linked notes and annotations
Local or cloud LLM summaries and question answering
Text-to-speech
Voice commands

For the first milestone, I deliberately kept the scope smaller. I focused on PDF rendering, navigation, search, persistence, and tests.

Choosing the first technology stack

I chose Python because it allowed me to experiment quickly. My first stack was:

Need	Tool
PDF rendering, text extraction, and search	PyMuPDF
Interactive prototype interface	JupyterLab and ipywidgets
Image handling	Pillow
Local saved data	JSON
Version control	Git and GitHub
Automated tests	pytest

The future desktop UI will use PySide6, but Jupyter was a useful place to learn the reader logic before dealing with desktop-window layouts, signals, menus, and packaging.

Building the first reader

The prototype opens a local PDF with PyMuPDF:

from pathlib import Path
import pymupdf

PDF_PATH = Path("test.pdf")
document = pymupdf.open(PDF_PATH)

print(document.page_count)

A PDF page is not automatically an image. PyMuPDF renders a page into a pixmap, and Pillow converts the pixel data into an image that Jupyter can display.

from PIL import Image

page = document[0]
pixmap = page.get_pixmap(dpi=120)

image = Image.frombytes(
    "RGB",
    (pixmap.width, pixmap.height),
    pixmap.samples
)

image

This gave me the basic page view. From there, I added buttons for Previous, Next, Go to page, Zoom In, and Zoom Out.

A key lesson: application state

One important concept I learned was application state. Instead of letting each button manage unrelated variables, I kept the reader's current information together:

reader_state = {
    "current_page": 0,
    "zoom_dpi": 120,
    "search_results": [],
    "search_index": 0,
    "bookmarks": [],
    "notes": []
}

The UI follows a simple pattern:

A button changes reader_state.
The application saves important changes if necessary.
A refresh function renders the current state.

For example, page navigation uses one shared function:

def change_page(new_page):
    if not 0 <= new_page < document.page_count:
        return

    reader_state["current_page"] = new_page
    save_current_reader_data()
    refresh_reader()

Using a single function for navigation prevents different controls from handling page changes in slightly different ways.

Searching and highlighting PDF text

PyMuPDF can find the rectangles where a text query appears on a page.

rectangles = page.search_for("research")

The returned rectangles use PDF coordinates, measured in points. The rendered page image uses pixels. Since PDF points are based on 72 points per inch, I learned to scale each search rectangle with this formula:

scale = dpi / 72
pixel_x = pdf_x * scale

That conversion lets the reader draw highlights in the correct position on the rendered image.

from PIL import ImageDraw

draw = ImageDraw.Draw(image, "RGBA")

for rect in rectangles:
    draw.rectangle(
        [
            rect.x0 * scale,
            rect.y0 * scale,
            rect.x1 * scale,
            rect.y1 * scale
        ],
        fill=(255, 235, 0, 90),
        outline=(255, 0, 0, 255),
        width=3
    )

This was one of the most useful lessons in the project: PDF document coordinates and screen-image coordinates are not the same thing.

Adding persistent bookmarks and notes

Bookmarks and notes should survive a restart. I did not want to modify the original PDF for this first version, so I stored personal reader data in a JSON file.

A document entry looks like this:

{
  "documents": {
    "/absolute/path/to/test.pdf": {
      "file_name": "test.pdf",
      "bookmarks": [
        {
          "page_number": 2,
          "label": "Important result"
        }
      ],
      "notes": [
        {
          "page_number": 5,
          "text": "Review this figure before the presentation.",
          "created_at": "2026-08-11 15:30"
        }
      ],
      "last_page": 5
    }
  }
}

A bookmark points to a page and has a label. A note points to a page, has text, and stores when it was created. The current page is also saved whenever the user navigates.

I used a temporary file before replacing the main JSON file:

def save_all_reader_data(data):
    temporary_path = DATA_PATH.with_suffix(".tmp")

    with temporary_path.open("w", encoding="utf-8") as file:
        json.dump(data, file, indent=2, ensure_ascii=False)

    os.replace(temporary_path, DATA_PATH)

This is safer than directly overwriting the main file because it reduces the risk of leaving a partially written JSON file if a save is interrupted.

Refactoring the notebook into modules

The first notebook worked, but it was becoming one large cell. That is acceptable for exploration, but difficult to maintain.

I moved reusable code into separate modules:

custom-ai-pdf-reader/
├── data/
│   └── reader_data.json
├── notebooks/
│   └── Untitled.ipynb
├── src/
│   ├── __init__.py
│   ├── pdf_service.py
│   ├── reader_state.py
│   └── storage_service.py
├── tests/
│   └── test_storage.py
├── .gitignore
├── pytest.ini
└── requirements.txt

`pdf_service.py`

This module is responsible for PDF-specific tasks:

def open_pdf(pdf_path):
    ...

def get_page_count(document):
    ...

def render_page(document, page_number, dpi, highlight_rectangles=None):
    ...

def search_document(document, query):
    ...

`storage_service.py`

This module handles JSON persistence:

def load_all_reader_data():
    ...

def save_all_reader_data(data):
    ...

def load_document_data(document_id, pdf_path):
    ...

def save_document_data(document_id, pdf_path, bookmarks, notes, last_page):
    ...

`reader_state.py`

This module stores the reader's active state:

reader_state = {
    "current_page": 0,
    "zoom_dpi": 120,
    "search_results": [],
    "search_index": 0,
    "bookmarks": [],
    "notes": []
}

The notebook now focuses on the interface and event handlers, while the reusable logic lives in Python files.

Writing automated tests

I added pytest tests for the storage layer. The tests use temporary folders, so they do not touch my real bookmarks, notes, or reader_data.json file.

Examples of what the tests verify:

Missing storage files return empty reader data.
Saved JSON can be loaded again.
A new document gets the expected default fields.
Bookmarks, notes, and last-read page are saved correctly.
The final JSON output is valid.

The first successful test run was a good milestone:

collected 5 items

5 passed in 0.02s

This was also my first practical lesson in why automated tests matter. The interface can look correct while a save or load function still has a hidden problem. Tests give the project a repeatable safety net before making larger changes.

Problems I encountered

Building this project involved several useful mistakes and fixes.

Tkinter was unavailable

I initially considered a Tkinter desktop interface, but the Linux Python environment did not include the required Tk bindings. Instead of spending the first phase on GUI installation problems, I switched to Jupyter widgets for the prototype and chose PySide6 for the future desktop application.

Ubuntu had an APT lock

An Ubuntu background update held the package-manager lock. The correct response was to wait and inspect the running update, not to delete lock files or force-stop the process.

Widgets displayed incorrectly

At one stage, interactive Jupyter widgets appeared as plain text or did not respond to clicks. The problem was environment setup: Jupyter, the Python kernel, and ipywidgets need to be connected to the same project environment. Restarting the kernel and testing a minimal button helped isolate the issue.

Old notebook functions conflicted with new modules

When I moved code into modules, I accidentally kept old versions of functions such as render_page(), search_document(), and JSON storage functions inside the notebook. This created duplicate names and confusing behavior. The fix was to keep the reusable function in one module and import it into the notebook.

Git repository inside another Git repository

I created a new project folder inside an existing Git repository and accidentally ran git init inside the nested folder. That created a second .git directory. The correct approach was to remove only the accidental nested .git folder and use the original repository at the parent level.

Pytest could not import `src`

My tests initially failed with ModuleNotFoundError: No module named 'src'. I fixed that by adding src/__init__.py and configuring pytest with a pytest.ini file.

[pytest]
pythonpath = .
testpaths = tests

The tests then passed.

GitHub workflow

I learned to use a safer Git workflow for each tested milestone:

git status
git add custom-ai-pdf-reader/src/
git add custom-ai-pdf-reader/tests/
git add custom-ai-pdf-reader/notebooks/
git commit -m "Add modular PDF reader prototype and storage tests"
git push

The .gitignore file is important because local PDFs, the virtual environment, temporary cache files, and personal reader data should not be uploaded.

__pycache__/
*.py[cod]
.pytest_cache/
.venv/
.ipynb_checkpoints/
data/
*.pdf

What I learned

This project taught me more than how to display a PDF in Python. The main lessons were:

A PDF is a document description, not simply an image.
Rendering DPI affects both clarity and memory usage.
PDF points must be scaled when drawing highlights on a pixel image.
Application state makes UI behavior easier to understand and maintain.
Event-driven interfaces use callbacks that run when users click buttons.
JSON serialization makes application data survive a restart.
Temporary-file replacement is safer than directly overwriting data files.
Zero-based page indexes in Python must be translated into human page numbers.
Reusable modules make code easier to test and later reuse in a desktop application.
Tests catch storage problems before they affect real user data.
Git repositories should have one clear root; accidentally nesting repositories causes confusion.

Next steps

The Jupyter prototype now has a tested storage layer. The next milestone is a PySide6 desktop MVP with:

A real desktop window
An Open PDF action
A scrollable rendered PDF page
Previous and Next controls
Page-number navigation
Zoom controls
A status bar

After the desktop foundation is stable, I plan to migrate persistence from JSON to SQLite, add text selection and annotations, then explore AI summaries, PDF question answering with citations, text-to-speech, and voice commands.

Closing thoughts

Starting small was the right choice. I did not begin by trying to build an AI system or a complete commercial PDF application. I started with one page, then navigation, then search, then bookmarks, notes, saved progress, modules, tests, and version control.

Each feature made the next one easier to understand. The project is still at an early stage, but it already has a working and tested foundation for a more capable custom research reader.

If you are building your own developer project, my advice is simple: keep the first version small, make each milestone testable, and commit working progress often.

Progress Update: I Turned My Python PDF Prototype into a Desktop Research Reader

Kavindu Kavishka Premarathna — Fri, 14 Aug 2026 16:11:14 +0000

My previous milestone was an interactive PDF-reader prototype running in Jupyter. It could render PDF pages, navigate, search text, save bookmarks and notes, and restore reading progress.

This update is about the next major step: moving that prototype into a real desktop application with PySide6. The project is still not an AI reader yet, but it now has the core features I need before adding an LLM: reading, navigation, search, notes, bookmarks, and saved annotations.

What changed

The reader is now a desktop application launched with:

python -m src.main

The desktop version currently supports:

Open any local PDF with a native file picker
Render pages in a scrollable window
Previous, Next, and Go-to-page navigation
Zoom controls and a Fit page view
Mouse-wheel scrolling within pages
Mouse-wheel page changes at the top or bottom of a page
Persistent last-read-page restoration
Dockable Bookmarks panel
Dockable Notes panel
Text search with highlighted results
Persistent highlight, underline, and strike-through annotations
Annotations panel with open and delete actions
Keyboard shortcuts for common reading actions

The important design choice is that bookmarks, notes, reading progress, and annotations remain in local reader data rather than modifying the original PDF. That keeps the original paper safe and lets the application later provide an explicit export option.

From notebook UI to desktop UI

The Jupyter prototype used ipywidgets. It was useful for learning the reader logic, but it was not the experience of a normal PDF application.

I moved the UI into PySide6 and kept the underlying reader services separate:

custom-ai-pdf-reader/
├── notebooks/
│   └── Untitled.ipynb
├── src/
│   ├── main.py
│   ├── pdf_service.py
│   ├── reader_state.py
│   └── storage_service.py
├── tests/
│   └── test_storage.py
├── pytest.ini
└── requirements.txt

This separation has been useful:

Module	Responsibility
`main.py`	Desktop interface, controls, panels, events
`pdf_service.py`	Open PDFs, render pages, extract and search text
`reader_state.py`	Current page, zoom level, search state, bookmarks, notes, annotations
`storage_service.py`	Save and load reader data from JSON

The UI can change from Jupyter to PySide6 without rewriting the PDF and persistence logic.

Building the first desktop reader

The desktop reader uses a QMainWindow as the application shell. The PDF page is rendered with PyMuPDF, converted into a Qt image, and shown through a QLabel inside a QScrollArea.

image = render_page(
    document=self.document,
    page_number=current_page,
    dpi=dpi
)

qimage = self.pil_to_qimage(image)
self.original_pixmap = QPixmap.fromImage(qimage)
self.update_page_display()

A scroll area is important because zoomed pages can become larger than the available window. It allows normal vertical and horizontal scrolling instead of forcing a page to remain at one fixed size.

Fit page and mouse-wheel navigation

A reader should not start by showing an oversized or cropped page. I added a Fit page mode that scales the rendered page to the available viewport while preserving its aspect ratio.

fitted_pixmap = self.original_pixmap.scaled(
    viewport_size,
    Qt.AspectRatioMode.KeepAspectRatio,
    Qt.TransformationMode.SmoothTransformation
)

The fit mode automatically updates when the window is resized. Manual zoom disables fit mode, and the Fit page button restores it.

I also added a more natural mouse-wheel behavior:

Scroll normally while reading a large page.
Scroll down at the bottom of the page to move to the next PDF page.
Scroll up at the top of the page to move to the previous PDF page.

This makes the reader feel closer to a standard document viewer while keeping page-based persistence and navigation.

Bookmarks and notes in dockable panels

Bookmarks and notes were already stored by the prototype. The desktop reader now exposes them through dockable side panels.

The Bookmarks panel supports:

Add a custom label to the current page
Double-click a bookmark to open its page
Delete a selected bookmark
Restore bookmarks for the opened document

The Notes panel supports:

Write a multi-line note for the current page
Save a timestamp with the note
Double-click a note to return to its page
Delete a selected note
Restore notes when the same PDF is opened again

I used QDockWidget so the panels can be docked at either side of the reader or closed temporarily. The View menu includes toggle actions, so a closed panel can always be reopened.

Desktop search

The reader can search the entire document and move through matching pages. PyMuPDF returns page rectangles for each search match, which are useful because they are measured in PDF coordinates.

rectangles = page.search_for(query)

When the app renders a page at a specific DPI, PDF rectangles must be converted to pixels:

scale = dpi / 72
pixel_x = pdf_x * scale

This allows search highlights to remain aligned with the rendered text at different zoom levels.

Persistent annotations

The newest feature is a first annotation workflow.

Because the current reader renders pages as images, it does not yet provide arbitrary click-and-drag text selection. Instead, the user searches for a word or phrase, navigates to a search result, and saves that result as one of three annotation types:

Highlight
Underline
Strike-through

Each annotation stores page number, PDF-coordinate rectangles, annotation type, searched text, and timestamp.

{
  "page_number": 4,
  "rectangles": [
    [80.0, 120.0, 240.0, 138.0]
  ],
  "type": "highlight",
  "text": "recognition over recall",
  "created_at": "2026-08-14 21:00"
}

Storing rectangles in PDF coordinates is important. Screen pixels change when DPI changes, but PDF coordinates remain stable. Every time a page is rendered, the reader scales the saved rectangles using the current DPI.

scale = dpi / 72

left = x0 * scale
top = y0 * scale
right = x1 * scale
bottom = y1 * scale

Highlights use a semi-transparent yellow fill, underlines use a blue line near the bottom of the match, and strike-through annotations use a red line through the middle of the match.

The Annotations panel lists saved annotations, opens their associated page on double-click, and lets the user delete a selected annotation.

Why annotations are stored outside the PDF

For this stage, annotations are saved in data/reader_data.json with bookmarks, notes, and reading progress.

This is intentional:

A paper may be read-only or signed.
The original PDF should remain unchanged.
Annotations can be deleted or edited later.
The project can eventually offer an explicit Export Annotated PDF action that writes to a separate copy.

The reader data now has this structure:

{
  "documents": {
    "/absolute/path/to/paper.pdf": {
      "file_name": "paper.pdf",
      "bookmarks": [],
      "notes": [],
      "annotations": [],
      "last_page": 0
    }
  }
}

Keyboard shortcuts

To improve reading productivity, I added shortcuts for common actions:

Shortcut	Action
`Ctrl + O`	Open PDF
`Ctrl + Q`	Exit reader
`Left Arrow`	Previous page
`Right Arrow`	Next page
`Ctrl + F`	Focus search
`Ctrl + B`	Add bookmark
`Ctrl + Plus`	Zoom in
`Ctrl + Minus`	Zoom out

The goal is not only to add features, but also to reduce unnecessary mouse movement while reading research papers.

Testing and version control

The JSON storage layer has automated pytest coverage. The suite checks empty storage, saving and loading data, default document data, bookmark/note/progress persistence, and valid JSON output.

5 passed in 0.02s

I also learned to be selective when staging files. The repository ignores virtual environments, temporary Python files, local PDFs, and personal reader data:

__pycache__/
*.py[cod]
.pytest_cache/
.venv/
.ipynb_checkpoints/
data/
*.pdf

Each tested milestone is committed separately, making it easier to return to a working version if a future feature introduces a problem.

What I learned in this milestone

This desktop stage taught me several practical lessons:

A notebook prototype and a desktop application can share core services while using completely different interfaces.
A QScrollArea is essential for readable zoomed document pages.
Fit-to-window and manual zoom are different modes and need clear behavior.
Dockable panels are a useful pattern for reader tools such as bookmarks, notes, and annotations.
A panel closed with its X button needs a View-menu toggle action so the user can restore it.
PDF coordinates and image pixels must be converted carefully to keep search and annotations aligned.
Local JSON storage is still suitable for a small personal reader, but SQLite will become useful as annotations and document collections grow.
A simple, reliable annotation workflow is better than attempting complex text selection too early.

Next steps

The basic reader is much closer to being ready for AI features. Before integrating an LLM, I still want to improve a few core areas:

Add an explicit clear-search button.
Add edit support for bookmarks and notes.
Add a recent-documents list.
Improve annotation text selection beyond search results.
Add export to a separate annotated PDF copy.
Add tests for PDF rendering and storage with annotations.

After these basics are stable, the next major phase will be LLM-assisted reading:

Paper and chapter summaries
Questions and answers over document text
Page-number citations for answers
Cached local summaries
Privacy controls for local versus cloud models

Closing thoughts

The project started with a single rendered page in a notebook. It now has a desktop reader with persistent research tools and a growing codebase that is modular, tested, and version controlled.

The biggest lesson has been to build the reading workflow first. An LLM can be useful, but it becomes far more useful when the application already knows which document is open, which page the user is reading, what they bookmarked, what they noted, and what they annotated.

The next phase is AI—but the reader now has a foundation worth building AI on.

Building "AXIS" (Step 1): Creating My Own Autonomous AI Agent to Organize Files

Kavindu Kavishka Premarathna — Sun, 02 Aug 2026 14:21:39 +0000

Ever since I started coding, I’ve had one massive, ultimate goal: To build my own personal AI Agent.

I don't just want a standard chatbot. I want an autonomous LLM-powered assistant that lives in my computer, understands my workflow, and handles the heavy lifting for me. I call this agent AXIS (Automated eXtraction and Intelligence System).

Building a fully autonomous AI agent is a massive project, so I decided to break it down.
This is Step 1: Giving AXIS the ability to see, understand, and automatically organize my local file system.

Here is a look at my progress so far, what I’ve learned, the hurdles I faced, and where this project is heading next.

📂 The First Mission: Conquering the Downloads Folder
Like any Computer Engineering student, developer, my folders were a nightmare. It was a chaotic mix of assignment PDFs and functional React code files. Here you can see a sample messy directory.

Instead of manually sorting them every week, I wanted AXIS to do the dirty work for me.

🛠️ What I Built and Learned So Far
To start, I needed to learn how to make a Python script run silently in the background and react to new files without destroying my computer's performance.

Event-Driven Architecture: Instead of writing a while True loop that constantly checks for new files (which burns CPU), I learned how to use the Python watchdog library. It acts as an event listener, meaning AXIS sleeps at 0% CPU usage and only wakes up when the OS tells it a new file has arrived.

Data Extraction & Keyword Matching: For PDFs, I used pypdf to extract text. If the script read technical words related to my studies, it moved the file to my Engineering folder. If it saw "React" or "code", it instantly went to my Software Projects folder.

🚧 **The Major Hurdle: Rule-Based Systems Are Blind
**The keyword system was great, but it hit a massive wall: Media files.

When I downloaded cinematic reference videos, 3D animated assets, or custom banners for my gaming channel, standard OCR (text recognition) completely failed. A rule-based system can't categorize a file if it doesn't know what it's looking at. AXIS was essentially blind to visual context.

🧠 The Solution: Giving AXIS "Eyes"
To solve this, I introduced my first Multimodal LLM integration: The Gemini Vision API.

Instead of searching for text, I configured AXIS to pass image files directly to the AI with a strict prompt, asking it to classify the visual content into my predefined categories.

The result was pure magic. AXIS could now look at a screenshot of a React UI, a complex system architecture diagram, or a highly stylized gaming logo and instantly move it to the correct folder—without relying on a single extracted keyword.

🚀 What’s Next? (The Ultimate Goal)
Right now, AXIS is smart, but it is restricted. It relies on a list of predefined folders I hardcoded into the script.

The next step for AXIS is true autonomy.
In Phase 2, I will remove the hardcoded categories completely. When I drop any file—whether it's an .exe, a movie, a random document, or a complex folder structure—AXIS will analyze the file types and contents, and dynamically generate the perfect folder structure on the fly.

It won't just sort files into boxes I made; it will build the boxes itself based on context.

This is just the beginning of my journey to building a fully-fledged personal AI agent. If you want to follow along, share ideas, or check out the code for Step 1, I’ve made it completely open-source!

💻 Check out the code on GitHub: https://github.com/KKPremarathna/A.X.I.S.

Have you ever tried building your own automation tools or AI agents? Let me know in the comments! Stay tuned for Phase 2.

DEV Community: Kavindu Kavishka Premarathna

Building a Custom AI PDF Reader in Python: From a Jupyter Prototype to Tested Modules

The project goal

Choosing the first technology stack

Building the first reader

A key lesson: application state

Searching and highlighting PDF text

Adding persistent bookmarks and notes

Refactoring the notebook into modules

pdf_service.py

storage_service.py

reader_state.py

Writing automated tests

Problems I encountered

Tkinter was unavailable

Ubuntu had an APT lock

Widgets displayed incorrectly

Old notebook functions conflicted with new modules

Git repository inside another Git repository

Pytest could not import src

GitHub workflow

What I learned

Next steps

Closing thoughts

Progress Update: I Turned My Python PDF Prototype into a Desktop Research Reader

What changed

From notebook UI to desktop UI

Building the first desktop reader

Fit page and mouse-wheel navigation

Bookmarks and notes in dockable panels

Desktop search

Persistent annotations

Why annotations are stored outside the PDF

Keyboard shortcuts

Testing and version control

What I learned in this milestone

Next steps

Closing thoughts

Building "AXIS" (Step 1): Creating My Own Autonomous AI Agent to Organize Files

`pdf_service.py`

`storage_service.py`

`reader_state.py`

Pytest could not import `src`