pal-code 0.1.0__py3-none-any.whl

pal/terminal/setup.py

@@ -0,0 +1,354 @@
+"""`pal setup`: look at this computer's GPU, pick the local models that suit it, download them with Ollama, and remember the choice.
+
+Runs by itself the first time `pal cli` or `pal web` starts in a terminal. Two models are chosen:
+- the main model, which builds and plans when you use a local model;
+- the helper, the small model Pal runs for its own jobs on every request (routing, trimming what you type, checking answers), even when the
+  main model is an API model.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from rich.console import Console
+from rich.padding import Padding
+from rich.table import Table
+from rich.text import Text
+
+from pal.llm_wrapper.modes import PROVIDER_KEYS
+from pal.terminal import backend, theme
+from pal.terminal.hardware import Hardware, detect
+from pal.terminal.local_models import BY_TAG, FIT_LABEL, budget_gb, by_tier, fit, recommend, suitable, tier_name
+
+INSTALL_OLLAMA = {"Windows": "download the installer from https://ollama.com/download",
+                  "Darwin": "download the app from https://ollama.com/download (or: brew install ollama)",
+                  "Linux": "run: curl -fsSL https://ollama.com/install.sh | sh"}
+
+
+def _say(console: Console, renderable, indent: int = 2) -> None:
+    console.print(Padding(renderable, (0, 0, 0, indent)))
+
+
+def ollama_installed() -> bool:
+    return shutil.which("ollama") is not None
+
+
+def pull(tag: str) -> bool:
+    """`ollama pull <tag>`, showing Ollama's own progress. True when it worked."""
+    exe = shutil.which("ollama")
+    if not exe:
+        return False
+    try:
+        return subprocess.call([exe, "pull", tag]) == 0
+    except OSError:
+        return False
+
+
+def show_table(console: Console, hw: Hardware) -> None:
+    """Every model in the catalogue, grouped by the GPU it needs, with how each fits this computer."""
+    _say(console, Text.assemble(("Local models by GPU memory", f"bold {theme.WHITE}"), (f"   this computer: {tier_name(hw)}", theme.MUTED)))
+    console.print()
+    for tier, models in by_tier():
+        head = f"{tier} GB GPU" if tier else "CPU"
+        mine = max((t for t, _ in by_tier() if t <= hw.vram_gb + 0.5), default=None) if hw.vram_gb else 0
+        mark = "  \u25C0 your computer" if tier == mine else ""
+        _say(console, Text.assemble((head, f"bold {theme.RED_HI}"), (mark, theme.WHITE)))
+        grid = Table.grid(padding=(0, 2))
+        for width in (22, 8, 10, 26):
+            grid.add_column(width=width, no_wrap=True, overflow="ellipsis")
+        grid.add_column(no_wrap=True, overflow="ellipsis")
+        for m in models:
+            f = fit(m.need_gb, hw)
+            grid.add_row(Text(m.tag, style=theme.WHITE), Text(f"{m.size_gb:g} GB", style=theme.INK), Text(m.use + (" *" if m.thinks else ""), style=theme.MUTED),
+                         Text(FIT_LABEL[f], style=f"bold {theme.RED_HI}" if f == "gpu" else theme.INK if f == "partial" else theme.MUTED),
+                         Text(m.note, style=theme.MUTED))
+        _say(console, grid, 4)
+        console.print()
+    _say(console, Text("Sizes are Ollama's 4-bit downloads (approximate). * prints its reasoning first, so Pal does not pick it by itself.", style=theme.MUTED))
+
+
+def default_pick(console: Console, question: str, options: list[tuple[str, str]], recommended: int = 0, other: bool = False,
+                 header: str = "Setup") -> str | None:
+    """A choice as a card in a terminal; without one (pipes, tests), the recommended choice."""
+    from pal.terminal import decide
+    if not decide._interactive():
+        return options[recommended][0] if options else None
+    q = decide.Question(question, [decide.Option(label, about) for label, about in options], header, recommended, other=other)
+    answer = decide.ask(console, q)
+    decide.show_answer(console, q, answer)
+    return answer
+
+
+LOCAL_MAIN = "A local model on this computer"
+API_MAIN = "An API model"
+
+
+def run_setup(console: Console, hw: Hardware | None = None, host: str = backend.DEFAULT_HOST, assume_yes: bool = False,
+              ask: Callable[[str], bool] | None = None, puller: Callable[[str], bool] = pull, ollama: Callable[[], bool] = ollama_installed, dry: bool = False,
+              pick: Callable[..., str | None] | None = None, main_kind: str | None = None, api_chooser: Callable | None = None) -> dict:
+    """Scan, choose, download (if allowed), save. Returns what was saved. `dry` only shows the recommendation (for a pretend computer).
+
+    The main model (it writes and plans) can be local or an API model. With an API model only the helper is downloaded. With a local one,
+    the models that suit this GPU are offered (the best first) and the one chosen is downloaded with the helper."""
+    hw = hw or detect()
+    rec = recommend(hw)
+    pick = pick or (lambda question, options, recommended=0, other=False: default_pick(console, question, options, recommended, other))
+    _say(console, Text("Pal setup", style=f"bold {theme.WHITE}"))
+    _say(console, Text(f"This computer: {hw.summary()}", style=theme.INK))
+    for note in hw.notes:
+        _say(console, Text(note, style=theme.RED_HI))
+    console.print()
+    if rec is None:
+        explain_api_only(console)
+        if not dry:
+            backend.save_prefs(helper_model="", setup_done="1")
+        return {"provider": "", "model": "", "helper_model": "", "downloaded": False, "api_only": True}
+    grid = Table.grid(padding=(0, 3))
+    for role, m, why in (("Best main model", rec.main, "builds and plans when you use a local model"), ("Helper", rec.helper, "Pal's own small jobs on every request: routing, trimming, checking")):
+        grid.add_row(Text(role, style=theme.MUTED), Text(m.tag, style=f"bold {theme.WHITE}"), Text(f"{m.size_gb:g} GB", style=theme.INK), Text(why, style=theme.MUTED))
+    _say(console, Text("For this computer", style=f"bold {theme.RED_HI}"))
+    _say(console, grid, 4)
+    _say(console, Text(f"Why: {rec.reason}.", style=theme.MUTED), 4)
+    console.print()
+    if dry:
+        if rec.others:
+            _say(console, Text("Also fits: " + ", ".join(m.tag for m in rec.others) + "   (every model: pal setup --list)", style=theme.MUTED), 4)
+        return {"provider": backend.LOCAL, "model": rec.main.tag, "helper_model": rec.helper.tag, "downloaded": False}
+
+    kind = main_kind or pick("Which main model should Pal use? (it writes and plans; the helper is always local)",
+                             [(LOCAL_MAIN, f"runs on your GPU, free and private: {rec.main.tag} fits best"),
+                              (API_MAIN, "OpenAI, Anthropic, Gemini, OpenRouter or any other: needs a key, nothing big to download")], 0)
+    api = kind in (API_MAIN, "api")
+
+    if not ollama():
+        how = INSTALL_OLLAMA.get(hw.system, INSTALL_OLLAMA["Linux"])
+        _say(console, Text.assemble(("Ollama runs local models (the helper too) and is not installed yet. ", theme.WHITE), (f"To install it, {how}.", theme.INK)))
+        _say(console, Text("Then run  pal setup  again. An API model works meanwhile:  pal cli --provider openrouter --model <name>", style=theme.MUTED))
+        backend.save_prefs(helper_model=rec.helper.tag, **({} if api else {"provider": backend.LOCAL, "model": rec.main.tag}))
+        return {"provider": "" if api else backend.LOCAL, "model": "" if api else rec.main.tag, "helper_model": rec.helper.tag, "downloaded": False}
+
+    info = backend.local_info(host)
+    installed = backend.chat_models(info) if info.get("ok") else []
+    main_tag = ""
+    saved: dict = {"helper_model": rec.helper.tag}
+    if api:
+        chosen = (api_chooser or (lambda c, system: ask_api(c, system)))(console, hw.system)
+        if chosen:
+            saved.update(provider=chosen[0], model=chosen[1])
+        else:
+            _say(console, Text("No API model chosen yet: pick one in a session with  /model <provider>:<model>", style=theme.MUTED))
+    else:
+        options = suitable(hw, installed)
+        labels = [(tag, about) for tag, about, _ in options]
+        main_tag = pick("Which local model should be the main one? (the best for your GPU is first; type another name to use it)", labels, 0, True) or rec.main.tag
+        main_tag = main_tag.strip().removeprefix("ollama pull ").strip()
+        saved.update(provider=backend.LOCAL, model=main_tag)
+
+    missing = [tag for tag in (main_tag, rec.helper.tag) if tag and tag not in installed]
+    if not missing:
+        _say(console, Text("Everything needed is already installed.", style=theme.INK))
+        backend.save_prefs(**saved, setup_done="1")
+        return {**{"provider": "", "model": ""}, **saved, "downloaded": True}
+    sizes = {m.tag: m.size_gb for m in (BY_TAG.get(x) for x in missing) if m}
+    total = sum(sizes.values())
+    question = f"Download {', '.join(missing)} now" + (f" (about {total:g} GB)" if total else "") + "?"
+    agreed = assume_yes or (ask or (lambda q: _confirm(console, q)))(question)
+    if not agreed:
+        _say(console, Text("Skipped. Download later with  pal setup, or pull any model yourself:  ollama pull <name>", style=theme.MUTED))
+        backend.save_prefs(**saved, setup_done="1")
+        return {**{"provider": "", "model": ""}, **saved, "downloaded": False}
+    ok = True
+    for tag in missing:
+        _say(console, Text(f"Downloading {tag} ...", style=theme.WHITE))
+        ok = puller(tag) and ok
+    _say(console, Text("Ready." if ok else "A download did not finish. Run  pal setup  again to retry.", style=f"bold {theme.RED_HI}" if ok else theme.RED_HI))
+    backend.save_prefs(**saved, setup_done="1" if ok else "")
+    return {**{"provider": "", "model": ""}, **saved, "downloaded": ok}
+
+
+KEY_HOWTO = {"Windows": 'setx {var} "your-key"   (then open a new terminal)', "Darwin": 'add  export {var}="your-key"  to ~/.zshrc',
+             "Linux": 'add  export {var}="your-key"  to ~/.bashrc'}
+
+
+def explain_api_only(console: Console) -> None:
+    keyed = [p for p, var in PROVIDER_KEYS.items() if os.environ.get(var)]
+    _say(console, Text("No GPU on this computer, so Pal uses an API model.", style=f"bold {theme.RED_HI}"))
+    _say(console, Text("Local models and Pal's local helper jobs (routing, trimming what you type, checking answers) are off here. The savers that need no "
+                       "model still work: only the relevant history, files and code are sent, and files are not sent twice.", style=theme.INK), 4)
+    console.print()
+    if keyed:
+        _say(console, Text(f"API key found for: {', '.join(keyed)}.", style=theme.WHITE))
+    _say(console, Text("Start with:  pal cli --provider openrouter --model <name>      browse models:  pal models --free", style=theme.INK))
+    _say(console, Text("or in a session:  /key openrouter <key>  then  /model openrouter:<name>", style=theme.MUTED))
+    _say(console, Text("Keys are never saved by Pal. To keep one, set it in your environment, for example OPENROUTER_API_KEY.", style=theme.MUTED))
+
+
+def ask_api(console: Console, system: str = "", ask: Callable[[str], str] | None = None, secret: Callable[[str], str] | None = None) -> tuple[str, str] | None:
+    """For a computer without a GPU: ask which API provider and model to use, and the key when it is not in the environment.
+    The key is put in this process's environment only (never written anywhere). Returns (provider, model), or None if the person stops."""
+    import getpass
+    ask = ask or (lambda q: console.input(Text("  " + q + " ", style=theme.WHITE)))
+    secret = secret or (lambda q: getpass.getpass("  " + q + " "))
+    names = list(PROVIDER_KEYS)
+    keyed = [p for p in names if os.environ.get(PROVIDER_KEYS[p])]
+    default = keyed[0] if keyed else "openrouter"
+    try:
+        provider = (ask(f"API provider ({', '.join(names)}) [{default}]:").strip().lower() or default)
+        if provider not in PROVIDER_KEYS:
+            _say(console, Text(f"Unknown provider {provider!r}.", style=theme.RED_HI))
+            return None
+        model = ask("Model name (for example the one your provider lists; pal models --free shows OpenRouter's):").strip()
+        if not model:
+            return None
+        var = PROVIDER_KEYS[provider]
+        if not os.environ.get(var):
+            key = secret(f"Paste your {provider} API key (it is not shown and not saved):").strip()
+            if not key:
+                return None
+            os.environ[var] = key
+            how = KEY_HOWTO.get(system or "Linux", KEY_HOWTO["Linux"]).format(var=var)
+            _say(console, Text(f"Using it for this session. To keep it for next time: {how}", style=theme.MUTED))
+    except (EOFError, KeyboardInterrupt):
+        console.print()
+        return None
+    backend.save_prefs(provider=provider, model=model)
+    return provider, model
+
+
+def _confirm(console: Console, question: str) -> bool:
+    try:
+        answer = console.input(Text.assemble(("  " + question + " ", theme.WHITE), ("[Y/n] ", theme.MUTED))).strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        console.print()
+        return False
+    return answer in ("", "y", "yes")
+
+
+def needs_setup() -> bool:
+    return not backend.load_prefs().get("setup_done") and not os.environ.get("PAL_SKIP_SETUP")
+
+
+def budget_note(hw: Hardware) -> str:
+    return f"about {budget_gb(hw):g} GB for models"
+
+
+# -- getting local models ready when a session starts -------------------------------------------------------------------------------
+
+
+OLLAMA_START_WAIT_S = 20
+
+
+@dataclass
+class LocalStatus:
+    state: str              # "ready", "off" (no GPU), "missing" (Ollama not installed), "stopped" (could not start), "remote"
+    detail: str = ""
+    info: dict | None = None
+
+
+def _is_local_host(host: str) -> bool:
+    return any(h in host for h in ("localhost", "127.0.0.1", "[::1]"))
+
+
+def install_command(system: str) -> list[str] | None:
+    """The command that installs Ollama on this computer, or None when it has to be downloaded by hand."""
+    if system == "Linux" and shutil.which("curl") and shutil.which("sh"):
+        return ["sh", "-c", "curl -fsSL https://ollama.com/install.sh | sh"]
+    if system == "Darwin" and shutil.which("brew"):
+        return ["brew", "install", "ollama"]
+    if system == "Windows" and shutil.which("winget"):
+        return ["winget", "install", "-e", "--id", "Ollama.Ollama", "--accept-source-agreements", "--accept-package-agreements"]
+    return None
+
+
+def install_ollama(console: Console, system: str, run: Callable[[list[str]], int] = subprocess.call) -> bool:
+    cmd = install_command(system)
+    if cmd is None:
+        _say(console, Text(f"Install Ollama by hand: {INSTALL_OLLAMA.get(system, INSTALL_OLLAMA['Linux'])}. Then run pal again.", style=theme.INK))
+        return False
+    _say(console, Text("Installing Ollama: " + " ".join(cmd), style=theme.MUTED))
+    try:
+        ok = run(cmd) == 0
+    except OSError:
+        ok = False
+    if system == "Windows" and not ollama_installed():          # winget puts it here; this terminal's PATH is from before
+        exe = Path(os.environ.get("LOCALAPPDATA", "")) / "Programs" / "Ollama"
+        if (exe / "ollama.exe").is_file():
+            os.environ["PATH"] = f"{exe}{os.pathsep}{os.environ.get('PATH', '')}"
+    return ok and ollama_installed()
+
+
+def start_ollama(host: str, wait_s: float = OLLAMA_START_WAIT_S, info: Callable[[str], dict] | None = None,
+                 popen: Callable | None = None, sleep: Callable[[float], None] | None = None) -> bool:
+    """Start `ollama serve` in the background (it keeps running after Pal exits, like the Ollama app) and wait until it answers."""
+    import time
+    info = info or backend.local_info
+    sleep = sleep or time.sleep
+    exe = shutil.which("ollama")
+    if not exe:
+        return False
+    from pal.paths import pal_home
+    log = pal_home() / "ollama.log"
+    log.parent.mkdir(parents=True, exist_ok=True)
+    kwargs: dict = {"stdout": log.open("ab"), "stderr": subprocess.STDOUT, "stdin": subprocess.DEVNULL}
+    if os.name == "nt":
+        kwargs["creationflags"] = getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+    else:
+        kwargs["start_new_session"] = True
+    try:
+        (popen or subprocess.Popen)([exe, "serve"], **kwargs)
+    except OSError:
+        return False
+    waited = 0.0
+    while waited < wait_s:
+        if info(host).get("ok"):
+            return True
+        sleep(0.5)
+        waited += 0.5
+    return bool(info(host).get("ok"))
+
+
+def ensure_local(console: Console, hw: Hardware, host: str = backend.DEFAULT_HOST, interactive: bool = True,
+                 ask: Callable[[str], bool] | None = None, installer: Callable | None = None, starter: Callable | None = None,
+                 info: Callable[[str], dict] | None = None, setup: Callable | None = None, ollama: Callable[[], bool] | None = None) -> LocalStatus:
+    """Make local models usable before the session starts: install Ollama (asking first), start it, and download the models chosen
+    for this GPU when they are missing (asking first). Never fails: the status says what is not ready and the session goes on."""
+    from pal.terminal.local_models import api_only
+    info = info or backend.local_info
+    ollama = ollama or ollama_installed
+    ask = ask or (lambda q: _confirm(console, q))
+    if api_only(hw):
+        return LocalStatus("off", "no GPU: API models only, local helper jobs off")
+    if not _is_local_host(host):
+        state = info(host)
+        return LocalStatus("ready" if state.get("ok") else "remote", f"Ollama at {host}" + ("" if state.get("ok") else " is not answering"), state)
+    if not ollama():
+        if interactive and ask("Local models run with Ollama, which is not installed. Install it now?"):
+            (installer or install_ollama)(console, hw.system)
+        if not ollama():
+            return LocalStatus("missing", f"Ollama is not installed: {INSTALL_OLLAMA.get(hw.system, INSTALL_OLLAMA['Linux'])}")
+    state = info(host)
+    if not state.get("ok"):
+        if not (starter or start_ollama)(host):
+            return LocalStatus("stopped", "Ollama did not start: see ~/.pal/ollama.log, or start it yourself with  ollama serve")
+        state = info(host)
+    prefs = backend.load_prefs()
+    have = set(backend.chat_models(state))
+    rec = recommend(hw)
+    local_main = prefs.get("provider", backend.LOCAL) == backend.LOCAL           # an API main model needs no big local download
+    wanted = [m for m in ((prefs.get("model") or (rec.main.tag if rec else "")) if local_main else "",
+                          prefs.get("helper_model") or (rec.helper.tag if rec else "")) if m]
+    if interactive and (needs_setup() or any(m not in have for m in wanted)):
+        (setup or run_setup)(console, hw, host=host, ask=ask)
+        state = info(host)
+        prefs = backend.load_prefs()
+    installed = backend.chat_models(state)
+    if not installed:
+        return LocalStatus("ready", "Ollama running, no models yet: pal setup downloads the ones for this GPU", state)
+    main = prefs.get("model") if prefs.get("provider") == backend.LOCAL and prefs.get("model") in installed else ""
+    helper = prefs.get("helper_model") if prefs.get("helper_model") in installed else ""
+    detail = "Ollama running" + (f" · {main}" if main else f" · {len(installed)} model{'s' if len(installed) != 1 else ''}") + (f" · helper {helper}" if helper else "")
+    return LocalStatus("ready", detail, state)

pal/terminal/syntax.py

@@ -0,0 +1,98 @@
+"""Does a file the model wrote parse? Checked before you review a change, so a missing bracket is fixed by the Build agent, not found by you.
+
+Python, JSON, YAML and TOML are checked with their own parsers. JavaScript, TypeScript, Go, Rust, Java, Kotlin, C, C++, C#, Ruby, PHP, Swift,
+Scala, Lua and shell use tree-sitter (installed with Pal for the code graph). Other files are not checked. A check never runs the code.
+"""
+from __future__ import annotations
+
+import importlib
+import json
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import PurePosixPath
+
+# extension -> (tree-sitter module, the function that returns its language)
+TREE_SITTER = {
+    ".js": ("tree_sitter_javascript", "language"), ".jsx": ("tree_sitter_javascript", "language"), ".mjs": ("tree_sitter_javascript", "language"),
+    ".cjs": ("tree_sitter_javascript", "language"), ".ts": ("tree_sitter_typescript", "language_typescript"),
+    ".tsx": ("tree_sitter_typescript", "language_tsx"), ".go": ("tree_sitter_go", "language"), ".rs": ("tree_sitter_rust", "language"),
+    ".java": ("tree_sitter_java", "language"), ".kt": ("tree_sitter_kotlin", "language"), ".kts": ("tree_sitter_kotlin", "language"),
+    ".c": ("tree_sitter_c", "language"), ".h": ("tree_sitter_c", "language"), ".cpp": ("tree_sitter_cpp", "language"),
+    ".cc": ("tree_sitter_cpp", "language"), ".hpp": ("tree_sitter_cpp", "language"), ".cs": ("tree_sitter_c_sharp", "language"),
+    ".rb": ("tree_sitter_ruby", "language"), ".php": ("tree_sitter_php", "language_php"), ".swift": ("tree_sitter_swift", "language"),
+    ".scala": ("tree_sitter_scala", "language"), ".lua": ("tree_sitter_lua", "language"), ".sh": ("tree_sitter_bash", "language"),
+    ".bash": ("tree_sitter_bash", "language"),
+}
+
+
+@dataclass(frozen=True)
+class SyntaxProblem:
+    path: str
+    line: int
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.path} line {self.line}: {self.message}"
+
+
+@lru_cache(maxsize=32)
+def _parser(ext: str):
+    """A tree-sitter parser for the extension, or None when the grammar is not installed."""
+    mod_name, fn = TREE_SITTER[ext]
+    try:
+        from tree_sitter import Language, Parser
+        mod = importlib.import_module(mod_name)
+        return Parser(Language(getattr(mod, fn)()))
+    except Exception:  # noqa: BLE001  (grammar missing or an incompatible version: the file is just not checked)
+        return None
+
+
+def _first_error(node):
+    """The innermost ERROR (or missing) node on the first broken path through the tree."""
+    found = None
+    while node is not None:
+        if node.type == "ERROR" or node.is_missing:
+            found = node
+        nxt = next((c for c in node.children if c.has_error or c.is_missing or c.type == "ERROR"), None)
+        node = nxt
+    return found
+
+
+def check(path: str, text: str) -> SyntaxProblem | None:
+    """The first syntax problem in the text, or None when it parses (or the language is not checked)."""
+    ext = PurePosixPath(path).suffix.lower()
+    try:
+        if ext in (".py", ".pyw"):
+            compile(text, path, "exec", dont_inherit=True)
+        elif ext == ".json":
+            json.loads(text)
+        elif ext in (".yaml", ".yml"):
+            import yaml
+            list(yaml.safe_load_all(text))
+        elif ext == ".toml":
+            try:
+                import tomllib
+            except ImportError:                         # Python 3.10: not checked
+                return None
+            tomllib.loads(text)
+        elif ext in TREE_SITTER:
+            parser = _parser(ext)
+            if parser is None:
+                return None
+            tree = parser.parse(text.encode("utf-8"))
+            if not tree.root_node.has_error:
+                return None
+            bad = _first_error(tree.root_node) or tree.root_node
+            what = f"missing {bad.type}" if bad.is_missing else "unexpected code"
+            return SyntaxProblem(path, bad.start_point[0] + 1, what)
+        else:
+            return None
+    except SyntaxError as e:
+        return SyntaxProblem(path, e.lineno or 1, e.msg)
+    except json.JSONDecodeError as e:
+        return SyntaxProblem(path, e.lineno, e.msg)
+    except Exception as e:  # noqa: BLE001  (yaml and toml errors carry their own types)
+        mark = getattr(e, "problem_mark", None)
+        line = (mark.line + 1) if mark is not None else getattr(e, "lineno", 1) or 1
+        return SyntaxProblem(path, line, str(getattr(e, "problem", None) or e).splitlines()[0][:160])
+    return None

pal/terminal/theme.py

@@ -0,0 +1,37 @@
+"""Colours and the wordmark. Black, red and white."""
+from __future__ import annotations
+
+RED = "#E50914"
+RED_HI = "#FF4D57"
+WHITE = "#FFFFFF"
+INK = "#E8E8E8"
+MUTED = "#8A8A8A"
+PANEL = "#1A1A1A"
+BG = "#000000"
+
+_GLYPHS = {                       # chunky pixel letters, 10 rows: ascender rows 0-1, x-height rows 2-7, descender rows 8-9
+    "p": ["      ", "      ", "XXXXX ", "XXXXXX", "XX  XX", "XX  XX", "XXXXXX", "XXXXX ", "XX    ", "XX    "],
+    "a": ["      ", "      ", " XXXX ", "    XX", " XXXXX", "XX  XX", "XX  XX", " XXXXX", "      ", "      "],
+    "l": ["XXX ", " XX ", " XX ", " XX ", " XX ", " XX ", " XX ", " XXX", "    ", "    "],
+    ".": ["  ", "  ", "  ", "  ", "  ", "  ", "XX", "XX", "  ", "  "],
+}
+
+
+def wordmark(text: str = "pal", dot: bool = True) -> list[list[tuple[str, str]]]:
+    """The wordmark as lines of (characters, colour): pixels drawn with half blocks (two pixel rows per line), two cells per pixel. The final dot is red."""
+    cols: list[tuple[list[str], str]] = [(_GLYPHS[ch], WHITE) for ch in text]
+    if dot:
+        cols.append((_GLYPHS["."], RED))
+    lines: list[list[tuple[str, str]]] = []
+    for r in range(0, 10, 2):
+        line: list[tuple[str, str]] = []
+        for i, (glyph, colour) in enumerate(cols):
+            top, bottom = glyph[r], glyph[r + 1]
+            chars = ""
+            for x in range(max(len(top), len(bottom))):
+                t = x < len(top) and top[x] == "X"
+                b = x < len(bottom) and bottom[x] == "X"
+                chars += ("\u2588" if t and b else "\u2580" if t else "\u2584" if b else " ") * 2      # two cells per pixel: a cell is about twice as tall as wide
+            line.append((chars + ("  " if i < len(cols) - 1 else ""), colour))
+        lines.append(line)
+    return lines