gaia run

Execute inference and emit presentation outputs.

gaia run infer [path]     Run belief propagation on the compiled graph
gaia run render [path]    Generate docs / GitHub / Obsidian outputs

Verb	Purpose
infer	Choose Junction Tree / TRW-BP / Mean Field VI based on graph size and treewidth; write .gaia/beliefs.json
render	Emit docs/, .github-output/, or gaia-wiki/ artifacts using compiled IR and (optionally) beliefs

The historical flat run verbs moved under this group (gaia infer --depth 1 <path> → gaia run infer --depth 1 <path>). See CLI Commands for workflow examples and use gaia run <verb> --help for the executable option surface.

Implementation

gaia.cli.commands.infer

gaia run infer -- run BP from compiled IR with metadata priors.

infer_command

infer_command(path: str = typer.Argument('.', help='Path to knowledge package directory'), depth: int = typer.Option(0, '--depth', help='Dependency depth for joint inference. 0=flat priors (default), 1=direct deps, -1=all transitive deps.')) -> None

Run BP inference on a compiled knowledge package.

Reads fresh .gaia/ir.json (run gaia build compile first), lowers the IR into a factor graph, runs belief propagation, and writes .gaia/beliefs.json. Priors come from claim metadata (set by priors.py and reason+prior DSL pairing during compilation). Review status is qualitative and never supplies numeric priors; gaia run infer previews the compiled graph without gating unreviewed warrants. Use gaia build check --gate or gaia inquiry review for publish-quality review gating.

With --depth N (N>0), dependency packages' factor graphs are merged for joint cross-package inference instead of using flat prior injection from dep_beliefs/. --depth -1 merges all transitive deps.

Example:

.. code-block:: bash

gaia build compile .
gaia run infer .
gaia run infer . --depth 1

Source code in gaia/cli/commands/infer.py

def infer_command(
    path: str = typer.Argument(".", help="Path to knowledge package directory"),
    depth: int = typer.Option(
        0,
        "--depth",
        help="Dependency depth for joint inference. "
        "0=flat priors (default), 1=direct deps, -1=all transitive deps.",
    ),
) -> None:
    """Run BP inference on a compiled knowledge package.

    Reads fresh ``.gaia/ir.json`` (run ``gaia build compile`` first),
    lowers the IR into a factor graph, runs belief propagation, and
    writes ``.gaia/beliefs.json``. Priors come from claim metadata (set
    by ``priors.py`` and ``reason+prior`` DSL pairing during
    compilation). Review status is qualitative and never supplies
    numeric priors; ``gaia run infer`` previews the compiled graph
    without gating unreviewed warrants. Use ``gaia build check --gate``
    or ``gaia inquiry review`` for publish-quality review gating.

    With ``--depth N`` (N>0), dependency packages' factor graphs are
    merged for joint cross-package inference instead of using flat
    prior injection from ``dep_beliefs/``. ``--depth -1`` merges all
    transitive deps.

    Example:

    .. code-block:: bash

        gaia build compile .
        gaia run infer .
        gaia run infer . --depth 1
    """
    loaded, compiled = _load_inference_inputs(path)
    _emit_graph_validation_errors(compiled)
    compiled_json = compiled.to_json()
    _require_fresh_compile_artifacts(loaded, compiled, compiled_json)

    factor_graph = _lower_inference_graph(loaded, compiled, depth=depth)
    _validate_factor_graph(factor_graph)

    engine = InferenceEngine()
    inference_result = engine.run(factor_graph)
    result = inference_result.result

    gaia_dir = loaded.pkg_path / ".gaia"
    gaia_dir.mkdir(exist_ok=True)

    _write_json(gaia_dir / "beliefs.json", _beliefs_payload(compiled, result))

    typer.echo(f"Inferred {len(result.beliefs)} beliefs")
    method_label = inference_result.method_used.upper()
    exact_label = " (exact)" if inference_result.is_exact else ""
    treewidth_label = (
        str(inference_result.treewidth) if inference_result.treewidth >= 0 else "not computed"
    )
    typer.echo(
        f"Method: {method_label}{exact_label}, "
        f"treewidth={treewidth_label}, {inference_result.elapsed_ms:.0f}ms"
    )
    if result.diagnostics.iterations_run:
        typer.echo(
            f"Converged: {result.diagnostics.converged} "
            f"after {result.diagnostics.iterations_run} iterations"
        )
    typer.echo(f"Output: {gaia_dir / 'beliefs.json'}")
    typer.echo(
        "Note: belief = posterior probability of the claim under the "
        "auto-compiled Bayesian network; uniform priors are used by default "
        "(override via priors.py or `gaia author register-prior`)."
    )

gaia.cli.commands.render

gaia run render command for package presentation outputs.

RenderTarget

Bases: StrEnum

Supported presentation targets for gaia run render.

render_command

render_command(path: str = typer.Argument('.', help='Path to knowledge package directory'), target: RenderTarget = _TARGET_OPTION) -> None

Render presentation outputs from a compiled package.

--target docs renders docs/detailed-reasoning.md from the compiled IR alone; when gaia run infer has also been run, the output is enriched with belief and prior values. --target github strictly requires inference results and emits the .github-output/ README/wiki/data bundle. --target obsidian writes gaia-wiki/ and enriches pages with beliefs when fresh inference results are available. --target all (default) always renders docs and adds github when inference results are available, emitting a warning when they are not.

Compile freshness is required; beliefs freshness is required when present. Typical pipeline: gaia build compile → gaia run infer → gaia run render.

Example:

.. code-block:: bash

gaia build compile .
gaia run infer .
gaia run render . --target all
gaia run render . --target obsidian

Source code in gaia/cli/commands/render.py

def render_command(
    path: str = typer.Argument(".", help="Path to knowledge package directory"),
    target: RenderTarget = _TARGET_OPTION,
) -> None:
    """Render presentation outputs from a compiled package.

    `--target docs` renders `docs/detailed-reasoning.md` from the compiled IR
    alone; when `gaia run infer` has also been run, the output is enriched with
    belief and prior values. `--target github` strictly requires inference
    results and emits the `.github-output/` README/wiki/data bundle.
    `--target obsidian` writes `gaia-wiki/` and enriches pages with beliefs
    when fresh inference results are available.
    `--target all` (default) always renders docs and adds github when
    inference results are available, emitting a warning when they are not.

    Compile freshness is required; beliefs freshness is required when
    present. Typical pipeline: ``gaia build compile`` → ``gaia run infer``
    → ``gaia run render``.

    Example:

    .. code-block:: bash

        gaia build compile .
        gaia run infer .
        gaia run render . --target all
        gaia run render . --target obsidian
    """
    loaded, compiled = _load_render_inputs(path)
    _emit_render_validation(compiled)
    ir = compiled.to_json()
    _require_render_artifacts_fresh(loaded, compiled, ir)

    # ── Load inference results if available ──
    # beliefs.json lives at .gaia/beliefs.json (written by `gaia run infer`).
    # If present it MUST be fresh (ir_hash matches compiled graph).
    # --target github requires beliefs; --target docs degrades gracefully.
    param_data = param_data_from_ir_metadata(ir)
    beliefs_data = _load_fresh_beliefs(loaded, compiled)
    want_docs, want_github, want_obsidian = _target_plan(target, beliefs_data)

    if want_docs:
        _write_docs_render(
            loaded=loaded,
            ir=ir,
            beliefs_data=beliefs_data,
            param_data=param_data,
        )

    if want_github:
        _write_github_render(
            loaded=loaded,
            ir=ir,
            beliefs_data=beliefs_data,
            param_data=param_data,
        )

    if want_obsidian:
        _write_obsidian_render(
            loaded=loaded,
            ir=ir,
            beliefs_data=beliefs_data,
            param_data=param_data,
        )