NewsAgent/SETUP.md

# Quick Setup Guide

Follow these steps to get News Agent running on your Fedora machine.

## 1. System Requirements

```bash
# Update system
sudo dnf update -y

# Install Python 3.11+
sudo dnf install python3.11 python3-pip -y
```

## 2. Install News Agent

```bash
# Navigate to project directory
cd ~/news-agent

# Create virtual environment
python3.11 -m venv .venv

# Activate it
source .venv/bin/activate

# Install dependencies
pip install feedparser httpx openai pydantic pydantic-settings jinja2 premailer python-dotenv pyyaml aiosqlite
```

## 3. Configuration

### Create `.env` file:
```bash
cp .env.example .env
nano .env
```

Add your credentials:
```env
# OpenRouter API Key (required)
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# SMTP Credentials (required)
SMTP_USERNAME=your-email@yourdomain.com
SMTP_PASSWORD=your-smtp-password

# Optional
OPENROUTER_SITE_URL=https://yoursite.com
OPENROUTER_SITE_NAME=YourSiteName
```

Get OpenRouter API key from: https://openrouter.ai/keys

### Update `config.yaml`:
```bash
nano config.yaml
```

Update email settings:
```yaml
email:
  to: "your-email@example.com"  # Where to receive digest
  from: "news-agent@yourdomain.com"  # Sender address
  smtp:
    host: "mail.yourdomain.com"  # Your mail server
    port: 587  # 587 for STARTTLS, 465 for SSL
    use_tls: true  # true for port 587
    use_ssl: false  # true for port 465
```

**Common mail servers:**
- **Your own**: Use your mail server hostname and SMTP credentials
- **Gmail**: `smtp.gmail.com:587` (requires App Password)
- **Outlook**: `smtp.office365.com:587`

## 4. Test Run

```bash
# Make sure virtual environment is activated
source .venv/bin/activate

# Run the agent
python -m src.main
```

**Expected output:**
```
INFO - News Agent starting...
INFO - Database initialized
INFO - Fetching from 15 RSS sources...
INFO - Fetched 127 articles from all sources
INFO - Saved 127 new articles
INFO - Processing 127 new articles with AI...
INFO - Filtering articles by relevance...
INFO - Selected 15 relevant articles
INFO - Generating AI summaries...
INFO - Generating email digest...
INFO - Sending email...
INFO - Daily digest sent successfully with 15 articles!
```

**Check logs:**
```bash
cat data/logs/news-agent.log
```

## 5. Set Up Systemd Timer

```bash
# Create user systemd directory
mkdir -p ~/.config/systemd/user

# Update service file with correct paths
sed "s|/home/%u/news-agent|$HOME/news-agent|g" systemd/news-agent.service > ~/.config/systemd/user/news-agent.service

# Copy timer file
cp systemd/news-agent.timer ~/.config/systemd/user/

# Reload systemd
systemctl --user daemon-reload

# Enable timer
systemctl --user enable news-agent.timer
systemctl --user start news-agent.timer

# Enable lingering (allows service to run when not logged in)
sudo loginctl enable-linger $USER
```

**Verify setup:**
```bash
# Check timer is active
systemctl --user list-timers

# Should show:
# NEXT                         LEFT          LAST PASSED UNIT              ACTIVATES
# Tue 2024-01-27 07:00:00 CET  12h left      -    -      news-agent.timer  news-agent.service
```

## 6. Monitoring

### View logs in real-time:
```bash
journalctl --user -u news-agent.service -f
```

### Check last run:
```bash
systemctl --user status news-agent.service
```

### Manual trigger:
```bash
systemctl --user start news-agent.service
```

### View timer schedule:
```bash
systemctl --user list-timers news-agent.timer
```

## 7. Verification Checklist

- [ ] Python 3.11+ installed
- [ ] Virtual environment created and activated
- [ ] All dependencies installed
- [ ] `.env` file created with OpenRouter API key and SMTP credentials
- [ ] `config.yaml` updated with your mail server settings
- [ ] Test run completed successfully
- [ ] Email received in inbox
- [ ] Systemd timer enabled and scheduled
- [ ] Lingering enabled for user

## Common Issues

### "No module named 'feedparser'"
```bash
source .venv/bin/activate
pip install feedparser httpx openai pydantic pydantic-settings jinja2 premailer python-dotenv pyyaml aiosqlite
```

### "Failed to send email"
Check your SMTP credentials and server settings:
```bash
# Verify .env has SMTP credentials
cat .env | grep SMTP

# Verify config.yaml has correct mail server
grep -A 5 "smtp:" config.yaml

# Check logs for specific error
tail -n 50 data/logs/news-agent.log
```

Common issues:
- Wrong port (587 for TLS, 465 for SSL)
- Missing TLS/SSL setting
- Invalid credentials
- Firewall blocking SMTP port

### "API key not found"
```bash
# Verify .env file exists and has correct format
cat .env

# Should show:
# OPENROUTER_API_KEY=sk-or-v1-...
```

### Timer not running
```bash
# Check timer status
systemctl --user status news-agent.timer

# If inactive:
systemctl --user enable news-agent.timer
systemctl --user start news-agent.timer

# Enable lingering
sudo loginctl enable-linger $USER
```

## Customization

### Change schedule time
Edit `~/.config/systemd/user/news-agent.timer`:
```ini
[Timer]
OnCalendar=08:30  # Run at 8:30 AM instead
```

Then reload:
```bash
systemctl --user daemon-reload
systemctl --user restart news-agent.timer
```

### Add/remove RSS feeds
Edit `config.yaml` under `sources.rss` section.

### Adjust AI filtering
In `config.yaml`:
```yaml
ai:
  filtering:
    min_score: 7.0  # Stricter filtering (default: 6.5)
    max_articles: 10  # Fewer articles (default: 15)
```

### Change AI model
In `config.yaml`:
```yaml
ai:
  model: "anthropic/claude-3.5-haiku"  # Better quality
  # or
  model: "meta-llama/llama-3.1-8b-instruct"  # Cheaper
```

## Next Steps

1. **Wait for first automated run** (tomorrow at 07:00)
2. **Monitor costs** at https://openrouter.ai/activity
3. **Adjust filtering threshold** based on article quality
4. **Add custom RSS feeds** for your specific interests
5. **Set up email forwarding** if not using local mailbox

## Support

- **Logs:** `data/logs/news-agent.log`
- **Database:** `data/articles.db` (SQLite)
- **Service status:** `systemctl --user status news-agent.service`
- **OpenRouter Dashboard:** https://openrouter.ai/activity