Metadata-Version: 2.4
Name: hermes-plugin-stagewhisper
Version: 0.2.0
Summary: StageWhisper BYO AI relay plugin for Hermes Agent
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: cryptography>=42

## StageWhisper Hermes Plugin

Hermes plugin that connects to StageWhisper's encrypted reasoning relay. Receives live call reasoning jobs, executes them via your configured LLM provider, and returns results.

### Install

```bash
pip install hermes-plugin-stagewhisper
hermes plugins enable stagewhisper
```

Or for local development, copy `hermes_stagewhisper_plugin/` into `~/.hermes/plugins/stagewhisper/`.

Configure these in your shell or `~/.hermes/.env`:
- `OPENAI_API_KEY` — Your LLM provider API key
- `OPENAI_BASE_URL` — API base URL (default: `https://api.openai.com/v1`)
- `STAGEWHISPER_REASONING_MODEL` — Model override (default: `gpt-4o`)
- `STAGEWHISPER_API_URL` — StageWhisper backend override (normally set by pairing)

### Pair

1. In StageWhisper desktop → Settings → Assistant → Hermes → **Generate Pairing Code**
2. On your Hermes host:

```bash
hermes stagewhisper pair --code <CODE>
```

The plugin exchanges X25519 keys and stores the relay config.

### Verify

```bash
hermes stagewhisper status
```

### BYO mode (end-to-end encrypted reasoning)

When the desktop is in BYO reasoning mode, all analysis prompts are encrypted end-to-end between the desktop and the plugin. The plugin decrypts, runs the prompt through your LLM, encrypts the result, and posts it back.

### Unpair

```bash
hermes stagewhisper unpair
```

### Tools for the LLM

The plugin registers three tools Hermes's LLM can call:
- `stagewhisper_pair(code, label, api_url)` — Pair with StageWhisper desktop
- `stagewhisper_relay(action)` — Start/stop/status/restart the relay
- `stagewhisper_unpair()` — Unpair and clear config

### Architecture

```
Desktop (E2EE) ↔ StageWhisper Backend (blind relay) ↔ Hermes Plugin (this)
                                                          ├── SSE stream consumer
                                                          ├── XChaCha20-Poly1305 crypto
                                                          └── OpenAI-compatible LLM provider
```
