gcn-circular-llm 0.1.0

Extract structured astrophysical information from NASA GCN circulars using an LLM via OpenRouter.

GCN Circular Parser

This is a light-weight package for extracting structured astrophysical information from NASA GCN circulars using an LLM via OpenRouter.

Features

• Fetch all circulars for a given event from the GCN archive
• Extract structured fields with an LLM: coordinates, redshift, host galaxy, classification, flux/magnitude measurements, observations, references, and a one-sentence summary
• Export magnitude/flux measurements across all circulars into a single time-sorted CSV light-curve table

Installation

git clone [e-mail]:LAujust/gcn_parser.git
cd gcn_parser
pip install -e .

Or install directly without cloning:

pip install git+https://github.com/LAujust/gcn_parser.git

Configuration

Set your OpenRouter API key:

export OPENROUTER_API_KEY=sk-or-v1-...

Or create a .env file (see .env.example).

Usage

Run the CLI for an event identifier:

# JSON to stdout
gcn-parser GRB250101A

# Save JSON and CSV light-curve
gcn-parser GRB250101A -o output.json --csv lightcurve.csv

# Use a different model
gcn-parser GRB250101A -m openai/gpt-4o

You can also run it as a module:

python -m gcn_parser GRB250101A

Output

JSON

Each circular is an object containing the GCN number and the extracted fields.

[
  {
    "gcn": "GCN 12345",
    "extraction": {
      "event_type": "GRB",
      "coordinates": {
        "ra": "12:34:56.78",
        "dec": "+12:34:56.7",
        "system": "J2000",
        "error_arcsec": 1.2
      },
      "redshift": 0.5,
      "host_galaxy": "Host Galaxy Name",
      "classification": "Long GRB",
      "flux_magnitude": [
        {
          "value": 18.5,
          "band": "r",
          "instrument": "ZTF",
          "utc": "2025-01-01T12:00:00Z",
          "mjd": null,
          "unit": "AB mag",
          "upper_limit": false
        }
      ],
      "observations": ["Swift/XRT follow-up"],
      "references": ["GCN 12344"],
      "confidence": "high",
      "summary": "..."
    }
  }
]

CSV Light-Curve

The --csv option aggregates all flux_magnitude measurements across circulars into a single table:

Column	Description
gcn_number	Source circular
utc	Observation time in ISO-8601 UTC
mjd	Modified Julian Date (optional)
value	Numeric measurement
unit	e.g. mag, AB mag, erg cm^-2 s^-1
band	Photometric band
instrument	Telescope or instrument
upper_limit	true if upper limit

Rows are sorted by date.

Project Structure

gcn_parser/
├── archive.py       # Fetch circulars from GCN archive
├── models.py        # Pydantic schema for structured extraction
├── extractor.py     # OpenRouter LLM client and prompt
├── csv_export.py    # Flatten measurements to CSV
├── cli.py           # argparse CLI entry point
└── __main__.py      # Enables `python -m gcn_parser`

Default Model

minimax/minimax-m2.5:free via OpenRouter.

License

This project is licensed under the MIT License. See LICENSE for details.