pal-code 0.1.0__py3-none-any.whl

pal/terminal/flow_cli.py

@@ -0,0 +1,439 @@
+"""The workflow in the terminal: one request, building a plan step by step, applying with checks, and the workflow commands."""
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+
+from rich.console import Console
+from rich.padding import Padding
+from rich.table import Table
+from rich.text import Text
+
+from pal.terminal import decide, theme, ui
+from pal.terminal.security import worst
+from pal.terminal.session import BudgetExceeded, Change, Turn
+from pal.terminal.workflow import (
+    AUTONOMY,
+    DEBUG_TRIES,
+    SETTING_ABOUT,
+    SETTINGS,
+    Workflow,
+    git_commit,
+    is_git_repo,
+    run_shell,
+)
+
+FLOW_COMMANDS: list[tuple[str, str]] = [
+    ("/new", "start a new plan (fresh conversation)"), ("/plans", "list this folder's plans"), ("/cd", "switch plan: /cd <name or number>"),
+    ("/current", "the current plan: branch, steps, context, pending"), ("/rename", "rename the current plan"), ("/delete-plan", "delete a plan"),
+    ("/load", "add files, folders or globs to the context (-n \"note\" adds a note)"), ("/ls", "list the context with token counts"),
+    ("/rm", "remove context by number, range, name or glob"), ("/clear-context", "remove all context (alias /unload)"),
+    ("/continue", "build the next step of the plan (all: build every step)"), ("/diff", "show the pending changes"),
+    ("/review", "review the pending changes in your browser"), ("/apply", "apply pending changes, run the checks, commit"),
+    ("/reject", "drop pending changes: /reject <file>  or  /reject all"), ("/log", "every version of the sandbox"),
+    ("/rewind", "go back: /rewind [n]  or  /rewind <version>"), ("/convo", "the plan's conversation"),
+    ("/branches", "list branches"), ("/checkout", "switch to (or create) a branch"), ("/delete-branch", "delete a branch"),
+    ("/autonomy", "none, basic, plus, semi or full"), ("/set", "one setting: /set auto-exec on"), ("/run", "run a command in this folder (asks first)"),
+    ("/debug", "run a command and let the Build agent fix it until it passes: /debug npm test"),
+]
+
+
+def spin(session, console: Console, label: str, fn: Callable):
+    """Run fn() with a spinner whose line shows the time and the tokens saved so far."""
+    from pal.terminal.keys import EscToStop
+    with console.status(Text(label, style=theme.MUTED), spinner="dots", spinner_style=theme.RED) as status, EscToStop():
+        done = threading.Event()
+        t0 = time.monotonic()
+
+        def tick() -> None:
+            while not done.wait(0.25):
+                line = Text(f"{label} {time.monotonic() - t0:.0f}s", style=theme.MUTED)
+                if session.saved > 0:
+                    line.append("  ·  saved so far ", style=theme.MUTED)
+                    line.append(f"{session.saved:,} tokens ({session.saved_pct:g}%)", style=f"bold {theme.RED_HI}")
+                line.append("   esc to stop", style=theme.MUTED)
+                status.update(line)
+        threading.Thread(target=tick, daemon=True).start()
+        try:
+            return fn()
+        finally:
+            done.set()
+
+
+def safely(console: Console, fn: Callable):
+    """Run a model request; report a stop, a budget or an error in one line instead of a traceback. Returns the result or None."""
+    try:
+        return fn()
+    except BudgetExceeded as e:
+        ui.say(console, Text(f"Stopped: {e}", style=theme.RED_HI))
+    except KeyboardInterrupt:
+        ui.say(console, Text("Stopped.", style=theme.MUTED))
+    except Exception as e:  # noqa: BLE001  (a model that cannot be reached, a missing key, a full context ...)
+        ui.say(console, Text(f"Something went wrong: {type(e).__name__}: {str(e)[:300]}", style=theme.RED_HI))
+    console.print()
+    return None
+
+
+DOING = {"build": "Pal is building…", "plan": "Pal is planning…", "ask": "Pal is thinking…"}
+
+
+def run_turn(wf: Workflow, text: str, console: Console) -> None:
+    """One request with the current agent, then what follows from it: pending changes to review, or a plan to build."""
+    s = wf.session
+    ui.show_user(console, text)
+    result = safely(console, lambda: spin(s, console, DOING.get(s.mode, "Pal is working…"), lambda: wf.tell(text)))
+    if result is None:
+        return
+    ui.show_reply(console, result, s)
+    if s.mode == "ask" and result.questions:
+        answers = decide.ask_all(console, result.questions)
+        console.print()
+        if answers is None:
+            ui.say(console, Text("Skipped. Answer in your own words whenever you like.", style=theme.MUTED))
+            console.print()
+        else:
+            run_turn(wf, decide.answers_message(result.questions, answers), console)
+        return
+    if s.mode == "build":
+        after_build(wf, result, console)
+    elif s.mode == "plan" and wf.plan.b.steps:
+        show_steps(wf, console)
+        if wf.plan.setting("auto-continue") and ui.confirm(console, f"Build the {len(wf.plan.b.steps)} steps now, into the sandbox?"):
+            continue_flow(wf, console, every=True)
+        else:
+            ui.say(console, Text("/continue builds the next step  ·  /continue all builds every step", style=theme.MUTED))
+            console.print()
+
+
+def after_build(wf: Workflow, result: Turn, console: Console) -> None:
+    if result.changes:
+        ui.show_changes(console, result.changes)
+    pending_line(wf, console)
+    if wf.plan.b.pending and wf.plan.setting("auto-apply"):
+        apply_flow(wf, console, ask=False)
+
+
+def pending_line(wf: Workflow, console: Console) -> None:
+    n, cmds = len(wf.plan.b.pending), wf.plan.b.commands
+    if not n:
+        return
+    line = Text.assemble((f"  {n} file{'s' if n != 1 else ''} pending in the sandbox", f"bold {theme.RED_HI}"), ("  (your files are not changed yet)", theme.MUTED))
+    ui.say(console, line)
+    if cmds:
+        ui.say(console, Text("  checks to run after applying: " + "  ·  ".join(cmds), style=theme.INK))
+    ui.say(console, Text("  /diff  ·  /review  ·  /apply  ·  /reject <file>  ·  /rewind", style=theme.MUTED))
+    console.print()
+
+
+def show_steps(wf: Workflow, console: Console) -> None:
+    grid = Table.grid(padding=(0, 1))
+    for i, step in enumerate(wf.plan.b.steps, 1):
+        mark = "✓" if i <= wf.plan.b.done else "•"
+        grid.add_row(Text(mark, style=theme.RED_HI if i <= wf.plan.b.done else theme.MUTED), Text(f"{i}.", style=theme.MUTED), Text(step, style=theme.INK))
+    ui.say(console, Text(f"Plan saved: {len(wf.plan.b.steps)} steps ({wf.plan.b.done} built)", style=f"bold {theme.WHITE}"))
+    ui.say(console, Padding(grid, (0, 0, 0, 2)))
+
+
+def continue_flow(wf: Workflow, console: Console, every: bool = False) -> None:
+    """Build the next step, or every remaining step, into the sandbox."""
+    s = wf.session
+    if wf.next_step() is None:
+        ui.say(console, Text("Every step is built. Make a new plan with the Plan agent, or ask Build for more." if wf.plan.b.steps else
+                             "There is no plan yet: switch to the Plan agent (tab) and describe the task.", style=theme.MUTED))
+        console.print()
+        return
+    while True:
+        nxt = wf.next_step()
+        if nxt is None:
+            break
+        i, step = nxt
+        ui.say(console, Text.assemble((f"Step {i} of {len(wf.plan.b.steps)}  ", f"bold {theme.WHITE}"), (step, theme.INK)))
+        label = f"Pal is building step {i}…"
+        result = safely(console, lambda label=label: spin(s, console, label, wf.build_step))
+        if result is None:
+            break
+        if result.changes:
+            ui.say(console, Text("  " + "  ".join(("+ " if c.is_new else "~ ") + c.path for c in result.changes), style=theme.INK))
+        for path, why in result.refused:
+            ui.say(console, Text(f"  refused {path}: {why}", style=theme.RED_HI))
+        if not every:
+            break
+    console.print()
+    pending_line(wf, console)
+    if wf.plan.b.pending and wf.plan.setting("auto-apply"):
+        apply_flow(wf, console, ask=False)
+
+
+def show_diff(wf: Workflow, console: Console) -> None:
+    diffs = wf.diffs()
+    if not diffs:
+        ui.say(console, Text("Nothing is pending.", style=theme.MUTED))
+        console.print()
+        return
+    changes = [Change(path, "", "", new, lines, findings) for path, new, lines, findings in diffs]
+    ui.show_changes(console, changes, limit=200)
+    console.print()
+
+
+def broken_pending(wf: Workflow) -> list:
+    """Pending files that do not parse (a fix that never came, or a file edited by hand into the sandbox)."""
+    from pal.terminal.syntax import check
+    return [p for path, new in wf.plan.b.pending.items() if (p := check(path, new))]
+
+
+def parses_or_confirmed(wf: Workflow, console: Console) -> bool:
+    """True when every pending file parses, or the person accepts the ones that do not (the default is no)."""
+    bad = broken_pending(wf)
+    if not bad:
+        return True
+    for prob in bad:
+        ui.say(console, Text(f"  ✗ {prob}", style=theme.RED_HI))
+    if ui.confirm(console, f"{len(bad)} pending file{'s' if len(bad) != 1 else ''} do{'es' if len(bad) == 1 else ''} not parse. Apply anyway?"):
+        return True
+    ui.say(console, Text("  Nothing applied. Fix it with the Build agent, or drop it with /reject <file>.", style=theme.MUTED))
+    console.print()
+    return False
+
+
+def apply_flow(wf: Workflow, console: Console, ask: bool = True, yes: bool = False) -> None:
+    """Write the pending changes, run the checks the person approves, roll back on failure (and auto-debug), and commit."""
+    s = wf.session
+    pending = wf.plan.b.pending
+    if not pending:
+        ui.say(console, Text("Nothing is pending.", style=theme.MUTED))
+        console.print()
+        return
+    if not parses_or_confirmed(wf, console):
+        return
+    level = worst([f for _, _, _, fs in wf.diffs() for f in fs])
+    n = len(pending)
+    if level == "critical" and not ui.confirm(console, f"A critical security problem was found (see /diff). Apply {n} file{'s' if n != 1 else ''} anyway?"):
+        ui.say(console, Text("  Nothing applied.", style=theme.MUTED))
+        return
+    if level != "critical" and ask and not yes and not wf.plan.setting("auto-apply") and not ui.confirm(console, f"Apply {n} file{'s' if n != 1 else ''} to {ui.short_path(s.cwd)}?"):
+        ui.say(console, Text("  Nothing applied. The changes stay in the sandbox.", style=theme.MUTED))
+        return
+
+    def run_command(cmd: str):
+        if not wf.plan.setting("auto-exec") and not ui.confirm(console, f"Run  {cmd}  in {ui.short_path(s.cwd)}?"):
+            return None, ""
+        ui.say(console, Text(f"  $ {cmd}", style=theme.WHITE))
+        ok, out = spin(s, console, "Running…", lambda: run_shell(cmd, s.cwd))
+        tail = "\n".join(out.strip().splitlines()[-12:])
+        if tail:
+            ui.say(console, Padding(Text(ui.clean_terminal(tail), style=theme.MUTED), (0, 0, 0, 4)))
+        ui.say(console, Text("  ✓ passed" if ok else "  ✗ failed", style=theme.RED_HI if not ok else f"bold {theme.WHITE}"))
+        return ok, out
+
+    def debug(cmd: str, output: str) -> bool:
+        ui.say(console, Text("  The check failed, so every file was put back. Asking the Build agent to fix it…", style=theme.INK))
+        mode = s.mode
+        s.mode = "build"
+        try:
+            result = safely(console, lambda: spin(s, console, "Pal is fixing…", lambda: wf.tell(
+                f"After applying your changes, the check `{cmd}` failed with:\n```\n{output}\n```\nFix the cause. Reply with the complete files to change.")))
+        finally:
+            s.mode = mode
+        return bool(result and result.changes)
+
+    def commit_message(files: list[str]) -> str:
+        label = next((v.label for v in reversed(wf.plan.b.versions) if not v.label.startswith(("applied", "rejected"))), "Pal changes")
+        try:
+            reply = s.client.ask(f"Write a git commit message for this change: {label}. Files: {', '.join(files)}. One line under 72 characters, "
+                                 "imperative mood, then optionally a blank line and up to 3 short bullet lines. Reply with the message only.")
+            text = ui.clean_terminal(reply.text).strip().strip("`").strip()
+            return text[:600] or label
+        except Exception:  # noqa: BLE001
+            return label[:72]
+
+    res = wf.apply(run_command, debug if wf.plan.setting("auto-debug") else None, commit_message)
+    for path in res.written if not res.rolled_back else []:
+        ui.say(console, Text.assemble(("  ✓ ", theme.RED_HI), (path, theme.WHITE)))
+    if res.rolled_back:
+        ui.say(console, Text(f"  ✗ {res.failed_command} failed: every file was put back as it was. The changes are still pending.", style=theme.RED_HI))
+        ui.say(console, Text("  Fix it with the Build agent, then /apply again" + ("" if wf.plan.setting("auto-debug") else ", or turn on  /set auto-debug on"), style=theme.MUTED))
+    elif res.commit:
+        ui.say(console, Text(f"  committed {res.commit}", style=f"bold {theme.WHITE}"))
+    elif res.written and is_git_repo(s.cwd) and not wf.plan.setting("auto-commit"):
+        ui.say(console, Text("  Not committed (auto-commit is off: /set auto-commit on).", style=theme.MUTED))
+    console.print()
+
+
+def debug_flow(wf: Workflow, cmd: str, console: Console, tries: int = DEBUG_TRIES) -> bool:
+    """/debug <command>: run it; while it fails, show the Build agent the output, apply its fix (asking first, unless auto-apply is on) and run it
+    again, at most `tries` fixes. If it still fails, offer to put every file back as it was. True when the command passes in the end."""
+    s = wf.session
+    say = lambda text, style=theme.MUTED: ui.say(console, Text(text, style=style))  # noqa: E731
+    before: dict[str, str | None] = {}                  # every file a fix touched, as it was before /debug
+    written: list[str] = []
+    for attempt in range(tries + 1):
+        say(f"  $ {cmd}", theme.WHITE)
+        ok, out = spin(s, console, "Running…", lambda: run_shell(cmd, s.cwd))
+        tail = "\n".join(out.strip().splitlines()[-12:])
+        if tail:
+            ui.say(console, Padding(Text(ui.clean_terminal(tail), style=theme.MUTED), (0, 0, 0, 4)))
+        if ok:
+            say("  ✓ passes" + (f" after {attempt} fix{'es' if attempt != 1 else ''}" if attempt else ""), f"bold {theme.WHITE}")
+            if written and wf.plan.setting("auto-commit") and is_git_repo(s.cwd):
+                sha = git_commit(s.cwd, sorted(set(written)), f"Fix: {cmd}"[:72])
+                if sha:
+                    say(f"  committed {sha}", f"bold {theme.WHITE}")
+            console.print()
+            return True
+        say("  ✗ fails", theme.RED_HI)
+        if attempt == tries:
+            break
+        mode, s.mode = s.mode, "build"
+        try:
+            ask = (f"Running `{cmd}` in the project fails with:\n```\n{ui.clean_terminal(out.strip())[-3000:]}\n```\n"
+                   "Find the cause and fix it. Reply with the complete files to change.")
+            result = safely(console, lambda q=ask: spin(s, console, "Pal is debugging…", lambda: wf.tell(q)))
+        finally:
+            s.mode = mode
+        if result is None:
+            return False
+        if result.text:
+            ui.show_reply(console, result, s)
+        if not result.changes:
+            say("  The Build agent proposed no file change, so /debug stops here.")
+            console.print()
+            return False
+        if not parses_or_confirmed(wf, console):
+            return False
+        files = ", ".join(sorted(wf.plan.b.pending))
+        if not wf.plan.setting("auto-apply") and not ui.confirm(console, f"Apply {files} and run  {cmd}  again?"):
+            say("  Stopped. The fix stays in the sandbox: /diff, /apply.")
+            console.print()
+            return False
+        for path in wf.plan.b.pending:
+            before.setdefault(path, wf.disk(path))
+        res = wf.apply(lambda c: (None, ""))            # write the fix; the command is run by this loop, not by apply
+        written += res.written
+    say(f"  Still failing after {tries} fix{'es' if tries != 1 else ''}.", theme.RED_HI)
+    if before and ui.confirm(console, f"Put the {len(before)} file(s) /debug changed back as they were?"):
+        wf._roll_back(before)
+        say("  Put back.")
+    console.print()
+    return False
+
+
+def handle_flow(cmd: str, rest: str, wf: Workflow, console: Console) -> bool:
+    """The workflow commands. True when `cmd` was one of them."""
+    say = lambda text, style=theme.MUTED: ui.say(console, Text(text, style=style))  # noqa: E731
+    b = wf.plan.b
+    try:
+        if cmd == "/plans":
+            for i, name in enumerate(wf.store.names(), 1):
+                say(f"{i:>3}  {name}" + ("   ◀ current" if name == wf.plan.name else ""), theme.WHITE if name == wf.plan.name else theme.INK)
+        elif cmd == "/current":
+            say(f"Plan {wf.plan.name}  ·  branch {wf.plan.branch}  ·  autonomy {wf.plan.autonomy}", f"bold {theme.WHITE}")
+            say(f"{len(b.steps)} steps ({b.done} built)  ·  {len(b.context)} files in context  ·  {len(b.pending)} pending  ·  {len(b.convo) // 2} messages")
+            if b.steps:
+                show_steps(wf, console)
+        elif cmd == "/rename":
+            wf.rename(rest)
+            say(f"Renamed to {rest}.")
+        elif cmd == "/delete-plan":
+            wf.delete(rest or wf.plan.name)
+            say(f"Deleted. Now on plan {wf.plan.name}.")
+        elif cmd == "/load":
+            note = ""
+            if rest.startswith("-n "):
+                note, rest = rest[3:].strip().strip("\"'"), ""
+            from pal.terminal.cli import split_paths
+            added, problems = wf.load(split_paths(rest), note)
+            for a in added:
+                say(f"  + {a}", theme.INK)
+            for p in problems:
+                say(f"  {p}", theme.RED_HI)
+            say(f"{len(b.context)} files in context. They go with every request; a file the model already has is not sent again.")
+        elif cmd == "/ls":
+            rows = wf.context_rows()
+            if not rows:
+                say("The context is empty. Add files with  /load <file or folder or glob>.")
+            grid = Table.grid(padding=(0, 2))
+            for i, name, tokens, problem in rows:
+                grid.add_row(Text(f"{i}", style=theme.MUTED), Text(name, style=theme.WHITE), Text(f"{tokens:,} tok", style=theme.INK), Text(problem, style=theme.RED_HI))
+            if rows:
+                ui.say(console, grid)
+                say(f"total about {sum(r[2] for r in rows):,} tokens")
+        elif cmd == "/rm":
+            from pal.terminal.cli import split_paths
+            gone = wf.remove(split_paths(rest))
+            say("removed: " + (", ".join(gone) or "nothing matched"))
+        elif cmd in ("/clear-context", "/unload"):
+            say(f"Removed {wf.clear()} item(s) from the context.")
+        elif cmd == "/continue":
+            continue_flow(wf, console, every=rest.strip() == "all")
+            return True
+        elif cmd == "/diff":
+            show_diff(wf, console)
+            return True
+        elif cmd == "/review":
+            from pal.terminal.review import open_review
+            path = open_review(wf)
+            say(f"Opened the review in your browser ({path}).")
+        elif cmd == "/apply":
+            apply_flow(wf, console, yes=rest.strip() in ("-y", "--yes"))
+            return True
+        elif cmd == "/reject":
+            gone = wf.reject(None if rest.strip() in ("all", "--all") else rest.split())
+            say("dropped: " + (", ".join(gone) or "nothing (give a pending file, or all)") + ("   (/rewind brings them back)" if gone else ""))
+        elif cmd == "/log":
+            vs = wf.log()
+            if not vs:
+                say("No versions yet: the Build agent's changes appear here.")
+            for v in reversed(vs[-30:]):
+                say(f"  {v.id}  {time.strftime('%H:%M', time.localtime(v.t))}  {len(v.pending):>2} pending  {v.label}", theme.INK)
+        elif cmd == "/rewind":
+            n = wf.rewind(int(rest) if rest.strip().isdigit() else 1, to="" if not rest.strip() or rest.strip().isdigit() else rest.strip())
+            say(f"Went back {n} version(s). {len(wf.plan.b.pending)} file(s) pending.")
+        elif cmd == "/convo":
+            for m in b.convo[-20:]:
+                ui.say(console, Text.assemble((f"{m['role']} ({m['agent']}): ", theme.RED_HI if m["role"] == "you" else theme.WHITE), (ui.clean_terminal(m["text"][:500]), theme.INK)))
+        elif cmd == "/branches":
+            for name in wf.plan.branches:
+                say(f"  {name}" + ("   ◀ current" if name == wf.plan.branch else ""), theme.WHITE if name == wf.plan.branch else theme.INK)
+        elif cmd == "/checkout":
+            created = wf.checkout(rest.strip())
+            say(f"{'Created and switched to' if created else 'Switched to'} branch {rest.strip()}.")
+        elif cmd == "/delete-branch":
+            wf.delete_branch(rest.strip())
+            say(f"Deleted branch {rest.strip()}.")
+        elif cmd == "/autonomy":
+            level = rest.strip().lower()
+            if level in AUTONOMY:
+                wf.plan.autonomy, wf.plan.custom = level, {}
+                wf.save()
+            say(f"Autonomy: {wf.plan.autonomy}" + ("" if level in AUTONOMY else "   (choose none, basic, plus, semi or full)"), f"bold {theme.WHITE}")
+            for name in SETTINGS:
+                say(f"  {'on ' if wf.plan.setting(name) else 'off'}  {name:<18} {SETTING_ABOUT[name]}", theme.INK if wf.plan.setting(name) else theme.MUTED)
+            if wf.plan.autonomy == "full":
+                say("Full runs commands and applies changes without asking: use it on a clean git branch.", theme.RED_HI)
+        elif cmd == "/set":
+            name, _, value = rest.partition(" ")
+            if name not in SETTINGS or value.strip().lower() not in ("on", "off", "true", "false"):
+                say(f"Use: /set <setting> on|off   settings: {', '.join(SETTINGS)}")
+            else:
+                wf.plan.custom[name] = value.strip().lower() in ("on", "true")
+                wf.save()
+                say(f"{name}: {'on' if wf.plan.setting(name) else 'off'}")
+        elif cmd == "/debug":
+            if not rest.strip():
+                say("Use: /debug <command>   for example  /debug npm test   or  /debug python -m pytest -q")
+            elif wf.plan.setting("can-exec") or ui.confirm(console, f"Commands are off for this plan (can-exec). Run  {rest.strip()}  anyway?"):
+                debug_flow(wf, rest.strip(), console)
+        elif cmd == "/run":
+            if not rest.strip():
+                say("Use: /run <command>")
+            elif ui.confirm(console, f"Run  {rest.strip()}  in {ui.short_path(wf.session.cwd)}?"):
+                ok, out = spin(wf.session, console, "Running…", lambda: run_shell(rest.strip(), wf.session.cwd))
+                ui.say(console, Padding(Text(ui.clean_terminal("\n".join(out.strip().splitlines()[-30:])), style=theme.INK), (0, 0, 0, 2)))
+                say("✓ exit 0" if ok else "✗ failed", theme.WHITE if ok else theme.RED_HI)
+        else:
+            return False
+    except ValueError as e:
+        say(str(e), theme.RED_HI)
+    console.print()
+    return True

pal/terminal/hardware.py

@@ -0,0 +1,199 @@
+"""What this computer can run: its GPUs and their video memory (VRAM), Apple Silicon's shared memory, and system RAM.
+
+Read without installing anything: `nvidia-smi` for NVIDIA cards (it ships with the driver), sysfs for AMD on Linux, the registry on Windows, `sysctl`
+on macOS. Every probe is optional and short; a probe that fails simply finds nothing, and Pal then plans for running on the CPU.
+"""
+from __future__ import annotations
+
+import os
+import platform
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class GPU:
+    name: str
+    vram_gb: float
+    vendor: str            # "nvidia" | "amd" | "intel" | "apple" | "other"
+
+
+@dataclass
+class Hardware:
+    system: str = ""                         # "Windows" | "Darwin" | "Linux"
+    ram_gb: float = 0.0
+    gpus: list[GPU] = field(default_factory=list)
+    apple_silicon: bool = False
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def discrete(self) -> list[GPU]:
+        """Cards with their own memory that Ollama can use (NVIDIA, AMD). Intel graphics share system memory and are treated as CPU."""
+        return [g for g in self.gpus if g.vendor in ("nvidia", "amd") and g.vram_gb >= 1.5]
+
+    @property
+    def vram_gb(self) -> float:
+        """Memory a model can use on the GPU: all NVIDIA (or all AMD) cards together, since Ollama splits a model across cards; Apple: shared memory."""
+        if self.apple_silicon:
+            return round(self.ram_gb * 0.70, 1)          # macOS lets the GPU use about two thirds to three quarters of unified memory
+        by_vendor: dict[str, float] = {}
+        for g in self.discrete:
+            by_vendor[g.vendor] = by_vendor.get(g.vendor, 0.0) + g.vram_gb
+        return round(max(by_vendor.values(), default=0.0), 1)
+
+    @property
+    def kind(self) -> str:
+        return "apple" if self.apple_silicon else ("gpu" if self.vram_gb else "cpu")
+
+    def summary(self) -> str:
+        if self.apple_silicon:
+            chip = self.gpus[0].name if self.gpus else "Apple Silicon"
+            return f"{chip} · {self.ram_gb:g} GB unified memory (about {self.vram_gb:g} GB for models)"
+        if self.discrete:
+            names = ", ".join(f"{g.name} {g.vram_gb:g} GB" for g in self.discrete)
+            return f"{names} · {self.ram_gb:g} GB RAM"
+        return f"no GPU · {self.ram_gb:g} GB RAM"
+
+
+def _run(cmd: list[str], timeout: float = 4.0) -> str:
+    exe = shutil.which(cmd[0])
+    if not exe:
+        return ""
+    try:
+        r = subprocess.run([exe, *cmd[1:]], capture_output=True, text=True, timeout=timeout)
+        return r.stdout if r.returncode == 0 else ""
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def _nvidia() -> list[GPU]:
+    out = _run(["nvidia-smi", "--query-gpu=name,memory.total", "--format=csv,noheader,nounits"])
+    gpus = []
+    for line in out.splitlines():
+        name, _, mb = line.rpartition(",")
+        try:
+            gpus.append(GPU(name.strip() or "NVIDIA GPU", round(float(mb) / 1024, 1), "nvidia"))
+        except ValueError:
+            continue
+    return gpus
+
+
+def _amd_linux(root: Path = Path("/sys/class/drm")) -> list[GPU]:
+    gpus = []
+    for card in sorted(root.glob("card[0-9]*")) if root.is_dir() else []:
+        dev = card / "device"
+        vram = dev / "mem_info_vram_total"
+        if "-" in card.name or not vram.is_file():
+            continue
+        try:
+            gb = round(int(vram.read_text().strip()) / 1024**3, 1)
+        except (OSError, ValueError):
+            continue
+        name = "AMD GPU"
+        for f in ("product_name", "model"):
+            try:
+                name = (dev / f).read_text().strip() or name
+                break
+            except OSError:
+                continue
+        gpus.append(GPU(name, gb, "amd"))
+    return gpus
+
+
+def _windows_gpus() -> list[GPU]:
+    """Every display adapter from the registry, with its real memory size (qwMemorySize; WMI's AdapterRAM stops at 4 GB)."""
+    if sys.platform != "win32":
+        return []
+    import winreg
+    base = r"SYSTEM\CurrentControlSet\Control\Class\{4d36e968-e325-11ce-bfc1-08002be10318}"
+    gpus = []
+    try:
+        root = winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, base)
+    except OSError:
+        return []
+    for i in range(32):
+        try:
+            sub = winreg.OpenKey(root, f"{i:04d}")
+        except OSError:
+            break
+        try:
+            name = str(winreg.QueryValueEx(sub, "DriverDesc")[0])
+        except OSError:
+            continue
+        size = 0
+        for value in ("HardwareInformation.qwMemorySize", "HardwareInformation.MemorySize"):
+            try:
+                raw = winreg.QueryValueEx(sub, value)[0]
+                size = int.from_bytes(raw, "little") if isinstance(raw, bytes) else int(raw)
+                break
+            except (OSError, ValueError, TypeError):
+                continue
+        low = name.lower()
+        vendor = "nvidia" if "nvidia" in low else "amd" if ("amd" in low or "radeon" in low) else "intel" if "intel" in low else "other"
+        gpus.append(GPU(name, round(size / 1024**3, 1), vendor))
+    return gpus
+
+
+def _ram_gb(system: str) -> float:
+    try:
+        if system == "Linux":
+            for line in Path("/proc/meminfo").read_text().splitlines():
+                if line.startswith("MemTotal:"):
+                    return round(int(line.split()[1]) / 1024**2, 1)
+        if system == "Darwin":
+            out = _run(["sysctl", "-n", "hw.memsize"])
+            return round(int(out.strip()) / 1024**3, 1) if out.strip() else 0.0
+        if system == "Windows":
+            import ctypes
+
+            class MEMORYSTATUSEX(ctypes.Structure):
+                _fields_ = [("dwLength", ctypes.c_ulong), ("dwMemoryLoad", ctypes.c_ulong), ("ullTotalPhys", ctypes.c_ulonglong),
+                            ("ullAvailPhys", ctypes.c_ulonglong), ("ullTotalPageFile", ctypes.c_ulonglong), ("ullAvailPageFile", ctypes.c_ulonglong),
+                            ("ullTotalVirtual", ctypes.c_ulonglong), ("ullAvailVirtual", ctypes.c_ulonglong), ("sullAvailExtendedVirtual", ctypes.c_ulonglong)]
+            stat = MEMORYSTATUSEX()
+            stat.dwLength = ctypes.sizeof(MEMORYSTATUSEX)
+            ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(stat))  # type: ignore[attr-defined]
+            return round(stat.ullTotalPhys / 1024**3, 1)
+    except (OSError, ValueError, AttributeError):
+        pass
+    try:
+        return round(os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES") / 1024**3, 1)
+    except (ValueError, OSError, AttributeError):
+        return 0.0
+
+
+def detect() -> Hardware:
+    """Look at this computer. Never raises."""
+    system = platform.system()
+    hw = Hardware(system=system, ram_gb=_ram_gb(system))
+    if system == "Darwin" and platform.machine().lower() in ("arm64", "aarch64"):
+        hw.apple_silicon = True
+        chip = _run(["sysctl", "-n", "machdep.cpu.brand_string"]).strip() or "Apple Silicon"
+        hw.gpus.append(GPU(chip, hw.ram_gb, "apple"))
+        return hw
+    hw.gpus = _nvidia()
+    if system == "Linux":
+        hw.gpus += _amd_linux()
+    if system == "Windows":
+        known = {g.name for g in hw.gpus}
+        hw.gpus += [g for g in _windows_gpus() if g.name not in known]
+    if not hw.discrete and any(g.vendor == "nvidia" for g in hw.gpus):
+        hw.notes.append("an NVIDIA card was found but not its memory: install or update the NVIDIA driver so nvidia-smi works")
+    return hw
+
+
+def from_spec(text: str) -> Hardware:
+    """A pretend computer for trying out recommendations: "cpu:16", "gpu:12" (VRAM GB, RAM 32), "gpu:24:64", "mac:16"."""
+    m = re.fullmatch(r"\s*(cpu|gpu|mac):(\d+(?:\.\d+)?)(?::(\d+(?:\.\d+)?))?\s*", text.lower())
+    if not m:
+        raise ValueError("use cpu:<RAM GB>, gpu:<VRAM GB>[:<RAM GB>] or mac:<memory GB>")
+    kind, a, b = m.group(1), float(m.group(2)), float(m.group(3)) if m.group(3) else None
+    if kind == "cpu":
+        return Hardware("Linux", a)
+    if kind == "mac":
+        return Hardware("Darwin", a, [GPU("Apple Silicon", a, "apple")], apple_silicon=True)
+    return Hardware("Linux", b or max(16.0, a * 2), [GPU("GPU", a, "nvidia")])