mediarag 0.1.14__tar.gz

mediarag-0.1.14/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 D Yiapanis
+
+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.

mediarag-0.1.14/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: mediarag
+Version: 0.1.14
+Summary: Multimodal local search over documents and media — pdf, office files, notes, images, audio and subtitles — from any MCP-capable agent.
+Author: D Yiapanis
+License: MIT
+Project-URL: Homepage, https://github.com/dyiapanis/mediarag
+Project-URL: Issues, https://github.com/dyiapanis/mediarag/issues
+Keywords: rag,mcp,search,embeddings,onnx,multimodal
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: onnxruntime==1.29.0
+Requires-Dist: numpy<3,>=2.0
+Requires-Dist: pillow<13,>=11.0
+Requires-Dist: tokenizers<1,>=0.20
+Requires-Dist: transformers==5.19.0
+Requires-Dist: torch<3,>=2.2
+Requires-Dist: torchvision<1,>=0.17
+Requires-Dist: huggingface_hub<3,>=0.26
+Dynamic: license-file
+
+# MediaRAG
+
+![MediaRAG — one semantic index over documents, images and audio](assets/banner.jpg)
+
+Multimodal local semantic search over documents and media, packaged as an
+agent-plugin per the [agent-plugins.org](https://agent-plugins.org/) 1.0
+standard.
+
+It indexes documents (pdf, office files, notes, html) and media (images, audio,
+subtitles) into one local SQLite corpus, and you search both by meaning from any
+MCP-capable agent. Video is not an ingest format: pull the soundtrack out first
+(`ffmpeg -i clip.mp4 -vn -ac 1 -ar 16000 soundtrack.wav`) and index that — the
+audio tower then makes the clip findable by what was said in it. "Which file mentions the
+landing" and "where is the clip where I talked about it" are the same kind of
+question.
+
+How it runs:
+
+- In-gateway: five native tools (`mediarag_search`, `mediarag_add_source`,
+  `mediarag_ingest_dir`, `mediarag_add_note`, `mediarag_status`) register once,
+  so one gateway serves all agents and the embedding model loads once.
+- Cross-client: `mcp.json` declares a stdio MCP server, so Claude Desktop,
+  Cursor, and other Agent Plugins compliant clients load the same package.
+  Per the spec the entry uses a plugin-relative `command`
+  (`./scripts/mcp_launch.py`), never a bare `python3`: portable plugins must not
+  depend on `PATH` or ambient variables for resolution. That launcher is
+  stdlib-only and finds an interpreter that can import the engine
+  (numpy/onnxruntime/transformers/torch, ~500 MB), which Agent Plugins 1.0 has
+  no field to declare — so a client without a provisioned interpreter needs one
+  command, once:
+
+  ```bash
+  python3 -m venv .venv && .venv/bin/python -m pip install -r requirements.txt
+  ```
+
+  Order of preference: `$MEDIARAG_PYTHON`, the package's own `.venv/`, the
+  client's `$PLUGIN_DATA/venv`, then the interpreter that started it. With none
+  present it exits 3 naming what's missing instead of vanishing mid-handshake.
+
+  If `uv` is installed, it can own the environment instead — same
+  `requirements.txt`, resolved and cached by the installer:
+
+  ```bash
+  uv run --with-requirements requirements.txt -- python -c pass   # once
+  ```
+
+  Set `MEDIARAG_AUTO_BOOTSTRAP=1` to have the launcher run that on start. It is
+  off by default: a first run pulls ~1.7 GB, longer than most clients wait.
+- Local-only: no cloud services. The corpus lives at `<root>/.corpus/store.db`.
+
+Documents and media are embedded by the same model into the same vector space
+(see [Embedding model](#embedding-model)), which is why one index answers both
+kinds of question.
+
+## Install
+
+As a Python package (any MCP client, no clone):
+
+```bash
+uvx --from git+https://github.com/dyiapanis/mediarag mediarag-mcp   # runs it
+pipx install git+https://github.com/dyiapanis/mediarag              # or: mediarag-mcp on PATH
+```
+
+As a Hermes plugin (dependencies provisioned by the host):
+
+```bash
+hermes plugins install dyiapanis/mediarag
+```
+
+The engine needs numpy, onnxruntime, transformers and torch (~1.7 GB with the
+model weights); `pipx`/`uvx`/`hermes` install that for you. Running from a bare
+checkout instead, see the MCP section below.
+
+## Features
+
+- Hybrid retrieval: semantic vectors plus an FTS5/BM25 keyword lane, fused with
+  reciprocal rank fusion. Exact-string lookups and meaning searches both work.
+- Documents and media in one index: pdf via `pdftotext`, docx/odt/epub/rst/html/csv/rtf
+  via `pandoc`, plus images, audio, and subtitles.
+- Incremental re-indexing: unchanged files are skipped on an mtime+size
+  fingerprint.
+- Source adapters: external collections through `sources.d` executables (see
+  below).
+
+## Install
+
+Python dependencies: `pip install -r requirements.txt`. The system tools are
+only needed for the lanes that use them: `ffmpeg` for audio, `pandoc` for
+documents, `pdftotext` for pdf.
+
+Runs on Linux and Windows. On Windows those system tools are not preinstalled —
+`winget install Gyan.FFmpeg JohnMacFarlane.Pandoc oschwartz10612.Poppler` (or the
+builds of your choice) and make sure they are on `PATH`. The corpus cache lives
+at `~\.cache\mediarag`; adapters are python scripts and are run through the
+current interpreter there, so they do not need the executable bit or a shebang.
+
+The embedding weights are not downloaded on startup. Once, before first search:
+
+```bash
+python scripts/fetch_model.py
+```
+
+That is about 285MB into the Hugging Face cache; what is in it, and why, is
+covered under [Embedding model](#embedding-model). After the download everything
+runs offline (`HF_HUB_OFFLINE=1`).
+
+## Embedding model
+
+One model embeds everything: [EmbeddingGemma
+2](https://huggingface.co/onnx-community/embeddinggemma-2-ONNX) in its ONNX q4
+build, on onnxruntime, on the CPU. It ships three towers — the text trunk, a
+vision encoder and an audio encoder — and all three write into the same
+768-dimensional space, so a pdf, a photograph and a clip of you talking about
+both are directly comparable.
+
+- **Snapshot** `daa72c51243991dfcaf9f9137d2c573d8f7790c0` of
+  `onnx-community/embeddinggemma-2-ONNX`. `scripts/fetch_model.py` pulls only the
+  q4 towers plus the processor configs, about 285MB, and never at startup. (A
+  cache that has also seen other quantisations of this model will be larger —
+  482MB on the machine this was written on — because those blobs are still there.)
+- **768 dimensions**, L2-normalised, stored as f32 blobs (3,072 bytes per row).
+  Retrieval is exact cosine over the whole corpus; there is no approximate index.
+- **1024-token cap** on the text trunk. Attention is quadratic in sequence
+  length, so tool input is sliced at that boundary rather than trusted.
+- **Chunking**: documents and notes at 1,500 characters, subtitles at 600,
+  audio in 11.2-second windows.
+- If the Hugging Face cache stores the ONNX shards as symlinks, they are
+  materialised once into `~/.cache/mediarag/onnx-real`: onnxruntime will not
+  load external-data blobs out of a sharded cache.
+
+The three embedders are parity-locked against the reference model — 12/12 golden
+vectors at cosine 1.000000 (`tests/fixtures/golden.json`, enforced by
+`tests/test_parity_slices.py`).
+
+## What it touches
+
+No telemetry. It shells out to `curl` (http sources), `ffmpeg`, `pandoc`,
+`pdftotext`, and `rclone` when those lanes are used, and to whatever adapter
+you drop in `sources.d/`. It reads the paths you pass plus the corpus at `root`
+(`mediarag-config.yaml` `root:`, else `MEDIARAG_ROOT`, else `~/.mediarag`). The Raindrop adapter calls
+`api.raindrop.io` with `RAINDROP_API_TOKEN` — optional; inside Hermes the token
+is resolved through the profile secret scope, and a missing scope does not
+inherit another profile's value.
+
+To run it as a Hermes plugin, point the plugin loader at this directory (or at
+the agent plugin catalog entry). The manifests (`mcp.json`, `plugin.yaml`,
+`plugin.json`) describe both the stdio MCP server (`scripts/mcp_server.py`,
+spawned by the client) and the in-gateway native tools. Neither mode opens a
+network listener.
+
+## Configuration
+
+Everything is optional and set through the environment:
+
+- `mediarag-config.yaml` — named corpus config in the plugin dir (`root:` key); wins over env and the default (see `mediarag-config.example.yaml`)
+- `MEDIARAG_ROOT` — corpus root (default: `~/.mediarag`)
+- `MEDIARAG_ALLOW_PRIVATE_URLS=1` — let `add_source` fetch loopback/private-network URLs (standalone; inside Hermes the host's `security.allow_private_urls` applies). Link-local and cloud-metadata addresses are always refused.
+- `RAINDROP_API_TOKEN`, `PCLOUD_MOUNT`, `OBSIDIAN_VAULT` — adapter inputs
+
+## Adapters
+
+`add_source` accepts public `http(s)://` URLs (fetched with curl, capped at 256MB;
+every redirect hop is checked and loopback/private/link-local/metadata hosts are refused)
+and source-scheme URIs (`<scheme>://...`) handled by adapters. Five ship in the
+box:
+
+- `dropbox://` — Dropbox through the desktop client's local folder, or any mirror
+  (`DROPBOX_DIR` env). Skips Dropbox's own `.dropbox/` bookkeeping.
+- `rclone://remote:path` — any [rclone](https://rclone.org/) remote. Files copy
+  into a persistent cache at `~/.cache/mediarag/rclone` and index from there.
+- `pcloud://` — walks a locally mounted pCloud drive (`PCLOUD_MOUNT` env).
+- `obsidian://` — an Obsidian vault; skips `.obsidian/`, `.trash/`, `.git/`.
+- `raindrop://` — Raindrop.io bookmarks through the REST API
+  (`RAINDROP_API_TOKEN` env).
+
+To write your own adapter, drop an executable at `sources.d/<scheme>` under the
+configured corpus root (`mediarag-config.yaml` / `MEDIARAG_ROOT` / `~/.mediarag`; a
+per-call `root` argument never adds adapters) that
+accepts `fetch <rest>` and prints one JSON object per line, either
+`{"uri","title","text"}` or `{"uri","path"}`. `status` reports the adapters it
+found; an unknown scheme fails with the list of what is available.
+
+## Development
+
+Tests are direct-run scripts, not pytest-collectable:
+
+- `python tests/test_contract.py` — tool/store/adapter contracts (no model)
+- `python tests/test_ingest_units.py` — chunking, subtitle timings, store integrity
+- `python tests/test_engine_deref.py` — sharded-cache materialisation (no model)
+- `python tests/test_config_root.py` — corpus-root precedence (no model)
+- `python tests/test_parity_slices.py` — FTS lane, RRF fusion, doc bridge (needs the model)
+
+The fixtures under `tests/fixtures/` are synthetic and deterministic, and nothing
+contacts the network. `tests/bench_engine.py` and `scripts/bench.sh` are the
+local benchmark harness. CI runs the model-free suites on Linux and Windows,
+plus the full parity lane on Linux.
+
+## License
+
+MIT. For security reports, see `SECURITY.md`.
+
+## Acknowledgements
+
+This project was developed with AI assistance using [Hermes Agent](https://github.com/NousResearch/hermes-agent).

mediarag-0.1.14/README.md

@@ -0,0 +1,204 @@
+# MediaRAG
+
+![MediaRAG — one semantic index over documents, images and audio](assets/banner.jpg)
+
+Multimodal local semantic search over documents and media, packaged as an
+agent-plugin per the [agent-plugins.org](https://agent-plugins.org/) 1.0
+standard.
+
+It indexes documents (pdf, office files, notes, html) and media (images, audio,
+subtitles) into one local SQLite corpus, and you search both by meaning from any
+MCP-capable agent. Video is not an ingest format: pull the soundtrack out first
+(`ffmpeg -i clip.mp4 -vn -ac 1 -ar 16000 soundtrack.wav`) and index that — the
+audio tower then makes the clip findable by what was said in it. "Which file mentions the
+landing" and "where is the clip where I talked about it" are the same kind of
+question.
+
+How it runs:
+
+- In-gateway: five native tools (`mediarag_search`, `mediarag_add_source`,
+  `mediarag_ingest_dir`, `mediarag_add_note`, `mediarag_status`) register once,
+  so one gateway serves all agents and the embedding model loads once.
+- Cross-client: `mcp.json` declares a stdio MCP server, so Claude Desktop,
+  Cursor, and other Agent Plugins compliant clients load the same package.
+  Per the spec the entry uses a plugin-relative `command`
+  (`./scripts/mcp_launch.py`), never a bare `python3`: portable plugins must not
+  depend on `PATH` or ambient variables for resolution. That launcher is
+  stdlib-only and finds an interpreter that can import the engine
+  (numpy/onnxruntime/transformers/torch, ~500 MB), which Agent Plugins 1.0 has
+  no field to declare — so a client without a provisioned interpreter needs one
+  command, once:
+
+  ```bash
+  python3 -m venv .venv && .venv/bin/python -m pip install -r requirements.txt
+  ```
+
+  Order of preference: `$MEDIARAG_PYTHON`, the package's own `.venv/`, the
+  client's `$PLUGIN_DATA/venv`, then the interpreter that started it. With none
+  present it exits 3 naming what's missing instead of vanishing mid-handshake.
+
+  If `uv` is installed, it can own the environment instead — same
+  `requirements.txt`, resolved and cached by the installer:
+
+  ```bash
+  uv run --with-requirements requirements.txt -- python -c pass   # once
+  ```
+
+  Set `MEDIARAG_AUTO_BOOTSTRAP=1` to have the launcher run that on start. It is
+  off by default: a first run pulls ~1.7 GB, longer than most clients wait.
+- Local-only: no cloud services. The corpus lives at `<root>/.corpus/store.db`.
+
+Documents and media are embedded by the same model into the same vector space
+(see [Embedding model](#embedding-model)), which is why one index answers both
+kinds of question.
+
+## Install
+
+As a Python package (any MCP client, no clone):
+
+```bash
+uvx --from git+https://github.com/dyiapanis/mediarag mediarag-mcp   # runs it
+pipx install git+https://github.com/dyiapanis/mediarag              # or: mediarag-mcp on PATH
+```
+
+As a Hermes plugin (dependencies provisioned by the host):
+
+```bash
+hermes plugins install dyiapanis/mediarag
+```
+
+The engine needs numpy, onnxruntime, transformers and torch (~1.7 GB with the
+model weights); `pipx`/`uvx`/`hermes` install that for you. Running from a bare
+checkout instead, see the MCP section below.
+
+## Features
+
+- Hybrid retrieval: semantic vectors plus an FTS5/BM25 keyword lane, fused with
+  reciprocal rank fusion. Exact-string lookups and meaning searches both work.
+- Documents and media in one index: pdf via `pdftotext`, docx/odt/epub/rst/html/csv/rtf
+  via `pandoc`, plus images, audio, and subtitles.
+- Incremental re-indexing: unchanged files are skipped on an mtime+size
+  fingerprint.
+- Source adapters: external collections through `sources.d` executables (see
+  below).
+
+## Install
+
+Python dependencies: `pip install -r requirements.txt`. The system tools are
+only needed for the lanes that use them: `ffmpeg` for audio, `pandoc` for
+documents, `pdftotext` for pdf.
+
+Runs on Linux and Windows. On Windows those system tools are not preinstalled —
+`winget install Gyan.FFmpeg JohnMacFarlane.Pandoc oschwartz10612.Poppler` (or the
+builds of your choice) and make sure they are on `PATH`. The corpus cache lives
+at `~\.cache\mediarag`; adapters are python scripts and are run through the
+current interpreter there, so they do not need the executable bit or a shebang.
+
+The embedding weights are not downloaded on startup. Once, before first search:
+
+```bash
+python scripts/fetch_model.py
+```
+
+That is about 285MB into the Hugging Face cache; what is in it, and why, is
+covered under [Embedding model](#embedding-model). After the download everything
+runs offline (`HF_HUB_OFFLINE=1`).
+
+## Embedding model
+
+One model embeds everything: [EmbeddingGemma
+2](https://huggingface.co/onnx-community/embeddinggemma-2-ONNX) in its ONNX q4
+build, on onnxruntime, on the CPU. It ships three towers — the text trunk, a
+vision encoder and an audio encoder — and all three write into the same
+768-dimensional space, so a pdf, a photograph and a clip of you talking about
+both are directly comparable.
+
+- **Snapshot** `daa72c51243991dfcaf9f9137d2c573d8f7790c0` of
+  `onnx-community/embeddinggemma-2-ONNX`. `scripts/fetch_model.py` pulls only the
+  q4 towers plus the processor configs, about 285MB, and never at startup. (A
+  cache that has also seen other quantisations of this model will be larger —
+  482MB on the machine this was written on — because those blobs are still there.)
+- **768 dimensions**, L2-normalised, stored as f32 blobs (3,072 bytes per row).
+  Retrieval is exact cosine over the whole corpus; there is no approximate index.
+- **1024-token cap** on the text trunk. Attention is quadratic in sequence
+  length, so tool input is sliced at that boundary rather than trusted.
+- **Chunking**: documents and notes at 1,500 characters, subtitles at 600,
+  audio in 11.2-second windows.
+- If the Hugging Face cache stores the ONNX shards as symlinks, they are
+  materialised once into `~/.cache/mediarag/onnx-real`: onnxruntime will not
+  load external-data blobs out of a sharded cache.
+
+The three embedders are parity-locked against the reference model — 12/12 golden
+vectors at cosine 1.000000 (`tests/fixtures/golden.json`, enforced by
+`tests/test_parity_slices.py`).
+
+## What it touches
+
+No telemetry. It shells out to `curl` (http sources), `ffmpeg`, `pandoc`,
+`pdftotext`, and `rclone` when those lanes are used, and to whatever adapter
+you drop in `sources.d/`. It reads the paths you pass plus the corpus at `root`
+(`mediarag-config.yaml` `root:`, else `MEDIARAG_ROOT`, else `~/.mediarag`). The Raindrop adapter calls
+`api.raindrop.io` with `RAINDROP_API_TOKEN` — optional; inside Hermes the token
+is resolved through the profile secret scope, and a missing scope does not
+inherit another profile's value.
+
+To run it as a Hermes plugin, point the plugin loader at this directory (or at
+the agent plugin catalog entry). The manifests (`mcp.json`, `plugin.yaml`,
+`plugin.json`) describe both the stdio MCP server (`scripts/mcp_server.py`,
+spawned by the client) and the in-gateway native tools. Neither mode opens a
+network listener.
+
+## Configuration
+
+Everything is optional and set through the environment:
+
+- `mediarag-config.yaml` — named corpus config in the plugin dir (`root:` key); wins over env and the default (see `mediarag-config.example.yaml`)
+- `MEDIARAG_ROOT` — corpus root (default: `~/.mediarag`)
+- `MEDIARAG_ALLOW_PRIVATE_URLS=1` — let `add_source` fetch loopback/private-network URLs (standalone; inside Hermes the host's `security.allow_private_urls` applies). Link-local and cloud-metadata addresses are always refused.
+- `RAINDROP_API_TOKEN`, `PCLOUD_MOUNT`, `OBSIDIAN_VAULT` — adapter inputs
+
+## Adapters
+
+`add_source` accepts public `http(s)://` URLs (fetched with curl, capped at 256MB;
+every redirect hop is checked and loopback/private/link-local/metadata hosts are refused)
+and source-scheme URIs (`<scheme>://...`) handled by adapters. Five ship in the
+box:
+
+- `dropbox://` — Dropbox through the desktop client's local folder, or any mirror
+  (`DROPBOX_DIR` env). Skips Dropbox's own `.dropbox/` bookkeeping.
+- `rclone://remote:path` — any [rclone](https://rclone.org/) remote. Files copy
+  into a persistent cache at `~/.cache/mediarag/rclone` and index from there.
+- `pcloud://` — walks a locally mounted pCloud drive (`PCLOUD_MOUNT` env).
+- `obsidian://` — an Obsidian vault; skips `.obsidian/`, `.trash/`, `.git/`.
+- `raindrop://` — Raindrop.io bookmarks through the REST API
+  (`RAINDROP_API_TOKEN` env).
+
+To write your own adapter, drop an executable at `sources.d/<scheme>` under the
+configured corpus root (`mediarag-config.yaml` / `MEDIARAG_ROOT` / `~/.mediarag`; a
+per-call `root` argument never adds adapters) that
+accepts `fetch <rest>` and prints one JSON object per line, either
+`{"uri","title","text"}` or `{"uri","path"}`. `status` reports the adapters it
+found; an unknown scheme fails with the list of what is available.
+
+## Development
+
+Tests are direct-run scripts, not pytest-collectable:
+
+- `python tests/test_contract.py` — tool/store/adapter contracts (no model)
+- `python tests/test_ingest_units.py` — chunking, subtitle timings, store integrity
+- `python tests/test_engine_deref.py` — sharded-cache materialisation (no model)
+- `python tests/test_config_root.py` — corpus-root precedence (no model)
+- `python tests/test_parity_slices.py` — FTS lane, RRF fusion, doc bridge (needs the model)
+
+The fixtures under `tests/fixtures/` are synthetic and deterministic, and nothing
+contacts the network. `tests/bench_engine.py` and `scripts/bench.sh` are the
+local benchmark harness. CI runs the model-free suites on Linux and Windows,
+plus the full parity lane on Linux.
+
+## License
+
+MIT. For security reports, see `SECURITY.md`.
+
+## Acknowledgements
+
+This project was developed with AI assistance using [Hermes Agent](https://github.com/NousResearch/hermes-agent).

mediarag-0.1.14/__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-0.1.14/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())