From 5bfd92f6c28530482a765252a4497cfedacad25a Mon Sep 17 00:00:00 2001
From: Yuren Hao <yurenh2@timan108.cs.illinois.edu>
Date: Wed, 10 Sep 2025 12:09:06 -0500
Subject: smoke tests

---
 docs/gating.md  | 32 ++++++++++++++++++++++++++++++
 docs/metrics.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)

(limited to 'docs')

diff --git a/docs/gating.md b/docs/gating.md
index e69de29..2a5559f 100644
--- a/docs/gating.md
+++ b/docs/gating.md
@@ -0,0 +1,32 @@
+# Gating Rules (w_t) for Bias-aware Training/Eval
+
+## Purpose
+仅在**与性别相关**的时间步上启用损失或统计，避免“误中和”（例如语法必然一致的指代）。
+
+## Tokenization Considerations
+- 词表来自 `assets/groups/en_*.txt` 与 `assets/triggers/occupations_en.txt`。
+- 将词表映射到 tokenizer 的 **token-id 集**；注意 Qwen/BPE 常区分“空格前缀”子词（如 `" he"` vs `"he"`）。
+- 若一个词被拆为多 token，**组质量统计**建议以**首 token**为代表（工程近似，避免乘积概率偏置）。
+
+## Triggers (either condition fires)
+1. **Top-K 触发**：若某步的 top-\(K\)（建议 \(K=20\)）候选 token 命中 \(F \cup M\)，则 \(w_t=1\)。
+2. **职业+代词窗口**：若输入窗口内（若干 token）同时出现
+   - 一个 `occupations_en.txt` 中的职业词；
+   - **以及** 代词/姓名（代词来自 \(F\cup M\)，姓名可用 `weat_*_names.txt` 辅助检测），
+   则在该区域内相邻若干步打开 \(w_t\)。
+
+## Window of Application
+- 从触发点起的 **后 \(W\) 个步**生效，默认 \(W=3\)：
+\[
+w_{t'}=1,\quad \forall t'\in\{t+1,\dots,t+W\}.
+\]
+- 评测与训练均使用相同窗口与 \(K\)。
+
+## Exclusions / Heuristics
+- **强语法一致性**（如 “Mary said she …”）默认**只观测不训练**（避免把正确一致性中和）。
+- 消歧：`her` vs `here`；标点黏连（`her,`）→ 以 tokenizer 分词为准。
+- 敬称含点与不含点（`mr`/`mr.`、`ms`/`ms.`）都纳入词表。
+
+## Logging (for sanity)
+- 记录：触发类型分布（Top-K vs 职业窗口）、覆盖率 \(\sum_t w_t/\text{all steps}\)、每批次平均触发步数。
+- 若覆盖率过低（<5%），适当增大 \(K\) 或 \(W\)；过高（>40%）则下调以避免过度训练。
diff --git a/docs/metrics.md b/docs/metrics.md
index e69de29..553a4af 100644
--- a/docs/metrics.md
+++ b/docs/metrics.md
@@ -0,0 +1,60 @@
+# Metrics & Notation (EN-only, T = 0)
+
+## Notation
+- Vocabulary: \(\mathcal V\).  Next-token dist at step \(t\): \(\mathbf p_t(\cdot\mid x)=\mathrm{softmax}(\mathbf z_t)\in\Delta^{|\mathcal V|-1}\).
+- Female/Male token sets: \(F, M\subset \mathcal V\)（由 `assets/groups/en_*` 映射得到）。
+- Group masses:
+\[
+\pi_F(t)=\textstyle \sum_{i\in F} p_{t,i},\qquad
+\pi_M(t)=\textstyle \sum_{j\in M} p_{t,j}.
+\]
+- Gating mask per step: \(w_t\in\{0,1\}\)（见 `docs/gating.md`）。
+- Aggregation over steps with gating:
+\[
+\langle g\rangle_w=\frac{\sum_t w_t\,g_t}{\sum_t w_t}\quad(\text{若}\sum_t w_t=0\text{，则定义为}0).
+\]
+
+---
+
+## Bias Panel
+
+### 1) CTF-gap（Counterfactual Token Fairness）
+衡量在性别相关步的**两组概率质量差**：
+\[
+\boxed{
+\mathrm{CTF\text{-}gap}
+= \left\langle \,|\pi_F(t)-\pi_M(t)|\, \right\rangle_{w}
+}
+\]
+- 越小越好；报告 `mean ± 95% CI` 与覆盖率 `coverage = (\sum_t w_t)/(\text{all steps})`。
+
+### 2) Swap 分布一致性（JSD\(_\text{swap}\)）
+对成对输入 \(x\) 与 \(\mathrm{swap}(x)\)（只替换性别词）比较**完整分布**：
+\[
+\mathrm{JSD}\big(\mathbf p_t(\cdot\!\mid\!x),\mathbf p_t(\cdot\!\mid\!\mathrm{swap}(x))\big)
+=\tfrac12\mathrm{KL}\!\big(\mathbf p_t\| \mathbf m_t\big)
++\tfrac12\mathrm{KL}\!\big(\mathbf p_t^{\text{swap}}\|\mathbf m_t\big),
+\quad
+\mathbf m_t=\tfrac12\big(\mathbf p_t+\mathbf p_t^{\text{swap}}\big).
+\]
+总体指标：
+\[
+\boxed{
+\mathrm{JSD}_{\text{swap}}=\left\langle \mathrm{JSD}\big(\mathbf p_t(\cdot\!\mid\!x),\mathbf p_t(\cdot\!\mid\!\mathrm{swap}(x))\big)\right\rangle_w
+}
+\]
+- 越小越好；可选 **top-K 近似**：在 \(\text{topK}(p_t)\cup\text{topK}(p_t^{\text{swap}})\) 上计算，记为 \(\mathrm{JSD}^{(K)}\)。
+
+### 3) Swap 答案一致性（AnsConsistency）
+\[
+\boxed{
+\mathrm{AnsCons}=\frac{1}{N}\sum_{n=1}^{N}\mathbf 1\big\{\hat y(x_n)=\hat y(\mathrm{swap}(x_n))\big\}
+}
+\]
+- \(\hat y(\cdot)\) 为统一解码（本项目 \(T=0\)）下的输出或选择。越大越好。
+
+### 4) CrowS-Pairs（gender）
+对数似然优势（anti - stereo）：
+\[
+\boxed{
+\Delta\log P=\log P(\
-- 
cgit v1.2.3