# jeeves

Combined-features IRC bot. Brings together DJ queue management, duck hunting,
recipes, news and weather, quote bank, image rendering, and keyword responses
in a single bot with a shared runtime-configurable settings store.

## Dependencies

- Sopel IRC framework
- Pillow (`pip install Pillow`) - only needed for `!draw`; all other features
  work without it

## Commands

### DJ (anyone / op for controls)
| Command | Description |
|---------|-------------|
| `!dj <url>` | Queue a YouTube URL (shorts, embeds, live not accepted) |
| `!np` | Show currently playing track |
| `!queue` | List up to 4 upcoming tracks |
| `!loop` | Show loop state |
| `!play` | Start or resume playback (op) |
| `!stop` | Pause playback (op) |
| `!skip` | Skip to next track (op) |
| `!remove` | Remove current track from queue (op) |
| `!loop <on\|off>` | Toggle queue looping (op) |
| `!clear` | Clear queue and stop playback (op) |

### Duck hunting (anyone in channel / op for control)
| Command | Description |
|---------|-------------|
| `!bang` | Fire at the current duck |
| `!reload` | Refill ammo (3-second cooldown) |
| `!score` | Top 5 players for this channel |
| `!score clear` | Clear scores for this channel (op/owner) |
| `!hunt` | Show hunt state (includes current spawn/flee times) |
| `!hunt start` | Start the hunt (op/owner) |
| `!hunt stop` | Stop the hunt (op/owner) |

### Recipes (anyone in channel)
| Command | Description |
|---------|-------------|
| `!breakfast [list]` | Random breakfast suggestion, or list all |
| `!lunch [list]` | Random lunch suggestion, or list all |
| `!dinner [list]` | Random dinner suggestion, or list all |
| `!snack [list]` | Random snack suggestion, or list all |
| `!recipe <name>` | Full recipe: name, ingredients, steps |

### News and weather (anyone)
| Command | Description |
|---------|-------------|
| `!weather <city>` | Current weather conditions |
| `!forecast <city>` | 3-day weather forecast |
| `!headlines [global\|mena\|egypt] [count]` | Latest RSS headlines |
| `!news` | Show auto-broadcast state |
| `!news on\|off` | Enable/disable auto-broadcast (op/owner) |

### Quotes (anyone / op for management)
| Command | Description |
|---------|-------------|
| `!quote` | Post a random quote |
| `!quote add <text>` | Add a quote (op/owner) |
| `!quote del <N>` | Delete quote by index (op/owner) |
| `!quote list` | Show total quote count |
| `!quotes` | Show auto-post state |
| `!quotes on\|off` | Enable/disable auto-posting (op/owner) |

### Art (anyone in channel)
| Command | Description |
|---------|-------------|
| `!draw [<lines>] <url>` | Render image as mIRC colour art (lines 4-12) |

### Config (owner / op)
| Command | Description |
|---------|-------------|
| `!set <key> <value>` | Set a config value (in channel: per-channel; in PM: global, owner only) |
| `!config [#channel]` | Show all config values for a channel |

### Admin (owner)
| Command | Description |
|---------|-------------|
| `!join #channel` | Join a channel |
| `!part [#channel]` | Leave a channel |
| `!chans` | List joined channels |
| `!pause` | Pause keyword responses |
| `!resume` | Resume keyword responses |

### Help
| Command | Description |
|---------|-------------|
| `!help` | Topics overview |
| `!help <topic>` | Commands in that topic |
| `!help <cmd>` | Command description |

## Runtime config keys

All keys are set via `!set <key> <value>`. Per-channel keys can be set in a
channel (affecting that channel only) or in PM (setting the global default).
Global-only keys must be set in PM by the owner.

| Key | Default | Scope | Description |
|-----|---------|-------|-------------|
| `dj_track_duration` | 120 | global | Seconds per track before auto-advance |
| `dj_queue_cap` | 50 | global | Max tracks in queue |
| `art_height` | 6 | global | Default lines for `!draw` (4-12) |
| `duck_spawn_min` | 60 | per-channel | Min seconds between duck spawns |
| `duck_spawn_max` | 300 | per-channel | Max seconds between duck spawns |
| `duck_flee_time` | 45 | per-channel | Seconds before duck flees |
| `duck_idle_rounds` | 3 | per-channel | Empty rounds before auto-stop (0=off) |
| `news_interval` | 90 | per-channel | Minutes between news broadcasts |
| `news_count` | 1 | per-channel | Headlines per broadcast cycle |
| `quotes_interval` | 60 | per-channel | Minutes between quote auto-posts |

## Config file keys

| Key | Description |
|-----|-------------|
| `[jeeves] db_path` | Path to main JSON database |
| `[jeeves] duck_db_path` | Path to duck scores SQLite database |
| `[jeeves] recipes_path` | Path to recipes JSON file |
| `[respond] keywords` | Newline-separated trigger words for keyword responses |
| `[respond] responses` | Newline-separated response lines (random choice) |