# Smart Intake

Unified document, image, and audio intake with auto-classification, routing, and human-in-the-loop review. Owned by the **Scribe** job class, but available to all job classes.

## What it does

Drop any file — photo of a receipt, grant PDF, business card scan, voice memo, invoice — and Smart Intake will:

1. **Extract text** using the best available method (vision LLM → OCR → PDF reader → audio transcription)
2. **Classify** the content type using a 3-tier pipeline (extraction templates → keyword heuristics → LLM refinement)
3. **Review gate** — low-confidence or unknown classifications are flagged for human review
4. **Route** to the right store automatically (donors, grants, events, advocacy, notes)
5. **Record** the operation in intake history for audit

## Tools

| Tool | Description |
|------|-------------|
| `smart_intake` | Process a single file through the pipeline |
| `batch_intake` | Process multiple files or a directory at once |
| `intake_history` | View intake history and statistics |
| `review_intake` | List, approve, or reject items in the review queue |
| `watch_folder` | Add/remove/list watched directories for auto-intake |
| `check_watches` | Check all watch folders for new files and process them |
| `clip_webpage` | Clip a web page — fetch, extract text, classify, and route |
| `list_templates` | List extraction templates learned from review corrections |

## Supported file types

- **Images**: PNG, JPG, TIFF, BMP, GIF, WebP (via vision LLM or OCR)
- **Documents**: PDF, DOCX, XLSX, CSV, TXT, Markdown
- **Audio**: MP3, WAV, M4A, OGG, FLAC, AAC (via faster-whisper)

## Content types & routing

| Content Type | Routes To | Key Fields Extracted |
|-------------|-----------|---------------------|
| Donation Receipt | Nonprofit donors | donor_name, amount, date |
| Grant Document | Grant pipeline | grant_name, funder, amount, deadline |
| Invoice | Notes | vendor, amount, due_date |
| Event Flyer | Event management | event_name, date, venue |
| Legislation | Advocacy tracker | bill_number, title, jurisdiction |
| Business Card | Donors/contacts | name, title, org, email, phone |
| Meeting Notes | Notes | date, attendees |
| Recipe | Notes | name, servings |

## Review Queue

Items are auto-flagged for review when:
- Classification confidence < 50%
- Content type is UNKNOWN

Review actions:
- **Approve** — route the item as classified (or with corrected type/fields)
- **Reject** — discard the item with a reason

When you approve with corrections, the system learns an **extraction template** so similar documents are classified correctly next time.

## Watch Folders

Monitor up to 10 directories for new files. Poll-based (no inotify dependency). Files are tracked by SHA-256 hash — already-seen files are skipped. Max 100 files per check cycle.

## Web Clipping

Clip web pages into your records. Content is fetched with httpx, HTML is stripped to text, saved as Markdown in `~/.familiar/data/clips/`, and run through the classification pipeline.

## Extraction Templates

Learned from review corrections. Templates store text patterns and field labels. When a new document matches a template (≥60% pattern coverage), the classification gets a +0.2 confidence boost. Max 100 templates, sorted by use count.

## Scribe Job Class

The Scribe is the dedicated records management role. Its workspace ("Records Office") shows:
- **Inbox** — recent intake entries
- **Review Queue** — items needing human verification
- **Recent Scans** — last processed files
- **Transcriptions** — audio file results
- **Statistics** — breakdown by content type
- **Search** — filter intake history

## Dashboard API

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/scribe/inbox` | GET | List inbox entries |
| `/api/scribe/inbox/process` | POST | Process a file |
| `/api/scribe/review` | GET | List review queue |
| `/api/scribe/review/<id>/approve` | POST | Approve item |
| `/api/scribe/review/<id>/reject` | POST | Reject item |
| `/api/scribe/search` | GET | Search history |
| `/api/scribe/stats` | GET | Intake + review stats |
| `/api/scribe/watches` | GET/POST | List/add watches |
| `/api/scribe/watches/<id>` | DELETE | Remove watch |
| `/api/scribe/clips` | GET | List web clips |
| `/api/scribe/templates` | GET | List templates |

## Dependencies

No new dependencies — uses existing platform capabilities:
- **Vision**: Ollama vision models (qwen2.5-vl, llava, llama3.2-vision)
- **OCR**: pytesseract + Pillow (`docs` extra)
- **PDF**: PyMuPDF (`docs` extra)
- **Audio**: faster-whisper (`voice` extra)
- **Web clipping**: httpx (core dep)

## Examples

```
"Scan this donation receipt" → smart_intake({filepath: "receipt.jpg"})
"Process all files in my inbox folder" → batch_intake({directory: "~/inbox"})
"What have I scanned recently?" → intake_history({action: "stats"})
"Show items needing review" → review_intake({action: "list"})
"Approve that receipt" → review_intake({action: "approve", item_id: "review_abc123"})
"Watch my Downloads folder" → watch_folder({action: "add", directory: "~/Downloads"})
"Check for new files" → check_watches({})
"Save this grant page" → clip_webpage({url: "https://example.com/grant"})
"What templates have we learned?" → list_templates({})
```
