mediarag 0.1.14__py3-none-any.whl

mediarag/__init__.py

@@ -0,0 +1,140 @@
+"""MediaRAG plugin entry — agent-plugins 1.0, loaded as hermes_plugins.<slug>.
+
+register(ctx) is the real loader contract: ctx.register_tool(name, toolset,
+schema={"type":"object","parameters":…}, handler, description). Handlers
+absorb dispatch kwargs themselves (**_x — Hermes passes task_id + extras).
+
+Env contract: register() checks that onnxruntime, numpy, and transformers
+import, and refuses to register tools when they do not. Install them with
+`pip install -r requirements.txt`. The model snapshot is loaded from the
+Hugging Face cache and is not downloaded on startup.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+_PLUGIN_DIR = os.path.dirname(os.path.abspath(__file__))
+
+def _config_root() -> str:
+    """Corpus root from mediarag-config.yaml in the plugin dir (named config, rag-config.yaml pattern).
+    # ponytail: flat `root:` line parse — no yaml dependency on the stdio spawn path;
+    # switch to yaml.safe_load if the config ever grows beyond one key.
+    """
+    path = os.path.join(_PLUGIN_DIR, "mediarag-config.yaml")
+    try:
+        with open(path, encoding="utf-8") as fh:
+            for line in fh:
+                if line.strip().startswith("root:"):
+                    return line.split(":", 1)[1].strip().strip("'\"")
+    except OSError:
+        pass
+    return ""
+
+
+TOOL_ROOT = _config_root() or os.environ.get("MEDIARAG_ROOT") or os.path.expanduser("~/.mediarag")
+
+PYVER = f"python{sys.version_info.major}.{sys.version_info.minor}"
+
+BOOTSTRAP_HINT = (
+    "MediaRAG engine deps missing — pip install -r requirements.txt "
+    "from the plugin directory"
+)
+
+
+def _engine_importable() -> bool:
+    try:
+        import onnxruntime  # noqa: F401
+        import numpy  # noqa: F401
+        import transformers  # noqa: F401
+        # The processor chain constructs a video processor needing BOTH torch and
+        # torchvision; without them every embed raises ImportError at call time
+        # while the plugin still advertises five working tools.
+        import torch  # noqa: F401
+        import torchvision  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+def register(ctx) -> None:
+    """MediaRAG native tool registration (Hermes loader contract)."""
+    # Deps arrive with the plugin install (python_dependencies / requirements.txt).
+    # Nothing here edits sys.path or the process environment: this runs inside the
+    # Hermes gateway, where either would leak into every other plugin.
+    if not _engine_importable():
+        print(f"[mediarag] {BOOTSTRAP_HINT}")
+        return
+
+    import json as _json
+
+    from .core import tools as _tools
+
+    def _json_result(handler):
+        """Registry dispatch contract: handler receives ONE positional arg (the
+        args dict, task_id-style extras included) and returns a str (dict
+        results are rejected — the workspace plugin's lifetime bug)."""
+        def wrapped(args=None, **kwargs):
+            a = dict(args or {})
+            a.update(kwargs)
+            return _json.dumps(handler(**a))
+        return wrapped
+
+    def reg(name, desc, handler, params, required):
+        ctx.register_tool(
+            name=name,
+            toolset="mediarag",
+            schema={"type": "object", "parameters": {
+                "type": "object", "properties": params, "required": required}},
+            handler=_json_result(handler),
+            check_fn=lambda: True,
+            description=desc,
+        )
+
+    reg(
+        "mediarag_search",
+        "Search documents and media (hybrid: semantic + keyword/BM25): text, images, "
+        "audio. Ranked hits with snippets, scores, spans, and image thumbnails.",
+        _tools.tool_search,
+        {
+            "query": {"type": "string", "description": "natural-language query (or keyword terms)"},
+            "k": {"type": "integer", "default": 5},
+            "kind": {"type": "string", "enum": ["text", "image", "audio"]},
+            "include_thumbnails": {"type": "boolean", "default": True},
+        },
+        ["query"],
+    )
+    reg(
+        "mediarag_add_note",
+        "Store a text note into the MediaRAG corpus (searchable afterwards).",
+        _tools.tool_add_note,
+        {"text": {"type": "string", "description": "note text"},
+         },
+        ["text"],
+    )
+    reg(
+        "mediarag_ingest_dir",
+        "Bulk-index a directory of documents and media (pdf, office, notes, "
+        "subtitles, images, audio). Per-file errors are collected, never fatal.",
+        _tools.tool_ingest_dir,
+        {"path": {"type": "string"},
+         },
+        ["path"],
+    )
+    reg(
+        "mediarag_add_source",
+        "Add one source: local file/dir, http(s) URL, or adapter scheme URI "
+        "(raindrop://, pcloud://, obsidian://, rclone://backend:path).",
+        _tools.tool_add_source,
+        {"source": {"type": "string"},
+         },
+        ["source"],
+    )
+    reg(
+        "mediarag_status",
+        "MediaRAG corpus status: row counts by kind, corpus root, adapters.",
+        _tools.tool_status,
+        {},
+        [],
+    )
+    print(f"[mediarag] 5 tools registered (corpus root: {TOOL_ROOT})")

mediarag/adapters/dropbox

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""MediaRAG source adapter: dropbox://<path-in-dropbox> — Dropbox assets via the
+desktop client's local folder (or any local mirror).
+
+Env: DROPBOX_DIR (default: "~/Dropbox"). Item shape: {"uri", "path"} — the
+indexer decodes/embeds real files itself, so this adapter deliberately does not
+carry its own extension list: `ing.index_file` knows which formats it can read
+(pdf/epub/docx via pandoc, pdf via pdftotext, images, audio) and returns an
+`unsupported_ext` skip for the rest. Duplicating that list here is how Dropbox
+PDFs would go missing without a word.
+"""
+import json
+import os
+import sys
+
+# Dropbox's own bookkeeping, plus the usual VCS/mount debris. Anything else is
+# the indexer's call.
+SKIP_DIRS = {".dropbox", ".dropbox.cache", ".git", ".obsidian", ".trash"}
+
+
+def main():
+    if len(sys.argv) != 3 or sys.argv[1] != "fetch":
+        print("usage: dropbox fetch <path-in-dropbox>  (e.g. dropbox://Papers)", file=sys.stderr)
+        return 2
+    base = os.path.expanduser(os.environ.get("DROPBOX_DIR", "~/Dropbox"))
+    sub = sys.argv[2].lstrip("/")
+    root = os.path.join(base, sub)
+    if not os.path.isdir(root):
+        print(f"not a directory: {root} (set DROPBOX_DIR if your Dropbox lives elsewhere)",
+              file=sys.stderr)
+        return 1
+    total = 0
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if not d.startswith(".") and d not in SKIP_DIRS]
+        for fn in sorted(filenames):
+            if fn.startswith(".") or fn.endswith(".dropbox.attr"):
+                continue
+            p = os.path.join(dirpath, fn)
+            print(json.dumps({"uri": f"dropbox://{os.path.relpath(p, base)}", "path": p},
+                             ensure_ascii=False))
+            total += 1
+    print(f"emitted {total} files under {sub or '/'} (indexer decides what it can read)",
+          file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mediarag/adapters/obsidian

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""MediaRAG source adapter: obsidian://<vault-path> — an Obsidian vault.
+
+Emits {"uri", "path"} items for indexable files under the vault, skipping
+Obsidian's own config/noise (.obsidian, .trash, .DS_Store, hidden dirs, .tmp).
+Vault resolution order for the arg (the part after obsidian://):
+  1. absolute or ~-expanded path as given
+  2. $OBSIDIAN_VAULT + arg
+Env: OBSIDIAN_VAULT (optional default vault). Indexable extensions = the server's.
+"""
+import json
+import os
+import sys
+
+SKIP_DIRS = {".obsidian", ".trash", ".git", ".smart-env", ".DS_Store"}
+SKIP_EXT = {".tmp", ".bak", ".partial"}
+
+
+def main():
+    if len(sys.argv) != 3 or sys.argv[1] != "fetch":
+        print("usage: obsidian fetch <vault-path>  (e.g. obsidian://~/notes/vault)", file=sys.stderr)
+        return 2
+    sub = sys.argv[2]
+    candidates = []
+    if sub.startswith("/"):
+        candidates.append(sub)
+    if sub.startswith("~"):
+        candidates.append(os.path.expanduser(sub))
+    default = os.environ.get("OBSIDIAN_VAULT", "")
+    if default:
+        candidates.append(os.path.join(os.path.expanduser(default), sub.lstrip("/")))
+    root = next((c for c in candidates if os.path.isdir(c)), None)
+    if root is None:
+        print(f"vault not found: tried {candidates} (set OBSIDIAN_VAULT or pass an absolute path)",
+              file=sys.stderr)
+        return 1
+    total = 0
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if not d.startswith(".") and d not in SKIP_DIRS]
+        for fn in sorted(filenames):
+            base, ext = os.path.splitext(fn)
+            if fn.startswith(".") or fn.endswith(".tmp") or ext.lower() in SKIP_EXT:
+                continue
+            p = os.path.join(dirpath, fn)
+            rel = os.path.relpath(p, root)
+            print(json.dumps({"uri": f"obsidian://{rel}", "path": p}, ensure_ascii=False))
+            total += 1
+    print(f"emitted {total} indexable files from vault {root}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mediarag/adapters/pcloud

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""MediaRAG source adapter: pcloud://<path-in-drive> — pCloud assets via the
+rclone FUSE mount (or any local mount point).
+
+Env: PCLOUD_MOUNT (default: "~/pCloud Drive"). Item shape: {"uri", "path"} —
+the indexer decodes/embeds real files itself. Every file is emitted; the indexer
+classifies extensions itself and reports unsupported ones as skips.
+"""
+import json
+import os
+import sys
+
+
+def main():
+    if len(sys.argv) != 3 or sys.argv[1] != "fetch":
+        print("usage: pcloud fetch <path-inside-drive>  (e.g. pcloud://Shared/wiki)", file=sys.stderr)
+        return 2
+    mount = os.environ.get("PCLOUD_MOUNT", "~/pCloud Drive")
+    mount = os.path.expanduser(mount)
+    sub = sys.argv[2]
+    if sub.startswith("/"):  # accept both "Shard/x" and "/Shared/x"
+        sub = sub.lstrip("/")
+    root = os.path.join(mount, sub)
+    if not os.path.isdir(root):
+        print(f"not a directory: {root} (set PCLOUD_MOUNT if your mount differs)", file=sys.stderr)
+        return 1
+    total = 0
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if not d.startswith(".") and d != ".corpus"]
+        for fn in sorted(filenames):
+            if fn.startswith("."):
+                continue
+            p = os.path.join(dirpath, fn)
+            print(json.dumps({"uri": f"pcloud://{os.path.relpath(p, mount)}", "path": p},
+                             ensure_ascii=False))
+            total += 1
+    print(f"emitted {total} indexable files under {sub}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mediarag/adapters/raindrop

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""MediaRAG source adapter: raindrop://bookmarks — Raindrop.io bookmarks as text items.
+
+Env: RAINDROP_API_TOKEN (required). Stdout = one JSON line per bookmark.
+Stdlib only; no dependencies. Community adapters follow this shape.
+"""
+import json
+import os
+import sys
+import urllib.request
+
+
+def resolve_token():
+    return os.environ.get("RAINDROP_API_TOKEN", "").strip()
+
+
+def main():
+    if len(sys.argv) != 3 or sys.argv[1] != "fetch":
+        print("usage: raindrop fetch <what> (e.g. raindrop://bookmarks)", file=sys.stderr)
+        return 2
+    token = resolve_token()
+    if not token:
+        print("set RAINDROP_API_TOKEN in the server environment", file=sys.stderr)
+        return 1
+    total = 0
+    page = -1  # raindrop pagination is 0-indexed; loop pre-increments
+    while True:
+        page += 1
+        url = f"https://api.raindrop.io/rest/v1/raindrops/0?perpage=50&page={page}"
+        req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+        try:
+            resp = json.load(urllib.request.urlopen(req, timeout=30))
+        except Exception as e:
+            print(f"raindrop API page {page} failed: {e}", file=sys.stderr)
+            return 1
+        if resp.get("result") not in (0, True):
+            print(f"raindrop API error on page {page}: {resp.get('error')}", file=sys.stderr)
+            return 1
+        items = resp.get("items") or []
+        for d in items:
+            title = (d.get("title") or "").strip() or "(untitled)"
+            parts = [f"# {title}"]
+            if d.get("excerpt"):
+                parts.append(f"Excerpt: {d['excerpt']}")
+            if d.get("tags"):
+                parts.append("Tags: " + ", ".join(d["tags"]))
+            if d.get("note"):
+                parts.append(f"Note: {d['note']}")
+            if d.get("link"):
+                parts.append(f"URL: {d['link']}")
+            text = "\n\n".join(parts).strip()
+            if not text:
+                continue
+            item = {"uri": f"raindrop://{d['_id']}", "title": title, "text": text}
+            print(json.dumps(item, ensure_ascii=False))
+            total += 1
+        if len(items) < 50:
+            break
+    print(f"emitted {total} bookmarks", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mediarag/adapters/rclone

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""MediaRAG source adapter: rclone://<remote>:<path> — ANY rclone-configured
+backend (Google Drive, OneDrive, S3, WebDAV, Dropbox, SFTP, …) in one adapter.
+
+Mechanism: `rclone copy` the subtree into a persistent local cache, then emit
+{"uri", "path"} items for indexable files (the server's native indexer decodes
+and embeds them itself). The cache is persistent (default ~/.cache/mediarag/
+rclone/<remote>/<path>) so thumbnails and re-indexing keep working afterwards.
+
+Env: RCLONE_ADAPTER_CACHE (default ~/.cache/mediarag/rclone). rclone credentials
+come from the server's rclone environment (config file / env), same as any
+rclone invocation.
+"""
+import json
+import os
+import subprocess
+import sys
+
+SKIP_DIRS = {".obsidian", ".trash", ".git"}
+
+
+def main():
+    if len(sys.argv) != 3 or sys.argv[1] != "fetch":
+        print("usage: rclone fetch \"<remote>:<path>\"  (e.g. rclone://gdrive:/notes)", file=sys.stderr)
+        return 2
+    target = sys.argv[2]
+    if ":" not in target:
+        print('target must be "<remote>:<path>", e.g. "gdrive:/notes"', file=sys.stderr)
+        return 1
+    remote, _, remote_path = target.partition(":")
+    # remote is joined into the cache path below, so it must be a bare remote
+    # name: "x/../../etc:y" would otherwise escape the cache directory.
+    if not remote or remote.startswith(".") or any(c in remote for c in ("/", "\\")):
+        print(f"invalid remote name {remote!r}: expected a bare rclone remote", file=sys.stderr)
+        return 1
+    remote_path = "/" + remote_path.lstrip("/")
+    cache = os.environ.get("RCLONE_ADAPTER_CACHE",
+                           os.path.expanduser("~/.cache/mediarag/rclone"))
+    dest = os.path.join(cache, remote, remote_path.lstrip("/"))
+    os.makedirs(dest, exist_ok=True)
+    # rclone copy: parallel, respects remotes' own config/env; exits non-zero on
+    # partial failure with a summary on stderr.
+    cp = subprocess.run(["rclone", "copy", f"{remote}:{remote_path}", dest,
+                         "--transfers", "8", "--checkers", "8"],
+                        capture_output=True, text=True)
+    for line in cp.stderr.strip().splitlines()[-3:]:
+        print(f"rclone: {line}", file=sys.stderr)
+    if cp.returncode != 0:
+        print(f"rclone copy failed (exit {cp.returncode})", file=sys.stderr)
+        return 1
+    total = 0
+    for dirpath, dirnames, filenames in os.walk(dest):
+        dirnames[:] = [d for d in dirnames if not d.startswith(".") and d not in SKIP_DIRS]
+        for fn in sorted(filenames):
+            if fn.startswith("."):
+                continue
+            p = os.path.join(dirpath, fn)
+            rel = os.path.relpath(p, os.path.join(cache, remote))
+            print(json.dumps({"uri": f"rclone://{remote}/{rel}", "path": p},
+                             ensure_ascii=False))
+            total += 1
+    print(f"emitted {total} indexable files from {remote}:{remote_path} (cache {dest})",
+          file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mediarag/core/engine.py

@@ -0,0 +1,238 @@
+"""MediaRAG plugin engine: EG2 towers via the HF processor + onnxruntime.
+
+Mirrors scripts/export_golden.py exactly (the validated reference stack).
+Parity gate: tests/bench_engine.py — cosine >= 0.999 vs goldens, all towers.
+
+Memory law (live-verified): variable-shape audio/image workloads grow ort
+arenas unbounded with the default memory pattern — every session sets
+enable_mem_pattern=False (12 GB + 27 GB swap observed without it).
+"""
+from __future__ import annotations
+
+import glob
+import os
+import shutil
+import sys
+import wave
+from functools import lru_cache
+
+try:
+    import fcntl
+except ImportError:  # Windows: no flock; materialize is single-process there
+    fcntl = None
+
+import numpy as np
+import onnxruntime as ort
+
+from transformers import EmbeddingGemma2Processor  # noqa: E402
+from PIL import Image  # noqa: E402
+
+QUERY_PREFIX = "task: search result | query: "
+DOC_PREFIX = "title: none | text: "
+REPO = "onnx-community/embeddinggemma-2-ONNX"
+MODEL_FILES = {
+    "trunk": "model_q4.onnx",
+    "vision": "vision_encoder_q4.onnx",
+    "audio": "audio_encoder_q4.onnx",
+}
+
+
+_REAL = os.path.expanduser("~/.cache/mediarag/onnx-real")
+
+
+def _external_escapes(onnx_dir: str) -> bool:
+    """onnxruntime resolves the model symlink, then requires external data
+    inside that directory. huggingface_hub shards blobs into blobs/ab/ vs
+    blobs/cd/, so the data file 'escapes'. A flat blobs/ dir does not.
+    """
+    for name in MODEL_FILES.values():
+        graph = os.path.join(onnx_dir, name)
+        data = graph + "_data"
+        if not (os.path.exists(graph) and os.path.exists(data)):
+            continue
+        gdir = os.path.dirname(os.path.realpath(graph))
+        try:
+            if os.path.commonpath([gdir, os.path.realpath(data)]) != gdir:
+                return True
+        except ValueError:
+            return True
+    return False
+
+
+def _fresh(dst: str, src: str) -> bool:
+    stamp = os.path.join(dst, ".src")
+    if not os.path.isfile(stamp):
+        return False
+    with open(stamp) as f:
+        if f.read() != src:
+            return False
+    for name in MODEL_FILES.values():
+        for fn in (name, name + "_data"):
+            sp = os.path.join(src, fn)
+            dp = os.path.join(dst, fn)
+            if not os.path.lexists(sp):
+                continue
+            if os.path.islink(dp) or not os.path.isfile(dp):
+                return False
+            if os.path.getsize(dp) != os.path.getsize(sp):
+                return False
+    return True
+
+
+def _materialize(src: str, dest: str | None = None) -> str:
+    """Copy the q4 towers to real files beside each other. ~480MB, once per snapshot.
+    ponytail: flock, not a lock manager. A crash mid-copy leaves a .tmp that the
+    next call deletes and rewrites.
+    """
+    dst = dest or _REAL
+    os.makedirs(os.path.dirname(dst), exist_ok=True)
+    fh = open(dst + ".lock", "a")
+    try:
+        if fcntl is not None:
+            fcntl.flock(fh, fcntl.LOCK_EX)
+        if _fresh(dst, src):
+            return dst
+        tmp = dst + ".tmp"
+        shutil.rmtree(tmp, ignore_errors=True)
+        os.makedirs(tmp)
+        for name in MODEL_FILES.values():
+            for fn in (name, name + "_data"):
+                sp = os.path.join(src, fn)
+                if os.path.lexists(sp):
+                    shutil.copyfile(sp, os.path.join(tmp, fn))  # follows the symlink
+        with open(os.path.join(tmp, ".src"), "w") as f:
+            f.write(src)
+        if os.path.isdir(dst):
+            shutil.rmtree(dst)
+        os.rename(tmp, dst)
+        return dst
+    finally:
+        if fcntl is not None:
+            fcntl.flock(fh, fcntl.LOCK_UN)
+        fh.close()
+
+
+def snap_dir() -> str:
+    hits = glob.glob(
+        os.path.expanduser(
+            "~/.cache/huggingface/hub/models--onnx-community--embeddinggemma-2-ONNX/snapshots/*/onnx"
+        )
+    )
+    if not hits:
+        raise RuntimeError(
+            "embedding model not downloaded — snapshot_download "
+            "onnx-community/embeddinggemma-2-ONNX (onnx/*_q4.onnx + *_q4.onnx_data)"
+        )
+    src = sorted(hits)[-1]
+    return _materialize(src) if _external_escapes(src) else src
+
+
+def _sess(model_path: str) -> ort.InferenceSession:
+    so = ort.SessionOptions()
+    so.enable_mem_pattern = False  # memory law
+    so.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+    so.intra_op_num_threads = 4
+    return ort.InferenceSession(model_path, so, providers=["CPUExecutionProvider"])
+
+
+@lru_cache(maxsize=1)
+def _processor():
+    return EmbeddingGemma2Processor.from_pretrained(REPO, local_files_only=True)
+
+
+@lru_cache(maxsize=4)
+def _trunk() -> ort.InferenceSession:
+    return _sess(os.path.join(snap_dir(), MODEL_FILES["trunk"]))
+
+
+@lru_cache(maxsize=2)
+def _vis() -> ort.InferenceSession:
+    return _sess(os.path.join(snap_dir(), MODEL_FILES["vision"]))
+
+
+@lru_cache(maxsize=2)
+def _aud() -> ort.InferenceSession:
+    return _sess(os.path.join(snap_dir(), MODEL_FILES["audio"]))
+
+
+Z = np.zeros((0, 512), np.float32)
+
+
+MAX_TOK = 1024  # ponytail: EG2 trunk is quadratic in sequence length — an unbounded
+# doc chunk (e.g. one 80KB paragraph) OOMs the host; 1024 tokens ≈ 4KB text, plenty for retrieval.
+
+
+def _cap_tokens(feeds: dict) -> dict:
+    """Slice input_ids/attention_mask to MAX_TOK (trust-boundary guard: tool inputs
+    like add_note/adapter text are unbounded; the trunk is not)."""
+    for k in ("input_ids", "attention_mask"):
+        if k in feeds and feeds[k].shape[-1] > MAX_TOK:
+            feeds[k] = feeds[k][..., :MAX_TOK]
+    return feeds
+
+
+def _finish(feeds: dict) -> np.ndarray:
+    v = np.asarray(_trunk().run(None, feeds)[1], dtype=np.float32).reshape(-1)  # [1] = sentence_embedding
+    return v / np.linalg.norm(v)
+
+
+def embed_query(q: str) -> np.ndarray:
+    q = (QUERY_PREFIX + q.strip()).strip()
+    p = _processor()(text=[q], return_tensors="np")
+    return _finish(_cap_tokens({"input_ids": p["input_ids"].astype(np.int64),
+                    "attention_mask": p["attention_mask"].astype(np.int64),
+                    "image_features": Z, "video_features": Z, "audio_features": Z}))
+
+
+def embed_doc(raw: str) -> np.ndarray:
+    raw = (DOC_PREFIX + raw.strip()).strip()
+    if raw == DOC_PREFIX.strip():
+        raise ValueError("empty text chunk")
+    p = _processor()(text=[raw], return_tensors="np")
+    return _finish(_cap_tokens({"input_ids": p["input_ids"].astype(np.int64),
+                    "attention_mask": p["attention_mask"].astype(np.int64),
+                    "image_features": Z, "video_features": Z, "audio_features": Z}))
+
+
+def embed_plain(raw: str) -> np.ndarray:
+    """verbatim text, no prompt template (caption/label lane)."""
+    raw = raw.strip()
+    if not raw:
+        raise ValueError("empty text chunk")
+    p = _processor()(text=[raw], return_tensors="np")
+    return _finish(_cap_tokens({"input_ids": p["input_ids"].astype(np.int64),
+                    "attention_mask": p["attention_mask"].astype(np.int64),
+                    "image_features": Z, "video_features": Z, "audio_features": Z}))
+
+
+def embed_image(path: str) -> np.ndarray:
+    img = Image.open(path).convert("RGB")
+    # ponytail: oversized images blow up the soft-token patch grid → onnxruntime
+    # arena abort (observed: 14 TB single-buffer request kills the process).
+    # Cap at 64 MP (8192^2): EG2 resizes to ≤ 560 px patches anyway — above this
+    # cap the pixels are pure waste. Upgrade path: pre-resize instead of reject.
+    if img.width * img.height > 64_000_000 or img.width > 16_384 or img.height > 16_384:
+        raise ValueError(f"image too large to embed: {img.size}")
+    p = _processor()(images=[img], return_tensors="np")
+    enc = _vis().run(None, {"pixel_values": p["pixel_values"],
+                            "pixel_position_ids": p["image_position_ids"].astype(np.int64)})[0]
+    n = int((p["input_ids"][0] == _processor().image_token_id).sum())
+    assert n == enc.shape[0], f"image token mismatch: {n} != {enc.shape[0]}"
+    return _finish({"input_ids": p["input_ids"].astype(np.int64),
+                    "attention_mask": p["attention_mask"].astype(np.int64),
+                    "image_features": enc.astype(np.float32),
+                    "video_features": Z, "audio_features": Z})
+
+
+def embed_audio(path: str) -> np.ndarray:
+    with wave.open(path, "rb") as w:
+        a = np.frombuffer(w.readframes(w.getnframes()), dtype=np.int16).astype(np.float32) / 32768.0
+    p = _processor()(audio=[a], sampling_rate=16000, return_tensors="np")
+    enc = _aud().run(None, {"input_features": p["input_features"].astype(np.float32),
+                            "input_features_mask": p["input_features_mask"]})[0]
+    n = int((p["input_ids"][0] == _processor().audio_token_id).sum())
+    assert n == enc.shape[0], f"audio token mismatch: {n} != {enc.shape[0]}"
+    return _finish({"input_ids": p["input_ids"].astype(np.int64),
+                    "attention_mask": p["attention_mask"].astype(np.int64),
+                    "image_features": Z, "video_features": Z,
+                    "audio_features": enc.astype(np.float32)})