Files

gortium cfe9e9c4b9 Convert to pip package

- Moved __init__.py and plugin.yaml into hermes_piper_plugin/ package directory
- Added pyproject.toml with build config and entry point registration
- Updated tests to reference new subdirectory paths
- Updated README with pip-based installation instructions

This converts the plugin from a flat layout (loaded via hermes plugins install)
to a proper pip package with the 'hermes_agent.plugins' entry point.

2026-06-17 12:11:37 -04:00

2.5 KiB

Raw Blame History

Hermes Piper Plugin

Makes Piper TTS the default provider instead of Microsoft Edge TTS.

Zero modifications to the Hermes repo. No fork required. The plugin monkey-patches tools.tts_tool.DEFAULT_PROVIDER at plugin load time.

Why

Piper is local, free, CPU-only — no API key, no cloud dependency
Edge TTS requires internet access and ffmpeg for Telegram voice bubbles
This eliminates the need to maintain a fork just to change the default

How it works

# At plugin load time, this single line runs:
tools.tts_tool.DEFAULT_PROVIDER = "piper"

That's it. DEFAULT_PROVIDER is read at call time, so changing it after import is safe. The plugin also logs the effective default at session start.

Installation

# Install from the internal Hermes package registry
pip install hermes-piper-plugin

# Or install in editable mode for development
git clone https://code.lazyworkhorse.net/gortium/hermes-piper-plugin.git
cd hermes-piper-plugin
pip install -e .

Note: The plugin used to be installed via hermes plugins install from the old flat layout. It is now a proper pip package. The entry point hermes_agent.plugins is registered automatically when you install the package — Hermes discovers it on next startup.

Testing

cd /path/to/hermes-piper-plugin
pip install pytest pyyaml
python -m pytest tests/ -v

Tests cover:

Manifest validation — confirms plugin.yaml structure and required fields
Monkey-patch logic — verifies DEFAULT_PROVIDER is changed to 'piper'
Idempotency — calling _apply_piper_patch() twice is safe
Error handling — import failures and exceptions are caught gracefully
Lifecycle hooks — on_session_start fires without errors
Plugin registration — register() wires tools, hooks, and logging correctly

Config

The plugin changes the default provider. You can still override per session by setting tts.provider in ~/.hermes/config.yaml:

tts:
  provider: elevenlabs      # override per-session
  voice: "Adam"             # ElevenLabs voice

Requires

piper-tts Python package (installed via pip)
Piper voice models (downloaded automatically on first use, ~50MB each)

Safety

If piper-tts is not installed, the TTS tool returns an error asking the user to install it — no silent fallback to Edge
Removing the plugin restores the original Hermes default (Edge)
No data loss risk. No changes to any file in the Hermes repo.

2.5 KiB Raw Blame History