gaia inspect

Visualize the compiled package graph.

gaia inspect starmap [path]            Render a starmap visualization (html/dot/svg)

Verb	Purpose
starmap	Static / interactive view of the compiled LocalCanonicalGraph

The historical flat inspect verbs moved under this group (gaia starmap --format svg → gaia inspect starmap --format svg). See CLI Commands for workflow examples and use gaia inspect <verb> --help for the executable option surface.

Implementation

gaia.cli.commands.starmap

gaia inspect starmap — emit a starmap of a compiled package (HTML, DOT, or SVG).

starmap_command

starmap_command(path: str = typer.Argument('.', help='Path to knowledge package directory'), out: str = typer.Option(None, '--out', help="Output file. Defaults to '.gaia/starmap.html' (html) or '.gaia/starmap.dot' (dot), relative to the package directory; absolute paths are honored as-is."), fmt: str = typer.Option('html', '--format', help="Output format: 'html' (interactive Sigma.js), 'dot' (paper-ready Graphviz source), or 'svg' (rendered figure, stellaris glow filters baked in)."), theme: str = typer.Option('light', '--theme', help="Visual theme for 'dot' / 'svg' output. 'light' (default) is the flat paper-friendly palette. 'stellaris' (alias: 'dark') is a deep-space dark variant. For 'svg' the stellaris variant gets an injected <defs> block with radial-gradient background and glow filters bound to contradiction / support / root nodes.")) -> None

Emit a starmap of the compiled package.

Three formats are supported:

• html (default) — single-file interactive Sigma.js visualization. Double-click to open in a browser; no server required.
• dot — a Graphviz digraph source. Pipe through dot (Graphviz) to get a paper-ready figure. graphviz must be installed separately (brew install graphviz / apt install graphviz).
• svg — rendered figure, end-to-end. Internally calls dot (light theme) or sfdp (stellaris/dark) on the dot source, then for the stellaris theme injects an SVG <defs> block with a radial gradient background and three glow filters keyed off class="..." markers (contradiction / support / root). Requires graphviz on PATH.

Compile freshness, beliefs freshness, and graph validation gates apply to all formats.

Examples:

Interactive HTML (default):

gaia inspect starmap path/to/pkg

DOT source (manually pipe through dot/sfdp for full control):

gaia inspect starmap path/to/pkg --format dot --out figures/starmap.dot dot -Tsvg figures/starmap.dot -o figures/starmap.svg

End-to-end paper figure (light, no glow):

gaia inspect starmap path/to/pkg --format svg --out figures/starmap.svg

End-to-end paper figure with stellaris glow defs baked in:

gaia inspect starmap path/to/pkg --format svg --theme stellaris \ --out figures/starmap_stellaris.svg

PNG preview at higher DPI from the dot source:

dot -Tpng -Gdpi=200 figures/starmap.dot -o figures/starmap.png

PDF for direct LaTeX \includegraphics inclusion:

dot -Tpdf figures/starmap.dot -o figures/starmap.pdf

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

def starmap_command(
    path: str = typer.Argument(".", help="Path to knowledge package directory"),
    out: str = typer.Option(
        None,
        "--out",
        help=(
            "Output file. Defaults to '.gaia/starmap.html' (html) or "
            "'.gaia/starmap.dot' (dot), relative to the package directory; "
            "absolute paths are honored as-is."
        ),
    ),
    fmt: str = typer.Option(
        "html",
        "--format",
        help=(
            "Output format: 'html' (interactive Sigma.js), 'dot' "
            "(paper-ready Graphviz source), or 'svg' (rendered figure, "
            "stellaris glow filters baked in)."
        ),
    ),
    theme: str = typer.Option(
        "light",
        "--theme",
        help=(
            "Visual theme for 'dot' / 'svg' output. 'light' (default) is the "
            "flat paper-friendly palette. 'stellaris' (alias: 'dark') is a "
            "deep-space dark variant. For 'svg' the stellaris variant gets "
            "an injected <defs> block with radial-gradient background and "
            "glow filters bound to contradiction / support / root nodes."
        ),
    ),
) -> None:
    r"""Emit a starmap of the compiled package.

    Three formats are supported:

    * ``html`` (default) — single-file interactive Sigma.js visualization.
      Double-click to open in a browser; no server required.
    * ``dot`` — a Graphviz ``digraph`` source. Pipe through ``dot`` (Graphviz)
      to get a paper-ready figure. ``graphviz`` must be installed separately
      (``brew install graphviz`` / ``apt install graphviz``).
    * ``svg`` — rendered figure, end-to-end. Internally calls ``dot``
      (light theme) or ``sfdp`` (stellaris/dark) on the dot source, then for
      the stellaris theme injects an SVG ``<defs>`` block with a radial
      gradient background and three glow filters keyed off ``class="..."``
      markers (contradiction / support / root). Requires ``graphviz`` on
      ``PATH``.

    Compile freshness, beliefs freshness, and graph validation gates apply to
    all formats.

    Examples:
      # Interactive HTML (default):
      gaia inspect starmap path/to/pkg

      # DOT source (manually pipe through dot/sfdp for full control):
      gaia inspect starmap path/to/pkg --format dot --out figures/starmap.dot
      dot -Tsvg figures/starmap.dot -o figures/starmap.svg

      # End-to-end paper figure (light, no glow):
      gaia inspect starmap path/to/pkg --format svg --out figures/starmap.svg

      # End-to-end paper figure with stellaris glow defs baked in:
      gaia inspect starmap path/to/pkg --format svg --theme stellaris \
          --out figures/starmap_stellaris.svg

      # PNG preview at higher DPI from the dot source:
      dot -Tpng -Gdpi=200 figures/starmap.dot -o figures/starmap.png

      # PDF for direct LaTeX \includegraphics inclusion:
      dot -Tpdf figures/starmap.dot -o figures/starmap.pdf
    """
    _validate_starmap_options(fmt, theme)
    loaded, compiled = _load_starmap_inputs(path)
    _emit_starmap_validation(compiled)
    ir = compiled.to_json()
    _require_starmap_artifacts_fresh(loaded, compiled, ir)

    # Beliefs are optional — degrade gracefully when absent. When present they
    # MUST be fresh, mirroring `render`.
    beliefs_data = _load_starmap_beliefs(loaded, compiled)
    param_data = param_data_from_ir_metadata(ir)
    exported_ids = {k["id"] for k in ir.get("knowledges", []) if k.get("exported")}

    graph_json = generate_graph_json(
        ir,
        beliefs_data=beliefs_data,
        param_data=param_data,
        exported_ids=exported_ids,
    )
    graph_payload = json.loads(graph_json)
    content = _render_starmap_content(graph_json, fmt=fmt, theme=theme)

    out_path = Path(out) if out is not None else Path(_DEFAULT_OUT[fmt])
    if not out_path.is_absolute():
        out_path = loaded.pkg_path / out_path
    out_path.parent.mkdir(parents=True, exist_ok=True)
    out_path.write_text(content, encoding="utf-8")

    node_count = len(graph_payload.get("nodes", []))
    edge_count = len(graph_payload.get("edges", []))
    typer.echo(f"Wrote starmap to {out_path} ({node_count} nodes, {edge_count} edges)")