mostlyrightmd 1.5.2__tar.gz → 1.7.0__tar.gz

{mostlyrightmd-1.5.2 → mostlyrightmd-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyrightmd
-Version: 1.5.2
+Version: 1.7.0
 Summary: Python SDK for quants, ML engineers, and AI agents — one interface to public data. Adapters ship weather + prediction-market settlements (Kalshi NHIGH/NLOW, Polymarket) today; SEC filings, Federal Reserve series, court filings, FDA approvals, and equities are next. Schema-versioned, leakage-free, local-first. Imports as `mostlyright`.
 Project-URL: Homepage, https://mostlyright.md
 Project-URL: Documentation, https://mostlyright.md/docs/sdk/
@@ -29,7 +29,7 @@ Requires-Dist: pandas<4.0,>=2.2; extra == 'polars'
 Requires-Dist: polars<2.0,>=1.0; extra == 'polars'
 Requires-Dist: pyarrow<24.0,>=17.0; extra == 'polars'
 Provides-Extra: research
-Requires-Dist: mostlyrightmd-weather<2.0,>=1.0.0; extra == 'research'
+Requires-Dist: mostlyrightmd-weather<2.0,>=1.7.0; extra == 'research'
 Requires-Dist: pandas<4.0,>=2.2; extra == 'research'
 Requires-Dist: pyarrow<24.0,>=17.0; extra == 'research'
 Description-Content-Type: text/markdown

{mostlyrightmd-1.5.2 → mostlyrightmd-1.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mostlyrightmd"
-version = "1.5.2"
+version = "1.7.0"
 description = "Python SDK for quants, ML engineers, and AI agents — one interface to public data. Adapters ship weather + prediction-market settlements (Kalshi NHIGH/NLOW, Polymarket) today; SEC filings, Federal Reserve series, court filings, FDA approvals, and equities are next. Schema-versioned, leakage-free, local-first. Imports as `mostlyright`."
 readme = "README.md"
 license = "MIT"
@@ -72,7 +72,12 @@ parquet = [
 # pandas upper bound aligned with `parquet` extra at <4.0; both backends
 # are exercised by the dual-pandas CI matrix.
 research = [
-    "mostlyrightmd-weather>=1.0.0,<2.0",
+    # >=1.7.0: forecast_nwp() threads member= to the weather impl, a kwarg
+    # introduced in mostlyrightmd-weather 1.7.0 (#74) — an older weather would
+    # TypeError on forecast_nwp(..., member=...). (Supersedes the >=1.6.0 floor
+    # for fetch_open_meteo(variables=...), #64 codex P1; default calls stay
+    # skew-tolerant via the core wrapper's conditional member threading.)
+    "mostlyrightmd-weather>=1.7.0,<2.0",
     "pyarrow>=17.0,<24.0",
     "pandas>=2.2,<4.0",
 ]

{mostlyrightmd-1.5.2 → mostlyrightmd-1.7.0}/src/mostlyright/_internal/_pairs.py

@@ -31,12 +31,16 @@ pairs() returns one row per settlement date, joining:
 
 This is the primary training/feature surface for AI settlement models.
 
-Forecast join:
-  - IEM MOS records (`forecast.json`) have `issued_at`; grouped by issued_at to
-    pick the most-recent run before market close, then temperature_f values for
-    valid_at timestamps within the settlement window are aggregated (max/min).
-  - Open-Meteo records (`forecast_series.json`) have no issued_at; all records
-    in the settlement window are used. temperature_c is converted to F.
+Forecast join (records are split by their authoritative ``source`` field —
+``source`` prefixed ``open_meteo`` -> Open-Meteo, else IEM MOS; see issue #67):
+  - IEM MOS records (`forecast.json`, `source="iem.archive"`) are grouped by
+    issued_at to pick the most-recent run before market close, then
+    temperature_f values for valid_at timestamps within the settlement window
+    are aggregated (max/min).
+  - Open-Meteo records (`forecast_series.json`, `source="open_meteo.*"`) use
+    all records in the settlement window. temperature_c is converted to F
+    (or a pre-converted temperature_f is used as-is). NOTE: Phase 20+ OM rows
+    also carry a derived `issued_at`, so `issued_at` is NOT the discriminator.
   - If both are available, IEM MOS is preferred. Open-Meteo used as fallback.
   - If forecast data is unavailable, forecast columns are None - the row is
     still returned.
@@ -180,6 +184,49 @@ def _select_best_run(
     return best_issued, runs[best_issued]
 
 
+def _to_iso_z(v: Any) -> Any:
+    """Coerce a timestamp-ish value to a canonical UTC ``...Z`` ISO string.
+
+    Open-Meteo rows produced directly by ``fetch_open_meteo(...).to_dict(
+    "records")`` carry pandas ``Timestamp`` ``valid_at`` / ``issued_at`` values,
+    not ISO strings. The forecast-window comparisons below are string-based, so
+    a direct caller of ``build_pairs_row`` would otherwise hit a ``TypeError``
+    comparing ``Timestamp`` to ``str`` (issue #67 / codex P2). ``str`` /
+    ``None`` pass through unchanged; anything date-like (pandas ``Timestamp`` is
+    a ``datetime`` subclass) is normalized to UTC and stamped ``%Y-%m-%dT%H:%M:%SZ``.
+    """
+    if v is None or isinstance(v, str):
+        return v
+    if hasattr(v, "strftime"):
+        try:
+            if getattr(v, "tzinfo", None) is not None:
+                v = v.astimezone(UTC)
+            return v.strftime("%Y-%m-%dT%H:%M:%SZ")
+        except Exception:
+            return v
+    return v
+
+
+def _is_open_meteo_record(r: dict[str, Any]) -> bool:
+    """True if ``r`` is an Open-Meteo forecast record (issue #67).
+
+    The authoritative signal is the ``source`` field: real Open-Meteo rows
+    carry ``source`` prefixed ``open_meteo`` (.previous_runs / .single_run /
+    .seamless / .live), while IEM MOS rows carry ``source="iem.archive"``.
+
+    For backward compatibility, the previously-documented *legacy* Open-Meteo
+    shape — no ``source`` AND no ``issued_at`` (the old ``forecast_series.json``
+    discriminator) — is also treated as Open-Meteo. Real IEM MOS rows always
+    carry an ``issued_at``, so a record lacking both fields can only be a
+    legacy OM row; this avoids regressing source-less OM callers to null.
+    """
+    src = str(r.get("source") or "")
+    if src.startswith("open_meteo"):
+        return True
+    # Legacy OM shape (pre-Phase-20): no source, no issued_at.
+    return not src and not r.get("issued_at")
+
+
 def _aggregate_fcst_temps_iem(
     run_records: list[dict[str, Any]],
     window_start_iso: str,
@@ -209,9 +256,19 @@ def _aggregate_fcst_temps_openmeteo(
     window_start_iso: str,
     window_end_iso: str,
 ) -> tuple[float | None, float | None]:
-    """Aggregate Open-Meteo hourly temperature_c (-> F) over the settlement window.
+    """Aggregate Open-Meteo hourly temperature (-> F) over the settlement window.
 
-    Open-Meteo stores temperature in Celsius. Conversion: F = C * 9/5 + 32.
+    Open-Meteo rows store temperature in Celsius. The field name varies by
+    producer, so accept all three shapes (issue #67):
+
+    - ``temperature_c`` — the unit-contract / specs name (°C -> F).
+    - ``temp_c`` — the canonical column name on a raw
+      ``fetch_open_meteo(...).to_dict("records")`` row (°C -> F).
+    - ``temperature_f`` — pre-converted Fahrenheit, the shape
+      ``research._fetch_open_meteo_range`` emits (used as-is).
+
+    Without covering all three, source-discriminated OM rows from either the
+    research() wrapper or the public fetcher would aggregate to null.
 
     Args:
         run_records: All Open-Meteo hourly records for the date.
@@ -221,12 +278,19 @@ def _aggregate_fcst_temps_openmeteo(
     Returns:
         (fcst_high_f, fcst_low_f) or (None, None) if no records in window.
     """
-    temps_f = [
-        r["temperature_c"] * 9 / 5 + 32
-        for r in run_records
-        if r.get("temperature_c") is not None
-        and window_start_iso <= r.get("valid_at", "") <= window_end_iso
-    ]
+    temps_f: list[float] = []
+    for r in run_records:
+        if not (window_start_iso <= r.get("valid_at", "") <= window_end_iso):
+            continue
+        temp_c = r.get("temperature_c")
+        if temp_c is None:
+            temp_c = r.get("temp_c")
+        if temp_c is not None:
+            temps_f.append(temp_c * 9 / 5 + 32)
+            continue
+        temp_f = r.get("temperature_f")
+        if temp_f is not None:
+            temps_f.append(temp_f)
     return (max(temps_f), min(temps_f)) if temps_f else (None, None)
 
 
@@ -250,7 +314,10 @@ def build_pairs_row(
         climate: NWS CLI record for the date (or None). Must be a dict or None
             - non-dict values are treated as None.
         forecasts: All forecast records with valid_at (or None if unavailable).
-            IEM MOS records have issued_at; Open-Meteo records do not.
+            Records are split by their ``source`` field: ``source`` prefixed
+            ``open_meteo`` -> Open-Meteo, everything else (e.g.
+            ``source="iem.archive"``) -> IEM MOS. ``issued_at`` is NOT used as
+            the discriminator (Phase 20+ Open-Meteo rows carry one too).
         forecast_model: Filter IEM MOS records to this model before run
             selection. None = no filtering (best available run).
         tz_override: IANA timezone name override for stations not in the known
@@ -295,9 +362,17 @@ def build_pairs_row(
         win_start_iso = win_start.strftime("%Y-%m-%dT%H:%M:%SZ")
         win_end_iso = win_end.strftime("%Y-%m-%dT%H:%M:%SZ")
 
-        # Separate IEM MOS (has issued_at) from Open-Meteo (no issued_at)
-        iem_records = [r for r in forecasts if r.get("issued_at")]
-        om_records = [r for r in forecasts if not r.get("issued_at")]
+        # Separate IEM MOS from Open-Meteo by the authoritative ``source``
+        # field (issue #67), with a legacy no-source/no-issued_at fallback —
+        # see _is_open_meteo_record. ``issued_at`` presence alone is NOT a
+        # valid discriminator: Phase 20+ Open-Meteo rows carry a derived
+        # ``issued_at`` (for cycle-math / previous-runs caching), so the old
+        # ``issued_at``-based split misrouted those rows into the IEM MOS
+        # aggregation path, silently nulling forecast temps and polluting IEM
+        # run-selection. research._fetch_open_meteo_range already documents
+        # this contract ("discriminates via row.get('source')").
+        om_records = [r for r in forecasts if _is_open_meteo_record(r)]
+        iem_records = [r for r in forecasts if not _is_open_meteo_record(r)]
 
         # Apply forecast_model filter to IEM MOS records before run selection.
         # Phase 17 Wave 4 iter-3 review HIGH: case-insensitive match because
@@ -339,19 +414,66 @@ def build_pairs_row(
 
         # Fall back to Open-Meteo if IEM MOS yielded no temperature data
         if fcst_high is None and om_records:
-            fcst_high, fcst_low = _aggregate_fcst_temps_openmeteo(
-                om_records, win_start_iso, win_end_iso
-            )
-            fcst_model = next((r.get("model") for r in om_records if r.get("model")), "open-meteo")
-            window_om = [
-                r for r in om_records if win_start_iso <= r.get("valid_at", "") <= win_end_iso
+            # Leakage guard (issue #67, codex P1): Phase 20+ OM rows carry a
+            # derived issued_at. Pre-#67 these flowed through the IEM branch,
+            # where _select_best_run filtered runs issued AFTER market close.
+            # The OM branch has no such filter, so apply the cutoff here too —
+            # otherwise a row from a run issued after settlement (e.g. live /
+            # single-run cycles mixed into training pairs) would leak its
+            # temperature/POP/QPF into the pair, not just its timestamp.
+            # Legacy source-less OM rows have no issued_at provenance and are
+            # kept (documented all-window behavior — nothing to leak).
+            cutoff_iso = market_close.strftime("%Y-%m-%dT%H:%M:%SZ")
+            # Normalize valid_at / issued_at to ISO-Z strings up front so direct
+            # callers passing raw fetch_open_meteo output (pandas Timestamps)
+            # don't TypeError against the string window bounds (codex P2). Shallow
+            # copies — the caller's row dicts are not mutated.
+            norm_om = [
+                {
+                    **r,
+                    "valid_at": _to_iso_z(r.get("valid_at")),
+                    "issued_at": _to_iso_z(r.get("issued_at")),
+                }
+                for r in om_records
             ]
-            probs = [
-                r["precipitation_probability_pct"]
-                for r in window_om
-                if r.get("precipitation_probability_pct") is not None
+            window_om = [
+                r
+                for r in norm_om
+                if win_start_iso <= r.get("valid_at", "") <= win_end_iso
+                and ((iss := r.get("issued_at")) is None or iss <= cutoff_iso)
             ]
-            fcst_pop = max(probs) if probs else None
+            fcst_high, fcst_low = _aggregate_fcst_temps_openmeteo(
+                window_om, win_start_iso, win_end_iso
+            )
+            if window_om:
+                fcst_model = next(
+                    (r.get("model") for r in window_om if r.get("model")), "open-meteo"
+                )
+                # POP: accept the unit-contract ``precipitation_probability_pct``
+                # OR the ``pop_6hr_pct`` alias research._fetch_open_meteo_range
+                # emits. Without the alias, source-discriminated wrapper rows
+                # would regress POP to None now that they no longer flow through
+                # the IEM branch. Explicit None-checks preserve a valid 0.0.
+                probs: list[float] = []
+                for r in window_om:
+                    p = r.get("precipitation_probability_pct")
+                    if p is None:
+                        p = r.get("pop_6hr_pct")
+                    if p is not None:
+                        probs.append(p)
+                fcst_pop = max(probs) if probs else None
+                # QPF: the OM unit-contract shape carries no QPF, but the
+                # research wrapper emits ``qpf_6hr_in`` — sum over the window to
+                # match IEM-branch semantics (else wrapper QPF regresses too).
+                qpfs_om = [r["qpf_6hr_in"] for r in window_om if r.get("qpf_6hr_in") is not None]
+                if qpfs_om:
+                    fcst_qpf = sum(qpfs_om)
+                # ISSUED_AT provenance: most-recent run timestamp (all already
+                # <= cutoff by the window_om filter above). None for legacy
+                # source-less rows.
+                om_issued = [iss for r in window_om if (iss := r.get("issued_at")) is not None]
+                if om_issued:
+                    fcst_issued = max(om_issued)
 
         fcst.update(
             {

{mostlyrightmd-1.5.2 → mostlyrightmd-1.7.0}/src/mostlyright/core/schemas/forecast_nwp.py

@@ -165,6 +165,9 @@ class NwpForecastSchema(Schema):
         ColumnSpec(name="precip_mm_1h", dtype="float64", units="mm", nullable=True),
         ColumnSpec(name="pressure_pa_surface", dtype="float64", units="Pa", nullable=True),
         ColumnSpec(name="pressure_pa_mslp", dtype="float64", units="Pa", nullable=True),
+        ColumnSpec(name="cloud_cover_pct", dtype="float64", units="percent", nullable=True),
+        ColumnSpec(name="visibility_m", dtype="float64", units="m", nullable=True),
+        ColumnSpec(name="cloud_ceiling_m", dtype="float64", units="m", nullable=True),
         # Provenance / QC -----------------------------------------------
         ColumnSpec(
             name="qc_status",

{mostlyrightmd-1.5.2 → mostlyrightmd-1.7.0}/src/mostlyright/forecasts.py

@@ -131,6 +131,7 @@ def forecast_nwp(
     cycle_range_end: datetime | None = None,
     fxx: int | None = None,
     mirror: str | None = None,
+    member: str | None = None,
     client: httpx.Client | None = None,
 ) -> pd.DataFrame:
     """Fetch an NWP forecast from NOAA Big Data Program direct-fetch.
@@ -149,6 +150,12 @@ def forecast_nwp(
         fxx: Forecast hour ahead of ``cycle``. Default ``1``.
         mirror: Force a specific NOAA BDP mirror (``"aws_bdp"`` or
             ``"nomads"``). Default: try AWS then NOMADS.
+        member: Ensemble member id — only valid for the member-capable
+            models GEFS (``"c00"``/``"p01"``..``"p30"``/``"avg"``/``"spr"``,
+            default ``"c00"``) and CFS (``"01"``..``"04"``, default
+            ``"01"``). ``None`` (default) is byte-identical to today.
+            Validation + the valid-member enums live in the weather impl;
+            this wrapper passes ``member`` straight through (issue #74).
         client: Reuse an ``httpx.Client`` for connection pooling.
 
     Returns:
@@ -157,7 +164,9 @@ def forecast_nwp(
     Raises:
         ValueError: ``model`` not in :data:`SUPPORTED_NWP_MODELS` and
             not a reserved ECMWF id; ``fxx`` is negative; ``cycle`` is
-            naive; ``mirror`` outside the supported set.
+            naive; ``mirror`` outside the supported set; ``member`` set
+            for a non-member model or not a valid member of the model's
+            ensemble (validated in the weather impl).
         NwpModelNotAvailableError: ``model`` is a reserved ECMWF id.
         SourceUnavailableError: ``[nwp]`` optional extra not installed.
         NoLiveForNwpError: every wired NOAA BDP mirror failed.
@@ -261,6 +270,14 @@ def forecast_nwp(
             source=f"nwp.{model}",
         ) from None
 
+    # Issue #74 cross-version skew guard: thread ``member`` only when the
+    # caller actually set it. Passing ``member=member`` unconditionally would
+    # make EVERY core-wrapper call TypeError against an older
+    # mostlyrightmd-weather whose impl predates the kwarg (core 1.7.0 +
+    # weather <=1.6.0 outside the [research] extra's floor). With the guard,
+    # default calls stay call-compatible across the skew; only explicit
+    # ``member=`` callers on an old weather see the loud TypeError.
+    member_kwargs: dict[str, str] = {} if member is None else {"member": member}
     return _impl(
         station,
         model,
@@ -270,4 +287,5 @@ def forecast_nwp(
         fxx=fxx,
         mirror=mirror,
         client=client,
+        **member_kwargs,
     )

{mostlyrightmd-1.5.2 → mostlyrightmd-1.7.0}/src/mostlyright/research.py

@@ -1381,6 +1381,14 @@ def _validate_research_kwargs(
 _FORECAST_SOURCES_ALLOWED: frozenset[str] = frozenset({"iem_mos", "open_meteo"})
 
 
+_OM_RESEARCH_VARIABLES: tuple[str, ...] = (
+    "temperature_2m",
+    "precipitation",
+    "precipitation_probability",
+)
+_OM_RESEARCH_SOURCE: str = "open_meteo.previous_runs"
+
+
 def _fetch_open_meteo_range(
     info: StationInfo,
     from_date: str,
@@ -1390,24 +1398,91 @@ def _fetch_open_meteo_range(
 ) -> dict[str, list[dict[str, Any]]]:
     """Phase 20 OM-05 — fetch Open-Meteo forecasts grouped by settlement date.
 
-    Wraps ``mostlyright.weather._fetchers._open_meteo.fetch_open_meteo`` in
-    training mode (Previous Runs API) and pivots its tabular DataFrame
-    into the ``{date_iso: [forecast_row, ...]}`` shape that
-    ``build_pairs(forecasts_by_date=...)`` expects. Each row carries
-    ``model`` / ``issued_at`` / ``valid_at`` / ``temperature_f`` /
-    ``pop_6hr_pct`` / ``qpf_6hr_in`` keys for build_pairs_row compatibility.
+    Reads from the Phase 20 forecast cache before hitting the network. On a
+    cache miss the fetcher writes each elapsed month's rows back so subsequent
+    calls for the same window are served from disk. Only the 3 variables
+    consumed by the pairs join are requested (Fix 3 — cuts weighted call cost).
+
+    Returns the ``{date_iso: [forecast_row, ...]}`` shape that
+    ``build_pairs(forecasts_by_date=...)`` expects.
     """
+    from datetime import date as _date
+    from datetime import timedelta as _timedelta
+
     import pandas as pd
 
     from mostlyright.weather._fetchers._open_meteo import fetch_open_meteo
+    from mostlyright.weather.cache import read_forecast_cache, write_forecast_cache
+
+    # Enumerate (year, month) partitions covered by [from_date, to_date].
+    start = _date.fromisoformat(from_date)
+    end = _date.fromisoformat(to_date)
+    months: list[tuple[int, int]] = []
+    cur = _date(start.year, start.month, 1)
+    while cur <= end:
+        months.append((cur.year, cur.month))
+        cur = _date(cur.year + (cur.month // 12), (cur.month % 12) + 1, 1)
+
+    # Serve cached partitions; collect months that need a network fetch.
+    all_rows: list[dict[str, Any]] = []
+    missing: list[tuple[int, int]] = []
+    for y, m in months:
+        hit = read_forecast_cache(info.icao, _OM_RESEARCH_SOURCE, model, y, m)
+        if hit is not None:
+            all_rows.extend(hit)
+        else:
+            missing.append((y, m))
+
+    # Fetch the missing span and populate the cache.
+    if missing:
+        # Issue #64 / codex P2: fetch on FULL-MONTH boundaries, not clamped to
+        # the request subrange. Clamping to [start, end] meant a subrange request
+        # (e.g. 2024-06-01..06-02) wrote only those days into the June partition;
+        # a later June window then read that partition as a "hit" and silently
+        # dropped the uncached days. Fetching whole months makes every written
+        # partition complete. The current UTC month is never served from cache
+        # (read_forecast_cache skip) nor written (write_forecast_cache skip), so
+        # its incompleteness is harmless — we only clamp the upper bound to today
+        # so we never request future dates with no data.
+        from datetime import datetime as _datetime
+
+        today = _datetime.now(UTC).date()
+        miss_start = _date(missing[0][0], missing[0][1], 1)
+        miss_end_y, miss_end_m = missing[-1]
+        last_day = _date(miss_end_y + (miss_end_m // 12), (miss_end_m % 12) + 1, 1) - _timedelta(
+            days=1
+        )
+        miss_end = min(last_day, today)
+
+        df_fetched = fetch_open_meteo(
+            info.icao,
+            miss_start.isoformat(),
+            miss_end.isoformat(),
+            model=model,
+            mode="training",
+            variables=_OM_RESEARCH_VARIABLES,
+        )
+
+        if df_fetched is not None and not df_fetched.empty:
+            for y, m in missing:
+                mask = (df_fetched["valid_at"].dt.year == y) & (
+                    df_fetched["valid_at"].dt.month == m
+                )
+                month_rows = df_fetched[mask].to_dict("records")
+                if month_rows:
+                    cleaned_rows = [
+                        {k: (None if pd.isna(v) else v) for k, v in r.items()} for r in month_rows
+                    ]
+                    write_forecast_cache(info.icao, _OM_RESEARCH_SOURCE, model, y, m, cleaned_rows)
+                    all_rows.extend(cleaned_rows)
 
-    df = fetch_open_meteo(info.icao, from_date, to_date, model=model, mode="training")
     groups: dict[str, list[dict[str, Any]]] = {}
-    if df is None or df.empty:
+    if not all_rows:
         return groups
-    for _, row in df.iterrows():
+
+    for row in all_rows:
         ftime = row.get("valid_at")
-        if ftime is None or (isinstance(ftime, float) and ftime != ftime):
+        if ftime is None or pd.isna(ftime):
             continue
         try:
             ftime_dt = pd.to_datetime(ftime, utc=True)
@@ -1421,8 +1496,7 @@ def _fetch_open_meteo_range(
         try:
             issued_iso = (
                 pd.to_datetime(issued_at, utc=True).strftime("%Y-%m-%dT%H:%M:%SZ")
-                if issued_at is not None
-                and not (isinstance(issued_at, float) and issued_at != issued_at)
+                if issued_at is not None and not pd.isna(issued_at)
                 else None
             )
         except Exception:
@@ -1430,21 +1504,21 @@ def _fetch_open_meteo_range(
         valid_iso = ftime_dt.strftime("%Y-%m-%dT%H:%M:%SZ")
         temp_c = row.get("temp_c")
         temperature_f: float | None = None
-        if temp_c is not None and not (isinstance(temp_c, float) and temp_c != temp_c):
+        if temp_c is not None and not pd.isna(temp_c):
             try:
                 temperature_f = float(temp_c) * 9.0 / 5.0 + 32.0
             except (TypeError, ValueError):
                 temperature_f = None
         pop_prob = row.get("precip_probability")
         pop_6hr_pct: float | None = None
-        if pop_prob is not None and not (isinstance(pop_prob, float) and pop_prob != pop_prob):
+        if pop_prob is not None and not pd.isna(pop_prob):
             try:
                 pop_6hr_pct = float(pop_prob) * 100.0
             except (TypeError, ValueError):
                 pop_6hr_pct = None
         precip_mm = row.get("precipitation_mm")
         qpf_6hr_in: float | None = None
-        if precip_mm is not None and not (isinstance(precip_mm, float) and precip_mm != precip_mm):
+        if precip_mm is not None and not pd.isna(precip_mm):
             try:
                 qpf_6hr_in = float(precip_mm) / 25.4
             except (TypeError, ValueError):
@@ -1540,8 +1614,16 @@ def research(
             (all entries are covered).
 
     Returns:
-        DataFrame (or ``list[dict]`` when ``as_dataframe=False``) with one
-        row per settlement date in ``[from_date, to_date]``. Columns:
+        DataFrame (or ``list[dict]`` when ``as_dataframe=False``) with **one
+        row per settlement date** in ``[from_date, to_date]`` — a *daily*
+        summary, NOT hourly/sub-daily observations (issue #52). Each row's
+        ``obs_*`` columns are aggregates over that date's settlement window:
+        ``obs_high_f``/``obs_low_f`` are the window max/min and ``obs_mean_f``
+        is the mean of the sub-daily METARs. ``research()`` does not return
+        raw hourly rows; sub-daily / ``raw_metar`` access is a Sprint 0.5+
+        item (raw METARs are preserved internally for the planned re-parse
+        workflow). For an observation-only daily frame without CLI/forecast
+        columns, see :func:`mostlyright.weather.obs` (also daily). Columns:
 
         ``date`` (index when DataFrame), ``station``, ``cli_high_f``,
         ``cli_low_f``, ``cli_report_type``, ``obs_high_f``, ``obs_low_f``,