Initial release: GitHub-style contribution graph for HF users

README.md

@@ -1,12 +1,40 @@
 ---
-title: Hf Contributions Graph
-emoji: 🦀
-colorFrom: gray
-colorTo: red
+title: HF Contributions Graph
+emoji: 📊
+colorFrom: green
+colorTo: green
 sdk: gradio
-sdk_version: 6.3.0
+sdk_version: 4.44.0
 app_file: app.py
 pinned: false
+license: mit
+short_description: GitHub-style contribution calendar for Hugging Face users
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🤗 Hugging Face Contributions Graph
+
+A GitHub-style contribution calendar that visualizes your activity on Hugging Face Hub.
+
+## Features
+
+- **GitHub-style calendar**: Exact replica of GitHub's contribution graph UI
+- **All activity types**: Tracks commits across models, datasets, and spaces
+- **Interactive**: Click any day to see contribution details
+- **Statistics**: Total contributions, streaks, and repo breakdown
+- **Dark/Light themes**: Switch between color schemes
+
+## How it works
+
+This app uses the Hugging Face Hub API to:
+1. Fetch all your public repositories (models, datasets, spaces)
+2. Get commit history for each repository
+3. Aggregate commits by date
+4. Display as a contribution calendar
+
+## Usage
+
+Enter any Hugging Face username and click "Fetch Contributions" to see their activity graph.
+
+## Privacy
+
+Only public repositories are counted. Private repos require authentication.

app.py

@@ -0,0 +1,490 @@
+"""
+Hugging Face Contributions Graph
+
+A GitHub-style contribution calendar for Hugging Face users.
+Shows daily commit activity across models, datasets, and spaces.
+"""
+
+import gradio as gr
+from datetime import datetime, timedelta
+from hf_contributions import fetch_user_contributions, ContributionStats
+from typing import Optional
+import json
+
+# GitHub-style color palette
+COLORS = {
+    "light": {
+        0: "#ebedf0",  # No contributions
+        1: "#9be9a8",  # Level 1 (1-3)
+        2: "#40c463",  # Level 2 (4-6)
+        3: "#30a14e",  # Level 3 (7-9)
+        4: "#216e39",  # Level 4 (10+)
+    },
+    "dark": {
+        0: "#161b22",
+        1: "#0e4429",
+        2: "#006d32",
+        3: "#26a641",
+        4: "#39d353",
+    }
+}
+
+
+def get_contribution_level(count: int) -> int:
+    """Determine the contribution level (0-4) based on count."""
+    if count == 0:
+        return 0
+    elif count <= 3:
+        return 1
+    elif count <= 6:
+        return 2
+    elif count <= 9:
+        return 3
+    else:
+        return 4
+
+
+def generate_calendar_data(contributions: dict[str, int], days: int = 365) -> list[dict]:
+    """Generate calendar data for the past N days."""
+    today = datetime.now().date()
+    start_date = today - timedelta(days=days - 1)
+
+    # Adjust to start from Sunday
+    days_since_sunday = start_date.weekday() + 1
+    if days_since_sunday == 7:
+        days_since_sunday = 0
+    start_date = start_date - timedelta(days=days_since_sunday)
+
+    calendar_data = []
+    current_date = start_date
+
+    while current_date <= today:
+        date_str = current_date.strftime("%Y-%m-%d")
+        count = contributions.get(date_str, 0)
+        level = get_contribution_level(count)
+
+        calendar_data.append({
+            "date": date_str,
+            "count": count,
+            "level": level,
+            "weekday": current_date.weekday(),
+            "month": current_date.month,
+            "day": current_date.day
+        })
+
+        current_date += timedelta(days=1)
+
+    return calendar_data
+
+
+def generate_contribution_graph_html(
+    stats: Optional[ContributionStats],
+    theme: str = "light",
+    username: str = ""
+) -> str:
+    """Generate the HTML/CSS for the GitHub-style contribution graph."""
+
+    if stats is None:
+        return """
+        <div style="text-align: center; padding: 40px; color: #666;">
+            <p>Enter a Hugging Face username to see their contribution graph</p>
+        </div>
+        """
+
+    colors = COLORS[theme]
+    calendar_data = generate_calendar_data(stats.contributions_by_date)
+
+    # Group by weeks
+    weeks = []
+    current_week = []
+
+    for day in calendar_data:
+        if len(current_week) == 7:
+            weeks.append(current_week)
+            current_week = []
+        current_week.append(day)
+
+    if current_week:
+        weeks.append(current_week)
+
+    # Generate month labels
+    months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+              "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+    month_positions = {}
+
+    for week_idx, week in enumerate(weeks):
+        for day in week:
+            if day["day"] <= 7:  # First week of month
+                month_positions[week_idx] = months[day["month"] - 1]
+                break
+
+    # Build HTML
+    squares_html = ""
+    for week_idx, week in enumerate(weeks):
+        for day in week:
+            color = colors[day["level"]]
+            tooltip = f'{day["count"]} contributions on {day["date"]}'
+            squares_html += f'''
+                <div class="day"
+                     data-date="{day["date"]}"
+                     data-count="{day["count"]}"
+                     data-level="{day["level"]}"
+                     style="background-color: {color};"
+                     title="{tooltip}"
+                     onclick="window.selectDay('{day["date"]}', {day["count"]})">
+                </div>
+            '''
+
+    # Month labels HTML
+    months_html = ""
+    last_month_week = -4
+    for week_idx, month_name in sorted(month_positions.items()):
+        if week_idx - last_month_week >= 4:  # At least 4 weeks apart
+            left_pos = week_idx * 15  # 11px square + 4px gap
+            months_html += f'<span style="position: absolute; left: {left_pos}px;">{month_name}</span>'
+            last_month_week = week_idx
+
+    bg_color = "#ffffff" if theme == "light" else "#0d1117"
+    text_color = "#24292f" if theme == "light" else "#c9d1d9"
+    border_color = "#d0d7de" if theme == "light" else "#30363d"
+
+    html = f'''
+    <style>
+        .contribution-graph {{
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+            background: {bg_color};
+            padding: 16px;
+            border-radius: 6px;
+            border: 1px solid {border_color};
+            overflow-x: auto;
+        }}
+
+        .graph-header {{
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 8px;
+            color: {text_color};
+        }}
+
+        .graph-title {{
+            font-size: 16px;
+            font-weight: 600;
+        }}
+
+        .graph-container {{
+            display: flex;
+            gap: 4px;
+        }}
+
+        .days-labels {{
+            display: flex;
+            flex-direction: column;
+            justify-content: space-around;
+            font-size: 10px;
+            color: {text_color};
+            padding-right: 8px;
+            height: 91px;
+        }}
+
+        .days-labels span {{
+            height: 11px;
+            line-height: 11px;
+        }}
+
+        .calendar-wrapper {{
+            position: relative;
+        }}
+
+        .months-row {{
+            position: relative;
+            height: 15px;
+            font-size: 10px;
+            color: {text_color};
+            margin-bottom: 4px;
+        }}
+
+        .calendar {{
+            display: grid;
+            grid-template-rows: repeat(7, 11px);
+            grid-auto-flow: column;
+            grid-auto-columns: 11px;
+            gap: 4px;
+        }}
+
+        .day {{
+            width: 11px;
+            height: 11px;
+            border-radius: 2px;
+            cursor: pointer;
+            transition: transform 0.1s ease;
+        }}
+
+        .day:hover {{
+            transform: scale(1.3);
+            outline: 1px solid {text_color};
+            outline-offset: 1px;
+        }}
+
+        .legend {{
+            display: flex;
+            align-items: center;
+            justify-content: flex-end;
+            gap: 4px;
+            margin-top: 8px;
+            font-size: 11px;
+            color: {text_color};
+        }}
+
+        .legend-item {{
+            width: 11px;
+            height: 11px;
+            border-radius: 2px;
+        }}
+
+        .stats-grid {{
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+            gap: 16px;
+            margin-top: 16px;
+            padding-top: 16px;
+            border-top: 1px solid {border_color};
+        }}
+
+        .stat-card {{
+            text-align: center;
+            padding: 12px;
+            background: {colors[0]};
+            border-radius: 6px;
+        }}
+
+        .stat-value {{
+            font-size: 24px;
+            font-weight: 600;
+            color: {text_color};
+        }}
+
+        .stat-label {{
+            font-size: 12px;
+            color: {text_color};
+            opacity: 0.8;
+        }}
+
+        .selected-day-info {{
+            margin-top: 16px;
+            padding: 12px;
+            background: {colors[0]};
+            border-radius: 6px;
+            display: none;
+            color: {text_color};
+        }}
+
+        .selected-day-info.active {{
+            display: block;
+        }}
+    </style>
+
+    <div class="contribution-graph">
+        <div class="graph-header">
+            <span class="graph-title">{stats.total_commits} contributions in the last year</span>
+        </div>
+
+        <div class="graph-container">
+            <div class="days-labels">
+                <span></span>
+                <span>Mon</span>
+                <span></span>
+                <span>Wed</span>
+                <span></span>
+                <span>Fri</span>
+                <span></span>
+            </div>
+
+            <div class="calendar-wrapper">
+                <div class="months-row">
+                    {months_html}
+                </div>
+                <div class="calendar">
+                    {squares_html}
+                </div>
+            </div>
+        </div>
+
+        <div class="legend">
+            <span>Less</span>
+            <div class="legend-item" style="background-color: {colors[0]};"></div>
+            <div class="legend-item" style="background-color: {colors[1]};"></div>
+            <div class="legend-item" style="background-color: {colors[2]};"></div>
+            <div class="legend-item" style="background-color: {colors[3]};"></div>
+            <div class="legend-item" style="background-color: {colors[4]};"></div>
+            <span>More</span>
+        </div>
+
+        <div class="stats-grid">
+            <div class="stat-card">
+                <div class="stat-value">{stats.total_commits}</div>
+                <div class="stat-label">Total Contributions</div>
+            </div>
+            <div class="stat-card">
+                <div class="stat-value">{stats.models_count}</div>
+                <div class="stat-label">Models</div>
+            </div>
+            <div class="stat-card">
+                <div class="stat-value">{stats.datasets_count}</div>
+                <div class="stat-label">Datasets</div>
+            </div>
+            <div class="stat-card">
+                <div class="stat-value">{stats.spaces_count}</div>
+                <div class="stat-label">Spaces</div>
+            </div>
+            <div class="stat-card">
+                <div class="stat-value">{stats.longest_streak}</div>
+                <div class="stat-label">Longest Streak</div>
+            </div>
+            <div class="stat-card">
+                <div class="stat-value">{stats.current_streak}</div>
+                <div class="stat-label">Current Streak</div>
+            </div>
+        </div>
+
+        <div id="selected-day" class="selected-day-info">
+            <strong id="day-date"></strong>: <span id="day-count"></span> contributions
+        </div>
+    </div>
+
+    <script>
+        window.selectDay = function(date, count) {{
+            const info = document.getElementById('selected-day');
+            const dateEl = document.getElementById('day-date');
+            const countEl = document.getElementById('day-count');
+
+            dateEl.textContent = date;
+            countEl.textContent = count;
+            info.classList.add('active');
+
+            // Highlight selected day
+            document.querySelectorAll('.day').forEach(d => d.style.outline = '');
+            event.target.style.outline = '2px solid #0969da';
+            event.target.style.outlineOffset = '1px';
+        }}
+    </script>
+    '''
+
+    return html
+
+
+# Store the current stats globally for the detail view
+current_stats: Optional[ContributionStats] = None
+
+
+def fetch_and_display(username: str, theme: str) -> tuple[str, str]:
+    """Fetch contributions and generate the display."""
+    global current_stats
+
+    if not username or not username.strip():
+        return (
+            generate_contribution_graph_html(None, theme),
+            "Please enter a username"
+        )
+
+    username = username.strip()
+
+    try:
+        # Fetch the data
+        current_stats = fetch_user_contributions(username)
+
+        # Generate the graph HTML
+        graph_html = generate_contribution_graph_html(current_stats, theme, username)
+
+        # Generate summary
+        summary = f"""
+### {username}'s Hugging Face Activity
+
+- **Total Contributions:** {current_stats.total_commits}
+- **Repositories:** {current_stats.total_repos} ({current_stats.models_count} models, {current_stats.datasets_count} datasets, {current_stats.spaces_count} spaces)
+- **Longest Streak:** {current_stats.longest_streak} days
+- **Current Streak:** {current_stats.current_streak} days
+"""
+        if current_stats.most_active_day:
+            summary += f"- **Most Active Day:** {current_stats.most_active_day} ({current_stats.most_active_count} contributions)"
+
+        return graph_html, summary
+
+    except Exception as e:
+        return (
+            f'<div style="color: red; padding: 20px;">Error: {str(e)}</div>',
+            f"Error fetching data for {username}: {str(e)}"
+        )
+
+
+# Create the Gradio interface
+with gr.Blocks(
+    title="HF Contributions Graph",
+    theme=gr.themes.Soft(),
+    css="""
+        .gradio-container { max-width: 1200px !important; }
+        footer { display: none !important; }
+    """
+) as demo:
+    gr.Markdown("""
+    # 🤗 Hugging Face Contributions Graph
+
+    GitHub-style contribution calendar for Hugging Face users.
+    See your daily activity across models, datasets, and spaces!
+    """)
+
+    with gr.Row():
+        with gr.Column(scale=4):
+            username_input = gr.Textbox(
+                label="Hugging Face Username",
+                placeholder="e.g., huggingface, Qwen, meta-llama",
+                lines=1
+            )
+        with gr.Column(scale=1):
+            theme_dropdown = gr.Dropdown(
+                choices=["light", "dark"],
+                value="light",
+                label="Theme"
+            )
+        with gr.Column(scale=1):
+            fetch_btn = gr.Button("Fetch Contributions", variant="primary")
+
+    graph_output = gr.HTML(
+        value=generate_contribution_graph_html(None, "light"),
+        label="Contribution Graph"
+    )
+
+    summary_output = gr.Markdown(
+        value="Enter a username and click 'Fetch Contributions' to see their activity."
+    )
+
+    # Event handlers
+    fetch_btn.click(
+        fn=fetch_and_display,
+        inputs=[username_input, theme_dropdown],
+        outputs=[graph_output, summary_output]
+    )
+
+    username_input.submit(
+        fn=fetch_and_display,
+        inputs=[username_input, theme_dropdown],
+        outputs=[graph_output, summary_output]
+    )
+
+    theme_dropdown.change(
+        fn=lambda u, t: fetch_and_display(u, t) if u else (generate_contribution_graph_html(None, t), ""),
+        inputs=[username_input, theme_dropdown],
+        outputs=[graph_output, summary_output]
+    )
+
+    gr.Markdown("""
+    ---
+    **How it works:** This app fetches your public repositories (models, datasets, spaces)
+    from the Hugging Face Hub API and counts commits to generate a contribution calendar.
+
+    **Note:** Only public repositories are counted. Private repos require authentication.
+    """)
+
+
+if __name__ == "__main__":
+    demo.launch()

hf_contributions.py

@@ -0,0 +1,204 @@
+"""
+Hugging Face Hub Contributions Fetcher
+
+Fetches contribution data (commits) from a user's models, datasets, and spaces
+using the Hugging Face Hub API.
+"""
+
+from huggingface_hub import HfApi
+from collections import defaultdict
+from datetime import datetime, timedelta
+from typing import Optional
+from dataclasses import dataclass
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ContributionStats:
+    """Statistics about a user's contributions."""
+    total_commits: int
+    total_repos: int
+    models_count: int
+    datasets_count: int
+    spaces_count: int
+    longest_streak: int
+    current_streak: int
+    most_active_day: Optional[str]
+    most_active_count: int
+    contributions_by_date: dict[str, int]
+    contributions_by_repo: dict[str, list[dict]]
+
+
+def get_date_range(days: int = 365) -> list[str]:
+    """Generate a list of date strings for the past N days."""
+    today = datetime.now().date()
+    return [
+        (today - timedelta(days=i)).strftime("%Y-%m-%d")
+        for i in range(days - 1, -1, -1)
+    ]
+
+
+def calculate_streaks(contributions: dict[str, int], days: int = 365) -> tuple[int, int]:
+    """Calculate longest and current contribution streaks."""
+    dates = get_date_range(days)
+
+    longest_streak = 0
+    current_streak = 0
+    temp_streak = 0
+
+    for date in dates:
+        if contributions.get(date, 0) > 0:
+            temp_streak += 1
+            longest_streak = max(longest_streak, temp_streak)
+        else:
+            temp_streak = 0
+
+    # Calculate current streak (from today backwards)
+    for date in reversed(dates):
+        if contributions.get(date, 0) > 0:
+            current_streak += 1
+        else:
+            break
+
+    return longest_streak, current_streak
+
+
+def fetch_user_contributions(
+    username: str,
+    token: Optional[str] = None,
+    days: int = 365,
+    progress_callback=None
+) -> ContributionStats:
+    """
+    Fetch all contributions for a Hugging Face user.
+
+    Args:
+        username: The HF username to fetch contributions for
+        token: Optional HF token for accessing private repos
+        days: Number of days to look back (default 365)
+        progress_callback: Optional callback for progress updates
+
+    Returns:
+        ContributionStats object with all contribution data
+    """
+    api = HfApi(token=token)
+    contributions_by_date = defaultdict(int)
+    contributions_by_repo = defaultdict(list)
+
+    cutoff_date = datetime.now() - timedelta(days=days)
+
+    # Collect all repos
+    repos = []
+
+    def update_progress(message: str):
+        if progress_callback:
+            progress_callback(message)
+        logger.info(message)
+
+    # Fetch models
+    update_progress(f"Fetching models for {username}...")
+    try:
+        models = list(api.list_models(author=username))
+        for model in models:
+            repos.append(("model", model.id))
+    except Exception as e:
+        logger.warning(f"Error fetching models: {e}")
+        models = []
+
+    # Fetch datasets
+    update_progress(f"Fetching datasets for {username}...")
+    try:
+        datasets = list(api.list_datasets(author=username))
+        for dataset in datasets:
+            repos.append(("dataset", dataset.id))
+    except Exception as e:
+        logger.warning(f"Error fetching datasets: {e}")
+        datasets = []
+
+    # Fetch spaces
+    update_progress(f"Fetching spaces for {username}...")
+    try:
+        spaces = list(api.list_spaces(author=username))
+        for space in spaces:
+            repos.append(("space", space.id))
+    except Exception as e:
+        logger.warning(f"Error fetching spaces: {e}")
+        spaces = []
+
+    total_repos = len(repos)
+    update_progress(f"Found {total_repos} repositories. Fetching commits...")
+
+    # Fetch commits for each repo
+    for idx, (repo_type, repo_id) in enumerate(repos):
+        update_progress(f"Processing {idx + 1}/{total_repos}: {repo_id}")
+
+        try:
+            commits = list(api.list_repo_commits(repo_id, repo_type=repo_type))
+
+            for commit in commits:
+                # Handle different date formats
+                if hasattr(commit, 'created_at'):
+                    commit_date = commit.created_at
+                elif hasattr(commit, 'date'):
+                    commit_date = commit.date
+                else:
+                    continue
+
+                # Convert to datetime if string
+                if isinstance(commit_date, str):
+                    try:
+                        commit_date = datetime.fromisoformat(commit_date.replace('Z', '+00:00'))
+                    except:
+                        continue
+
+                # Skip commits older than cutoff
+                if commit_date.replace(tzinfo=None) < cutoff_date:
+                    continue
+
+                date_str = commit_date.strftime("%Y-%m-%d")
+                contributions_by_date[date_str] += 1
+
+                contributions_by_repo[repo_id].append({
+                    "date": date_str,
+                    "message": getattr(commit, 'title', getattr(commit, 'message', 'No message')),
+                    "repo_type": repo_type
+                })
+
+        except Exception as e:
+            logger.warning(f"Error fetching commits for {repo_id}: {e}")
+            continue
+
+    # Calculate statistics
+    total_commits = sum(contributions_by_date.values())
+    longest_streak, current_streak = calculate_streaks(contributions_by_date, days)
+
+    most_active_day = None
+    most_active_count = 0
+    if contributions_by_date:
+        most_active_day = max(contributions_by_date, key=contributions_by_date.get)
+        most_active_count = contributions_by_date[most_active_day]
+
+    return ContributionStats(
+        total_commits=total_commits,
+        total_repos=total_repos,
+        models_count=len(models),
+        datasets_count=len(datasets),
+        spaces_count=len(spaces),
+        longest_streak=longest_streak,
+        current_streak=current_streak,
+        most_active_day=most_active_day,
+        most_active_count=most_active_count,
+        contributions_by_date=dict(contributions_by_date),
+        contributions_by_repo=dict(contributions_by_repo)
+    )
+
+
+if __name__ == "__main__":
+    # Test with a known active user
+    stats = fetch_user_contributions("huggingface")
+    print(f"Total commits: {stats.total_commits}")
+    print(f"Total repos: {stats.total_repos}")
+    print(f"Longest streak: {stats.longest_streak} days")

requirements.txt

@@ -0,0 +1,3 @@
+gradio>=4.0.0
+huggingface_hub>=0.20.0
+pandas>=2.0.0