miku-discord/readmes/PROFILE_PICTURE_FEATURE.md

# Profile Picture Update Feature

## Overview
Miku can now autonomously update her Discord profile picture by searching for Hatsune Miku artwork on Danbooru and intelligently cropping it for profile use.

## How It Works

### 1. Autonomous Trigger
- Miku's autonomous engine can decide to update her profile picture once per day
- The decision is influenced by:
  - **Time since last update**: Must be at least 24 hours
  - **Current mood**: More likely in creative moods (bubbly, excited, curious, flirty, romantic, silly)
  - **Server activity**: Prefers quiet times (< 5 messages in past hour)
  - **Cooldown**: At least 30 minutes since last autonomous action
  - **Impulsiveness**: Based on current mood's impulsiveness trait

### 2. Image Search
When triggered, Miku searches Danbooru with the following criteria:
- **Tags**: `hatsune_miku solo rating:g,s score:>10`
  - `solo`: Single character for better profile pictures
  - `rating:g,s`: General and Sensitive ratings only (SFW content)
  - `score:>10`: Quality filter to get well-received artwork
- **Mood-based tags**: Additional tags based on current mood
  - `bubbly/happy/excited` → adds "smile happy"
  - `sleepy/asleep` → adds "closed_eyes sleepy"
  - `serious` → adds "serious"
  - `melancholy` → adds "sad"
  - `flirty` → adds "smile wink"
  - `romantic` → adds "heart blush"
  - `shy` → adds "blush embarrassed"
  - `angry/irritated` → adds "angry frown"

### 3. Image Filtering
Posts are filtered for suitability:
- ✅ Must be JPG or PNG format (no videos/GIFs)
- ✅ Minimum 300x300 pixels
- ✅ Aspect ratio between 0.7 and 1.5 (portrait or square)
- ✅ Not used in the last 100 profile updates
- ✅ Must have a valid file URL

### 4. Intelligent Cropping
The selected image is cropped using smart algorithms:

**Portrait Images (taller than wide)**:
- Crops a square from the upper portion (top 60%)
- Centers horizontally
- Starts 10% from top to avoid cutting off the head

**Landscape Images (wider than tall)**:
- Crops a centered square

**Square Images**:
- Uses the full image

The cropped image is then resized to 512x512 pixels (Discord's recommended size) using high-quality LANCZOS resampling.

### 5. Announcement
When successful, Miku announces the change in her autonomous channel with messages like:
- "*updates profile picture* ✨ What do you think? Does it suit me?"
- "I found a new look! *twirls* Do you like it? 💚"
- "*changes profile picture* Felt like switching things up today~ ✨"
- "New profile pic! I thought this one was really cute 💚"
- "*updates avatar* Time for a fresh look! ✨"

## Files Modified/Created

### New Files
1. **`bot/utils/profile_picture_manager.py`**
   - Core functionality for searching, downloading, and cropping images
   - State management to track last update time and used posts
   - Danbooru API integration

### Modified Files
1. **`bot/utils/autonomous_v1_legacy.py`**
   - Added `miku_update_profile_picture_for_server()` function

2. **`bot/utils/autonomous.py`**
   - Added "update_profile" action type to `autonomous_tick_v2()`
   - Imports the new profile picture function

3. **`bot/utils/autonomous_engine.py`**
   - Added `_should_update_profile()` decision method
   - Integrated profile picture update into the decision flow

4. **`bot/commands/actions.py`**
   - Added `update_profile_picture()` function for manual testing

### State File
- **`bot/memory/profile_picture_state.json`**
  - Tracks last update timestamp
  - Stores list of recently used post IDs (last 100)

## Rate Limits

### Discord Limits
- Discord allows ~2 profile picture changes per 10 minutes globally
- **Our implementation**: Maximum 1 change per 24 hours
- This conservative limit prevents any rate limit issues

### Danbooru Limits
- No authentication required for basic searches
- Rate limit: ~1 request per second
- **Our usage**: 1 search request per 24+ hours (well within limits)

## Manual Testing

To manually trigger a profile picture update (for testing):

```python
# In bot code or via command:
from commands.actions import update_profile_picture

# Update with current mood
success = await update_profile_picture()

# Update with specific mood
success = await update_profile_picture(mood="excited")
```

## Dependencies

Already included in `requirements.txt`:
- `aiohttp` - For async HTTP requests to Danbooru
- `Pillow` - For image processing and cropping
- `discord.py` - For updating the bot's avatar

No additional dependencies needed!

## Potential Enhancements

Future improvements could include:
1. **Artist attribution**: Store and display artist information
2. **User voting**: Let server members vote on profile pictures
3. **Seasonal themes**: Special searches for holidays/events
4. **Custom image sources**: Support for other art platforms
5. **Advanced face detection**: Use OpenCV or face_recognition library for better cropping
6. **Vision model validation**: Use MiniCPM-V to verify the crop looks good before applying

## Safety & Ethics

- ✅ Only searches SFW content (general/sensitive ratings)
- ✅ Respects Danbooru's terms of service
- ✅ Conservatively rate-limited to avoid abuse
- ⚠️ Uses publicly available artwork (consider attribution in future)
- ✅ Maintains history to avoid repeating same images

## Testing Checklist

- [ ] Verify profile picture updates successfully
- [ ] Check cropping quality on various image types
- [ ] Confirm mood-based tag selection works
- [ ] Test rate limiting (shouldn't update if < 24 hours)
- [ ] Verify announcement messages appear
- [ ] Check state persistence across bot restarts
- [ ] Confirm Danbooru API responses are handled correctly
- [ ] Test failure cases (network errors, invalid images, etc.)