Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,11 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+
+# Virtual environment (created by install.sh)
+.venv/
+
+# OS / editor noise
+.DS_Store
+*.swp

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oohfixer.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,144 @@
+# Caption Tool
+
+A small, friendly tool that writes text descriptions (captions) for every image
+in a folder — all on your own computer.
+
+- **No API key. No account. No internet** (after the first-time model download).
+- **Private:** your images never leave your machine.
+- **Lightweight:** runs on a GPU with as little as **2 GB of VRAM**.
+- **Whole folders at once:** point it at a directory and it captions everything.
+
+Made by [oohfixer.com](https://oohfixer.com).
+
+---
+
+## What it does
+
+For every image it finds, Caption Tool writes a matching text file next to it:
+
+```
+vacation.jpg   →   vacation.txt
+cat.png        →   cat.txt
+```
+
+That's it. The caption sits in the `.txt` file, ready to use for training
+image models, organizing photos, or search.
+
+---
+
+## Install
+
+You need **Python 3.13 or older** (3.14 doesn't work with this tool's
+dependencies).
+
+### One command (recommended)
+
+Open a terminal and run:
+
+```bash
+curl -fsSL https://oohfixer.com/caption-tool/install.sh | bash
+```
+
+This downloads the tool, installs what it needs in its own isolated
+environment, and adds a **`captions`** command you can run from anywhere. When it
+finishes, open a new terminal (or run `source ~/.bashrc`).
+
+Then just type:
+
+```bash
+captions
+```
+
+### Manual install
+
+If you'd rather set it up by hand:
+
+1. Download this folder and open a terminal in it.
+2. Install the requirements:
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. Run it:
+
+   ```bash
+   python caption.py
+   ```
+
+---
+
+## Use it
+
+Just run it:
+
+```bash
+python caption.py
+```
+
+It will ask you for a folder of images, show the settings, and caption them.
+Sit back — a progress bar shows how far it's gotten.
+
+### Want to skip the questions?
+
+If you already know what you want, you can do it in one line:
+
+```bash
+python caption.py --path "/path/to/your/images"
+```
+
+Useful extras:
+
+| Option | What it does |
+| --- | --- |
+| `--path "FOLDER"` | Caption this folder right away (no prompt). |
+| `--force` | Re-caption images that already have a `.txt` file. |
+| `--model florence2-base` | Pick a different model (see below). |
+| `--max-new-tokens 512` | Allow longer captions. |
+
+---
+
+## Choosing a model
+
+When you run it, you can pick which AI model writes the captions. Bigger = more
+detailed, but uses more VRAM.
+
+| Model | Size | Best for |
+| --- | --- | --- |
+| **florence2-large-ft** (default) | ~1.5 GB | Best quality. Needs a normal GPU. |
+| florence2-large | ~1.5 GB | Slightly less accurate. |
+| **florence2-base** | ~0.45 GB | **2 GB GPUs**, or when you want it fast. |
+
+If your card only has 2 GB of VRAM, choose **florence2-base**.
+
+---
+
+## Prefix and suffix (optional)
+
+If you're captioning images to train your own image model, you may want a
+**trigger word** on every caption (for example, your subject's name). Set a
+**prefix** and the tool adds it to the front of every caption automatically.
+A **suffix** does the same at the end.
+
+Leave them empty if you just want plain descriptions.
+
+---
+
+## Settings
+
+Settings are stored in `caption_config.json` next to the script. You can edit
+that file directly, or change things from the tool's menu. The defaults:
+
+- Skip images that already have a caption (so re-running is safe).
+- At least ~15 words per caption (it re-captions anything shorter).
+- 256 token cap on caption length.
+
+---
+
+## Questions
+
+- **Does it need to be online?** Only the very first time, to download the
+  model. After that, everything runs offline.
+- **Where do my images go?** Nowhere. They're processed locally and the caption
+  is saved next to each image.
+- **What image types?** jpg, png, webp, bmp, tiff.

caption.py

@@ -0,0 +1,361 @@
+#!/usr/bin/env python3
+"""
+Caption Tool — caption entire folders of images locally.
+
+Runs 100% on your machine. No API key, no internet after the first model
+download. Works on GPUs with as little as 2 GB of VRAM (use Florence-2-base).
+
+For every image it writes a matching <image>.txt caption file next to it.
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+import warnings
+
+warnings.filterwarnings("ignore")
+os.environ.setdefault("TRANSFORMERS_VERBOSITY", "error")
+os.environ.setdefault("HF_HUB_DISABLE_PROGRESS_BARS", "1")
+
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Prompt, Confirm
+from rich.progress import (
+    Progress,
+    SpinnerColumn,
+    BarColumn,
+    TextColumn,
+    TimeElapsedColumn,
+    TaskProgressColumn,
+)
+from rich.live import Live
+from rich.table import Table
+from rich.text import Text
+
+console = Console()
+
+CONFIG_PATH = Path(__file__).parent / "caption_config.json"
+
+# Model choices. Sizes are approximate fp16 GPU footprint.
+MODELS = {
+    "florence2-large-ft": ("microsoft/Florence-2-large-ft", "~1.5 GB — best quality (recommended)"),
+    "florence2-large":    ("microsoft/Florence-2-large",    "~1.5 GB — base, slightly less accurate"),
+    "florence2-base":     ("microsoft/Florence-2-base",     "~0.45 GB — fast, great for 2 GB GPUs"),
+}
+
+DEFAULT_CONFIG = {
+    "model": "microsoft/Florence-2-large-ft",
+    "prefix": "",
+    "suffix": "",
+    "max_new_tokens": 256,
+    "min_words": 15,
+    "skip_existing": True,
+}
+
+
+def _model_family(model_id: str) -> str:
+    return "florence2" if "florence" in model_id.lower() else "unknown"
+
+
+IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp", ".bmp", ".tiff", ".tif"}
+
+
+def load_config() -> dict:
+    if CONFIG_PATH.exists():
+        with open(CONFIG_PATH) as f:
+            cfg = json.load(f)
+        return {**DEFAULT_CONFIG, **cfg}
+    return DEFAULT_CONFIG.copy()
+
+
+def save_config(cfg: dict):
+    with open(CONFIG_PATH, "w") as f:
+        json.dump(cfg, f, indent=2)
+
+
+def find_images(path: Path) -> list[Path]:
+    if path.is_file():
+        if path.suffix.lower() in IMAGE_EXTENSIONS:
+            return [path]
+        return []
+    return sorted(p for p in path.rglob("*") if p.suffix.lower() in IMAGE_EXTENSIONS)
+
+
+def load_model(model_id: str):
+    """Load the captioning model onto the GPU, or CPU if no GPU is present."""
+    import torch
+    from transformers import AutoProcessor, AutoModelForCausalLM
+
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    device_label = (
+        f"CUDA ({torch.cuda.get_device_name(0)})" if device.type == "cuda" else "CPU"
+    )
+    dtype = torch.float16 if device.type == "cuda" else torch.float32
+    family = _model_family(model_id)
+
+    with console.status(f"[bold cyan]Loading [white]{model_id}[/white] on {device_label}...", spinner="dots"):
+        processor = AutoProcessor.from_pretrained(model_id, trust_remote_code=True)
+        model = AutoModelForCausalLM.from_pretrained(
+            model_id, torch_dtype=dtype, trust_remote_code=True
+        ).to(device)
+        model.eval()
+
+    return (processor, model, device, dtype, family), device_label
+
+
+def _generate_caption(processor, model, img, device, dtype, max_new_tokens: int, task: str) -> str:
+    """Run one Florence-2 caption generation for the given task prompt."""
+    import torch
+
+    inputs = processor(text=task, images=img, return_tensors="pt")
+    inputs = {k: v.to(device) for k, v in inputs.items()}
+    if "pixel_values" in inputs:
+        inputs["pixel_values"] = inputs["pixel_values"].to(dtype)
+    output_ids = model.generate(**inputs, max_new_tokens=max_new_tokens, num_beams=3)
+    raw = processor.batch_decode(output_ids, skip_special_tokens=False)[0]
+    parsed = processor.post_process_generation(raw, task=task, image_size=(img.width, img.height))
+    return parsed[task].strip()
+
+
+def caption_image(model_bundle, image_path: Path, prefix: str, suffix: str,
+                 max_new_tokens: int, min_words: int = 0) -> str:
+    import torch
+    from PIL import Image
+
+    processor, model, device, dtype, family = model_bundle
+    img = Image.open(image_path).convert("RGB")
+
+    with torch.no_grad():
+        caption = _generate_caption(
+            processor, model, img, device, dtype, max_new_tokens, "<MORE_DETAILED_CAPTION>"
+        )
+
+        # Florence-2 has no native minimum length, so re-run with a stronger
+        # prompt if the first caption came out too short.
+        if min_words and len(caption.split()) < min_words:
+            stronger = (
+                "Describe this image in extensive detail for a training caption. "
+                "Cover the subject, clothing, hair, lighting, pose, expression, "
+                "background, and camera angle."
+            )
+            caption = _generate_caption(
+                processor, model, img, device, dtype, max_new_tokens, stronger
+            )
+
+    parts = [p for p in (prefix.strip(), caption, suffix.strip()) if p]
+    return ", ".join(parts) if prefix or suffix else caption
+
+
+def select_model(current: str) -> str:
+    console.print("\n[bold]Available models:[/bold]")
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    for key, (model_id, desc) in MODELS.items():
+        marker = "→" if model_id == current else " "
+        table.add_row(f"[cyan]{marker} {key}[/cyan]", model_id, f"[dim]{desc}[/dim]")
+    console.print(table)
+
+    choice = Prompt.ask(
+        "\nModel shortname or full HF model ID",
+        default=next((k for k, (m, _) in MODELS.items() if m == current), current),
+    )
+    if choice in MODELS:
+        return MODELS[choice][0]
+    return choice  # allow any Hugging Face model ID
+
+
+def parse_args():
+    p = argparse.ArgumentParser(description="Caption Tool — local batch image captioner.")
+    p.add_argument("--path", help="Image folder or file (skips the path prompt)")
+    p.add_argument("--model", help="Override the model (shortname or HF ID)")
+    p.add_argument("--max-new-tokens", type=int, help="Override max new tokens")
+    p.add_argument("--force", action="store_true", help="Re-caption even if a .txt already exists")
+    return p.parse_args()
+
+
+def _hsl_hex(hue: float) -> str:
+    """Hue (0-360) → hex color string, full saturation, mid lightness."""
+    hue %= 360
+    s, l = 1.0, 0.55
+    c = (1 - abs(2 * l - 1)) * s
+    hp = hue / 60
+    x = c * (1 - abs((hp % 2) - 1))
+    m = l - c / 2
+    if hp < 1:
+        r, g, b = c, x, 0
+    elif hp < 2:
+        r, g, b = x, c, 0
+    elif hp < 3:
+        r, g, b = 0, c, x
+    elif hp < 4:
+        r, g, b = 0, x, c
+    elif hp < 5:
+        r, g, b = x, 0, c
+    else:
+        r, g, b = c, 0, x
+    R = int((r + m) * 255)
+    G = int((g + m) * 255)
+    B = int((b + m) * 255)
+    return f"#{R:02x}{G:02x}{B:02x}"
+
+
+def _header_text(offset: int) -> "Text":
+    """Build the title panel content with a rainbow-shimmer oohfixer.com."""
+    t = Text()
+    t.append("Caption Tool", style="bold white")
+    t.append("\n")
+    t.append("Caption entire image folders locally — no API key required", style="dim")
+    t.append("\n")
+    for i, ch in enumerate("oohfixer.com"):
+        hue = (i * 18 + offset) % 360
+        t.append(ch, style=f"bold {_hsl_hex(hue)}")
+    return t
+
+
+def show_header():
+    """Print the title. Animate a rainbow shimmer on a real terminal; static otherwise."""
+    panel = lambda off: Panel(_header_text(off), style="bold blue", expand=False)  # noqa: E731
+    if console.is_terminal:
+        with Live(console=console, refresh_per_second=24, transient=False) as live:
+            for frame in range(40):
+                live.update(panel(frame * 14))
+                time.sleep(0.03)
+    else:
+        console.print(panel(0))
+
+
+def main():
+    args = parse_args()
+
+    show_header()
+
+    cfg = load_config()
+
+    # --- Path input (use --path if given) ---
+    if args.path:
+        target = Path(args.path).expanduser().resolve()
+    else:
+        raw = Prompt.ask("\n[bold]Image folder or file path[/bold]")
+        target = Path(raw).expanduser().resolve()
+
+    if not target.exists():
+        console.print(f"[red]✗ Path not found:[/red] {target}")
+        sys.exit(1)
+
+    images = find_images(target)
+    if not images:
+        console.print("[red]✗ No images found.[/red]")
+        sys.exit(1)
+
+    # CLI / config overrides
+    if args.model:
+        cfg["model"] = args.model
+    if args.max_new_tokens:
+        cfg["max_new_tokens"] = args.max_new_tokens
+    if args.force:
+        cfg["skip_existing"] = False
+
+    # Filter already-captioned unless skipping is disabled
+    pending = images
+    if cfg["skip_existing"]:
+        pending = [p for p in images if not p.with_suffix(".txt").exists()]
+        skipped = len(images) - len(pending)
+    else:
+        skipped = 0
+
+    console.print(f"\n[green]✓[/green] Found [bold]{len(images)}[/bold] image(s)", end="")
+    if skipped:
+        console.print(f"  [dim]({skipped} already captioned, skipping)[/dim]", end="")
+    console.print()
+
+    if not pending:
+        console.print("[yellow]All images already have captions. Run with --force to redo them.[/yellow]")
+        sys.exit(0)
+
+    # --- Settings summary + optional changes (skip prompts when --path given) ---
+    console.print(Panel(
+        f"[cyan]Model:[/cyan]       {cfg['model']}\n"
+        f"[cyan]Prefix:[/cyan]      {cfg['prefix'] or '[dim](none)[/dim]'}\n"
+        f"[cyan]Suffix:[/cyan]      {cfg['suffix'] or '[dim](none)[/dim]'}\n"
+        f"[cyan]Max tokens:[/cyan]  {cfg['max_new_tokens']}\n"
+        f"[cyan]Min words:[/cyan]  {cfg['min_words']} (0 = no minimum)\n"
+        f"[cyan]Skip existing:[/cyan] {cfg['skip_existing']}",
+        title="[bold]Current Settings[/bold]",
+        expand=False,
+    ))
+
+    # Only offer to change settings when running interactively (no --path).
+    if not args.path and Confirm.ask("Change settings?", default=False):
+        cfg["model"] = select_model(cfg["model"])
+        cfg["prefix"] = Prompt.ask("Caption prefix (trigger word, etc.)", default=cfg["prefix"])
+        cfg["suffix"] = Prompt.ask("Caption suffix", default=cfg["suffix"])
+        cfg["max_new_tokens"] = int(Prompt.ask("Max new tokens", default=str(cfg["max_new_tokens"])))
+        cfg["min_words"] = int(Prompt.ask("Min words (re-caption if shorter)", default=str(cfg["min_words"])))
+        cfg["skip_existing"] = Confirm.ask("Skip already-captioned images?", default=cfg["skip_existing"])
+        save_config(cfg)
+        console.print("[dim]Settings saved.[/dim]")
+
+    proceed = args.path or Confirm.ask(f"\nCaption [bold]{len(pending)}[/bold] image(s)?", default=True)
+    if not proceed:
+        console.print("[dim]Aborted.[/dim]")
+        sys.exit(0)
+
+    # --- Load model ---
+    console.print()
+    try:
+        model_bundle, device_label = load_model(cfg["model"])
+    except Exception as e:
+        console.print(f"[red]✗ Failed to load model:[/red] {e}")
+        sys.exit(1)
+
+    console.print(f"[green]✓[/green] Model ready on [bold]{device_label}[/bold]\n")
+
+    # --- Caption loop ---
+    errors = []
+    done = 0
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[bold cyan]{task.description}"),
+        BarColumn(),
+        TaskProgressColumn(),
+        TimeElapsedColumn(),
+        console=console,
+        transient=False,
+    ) as progress:
+        task = progress.add_task("Captioning...", total=len(pending))
+
+        for img_path in pending:
+            progress.update(task, description=f"[bold cyan]{img_path.name}")
+            try:
+                caption = caption_image(
+                    model_bundle, img_path,
+                    cfg["prefix"], cfg["suffix"], cfg["max_new_tokens"], cfg["min_words"]
+                )
+                txt_path = img_path.with_suffix(".txt")
+                txt_path.write_text(caption, encoding="utf-8")
+                done += 1
+            except Exception as e:
+                errors.append((img_path.name, str(e)))
+            progress.advance(task)
+
+    # --- Summary ---
+    console.print()
+    if errors:
+        console.print(f"[green]✓ {done} captioned[/green]  [red]✗ {len(errors)} failed[/red]")
+        for name, err in errors:
+            console.print(f"  [red]{name}:[/red] {err}")
+    else:
+        console.print(Panel(
+            f"[bold green]✓ {done} image(s) captioned successfully[/bold green]\n"
+            f"[dim]Output: .txt files alongside each image[/dim]",
+            style="green",
+            expand=False,
+        ))
+
+
+if __name__ == "__main__":
+    main()

caption_config.json

@@ -0,0 +1,8 @@
+{
+  "model": "microsoft/Florence-2-large-ft",
+  "prefix": "",
+  "suffix": "",
+  "max_new_tokens": 256,
+  "min_words": 15,
+  "skip_existing": true
+}

install.sh

@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+#
+# Caption Tool installer
+#
+# One-command install (host this file, then):
+#   curl -fsSL https://oohfixer.com/caption-tool/install.sh | bash
+#
+# Local install (run from this folder):
+#   bash install.sh
+#
+# Environment overrides:
+#   CAPTION_TOOL_BASE -> base URL the files are served from (download mode)
+#   CAPTION_TOOL_DIR  -> install location (default ~/.local/share/caption_tool)
+
+set -euo pipefail
+
+BASE_URL="${CAPTION_TOOL_BASE:-https://oohfixer.com/caption-tool}"
+INSTALL_DIR="${CAPTION_TOOL_DIR:-$HOME/.local/share/caption_tool}"
+BIN_DIR="$HOME/.local/bin"
+VENV="$INSTALL_DIR/.venv"
+
+info()  { printf '%s\n' "$1"; }
+err()   { printf 'Error: %s\n' "$1" >&2; }
+
+# Ask a yes/no question on the terminal so it works even when this script is
+# piped in via curl (where stdin is the script itself, not the keyboard).
+prompt_yes_no() {
+  local ans
+  if [ -r /dev/tty ]; then
+    read -r -p "$1 [y/N] " ans < /dev/tty || ans=""
+  else
+    read -r -p "$1 [y/N] " ans || ans=""
+  fi
+  case "$ans" in
+    y|Y|yes|YES|Yes) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Best-effort install of Python 3.13 via the system package manager.
+install_python() {
+  local os_id=""
+  if [ -f /etc/os-release ]; then
+    # shellcheck disable=SC1091
+    os_id="$(. /etc/os-release && echo "$ID")"
+  fi
+
+  case "$os_id" in
+    ubuntu|debian|linuxmint|pop|raspbian|kali)
+      sudo apt-get update
+      if ! sudo apt-get install -y python3.13 python3.13-venv; then
+        sudo apt-get install -y software-properties-common
+        sudo add-apt-repository -y ppa:deadsnakes/ppa
+        sudo apt-get update
+        sudo apt-get install -y python3.13 python3.13-venv
+      fi
+      ;;
+    fedora|rhel|centos|rocky|almalinux)
+      sudo dnf install -y python3.13
+      ;;
+    arch|manjaro)
+      err "Arch-based systems do not provide older Python easily."
+      info "Install python-3.13 from the AUR, then re-run this installer."
+      return 1
+      ;;
+    *)
+      if command -v brew >/dev/null 2>&1; then
+        brew install python@3.13
+      else
+        err "Could not detect your OS package manager."
+        info "Install Python 3.13 manually (https://www.python.org/downloads/), then re-run."
+        return 1
+      fi
+      ;;
+  esac
+}
+
+# --- 1. Locate or install a suitable Python --------------------------------
+PYBIN=""
+if command -v python3 >/dev/null 2>&1; then
+  PYVER="$(python3 --version 2>&1 | sed 's/Python //')"
+  PYMAJ="$(printf '%s' "$PYVER" | cut -d. -f1)"
+  PYMIN="$(printf '%s' "$PYVER" | cut -d. -f2)"
+  if [ "$PYMAJ" -gt 3 ] || { [ "$PYMAJ" -eq 3 ] && [ "$PYMIN" -ge 14 ]; }; then
+    if prompt_yes_no "Python $PYVER is installed, but Caption Tool needs 3.13 or older. Install Python 3.13 now?"; then
+      install_python || true
+      PYBIN="$(command -v python3.13 || true)"
+    fi
+  else
+    PYBIN="$(command -v python3)"
+  fi
+else
+  if prompt_yes_no "Python 3 was not found. Install Python 3.13 now?"; then
+    install_python || true
+    PYBIN="$(command -v python3.13 || command -v python3 || true)"
+  fi
+fi
+
+if [ -z "$PYBIN" ]; then
+  err "A Python 3.13 (or older) interpreter is required."
+  info "Install it, then re-run:  bash install.sh"
+  exit 1
+fi
+
+# Re-verify the chosen interpreter is acceptable.
+PYVER="$("$PYBIN" --version 2>&1 | sed 's/Python //')"
+PYMAJ="$(printf '%s' "$PYVER" | cut -d. -f1)"
+PYMIN="$(printf '%s' "$PYVER" | cut -d. -f2)"
+if [ "$PYMAJ" -gt 3 ] || { [ "$PYMAJ" -eq 3 ] && [ "$PYMIN" -ge 14 ]; }; then
+  err "Python $PYVER is still too new. Caption Tool requires 3.13 or older."
+  exit 6
+fi
+
+# --- 2. Locate the source files (local copy or download) --------------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")" && pwd)"
+if [ -f "$SCRIPT_DIR/caption.py" ]; then
+  SRC_MODE="local"
+  SRC="$SCRIPT_DIR"
+else
+  SRC_MODE="download"
+  SRC="$BASE_URL"
+fi
+
+# --- 3. Create install dir + virtual environment ----------------------------
+info "Installing Caption Tool"
+info "  Location: $INSTALL_DIR"
+info ""
+
+info "Step 1/5  Preparing the isolated Python environment..."
+mkdir -p "$INSTALL_DIR"
+if [ ! -d "$VENV" ]; then
+  "$PYBIN" -m venv "$VENV"
+fi
+
+# --- 4. Fetch the tool files -------------------------------------------------
+info "Step 2/5  Getting the tool files..."
+if [ "$SRC_MODE" = "local" ]; then
+  cp "$SRC/caption.py"         "$INSTALL_DIR/"
+  cp "$SRC/caption_config.json" "$INSTALL_DIR/"
+  cp "$SRC/requirements.txt"   "$INSTALL_DIR/"
+else
+  curl -fsSL "$SRC/caption.py"          -o "$INSTALL_DIR/caption.py"
+  curl -fsSL "$SRC/caption_config.json" -o "$INSTALL_DIR/caption_config.json"
+  curl -fsSL "$SRC/requirements.txt"    -o "$INSTALL_DIR/requirements.txt"
+fi
+
+# --- 5. Install dependencies -------------------------------------------------
+info "Step 3/5  Installing dependencies (this can take a few minutes)..."
+"$VENV/bin/pip" install --quiet --upgrade pip
+"$VENV/bin/pip" install --quiet -r "$INSTALL_DIR/requirements.txt"
+
+# --- 6. Create the global 'captions' command ---------------------------------
+info "Step 4/5  Creating the 'captions' command..."
+mkdir -p "$BIN_DIR"
+cat > "$BIN_DIR/captions" <<EOF
+#!/usr/bin/env bash
+exec "$VENV/bin/python" "$INSTALL_DIR/caption.py" "\$@"
+EOF
+chmod +x "$BIN_DIR/captions"
+
+# --- 7. Make sure ~/.local/bin is on PATH ------------------------------------
+NEED_RESTART=0
+if [[ ":$PATH:" != *":$BIN_DIR:"* ]]; then
+  RC="$HOME/.bashrc"
+  case "${SHELL:-}" in
+    *zsh) RC="$HOME/.zshrc" ;;
+  esac
+  if [ -f "$RC" ] && ! grep -q 'caption_tool_path' "$RC"; then
+    printf '\nexport PATH="%s:$PATH"  # caption_tool_path\n' "$BIN_DIR" >> "$RC"
+  fi
+  NEED_RESTART=1
+fi
+
+# --- 8. Done -----------------------------------------------------------------
+info "Step 5/5  Done."
+info ""
+info "Caption Tool is installed."
+if [ "$NEED_RESTART" = "1" ]; then
+  info "Run the next line (or open a new terminal) to use 'captions' anywhere:"
+  info "    source $RC"
+else
+  info "The command 'captions' is ready to use now."
+fi
+info ""
+info "Start captioning:        captions"
+info "Or point at a folder:    captions --path \"/path/to/images\""

requirements.txt

@@ -0,0 +1,8 @@
+# Caption Tool — local image captioner
+# Needs Python 3.13 or older. Python 3.14 breaks the tokenizer build.
+
+torch>=2.1.0
+torchvision>=0.20.0
+transformers==4.46.3
+Pillow>=10.0.0
+rich>=13.0.0