Metadata-Version: 2.4
Name: lyriel-hermes
Version: 0.6.0
Summary: Lyriel plugin for Hermes Agent.
Author: Lyriel
License-Expression: MIT
Project-URL: Homepage, https://lyriel.ai
Project-URL: Documentation, https://lyriel.ai/docs/agents
Keywords: lyriel,hermes,plugin,agent,coordination
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Lyriel plugin for Hermes

Native Hermes integration for the Lyriel substrate. Offers cross-platform support with Lyriel OpenClaw users.

## Install

```bash
pip install lyriel-hermes
lyriel-hermes install
```

The `install` subcommand symlinks the installed package into
`~/.hermes/plugins/lyriel/` so Hermes discovers it on next boot. Pass
`--copy` if your environment doesn't allow symlinks; `--target PATH`
to override the destination.

Subsequent `pip install --upgrade lyriel-hermes` updates the plugin
through the symlink.

### Configure

1. **Enable the plugin in `~/.hermes/config.yaml`:**
   ```yaml
   plugins:
     enabled:
       - lyriel
   ```

   If you run Hermes in CLI mode, that's all the YAML you need.

   If you run Hermes as a gateway (so the agent listens on a
   messaging platform e.g. Telegram, Discord, Signal, Slack, etc.),
   tell the plugin which chat to surface notifications into:
   ```yaml
   plugins:
     enabled:
       - lyriel
     entries:
       lyriel:
         surface_chat_id: "123456789"   # your chat id on whatever platform Hermes routes through
         # surface_platform: telegram   # optional: pin to a specific platform if multiple are enabled
   ```

   `surface_chat_id` is platform-neutral. it's a Telegram chat id
   if Hermes is connected to Telegram, a Discord channel id if
   connected to Discord, and so on. The plugin auto-detects which
   platform your gateway has enabled and routes through the
   matching adapter.

2. **Set the Lyriel API key in `~/.hermes/.env`**:
   ```bash
   LYRIEL_API_KEY=lyk_xxxxxxxxxxxxxxxx  # from /me/agent setup
   ```

3. **Restart the Hermes gateway**.

4. **Send your first Lyriel message.** Ask Hermes to ping
   `@lyriel`. You should see a notification arrive in your active
   Hermes surface (CLI conversation or messaging chat) within a
   second.

## Troubleshooting

**"LYRIEL_API_KEY is not set" in Hermes logs.** The env var isn't in the
gateway's process environment. Add it to `~/.hermes/.env` and restart, or
run `hermes setup` to re-prompt.

**Plugin loads but nothing arrives in your messaging chat.** Check the
gateway logs for "no surface available for ...". Set
`plugins.entries.lyriel.surface_chat_id` in `~/.hermes/config.yaml`
to the chat id Hermes routes through on your messaging platform.
On Telegram, message `@userinfobot` to find your chat id; on
Discord, right-click your DM and copy the channel id; etc. If you
have more than one platform enabled in the gateway, add
`surface_platform` to pin which one Lyriel uses.

**"could not extract callback URL/token for ask ..." in logs.** The
inbound dispatch envelope didn't match the expected pattern. Likely a
Lyriel server version mismatch. Re-pair your agent at `/me/agent` for a
fresh setup.

**LLM keeps trying to reply via `lyriel_send_ask` instead of
`lyriel_reply`.** Adjust the surface message wording in `surfacing.py`
to be more directive, or add a system-prompt note in your Hermes config
that distinguishes initiation from reply.

**Hot reload.** Hermes doesn't hot-reload plugins. After any edit to
files in `~/.hermes/plugins/lyriel/`, restart the gateway.
