jupyter-hermes-proxy 0.1.0__tar.gz

jupyter_hermes_proxy-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.whl

jupyter_hermes_proxy-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: jupyter-hermes-proxy
+Version: 0.1.0
+Summary: Jupyter server proxy for Hermes Agent dashboard
+Project-URL: Homepage, https://github.com/dive4dec/jupyter-hermes-proxy
+Project-URL: Bug Tracker, https://github.com/dive4dec/jupyter-hermes-proxy/issues
+Author-email: Chung Chan <chung.chan@cityu.edu.hk>
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: jupyter-server-proxy>=4.0
+Description-Content-Type: text/markdown
+
+# jupyter-hermes-proxy
+
+Launch the [Hermes Agent](https://github.com/nousresearch/hermes-agent) dashboard from JupyterLab as a native launcher entry.
+
+## Features
+
+- One-click launch from the JupyterLab launcher panel with a custom Hermes icon
+- Automatic port management via [jupyter-server-proxy](https://github.com/jupyter-server/jupyter-server-proxy)
+- Works behind reverse proxies (no manual port forwarding needed)
+- **Two modes**: spawn a new dashboard, or connect to an existing one
+- Configurable Hermes executable path via `HERMES_BIN_PATH`
+
+## Installation
+
+```bash
+pip install jupyter-hermes-proxy
+```
+
+Then restart JupyterLab. The "Hermes Dashboard" launcher entry will appear automatically.
+
+## Configuration
+
+### Spawn mode (default)
+
+By default the proxy searches for `hermes` in `PATH` and spawns a new dashboard process when you click the launcher.
+
+Override the binary path:
+
+```bash
+export HERMES_BIN_PATH=/path/to/hermes
+```
+
+### URL mode (connect to existing dashboard)
+
+When Hermes dashboard is already running (e.g. supervised by s6 in Docker), point the proxy at it:
+
+```bash
+export HERMES_DASHBOARD_URL=http://127.0.0.1:9119
+```
+
+In this mode the proxy **does not spawn a new process** — it simply proxies traffic to the existing dashboard. No `hermes` binary on PATH is required.
+
+## Related Packages
+
+- **[jupyter-ai-hermes](https://github.com/dive4dec/jupyter-ai-hermes)** — Hermes Agent as an ACP persona for Jupyter AI chat, with live notebook context injection and MCP tools for cell management.
+
+Both packages share the same `HERMES_BIN_PATH` environment variable convention.
+
+## Development
+
+```bash
+git clone git@github.com:dive4dec/jupyter-hermes-proxy.git
+cd jupyter-hermes-proxy
+pip install -e .
+```
+
+## How It Works
+
+This package registers a server spec under the `jupyter_serverproxy_servers` entry point.
+
+- **Spawn mode**: `jupyter-server-proxy` calls `setup_hermes()` which returns a command that spawns `hermes dashboard` on an ephemeral port and proxies it through the Jupyter server.
+- **URL mode**: `setup_hermes()` returns the pre-existing dashboard URL directly, so jupyter-server-proxy connects to it without spawning anything.
+
+## License
+
+MIT

jupyter_hermes_proxy-0.1.0/README.md

@@ -0,0 +1,66 @@
+# jupyter-hermes-proxy
+
+Launch the [Hermes Agent](https://github.com/nousresearch/hermes-agent) dashboard from JupyterLab as a native launcher entry.
+
+## Features
+
+- One-click launch from the JupyterLab launcher panel with a custom Hermes icon
+- Automatic port management via [jupyter-server-proxy](https://github.com/jupyter-server/jupyter-server-proxy)
+- Works behind reverse proxies (no manual port forwarding needed)
+- **Two modes**: spawn a new dashboard, or connect to an existing one
+- Configurable Hermes executable path via `HERMES_BIN_PATH`
+
+## Installation
+
+```bash
+pip install jupyter-hermes-proxy
+```
+
+Then restart JupyterLab. The "Hermes Dashboard" launcher entry will appear automatically.
+
+## Configuration
+
+### Spawn mode (default)
+
+By default the proxy searches for `hermes` in `PATH` and spawns a new dashboard process when you click the launcher.
+
+Override the binary path:
+
+```bash
+export HERMES_BIN_PATH=/path/to/hermes
+```
+
+### URL mode (connect to existing dashboard)
+
+When Hermes dashboard is already running (e.g. supervised by s6 in Docker), point the proxy at it:
+
+```bash
+export HERMES_DASHBOARD_URL=http://127.0.0.1:9119
+```
+
+In this mode the proxy **does not spawn a new process** — it simply proxies traffic to the existing dashboard. No `hermes` binary on PATH is required.
+
+## Related Packages
+
+- **[jupyter-ai-hermes](https://github.com/dive4dec/jupyter-ai-hermes)** — Hermes Agent as an ACP persona for Jupyter AI chat, with live notebook context injection and MCP tools for cell management.
+
+Both packages share the same `HERMES_BIN_PATH` environment variable convention.
+
+## Development
+
+```bash
+git clone git@github.com:dive4dec/jupyter-hermes-proxy.git
+cd jupyter-hermes-proxy
+pip install -e .
+```
+
+## How It Works
+
+This package registers a server spec under the `jupyter_serverproxy_servers` entry point.
+
+- **Spawn mode**: `jupyter-server-proxy` calls `setup_hermes()` which returns a command that spawns `hermes dashboard` on an ephemeral port and proxies it through the Jupyter server.
+- **URL mode**: `setup_hermes()` returns the pre-existing dashboard URL directly, so jupyter-server-proxy connects to it without spawning anything.
+
+## License
+
+MIT

jupyter_hermes_proxy-0.1.0/jupyter_hermes_proxy/__init__.py

@@ -0,0 +1,75 @@
+"""Jupyter server proxy for Hermes Agent dashboard."""
+
+import os
+import shutil
+from typing import Any, Dict, List, Optional
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+def _find_hermes() -> str:
+    """Locate the ``hermes`` executable, respecting HERMES_BIN_PATH override."""
+    path = os.environ.get("HERMES_BIN_PATH") or shutil.which("hermes")
+    if not path:
+        raise FileNotFoundError(
+            "Cannot find 'hermes' in PATH. "
+            "Install Hermes Agent or set HERMES_BIN_PATH to its full path."
+        )
+    return path
+
+
+def _hermes_cmd(port: int, unix_socket: str) -> List[str]:
+    """Build the command to launch the Hermes dashboard.
+
+    ``jupyter-server-proxy`` substitutes ``{port}`` with an ephemeral port
+    before calling this function, so we use that to tell the dashboard which
+    port to listen on.
+    """
+    hermes_bin = _find_hermes()
+    return [
+        hermes_bin,
+        "dashboard",
+        "--port={port}",
+        "--host=127.0.0.1",
+        "--no-open",
+        "--skip-build",
+    ]
+
+
+def _hermes_url() -> Optional[str]:
+    """Return the pre-existing dashboard URL if HERMES_DASHBOARD_URL is set."""
+    return os.environ.get("HERMES_DASHBOARD_URL")
+
+
+def setup_hermes() -> Dict[str, Any]:
+    """Return a jupyter-server-proxy server spec for the Hermes dashboard.
+
+    When ``HERMES_DASHBOARD_URL`` is set (e.g. ``http://127.0.0.1:9119``),
+    the proxy connects to an existing Hermes dashboard instead of spawning
+    a new process. This is the recommended mode in Docker/s6 deployments
+    where Hermes is already supervised.
+
+    See: https://jupyter-server-proxy.readthedocs.io/
+    """
+    existing_url = _hermes_url()
+
+    if existing_url:
+        return {
+            "url": existing_url,
+            "timeout": 90,
+            "new_browser_tab": True,
+            "launcher_entry": {
+                "title": "Hermes Dashboard",
+                "icon_path": os.path.join(HERE, "icons", "hermes.svg"),
+            },
+        }
+
+    return {
+        "command": _hermes_cmd,
+        "timeout": 90,
+        "new_browser_tab": True,
+        "launcher_entry": {
+            "title": "Hermes Dashboard",
+            "icon_path": os.path.join(HERE, "icons", "hermes.svg"),
+        },
+    }

jupyter_hermes_proxy-0.1.0/jupyter_hermes_proxy/icons/hermes.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <circle cx="32" cy="32" r="30" fill="#6366f1"/>
+  <text x="32" y="42" text-anchor="middle" fill="white" font-size="28" font-family="Arial, sans-serif" font-weight="bold">H</text>
+</svg>

jupyter_hermes_proxy-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jupyter-hermes-proxy"
+version = "0.1.0"
+description = "Jupyter server proxy for Hermes Agent dashboard"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Chung Chan", email = "chung.chan@cityu.edu.hk"},
+]
+requires-python = ">=3.12"
+dependencies = [
+    "jupyter-server-proxy>=4.0",
+]
+
+[project.entry-points."jupyter_serverproxy_servers"]
+hermes = "jupyter_hermes_proxy:setup_hermes"
+
+[project.urls]
+Homepage = "https://github.com/dive4dec/jupyter-hermes-proxy"
+"Bug Tracker" = "https://github.com/dive4dec/jupyter-hermes-proxy/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["jupyter_hermes_proxy"]
+include = ["jupyter_hermes_proxy/icons"]

jupyter_hermes_proxy-0.1.0/tests/test_hermes_lookup.py

@@ -0,0 +1,141 @@
+"""Tests for jupyter-hermes-proxy hermes executable lookup and proxy modes."""
+
+import os
+import sys
+from unittest.mock import patch
+
+import pytest
+
+
+class TestFindHermes:
+    """Test _find_hermes() resolves the hermes binary correctly."""
+
+    def test_env_var_overrides_path(self, monkeypatch):
+        """HERMES_BIN_PATH takes precedence over PATH lookup."""
+        import jupyter_hermes_proxy
+
+        path_bin = "/usr/local/bin/hermes"
+        env_bin = "/opt/data/mamba/envs/main/bin/hermes"
+
+        monkeypatch.setenv("HERMES_BIN_PATH", env_bin)
+        with patch("shutil.which", return_value=path_bin):
+            result = jupyter_hermes_proxy._find_hermes()
+
+        assert result == env_bin
+        assert result != path_bin
+
+    def test_falls_back_to_shutil_which(self, monkeypatch):
+        """shutil.which is used when HERMES_BIN_PATH is not set."""
+        import jupyter_hermes_proxy
+
+        path_bin = "/usr/local/bin/hermes"
+
+        monkeypatch.delenv("HERMES_BIN_PATH", raising=False)
+        with patch("shutil.which", return_value=path_bin):
+            result = jupyter_hermes_proxy._find_hermes()
+
+        assert result == path_bin
+
+    def test_raises_file_not_found_when_missing(self, monkeypatch):
+        """FileNotFoundError is raised when neither env var nor PATH works."""
+        import jupyter_hermes_proxy
+
+        monkeypatch.delenv("HERMES_BIN_PATH", raising=False)
+        with patch("shutil.which", return_value=None):
+            with pytest.raises(FileNotFoundError, match="hermes"):
+                jupyter_hermes_proxy._find_hermes()
+
+    def test_env_var_used_even_when_path_exists(self, monkeypatch):
+        """HERMES_BIN_PATH must override a binary found in PATH."""
+        import jupyter_hermes_proxy
+
+        path_bin = "/usr/local/bin/hermes"
+        env_bin = "/opt/custom/bin/hermes"
+
+        monkeypatch.setenv("HERMES_BIN_PATH", env_bin)
+        with patch("shutil.which", return_value=path_bin):
+            result = jupyter_hermes_proxy._find_hermes()
+
+        assert result == env_bin
+        assert result != path_bin
+
+
+class TestHermesCmd:
+    """Test _hermes_cmd() builds the correct command list."""
+
+    def test_basic_command(self, monkeypatch):
+        """Command includes dashboard flags."""
+        import jupyter_hermes_proxy
+
+        monkeypatch.setattr(jupyter_hermes_proxy, "shutil", __import__("shutil"))
+        with patch("shutil.which", return_value="/usr/bin/hermes"):
+            cmd = jupyter_hermes_proxy._hermes_cmd(8765, "")
+
+        assert cmd[0] == "/usr/bin/hermes"
+        assert "dashboard" in cmd
+        assert "--port={port}" in cmd
+        assert "--host=127.0.0.1" in cmd
+        assert "--no-open" in cmd
+        assert "--skip-build" in cmd
+
+
+class TestSetupHermes:
+    """Test setup_hermes() returns a valid server spec in both modes."""
+
+    def _get_module(self):
+        import jupyter_hermes_proxy
+        return jupyter_hermes_proxy
+
+    # -- Spawn mode (no HERMES_DASHBOARD_URL) --
+
+    def test_spawn_mode_has_command(self, monkeypatch):
+        """Spawn mode contains 'command', not 'url'."""
+        monkeypatch.delenv("HERMES_DASHBOARD_URL", raising=False)
+        with patch("shutil.which", return_value="/usr/bin/hermes"):
+            spec = self._get_module().setup_hermes()
+
+        assert "command" in spec
+        assert "url" not in spec
+
+    def test_spawn_mode_has_timeout_and_launcher(self, monkeypatch):
+        """Spawn spec contains all required keys."""
+        monkeypatch.delenv("HERMES_DASHBOARD_URL", raising=False)
+        with patch("shutil.which", return_value="/usr/bin/hermes"):
+            spec = self._get_module().setup_hermes()
+
+        assert spec["timeout"] == 90
+        assert spec["launcher_entry"]["title"] == "Hermes Dashboard"
+        assert "hermes.svg" in spec["launcher_entry"]["icon_path"]
+
+    # -- URL mode (HERMES_DASHBOARD_URL set) --
+
+    def test_url_mode_has_url_not_command(self, monkeypatch):
+        """URL mode contains 'url', not 'command'."""
+        monkeypatch.setenv("HERMES_DASHBOARD_URL", "http://127.0.0.1:9119")
+        spec = self._get_module().setup_hermes()
+
+        assert "url" in spec
+        assert "command" not in spec
+
+    def test_url_mode_preserves_url_value(self, monkeypatch):
+        """URL mode propagates the env var value directly."""
+        monkeypatch.setenv("HERMES_DASHBOARD_URL", "http://127.0.0.1:9119")
+        spec = self._get_module().setup_hermes()
+
+        assert spec["url"] == "http://127.0.0.1:9119"
+
+    def test_url_mode_has_timeout_and_launcher(self, monkeypatch):
+        """URL spec also contains timeout and launcher entry."""
+        monkeypatch.setenv("HERMES_DASHBOARD_URL", "http://127.0.0.1:9119")
+        spec = self._get_module().setup_hermes()
+
+        assert spec["timeout"] == 90
+        assert spec["launcher_entry"]["title"] == "Hermes Dashboard"
+        assert "hermes.svg" in spec["launcher_entry"]["icon_path"]
+
+    def test_url_mode_ignores_hermes_bin(self, monkeypatch):
+        """URL mode does not need hermes binary on PATH."""
+        monkeypatch.setenv("HERMES_DASHBOARD_URL", "http://127.0.0.1:9119")
+        # No shutil.which mock — should not be called
+        spec = self._get_module().setup_hermes()
+        assert spec["url"] == "http://127.0.0.1:9119"