gaia-cli

Gaia CLI Toolchain Reference

Complete reference for the gaia command-line tool. Covers the full lifecycle: scaffold a package, author knowledge, compile to IR, validate, review, run inference, and publish.

1. Install

pip install gaia-lang    # or: uv pip install gaia-lang
gaia --help              # verify installation

Requires Python 3.12+.

2. gaia init

gaia init <name>

The name must end with -gaia (e.g., galileo-falling-bodies-gaia).

Naming convention

Surface	Convention	Example
Git repo	any name (convention: kebab-case-gaia)	galileo-falling-bodies-gaia
PyPI / package name	kebab-case-gaia	galileo-falling-bodies-gaia
Python import	snake_case (no -gaia suffix)	galileo_falling_bodies

What it creates

• pyproject.toml with [tool.gaia] section (auto-generated type and uuid)
• src/<import_name>/__init__.py with a starter template
• .gitignore
• Auto-runs uv add gaia-lang to pin the dependency

3. Package structure

my-package-gaia/
├── pyproject.toml          # [tool.gaia] type + uuid
├── references.json         # Optional: bibliography in CSL-JSON format (for [@key] citations)
├── src/
│   └── my_package/
│       ├── __init__.py     # DSL declarations, re-exports
│       ├── motivation.py   # Optional: organize by chapter/section
│       └── priors.py        # Optional: prior assignments via reason+prior pairing
├── artifacts/              # Source material (PDF, markdown)
├── .gaia/                  # Created by gaia compile (git tracked)
│   ├── ir.json
│   ├── ir_hash
│   └── beliefs.json        # Created by gaia infer
└── .gitignore

pyproject.toml required fields

[project]
name = "my-package-gaia"
version = "1.0.0"
requires-python = ">=3.12"

[tool.gaia]
type = "knowledge-package"
uuid = "..."              # Auto-generated by gaia init

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

4. gaia compile

gaia compile .

Imports the top-level package, collects all DSL declarations, and writes:

• .gaia/ir.json — the compiled Gaia IR
• .gaia/ir_hash — content hash for integrity checks

Generate per-module reasoning graphs

gaia render . --target docs

Generates docs/detailed-reasoning.md with per-module Mermaid reasoning graphs and full claim details.

Note: --target docs works without beliefs (enriches with posteriors when available). --target github requires beliefs on disk — run gaia infer first.

Generate GitHub presentation skeleton

gaia render . --target github

Generates .github-output/ with wiki pages, README skeleton, React Pages template, graph.json, and manifest. After generation, use /gaia:publish to fill narrative content.

5. gaia check

gaia check .
gaia check --brief .
gaia check --show <module|label> .
gaia check --brief --show <module|label> .
gaia check --hole .

Validates package structure and IR consistency. Used by registry CI during publishing.

Options:

• --brief / -b — Show per-module warrant structure overview (claims with roles, strategies with priors, operators)
• --show / -s — Expand a specific module name or claim/strategy label with full warrant trees
• --hole — Show detailed prior review report for all independent claims (holes without priors + covered with priors)

Common errors:

• Missing [tool.gaia].type in pyproject.toml
• Duplicate labels across declarations
• Stale compiled artifacts (.gaia/ir_hash mismatch)
• IR structural validation errors (missing references, duplicate IDs)

Diagnostic output

gaia check also reports informational diagnostics (not errors) useful for completeness checking during formalization:

• Independent premises — claims not concluded by any strategy that need priors. Each shows prior=X if set, or ⚠ no prior (defaults to 0.5) if missing.
• Holes (no prior set) — count of independent claims still missing priors, shown in the summary when > 0
• Derived conclusions — claims whose belief comes from BP propagation (do not set priors)
• Orphaned claims — claims not referenced by any strategy
• Background-only claims — claims only used in strategy background=, not as premises

--hole output

Detailed report for prior review. Lists all independent claims split into two groups:

• Holes: claims without priors — shows each claim's QID, content preview, and NOT SET (defaults to 0.5) status
• Covered: claims with priors — shows each claim's prior=X and justification reason

Use --hole during prior review to:

1. Identify which claims still need priors in priors.py
2. Verify that existing prior values and justifications are reasonable
3. Confirm "All independent claims have priors assigned" before running inference

--brief output

Per-module overview showing:

• Settings with label + truncated content
• Claims with role (independent/derived/structural/background/orphaned) and prior
• Strategies with type, premise labels → conclusion, prior, and reason
• Operators with type, variables, and reason

--show output

When given a module name (e.g., --show motivation): expands all claims with full content and strategies with recursive warrant trees, including composite sub-strategy expansion.

When given a claim label (e.g., --show hypothesis): shows the claim's full content and all strategies that conclude to it, with all premises listed.

6. Priors

Priors are set directly in DSL source via reason+prior pairing and priors.py, then baked into claim metadata at compile time. No separate review sidecar is needed.

Inline reason+prior pairing

Strategies accept a prior= keyword that pairs with their reason=:

H = claim("Hypothesis X", label="hypothesis")
E = claim("Evidence Y", label="evidence")

deduction(E, concludes=H, prior=0.85, reason="Strong experimental support")

priors.py (batch priors)

For leaf claims (independent premises) without a concluding strategy, assign priors in src/<package>/priors.py:

from . import some_claim, another_claim

PRIORS = {
    some_claim: (0.9, "Justification for high prior."),
    another_claim: (0.3, "Justification for low prior."),
}

These are applied at load time before compilation. gaia check --brief shows which claims are independent (need priors) vs derived (get beliefs from BP).

For complete prior assignment guide and BP interpretation, see the review skill.

7. gaia infer

gaia infer [PATH] [--depth N]

Compiles IR into a factor graph, runs belief propagation, and writes posterior beliefs to .gaia/beliefs.json.

• Auto-runs uv sync --quiet before loading the package to ensure dependencies are installed.
• Priors come from claim metadata (priors.py + DSL reason+prior pairing), baked in at compile time. No review sidecar is needed.
• Auto-selects algorithm based on factor graph treewidth:
  • Junction tree (exact inference, treewidth ≤ 15)
  • Generalized BP (region decomposition, treewidth 16-30)
  • Loopy BP (approximation, treewidth > 30)
• Output: .gaia/beliefs.json

Dependency depth

Flag	Behavior
--depth 0 (default)	Uses flat priors for foreign nodes; optionally reads dep_beliefs/ for upstream beliefs
--depth 1	Merges direct dependency factor graphs for joint cross-package inference
--depth -1	Merges all transitive dependency factor graphs

# Local inference only (default)
gaia infer .

# Joint inference with direct dependencies
gaia infer . --depth 1

# Joint inference with all transitive dependencies
gaia infer . --depth -1

With --depth 0, foreign nodes (references to claims in other packages) get flat priors unless a dep_beliefs/ directory provides upstream belief files. With --depth 1 or -1, the dependency packages' full factor graphs are merged into a single graph for joint inference, replacing flat prior injection with structural reasoning.

8. gaia register

Publishes a package to the Gaia registry. Requires a git tag pushed to GitHub.

gaia register . --registry-dir ../gaia-registry --create-pr

Registry CI validates:

• gaia compile succeeds and hash matches .gaia/ir_hash
• gaia check passes
• Namespace is valid
• UUID is unique across the registry

Note: gaia register --create-pr creates the registry branch locally but does not automatically push it to your fork. After running the command, you must manually push and create the PR:

cd <registry-dir>
git push origin register/<name>-<version>
gh pr create --repo SiliconEinstein/gaia-registry --base main \
  --head <your-user>:register/<name>-<version> --title "register: <name> <version>" --body "..."

9. gaia add

Install a registered package from the official registry.

gaia add <package>
gaia add <package> --version 1.0.0    # pin version

Resolves packages from https://github.com/SiliconEinstein/gaia-registry.

10. Workflow summary

gaia init
  → write DSL declarations + priors
    → gaia compile .
      → gaia check .
        → gaia infer .
          → gaia render . --target github
            → /gaia:publish
              → gaia render . --target docs
                → gaia register . --registry-dir ../gaia-registry --create-pr

1. Scaffold — gaia init my-package-gaia
2. Author — Write knowledge declarations in src/<package>/, set priors via reason+prior pairing and priors.py
3. Compile — gaia compile . to produce IR
4. Validate — gaia check . to catch structural errors early
5. Infer — gaia infer . to compute posterior beliefs (optionally --depth 1 for cross-package)
6. Present — gaia render . --target github to generate GitHub presentation skeleton, then /gaia:publish to fill narrative content
7. Detail — gaia render . --target docs to generate per-module reasoning graphs
8. Publish — Tag, push, and gaia register to submit to the registry