.agent/coding_conventions.md

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