Upload folder using huggingface_hub

README.md

@@ -1,13 +1,57 @@
 ---
-title: Skyread
-emoji: 👀
-colorFrom: pink
-colorTo: gray
+title: SkyRead 探空白話判讀器
+emoji: 🌤️
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
 sdk_version: 6.17.3
-python_version: '3.13'
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🌤️ SkyRead — 探空白話判讀器
+
+> 把艱深的 Skew-T 探空圖，翻成**同行看的指數**與**阿嬤看的帶傘建議**。
+
+![SkyRead Skew-T](docs/screenshot.png)
+
+## Why
+
+每天全球施放上千顆探空氣球，但讀懂一張 Skew-T 需要多年訓練。
+SkyRead 把它變成兩張卡片：給氣象同行的指數摘要，和給長輩的
+「要不要帶傘、能不能曬棉被」。
+
+## The honest small-model architecture
+
+| 層 | 負責 | 由誰做 |
+|----|------|--------|
+| 數值 | CAPE/CIN、LCL/LFC/EL、K、LI、TT、PWAT | **MetPy**（確定性計算，AI 不碰數字） |
+| 同行版卡片 | 指數摘要——專業讀者要的就是精確數字 | 規則式模板（確定性） |
+| 生活版卡片 | 把建議講成阿嬤聽得懂的人話 | **Qwen3-0.6B**（本機推論，只改寫草稿） |
+| 保險 | 模型失敗或輸出不合格時 | 規則式 fallback（同時是 LLM 的草稿） |
+
+小模型算不準 CAPE——所以我們不讓它算。它只做小模型真正擅長、
+也是唯一需要它的事：把一句數值正確的天氣提醒，改寫成自然的人話。
+改寫結果還要通過驗證（繁中、禁簡體字、長度、不得回音指令），
+不合格會自動重試，重試仍不過就用草稿原文。
+
+## Data sources
+
+- 🛰️ 即時探空：石垣島 47918 / 香港 45004 等鄰近測站（University of Wyoming
+  archive；台灣本島測站未開放於該資料庫，故取距離最近者）
+- 📚 經典個案：MetPy 內建（含 1999-05-04 Oklahoma tornado outbreak）
+- 📄 上傳 CSV：`pressure,temperature,dewpoint,direction,speed`（hPa/°C/deg/kt），
+  範例檔在 `examples/sample_sounding.csv`
+
+## Run locally
+
+```bash
+uv sync
+uv run python app.py            # Gradio UI at http://127.0.0.1:7860
+uv run python -m skyread.spike  # CLI end-to-end demo
+uv run pytest tests/ -v
+```
+
+## Built for
+
+Hugging Face **Build Small Hackathon 2026** — Backyard AI track.

app.py

@@ -0,0 +1,137 @@
+"""SkyRead — Gradio app: sounding -> Skew-T plot + dual-layer interpretation.
+
+Run locally:
+    uv run python app.py
+"""
+
+from __future__ import annotations
+
+import threading
+
+import gradio as gr
+from matplotlib.figure import Figure
+
+from skyread.indices import compute_indices
+from skyread.interpret import interpret_rule_based
+from skyread.live import STATIONS, latest_sounding
+from skyread.llm import MODEL_ID, interpret_llm, warm_up
+from skyread.plot import make_skewt
+from skyread.sounding import Sounding, load_csv, load_sample
+
+# Curated, demo-safe example soundings bundled with MetPy (zero network).
+EXAMPLES: dict[str, str] = {
+    "1999-05-04 Oklahoma (強對流 / tornado outbreak)": "may4_sounding.txt",
+    "2010-01-20 winter case": "jan20_sounding.txt",
+    "2011-11-11 case": "nov11_sounding.txt",
+}
+
+SOURCE_LIVE = "🛰️ 即時探空（鄰近測站）"
+SOURCE_EXAMPLE = "📚 經典個案"
+SOURCE_UPLOAD = "📄 上傳 CSV"
+
+_MODEL_NAME = MODEL_ID.split("/")[-1]
+_BADGE_LLM = (
+    f"🧠 生活版由 **{_MODEL_NAME}**（本機推論）改寫；"
+    "同行版與所有數值由 MetPy 確定性計算。"
+)
+_BADGE_RULE = "📐 規則式判讀（fallback）；所有數值由 MetPy 確定性計算。"
+
+
+def _load_sounding(
+    source: str, station_label: str, example_label: str, uploaded: str | None
+) -> Sounding:
+    """Resolve the selected data source into a parsed Sounding."""
+    if source == SOURCE_LIVE:
+        return latest_sounding(STATIONS[station_label])
+    if source == SOURCE_UPLOAD:
+        if not uploaded:
+            raise ValueError("請先上傳 CSV 檔")
+        return load_csv(uploaded, name="uploaded")
+    return load_sample(EXAMPLES[example_label])
+
+
+def analyze(
+    source: str,
+    station_label: str,
+    example_label: str,
+    uploaded: str | None,
+    use_llm: bool,
+) -> tuple[Figure | None, str, str, str]:
+    """Run the full chain and return (figure, pro_md, grandma_md, badge_md)."""
+    # The whole chain is guarded: a CSV can parse fine yet still blow up in
+    # index computation or plotting (empty profile, increasing pressure, …).
+    try:
+        snd = _load_sounding(source, station_label, example_label, uploaded)
+        indices = compute_indices(snd)
+        if use_llm:
+            cards, engine = interpret_llm(indices, snd.name)
+        else:
+            cards, engine = interpret_rule_based(indices, snd.name), "rule-based"
+        badge = _BADGE_LLM if engine == "llm" else _BADGE_RULE
+        return make_skewt(snd), cards["pro"], cards["grandma"], badge
+    except Exception as exc:  # surface as a friendly message, never a crash
+        return None, f"⚠️ 讀取失敗：{exc}（可改選經典個案）", "", ""
+
+
+def _analyze_fast(
+    source: str, station_label: str, example_label: str, uploaded: str | None
+) -> tuple[Figure | None, str, str, str]:
+    """Instant first paint on page load: skip the LLM, show rule-based cards."""
+    return analyze(source, station_label, example_label, uploaded, use_llm=False)
+
+
+def build_ui() -> gr.Blocks:
+    """Construct the Gradio interface."""
+    with gr.Blocks(title="SkyRead 探空白話判讀器") as demo:
+        gr.Markdown(
+            "# 🌤️ SkyRead — 探空白話判讀器\n"
+            "把艱深的 Skew-T 探空圖，翻成**同行看的指數**與**阿嬤看的帶傘建議**。\n"
+            "_數值由 MetPy 精確計算，AI 只負責把數字講成人話。_"
+        )
+        with gr.Row():
+            with gr.Column(scale=1):
+                source = gr.Radio(
+                    choices=[SOURCE_LIVE, SOURCE_EXAMPLE, SOURCE_UPLOAD],
+                    value=SOURCE_EXAMPLE,
+                    label="資料來源",
+                )
+                station = gr.Dropdown(
+                    choices=list(STATIONS),
+                    value=list(STATIONS)[0],
+                    label="即時測站（台灣探空未開放於 Wyoming 資料庫，取最近測站）",
+                )
+                example = gr.Dropdown(
+                    choices=list(EXAMPLES), value=list(EXAMPLES)[0], label="範例探空"
+                )
+                upload = gr.File(
+                    label="探空 CSV (pressure,temperature,dewpoint,direction,speed)",
+                    file_types=[".csv"],
+                    type="filepath",
+                )
+                use_llm = gr.Checkbox(
+                    value=True,
+                    label=f"🧠 用 {_MODEL_NAME} 潤飾生活版（慢幾秒，但更像人話）",
+                )
+                btn = gr.Button("判讀 ☁️", variant="primary")
+            with gr.Column(scale=1):
+                plot = gr.Plot(label="Skew-T / Log-P")
+        pro = gr.Markdown()
+        grandma = gr.Markdown()
+        badge = gr.Markdown()
+
+        btn.click(
+            analyze,
+            inputs=[source, station, example, upload, use_llm],
+            outputs=[plot, pro, grandma, badge],
+        )
+        demo.load(
+            _analyze_fast,
+            inputs=[source, station, example, upload],
+            outputs=[plot, pro, grandma, badge],
+        )
+    return demo
+
+
+if __name__ == "__main__":
+    threading.Thread(target=warm_up, daemon=True).start()
+    build_ui().launch(theme=gr.themes.Soft())

examples/sample_sounding.csv

@@ -0,0 +1,10 @@
+pressure,temperature,dewpoint,direction,speed
+1000,30.0,24.0,180,10
+925,24.0,20.0,190,15
+850,18.0,14.0,200,20
+700,8.0,2.0,220,25
+500,-10.0,-20.0,240,35
+400,-22.0,-35.0,250,45
+300,-38.0,-55.0,260,55
+250,-48.0,-65.0,260,60
+200,-55.0,-70.0,270,65

pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "skyread"
+version = "0.1.0"
+description = "Turn Skew-T soundings into plain-language weather advice — MetPy computes, a 0.5B LLM narrates"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "gradio>=6.17.3",
+    "matplotlib>=3.10.9",
+    "metpy>=1.7.1",
+    "pandas>=3.0.3",
+    "siphon>=0.10.0",
+    "torch>=2.11.0",
+    # >=4.51 for the qwen3 architecture. NOTE: this drops MiniCPM3 support
+    # (its remote code needs 4.46.x) — see PROGRESS notes, 2026-06-11.
+    "transformers>=4.51",
+]
+
+# Linux boxes here run driver CUDA 12.8, but PyPI torch ships cu130-only
+# builds; pull the cu128 wheels instead (macOS keeps PyPI).
+# NOTE: when re-exporting requirements.txt for the HF Space, keep torch
+# from PyPI (strip the download.pytorch.org lines).
+[tool.uv.sources]
+torch = [{ index = "pytorch-cu128", marker = "sys_platform == 'linux'" }]
+
+[[tool.uv.index]]
+name = "pytorch-cu128"
+url = "https://download.pytorch.org/whl/cu128"
+explicit = true
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "ruff>=0.15.16",
+]

requirements.txt

@@ -0,0 +1,315 @@
+# This file was autogenerated by uv via the following command:
+#    uv export --format requirements-txt --no-hashes --no-dev --no-emit-project --no-sources -o requirements.txt
+annotated-doc==0.0.4
+    # via
+    #   fastapi
+    #   typer
+annotated-types==0.7.0
+    # via pydantic
+anyio==4.13.0
+    # via
+    #   gradio
+    #   httpx
+    #   starlette
+audioop-lts==0.2.2 ; python_full_version >= '3.13'
+    # via gradio
+beautifulsoup4==4.15.0
+    # via siphon
+brotli==1.2.0
+    # via gradio
+certifi==2026.5.20
+    # via
+    #   httpcore
+    #   httpx
+    #   pyproj
+    #   requests
+charset-normalizer==3.4.7
+    # via requests
+click==8.4.1
+    # via
+    #   huggingface-hub
+    #   typer
+    #   uvicorn
+colorama==0.4.6 ; sys_platform == 'win32'
+    # via
+    #   click
+    #   tqdm
+contourpy==1.3.3
+    # via matplotlib
+cuda-bindings==13.3.1 ; sys_platform == 'linux'
+    # via torch
+cuda-pathfinder==1.5.5 ; sys_platform == 'linux'
+    # via cuda-bindings
+cuda-toolkit==13.0.2 ; sys_platform == 'linux'
+    # via torch
+cycler==0.12.1
+    # via matplotlib
+fastapi==0.136.3
+    # via gradio
+filelock==3.29.1
+    # via
+    #   huggingface-hub
+    #   torch
+flexcache==0.3
+    # via pint
+flexparser==0.4
+    # via pint
+fonttools==4.63.0
+    # via matplotlib
+fsspec==2026.4.0
+    # via
+    #   gradio-client
+    #   huggingface-hub
+    #   torch
+gradio==6.17.3
+    # via skyread
+gradio-client==2.5.0
+    # via
+    #   gradio
+    #   hf-gradio
+groovy==0.1.2
+    # via gradio
+h11==0.16.0
+    # via
+    #   httpcore
+    #   uvicorn
+hf-gradio==0.4.1
+    # via gradio
+hf-xet==1.5.1 ; platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'
+    # via huggingface-hub
+httpcore==1.0.9
+    # via httpx
+httpx==0.28.1
+    # via
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   safehttpx
+huggingface-hub==1.19.0
+    # via
+    #   gradio
+    #   gradio-client
+    #   tokenizers
+    #   transformers
+idna==3.18
+    # via
+    #   anyio
+    #   httpx
+    #   requests
+jinja2==3.1.6
+    # via
+    #   gradio
+    #   torch
+kiwisolver==1.5.0
+    # via matplotlib
+markdown-it-py==4.2.0
+    # via rich
+markupsafe==3.0.3
+    # via
+    #   gradio
+    #   jinja2
+matplotlib==3.10.9
+    # via
+    #   metpy
+    #   skyread
+mdurl==0.1.2
+    # via markdown-it-py
+metpy==1.7.1
+    # via skyread
+mpmath==1.3.0
+    # via sympy
+networkx==3.6.1
+    # via torch
+numpy==2.4.6
+    # via
+    #   contourpy
+    #   gradio
+    #   matplotlib
+    #   metpy
+    #   pandas
+    #   scipy
+    #   siphon
+    #   transformers
+    #   xarray
+nvidia-cublas==13.1.1.3 ; sys_platform == 'linux'
+    # via
+    #   nvidia-cudnn-cu13
+    #   nvidia-cusolver
+    #   torch
+nvidia-cuda-cupti==13.0.85 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cuda-nvrtc==13.0.88 ; sys_platform == 'linux'
+    # via
+    #   cuda-toolkit
+    #   nvidia-cublas
+nvidia-cuda-runtime==13.0.96 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cudnn-cu13==9.20.0.48 ; sys_platform == 'linux'
+    # via torch
+nvidia-cufft==12.0.0.61 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cufile==1.15.1.6 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-curand==10.4.0.35 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cusolver==12.0.4.66 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cusparse==12.6.3.3 ; sys_platform == 'linux'
+    # via
+    #   cuda-toolkit
+    #   nvidia-cusolver
+nvidia-cusparselt-cu13==0.8.1 ; sys_platform == 'linux'
+    # via torch
+nvidia-nccl-cu13==2.29.7 ; sys_platform == 'linux'
+    # via torch
+nvidia-nvjitlink==13.0.88 ; sys_platform == 'linux'
+    # via
+    #   cuda-toolkit
+    #   nvidia-cufft
+    #   nvidia-cusolver
+    #   nvidia-cusparse
+nvidia-nvshmem-cu13==3.4.5 ; sys_platform == 'linux'
+    # via torch
+nvidia-nvtx==13.0.85 ; sys_platform == 'linux'
+    # via cuda-toolkit
+orjson==3.11.9
+    # via gradio
+packaging==26.2
+    # via
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   matplotlib
+    #   pooch
+    #   transformers
+    #   xarray
+pandas==3.0.3
+    # via
+    #   gradio
+    #   metpy
+    #   siphon
+    #   skyread
+    #   xarray
+pillow==12.2.0
+    # via
+    #   gradio
+    #   matplotlib
+pint==0.25.3
+    # via metpy
+platformdirs==4.10.0
+    # via
+    #   pint
+    #   pooch
+pooch==1.9.0
+    # via metpy
+protobuf==7.35.0
+    # via siphon
+pydantic==2.13.4
+    # via
+    #   fastapi
+    #   gradio
+pydantic-core==2.46.4
+    # via pydantic
+pydub==0.25.1
+    # via gradio
+pygments==2.20.0
+    # via rich
+pyparsing==3.3.2
+    # via matplotlib
+pyproj==3.7.2
+    # via metpy
+python-dateutil==2.9.0.post0
+    # via
+    #   matplotlib
+    #   pandas
+python-multipart==0.0.32
+    # via gradio
+pytz==2026.2
+    # via gradio
+pyyaml==6.0.3
+    # via
+    #   gradio
+    #   huggingface-hub
+    #   transformers
+regex==2026.5.9
+    # via transformers
+requests==2.34.2
+    # via
+    #   pooch
+    #   siphon
+rich==15.0.0
+    # via typer
+safehttpx==0.1.7
+    # via gradio
+safetensors==0.8.0
+    # via transformers
+scipy==1.17.1
+    # via metpy
+semantic-version==2.10.0
+    # via gradio
+setuptools==81.0.0
+    # via torch
+shellingham==1.5.4
+    # via typer
+siphon==0.10.0
+    # via skyread
+six==1.17.0
+    # via python-dateutil
+soupsieve==2.8.4
+    # via beautifulsoup4
+starlette==1.2.1
+    # via
+    #   fastapi
+    #   gradio
+sympy==1.14.0
+    # via torch
+tokenizers==0.22.2
+    # via transformers
+tomlkit==0.14.0
+    # via gradio
+torch==2.12.0
+    # via skyread
+tqdm==4.68.2
+    # via
+    #   huggingface-hub
+    #   transformers
+traitlets==5.15.1
+    # via metpy
+transformers==5.11.0
+    # via skyread
+triton==3.7.0 ; sys_platform == 'linux'
+    # via torch
+typer==0.25.1
+    # via
+    #   gradio
+    #   hf-gradio
+    #   huggingface-hub
+    #   transformers
+typing-extensions==4.15.0
+    # via
+    #   anyio
+    #   beautifulsoup4
+    #   fastapi
+    #   flexcache
+    #   flexparser
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   pint
+    #   pydantic
+    #   pydantic-core
+    #   starlette
+    #   torch
+    #   typing-inspection
+typing-inspection==0.4.2
+    # via
+    #   fastapi
+    #   pydantic
+tzdata==2026.2 ; sys_platform == 'emscripten' or sys_platform == 'win32'
+    # via pandas
+urllib3==2.7.0
+    # via requests
+uvicorn==0.49.0
+    # via gradio
+xarray==2026.4.0
+    # via metpy

skyread/indices.py

@@ -0,0 +1,56 @@
+"""Deterministic stability-index computation via MetPy.
+
+This is the *non-AI* core of SkyRead: every number here is computed exactly by
+MetPy, not estimated by a model. The LLM layer (:mod:`skyread.interpret`) only
+turns these numbers into plain language.
+"""
+
+from __future__ import annotations
+
+import metpy.calc as mpcalc
+
+from skyread.sounding import Sounding
+
+
+def compute_indices(snd: Sounding) -> dict[str, float]:
+    """Compute the standard convective stability indices for a sounding.
+
+    Args:
+        snd: A parsed sounding.
+
+    Returns:
+        Mapping of index name to a plain float (SI-stripped, rounded), e.g.
+        ``cape_jkg``, ``cin_jkg``, ``lcl_hpa``, ``lfc_hpa``, ``el_hpa``,
+        ``k_index``, ``lifted_index``, ``total_totals``, ``pwat_mm``. Values
+        that cannot be computed (e.g. no LFC) are ``float('nan')``.
+    """
+    p, t, td = snd.pressure, snd.temperature, snd.dewpoint
+
+    parcel = mpcalc.parcel_profile(p, t[0], td[0]).to("degC")
+    cape, cin = mpcalc.surface_based_cape_cin(p, t, td)
+
+    lcl_p, _ = mpcalc.lcl(p[0], t[0], td[0])
+    lfc_p, _ = mpcalc.lfc(p, t, td)
+    el_p, _ = mpcalc.el(p, t, td)
+
+    def _hpa(q) -> float:
+        return round(float(q.to("hPa").magnitude), 1)
+
+    def _scalar(q, unit: str) -> float:
+        return round(float(q.to(unit).magnitude), 1)
+
+    def _index(q) -> float:
+        """Index values (K, LI, TT) are reported in their native degree unit."""
+        return round(float(q.magnitude), 1)
+
+    return {
+        "cape_jkg": _scalar(cape, "joule/kilogram"),
+        "cin_jkg": _scalar(cin, "joule/kilogram"),
+        "lcl_hpa": _hpa(lcl_p),
+        "lfc_hpa": _hpa(lfc_p),
+        "el_hpa": _hpa(el_p),
+        "k_index": _index(mpcalc.k_index(p, t, td)),
+        "lifted_index": _index(mpcalc.lifted_index(p, t, parcel)[0]),
+        "total_totals": _index(mpcalc.total_totals_index(p, t, td)),
+        "pwat_mm": _scalar(mpcalc.precipitable_water(p, td), "mm"),
+    }

skyread/interpret.py

@@ -0,0 +1,130 @@
+"""Turn computed indices into plain-language, dual-layer interpretation.
+
+Architecture note — this is where (and the *only* place) AI is load-bearing:
+
+* The numbers come from MetPy (exact, deterministic).
+* :func:`build_llm_prompt` is what we hand to a small LLM (e.g. Qwen3-0.6B)
+  to produce natural, two-audience interpretation.
+* :func:`interpret_rule_based` is a deterministic stand-in that runs today with
+  no model download. It proves the data->language shape end-to-end and doubles
+  as a few-shot example / safe fallback for the LLM.
+
+Thresholds follow the standard convective-parameter references (K-index, Lifted
+Index, Total Totals, CAPE/CIN).
+"""
+
+from __future__ import annotations
+
+import math
+
+# (lower_bound_inclusive, label, pro_phrase, grandma_phrase)
+_CAPE_BANDS = (
+    (4000, "extreme", "極端不穩定", "空氣非常不穩定，會有劇烈雷雨"),
+    (2500, "strong", "強烈不穩定", "很可能有強雷雨"),
+    (1000, "moderate", "中等不穩定", "下午容易有雷陣雨"),
+    (1, "marginal", "弱不穩定", "可能有零星短暫雷雨"),
+    (-math.inf, "stable", "穩定", "天氣大致穩定，不太會有雷雨"),
+)
+
+
+def _cape_band(cape_jkg: float) -> tuple[str, str, str]:
+    """Return (label, pro_phrase, grandma_phrase) for a CAPE value."""
+    value = 0.0 if math.isnan(cape_jkg) else cape_jkg
+    for lower, label, pro, grandma in _CAPE_BANDS:
+        if value >= lower:
+            return label, pro, grandma
+    return "stable", "穩定", "天氣大致穩定"
+
+
+def assess(indices: dict[str, float]) -> dict[str, str]:
+    """Derive a qualitative severity assessment from raw indices.
+
+    Args:
+        indices: Output of :func:`skyread.indices.compute_indices`.
+
+    Returns:
+        Mapping with ``label``, ``pro_phrase``, ``grandma_phrase`` and a
+        ``cap_note`` describing the convective inhibition (CIN) barrier.
+    """
+    label, pro, grandma = _cape_band(indices["cape_jkg"])
+
+    cin = indices["cin_jkg"]
+    if label == "stable":
+        # With no CAPE there is nothing for the cap to hold back; talking
+        # about "convection starting easily" here reads as a contradiction.
+        cap_note = "無明顯對流潛勢"
+    elif math.isnan(cin) or cin >= -25:
+        cap_note = "幾乎沒有對流抑制，對流容易啟動"
+    elif cin >= -100:
+        cap_note = "有中等的對流抑制（蓋子），需要日照加熱才會爆發"
+    else:
+        cap_note = "對流抑制很強，除非有強迫抬升，否則不易發展"
+
+    return {
+        "label": label,
+        "pro_phrase": pro,
+        "grandma_phrase": grandma,
+        "cap_note": cap_note,
+    }
+
+
+def build_grandma_prompt(indices: dict[str, float], name: str) -> str:
+    """Build the rewrite prompt handed to a small LLM for the grandma card.
+
+    The pro card is pure numbers and stays rule-based; only the layperson
+    sentence benefits from a natural-language touch. The rule-based grandma
+    line is embedded as a factually-correct draft, so the model only rewrites
+    tone — a task small models handle far more reliably than free generation.
+
+    Args:
+        indices: Output of :func:`skyread.indices.compute_indices`.
+        name: Label of the sounding (station / case name).
+
+    Returns:
+        A ready-to-send prompt string requesting a single rewritten sentence.
+    """
+    draft = interpret_rule_based(indices, name)["grandma"].removeprefix("【生活版】")
+    return (
+        "把這句天氣提醒改寫成更口語、更親切的說法"
+        "（講給長輩聽，一到兩句）：\n"
+        f"「{draft}」\n"
+        "保留原本的結論與建議，不要新增資訊。只輸出改寫後的句子。"
+        "全程使用臺灣慣用的繁體中文，絕對不可出現任何簡體字。"
+    )
+
+
+def interpret_rule_based(indices: dict[str, float], name: str) -> dict[str, str]:
+    """Produce dual-layer cards deterministically (no model required).
+
+    Args:
+        indices: Output of :func:`skyread.indices.compute_indices`.
+        name: Label of the sounding.
+
+    Returns:
+        Mapping with ``pro`` and ``grandma`` card text.
+    """
+    a = assess(indices)
+
+    def _lvl(key: str) -> str:
+        value = indices[key]
+        return "資料未及" if math.isnan(value) else f"{value:.0f} hPa"
+
+    pro = (
+        f"【同行版 · {name}】"
+        f"CAPE {indices['cape_jkg']:.0f} J/kg、"
+        f"CIN {indices['cin_jkg']:.0f} J/kg、"
+        f"LI {indices['lifted_index']:.0f}、"
+        f"K {indices['k_index']:.0f}、"
+        f"TT {indices['total_totals']:.0f}。"
+        f"大氣呈{a['pro_phrase']}，{a['cap_note']}。"
+        f"LFC≈{_lvl('lfc_hpa')}、EL≈{_lvl('el_hpa')}，"
+        f"可降水量 {indices['pwat_mm']:.0f} mm。"
+    )
+    grandma = f"【生活版】{a['grandma_phrase']}。"
+    if a["label"] in ("moderate", "strong", "extreme"):
+        grandma += "出門記得帶傘，棉被先別曬，午後盡量避免在空曠處。☔"
+    elif a["label"] == "marginal":
+        grandma += "出門帶把傘以防萬一，棉被早點曬、早點收。🌦️"
+    else:
+        grandma += "今天適合外出，棉被可以放心曬。☀️"
+    return {"pro": pro, "grandma": grandma}

skyread/live.py

@@ -0,0 +1,58 @@
+"""Fetch the latest real sounding from the University of Wyoming archive.
+
+Network access happens only here. Any failure should be caught by the caller
+(the app falls back to bundled examples), so a dead upstream never kills a demo.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from siphon.simplewebservice.wyoming import WyomingUpperAir
+
+from skyread.sounding import Sounding, from_wyoming_dataframe
+
+# Taiwan's own stations (Banqiao 46692, Pingtung 46810) are not published to
+# the Wyoming archive, so we offer the nearest reliably-available stations.
+STATIONS: dict[str, str] = {
+    "石垣島 47918（離台灣最近，~270km）": "47918",
+    "香港京士柏 45004": "45004",
+    "奄美名瀨 47909": "47909",
+    "日本館野 47646": "47646",
+}
+DEFAULT_STATION = "47918"
+
+_COLUMNS = ["pressure", "height", "temperature", "dewpoint", "direction", "speed"]
+
+
+def _latest_synoptic(now: datetime) -> datetime:
+    """Round ``now`` down to the most recent 00Z/12Z synoptic hour."""
+    base = now.replace(minute=0, second=0, microsecond=0)
+    return base.replace(hour=12) if base.hour >= 12 else base.replace(hour=0)
+
+
+def latest_sounding(station: str = DEFAULT_STATION, max_lookback: int = 4) -> Sounding:
+    """Fetch the most recent sounding, stepping back 12 h per attempt.
+
+    Args:
+        station: WMO station identifier.
+        max_lookback: How many 12-hourly synoptic times to try.
+
+    Returns:
+        The parsed :class:`Sounding`, named ``"<station> <time>Z"``.
+
+    Raises:
+        RuntimeError: If no sounding exists within the lookback window.
+    """
+    candidate = _latest_synoptic(datetime.now(timezone.utc))
+    for _ in range(max_lookback):
+        try:
+            df = WyomingUpperAir.request_data(candidate.replace(tzinfo=None), station)
+        except ValueError:  # Wyoming returns this when the hour has no data yet
+            candidate -= timedelta(hours=12)
+            continue
+        name = f"{station} {candidate:%Y-%m-%d %H}Z"
+        return from_wyoming_dataframe(df[_COLUMNS], name=name)
+    raise RuntimeError(
+        f"No sounding for station {station} in the last {max_lookback * 12} hours"
+    )

skyread/llm.py

@@ -0,0 +1,159 @@
+"""Small-LLM rewriting of the grandma card, with deterministic fallback.
+
+Model layering (the hackathon's "honest small-model fit" story):
+
+* MetPy computes every number exactly (:mod:`skyread.indices`).
+* The pro card is pure numbers, so it stays rule-based — exact by design.
+* A small LLM only *rewrites* the layperson sentence from a factually-correct
+  draft, the one place natural language genuinely matters.
+* Any failure (load, generation, malformed output) silently falls back to
+  the rule-based cards, so the app never breaks on stage.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import threading
+from functools import lru_cache
+
+from skyread.interpret import build_grandma_prompt, interpret_rule_based
+
+logger = logging.getLogger(__name__)
+
+# Qwen3-0.6B: validated 100% Traditional-Chinese-clean on the GPU box
+# (MiniCPM3-4B kept slipping into Simplified on unstable-weather wording and
+# needs the old transformers 4.46 pin — see PROGRESS notes, 2026-06-11).
+MODEL_ID = os.environ.get("SKYREAD_MODEL_ID", "Qwen/Qwen3-0.6B")
+
+_MAX_REWRITE_CHARS = 180
+_MAX_ATTEMPTS = 3
+
+# High-frequency simplified-only characters: one hit means the model slipped
+# out of Traditional Chinese, so the rewrite is rejected. Shared forms that
+# are also standard in Taiwan (e.g. 后 in 皇后, 台, 干, 呆) are deliberately
+# excluded only when ambiguity is likely; the gate is biased toward rejecting,
+# since the fallback is graceful.
+_SIMPLIFIED_CHARS = frozenset(
+    "记伞来这为时说对让们个无气电视见车东转动书长门点云飞应过头实发现别样"
+    "认师问题难岁热闹风阴湿预报员变坏轻紧稳鲜盖旷阵处带备凉润闷强从众传写"
+    "决刚务医华单压历双叶号听响围国图块坚执扩扫护担拥挂损换据断显晓暂术机"
+    "杂权条极标树桥梦检楼归录忆怀态总惊惯愿凭"
+    "会还没几开关边儿学间阳雾闪温适当满离远进节随虽谢请"
+)
+
+
+def _pick_device() -> str:  # pragma: no cover - hardware dependent
+    """Best available device: CUDA, then Apple MPS, then CPU."""
+    import torch
+
+    if torch.cuda.is_available():
+        return "cuda"
+    if torch.backends.mps.is_available():
+        return "mps"
+    return "cpu"
+
+
+_LOAD_LOCK = threading.Lock()
+
+
+@lru_cache(maxsize=1)
+def _load_model_once():  # pragma: no cover - exercised manually / on the Space
+    """Load tokenizer and model (call via :func:`_load_model`)."""
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
+    model = AutoModelForCausalLM.from_pretrained(MODEL_ID, dtype="auto")
+    model.to(_pick_device())
+    model.eval()
+    return tokenizer, model
+
+
+def _load_model():  # pragma: no cover - thin thread-safety wrapper
+    """Thread-safe single load: the warm-up thread may race the first request.
+
+    ``lru_cache`` alone does not serialise concurrent first calls — two
+    threads can both miss the cache and load the model twice.
+    """
+    with _LOAD_LOCK:
+        return _load_model_once()
+
+
+def _generate(prompt: str) -> str:  # pragma: no cover - needs model weights
+    """Run one chat-formatted sampled generation and return the new text only.
+
+    Sampling (not greedy) on purpose: a rejected output would otherwise be
+    deterministic, making the retry loop in :func:`interpret_llm` useless.
+    """
+    import torch
+
+    tokenizer, model = _load_model()
+    encoded = tokenizer.apply_chat_template(
+        [{"role": "user", "content": prompt}],
+        add_generation_prompt=True,
+        enable_thinking=False,  # Qwen3: skip <think> blocks; no-op elsewhere
+        return_tensors="pt",
+        return_dict=True,
+    ).to(model.device)
+    with torch.no_grad():
+        output = model.generate(
+            **encoded,
+            max_new_tokens=96,
+            do_sample=True,
+            temperature=0.6,
+            top_p=0.9,
+        )
+    new_tokens = output[0][encoded["input_ids"].shape[1] :]
+    return tokenizer.decode(new_tokens, skip_special_tokens=True)
+
+
+def _clean_rewrite(text: str) -> str | None:
+    """Validate and normalise a rewrite; ``None`` if it is not usable."""
+    line = text.strip().strip("「」\"' \n")
+    if not line or len(line) > _MAX_REWRITE_CHARS:
+        return None
+    if any(marker in line for marker in ("改寫", "原句", "輸出")):
+        return None  # instruction echo, not a rewrite
+    if not re.search(r"[一-鿿]", line):
+        return None
+    if any(char in _SIMPLIFIED_CHARS for char in line):
+        return None  # slipped into Simplified Chinese
+    return line
+
+
+def interpret_llm(indices: dict[str, float], name: str) -> tuple[dict[str, str], str]:
+    """Interpret indices, rewriting the grandma card with a small LLM.
+
+    Args:
+        indices: Output of :func:`skyread.indices.compute_indices`.
+        name: Label of the sounding.
+
+    Returns:
+        ``(cards, engine)`` where ``engine`` is ``"llm"`` or ``"rule-based"``.
+    """
+    cards = interpret_rule_based(indices, name)
+    prompt = build_grandma_prompt(indices, name)
+    try:
+        for attempt in range(_MAX_ATTEMPTS):
+            raw = _generate(prompt)
+            rewritten = _clean_rewrite(raw)
+            if rewritten is not None:
+                return {**cards, "grandma": "【生活版】" + rewritten}, "llm"
+            logger.warning(
+                "LLM rewrite unusable (attempt %d/%d): %r",
+                attempt + 1,
+                _MAX_ATTEMPTS,
+                raw[:200],
+            )
+    except Exception:
+        logger.exception("LLM generation failed, falling back")
+    return cards, "rule-based"
+
+
+def warm_up() -> None:
+    """Eagerly load the model (call from a background thread at app start)."""
+    try:
+        _load_model()
+    except Exception:  # pragma: no cover
+        logger.exception("Model warm-up failed; rule-based fallback will be used")

skyread/plot.py

@@ -0,0 +1,62 @@
+"""Render a Skew-T / Log-P diagram from a sounding.
+
+Uses MetPy's :class:`~metpy.plots.SkewT` so the plotted curves come straight
+from the data — no chart-image reading involved. A Matplotlib ``Figure`` is
+returned so Gradio's ``gr.Plot`` can display it directly.
+"""
+
+from __future__ import annotations
+
+import matplotlib
+
+matplotlib.use("Agg")  # headless backend for server-side rendering
+
+import metpy.calc as mpcalc  # noqa: E402
+from matplotlib.figure import Figure  # noqa: E402
+from metpy.plots import SkewT  # noqa: E402
+
+from skyread.sounding import Sounding  # noqa: E402
+
+
+def make_skewt(snd: Sounding) -> Figure:
+    """Build a Skew-T figure (temperature, dewpoint, parcel path, CAPE/CIN).
+
+    The figure is constructed directly (not via pyplot), so it is never
+    registered in pyplot's global manager — repeated requests on a long-lived
+    server would otherwise leak every figure.
+
+    Args:
+        snd: A parsed sounding.
+
+    Returns:
+        A Matplotlib figure ready for display or saving.
+    """
+    fig = Figure(figsize=(7, 8))
+    skew = SkewT(fig, rotation=45)
+
+    skew.plot(
+        snd.pressure, snd.temperature, "tab:red", linewidth=2, label="Temperature"
+    )
+    skew.plot(snd.pressure, snd.dewpoint, "tab:green", linewidth=2, label="Dewpoint")
+    skew.plot_barbs(snd.pressure[::3], snd.u_wind[::3], snd.v_wind[::3])
+
+    parcel = mpcalc.parcel_profile(
+        snd.pressure, snd.temperature[0], snd.dewpoint[0]
+    ).to("degC")
+    skew.plot(
+        snd.pressure, parcel, "black", linewidth=1.5, linestyle="--", label="Parcel"
+    )
+    skew.shade_cape(snd.pressure, snd.temperature, parcel)
+    skew.shade_cin(snd.pressure, snd.temperature, parcel)
+
+    skew.plot_dry_adiabats(alpha=0.3)
+    skew.plot_moist_adiabats(alpha=0.3)
+    skew.plot_mixing_lines(alpha=0.3)
+
+    skew.ax.set_xlim(-40, 50)
+    skew.ax.set_ylim(1050, 100)
+    skew.ax.set_xlabel("Temperature (°C)")
+    skew.ax.set_ylabel("Pressure (hPa)")
+    skew.ax.set_title(f"Skew-T / Log-P — {snd.name}")
+    skew.ax.legend(loc="upper right", fontsize=8)
+    return fig

skyread/sounding.py

@@ -0,0 +1,107 @@
+"""Load radiosonde sounding data into a units-aware structure.
+
+This module is pure I/O + parsing. It returns MetPy/pint quantities ready to be
+fed into :mod:`skyread.indices`. Two sources are supported for the spike:
+
+* MetPy's bundled sample soundings (``get_test_data``) — zero network, perfect
+  for demos that must never break.
+* University-of-Wyoming-style fixed-width text (also the IGRA2-export shape) —
+  the format users upload or fetch online.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pandas as pd
+from metpy.calc import wind_components
+from metpy.cbook import get_test_data
+from metpy.units import units
+from pint import Quantity
+
+
+@dataclass
+class Sounding:
+    """A parsed atmospheric sounding with units attached.
+
+    Attributes:
+        pressure: Pressure profile (hPa), decreasing upward.
+        temperature: Environmental temperature profile (degC).
+        dewpoint: Dewpoint temperature profile (degC).
+        u_wind: Zonal wind component (knots).
+        v_wind: Meridional wind component (knots).
+        name: Human-readable label for the sounding.
+    """
+
+    pressure: Quantity
+    temperature: Quantity
+    dewpoint: Quantity
+    u_wind: Quantity
+    v_wind: Quantity
+    name: str
+
+
+def from_wyoming_dataframe(df: pd.DataFrame, name: str) -> Sounding:
+    """Build a :class:`Sounding` from a Wyoming-style dataframe.
+
+    Args:
+        df: Columns ``pressure, height, temperature, dewpoint, direction, speed``.
+        name: Label for the sounding.
+
+    Returns:
+        A units-aware :class:`Sounding`.
+    """
+    df = df.dropna(
+        subset=("temperature", "dewpoint", "direction", "speed"), how="all"
+    ).reset_index(drop=True)
+
+    pressure = df["pressure"].to_numpy() * units.hPa
+    temperature = df["temperature"].to_numpy() * units.degC
+    dewpoint = df["dewpoint"].to_numpy() * units.degC
+    u_wind, v_wind = wind_components(
+        df["speed"].to_numpy() * units.knots,
+        df["direction"].to_numpy() * units.deg,
+    )
+    return Sounding(pressure, temperature, dewpoint, u_wind, v_wind, name)
+
+
+def load_csv(path: str, name: str = "uploaded") -> Sounding:
+    """Load a user-uploaded CSV sounding.
+
+    Expected columns (header row, case-insensitive): ``pressure, temperature,
+    dewpoint, direction, speed``. Pressure in hPa, temperatures in degC,
+    direction in degrees, speed in knots.
+
+    Args:
+        path: Path to the CSV file.
+        name: Label for the sounding.
+
+    Returns:
+        The parsed :class:`Sounding`.
+
+    Raises:
+        ValueError: If required columns are missing.
+    """
+    df = pd.read_csv(path)
+    df.columns = [c.strip().lower() for c in df.columns]
+    required = {"pressure", "temperature", "dewpoint", "direction", "speed"}
+    missing = required - set(df.columns)
+    if missing:
+        raise ValueError(f"CSV missing columns: {sorted(missing)}")
+    return from_wyoming_dataframe(df[list(required)], name=name)
+
+
+def load_sample(name: str = "may4_sounding.txt") -> Sounding:
+    """Load a MetPy bundled sample sounding (no network at runtime).
+
+    Args:
+        name: One of ``may4_sounding.txt``, ``jan20_sounding.txt``,
+            ``nov11_sounding.txt``.
+
+    Returns:
+        The parsed :class:`Sounding`.
+    """
+    path = get_test_data(name, as_file_obj=False)
+    col_names = ["pressure", "height", "temperature", "dewpoint", "direction", "speed"]
+    df = pd.read_fwf(path, skiprows=5, usecols=[0, 1, 2, 3, 6, 7], names=col_names)
+    return from_wyoming_dataframe(df, name=name.replace("_sounding.txt", ""))

skyread/spike.py

@@ -0,0 +1,34 @@
+"""End-to-end spike: sounding -> MetPy indices -> dual-layer interpretation.
+
+Run:
+    uv run python -m skyread.spike
+"""
+
+from __future__ import annotations
+
+from skyread.indices import compute_indices
+from skyread.interpret import build_grandma_prompt, interpret_rule_based
+from skyread.sounding import load_sample
+
+
+def main() -> None:
+    """Run the full SkyRead chain on a bundled sample sounding and print it."""
+    snd = load_sample("may4_sounding.txt")
+    print(f"# Sounding: {snd.name}  ({len(snd.pressure)} levels)\n")
+
+    indices = compute_indices(snd)
+    print("## Step 1 — MetPy computed indices (deterministic):")
+    for key, value in indices.items():
+        print(f"   {key:>14}: {value}")
+
+    cards = interpret_rule_based(indices, snd.name)
+    print("\n## Step 2 — dual-layer cards (rule-based draft / fallback):")
+    print("   " + cards["pro"])
+    print("   " + cards["grandma"])
+
+    print("\n## Step 3 — the rewrite prompt that goes to the small LLM:")
+    print("   " + build_grandma_prompt(indices, snd.name).replace("\n", "\n   "))
+
+
+if __name__ == "__main__":
+    main()

tests/test_app.py

@@ -0,0 +1,27 @@
+"""Tests for the Gradio glue layer (no model download, no network)."""
+
+from pathlib import Path
+
+import app
+
+
+def test_analyze_surfaces_compute_errors_as_message(tmp_path: Path) -> None:
+    # Parses fine (all columns present) but is physically unusable: the
+    # failure happens in compute_indices, not in loading.
+    bad = tmp_path / "empty.csv"
+    bad.write_text("pressure,temperature,dewpoint,direction,speed\n")
+    fig, pro, grandma, badge = app.analyze(
+        app.SOURCE_UPLOAD, "", "", str(bad), use_llm=False
+    )
+    assert fig is None
+    assert pro.startswith("⚠️")
+
+
+def test_analyze_example_rule_based_returns_cards() -> None:
+    fig, pro, grandma, badge = app.analyze(
+        app.SOURCE_EXAMPLE, "", next(iter(app.EXAMPLES)), None, use_llm=False
+    )
+    assert fig is not None
+    assert pro.startswith("【同行版")
+    assert grandma.startswith("【生活版】")
+    assert "MetPy" in badge

tests/test_indices.py

@@ -0,0 +1,51 @@
+"""Baseline tests for deterministic index computation (synthetic profile)."""
+
+import numpy as np
+from metpy.units import units
+
+from skyread.indices import compute_indices
+from skyread.sounding import Sounding
+
+EXPECTED_KEYS = {
+    "cape_jkg",
+    "cin_jkg",
+    "lcl_hpa",
+    "lfc_hpa",
+    "el_hpa",
+    "k_index",
+    "lifted_index",
+    "total_totals",
+    "pwat_mm",
+}
+
+
+def _synthetic_sounding() -> Sounding:
+    """A hand-made conditionally-unstable profile (9 levels)."""
+    pressure = (
+        np.array([1000.0, 925.0, 850.0, 700.0, 500.0, 400.0, 300.0, 250.0, 200.0])
+        * units.hPa
+    )
+    temperature = (
+        np.array([30.0, 24.0, 18.0, 8.0, -10.0, -22.0, -38.0, -48.0, -55.0])
+        * units.degC
+    )
+    dewpoint = (
+        np.array([24.0, 20.0, 14.0, 2.0, -20.0, -35.0, -55.0, -65.0, -70.0])
+        * units.degC
+    )
+    zeros = np.zeros(9) * units.knots
+    return Sounding(pressure, temperature, dewpoint, zeros, zeros, "synthetic")
+
+
+def test_compute_indices_returns_all_expected_keys() -> None:
+    assert set(compute_indices(_synthetic_sounding())) == EXPECTED_KEYS
+
+
+def test_compute_indices_unstable_profile_has_positive_cape() -> None:
+    assert compute_indices(_synthetic_sounding())["cape_jkg"] > 0
+
+
+def test_compute_indices_values_are_plain_floats() -> None:
+    assert all(
+        isinstance(v, float) for v in compute_indices(_synthetic_sounding()).values()
+    )

tests/test_interpret.py

@@ -0,0 +1,64 @@
+"""Baseline tests for the rule-based interpretation layer."""
+
+from skyread.interpret import assess, build_grandma_prompt, interpret_rule_based
+
+
+def _indices(cape: float, cin: float) -> dict[str, float]:
+    return {
+        "cape_jkg": cape,
+        "cin_jkg": cin,
+        "lcl_hpa": 900.0,
+        "lfc_hpa": 850.0,
+        "el_hpa": 200.0,
+        "k_index": 36.0,
+        "lifted_index": -6.0,
+        "total_totals": 53.0,
+        "pwat_mm": 40.0,
+    }
+
+
+def test_assess_extreme_cape_returns_extreme_label() -> None:
+    assert assess(_indices(4500.0, -10.0))["label"] == "extreme"
+
+
+def test_assess_zero_cape_returns_stable_label() -> None:
+    assert assess(_indices(0.0, 0.0))["label"] == "stable"
+
+
+def test_assess_nan_cape_treated_as_stable() -> None:
+    assert assess(_indices(float("nan"), 0.0))["label"] == "stable"
+
+
+def test_assess_stable_cap_note_does_not_claim_easy_initiation() -> None:
+    # CAPE 0 + CIN 0 means "no convection at all", not "convection starts easily".
+    note = assess(_indices(0.0, 0.0))["cap_note"]
+    assert "容易啟動" not in note
+
+
+def test_interpret_rule_based_marginal_advises_umbrella_not_carefree_sunning() -> None:
+    # "可能有雷雨" must not be followed by "棉被可以放心曬".
+    cards = interpret_rule_based(_indices(300.0, -200.0), "test")
+    assert "傘" in cards["grandma"]
+    assert "放心曬" not in cards["grandma"]
+
+
+def test_interpret_rule_based_unstable_advises_umbrella() -> None:
+    cards = interpret_rule_based(_indices(2000.0, -50.0), "test")
+    assert "帶傘" in cards["grandma"]
+
+
+def test_interpret_rule_based_stable_allows_sunbathing_quilt() -> None:
+    cards = interpret_rule_based(_indices(0.0, 0.0), "test")
+    assert "曬" in cards["grandma"]
+
+
+def test_build_grandma_prompt_embeds_rule_based_draft() -> None:
+    prompt = build_grandma_prompt(_indices(2000.0, -50.0), "test")
+    draft = interpret_rule_based(_indices(2000.0, -50.0), "test")
+    assert draft["grandma"].removeprefix("【生活版】") in prompt
+
+
+def test_build_grandma_prompt_requests_rewrite_only() -> None:
+    prompt = build_grandma_prompt(_indices(1500.0, -30.0), "test")
+    assert "繁體中文" in prompt
+    assert "只輸出改寫後的句子" in prompt

tests/test_live.py

@@ -0,0 +1,20 @@
+"""Tests for live-sounding time logic (network calls are not tested here)."""
+
+from datetime import datetime, timezone
+
+from skyread.live import _latest_synoptic
+
+
+def test_latest_synoptic_morning_rounds_to_00z() -> None:
+    now = datetime(2026, 6, 11, 3, 30, tzinfo=timezone.utc)
+    assert _latest_synoptic(now) == datetime(2026, 6, 11, 0, 0, tzinfo=timezone.utc)
+
+
+def test_latest_synoptic_afternoon_rounds_to_12z() -> None:
+    now = datetime(2026, 6, 11, 15, 0, tzinfo=timezone.utc)
+    assert _latest_synoptic(now) == datetime(2026, 6, 11, 12, 0, tzinfo=timezone.utc)
+
+
+def test_latest_synoptic_exactly_noon_is_12z() -> None:
+    now = datetime(2026, 6, 11, 12, 0, tzinfo=timezone.utc)
+    assert _latest_synoptic(now) == datetime(2026, 6, 11, 12, 0, tzinfo=timezone.utc)

tests/test_llm.py

@@ -0,0 +1,105 @@
+"""Tests for the LLM rewrite layer (no model download needed)."""
+
+import pytest
+
+from skyread import llm
+
+_INDICES = {
+    "cape_jkg": 1500.0,
+    "cin_jkg": -30.0,
+    "lcl_hpa": 900.0,
+    "lfc_hpa": 850.0,
+    "el_hpa": 200.0,
+    "k_index": 36.0,
+    "lifted_index": -4.0,
+    "total_totals": 50.0,
+    "pwat_mm": 45.0,
+}
+
+
+def test_clean_rewrite_accepts_normal_sentence() -> None:
+    text = "「今天下午會打雷，出門帶把傘卡安心。」"
+    assert llm._clean_rewrite(text) == "今天下午會打雷，出門帶把傘卡安心。"
+
+
+def test_clean_rewrite_rejects_instruction_echo() -> None:
+    assert llm._clean_rewrite("好的，以下是改寫後的句子：") is None
+
+
+def test_clean_rewrite_rejects_empty_and_non_chinese() -> None:
+    assert llm._clean_rewrite("   ") is None
+    assert llm._clean_rewrite("Sure! Here is the sentence.") is None
+
+
+def test_clean_rewrite_rejects_overlong_output() -> None:
+    assert llm._clean_rewrite("雨" * 300) is None
+
+
+def test_clean_rewrite_rejects_simplified_chinese() -> None:
+    # Real failure modes observed from MiniCPM3-4B on the GPU box.
+    assert llm._clean_rewrite("下午有機會打雷下雨，记得帶把伞。") is None
+    assert llm._clean_rewrite("今天天氣挺稳当的，不太會打雷下雨。") is None
+    assert llm._clean_rewrite("棉被可以拿出来晒太陽。") is None
+    assert llm._clean_rewrite("可能会有小小滴雨滴哦！") is None
+    assert llm._clean_rewrite("今天温度舒适，适合外出。") is None
+
+
+def test_clean_rewrite_accepts_pure_traditional_sentence() -> None:
+    text = "下午可能會打雷下雨，記得帶把傘，棉被先別曬喔。"
+    assert llm._clean_rewrite(text) == text
+
+
+def test_interpret_llm_falls_back_when_generation_fails(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def boom(prompt: str) -> str:
+        raise RuntimeError("model exploded")
+
+    monkeypatch.setattr(llm, "_generate", boom)
+    cards, engine = llm.interpret_llm(_INDICES, "test")
+    assert engine == "rule-based"
+    assert cards["pro"].startswith("【同行版")
+    assert cards["grandma"].startswith("【生活版】")
+
+
+def test_interpret_llm_falls_back_when_output_unusable(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(llm, "_generate", lambda prompt: "Here you go!")
+    cards, engine = llm.interpret_llm(_INDICES, "test")
+    assert engine == "rule-based"
+
+
+def test_interpret_llm_retries_until_a_usable_rewrite(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    outputs = iter(["可能会有雨。", "下午可能下雨，帶把傘較安心。"])
+    monkeypatch.setattr(llm, "_generate", lambda prompt: next(outputs))
+    cards, engine = llm.interpret_llm(_INDICES, "test")
+    assert engine == "llm"
+    assert cards["grandma"] == "【生活版】下午可能下雨，帶把傘較安心。"
+
+
+def test_interpret_llm_gives_up_after_max_attempts(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    calls: list[str] = []
+
+    def always_simplified(prompt: str) -> str:
+        calls.append(prompt)
+        return "可能会有雨。"
+
+    monkeypatch.setattr(llm, "_generate", always_simplified)
+    cards, engine = llm.interpret_llm(_INDICES, "test")
+    assert engine == "rule-based"
+    assert len(calls) == llm._MAX_ATTEMPTS
+
+
+def test_interpret_llm_rewrites_only_grandma_card(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(llm, "_generate", lambda prompt: "下午會打雷，帶傘較妥當。")
+    cards, engine = llm.interpret_llm(_INDICES, "test")
+    assert engine == "llm"
+    assert cards["grandma"] == "【生活版】下午會打雷，帶傘較妥當。"
+    assert cards["pro"].startswith("【同行版")  # untouched, rule-based numbers

tests/test_plot.py

@@ -0,0 +1,36 @@
+"""Tests for the Skew-T renderer (headless, no display)."""
+
+import numpy as np
+from matplotlib.figure import Figure
+from metpy.units import units
+
+from skyread.plot import make_skewt
+from skyread.sounding import Sounding
+
+
+def _sounding() -> Sounding:
+    pressure = (
+        np.array([1000.0, 925.0, 850.0, 700.0, 500.0, 400.0, 300.0, 250.0, 200.0])
+        * units.hPa
+    )
+    temperature = (
+        np.array([30.0, 24.0, 18.0, 8.0, -10.0, -22.0, -38.0, -48.0, -55.0])
+        * units.degC
+    )
+    dewpoint = (
+        np.array([24.0, 20.0, 14.0, 2.0, -20.0, -35.0, -55.0, -65.0, -70.0])
+        * units.degC
+    )
+    zeros = np.zeros(9) * units.knots
+    return Sounding(pressure, temperature, dewpoint, zeros, zeros, "synthetic")
+
+
+def test_make_skewt_returns_figure_outside_pyplot_registry() -> None:
+    import matplotlib.pyplot as plt
+
+    before = plt.get_fignums()
+    fig = make_skewt(_sounding())
+    assert isinstance(fig, Figure)
+    # Figures must not accumulate in pyplot's global manager (memory leak on
+    # a long-lived Space).
+    assert plt.get_fignums() == before