Blame for ui/tab_overview.py

"""
Overview tab: presentation and key takeaways for the SolarWine app.
"""

from __future__ import annotations

import pandas as pd
import streamlit as st

from config import settings
from ui.bootstrap import (
    check_ai_health,
    ensure_ims_refresh_background,
    load_labels,
    load_metrics,
)

_ASSETS = settings.PROJECT_ROOT / "assets"


def render_tab_overview() -> None:
    _ai_status = check_ai_health()
    _ims_status = ensure_ims_refresh_background()

    status_cols = st.columns(2)
    with status_cols[0]:
        if _ai_status.get("ok"):
            st.caption("AI service status: healthy (Gemini reachable).")
        else:
            st.warning(
                "AI service status: unavailable. "
                "Gemini calls may fall back to biology-only answers or cached data. "
                "Check your GOOGLE_API_KEY or network access."
            )
            if _ai_status.get("error"):
                st.caption(f"AI health check error: `{_ai_status['error']}`")

    with status_cols[1]:
        if _ims_status.get("running"):
            st.caption("IMS cache status: refreshing recent weather data in the background…")
        elif _ims_status.get("ok"):
            st.caption("IMS cache status: refreshed with recent weather data.")
        else:
            st.warning(
                "IMS cache status: not up to date. "
                "Latest weather in the app may be stale until IMS is fixed."
            )
            if _ims_status.get("error"):
                st.caption(f"IMS refresh error: `{_ims_status['error']}`")

    st.markdown("## 1. SolarWine — Smart Shading for Agrivoltaic Vineyards")
    st.markdown(
        "**Site:** Sde Boker research station, Negev desert, Israel  \n"
        "**Crop:** *Vitis vinifera* cv. Semillon grapevine  \n"
        "**Challenge:** Solar panels and grapevines compete for the same sunlight. "
        "How do we split it so both thrive?"
    )

    _vineyard_img = _ASSETS / "vineyard_panels.png"
    _closeup_img = _ASSETS / "vineyard_closeup.png"
    if _vineyard_img.exists() or _closeup_img.exists():
        _p_img_l, _p_img_r = st.columns(2)
        if _vineyard_img.exists():
            with _p_img_l:
                st.image(str(_vineyard_img), width='stretch',
                         caption="Solar trackers above grapevine rows")
        if _closeup_img.exists():
            with _p_img_r:
                st.image(str(_closeup_img), width='stretch',
                         caption="Grapevines under tilted solar panels")

    st.markdown(
        "**Why photosynthesis?** Our working hypothesis is simple: "
        "a vine that photosynthesizes well produces good wine. Photosynthesis "
        "drives sugar accumulation, flavor-compound synthesis, and canopy health "
        "— so if we can keep A (net carbon assimilation) high throughout the "
        "growing season, grape quality follows. Everything in this system is "
        "built around measuring, predicting, and protecting photosynthesis."
    )
    st.markdown(
        "The Negev provides **far more radiation** than a grapevine can use — "
        "midday PAR routinely exceeds 2000 µmol/m²/s, but photosynthesis "
        "saturates well below that. The surplus can be harvested as electricity "
        "without hurting the vine."
    )
    st.markdown(
        "But first we need to *measure* how much photosynthesis the vine actually "
        "performs — that's what the Farquhar model does."
    )

    with st.expander("What is agrivoltaics? What is PAR?"):
        st.markdown(
            "**Agrivoltaics** is the dual use of land for both agriculture and solar "
            "energy — panels are mounted above the crops so both share the same field.\n\n"
            "**PAR (Photosynthetically Active Radiation)** is the slice of sunlight "
            "(wavelengths 400–700 nm) that plants actually use for photosynthesis, "
            "measured in µmol photons/m²/s.\n\n"
            "**Light saturation** means that beyond a certain PAR threshold, more "
            "light does *not* increase photosynthesis — the vine's internal "
            "biochemistry becomes the bottleneck, not the light supply.\n\n"
            "**Why Sde Boker?** The Negev desert delivers extreme radiation, well "
            "above the vine's saturation point, making it an ideal site to demonstrate "
            "that surplus light can be redirected to electricity without harming the crop."
        )

    st.divider()

    st.markdown("## 2. Two-Stage Pipeline")
    st.markdown(
        "We built a two-stage system to model and then predict vine photosynthesis:"
    )

    _p_s1, _p_arrow1, _p_s2, _p_arrow2, _p_s3 = st.columns([3, 1, 3, 1, 3])
    with _p_s1:
        st.markdown(
            "### Stage 1: Measure\n"
            "**6 on-site sensors** (PAR, leaf temp, air temp, CO₂, VPD, humidity) "
            "→ Farquhar FvCB mechanistic model → **photosynthesis rate A** "
            "(µmol CO₂ m⁻² s⁻¹)"
        )
    with _p_arrow1:
        st.markdown("<div style='text-align:center; font-size:2rem; padding-top:2rem'>→</div>",
                     unsafe_allow_html=True)
    with _p_s2:
        st.markdown(
            "### Stage 2: Predict\n"
            "**On-site sensors + IMS weather** (station 43 — temperature, GHI, "
            "humidity, wind, rain) → ML regressors (RF, GBR, XGBoost) → "
            "**forecast A ahead of time**"
        )
    with _p_arrow2:
        st.markdown("<div style='text-align:center; font-size:2rem; padding-top:2rem'>→</div>",
                     unsafe_allow_html=True)
    with _p_s3:
        st.markdown(
            "### Goal\n"
            "Predict tomorrow's photosynthesis so the **panel-tilt optimizer** "
            "can plan tracker angles a day ahead — shading only when the vine "
            "actually needs protection."
        )

    st.info(
        "**CO₂ correction:** On-site CO₂ sensor reads ~600 ppm (known warm bias). "
        "A ×0.7 correction factor brings values to ~420 ppm, consistent with "
        "ambient atmospheric levels."
    )

    with st.expander("Key terms: Farquhar model, ML regressors, IMS"):
        st.markdown(
            "**Farquhar FvCB model** (1980) is the standard physics-based model that "
            "predicts leaf photosynthesis from light, temperature, and CO₂ — think of "
            "it as a formula that says *'given this much light and heat, the leaf fixes "
            "this much carbon.'*\n\n"
            "**ML regressors** are machine-learning algorithms that learn patterns "
            "from data:\n"
            "- **RF (Random Forest):** many decision trees vote together\n"
            "- **GBR (Gradient Boosted Regression):** trees are added one at a time, "
            "each correcting the previous errors\n"
            "- **XGBoost:** an optimised variant of gradient boosting\n\n"
            "**IMS** — Israel Meteorological Service, providing free public weather "
            "station data.\n\n"
            "**VPD (Vapor Pressure Deficit)** measures how dry the air is. High VPD "
            "makes the vine close its stomata (leaf pores) to conserve water, which "
            "reduces CO₂ intake and slows photosynthesis.\n\n"
            "**Why two stages?** Stage 1 computes A from current sensor readings "
            "(what is happening *now*); Stage 2 learns to *forecast* A ahead of time "
            "so the tracker optimizer can plan tomorrow's panel angles today."
        )

    st.divider()

    st.markdown("## 3. Stage 1 — Farquhar Mechanistic Model")
    st.markdown(
        "The Farquhar et al. (1980) model with Greer & Weedon (2012) grapevine "
        "parameters computes **A = min(Ac, Aj) − Rd** at each 15-min interval "
        "during the growing season (May–Sep, daytime PAR > 50)."
    )

    _p_labels_path = settings.PROCESSED_DIR / "stage1_labels.csv"
    _p_val_img = settings.OUTPUTS_DIR / "stage1_validation.png"

    if _p_labels_path.exists():
        _p_labels = load_labels(str(_p_labels_path))
        _p_labels.index = pd.to_datetime(_p_labels.index, utc=True)

        _pc1, _pc2, _pc3, _pc4 = st.columns(4)
        _pc1.metric("Observations", f"{len(_p_labels):,}")
        _pc2.metric("Mean A", f"{_p_labels.iloc[:, 0].mean():.1f} µmol m⁻² s⁻¹")
        _pc3.metric("Date from", _p_labels.index.min().strftime("%Y-%m-%d"))
        _pc4.metric("Date to", _p_labels.index.max().strftime("%Y-%m-%d"))
    else:
        st.warning("Stage 1 labels not found — run the pipeline first.")

    if _p_val_img.exists():
        st.image(str(_p_val_img), width='stretch',
                 caption="Top: Diurnal A pattern (bell curve peaking mid-morning). "
                         "Bottom: A vs PAR (light-response curve with saturation).")

    st.success(
        "**Key insight:** The model produces physiologically plausible A values — "
        "a clear diurnal bell curve and the expected light-saturation response."
    )
    st.markdown(
        "With reliable A measurements in hand, the next step is *predicting* A "
        "from weather data so the system can plan ahead."
    )

    with st.expander("Reading the results: what is A? What do the plots show?"):
        st.markdown(
            "**A (net photosynthesis rate)** is measured in µmol CO₂ per m² of leaf "
            "per second — higher means the vine is growing faster. Healthy grapevines "
            "typically range from 5 to 20.\n\n"
            "**Diurnal bell curve:** photosynthesis peaks mid-morning when both light "
            "and temperature are favourable, then drops in the afternoon heat.\n\n"
            "**Light-response curve:** A increases with PAR up to a point, then "
            "flattens (saturates) — this proves the vine cannot use all of the "
            "Negev's intense sunlight.\n\n"
            "**\"Physiologically plausible\"** means the model reproduces the patterns "
            "that plant biologists expect from real grapevines — it behaves like a "
            "real vine, not just a curve fit."
        )

    st.divider()

    st.markdown("## 4. Stage 2 — ML Prediction from Weather Data")

    _p_metrics_path = settings.OUTPUTS_DIR / "stage2_metrics.csv"
    _p_pred_img = settings.OUTPUTS_DIR / "stage2_predictions.png"
    _p_ts_path = settings.OUTPUTS_DIR / "ts_horizon_comparison.csv"

    if _p_metrics_path.exists():
        _p_metrics = load_metrics(str(_p_metrics_path))
        st.markdown("#### Cross-sectional model comparison")
        st.dataframe(_p_metrics, hide_index=True)

        if "R2" in _p_metrics.columns:
            _p_best = _p_metrics.loc[_p_metrics["R2"].idxmax()]
            st.markdown(
                f"**Best model:** {_p_best['model']} — "
                f"R² = {_p_best['R2']:.3f}, RMSE = {_p_best['RMSE']:.2f} µmol m⁻² s⁻¹. "
                f"Explains **{_p_best['R2']*100:.0f}%** of variance in A from weather data."
            )
    else:
        st.warning("Stage 2 metrics not found.")

    if _p_pred_img.exists():
        st.image(str(_p_pred_img), width='stretch',
                 caption="Left: Predicted vs approximate A (scatter). "
                         "Right: Time-series overlay showing temporal patterns.")

    if _p_ts_path.exists():
        _p_ts = load_metrics(str(_p_ts_path))
        st.markdown("#### Time-series forecasting (lagged features)")
        _p_ts_all = _p_ts[_p_ts["season"] == "all"] if "season" in _p_ts.columns else _p_ts
        _p_ts_ts = _p_ts_all[_p_ts_all["approach"] == "time_series"].copy()
        if not _p_ts_ts.empty:
            _p_ts_disp = _p_ts_ts[["horizon", "RMSE", "MAE", "R2"]].copy()
            for _c in ["RMSE", "MAE", "R2"]:
                _p_ts_disp[_c] = _p_ts_disp[_c].round(3)
            st.dataframe(_p_ts_disp, hide_index=True)
            _p_best_ts = _p_ts_ts.loc[_p_ts_ts["R2"].idxmax()]
            st.markdown(
                f"**Best horizon:** {_p_best_ts['horizon']} — "
                f"R² = {_p_best_ts['R2']:.3f}, RMSE = {_p_best_ts['RMSE']:.2f}. "
                "Adding recent A history dramatically improves short-term predictions."
            )

    with st.expander("Understanding the metrics: R², RMSE, cross-sectional vs time-series"):
        st.markdown(
            "**R² (R-squared):** the proportion of variance explained by the model. "
            "R² = 0.87 means the model explains 87% of the variation in A — close to "
            "1.0 is excellent, 0.0 means no better than guessing the average.\n\n"
            "**RMSE (Root Mean Squared Error):** the average prediction error in the "
            "same units as A (µmol/m²/s). Lower is better. It penalises large errors "
            "more than small ones.\n\n"
            "**Cross-sectional model:** predicts A from the weather at the *same* "
            "moment — no memory of what happened before.\n\n"
            "**Time-series model:** also uses recent past values (lags) — "
            "*\"what was A 15 minutes ago?\"* This helps because photosynthesis changes "
            "smoothly over time.\n\n"
            "**Why short horizons are better:** recent A values are very informative; "
            "predicting 15 minutes ahead is much easier than predicting a month ahead."
        )

    st.divider()

    st.markdown("## 5. ML Strategy — Four Prediction Layers")
    st.markdown(
        "Predicting photosynthesis is not a single-model problem. We stack four "
        "complementary approaches, each adding a capability the previous one lacks:"
    )

    _ml_cols = st.columns(4)
    with _ml_cols[0]:
        st.markdown(
            "### Layer 1\n"
            "**Cross-sectional ML**\n\n"
            "RF, GBR, XGBoost trained on IMS weather features at the *same* time step. "
            "No memory of the past — purely \"given today's weather, what is A right now?\" "
            "Best R² ≈ 0.80."
        )
    with _ml_cols[1]:
        st.markdown(
            "### Layer 2\n"
            "**Time-series forecasting**\n\n"
            "Adds lagged A and rolling weather windows (15 min – 3 h) as features. "
            "A separate model per horizon (15-min to 1-month). "
            "Best R² ≈ 0.87 at 15-min; degrades at longer horizons."
        )
    with _ml_cols[2]:
        st.markdown(
            "### Layer 3\n"
            "**Chronos-2 foundation model**\n\n"
            "Amazon's pre-trained 120M-parameter time-series model. Zero-shot "
            "day-ahead forecast (24 h / 96 steps) with probabilistic confidence "
            "bands — no task-specific training needed. Optional LoRA fine-tuning."
        )
    with _ml_cols[3]:
        st.markdown(
            "### Layer 4\n"
            "**LLM orchestration (Gemini)**\n\n"
            "Two roles: (a) *Data engineer* — LLM-generated anomaly thresholds and "
            "stress features; (b) *Routing agent* — classifies real-time conditions "
            "and picks FvCB or ML ensemble per 15-min slot, plus day-ahead advisory."
        )

    st.markdown(
        "Each layer feeds the next: cross-sectional models establish a baseline, "
        "time-series models exploit temporal continuity, Chronos-2 extends the "
        "horizon to 24 hours with uncertainty quantification, and Gemini ties "
        "everything together — cleaning the data, selecting the right model for "
        "each moment, and producing actionable day-ahead shading recommendations."
    )
    st.markdown(
        "Predictions alone aren't enough — we also need to understand exactly "
        "how panel shadows affect each part of the canopy."
    )

    with st.expander("Why four layers instead of one best model?"):
        st.markdown(
            "**No single model wins everywhere.** Cross-sectional ML is robust but "
            "blind to recent trends. Time-series models excel at short horizons but "
            "degrade beyond a few hours. Chronos-2 handles day-ahead with built-in "
            "uncertainty but needs a sanity check. The Gemini routing agent acts as "
            "an intelligent dispatcher:\n\n"
            "- **Cool morning, T < 30 °C →** route to Farquhar (mechanistic model "
            "is most accurate in the RuBP-limited regime)\n"
            "- **Hot afternoon, T > 30 °C →** route to ML ensemble (better at "
            "capturing stress-induced non-linearities)\n"
            "- **Day-ahead planning →** Chronos-2 probabilistic forecast, cross-checked "
            "against vine biology rules (no shade before 10:00, no shade in May, "
            "5% annual energy ceiling)\n\n"
            "**Foundation model (Chronos-2):** a large neural network pre-trained on "
            "millions of time series from many domains. It learns general patterns "
            "(trends, seasonality, noise) and can forecast new series *zero-shot* — "
            "without any vineyard-specific training.\n\n"
            "**LoRA fine-tuning:** Low-Rank Adaptation — a lightweight method to "
            "specialise the foundation model on our vineyard data using only ~500 "
            "training steps, without modifying the original weights.\n\n"
            "**LLM orchestration:** using a large language model (Gemini) not for "
            "chat, but as a reasoning engine that reads sensor statistics, applies "
            "domain rules, and outputs structured decisions (thresholds, routing "
            "choices, shading schedules)."
        )

    st.divider()

    st.markdown("## 6. Shadow Model & Shading Analysis")
    st.markdown(
        "A 3D ray-tracing shadow model computes where panel shadows fall on a "
        "VSP-trained canopy (1.2 m tall, 3 vertical zones). Combined with the "
        "Farquhar model, this shows how much photosynthesis the vine retains "
        "under panels. At midsummer noon the vine retains the vast majority of "
        "its photosynthesis under the panel — light saturation means halving PAR "
        "barely affects A, so the surplus can be harvested as electricity."
    )
    st.markdown(
        "This shadow model becomes the physics engine inside the tracker "
        "controller — it evaluates candidate tilt angles and their effect on "
        "each canopy zone in real time."
    )
    st.info(
        "See the **Shading Simulator** tab for the interactive 3D shadow viewer "
        "with date/hour controls, PAR and photosynthesis heatmaps, and zone-level analysis."
    )

    with st.expander("How the shadow model works"):
        st.markdown(
            "**VSP trellis (Vertical Shoot Positioning):** the standard vineyard "
            "training system where shoots grow upward in a flat plane, creating a wall "
            "of leaves roughly 1.2 m tall.\n\n"
            "**3 vertical zones:** the canopy is divided into bottom (trunk/cordons), "
            "middle (fruiting zone — where the grapes hang), and top (main leaf area). "
            "Each zone has different leaf density and economic importance.\n\n"
            "**Ray-tracing:** the model tracks the sun's position, calculates where "
            "the panel casts a shadow, and determines which parts of the canopy are "
            "shaded versus sunlit at each time step.\n\n"
            "**Why the vine barely notices the panel:** at midday, even the shaded "
            "parts receive enough scattered (diffuse) light plus direct light from "
            "unshaded portions to saturate photosynthesis."
        )

    st.divider()

    st.markdown("## 7. Tracker Control & Optimization")
    st.markdown(
        "**Default = full astronomical tracking** (maximum energy generation). "
        "Anti-tracking is a rare, minimum-dose intervention ONLY when the fruiting "
        "zone faces measurable heat/radiation risk. The user sets a hard energy "
        "sacrifice ceiling (e.g. 5%/year) — the system guarantees it is never exceeded."
    )

    _tc_cols = st.columns(4)
    with _tc_cols[0]:
        st.markdown(
            "### Budget Hierarchy\n"
            "User sets an annual ceiling (e.g. 5%). Distributed "
            "Year → Month → Week → Day → 15-min slot. "
            "July–Aug get ~85% of the budget. Unused slots roll forward."
        )
    with _tc_cols[1]:
        st.markdown(
            "### Intervention Gate\n"
            "Hard pass/fail filter. **No-shade windows:** before 10:00, May, "
            "T < 28 °C, CWSI < 0.3. Eligible only when ALL pass: "
            "T ≥ 30 °C, CWSI ≥ 0.4, GHI ≥ 500, FvCB confirms shading helps."
        )
    with _tc_cols[2]:
        st.markdown(
            "### Minimum Dose\n"
            "Scan offsets [3°, 5°, 8°, 10°, 15°, 20°] smallest-first. "
            "Select first that brings fruiting-zone PAR < 400 µmol while top "
            "canopy > 70% sunlit, within budget."
        )
    with _tc_cols[3]:
        st.markdown(
            "### Day-Ahead DP\n"
            "Discrete Dynamic Programming at sunrise: optimize 96-slot trajectory. "
            "Utility = energy value + crop value − movement cost, subject to "
            "daily budget. Phenological weighting (1.5× veraison)."
        )

    st.markdown(
        "**Typical day:** full tracking 05:00–11:00 → minimum-dose shading "
        "~3–8° from 11:00–15:30 → full tracking by 16:00. Over a season: "
        "~92% full tracking, ~8% shading, sacrifice ≤ 5%."
    )
    st.info(
        "This control system is the next implementation phase. The measurement, "
        "prediction, and shadow modules above are its foundation. "
        "Manual **LiCor gas-exchange measurements** (LI-6400/6800) will serve as "
        "ground truth for calibrating model parameters and fine-tuning the ML pipeline."
    )

    with st.expander("How does the day-ahead optimizer work?"):
        st.markdown(
            "**DP in plain English:** plan the best tilt angle for each 15-min slot, "
            "knowing that each choice affects how much budget remains for later slots.\n\n"
            "**Utility function:** balances electricity revenue vs crop protection, and "
            "penalises motor movement (each tilt change costs energy and wear).\n\n"
            "**Phenological weighting:** crop value varies by growth stage — 1.5× during "
            "veraison (berry ripening), 0.5× post-harvest — so the system shades more "
            "aggressively when fruit quality is most at stake.\n\n"
            "**Zone weighting:** top canopy 60%, fruiting zone 30%, trunk 10% — "
            "penalises shading productive upper leaves, which generate most of the "
            "vine's energy.\n\n"
            "**Real-time override:** the DP plan is a *schedule*, not a command. Live "
            "sensor readings override if the forecast diverges from reality.\n\n"
            "**Fallback:** if anything fails — sensor dropout, model error, comms loss — "
            "the tracker reverts to full astronomical tracking (zero sacrifice)."
        )

    st.markdown("## 8. Key Takeaways")
    st.markdown("""
- **Farquhar model** → reliable 15-min photosynthesis measurements from on-site sensors
- **Four ML layers** → day-ahead prediction with uncertainty (cross-sectional → time-series → Chronos-2 → Gemini routing)
- **Shadow model** → physics engine for evaluating tilt-angle effects on each canopy zone
- **Tracker control** → budget-constrained DP optimization; minimum-dose shading; ≤ 5% energy sacrifice guaranteed
- **LiCor calibration** → manual gas-exchange ground truth triggers automated model retraining and versioned deployment
- **Full story** → measure → predict → simulate → control → calibrate — each module feeds the next
    """)
    st.markdown("Learn more at [solarwine.ai](https://www.solarwine.ai/)")