Stellarhound — stargazing forecasts, dark-sky sites & aurora

Compute astrophotography field of view, image scale, diffraction limits, and seeing sampling (fov-v1). Use when the user asks "will M31 fit in my telescope + camera", "what is the image scale of an RedCat 51 / Askar SQA55 / EdgeHD 8 with an ASI2600MC", or "am I undersampled or oversampled". Uses Stellarhound's deterministic fov-v1 rules (exact 2*atan(s / 2f) field of view, 206.265*pixel_um/f_mm image scale, Dawes 116/D and Rayleigh 138/D limits, and Nyquist 2-3 px/FWHM sampling bands across 1.5", 2.0", 2.5", 3.0" seeing). Args: focal_length_mm: Effective focal length in mm (include reducer/barlow factor if used, >0). aperture_mm: Clear aperture diameter in mm (>0). sensor_w_mm: Sensor width in mm (>0). sensor_h_mm: Sensor height in mm (>0). pixel_um: Pixel pitch in micrometres (>0, optional). Returns {rules_version, fov_w_deg, fov_h_deg, fov_diag_deg, fov_w_arcmin, fov_h_arcmin, f_ratio, scale_arcsec_px, dawes_arcsec, rayleigh_arcsec, sampling:[{fwhm_arcsec, px_per_fwhm, verdict}], source_url, citation}.

Recommend dark-sky sites near a location, ranked by whether the drive is worth it. Use for "where should I drive to stargaze near X". Sites are grouped by drivability (how far), then ranked by a drive-worth score combining the best weather window over the next 7 nights, how much darker the site is than the user's location, and drive time. Drive times are approximate (straight-line x 1.3), not routed. Args: lat: Latitude in decimal degrees (-90..90). lon: Longitude in decimal degrees (-180..180). limit: Max sites to return, 1-12 (default 5). Returns {ranking (methodology note), tiers:[{tier, label, hint, sites:[...]}], nearest_km, uncertainty_note, attribution} — sites grouped into drivability tiers. Include the methodology note when presenting — it explains the ordering honestly.

Get the aurora (northern/southern lights) outlook for a location. Use for "any chance of aurora tonight near X". Combines the Kp-index forecast with the location's geomagnetic latitude to say whether aurora could be visible there, and when. Args: lat: Latitude in decimal degrees (-90..90). lon: Longitude in decimal degrees (-180..180). Returns {kp_forecast:[{time, kp, flag: observed|estimated|predicted}, ...], visibility assessment fields, attribution}. Kp entries are flagged by how firm they are — keep those labels when presenting.

Estimate light pollution at any point: approximate Bortle class and what's visible there. Use for "how dark is the sky at X" / "can I see the Milky Way from X". Returns the zenith-brightness-derived estimate (mpsas, approximate Bortle class) and a plain-language ceiling: what the Milky Way, naked-eye and telescope views are like under that sky. This is a satellite-data estimate, not a field measurement — say so. Args: lat: Latitude in decimal degrees (-90..90). lon: Longitude in decimal degrees (-180..180). Returns {light_pollution:{bortle_approx, mpsas, ceiling:{label, milky_way, naked_eye, telescope}, note}, attribution}.

Score the next nights for stargazing at a location (0-100 per night). Use for "when should I stargaze this week near X", "is Saturday any good for the Milky Way", trip planning. Each night combines the three-layer cloud-cover forecast, moon illumination and up-fraction, and the astronomical-darkness window; `best_window` names the best upcoming night. Also returns the location's light-pollution estimate (approximate Bortle class + what's visible at that darkness). Args: lat: Latitude in decimal degrees (-90..90). You know city coordinates — pass them. lon: Longitude in decimal degrees (-180..180). nights: How many nights ahead to score, 1-16 (default 7; forecasts beyond ~7 nights are increasingly uncertain). Returns {timezone, light_pollution, nights:[{date, darkness, moon, cloud, score:{value, band, summary}}], best_window, uncertainty_note, attribution}. Present scores/verdicts verbatim; skies beyond ~7 days are provisional.

Get tonight's stargazing plan for a location: score, darkness window, and what to observe. Use when the user asks "what can I see tonight" / "is tonight worth going out". Returns tonight's sky score and darkness window plus a ranked agenda of observing targets appropriate for the location's sky darkness. Args: lat: Latitude in decimal degrees (-90..90). lon: Longitude in decimal degrees (-180..180). Returns {timezone, light_pollution, tonight:{date, darkness, weather,...}, targets/agenda entries, attribution}. Report as returned.