Metadata-Version: 2.4
Name: hermes-music
Version: 0.1.0
Summary: Music generation plugin for Hermes Agent — Suno AI, MIDI composition, and music library management
Author: buckster123
License-Expression: MIT
Project-URL: Homepage, https://github.com/buckster123/hermes-music-plugin
Project-URL: Repository, https://github.com/buckster123/hermes-music-plugin
Project-URL: Issues, https://github.com/buckster123/hermes-music-plugin/issues
Keywords: hermes,agent,music,suno,midi,ai-music
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: midi
Requires-Dist: midiutil>=1.2; extra == "midi"
Provides-Extra: retry
Requires-Dist: tenacity>=8.0; extra == "retry"
Provides-Extra: all
Requires-Dist: midiutil>=1.2; extra == "all"
Requires-Dist: tenacity>=8.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: responses>=0.23; extra == "dev"
Requires-Dist: midiutil>=1.2; extra == "dev"
Requires-Dist: tenacity>=8.0; extra == "dev"
Dynamic: license-file

# 🎵 Hermes Music Plugin

Music generation plugin for [Hermes Agent](https://github.com/NousResearch/hermes-agent) — powered by Suno AI.

Generate music, compose from MIDI, search & curate your library — all from your agent's toolbox.

## Features

- **AI Music Generation** — Generate songs via Suno AI with style tags, prompts, and model selection (V3.5–V5)
- **MIDI Composition** — Create MIDI files from note names/numbers, then use them as references for AI generation
- **Music Library** — Browse, search, favorite, and track play counts across all generated songs
- **Multi-Agent** — Track which agent created which song with agent_id attribution
- **Async Support** — Generate in blocking mode (wait for result) or async (poll for status)

## Install

```bash
# Basic (Suno generation only)
pip install hermes-music

# With MIDI composition support
pip install hermes-music[midi]

# Everything
pip install hermes-music[all]
```

## Setup

Add your Suno API key to `~/.hermes/.env`:

```
SUNO_API_KEY=your_key_here
```

Get a key at [sunoapi.org](https://sunoapi.org).

The plugin auto-discovers via entry points — no config changes needed. After install, start a new Hermes session and the music tools will be available.

Enable the toolset:
```bash
hermes tools enable music
```

## Tools

| Tool | Description |
|------|-------------|
| `music_generate` | Generate AI music with Suno (blocking or async) |
| `music_status` | Check generation progress |
| `music_result` | Get completed audio file |
| `music_list` | List recent generation tasks |
| `music_favorite` | Toggle favorite on a song |
| `music_library` | Browse library with filters |
| `music_search` | Search by title, prompt, or style |
| `music_play` | Mark played, get file path |
| `midi_create` | Create MIDI from notes (no API key needed) |
| `music_compose` | Generate music from MIDI reference |

## Examples

```
# In a Hermes chat session:
"Generate an ambient electronic track for coding"
"Create a MIDI melody with C4 E4 G4 C5 and compose it into jazz piano"
"Search my music library for ambient tracks"
"Favorite that last track"
```

## Data Storage

All data lives in `~/.hermes/music/`:
```
~/.hermes/music/
├── audio/          # Downloaded MP3 files
├── midi/           # Generated MIDI files
└── tasks.json      # Task state & library metadata
```

## Development

```bash
git clone https://github.com/buckster123/hermes-music-plugin
cd hermes-music-plugin
pip install -e ".[dev]"
pytest
```

## Credits

- Ported from [ApexAurum](https://github.com/buckster123/ApexAurum) music pipeline
- Powered by [Suno AI](https://suno.ai) via [sunoapi.org](https://sunoapi.org)
- Built for [Hermes Agent](https://github.com/NousResearch/hermes-agent) by [Nous Research](https://nousresearch.com)

## License

MIT
