# Long-text inference: chunks and sliding windows

Implemented in `predict_windows.py` for all three local classifiers. The saved models and training results are unchanged. This is an inference strategy, not a larger native context window or additional training.

## Starting settings and experiment range

| Model | Start: total window / context overlap | Window sizes to compare | Overlap to compare |
| --- | --- | --- | --- |
| Open Emotions | 128 / 32 tokens | 64, 96, 128 | 0%, approximately 25%, approximately 50% |
| Open Morals | 256 / 64 tokens | 128, 192, 256 | 0%, approximately 25%, approximately 50% |
| Open Sensations | 128 / 32 tokens | 64, 96, 128 | 0%, approximately 25%, approximately 50% |

These are starting hypotheses, not empirically selected optimal settings. Default overlap is one quarter of the total window size; overlap itself is measured in **context tokens**, so special tokens and the sensory prefix make its fraction of usable context slightly larger. For a 128-token plain-text window, two special tokens leave 126 content tokens; overlap 32 gives a step of 94. Morals at 256/64 leaves 254 content tokens and a step of 190. Sensory capacity is calculated dynamically after reserving its repeated prefix.

Use zero overlap for independent chunks; sliding windows preserve some context across boundaries at extra compute cost. Smaller windows can isolate local cues but lose broader context. Large mixed-topic windows can dilute a brief emotion or moral cue. Overlap may rescue a boundary cue, but can also change predictions. Token windows may cut sentences; sentence-aware boundaries are a possible future comparison, not implemented here.

## Run locally from PowerShell

```powershell
# Default: emotions, 128 total tokens, 32 context tokens overlap.
.\.venv\Scripts\python.exe predict_windows.py --task open-emotions --file document.txt --output results.json

# Non-overlapping 96-token emotion chunks.
.\.venv\Scripts\python.exe predict_windows.py --task open-emotions --file document.txt --mode chunks --window-size 96

# Moral framing, 192 tokens with 48-token overlap.
.\.venv\Scripts\python.exe predict_windows.py --task open-morals --file document.txt --window-size 192 --overlap 48

# Sensory associations: only windows containing a complete target mention are evaluated.
.\.venv\Scripts\python.exe predict_windows.py --task open-sensations --file document.txt --target aroma --window-size 128 --overlap 32
```

Input files are UTF-8. `--text "A short example."` is also supported. `--model` accepts a local checkpoint directory, including extracted continuation archives. Model loading occurs once per command, with windows inferred in batches of up to eight on CPU. A persistent API can retain loaded models instead of starting a process per request.

The helper rejects sizes beyond each model's evaluated limit (128/256/128). Prefix and special tokens are included in the limit. It tokenizes the full document, feeds bounded slices without truncation, and covers every context token for emotions and morals. Sensations deliberately skips windows lacking a complete target mention; missing targets or no eligible window produce an error. This does not turn the sensory model into a whole-document sensory-presence detector.

## Interpret the output

Each window includes zero-based, end-exclusive token and Python-character offsets, its original text span, input token count, selected labels, and every label score. Unicode byte-level token boundaries can share character offsets, so a displayed span may overlap its neighbor even with zero token overlap.

Per-window labels use the existing validation-selected short-input threshold. This threshold has **not** been validated for long-document windows. `exploratory_summary` contains each label's maximum and arithmetic mean window score, with no document-level label decision:

- Maximum helps inspect whether a strong local cue occurred somewhere, but more windows create more chances for a false positive.
- Mean describes average window scores but can dilute short salient passages. Overlapping windows repeat evidence and are not independent votes. The final partial window receives equal weight in this simple mean.

Neither statistic is a calibrated document-level probability. Do not claim that an emotion or moral category characterizes the entire document merely because one window exceeds threshold. Keep evidence spans available for review.

## Diagnostic experiment completed

`experiment_windows.py` compares three sizes and both no overlap and 25% overlap for each model: **18 configurations**. It uses a roughly 670-token assistant-authored mixed-topic sample containing gratitude, worry, sensory descriptions, moral framing, and ordinary logistics. Paragraphs repeat to exercise long-input handling. There are no human reference labels; this is a behavior and runtime diagnostic, not an accuracy benchmark.

Results: `outputs/window-experiment/RESULTS.md`; complete per-window evidence is saved beside it, along with the sample and `comparison.json`. In the initial run, individual configurations took about 0.34–0.62 seconds on CPU after loading, for this single sample. These are single-run timings, not a service throughput guarantee.

At the starting sizes, overlap changed the selected emotion cues and increased the number of evaluated windows. Morals focused on care across mixed-topic windows while missing some other explicit cues. Sensations continued to overpredict several modalities. Therefore this experiment does not establish an accuracy improvement from overlap or solve the sensory prototype's limitations.

Boundary verification passed: all content tokens covered, model inputs within limits, exact token-ID equivalence for a short input with/without the sensory prefix, complete sensory target mentions, and rejection of invalid overlap/missing targets. A command-line run also successfully wrote long-text emotion results.

## Choose settings with labeled data

1. Collect representative documents and annotate relevant spans and/or document-level labels. Keep repeated text, authors, and related documents in the same split.
2. On a development split, compare the sizes above with zero, 25%, and 50% overlap. Fix whether the task concerns local spans or document-level presence before choosing aggregation.
3. Compare precision, recall, macro/micro F1, boundary failures, processed tokens, and latency; repeated windows are not independent evaluation examples.
4. If providing document-level labels, calibrate aggregation and thresholds on development data rather than recycling the short-input threshold.
5. Freeze the chosen configuration, then evaluate once on an untouched test split. Keep the current model-training test sets separate from this new windowing experiment.

Reproduce the diagnostics with `.\.venv\Scripts\python.exe experiment_windows.py` and the boundary checks with `.\.venv\Scripts\python.exe test_windows.py`. Diagnostic result files can be regenerated; trained checkpoints are never overwritten.