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_status.py

View on GitHub
#!/usr/bin/env python3
"""Where you stand in a Kaggle competition: time left, submissions left, scores, quota.

    competition_status.py rsna-knee-abnormality-detection
    competition_status.py titanic --json

Facts only. It reads the deadline, your rank, how many submissions are left
today, the submissions still being scored, your best and latest scores, and
this week's GPU and TPU hours. It changes nothing.

Needs a credential: an API token or `kaggle auth login`. The count of
submissions left comes from the Kaggle CLI when it is installed; without it
the count is worked out from your submission list and marked as an estimate.
"""

from __future__ import annotations

import argparse
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_status"
BEST_OF = 100  # submissions read to find your best public score: one page


def submission_counts(info: dict, submissions: list[dict], limits: dict | None, now) -> dict:
    """How many submissions were made today and how many are left."""
    midnight = now.replace(hour=0, minute=0, second=0, microsecond=0)
    today = [
        row
        for row in submissions
        if (text.parse_time(row["date"]) or midnight.replace(year=1970)) >= midnight
    ]
    daily = info.get("max_daily_submissions")
    counts = {"today": len(today), "daily_limit": daily, "left": None, "source": None}
    if limits is not None:
        # Kaggle's own counts: the list above holds only the latest submissions.
        counts["today"] = limits["numToday"]
        counts["left"] = limits["numAllowedNow"]
        counts["lifetime"] = limits["numTotal"]
        counts["source"] = "kaggle-cli"
    elif daily:
        counts["left"] = max(int(daily) - len(today), 0)
        counts["source"] = "estimate"
    return counts


def quota_lines(quota: dict, now) -> list[str]:
    lines = []
    refresh = text.when(quota.get("quota_refresh_time"), now)
    for label, key in (("GPU this week", "gpu_quota"), ("TPU this week", "tpu_quota")):
        part = quota.get(key) if isinstance(quota.get(key), dict) else {}
        used = competition.seconds(part.get("time_used"))
        allowed = competition.seconds(part.get("total_time_allowed"))
        if used is None or allowed is None:
            continue
        lines.append(f"{label}: {used / 3600:.1f} h used of {allowed / 3600:.1f} h")
    if lines:
        lines.append(f"quota resets: {refresh}")
    return lines


def collect(slug: str, token: str, limit: int) -> tuple[dict | None, mcp_client.Result]:
    """Gather everything. Returns ``(report, the facts result)``; report is None on failure."""
    facts_result = competition.fetch_facts(slug, token)
    if not facts_result.ok or not isinstance(facts_result.data, dict):
        return None, facts_result
    now = text.now_utc()
    info = competition.facts(slug, facts_result.data)

    unavailable: dict[str, str] = {}
    read_limit = max(limit, BEST_OF)
    submissions, sub_result = competition.fetch_submissions(slug, token, limit=read_limit)
    if not sub_result.ok:
        unavailable["submissions"] = mcp_client.error_message(sub_result.response)[:200]

    board, _, board_result = competition.fetch_leaderboard(slug, token)
    if not board_result.ok:
        unavailable["leaderboard"] = mcp_client.error_message(board_result.response)[:200]
    higher = competition.higher_is_better(board)

    quota_result = mcp_client.request("get_accelerator_quota", {}, token=token)
    quota = quota_result.data if quota_result.ok and isinstance(quota_result.data, dict) else {}
    if not quota:
        unavailable["quota"] = mcp_client.error_message(quota_result.response)[:200]

    report = {
        "competition": info,
        "direction": None if higher is None else ("higher" if higher else "lower"),
        "leader_score": board[0]["score"] if board else None,
        "counts": submission_counts(info, submissions, competition.submission_limits(slug), now),
        "pending": [row for row in submissions if row["status"] == "PENDING"],
        "best": competition.best_submission(submissions, higher),
        # The best of the submissions read; older ones may exist when the read was full.
        "best_of": len(submissions) if len(submissions) >= read_limit else None,
        "latest": submissions[:limit],
        "quota": quota,
        "unavailable": unavailable,
        "checked": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
    }
    return report, facts_result


def text_lines(report: dict) -> list[str]:
    info = report["competition"]
    now = text.parse_time(report["checked"])
    missing = report["unavailable"]
    direction = {
        "higher": "higher is better",
        "lower": "lower is better",
        None: "direction not shown by the leaderboard",
    }[report["direction"]]
    rows: list[tuple[str, str]] = [("deadline", text.when(info.get("deadline"), now))]
    if info.get("entry_deadline"):
        rows.append(("join by", text.when(info["entry_deadline"], now)))
    rows.append(("metric", f"{info['metric'] or 'not given'} ({direction})"))
    rows.append(
        ("submit with", "a notebook (code competition)" if info["notebook_only"] else "a file")
    )
    teams = f"{int(info['team_count']):,}" if info.get("team_count") else "?"
    if info["user_has_entered"]:
        rank = info.get("user_rank")
        rows.append(("your rank", f"{rank} of {teams} teams" if rank else f"no rank yet ({teams})"))
    else:
        rows.append(("your rank", "you have not entered this competition"))

    counts = report["counts"]
    if info["submissions_disabled"]:
        rows.append(("submissions", "closed"))
    elif "submissions" in missing:
        rows.append(("submissions", f"not available ({missing['submissions']})"))
    else:
        daily = f" of {counts['daily_limit']} a day" if counts["daily_limit"] else ""
        if counts["source"] == "kaggle-cli":
            left = f"{counts['left']} left{daily} (Kaggle's count)"
        elif counts["source"] == "estimate":
            left = f"about {counts['left']} left{daily} (estimated; counted since 00:00 UTC)"
        else:
            left = "the daily limit is not given"
        rows.append(("submissions", f"{counts['today']} today, {left}"))

    for row in report["pending"]:
        rows.append(("being scored", f"submission {row['ref']}, sent {_stamp(row['date'])}"))

    best = report["best"]
    if best:
        leader = f"; the leader has {report['leader_score']}" if report["leader_score"] else ""
        label = f"best of latest {report['best_of']}" if report.get("best_of") else "best public"
        rows.append(
            (
                label,
                f"{best['public_score']} on {text.day(best['date'])} (submission {best['ref']})"
                f"{leader}",
            )
        )
    width = max(len(label) for label, _ in rows) + 1
    lines = [info["title"]] + [f"  {label + ':':<{width}} {value}" for label, value in rows]

    if report["latest"]:
        lines.append("  latest submissions:")
        for row in report["latest"]:
            score = row["public_score"] or "-"
            lines.append(
                f"    {_stamp(row['date'])}  {row['status']:<8}  {score:<10}  "
                f"{text.shorten(text.collapse(row['description']), 60)}  [{row['ref']}]"
            )
    elif "submissions" not in missing:
        lines.append("  latest submissions: none yet")

    if "quota" in missing:
        lines.append(f"  quota: not available ({missing['quota']})")
    lines += [f"  {line}" for line in quota_lines(report["quota"], now)]
    return lines


def _stamp(value: object) -> str:
    moment = text.parse_time(value)
    return moment.strftime("%Y-%m-%d %H:%M") if moment else "-"


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Where you stand in a Kaggle competition: time left, submissions left, "
        "scores, quota.",
        epilog="Needs a Kaggle credential: an API token or `kaggle auth login`.",
    )
    script.add_competition(parser)
    script.add_limit(parser, 5, "of your latest submissions")
    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("your status in a competition")

    report, facts_result = collect(slug, token, args.limit)
    if report is None:
        return facts_result.fail(competition=slug)

    attrs = {"source": SOURCE, "tool": TOOL, "competition": slug}
    if args.json:
        untrusted.emit_json(report, indent=2 if args.pretty else None, **attrs)
    else:
        # The title, the submission messages and Kaggle's error text are data.
        with untrusted.Block(**attrs) as block:
            for line in text_lines(report):
                block.write(line)
    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