kaggle 2.2.0__tar.gz → 2.2.2__tar.gz

{kaggle-2.2.0 → kaggle-2.2.2}/.gitignore

@@ -49,6 +49,7 @@ coverage.xml
 *,cover
 .hypothesis/
 venv/
+.venv
 .python-version
 
 # Translations

{kaggle-2.2.0 → kaggle-2.2.2}/CHANGELOG.md

@@ -3,6 +3,30 @@ Changelog
 
 ### Next
 
+### 2.2.2
+
+* Clarify LLMS_AVAILABLE vs. full model set in benchmarks docs (#1061)
+* Add kernels topics command (#1056)
+* Improve benchmark task error messages in kaggle CLI (#1057)
+* Fix dataset metadata column/file description updates and docs (#1055)
+* Expand Kaggle CLI skill references (#1054)
+* Tag benchmarks token requests with CLI source for analytics (#1050)
+* Add machine_shape to kernels_initialize metadata template and docs (#1048)
+* Fix 403 for dataset, model, and benchmark topics list (#1051)
+* Fix test_benchmarks_cli.py assertions (#1049)
+* Add paginated downloads for kernel output files (#1046)
+* fix(tests): resolve infinite loop in test_kernels_d_status (#1043)
+
+### 2.2.1
+
+* Add `kaggle competitions team-submissions` command (#1036)
+* Add `kaggle quota` command for GPU/TPU accelerator quota (#1029)
+* Support optional kernel version in specifier (#1035)
+* feat(benchmarks): Add log and download source files (#1019)
+* Fix benchmarks CLI error handling and UX improvements (#1024, #1026, #1028, #1030, #1032, #1037, #1039)
+* Fix JSON serialization and download label display (#1038, #1040, #1042)
+* Set proper permissions on auth file (#1033)
+
 ### 2.2.0
 
 * Add test runner workflow

{kaggle-2.2.0 → kaggle-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kaggle
-Version: 2.2.0
+Version: 2.2.2
 Summary: Access Kaggle resources anywhere
 Project-URL: Homepage, https://github.com/Kaggle/kaggle-cli
 Project-URL: Issues, https://github.com/Kaggle/kaggle-cli/issues
@@ -214,10 +214,11 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.11
 Requires-Dist: bleach
 Requires-Dist: jupytext
-Requires-Dist: kagglesdk<1.0,>=0.1.24
+Requires-Dist: kagglesdk<1.0,>=0.1.30
 Requires-Dist: packaging
 Requires-Dist: protobuf
 Requires-Dist: python-dateutil
+Requires-Dist: python-dotenv
 Requires-Dist: python-slugify
 Requires-Dist: requests
 Requires-Dist: tqdm

{kaggle-2.2.0 → kaggle-2.2.2}/docs/benchmarks.md

@@ -77,6 +77,8 @@ In addition to the three credential variables written by `auth`, `init` also wri
 *   `LLM_DEFAULT_EVAL` — Default model slug for evaluation.
 *   `LLMS_AVAILABLE` — Comma-separated list of available model slugs.
 
+> **Note:** `LLMS_AVAILABLE` is a curated subset of models intended for local development and testing — it is **not** the full set of available models, and the Model Proxy token itself is not restricted to these models. To see all available models, use `kaggle benchmarks tasks models`. To run a task against any model (including those not in `LLMS_AVAILABLE`), use `kaggle benchmarks tasks run`, which executes on Kaggle's infrastructure with access to the full model catalog.
+
 `init` also creates two files alongside the example file:
 
 *   **`example_task.py`** (or custom name via `--example-file`) — A starter Python script demonstrating how to define a benchmark task using `@task` decorators and the `kaggle_benchmarks` library.
@@ -271,6 +273,8 @@ kaggle benchmarks tasks status <TASK> [options]
 
 Prints the task's metadata (slug, creation status, creation time, URL) followed by a table of all runs. Each run row shows the model name, run state, start time, and end time. Any errored runs display their error messages below the table.
 
+If task creation itself failed, the `Status:` line shows the failure *kind* — the cleaned creation-state enum, titlecased (e.g. `Kernel_Without_Run`, `No_Model_Specified`, `Validation_Failed`, `Errored`) — and an `Error:` line is appended below it with the server-provided `creation_error_message` explaining what went wrong.
+
 ---
 
 ### `kaggle benchmarks tasks download`
@@ -329,10 +333,29 @@ Downloads and extracts the output zip archive for each completed run. Files are
    ├── output files...
 ```
 
-Already-downloaded runs (where the output directory exists) are automatically skipped unless the `-f` / `--force` flag is used, in which case they are overwritten.
+Progress is rendered as a table with one row per run:
+
+```
+Model                File                                     Size       Progress
+──────────────────── ──────────────────────────────────────── ────────── ──────────
+gemini-2.5-pro       gemini-2.5-pro/12345/                    1.24MB     Done
+claude-sonnet-4      claude-sonnet-4/12346/                   2.10MB     Cached
+```
+
+The `Size` column reports the extracted on-disk size of the run's output directory. The `Progress` column is one of `Done` (freshly downloaded), `Cached` (output directory already on disk from a previous download), or `Bad zip` (downloaded archive was corrupt).
+
+Already-downloaded runs (where the output directory exists) are automatically skipped — they appear as `Cached` rows — unless the `-f` / `--force` flag is used, in which case they are overwritten.
 
 When `--include-source` is used, the downloaded zip also contains the kernel session's source files (e.g., `__notebook__.ipynb` and `__notebook_source__.ipynb`).
 
+If you re-run with `-s` after a previous download that omitted source notebooks, the cached directories are not re-fetched and the `-s` flag is effectively ignored. The CLI detects this and prints a tip after the summary:
+
+```
+Tip: 2 cached run(s) lack source notebooks. Re-run with -f -s to fetch them.
+```
+
+Use `-f -s` together to force re-download and backfill the source notebooks into the cached runs.
+
 ---
 
 ### `kaggle benchmarks tasks log`

{kaggle-2.2.0 → kaggle-2.2.2}/docs/datasets_metadata.md

@@ -74,7 +74,7 @@ The following metadata is currently supported:
     * `schema`: File schema (definition below):
       * `fields`: Array of fields in the dataset.  Please note that this needs to include ALL of the fields in the data in order or they will not be matched up correctly.  A later version of the API will fix this bug.
         * `name`: Field name
-        * `title`: Field description
+        * `description`: Field description (Note: `title` is also accepted for backward compatibility, but `description` is preferred)
         * `type`: Field type. A best-effort list of types will be kept at the bottom of this page, but new types may be added that are not documented here.
   * `keywords`: Contains an array of strings that correspond to an existing tag on Kaggle.  If a specified tag doesn't exist, the upload will continue, but that specific tag won't be added.  
 * `kaggle datasets version` (create a new version for an existing Dataset):
@@ -88,7 +88,7 @@ The following metadata is currently supported:
     * `schema`: File schema (definition below):
       * `fields`: Array of fields in the dataset.  Please note that this needs to include ALL of the fields in the data in order or they will not be matched up correctly.  A later version of the API will fix this bug.
         * `name`: Field name
-        * `title`: Field description
+        * `description`: Field description (Note: `title` is also accepted for backward compatibility, but `description` is preferred)
         * `type`: Field type. A best-effort list of types will be kept at the bottom of this page, but new types may be added that are not documented here.
   * `keywords`: Contains an array of strings that correspond to an existing tag on Kaggle.  If a specified tag doesn't exist, the upload will continue, but that specific tag won't be added.  
 * `kaggle datasets metadata --update` (update metadata for an existing Dataset) supports all fields mentioned above for `kaggle datasets version`, and additionally:

{kaggle-2.2.0 → kaggle-2.2.2}/docs/kernels.md

@@ -226,6 +226,8 @@ kaggle kernels output <KERNEL> [options]
 *   `-o, --force`: Force download, overwriting existing files.
 *   `-q, --quiet`: Suppress verbose output.
 *   `--file-pattern <REGEX>`: Regex pattern to match against filenames. Only files matching the pattern will be downloaded.
+*   `--page-size <SIZE>`: Number of output files to request per page. Default size is 20, max is 200.
+*   `--page-token <TOKEN>`: Download files from a specific output page. If Kaggle returns another page token, it is printed after the download.
 
 **Example:**
 
@@ -240,9 +242,27 @@ Download PNG files only:
 kaggle kernels output <kernel> --file-pattern ".*\.png$"  # Only PNG files
 ```
 
+Download matching PNG files across all output pages:
+
+```bash
+kaggle kernels output <kernel> --file-pattern ".*\.png$"
+```
+
+Download files from a specific output page:
+
+```bash
+kaggle kernels output <kernel> --page-token <TOKEN>
+```
+
+Download files in smaller pages:
+
+```bash
+kaggle kernels output <kernel> --page-size 50
+```
+
 **Purpose:**
 
-Use this command to retrieve the files generated by a kernel run, such as submission files, processed data, or visualizations.
+Use this command to retrieve the files generated by a kernel run, such as submission files, processed data, or visualizations. By default, output downloads scan every available output page, so `--file-pattern` can match files beyond the first page. Use `--page-size` to control how many files are requested on each page, and use `--page-token` when you only want to download files from one specific page.
 
 ## `kaggle kernels status`
 
@@ -299,3 +319,72 @@ kaggle kernels delete $KAGGLE_DEVELOPER/exercise-delete --yes
 **Purpose:**
 
 This command permanently removes one of your kernels from Kaggle. Use with caution.
+
+## `kaggle kernels topics list`
+
+Lists discussion topics for a kernel.
+
+**Usage:**
+
+```bash
+kaggle kernels topics list <KERNEL> [options]
+```
+
+**Arguments:**
+
+*   `<KERNEL>`: Kernel ref in format `<owner>/<kernel-slug>` (e.g., `owner/kernel-slug`).
+
+**Options:**
+
+*   `--sort-by <SORT_BY>`: Sort order. Valid options: `hot`, `top`, `new`, `recent`, `active`, `relevance`.
+*   `-s, --search <SEARCH_TERM>`: Search query to filter topics.
+*   `--page-size <PAGE_SIZE>`: Number of items per page.
+*   `--page-token <PAGE_TOKEN>`: Page token for pagination.
+*   `-v, --csv`: Print results in CSV format.
+*   `-q, --quiet`: Suppress verbose output.
+
+**Example:**
+
+List recent topics for the `owner/kernel-slug` kernel:
+
+```bash
+kaggle kernels topics list owner/kernel-slug --sort-by recent
+```
+
+**Purpose:**
+
+This command lets you browse discussion topics for a specific kernel.
+
+## `kaggle kernels topics show`
+
+Displays a kernel discussion topic with all comments in tree form.
+
+**Usage:**
+
+```bash
+kaggle kernels topics show <TOPIC_REF> [options]
+```
+
+**Arguments:**
+
+*   `<TOPIC_REF>`: A topic reference, which can be:
+    *   `<kernel>/<topic-id>` (e.g., `owner/kernel-slug/12345`)
+    *   `<kernel> <topic-id>` (two separate arguments, where `<topic-id>` is passed as second argument)
+    *   `<topic-id>` (bare numeric ID)
+
+**Options:**
+
+*   `--page-size <PAGE_SIZE>`: Number of comments to show per page.
+*   `--page-token <PAGE_TOKEN>`: Page token for comment pagination.
+*   `-v, --csv`: Print results in CSV format.
+*   `-q, --quiet`: Suppress verbose output.
+
+**Example:**
+
+```bash
+kaggle kernels topics show owner/kernel-slug/12345
+```
+
+**Purpose:**
+
+This command displays a full discussion topic along with all of its comments rendered in an indented tree structure.

{kaggle-2.2.0 → kaggle-2.2.2}/docs/kernels_metadata.md

@@ -12,6 +12,7 @@ Here's a basic example for `kernel-metadata.json`:
   "is_private": "false",
   "enable_gpu": "false",
   "enable_internet": "false",
+  "machine_shape": "",
   "dataset_sources": ["timoboz/my-awesome-dataset"],
   "competition_sources": [],
   "kernel_sources": [],
@@ -34,6 +35,7 @@ We currently support the following metadata fields for kernels.
 * `is_private`: Whether or not the kernel should be private. If not specified, will be `true`.
 * `enable_gpu`: Whether or not the kernel should run on a GPU. If not specified, will be `false`.
 * `enable_internet`: Whether or not the kernel should be able to access the internet. If not specified, will be `false`.
+* `machine_shape`: The accelerator/GPU type to use (e.g., `NvidiaTeslaT4`, `NvidiaTeslaP100`, or `Tpu1VmV38`).
 * `dataset_sources`: A list of dataset sources, specified as `"username/dataset-slug"`
 * `competition_sources`: A list of competition sources, specified as `"competition-slug"`
 * `kernel_sources`: A list of kernel sources, specified as `"username/kernel-slug"`

{kaggle-2.2.0 → kaggle-2.2.2}/docs/simulation_competitions.md

@@ -140,6 +140,30 @@ kaggle competitions logs 98765432 1 -p ./logs
 
 This downloads the log file as `episode-98765432-agent-0-logs.json`.
 
+## 9. Inspect Top Teams' Active Agents
+
+You can study how the leading teams' agents are performing — useful for scouting strategies or understanding the metagame. Start from the leaderboard to grab the team ID:
+
+```bash
+kaggle competitions leaderboard connectx -s
+```
+
+This prints a table with columns `teamId`, `teamName`, `submissionDate`, `score`. Take the `teamId` of the team you want to inspect (e.g., first place), then list every active submission they have on the leaderboard:
+
+```bash
+kaggle competitions team-submissions 42
+```
+
+This returns the team's public-safe submissions — `id`, `dateSubmitted`, and `publicScore`. For simulation competitions every leaderboard-eligible submission is listed (not just the best one), so you can see the full rotation of agents a top team is fielding.
+
+Pick the submission with the highest `publicScore` and list its episodes, just like you would for your own:
+
+```bash
+kaggle competitions episodes 98765432
+```
+
+From there you can pull replays and agent logs for any episode that submission played in (`kaggle competitions replay <episode_id>` / `kaggle competitions logs <episode_id> <agent_index>`).
+
 ## Putting It All Together
 
 Here's a typical workflow for iterating on a simulation competition agent:
@@ -167,4 +191,8 @@ kaggle competitions logs 98765432 0
 
 # Check the leaderboard
 kaggle competitions leaderboard connectx -s
+
+# Scout the leader: list their active agents, then pick the best one's episodes
+kaggle competitions team-submissions <leader-team-id>
+kaggle competitions episodes <best-submission-id>
 ```

{kaggle-2.2.0 → kaggle-2.2.2}/pyproject.toml

@@ -24,7 +24,7 @@ keywords = ["Kaggle", "API"]
 requires-python = ">= 3.11"
 dependencies = [
     "bleach",
-    "kagglesdk >= 0.1.24, < 1.0", # sync with kagglehub
+    "kagglesdk >= 0.1.30, < 1.0", # sync with kagglehub
     "python-slugify",
     "requests",
     "python-dateutil",
@@ -33,6 +33,7 @@ dependencies = [
     "packaging",
     "protobuf",
     "jupytext",
+    "python-dotenv",
 ]
 
 [project.scripts]
@@ -97,7 +98,8 @@ module = [
     # TODO(b/505845982): Generate type hints for kagglesdk
     "kagglesdk.*",
     "kaggle_api_extended.*",
-    "jupytext.*"
+    "jupytext.*",
+    "dotenv.*"
 ]
 ignore_missing_imports = true
 

{kaggle-2.2.0 → kaggle-2.2.2}/requirements.lock

@@ -26,7 +26,7 @@ jupyter-core==5.9.1
     # via nbformat
 jupytext==1.19.1
     # via kaggle (pyproject.toml)
-kagglesdk==0.1.24
+kagglesdk==0.1.25
     # via kaggle (pyproject.toml)
 markdown-it-py==4.0.0
     # via
@@ -50,6 +50,8 @@ protobuf==7.34.1
     #   kagglesdk
 python-dateutil==2.9.0.post0
     # via kaggle (pyproject.toml)
+python-dotenv==1.2.2
+    # via kaggle (pyproject.toml)
 python-slugify==8.0.4
     # via kaggle (pyproject.toml)
 pyyaml==6.0.3

kaggle-2.2.2/skills/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: kaggle-cli
+description: >
+  Use the local Kaggle CLI skill for command guidance, workflows, and
+  troubleshooting across competitions, datasets, kernels/notebooks, models,
+  model variations and versions, inbox file uploads, forums/discussions,
+  benchmarks, configuration, OAuth/API-token authentication, and accelerator
+  quota. Activate this skill when the user asks about kaggle CLI commands,
+  examples, flags, metadata files, download/upload flows, submissions,
+  benchmark tasks, or Kaggle CLI behavior.
+---
+
+# Kaggle CLI
+
+Use this skill to answer or operate on the `kaggle` command-line tool. Treat
+this skill and its references as the available command guide.
+
+## Quick Start
+
+```bash
+pip install kaggle
+kaggle --help
+```
+
+Authentication options:
+
+```bash
+kaggle auth login
+# or set KAGGLE_API_TOKEN
+# or place an access token in ~/.kaggle/access_token
+# or use legacy ~/.kaggle/kaggle.json credentials
+```
+
+## Command Tree
+
+```text
+kaggle
+├── competitions | c
+│   ├── list, files, download, submit, submissions, leaderboard
+│   ├── team-submissions, episodes, replay, logs, pages
+│   └── topics {list, show}, topic-messages
+├── datasets | d
+│   ├── list, files, download, init, create, version
+│   ├── metadata, status, delete
+│   └── topics {list, show}
+├── kernels | k
+│   └── list, files, init, push|update, pull|get, output, status, logs, delete
+├── models | m
+│   ├── list, init, create, get, update, delete
+│   ├── topics {list, show}
+│   └── variations | instances | v | i
+│       ├── get, init, create, files, list, update, delete
+│       └── versions | v {list, create, download, files, delete}
+├── files {upload}
+├── forums | f {list, topics {list, show}}
+├── benchmarks | b
+│   ├── auth, init
+│   ├── tasks | t {push, run, list, status, download, log|logs, models, delete, publish}
+│   └── topics {list, show}
+├── config {view, set, unset}
+├── auth {login, print-access-token, revoke}
+└── quota
+```
+
+Note: the CLI accepts aliases such as `kernels get` for `kernels pull` and
+`kernels update` for `kernels push`. Do not recommend
+`models variations versions init`; use `models variations init` for variation
+metadata instead.
+
+## Reference Map
+
+Read only the reference needed for the user's task:
+
+- [Competitions](references/competitions.md) - competition discovery, files, downloads, submissions, leaderboards, simulations, pages, topics.
+- [Datasets](references/datasets.md) - dataset search, files, downloads, metadata, create/version/status/delete, topics.
+- [Kernels](references/kernels.md) - notebook/script discovery, metadata, push/pull, outputs, status, logs, delete.
+- [Models](references/models.md) - model records, metadata, create/get/update/delete, model topics.
+- [Model Variations](references/model_variations.md) - create and manage framework-specific model variations.
+- [Model Variation Versions](references/model_variations_versions.md) - create, list, download, inspect, and delete variation versions.
+- [Files](references/files.md) - inbox uploads, resumable uploads, directory compression behavior.
+- [Forums](references/forums.md) - global discussion forums, topics, and comments.
+- [Benchmarks](references/benchmarks.md) - benchmark auth/init, task push/run/status/download/log/model flows, benchmark topics.
+- [Configuration](references/configuration.md) - config file, default path, proxy, default competition.
+- [Authentication](references/auth.md) - OAuth login, access token printing, revocation, token/key sources.
+- [Quota](references/quota.md) - weekly GPU/TPU accelerator quota.
+
+## Operating Guidance
+
+- Read only the reference needed for the user's task.
+- Prefer `kaggle <group> --help` or `kaggle <group> <command> --help` when a flag
+  is uncertain in the installed CLI.
+- For metadata files, prefer the relevant `init` command to generate a starter
+  file before editing it.
+- Do not invent commands that are not listed in this skill. If live `--help`
+  output differs, report it as a version-specific difference.

kaggle-2.2.2/skills/references/auth.md

@@ -0,0 +1,137 @@
+# Authentication CLI Reference
+
+Use `kaggle auth` to run OAuth login, print an OAuth access token, or revoke the
+active OAuth refresh token. The CLI also supports non-command authentication via
+`KAGGLE_API_TOKEN`, `~/.kaggle/access_token`, and legacy API key credentials.
+
+## Prerequisites
+
+- Python 3.11+ with the `kaggle` package installed.
+- A Kaggle account.
+- Browser access for the default OAuth login flow, or use `--no-launch-browser`
+  to print a URL.
+
+## Command Hierarchy
+
+```text
+kaggle auth
+├── login
+├── print-access-token
+└── revoke
+```
+
+## Authentication Sources
+
+The CLI authentication flow tries these sources:
+
+1. Access token sources such as `KAGGLE_API_TOKEN` or
+   `~/.kaggle/access_token`.
+2. Legacy API key config from environment/config values `username` and `key`.
+3. OAuth credentials created by `kaggle auth login`.
+
+If none succeed, the CLI prints auth help and exits.
+
+Some commands are allowed logged out, including help/version and selected
+public dataset file/download flows.
+
+## `kaggle auth login`
+
+Runs Kaggle OAuth login.
+
+**Usage:**
+
+```bash
+kaggle auth login [options]
+```
+
+**Options:**
+
+- `--no-launch-browser`: Do not launch a browser; print an auth URL instead.
+- `--force`: Re-run login even if already logged in.
+
+**Examples:**
+
+```bash
+kaggle auth login
+kaggle auth login --no-launch-browser
+kaggle auth login --force
+```
+
+**Purpose:** Store OAuth credentials for the active Kaggle account.
+
+**Behavior details:**
+
+- If credentials already exist and `--force` is not set, the command prints the
+  current account and exits with instructions to use `--force`.
+- The OAuth flow requests the default scope `resources.admin:*`.
+
+## `kaggle auth print-access-token`
+
+Prints an access token for the active OAuth account.
+
+**Usage:**
+
+```bash
+kaggle auth print-access-token [options]
+```
+
+**Options:**
+
+- `--expiration <DURATION>`: Override token duration.
+
+**Examples:**
+
+```bash
+kaggle auth print-access-token
+```
+
+**Purpose:** Emit a token that can be placed in `KAGGLE_API_TOKEN` or another
+supported token source.
+
+**Behavior details:**
+
+- Requires OAuth credentials from `kaggle auth login`.
+- If no OAuth credentials exist, the command tells the user to run
+  `kaggle auth login`.
+- Some CLI help examples use short forms such as `6h`. For automation, omit
+  `--expiration` unless the accepted duration format has been verified with
+  the installed CLI.
+
+## `kaggle auth revoke`
+
+Revokes the active OAuth refresh token.
+
+**Usage:**
+
+```bash
+kaggle auth revoke [options]
+```
+
+**Options:**
+
+- `--reason <TEXT>`: Reason sent to the server.
+
+**Examples:**
+
+```bash
+kaggle auth revoke
+kaggle auth revoke --reason "rotating credentials"
+```
+
+**Purpose:** Invalidate the active OAuth credential.
+
+**Behavior details:**
+
+- If no OAuth credentials exist, the command prints `There is no token to
+  revoke.` and exits successfully.
+- If no reason is provided, the default reason is
+  `Manually revoked by user with kaggle-cli`.
+
+## Legacy And Token Auth Notes
+
+- `KAGGLE_API_TOKEN` can authenticate without a legacy username/key pair when
+  the token introspection succeeds.
+- Legacy config can come from `~/.kaggle/kaggle.json` or environment variables
+  such as `KAGGLE_USERNAME` and `KAGGLE_KEY`.
+- Prefer `kaggle auth login` for OAuth credentials or `KAGGLE_API_TOKEN` for
+  non-interactive authentication.