scribecast 0.1.0__py3-none-any.whl

scribecast/mcp.py

@@ -0,0 +1,190 @@
+"""scribecast.mcp — a minimal stdio JSON-RPC 2.0 MCP server exposing scribecast to any agent.
+
+Zero third-party dependency (no mcp-sdk required) so it installs with the base wheel. Implements
+the MCP subset that matters: `initialize`, `tools/list`, `tools/call`. Speaks newline-delimited
+JSON-RPC over stdin/stdout (the common stdio transport). Any MCP client (Claude, Hermes, Cursor)
+or a plain worker can drive it.
+
+Tools:
+  render_note_video(ref, source?, engine?, voice?, narrate?)  -> {output, engine, duration, ...}
+  recommend_engine(ref, source?)                              -> {recommended, reason, scores}
+  list_sources()                                              -> {source: {tool, available}}
+  list_voices()                                               -> {voices: [...]}
+
+Run:  python -m scribecast.mcp     (stdio)
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+from . import __version__
+from .logging_setup import get_logger
+
+_log = get_logger(__name__)
+
+PROTOCOL_VERSION = "2024-11-05"
+
+TOOLS = [
+    {
+        "name": "render_note_video",
+        "description": "Resolve a note from a source and render it into a narrated video. "
+                       "Returns the output mp4 path. Engine: user choice wins over recommendation.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "ref": {"type": "string", "description": "source:locator or locator, e.g. file:notes.md, gbrain:my-slug"},
+                "source": {"type": "string", "description": "default source if ref has no prefix (file/gbrain/vault/ksum/stdin)"},
+                "engine": {"type": "string", "enum": ["hyperframes", "manim", "remotion"], "description": "force engine (wins over recommendation)"},
+                "voice": {"type": "string", "description": "edge-tts voice id"},
+                "out": {"type": "string", "description": "output mp4 path"},
+                "narrate": {"type": "boolean", "description": "narrate with edge-tts (default true)"},
+            },
+            "required": ["ref"],
+        },
+    },
+    {
+        "name": "recommend_engine",
+        "description": "Recommend a render engine from a note's content (advisory; user always decides).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "ref": {"type": "string"},
+                "source": {"type": "string"},
+            },
+            "required": ["ref"],
+        },
+    },
+    {
+        "name": "list_sources",
+        "description": "List note sources and whether each one's tool is available on this machine.",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "list_voices",
+        "description": "List common edge-tts voice ids for narration.",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+]
+
+
+def _ok(result: Any) -> dict:
+    # MCP tools/call returns content blocks
+    return {"content": [{"type": "text", "text": json.dumps(result, indent=2)}], "isError": False}
+
+
+def _err(msg: str) -> dict:
+    return {"content": [{"type": "text", "text": msg}], "isError": True}
+
+
+def _call_tool(name: str, args: dict) -> dict:
+    """Dispatch a tool call, converting ANY exception (missing args, bad enum, engine error)
+    into a JSON-RPC tool error. Nothing here may propagate — an uncaught exception would kill
+    the server's stdin loop (P0). args is validated defensively (ref required for render/recommend)."""
+    _log.info("mcp: tools/call name=%s", name)
+    try:
+        return _dispatch_tool(name, args)
+    except Exception as exc:  # noqa: BLE001 — deliberate catch-all; server must never crash
+        _log.error("mcp: tool %s raised %s: %s", name, type(exc).__name__, exc)
+        return _err(f"{type(exc).__name__}: {exc}")
+
+
+def _dispatch_tool(name: str, args: dict) -> dict:
+    if name == "render_note_video":
+        from .pipeline import render_note, PipelineError
+        from .resolver import ResolverError
+        if not args.get("ref"):
+            return _err("render_note_video requires 'ref'")
+        try:
+            res = render_note(
+                args["ref"], source=args.get("source"), engine=args.get("engine"),
+                voice=args.get("voice"), out=args.get("out"),
+                narrate=args.get("narrate", True),
+            )
+        except (PipelineError, ResolverError) as exc:
+            return _err(f"{type(exc).__name__}: {exc}")
+        return _ok({"output": res.output, "engine": res.engine,
+                    "recommended": res.recommendation.engine, "cards": res.cards,
+                    "narrated": res.narrated, "duration": res.duration, "notes": res.notes})
+    if name == "recommend_engine":
+        from .resolver import resolve, ResolverError
+        from .selector import recommend_engine
+        if not args.get("ref"):
+            return _err("recommend_engine requires 'ref'")
+        try:
+            text = resolve(args["ref"], source=args.get("source", "file"))
+        except ResolverError as exc:
+            return _err(str(exc))
+        rec = recommend_engine(text)
+        return _ok({"recommended": rec.engine, "reason": rec.reason, "scores": rec.scores})
+    if name == "list_sources":
+        from .resolver import list_sources
+        return _ok(list_sources())
+    if name == "list_voices":
+        return _ok({"voices": ["en-US-AriaNeural", "en-US-GuyNeural", "en-GB-RyanNeural",
+                               "en-IN-NeerjaNeural", "en-AU-NatashaNeural"]})
+    return _err(f"unknown tool: {name}")
+
+
+def handle(req: dict) -> dict | None:
+    """Handle one JSON-RPC request. Returns a response dict, or None for notifications."""
+    method = req.get("method")
+    rid = req.get("id")
+    if method == "initialize":
+        return {"jsonrpc": "2.0", "id": rid, "result": {
+            "protocolVersion": PROTOCOL_VERSION,
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "scribecast", "version": __version__},
+        }}
+    if method == "notifications/initialized":
+        return None
+    if method == "tools/list":
+        return {"jsonrpc": "2.0", "id": rid, "result": {"tools": TOOLS}}
+    if method == "tools/call":
+        params = req.get("params", {})
+        result = _call_tool(params.get("name", ""), params.get("arguments", {}) or {})
+        return {"jsonrpc": "2.0", "id": rid, "result": result}
+    if method == "ping":
+        return {"jsonrpc": "2.0", "id": rid, "result": {}}
+    # unknown method: notifications (no id) get no response per JSON-RPC; requests get an error
+    if rid is None:
+        return None
+    return {"jsonrpc": "2.0", "id": rid,
+            "error": {"code": -32601, "message": f"method not found: {method}"}}
+
+
+def serve(stdin=None, stdout=None) -> None:
+    """Run the stdio JSON-RPC loop (newline-delimited). A handler exception is converted to a
+    JSON-RPC internal error (or swallowed for notifications) — the loop NEVER dies on bad input."""
+    stdin = stdin or sys.stdin
+    stdout = stdout or sys.stdout
+    os.environ["SCRIBECAST_MCP_ACTIVE"] = "1"  # tells the resolver that stdin is the transport
+    # logs MUST go to stderr — stdout is the JSON-RPC transport
+    from .logging_setup import configure_logging
+    configure_logging(stream=sys.stderr)
+    _log.info("mcp: scribecast server started (v%s)", __version__)
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError:  # pragma: no cover - malformed line skip
+            continue
+        try:
+            resp = handle(req)
+        except Exception as exc:  # noqa: BLE001 — server must never crash on a single bad request
+            rid = req.get("id") if isinstance(req, dict) else None
+            resp = None if rid is None else {
+                "jsonrpc": "2.0", "id": rid,
+                "error": {"code": -32603, "message": f"internal error: {type(exc).__name__}: {exc}"},
+            }
+        if resp is not None:
+            stdout.write(json.dumps(resp) + "\n")
+            stdout.flush()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    serve()

scribecast/pipeline.py

@@ -0,0 +1,264 @@
+"""scribecast.pipeline — the render_note core: resolve -> script -> render -> narrate -> mux -> mp4.
+
+Imports vidkit (vidkit_core) for narration + mux + probe; never shells a vendored copy.
+
+Default renderer ("cards"): split the script into titled text cards, render each as a PNG with
+Pillow, assemble an image-sequence mp4 with ffmpeg, then narrate (edge-tts) and mux (the
+bug-fixed vidkit mux — video duration authoritative). This default has only Pillow + ffmpeg as
+needs and works without a browser or Manim. The heavy engines (manim/remotion) are opt-in and
+delegate to the vidkit engine kits when their extras are installed.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+import textwrap
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .config import Config, load_config
+from .resolver import resolve, ResolverError
+from .selector import choose, Recommendation
+from .logging_setup import get_logger
+
+_log = get_logger(__name__)
+
+
+class PipelineError(RuntimeError):
+    """Raised when the render pipeline cannot complete (missing dep, render failure)."""
+
+
+@dataclass
+class RenderResult:
+    output: str                       # path to the final mp4
+    engine: str
+    recommendation: Recommendation
+    cards: int
+    narrated: bool
+    duration: float | None = None
+    notes: list[str] = field(default_factory=list)
+
+
+# ---- script segmentation --------------------------------------------------
+def script_from_text(text: str, max_cards: int = 12) -> list[tuple[str, str]]:
+    """Turn note text into [(title, body)] cards. Splits on markdown headings; falls back to
+    paragraph chunks. Keeps it bounded so a long note doesn't make a 200-card video."""
+    text = (text or "").strip()
+    if not text:
+        raise PipelineError("empty script: nothing to render")
+    cards: list[tuple[str, str]] = []
+    cur_title, cur_body = "", []
+    for line in text.splitlines():
+        s = line.strip()
+        if s.startswith("#"):
+            if cur_title or cur_body:
+                cards.append((cur_title, "\n".join(cur_body).strip()))
+            cur_title = s.lstrip("#").strip()
+            cur_body = []
+        else:
+            cur_body.append(line)
+    if cur_title or cur_body:
+        cards.append((cur_title, "\n".join(cur_body).strip()))
+
+    # fallback: no headings (single untitled card) -> chunk into paragraphs
+    if not cards or (len(cards) == 1 and not cards[0][0]):
+        paras = [p.strip() for p in text.split("\n\n") if p.strip()]
+        if len(paras) > 1:
+            cards = [("", p) for p in paras]
+    # bound
+    if len(cards) > max_cards:
+        cards = cards[:max_cards]
+    # ensure at least one card with content
+    cards = [(t, b) for (t, b) in cards if (t or b)]
+    if not cards:
+        cards = [("", text[:500])]
+    return cards
+
+
+# ---- default "cards" renderer (Pillow -> ffmpeg image sequence) -----------
+def _render_cards(cards: list[tuple[str, str]], out_path: str, *,
+                  width: int = 1280, height: int = 720, seconds_per_card: float = 3.0,
+                  fps: int = 24) -> str:
+    try:
+        from PIL import Image, ImageDraw, ImageFont
+    except ImportError as exc:  # pragma: no cover - Pillow present in this env
+        raise PipelineError(
+            "the default 'cards' renderer needs Pillow. Install: pip install pillow "
+            "(or pip install vidkit[manim])."
+        ) from exc
+    if shutil.which("ffmpeg") is None:  # pragma: no cover - ffmpeg present in this env
+        raise PipelineError("ffmpeg is required to assemble the video but is not on PATH.")
+
+    import tempfile
+    bg = (16, 18, 28)
+    fg = (236, 238, 245)
+    accent = (110, 123, 255)
+
+    def _font(size: int):
+        for cand in ("/System/Library/Fonts/Helvetica.ttc",
+                     "/System/Library/Fonts/Supplemental/Arial.ttf",
+                     "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"):
+            if Path(cand).exists():
+                try:
+                    return ImageFont.truetype(cand, size)
+                except Exception:  # pragma: no cover - system font present
+                    pass
+        return ImageFont.load_default()  # pragma: no cover - only if no system font
+
+    title_f = _font(56)
+    body_f = _font(34)
+    seconds_per_card = max(0.3, float(seconds_per_card))   # clamp: negative/zero -> cryptic ffmpeg fail
+    frames_dir = Path(tempfile.mkdtemp(prefix="scribecast-frames-"))
+    try:
+        # One PNG per card (not N identical frames) + a concat demuxer with per-image durations:
+        # avoids the frame-explosion (was int(spc*fps) identical files per card).
+        concat_lines = []
+        for idx, (title, body) in enumerate(cards):
+            img = Image.new("RGB", (width, height), bg)
+            d = ImageDraw.Draw(img)
+            y = 90
+            if title:
+                d.rectangle([(80, y - 20), (88, y + 60)], fill=accent)
+                d.text((110, y), title[:80], font=title_f, fill=fg)
+                y += 110
+            for para in (body or "").split("\n"):
+                for wrapped in textwrap.wrap(para, width=58) or [""]:
+                    if y > height - 80:
+                        break
+                    d.text((110, y), wrapped, font=body_f, fill=fg)
+                    y += 46
+                y += 10
+            png = frames_dir / f"card_{idx:04d}.png"
+            img.save(png)
+            concat_lines.append(f"file '{png.name}'")
+            concat_lines.append(f"duration {seconds_per_card}")
+        # concat demuxer needs the last file repeated (its duration is otherwise dropped)
+        if concat_lines:
+            last_png = f"card_{len(cards) - 1:04d}.png"
+            concat_lines.append(f"file '{last_png}'")
+        (frames_dir / "concat.txt").write_text("\n".join(concat_lines))
+
+        Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+        cmd = ["ffmpeg", "-y", "-f", "concat", "-safe", "0", "-i", str(frames_dir / "concat.txt"),
+               "-vf", f"fps={fps},format=yuv420p", "-c:v", "libx264", out_path]
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+    finally:
+        shutil.rmtree(frames_dir, ignore_errors=True)
+    if proc.returncode != 0:
+        raise PipelineError(f"ffmpeg card assembly failed: {proc.stderr[-800:]}")  # pragma: no cover
+    if not Path(out_path).exists() or Path(out_path).stat().st_size == 0:
+        raise PipelineError("card render produced no output")  # pragma: no cover
+    return out_path
+
+
+def _render_engine(engine: str, cards, out_path, **kw) -> str:
+    """Dispatch to the chosen engine. 'hyperframes'/'cards' use the built-in Pillow renderer
+    (always available). 'manim'/'remotion' require their extras + kits; raise a clear error if
+    not installed (never silently degrade to a different engine)."""
+    if engine in ("hyperframes", "cards"):
+        return _render_cards(cards, out_path, **kw)
+    if engine == "manim":
+        try:
+            import manim  # noqa: F401
+        except ImportError as exc:  # pragma: no cover - manim installed in this env
+            raise PipelineError(
+                "engine 'manim' needs the manim extra: pip install vidkit[manim]. "
+                "(Or choose --engine hyperframes for the dependency-light default.)"
+            ) from exc
+        # Real cinematic adapter: renders the cards through vqkit.CinematicScene (moving camera,
+        # animated reveal, MathTex). NOT a silent fallback to hyperframes.
+        from .engines.manim_adapter import render_cards_manim, ManimAdapterError
+        quality = kw.pop("quality", "m")
+        try:
+            return render_cards_manim(cards, out_path, quality=quality)
+        except ManimAdapterError as exc:
+            raise PipelineError(str(exc)) from exc
+    if engine == "remotion":
+        # Real adapter: drives the remotion_kit ScribecastCards composition. Raises a clear
+        # error if Node/kit/node_modules are missing — NEVER a silent fallback to another engine.
+        from .engines.remotion_adapter import render_cards_remotion, RemotionAdapterError
+        spc = kw.pop("seconds_per_card", 3.0)
+        try:
+            return render_cards_remotion(cards, out_path, per_card_seconds=spc)
+        except RemotionAdapterError as exc:
+            raise PipelineError(str(exc)) from exc
+    raise PipelineError(f"unknown engine '{engine}'")
+
+
+def render_note(ref, *, source: str | None = None, engine: str | None = None,
+                voice: str | None = None, out: str | None = None,
+                narrate: bool = True, config: Config | None = None,
+                seconds_per_card: float = 3.0) -> RenderResult:
+    """Resolve a note reference, build a card script, render a video, narrate it, and mux.
+
+    ref:     a `source:locator` / locator, or a list (merge).
+    Returns RenderResult with the output mp4 path. USER-WINS on engine (explicit > recommended).
+    """
+    cfg = config or load_config(overrides={"engine": engine, "voice": voice, "source": source})
+    src = source or cfg.source
+    notes: list[str] = []
+    _log.info("render_note: ref=%r source=%s narrate=%s", ref, src, narrate)
+
+    # 1) resolve
+    text = resolve(ref, source=src)
+    _log.debug("render_note: resolved %d chars", len(text))
+
+    # 2) engine selection — ALL precedence lives in selector.resolve_engine (single contract:
+    #    explicit user engine > non-default config engine > heuristic recommendation). Pipeline
+    #    does NO reconciliation of its own.
+    from .selector import resolve_engine
+    eng, rec = resolve_engine(text, user_choice=engine, config_engine=cfg.engine)
+    notes.append(f"engine={eng} (recommended={rec.engine}: {rec.reason})")
+    _log.info("render_note: engine=%s (recommended=%s, user=%s, config=%s)",
+              eng, rec.engine, engine, cfg.engine)
+
+    # 3) script
+    cards = script_from_text(text)
+    _log.info("render_note: %d card(s) from script", len(cards))
+
+    # 4) render — intermediates go in a UNIQUE temp dir (not fixed names in the shared out_dir),
+    #    so concurrent render_note calls can't clobber each other's _silent.mp4 / _vo.mp3.
+    out_dir = Path(cfg.out_dir); out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out or str(out_dir / "scribecast.mp4")
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)   # honor a user -o into a new dir
+    import tempfile as _tf
+    work = Path(_tf.mkdtemp(prefix="scribecast-render-"))
+    try:
+        silent = str(work / "_silent.mp4")
+        _log.info("render_note: rendering %d card(s) via %s", len(cards), eng)
+        _render_engine(eng, cards, silent, seconds_per_card=seconds_per_card)
+        _log.debug("render_note: engine render complete -> %s", silent)
+
+        # 5) narrate + mux (imports vidkit; video duration authoritative via the apad fix)
+        narrated = False
+        if narrate:
+            try:
+                from vidkit_core.audio import synth_voiceover, mux
+                script_text = ". ".join(f"{t}. {b}" if t else b for t, b in cards)[:4000]
+                vo = str(work / "_vo.mp3")
+                _log.info("render_note: narrating (voice=%s)", voice or cfg.voice)
+                synth_voiceover(script_text, vo, voice=voice or cfg.voice)
+                mux(silent, voiceover=vo, out_path=out_path)
+                narrated = True
+                _log.info("render_note: narrated + muxed -> %s", out_path)
+            except Exception as exc:  # narration is best-effort; never silently fake it
+                notes.append(f"narration skipped: {type(exc).__name__}: {exc}")
+                _log.warning("render_note: narration skipped (%s: %s); using silent video",
+                             type(exc).__name__, exc)
+                shutil.copy(silent, out_path)
+        else:
+            shutil.copy(silent, out_path)
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+    # 6) probe
+    duration = None
+    try:
+        from vidkit_core.render import ffprobe
+        duration = ffprobe(out_path).duration
+    except Exception:
+        pass
+    _log.info("render_note: done -> %s (%.2fs, narrated=%s)", out_path, duration or 0.0, narrated)
+
+    return RenderResult(output=out_path, engine=eng, recommendation=rec,
+                        cards=len(cards), narrated=narrated, duration=duration, notes=notes)

scribecast/resolver.py

@@ -0,0 +1,171 @@
+"""scribecast.resolver — turn a note reference into clean text from any configured source.
+
+A reference is `source:locator` (e.g. `file:notes.md`, `gbrain:two-brain-architecture`,
+`vault:what did I decide about X`, `ksum:https://...`, `stdin:`) OR a bare locator with an
+explicit `source=` argument. `merge` takes multiple refs and concatenates them with headers.
+
+Source CLIs are called as subprocess for READING text only (note resolution), never as the
+render engine. A missing CLI raises ResolverError naming the tool — never returns silent empty.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Iterable
+
+from .logging_setup import get_logger
+
+_log = get_logger(__name__)
+
+# Known sources and the CLI each needs (None = no external tool).
+SOURCES: dict[str, str | None] = {
+    "file": None,
+    "stdin": None,
+    "gbrain": "gbrain",
+    "vault": "praxvault-ask",
+    "ksum": "ksum",
+    "openmemory": "openmemory",   # optional; config-gated, may not exist
+    "merge": None,
+}
+
+
+class ResolverError(RuntimeError):
+    """Raised when a note cannot be resolved (missing tool, missing file, empty result)."""
+
+
+def _run(cmd: list[str], tool: str, timeout: int = 120) -> str:
+    if shutil.which(cmd[0]) is None and not Path(cmd[0]).exists():
+        _log.error("resolver: tool %r not on PATH", tool)
+        raise ResolverError(
+            f"source needs '{tool}' but it is not on PATH. Install/expose it, or pick another source."
+        )
+    _log.debug("resolver: running %s", " ".join(cmd))
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired as exc:
+        _log.error("resolver: %s timed out after %ds", tool, timeout)
+        raise ResolverError(f"{tool} timed out after {timeout}s") from exc
+    if proc.returncode != 0:
+        _log.error("resolver: %s failed (exit %d)", tool, proc.returncode)
+        raise ResolverError(f"{tool} failed (exit {proc.returncode}): {proc.stderr.strip()[:500]}")
+    text = proc.stdout.strip()
+    if not text:
+        _log.error("resolver: %s returned empty output", tool)
+        raise ResolverError(f"{tool} returned empty output for the given reference")
+    _log.info("resolver: %s resolved %d chars", tool, len(text))
+    return text
+
+
+def _resolve_file(locator: str) -> str:
+    p = Path(locator).expanduser()
+    if not p.is_file():
+        raise ResolverError(f"file not found: {p}")
+    text = p.read_text(encoding="utf-8", errors="replace").strip()
+    if not text:
+        raise ResolverError(f"file is empty: {p}")
+    return text
+
+
+def _resolve_stdin(_locator: str) -> str:
+    # Guard: if stdin is a TTY (no pipe) it would block forever waiting for EOF; and under the
+    # MCP server stdin IS the JSON-RPC transport (reading it would hang the server). Refuse both.
+    if sys.stdin is None or sys.stdin.isatty():
+        raise ResolverError("stdin source selected but nothing is piped (or stdin is a terminal)")
+    if os.environ.get("SCRIBECAST_MCP_ACTIVE") == "1":
+        raise ResolverError("stdin source is not available inside the MCP server "
+                            "(stdin is the JSON-RPC transport); use file/gbrain/vault/ksum")
+    data = sys.stdin.read().strip()
+    if not data:
+        raise ResolverError("stdin source selected but no piped input was received")
+    return data
+
+
+def _check_locator(locator: str, tool: str) -> None:
+    """Reject locators that would be mis-parsed as CLI options (argv option injection)."""
+    if locator.startswith("-"):
+        raise ResolverError(
+            f"{tool}: locator may not start with '-' (would be parsed as an option): {locator!r}"
+        )
+
+
+def _resolve_gbrain(locator: str) -> str:
+    _check_locator(locator, "gbrain")
+    return _run(["gbrain", "get", locator], "gbrain")
+
+
+def _resolve_vault(locator: str) -> str:
+    # praxvault-ask <query> — plain-text answer used as the note body.
+    _check_locator(locator, "praxvault-ask")
+    return _run(["praxvault-ask", locator], "praxvault-ask")
+
+
+def _resolve_ksum(locator: str) -> str:
+    _check_locator(locator, "ksum")
+    return _run(["ksum", locator, "--no-save"], "ksum")
+
+
+def _resolve_openmemory(locator: str) -> str:
+    _check_locator(locator, "openmemory")
+    return _run(["openmemory", "get", locator], "openmemory")
+
+
+_DISPATCH = {
+    "file": _resolve_file,
+    "stdin": _resolve_stdin,
+    "gbrain": _resolve_gbrain,
+    "vault": _resolve_vault,
+    "ksum": _resolve_ksum,
+    "openmemory": _resolve_openmemory,
+}
+
+
+def _split_ref(ref: str, default_source: str) -> tuple[str, str]:
+    """Split `source:locator`. If no known `source:` prefix, use default_source and whole ref."""
+    if ":" in ref:
+        head, _, tail = ref.partition(":")
+        if head in SOURCES:
+            return head, tail
+    return default_source, ref
+
+
+def resolve(ref: str | Iterable[str], source: str = "file") -> str:
+    """Resolve a reference (or several, for merge) to text.
+
+    ref:    a single `source:locator` / locator, OR an iterable of them (merge).
+    source: default source when a ref carries no `source:` prefix.
+    """
+    # merge: iterable of refs
+    if not isinstance(ref, str):
+        refs = list(ref)
+        if not refs:
+            raise ResolverError("merge: no references given")
+        parts = []
+        for r in refs:
+            src, loc = _split_ref(r, source)
+            text = _resolve_one(src, loc)
+            parts.append(f"## Source: {src}:{loc}\n\n{text}")
+        return "\n\n---\n\n".join(parts)
+
+    src, loc = _split_ref(ref, source)
+    if src == "merge":
+        raise ResolverError("merge needs multiple references; pass a list to resolve()")
+    return _resolve_one(src, loc)
+
+
+def _resolve_one(src: str, locator: str) -> str:
+    fn = _DISPATCH.get(src)
+    if fn is None:
+        raise ResolverError(f"unknown source '{src}'. Known: {', '.join(sorted(_DISPATCH))}")
+    return fn(locator)
+
+
+def list_sources() -> dict[str, dict]:
+    """Describe each source + whether its tool is currently available."""
+    out = {}
+    for name, tool in SOURCES.items():
+        available = True if tool is None else (shutil.which(tool) is not None)
+        out[name] = {"tool": tool, "available": available}
+    return out