PHOTON — local photo intelligence console

A local web application that scans your photo collection, uses local Ollama vision models to describe + categorize each photo, and embeds standard metadata inside photo files so everything becomes searchable across Spotlight, Finder, Photos, Lightroom, etc.

Original photos remain completely untouched unless you explicitly choose to edit or delete them.

---

Quick Start (Zero-Config)

Drop this directory inside the photo collection you want to organize, then run:

cd "your-photo-library/photon"
python3 server.py
# Open http://localhost:8765 in your browser

Automatic Folder Detection & Overrides

• Auto-Detection: Scans the parent directory of wherever server.py lives.
• Persistence: Remembers your last scanned folder (photon_folder.json).
• CLI & Environment Overrides:

  python3 server.py /path/to/photos                       # CLI argument override
  PHOTON_FOLDER=/path/to/photos python3 server.py         # Environment variable override
  PHOTON_PORT=8766 python3 server.py                      # Custom port
  

Prerequisites

• Ollama running locally with a vision model (e.g. ollama pull qwen3.5:9b or ollama pull qwen3.5:4b).
• exiftool (installed via Homebrew: brew install exiftool).
• macOS (sips built-in for fast downscaling & pixel integrity verification).
• ffmpeg / ffprobe (optional: for video frame extraction & video thumbnails).

---

Key Features & Capabilities

1. Multithreaded 3-Stage Pipeline

1. Downscale Stage: Uses macOS sips to create fast temp copies (original files are read-only).
2. Inference Stage: Calls local Ollama vision models to determine {description, category}.
3. Write Stage: Uses exiftool to embed metadata with atomic renames and date preservation (-P).

2. Search & Interactive Library Browser

• Instant Search: Full-text keyword search across descriptions, categories, filenames, and paths.
• Filter Chips: 1-click taxonomy pills (People, Animals, Screenshots, Vehicles, Objects, etc.).
• Sub-Views:
  • Tagged: Explore and filter all processed photos.
  • Untagged: Browse photos awaiting tagging.
  • Failed: View and retry failed operations.
  • Videos: Frame extraction, AI tagging, and native video player.
  • Duplicates: Perceptual hash index (pHash) visual duplicate grouping.

3. Full-Screen Lightbox & Organic Browsing

• Snappy Viewer: Full-resolution image/video lightbox with metadata inspector.
• 0ms Image Prefetching: Pre-caches adjacent images in memory for instant switching.
• Keyboard Shortcuts:
  • ← / → : Navigate previous / next photo.
  • Esc : Close Lightbox.
  • Delete / Backspace : Delete current photo on disk.

4. Disk Photo Deletion & Management

• Single & Bulk Deletion: Click "Delete Photo" or select multiple photos to permanently delete them on disk (or send to macOS Trash).
• Automated Cleanup: Deleting a photo purges its entry from photon_journal.jsonl, removes _organized/ symlinks, and clears thumbnail & view caches.

5. Bulk Operations & Export

• Select Mode: Range selection via Shift-Click or "Select All Matching".
• Exporting: Export catalog metadata to CSV or JSON.
• ZIP Downloads: Stream original-quality files into a single ZIP archive.

6. Trust & Safety Safeguards

• Verify Pixel Integrity: Option to double-hash image pixels via raw BMP conversions before and after writes. Guarantees 100% zero image corruption.
• Organized Symlinks: Generates relative portable Finder aliases in [folder]/_organized/[category]/[name].
• Undo All Tags: One-click exiftool pass to cleanly remove all photon-tagged metadata and categories.
• Persistent Failure Retries: Saves errored paths to photon_failures.jsonl with 1-click retry.

7. Quality Control & Custom Taxonomies

• Blind Accuracy Grader: Interactive 100-photo audit mode to score description quality.
• Custom Categories: Edit, add, or customize category schemas (photon_categories.json).

---

Standard Metadata Specifications

exiftool embeds the following tags into image files:

• EXIF:ImageDescription, IPTC:Caption-Abstract, XMP-dc:Description — Description string
• XMP-dc:Subject, IPTC:Keywords — Category string + photon-tagged keyword

---

License & Safety Notice

Original photo files are never deleted or modified unless you explicitly trigger Delete Photo, Metadata Writing, or Undo All Tags.