miku-discord/readmes/DM_ANALYSIS_FEATURE.md

# DM Interaction Analysis Feature

## Overview
This feature automatically analyzes user interactions with Miku in DMs and reports significant positive or negative interactions to the bot owner.

## How It Works

1. **Automatic Analysis**: Once every 24 hours (at 2:00 AM), the system analyzes DM conversations from the past 24 hours.

2. **Sentiment Evaluation**: Each user's messages are evaluated for:
   - **Positive behaviors**: Kindness, affection, respect, genuine interest, compliments, supportive messages, love
   - **Negative behaviors**: Rudeness, harassment, inappropriate requests, threats, abuse, disrespect, mean comments

3. **Reporting**: If an interaction is significantly positive (score ≥ 5) or negative (score ≤ -3), Miku will send a report to the bot owner via Discord DM.

4. **One Report Per User Per Day**: Once a user has been reported, they won't be reported again for 24 hours (but their report is still saved).

5. **Persistent Storage**: All analysis reports are saved to `memory/dm_reports/` with filenames like `{user_id}_{timestamp}.json`

## Setup

### Environment Variables
Add your Discord user ID to the environment variables:

```bash
OWNER_USER_ID=your_discord_user_id_here
```

Without this variable, the DM analysis feature will be disabled.

### Docker Environment
If using docker-compose, add to your environment configuration:

```yaml
environment:
  - OWNER_USER_ID=123456789012345678
```

## Report Format

Reports sent to the owner include:
- User information (username, ID, message count)
- Overall sentiment (positive/neutral/negative)
- Sentiment score (-10 to +10)
- Miku's feelings about the interaction (in her own voice)
- Notable moments or quotes
- Key behaviors observed

## API Endpoints

### Manual Analysis Trigger
```bash
POST /dms/analysis/run
```
Manually triggers the daily analysis (analyzes one user and reports if significant).

### Analyze Specific User
```bash
POST /dms/users/{user_id}/analyze
```
Analyzes a specific user's interactions and sends a report if significant.

### Get Recent Reports
```bash
GET /dms/analysis/reports?limit=20
```
Returns the most recent analysis reports.

### Get User-Specific Reports
```bash
GET /dms/analysis/reports/{user_id}?limit=10
```
Returns all analysis reports for a specific user.

## File Structure

```
memory/
├── dm_reports/
│   ├── 123456789_20251030_143022.json    # Individual reports
│   ├── 987654321_20251030_150133.json
│   └── reported_today.json                # Tracks which users have been reported today
└── dms/
    ├── 123456789.json                     # Original DM logs
    └── 987654321.json
```

## Report File Format

Each report JSON file contains:
```json
{
  "user_id": 123456789,
  "username": "SomeUser",
  "overall_sentiment": "positive",
  "sentiment_score": 8,
  "key_behaviors": [
    "Expressed genuine affection",
    "Asked thoughtful questions",
    "Showed appreciation"
  ],
  "your_feelings": "I really enjoyed our conversation! They're so sweet and kind.",
  "notable_moment": "When they said 'You always make my day better'",
  "should_report": true,
  "analyzed_at": "2025-10-30T14:30:22.123456",
  "message_count": 15
}
```

## Scheduled Behavior

- **Daily Analysis**: Runs at 2:00 AM every day
- **Rate Limiting**: Only one user is reported per day to avoid spam
- **Message Threshold**: Users must have at least 3 messages in the last 24 hours to be analyzed

## Privacy & Data Management

- All reports are stored locally and never sent to external services (except to the owner's Discord DM)
- Reports include conversation context but are only accessible to the bot owner
- The bot owner can delete user data at any time using the existing DM management API endpoints
- Reports are kept indefinitely for record-keeping purposes

## Testing

To test the feature manually:
1. Set your `OWNER_USER_ID` environment variable
2. Restart the bot
3. Have a conversation with Miku in DMs (at least 3 messages)
4. Call the analysis endpoint: `POST /dms/users/{your_user_id}/analyze`
5. Check your Discord DMs for the report

## Troubleshooting

**Feature not working?**
- Check that `OWNER_USER_ID` is set correctly
- Look for initialization messages in bot logs: "📊 DM Interaction Analyzer initialized"
- Verify the scheduled task is registered: "⏰ Scheduled daily DM analysis at 2:00 AM"

**Not receiving reports?**
- Ensure users have sent at least 3 messages in the last 24 hours
- Check that interactions are significant enough (score ≥ 5 or ≤ -3)
- Verify you haven't blocked the bot's DMs
- Check the bot logs for error messages

**Want to see all reports?**
- Use the API endpoint: `GET /dms/analysis/reports`
- Or check the `memory/dm_reports/` directory directly