fix(weather): normalize structured source language

[IceCodeNew]

Summary

• validate the packaged Open-Meteo WMO mapping during module import without freezing the cached lookup object
• convert structured Open-Meteo weather, air-quality, and pollen data into consistent English source documents
• convert structured AQICN context into the same fixed English source language
• preserve each location's configured final output language through the existing LLM contract

Language boundary

Open-Meteo returns language-neutral structured JSON rather than Chinese or English prose. The adapters now format project-owned structured data in English and declare the resulting source documents as en. The system prompt already requires every output field to use input.output_language, so no duplicate prompt rule was added.

Review fixes

• fix(weather): render readable WMO conditions #85 Qodo: reference-data failures now surface deterministically during module import
• fix(weather): normalize structured source language #86 Qodo: import-time validation no longer stores a frozen mapping; runtime lookups still use the cached loader boundary

Validation

• 846 passed
• line coverage: 99.85%
• branch coverage: 99.52%
• prek run --all-files
• commit hooks passed

Local CodeRabbit review was not run because the security approval denied exporting an unpublished diff. GitHub review bots can review the published commit.

Summary by CodeRabbit

• New Features

  • Open-Meteo weather forecasts, pollen information, and source descriptions are now provided in English.
  • Air-quality and allergen categories and guidance are now displayed in English.
  • Weather forecasts use clearer English formatting, including standard units such as °C, mm, and km/h.

• Bug Fixes

  • Unrecognized weather codes now display “Unrecognized weather condition” and are recorded in security logs.
  • Source and snapshot language metadata now accurately reflects English content.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change switches Open-Meteo, air-quality, and allergen outputs from Chinese to English, updates packaged reference data and guidance labels, changes weather formatting and fallbacks, and adjusts related tests and design documentation.

Changes

English localization

Layer / File(s)	Summary
English reference data and metadata weather_briefing/data/*, weather_briefing/reference_data.py, weather_briefing/weather_context.py, weather_briefing/air_quality.py, tests/test_air_quality.py, tests/test_allergen.py, tests/test_languages.py, tests/test_reference_data.py	Weather-code descriptions, air-quality guidance, allergen guidance, provider metadata, and related assertions now use English values.
Open-Meteo English rendering weather_briefing/weather_context.py, tests/test_weather_context.py, tests/test_render.py, docs/design.md	Forecast formatting, pollen attribution, unknown weather-code fallback text, rendering assertions, and provider documentation now describe English output.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• IceCodeNew/weather-briefing#23: Added the Open-Meteo pollen allergen outputs updated here.
• IceCodeNew/weather-briefing#72: Added language metadata plumbing used by these English output changes.
• IceCodeNew/weather-briefing#85: Updated the Open-Meteo WMO weather-code rendering and fallback path.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: normalizing the weather source language for weather data and structured outputs.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/wmo-reference-data-boundary

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Validate Open-Meteo WMO mapping at weather module startup

🐞 Bug fix 📝 Documentation 🕐 20-40 Minutes

AI Description

• Eager-load and validate packaged Open-Meteo WMO code mapping during module import.
• Reuse a single validated mapping for Open-Meteo forecast formatting.
• Document fixed zh-CN source documents and downstream multilingual translation behavior.

Diagram

graph TD
A([Process start]) --> B["weather_context.py import"] --> C["reference_data.py"] --> D[("open_meteo_weather_codes.json")]
E["OpenMeteoProvider"] --> F["Forecast formatting"] --> B
F --> G["Multilingual briefing"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Explicit startup preflight (app entrypoint)

• ➕ Avoids import-time I/O/validation side effects
• ➕ Allows centralizing all reference-data checks in one place
• ➖ Requires wiring a new initialization step across entrypoints/CLIs
• ➖ Still needs guarantees it runs before first weather request

2. CI/package-time validation only

• ➕ Keeps runtime startup minimal
• ➕ Catches malformed packaged data before release
• ➖ Does not protect against runtime packaging/deployment issues
• ➖ Doesn’t help when running from source with missing data files

Recommendation: Current approach is a good reliability tradeoff: it fails deterministically on startup if packaged WMO mapping is missing/malformed, and it removes per-call mapping loads. If startup side effects become a concern later, the next best option is a centralized preflight in the application entrypoint(s).

Files changed (2) +4 / -4

Bug fix (1) +3 / -3

weather_context.pyEager-load Open-Meteo WMO descriptions on import +3/-3

Eager-load Open-Meteo WMO descriptions on import

• Adds a module-level '_OPEN_METEO_WEATHER_CODES' initialized via 'open_meteo_weather_code_descriptions()' so reference data is validated at import/startup. Refactors the weather-code description helper to reuse this mapping rather than loading it lazily during formatting.

weather_briefing/weather_context.py

Documentation (1) +1 / -1

design.mdClarify Open-Meteo language model and startup validation behavior +1/-1

Clarify Open-Meteo language model and startup validation behavior

• Updates the OpenMeteoProvider design notes to state it always produces a 'zh-CN' source document. Clarifies that the LLM translates the full source document into each location’s configured output language, and notes the WMO mapping is validated at module load time.

docs/design.md

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.79%. Comparing base (6c3c662) to head (0a88d41).
⚠️ Report is 1 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##           master      #86   +/-   ##
=======================================
  Coverage   99.79%   99.79%           
=======================================
  Files          45       45           
  Lines        8800     8810   +10     
  Branches      526      526           
=======================================
+ Hits         8782     8792   +10     
  Misses         13       13           
  Partials        5        5           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 39 rules

1. Frozen WMO mapping snapshot ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

weather_context stores the Open‑Meteo weather-code mapping in a module-level constant, so later
open_meteo_weather_code_descriptions.cache_clear() or loader monkeypatches will not affect
_open_meteo_weather_description lookups. This can reduce test isolation and makes any future
reference-data reload/debug workflow harder because lookups bypass the cached function boundary
after import.

Code

weather_briefing/weather_context.py[53]

+_OPEN_METEO_WEATHER_CODES = open_meteo_weather_code_descriptions()

Relevance

⭐⭐ Medium

Repo already snapshots cached reference data at import (PR#77); no past evidence about
cache_clear/monkeypatch isolation here.

PR-#77
PR-#85

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The PR introduces a module-level _OPEN_METEO_WEATHER_CODES initialized by calling
open_meteo_weather_code_descriptions() and changes _open_meteo_weather_description to consult
that constant instead of the cached function. The mapping function is explicitly @cache-decorated
and tests already use cache_clear() to validate behavior, but clearing that cache would not
refresh the constant held by weather_context after import.

weather_briefing/weather_context.py[49-54]
weather_briefing/weather_context.py[1044-1047]
weather_briefing/reference_data.py[145-169]
tests/test_reference_data.py[101-107]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`weather_briefing.weather_context` snapshots the Open‑Meteo WMO mapping into `_OPEN_METEO_WEATHER_CODES` at import time. After that, clearing `open_meteo_weather_code_descriptions`’s `@cache` (or monkeypatching `load_reference_data`) won’t change what `_open_meteo_weather_description` returns, because it no longer consults the cached function.

## Issue Context
This PR intentionally validates reference data at module load, but the current approach also freezes the mapping object for the lifetime of the Python process.

## Fix Focus Areas
- weather_briefing/weather_context.py[51-54]
- weather_briefing/weather_context.py[1044-1047]

## Suggested change
Keep the import-time validation, but avoid freezing the lookup source:
- At module load: call `open_meteo_weather_code_descriptions()` once purely for validation (discard result).
- In `_open_meteo_weather_description`: call `open_meteo_weather_code_descriptions()` (it remains cheap due to `@cache`).

This preserves deterministic startup validation while keeping cache clearing / monkeypatching effective for tests.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---