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

shared/credentials.py

View on GitHub
"""Find Kaggle credentials the way the Kaggle CLI does.

One resolver for every script, so a checker and the tool it checks never
disagree. The order mirrors ``kaggle`` 2.2.x and ``kagglesdk``:

1. API token: ``KAGGLE_API_TOKEN`` (the token itself, or a path to a file that
   holds it), then ``~/.kaggle/access_token``, then ``~/.kaggle/access_token.txt``.
2. Legacy key: ``KAGGLE_USERNAME`` + ``KAGGLE_KEY``, then ``kaggle.json`` in
   ``KAGGLE_CONFIG_DIR`` or ``~/.kaggle``.
3. OAuth: ``~/.kaggle/credentials.json``, written by ``kaggle auth login``.

Nothing here writes a credential or prints one.
"""

from __future__ import annotations

import json
import os
import re
import sys
from dataclasses import dataclass, field
from pathlib import Path

if __package__ in (None, ""):
    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

from shared import kaggle_cli  # noqa: E402

ENV_FILE_VAR = "KAGGLE_ENV_FILE"
# The only variables taken from an env file. Anything else in it is ignored,
# including settings that redirect the CLI or switch on its request logging.
ENV_FILE_KEYS = frozenset(
    {
        "KAGGLE_API_TOKEN",
        "KAGGLE_USERNAME",
        "KAGGLE_KEY",
        "KAGGLE_CONFIG_DIR",
        "KAGGLE_MCP_TOKEN",
    }
)
# Matched with fullmatch: "$" would also match before a final line break.
_HEX32_RE = re.compile(r"[0-9a-f]{32}")
# A bearer token is one run of printable ASCII: no spaces, no line breaks.
_BEARER_RE = re.compile(r"[\x21-\x7e]+")


@dataclass(frozen=True)
class Credential:
    """One credential that was found. ``repr`` never includes the secret."""

    kind: str  # "api_token" | "legacy_key" | "oauth"
    source: str  # where it was found, never the value
    username: str = ""
    secret: str = field(default="", repr=False)


def config_dir() -> Path:
    """Directory the CLI reads ``kaggle.json`` from."""
    override = os.environ.get("KAGGLE_CONFIG_DIR")
    if override:
        return Path(override)
    default = Path.home() / ".kaggle"
    if sys.platform.startswith("linux") and not default.exists():
        xdg = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
        return Path(xdg) / "kaggle"
    return default


def _read_token_file(path: Path) -> str:
    try:
        return path.read_text(encoding="utf-8").strip()
    except OSError:
        return ""


def api_token() -> Credential | None:
    """The API token, from the environment first and then the token file."""
    value = os.environ.get("KAGGLE_API_TOKEN", "").strip()
    if value:
        as_path = Path(value)
        try:
            is_file = as_path.is_file()
        except OSError:
            is_file = False
        if is_file:
            token = _read_token_file(as_path)
            if token:
                return Credential("api_token", "file named by KAGGLE_API_TOKEN", secret=token)
        else:
            return Credential("api_token", "KAGGLE_API_TOKEN", secret=value)
    for name in ("access_token", "access_token.txt"):
        path = Path.home() / ".kaggle" / name
        token = _read_token_file(path)
        if token:
            return Credential("api_token", f"~/.kaggle/{name}", secret=token)
    return None


def _read_kaggle_json() -> dict:
    path = config_dir() / "kaggle.json"
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, ValueError):
        return {}
    return data if isinstance(data, dict) else {}


def legacy_key() -> Credential | None:
    """Legacy username + key, from the environment or ``kaggle.json``."""
    username = os.environ.get("KAGGLE_USERNAME", "").strip()
    key = os.environ.get("KAGGLE_KEY", "").strip()
    if username and key:
        return Credential("legacy_key", "KAGGLE_USERNAME + KAGGLE_KEY", username, key)
    data = _read_kaggle_json()
    username = str(data.get("username") or username).strip()
    key = str(data.get("key") or key).strip()
    if username and key:
        return Credential("legacy_key", "kaggle.json", username, key)
    return None


def oauth() -> Credential | None:
    """OAuth credentials saved by ``kaggle auth login``."""
    path = Path.home() / ".kaggle" / "credentials.json"
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, ValueError):
        return None
    if not isinstance(data, dict) or not data.get("refresh_token"):
        return None
    return Credential("oauth", "~/.kaggle/credentials.json", str(data.get("username") or ""))


def discover() -> list[Credential]:
    """Every credential present, in the order the CLI would try them."""
    return [cred for cred in (api_token(), legacy_key(), oauth()) if cred is not None]


def resolve() -> Credential | None:
    """The credential the CLI would try first, or None."""
    found = discover()
    return found[0] if found else None


def kagglehub_ready() -> bool:
    """True when kagglehub has a credential: it reads API tokens and legacy keys, not OAuth."""
    return any(credential.kind != "oauth" for credential in discover())


def usable_bearer(value: str) -> str:
    """``value`` when it can go into an HTTP header as it is, otherwise ``""``.

    A value with a space or a line break is not a token. Sending it would make
    the HTTP library raise an error whose text quotes the value.
    """
    return value if _BEARER_RE.fullmatch(value) else ""


def oauth_access_token() -> str:
    """The OAuth access token from ``kaggle auth print-access-token``, or ``""``.

    The CLI can print warnings on standard output before the token (an
    out-of-date notice, a file-permission warning), so only the last line is
    taken, and only when it looks like a token.
    """
    if oauth() is None:
        return ""
    result = kaggle_cli.run(["auth", "print-access-token"], timeout=60)
    if result.returncode != 0:
        return ""
    lines = [line.strip() for line in result.stdout.splitlines() if line.strip()]
    return usable_bearer(lines[-1]) if lines else ""


def bearer_token() -> str:
    """A bearer token for the MCP server, or ``""`` when there is none.

    ``KAGGLE_MCP_TOKEN`` overrides everything. Then, in order: the API token,
    the OAuth access token from ``kaggle auth print-access-token``, and last
    the legacy key. The legacy key comes last because the MCP server is
    documented for tokens; the key is kept only so older setups behave as
    before. A value that could not be sent as a header is skipped.
    """
    override = usable_bearer(os.environ.get("KAGGLE_MCP_TOKEN", "").strip())
    if override:
        return override
    token = api_token()
    if token is not None and usable_bearer(token.secret):
        return token.secret
    access = oauth_access_token()
    if access:
        return access
    legacy = legacy_key()
    return usable_bearer(legacy.secret) if legacy is not None else ""


def describe_token(value: str) -> str:
    """Name the token type from its shape, without revealing it."""
    if value.startswith("KGAT_"):
        return "API token"
    if value.startswith("KGRT_"):
        return "OAuth refresh token"
    if _HEX32_RE.fullmatch(value):
        return "legacy API key"
    return "token"


def username() -> str:
    """Kaggle username: environment, ``kaggle.json``, saved OAuth login, then the CLI."""
    name = os.environ.get("KAGGLE_USERNAME", "").strip()
    if name:
        return name
    name = str(_read_kaggle_json().get("username") or "")
    if name:
        return name
    cred = oauth()
    if cred and cred.username and api_token() is None:
        return cred.username
    ok, name = verify()
    return name if ok else ""


def verify() -> tuple[bool, str]:
    """Ask Kaggle whether the configured credential works. Returns ``(ok, username)``.

    Two CLI calls are needed. ``kaggle config view`` names the account, but
    for a legacy key or a saved OAuth login it does not contact the server, so
    a revoked key still passes it. ``kaggle quota`` needs a signed-in account
    and fails for a credential the server no longer accepts.
    """
    view = kaggle_cli.run(["config", "view"], timeout=60)
    if view.returncode != 0:
        return False, ""
    if kaggle_cli.run(["quota"], timeout=60).returncode != 0:
        return False, ""
    match = re.search(r"^- username: (\S+)", view.stdout, re.MULTILINE)
    return True, match.group(1) if match else ""


def load_env_file(path: Path) -> list[str]:
    """Load credential variables from one file without overriding the environment.

    Lines are ``KEY=value``; ``export`` prefixes and surrounding quotes are
    accepted. Only the names in ``ENV_FILE_KEYS`` are used. Returns the names
    that were set.
    """
    try:
        text = Path(path).read_text(encoding="utf-8")
    except OSError:
        return []
    loaded: list[str] = []
    for raw in text.splitlines():
        line = raw.strip()
        if not line or line.startswith("#") or "=" not in line:
            continue
        if line.startswith("export "):
            line = line[len("export ") :].lstrip()
        key, value = line.split("=", 1)
        key = key.strip()
        value = value.strip()
        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
            value = value[1:-1]
        if key not in ENV_FILE_KEYS:
            continue
        if key not in os.environ:
            os.environ[key] = value
            loaded.append(key)
    return loaded


def load_configured_env_file() -> list[str]:
    """Load the file named by ``KAGGLE_ENV_FILE``, if that variable is set.

    This is the only ``.env`` file the skill reads. Nothing is searched for.
    """
    path = os.environ.get(ENV_FILE_VAR, "").strip()
    return load_env_file(Path(path).expanduser()) if path else []
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