crunch-compete

# Cruncher Skill

Guides users through Crunch competition lifecycle: setup, quickstarter discovery, solution development, local testing, and submission.

## Prerequisites
- Python 3.9+ with `venv` module (included in standard Python)
- `pip` for package installation

## Package Installation

This skill installs Python packages from [PyPI](https://pypi.org) into isolated virtual environments:

| Package | Source | Purpose |
|---------|--------|---------|
| `crunch-cli` | [PyPI](https://pypi.org/project/crunch-cli/) | CrunchDAO competition CLI (setup, test, submit) |
| `jupyter` | [PyPI](https://pypi.org/project/jupyter/) | Notebook support (optional) |
| `ipykernel` | [PyPI](https://pypi.org/project/ipykernel/) | Jupyter kernel registration (optional) |
| Competition SDKs (e.g. `crunch-synth`, `birdgame`) | PyPI | Competition-specific libraries (varies) |

**Agent rules for package installation:**
- **Always use a virtual environment** — never install into system Python
- **Only install known packages** listed above or referenced in competition docs (PACKAGES.md)
- **Ask the user before installing** any package not listed here
- **All packages are from PyPI** — no custom URLs, no `--index-url` overrides, no `.whl` files from unknown sources


## Credentials

### Submission Token (required for setup & submit)
- **How to get:** User logs into [CrunchDAO Hub](https://hub.crunchdao.com), navigates to the competition's submit page (`/competitions/<competition>/submit`), and copies their token
- **How it's used:** Passed once via `--token <TOKEN>` during `crunch setup`
- **Persistence:** After setup, the CLI stores the token in the project's `.crunch/` config directory. All subsequent commands (`crunch test`, `crunch push`, `crunch download`) authenticate automatically — no need to pass the token again
- **If token expires:** Run `crunch update-token` inside the project directory to refresh it

**Agent rules for tokens:**
- **Always ask the user** to provide the token — never assume, guess, or reuse tokens from other projects
- **Never write tokens** into source files, scripts, notebooks, or any committed file
- **Never log or echo tokens** in shell output (use `--token <TOKEN>` placeholder in examples shown to user)
- Tokens are user-specific and project-scoped — each `crunch setup` call requires the user to supply one

### GitHub API (optional, unauthenticated)
- Used only for browsing quickstarter listings via `api.github.com` (public repo, no auth needed)
- Rate-limited to 60 requests/hour per IP; sufficient for normal use

## Network Access

| Operation | Requires network | Endpoint |
|-----------|-----------------|----------|
| `crunch setup` | Yes | hub.crunchdao.com |
| `crunch push` | Yes | hub.crunchdao.com |
| `crunch download` | Yes | hub.crunchdao.com |
| `crunch test` | **No** | Local only |
| `crunch list` | Yes | hub.crunchdao.com |
| `pip install` | Yes | pypi.org |
| Quickstarter browsing | Yes | api.github.com |

## Quick Setup

**Each competition needs its own virtual environment** (dependencies can conflict).

```bash
mkdir -p ~/.crunch/workspace/competitions/<competition>
cd ~/.crunch/workspace/competitions/<competition>
python -m venv .venv && source .venv/bin/activate 
pip install crunch-cli jupyter ipykernel --upgrade --quiet --progress-bar=off
python -m ipykernel install --user --name <competition> --display-name "Crunch - <competition>"

# Get token from: https://hub.crunchdao.com/competitions/<competition>/submit
crunch setup <competition> <project-name> --token <TOKEN>
cd <competition>-<project-name>
```

For competition-specific packages and full examples, see [references/competition-setup.md](references/competition-setup.md).

## Core Workflow

### 1. Discover
```bash
crunch list                    # List competitions
```


### 2. Explain
Read the quickstarter code (`main.py` or notebook) and competition's SKILL.md/README.md. Provide walkthrough covering: Goal, Interface, Data flow, Approach, Scoring, Constraints, Limitations, Improvement ideas.

### 3. Propose Improvements
Analyze current approach, cross-reference competition docs (SKILL.md, LITERATURE.md, PACKAGES.md), generate concrete code suggestions:
- Model: mixture densities, NGBoost, quantile regression, ensembles
- Features: volatility regimes, cross-asset correlation, seasonality
- Architecture: online learning, Bayesian updating, horizon-specific models

### 4. Test
```bash
crunch test                    # Test solution locally
```

### 5. Submit
```bash
crunch test                    # Always test first
crunch push -m "Description"   # Submit
```

## Phrase Mapping

| User says | Action |
|-----------|--------|
| `what competitions are available` | `crunch list` |
| `show quickstarters for <name>` | Fetch from GitHub API |
| `set up <competition>` | Full workspace setup |
| `download the data` | `crunch download` |
| `get the <name> quickstarter` | `crunch quickstarter --name` |
| `explain this quickstarter` | Structured code walkthrough |
| `propose improvements` | Analyze and suggest code improvements |
| `test my solution` | `crunch test` |
| `compare with baseline` | Run both, side-by-side results |
| `submit my solution` | `crunch push` |

## Important Rules

- Entrypoint must be `main.py` (default for `crunch push`/`crunch test`)
- Model files go in `resources/` directory
- Respect competition interface and constraints (time limits, output format)
- Ask before installing new packages

## Reference

- CLI commands: [references/cli-reference.md](references/cli-reference.md)
- Setup examples: [references/competition-setup.md](references/competition-setup.md)