Skip to content

Gaia Lang v0.5.0a1 Alpha Release Notes

Gaia Lang v0.5.0a1 is the first public alpha preview of the v0.5 release line. It is intended for Gaia package authors, contributors, and early adopters who want to test the new authoring, inference, Bayes, rendering, and package workflow before the v0.5 API is frozen.

This is not a stable release. Command names, Python import surfaces, Bayes helpers, review tooling, and package workflow details may still change before beta.

Install

Use a fresh Python 3.12+ environment:

python -m venv /tmp/gaia-v05-alpha
source /tmp/gaia-v05-alpha/bin/activate
pip install gaia-lang==0.5.0a1

Or, if you intentionally allow prereleases:

pip install --pre gaia-lang

After installation, include gaia --version output in bug reports:

gaia --version

The alpha wheel should report gaia-lang 0.5.0a1, channel: a, the source commit used to build the wheel, and the current IR schema string.

Release provenance:

Who Should Try This

Try this alpha if you are:

  • building or migrating Gaia knowledge packages
  • testing the grouped v0.5 CLI
  • evaluating the new gaia.engine.* Python import surface
  • trying the Bayes model/compare workflow on real examples
  • helping find stale documentation, migration gaps, or package-corpus failures

Stay on gaia-lang==0.4.4 if you need the current stable install target or do not want to adjust package code yet.

Major Changes Since v0.4

Grouped CLI Surface

The old flat CLI verbs are no longer the primary interface. v0.5 organizes the CLI by workflow:

  • gaia build ... for package initialization, compilation, and checking
  • gaia run ... for inference and rendering
  • gaia inspect ... for graph inspection
  • gaia pkg ... for package dependencies, scaffolds, and registration
  • gaia author ... for agent-friendly DSL authoring
  • gaia bayes ... for Bayes model and distribution helpers
  • gaia inquiry ... and gaia trace ... for local review/debugging workflows

See Migration to alpha 0 for the old-to-new command mapping.

Canonical gaia.engine.* Python API

The canonical Python API now lives under gaia.engine.*. The historical top-level namespaces such as gaia.lang, gaia.bp, and gaia.ir are not the v0.5 contract. Existing packages should update imports to the new engine facades, for example:

from gaia.engine.lang import claim, derive, note, observe

The engine facades are documented under Gaia Engine API.

Agent-Friendly Authoring

v0.5 adds a structured authoring surface for agents and humans who want to modify packages without hand-editing every DSL statement:

  • gaia author claim
  • gaia author observe
  • gaia author derive
  • gaia author compute
  • gaia author infer
  • gaia author compose
  • gaia pkg scaffold
  • gaia pkg add-module
  • gaia pkg add-import

This surface is useful for reproducible package edits, but it is still alpha. Please report confusing command output, unsafe prewrite behavior, or generated source that is hard to review.

Unified Bayes Model Comparison

The Bayes surface has moved toward a clearer model/data comparison contract:

  • define parameter-value hypotheses with parameter(...)
  • define predictive models with bayes.model(...)
  • record observations with observe(...)
  • compare competing models with bayes.compare(...)
  • use distribution factories such as Binomial, BetaBinomial, and Normal from gaia.engine.lang

The Mendel example package exercises this path with a Bayesian comparison between Mendelian segregation and a diffuse alternative. See Bayes Module And Continuous Quantities.

Package Corpus Validation

The release pipeline validates real Gaia packages, not only unit tests. The locked alpha corpus currently includes:

  • examples/galileo-v0-5-gaia
  • examples/mendel-v0-5-gaia

For each package, the corpus runner checks that Gaia can compile, structurally check, infer, and render docs/GitHub/Obsidian outputs. The corpus gate does not yet require every review warrant to be accepted; ReviewManifest remains an alpha preview rather than a complete publication ecosystem.

ReviewManifest And Quality Gate Preview

v0.5 includes local plumbing for action-level review state through ReviewManifest, gaia build check --warrants, gaia inquiry review, and gaia build check --gate.

This is an alpha preview, not a finished reviewer ecosystem. The mechanism can generate and consume .gaia/review_manifest.json, and the quality gate is useful for local package hardening. However, the end-to-end author/reviewer workflow, registry-level reviewer assignment, and smooth package-publication policy are still being hardened.

Important caveats for v0.5.0a1:

  • release corpus validation does not currently require accepted .gaia/review_manifest.json entries
  • local preview inference can run without treating review status as a hard gate
  • gaia review is a help-visible skeleton, while gaia inquiry review is the current local review command
  • review UX and docs are expected to change before beta

Treat this as an experimental integrity layer and report cases where the gate is unclear, too strict, or hard to satisfy.

Breaking Changes And Migration Notes

v0.5 is a breaking release line relative to v0.4.

Expected migration work:

  • update flat CLI invocations such as gaia compile to grouped commands such as gaia build compile
  • update imports to gaia.engine.*
  • recompile .gaia/ir.json and .gaia/ir_hash with v0.5
  • rerun gaia build check, gaia run infer, and render commands before comparing output to older package artifacts
  • move new code away from legacy compatibility helpers and toward claim, note, derive, compute, infer, relation verbs, and the Bayes model/compare surface

See Migration to alpha 0 for detailed command and import tables.

Known Limitations

  • v0.5.0a1 is an alpha release; APIs and semantics may change before beta.
  • The review ecosystem is local and experimental; registry-level review assignment is not complete.
  • Some downstream packages will require import-path and CLI-command migration.
  • Bayes model comparison is ready for early testing, but external backend adapters and richer probabilistic-programming integrations are not part of this alpha.
  • Normal users should not expect pip install gaia-lang to resolve this alpha unless they use --pre or pin gaia-lang==0.5.0a1.

Release Validation Contract

The v0.5.0a1 artifact was published after these gates passed on the release commit:

  • release workflow run: https://github.com/SiliconEinstein/Gaia/actions/runs/26069929917
  • PR/push CI on the release line before publication
  • docs build
  • wheel smoke from a fresh virtual environment
  • full test suite via make test-all
  • package corpus via uv run python scripts/run_package_corpus.py
  • release workflow dry run for version=0.5.0a1, channel=a

Every published PyPI artifact should also have a matching v<version> tag. Prereleases use GitHub prereleases; stable releases use normal GitHub releases.

After publication, maintainers should run a fresh PyPI install smoke:

python -m venv /tmp/gaia-v05-alpha-smoke
source /tmp/gaia-v05-alpha-smoke/bin/activate
pip install gaia-lang==0.5.0a1
gaia --version
gaia --help

Feedback Wanted

Please open issues or PRs for:

  • unclear v0.4 to v0.5 migration steps
  • broken grouped CLI commands
  • stale documentation
  • confusing gaia author or gaia bayes behavior
  • example package failures
  • quality-gate false positives or hard-to-satisfy review states