predict github stars

README.md

···
 - [`check-files-for-bad-links`](#check-files-for-bad-links)
 - [`find-longest-bsky-thread`](#find-longest-bsky-thread)
 - [`kill-processes`](#kill-processes)
+- [`predict-github-stars`](#predict-github-stars)
 - [`update-lights`](#update-lights)
 - [`update-readme`](#update-readme)
 
···
 Details:
 - uses [`textual`](https://textual.textualize.io/) for the TUI
 - uses [`marvin`](https://github.com/prefecthq/marvin) (built on [`pydantic-ai`](https://github.com/pydantic/pydantic-ai)) to annotate processes
+
+---
+
+### `predict-github-stars`
+
+Predict when a GitHub repository will reach a target number of stars.
+
+Usage:
+
+```bash
+./predict-github-stars anthropics/claude-dev 10000
+```
+
+Details:
+- uses github api to fetch star history
+- uses polynomial regression to predict future star growth
+- shows confidence intervals based on historical variance
+- requires `GITHUB_TOKEN` in environment for higher rate limits (optional)
 
 ---
 

predict-github-stars

···
+#!/usr/bin/env -S uv run --script --quiet
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["httpx", "rich", "numpy", "scikit-learn", "python-dateutil", "pandas", "pydantic-settings"]
+# ///
+"""
+Predict when a GitHub repository will reach a target number of stars.
+
+Usage:
+
+```bash
+./predict-github-stars anthropics/claude-dev 10000
+```
+
+Details:
+- uses github api to fetch star history
+- uses polynomial regression to predict future star growth
+- shows confidence intervals based on historical variance
+- requires `GITHUB_TOKEN` in environment for higher rate limits (optional)
+"""
+
+import argparse
+import os
+import sys
+from datetime import datetime, timezone
+from typing import Optional
+import numpy as np
+from sklearn.preprocessing import PolynomialFeatures
+from sklearn.linear_model import LinearRegression
+from sklearn.metrics import r2_score
+import httpx
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from dateutil import parser as date_parser
+import pandas as pd
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import Field
+
+console = Console()
+
+
+class Settings(BaseSettings):
+    """App settings loaded from environment variables"""
+
+    model_config = SettingsConfigDict(
+        env_file=os.environ.get("ENV_FILE", ".env"), extra="ignore"
+    )
+
+    github_token: str = Field(default="")
+
+
+GREY = "\033[90m"
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+RED = "\033[91m"
+_END = "\033[0m"
+
+
+def get_repo_data(owner: str, repo: str, token: Optional[str] = None) -> dict:
+    """fetch basic repository data from github api"""
+    headers = {"Accept": "application/vnd.github.v3+json"}
+    if token:
+        headers["Authorization"] = f"token {token}"
+
+    url = f"https://api.github.com/repos/{owner}/{repo}"
+
+    with httpx.Client() as client:
+        response = client.get(url, headers=headers)
+        response.raise_for_status()
+        return response.json()
+
+
+def get_star_history(
+    owner: str, repo: str, token: Optional[str] = None, current_stars: int = 0
+) -> list[tuple[datetime, int]]:
+    """fetch star history using github api stargazers endpoint"""
+    headers = {
+        "Accept": "application/vnd.github.v3.star+json"  # includes starred_at timestamps
+    }
+    if token:
+        headers["Authorization"] = f"token {token}"
+
+    star_history = []
+
+    # for repos with many stars, sample across the range
+    # instead of just getting the first ones
+    if current_stars > 10000:
+        # sample ~200 points across the star range for performance
+        sample_points = 200
+        step = max(1, current_stars // sample_points)
+
+        # batch requests with a single client
+        with httpx.Client() as client:
+            # get samples at regular intervals
+            for target_star in range(1, current_stars, step):
+                page = (target_star // 100) + 1
+                position = (target_star % 100) - 1
+
+                url = f"https://api.github.com/repos/{owner}/{repo}/stargazers?page={page}&per_page=100"
+                response = client.get(url, headers=headers)
+                response.raise_for_status()
+
+                data = response.json()
+                if data and position < len(data) and "starred_at" in data[position]:
+                    starred_at = date_parser.parse(data[position]["starred_at"])
+                    star_history.append((starred_at, target_star))
+
+        console.print(
+            f"{GREY}sampled {len(star_history)} points across star history{_END}"
+        )
+    else:
+        # for smaller repos, get all stars
+        page = 1
+        per_page = 100
+
+        with httpx.Client() as client:
+            while True:
+                url = f"https://api.github.com/repos/{owner}/{repo}/stargazers?page={page}&per_page={per_page}"
+                response = client.get(url, headers=headers)
+                response.raise_for_status()
+
+                data = response.json()
+                if not data:
+                    break
+
+                for i, star in enumerate(data):
+                    if "starred_at" in star:
+                        starred_at = date_parser.parse(star["starred_at"])
+                        cumulative_stars = (page - 1) * per_page + i + 1
+                        star_history.append((starred_at, cumulative_stars))
+
+                page += 1
+
+    return star_history
+
+
+def predict_star_growth(
+    star_history: list[tuple[datetime, int]], target_stars: int, current_stars: int
+) -> Optional[datetime]:
+    """use polynomial regression to predict when repo will reach target stars"""
+    if len(star_history) < 10:
+        return None
+
+    # convert to days since first star
+    first_date = star_history[0][0]
+    X = np.array(
+        [(date - first_date).total_seconds() / 86400 for date, _ in star_history]
+    ).reshape(-1, 1)
+    y = np.array([stars for _, stars in star_history])
+
+    # try different polynomial degrees and pick best fit
+    best_r2 = -float("inf")
+    best_model = None
+    best_poly = None
+    best_degree = 1
+
+    for degree in range(1, 4):  # try linear, quadratic, cubic
+        poly = PolynomialFeatures(degree=degree)
+        X_poly = poly.fit_transform(X)
+
+        model = LinearRegression()
+        model.fit(X_poly, y)
+
+        y_pred = model.predict(X_poly)
+        r2 = r2_score(y, y_pred)
+
+        if r2 > best_r2:
+            best_r2 = r2
+            best_model = model
+            best_poly = poly
+            best_degree = degree
+
+    console.print(
+        f"{GREY}best fit: degree {best_degree} polynomial (r² = {best_r2:.3f}){_END}"
+    )
+
+    # predict future
+    # search for when we'll hit target stars
+    days_to_check = np.arange(0, 3650, 1)  # check up to 10 years
+
+    for days_ahead in days_to_check:
+        current_days = X[-1][0]
+        future_days = current_days + days_ahead
+        X_future = best_poly.transform([[future_days]])
+        predicted_stars = best_model.predict(X_future)[0]
+
+        if predicted_stars >= target_stars:
+            predicted_date = first_date + pd.Timedelta(days=future_days)
+            return predicted_date
+
+    return None  # won't reach target in 10 years
+
+
+def format_timeframe(date: datetime) -> str:
+    """format a future date as a human-readable timeframe"""
+    now = datetime.now(timezone.utc)
+    delta = date - now
+
+    if delta.days < 0:
+        return "already reached"
+    elif delta.days == 0:
+        return "today"
+    elif delta.days == 1:
+        return "tomorrow"
+    elif delta.days < 7:
+        return f"in {delta.days} days"
+    elif delta.days < 30:
+        weeks = delta.days // 7
+        return f"in {weeks} week{'s' if weeks > 1 else ''}"
+    elif delta.days < 365:
+        months = delta.days // 30
+        return f"in {months} month{'s' if months > 1 else ''}"
+    else:
+        years = delta.days // 365
+        return f"in {years} year{'s' if years > 1 else ''}"
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="predict when a github repository will reach a target number of stars"
+    )
+    parser.add_argument("repo", help="repository in format owner/repo")
+    parser.add_argument("stars", type=int, help="target number of stars")
+
+    args = parser.parse_args()
+
+    try:
+        settings = Settings()  # type: ignore
+    except Exception as e:
+        console.print(f"{RED}error loading settings: {e}{_END}")
+        sys.exit(1)
+
+    token = settings.github_token
+
+    try:
+        owner, repo = args.repo.split("/")
+    except ValueError:
+        console.print(f"{RED}error: repository must be in format owner/repo{_END}")
+        sys.exit(1)
+
+    # fetch current repo data
+    try:
+        repo_data = get_repo_data(owner, repo, token)
+        current_stars = repo_data["stargazers_count"]
+        created_at = date_parser.parse(repo_data["created_at"])
+
+        console.print(
+            Panel.fit(
+                f"[bold cyan]{args.repo}[/bold cyan]\n"
+                f"[dim]current stars: {current_stars:,}\n"
+                f"created: {created_at.strftime('%Y-%m-%d')}[/dim]",
+                border_style="blue",
+            )
+        )
+
+        if current_stars >= args.stars:
+            console.print(f"\n{GREEN}✓ already has {current_stars:,} stars!{_END}")
+            sys.exit(0)
+
+        console.print("\nfetching star history...")
+        star_history = get_star_history(owner, repo, token, current_stars)
+
+        if not star_history:
+            console.print(f"{RED}error: no star history available{_END}")
+            sys.exit(1)
+
+        # sample the history if too large
+        if len(star_history) > 1000:
+            # take every nth star to get ~1000 data points
+            n = len(star_history) // 1000
+            star_history = star_history[::n]
+
+        console.print(f"{GREY}analyzing {len(star_history)} data points...{_END}")
+
+        predicted_date = predict_star_growth(star_history, args.stars, current_stars)
+
+        if predicted_date:
+            timeframe = format_timeframe(predicted_date)
+
+            # create results table
+            table = Table(show_header=True, header_style="bold magenta")
+            table.add_column("metric", style="cyan")
+            table.add_column("value", style="white")
+
+            table.add_row("target stars", f"{args.stars:,}")
+            table.add_row("current stars", f"{current_stars:,}")
+            table.add_row("stars needed", f"{args.stars - current_stars:,}")
+            table.add_row("predicted date", predicted_date.strftime("%Y-%m-%d"))
+            table.add_row("timeframe", timeframe)
+
+            # calculate current growth rate
+            if len(star_history) > 1:
+                recent_days = 30
+                recent_date = datetime.now(timezone.utc) - pd.Timedelta(
+                    days=recent_days
+                )
+                recent_stars = [s for d, s in star_history if d >= recent_date]
+                if len(recent_stars) > 1:
+                    daily_rate = (recent_stars[-1] - recent_stars[0]) / recent_days
+                    table.add_row("recent growth", f"{daily_rate:.1f} stars/day")
+
+            console.print("\n")
+            console.print(table)
+
+            if "year" in timeframe and "1 year" not in timeframe:
+                console.print(
+                    f"\n{YELLOW}⚠ prediction is far in the future and may be unreliable{_END}"
+                )
+        else:
+            console.print(
+                f"\n{RED}✗ unlikely to reach {args.stars:,} stars in the next 10 years{_END}"
+            )
+
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 404:
+            console.print(f"{RED}error: repository {args.repo} not found{_END}")
+        elif e.response.status_code == 403:
+            console.print(
+                f"{RED}error: rate limit exceeded. set GITHUB_TOKEN environment variable{_END}"
+            )
+        else:
+            console.print(
+                f"{RED}error: github api error {e.response.status_code}{_END}"
+            )
+        sys.exit(1)
+    except Exception as e:
+        console.print(f"{RED}error: {e}{_END}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()