topic-monitor

What this skill does

# Topic Monitor

**Monitor what matters. Get notified when it happens.**

Topic Monitor transforms your assistant from reactive to proactive by continuously monitoring topics you care about and intelligently alerting you only when something truly matters.

## Core Capabilities

1. **Topic Configuration** - Define subjects with custom parameters
2. **Scheduled Monitoring** - Automated searches at configurable intervals
3. **AI Importance Scoring** - Smart filtering: immediate alert vs digest vs ignore
4. **Contextual Summaries** - Not just links—meaningful summaries with context
5. **Weekly Digest** - Low-priority findings compiled into readable reports
6. **Memory Integration** - References your past conversations and interests

## First Run

When you first use Topic Monitor, run the interactive setup wizard:

```bash
python3 scripts/setup.py
```

The wizard will guide you through:

1. **Topics** - What subjects do you want to monitor?
2. **Search queries** - How to search for each topic
3. **Keywords** - What terms indicate relevance
4. **Frequency** - How often to check (hourly/daily/weekly)
5. **Importance threshold** - When to send alerts (low/medium/high)
6. **Weekly digest** - Compile non-urgent findings into a summary

The wizard creates `config.json` with your preferences. You can always edit it later or use `manage_topics.py` to add/remove topics.

**Example session:**
```
🔍 Topic Monitor - Setup Wizard

What topics do you want to monitor?
  > AI Model Releases
  > Security Vulnerabilities
  > 

--- Topic 1/2: AI Model Releases ---
  Search query for 'AI Model Releases' [AI Model Releases news updates]: new AI model release announcement
  Keywords to watch for in 'AI Model Releases'?
  > GPT, Claude, Llama, release

--- Topic 2/2: Security Vulnerabilities ---
  Search query for 'Security Vulnerabilities' [Security Vulnerabilities news updates]: CVE critical vulnerability patch
  Keywords to watch for in 'Security Vulnerabilities'?
  > CVE, vulnerability, critical, patch

How often should I check for updates?
  1. hourly
  2. daily *
  3. weekly

✅ Setup Complete!
```

## Quick Start

Already know what you're doing? Here's the manual approach:

```bash
# Initialize config from template
cp config.example.json config.json

# Add a topic
python3 scripts/manage_topics.py add "Product Updates" \
  --keywords "release,update,patch" \
  --frequency daily \
  --importance medium

# Test monitoring (dry run)
python3 scripts/monitor.py --dry-run

# Set up cron for automatic monitoring
python3 scripts/setup_cron.py
```

## Topic Configuration

Each topic has:

- **name** - Display name (e.g., "AI Model Releases")
- **query** - Search query (e.g., "new AI model release announcement")
- **keywords** - Relevance filters (["GPT", "Claude", "Llama", "release"])
- **frequency** - `hourly`, `daily`, `weekly`
- **importance_threshold** - `high` (alert immediately), `medium` (alert if important), `low` (digest only)
- **channels** - Where to send alerts (["telegram", "discord"])
- **context** - Why you care (for AI contextual summaries)

### Example config.json

```json
{
  "topics": [
    {
      "id": "ai-models",
      "name": "AI Model Releases",
      "query": "new AI model release GPT Claude Llama",
      "keywords": ["GPT", "Claude", "Llama", "release", "announcement"],
      "frequency": "daily",
      "importance_threshold": "high",
      "channels": ["telegram"],
      "context": "Following AI developments for work",
      "alert_on": ["model_release", "major_update"]
    },
    {
      "id": "tech-news",
      "name": "Tech Industry News",
      "query": "technology startup funding acquisition",
      "keywords": ["startup", "funding", "Series A", "acquisition"],
      "frequency": "daily",
      "importance_threshold": "medium",
      "channels": ["telegram"],
      "context": "Staying informed on tech trends",
      "alert_on": ["major_funding", "acquisition"]
    },
    {
      "id": "security-alerts",
      "name": "Security Vulnerabilities",
      "query": "CVE critical vulnerability security patch",
      "keywords": ["CVE", "vulnerability", "security", "patch", "critical"],
      "frequency": "hourly",
      "importance_threshold": "high",
      "channels": ["telegram", "email"],
      "context": "DevOps security monitoring",
      "alert_on": ["critical_cve", "zero_day"]
    }
  ],
  "settings": {
    "digest_day": "sunday",
    "digest_time": "18:00",
    "max_alerts_per_day": 5,
    "deduplication_window_hours": 72,
    "learning_enabled": true
  }
}
```

## Scripts

### manage_topics.py

Manage research topics:

```bash
# Add topic
python3 scripts/manage_topics.py add "Topic Name" \
  --query "search query" \
  --keywords "word1,word2" \
  --frequency daily \
  --importance medium \
  --channels telegram

# List topics
python3 scripts/manage_topics.py list

# Edit topic
python3 scripts/manage_topics.py edit eth-price --frequency hourly

# Remove topic
python3 scripts/manage_topics.py remove eth-price

# Test topic (preview results without saving)
python3 scripts/manage_topics.py test eth-price
```

### monitor.py

Main monitoring script (run via cron):

```bash
# Normal run (alerts + saves state)
python3 scripts/monitor.py

# Dry run (no alerts, shows what would happen)
python3 scripts/monitor.py --dry-run

# Force check specific topic
python3 scripts/monitor.py --topic eth-price

# Verbose logging
python3 scripts/monitor.py --verbose
```

**How it works:**
1. Reads topics due for checking (based on frequency)
2. Searches using web-search-plus or built-in web_search
3. Scores each result with AI importance scorer
4. High-importance → immediate alert
5. Medium-importance → saved for digest
6. Low-importance → ignored
7. Updates state to prevent duplicate alerts

### digest.py

Generate weekly digest:

```bash
# Generate digest for current week
python3 scripts/digest.py

# Generate and send
python3 scripts/digest.py --send

# Preview without sending
python3 scripts/digest.py --preview
```

Output format:
```markdown
# Weekly Research Digest - [Date Range]

## 🔥 Highlights

- **AI Models**: Claude 4.5 released with improved reasoning
- **Security**: Critical CVE patched in popular framework

## 📊 By Topic

### AI Model Releases
- [3 findings this week]

### Security Vulnerabilities
- [1 finding this week]

## 💡 Recommendations

Based on your interests, you might want to monitor:
- "Kubernetes security" (mentioned 3x this week)
```

### setup_cron.py

Configure automated monitoring:

```bash
# Interactive setup
python3 scripts/setup_cron.py

# Auto-setup with defaults
python3 scripts/setup_cron.py --auto

# Remove cron jobs
python3 scripts/setup_cron.py --remove
```

Creates cron entries:
```cron
# Topic Monitor - Hourly topics
0 * * * * cd /path/to/skills/topic-monitor && python3 scripts/monitor.py --frequency hourly

# Topic Monitor - Daily topics  
0 9 * * * cd /path/to/skills/topic-monitor && python3 scripts/monitor.py --frequency daily

# Topic Monitor - Weekly digest
0 18 * * 0 cd /path/to/skills/topic-monitor && python3 scripts/digest.py --send
```

## AI Importance Scoring

The scorer uses multiple signals to decide alert priority:

### Scoring Signals

**HIGH priority (immediate alert):**
- Major breaking news (detected via freshness + keyword density)
- Price changes >10% (for finance topics)
- Product releases matching your exact keywords
- Security vulnerabilities in tools you use
- Direct answers to specific questions you asked

**MEDIUM priority (digest-worthy):**
- Related news but not urgent
- Minor updates to tracked products
- Interesting developments in your topics
- Tutorial/guide releases
- Community discussions with high engagement

**LOW priority (ignore):**
- Duplicate news (already alerted)
- Tangentially related content
- Low-quality sources
- Outdated information
- Spam/promotional content

### Learning Mode

When enabled (`learning_enabled: true`), the system:
1. Tracks which alerts you interact with
2. Adjust