# Proctor reference, version 1

A portable PyTorch implementation of the original sequence-local false-positive concentration objective, with a Markdown article and retained language-model experiment evidence.

**For the blog handoff:** start with [EXPLAINER.md](EXPLAINER.md) and [WEB_AGENT_HANDOFF.md](WEB_AGENT_HANDOFF.md).

## Run the example and tests

Use Python 3.10 or newer and install the [official PyTorch build](https://pytorch.org/get-started/locally/) appropriate to your platform. CPU execution is sufficient for the example and all included tests. There are no other runtime dependencies.

From this directory:

```sh
python -B example.py
python -B -m unittest discover -s tests -v
```

The example reports approximately:

| Case | CE | Penalty | Objective |
|---|---:|---:|---:|
| Repeated wrong preference | 0.693147 | 0.441800 | 1.134947 |
| Distributed wrong preference | 0.693147 | 0.000000 | 0.693147 |

It also checks finite gradients. It does not load a model or start training.

## Use the loss

```python
from proctor import proctor_loss

# logits: floating-point tensor [batch, positions, vocabulary]
# targets: torch.long tensor [batch, positions], already aligned with logits
terms = proctor_loss(logits, targets)
loss = terms.objective
loss.backward()
```

All returned values are scalar tensors with gradients. `cross_entropy` and `penalty` are available separately for reporting. The penalty coefficient is fixed at one.

The input contract requires finite logits representable in float32, a nonempty batch and sequence, at least two vocabulary items, valid target IDs, and a shared device. Sequences must have equal lengths and contain no padding or ignored positions. The function casts logits to float32 exactly as the experiment did. It does no target shifting and does not concatenate sequences. Eager validation can synchronize a GPU. This implementation prioritizes inspectability, with no acceleration or throughput claim.

## Contents

- `EXPLAINER.md`: complete article draft, with relative links to its figures.
- `proctor.py`: standalone loss module.
- `example.py`, `example_logging.py`: deterministic numerical example and logging.
- `tests/`: definition, gradient, invariant, boundary, and evidence checks.
- `data/`: publication measurements, original configuration extracts, and source hashes.
- `figures/`: PNG images for embedding and SVG versions for scaling or restyling.
- `VALIDATION.md`: exact verification performed for this release.
- `LIMITATIONS.md`: research and implementation qualifications.
- `WEB_AGENT_HANDOFF.md`: instructions for turning the material into the final blog.

## Logging and retention

The numerical example uses **bounded-run** retention: each invocation replaces only `logs/example.jsonl`, retaining its most recent runtime. Logs include a runtime ID, environment versions, tensor shapes, case transitions, outcomes, and exception traces. They contain no dataset text. The loss module uses the Python logger named `proctor`; applications importing it own handler configuration and retention. The module itself writes no files.

The source repository excludes runtime logs, bytecode, virtual environments, weights, and archives. The reduced JSON evidence and publication figures are deliberately retained as documentation assets. The release ZIP excludes development repository metadata and runtime logs.

## Reproduction boundary

The included example reproduces the loss calculation. The JSON records preserve historical experimental results. Reproducing original FineWeb training additionally requires the original data and tokenizer artifacts, architecture, training environment, and schedule semantics. Those artifacts are not shipped here. The retained source-log hashes identify the records inspected; they are not a public download location or independent verification of the original experiments.

## License

Original package code, text, figures, and documentation evidence: **CC0-1.0**. See [LICENSE](LICENSE) and the [CC0 deed](https://creativecommons.org/publicdomain/zero/1.0/).

Dependencies, datasets, and any original training artifacts retain their own terms. No attribution requirement is added. Linking back to the eventual article would be welcome, but is optional.