wisent 0.1.1__py3-none-any.whl → 0.5.1__py3-none-any.whl

wisent/cli/wisent_cli/main.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+from typing import Optional
+
+import typer
+
+from wisent_guard.cli.wisent_cli.version import APP_NAME, APP_VERSION
+from wisent_guard.cli.wisent_cli.ui import print_banner
+from wisent_guard.cli.wisent_cli.commands.listing import app as listing_app
+from wisent_guard.cli.wisent_cli.commands.train_cmd import app as train_app
+from wisent_guard.cli.wisent_cli.commands.help_cmd import app as help_router_app
+from wisent_guard.cli.wisent_cli.shell import app as shell_app
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="markdown",
+    help=(
+        "[bold]Wisent Guard[/] – steerable activations / steering vectors.\n"
+        "Collect activations, train steering vectors, and inspect loaders & methods.\n\n"
+        "Natural commands (no dashes) + `help <topic>` and a `wisent` shell."
+    ),
+)
+
+app.add_typer(listing_app, name="list")
+app.add_typer(train_app,   name="")           # attach commands directly (e.g., train)
+app.add_typer(help_router_app, name="")       # help router lives at root (help ...)
+app.add_typer(shell_app,  name="shell")
+
+STATE = {"verbose": False}
+
+@app.callback(invoke_without_command=True)
+def _main_callback(
+    ctx: typer.Context,
+    version: Optional[bool] = typer.Option(None, "--version", "-V", help="Show version and exit."),
+    no_banner: bool = typer.Option(False, "--no-banner", help="Disable the startup banner."),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Verbose logging."),
+    logo_width: Optional[int] = typer.Option(None, "--logo-width", help="Width of the wisent badge (28–96)."),
+):
+    """
+    Welcome to **Wisent Guard**.
+
+    Examples:
+      • `wisent help train`
+      • `wisent train model meta-llama/Llama-3.2-1B-Instruct loader custom path ./custom.json training_limit 5 method caa`
+      • `wisent list list-methods`      (methods)
+      • `wisent list list-loaders`      (loaders)
+      • `wisent list list-aggregations` (aggregations)
+      • `wisent shell start`            (interactive 'wisent' prompt)
+    """
+    if version:
+        typer.echo(f"{APP_NAME} {APP_VERSION}")
+        raise typer.Exit()
+
+    STATE["verbose"] = verbose
+    if not no_banner and (ctx.invoked_subcommand is None or ctx.info_name in {"--help", None}):
+        print_banner(APP_NAME, width=logo_width or 48)
+
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+
+@app.command("instructions")
+def instructions():
+    msg = """
+[bold]Quickstart (no-dash style)[/]
+
+• Preview a run without executing:
+  [b]wisent train model gpt2 plan-only true[/]
+
+• Discover components:
+  [b]wisent list list-methods[/] | [b]wisent list list-loaders[/] | [b]wisent list list-aggregations[/]
+
+• Get help:
+  [b]wisent help train[/], [b]wisent help method caa[/], [b]wisent help loader custom[/]
+
+• Full training example (natural):
+  [b]wisent train model meta-llama/Llama-3.2-1B-Instruct loader custom path ./wisent_guard/cli/cli_examples/custom_dataset.json training_limit 5 \\
+        method caa layers 10..12 aggregation continuation_token device cuda dtype float16 save_dir ./steering_output normalize_layers true[/]
+
+Tip: add [b]interactive true[/] for a guided wizard.
+"""
+    try:
+        from rich.panel import Panel
+        from wisent_guard.cli.wisent_cli.ui import echo
+        echo(Panel.fit(msg, title="Instructions", border_style="green"))
+    except Exception:
+        print(msg)
+
+def run():
+    app()
+
+if __name__ == "__main__":
+    run()

wisent/cli/wisent_cli/shell.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+import shlex
+import typer
+
+from wisent_guard.cli.wisent_cli.ui import print_banner, echo
+
+try:
+    from rich.panel import Panel
+    HAS_RICH = True
+except Exception:
+    HAS_RICH = False
+
+__all__ = ["app", "start"]
+
+app = typer.Typer(help="Interactive shell")
+
+def _run_cli_line(line: str) -> None:
+    from typer.main import get_command
+    from wisent_guard.cli.wisent_cli.main import app as root_app
+    click_cmd = get_command(root_app)
+    args = shlex.split(line)
+    try:
+        click_cmd.main(args=args, standalone_mode=False, prog_name="wisent")
+    except SystemExit as e:
+        if e.code not in (0, None):
+            raise
+
+@app.command("start")
+def start(
+    logo_width: int = typer.Option(48, "--logo-width", "-w", help="Logo width for the banner (28–96)."),
+    show_banner: bool = typer.Option(True, "--banner/--no-banner", help="Show banner when the shell starts."),
+):
+    """
+    Launch the interactive **wisent** shell.
+
+    Inside the shell, run:
+      • `help` / `help train` / `help method caa`
+      • `instructions`
+      • `train model ...` (no dashes)
+
+    Type `exit`, `quit`, or press `Ctrl-D` to leave.
+    """
+    if show_banner:
+        print_banner("Wisent Guard", logo_width)
+
+    hint = "Type 'help', 'help train', 'instructions', or any command like 'train model ...'. Type 'exit' to quit."
+    if HAS_RICH:
+        echo(Panel(hint, title="Welcome to the wisent shell", border_style="green"))
+    else:
+        print(hint)
+
+    GREEN, OFF = ("\x1b[32m", "\x1b[0m")
+    while True:
+        try:
+            if HAS_RICH:
+                from rich.console import Console
+                line = Console().input("[bold green]wisent[/] ")
+            else:
+                line = input(f"{GREEN}wisent{OFF} ")
+        except (EOFError, KeyboardInterrupt):
+            typer.echo("\nBye.")
+            break
+
+        line = line.strip()
+        if not line:
+            continue
+        if line in {"exit", "quit", "q"}:
+            typer.echo("Bye.")
+            break
+        if line in {"help", "--help", "-h"}:
+            _run_cli_line("--help")
+            continue
+        if line.startswith("help "):
+            _run_cli_line(line)
+            continue
+        if line in {"instructions", "--instructions"}:
+            _run_cli_line("instructions")
+            continue
+
+        _run_cli_line(line)

wisent/cli/wisent_cli/ui.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from rich.console import Console
+    from rich.panel import Panel
+    from rich.text import Text
+    HAS_RICH = True
+    _console = Console()
+except Exception:  # pragma: no cover
+    HAS_RICH = False
+    _console = None
+
+__all__ = ["print_banner", "echo"]
+
+def _render_wisent_mark(width: int = 48) -> str:
+    logo = """
+.................  .:--++*##%%%%##**+=-:.  .................
+..             .:=*%@@@@@@@%%%%%%%@@@@@@%*=:.             ..
+.           .-*%@@@%#+=-::.........:-=+#%@@@%*=.           .
+.         -*%@@@#=:.                    .:=*%@@@*-.        .
+.      .-#@@@*=.                            .-*@@@#-.      .
+.     :#@@@*:                                  :+%@@#-     .
+.   .+@@@*:                                      :+@@@+.   .
+.  .*@@@@%*=:.                                     -%@@#:  .
+. .#@@#=*%@@@%*-:.                                  .#@@%: .
+..*@@%.  .-+#@@@@#+-:.                               .*@@%..
+.=@@@-       :-+#@@@@%*=:.                            .%@@*.
+:#@@+           .:-+#@@@@%#+=:.                        -@@@-
+=@@@:                .-=*%@@@@%#+=:..                  .#@@+
++@@@*=:.                 .:-+*%@@@@%#*=-:..             *@@+
++@@@@@@#+-..                  .:-=*#@@@@@%#*+--..       +@@+
++@@#-+%@@@%:                        .:-=*#%@@@@@%#*+=-:.*@@+
+=@@%. .=@@@:                             ..:-=+#%%@@@@@%@@@+
+:%@@=  :@@@-                                    ..::-=+#@@@=
+.+@@%. .#@@*                                           +@@#:
+..%@@*. =@@@:                                         =@@@-.
+. :%@@*..#@@#.                         .:..          =@@@= .
+.  :%@@*.:%@@*.                       :#@@%#*+=-::..+@@@=  .
+.   :#@@%-:%@@#:                    .+@@@#%%@@@@@@%%@@%-   .
+.    .+@@@*=#@@%-                 .=%@@%=...::-=#@@@@*.    .
+.      :*@@@#%@@@*:             .=%@@@+.     .:*%@@#-      .
+.        :+%@@@@@@@*-.       :=*@@@%+.    .-+%@@@*-.       .
+.          .=*%@@@@@@#+:.:-+#@@@%*-. .:-+#%@@@#+:          .
+.             .-+#%@@@@@@@@@@@@#*+**#@@@@@%*=:.            .
+..............   ..-=+*#%%%@@@@@@@@%%#*=-:.   ..............
+ ...................  ....:::::::::.... ................... 
+""".strip("\n")
+    return "\n".join(line.center(width) for line in logo.splitlines())
+
+
+def print_banner(title: str, width: int | None = None) -> None:
+    if HAS_RICH:
+        usable = 64 if width is None else width
+        badge = _render_wisent_mark(usable)
+        _console.print(Panel.fit(Text(badge, style="green"), title=f"[b green]{title}[/]", border_style="green"))
+        _console.print("[dim]Steering vectors & activation tooling[/]\n")
+    else:
+        GREEN, OFF = "\x1b[32m", "\x1b[0m"
+        print(GREEN + _render_wisent_mark(width or 48) + OFF)
+        print(f"{title} – Steering vectors & activation tooling\n")
+
+
+def echo(obj: Any) -> None:
+    if HAS_RICH:
+        _console.print(obj)
+    else:
+        print(obj)

wisent/cli/wisent_cli/util/aggregations.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+from typing import Dict, Optional
+
+__all__ = ["agg_cls", "descriptions", "name_map", "pick"]
+
+def agg_cls():
+    from wisent_guard.core.activations.core.atoms import ActivationAggregationStrategy
+    return ActivationAggregationStrategy
+
+def descriptions() -> Dict[object, str]:
+    A = agg_cls()
+    return {
+        A.CHOICE_TOKEN: "Target A/B choice tokens (multiple choice).",
+        A.CONTINUATION_TOKEN: "Use the first token of the continuation.",
+        A.LAST_TOKEN: "Always select the last token.",
+        A.FIRST_TOKEN: "Always select the first token.",
+        A.MEAN_POOLING: "Aggregate by mean over all tokens.",
+        A.MAX_POOLING: "Aggregate by max over all tokens.",
+    }
+
+def name_map() -> Dict[str, object]:
+    A = agg_cls()
+    d = descriptions()
+    mapping = {s.name.lower(): s for s in d}
+    mapping.update({
+        "cont": A.CONTINUATION_TOKEN,
+        "choice": A.CHOICE_TOKEN,
+        "mean": A.MEAN_POOLING,
+        "max": A.MAX_POOLING,
+        "first": A.FIRST_TOKEN,
+        "last": A.LAST_TOKEN,
+    })
+    return mapping
+
+def pick(name: Optional[str]):
+    if not name:
+        return agg_cls().CONTINUATION_TOKEN
+    key = name.strip().lower()
+    mapping = name_map()
+    if key not in mapping:
+        valid = ", ".join(sorted(mapping.keys()))
+        raise ValueError(f"Unknown aggregation {name!r}. Valid: {valid}")
+    return mapping[key]

wisent/cli/wisent_cli/util/parsing.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+import re
+from typing import Dict, List, Optional, Tuple
+
+__all__ = [
+    "to_bool", "parse_layers", "parse_kv", "parse_natural_tokens",
+    "BOOL_TRUE", "BOOL_FALSE", "DTYPE_MAP", "TOP_KEYS"
+]
+
+BOOL_TRUE = {"1", "true", "yes", "y", "on"}
+BOOL_FALSE = {"0", "false", "no", "n", "off"}
+
+DTYPE_MAP = {None: None, "float32": "float32", "float16": "float16", "bfloat16": "bfloat16"}
+
+TOP_KEYS = {
+    "model", "loader", "loaders_location", "methods_location", "method", "layers",
+    "aggregation", "device", "store_device", "dtype", "save_dir",
+    "return_full_sequence", "normalize_layers", "interactive", "plan-only", "plan_only", "confirm"
+}
+
+def to_bool(s: str) -> bool:
+    ls = s.lower()
+    if ls in BOOL_TRUE: return True
+    if ls in BOOL_FALSE: return False
+    raise ValueError(f"Expected a boolean (true/false), got {s!r}")
+
+def parse_layers(spec: Optional[str]) -> Optional[str]:
+    if not spec: return None
+    s = spec.strip().replace(" ", "")
+    if re.match(r"^\d+(,\d+)*$", s):  # 5,7,9
+        return s
+    s = s.replace("-", "..").replace(":", "..")
+    if re.match(r"^\d+\.\.(\d+)$", s): return s
+    if re.match(r"^\d+$", s): return s
+    raise ValueError("Invalid layers spec. Use '12' or '5,10,20' or '10..20' (also '10-20'/'10:20').")
+
+def parse_kv(items: List[str]) -> Dict[str, object]:
+    out: Dict[str, object] = {}
+    for item in items:
+        if "=" not in item:
+            raise ValueError(f"Expected key=value, got: {item!r}")
+        k, v = item.split("=", 1)
+        k, v = k.strip(), v.strip()
+        lv = v.lower()
+        if lv in {"true", "false"}:
+            out[k] = (lv == "true")
+        else:
+            try:
+                out[k] = float(v) if "." in v else int(v)
+            except ValueError:
+                out[k] = v
+    return out
+
+def parse_natural_tokens(tokens: List[str]) -> Tuple[Dict[str, str], Dict[str, str], Dict[str, str]]:
+    """
+    Return (top_level, loader_kwargs, method_kwargs).
+    Understands:
+      - key value
+      - key=value
+      - sections: loader ..., method ...
+      - dotted keys: loader.path=..., method.alpha=...
+    """
+    top: Dict[str, str] = {}
+    lkw: Dict[str, str] = {}
+    mkw: Dict[str, str] = {}
+    ctx: Optional[str] = None
+
+    i = 0
+    while i < len(tokens):
+        tok = tokens[i]
+
+        if "=" in tok:
+            k, v = tok.split("=", 1)
+            k, v = k.strip(), v.strip()
+            if k.startswith("loader."):
+                lkw[k.split(".", 1)[1]] = v
+            elif k.startswith("method."):
+                mkw[k.split(".", 1)[1]] = v
+            elif k in TOP_KEYS:
+                top[k] = v
+            elif ctx == "loader":
+                lkw[k] = v
+            elif ctx == "method":
+                mkw[k] = v
+            else:
+                top[k] = v
+            i += 1
+            continue
+
+        lt = tok.lower()
+        if lt in {"loader", "method"}:
+            ctx = lt
+            if i + 1 < len(tokens) and "=" not in tokens[i + 1] and tokens[i + 1].lower() not in TOP_KEYS:
+                if lt == "loader":
+                    top["loader"] = tokens[i + 1]
+                else:
+                    top["method"] = tokens[i + 1]
+                i += 2
+            else:
+                i += 1
+            continue
+
+        if lt in TOP_KEYS:
+            if i + 1 >= len(tokens) or tokens[i + 1].lower() in TOP_KEYS or "=" in tokens[i + 1]:
+                top[lt] = "true"
+                i += 1
+            else:
+                top[lt] = tokens[i + 1]
+                i += 2
+            ctx = None
+            continue
+
+        if ctx in {"loader", "method"}:
+            if i + 1 < len(tokens) and "=" not in tokens[i + 1] and tokens[i + 1].lower() not in TOP_KEYS:
+                key = tok
+                val = tokens[i + 1]
+                (lkw if ctx == "loader" else mkw)[key] = val
+                i += 2
+            else:
+                (lkw if ctx == "loader" else mkw)[tok] = "true"
+                i += 1
+            continue
+
+        i += 1
+
+    return top, lkw, mkw

wisent/cli/wisent_cli/version.py

@@ -0,0 +1,4 @@
+__all__ = ["APP_NAME", "APP_VERSION"]
+
+APP_NAME = "Wisent Guard"
+APP_VERSION = "0.1.0"

wisent/core/__init__.py

@@ -0,0 +1,27 @@
+from wisent_guard.core.activations import Activations
+from wisent_guard.core.classifier.classifier import ActivationClassifier, Classifier
+
+from .utils.device import empty_device_cache, preferred_dtype, resolve_default_device, resolve_device, resolve_torch_device
+from .steering import SteeringMethod, SteeringType
+
+__all__ = [
+    "ActivationClassifier",
+    "ActivationHooks",
+    "Activations",
+    "Classifier",
+    "ContrastivePairSet",
+    "Layer",
+    "Model",
+    "ModelParameterOptimizer",
+    "PromptFormat",
+    "SecureCodeEvaluator",
+    "SteeringMethod",
+    "SteeringType",
+    "TokenScore",
+    "enforce_secure_execution",
+    "empty_device_cache",
+    "preferred_dtype",
+    "resolve_default_device",
+    "resolve_device",
+    "resolve_torch_device",
+]