exif-test/AGENTS.md

EXIF Test — Agent Guide

EXIF + OCR test backend that validates GPS data survives the upload pipeline. Photo upload with metadata preservation, OCR machine ID reading, session management, and GPS proximity search.

Stack

• Python 3.11+, FastAPI, uvicorn
• Pillow, pillow-heif — image processing (JPEG, HEIC/HEIF)
• pytesseract — Tesseract OCR
• Optional LLM OCR — OpenCode Go / Google Gemini
• Frontend: vanilla JS SPA, IndexedDB offline queue
• Service worker (static/sw.js) — offline photo queue

Project Structure

server.py                 # ~1.5K lines — ALL FastAPI routes in one file
new_endpoints.py          # Placeholder for future endpoints
FEATURE_PLAN.md           # ~629 lines — comprehensive roadmap (✅ done / 💡 proposed)
requirements.txt
test_e2e_smoke.sh         # End-to-end smoke test

static/
  index.html              # SPA frontend (~79KB)
  sw.js                   # Service worker for offline photo queue

How to Run

# Dev (with reload)
uvicorn server:app --reload --host 0.0.0.0 --port 8903

# Production
python server.py
# or
uvicorn server:app --host 0.0.0.0 --port 8903

Key Architecture

• Single-file backend — server.py has all routes
• Hotels dotenv from ~/.hermes/.env
• Uses photos.db for photo/session metadata
• Loads machine data from canteen-asset-tracker/assets.db
• Supports Tesseract and optional LLM-based OCR (OpenCode Go, Google Gemini)
• Frontend has IndexedDB offline queue for uploading photos without connection

Features

• Photo upload with EXIF metadata extraction
• OCR machine ID reading (ConnectID sticker)
• Session-based grouping
• GPS proximity search
• Export: CSV, KML, clipboard
• Bulk assign to machines

Production

• Port: 8903
• No systemd
• Dev only — --reload in dev scripts

Pitfalls

• No requirements.txt committed — dependencies inferred from imports
• Single-file backend — server.py is ~1.5K lines
• LLM-based OCR requires OpenCode Go or Gemini configured in environment
• HEIC support requires pillow-heif + system libheif