README.md

---
title: Tokyo Weather Forecast Lab
sdk: gradio
app_file: app.py
pinned: false
---

# WeatherPred

A Gradio app for comparing Tokyo five-day weather forecasts from Open-Meteo with a local ONNX model forecast.

## Repository Layout

```text
app.py                    # HuggingFace Spaces entrypoint
weatherpred/              # Application package
  config.py               # Paths, constants, Tokyo coordinates
  data.py                 # Open-Meteo fetch and CSV/JSON cache
  modeling.py             # ONNX inference and forecast comparison
  agent.py                # Gemini-backed agent orchestration and fallback logic
  prompts.py              # LLM routing and response prompts
  tools.py                # Deterministic forecast/trend/seasonality/model tools
  dashboard.py            # Gradio UI
  zerogpu.py              # HuggingFace ZeroGPU compatibility
models/mock_model/        # ONNX model artifacts
scripts/                  # Data/model utility scripts
requirements.txt          # Runtime dependencies
requirements-train.txt    # Optional model training dependencies
```

## Local Run

```bash
pip install -r requirements.txt
python scripts/fetch_historical_weather.py
python app.py
```

## HuggingFace ZeroGPU

Free HuggingFace Gradio Spaces may run on ZeroGPU only. A tiny hidden compatibility probe is decorated with `@spaces.GPU(duration=10)` so the Space satisfies the ZeroGPU startup check, while the real weather dashboard refresh remains CPU-based. The local fallback keeps the app runnable outside HuggingFace.

## Agent Capabilities

The chat agent uses Gemini when `GEMINI_API_KEY` is available, with a deterministic fallback parser when it is not. It can route user requests to typed Python tools for:

- next-N-day forecasts, up to 16 days
- historical trends over the cached weather history
- seasonal/monthly cyclic patterns
- model-vs-Open-Meteo comparison
- model and data-source explanation

The LLM does not invent forecasts directly; it selects tools and explains their computed results.

## Optional Gemini Briefing

Set `GEMINI_API_KEY` as a HuggingFace Space secret. If it is absent, the app uses deterministic fallback summaries and routing.

## Optional Model Export

```bash
pip install -r requirements-train.txt
python scripts/fetch_historical_weather.py
python scripts/train_export_onnx.py
```

The training helper exports the ONNX model to `models/mock_model/model.onnx`.