pal-code 0.1.0__py3-none-any.whl

pal/terminal/history.py

@@ -0,0 +1,88 @@
+"""What you typed before, per folder: ↑ and ↓ in the input box walk through it, Ctrl+R searches it.
+
+Kept in ~/.pal/projects/<folder id>/history (newest last, at most MAX entries). A line that sets a key (/key ...) is never kept, and
+key-shaped strings in any line are hidden first, so the file never holds a secret.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pal.paths import pal_home
+from pal.terminal.security import redact_secrets
+from pal.terminal.workflow import project_id
+
+MAX = 500
+
+
+class History:
+    def __init__(self, folder: Path, home: Path | None = None):
+        self.path = (home or pal_home()) / "projects" / project_id(Path(folder)) / "history"
+        self.items: list[str] = self._load()
+
+    def _load(self) -> list[str]:
+        try:
+            lines = self.path.read_text(encoding="utf-8").splitlines()
+        except OSError:
+            return []
+        out = []
+        for line in lines:
+            try:
+                item = json.loads(line)
+            except ValueError:
+                continue
+            if isinstance(item, str) and item.strip():
+                out.append(item)
+        return out[-MAX:]
+
+    def add(self, text: str) -> None:
+        text = text.strip()
+        if not text or text.split(" ", 1)[0] in ("/key",):
+            return
+        text, _ = redact_secrets(text)
+        if self.items and self.items[-1] == text:
+            return
+        self.items.append(text)
+        self.items = self.items[-MAX:]
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text("".join(json.dumps(x) + "\n" for x in self.items), encoding="utf-8")
+        except OSError:
+            pass
+
+    def search(self, query: str, before: int) -> int | None:
+        """The index of the newest entry older than `before` that contains `query` (case-insensitive), or None."""
+        q = query.lower()
+        for i in range(min(before, len(self.items)) - 1, -1, -1):
+            if q in self.items[i].lower():
+                return i
+        return None
+
+
+class Browser:
+    """↑/↓ through a History while typing, keeping the unsent draft to come back to."""
+
+    def __init__(self, history: History):
+        self.h, self.pos, self.draft = history, len(history.items), ""
+
+    def older(self, current: str) -> str | None:
+        if self.pos == len(self.h.items):
+            self.draft = current
+        if self.pos == 0:
+            return None
+        self.pos -= 1
+        return self.h.items[self.pos]
+
+    def newer(self) -> str | None:
+        if self.pos >= len(self.h.items):
+            return None
+        self.pos += 1
+        return self.draft if self.pos == len(self.h.items) else self.h.items[self.pos]
+
+    def find(self, query: str) -> str | None:
+        """Ctrl+R: the next older entry containing the query."""
+        i = self.h.search(query, self.pos)
+        if i is None:
+            return None
+        self.pos = i
+        return self.h.items[i]

pal/terminal/keys.py

@@ -0,0 +1,83 @@
+"""Esc stops Pal while it works (a model reply, a check running), like Ctrl+C, and the box comes back.
+
+While a spinner runs, a small thread watches the keyboard. A lone Esc (not the start of an arrow key's escape sequence) interrupts the main
+thread, which the request code already handles as "Stopped.". Ctrl+C keeps working as before. Only in a real terminal.
+"""
+from __future__ import annotations
+
+import _thread
+import os
+import sys
+import threading
+import time
+
+
+class EscToStop:
+    def __init__(self, enabled: bool | None = None):
+        self.enabled = (sys.stdin.isatty() and sys.stdout.isatty()) if enabled is None else enabled
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._saved: list | None = None
+        self.pressed = False
+
+    def __enter__(self) -> EscToStop:
+        if not self.enabled:
+            return self
+        if os.name != "nt":
+            try:
+                import termios
+                import tty
+                fd = sys.stdin.fileno()
+                self._saved = termios.tcgetattr(fd)
+                tty.setcbreak(fd)                       # keys arrive one by one; Ctrl+C still sends an interrupt
+            except Exception:  # noqa: BLE001  (not a real terminal after all)
+                self.enabled = False
+                return self
+        self._thread = threading.Thread(target=self._watch, daemon=True, name="pal-esc")
+        self._thread.start()
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(0.5)
+        if self._saved is not None:
+            try:
+                import termios
+                termios.tcsetattr(sys.stdin.fileno(), termios.TCSADRAIN, self._saved)
+            except Exception:  # noqa: BLE001
+                pass
+
+    def _fire(self) -> None:
+        self.pressed = True
+        self._stop.set()
+        _thread.interrupt_main()
+
+    def _watch(self) -> None:
+        if os.name == "nt":
+            import msvcrt
+            while not self._stop.is_set():
+                if msvcrt.kbhit():  # type: ignore[attr-defined]
+                    ch = msvcrt.getwch()  # type: ignore[attr-defined]
+                    if ch == "\x1b":
+                        self._fire()
+                        return
+                    if ch in ("\x00", "\xe0") and msvcrt.kbhit():  # type: ignore[attr-defined]
+                        msvcrt.getwch()  # type: ignore[attr-defined]   # the second half of an arrow or function key
+                time.sleep(0.05)
+            return
+        import select
+        fd = sys.stdin.fileno()
+        while not self._stop.is_set():
+            ready, _, _ = select.select([fd], [], [], 0.1)
+            if not ready:
+                continue
+            ch = os.read(fd, 1)
+            if ch != b"\x1b":
+                continue
+            more, _, _ = select.select([fd], [], [], 0.05)      # an arrow key sends ESC [ A at once; a lone Esc sends nothing after
+            if more:
+                os.read(fd, 8)
+                continue
+            self._fire()
+            return

pal/terminal/local_models.py

@@ -0,0 +1,261 @@
+"""Which local model to run on which computer.
+
+The catalogue lists well-known models from the Ollama library with their 4-bit download size (Ollama's default `q4_K_M` builds; sizes are
+approximate). From the size Pal works out the video memory each needs, so it can group them by GPU, and pick for this computer:
+
+- the **main model**, which writes and plans when you choose a local model: the strongest one that fits next to the helper;
+- the **helper**, the small model Pal runs for its own jobs on every request (routing, trimming what you type, checking answers): a fast one.
+
+Models that are already installed but not in the catalogue are judged the same way, from their size. Reasoning models (deepseek-r1, qwen3) print
+their thinking before the answer, so they are listed but not picked automatically.
+"""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+
+from pal.terminal.hardware import Hardware
+
+CONTEXT_GB = 1.0          # room for the conversation (an 8k-token context) on top of the weights
+OVERHEAD = 1.1            # runtime buffers on top of the file size
+USABLE = 0.92             # the share of VRAM a model can really use (the desktop and drivers keep some)
+TIERS = [0, 4, 6, 8, 12, 16, 24, 48, 80]     # GB of VRAM (0 = no GPU, runs on the CPU)
+
+
+@dataclass(frozen=True)
+class LocalModel:
+    tag: str
+    params_b: float
+    size_gb: float
+    use: str               # "code" | "general" | "reasoning" | "small"
+    rank: int              # how well it builds and plans in Pal (higher is better)
+    helper: bool = False   # fast and follows short instructions well: a good helper
+    thinks: bool = False   # prints its reasoning first: not picked automatically
+    note: str = ""
+
+    @property
+    def need_gb(self) -> float:
+        """Memory to run it with a working context."""
+        return round(self.size_gb * OVERHEAD + CONTEXT_GB, 1)
+
+    @property
+    def min_vram_gb(self) -> int:
+        """The smallest GPU tier it fits on fully."""
+        need = self.need_gb / USABLE
+        return next((t for t in TIERS[1:] if t >= need), math.ceil(need))
+
+
+CATALOGUE: list[LocalModel] = [
+    # tiny: helpers, and machines without a GPU
+    LocalModel("qwen2.5:0.5b", 0.5, 0.4, "small", 22, helper=True, note="tiny and fast; a helper for small machines"),
+    LocalModel("qwen3:0.6b", 0.6, 0.5, "small", 25, thinks=True),
+    LocalModel("gemma3:1b", 1.0, 0.8, "small", 34),
+    LocalModel("llama3.2:1b", 1.2, 1.3, "small", 35, helper=True),
+    LocalModel("qwen2.5:1.5b", 1.5, 1.0, "small", 42, helper=True, note="the default helper: fast, follows instructions"),
+    LocalModel("qwen2.5-coder:1.5b", 1.5, 1.0, "code", 46, note="small coder for CPU-only machines"),
+    LocalModel("qwen3:1.7b", 1.7, 1.4, "small", 45, thinks=True),
+    LocalModel("llama3.2:3b", 3.2, 2.0, "small", 52, helper=True, note="the best helper when there is room"),
+    LocalModel("qwen2.5:3b", 3.1, 1.9, "small", 53, helper=True),
+    LocalModel("qwen2.5-coder:3b", 3.1, 1.9, "code", 56, note="coder for 4 GB GPUs and CPUs"),
+    LocalModel("phi4-mini", 3.8, 2.5, "general", 57),
+    LocalModel("qwen3:4b", 4.0, 2.6, "general", 60, thinks=True),
+    LocalModel("gemma3:4b", 4.3, 3.3, "general", 58),
+    # 7-9B: 6-8 GB GPUs
+    LocalModel("mistral:7b", 7.2, 4.1, "general", 62),
+    LocalModel("qwen2.5:7b", 7.6, 4.7, "general", 71),
+    LocalModel("qwen2.5-coder:7b", 7.6, 4.7, "code", 75, note="best coder for 8 GB GPUs"),
+    LocalModel("llama3.1:8b", 8.0, 4.9, "general", 70),
+    LocalModel("qwen3:8b", 8.2, 5.2, "general", 73, thinks=True),
+    LocalModel("deepseek-r1:8b", 8.0, 5.2, "reasoning", 69, thinks=True),
+    LocalModel("gemma2:9b", 9.2, 5.4, "general", 68),
+    # 12-16B: 12-16 GB GPUs
+    LocalModel("mistral-nemo:12b", 12.2, 7.1, "general", 74),
+    LocalModel("gemma3:12b", 12.0, 8.1, "general", 77),
+    LocalModel("deepseek-coder-v2:16b", 16.0, 8.9, "code", 78, note="fast for its size (mixture of experts)"),
+    LocalModel("qwen2.5:14b", 14.7, 9.0, "general", 80),
+    LocalModel("qwen2.5-coder:14b", 14.7, 9.0, "code", 83, note="best coder for 12-16 GB GPUs"),
+    LocalModel("deepseek-r1:14b", 14.8, 9.0, "reasoning", 79, thinks=True),
+    LocalModel("phi4:14b", 14.7, 9.1, "general", 81),
+    LocalModel("qwen3:14b", 14.8, 9.3, "general", 82, thinks=True),
+    # 22-32B: 24 GB GPUs
+    LocalModel("codestral:22b", 22.2, 13.0, "code", 85),
+    LocalModel("mistral-small:24b", 23.6, 14.0, "general", 84),
+    LocalModel("gemma3:27b", 27.4, 17.0, "general", 86),
+    LocalModel("qwen3:30b", 30.5, 19.0, "general", 87, thinks=True, note="mixture of experts: fast for its size"),
+    LocalModel("qwen2.5:32b", 32.8, 20.0, "general", 89),
+    LocalModel("qwen2.5-coder:32b", 32.8, 20.0, "code", 95, note="best local coder for 24 GB GPUs"),
+    LocalModel("qwen3:32b", 32.8, 20.0, "general", 91, thinks=True),
+    LocalModel("deepseek-r1:32b", 32.8, 20.0, "reasoning", 88, thinks=True),
+    # 70B+: 48 GB and more
+    LocalModel("llama3.3:70b", 70.6, 43.0, "general", 92),
+    LocalModel("deepseek-r1:70b", 70.6, 43.0, "reasoning", 90, thinks=True),
+    LocalModel("qwen2.5:72b", 72.7, 47.0, "general", 94),
+    # newer models (sizes are Ollama's default downloads, October 2026)
+    LocalModel("qwen3.5:0.8b", 0.8, 1.3, "small", 30, thinks=True),
+    LocalModel("qwen3.5:2b", 2.0, 2.7, "small", 50, thinks=True),
+    LocalModel("qwen3.5:4b", 4.0, 3.4, "general", 64, thinks=True),
+    LocalModel("gemma4:e2b", 2.0, 4.6, "general", 55, thinks=True, note="reads images too"),
+    LocalModel("gemma4:e4b", 4.0, 6.6, "general", 66, thinks=True, note="reads images too"),
+    LocalModel("qwen3.5:9b", 9.0, 6.6, "general", 79, thinks=True, note="reads images too"),
+    LocalModel("gemma4:12b", 12.0, 8.0, "general", 82, thinks=True, note="reads images too"),
+    LocalModel("gpt-oss:20b", 21.0, 14.0, "reasoning", 90, thinks=True, note="OpenAI's open model; reasons before answering"),
+    LocalModel("devstral-small-2:24b", 24.0, 15.0, "code", 93, note="agentic coding: multi-file edits, explores a codebase"),
+    LocalModel("qwen3.5:27b", 27.0, 17.0, "general", 92, thinks=True),
+    LocalModel("qwen3.6:27b", 27.0, 18.0, "code", 96, thinks=True, note="strong agentic coder; thinks first"),
+    LocalModel("gemma4:26b", 26.0, 18.0, "general", 89, thinks=True, note="mixture of experts: fast for its size"),
+    LocalModel("qwen3-coder:30b", 30.5, 19.0, "code", 97, note="best local coder for 24 GB GPUs: mixture of experts, fast, 256K context"),
+    LocalModel("gemma4:31b", 31.0, 20.0, "general", 91, thinks=True),
+    LocalModel("qwen3.5:35b", 35.0, 22.0, "general", 93, thinks=True, note="mixture of experts: fast for its size"),
+    LocalModel("qwen3.6:35b", 35.0, 24.0, "code", 97, thinks=True, note="mixture of experts; strong agentic coder; thinks first"),
+]
+BY_TAG = {m.tag: m for m in CATALOGUE}
+
+
+def budget_gb(hw: Hardware) -> float:
+    """Memory models may use: on the GPU (or Apple's shared memory) when there is one, else half the RAM for running on the CPU."""
+    return round(hw.vram_gb * (1.0 if hw.apple_silicon else USABLE), 1) if hw.vram_gb else round(hw.ram_gb * 0.5, 1)
+
+
+def fit(need_gb: float, hw: Hardware) -> str:
+    """'gpu' (fits on the GPU), 'partial' (part on the GPU, part on the CPU: works, slower), 'no gpu' (Pal does not run local models without one)
+    or 'too big'."""
+    if hw.vram_gb:
+        room = budget_gb(hw)
+        if need_gb <= room:
+            return "gpu"
+        if not hw.apple_silicon and need_gb <= room + hw.ram_gb * 0.5:
+            return "partial"
+        return "too big"
+    return "no gpu"
+
+
+FIT_LABEL = {"gpu": "fits your GPU", "partial": "partly on the CPU (slower)", "no gpu": "needs a GPU", "too big": "too big for this computer"}
+
+
+def tier_name(hw: Hardware) -> str:
+    if not hw.vram_gb:
+        return "no GPU (API models only)"
+    if hw.apple_silicon:
+        return f"{hw.ram_gb:g} GB unified memory"
+    vram = hw.vram_gb
+    t = max((x for x in TIERS[1:] if x <= vram + 0.5), default=4)
+    return f"{t} GB {'unified memory' if hw.apple_silicon else 'GPU'}"
+
+
+@dataclass
+class Recommendation:
+    main: LocalModel
+    helper: LocalModel
+    others: list[LocalModel]          # other good choices that fit, best first
+    reason: str
+
+
+def pick_helper(hw: Hardware) -> LocalModel:
+    room = budget_gb(hw)
+    if hw.vram_gb and room >= 14:
+        return BY_TAG["llama3.2:3b"]
+    if (hw.vram_gb and room >= 4.5) or (not hw.vram_gb and hw.ram_gb >= 12):
+        return BY_TAG["qwen2.5:1.5b"]
+    return BY_TAG["qwen2.5:0.5b"]
+
+
+def api_only(hw: Hardware) -> bool:
+    """No GPU (and not Apple Silicon): Pal offers no local model on this computer and uses API models only."""
+    return not hw.vram_gb
+
+
+CODE_BONUS = 8          # Pal writes software: a coding model beats a general one of a similar rank (qwen2.5-coder:3b over mistral:7b)
+
+
+def score(m: LocalModel) -> int:
+    return m.rank + (CODE_BONUS if m.use == "code" else 0)
+
+
+def recommend(hw: Hardware) -> Recommendation | None:
+    """The best main model that fits the GPU (coding models first: Pal builds software), and the helper. The helper goes on the GPU beside the
+    main model when there is room, else on the CPU, where a small model is still quick. On a CPU only, models are kept small enough to answer
+    in reasonable time."""
+    if api_only(hw):
+        return None
+    helper = pick_helper(hw)
+    room = budget_gb(hw)
+    usable = [m for m in CATALOGUE if not m.thinks and m.use != "small" and m.need_gb <= room]
+    if not usable:
+        usable = [m for m in CATALOGUE if not m.thinks and m.need_gb <= max(room, 1.6)] or [BY_TAG["qwen2.5-coder:1.5b"]]
+    ranked = sorted(usable, key=score, reverse=True)
+    main = ranked[0]
+    where = "on your GPU" if hw.vram_gb else "on your CPU"
+    if main.need_gb + helper.need_gb - CONTEXT_GB <= room or not hw.vram_gb:
+        beside = "beside it"
+    else:
+        beside = "when needed (Ollama swaps the two in shared memory)" if hw.apple_silicon else "on the CPU, where it is still quick"
+    reason = f"the strongest model that runs {where} ({main.need_gb:g} GB of about {room:g} GB); the helper runs {beside}"
+    return Recommendation(main, helper, ranked[1:6], reason)
+
+
+def by_tier() -> list[tuple[int, list[LocalModel]]]:
+    """The catalogue grouped by the smallest GPU each model fits on fully."""
+    groups: dict[int, list[LocalModel]] = {}
+    for m in CATALOGUE:
+        groups.setdefault(m.min_vram_gb, []).append(m)
+    return [(t, sorted(ms, key=lambda m: -m.rank)) for t, ms in sorted(groups.items())]
+
+
+_BASE = re.compile(r"^([^:]+):(\d+(?:\.\d+)?[bm])\b", re.I)
+
+
+def lookup(name: str) -> LocalModel | None:
+    """The catalogue entry for an installed model, also for longer tags of the same model (llama3.1:8b-instruct-q4_K_M is llama3.1:8b)."""
+    if name in BY_TAG or name.removesuffix(":latest") in BY_TAG:
+        return BY_TAG.get(name) or BY_TAG[name.removesuffix(":latest")]
+    m = _BASE.match(name)
+    return BY_TAG.get(f"{m.group(1)}:{m.group(2).lower()}") if m else None
+
+
+def guess_rank(params_b: float) -> int:
+    """A rank for a model the catalogue does not know, from its size: bigger is usually better, with diminishing returns."""
+    return int(min(90, 30 + 7 * math.log2(params_b))) if params_b >= 1 else 20
+
+
+def installed_fit(models: list[dict], hw: Hardware) -> list[dict]:
+    """Ollama's installed models with how each fits: from the catalogue when known, else from the file size Ollama reports."""
+    out = []
+    for m in models:
+        if m.get("embedding"):
+            continue
+        known = lookup(m["name"])
+        need = round((m.get("size_gb") or 0) * OVERHEAD + CONTEXT_GB, 1) if m.get("size_gb") else (known.need_gb if known else CONTEXT_GB)
+        out.append({**m, "need_gb": need, "fit": fit(need, hw), "rank": known.rank if known else guess_rank(m.get("params_b") or 0)})
+    return out
+
+
+def best_installed(models: list[dict], hw: Hardware, exclude: str = "") -> str | None:
+    """The strongest installed chat model that fits the GPU (or CPU); if none fits, the smallest one."""
+    rows = [r for r in installed_fit(models, hw) if r["name"] != exclude]
+    if not rows:
+        return None
+    if api_only(hw):
+        return None
+    good = [r for r in rows if r["fit"] == "gpu"]
+    return (max(good, key=lambda r: (r["rank"], r["need_gb"])) if good else min(rows, key=lambda r: r["need_gb"]))["name"]
+
+
+def suitable(hw: Hardware, installed: list[str] | None = None, limit: int = 6) -> list[tuple[str, str, bool]]:
+    """Main-model choices for this GPU, best first: (tag, one line about it, installed?). The recommended model leads, then installed models that
+    fit, then the next best downloads. Reasoning models are left out (they can still be chosen by name)."""
+    rec = recommend(hw)
+    if rec is None:
+        return []
+    have = set()
+    for h in installed or []:
+        known = lookup(h)
+        have.add(known.tag if known else h)
+    picks = [rec.main] + [m for m in rec.others if m.tag != rec.main.tag]
+    for name in installed or []:
+        known = lookup(name)
+        if known and known not in picks and not known.thinks and known.use != "small" and fit(known.need_gb, hw) == "gpu":
+            picks.append(known)
+    picks.sort(key=lambda m: (m.tag != rec.main.tag, m.tag not in have, -score(m)))
+    return [(m.tag, (f"installed · {m.note or m.use}" if m.tag in have else f"{m.size_gb:g} GB download · {m.note or m.use}"), m.tag in have)
+            for m in picks[:limit]]

pal/terminal/logo.py

@@ -0,0 +1,117 @@
+"""The Pal logo (two people hugging, white and red with a black outline) as pixels for the terminal.
+
+Drawn from the logo image at 24 x 26 pixels with half blocks, two pixel rows per text line, so it shows in any terminal with colour and needs no
+image support. W white, R red, K the black outline, . see-through (the terminal's own background).
+"""
+from __future__ import annotations
+
+from pal.terminal import theme
+
+GRID = [
+    '......KKKK.....K........',
+    '.....KWWWWWK.KRRRK......',
+    '....KWWWWWWWKRRRRRK.....',
+    '....KWWWWWWWKRRRRRRK....',
+    '....KWWWWWWWWKRRRRRR....',
+    '....KWWWWWWWWKRRRRRR....',
+    '....KWWWWWWWWKRRRRRR....',
+    '....KWWWWWWWWWRRRRRR....',
+    '....KWWWWWWWWKRRRRRK....',
+    '...KRKWWWWWWWKRRRRKKK...',
+    '..KRRKKWWWWWWKRRRKWWK...',
+    '..KRRRKKWWWWKRRRRKWWK...',
+    '...KRRRRKKKKRRRRRKKKK...',
+    '..KKKRRRRRRRRRRRRRRRRK..',
+    '..WWWKRRRRRRRRKKWKRRRR..',
+    '.KWWWWKRRRRRRKWWWKRRRRK.',
+    '.KWWWWWKKRRRKWWWWKRRRRR.',
+    'KWWWWWWWWKKKWWWWKRRRRRRK',
+    'KWWWWWWWWWWWWWWWKRRRRRRK',
+    'KWWWWWWWWWWWWWWKRRRRRRRK',
+    'KWWWWWWWWWWWWWKRRRRRRRRK',
+    'KWWWWWWWWWWWWKRRRRRRRRRK',
+    'KWWWWWWWWWKKRRRRRRRRRRRK',
+    'KWWWWWWWWKRRRRRRRRRRRRRK',
+    'KWWWWWWWWKRRRRRRRRRRRRRK',
+    'KKKKKKKKKKKKKKKKKKKKKKKK',
+]
+COLOURS = {"W": theme.WHITE, "R": theme.RED, "K": "#000000"}
+
+
+def logo_lines(grid: list[str] | None = None) -> list[list[tuple[str, str]]]:
+    """Lines of (characters, style). The style is 'fg bg' in hex, or '' for nothing drawn: rich and prompt_toolkit both read it after a small change."""
+    g = grid or GRID
+    out: list[list[tuple[str, str]]] = []
+    for y in range(0, len(g), 2):
+        top, bottom = g[y], g[y + 1] if y + 1 < len(g) else "." * len(g[y])
+        line: list[tuple[str, str]] = []
+        for t, b in zip(top, bottom):
+            ct, cb = COLOURS.get(t), COLOURS.get(b)
+            if ct is None and cb is None:
+                line.append((" ", ""))
+            elif ct is None:
+                line.append(("▄", f"{cb}|"))
+            elif cb is None or ct == cb:
+                line.append(("▀" if cb is None else "█", f"{ct}|"))
+            else:
+                line.append(("▀", f"{ct}|{cb}"))
+        out.append(line)
+    return out
+
+
+def rich_style(style: str) -> str:
+    fg, _, bg = style.partition("|")
+    return (fg + (f" on {bg}" if bg else "")) if fg else ""
+
+
+def ptk_style(style: str) -> str:
+    fg, _, bg = style.partition("|")
+    return (f"fg:{fg}" + (f" bg:{bg}" if bg else "")) if fg else ""
+
+
+# The same logo as braille dots (2 x 4 dots per character): the dot-matrix look of the start screen. R red, W white, space: nothing.
+BRAILLE = [
+    '     ⢀⣤⣶⣶⣦⣄  ⢀⣠⣤⣄⡀      ',
+    '    ⢀⣾⣿⣿⣿⣿⣿⣷⡄⢿⣿⣿⣿⣿⣷⡀    ',
+    '    ⢸⣿⣿⣿⣿⣿⣿⣿⣿⡌⣿⣿⣿⣿⣿⣧    ',
+    '    ⠸⣿⣿⣿⣿⣿⣿⣿⣿⡇⢹⣿⣿⣿⣿⡿    ',
+    '   ⢀⣤⠹⣿⣿⣿⣿⣿⣿⣿⡇⣾⣿⣿⣿⠿⠃    ',
+    '   ⣿⣿⣷⣙⠿⣿⣿⣿⣿⠟⣴⣿⣿⣿⢡⣾⣿⡇   ',
+    '  ⢀⣘⠻⣿⣿⣷⣦⣭⣥⣴⣿⣿⣿⡿⠿⣦⣭⣥⣄   ',
+    ' ⢀⣾⣿⣷⣮⡙⢿⣿⣿⣿⣿⣿⠟⣩⣶⣶⠘⣿⣿⣿⣷⡀ ',
+    ' ⣼⣿⣿⣿⣿⣿⣷⣌⡻⠿⢛⣡⣾⣿⣿⠟⣼⣿⣿⣿⣿⣷ ',
+    '⢀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⢋⣼⣿⣿⣿⣿⣿⣿⡆',
+    '⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⢋⣴⣿⣿⣿⣿⣿⣿⣿⣿⡇',
+    '⢸⣿⣿⣿⣿⣿⣿⣿⣿⡟⣭⣴⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇',
+    '⠸⠿⠿⠿⠿⠿⠿⠿⠿⠇⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠇',
+]
+BRAILLE_COLOURS = [
+    '     WWWWWW  RRRRR      ',
+    '    WWWWWWWWWRRRRRRR    ',
+    '    WWWWWWWWWWRRRRRR    ',
+    '    WWWWWWWWWWRRRRRR    ',
+    '   RRWWWWWWWWWRRRRRR    ',
+    '   RRRWWWWWWWRRRRWWWW   ',
+    '  WWRRRRRRRRRRRRRRRRR   ',
+    ' WWWWWRRRRRRRRWWWRRRRRR ',
+    ' WWWWWWWWRRRWWWWWRRRRRR ',
+    'WWWWWWWWWWWWWWWWRRRRRRRR',
+    'WWWWWWWWWWWWWWRRRRRRRRRR',
+    'WWWWWWWWWWRRRRRRRRRRRRRR',
+    'WWWWWWWWWWRRRRRRRRRRRRRR',
+]
+
+
+def braille_lines() -> list[list[tuple[str, str]]]:
+    """Lines of (characters, colour) runs; colour '' for blanks."""
+    out = []
+    for chars, cols in zip(BRAILLE, BRAILLE_COLOURS):
+        runs: list[tuple[str, str]] = []
+        for ch, c in zip(chars, cols):
+            colour = {"R": theme.RED, "W": theme.WHITE}.get(c, "")
+            if runs and runs[-1][1] == colour:
+                runs[-1] = (runs[-1][0] + ch, colour)
+            else:
+                runs.append((ch, colour))
+        out.append(runs)
+    return out

pal/terminal/models.py

@@ -0,0 +1,99 @@
+"""Which local model is the strongest one on this machine?
+
+"Strongest" here means the largest chat model Ollama has installed, judged by parameter count (from Ollama's own details, else from the name,
+else from the file size). That is a proxy: a bigger model is usually better but needs more memory, so the page shows the choice and lets you
+change it. Embedding models are never chosen: they cannot chat.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass
+from typing import Any
+
+EMBEDDING_HINTS = ("embed", "bge-", "minilm", "nomic", "e5-", "gte-", "snowflake-arctic", "mxbai", "paraphrase", "rerank")
+_GB_PER_BILLION = 0.55          # a 4-bit model is roughly 0.55 GB per billion parameters: only used when nothing else says how big it is
+_DETAIL = re.compile(r"^\s*(\d+(?:\.\d+)?)\s*([BM])\s*$", re.I)
+_TAG = re.compile(r"(?<![\w.])(\d+(?:\.\d+)?)b(?![a-z])", re.I)
+
+
+@dataclass(frozen=True)
+class LocalModel:
+    name: str
+    params_b: float | None       # billions of parameters, when known
+    size_gb: float | None        # size on disk
+    family: str
+    quant: str
+    embedding: bool
+
+    @property
+    def power(self) -> float:
+        """The number models are ranked by: parameters in billions, else estimated from the file size, else 0."""
+        if self.params_b is not None:
+            return self.params_b
+        return round(self.size_gb / _GB_PER_BILLION, 2) if self.size_gb else 0.0
+
+    def label(self) -> str:
+        bits = [self.name]
+        if self.params_b is not None:
+            bits.append(f"{self.params_b:g}B")
+        if self.size_gb:
+            bits.append(f"{self.size_gb:.1f} GB")
+        return " | ".join(bits)
+
+
+def _params_from(name: str, details: dict) -> float | None:
+    m = _DETAIL.match(str(details.get("parameter_size") or ""))
+    if m:
+        value = float(m.group(1))
+        return value / 1000 if m.group(2).upper() == "M" else value
+    tag = name.split(":", 1)[1] if ":" in name else ""
+    found = _TAG.search(tag) or _TAG.search(name)
+    return float(found.group(1)) if found else None
+
+
+def parse_tags(payload: Any) -> list[LocalModel]:
+    """Ollama's /api/tags -> models. Tolerant: anything that is not a named model is skipped."""
+    out: list[LocalModel] = []
+    items = payload.get("models") if isinstance(payload, dict) else None
+    for m in items if isinstance(items, list) else []:
+        if not isinstance(m, dict):
+            continue
+        name = str(m.get("name") or m.get("model") or "")
+        if not name:
+            continue
+        details: dict = m["details"] if isinstance(m.get("details"), dict) else {}
+        size = m.get("size")
+        out.append(LocalModel(name=name, params_b=_params_from(name, details), size_gb=round(size / 1e9, 2) if isinstance(size, (int, float)) and size > 0 else None,
+                              family=str(details.get("family") or ""), quant=str(details.get("quantization_level") or ""),
+                              embedding=any(h in name.lower() or h in str(details.get("family") or "").lower() for h in EMBEDDING_HINTS)))
+    return sorted(out, key=lambda x: x.name)
+
+
+def strongest(models: list[LocalModel]) -> LocalModel | None:
+    """The largest chat model (ties: the bigger file, then the name), or None when there is none."""
+    chat = [m for m in models if not m.embedding]
+    return max(chat, key=lambda m: (m.power, m.size_gb or 0.0, m.name)) if chat else None
+
+
+def fetch_tags(url: str, get: Any = None, timeout: float = 3.0) -> Any:
+    if get is None:
+        import requests
+        get = requests.get
+    r = get(f"{url.rstrip('/')}/api/tags", timeout=timeout)
+    r.raise_for_status()
+    return r.json()
+
+
+def discover(url: str, get: Any = None) -> dict:
+    """What the page needs: whether Ollama answers, the models it has, and the recommended one."""
+    try:
+        models = parse_tags(fetch_tags(url, get))
+    except Exception as e:  # noqa: BLE001  (not running, not reachable, or not Ollama)
+        return {"ok": False, "url": url, "models": [], "recommended": None, "error": f"Ollama is not reachable at {url} ({type(e).__name__}). Start it with `ollama serve`."}
+    best = strongest(models)
+    error = None
+    if not models:
+        error = "Ollama is running but has no models. Pull one, for example: ollama pull llama3.1:8b"
+    elif best is None:
+        error = "Ollama has only embedding models, which cannot chat. Pull a chat model, for example: ollama pull llama3.1:8b"
+    return {"ok": best is not None, "url": url, "models": [{**asdict(m), "label": m.label()} for m in models], "recommended": best.name if best else None, "error": error}