Metadata-Version: 2.4
Name: aitrendradar
Version: 1.0.0
Summary: AI-powered trend radar that surfaces what matters in tech before everyone else finds out
Author: theihtisham
License: MIT
Project-URL: Repository, https://github.com/your-username/ai-trend-radar
Project-URL: Issues, https://github.com/your-username/ai-trend-radar/issues
Keywords: trends,github,hackernews,devto,ai,monitoring,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: web
Requires-Dist: flask>=3.0.0; extra == "web"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
Dynamic: license-file

# AITrendRadar

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

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Tests](https://img.shields.io/badge/tests-pytest-green.svg)](https://docs.pytest.org/)
[![PyPI version](https://img.shields.io/pypi/v/aitrendradar?style=for-the-badge&logo=pypi&color=3775A9)](https://pypi.org/project/aitrendradar/)

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

```bash
# 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

```bash
# 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)

```bash
# 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

```python
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

```bash
# 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](LICENSE) for details.
