Conventions & Maintenance Rules¶
This file governs how the collection grows without turning into an inconsistent taxonomy.
1. Criteria for creating a new datasheet¶
A new domain file is justified only when at least one of these axes changes materially:
Do not create a separate file merely because there is:
- a new product;
- a new checkpoint;
- a new acronym;
- a new sampler;
- a new UI;
- a new adaptation technique.
Those belong in the document whose mechanism already covers the new development.
2. Canonical datasheet structure¶
When applicable, follow this order:
- Scope & boundary
- Canonical computational graph
- Representation / state tensors
- Governing equations
- Architecture parameters
- Training/objective parameters
- Inference controls
- Coupling matrix
- Compute/memory model
- Observables
- Failure surfaces
- Experimental protocol
- Backend/tool mapping
- Dated technology snapshot
- References
Not every file needs every section, but omissions should be intentional.
3. Provenance tags¶
Use the canonical definitions in 19_PARAMETER_GLOSSARY_AND_REGISTRY.
Main tags:
ARCH
MODEL
OBJ
DATA
TRAIN
ALIGN
PEFT
DISTILL
MERGE
GEN
COND
INF
STATE
BACKEND
PIPE
INDEX
EVAL
SEC
UI
HEURISTIC
COND identifies inputs or representations that condition the prediction, such as a speaker embedding or reference image.
A variable may carry more than one tag when it crosses layers.
4. Levels of assertion¶
Every technical statement should fall, implicitly or explicitly, into one of these classes:
Identity / definition¶
True by definition.
Example:
Architecture fact¶
True for a specific family/model.
Example:
a particular model uses GQA.
Requires a source/snapshot when contemporary.
Approximation¶
A useful engineering model.
Example:
Here, b is bytes per cached element, B is batch size, T is cached length per sequence, L is the number of layers, n_kv is the number of KV heads, and d_h is their dimension. This estimates K/V tensor payload for a dense, uniform MHA/GQA/MQA cache with equal K and V dimensions, excluding allocator/metadata overhead. Sliding-window, MLA, compressed caches, or variable lengths require adapting the estimate.
State assumptions when necessary.
Empirical regularity¶
Behavior observed in common operating regimes.
Example:
very high CFG often degrades images in a particular family.
Heuristic¶
Operational recommendation.
It must be clearly separated from the mathematics.
Vendor/UI behavior¶
Valid only for the identified product/backend.
5. The “phenomenology ≠ mechanism” rule¶
Two knobs can produce a similar subjective effect without being equivalent.
Example:
even if both can alter the perceived degree of “freedom.”
Never turn a perceptual analogy into a mathematical equivalence.
6. Symbols¶
Symbols are local to the domain where collisions exist.
Rules:
- \(\mathcal L\) reserved for loss whenever practical;
- \(\theta\) for learned parameters;
- \(B\) for batch;
- \(T\) for length/time, always contextualized;
- \(d\) for dimension;
- \(r\) for low-rank rank in PEFT context;
- \(\eta\) for learning rate in training context;
- \(\tau\) for contrastive/calibration temperature when defined;
- \(s\) for CFG/guidance when defined.
See collisions in 19_PARAMETER_GLOSSARY_AND_REGISTRY.
7. Tensor shapes¶
Always make axis order explicit when shape matters.
Preferred forms:
Sequence¶
Latent image¶
Video¶
or another order provided it is declared.
Do not silently assume a framework convention.
8. Units¶
Memory¶
Prefer GiB/MiB when computing in binary units.
Commercial storage¶
GB/TB may be decimal when reproducing a vendor specification.
Bandwidth¶
Specify GB/s or GiB/s when precision matters.
Time¶
ms/s.
Throughput¶
Always name the unit:
- tokens/s;
- samples/s;
- frames/s;
- requests/s.
9. Snapshot policy¶
The collection mixes two kinds of knowledge.
Durable core¶
Equations, definitions, taxonomies.
These should not depend on the date.
Technology snapshot¶
- current models;
- backend features;
- library support;
- active benchmarks;
- specs/protocols.
Always include the date in the global updated: header and, where needed, in the snapshot section.
10. Source policy¶
For contemporary claims, prefer:
- original paper;
- official documentation;
- official repository;
- standards/framework body;
- trustworthy survey.
Avoid using a secondary post as the primary source when the original exists.
11. Cross-link policy¶
Each language edition has its own directory: docs/en-US/ or docs/pt-BR/.
Use Markdown links with relative destinations and the .md extension:
[02_LLM_TRANSFORMER_INFERENCE_DATASHEET](02_LLM_TRANSFORMER_INFERENCE_DATASHEET.md)
Resolve each destination relative to the current file; keep links within the same edition unless a language switch is intended.
12. File naming¶
Numbered datasheets:
NN_UPPER_SNAKE_CASE_DATASHEET.md
Established exceptions should retain their names to avoid breaking backlinks.
Meta files do not need numbers:
CONVENTIONS.md
CHANGELOG.md
13. Rename policy¶
Do not rename an existing file without:
- updating all Markdown links;
- recording the change in the CHANGELOG;
- ideally retaining an alias or migration note.
Knowledge management favors stable identifiers.
14. Canonical parameter naming¶
When a term collides, use a qualified name:
- Sampling Temperature;
- Contrastive Temperature;
- Distillation Temperature.
Do not use an ambiguous short name in a cross-domain table.
15. Backend-specific parameters¶
Record them as:
canonical concept → backend alias
Example:
Context Length → n_ctx / num_ctx / context_length
Do not create a new concept for every alias.
16. UI knobs¶
Every UI variable should carry UI until its mapping is known.
Example:
"Creativity" [UI]
Only after documentation should it become something like:
Creativity → temperature + top-p
if that is genuinely what the product implements.
17. Presets¶
A preset does not belong in the mathematical core.
Place it under a section such as:
Empirical operating points
with:
- model/family;
- backend;
- date;
- purpose.
Never write a universal “golden setup.”
18. Ranges¶
Separate:
- mathematical domain;
- backend accepted range;
- empirical useful range.
Example:
Sampling Temperature:
is the mathematical domain.
A UI limiting it to 0..2 is an implementation constraint.
19. Reproducibility language¶
Never write:
same seed = same result
as a universal law.
Use:
20. Physical cost¶
Whenever a parameter increases a relevant dimension, try to show the impact on:
- VRAM;
- RAM;
- bandwidth;
- FLOPs;
- latency;
- storage.
Example:
is more useful than simply saying “more context uses more VRAM.”
21. Coupling matrices¶
Where possible, a table should make explicit:
parameter ↑ → primary effect → secondary effect → failure surface
Do not use monotonic arrows when the relationship is non-monotonic.
22. Observables¶
Every control section should, where possible, point to a measurable variable.
Ideal:
That turns tuning into experimentation.
23. Evaluation policy¶
Every important comparative recommendation should be testable according to 17_EVALUATION_BENCHMARK_EXPERIMENTATION_DATASHEET.
Avoid:
- single-seed conclusions;
- benchmark scores without versions;
- leaderboards without a system definition;
- subjective impressions presented as facts.
24. Security policy¶
No prompt should be treated as a security boundary.
Security controls should exist in:
- authn/authz;
- sandboxing;
- validation;
- tool scope;
- runtime policy;
- logs/audit;
- rollback.
See 18_SECURITY_ROBUSTNESS_FAILURE_MODES_DATASHEET.
25. Deprecation¶
Outdated content should not disappear without explanation when it remains historically useful.
Mark it:
LEGACY
MODEL-SPECIFIC
SUPERSEDED
Explain why it stopped being universal.
26. Changelog discipline¶
Every structural change should be recorded in CHANGELOG.
Minor typo fixes do not require individual entries.
Record:
- date;
- affected files;
- conceptual change;
- breaking rename, if any.
27. Definition of done for a new datasheet¶
Before considering it complete:
- [ ] scope defined;
- [ ] computational graph;
- [ ] representation/state;
- [ ] central equations;
- [ ] parameters classified;
- [ ] physical cost where relevant;
- [ ] observables;
- [ ] failure surfaces;
- [ ] cross-links;
- [ ] dated snapshot;
- [ ] references;
- [ ] valid relative Markdown links;
- [ ] balanced formulas/fences.
28. Editorial philosophy¶
The collection should not answer only:
“which button should I change?”
It should let the reader reconstruct:
And across the full lifecycle:
That is the epistemic contract of the collection.