Metadata-Version: 2.5
Name: kag
Version: 0.2.2
Summary: Kaggle competition bootstrapper TUI - get right into the data
Project-URL: Homepage, https://github.com/Andrew-Girgis/kag
Project-URL: Repository, https://github.com/Andrew-Girgis/kag
Project-URL: Issues, https://github.com/Andrew-Girgis/kag/issues
Author: Andrew Girgis
License-Expression: MIT
License-File: LICENSE
Keywords: cli,data-science,kaggle,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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 :: Software Development :: User Interfaces
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.13.0
Requires-Dist: kaggle>=2.2
Requires-Dist: markdownify>=1.2.0
Requires-Dist: packaging>=24.0
Requires-Dist: requests>=2.32.0
Requires-Dist: rich>=15.0.0
Requires-Dist: textual>=8.2.3
Description-Content-Type: text/markdown

# kag - fresh Kaggle competition workspaces from your terminal

[![PyPI](https://img.shields.io/pypi/v/kag.svg)](https://pypi.org/project/kag/)
[![Python Versions](https://img.shields.io/pypi/pyversions/kag.svg)](https://pypi.org/project/kag/)

`kag` is a Textual TUI inspired by [`try`](https://github.com/tobi/try), built for Kaggle workflows.

It helps you go from "I want to work on this competition" to a ready folder with data, notebook, notes, and editor open.

## Demo

Asciinema walkthrough placeholder: `docs/demo-placeholder.md`

Planned recording file path: `docs/demo.cast`

## What kag does

- Shows a searchable competition picker with sections:
  - `Your notebooks` (local projects in `KAG_PATH`)
  - `Joined competitions`
  - `All competitions`
- Uses paginated loading for competitions (`20` per page) and auto-loads more when you reach the end.
- Scaffolds a project folder:
  - `data/` (download + extract) with `data/SCHEMA.md` describing each file's columns
  - `<competition>.ipynb`
  - `notes.md` (overview, evaluation, data description, rules, and top notebooks from Kaggle)
  - `AGENTS.md` and `CLAUDE.md` so coding agents start with the metric, submission format, and limits
  - `.kag/competition.json` (machine-readable competition metadata)
  - `pyproject.toml` listing the Python packages, and a `.venv` with them installed once you agree (see [Python environment](#python-environment))
  - `git init` (optional)
- Checks competition access before download and opens browser tabs for `overview` + `rules` when acceptance is needed.
- Fills `notes.md` from Kaggle's official competition pages (`Overview`, `Evaluation`, `Data`, `Code`, `Rules`).

## Installation

`kag` is published on PyPI and installs as a global terminal command.

### Recommended: uv

```bash
uv tool install kag
```

### Alternative: pipx

```bash
pipx install kag
```

### Fallback: pip

```bash
python -m pip install kag
```

Validate your install:

```bash
kag --version
kag doctor
```

For development from this repository:

```bash
uv sync
uv run kag doctor
```

Maintainer release planning lives in [`docs/release.md`](docs/release.md).

## Setup guide

### 1. Install kag

```bash
uv tool install kag
```

### 2. Sign in to Kaggle

kag installs the Kaggle CLI and library for you (Python 3.11+); there is nothing else to install. Sign in once in your browser:

```bash
kag login
```

This runs the Kaggle CLI bundled with kag (`kaggle auth login`) and caches credentials in `~/.kaggle/`. You don't need a separate `kaggle` command: `kag kaggle <args>` runs the bundled CLI (for example `kag kaggle competitions submit -c titanic -f submission.csv -m "first try"`). Other ways to authenticate also work:
- API token: `KAGGLE_API_TOKEN`, or the token saved to `~/.kaggle/access_token`
- Legacy: `KAGGLE_USERNAME` + `KAGGLE_KEY`, or `~/.kaggle/kaggle.json` containing `username` and `key`

### 3. Verify your environment

```bash
kag doctor
```

Fix any `FAIL` rows before starting a competition workspace.

### 4. Choose where projects are created

By default, `kag` creates projects in `~/Kaggle`. Set `kag_path` in the optional config file, `~/.kag_config.toml`:

```toml
kag_path = "~/Kaggle"     # ~ and $VARIABLES are expanded
default_editor = "code"   # highlighted first in the editor picker: code, cursor, zed, windsurf or jupyter
auto_git = true
```

If the file can't be read, kag says so when it starts and uses the defaults; `kag doctor` shows the problem too.

Or set `KAG_PATH` for one shell or session:

```bash
export KAG_PATH=~/Kaggle
```

Environment variables (`KAG_PATH`, `KAG_THEME`, `KAG_UPDATE_CHECK`) take priority over `~/.kag_config.toml`, which takes priority over the defaults.

#### Colours and themes

By default kag uses your terminal's own colours, with no background fill, so a transparent, blurred or themed terminal background shows through. Change it in `~/.kag_config.toml` or with `KAG_THEME`, which takes priority:

```toml
theme = "terminal"     # default: your terminal's background and 16-colour palette
# theme = "kag"        # kag's dark look
# theme = "nord"       # or any built-in Textual theme: gruvbox, dracula, tokyo-night,
                       # catppuccin-mocha, rose-pine, solarized-light, ...
```

You can also press `Ctrl+P` in kag and choose **Theme** to try themes live; the one you pick is saved to `~/.kag_config.toml`. An unknown name falls back to `terminal` with a warning, and `kag doctor` shows the active theme. kag respects [`NO_COLOR`](https://no-color.org).

#### Python environment

Every new project gets a `pyproject.toml` listing its Python packages. Installing them downloads and runs code from PyPI, so by default kag shows you the list and asks first (the default answer is No). Every part of this can be changed in the `[environment]` section of `~/.kag_config.toml`; these are the defaults:

```toml
[environment]
create = true          # false: no pyproject.toml or .venv (the older auto_venv = false also works)
install = "ask"        # "ask" shows the list and asks y/N; "always" installs; "never" only writes pyproject.toml
python = ""            # e.g. "3.12"; empty uses uv's default
packages = ["pandas", "numpy", "matplotlib", "seaborn", "scikit-learn", "ipykernel"]
command = []           # replace the install step, e.g. ["pixi", "install"]
```

kag installs with `uv sync`, or with `python -m venv` plus `pip` if `uv` isn't on your PATH. Output goes to `.kag/logs/environment.log`. If you skip the install, or it fails, kag still creates the project and tells you the command to run later. An existing `pyproject.toml` or `.venv` is never replaced, and kag only installs a `pyproject.toml` it wrote itself and you haven't edited. For any other `pyproject.toml`, kag installs nothing and tells you to run `uv sync` yourself (a custom `command` still runs).

### 5. Start using kag

```bash
kag
kag titanic
```

Optional shell integration lets `kag` automatically `cd` into the selected project directory:

```bash
eval "$(kag init)"
```

## Quick start

```bash
kag login            # sign in to Kaggle (first time only)
kag                  # open the competition picker
kag titanic          # open the picker searching for "titanic"
kag new titanic      # create a workspace without the TUI
```

## Commands

Commands are words; options such as `--force` or `--json` modify them.

```bash
kag [query]                  # open the picker, optionally searching
kag search <query>           # same, and works for words like "new" or "login"
kag new <competition>        # create a workspace without the TUI (see below)
kag login [--force]          # sign in to Kaggle in your browser
kag doctor [--json]          # check your environment
kag init                     # print shell integration that cds into new projects
kag kaggle <args>            # run the Kaggle CLI bundled with kag
kag --help                   # help (also `kag <command> --help`)
kag --version                # installed version
```

A bare query searches unless its first word is a command name; use `kag search <query>` to search for "new", "login", and so on. `kag --help` works without Kaggle authentication. The older `kag --doctor` and `kag --init` forms still work.

## For scripts and AI agents: `kag new`

`kag new` builds the same workspace as the TUI without any prompts, which makes it usable from scripts and coding agents:

```bash
kag new titanic --json                  # create ~/Kaggle/titanic and print a JSON result
kag new titanic --json --no-download    # metadata, notes, and agent files only
kag new titanic --json --force          # existing folder: add missing files (never overwrites)
```

Options: `--no-download`, `--no-git`, `--no-venv`, `--install`, `--editor NAME`, `--force`, `--json`. Progress goes to stderr; the result goes to stdout.

`kag new` can't ask before installing packages. With the default `install = "ask"`, it writes `pyproject.toml`, skips the install, and reports `"environment": {"status": "not_installed", "packages": [...], "install_command": "uv sync"}` so the agent can ask you first. `--install` agrees for that run, and `install = "always"` agrees every time.

| Status | Exit code | Meaning |
|---|---|---|
| `created` / `updated` | 0 | Workspace ready. `next_steps` says where to start (`AGENTS.md`). |
| `error` | 1 | Something failed; see `message`. |
| `needs_join` | 3 | Join the competition and accept its rules at `url` (a human has to click), then rerun. |
| `exists` | 4 | The folder already exists; rerun with `--force` to add missing files. |
| `cancelled` | 130 | Interrupted with Ctrl-C; changes were rolled back. |

Every project includes `AGENTS.md` (plus a `CLAUDE.md` that imports it) and `.kag/competition.json`, so an agent starts with the metric, submission template, and daily submission limit. When data is downloaded, `data/SCHEMA.md` (kept local with the data, not committed) adds per-file column schemas; with `--no-download`, `files.schema` is `null` until a later `kag new --force` downloads the data.

## How it works

1. Open picker (`kag`)
2. Search and select competition or local project
3. If needed, choose download and editor
4. `kag` verifies competition access before download
5. Project is scaffolded and opened
6. If the `kag init` shell hook is installed, your shell `cd`s into the project

## Search behavior

Search is currently case-insensitive substring filtering over competition slug/title and local project names.

## Troubleshooting

Run:

```bash
kag doctor
```

It checks:

- `kag` on PATH
- bundled Kaggle CLI + auth status
- API probe (`kaggle competitions list --page-size 1`)
- shell hook presence
- writable directories
- detected editors

If you pick Jupyter Lab (or another editor) when creating a project, its output is written to `.kag/logs/<editor>.log` inside the project. On a headless or SSH session, find the Jupyter server URL and token there, or run `jupyter server list`.

## Current limitations

- Competition join/terms acceptance is browser-assisted (not a direct Kaggle CLI command).
- Notes extraction depends on Kaggle page APIs/content shape and may vary by competition.
- Search is substring-based (not fuzzy-ranked yet).

## License

MIT
