kaggle-free-gpu 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- kaggle_free_gpu/__init__.py +4 -0
- kaggle_free_gpu/cli.py +308 -0
- kaggle_free_gpu/client.py +843 -0
- kaggle_free_gpu/models.py +230 -0
- kaggle_free_gpu/quota.py +227 -0
- kaggle_free_gpu/server.py +168 -0
- kaggle_free_gpu-0.1.0.dist-info/METADATA +266 -0
- kaggle_free_gpu-0.1.0.dist-info/RECORD +11 -0
- kaggle_free_gpu-0.1.0.dist-info/WHEEL +4 -0
- kaggle_free_gpu-0.1.0.dist-info/entry_points.txt +4 -0
- kaggle_free_gpu-0.1.0.dist-info/licenses/LICENSE +22 -0
kaggle_free_gpu/cli.py
ADDED
|
@@ -0,0 +1,308 @@
|
|
|
1
|
+
"""Command-line interface for Kaggle Free-GPU (`kaggle-free-gpu` / `kfg`)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import json
|
|
7
|
+
import re
|
|
8
|
+
import sys
|
|
9
|
+
import time
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
|
|
12
|
+
from rich.console import Console
|
|
13
|
+
from rich.markup import escape as rich_escape
|
|
14
|
+
from rich.panel import Panel
|
|
15
|
+
from rich.table import Table
|
|
16
|
+
|
|
17
|
+
from kaggle_free_gpu.client import KaggleAPIError, KaggleAuthError, KaggleGPUClient
|
|
18
|
+
|
|
19
|
+
console = Console()
|
|
20
|
+
_ANSI_CTRL_RE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|[\x00-\x08\x0b-\x1f\x7f-\x9f]")
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _safe_text(val: object) -> str:
|
|
24
|
+
"""Strip ANSI/OSC terminal escape codes and escape Rich markup tags from untrusted text."""
|
|
25
|
+
cleaned = _ANSI_CTRL_RE.sub("", str(val if val is not None else ""))
|
|
26
|
+
return rich_escape(cleaned)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _poll_until_done(client: KaggleGPUClient, ref: str, poll_interval: float = 10.0, timeout_sec: float = 3600.0) -> str:
|
|
30
|
+
"""Poll kernel_status until COMPLETE or ERROR."""
|
|
31
|
+
start = time.time()
|
|
32
|
+
last_status = ""
|
|
33
|
+
while True:
|
|
34
|
+
res = client.kernel_status(ref)
|
|
35
|
+
status = res.status
|
|
36
|
+
elapsed = int(time.time() - start)
|
|
37
|
+
if status != last_status:
|
|
38
|
+
console.print(f"[cyan][{elapsed}s][/cyan] {_safe_text(ref)} -> [bold]{_safe_text(status)}[/bold]")
|
|
39
|
+
last_status = status
|
|
40
|
+
if status in ("COMPLETE", "ERROR") or status.startswith("ERROR_"):
|
|
41
|
+
if res.failure_message:
|
|
42
|
+
console.print(f"[red]Failure:[/red] {_safe_text(res.failure_message)}")
|
|
43
|
+
if res.hint:
|
|
44
|
+
console.print(f"[yellow]Hint:[/yellow] {_safe_text(res.hint)}")
|
|
45
|
+
return status
|
|
46
|
+
if elapsed >= timeout_sec:
|
|
47
|
+
console.print(f"[yellow]Timeout reached ({timeout_sec}s) while status is {_safe_text(status)}.[/yellow]")
|
|
48
|
+
return status
|
|
49
|
+
time.sleep(poll_interval)
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def cmd_push(args: argparse.Namespace) -> int:
|
|
53
|
+
client = KaggleGPUClient()
|
|
54
|
+
res = client.push_kernel(dir_path=args.dir, allow_mismatch=args.allow_mismatch)
|
|
55
|
+
if args.json:
|
|
56
|
+
print(json.dumps(res.model_dump(), indent=2))
|
|
57
|
+
return 0 if res.ok else 1
|
|
58
|
+
|
|
59
|
+
for w in res.warnings:
|
|
60
|
+
console.print(f"[yellow]Warning:[/yellow] {_safe_text(w)}")
|
|
61
|
+
|
|
62
|
+
if not res.ok:
|
|
63
|
+
console.print(Panel(_safe_text(res.error or "Push failed"), title="[red]Push Rejected[/red]", border_style="red"))
|
|
64
|
+
return 1
|
|
65
|
+
|
|
66
|
+
console.print(
|
|
67
|
+
Panel(
|
|
68
|
+
f"[bold green]Pushed successfully![/bold green]\n"
|
|
69
|
+
f"Ref: [cyan]{_safe_text(res.ref)}[/cyan]\n"
|
|
70
|
+
f"Title: {_safe_text(res.title)}\n"
|
|
71
|
+
f"Version: {_safe_text(res.version_number)}\n"
|
|
72
|
+
f"GPU Enabled: {res.enable_gpu} | Private: {res.is_private}\n"
|
|
73
|
+
f"URL: {_safe_text(res.url)}",
|
|
74
|
+
title="Kaggle Free-GPU Push",
|
|
75
|
+
border_style="green",
|
|
76
|
+
)
|
|
77
|
+
)
|
|
78
|
+
|
|
79
|
+
if args.wait:
|
|
80
|
+
final_status = _poll_until_done(client, res.ref, poll_interval=args.poll_interval)
|
|
81
|
+
if final_status != "COMPLETE":
|
|
82
|
+
return 1
|
|
83
|
+
if args.out_dir:
|
|
84
|
+
out_res = client.kernel_output(res.ref, args.out_dir)
|
|
85
|
+
console.print(f"[green]Output downloaded to:[/green] {_safe_text(out_res.out_dir)} (runtime: {out_res.runtime_seconds}s)")
|
|
86
|
+
if out_res.stdout_tail:
|
|
87
|
+
console.print(Panel(_safe_text(out_res.stdout_tail.strip()), title="Stdout", border_style="blue"))
|
|
88
|
+
return 0
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def cmd_status(args: argparse.Namespace) -> int:
|
|
92
|
+
client = KaggleGPUClient()
|
|
93
|
+
if args.wait:
|
|
94
|
+
final_status = _poll_until_done(client, args.ref, poll_interval=args.poll_interval)
|
|
95
|
+
return 0 if final_status == "COMPLETE" else 1
|
|
96
|
+
|
|
97
|
+
res = client.kernel_status(args.ref)
|
|
98
|
+
if args.json:
|
|
99
|
+
print(json.dumps(res.model_dump(), indent=2))
|
|
100
|
+
return 0 if not res.status.startswith("ERROR") else 1
|
|
101
|
+
|
|
102
|
+
color = "green" if res.status == "COMPLETE" else ("red" if "ERROR" in res.status else "yellow")
|
|
103
|
+
console.print(f"[bold]{_safe_text(res.ref)}[/bold]: [{color}]{_safe_text(res.status)}[/{color}]")
|
|
104
|
+
if res.failure_message:
|
|
105
|
+
console.print(f"[red]Failure:[/red] {_safe_text(res.failure_message)}")
|
|
106
|
+
if res.hint:
|
|
107
|
+
console.print(f"[yellow]Hint:[/yellow] {_safe_text(res.hint)}")
|
|
108
|
+
return 0 if not res.status.startswith("ERROR") else 1
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def cmd_output(args: argparse.Namespace) -> int:
|
|
112
|
+
client = KaggleGPUClient()
|
|
113
|
+
res = client.kernel_output(
|
|
114
|
+
owner_slug=args.ref,
|
|
115
|
+
out_dir=args.out_dir,
|
|
116
|
+
max_size_mb=args.max_size_mb,
|
|
117
|
+
force_large=args.force_large,
|
|
118
|
+
)
|
|
119
|
+
if args.json:
|
|
120
|
+
print(json.dumps(res.model_dump(), indent=2))
|
|
121
|
+
return 0
|
|
122
|
+
|
|
123
|
+
for w in res.warnings:
|
|
124
|
+
console.print(f"[yellow]Warning:[/yellow] {_safe_text(w)}")
|
|
125
|
+
if res.hint:
|
|
126
|
+
console.print(f"[yellow]Hint:[/yellow] {_safe_text(res.hint)}")
|
|
127
|
+
|
|
128
|
+
console.print(
|
|
129
|
+
f"[bold green]Pulled output for {_safe_text(res.ref)}[/bold green] -> [cyan]{_safe_text(res.out_dir)}[/cyan] "
|
|
130
|
+
f"(runtime: {res.runtime_seconds}s, GPU-hrs: {res.gpu_hours_recorded})"
|
|
131
|
+
)
|
|
132
|
+
if res.files:
|
|
133
|
+
table = Table(title="Working Directory Output Files")
|
|
134
|
+
table.add_column("File", style="cyan")
|
|
135
|
+
table.add_column("Size (bytes)", justify="right")
|
|
136
|
+
table.add_column("Downloaded")
|
|
137
|
+
for f in res.files:
|
|
138
|
+
table.add_row(
|
|
139
|
+
_safe_text(f.file_name),
|
|
140
|
+
str(f.size_bytes) if f.size_bytes is not None else "?",
|
|
141
|
+
"[green]Yes[/green]" if f.downloaded else f"[red]Skipped[/red] ({_safe_text(f.skipped_reason)})",
|
|
142
|
+
)
|
|
143
|
+
console.print(table)
|
|
144
|
+
|
|
145
|
+
if res.stdout_tail:
|
|
146
|
+
console.print(Panel(_safe_text(res.stdout_tail.strip()), title="Stdout (Tail)", border_style="blue"))
|
|
147
|
+
if res.stderr_tail.strip():
|
|
148
|
+
console.print(Panel(_safe_text(res.stderr_tail.strip()), title="Stderr (Tail)", border_style="yellow"))
|
|
149
|
+
return 0
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def cmd_list(args: argparse.Namespace) -> int:
|
|
153
|
+
client = KaggleGPUClient()
|
|
154
|
+
mine = not (args.user or args.search) or args.mine
|
|
155
|
+
items = client.list_kernels(
|
|
156
|
+
mine=mine,
|
|
157
|
+
user=args.user,
|
|
158
|
+
search=args.search,
|
|
159
|
+
page_size=args.page_size,
|
|
160
|
+
)
|
|
161
|
+
if args.json:
|
|
162
|
+
print(json.dumps(items, indent=2))
|
|
163
|
+
return 0
|
|
164
|
+
|
|
165
|
+
table = Table(title="Kaggle Kernels")
|
|
166
|
+
table.add_column("Ref (owner/slug)", style="cyan")
|
|
167
|
+
table.add_column("Title")
|
|
168
|
+
table.add_column("Author")
|
|
169
|
+
table.add_column("Last Run (UTC)")
|
|
170
|
+
for item in items:
|
|
171
|
+
table.add_row(
|
|
172
|
+
_safe_text(item["ref"]),
|
|
173
|
+
_safe_text(item["title"]),
|
|
174
|
+
_safe_text(item["author"]),
|
|
175
|
+
_safe_text(item["last_run_time"]),
|
|
176
|
+
)
|
|
177
|
+
console.print(table)
|
|
178
|
+
return 0
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
def cmd_delete(args: argparse.Namespace) -> int:
|
|
182
|
+
client = KaggleGPUClient()
|
|
183
|
+
confirmed = args.yes
|
|
184
|
+
if not confirmed:
|
|
185
|
+
console.print(
|
|
186
|
+
f"[bold red]WARNING:[/bold red] Deleting kernel [cyan]{_safe_text(args.ref)}[/cyan] is "
|
|
187
|
+
"[bold]PERMANENT and UNRECOVERABLE[/bold]."
|
|
188
|
+
)
|
|
189
|
+
ans = input(f"Type '{args.ref}' to confirm permanent deletion: ").strip()
|
|
190
|
+
if ans != args.ref:
|
|
191
|
+
console.print("[yellow]Deletion aborted.[/yellow]")
|
|
192
|
+
return 1
|
|
193
|
+
confirmed = True
|
|
194
|
+
|
|
195
|
+
res = client.delete_kernel(args.ref, confirm=confirmed)
|
|
196
|
+
if args.json:
|
|
197
|
+
print(json.dumps(res, indent=2))
|
|
198
|
+
return 0 if res.get("deleted") else 1
|
|
199
|
+
|
|
200
|
+
if res.get("deleted"):
|
|
201
|
+
console.print(f"[green]Deleted kernel {_safe_text(args.ref)}.[/green]")
|
|
202
|
+
return 0
|
|
203
|
+
console.print(f"[red]{_safe_text(res.get('message'))}[/red]")
|
|
204
|
+
return 1
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def cmd_quota(args: argparse.Namespace) -> int:
|
|
208
|
+
client = KaggleGPUClient()
|
|
209
|
+
if args.sync_used_gpu_hours is not None:
|
|
210
|
+
client.quota_ledger.record_manual_adjustment(
|
|
211
|
+
gpu_hours_used=args.sync_used_gpu_hours,
|
|
212
|
+
note="CLI manual quota sync",
|
|
213
|
+
)
|
|
214
|
+
est = client.quota_estimate()
|
|
215
|
+
if args.json:
|
|
216
|
+
print(json.dumps(est, indent=2))
|
|
217
|
+
return 0
|
|
218
|
+
|
|
219
|
+
console.print(
|
|
220
|
+
Panel(
|
|
221
|
+
f"Weekly Budget: [bold]{est['weekly_budget_gpu_hours']} GPU-hours[/bold] (rolling 7-day window)\n"
|
|
222
|
+
f"T4 x2 Multiplier: [bold]{est['t4_x2_multiplier']}x[/bold] (2 GPU-hours per wall-clock hour)\n"
|
|
223
|
+
f"Estimated Used (7d): [yellow]{est['estimated_gpu_hours_used']} GPU-hours[/yellow] "
|
|
224
|
+
f"({est['estimated_wall_hours_used_t4_x2']} wall-hours on T4 x2)\n"
|
|
225
|
+
f"Estimated Remaining: [green]{est['estimated_gpu_hours_remaining']} GPU-hours[/green] "
|
|
226
|
+
f"(~{est['estimated_wall_hours_remaining_t4_x2']} wall-hours on T4 x2)\n"
|
|
227
|
+
f"Single Session Cap: {est['single_session_cap_hours']} hours\n\n"
|
|
228
|
+
f"[dim]{est['notice']}[/dim]",
|
|
229
|
+
title="Kaggle Free-GPU Quota Estimate",
|
|
230
|
+
border_style="cyan",
|
|
231
|
+
)
|
|
232
|
+
)
|
|
233
|
+
return 0
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
237
|
+
parser = argparse.ArgumentParser(
|
|
238
|
+
prog="kaggle-free-gpu",
|
|
239
|
+
description="Run GPU workloads on Kaggle's free Tesla T4 x2 GPUs from the terminal or any coding agent.",
|
|
240
|
+
)
|
|
241
|
+
sub = parser.add_subparsers(dest="command", required=True)
|
|
242
|
+
|
|
243
|
+
# push
|
|
244
|
+
p_push = sub.add_parser("push", help="Validate and push a kernel folder to Kaggle GPU")
|
|
245
|
+
p_push.add_argument("dir", type=Path, help="Folder containing kernel-metadata.json and script")
|
|
246
|
+
p_push.add_argument("--wait", action="store_true", help="Poll status until COMPLETE or ERROR")
|
|
247
|
+
p_push.add_argument("--poll-interval", type=float, default=10.0, help="Seconds between status polls")
|
|
248
|
+
p_push.add_argument("--out-dir", type=Path, default=None, help="Download output to this folder once complete")
|
|
249
|
+
p_push.add_argument("--allow-mismatch", action="store_true", help="Bypass Gotcha #1 slug mismatch guard (for testing)")
|
|
250
|
+
p_push.add_argument("--json", action="store_true", help="Output raw JSON")
|
|
251
|
+
p_push.set_defaults(func=cmd_push)
|
|
252
|
+
|
|
253
|
+
# status
|
|
254
|
+
p_status = sub.add_parser("status", help="Check kernel execution status (QUEUED/RUNNING/COMPLETE/ERROR)")
|
|
255
|
+
p_status.add_argument("ref", help="Kernel reference (<owner>/<title-derived-slug>)")
|
|
256
|
+
p_status.add_argument("--wait", action="store_true", help="Poll status until COMPLETE or ERROR")
|
|
257
|
+
p_status.add_argument("--poll-interval", type=float, default=10.0, help="Seconds between status polls")
|
|
258
|
+
p_status.add_argument("--json", action="store_true", help="Output raw JSON")
|
|
259
|
+
p_status.set_defaults(func=cmd_status)
|
|
260
|
+
|
|
261
|
+
# output
|
|
262
|
+
p_out = sub.add_parser("output", help="Download kernel output files and execution logs")
|
|
263
|
+
p_out.add_argument("ref", help="Kernel reference (<owner>/<title-derived-slug>)")
|
|
264
|
+
p_out.add_argument("--out-dir", type=Path, default=Path("./outputs"), help="Destination directory")
|
|
265
|
+
p_out.add_argument("--max-size-mb", type=int, default=500, help="Skip files larger than this size in MB")
|
|
266
|
+
p_out.add_argument("--force-large", action="store_true", help="Download files even if they exceed --max-size-mb")
|
|
267
|
+
p_out.add_argument("--json", action="store_true", help="Output raw JSON")
|
|
268
|
+
p_out.set_defaults(func=cmd_output)
|
|
269
|
+
|
|
270
|
+
# list
|
|
271
|
+
p_list = sub.add_parser("list", help="List Kaggle kernels")
|
|
272
|
+
p_list.add_argument("--mine", action="store_true", help="List your own kernels (default if no user/search)")
|
|
273
|
+
p_list.add_argument("--user", default=None, help="Filter by Kaggle username")
|
|
274
|
+
p_list.add_argument("--search", default=None, help="Search query")
|
|
275
|
+
p_list.add_argument("--page-size", type=int, default=20, help="Results per page")
|
|
276
|
+
p_list.add_argument("--json", action="store_true", help="Output raw JSON")
|
|
277
|
+
p_list.set_defaults(func=cmd_list)
|
|
278
|
+
|
|
279
|
+
# delete
|
|
280
|
+
p_del = sub.add_parser("delete", help="Permanently delete a Kaggle kernel (requires confirmation)")
|
|
281
|
+
p_del.add_argument("ref", help="Kernel reference (<owner>/<title-derived-slug>)")
|
|
282
|
+
p_del.add_argument("--yes", action="store_true", help="Confirm permanent deletion without interactive prompt")
|
|
283
|
+
p_del.add_argument("--json", action="store_true", help="Output raw JSON")
|
|
284
|
+
p_del.set_defaults(func=cmd_delete)
|
|
285
|
+
|
|
286
|
+
# quota
|
|
287
|
+
p_quota = sub.add_parser("quota", help="Estimate rolling 7-day GPU quota from local history")
|
|
288
|
+
p_quota.add_argument("--sync-used-gpu-hours", type=float, default=None, help="Record manual GPU hours used")
|
|
289
|
+
p_quota.add_argument("--json", action="store_true", help="Output raw JSON")
|
|
290
|
+
p_quota.set_defaults(func=cmd_quota)
|
|
291
|
+
|
|
292
|
+
return parser
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
def main() -> None:
|
|
296
|
+
parser = build_parser()
|
|
297
|
+
args = parser.parse_args()
|
|
298
|
+
try:
|
|
299
|
+
rc = args.func(args)
|
|
300
|
+
sys.exit(rc)
|
|
301
|
+
except (KaggleAuthError, KaggleAPIError, FileNotFoundError, ValueError) as exc:
|
|
302
|
+
console.print(f"[bold red]Error:[/bold red] {_safe_text(exc)}")
|
|
303
|
+
sys.exit(1)
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
if __name__ == "__main__":
|
|
307
|
+
main()
|
|
308
|
+
|