Spaces:
Running
Running
File size: 2,821 Bytes
95cbc5b | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 | ## Coding conventions (enforced under deadline pressure)
This repo is optimized for: **correctness, reproducibility, and not leaking labels**. Read `architecture.md` first.
## Python style (hard rules)
- **Typed dataclasses everywhere** for public API shapes (actions/observations/state).
- Use `@dataclass(frozen=True, slots=True)` by default.
- Public functions must be type-annotated end-to-end.
- **No untyped dicts in public APIs.** Dicts are allowed only internally (e.g., during XML parse), and must be converted to dataclasses at the boundary.
- Keep functions small. Prefer pure functions (`reward.py`) with no hidden state.
## Import ordering
1. stdlib
2. third-party
3. local modules
Within a section: alphabetical. One import per line if it improves diff clarity.
## Docstrings and naming
- Docstrings: short, imperative, include constraints (e.g., must not leak ground truth).
- Names: explicit over clever (`compute_reward`, `parse_action_xml`, `EpisodeState`).
## Error handling patterns
- **Never crash on model output.** Malformed actions must be handled gracefully.
- Raise exceptions only for programmer errors; user/model errors return structured error fields.
- Every boundary (HTTP handlers, XML parser) must be defensive:
- validate inputs
- clamp budgets
- return safe defaults
## Forbidden patterns (do not do these)
- **No LLM-as-judge in reward.** Reward must be verifiable (dataset truth + keyword checks). See `architecture.md`.
- **No label leakage**: do not log, return, or print ground truth in observations, HTTP responses, or debug endpoints.
- **No hardcoded local paths** (e.g., `C:\\Users\\...`, `/home/...`). Use repo-relative paths + `pathlib`.
- **No committing data files > 5MB** without explicit team sign-off. (If necessary, use HF Datasets or remote storage.)
- **No localStorage in any UI.** If you add UI later (unlikely), store state server-side or in-memory only.
- **No adding endpoints/features after scope freeze** (midnight Saturday).
## Repo hygiene
- Prefer CLI-driven ops so teammates can reproduce quickly:
- HF: `huggingface-cli`, `hf` (where available), `git lfs` if needed
- GCP: `gcloud`
- Keep logs minimal. Under hackathon pressure, noisy logs hide real bugs.
- Dont vendor big artifacts in git. Link them (video, wandb, Space) from README.
## Scope creep rule (non-negotiable)
If youre tempted to add a feature that isnt required for the locked deliverables:
- Append one bullet to `FUTURE_WORK.md` (with 1-line rationale).
- Return to your current task.
## Cross-reference
- Architecture contract: `architecture.md`
- Scope and fallbacks: `project_context.md`
- Locked decisions: `decision_log.md`
|