Organize documentation: Move all .md files to readmes/ directory
This commit is contained in:
147
readmes/DM_ANALYSIS_FEATURE.md
Normal file
147
readmes/DM_ANALYSIS_FEATURE.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user