Guides

Ingest strategies

obs(station, from, to, opts) is the ingest-planner surface. It picks how to pull observations: a one-off date-bounded fetch, a year-aligned warm cache, or (future) a hosted precompute endpoint (not yet available). The default strategy: “auto” picks the right one for your window.

Three strategies

Strategy	When to use	Cache behavior
`exact_window`	One-off ≤7-day window. Cheapest path for a single call.	None — fetches exactly the requested bytes.
`warm_cache`	Year-aligned. Reusable across calls with overlapping windows.	Writes year-padded parquet; subsequent calls in the same year are local-only.
`hosted`	v0.2.x — precomputed-API for fleet-scale ingest. Not yet wired.	(Future)
`auto` (default)	Picks `exact_window` ≤7 days; `warm_cache` otherwise.	Per the picked strategy.

Auto-router heuristic

1
window = (to_date - from_date)
2

3
if window ≤ 7 days:    strategy = exact_window
4
else:                  strategy = warm_cache

The 7-day cut roughly matches AWC’s 168-hour live window — anything inside there can be answered cheaply by a single fetch; anything wider benefits from year-aligned caching.

source=<one> always forces exact_window regardless of window size — single-source queries can’t honor the multi-source merge that warm_cache enables.

1
from mostlyright.weather import obs
2

3
# Auto-router — 7-day window picks exact_window
4
rows = obs("KNYC", "2025-01-06", "2025-01-12")
5

6
# Explicit — pull a year-padded warm cache for repeated backtest queries
7
rows = obs("KNYC", "2024-01-01", "2024-12-31", strategy="warm_cache")
8

9
# Single source — auto-picks exact_window
10
rows = obs("KNYC", "2025-01-06", "2025-01-12", source="iem")

1
import { obs } from "@mostlyrightmd/weather";
2

3
// Auto-router
4
const rows = await obs("KNYC", "2025-01-06", "2025-01-12");
5

6
// Explicit
7
const yearRows = await obs("KNYC", "2024-01-01", "2024-12-31", {
8
  strategy: "warm_cache",
9
});
10

11
// hosted strategy throws DataAvailabilityError until v0.2.x
12
await obs("KNYC", "2025-01-06", "2025-01-12", { strategy: "hosted" });
13
// → DataAvailabilityError(reason="model_unavailable",
14
//                         hint="hosted strategy deferred to v0.2.x …")

exact_window in depth

Cheapest for one-off queries. ≤2 MB of HTTP per call for a week of one station.
No cache write. Subsequent identical calls re-fetch.
Honors source=. Single-source pinning; the fetcher emits only that source’s rows.
No year-padding. A 2025-01-06 to 2025-01-12 call pulls exactly that range.

warm_cache in depth

Year-aligned. A call for 2025-01-06 to 2025-01-12 pulls Jan-2025 + (if needed) Feb-2025, padded to month boundaries, written to parquet.
Multi-source merge. Pulls AWC + IEM + GHCNh; merges per OBSERVATION_SOURCE_PRIORITY.
Subsequent calls are local-only for any window inside an already-cached year.
Backtest path — this is what research() uses internally.

hosted (v0.2.x — not yet)

Reserved for a future hosted precompute API. Calls raise DataAvailabilityError(reason="model_unavailable") today; the signature stays stable so caller code keeps working when v0.2.x ships.

Source-filter routing

Caller writes	Strategy picked
`obs("KNYC", from, to)` (no source)	auto-router (size)
`obs("KNYC", from, to, source="iem")`	`exact_window`
`obs("KNYC", from, to, source="awc")`	`exact_window`
`obs(..., strategy="warm_cache")`	forced `warm_cache`
`obs(..., strategy="warm_cache", source=…)`	`ValueError` — incompatible

The single-source + multi-source-merge combination is a category error; the router catches it at the call site rather than letting it produce wrong rows.

When NOT to use `obs()`

obs() is for raw observation rows. If you want joined observation + climate + (optional) forecast rows keyed by settlement date, use research(). research() calls obs() internally under the hood.