hermes-piper-plugin/README.md

# 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

```python
# 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

```bash
# 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

```bash
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`:

```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.