SigOrbit Trainer

Offline, auditable training workflows for SigOrbit. The project trains the 257 px SO(2)-canonicalized signature encoder from random initialization without requiring an unpublished initializer. C8 and C4 steerable backbones are supported; the C4 variant trains 2.7× faster with comparable margin.

Code-only boundary: MIT covers this repository's code only. This project contains no signatures, datasets, embeddings, checkpoints, or trained weights, and does not grant rights to any of them. A public dataset listing or Hugging Face card is not evidence of permission.

Status

Alpha. The source is published on GitHub; there is no PyPI release yet. The three-stage trainer, epoch-boundary resume, strict provenance records and a completed from-scratch 257 px run are implemented. Historical checkpoint metrics remain historical evidence, not a reproduction claim.

Architecture and pipeline

The trainer does not define a second neural network. It pins sigorbit==0.1.0 and imports the runtime package's ModelConfig, SteerableEncoder and CanonicalizedEncoder classes:

The end-to-end workflow wraps three training stages:

1. validate an immutable local manifest and a separate rights attestation;
2. train the C4 or C8 backbone from random weights with PK sampling, discrete rotation augmentation and a temporary ArcFace head;
3. restore the best backbone and train only the SO(2) canonicalizer against known synthetic angles;
4. jointly optimize canonicalizer, backbone and ArcFace head using identity, circular-orientation and cosine-consistency objectives;
5. evaluate on signer-disjoint validation identities, restore the best joint checkpoint and export an inference-only SigOrbit artifact.

There are no reflections: the symmetry is SO(2)+C_N (N = group_order), not O(2)/D_N. The ArcFace classifier, optimizers and schedulers exist only in recovery checkpoints; the deployable artifact contains the canonicalizer and backbone.

Install for development

git clone https://github.com/jordi-murgo/sigorbit-trainer.git
cd sigorbit-trainer
uv sync --extra dev

Safe smoke test

The smoke source generates non-person synthetic strokes in memory:

uv run sigorbit-train config validate configs/smoke.toml
uv run sigorbit-train run configs/smoke.toml

Interrupted runs can resume from the directory named by RUN/checkpoints/latest.json:

sigorbit-train resume CONFIG.toml --checkpoint RUN/checkpoints/stage=...-epoch=...-step=...

Resume is exact at a completed epoch boundary when the configuration, dataset, class map, architecture, device topology, optimizer, scheduler, and RNG schema match. The current alpha does not checkpoint mid-epoch.

Runtime controls keep the optimization schedule separate from resource-saving stops. joint.epochs remains the cosine-scheduler horizon, while joint.min_epochs prevents patience from stopping the joint stage before that floor. runtime.precision = "bf16" autocasts CUDA training forwards after a startup capability check; parameters and exported weights remain FP32.

The checkpoint directory retains only targets referenced by latest.json and the per-stage best-*.json pointers. Superseded epoch checkpoints are removed after each atomic pointer update.

Training with authorized local data

Training never downloads data inside the trainer process. A standalone script downloads, deduplicates, and materializes an authorized Hugging Face imagefolder dataset into the offline contract in one step:

HF_TOKEN=hf_... scripts/prepare_dataset.sh

Options: HF_DATASET, HF_REVISION, DATASET_ID, DEDUPLICATE, OUTPUT_DIR, WORK_DIR. See scripts/prepare_dataset.sh --help for details.

If an authorized dataset is already saved as a local Hugging Face DatasetDict, materialize it manually:

sigorbit-train dataset import-hf-disk \
  /secure/source-dataset \
  /secure/sigorbit-dataset \
  --dataset-id authorized-signatures \
  --revision IMMUTABLE_SOURCE_REVISION \
  --assert-genuine-only

sigorbit-train dataset attest \
  /secure/sigorbit-dataset/dataset.toml \
  /secure/sigorbit-dataset/rights.attestation.json \
  --purpose research-only \
  --authorization-reference APPROVAL_REFERENCE \
  --assert-authorized-use

sigorbit-train dataset validate \
  /secure/sigorbit-dataset/dataset.toml \
  --attestation /secure/sigorbit-dataset/rights.attestation.json

uv run sigorbit-train run configs/c8-257-final.toml

The importer only reads an already-local directory. attest records the operator's assertion and does not create legal rights. Keep both materialized data and attestation outside the repository.

The historical CEDAR/BHSig260-derived aggregate may only be used after acquiring the sources under applicable terms and documenting authorization. Its trained weights must not be published or used commercially without a separate legal, privacy, and model-release review.

Read docs/DATA_POLICY.md, docs/REPRODUCIBILITY.md, and docs/MODEL_RELEASE_POLICY.md before training.

The validated configurations and observed runs are documented in docs/TRAINING_RECIPE.md, docs/RESULTS_c8-257-final.md, and docs/RESULTS_c4-257-b64.md.

Randomized splits

Manifest splits can be repartitioned by writer before training, which is the recommended way to check that a result is not an artefact of one partition:

sigorbit-train dataset split-preview CONFIG.toml --random-seed 1234
sigorbit-train run CONFIG.toml --random-seed 1234

Splits move whole signers, never individual samples, and the seed enters the dataset fingerprint so a resume cannot silently change the partition. See docs/DATASET_MANIFEST.md.

Evaluation

Training reports clean leave-one-out retrieval plus per-angle top-1, median margin, and fragile rate on validation identities. The manifest test split is never used for selection and requires an explicit opt-in:

sigorbit-train evaluate CONFIG.toml \
  --checkpoint RUN/sigorbit-c8-257-retrained-v1.pt --split validation
sigorbit-train evaluate CONFIG.toml \
  --checkpoint RUN/sigorbit-c8-257-retrained-v1.pt --split test --allow-test-split

Relationship with SigOrbit

sigorbit-trainer owns data manifests, augmentation, losses, optimization, resume state, evaluation, and run provenance. sigorbit owns the encoder architecture, inference preprocessing, and runtime checkpoint compatibility. The trainer pins sigorbit==0.1.0; architecture changes require a new trainer release and model identifier.

Licence

MIT for this repository's code. Dataset, model-weight, privacy, and third-party rights are separate. See NOTICE.