Metadata-Version: 2.4
Name: starfyi
Version: 0.1.1
Summary: Stars, constellations and astronomy API client — starfyi.com
Project-URL: Homepage, https://starfyi.com
Project-URL: Documentation, https://starfyi.com/developers/
Project-URL: Repository, https://github.com/fyipedia/starfyi
Project-URL: Issues, https://github.com/fyipedia/starfyi/issues
Project-URL: Changelog, https://github.com/fyipedia/starfyi/releases
Author: FYIPedia
License-Expression: MIT
License-File: LICENSE
Keywords: astronomy,astrophysics,constellation,cosmos,deep-sky,exoplanet,star,telescope
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: typer>=0.15; extra == 'all'
Provides-Extra: api
Requires-Dist: httpx>=0.27; extra == 'api'
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == 'cli'
Requires-Dist: typer>=0.15; extra == 'cli'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# starfyi

[![PyPI version](https://agentgif.com/badge/pypi/starfyi/version.svg)](https://pypi.org/project/starfyi/)
[![Python](https://img.shields.io/pypi/pyversions/starfyi)](https://pypi.org/project/starfyi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/starfyi/)

Python API client and CLI for stars, constellations, exoplanets, and deep-sky objects. Access 119,602 stars with spectral classifications and magnitudes, 20 constellations with mythology and star charts, 6,128 confirmed exoplanets, and 13,305 deep-sky objects (nebulae, galaxies, clusters) — all with zero dependencies.

Extracted from [StarFYI](https://starfyi.com/), an astronomy reference platform with 195 glossary terms, 65 educational guides, 7 spectral classes, and interactive sky maps for astronomers, astrophysics students, and developers building astronomy applications.

> **Explore the cosmos at [starfyi.com](https://starfyi.com/)** — browse the [star catalog](https://starfyi.com/stars/), explore [constellations](https://starfyi.com/constellations/), discover [exoplanets](https://starfyi.com/exoplanets/), and search [deep-sky objects](https://starfyi.com/deep-sky/).

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/starfyi/main/demo.gif" alt="starfyi demo — star lookup, spectral classification, and constellation browsing in Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [Stars & Stellar Classification](#stars--stellar-classification)
  - [Constellations](#constellations)
  - [Exoplanets](#exoplanets)
  - [Deep-Sky Objects](#deep-sky-objects)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [API Reference](#api-reference)
- [Learn More About Astronomy](#learn-more-about-astronomy)
- [Also Available](#also-available)
- [Science FYI Family](#science-fyi-family)
- [FYIPedia Developer Tools](#fyipedia-developer-tools)
- [License](#license)

## Install

```bash
pip install starfyi                # Core (zero deps)
pip install "starfyi[cli]"         # + Command-line interface (typer, rich)
pip install "starfyi[mcp]"         # + MCP server for AI assistants
pip install "starfyi[api]"         # + HTTP client for starfyi.com API
pip install "starfyi[all]"         # Everything
```

Or run instantly without installing:

```bash
uvx --from starfyi starfyi search sirius
```

## Quick Start

```python
from starfyi.api import StarFYI

with StarFYI() as api:
    # Look up any star by name — 119,602 stars in the catalog
    sirius = api.get_star("sirius")
    print(sirius["name"])            # Sirius
    print(sirius["magnitude"])       # -1.44 (brightest star in the night sky)
    print(sirius["distance_ly"])     # 8.60 light-years
    print(sirius["spectral_class"])  # a (A-type main sequence)
    print(sirius["constellation"])   # canis-major

    # Browse constellations, exoplanets, deep-sky objects
    constellations = api.list_constellations()
    exoplanets = api.list_exoplanets(limit=10)
    deep_sky = api.list_deep_sky(limit=10)
```

## What You Can Do

### Stars & Stellar Classification

The star catalog contains **119,602 stars** with positions, magnitudes, distances, and spectral classifications. Stars are classified using the **Morgan-Keenan (MK) system**, which sorts stars by surface temperature into 7 spectral classes. The famous mnemonic "Oh Be A Fine Guy/Girl, Kiss Me" helps remember the sequence from hottest to coolest.

| Spectral Class | Temperature (K) | Color | Examples |
|---------------|----------------|-------|---------|
| **O** | 30,000-50,000+ | Blue | Naos, Mintaka (rare, <0.003% of stars) |
| **B** | 10,000-30,000 | Blue-white | Rigel, Spica, Regulus |
| **A** | 7,500-10,000 | White | Sirius, Vega, Altair, Fomalhaut |
| **F** | 6,000-7,500 | Yellow-white | Canopus, Procyon, Polaris |
| **G** | 5,200-6,000 | Yellow | Sun, Alpha Centauri A, Capella |
| **K** | 3,700-5,200 | Orange | Arcturus, Aldebaran, Epsilon Eridani |
| **M** | 2,400-3,700 | Red | Betelgeuse, Proxima Centauri (75% of stars) |

Each star record includes apparent magnitude (brightness as seen from Earth), absolute magnitude (intrinsic luminosity at 10 parsecs), right ascension and declination (celestial coordinates), color index (B-V), and distance in light-years.

```python
from starfyi.api import StarFYI

with StarFYI() as api:
    # Look up Sirius — brightest star in the night sky
    sirius = api.get_star("sirius")
    print(sirius["magnitude"])            # -1.44 (apparent magnitude)
    print(sirius["absolute_magnitude"])   # 1.45
    print(sirius["distance_ly"])          # 8.60 light-years
    print(sirius["spectral_class"])       # a (A-type)
    print(sirius["color_index"])          # 0.009 (blue-white)
    print(sirius["ra_hours"])             # 6 (right ascension)
    print(sirius["dec_degrees"])          # -16 (declination)

    # List all 7 spectral classes
    classes = api.list_spectral_classes()
    for sc in classes["results"]:
        print(sc["letter"])  # O, B, A, F, G, K, M
```

Learn more: [Star Catalog](https://starfyi.com/stars/) · [Spectral Classes](https://starfyi.com/spectral-classes/) · [Astronomy Glossary](https://starfyi.com/glossary/)

### Constellations

Explore **20 major constellations** with mythology, notable stars, deep-sky objects, and observation guides. The 88 modern constellations recognized by the International Astronomical Union (IAU) divide the celestial sphere into regions, with these 20 being the most prominent and widely recognized.

| Constellation | Season | Notable Stars | Key Objects |
|--------------|--------|---------------|-------------|
| **Orion** | Winter | Betelgeuse, Rigel, Bellatrix | Orion Nebula (M42) |
| **Ursa Major** | Year-round (N) | Dubhe, Merak, Alioth | Big Dipper asterism |
| **Scorpius** | Summer | Antares, Shaula, Sargas | Butterfly Cluster (M6) |
| **Leo** | Spring | Regulus, Denebola | Leo Triplet galaxies |
| **Cygnus** | Summer | Deneb, Albireo | North America Nebula |
| **Cassiopeia** | Year-round (N) | Schedar, Caph | Heart and Soul Nebulae |
| **Sagittarius** | Summer | Kaus Australis, Nunki | Galactic center, M8 Lagoon |
| **Lyra** | Summer | Vega | Ring Nebula (M57) |
| **Crux** | Year-round (S) | Acrux, Mimosa | Jewel Box Cluster |
| **Taurus** | Winter | Aldebaran | Pleiades (M45), Crab Nebula |

```python
from starfyi.api import StarFYI

with StarFYI() as api:
    # Browse 20 constellations
    constellations = api.list_constellations()
    for c in constellations["results"]:
        print(c["slug"])  # orion, ursa-major, scorpius, ...

    # Get constellation detail with star lists and mythology
    orion = api.get_constellation("orion")
    print(orion)
```

Learn more: [Constellations](https://starfyi.com/constellations/) · [Astronomy Guides](https://starfyi.com/guides/)

### Exoplanets

StarFYI catalogs **6,128 confirmed exoplanets** — planets orbiting stars beyond our solar system. Since the first confirmed detection in 1992 (PSR B1257+12 system) and the first around a Sun-like star in 1995 (51 Pegasi b), exoplanet science has revealed that planetary systems are common throughout the Milky Way.

Detection methods include transit photometry (Kepler, TESS), radial velocity (Doppler spectroscopy), direct imaging, gravitational microlensing, and astrometry. The majority of known exoplanets have been discovered by the Kepler space telescope and its successor TESS.

```python
from starfyi.api import StarFYI

with StarFYI() as api:
    # Browse 6,128 confirmed exoplanets
    exoplanets = api.list_exoplanets(limit=10)
    print(exoplanets["count"])  # 6128

    # Get exoplanet detail
    detail = api.get_exoplanet("kepler-442-b")
    print(detail)
```

Learn more: [Exoplanet Catalog](https://starfyi.com/exoplanets/) · [Astronomy Glossary](https://starfyi.com/glossary/)

### Deep-Sky Objects

Explore **13,305 deep-sky objects** — nebulae, galaxies, star clusters, and other extended astronomical objects beyond the solar system. The catalog includes objects from the Messier catalog (110 objects), the New General Catalogue (NGC, 7,840 objects), and the Index Catalogue (IC, 5,386 objects).

| Type | Description | Famous Examples |
|------|-------------|----------------|
| **Emission Nebula** | Ionized gas emitting light | Orion Nebula (M42), Eagle Nebula (M16) |
| **Planetary Nebula** | Expelled stellar atmosphere | Ring Nebula (M57), Helix Nebula (NGC 7293) |
| **Reflection Nebula** | Dust reflecting starlight | Witch Head, Pleiades haze |
| **Open Cluster** | Young, loosely bound stars | Pleiades (M45), Hyades |
| **Globular Cluster** | Ancient, densely packed stars | Omega Centauri, M13 (Hercules) |
| **Spiral Galaxy** | Rotating disk with arms | Andromeda (M31), Whirlpool (M51) |
| **Elliptical Galaxy** | Smooth, featureless profile | M87 (Virgo A), M32 |

```python
from starfyi.api import StarFYI

with StarFYI() as api:
    # Browse 13,305 deep-sky objects
    dso = api.list_deep_sky(limit=10)
    print(dso["count"])  # 13305

    # Get deep-sky object detail
    detail = api.get_deep_sky("m42")
    print(detail)
```

Learn more: [Deep-Sky Objects](https://starfyi.com/deep-sky/) · [Astronomy Guides](https://starfyi.com/guides/)

## Command-Line Interface

```bash
pip install "starfyi[cli]"

starfyi search sirius               # Search stars by name
starfyi search "orion nebula"        # Search deep-sky objects
starfyi search kepler                # Search exoplanets
```

## MCP Server (Claude, Cursor, Windsurf)

Add astronomy lookup tools to any AI assistant that supports [Model Context Protocol](https://modelcontextprotocol.io/).

```bash
pip install "starfyi[mcp]"
```

Add to your `claude_desktop_config.json`:

```json
{
    "mcpServers": {
        "starfyi": {
            "command": "uvx",
            "args": ["--from", "starfyi[mcp]", "python", "-m", "starfyi.mcp_server"]
        }
    }
}
```

## REST API Client

```bash
pip install "starfyi[api]"
```

```python
from starfyi.api import StarFYI

with StarFYI() as api:
    stars = api.list_stars()                    # GET /api/v1/stars/
    sirius = api.get_star("sirius")            # GET /api/v1/stars/sirius/
    constellations = api.list_constellations()  # GET /api/v1/constellations/
    exoplanets = api.list_exoplanets()          # GET /api/v1/exoplanets/
    deep_sky = api.list_deep_sky()              # GET /api/v1/deep-sky/
    results = api.search("betelgeuse")          # GET /api/v1/search/?q=betelgeuse
```

### Example

```bash
curl -s "https://starfyi.com/api/v1/stars/sirius/"
```

```json
{
  "name": "Sirius",
  "slug": "sirius",
  "constellation": "canis-major",
  "spectral_class": "a",
  "spectral_class_letter": "A",
  "magnitude": "-1.44",
  "absolute_magnitude": "1.45",
  "distance_ly": "8.60",
  "color_index": "0.009",
  "ra_hours": 6,
  "dec_degrees": -16,
  "is_featured": true
}
```

Full API documentation at [starfyi.com/developers/](https://starfyi.com/developers/).

## API Reference

| Method | Description |
|--------|-------------|
| `list_stars(**params)` | List 119,602 stars with pagination |
| `get_star(slug)` | Get star detail with position and spectral data |
| `list_constellations(**params)` | List 20 constellations |
| `get_constellation(slug)` | Get constellation detail with mythology and stars |
| `list_exoplanets(**params)` | List 6,128 confirmed exoplanets |
| `get_exoplanet(slug)` | Get exoplanet detail |
| `list_deep_sky(**params)` | List 13,305 deep-sky objects |
| `get_deep_sky(slug)` | Get deep-sky object detail |
| `list_spectral_classes(**params)` | List 7 spectral classes (O, B, A, F, G, K, M) |
| `get_spectral_classe(slug)` | Get spectral class detail |
| `list_comparisons(**params)` | List star comparisons |
| `get_comparison(slug)` | Get side-by-side comparison |
| `list_glossary(**params)` | List 195 astronomy glossary terms |
| `get_term(slug)` | Get glossary term definition |
| `list_guides(**params)` | List 65 educational guides |
| `get_guide(slug)` | Get guide content |
| `search(query)` | Search across all astronomy content |

## Learn More About Astronomy

- **Browse**: [Star Catalog](https://starfyi.com/stars/) · [Constellations](https://starfyi.com/constellations/) · [Exoplanets](https://starfyi.com/exoplanets/) · [Deep-Sky Objects](https://starfyi.com/deep-sky/)
- **Classification**: [Spectral Classes](https://starfyi.com/spectral-classes/)
- **Reference**: [Astronomy Glossary](https://starfyi.com/glossary/)
- **Guides**: [Educational Guides](https://starfyi.com/guides/)
- **API**: [REST API Docs](https://starfyi.com/developers/) · [OpenAPI Spec](https://starfyi.com/api/v1/)

## Also Available

| Platform | Install | Link |
|----------|---------|------|
| **npm** | `npm install starfyi` | [npm](https://www.npmjs.com/package/starfyi) |
| **MCP** | `uvx --from "starfyi[mcp]" python -m starfyi.mcp_server` | [Config](#mcp-server-claude-cursor-windsurf) |

## Science FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem — physical sciences, chemistry, geology, astronomy, and materials.

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| chemfyi | [PyPI](https://pypi.org/project/chemfyi/) | [npm](https://www.npmjs.com/package/chemfyi) | Periodic table, 500 compounds, 371 reactions — [chemfyi.com](https://chemfyi.com/) |
| alloyfyi | [PyPI](https://pypi.org/project/alloyfyi/) | [npm](https://www.npmjs.com/package/alloyfyi) | 765 metal alloys, 12 families, compositions — [alloyfyi.com](https://alloyfyi.com/) |
| gemfyi | [PyPI](https://pypi.org/project/gemfyi/) | [npm](https://www.npmjs.com/package/gemfyi) | 442 gemstones, Mohs scale, grading — [gemfyi.com](https://gemfyi.com/) |
| **starfyi** | [PyPI](https://pypi.org/project/starfyi/) | [npm](https://www.npmjs.com/package/starfyi) | **119,602 stars, 6,128 exoplanets, 13,305 deep-sky objects — [starfyi.com](https://starfyi.com/)** |
| mineralfyi | [PyPI](https://pypi.org/project/mineralfyi/) | [npm](https://www.npmjs.com/package/mineralfyi) | 6,215 minerals, 7 crystal systems — [mineralfyi.com](https://mineralfyi.com/) |

## FYIPedia Developer Tools

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| colorfyi | [PyPI](https://pypi.org/project/colorfyi/) | [npm](https://www.npmjs.com/package/@fyipedia/colorfyi) | Color conversion, WCAG contrast, harmonies — [colorfyi.com](https://colorfyi.com/) |
| emojifyi | [PyPI](https://pypi.org/project/emojifyi/) | [npm](https://www.npmjs.com/package/emojifyi) | Emoji encoding & metadata for 3,953 emojis — [emojifyi.com](https://emojifyi.com/) |
| symbolfyi | [PyPI](https://pypi.org/project/symbolfyi/) | [npm](https://www.npmjs.com/package/symbolfyi) | Symbol encoding in 11 formats — [symbolfyi.com](https://symbolfyi.com/) |
| unicodefyi | [PyPI](https://pypi.org/project/unicodefyi/) | [npm](https://www.npmjs.com/package/unicodefyi) | Unicode lookup with 17 encodings — [unicodefyi.com](https://unicodefyi.com/) |
| fontfyi | [PyPI](https://pypi.org/project/fontfyi/) | [npm](https://www.npmjs.com/package/fontfyi) | Google Fonts metadata & CSS — [fontfyi.com](https://fontfyi.com/) |
| distancefyi | [PyPI](https://pypi.org/project/distancefyi/) | [npm](https://www.npmjs.com/package/distancefyi) | Haversine distance & travel times — [distancefyi.com](https://distancefyi.com/) |
| timefyi | [PyPI](https://pypi.org/project/timefyi/) | [npm](https://www.npmjs.com/package/timefyi) | Timezone ops & business hours — [timefyi.com](https://timefyi.com/) |
| namefyi | [PyPI](https://pypi.org/project/namefyi/) | [npm](https://www.npmjs.com/package/namefyi) | Korean romanization & Five Elements — [namefyi.com](https://namefyi.com/) |
| unitfyi | [PyPI](https://pypi.org/project/unitfyi/) | [npm](https://www.npmjs.com/package/unitfyi) | Unit conversion, 220 units — [unitfyi.com](https://unitfyi.com/) |
| holidayfyi | [PyPI](https://pypi.org/project/holidayfyi/) | [npm](https://www.npmjs.com/package/holidayfyi) | Holiday dates & Easter calculation — [holidayfyi.com](https://holidayfyi.com/) |
| cocktailfyi | [PyPI](https://pypi.org/project/cocktailfyi/) | — | Cocktail ABV, calories, flavor — [cocktailfyi.com](https://cocktailfyi.com/) |
| fyipedia | [PyPI](https://pypi.org/project/fyipedia/) | — | Unified CLI: `fyi star info sirius` — [fyipedia.com](https://fyipedia.com/) |
| fyipedia-mcp | [PyPI](https://pypi.org/project/fyipedia-mcp/) | — | Unified MCP hub for AI assistants — [fyipedia.com](https://fyipedia.com/) |

## License

MIT
