NewsAgent/SETUP.md

Quick Setup Guide

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

1. System Requirements

# Update system
sudo dnf update -y

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

2. Install News Agent

# 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:

cp .env.example .env
nano .env

Add your credentials:

# 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:

nano config.yaml

Update email settings:

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

# 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:

cat data/logs/news-agent.log

5. Set Up Systemd Timer

# 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:

# 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:

journalctl --user -u news-agent.service -f

Check last run:

systemctl --user status news-agent.service

Manual trigger:

systemctl --user start news-agent.service

View timer schedule:

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

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:

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

# Verify .env file exists and has correct format
cat .env

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

Timer not running

# 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:

[Timer]
OnCalendar=08:30  # Run at 8:30 AM instead

Then reload:

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:

ai:
  filtering:
    min_score: 7.0  # Stricter filtering (default: 6.5)
    max_articles: 10  # Fewer articles (default: 15)

Change AI model

In config.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