openclacky 1.2.12 → 1.2.14

data/lib/clacky/default_parsers/pdf_parser.rb

@@ -8,113 +8,97 @@
 #
 # Output:
 #   stdout — extracted text content (UTF-8)
-#   stderr — error messages
+#   stderr — error / progress messages
 #   exit 0 — success
-#   exit 1 — failure
+#   exit 1 — hard failure (file unreadable, pdftotext missing, etc.)
 #
-# This file lives in ~/.clacky/parsers/ and can be modified by the LLM.
+# Strategy
+# --------
+# PDF pages naturally fall into two kinds: pages with a real text layer,
+# and scanned-image pages. The right tool is a per-page property, not a
+# document-level one. So:
 #
-# Extraction pipeline (first successful step wins):
-#   1. pdftotext (poppler)     — fastest, text-based PDFs
-#   2. pdfplumber (Python)     — handles more layouts
-#                                (→ pdf_parser_plumber.py)
-#   3. OCR (tesseract)         — scanned / image-only PDFs
-#                                (→ pdf_parser_ocr.py)
+#   1. Run pdftotext once over the whole file (`-layout`), split by `\f`.
+#   2. Pages with enough bytes → emit text directly.
+#   3. Pages below threshold → list page numbers in a Notice section
+#      with a shell command template the agent can run on demand to
+#      render a specific page to PNG, then file_reader that PNG.
 #
-# Each extractor is a plain, self-contained function. Python-backed steps
-# shell out to a sibling .py script so the LLM can edit them directly
-# (with proper syntax highlighting, linters, and per-file run/debug)
-# instead of wrestling with embedded heredocs.
+# The parser does NOT pre-render images. Most weak pages will never be
+# read (the answer is often already in the text-layer pages). Rendering
+# all of them up front is wasteful — 55 pages takes ~14s and most goes
+# to waste. The agent decides when (and which page) to OCR based on the
+# user's actual question.
 #
-# VERSION: 3
+# VERSION: 6
 
 require "open3"
 
-# Minimum useful output (in bytes). Below this, a step is considered a
-# miss and the next fallback is tried.
-MIN_CONTENT_BYTES = 20
+MIN_PAGE_BYTES = 20
 
-# Script directory — resolve sibling .py helpers relative to this file
-# so it works both from the gem's default_parsers/ dir and from the
-# copied-to-user ~/.clacky/parsers/ dir.
-SCRIPT_DIR = File.dirname(File.expand_path(__FILE__))
-
-def try_pdftotext(path)
-  stdout, _stderr, status = Open3.capture3("pdftotext", "-layout", "-enc", "UTF-8", path, "-")
-  return nil unless status.success?
-  text = stdout.strip
-  return nil if text.bytesize < MIN_CONTENT_BYTES
-  text
-rescue Errno::ENOENT
-  nil # pdftotext not installed
-end
-
-def try_pdfplumber(path)
-  script = File.join(SCRIPT_DIR, "pdf_parser_plumber.py")
-  return nil unless File.exist?(script)
-
-  stdout, _stderr, status = Open3.capture3("python3", script, path)
-  return nil unless status.success?
-  text = stdout.strip
-  return nil if text.bytesize < MIN_CONTENT_BYTES
-  text
-rescue Errno::ENOENT
-  nil # python3 not available
+def die(msg)
+  warn msg
+  exit 1
 end
 
-# OCR fallback for scanned/image-only PDFs.
-# See pdf_parser_ocr.py for the actual extraction logic.
-#
-# Installation hints (also printed on final failure):
-#   macOS:   brew install tesseract tesseract-lang poppler
-#            pip3 install pytesseract pdf2image
-#   Linux:   apt install tesseract-ocr tesseract-ocr-chi-sim poppler-utils
-#            pip3 install pytesseract pdf2image
-def try_ocr(path)
-  # Quick capability check — avoid spawning python if tesseract is missing.
-  _stdout, _stderr, status = Open3.capture3("tesseract", "--version")
-  return nil unless status.success?
-
-  script = File.join(SCRIPT_DIR, "pdf_parser_ocr.py")
-  return nil unless File.exist?(script)
-
-  stdout, stderr, status = Open3.capture3("python3", script, path)
+def pdftotext_pages(path)
+  stdout, stderr, status = Open3.capture3(
+    "pdftotext", "-layout", "-enc", "UTF-8", path, "-"
+  )
   unless status.success?
-    warn stderr.strip unless stderr.strip.empty?
+    warn "pdftotext failed: #{stderr.strip}"
     return nil
   end
-  text = stdout.strip
-  return nil if text.bytesize < MIN_CONTENT_BYTES
-  text
+  pages = stdout.split("\f", -1)
+  pages.pop if pages.last && pages.last.strip.empty?
+  pages.map(&:strip)
 rescue Errno::ENOENT
-  nil # tesseract or python3 not available
+  warn "pdftotext not found. Install poppler (`brew install poppler` / `apt install poppler-utils`)."
+  nil
 end
 
-# --- main ---
+def main(argv)
+  die "Usage: pdf_parser.rb <file_path>" if argv.empty?
+  path = argv[0]
+  die "File not found: #{path}" unless File.file?(path)
 
-path = ARGV[0]
+  pages = pdftotext_pages(path)
+  die "Could not extract text from PDF." if pages.nil?
 
-if path.nil? || path.empty?
-  warn "Usage: ruby pdf_parser.rb <file_path>"
-  exit 1
-end
+  weak = []
+  body_chunks = []
+  pages.each_with_index do |text, idx|
+    n = idx + 1
+    if text.bytesize >= MIN_PAGE_BYTES
+      body_chunks << "--- Page #{n} ---\n\n#{text}"
+    else
+      body_chunks << "--- Page #{n} ---\n\n[no extractable text layer]"
+      weak << n
+    end
+  end
 
-unless File.exist?(path)
-  warn "File not found: #{path}"
-  exit 1
-end
+  output = body_chunks.join("\n\n")
 
-# Try each extractor in order; first non-nil result wins.
-text = try_pdftotext(path) || try_pdfplumber(path) || try_ocr(path)
+  if weak.any?
+    abs_path = File.expand_path(path)
+    notice = +"\n\n--- Notice ---\n\n"
+    notice << "#{weak.size} of #{pages.size} pages have no extractable text layer "
+    notice << "(likely scanned images).\n"
+    notice << "Pages without text: #{weak.join(', ')}\n\n"
+    notice << "To OCR a specific page, render it to PNG via shell, then "
+    notice << "file_reader the PNG (it will be transcribed via the "
+    notice << "vision/OCR pipeline):\n\n"
+    notice << "  pdftoppm -r 150 -f <N> -l <N> -png -singlefile "
+    notice << "#{abs_path.inspect} /tmp/clacky-pdf-page-<N>\n"
+    notice << "  # produces /tmp/clacky-pdf-page-<N>.png\n\n"
+    notice << "Only render pages you actually need. If the user's question "
+    notice << "is already answered by the extracted text above, skip OCR.\n"
+    output << notice
+  end
 
-if text
-  print text
+  $stdout.write(output)
+  $stdout.write("\n") unless output.end_with?("\n")
   exit 0
-else
-  warn "Could not extract text from PDF."
-  warn "For text-based PDFs, install poppler: brew install poppler (macOS) / apt install poppler-utils (Linux)"
-  warn "For scanned PDFs (OCR):"
-  warn "  macOS: brew install tesseract tesseract-lang poppler && pip3 install pytesseract pdf2image"
-  warn "  Linux: apt install tesseract-ocr tesseract-ocr-chi-sim poppler-utils && pip3 install pytesseract pdf2image"
-  exit 1
 end
+
+main(ARGV) if __FILE__ == $PROGRAM_NAME

data/lib/clacky/default_parsers/pdf_parser_vlm.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Clacky PDF Parser — VLM (Vision Language Model) extractor
+
+Renders each PDF page to PNG via pdftoppm (poppler), then asks the
+configured OCR sidecar (e.g. gemini-3-5-flash, gpt-4o-mini) to transcribe
+each page through the local Clacky server's internal OCR endpoint.
+
+Why through HTTP and not direct API call?
+  The OCR sidecar config (model, base_url, api_key) lives in the agent's
+  ~/.clacky/config.yml. We don't re-implement that lookup here — instead
+  the local Clacky server exposes /api/internal/ocr-image which already
+  has the agent_config in scope. This parser stays a thin client.
+
+Usage:
+    python3 pdf_parser_vlm.py <file_path>
+
+Stdout: extracted text (UTF-8), pages separated by `\\n\\n--- Page N ---\\n\\n`
+Stderr: progress + error messages
+Exit:   0 on success, 1 on failure (server unavailable, no sidecar, etc.)
+
+Environment:
+    CLACKY_SERVER_HOST  default 127.0.0.1
+    CLACKY_SERVER_PORT  default 7070
+"""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+
+PAGE_SEPARATOR = "\n\n--- Page {n} ---\n\n"
+RENDER_DPI = 150
+REQUEST_TIMEOUT = 120  # seconds; VLMs can be slow
+
+
+def server_url():
+    host = os.environ.get("CLACKY_SERVER_HOST", "127.0.0.1")
+    port = os.environ.get("CLACKY_SERVER_PORT", "7070")
+    return f"http://{host}:{port}/api/internal/ocr-image"
+
+
+def render_pages(pdf_path, out_dir):
+    prefix = os.path.join(out_dir, "page")
+    cmd = ["pdftoppm", "-r", str(RENDER_DPI), "-png", pdf_path, prefix]
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        sys.stderr.write(f"pdftoppm failed: {proc.stderr.strip()}\n")
+        return []
+    pages = sorted(
+        os.path.join(out_dir, f) for f in os.listdir(out_dir)
+        if f.startswith("page-") and f.endswith(".png")
+    )
+    return pages
+
+
+def transcribe_page(image_path, page_num):
+    with open(image_path, "rb") as f:
+        body = f.read()
+
+    boundary = "----clacky-vlm-boundary"
+    parts = []
+    parts.append(f"--{boundary}\r\n".encode())
+    parts.append(
+        b'Content-Disposition: form-data; name="image"; filename="page.png"\r\n'
+        b"Content-Type: image/png\r\n\r\n"
+    )
+    parts.append(body)
+    parts.append(f"\r\n--{boundary}\r\n".encode())
+    parts.append(
+        b'Content-Disposition: form-data; name="prompt"\r\n\r\n'
+    )
+    parts.append(
+        f"This is page {page_num} of a scanned PDF. Extract every legible text "
+        "verbatim, preserving reading order. Render tables as Markdown tables. "
+        "Skip decorative elements. Output plain Markdown only — no commentary."
+        .encode()
+    )
+    parts.append(f"\r\n--{boundary}--\r\n".encode())
+    payload = b"".join(parts)
+
+    req = urllib.request.Request(
+        server_url(),
+        data=payload,
+        headers={"Content-Type": f"multipart/form-data; boundary={boundary}"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.URLError as e:
+        sys.stderr.write(f"page {page_num}: server unreachable ({e})\n")
+        return None
+    except Exception as e:
+        sys.stderr.write(f"page {page_num}: {e}\n")
+        return None
+
+    if not data.get("ok"):
+        sys.stderr.write(f"page {page_num}: {data.get('message', 'unknown error')}\n")
+        return None
+    return data.get("text", "")
+
+
+def main():
+    if len(sys.argv) != 2:
+        sys.stderr.write("Usage: pdf_parser_vlm.py <file_path>\n")
+        sys.exit(1)
+    path = sys.argv[1]
+    if not os.path.exists(path):
+        sys.stderr.write(f"File not found: {path}\n")
+        sys.exit(1)
+
+    with tempfile.TemporaryDirectory(prefix="clacky_vlm_") as tmp:
+        pages = render_pages(path, tmp)
+        if not pages:
+            sys.stderr.write("Failed to render PDF pages (is poppler installed?)\n")
+            sys.exit(1)
+
+        sys.stderr.write(f"VLM OCR: {len(pages)} page(s) to transcribe...\n")
+        chunks = []
+        for i, page in enumerate(pages, 1):
+            text = transcribe_page(page, i)
+            if text is None:
+                # Server unreachable / no sidecar — bail so caller falls back.
+                sys.exit(1)
+            chunks.append(PAGE_SEPARATOR.format(n=i) + text)
+
+        sys.stdout.write("".join(chunks).strip())
+
+
+if __name__ == "__main__":
+    main()

data/lib/clacky/default_skills/persist-memory/SKILL.md

@@ -48,10 +48,11 @@ Scan the list above:
 
 Use the `write` tool. Always include the YAML frontmatter shown above.
 
-## Hard constraints (CRITICAL)
+## Guidelines
 
-- Each file MUST stay under **4000 characters of content** (after the frontmatter).
-- If merging would exceed this limit, remove the least important information — do NOT split into multiple files for the same topic.
+- Aim for around 4000 characters of content (after the frontmatter). This is a soft target — moderate overshoot is fine, do NOT iterate writes just to shave characters.
+- If a file grows much larger than that (say, well past 8000), trim the least important information rather than splitting one topic across multiple files.
+- Prefer merging into an existing file over creating a new one. Only create a new file when no existing topic genuinely covers the area.
 - Write concise, factual Markdown — no fluff, no redundant headings.
 - One topic per file. Don't bundle unrelated facts together.
 - Do NOT use `terminal` or `file_reader` to list the memories directory — the list above is authoritative.

data/lib/clacky/default_skills/search-skills/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: search-skills
+description: 'Search ALL installed skills (including ones not shown in AVAILABLE SKILLS) by keyword. Use this whenever you suspect a fitting skill might exist but is not listed in your system prompt — for example before building a new skill, when the user mentions a domain not covered by visible skills, or after seeing the (N more skills installed) hint. Triggers on phrases like search skills, find a skill for, is there a skill that, 查找skill, 有没有skill做.'
+disable-model-invocation: false
+user-invocable: true
+fork_agent: true
+auto_summarize: true
+forbidden_tools:
+  - write
+  - edit
+  - terminal
+  - web_search
+  - web_fetch
+  - browser
+---
+
+# Search Skills Subagent
+
+You are a Skill Search Subagent. Given a keyword or topic from the parent agent, scan the complete list of installed skills below and return the best matches.
+
+The AVAILABLE SKILLS section in the parent agent system prompt is capped (~30 entries). The list below is the FULL list — pre-loaded for you, no scanning required. Your job is to look beyond that cap so the parent does not redundantly create a new skill when one already exists.
+
+## Complete Skill Inventory
+
+This list was pre-loaded — do NOT re-scan the filesystem or call any tools.
+
+<%= all_skills_meta %>
+
+## Workflow
+
+### Step 1 — Extract keywords
+
+Pull 2-4 keywords from the input task. Both English and Chinese terms are valid (skill descriptions are bilingual).
+
+### Step 2 — Match against the inventory above
+
+For each skill in the inventory, judge relevance against the keywords:
+- Strong match: keyword appears in the skill `name` or clearly in the `description`'s purpose statement
+- Weak match: keyword appears only in the trigger examples or peripheral mentions
+
+### Step 3 — Return a ranked summary
+
+Return at most 5 results, strongest matches first:
+
+```
+Found N matching skill(s) for: <keywords>
+
+1. <name>  (<source>)
+   <description trimmed to ~200 chars>
+
+2. ...
+```
+
+If nothing genuinely matches, return exactly: `No installed skill matches: <task>`
+
+## Rules
+
+- Do NOT invoke any tool. The inventory above is authoritative; just match and return.
+- Do NOT recommend creating a new skill — that is the parent agent's call.
+- If the task is vague, return what genuinely matched, do not invent relevance.
+- Default skills (built-in) are part of the inventory but typically also visible to the parent — flagging them is still useful as a reminder.

data/lib/clacky/idle_compression_timer.rb

@@ -17,7 +17,7 @@ module Clacky
     # Seconds of inactivity before idle compression is triggered.
     # Kept under the 5-minute prompt cache TTL so the compression call itself
     # still hits the existing prefix cache.
-    IDLE_DELAY = 314
+    IDLE_DELAY = 266
 
     # @param agent [Clacky::Agent] the agent whose messages will be compressed
     # @param session_manager [Clacky::SessionManager, nil] used to persist session after compression

data/lib/clacky/message_format/open_ai.rb

@@ -206,7 +206,13 @@ module Clacky
           # Skip malformed tool calls where name or arguments is nil (broken API response)
           next if name.nil? || arguments.nil?
 
-          { id: call["id"], type: call["type"], name: name, arguments: arguments }
+          tc = { id: call["id"], type: call["type"], name: name, arguments: arguments }
+          # Vertex Gemini's OpenAI shim returns thought_signature inside
+          # tool_calls[i].extra_content.google and requires it echoed back on
+          # replay, otherwise the next turn 400s with "Function call is missing
+          # a thought_signature". Preserve it through the canonical layer.
+          tc[:extra_content] = call["extra_content"] if call["extra_content"]
+          tc
         end
       end
 

data/lib/clacky/openai_stream_aggregator.rb

@@ -72,7 +72,7 @@ module Clacky
     def to_h
       tool_calls = @tool_calls.keys.sort.map do |idx|
         tc = @tool_calls[idx]
-        {
+        out = {
           "id"       => tc[:id],
           "type"     => tc[:type] || "function",
           "function" => {
@@ -80,6 +80,8 @@ module Clacky
             "arguments" => tc[:arguments].to_s
           }
         }
+        out["extra_content"] = tc[:extra_content] if tc[:extra_content]
+        out
       end
 
       message = {
@@ -104,6 +106,7 @@ module Clacky
         slot[:name] ||= fn["name"] if fn["name"]
         slot[:arguments] << fn["arguments"].to_s if fn["arguments"]
       end
+      slot[:extra_content] = tc["extra_content"] if tc["extra_content"]
     end
 
     private def parse_or_nil(s)

data/lib/clacky/providers.rb

@@ -39,19 +39,30 @@ module Clacky
           "abs-claude-haiku-4-5",
           "dsk-deepseek-v4-pro",
           "dsk-deepseek-v4-flash",
-          "or-gemini-3-1-pro"
+          "or-gemini-3-1-pro",
+          "or-gemini-3-5-flash"
         ],
         # Image generation models served by the openclacky platform
         # gateway. The gateway exposes a standard OpenAI-compatible
         # /v1/images/generations endpoint, so the same OpenAICompat
-        # provider class handles them. `or-` prefix mirrors the chat
-        # model naming — these are routed through the OpenRouter
-        # backend by the platform.
+        # provider class handles them. `or-` prefix is a routing alias
+        # only — the platform may dispatch to OpenRouter or Vertex AI
+        # (Gemini Nano Banana family) depending on the model.
         "image_models" => [
           "or-gemini-3-pro-image",
+          "or-gemini-3-1-flash-image",
           "or-gpt-image-2"
         ],
+        "image_model_aliases" => {
+          "or-gemini-3-pro-image"      => "Nano Banana Pro",
+          "or-gemini-3-1-flash-image"  => "Nano Banana 2",
+          "or-gpt-image-2"             => "GPT Image 2"
+        },
         "default_image_model" => "or-gpt-image-2",
+        # Default OCR sidecar — used when the primary model is text-only.
+        # Candidates are derived from the provider's vision-capable models;
+        # this just picks the cheap+fast default to surface in "auto" mode.
+        "default_ocr_model" => "or-gemini-3-5-flash",
         # Provider-level default: the Claude family served here is vision-capable.
         "capabilities" => { "vision" => true }.freeze,
         # Model-level overrides: DeepSeek models routed through this provider
@@ -65,20 +76,17 @@ module Clacky
         # Per-primary lite pairing: keys are "strong" primary models, values
         # are the lite sidekick to auto-inject when that primary is the
         # default. Lite is consumed by some subagents for cheap/fast work;
-        # weak models (haiku / v4-flash) ARE the lite tier themselves, so
-        # they're intentionally not listed here — no injection happens when
-        # the default model is already lite-class.
-        #
-        # or-gemini-3-1-pro is intentionally absent: Gemini has no lite
-        # sibling wired up (yet) on this provider; subagents using the
-        # Gemini default will just reuse it for lite work until we add one.
+        # weak models (haiku / v4-flash / 3-5-flash) ARE the lite tier
+        # themselves, so they're intentionally not listed here as keys —
+        # no injection happens when the default model is already lite-class.
         "lite_models" => {
           "abs-claude-opus-4-8"   => "abs-claude-haiku-4-5",
           "abs-claude-opus-4-7"   => "abs-claude-haiku-4-5",
           "abs-claude-opus-4-6"   => "abs-claude-haiku-4-5",
           "abs-claude-sonnet-4-6" => "abs-claude-haiku-4-5",
           "abs-claude-sonnet-4-5" => "abs-claude-haiku-4-5",
-          "dsk-deepseek-v4-pro"   => "dsk-deepseek-v4-flash"
+          "dsk-deepseek-v4-pro"   => "dsk-deepseek-v4-flash",
+          "or-gemini-3-1-pro"     => "or-gemini-3-5-flash"
         },
         # Fallback chain: if a model is unavailable, try the next one in order.
         # Keys are primary model names; values are the fallback model to use instead.
@@ -141,6 +149,7 @@ module Clacky
         # until we ship a dedicated client-side adapter for that protocol.
         "image_models" => [],
         "default_image_model" => nil,
+        "default_ocr_model" => "google/gemini-2.5-flash",
         "website_url" => "https://openrouter.ai/keys"
       }.freeze,
 
@@ -188,6 +197,7 @@ module Clacky
         "model_capabilities" => {
           "MiniMax-M3" => { "vision" => true }.freeze
         }.freeze,
+        "default_ocr_model" => "MiniMax-M3",
         "website_url" => "https://www.minimaxi.com/user-center/basic-information/interface-key"
       }.freeze,
 
@@ -214,6 +224,7 @@ module Clacky
         ].freeze,
         # k2.5 / k2.6 are multimodal; legacy k2 text-only models need model_capabilities override if added.
         "capabilities" => { "vision" => true }.freeze,
+        "default_ocr_model" => "kimi-k2.5",
         "website_url" => "https://platform.moonshot.cn/console/api-keys"
       }.freeze,
 
@@ -261,6 +272,7 @@ module Clacky
         "api" => "anthropic-messages",
         "default_model" => "claude-sonnet-4-6",
         "models" => ["claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5"],
+        "default_ocr_model" => "claude-haiku-4-5",
         "website_url" => "https://console.anthropic.com/settings/keys"
       }.freeze,
 
@@ -275,6 +287,7 @@ module Clacky
         "model_capabilities" => {
           "mimo-v2-omni" => { "vision" => true }.freeze
         }.freeze,
+        "default_ocr_model" => "mimo-v2-omni",
         "website_url" => "https://platform.xiaomimimo.com/"
       }.freeze,
 
@@ -304,6 +317,7 @@ module Clacky
         "model_capabilities" => {
           "glm-5v-turbo" => { "vision" => true }.freeze
         }.freeze,
+        "default_ocr_model" => "glm-5v-turbo",
         "website_url" => "https://open.bigmodel.cn/usercenter/apikeys"
       }.freeze,
 
@@ -334,6 +348,7 @@ module Clacky
           "gpt-image-2"
         ],
         "default_image_model" => "gpt-image-2",
+        "default_ocr_model" => "gpt-5.4-mini",
         "website_url" => "https://platform.openai.com/api-keys"
       }.freeze,
 
@@ -359,6 +374,7 @@ module Clacky
         "model_capabilities" => {
           "qwen3.7-max" => { "vision" => false }.freeze
         }.freeze,
+        "default_ocr_model" => "qwen3.6-flash",
         "lite_models" => {
           "qwen3.7-max"      => "qwen3.6-flash",
           "qwen3.6-plus"     => "qwen3.6-flash",
@@ -487,6 +503,30 @@ module Clacky
         preset&.dig("image_models") || []
       end
 
+      def image_model_aliases(provider_id)
+        preset = PRESETS[provider_id]
+        preset&.dig("image_model_aliases") || {}
+      end
+
+      def video_model_aliases(provider_id)
+        preset = PRESETS[provider_id]
+        preset&.dig("video_model_aliases") || {}
+      end
+
+      def audio_model_aliases(provider_id)
+        preset = PRESETS[provider_id]
+        preset&.dig("audio_model_aliases") || {}
+      end
+
+      def media_model_aliases(provider_id, kind)
+        case kind.to_s
+        when "image" then image_model_aliases(provider_id)
+        when "video" then video_model_aliases(provider_id)
+        when "audio" then audio_model_aliases(provider_id)
+        else {}
+        end
+      end
+
       # Video generation models — placeholder. No provider supports video
       # via Clacky yet; once they do, declare "video_models" alongside
       # "image_models" in the relevant PRESETS entry and this returns it.
@@ -501,6 +541,31 @@ module Clacky
         preset&.dig("audio_models") || []
       end
 
+      # OCR sidecar candidates: every chat model under this provider that's
+      # vision-capable. Derived from `vision` capability so we don't have
+      # to maintain a parallel list — a model that can see is by definition
+      # a candidate for "describe an image as text". Image-generation models
+      # are excluded (they take prompts and return pixels, not the other way).
+      # @param provider_id [String]
+      # @return [Array<String>]
+      def ocr_models(provider_id)
+        preset = PRESETS[provider_id]
+        return [] unless preset
+        (preset["models"] || []).select { |m| supports?(provider_id, :vision, model_name: m) }
+      end
+
+      # Default OCR sidecar model for a provider. Falls back to the first
+      # vision-capable model if the preset doesn't pin an explicit default.
+      # @param provider_id [String]
+      # @return [String, nil] nil when the provider has zero vision-capable models
+      def default_ocr_model(provider_id)
+        preset = PRESETS[provider_id]
+        return nil unless preset
+        explicit = preset["default_ocr_model"]
+        return explicit if explicit && ocr_models(provider_id).include?(explicit)
+        ocr_models(provider_id).first
+      end
+
       # Unified entry for media model lookup by kind.
       # @param provider_id [String]
       # @param kind [String] one of "image" / "video" / "audio"