reyden009/speculative-decoding-lab

1# AGENTS.md — Rules for agents (and humans) working in this repo2 3This repository is a **research project** with a master plan and reproducible4protocol. Before touching code or experiments, read this completely.5 6## 1. Context in one sentence7 8Empirical study of modern speculative decoding (EAGLE-3/DFlash/DSpark) on an9RTX 4060 Ti 16 GB with Gemma 4 12B and Qwen3-8B GGUF: acceptance by domain,10quantization and hardware break-even. The research documentation (thesis, gaps,11plan) lives locally in `docs/` (not versioned); live status is ALWAYS in12`STATUS.md` (local, not versioned).13 14## 2. Conventions15 16- **Language**: docs, logs and commit messages in **English**; code and17  technical metadata in **English**. Do not mix languages within one file.18- **Documentation**: markdown and session logs in `docs/`, live status in19  `STATUS.md` — all local, **not versioned**. The corpus `papers/` and its20  notes `notes/` are not versioned (regenerated locally with a download script,21  outside the repo).22- **Environment**: activate with `source scripts/spec-env.sh` (uv + CUDA in23  `~/cuda`). Never install anything with sudo; if privileges are needed, ask24  uli and wait.25- **Minimum quality before commit**: `ruff check`, `ruff format --check`,26  `pyright` with no errors on what you touched.27 28## 3. Git rules29 30- **Logical commits** (never a mega-commit); concise messages in English with a31  type prefix (`docs:`, `chore:`, `feat:`, `fix:`).32- **Do not version**: `models/`, `*.gguf`, `papers/`, `notes/`,33  `experiments/runs/`, `.venv/`, `.atl/` (see `.gitignore`).34- Do not commit regenerable artifacts (PDFs, raw runs, build logs).35- Before committing: `git status` + `git diff` to review what goes in.36 37## 4. Experiments (Phase 1+)38 39- **Never** launch a run without a viable `--resume` (incremental JSONL) unless40  explicitly decided.41- Follow the master plan protocol (§4): fixed seeds (42), documented temperature,42  target-only baseline with the SAME quantization, config.json + metrics.json per43  run in `experiments/runs/<id>/`.44- **Do not** use the full DeepSpec data cache (~38 TB); only subsamples.45- Do not change the master plan targets/decisions (§10) without uli's approval.46 47## 5. Sessions and handoff (mandatory)48 49At the end of any work session:50 511. Write the session log at `docs/logs/YYYY-MM-DD-sesion-NN-asunto.md` (local52   logbook, not versioned: what was done, decisions, pending items, what is53   still running).542. Update `STATUS.md` (local, not versioned: current phase, what is running,55   pending, next steps).563. Save in engram (`mem_save`/`mem_session_summary`) non-obvious decisions and57   discoveries (project: `spectulative_decoding`).584. If background processes remain (downloads, builds, runs): note them in59   STATUS.md (local) with PID and log.60 61A new agent opening the repo should read: `AGENTS.md` → (local `STATUS.md`,62docs and logs) before acting.63 64## 6. Forbidden / careful65 66- **Forbidden**: sudo without notice; versioning models/PDFs/runs; using the67  38 TB cache; modifying raw results; deleting another session's68  `experiments/runs/`.69- **Careful**: recompiling llama.cpp without noting the exact commit; changing70  the overnight/resume regime; discarding speedup < 1 results (they are valid71  data, not errors).72