Skip to content

shepsci/kaggle-skill / skills/kaggle

kaggle

Flagged

Unified Kaggle skill. Use when the user explicitly mentions Kaggle, kaggle.com, a Kaggle URL, Kaggle competitions, Kaggle datasets/models/notebooks, Kaggle forums/discussions/writeups, Kaggle benchmarks, hackathons hosted on Kaggle, Kaggle badges, or Kaggle account setup. Do not use for generic ML, GPU/TPU, notebook, dataset, benchmark, or data-science tasks unless the user clearly ties them to Kaggle.

FileKindSize
SKILL.mdskill md10.3 KB
modules/README.mdmarkdown2.3 KB
modules/badges/README.mdmarkdown1.6 KB
modules/badges/references/badge-catalog.mdmarkdown6.6 KB
modules/badges/scripts/badge_registry.pyscript8.5 KB
modules/badges/scripts/badge_tracker.pyscript4.1 KB
modules/badges/scripts/orchestrator.pyscript5.3 KB
modules/badges/scripts/phase_1_instant_api.pyscript24.0 KB
modules/badges/scripts/phase_2_competition.pyscript13.5 KB
modules/badges/scripts/phase_3_pipeline.pyscript11.7 KB
modules/badges/scripts/phase_4_browser.pyscript2.2 KB
modules/badges/scripts/phase_5_streaks.pyscript5.6 KB
modules/badges/scripts/templates/README_dataset.mdmarkdown573 B
modules/badges/scripts/templates/dataset-metadata.jsonconfig871 B
modules/badges/scripts/templates/kernel-metadata.jsonconfig412 B
modules/badges/scripts/templates/model-instance-metadata.jsonconfig253 B
modules/badges/scripts/templates/model-metadata.jsonconfig355 B
modules/badges/scripts/templates/python_notebook.ipynbother1.3 KB
modules/badges/scripts/templates/r_notebook.ipynbother1.1 KB
modules/badges/scripts/templates/submission_titanic.csvother2.8 KB
modules/badges/scripts/templates/utility_script.pyscript802 B
modules/badges/scripts/utils.pyscript3.9 KB
modules/benchmarks/README.mdmarkdown1.2 KB
modules/benchmarks/references/benchmark-endpoints.mdmarkdown1.6 KB
modules/benchmarks/references/benchmarks-cli.mdmarkdown4.4 KB
modules/competitions/README.mdmarkdown5.8 KB
modules/competitions/hackathons/README.mdmarkdown2.9 KB
modules/competitions/hackathons/references/episode-endpoints.mdmarkdown2.2 KB
modules/competitions/hackathons/references/hackathon-endpoints.mdmarkdown4.6 KB
modules/competitions/hackathons/scripts/fetch_writeup.pyexecutablescript10.5 KB
modules/competitions/hackathons/scripts/hackathon_overview.pyexecutablescript1.5 KB
modules/competitions/hackathons/scripts/list_writeups.pyexecutablescript9.9 KB
modules/competitions/references/competition-categories.mdmarkdown2.1 KB
modules/competitions/references/competition-operations.mdmarkdown5.7 KB
modules/competitions/references/competition-overview.mdmarkdown3.9 KB
modules/competitions/references/competition-research.mdmarkdown3.0 KB
modules/competitions/scripts/competition_brief.pyscript5.4 KB
modules/competitions/scripts/competition_details.pyscript8.2 KB
modules/competitions/scripts/competition_download.pyscript5.1 KB
modules/competitions/scripts/competition_episodes.pyscript9.2 KB
modules/competitions/scripts/competition_leaderboard.pyscript12.3 KB
modules/competitions/scripts/competition_ledger.pyscript3.3 KB
modules/competitions/scripts/competition_pages.pyexecutablescript1.7 KB
modules/competitions/scripts/competition_status.pyscript9.0 KB
modules/competitions/scripts/competition_submit.pyscript8.9 KB
modules/competitions/scripts/competition_validate.pyscript14.2 KB
modules/competitions/scripts/competition_watch.pyscript5.9 KB
modules/competitions/scripts/list_competitions.pyscript13.3 KB
modules/datasets/README.mdmarkdown2.1 KB
modules/datasets/references/kagglehub-datasets.mdmarkdown2.6 KB
modules/datasets/scripts/dataset_download.pyscript4.1 KB
modules/datasets/scripts/dataset_publish.pyscript5.5 KB
modules/discussions/README.mdmarkdown2.1 KB
modules/discussions/references/writeups.mdmarkdown5.8 KB
modules/discussions/scripts/forums.pyscript22.0 KB
modules/discussions/scripts/leaderboard_writeups.pyscript24.8 KB
modules/models/README.mdmarkdown2.6 KB
modules/models/references/kagglehub-models.mdmarkdown1.7 KB
modules/models/scripts/model_download.pyscript4.5 KB
modules/models/scripts/model_publish.pyscript8.7 KB
modules/notebooks/README.mdmarkdown2.6 KB
modules/notebooks/scripts/notebook_push.pyscript5.7 KB
modules/notebooks/scripts/notebook_run.pyscript2.8 KB
modules/notebooks/scripts/notebook_wait.pyscript3.7 KB
modules/references/README.mdmarkdown454 B
modules/references/cli-reference.mdmarkdown13.4 KB
modules/references/kaggle-knowledge.mdmarkdown7.6 KB
modules/references/mcp-reference.mdmarkdown18.9 KB
modules/setup/README.mdmarkdown3.0 KB
modules/setup/references/kaggle-setup.mdmarkdown6.7 KB
modules/setup/scripts/check_all_credentials.pyscript5.7 KB
modules/setup/scripts/doctor.pyscript10.2 KB
modules/setup/scripts/save_credentials.pyscript3.9 KB
scripts/kaggle_skill.pyscript11.5 KB
shared/__init__.pyscript0 B
shared/competition.pyscript20.0 KB
shared/credentials.pyscript9.6 KB
shared/hub.pyscript2.9 KB
shared/kaggle_cli.pyscript20.7 KB
shared/ledger.pyscript3.6 KB
shared/mcp_client.pyscript11.6 KB
shared/net.pyscript6.9 KB
shared/notebook.pyscript4.4 KB
shared/preflight.pyscript5.1 KB
shared/safe_extract.pyscript2.7 KB
shared/script.pyscript11.2 KB
shared/text.pyscript10.5 KB
shared/untrusted.pyscript7.6 KB

modules/competitions/scripts/competition_leaderboard.py

View on GitHub
#!/usr/bin/env python3
"""A competition's leaderboard: the top, your row, the medal lines, what moved.

    competition_leaderboard.py rsna-knee-abnormality-detection
    competition_leaderboard.py titanic --top 20 --no-save

Prints the top rows, your team's rank and score with the gap to the leader,
and, when the competition awards medals, the score at each medal line. Each
run saves a snapshot under ./.kaggle-skill/leaderboard/<competition>/ and
compares with the one before, so the second run onwards says what moved.

Needs a credential: an API token or `kaggle auth login`. The public
leaderboard is not the final one: the private leaderboard decides. After the
deadline, --private prints the private one.
"""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

SKILL_ROOT = Path(__file__).resolve().parents[3]
sys.path.insert(0, str(SKILL_ROOT))

from shared import competition, credentials, mcp_client, script, text, untrusted  # noqa: E402

SOURCE = "kaggle-mcp"
TOOL = competition.LEADERBOARD_TOOL
DEFAULT_MAX_ROWS = 2000
MEDALS = ("gold", "silver", "bronze")


def snapshot_dir(slug: str) -> Path:
    return script.state_dir() / "leaderboard" / slug


def latest_snapshot(slug: str, board: str = "public") -> dict | None:
    """The newest saved snapshot of this board, or None."""
    try:
        files = sorted(snapshot_dir(slug).glob("*.json"))
    except OSError:
        return None
    for file in reversed(files):
        try:
            data = json.loads(file.read_text(encoding="utf-8"))
        except (OSError, ValueError):
            continue
        if isinstance(data, dict) and data.get("rows") and data.get("board", "public") == board:
            return data
    return None


def save_snapshot(slug: str, snapshot: dict) -> Path:
    name = snapshot["time"].replace(":", "").replace("-", "") + ".json"
    return script.write_state(snapshot_dir(slug) / name, json.dumps(snapshot, ensure_ascii=False))


def find_team(rows: list[dict], team: str, near_rank: int | None) -> dict | None:
    """Your row. Team names are not unique, so the rank Kaggle reports comes first.

    The row at that rank when its name is yours; else the row with your name
    nearest that rank; else the row at that rank.
    """
    at_rank = rows[near_rank - 1] if near_rank and 0 < near_rank <= len(rows) else None
    if team:
        if at_rank is not None and at_rank["team"] == team:
            return at_rank
        named = [row for row in rows if row["team"] == team]
        if named:
            return min(named, key=lambda row: abs(row["rank"] - (near_rank or row["rank"])))
    return at_rank


def gap(mine: str | None, other: str | None, higher: bool | None) -> float | None:
    """How far ``mine`` is behind ``other``: positive means behind."""
    a, b = competition.score_value(mine), competition.score_value(other)
    if a is None or b is None or higher is None:
        return None
    return (b - a) if higher else (a - b)


def build(
    slug: str, token: str, top: int, max_rows: int, private: bool = False
) -> tuple[dict | None, mcp_client.Result | int]:
    """The snapshot, or None with the failed result (or an exit code)."""
    facts_result = competition.fetch_facts(slug, token)
    if not facts_result.ok or not isinstance(facts_result.data, dict):
        return None, facts_result
    info = competition.facts(slug, facts_result.data)
    deadline = text.parse_time(info.get("deadline"))
    ended = deadline is not None and deadline < text.now_utc()
    if private and not ended:
        return None, script.fail(
            "the private leaderboard is shown only after the deadline", script.EXIT_USAGE
        )
    team_count = int(info.get("team_count") or 0)
    medal_ranks = competition.medal_ranks(team_count) if info["awards_points"] else {}

    wanted = max([top, int(info.get("user_rank") or 0), *medal_ranks.values()])
    rows, more, board_result = competition.fetch_leaderboard(
        slug, token, min(wanted, max_rows), public=not private
    )
    if not board_result.ok:
        return None, board_result

    # The team name is on your own submissions, not on the competition's facts.
    mine_name = ""
    if info["user_has_entered"]:
        own, _ = competition.fetch_submissions(slug, token, limit=1)
        mine_name = own[0]["team_name"] if own else ""
    # After the deadline Kaggle's rank is the private one: on the public board
    # the row at that rank is another team's, so only the name finds yours.
    rank_here = info.get("user_rank") if (private or not ended) else None
    mine = find_team(rows, mine_name, rank_here) if info["user_has_entered"] else None

    higher = competition.higher_is_better(rows)
    lines = {}
    for medal, rank in medal_ranks.items():
        if 0 < rank <= len(rows):
            lines[medal] = {"rank": rank, "score": rows[rank - 1]["score"]}
        elif rank > 0:
            lines[medal] = {"rank": rank, "score": None}
    snapshot = {
        "time": text.now_utc().strftime("%Y-%m-%dT%H:%M:%SZ"),
        "competition": slug,
        "board": "private" if private else "public",
        "ended": ended,
        "title": info["title"],
        "team_count": team_count,
        "higher_is_better": higher,
        "awards_medals": info["awards_points"],
        "user_rank": info.get("user_rank"),
        "mine": mine,
        "medal_lines": lines,
        "rows": rows,
        "more_rows": more,
    }
    return snapshot, board_result


def movement(before: dict, now: dict) -> list[str]:
    """What changed between two snapshots, as short phrases."""
    changes = []
    old_mine, new_mine = before.get("mine") or {}, now.get("mine") or {}
    if old_mine.get("rank") and new_mine.get("rank") and old_mine["rank"] != new_mine["rank"]:
        changes.append(f"your rank {old_mine['rank']} → {new_mine['rank']}")
    if old_mine.get("score") and new_mine.get("score") and old_mine["score"] != new_mine["score"]:
        changes.append(f"your score {old_mine['score']} → {new_mine['score']}")
    old_top = (before.get("rows") or [{}])[0].get("score")
    new_top = (now.get("rows") or [{}])[0].get("score")
    if old_top and new_top and old_top != new_top:
        changes.append(f"leader {old_top} → {new_top}")
    for medal in MEDALS:
        old_line = (before.get("medal_lines") or {}).get(medal) or {}
        new_line = (now.get("medal_lines") or {}).get(medal) or {}
        if old_line.get("score") and new_line.get("score"):
            if old_line["score"] != new_line["score"]:
                changes.append(f"{medal} line {old_line['score']} → {new_line['score']}")
    if before.get("team_count") != now.get("team_count"):
        changes.append(f"teams {before.get('team_count'):,} → {now.get('team_count'):,}")
    return changes


def text_lines(snapshot: dict, top: int, previous: dict | None) -> list[str]:
    higher = snapshot["higher_is_better"]
    direction = {True: "higher is better", False: "lower is better", None: "direction not shown"}
    board = snapshot.get("board", "public")
    lines = [
        f"{board.capitalize()} leaderboard of {snapshot['competition']}: "
        f"{snapshot['team_count']:,} teams, {direction[higher]}",
        f"  {'rank':>5}  {'score':<12}  team",
    ]
    for row in snapshot["rows"][:top]:
        lines.append(f"  {row['rank']:>5}  {row['score']:<12}  {text.shorten(row['team'], 50)}")

    mine = snapshot["mine"]
    leader = snapshot["rows"][0]["score"] if snapshot["rows"] else None
    if mine:
        behind = gap(mine["score"], leader, higher)
        tail = f"; {behind:.5g} behind the leader" if behind else ""
        lines.append(f"  you: rank {mine['rank']}, score {mine['score']} ({mine['team']}){tail}")
    elif snapshot.get("user_rank") and snapshot.get("ended") and board == "public":
        lines.append(
            f"  you: rank {snapshot['user_rank']} on the private leaderboard; "
            "your team's row was not found on this one"
        )
    elif snapshot.get("user_rank"):
        lines.append(
            f"  you: rank {snapshot['user_rank']}; your row is past the "
            f"{len(snapshot['rows']):,} rows that were read"
        )
    else:
        lines.append("  you: not on this leaderboard")

    if snapshot["awards_medals"] and snapshot["medal_lines"]:
        if snapshot.get("ended"):
            lines.append("  medal lines at the final team count:")
        else:
            lines.append("  medal lines at today's team count (they move as teams join):")
        for medal in MEDALS:
            line = snapshot["medal_lines"].get(medal)
            if not line:
                continue
            if line["score"] is None:
                lines.append(f"    {medal:<6}  rank {line['rank']:>5}  (not read)")
                continue
            note = ""
            if mine:
                behind = gap(mine["score"], line["score"], higher)
                ranks = mine["rank"] - line["rank"]
                if ranks <= 0:
                    note = "  you are inside"
                elif behind:
                    note = f"  you are {behind:.5g} and {ranks} ranks behind"
                elif higher is None:
                    note = f"  you are {ranks} ranks behind"
                else:
                    note = f"  you are level on score, {ranks} ranks behind"
            lines.append(f"    {medal:<6}  rank {line['rank']:>5}  score {line['score']}{note}")
    elif not snapshot["awards_medals"]:
        lines.append("  medals: this competition awards none")

    if previous:
        changes = movement(previous, snapshot)
        since = text.when(previous.get("time"), text.parse_time(snapshot["time"]))
        lines.append(f"  since {since}: " + ("; ".join(changes) if changes else "nothing moved"))
    return lines


def ended_note(snapshot: dict) -> str | None:
    """After the deadline, where the final ranks are."""
    if snapshot.get("ended") and snapshot.get("board", "public") == "public":
        return (
            "The competition has ended: the private leaderboard decides the final ranks. "
            "Add --private to see it."
        )
    return None


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="A competition's leaderboard: the top, your row, the medal lines, what moved.",
        epilog="Needs a Kaggle credential: an API token or `kaggle auth login`.",
    )
    script.add_competition(parser)
    parser.add_argument(
        "--top", type=script.positive_int, default=10, metavar="N", help="Rows to print"
    )
    parser.add_argument(
        "--max-rows",
        type=script.positive_int,
        default=DEFAULT_MAX_ROWS,
        metavar="N",
        help=f"Read at most N rows to find your row and the medal lines "
        f"(default: {DEFAULT_MAX_ROWS})",
    )
    parser.add_argument(
        "--private",
        action="store_true",
        help="The private leaderboard, which decides the final ranks (after the deadline only)",
    )
    parser.add_argument(
        "--no-save", action="store_true", help="Do not save a snapshot for the next comparison"
    )
    script.add_json(parser)
    args = parser.parse_args(argv)
    (slug,) = script.positionals(parser, args)

    credentials.load_configured_env_file()
    token = mcp_client.resolve_token()
    if not token:
        return script.no_credential("the leaderboard")

    snapshot, result = build(slug, token, args.top, args.max_rows, private=args.private)
    if snapshot is None:
        return result if isinstance(result, int) else result.fail(competition=slug)
    previous = latest_snapshot(slug, snapshot["board"])

    attrs = {"source": SOURCE, "tool": TOOL, "competition": slug}
    if args.json:
        document = {**snapshot, "rows": snapshot["rows"][: args.top]}
        document["changes"] = movement(previous, snapshot) if previous else None
        untrusted.emit_json(document, indent=2 if args.pretty else None, **attrs)
    else:
        # Team names are written by participants.
        with untrusted.Block(**attrs) as block:
            for line in text_lines(snapshot, args.top, previous):
                block.write(line)
        note = ended_note(snapshot)
        if note:
            print(note)
    if not args.no_save:
        try:
            print(f"Snapshot saved: {save_snapshot(slug, snapshot)}")
        except OSError as exc:
            script.warn(f"the snapshot was not saved: {exc}")
    return script.EXIT_OK


if __name__ == "__main__":
    sys.exit(main())
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall