Add complete scanner-workflow project with auto-scan functionality

scanner/scanner-workflow/README.md

@@ -0,0 +1,219 @@
+# 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:**
+   ```bash
+   cd scanner-workflow
+   ```
+
+2. **Install Python dependencies:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Configure environment variables:**
+   ```bash
+   cp .env.example .env
+   # Edit .env and add your API key
+   ```
+
+4. **Configure scanner settings (optional):**
+   ```bash
+   # 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:
+
+```bash
+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:
+
+```bash
+python scanner-auto.py --max-scans 10
+```
+
+### Test Scanner Detection
+
+Check if the scanner is detected without actually scanning:
+
+```bash
+python scanner-auto.py --test
+```
+
+## Configuration
+
+### config.yml
+
+```yaml
+# 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
+
+```bash
+# 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`:
+```bash
+API_KEY=sk-your-openai-api-key
+```
+
+Update `config.yml`:
+```yaml
+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`:
+
+```yaml
+api_url: "http://localhost:11434/v1/chat/completions"
+model: "llama3"
+```
+
+Install Ollama:
+```bash
+# 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:
+   ```bash
+   brscan-skey --version
+   ```
+
+2. Try different `brother_cmd` in `config.yml`:
+   ```yaml
+   brother_cmd: "brscan4 -s"
+   ```
+
+3. Test detection:
+   ```bash
+   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:
+   ```bash
+   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:
+```bash
+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!