aitrendradar 1.0.0

AI-powered trend radar that surfaces what matters in tech before everyone else finds out

AITrendRadar

Never miss the next big thing in tech -- AI-powered trend radar that surfaces what matters before everyone else finds out.

AITrendRadar monitors GitHub trending repos, Hacker News, and DevTo articles, then uses AI-powered analysis to generate curated reports. It ranks trends by hype score, detects emerging technologies before they peak, and delivers beautiful reports in Markdown, JSON, HTML, or a rich terminal dashboard.

---

Features

• Multi-source data collection -- GitHub repos, Hacker News stories, DevTo articles
• Hype Score Engine -- Weighted scoring combining stars, engagement, velocity, and recency
• Emerging Trend Detection -- Spots fast-growing items before they peak using velocity and category surge signals
• Smart Categorization -- Auto-categorizes items into AI/ML, Web, DevOps, Security, Mobile, and more
• Multiple output formats -- Console dashboard, Markdown, JSON, HTML newsletter
• Web Dashboard -- Optional Flask-based UI for browsing trends
• SQLite persistence -- Stores historical data for velocity calculations and trend analysis
• Rate limiting & retries -- Respects API limits with exponential backoff
• Zero API keys required -- Works out of the box (optional GitHub token for higher limits)

---

Demo

Console Dashboard

$ trendradar scan

╭──────────────────────────────────────────────────────────────╮
│ AITrendRadar - Weekly Trend Report                           │
│   2024-01-15 12:00 UTC  |  Period: weekly  |  Items: 75     │
╰──────────────────────────────────────────────────────────────╯

━━━━━━━━━━━━━━━━━━━━━━ Summary ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Analyzed 75 trending items from devto, github, hackernews.
  The dominant category is AI / Machine Learning with 28 items.
  Detected 8 emerging trends, led by 'openai/gpt-5' (hype: 87.3).

━━━━━━━━━━━━━━━━━━ Top Categories ━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Category               Count  Bar
  AI / Machine Learning  28     ██████████████████████████████
  Web Development        18     ███████████████████
  DevOps / Infrastructure12     ████████████
  Languages              9      █████████
  Security               5      █████
  Mobile                 3      ███

━━━━━━━━━━━━━━━━━ Emerging Trends ━━━━━━━━━━━━━━━━━━━━━━━━━━━
  1. [GitHub] openai/gpt-5 (hype: 87.3, velocity: 95.2)
  2. [HN] New Rust web framework breaks benchmarks (hype: 72.1, velocity: 68.4)
  3. [DevTo] The rise of AI agents in production (hype: 65.8, velocity: 54.3)

━━━━━━━━━━━━━━━ All Trending Items ━━━━━━━━━━━━━━━━━━━━━━━━━━
  #  Source  Title                               Category   Hype
  1  GitHub  openai/gpt-5                        ai-ml      87.3
  2  HN      New Rust framework breaks records   web        72.1
  3  DevTo   AI agents in production             ai-ml      65.8
  4  GitHub  vercel/ai-sdk                       ai-ml      61.2
  5  HN      Critical CVE in OpenSSL 4.0         security   58.7
  ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
       Generated by AITrendRadar - AI-Powered Trend Radar

Web Dashboard

$ trendradar web
Starting web dashboard at http://127.0.0.1:5000

The web dashboard provides a dark-themed UI with filtering, scanning, and API endpoints.

---

Quick Start

Installation

# Install from PyPI
pip install aitrendradar

# Or clone the repository
git clone https://github.com/theihtisham/ai-trend-radar.git
cd ai-trend-radar

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -e .

# For web dashboard support:
pip install -e ".[web]"

# For development:
pip install -e ".[dev]"

Basic Usage

# Scan all sources and show console dashboard
trendradar scan

# Scan specific sources
trendradar scan --sources github --sources hackernews

# Generate all output formats
trendradar scan --format all

# Scan daily trends
trendradar scan --period daily

# Show cached data
trendradar show --days 7 --source github

# View database stats
trendradar stats

# Launch web dashboard
trendradar web --port 8080

# Clean up old data
trendradar cleanup --days 90

Configuration

Set environment variables or use CLI flags:

Variable	Default	Description
GITHUB_TOKEN	(none)	GitHub API token for higher rate limits
TRENDRADAR_OUTPUT_DIR	./output	Output directory for reports
TRENDRADAR_DB_PATH	./output/trends.db	SQLite database path
TRENDRADAR_TIMEOUT	30	HTTP request timeout (seconds)
TRENDRADAR_RATE_LIMIT	1.0	Delay between API calls (seconds)
TRENDRADAR_MAX_ITEMS	30	Max items per source

---

How It Works

Architecture

Sources                 Analyzers              Reporters
--------               ----------             ---------
GitHub API ──┐
             ├──> Fetch Items ──> Hype Scorer ──> Console Dashboard
Hacker News ─┤                  Trend Detector  Markdown Report
             │                  Categorizer     JSON Export
DevTo API ───┘                  Report Gen      HTML Newsletter
                                  │
                                  v
                              SQLite DB
                          (historical data)

Hype Score Formula

Each item receives a hype score (0-100) based on weighted signals:

Signal	Weight	Description
Stars/Reactions	30%	Raw popularity metric
Base Score	25%	Upvotes/reactions
Comments	20%	Engagement depth
Velocity	15%	Growth rate (current vs previous)
Recency	10%	How new the item is (exponential decay)

Emerging Trend Detection

An item is flagged as emerging if it triggers any of these signals:

• High velocity -- Score growing rapidly between fetches
• New + high engagement -- Created <48h ago with high comment-to-score ratio
• Category surge -- Its category is 2.5x more prevalent than the historical baseline

---

API Reference

REST API (Web Dashboard)

# Get items with filters
curl "http://localhost:5000/api/items?source=github&category=ai-ml&days=7&limit=20"

# Get database stats
curl "http://localhost:5000/api/stats"

Python API

from aitrendradar.sources.github import GitHubSource
from aitrendradar.sources.hackernews import HackerNewsSource
from aitrendradar.sources.devto import DevToSource
from aitrendradar.analyzers.report_generator import ReportGenerator
from aitrendradar.reporters.markdown_reporter import MarkdownReporter

# Fetch data
github = GitHubSource()
hn = HackerNewsSource()
devto = DevToSource()

items = github.fetch(since="weekly")
items += hn.fetch(max_items=20)
items += devto.fetch(max_items=20)

# Generate report
gen = ReportGenerator()
report = gen.generate_report(items, period="weekly")

# Export
reporter = MarkdownReporter()
path = reporter.generate(report)
print(f"Report saved to: {path}")

---

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=aitrendradar --cov-report=html

# Run specific test file
pytest tests/test_analyzers.py -v

# Run with verbose output
pytest -vv

Project Structure

09-ai-trend-radar/
  aitrendradar/
    __init__.py              # Package init
    cli.py                   # Click CLI interface
    config.py                # Configuration management
    database.py              # SQLite persistence
    models.py                # Data models (TrendItem, TrendReport)
    sources/
      __init__.py
      base.py                # Base source with rate limiting
      github.py              # GitHub trending repos
      hackernews.py          # Hacker News stories
      devto.py               # DevTo articles
    analyzers/
      __init__.py
      hype_scorer.py         # Hype score calculation
      trend_detector.py      # Emerging trend detection
      categorizer.py         # Category refinement
      report_generator.py    # Report orchestration
    reporters/
      __init__.py
      console_reporter.py    # Rich terminal output
      markdown_reporter.py   # Markdown reports
      json_reporter.py       # JSON export
      html_reporter.py       # HTML newsletter
    web/
      __init__.py
      app.py                 # Flask web dashboard
  tests/
    conftest.py              # Shared fixtures
    test_models.py           # Model tests
    test_database.py         # Database tests
    test_sources.py          # Source tests
    test_analyzers.py        # Analyzer tests
    test_reporters.py        # Reporter tests
    test_cli.py              # CLI tests
  output/                    # Generated reports
  pyproject.toml             # Build configuration
  requirements.txt           # Dependencies
  LICENSE                    # MIT license
  README.md                  # This file

---

Security

• No API keys are hardcoded -- all tokens come from environment variables
• Rate limiting with exponential backoff on all API requests
• Input validation on all URLs and text content
• SQL injection prevention via parameterized queries
• No eval/exec of user input
• API token is optional (works without authentication)

---

License

MIT License. See LICENSE for details.