stargazing-core

Shared astronomical computation package for the stargazing toolchain — telescope optics, deep-sky catalog, and equipment presets used by both mcp-stargazing and stargazing-place-finder.

Installation

pip install stargazing-core

Requires Python ≥ 3.11.

Quick Start

from stargazing_core import TelescopeConfig, TelescopeOptics, TELESCOPE_PRESETS

# Look up a preset
config = TELESCOPE_PRESETS['seestar-s50']

# Compute derived optics
optics = config.compute_optics()
print(f'FOV: {optics.fov_width_deg:.1f}° × {optics.fov_height_deg:.1f}°')
# → FOV: 1.7° × 1.3°

Modules

Consumers

Public API

All symbols are importable from the top-level package:

from stargazing_core import (
    # Telescope
    TelescopeConfig, TelescopeOptics, TELESCOPE_PRESETS,
    # Deep-sky matching
    DeepSkyCatalog, load_objects,
    match_telescope_targets, filter_candidates_by_lst, score_deep_sky_objects,
    # Shooting plan
    ShootingPlan, ShootingSlot, generate_shooting_schedule,
    # Mosaic
    MosaicPanel, MosaicGrid, compute_mosaic_grid,
    # Celestial models
    CelestialPosition, RiseSet, MoonInfo, VisiblePlanet,
    # Astronomy
    calculate_moon_info, get_moon_altaz, get_visible_planets, identify_constellation,
    # Geometry
    GeoPoint, GeoBounds, TimeInfo, validate_coordinates,
    # Time grid
    generate_time_grid, find_rise_set_indices,
    # Pagination
    PaginatedResult,
)

Compatibility

generate_shooting_schedule interprets historical naive dusk/dawn strings as UTC. An explicit ISO UTC offset preserves the instant and is converted to UTC for scheduling, including altitude-curve alignment and moonset delay. The original input strings remain echoed in dusk/dawn; slot timestamps are UTC. A nonpositive interval yields an empty plan with zero duration and a warning. These source fixes need a package release before installed consumers receive them; no version publication is included in this change.

Target ranking computes positions for the requested observing night. Missing/non-finite photometry earns no surface-brightness bonus; telescope results represent unknown magnitudes as null and keep suitability scores finite. The filter matcher recognizes common SIMBAD type codes such as OpC, HII, G, and PN as well as English object types. These source corrections require a new core package release before installed consumers receive them.

Cross-repository CI

Changes to core run both consumer suites against a locally built core wheel. The shared baseline/candidate policy is documented in mcp-stargazing/docs/dependency-chain-ci.md.

Release

Version: 0.1.0 (PyPI)

Release process:

1. Bump version in pyproject.toml
2. Merge to main → auto-tag workflow creates vX.Y.Z tag
3. Tag push triggers release-pypi.yml → OIDC Trusted Publishing to PyPI
4. GitHub Release auto-generated

Development

uv sync
uv run pytest -v
uv run ruff format --check . && uv run ruff check .