How we decide
whether tonight is worth it

Phase 1 R10 R8

The pre-overhaul pipeline finished with an LLM (google/gemini-3-flash-preview via OpenRouter) returning adjusted_*_index values bounded to ±0.100. Identical inputs produced non-identical outputs because the model's tempered randomness sat on the numeric output path.

R10 — remove LLM numeric mutation. The module formerly named stargazing/ai_adjust.py was renamed stargazing/narrate.py. Its only exported function is now get_narration(score_trace) -> str; the OpenRouter client survives, the score-mutation branch was deleted. Narration is opt-in via ?narrate=1 on /api/score, so a 1–3 s LLM round-trip no longer blocks every request, and an LLM outage has zero numeric effect.

R8 — split sky-quality from feasibility. compute_stargazing_indices now returns two distinct [0, 1] scores instead of a single mashed-together number:

"sky_quality":  geometric blend of LP, cloud, moon,
                transparency, seeing (optical state)
"feasibility":  fog, dew, wind, comfort, precip risk
                (whether you can actually set up)

The legacy aliases astrophotography_index and stargazing_index are preserved for one release cycle and computed as sky_quality × feasibility. The frontend reads finalScore.mean from the new contract.

Phase 3 R9

The old per-night scorer (_compute_night at stargazing/index.py:487–552) was refactored into _compute_bin(bin_dt, bin_minutes=30). Static fetches (light-pollution atlas lookup, elevation, target geometry) are cached outside the loop; only weather, air quality, and astronomy refresh per bin. Open-Meteo's hourly arrays are interpolated to bin resolution; 7Timer's 3 h bands are nearest-neighbor; NWS periods are matched to the bin's local time.

A new module stargazing/session.py exposes score_session(config, start, end, mode, bin_minutes=30) -> SessionResult returning:

bins:           list[BinScore]
best_window:    { start, end, mean_score, usable_minutes }
session_score:  duration-weighted mean over usable bins
instant_score:  single-bin score at the requested moment

Best-window optimizer. Longest contiguous run of bins where mean_score ≥ mode.usable_threshold (0.55 for naked-eye, 0.65 for planetary, 0.70 for astrophoto), satisfying mode.session_min_minutes (30/45/120). If no contiguous window meets the threshold, the API falls back to the highest single bin and the frontend renders a "best instant" card.

Public surface: GET /api/session?lat=&lon=&mode=&window_hours= returns the full SessionResult; GET /api/score?mode= reports bestWindow, sessionScore, instantScore, and usableMinutes alongside the legacy keys.

Phase 3 R7

Defined in stargazing/modes.py and applied by _compute_bin. The old per-mode weight constants in stargazing/scoring.py (ASTROPHOTOGRAPHY_DEGRADER_WEIGHTS, STARGAZING_DEGRADER_WEIGHTS) were deleted.

Target geometry — deterministic fallback. When the user has not pinned a target, PyEphem (already a dependency) computes the policy-default for each bin. The chosen alt/az is exposed at targetAltAz on every /api/score response and surfaces as a reason in the trace so users understand why a 32° airmass penalty applies.

Modes 4–6 (milky_way, dso_visual, meteor) are modeled internally but not exposed in this release cycle.

Phase 2 R11

The new package stargazing/providers/ wraps each fetcher (openmeteo.py, nws.py, seventimer.py, smoke.py, firms.py, swpc.py) behind a common contract:

@dataclass
class Observation:
    source: str            # "openmeteo" | "nws" | "7timer" | ...
    variable: str          # "cloud_cover_low" | "precip_prob" | ...
    value: float | int | str
    units: str
    valid_at: datetime
    issued_at: datetime | None
    freshness_minutes: float | None
    confidence: float | None

An EnsemblePolicy consumes the per-variable observation list and emits:

@dataclass
class EnsembleResult:
    mean, sigma, p10, p90: float
    members: list[Observation]
    skill_weights: dict[str, float]

Confidence interval on the public score. The scoring function is pure-Python and cheap enough that we Monte-Carlo it 64 times (visible at finalScore.samples = 64), sampling each input ensemble at every iteration, then aggregate. The result surfaces as finalScore.{mean, p10, p90, sigma} on every response.

Disagreement widens, doesn't worsen. The old worst-source-wins reducer (scoring.py:_blend_cloud_cover) was replaced by the ensemble. When sources spread far apart, the reported mean stays put but sigma grows and a uncertainty-role entry appears in reasons[]. The per-variable spread is browsable under ensemble.{variable}.disagreement.

Source-skill table. data/skill_table.json keyed by (source, variable, region, horizon_hours) -> expected MAE/Brier. Bootstrapped uniform; Phase 5 updates it weekly from retrospective NOAA observations.

Phase 4 R2 physics.linear_lp

The module stargazing/physics/brightness.py exposes three primitives:

mpsas_to_luminance(mpsas)  -> float   # ncd/m²
luminance_to_mpsas(L_ncd)  -> float
natural_sky_brightness_ratio(L)  -> float

Round-trip identity: luminance_to_mpsas(mpsas_to_luminance(m)) == m to within float epsilon. The DJ Lorenz 2024 atlas [14] still feeds the pixel lookup; the returned mpsas is converted to luminance immediately, summed linearly with moonlight (R5), Kyba cloud-amplified urban skyglow (R3), and any aerosol scatter contribution (R6), then converted back to mpsas for the physical.predictedMpsas field.

Bortle is no longer a primitive — it becomes a display-time bin computed from predictedMpsas. The public fields exposed under physical are:

predictedMpsas             # total sky brightness at the target alt/az
naturalSkyBrightnessRatio  # L_total / L_natural_zenith
limitingMagnitudeEstimate  # from L_total via NPS guide [3]
naturalSkyBrightnessCdm2
artificialSkyBrightnessCdm2
totalSkyBrightnessCdm2

Reference baselines: natural zenith ~21.8 mpsas (Falchi et al. 2016 [4]); Bortle 1 dark site ~22.0; Bortle 7 suburban ~17.5–18.0.

Phase 4 R5 physics.ks_moonlight

The Krisciunas & Schaefer 1991 V-band scattered-moonlight model [6] is implemented at stargazing/physics/moonlight.py. Inputs:

alpha    moon phase angle (radians)
Z_moon   moon zenith distance     = 90° - moon_altitude
Z_obj    target zenith distance   = 90° - target_altitude
rho      moon-target angular separation
k        atmospheric extinction coefficient (R6)

The model returns the scattered moonlight contribution in nano-lambert, converted to ncd/m² and added linearly to the sky-brightness budget in brightness.py. The exact formulation matches the published equations (illuminance, Rayleigh + Mie scattering functions, optical-depth term) — no novel coefficients, no curve-fits.

Behaviour summary:

• Moon below horizon (moonAltitudeDeg < 0) ⇒ zero scattered contribution regardless of phase.
• Full Moon at zenith on a Bortle 1 site is brighter than full Moon at altitude 0°, as required by the Phase 0 spike's gate criteria.
• Target geometry comes from the active mode's target_altitude_policy (see §3).

Exposed at: physical.moonAltitudeDeg, physical.moonAzimuthDeg, physical.moonIllumination, physical.moonLuminance.

Phase 4 R3 physics.cloud_amplification

Implemented at stargazing/physics/clouds.py:

obstruction_probability(low, mid, high) -> float
cloud_base_height(low, mid, high)       -> float (km)
skyglow_amplification(L_artificial,
                      cloud_cover,
                      base_height_km)   -> float multiplier

The Kyba et al. 2015 multiplier [5] spans roughly 0.7× (clear) to 18× (overcast over a heavily lit basin), depending on the local artificial-brightness baseline and cloud base height. Low cloud over bright cities amplifies the most; high cirrus over a dark site barely changes things.

Cloud-cover ensemble inputs (ensemble.cloud_cover_low, cloud_cover_mid, cloud_cover_high) feed both functions per bin. The scoring path uses the obstruction probability as a sky-quality multiplier (stars blocked) and the amplification multiplier as a contributor to physical.totalSkyBrightnessCdm2 (sky brightened). The two effects are surfaced separately:

physical.cloudObstructionProbability  # 0..1
physical.cloudBaseHeightKm            # km
physical.kybaAmplification            # multiplier

This separation also lets the reasons panel distinguish "low clouds blocked your stars" from "cloud deck over the city made the sky 4× brighter" — same data, different physical phenomenon.

Phase 4 R6 physics.airmass_extinction

At stargazing/physics/extinction.py:

airmass(altitude_deg) -> float
    # Kasten & Young 1989 [20] — more accurate
    # than sec(z) at low altitudes.

extinction_coefficient(aod, dust, tcwv,
                       visibility, humidity_profile) -> float k
    # Combines aerosol optical depth (smoke, dust),
    # total column water vapor, and surface visibility
    # into a single mag/airmass coefficient.

Kasten–Young approximation (the actual formula in code):

X(z) = 1 / (cos(z) + 0.50572 * (96.07995 - z)^-1.6364)

The same k coefficient is applied to (a) light-pollution luminance traveling along the line of sight, (b) Krisciunas–Schaefer scattered moonlight, and (c) the transparency degrader. A wildfire that triples aerosol optical depth therefore degrades three independent terms through one coefficient — physically correct, and naturally surfaced through the same reason trace entry.

Fresh smoke nowcasts come from stargazing/providers/firms.py (NASA FIRMS active-fire data within 500 km upwind, used when AOD is stale > 6 h [15] [16]). Exposed at physical.aerosolOpticalDepth, physical.extinctionCoefficient, physical.targetAirmass, physical.targetAltitudeDeg.

Phase 4 R4

The pre-overhaul scoring.py:307 contained:

precip_ceiling = 1 - PoP / 100  # WRONG: dims sky quality

That line was deleted. PoP and QPF moved entirely into the feasibility track as risk terms, where they (a) lower usableMinutes when high, (b) emit a precip_risk reason of role risk with effect proportional to PoP × QPF, and (c) reduce finalScore only through the sky_quality × feasibility product.

The hard precipitation gate (active rain/snow) survives — when an ensemble reports precipitation_present at the target bin, that bin scores 0.01 and emits a precipitation reason of role gate per the NOAA NWS PoP definition [9].

NWS PoP definition (verbatim): "The probability of precipitation is the probability that measurable precipitation (≥ 0.01") will occur at any given point in the forecast area during the forecast period." A 40 % PoP is therefore an areal-coverage-weighted probability, not a sky-quality dimmer.

Phase 1 Phase 5 R10

Deterministic reason trace. stargazing/reasoner.py reads the component dict returned by compute_stargazing_indices and emits an ordered reasons[] array of {factor, role, effect, explanation} entries. Roles: gate (hard cap, e.g. active precip, daylight), risk (lowers usable minutes, e.g. PoP), degrader (reduces score, e.g. moonlight), uncertainty (widens CI, e.g. source disagreement). Identical inputs ⇒ identical reasons.

Source trace. Every score response includes sourceTrace[] with per-variable provenance: which provider, freshness in minutes, reported confidence. The frontend renders this as a collapsed "what fed this score" panel with freshness pills.

Model versioning. Every public response carries modelVersion: "2026.06.0" at the top level and persists with the record in data/forecasts.db. The forecast store schema bumped from v1 to v2 (Phase 3) with a read-time adapter (_adapt_v1_to_v2(payload)) so old shared links still resolve.

No more query log. stargazing/query_log.py was deleted; its observational role is subsumed by the residual store (§11) and forecast_store.

Phase 5 R12

Residual store. A new SQLite table inside the existing data/forecasts.db:

CREATE TABLE observations (
    forecast_id TEXT,
    observed_at TEXT,
    source TEXT,              -- "metar" | "asos" | "goes" | "noaa_obs"
    variable TEXT,            -- "cloud_cover_pct" | "visibility_m" |
                              -- "precip_present"
    observed_value REAL,
    predicted_value REAL,
    lead_time_minutes INTEGER,
    ingested_at TEXT,
    PRIMARY KEY (forecast_id, source, variable, observed_at)
)

Typed API at stargazing/calibration/store.py.

METAR/ASOS ingest. stargazing/calibration/metar_ingest.py polls aviationweather.gov every 6 h for the nearest reporting station to each scored query, joining observed cloud cover, visibility, and precipitation against the matching predicted values. Station coverage is airport-only — matches are by nearest within 100 km, with station ID + distance recorded for transparency.

GOES-R retrospective cloud (CONUS only). stargazing/calibration/goes_ingest.py pulls cloud optical depth gridded product from NOAA CLASS on a daily rolling 7-day window [10] [11].

Reliability dashboards. GET /calibration renders reliability diagrams (predicted probability vs observed frequency), MAE/RMSE by lead time, and false-clear vs false-bad rates (asymmetric weighting — false-clear is worse). The route is env-gated behind GOSTARGAZING_CALIBRATION_ENABLED=1 and returns 404 when disabled, so the dashboard is operator-internal.

Skill-table update. Weekly cron at stargazing/calibration/update_skill.py consumes the residual store, recomputes per-source per-variable MAE-weighted skill weights, and writes back to data/skill_table.json. Caps prevent any single source from dominating.

Model A/B framework. stargazing/calibration/ab.py runs candidate model versions in shadow mode against the active version; both scores are stored and scored retrospectively. Promotion is manual (a config.yaml setting), but the data to make the call is automated.

All five items are scaffolding-complete in the codebase: the ingestion-side data model, residual-store columns, and reasons-trace roles exist for each. The only missing pieces are the verified ingestion paths (user accounts + report submission for the first; device-pairing for the second; webhook auth + storage for the third), the threshold tuning for the additional modes, and the cron registration for the VIIRS update. None require algorithmic changes to land — they extend the existing provider abstraction (§4) rather than modifying it.