ViperEkura
4de42d83c2
- Replace argparse with click in all scripts (train, server, generate, preprocess, benchmark) - Add --config YAML support to train.py with CLI flag override - Add --dry-run mode to validate config before training - Add type annotations throughout benchmark.py - Unify docstring format across all commands - Remove redundant deps httpx, requests, pyyaml, rich from pyproject.toml - Net -346 lines while adding YAML config support
73 lines
2.9 KiB
Markdown
73 lines
2.9 KiB
Markdown
# AGENTS.md — AstrAI Development Guide
|
||
|
||
## Quick commands
|
||
|
||
```bash
|
||
# Lint + format (only files you touched)
|
||
ruff check --fix scripts/tools/train.py ...
|
||
ruff format scripts/tools/train.py ...
|
||
|
||
# Full-project format check (CI gate)
|
||
ruff format --check .
|
||
|
||
# Tests
|
||
python -m pytest tests/ -x -q # quick, stop on first failure
|
||
python -m pytest tests/ -v # CI mode
|
||
|
||
# Install dev deps
|
||
pip install .[dev] # includes pytest, ruff, httpx2
|
||
```
|
||
|
||
## CI gates
|
||
|
||
- **Lint CI**: only `ruff format --check .` + `ruff check . --select I` (import-order only). Full `ruff check` is **not** enforced in CI.
|
||
- **Test CI**: `python -m pytest tests/ -v`, Python 3.12, CPU-only (no GPU agents).
|
||
- `scripts/eval/` has **978 pre-existing ruff violations** — ignore them in your changes.
|
||
|
||
## Script conventions (post-refactor)
|
||
|
||
All `scripts/tools/*.py` use **click** (not argparse):
|
||
- Each script defines a `*_command` click command (e.g. `train_command`, `server_command`).
|
||
- Can be run standalone: `python scripts/tools/train.py --config pretrain.yaml`
|
||
- Uses `"""One-line docstring."""` style matching the rest of the project.
|
||
|
||
## Train config
|
||
|
||
- Supports `--config pretrain.yaml` + CLI flag override (CLI wins).
|
||
- Supports `--dry-run` to validate without training.
|
||
- YAML sections map to CLI flag names directly (e.g. `training.batch_per_device` → `--batch_per_device`).
|
||
|
||
## .gitignore: deny-by-default
|
||
|
||
Everything is ignored by default (`*`), then whitelisted by patterns:
|
||
- `!astrai/**/*.py`, `!scripts/**/*.py`, `!tests/**/*.py`, `!csrc/**/*.{py,cu,h,cuh}`
|
||
- `!pyproject.toml`, `!setup.py`, `!README.md`, `!.github/**`
|
||
- New Python files in `astrai/`, `scripts/`, `tests/` get picked up automatically.
|
||
- New files at root or in other dirs need an explicit `!` rule.
|
||
|
||
## Dependencies
|
||
|
||
- `pyyaml` is declared in `pyproject.toml` (used by train.py `--config`), though it also comes transitively via `huggingface-hub`.
|
||
- `httpx2` is a **dev-only** dependency (required by `starlette.testclient` used in inference tests).
|
||
- CUDA extension (`csrc/kernels/`) builds only when `nvcc` is available; `pip install .` falls back gracefully on CPU.
|
||
|
||
## Environment
|
||
|
||
- Python 3.12+
|
||
- PyTorch 2.11 with cu128 (`extra-index-url` in pyproject.toml)
|
||
- 8×L20D (48GB) training setup with NV18 interconnect
|
||
|
||
## Project layout (key directories)
|
||
|
||
| Dir | Purpose |
|
||
|-----|---------|
|
||
| `astrai/` | Core library (model, trainer, dataset, inference, config) |
|
||
| `scripts/tools/` | CLI scripts (train, server, generate, preprocess, benchmark) |
|
||
| `scripts/eval/` | Evaluation scripts (pre-existing lint debt, not actively changed) |
|
||
| `csrc/kernels/` | Custom CUDA kernels (attention decode/prefill) |
|
||
| `tests/` | pytest suites, no GPU required |
|
||
| `data/pretrain_unified/` | Pretraining shards (.bin + meta.json per chunk) |
|
||
| `checkpoint/` | Training checkpoints (gitignored at runtime) |
|
||
| `params/` | Model params/tokenizer (gitignored at runtime) |
|
||
| `assets/docs/` | Documentation and design docs |
|