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:

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:

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

POST /dms/analysis/run

Manually triggers the daily analysis (analyzes one user and reports if significant).

Analyze Specific User

POST /dms/users/{user_id}/analyze

Analyzes a specific user's interactions and sends a report if significant.

Get Recent Reports

GET /dms/analysis/reports?limit=20

Returns the most recent analysis reports.

Get User-Specific Reports

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:

{
  "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