[audreyt]

Stacked on #124 (which is stacked on #120). The change here is the commits after #124's (69fcfb2, 91f4d80, a02055b, f5223e7, the merge of #124 ca6f899, and 2849036). Please review #120 and #124 first.

Summary

Surveys often collect few demographics, yet responses carry context such as "I run a bakery" or "my elderly mother relies on paratransit". This adds src/participant_context, a stage that turns that context into columns, so opinions can be compared across groups.

For each configured attribute:

1. An extraction model (CONTEXT_*, either clairic or systemone, through the Extractor interface from Extract quotes as exact spans with Mercury or Clairic (stacked on #120) #124) marks the participant's own words as evidence. Every span is checked against the response.
2. The decision model (DECISION_*), when set, checks that evidence, seeing the whole response too. For an attribute with labels it picks one of them or none. For an attribute without labels it answers one yes/no question, whether the evidence states what the attribute asks (at DECISION_THRESHOLD), and rejected evidence is dropped.

When the extraction model marks nothing, the attribute gets no evidence and no further question is asked; an attribute with labels then gets the label none if a decision model is set. Marked evidence is only a candidate, as extraction models sometimes mark unrelated words, which is why the decision model checks it. Without a decision model, evidence is written unchecked and should be reviewed. A blank response reaches no model and is treated as one where nothing is marked, so a blank row no longer fails a run on hosts such as Mercury that reject empty text.

export CONTEXT_ENDPOINT_TYPE=clairic   # or systemone with Mercury Decide
export CLOUDFLARE_ACCOUNT_ID=<ACCOUNT_ID>
export CONTEXT_MODEL_API_KEY=<CLOUDFLARE_API_TOKEN>

python3 -m src.participant_context.participant_context_runner \
  --input_csv <OUTPUT_DIR>/processed.csv \
  --output_csv <OUTPUT_DIR>/processed_with_context.csv \
  --additional_context_file src/default-additional-context.md

The default attribute is role (business_owner, parent_or_caregiver, shift_worker, remote_worker). --attributes_file takes a JSON list of others, each with a name, the instructions for what to mark, and optional labels; the file is validated (unique identifier names, label keys without spaces, none reserved). The output adds <name>_evidence, <name>_not_stated, <name>_label and <name>_label_probability.

Evaluation

The 28-response transit survey from #124, with role labels written down before the first run (9 participants state a role, 19 do not). Labels came from local Clef in both runs; only the extraction backend differs.

Extraction backend	Correct labels	Evidence found (of 9)	False role	Evidence verbatim
Clairic	27 of 28	9	1	28 of 28
Mercury Decide	23 of 28	4	0	28 of 28

• Clairic found evidence for all nine roles, usually as a short phrase ("kids", "shop", "elderly mother"). Its one error: a participant whose response begins "Bus." and who was "written up at work" for being late got the evidence "Bus", which Clef labeled shift_worker (probability 0.80, against 0.98 or more for the correct labels).
• Mercury was precise but missed five roles stated indirectly (children, a daughter, an elderly mother, a son, a shop), reporting them as not stated with probability above 0.93.

With 28 responses this is a sanity check, not a benchmark; on this set Clairic is the better default for this stage.

A review run also tried an evidence-only attribute, tenure ("how long they have lived in the city"), which only one participant states ("30 years"). Without a check, Clairic also marked "older people", "last year", "suburban" and two other phrases in responses that never say. Neither span confidence (up to 0.94 on those) nor not_stated separated them from real evidence, so a threshold would not have fixed it. With the yes/no check (91f4d80) and local Clef, only "30 years" remains, in two Clairic runs and one Mercury run, and the role results are unchanged.

Test plan

• pytest (342 tests), including fake-model tests for evidence and labels, the yes/no check on evidence without labels (rejected evidence dropped, silence never asked about), the none option, single-span fields, <response> joining, attribute-file validation and the runner's CSV columns; each of these was checked to fail when the behavior is removed
• Live: the runner with CONTEXT_ENDPOINT_TYPE=clairic and with =systemone (Mercury), labels from local Clef: exit 0, results above
• Live: the survey with two blank rows added (empty, and empty <response> segments), on Mercury and on Clairic with Clef: exit 0, both blank rows none, role results unchanged
• Live: a custom attributes file with the evidence-only tenure attribute, with and without a decision model: results above