# ASTRA

> A declarative YAML specification for scientific analyses that captures inputs, outputs, decisions, and evidence to make research reproducible and auditable by agents and humans alike.

ASTRA (Agentic Schema for Transparent Research Analysis) is an open-source YAML specification developed by Lightcone Research for structuring scientific analyses. It separates *what* you want to learn from *how* to compute it, giving every methodological choice an explicit, machine-readable place in the record. The project is currently in early alpha (v0.0.10), with breaking changes expected between minor versions.

## What It Is

ASTRA is a structured format — centered on an `astra.yaml` file — that captures every consequential choice in a scientific analysis: its inputs, outputs, decisions, and the evidence behind them. The core insight is that code captures execution but not the full structure of an analysis; notebooks and scripts scatter methodological choices across comments and memory, making results hard to reproduce, audit, or extend. ASTRA addresses this by making decisions explicit: each decision names the options that were considered, links to evidence, and feeds into a *universe* — a record of results for a given set of choices. The spec is intentionally agnostic to the execution harness, so agents, workflow runners, and humans can all read and act on the same file.

## Core Concepts

- **Analysis (`astra.yaml`)**: Declares the design space — inputs, outputs, and decisions with their options and rationale.
- **Universe**: A companion YAML file that picks one option per decision, yielding one set of results. A single analysis can carry many universes.
- **Decisions**: Named methodological choices (e.g., fitting method, feature scaling) with explicit options, defaults, and optional dependency constraints between options.
- **Recipes**: Commands attached to outputs that reference inputs and decisions, making the execution path traceable.

## CLI and Tooling

The `astra-tools` Python package (installable via `uv tool install astra-tools`) provides the `astra` CLI with commands for validation (`astra validate`), inspection (`astra info`), and visualization (`astra viz`). The schema itself is defined in LinkML and generates multi-language bindings including Python, TypeScript, JSON Schema, JSON-LD, OWL, and Java. The schema and code are licensed separately: the schema under CC BY 4.0 and the code under BSD 3-Clause, both permissive for commercial and academic use.

## Repository Architecture

The `astra-spec` repository holds the LinkML schema source and documentation site. The Python CLI and SDK (`astra-tools`) live in a separate repository (`LightconeResearch/astra-tools`), sharing the `astra.*` Python namespace via PEP 420. The project requires Python 3.9+, `uv`, and `just` for development. Versioned documentation is published to GitHub Pages via `mike`, with each release tagged and injected into generated artifacts at build time.

## Update: v0.0.10

The latest release is v0.0.10, published on 2026-05-08, with the repository last updated on 2026-05-15. The project is in active early-alpha development — the schema, CLI, and tooling are all still evolving. The maintainers explicitly warn users to pin the schema version in their analyses and to expect breaking changes between minor versions. The project is soliciting bug reports, design challenges, and use cases via GitHub issues and a community forum, and is connected to the Agentic AI 4 Science Developer Summit organized by Lightcone Research.

## Features
- Declarative YAML specification for scientific analyses
- Explicit methodological decision tracking with options and rationale
- Universe system for recording results per decision configuration
- CLI for validation, inspection, and visualization (astra-tools)
- Execution-harness agnostic design
- LinkML schema with multi-language bindings (Python, TypeScript, JSON Schema, JSON-LD, OWL, Java)
- Versioned schema with pinning support
- Reproducible and auditable experiment records
- Evidence linking for methodological choices
- Recipe system for traceable output commands

## Integrations
Python, uv, LinkML, PyPI, GitHub Actions, JSON Schema, JSON-LD, OWL

## Platforms
CLI, API, DEVELOPER_SDK

## Pricing
Open Source

## Version
v0.0.10

## Links
- Website: https://astra-spec.org
- Documentation: https://astra-spec.org/latest/
- Repository: https://github.com/LightconeResearch/astra-spec
- EveryDev.ai: https://www.everydev.ai/tools/astra-spec