canteen-seed-import/AGENTS.md

Canteen Seed Import — Agent Guide

Standalone seed data import tool for populating the Canteen assets database from Cantaloupe CSV exports. Conceptual prototype before integration into admin panel.

Stack

• Python 3.11+, pandas, numpy, sqlite-utils
• httpx — sync to remote DB targets
• rich — CLI output formatting
• click — CLI framework
• FastAPI + uvicorn — web UI for import workflow
• python-multipart — file upload

Project Structure

main.py                   # CLI entry point (seed/update modes)
parser.py                 # CSV/Excel parsing, header mapping, location extraction
db_writer.py              # SQLite write operations
sync.py                   # Sync to remote DB targets
backup.py                 # Backup/restore GPS + photo data
reporter.py               # Validation report generation
requirements.txt
start.sh                  # Production launch (port 8091)
start-dev.sh              # Dev launch (port 8093, separate dev DB)

seed-data/
  import_seed.csv         # Main import CSV
  headers_modified.csv    # Header mapping reference
  reference_handbook.md   # Extraction rules
  validation_report.md    # Validation results

web/
  server.py               # FastAPI web UX
  static/
    index.html            # Import web UI

How to Run

# CLI seed import
python main.py seed-data/import_seed.csv --db /path/to/assets.db

# CLI update mode (incremental)
python main.py seed-data/import_seed.csv --mode update --db /path/to/assets.db

# Web UI (production)
./start.sh

# Web UI (dev)
./start-dev.sh

Key Architecture

• Two modes: seed (fresh insert) and update (incremental — skips existing)
• Dry-run support: preview changes before committing
• Backup-preserving — creates DB backups before imports
• Web UI provides: Excel upload, preview, import, backup management, report viewing
• GPS location derivation from address/city/state columns

Production

• Port: 8091 (prod), 8093 (dev)
• Configurable via: CANTEEN_IMPORT_PORT env var
• No systemd

Environment Variables

Var	Default	Description
CANTEEN_IMPORT_PORT	8091	Web UI port
CANTEEN_DB_PATH	—	Target DB path for sync mode

Pitfalls

• Seed data CSVs use custom header format — parser.py has header mapping logic
• Location extraction is heuristic (address/columns → GPS lookup)
• Web UI and CLI share the same parser/db_writer modules