README.md

metadata

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)