README: refresh Space metadata

README.md

@@ -1,117 +1,82 @@
-# SolarWine — Photosynthesis Prediction for Agrivoltaic Vineyards
-
-A two-stage pipeline that models grapevine photosynthesis under agrivoltaic panels (solar panels above vineyard rows) and predicts it from publicly available weather data. Built for the Sde Boker research site (Negev, Israel).
-
-## Status — May 2026
-
-- **2026 sensor migration complete.** `DEVICE_REGISTRY` clean-replaced (19 Crop_2Soil with spectrometer + dual soil profile, 12 panel thermocouples, 4 trackers). `VineSnapshot` rewritten with NDVI / PRI / PSRI / SIPI / GCI / LCI / DUVI + dual-soil + position-keyed dicts. Treatment = rows 501/502/503/504/509; Reference = row 202.
-- **Energy predictor refreshed.** New `scripts/refresh_energy_data.py` + `scripts/train_energy_predictor.py`. Hourly MAE 4.5 kWh on the May hold-out; **daily bias +50%** is intervention-regime drift (training tracker-angle avg −15°, hold-out avg −51° due to active shading), not a code bug — fix lands once ≥3 months of 2026 growing-season data accumulate (~Aug 2026).
-- **2026 ML pipeline scaffolded.** `scripts/collect_2026_training_data.py` pulls treatment + reference Crop_2Soil + IMS, applies a tracker-angle + ShadowModel PAR-shading correction (PAR factor 0.10–1.00, median 0.82), then computes Farquhar A as labels. First 10 days: 1,896 rows, daytime mean A ≈ 11.7 µmol CO₂/m²/s — squarely in the Greer–Weedon Semillon range.
-- **Frontend redesigned.** React app at `frontend/` rebuilt to the SolarWine editorial design system (Negev sand surfaces, vine green + sun gold, Source Serif 4 + IBM Plex Sans + IBM Plex Mono). All 11 pages — Home, Agronomy, Photosynthesis, Shading, Power, Trackers, Control loop, Advisor, Monitoring, Documentation, **Research** (new) — use the new chrome and Recharts wrappers.
-- **Streamlit dashboard cleaned of stale data.** Control Replay defaults to a fresh 2026 sim log; `scripts/run_control_simulation.py` defaults to `today − 7 d / today`; Shading tab clarifies the legacy `sensors_wide.csv` is frozen at Feb 2026; freshness warnings flag stale logs.
-
-See `context/3_todo.md` § 12 for the rolling work log. `frontend/` is the production UI; `app.py` remains as the legacy Streamlit dashboard.
-
-## What it does
-
-**Stage 1 — Mechanistic model (sensors → photosynthesis rate A)**
-Uses on-site sensor data (PAR, leaf temperature, CO2, VPD, air temperature) collected at 15-minute intervals to compute net carbon assimilation *A* via the Farquhar et al. (1980) biochemical model, with Greer & Weedon (2012) temperature response curves calibrated for *Vitis vinifera*. Includes Crop Water Stress Index (CWSI) and stomatal conductance adjustments. Only the growing season (May–September) is used; vines are dormant October–April.
-
-**Stage 2 — ML prediction (IMS weather → A)**
-Trains regression models to predict *A* using only Israel Meteorological Service (IMS) station 43 data (air temperature, GHI solar radiation, relative humidity, rainfall, wind speed). This enables photosynthesis forecasting without on-site sensors. Models evaluated: Linear Regression, Decision Tree, Random Forest, Gradient Boosting, and XGBoost.
-
-**Time-series forecasting**
-Direct multi-horizon forecasting (15 min, 1 hour, 1 day, 1 week, 1 month ahead) using lag features and daytime-session indexing to handle overnight gaps. Per-horizon XGBoost/GradientBoosting models.
-
-**Tracker optimizer**
-Simulates agrivoltaic panel tilt angles to find the optimal tradeoff between solar energy capture and crop photosynthesis. Computes a stress-aware daily schedule that recommends shading during heat stress periods, with season-level summaries of energy yield, photosynthesis impact, and estimated water savings.
-
-**Solar geometry & canopy photosynthesis**
-Calculates sun position, panel shadow geometry, and diffuse/direct PAR reaching the vine canopy at configurable panel dimensions and row spacings.
-
-## Interactive Streamlit app
-
-A branded dashboard (`app.py`, ~1900 lines) with:
-
-- **Sidebar** — Run Stage 1 / Stage 2, download IMS data (chunked 7-day fetches for 2024–2025), data status indicators
-- **Stage 1 tab** — Labels distribution, validation plots, Farquhar model outputs
-- **Stage 2 tab** — Model comparison metrics (RMSE, MAE, R²), prediction vs actual plots, feature importance
-- **EDA tab** — Sensor distributions, A over time, IMS weather statistics, merged dataset exploration
-- **Time-Series tab** — Multi-horizon forecast results with per-tab explanations
-- **Tracker Optimizer tab** — Tilt-angle simulations, stress heatmaps, daily shading schedule, season summary
-- **About tab** — Two-stage rationale, methodology, and project roadmap
-
-## Project structure
-
-```
-config/settings.py        Site/panel geometry, IMS channel map, paths, train ratio
-src/
-  farquhar_model.py       Farquhar–Greer–Weedon mechanistic photosynthesis model
-  sensor_data_loader.py   Load and filter on-site sensor CSVs
-  ims_client.py           IMS REST API client with caching
-  preprocessor.py         Merge IMS + labels, add time features, temporal split
-  predictor.py            Train/evaluate ML regressors (LR, DT, RF, GBR, XGB)
-  ts_predictor.py         Lag-based multi-horizon time-series forecasting
-  tracker_optimizer.py    Tilt-angle simulation and stress-aware scheduling
-  solar_geometry.py       Sun position, shadow projection, canopy PAR
-  canopy_photosynthesis.py  Canopy-level photosynthesis integration
-scripts/
-  download_ims_data.py    CLI: fetch IMS station data (--list-channels, date range)
-  run_pipeline.py         CLI: execute full Stage 1 → Stage 2 pipeline
-  create_sample_data.py   Generate trimmed sample CSV for cloud deployment
-  eda.py                  Standalone exploratory data analysis
-app.py                    Streamlit dashboard
-Data/Seymour/             On-site sensor data (15-min intervals)
-Data/ims/                 Cached IMS API responses
-Data/processed/           Intermediate files (labels, merged data)
-outputs/                  Metrics CSVs and plots (gitignored)
-assets/                   Logo and vineyard imagery
-```
-
-## Setup
-
-```bash
-python -m venv .venv
-source .venv/bin/activate   # Windows: .venv\Scripts\activate
-pip install -r requirements.txt
-```
-
-Create a `.env` file with your IMS API token:
-
-```
-IMS_API_TOKEN=<your-token>
-```
-
-See [ims_api_documentation.md](ims_api_documentation.md) for token registration.
-
-## Usage
-
-### Download IMS weather data
-
-```bash
-python -m scripts.download_ims_data --list-channels          # show available channels
-python -m scripts.download_ims_data --from 2024-01-01 --to 2024-12-31
-```
-
-### Run the pipeline
-
-```bash
-python -m scripts.run_pipeline
-```
-
-Stage 1: load sensors → filter daytime → keep growing season (May–Sep) → compute Farquhar *A* → save labels.
-Stage 2: load IMS + labels → merge on timestamp → add time features → temporal train/test split → train & evaluate models → save metrics and plots to `outputs/`.
-
-### Launch the app
-
-```bash
-streamlit run app.py
-```
-
-## Key dependencies
-
-pandas, numpy, scikit-learn, xgboost, pvlib, matplotlib, seaborn, plotly, streamlit, requests, python-dotenv
-
-## Deployment
-
-See [DEPLOY.md](DEPLOY.md) for Streamlit Community Cloud deployment instructions. A trimmed sensor sample (`sensors_wide_sample.csv`) is included for cloud use where the full 982 MB dataset is not available.
+---
+title: SolarWine API
+emoji: 🌿
+colorFrom: green
+colorTo: yellow
+sdk: docker
+app_port: 7860
+private: true
+---
+
+# SolarWine API
+
+FastAPI backend for the SolarWine agrivoltaic vineyard control system.
+
+## Endpoints
+
+### Health & Monitoring
+- `GET|HEAD /api/health` — system health (uptime, Redis, TB, IMS, Gemini status)
+- `GET /api/health/data` — data freshness per source (age, ok/degraded)
+- `GET /api/health/data-sources` — per-source green/yellow/red status with thresholds
+
+### Weather (IMS Station 43)
+- `GET /api/weather/current` — latest weather readings + data age
+- `GET /api/weather/history?start_date&end_date&format` — historical weather (hourly)
+- `GET /api/weather/forecast` — weather forecast
+
+### Vine Sensors (ThingsBoard)
+- `GET /api/sensors/snapshot` — latest readings (treatment vs reference)
+- `GET /api/sensors/history?type&area&hours` — sensor time-series
+- `GET /api/sensors/soil-moisture?hours` — soil moisture history
+- `GET /api/sensors/rain?hours` — rainfall history
+
+### Energy
+- `GET /api/energy/current` — current power output (kW)
+- `GET /api/energy/daily/{date}` — daily production + hourly profile
+- `GET /api/energy/history` — energy generation time-series
+- `GET /api/energy/predict/{date}` — predicted daily generation
+
+### Photosynthesis
+- `GET /api/photosynthesis/current?model` — current A rate (FvCB or ML)
+- `GET /api/photosynthesis/forecast` — 24h predicted A profile
+
+### Control System
+- `GET /api/control/status` — last control loop tick
+- `GET /api/control/plan` — current day-ahead plan
+- `GET /api/control/budget` — energy budget status
+- `GET /api/control/trackers` — tracker angles and modes
+
+### Chatbot (Gemini AI)
+- `POST /api/chatbot/message` — send message to vineyard advisor
+- `POST /api/chatbot/feedback` — submit feedback on response
+- `GET /api/chatbot/briefing` — current system status briefing
+
+### Biology
+- `GET /api/biology/phenology` — current growth stage
+- `GET /api/biology/rules` — all biology rules
+- `GET /api/biology/rules/{name}` — single rule detail
+- `GET /api/biology/chill-units?season_start` — accumulated chill units
+
+### Auth
+- `POST /api/auth/login` — JWT token (guest mode when JWT_SECRET unset)
+
+### Events
+- `GET /api/events/stream` — SSE stream for live frontend updates
+
+Interactive docs at `/docs`.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `IMS_API_TOKEN` | Yes | IMS weather API token |
+| `THINGSBOARD_HOST` | Yes | ThingsBoard server URL |
+| `THINGSBOARD_USERNAME` | Yes | ThingsBoard login |
+| `THINGSBOARD_PASSWORD` | Yes | ThingsBoard password |
+| `GOOGLE_API_KEY` | No | Gemini AI for chatbot/advisor |
+| `JWT_SECRET` | No | JWT signing key (guest mode if unset) |
+| `ADMIN_PASSWORD` | No | Login password |
+| `REDIS_URL` | No | Upstash Redis for shared cache |
+| `SENTRY_DSN` | No | Sentry error tracking |
+| `SMTP_HOST` | No | Email alerts (with ALERT_EMAIL_TO) |
+| `ALERT_EMAIL_TO` | No | Alert recipient email(s) |