https://github.com/jltk/briefgeist
Privacy-first desktop app for scanning, understanding and replying to letters.
https://github.com/jltk/briefgeist
automation document-analysis local-llm ocr python tesseract
Last synced: 5 months ago
JSON representation
Privacy-first desktop app for scanning, understanding and replying to letters.
- Host: GitHub
- URL: https://github.com/jltk/briefgeist
- Owner: jltk
- License: gpl-3.0
- Created: 2025-05-28T23:41:52.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-05-30T20:04:35.000Z (6 months ago)
- Last Synced: 2025-06-09T19:07:37.799Z (5 months ago)
- Topics: automation, document-analysis, local-llm, ocr, python, tesseract
- Language: Python
- Homepage:
- Size: 34.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Briefgeist
[](LICENSE)
[](https://www.python.org/)
*v0.1.0-preview*
**Briefgeist** is a privacy-first, local desktop assistant for automating the reading, analysis, and response of scanned physical letters.
1. **Watcher service** (Watchdog) for real-time monitoring of incoming scans
2. **OCR module** (Tesseract) for text extraction from PDF scans
3. **Analysis Engine** (local LLM via Ollama “gemma:7b”)
## 📦 Installation
```bash
git clone https://github.com/jltk/briefgeist.git
cd briefgeist
python -m venv venv
source venv/bin/activate # bzw. venv\Scripts\activate on Windows
pip install -r requirements.txt
```
---
## ✅ Features
- 🖨️ Scan letters (via NAPS2)
- 🧠 Analyze content with a local LLM (Gemma 7B via Ollama)
- 🗣 Text-to-speech playback (Coqui TTS)
- 📄 Suggest replies or fill forms
- 🖥️ Simple GUI (NiceGUI)
- 💻 100% offline, no cloud or telemetry
| Feature | Status |
|--------------------|--------|
| OCR (ocrmypdf) | ✅ |
| Text extraction | ✅ |
| Local LLM (Ollama) | ✅ |
| TTS voice output | ✅ |
| GUI (NiceGUI) | ✅ |
| Multi-page scan | ✅ |
---
## 🛠 Setup (Windows 10+)
### 1. Install System Dependencies
- [Python 3.11](https://www.python.org/downloads/release/python-3119/)
- [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
→ Select: "Desktop development with C++"
- [Tesseract OCR (UB Mannheim)](https://github.com/UB-Mannheim/tesseract/wiki)
- [SumatraPDF](https://www.sumatrapdfreader.org/download-free-pdf-viewer.html)
- [NAPS2 (scanner frontend)](https://www.naps2.com)
- [Ollama (LLM runtime)](https://ollama.com)
### 2. Clone This Repo
```bash
git clone https://github.com/yourname/briefgeist.git
cd briefgeist
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```
### 3. Start Ollama
```bash
ollama run gemma:7b
```
---
## 🚀 Usage
### 1. Scan
Use NAPS2 to scan a letter as PDF into the `input/` folder.
### 2. Process with Watcher
```bash
python watcher/watcher.py
```
This will:
* OCR the scanned PDF
* Extract text
* Save `.txt` in `output/`
* Archive the original in `processed/`
### 3. Open GUI
```bash
python ui/app.py
```
* Upload the `.txt`
* Click "Analyze"
* Click "Read Aloud"
---
## 🧪 Testing
| Test Step | Expected Result |
| -------------------- | ----------------------------------- |
| Drop PDF in `input/` | Processed + `.txt` created |
| Run GUI | Interface appears with input fields |
| Analyze | LLM provides meaningful summary |
| Read Aloud | Voice plays locally |
| Print PDF (optional) | Sent to default printer |
---
## 🗂 Project Structure
```
briefgeist/
├── core/
├── ui/
├── watcher/
├── input/ ← Drop PDFs here
├── output/ ← Get your results here
├── processed/ ← Archived input
```
---
## 🔐 Security & Privacy
Briefgeist runs fully offline. No cloud calls. No telemetry. No account required.
---
## 📦 Next Milestones
* [ ] Improve UI/UX
* [ ] Form field detection (insurance, invoices, etc.)
* [ ] Auto-response generation as PDF
* [ ] One-click print & archive
* [ ] Portable GUI build (PyInstaller)
---
## 💬 License
GPLv3