Metadata-Version: 2.4
Name: caudex
Version: 0.4.0
Summary: Run Jupyter notebooks on Kaggle's GPUs from your terminal
Author-email: Sohanur Islam Shuvo <mdsohanurislamshuvo@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://pypi.org/project/caudex/
Project-URL: Changelog, https://pypi.org/project/caudex/#history
Keywords: kaggle,jupyter,notebook,gpu,cli,machine-learning
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9,>=8.2
Requires-Dist: kaggle<3,>=2.2.4
Requires-Dist: platformdirs<6,>=4
Requires-Dist: prompt_toolkit<4,>=3.0.40
Requires-Dist: rich<16,>=13
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pyinstaller>=6.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=6.1; extra == "dev"
Dynamic: license-file

# caudex

**Run your Jupyter notebooks on Kaggle's free GPUs, from your terminal.**

Write a notebook on your laptop, send it to Kaggle, watch it run, get your files back.
No browser tabs, no dropdown menus, no refreshing a page to see if it finished.

It uses **your own** Kaggle account and your own free weekly quota. Nothing goes through
anyone else's servers, and every file stays on your machine.

---

## Install

```bash
pip install caudex
```

You need **Python 3.11 or newer** and a free Kaggle account.

Works on **Windows**, **Linux**, and **macOS on Apple Silicon** (M1 and later).
Intel Macs are not supported — `pip` will say it cannot find a matching
distribution rather than installing something that does not run.

---

## Step 1 — connect your Kaggle account

You do this once.

```bash
caudex auth --setup
```

It will ask for your Kaggle **username** and an **API key**. To get the key:

1. Go to **kaggle.com**, click your profile picture → **Settings**
2. Scroll to **API** → click **Create New Token**
3. A file called `kaggle.json` downloads — open it in any text editor
4. Copy the two values into the prompt

Check it worked:

```bash
caudex whoami
```

---

## Step 2 — make a notebook project

```bash
caudex init train.ipynb
```

This creates a folder with a starter notebook inside it, and tells you where it is.
Open that notebook in Jupyter, VS Code, or whatever you normally use, and write your code.

**One thing to know:** anything you want to keep must be saved to `/kaggle/working/`.

```python
model.save("/kaggle/working/model.keras")
df.to_csv("/kaggle/working/scores.csv", index=False)
```

That folder is the only thing that comes back to you. Everything else on the Kaggle
machine disappears when the run ends.

---

## Step 3 — run it

```bash
caudex execute --gpu
```

That one command does the whole job: uploads your notebook, starts it on Kaggle, streams
the output to your screen as it happens, waits for it to finish, and downloads your files.

Leave off `--gpu` and it runs on a CPU instead — which **doesn't use any of your GPU
hours**, so it's the cheap way to check your code works before spending quota on it.

When it finishes you'll see where your files went, and a summary of how long each cell
took.

---

## The easier way: open the shell

Typing `caudex` on its own opens an interactive session:

```
 ██████╗ █████╗ ██╗   ██╗██████╗ ███████╗██╗  ██╗
██╔════╝██╔══██╗██║   ██║██╔══██╗██╔════╝╚██╗██╔╝
██║     ███████║██║   ██║██║  ██║█████╗   ╚███╔╝
██║     ██╔══██║██║   ██║██║  ██║██╔══╝   ██╔██╗
╚██████╗██║  ██║╚██████╔╝██████╔╝███████╗██╔╝ ██╗
 ╚═════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝

  0.4.0
  your-username  ·  GPU 12h left
  no project — try:  init train.ipynb
  /  commands    ^C  cancel    ^D  exit
```

Inside it you can drop the `caudex` prefix and the folder name — it remembers which
project you're working on:

```
> use ./my-experiment
> execute --gpu
> logs
```

Press **`/`** to see every command in a menu; arrow keys to pick one, Enter to accept it,
Enter again to run. **Ctrl-C** cancels whatever is running without closing the session.
**Ctrl-D** or `exit` leaves.

It remembers your history between sessions, and Tab completes commands, options and
file paths.

---

## Watching a long run

```bash
caudex ui
```

A live dashboard: your notebooks on the left, the current run's status and log tail on
the right, your remaining quota along the bottom. `j`/`k` to move, `Enter` to follow a
notebook's log, `q` to leave.

If you'd rather just tail the log:

```bash
caudex logs --follow
```

---

## Things you'll want sooner or later

| I want to… | Type this |
|---|---|
| See how much GPU time I have left | `caudex quota` |
| List my notebooks on Kaggle | `caudex notebooks` |
| Check on a run I stopped watching | `caudex status` |
| Read the log of a run that failed | `caudex logs` |
| Download the results again | `caudex pull` |
| Switch a project between CPU and GPU | `caudex runtime use gpu` |
| Find where my files are being saved | `caudex paths show` |
| Turn a `.py` script into a notebook | `caudex convert script.py` |
| Use a Kaggle dataset in my notebook | `caudex dataset attach owner/name` |

Add `--help` to anything for the full list of options.

---

## Where your files go

Run `caudex paths show` and it will tell you exactly. By default:

- **Your notebook projects** live wherever you made them
- **Results** come back to a folder per notebook, under your user directory
- **Your Kaggle token** sits in `~/.kaggle/kaggle.json` — the same file the official
  `kaggle` command uses, so the two work side by side

You can change where results land:

```bash
caudex paths set output_dir ~/kaggle-results
```

---

## If something goes wrong

**"Kaggle auth failed"** — your token has expired or been revoked. Make a new one at
kaggle.com → Settings → API → Create New Token, then run `caudex auth --setup` again.

**The run stops and says it timed out** — that means caudex gave up watching, *not* that
your notebook died. It is probably still running on Kaggle and still using your quota.
Check it with `caudex status`, or use `caudex execute --on-timeout cancel` next time if
you'd rather it stopped the run too.

**Your notebook produced no files** — anything you want back has to be written to
`/kaggle/working/`. Files written anywhere else are thrown away when the run ends.

**You ran out of GPU hours** — Kaggle gives you a fixed number per week and resets them
on a fixed day; `caudex quota` shows both. CPU runs don't touch that budget, so you can
keep working while you wait.

---

## Exit codes, for scripts

`0` worked · `1` failed · `2` you typed something wrong · `124` gave up waiting

`124` is deliberately not `1`: a run that outlives your patience is not a run that broke.

---

## Licence

Apache-2.0.
