Add AGENTS.md for AI agent context

2026-05-25 20:18:58 -04:00
parent 064740ef2e
commit 9888601863
1 changed files with 80 additions and 0 deletions
@@ -0,0 +1,80 @@
+# 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
+
+```bash
+# 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