PR #18689: feat(gateway): lastfm plugin for music discovery

• Repository: NousResearch/hermes-agent
• Author: w87x
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/18689

Description (problem / solution / changelog)

What does this PR do?

Added last.fm plugin for music discovery and metadata

Related Issue

(https://github.com/NousResearch/hermes-agent/issues/18687)

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

• plugins/lastfm/__init__.py — registers 5 tools into the lastfm toolset
• plugins/lastfm/client.py — stdlib-only Last.fm API client (urllib, no new dependencies)
• plugins/lastfm/tools.py — handlers and JSON schemas for all 5 tools
• plugins/lastfm/plugin.yaml — plugin manifest
• plugins/lastfm/README.md — setup, usage examples, API coverage table, ToS notes
• hermes_cli/config.py — adds LASTFM_API_KEY to OPTIONAL_ENV_VARS so hermes env prompts for it
• tests/plugins/test_lastfm_plugin.py — 54 unit tests, no real HTTP calls

Tools added:

How to Test

1. Run hermes env, enter a free Last.fm API key (https://www.last.fm/api/account/create)
2. hermes tools | grep lastfm — should list all 5 tools
3. hermes -p 'Find 10 artists similar to Boards of Canada and Aphex Twin using lastfm_discover'
4. hermes -p 'What are the top tracks in the ambient tag on Last.fm?'
5. Unit tests: python3 -m unittest tests.plugins.test_lastfm_plugin -v

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (feat(plugins):)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this feature
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (54 tests)
• I've tested on my platform: macOS 15

Documentation & Housekeeping

• I've updated relevant documentation (plugins/lastfm/README.md)
• I've updated cli-config.yaml.example if I added/changed config keys — N/A (key goes in .env, not config)
• I've updated CONTRIBUTING.md or AGENTS.md — N/A
• I've considered cross-platform impact — stdlib only, no platform-specific code
• I've updated tool descriptions/schemas — schemas are in tools.py, documented in README

Notes

• Zero new runtime dependencies — client.py uses urllib and json only
• Auth follows the same pattern as other tool API keys: hermes env → saved to ~/.hermes/.env → loaded into os.environ at startup
• All responses include _source: "Powered by Last.fm" to satisfy Last.fm API ToS attribution requirement. Free API key is for non-commercial use; commercial deployments should contact [email protected]

Changed files

• cli-config.yaml.example (modified, +42/-0)
• hermes_cli/config.py (modified, +40/-1)
• model_tools.py (modified, +20/-0)
• plugins/lastfm/README.md (added, +137/-0)
• plugins/lastfm/__init__.py (added, +54/-0)
• plugins/lastfm/client.py (added, +164/-0)
• plugins/lastfm/plugin.yaml (added, +16/-0)
• plugins/lastfm/tools.py (added, +795/-0)
• tests/plugins/test_lastfm_plugin.py (added, +671/-0)
• tests/tools/test_agent_profiles.py (added, +528/-0)
• tools/delegate_tool.py (modified, +347/-11)