Metadata-Version: 2.5
Name: kagglex
Version: 0.2.0
Summary: Execute local Python code, modules, and experiments seamlessly on Kaggle GPUs.
Project-URL: Homepage, https://github.com/Hari31416/kagglex
Project-URL: Repository, https://github.com/Hari31416/kagglex
Project-URL: Issues, https://github.com/Hari31416/kagglex/issues
Author-email: Harikesh Kushwaha <harikeshkumar0926@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Harikesh Kushwaha
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cli,deep-learning,gpu,kaggle,machine-learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: kaggle>=1.6.0
Requires-Dist: pathspec>=0.11.0
Requires-Dist: requests>=2.28.0
Requires-Dist: websocket-client>=1.7.0
Description-Content-Type: text/markdown

# kagglex

Execute local Python code, modules, and experiments seamlessly on Kaggle GPUs and TPUs.

## Overview

`kagglex` enables machine learning practitioners and researchers to transparently package and dispatch local Python code, standalone scripts, or complete packages to Kaggle's cloud GPU and TPU environments without tedious manual uploading or notebook maintenance.

## Features

- Flexible project detection for standalone scripts, flat packages, or `src/` layout projects
- Pre-flight validation with local AST syntax checking and credential verification
- Automatic ignore filtering powered by `pathspec` supporting `.gitignore` and `.kaggleignore`
- Dual-tier packaging preventing bloated uploads and base64 truncation
- Automated multi-GPU execution using `torchrun`
- Secure Kaggle Secrets integration for WandB, HuggingFace, and custom credentials
- Local experiment history repository for tracking past runs, statuses, and durations
- Interactive REPL execution on active Kaggle notebooks via Jupyter proxy URL
- Programmatic Python SDK alongside the `kagglex` CLI

## Installation

Install via uv or pip:

```bash
uv pip install kagglex
```

## CLI Usage

### Run a Standalone Script

```bash
kagglex run --file train.py --gpu t4-2x --title "Pilot Training"
```

### Run a Module with Multi-GPU

```bash
kagglex run "python -m mypkg.train --epochs 10" --gpu t4-2x --multi-gpu
```

### Stream Remote Logs in Real-Time

```bash
kagglex run "python train.py" --stream
```

### List Recent Runs

```bash
kagglex list
```

### Check Status or Cancel a Run

```bash
kagglex status my-experiment
kagglex cancel my-experiment
```

### Pull Downloaded Outputs

```bash
kagglex pull my-experiment --output-dir ./results --include-outputs "*.json" "checkpoints/*"
```

### Push a Kaggle Dataset

```bash
kagglex dataset push --data-dir ./data/embeddings --title "Embeddings Dataset"
```

### Interactive REPL on Running Kaggle Notebooks

When a notebook is already open in Kaggle, copy its proxy URL (`Run -> Kaggle Jupyter Server -> Copy URL`) and run commands with sub-second feedback:

```bash
# Verify connection
kagglex exec --url "https://kkb-production.jupyter-proxy.kaggle.net?token=..." --test

# Query remote GPU status
kagglex exec --url "https://kkb-production.jupyter-proxy.kaggle.net?token=..." --gpu-info

# Execute inline Python snippets
kagglex exec "import torch; print(torch.cuda.device_count())"

# Execute a local Python file remotely
kagglex exec --file evaluate.py

# List and transfer files
kagglex exec --list-files
kagglex exec --upload ./checkpoint.pt
kagglex exec --download run_results.json -o ./local_results.json
```

Alternatively, set the environment variable:

```bash
export KAGGLE_JUPYTER_URL="https://kkb-production.jupyter-proxy.kaggle.net?token=..."
```

## Python SDK Usage

```python
from kagglex import KaggleRunner, RunConfig

runner = KaggleRunner()
job = runner.run(
    command="python -m mypkg.train --batch-size 64",
    title="Fine Tuning Run",
    gpu="t4-2x",
    multi_gpu=True,
    wait=True,
)

print(f"Status: {job.status}")
job.pull_outputs(destination_dir="./results")
```
