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:**
   ```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!