ASTRA

ASTRA, the Agentic Schema for Transparent Research Analysis, is an open specification for describing a research analysis in one YAML file, astra.yaml. Your code says how the analysis runs; astra.yaml says what it is: its inputs and outputs, the methodological choices behind them, and the evidence for those choices. Anyone who picks up the work, an agent or a person, can read it without reading the code.

ASTRA doesn't depend on any tool. It has its own documentation, schema and releases at astra-spec.org; this page covers what you need to use it with the Lightcone Stack.

What an analysis recordsCopy Anchor Link

An ASTRA record is a graph: each element is a node, and the fields that name other elements are its edges. Here is a slice of one, an example from Price-Whelan & Bonaca (2018), Off the beaten path: Gaia reveals GD-1 stars outside of the main stream:

◈Prior insight

MWPotential2014: bulge, disk and NFW halo, 220 km/s at the Sun

Bovy 2015 · DOI and exact quote

▤Input

Koposov et al. distances

▤Input

Koposov et al. radial velocities

◇Decision

Milky Way potential

• Paper 2018 potential
• Gala Milky Way v1
• Gala Milky Way v2 ◈

◇Decision

Progenitor mass

• 10⁵ M_☉, losing mass
• 6 × 10⁴ M_☉

◆Output · data

Orbit fit

python fit_orbit.py--potential{decisions.potential}

◆Output · data

Particle-spray toy streams

python spray_stream.py--mass{decisions.progenitor_mass}

◆Output · figure

Figure 2: data vs toy streams

python plot_density.py--models{outputs.toy_streams}

●Finding

GD-1 is clumpier than smooth-potential models predict

density scatter 0.58, vs 0.31–0.44

Inputs feed the outputs that list them, and one output can feed another. Each decision parameterizes the outputs whose recipes use it, and an option can cite the prior insight that backs it; the filled options are each decision's default. A finding cites the outputs that support it.

Each element type in full:

DecisionsCopy Anchor Link

Results depend on choices, such as which data to include or which prior to assume. In most research code those choices sit in scattered scripts and in people's heads. In ASTRA each one is a decision: it lists the options you considered, records why the choice matters, and names the default. An output lists the decisions it depends on, and its recipe receives the chosen option:

outputs:
  - id: fit_params
    type: table
    format: csv
    description: Slope, intercept and scatter for the fitted relation.
    inputs: [catalog_data]
    decisions: [fit_method]
    recipe:
      command: >-
        python src/fit_period_luminosity.py
        --catalog {inputs.catalog_data}
        --method {decisions.fit_method}
        --out {output}

decisions:
  fit_method:
    label: Fitting method
    rationale: The fitting method determines how outliers influence the inferred relation.
    default: ordinary_least_squares
    options:
      ordinary_least_squares:
        label: Ordinary least squares
      robust_linear:
        label: Robust linear fit

An option can also list the prior insights that back it.

Prior insightsCopy Anchor Link

A prior insight records something the analysis takes from the literature: a claim, and the evidence for it. Each piece of evidence cites a paper by its DOI and quotes the exact sentence the claim rests on, with its page. In the example from Price-Whelan & Bonaca (2018), one of the Milky Way potential options rests on this insight from Bovy (2015):

prior_insights:
  mwpotential2014_composition:
    id: mwpotential2014_composition
    claim: >-
      galpy's MWPotential2014 is a three-component Milky Way model: a power-law bulge,
      a Miyamoto–Nagai disk and an NFW dark-matter halo, fit to dynamical data.
    created_at: '2026-09-10T13:30:00Z'
    evidence:
      - id: ev2
        doi: "10.1088/0067-0049/216/2/29"
        quote:
          exact: >-
            The galpy.potential module also contains a model MWPotential2014 for the
            Milky Way’s gravitational potential that is designed to provide a simple,
            easy-to-use model in cases where a realistic model for the Milky Way is
            required.
        location:
          page: 7

The astra command can check each quote against its paper: a quote that isn't in the paper fails validation.

What the analysis concludes goes into findings, which have the same shape as prior insights but cite the analysis's own outputs as their evidence, such as a figure or a table of results.

How the stack uses itCopy Anchor Link

• Agent Skills: the astra skill teaches your agent the format, so it writes and revises astra.yaml with you. A hook validates the file each time the agent saves it.
• Lightcone CLI: lc executes the recipes. Each output that lc runs needs a format, a recipe, and its inputs and decisions declared; its file lands in results/, next to a manifest that records how it was made.
• MySTRA: the report refers to outputs, decisions and values by their path in astra.yaml, rather than copying them.
• Lightcone Lab: the workbench shows the analysis as an inventory and a pipeline.

Keep the version: field that lc init writes: it is the version of the ASTRA schema, separate from the version of any tool.

The astra commandCopy Anchor Link

astra-tools provides the astra command, which validates and inspects a specification. Install it with uv, at the version the current Lightcone CLI expects:

uv tool install astra-tools@0.2.18

Then run it from your project directory:

astra validate
astra info

With no file name, validate checks every specification file in the project.

To check the quotes in your evidence, add each cited paper to astra's local cache, then validate with --verify-evidence:

astra paper add 10.1088/0067-0049/216/2/29 --pdf bovy2015.pdf
astra validate astra.yaml --verify-evidence

Without --pdf, paper add downloads the paper itself: arXiv DOIs straight from arXiv, and other DOIs from an open-access copy when one exists. Publisher DOIs often have none, as for Bovy (2015) above, so download the PDF yourself and register it with --pdf. Evidence that cites the analysis's own outputs is skipped until those outputs exist.

The agent plugin runs astra with its own pinned version, so you only need to install it to check things yourself.

Learn moreCopy Anchor Link

• Getting started with ASTRA: the format on its own, without Lightcone.
• Specification reference: every element and field.
• CLI reference: validation, inspection and paper tools.