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.
@@ -0,0 +1,4 @@
1
+ """Kaggle Free-GPU MCP Server & CLI for Coding Agents."""
2
+
3
+ __version__ = "0.1.0"
4
+
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
+