English · Español

Style Guide

Per §0.2 of LYNX_CORTEX.md. This is the contract every phase's code, math, diagrams, and logs adhere to.

Code

• Python 3.11. Typed (typing), linted (ruff), formatted (ruff format), tested (pytest).
• Public functions and modules have docstrings; internal helpers can stay terse.
• No comments that restate the code. Reserve comments for non-obvious why — a hidden constraint, a subtle invariant, a workaround for a specific bug.
• Per-module README.md (under src/<module>/) covers: purpose, public API, design notes, performance notes.
• Imports: standard lib → third-party → local; alphabetized within group; ruff enforces this.

Math notation

• LaTeX in markdown notebooks; use $...$ inline and $$...$$ for displayed.
• Every formula has a one-line plain-English gloss directly beneath it.
• Vectors: lowercase bold \mathbf{x}. Matrices: uppercase bold \mathbf{A}. Tensors of rank ≥ 3: calligraphic \mathcal{T}.
• Indices: i, j, k for spatial; t, s for sequence position; b for batch; h for head.
• Probabilities: p for model, q for data (avoids the common p_model vs p_data ambiguity).

Diagrams

• Flow / architecture: mermaid (*.mmd), rendered to SVG and committed.
• Tensors / distributions / training curves: matplotlib, exported as PNG.
• Computation graphs: graphviz (*.dot), rendered to SVG.

Logs

• Structured JSON via structlog. One key per fact; no string-formatted blobs.
• From Phase 30 onward, also emit Prometheus exposition format for runtime metrics.

Reproducibility

• Every script accepts --seed, --log-dir, --config <yaml> (or uses sensible defaults).
• Every checkpoint has a side-car .json with git SHA, config hash, data manifest hash, library versions.

Commits

• Atomic per concept. One concept = one commit (or one PR if branching).
• Title in imperative mood. Body explains the why and any numbers measured.