8000 GitHub - jaiveer077/gnome-pdf-agent: Custom ai-pdf agent using langchain built on top of GTK4. · GitHub
[go: up one dir, main page]

Skip to content
8000

About

Custom ai-pdf agent using langchain built on top of GTK4.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

🦊 GNOME PDF Agent

A native GNOME desktop AI assistant overlay. Highlight confusing text in any PDF (or anywhere on screen), press a hotkey, and get clear, context-aware explanations — without ever leaving your document or opening a browser.


📖 Table of Contents


🧐 What Is This?

GNOME PDF Agent is a seamless, distraction-free reading companion built specifically for the Linux desktop environment.

When you are reading a dense academic paper, textbook, or technical documentation in a standard viewer (like GNOME Document Viewer / Evince), you can simply highlight any confusing sentence with your mouse. By clicking a button or using a hotkey, a native sidebar slides in, allowing you to ask questions about that specific text.

More importantly, it is context-aware. If you load your PDF into the app beforehand, it reads and remembers the entire document. When you ask a question, the assistant uses the surrounding context from your document to give you highly accurate, tailored answers instead of generic guesses.


🎯 The Problem It Solves

Reading complex material often involves constant, frustrating context-switching:

  1. The Distraction Penalty: You hit an unfamiliar term, alt-tab to a web browser, search for the definition, and inevitably lose your train of thought (or get distracted by open tabs).
  2. Generic Answers: Standard chatbots don't know what you are reading. They give you broad definitions that might not apply to the specific context of your textbook or paper.
  3. Friction: Having to constantly copy text, switch windows, paste it into a prompt box, and manually explain what you are reading is tedious.

GNOME PDF Agent solves this by:

  • Keeping the assistant right next to your reading material in a beautiful, native sidebar.
  • Automatically grabbing what you highlight so you never have to copy and paste.
  • Cross-referencing your questions against the specific PDF you are currently reading to provide perfectly tailored explanations.

⚙️ How It Works (Workflow)

The application workflow is designed to be invisible and frictionless.

  1. Ingestion: You load a PDF into the application. The system quietly reads the document, breaks it down into paragraphs, and stores a mathematical representation (vectors) of the text on your local hard drive.
  2. Selection: You read your document normally. When you highlight text, the application intercepts your operating system's "Primary Selection" buffer (the temporary memory that holds highlighted text).
  3. Retrieval: You ask a question. The system instantly searches through the mathematical representations of your PDF to find the 3 or 4 paragraphs most relevant to your highlighted text and question.
  4. Generation: The application packages your question, your highlighted text, and the relevant paragraphs from the PDF, and sends them to a powerful cloud AI brain.
  5. Streaming: The AI processes the context and streams the answer back to your sidebar, typing it out in real-time.

🧰 Tech 7B0F Stack

The project leverages a modern, cutting-edge technology stack to provide a smooth desktop experience combined with powerful AI:

Frontend / Desktop Experience

  • Python 3: The core logic driving the application.
  • GTK4 & libadwaita (via PyGObject): The foundation of the user interface. GTK4 provides hardware-accelerated rendering, while libadwaita ensures the application perfectly matches the modern, rounded, and polished design language of the GNOME desktop environment.
  • Wayland APIs: Deep operating system integration allows the app to read the Wayland Primary Selection buffer securely and instantly, enabling the "highlight-to-grab" functionality without needing clipboard managers.

AI & Data Processing

  • LangChain: An advanced framework used to orchestrate AI pipelines. It manages the flow of taking your question, retrieving the right data, and formatting the prompts that go to the AI.
  • ChromaDB: A high-performance vector database running locally on your machine. It stores the "embeddings" (mathematical vectors) of your PDFs. When you ask a question, Chroma performs an ultra-fast semantic search to find paragraphs in your document that mean the same thing as your question, even if they don't use the exact same words.
  • PyPDF & Recursive Text Splitters: Tools used to accurately extract raw text from PDF files and slice them into overlapping chunks so that context isn't lost at the edges of paragraphs.
  • Asynchronous Networking (HTTPX): The app uses fully asynchronous network calls and Server-Sent Events (SSE) to talk to the cloud brain. This ensures that the desktop interface never freezes while waiting for the network, and allows answers to stream in word-by-word.

🚀 How to Run on Your Machine

Since the heavy lifting (the AI processing backend) is securely hosted in the cloud, you only need to run the lightweight desktop client on your machine.

Prerequisites

You need a Linux distribution running GNOME (like Fedora or Ubuntu) and Python 3 installed. You will also need the system packages for GTK4.

On Fedora, you can install the requirements with:

sudo dnf install python3-devel gcc python3-gobject gtk4 libadwaita gobject-introspection

Installation Steps

  1. Clone the repository and enter the directory:

    git clone https://github.com/jaiveer077/gnome-pdf-agent.git
    cd gnome-pdf-agent
  2. Create a virtual environment: We recommend creating a virtual environment that has access to your system's GTK packages.

    python3 -m venv --system-site-packages .venv
    source .venv/bin/activate
  3. Install the Python dependencies:

    pip install -r requirements.txt
  4. Launch the app!

    python3 main.py

💡 Usage

  1. Open the app using the command above.
  2. Click Load PDF Database and select the PDF you are about to read. Wait a few moments for the indexing to complete.
  3. Open your PDF in any viewer (like Evince or your web browser).
  4. Highlight any confusing text with your mouse.
  5. In the assistant window, click Grab Highlighted Text.
  6. Type your question into the entry box (e.g., "Explain this concept like I'm 5" or "How does this relate to the previous chapter?") and click Ask AI.
  7. Watch the tailored answer stream directly into your sidebar!

About

Custom ai-pdf agent using langchain built on top of GTK4.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0