Add EasyCom interaction weak-label pipeline

README.md

@@ -1658,6 +1658,123 @@ semantics. Run the following controlled experiments:
 The frozen-Omni head is the cleanest representation test. LoRA can be reported
 as a second-stage ceiling, not as the only result.
 
+## Transcript-derived interaction-event proxies
+
+EasyCom's released human transcriptions contain inclusive 20 FPS
+`Start_Frame`/`End_Frame`, `Participant_ID`, `Transcription`, and
+`Target_of_Speech`.  They do **not** contain a semantic backchannel class.
+[`derive_easycom_interaction_events.py`](derive_easycom_interaction_events.py)
+therefore separates observed timing relations from weak semantic proxies:
+
+- `ordinary_switch`: a non-overlapping recent speaker change followed by a
+  sustained incoming turn;
+- `overlap_takeover`: an observed overlapping onset followed by sustained
+  takeover, without claiming interruption intent;
+- `overlap_hold`: overlap without enough evidence for takeover;
+- `backchannel_proxy_high`: a conservative short lexical response while the
+  same other participant dominates immediately before and after it;
+- `interruption_proxy_high`: the previous transcript has a non-boundary
+  trailing cutoff and the incoming participant takes over;
+- `nonverbal_feedback`: laughter-only feedback around another participant's
+  floor; pure `[H]`, `[C]`, `[T]`, and `[U]` records are ambiguous candidates.
+
+`backchannel_candidate`, `interruption_candidate`, and
+`nonverbal_candidate` are retained for auditing but masked from auxiliary
+training.  `[X]` continuations across adjacent one-minute files are not new
+events.  Source-time gaps larger than one second create separate segments, so
+the dense EgoSpeak concatenation does not create a false switch across a
+redacted interval.  A one- or two-frame annotation/media endpoint discrepancy
+is clamped and reported; larger disagreement is fatal.
+
+A read-only audit on the raw-data machine is:
+
+```bash
+cd /mnt/58462F4C462F29E8/Code/icassp2027-experiment
+
+python3 derive_easycom_interaction_events.py \
+  --dataset-root /mnt/58462F4C462F29E8/Datasets/easycom \
+  --target-root /mnt/58462F4C462F29E8/Code/EgoSpeak/dataset/EasyCom/target_perframe \
+  --examples-per-event 10
+```
+
+To persist JSONL/CSV reports outside the dataset, add:
+
+```bash
+  --output-dir reports/easycom_interaction_events_v1 \
+  --overwrite
+```
+
+In an environment with NumPy, add `--write-frame-arrays` to also write one
+`Session_*.aux_targets.npz` per session.  It contains 5 Hz `event_onsets`,
+`event_roles`, collision flags, and event-name metadata aligned to
+`target_perframe`.  The raw EasyCom tree is never modified.
+
+The initial all-session audit found 6,981 utterances, including 530
+high-confidence backchannel proxies, 78 high-confidence interruption proxies,
+937 overlap-takeovers, 686 overlap-holds, and 349 laughter-feedback events.
+These counts establish usable weak-supervision coverage, not label accuracy.
+Before training, inspect a stratified sample from Sessions 4--12 and freeze the
+rules; do not tune thresholds on test Sessions 1--3.  The primary evaluator
+remains the original EgoSpeak three-label AP/mAP protocol.
+
+### Optional DeepSeek adjudication of ambiguous candidates
+
+DeepSeek is not required for the deterministic timing labels above.  It is an
+optional second-stage weak-label adjudicator for only
+`backchannel_candidate` and `interruption_candidate`; sending all 6,981
+utterances to an LLM would add cost and noise without adding observable
+prosody, gaze, or intent.  The current audit contains 614 such candidates over
+all sessions and 497 in the training split (Sessions 4--12).
+
+[`adjudicate_easycom_interaction_events.py`](adjudicate_easycom_interaction_events.py)
+uses DeepSeek JSON Output through the standard-library HTTP client, so no
+additional Python package is required.  It makes two differently instructed
+conservative passes.  A candidate is promoted only if both passes return the candidate's
+matching semantic label with high confidence; disagreements, medium/low
+confidence, short answers, cooperative overlaps, and uncertain cases remain
+masked.  The result is still a weak proxy and must not be presented as human
+ground truth.  The append-only JSONL records prompt/model metadata and resumes
+completed candidates, while rejecting a mixed model or prompt configuration.
+
+First inspect exactly what would leave the machine.  This makes no API call and
+does not require a key:
+
+```bash
+python3 adjudicate_easycom_interaction_events.py \
+  --input-dir reports/easycom_interaction_events_v1 \
+  --output reports/easycom_interaction_llm_v1.jsonl \
+  --max-events 16 \
+  --dry-run
+```
+
+If external transcript upload is authorized, enter the key without placing it
+in shell history and run a 32-candidate pilot:
+
+```bash
+read -s -p "DeepSeek API key: " DEEPSEEK_API_KEY; echo
+export DEEPSEEK_API_KEY
+
+python3 adjudicate_easycom_interaction_events.py \
+  --input-dir reports/easycom_interaction_events_v1 \
+  --output reports/easycom_interaction_llm_pilot_v1.jsonl \
+  --max-events 32 \
+  --selection-seed 2027 \
+  --batch-size 8 \
+  --passes 2 \
+  --allow-external-transcript-upload
+
+unset DEEPSEEK_API_KEY
+```
+
+Audit the pilot rationales and precision manually before running the full
+training split.  For the full pass, use a new output path, remove
+`--max-events`, and keep the default `--splits train`.  The default model is
+`deepseek-v4-flash`; it can be changed with `--model` or `DEEPSEEK_MODEL` as
+the provider's available model names evolve.  Never tune the prompt or
+acceptance rule using Sessions 1--3.  LLM-adjudicated candidates are deliberately
+kept in a separate JSONL until pilot precision is accepted; they are not yet
+silently merged into the training arrays.
+
 ## Candidate improvement: explicit working and long memory
 
 Motivated by EgoSpeak's separation of long-term and working memory, test an