NewsAgent/QUICK_START.md

Quick Start Guide

Get your News Agent running in 5 minutes!

1. Initial Setup

# Navigate to project directory
cd ~/news-agent

# Run setup script
./setup.sh

# This creates config.yaml and .env from templates

2. Configure Credentials

Edit .env file (no quotes needed):

nano .env

OPENROUTER_API_KEY=sk-or-v1-your-actual-key-here
SMTP_USERNAME=your-email@yourdomain.com
SMTP_PASSWORD=your-smtp-password

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

3. Configure Email Settings

nano config.yaml

Update these sections:

email:
  to: "your-email@example.com"
  from: "news-agent@yourdomain.com"
  smtp:
    host: "mail.yourdomain.com"
    port: 587
    use_tls: true

4. Install Dependencies

python3.11 -m venv .venv
source .venv/bin/activate
pip install feedparser httpx openai pydantic pydantic-settings jinja2 premailer python-dotenv pyyaml aiosqlite

5. Test Run

python -m src.main

Expected output:

INFO - News Agent starting...
INFO - Fetching from 14 RSS sources...
INFO - Fetched 152 articles from all sources
INFO - Processing XX new articles with AI...
INFO - Filtering articles by relevance...
INFO - Selected 10 relevant articles
INFO - Generating AI summaries...
INFO - Sending email...
INFO - Email sent successfully to your-email@example.com
INFO - Daily digest sent successfully with 10 articles!

Check your email inbox!

6. Set Up Daily Schedule

# Copy systemd files
mkdir -p ~/.config/systemd/user
cp systemd/news-agent.service ~/.config/systemd/user/
cp systemd/news-agent.timer ~/.config/systemd/user/

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

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

# Check status
systemctl --user list-timers

Done! You'll receive daily digests at 07:00 Europe/Oslo time.

Common Adjustments

Get More Articles

Edit config.yaml:

ai:
  filtering:
    min_score: 5.0  # Lower = more articles (default: 5.5)

Change AI Model

Free (with rate limits):

ai:
  model: "google/gemini-2.0-flash-exp:free"

Recommended (paid, ~$0.05/day):

ai:
  model: "openai/gpt-4o-mini"

Best quality (~$0.10/day):

ai:
  model: "anthropic/claude-3.5-haiku"

Change Schedule Time

Edit ~/.config/systemd/user/news-agent.timer:

[Timer]
OnCalendar=08:30  # Change to your preferred time

Then reload:

systemctl --user daemon-reload
systemctl --user restart news-agent.timer

Troubleshooting

Only 1-2 Articles in Email

Lower the filtering threshold in config.yaml:

ai:
  filtering:
    min_score: 5.0  # Was 5.5 or 6.5

Hit Rate Limit

Switch to paid model (see "Change AI Model" above)

No Email Received

1. Check logs: tail -f data/logs/news-agent.log
2. Test email: python -m src.test_email_simple
3. See SMTP_CONFIG.md for detailed troubleshooting

Model Not Found Error

Update model name in config.yaml - see MODELS.md for current names

Next Steps

• Read TROUBLESHOOTING.md for solutions to common issues
• Read MODELS.md to choose the best AI model for your needs
• Read SMTP_CONFIG.md for email server configuration help
• Customize RSS feeds in config.yaml
• Adjust your interests in config.yaml for better filtering

Cost Estimate

• Free models: $0/month (with rate limits)
• GPT-4o-mini: ~$1.50-3.00/month
• Claude Haiku: ~$3.00-7.50/month

Monitor costs: https://openrouter.ai/activity

Enjoy your daily tech news digests!