help_display_ascii.py

Go to the documentation of this file.

# Copyright (c) 2025-present Aquin Labs Private Limited. All Rights Reserved.
"""ASCII terminal layout for `aquin help`."""
 
from __future__ import annotations
 
from typing import Literal
 
from aquin.ascii_layout import (
    box_line,
    box_lines,
    center,
    kv_line,
    print_banner,
    print_section,
    rule,
    width,
)
 
SessionMode = Literal["llm"]
 
def help_payload(
    *,
    connected: bool,
    mode: SessionMode | None,
    show_llm: bool,
    model_id: str | None = None,
    show_embed: bool = False,
) -> dict:
    """Structured help for `--json` / quiet CLI surfaces."""
    from aquin.session_mode import mode_label
 
    session: dict = {"loggedIn": bool(connected)}
    if connected:
        session["model"] = model_id
        session["mode"] = mode
        session["modeLabel"] = mode_label(mode) if mode and model_id else None
    else:
        session["account"] = "not logged in"
 
    sections: list[dict] = [
        {
            "title": "Meta",
            "commands": [
                ("status", "loaded model & local engine"),
                ("version", "installed CLI version"),
                ("license", "read engine license"),
                ("update", "upgrade from PyPI"),
                ("desktop install", "install Aquin desktop"),
                ("setup machine", "GPU host + daemon for desktop tunnel"),
            ],
        },
        {
            "title": "Develop",
            "commands": [
                ("train", "<recipe.yaml>  DataRevision → train → gate"),
            ],
        },
        {
            "title": "Workflow",
            "commands": [
                ("load model", "<id>  load model into VRAM"),
                ("unload", "free VRAM"),
                ("prompt", "<text>  try the loaded model"),
                ("chat", "multi-turn agent"),
                ("help commands", "tracked command log"),
            ],
        },
        {
            "title": "Models & SAE",
            "commands": [
                ("load model", "<hf-id>"),
                ("info sae", "<model-l{n}>"),
                ("load sae", "<model-l{n}> | --user | --path"),
                ("sae train / align", "train supports --activations"),
                ("sae catalog-metrics / publish", "public catalog pipeline"),
            ],
        },
        {
            "title": "Diff",
            "commands": [
                ("diff weight", "--checkpoint <path>  ||dW|| + merge verdict"),
                ("diff sae", "--checkpoint <path>"),
                ("diff residue", "--checkpoint <path>  activation drift"),
            ],
        },
        {
            "title": "Check",
            "commands": [
                ("check trajectory", "--checkpoints <glob>"),
            ],
        },
        {
            "title": "AQIT · capture & SAE",
            "commands": [
                ("activations capture", "--dir <path> [--balance] [--granularity token]"),
                ("activations replay", "--from <capture_dir>"),
                ("features compare", "--from <capture_dir> --group <field>"),
                ("capture-activations", "legacy alias"),
                ("feature locate", "rank SAE features"),
                ("sae-stats", "--prompts <file>"),
                ("sae train", "[--activations <dir>] [--balance]"),
            ],
        },
    ]
 
    if show_llm:
        sections.append({
            "title": "AQIT · inspect",
            "commands": [
                ("trace", "--prompt --layer"),
                ("feature logit", "--feature"),
                ("feature neighbor", "--feature"),
                ("steer", "--feature_idx [--save|--vector] [--eval]"),
                ("sweep", "--feature_idx [--strengths] [--eval]"),
                ("multi-steer", "combined steering"),
                ("check attention", "--prompt"),
                ("check layer", "--prompts [--localize]"),
                ("check perturbation", "--prompt"),
                ("check confidence", "--prompts"),
                ("check weight", "trojan + rank"),
                ("benchmark", "--feature_idx"),
            ],
        })
        sections.append({
            "title": "AQIT · evals",
            "commands": [
                ("eval consistency", "--query --templates"),
                ("eval suppress", "--topics"),
                ("eval boundary", "--prompts"),
                ("eval custom", "--name --prompts"),
                ("red-team", "[--vectors]"),
            ],
        })
        sections.append({
            "title": "AQIT · simulate",
            "commands": [
                ("simulate", "--dataset"),
                ("list simulation", "saved runs"),
                ("replay simulation", "--run_id"),
                ("compare simulation", "--run_id_a --run_id_b"),
            ],
        })
 
    sections.append({
        "title": "Shared",
        "commands": [
            ("commands list", "tracked outputs"),
            ("<tool-verb>", "any registry tool one-shot"),
        ],
    })
 
    return {
        "session": session,
        "sections": [
            {
                "title": s["title"],
                "commands": [{"cmd": c, "desc": d} for c, d in s["commands"]],
            }
            for s in sections
        ],
        "next": "aquin load model <id> → aquin prompt \"hello\"",
        "docs": "https://aquin.app/docs",
    }
 
 
def render_help_quiet(
    *,
    connected: bool,
    mode: SessionMode | None,
    show_llm: bool,
    model_id: str | None = None,
    show_embed: bool = False,
) -> None:
    """Section title + real bordered command tables."""
    from aquin.table_plain import print_table
 
    payload = help_payload(
        connected=connected,
        mode=mode,
        show_llm=show_llm,
        show_embed=show_embed,
        model_id=model_id,
    )
 
    session = payload["session"]
    if session.get("model"):
        mode_bit = f"  ({session['modeLabel']})" if session.get("modeLabel") else ""
        print(f"  model   {session['model']}{mode_bit}")
    else:
        print("  model   not loaded")
    print()
 
    for section in payload["sections"]:
        cmds = section["commands"]
        print_table(
            ["command", "description"],
            [[row["cmd"], row["desc"]] for row in cmds],
            max_col=56,
            title=section["title"],
        )
        print()
 
    print(f"  {payload['next']}")
    print(f"  docs  {payload['docs']}")
 
 
def _cmd_row(cmd: str, desc: str, w: int) -> list[str]:
    inner = w - 4
    cmd_w = min(30, max(len(cmd), inner // 3))
    text = f"  {cmd.ljust(cmd_w)}  {desc}"
    return box_lines(text, w)
 
 
def _section_rows(
    title: str,
    rows: list[tuple[str, str]],
    *,
    footnote: str | None = None,
    w: int,
) -> None:
    body: list[str] = []
    for cmd, desc in rows:
        body.extend(_cmd_row(cmd, desc, w))
    if footnote:
        body.append(box_line("", w))
        for line in box_lines(f"  {footnote}", w):
            body.append(line)
    print_section(title, body, w=w)
 
 
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
 
    w = width()
    print_banner(subtitle="HELP", w=w)
 
    meta_rows: list[str] = []
    if connected:
        if model_id:
            label = f"{model_id}  ({mode_label(mode)})" if mode else model_id
            meta_rows.append(kv_line("model", label, w=w))
        else:
            meta_rows.append(kv_line("model", "(not loaded)", w=w))
    else:
        meta_rows.append(kv_line("account", "not logged in", w=w))
    print_section("SESSION", meta_rows, w=w)
 
    _section_rows(
        "META",
        [
            ("status", "loaded model & local engine"),
            ("version", "installed CLI version"),
            ("license", "read engine license"),
            ("update", "upgrade from PyPI"),
            ("desktop install", "install Aquin desktop"),
            ("setup machine", "GPU host + daemon for desktop tunnel"),
        ],
        w=w,
    )
 
    _section_rows(
        "WORKFLOW",
        [
            ("load model", "<id>  load model into VRAM"),
            ("unload", "free VRAM"),
            ("prompt", "<text>  try the loaded model"),
            ("chat", "multi-turn agent"),
            ("help commands", "tracked command log"),
        ],
        footnote="load model <id> -> prompt / trace / chat",
        w=w,
    )
 
    _section_rows(
        "DIFF",
        [
            ("diff weight", "--checkpoint <path>  ||dW|| + merge verdict"),
            ("diff sae", "--checkpoint <path>"),
            ("diff residue", "--checkpoint <path>  activation drift"),
        ],
        w=w,
    )
 
    _section_rows(
        "MODELS & SAE",
        [
            ("load model", "<hf-id>"),
            ("info sae", "<model-l{n}>"),
            ("load sae", "<model-l{n}> | --user | --path"),
            ("sae train / align", "train supports --activations"),
            ("sae catalog-metrics / publish", "public catalog pipeline"),
        ],
        w=w,
    )
 
    _section_rows(
        "CHECK",
        [
            ("check trajectory", "--checkpoints <glob>"),
        ],
        w=w,
    )
 
    _section_rows(
        "CAPTURE & PROBES",
        [
            ("capture-activations", "--dir <path>"),
            ("feature locate", "rank SAE features"),
            ("sae-stats", "--prompts <file>"),
        ],
        w=w,
    )
 
    if show_llm:
        _section_rows(
            "INSPECTION | LLM",
            [
                ("trace", "--prompt --layer"),
                ("feature logit", "--feature"),
                ("feature neighbor", "--feature"),
                ("steer", "--feature_idx [--save|--vector] [--eval]"),
                ("multi-steer", "combined steering"),
                ("check attention", "--prompt"),
                ("check layer", "--prompts [--localize]"),
                ("check perturbation", "--prompt"),
                ("check confidence", "--prompts"),
                ("check weight", "trojan + rank"),
                ("benchmark", "--feature_idx"),
            ],
            w=w,
        )
        _section_rows(
            "EVALS | LLM",
            [
                ("eval consistency", "--query --templates"),
                ("eval suppress", "--topics"),
                ("eval boundary", "--prompts"),
                ("eval custom", "--name --prompts"),
                ("red-team", "[--vectors]"),
            ],
            w=w,
        )
        _section_rows(
            "SIMULATION | LLM",
            [
                ("simulate", "--dataset"),
                ("list simulation", "saved runs"),
                ("replay simulation", "--run_id"),
                ("compare simulation", "--run_id_a --run_id_b"),
            ],
            w=w,
        )
 
    _section_rows(
        "SHARED",
        [
            ("commands list", "tracked outputs"),
            ("<tool-verb>", "any registry tool one-shot"),
        ],
        footnote="GPU tools support --check (JSON + PNG in cwd)",
        w=w,
    )
 
    print(rule("-", w))
    print(center("1. aquin train recipe.yaml  |  2. gate FAIL → inspect  |  3. load / eval", w))
    print(center("docs: https://aquin.app/docs", w))
    print(rule("-", w))
    print()