crunch-compete

在参加 Crunch 竞赛时使用 - 设置工作区、探索快速入门、本地测试解决方案或提交参赛作品。

# 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)

---

## 中文说明

# Cruncher Skill

引导用户完成 Crunch 竞赛的完整生命周期：环境设置、quickstarter 探索、解决方案开发、本地测试和提交。

## 前置条件
- 带有 `venv` 模块的 Python 3.9+（标准 Python 已包含）
- 用于安装软件包的 `pip`

## 软件包安装

此技能会将来自 [PyPI](https://pypi.org) 的 Python 软件包安装到隔离的虚拟环境中：

| 软件包 | 来源 | 用途 |
|---------|--------|---------|
| `crunch-cli` | [PyPI](https://pypi.org/project/crunch-cli/) | CrunchDAO 竞赛 CLI（设置、测试、提交） |
| `jupyter` | [PyPI](https://pypi.org/project/jupyter/) | Notebook 支持（可选） |
| `ipykernel` | [PyPI](https://pypi.org/project/ipykernel/) | Jupyter 内核注册（可选） |
| 竞赛 SDK（例如 `crunch-synth`、`birdgame`） | PyPI | 竞赛专用库（各不相同） |

**代理软件包安装规则：**
- **始终使用虚拟环境** —— 绝不安装到系统 Python 中
- **仅安装已知软件包** —— 上面列出的或竞赛文档（PACKAGES.md）中引用的软件包
- **安装任何未列出的软件包前先询问用户**
- **所有软件包均来自 PyPI** —— 不使用自定义 URL，不使用 `--index-url` 覆盖，不使用来自未知来源的 `.whl` 文件


## 凭证

### 提交令牌（设置和提交时必需）
- **如何获取：** 用户登录 [CrunchDAO Hub](https://hub.crunchdao.com)，进入竞赛的提交页面（`/competitions/<competition>/submit`），并复制其令牌
- **如何使用：** 在 `crunch setup` 期间通过 `--token <TOKEN>` 传递一次
- **持久化：** 设置完成后，CLI 会将令牌存储在项目的 `.crunch/` 配置目录中。后续所有命令（`crunch test`、`crunch push`、`crunch download`）都会自动认证 —— 无需再次传递令牌
- **若令牌过期：** 在项目目录内运行 `crunch update-token` 进行刷新

**代理令牌规则：**
- **始终要求用户**提供令牌 —— 绝不假设、猜测或复用其他项目的令牌
- **绝不将令牌写入**源文件、脚本、notebook 或任何已提交的文件中
- **绝不在 shell 输出中记录或回显令牌**（在向用户展示的示例中使用 `--token <TOKEN>` 占位符）
- 令牌是用户专属且项目范围限定的 —— 每次 `crunch setup` 调用都需要用户提供一个

### GitHub API（可选，无需认证）
- 仅用于通过 `api.github.com` 浏览 quickstarter 列表（公共仓库，无需认证）
- 每个 IP 每小时限制 60 次请求；对于正常使用足够

## 网络访问

| 操作 | 是否需要网络 | 端点 |
|-----------|-----------------|----------|
| `crunch setup` | 是 | hub.crunchdao.com |
| `crunch push` | 是 | hub.crunchdao.com |
| `crunch download` | 是 | hub.crunchdao.com |
| `crunch test` | **否** | 仅本地 |
| `crunch list` | 是 | hub.crunchdao.com |
| `pip install` | 是 | pypi.org |
| Quickstarter 浏览 | 是 | api.github.com |

## 快速设置

**每个竞赛都需要自己的虚拟环境**（依赖可能冲突）。

```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>