collaboration/scanner/scanner-workflow/README.md

Brother Scanner Auto-Workflow

Automated scanning workflow for Brother DS mobile scanners with LLM-powered document naming.

Features

• 🔍 Auto-detect - Automatically detects when you place a document in the scanner
• 📄 Auto-scan - Starts scanning without manual intervention
• 🧠 Smart naming - Uses LLM to generate meaningful titles
• 💾 Local storage - Saves to configured local folder
• 📊 Scan logging - Tracks all scans in JSON log

Prerequisites

Hardware

• Brother DS-640 scanner (or compatible Brother mobile scanner)

Software

• Python 3.9+
• Brother scanner drivers and CLI tools (brscan-skey or brscan4)
• LLM API (OpenAI or OpenAI-compatible like Ollama)

Installation

1. Clone or navigate to the project directory:

   cd scanner-workflow
   

2. Install Python dependencies:

   pip install -r requirements.txt
   

3. Configure environment variables:

   cp .env.example .env
   # Edit .env and add your API key
   

4. Configure scanner settings (optional):

   # Edit config.yml to set scan directory and brother command
   # For DS-640, try: brother_cmd: "brscan-skey -s"
   

Usage

Basic Auto-Scan (Continuous Mode)

Run the scanner in auto-detect mode. It will wait for you to place a document and automatically scan it:

python scanner-auto.py

The script will:

1. Wait for you to place a document in the scanner
2. Auto-detect when the document is ready
3. Start scanning automatically
4. Generate a meaningful title using LLM
5. Save as {title} - {timestamp}.pdf

Limit Number of Scans

Scan a maximum of 10 documents and then stop:

python scanner-auto.py --max-scans 10

Test Scanner Detection

Check if the scanner is detected without actually scanning:

python scanner-auto.py --test

Configuration

config.yml

# Directory where scanned PDFs will be saved
scan_dir: "scans"

# Brother scanner command
brother_cmd: "brscan-skey -s"

# LLM API configuration
api_url: "http://localhost:11434/v1/chat/completions"
model: "llama3"

.env

# LLM API Key (optional for local LLMs like Ollama)
API_KEY=

File Structure

scanner-workflow/
├── scanner-auto.py          # Main script
├── config.yml               # Configuration
├── .env.example             # Environment template
├── requirements.txt         # Python dependencies
├── README.md                # This file
├── .env                     # Your API key (create from .env.example)
├── scans/                   # Output directory (auto-created)
│   ├── scan_log.json        # Scan history
│   └── *.pdf                # Scanned documents
└── tests/                   # (optional) Test scripts

LLM Integration

Using OpenAI

Set your API key in .env:

API_KEY=sk-your-openai-api-key

Update config.yml:

api_url: "https://api.openai.com/v1/chat/completions"
model: "gpt-3.5-turbo"

Using Ollama (Local)

No API key needed! Just run Ollama locally and update config.yml:

api_url: "http://localhost:11434/v1/chat/completions"
model: "llama3"

Install Ollama:

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Then pull the model
ollama pull llama3

Troubleshooting

Scanner not detected

1. Check if Brother scanner tools are installed:

   brscan-skey --version
   

2. Try different brother_cmd in config.yml:

   brother_cmd: "brscan4 -s"
   

3. Test detection:

   python scanner-auto.py --test
   

LLM not working

1. Verify API key in .env
2. Check API URL in config.yml
3. Test API connectivity:

   curl -X POST $api_url \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model":"'$model'","messages":[{"role":"user","content":"Hello"}]}'
   

Permission errors

Make sure the script can write to the scan directory:

chmod +x scanner-auto.py

Example Output

============================================================
🤖 Brother Scanner - Auto-Detect Mode
============================================================
📁 Scan directory: scans
🔄 Brother command: brscan-skey -s
🧠 LLM API: http://localhost:11434/v1/chat/completions
============================================================

[14:30:15] Waiting for document...
✓ Document detected by scanner
→ Starting scan: brscan-skey -s -f scans/scan_20260214_143015.pdf
✓ Scan completed: scan_20260214_143015.pdf (245678 bytes)
→ Generating title with LLM...
✓ LLM title: Invoice from Acme Corp
✓ Saved as: Invoice from Acme Corp - 20260214_143015.pdf

License

MIT License - Feel free to use and modify as needed.

Contributing

Suggestions and improvements welcome!