help_display.py

Go to the documentation of this file.

# Copyright (c) 2025-present Aquin Labs Private Limited. All Rights Reserved.
"""Rich terminal layout for `aquin help` - no GPU / torch imports."""
 
from __future__ import annotations
 
from typing import Literal
 
from rich.console import Console, Group
from rich.panel import Panel
from rich.rule import Rule
from rich.table import Table
from rich.text import Text
from rich.theme import Theme
 
SessionMode = Literal["llm"]
 
_THEME = Theme({
    "brand": "bold #facc15",
    "heading": "bold bright_white",
    "cmd": "bold #34d399",
    "muted": "dim #6b7280",
    "label": "dim #9ca3af",
    "value": "#e5e7eb",
    "accent": "#34d399",
    "warn": "#fbbf24",
})
 
 
def _console() -> Console:
    return Console(theme=_THEME, highlight=False)
 
 
def _cmd_table(rows: list[tuple[str, str]]) -> Table:
    table = Table(
        box=None,
        show_header=False,
        pad_edge=False,
        padding=(0, 1),
        collapse_padding=True,
    )
    table.add_column(style="cmd", no_wrap=True, min_width=26, max_width=42)
    table.add_column(style="muted", overflow="fold")
    for cmd, desc in rows:
        table.add_row(cmd, desc)
    return table
 
 
def _section(title: str, rows: list[tuple[str, str]], *, footnote: str | None = None) -> Group:
    parts: list = [Rule(f"[heading]{title}[/]", style="dim #374151")]
    if rows:
        parts.append(_cmd_table(rows))
    if footnote:
        parts.append(Text(footnote, style="muted"))
    return Group(*parts)
 
 
def render_help(
    *,
    connected: bool,
    mode: SessionMode | None,
    show_llm: bool,
    model_id: str | None = None,
    show_embed: bool = False,
) -> None:
    from aquin.session_mode import mode_label
 
    console = _console()
 
    title = Text("aquin", style="brand")
    title.append("  CLI", style="heading")
 
    meta = Table.grid(padding=(0, 2))
    meta.add_column(style="label", justify="right")
    meta.add_column(style="value")
    if model_id:
        if mode:
            meta.add_row(
                "model",
                Text.assemble((model_id, "value"), (f"  ({mode_label(mode)})", "accent")),
            )
        else:
            meta.add_row("model", model_id)
    else:
        meta.add_row("model", "[warn]not loaded[/]")
 
    console.print(Panel(Group(title, "", meta), border_style="dim #374151", padding=(0, 1)))
    console.print()
 
    sections: list[Group] = []
 
    sections.append(
        _section(
            "Meta",
            [
                ("status", "Loaded model & local engine"),
                ("version", "Installed CLI version"),
                ("license", "AQIT Apache 2.0 license"),
                ("update", "Upgrade from PyPI"),
                ("desktop install", "Install Aquin desktop (detect OS, confirm)"),
                ("setup machine", "Prepare this host + model daemon; print SSH tunnel for desktop"),
            ],
        )
    )
 
    sections.append(
        _section(
            "Develop",
            [
                ("aqit train", "<recipe.yaml>  DataRevision → train → Checkpoint → EvalGate"),
            ],
            footnote="AQIT: Recipe for CSV linear/boosting and LLM LoRA. Inspect after a failed gate.",
        )
    )
 
    sections.append(
        _section(
            "Workflow",
            [
                ("load model", "<id>  load & keep model resident in VRAM"),
                ("unload", "free the resident model's VRAM ([--stop] to stop engine)"),
                ("prompt", "<text>  try the loaded model (quick generation)"),
                ("help commands", "show tracked-command subcommands and flags"),
                ("chat", "multi-turn agent (loaded model)"),
            ],
            footnote="aquin load model <id> -> aquin prompt \"hello\" / trace / chat.  Model stays resident across commands; do not shell-bg the load command.",
        )
    )
 
    sections.append(
        _section(
            "Models & SAE",
            [
                ("load model", "<hf-id>  e.g. meta-llama/Llama-3.2-1B-Instruct"),
                ("info sae", "<model-l{n}>  SAE metadata"),
                ("load sae", "<model-l{n}> | --user <name> | --path <file>"),
                ("sae train / align", "train supports --activations <dir>"),
                ("sae catalog-metrics / publish", "public catalog pipeline"),
            ],
            footnote="Pass HuggingFace ids directly. Self-train: aquin sae train.",
        )
    )
 
    sections.append(
        _section(
            "Diff",
            [
                ("diff weight", "--checkpoint <path>  per-layer ||dW|| + merge verdict"),
                ("diff sae", "--checkpoint <path>  feature activation deltas"),
                ("diff residue", "--checkpoint <path>  activation drift per layer"),
            ],
        )
    )
 
    sections.append(
        _section(
            "Check",
            [
                ("check trajectory", "--checkpoints <glob>  multi-step trajectory"),
            ],
        )
    )
 
    sections.append(
        _section(
            "AQIT: capture and SAE",
            [
                ("aqit activations capture", "--dir <path>"),
                ("aqit activations replay", "--from <capture_dir>"),
                ("aqit features compare", "--from <capture_dir> --group <field>"),
                ("aqit feature locate", "rank SAE features  [--umap]"),
                ("aqit sae train", "[--activations <dir>]"),
            ],
        )
    )
 
    if show_llm:
        sections.append(
            _section(
                "AQIT: inspect | LLM",
                [
                    ("aqit trace", "--prompt <text> --layer <n>"),
                    ("aqit feature logit", "--feature <idx>"),
                    ("aqit steer", "--feature_idx <n> [--save|--vector]"),
                    ("aqit check attention", "--prompt <text>"),
                    ("aqit check layer", "--prompts <json>"),
                    ("aqit benchmark", "--feature_idx <n>"),
                ],
            )
        )
        sections.append(
            _section(
                "AQIT: evals | LLM",
                [
                    ("aqit eval consistency", "--query --templates"),
                    ("aqit eval suppress", "--topics <json>"),
                    ("aqit eval custom", "--name --prompts --reference_answers"),
                    ("aqit red-team", "[--vectors <json>]"),
                ],
            )
        )
        sections.append(
            _section(
                "AQIT: simulate",
                [
                    ("aqit simulate", "--dataset <path>"),
                    ("aqit list simulation", "saved runs"),
                    ("aqit replay simulation", "--run_id <id>"),
                    ("aqit compare simulation", "--run_id_a --run_id_b"),
                ],
            )
        )
 
    sections.append(
        _section(
            "Shared",
            [
                ("commands list / show / clear", "tracked CLI outputs (local)"),
                ("<tool-verb>", "any registry tool one-shot"),
            ],
            footnote="GPU tools support  --check  (JSON + PNG artifacts in cwd)",
        )
    )
 
    if not connected:
        console.print(
            Text(
                "Load a model with aquin load model <id>, then run tools.",
                style="muted",
            )
        )
        console.print()
 
    for block in sections:
        console.print(block)
        console.print()
 
    workflow = Table(box=None, show_header=False, pad_edge=False, padding=(0, 1))
    workflow.add_column(style="label", justify="right", width=3)
    workflow.add_column(style="cmd")
    workflow.add_row("1.", "aqit train recipe.yaml")
    workflow.add_row("2.", "if EvalGate FAIL → aqit inspect that run")
    workflow.add_row("3.", "aqit load model …  /  aqit eval custom --prompts probes.jsonl")
 
    console.print(Rule("[heading]Typical workflow[/]", style="dim #374151"))
    console.print(workflow)
    console.print()
    console.print(Text("Docs: https://aquin.app/docs", style="muted"))
    console.print(
        Text(
            "AQIT is Apache 2.0. Run  aqit help  for commands.",
            style="muted",
        )
    )