Weather Model Run Discovery

Overview

Resolve a numerical weather prediction run before downloading model fields. Probe exact objects or narrow prefixes, verify a request-specific completion contract, and return the newest qualifying initialization with its source metadata.

This skill decides which run and objects exist. Use weather-model-data-fetching afterward to transfer or subset the data.

When to Use This Skill

• An application needs the newest usable GFS, GEFS, HRRR, RAP, NAM, or similar model cycle.
• The nominal latest cycle returns 404, has only early forecast hours, or is still changing.
• Equivalent AWS, NOMADS, Google, Azure, or other mirrors must be compared without silently mixing runs.
• A scheduled job needs a bounded fallback to an older complete cycle.
• The resolved run and provider must be recorded for later reproduction.

Do not activate this skill when the initialization is already fixed or when the task is to download, decode, or interpret model variables.

Define Complete Before Probing

Collect the following request contract:

• model, domain, product, and ensemble member;
• legal UTC cycle hours and cycle interval;
• required forecast hours;
• required companion objects, such as pressure and surface products;
• required inventory or index sidecars;
• provider priority and whether cross-provider fallback is allowed;
• maximum lookback, maximum probes, and freshness requirement.

A run is complete only when every sentinel required by the consumer exists. Examples include:

• one product at one forecast hour for a single-image job;
• both pressure-level and surface files for a sounding;
• the terminal forecast hour needed by a time series;
• every required member for an ensemble statistic.

The presence of forecast hour zero does not prove that a run is complete.

Discovery Workflow

1. Normalize the current time and all candidate initialization times to UTC.
2. Enumerate only legal cycles, newest first, within the lookback bound.
3. Build documented object keys for the exact model, product, member, and forecast hour. Never recursively scan an entire bucket.
4. Probe exact objects with HeadObject, HTTP HEAD, or a narrow paginated prefix listing. A probe should retrieve metadata, not the model payload.
5. Require every sentinel and sidecar in the completion contract. Reject zero- length or obviously placeholder objects.
6. For a live mirror that may expose objects before publication finishes, repeat the metadata probe after a short bounded interval and require stable size and object identity.
7. Select the first complete candidate. A fallback provider must refer to the same initialization, product, member, and forecast hour.
8. Emit a resolution record before starting the download.

Use a provider's documented cycle status page as supporting evidence, not as a substitute for probing the exact objects the consumer requires.

Minimal Resolver Example

Keep provider-specific key construction separate from the selection rule. This example accepts a metadata-only probe callback so it can be used with S3, HTTP, or a test fixture.

from datetime import datetime, timedelta, timezone


def candidate_cycles(now, cycle_hours, lookback):
    now = now.astimezone(timezone.utc).replace(minute=0, second=0, microsecond=0)
    allowed = sorted(set(cycle_hours), reverse=True)
    candidates = []
    for days_back in range((lookback // 24) + 2):
        day = (now - timedelta(days=days_back)).date()
        for hour in allowed:
            cycle = datetime(day.year, day.month, day.day, hour, tzinfo=timezone.utc)
            if cycle <= now and now - cycle <= timedelta(hours=lookback):
                candidates.append(cycle)
    return sorted(set(candidates), reverse=True)


def resolve_latest(now, cycle_hours, lookback, required_objects, probe):
    """Return one complete run; probe(uri) returns metadata or None."""
    attempts = []
    for cycle in candidate_cycles(now, cycle_hours, lookback):
        requested = required_objects(cycle)
        found = {name: probe(uri) for name, uri in requested.items()}
        missing = [name for name, metadata in found.items() if not metadata]
        attempts.append({"cycle": cycle.isoformat(), "missing": missing})
        if not missing:
            return {
                "initialization": cycle.isoformat(),
                "objects": [

…