Blame for README.md

# Synthetic Signed Bank Document Generator

A modular, deterministic, configuration-driven pipeline that takes scanned
bank document templates with blank signature fields, fills them with
realistic handwritten signatures drawn from a public signature dataset,
applies configurable physical/scanner degradation, and exports both the
rendered document and a comprehensive per-sample metadata JSON — suitable
for training and benchmarking document-AI / signature-verification models.

```
python main.py --config configs/generate.yaml --count 10000
```

---

## Table of contents

1. [Installation](#installation)
2. [Project layout](#project-layout)
3. [Input assets](#input-assets)
4. [Quick start](#quick-start)
5. [Configuration](#configuration)
6. [Architecture / pipeline stages](#architecture--pipeline-stages)
7. [Metadata schema](#metadata-schema)
8. [Verification test cases](#verification-test-cases)
9. [Difficulty scoring](#difficulty-scoring)
10. [Signature box annotation](#signature-box-annotation)
11. [Determinism & reproducibility](#determinism--reproducibility)
12. [Validation](#validation)
13. [Visualization](#visualization)
14. [Testing](#testing)
15. [Extending the pipeline](#extending-the-pipeline)

---

## Installation

Requires **Python 3.12+** (developed and tested against 3.11.9 as well; no
3.12-only syntax is used, so 3.11 works too).

```bash
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

Core dependencies: OpenCV, NumPy, SciPy, Pillow, scikit-image, Shapely,
PyYAML, Pydantic, Albumentations, OmegaConf, Matplotlib, tqdm, pytest.

## Project layout

```
cc/
├── image/                    # 9 scanned bank document templates (provided)
├── dataset/                  # Public handwritten signature dataset (provided)
├── annotations/              # Signature box annotations, one JSON per template
├── configs/
│   ├── default.yaml          # Every config field with its default value
│   ├── generate.yaml         # Example large-batch dataset config
│   └── examples/             # Focused example configs (see below)
├── output/                   # Generated PNG + JSON land here
├── src/
│   ├── config/                # Pydantic schema + OmegaConf loader
│   ├── templates/             # TemplateLoader, annotation schema, CV box detector
│   ├── signatures/             # SignatureDataset discovery/sampling
│   ├── rendering/              # SignaturePreprocessor, Renderer (blending)
│   ├── placement/              # PlacementEngine
│   ├── augmentation/           # AugmentationEngine + effect implementations
│   ├── analysis/                # GeometryAnalyzer, DifficultyAnalyzer, ValidationEngine
│   ├── verification/             # Verification test-case registry + CASE_TABLE (case_type 1a-5b)
│   ├── metadata/                # MetadataExporter
│   ├── visualization/           # Debug figure rendering
│   ├── utils/                   # Logging, seeding, geometry, I/O, names
│   └── generator.py             # DatasetGenerator orchestrator (+ multiprocessing)
├── tests/                     # pytest unit + integration tests
├── main.py                    # CLI entry point
└── requirements.txt
```

## Input assets

This repository ships with:

* **`image/`** — 9 real scanned bank document templates (guarantee letters,
  loan agreements, account mandates), auto-discovered recursively regardless
  of subfolder layout. Each gets a stable id `bank_doc_01` … `bank_doc_09`,
  assigned by a deterministic sort of their discovered paths.
* **`dataset/`** — A public handwritten signature dataset (CEDAR-style:
  `genuine/original_<signer>_<sample>.png` and
  `forged/forgeries_<signer>_<sample>.png`), auto-discovered recursively.
  Nested `dataset/personNNN/*.png`-style layouts are also supported — the
  loader falls back to using each signature's parent folder name as its
  signer group when the CEDAR filename pattern doesn't match, and to an
  auto-generated id when no identity can be inferred at all. An optional
  `dataset/metadata.csv` with `path`/`filename` + `signer`/`source_type`
  columns can override both the identity association and genuine/forged
  labeling for any file, plus an optional `script` column (`"latin"` by
  default) recording the handwriting script a signature is written in.
  `dataset/hindi_bengali/` + the matching rows in `dataset/metadata.csv`
  bundle 7 real, named, multi-script signers (Hindi/Devanagari-style,
  Bengali-style, and Latin cursive) alongside the 55 anonymous CEDAR
  identities, so generated samples aren't exclusively Latin-script English
  names — `SignerIdentityRegistry.display_name()` (`src/verification/registry.py`)
  returns a metadata.csv-sourced name as-is instead of generating one, and
  every `SignatureRecord`/`verification` metadata block carries its `script`.
  These signers have very few reference samples each (1-3, no forged
  counterpart) — `records_for_group(..., "forged")` falls back to their
  genuine samples with a logged warning rather than failing, so the `3b`
  skilled-forgery case degrades gracefully rather than erroring for them.

Nothing about either directory's internal layout is hardcoded — add more
template images or more signature images/folders and they will be picked up
automatically on the next run.

## Quick start

```bash
# 1. Generate 10 samples with all defaults (configs/default.yaml)
python main.py

# 2. Generate a large, varied batch
python main.py --config configs/generate.yaml --count 10000

# 3. Generate one fully reproducible, fixed-identity sample with a debug figure
python main.py --config configs/examples/single_document_demo.yaml --save-visualization

# 4. Override arbitrary nested config values from the command line
python main.py --set placement.rotation_deg.max=6 --set augmentation.coffee_stain.enabled=true

# 5. Restrict to one template, use 8 worker processes, don't overwrite existing files
python main.py --template bank_doc_03 --count 5000 --workers 8
```

Every run writes `output/<prefix>_<NNNNNN>.png` + `.json` pairs, plus
`output/generation_summary.json` (batch statistics) and
`output/resolved_config.yaml` (the fully-resolved config actually used, for
provenance/reproduction).

### CLI reference

| Flag | Effect |
|---|---|
| `--config PATH` | User YAML merged on top of `configs/default.yaml` |
| `--count N` | Number of samples |
| `--seed N` | Master random seed |
| `--workers N` | Worker process count (`1` = sequential, in-process) |
| `--output DIR` | Output directory |
| `--template ID` | Force every sample to use one template (e.g. `bank_doc_03`) |
| `--start-index N` | First sample number (for resuming/sharding a batch) |
| `--overwrite` | Regenerate samples even if their files already exist |
| `--save-visualization` | Also write a debug figure per sample |
| `--set key.path=value` | Arbitrary dot-path config override (repeatable) |
| `--log-level LEVEL` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |

## Configuration

Configuration is layered: `configs/default.yaml` (every field, documented) →
an optional `--config` user YAML (merged on top) → `--set key=value` CLI
overrides (highest precedence). The merged result is validated against a
Pydantic schema (`src/config/schema.py`) — invalid types, out-of-range
values, or unknown keys fail fast with a clear error instead of silently
being ignored.

Any placement/augmentation numeric parameter accepts either a fixed scalar
or a range, resolved independently per sample by a seeded RNG:

```yaml
placement:
  scale_factor: 0.84          # fixed
  rotation_deg:
    min: -5
    max: 5                    # sampled uniformly per sample
```

Every augmentation effect follows the same shape:

```yaml
augmentation:
  coffee_stain:
    enabled: true
    strength: 0.42             # or {min: ..., max: ...}
    probability: 0.1            # per-sample chance of actually applying
    seed: null                  # optional explicit seed; default derives from (master_seed, sample_index, name)
```

These effects are covered by **20 configurable families** (a couple are
strict specializations of another and share one family with a `type`/`tone`
selector, so the config surface stays coherent):

| Family | Covers |
|---|---|
| `rotation` | Extra probabilistic jitter on top of `placement.rotation_deg` |
| `stroke_dilation` | Ink stroke thickness variation |
| `motion_blur`, `gaussian_blur` | Signature-layer blur |
| `perspective` | Whole-page perspective warp |
| `scanner_noise`, `salt_pepper` | Sensor/impulse noise |
| `jpeg_compression` | Lossy re-encode artifacts (applied last) |
| `contrast`, `gamma` | Photometric shifts |
| `coffee_stain` | Coffee-ring blotches |
| `stain` (`type: paper\|water\|random`) | Paper stains + water stains |
| `shadow` (`type: edge\|corner\|fold\|random`) | Edge / corner / fold shadows |
| `crumple` | Paper crumpling + wrinkle lines |
| `discoloration` (`tone: yellow\|grey\|sepia\|random`) | General discoloration + paper yellowing |
| `page_tilt` | Crooked scanner feed |
| `dust`, `scanner_streaks` | Sensor debris / dirty-glass streaks |
| `ink_fading`, `ink_bleed` | Ink density effects |

See `configs/default.yaml` for every field and its default, and
`configs/generate.yaml` / `configs/examples/*.yaml` for worked examples
(a large varied batch, a fixed-identity single-document demo, an "easy"
preset, and a "hard/degraded" preset).

## Architecture / pipeline stages

Each sample flows through the same 11 stages the spec describes, one class
per stage:

| # | Stage | Class |
|---|---|---|
| 1 | Load template | `TemplateLoader` |
| 2 | Resolve signature box(es) | `TemplateLoader` (manual annotation, or CV auto-detect fallback) |
| 3 | Assign signer name/role | `src.utils.names` + config |
| 4 | Select a signature image | `SignatureDataset` |
| 5 | Clean/preprocess signature | `SignaturePreprocessor` |
| 6 | Fit & position in box | `PlacementEngine` |
| 7 | Signature-layer augmentation | `AugmentationEngine.apply_to_signature` |
| 8 | Blend onto document | `Renderer` |
| 9 | Document-level augmentation | `AugmentationEngine.apply_to_document` |
| 10 | Detect rendered signature + geometry | `GeometryAnalyzer` |
| 11 | Difficulty score | `DifficultyAnalyzer` |
| — | Export | `MetadataExporter` |
| — | Verify | `ValidationEngine` |

`GeneratorContext` (in `src/generator.py`) wires all of the above together
for one sample; `DatasetGenerator` drives it across a batch, either
sequentially (`workers=1`) or via a `ProcessPoolExecutor` where each worker
builds one `GeneratorContext` (via a pool initializer) and reuses it for
every sample it's assigned.

### Signature cleaning (`SignaturePreprocessor`)

Signature dataset images are flat grayscale/RGB scans with no alpha
channel. The preprocessor estimates the local paper background level,
derives a soft per-pixel alpha from how dark each pixel is relative to that
background (gamma-softened to preserve antialiased stroke edges/natural
texture rather than a hard binary mask), removes sub-pixel speckle noise via
connected-component filtering, and tightly crops to the ink content. A
flat ink color (randomly chosen per sample from a small realistic pool —
black, blue-black, ballpoint blue) is applied to the RGB channels; the alpha
channel carries all of the texture.

### Placement (`PlacementEngine`)

Rotates first (about the signature's own center, on an auto-expanding
transparent canvas so nothing clips), then scales to fit the box's
margin-adjusted interior while preserving aspect ratio (never stretches),
then positions via an anchor point (`center`, `top_left`, …) plus
pixel offsets. A configurable `misplacement_probability` optionally kicks
the signature away from its anchored position by up to
`misplacement_strength * max(box_w, box_h)` in a random direction — the
mechanism behind intentionally "hard" (badly-placed) samples.
A signature is never allowed to shrink below a legible minimum height
(16px) even inside a very short box; on the real bundled templates several
signature lines are only 12-24px tall, and a naive fit-to-box scale would
otherwise render an invisible, sub-pixel signature.

### Rendering (`Renderer`)

Supports `multiply`, `darken`, and `alpha` blend modes, configurable ink
opacity, alpha-edge feathering (`feather_px`), an overall blur to match scan
resolution (`blur_sigma`), a light Gaussian sensor-noise pass baked into
every render, and a final mild anti-aliasing blur.

### Detection (`GeometryAnalyzer`)

Detection is scoped to the *known* signature field (the annotated box, and,
if nothing is found there, a widened window around the union of the box and
the pre-augmentation placement location) rather than searching the whole
page — exactly how a real pipeline would use its layout annotations, and
what makes the box-vs-detection coverage metrics meaningful in the first
place. Ink is separated from the local paper background via adaptive
thresholding; a heuristic filter discards thin, wide, solid components
(printed "sign here" rule lines) so a blank field is never mistaken for a
signature. From the resulting ink mask it computes: axis-aligned bounding
box, `cv2.minAreaRect` minimum rotated rectangle, a convex-hull polygon,
centroid, PCA-based orientation, ink pixel count, `box_coverage_pct`,
`containment_pct`, `ink_fill_ratio`, `polygon_overlap_proxy` (IoU),
distance from box center, and margin utilization.

## Metadata schema

One JSON per sample, always containing the full schema (fields for
augmentations that weren't applied are present with a neutral value, not
omitted):

```jsonc
{
  "document_id": "sample_000001",
  "template": "bank_doc_03",
  "document_type": "deed_of_guarantee",
  "page": 1, "page_size": [1024, 559], "dpi": 300,
  "signer": {"name": "Jane Doe", "role": "Guarantor (Authorized Signatory)"},
  "signature_source": {"signature_id": "sig_001437", "path": "dataset/genuine/original_14_7.png",
                         "signer_group": "signer_0014", "source_type": "genuine"},
  "placement": {"x_offset": 8.0, "y_offset": -4.0, "rotation_deg": -3.0, "scale_factor": 0.84,
                 "anchor_point": "center", "misplaced": false, ...},
  "rendering": {"blend_mode": "multiply", "ink_opacity": 0.91, "blur_sigma": 0.34, ...},
  "difficulty": {"score": 0.57, "tier": "medium", "misplacement": 0.38, "whitespace": 0.14,
                  "faintness": 0.45, "smallness": 0.31, "low_texture": 0.12},
  "quality": {"degraded": false, "scanner_quality": 0.85, "paper_quality": 0.85, "render_quality": 0.85},
  "verification": {
    "case_type": "3a", "verdict": "REJECT", "reject_code": "IDENTITY_MISMATCH",
    "target_box_id": "sig1", "expected_signer_group": "signer_0014", "expected_signer_script": "latin",
    "actual_signer_group": "signer_0027", "actual_source_type": "genuine", "actual_signer_script": "latin",
    "companion": null
  },
  "augmentation": {
    "rotate_deg": -2, "scale_factor": 0.84, "stroke": 0.12, "noise_amount": 0.06,
    "stain_type": null, "stain_strength": 0.0, "shadow_type": "corner", "shadow_strength": 0.55,
    "coffee_stain_strength": 0.42, "crumple_strength": 0.18, "tilt_deg": 1.3,
    "discoloration_strength": 0.0, "blur_sigma": 0.35, "jpeg_quality": 82, "scanner_noise": 0.02,
    "effects": { "...every single effect, always present, with enabled/applied/strength/probability/seed/params...": {} }
  },
  "geometry": {
    "box_px": [1200, 830, 1530, 950], "target_box": [...], "actual_box": [...],
    "signature_bbox_px": [...], "signature_polygon_px": [[x, y], ...], "convex_hull_px": [...],
    "min_rotated_rect": {"center": [...], "size": [...], "angle_deg": ...},
    "centroid_px": [...], "orientation_deg": ..., "ink_pixels": ..., "detected": true
  },
  "metrics": {
    "box_coverage_pct": 84.2, "containment_pct": 96.3, "ink_fill_ratio": 0.28,
    "polygon_overlap_proxy": 0.71, "distance_from_box_center_px": 12.4, "margin_utilization": 0.6,
    "mean_dark_intensity": 142.1, "gray_stddev": 38.6, "signature_area_ratio": 0.011
  },
  "provenance": {"master_seed": 1234, "sample_index": 1}
}
```

The `augmentation.effects.<name>` block is the full audit trail for every
one of the 20 effect families: whether it was `enabled` in config, whether
its probability roll actually `applied` it, the resolved `strength`, and
any effect-specific `params` (e.g. `{"resolved_type": "corner"}` for
shadow, `{"quality": 58}` for JPEG compression) — this is present even when
`applied: false`, so the schema is identical across every sample regardless
of what happened to fire.

`quality.degraded` is `true` iff `quality.case_type == "1d"` **or**
`quality.notes` contains the substring `"low-quality"` (case-insensitive) —
both driven by `quality.case_type` / `quality.notes` in config (see
`configs/examples/hard_degraded.yaml`). `verification` is present (with
every field `null`) on every sample; see the next section for when it's
populated.

## Verification test cases

Setting `quality.case_type` to one of 12 recognized codes switches sample
generation into **scenario-driven mode**: instead of a random genuine
signature in a random box, the pipeline renders the specific scenario the
code describes and stamps the sample's `verification` metadata block with
the matching ground-truth `verdict`/`reject_code` — producing a labeled
benchmark for a downstream verifier. Any other value (or leaving it unset)
behaves exactly as before.

| Code | Scenario | Verdict | Reject code |
|---|---|---|---|
| `1a` | Correct signer signs normally | PASS | - |
| `1b` | Correct signer, natural pen variation (a different genuine sample of the same person) | PASS | - |
| `1c` | Multi-signer form, both boxes sign correctly | PASS | - |
| `1d` | Correct signer, scan degraded (pair with `configs/examples/hard_degraded.yaml`) | PASS | - |
| `2a` | Box left completely blank | REJECT | `NO_SIGNATURE` |
| `2b` | Printed/typed name only, no handwriting | REJECT | `NO_SIGNATURE` |
| `3a` | Wrong real person signs the box (a different genuine signer) | REJECT | `IDENTITY_MISMATCH` |
| `3b` | Skilled-forgery sample used (CEDAR `forged/` sample of the authorized signer) | REJECT | `IDENTITY_MISMATCH` |
| `4a` | Authorized signer, but wrong role's box (the *other* box's authorized signer signs here instead) | REJECT | `ROLE_MISMATCH` |
| `4b` | Signer from a different form entirely (authorized elsewhere, not on this template) | REJECT | `ROLE_MISMATCH` |
| `5a` | Required signer's box left empty (while a companion box is correctly signed) | REJECT | `REQUIRED_SIGNER_ABSENT` |
| `5b` | Someone else signs in the required signer's place (while a companion box is correctly signed) | REJECT | `REQUIRED_SIGNER_ABSENT` |

```bash
python main.py --config configs/examples/verification_cases.yaml --set quality.case_type=3a --count 10
python scripts/generate_verification_suite.py --per-case 2   # one labeled batch covering all 12 codes
```

### How ground truth is derived

`src/verification/registry.py`'s `SignerIdentityRegistry` deterministically
assigns an "authorized signer" identity (one of the discovered CEDAR signer
groups) to every `(template_id, box_id)` pair, purely as a function of the
master seed — there's no persisted state, consistent with the rest of the
pipeline's seeding model. Every case type is defined declaratively in
`src/verification/case_types.py` (`CASE_TABLE`) as what should actually be
rendered (`signature_mode`: genuine-correct, blank, printed-text,
wrong-signer, skilled-forgery, role-swap, foreign-template-signer, ...) plus
whether a companion box on the same page should also be filled with its own
correctly-authorized signature (`1c`/`5a`/`5b` — the cases whose label only
makes sense in a multi-signer-page context). The `verification` metadata
block records both the expected and actual signer group so the label is
independently auditable, not just asserted.

Companion-box rendering exists purely for visual/contextual realism (so a
"required signer absent" sample actually shows a properly multi-signed
page); it does not get its own `geometry`/`difficulty` block — the schema
stays single-target-box-centric, same as it's always been. `signature_source`
is `null` for the two blank scenarios (`2a`/`5a`); the expected identity in
that case lives only in `verification.expected_signer_group`.

## Difficulty scoring

Computed exactly as specified, from the post-render, post-augmentation
detected geometry (a pure function — no randomness — so it is always
reproducible from its own recorded components):

```
misplacement = clamp(1 - polygon_overlap_proxy, 0, 1)
whitespace   = clamp(whitespace_ratio, 0, 1)              # whitespace_ratio = 1 - ink_fill_ratio
faintness    = clamp((mean_dark_intensity - 90) / 120, 0, 1)
smallness    = clamp(1 - signature_area_ratio / 0.04, 0, 1)
low_texture  = clamp(1 - gray_stddev / 60, 0, 1)

score = 0.35*misplacement + 0.20*whitespace + 0.20*faintness + 0.15*smallness + 0.10*low_texture

tier = "easy" if score < 0.33 else "medium" if score < 0.66 else "hard"
```

**A note on the bundled templates:** `smallness` uses a fixed reference of
4% of page area. On the 9 real bank forms shipped in `image/`, the actual
signature lines are (realistically) much smaller than that — typically
0.2%–1.5% of the page — so `smallness`, and with it the overall score, runs
structurally high (mostly `medium`/`hard`) even under the "clean" example
preset. This is an accurate reflection of how small real bank-form
signature fields are relative to a full page, not a bug in the scoring
formula, which is intentionally implemented exactly as specified (weights
and the `0.04` reference are not something the pipeline silently retunes).
If your use case wants a different-looking tier distribution, adjust
`difficulty.easy_threshold` / `difficulty.hard_threshold` in config, or
supply larger signature boxes in your own annotations.

## Signature box annotation

Two modes, in order of preference:

* **Mode 2 — manual annotation (preferred, used for all 9 bundled
  templates):** `annotations/<template_id>.json`:

  ```json
  {
    "id": "bank_doc_03",
    "source_image": "image/guarantee/image.png",
    "document_type": "deed_of_guarantee",
    "pages": [{
      "page": 1, "page_size": [1024, 559], "dpi": 300,
      "signature_boxes": [
        {"id": "sig1", "x1": 595, "y1": 399, "x2": 748, "y2": 431,
         "role": "Guarantor (Authorized Signatory)", "name": "Guarantor"}
      ]
    }]
  }
  ```

  The 9 bundled annotation files were hand-measured against each template
  image (using a coordinate-grid overlay for precision) — every signature
  field, its role, and page geometry are captured exactly.

* **Mode 1 — automatic CV detection (fallback):** if no
  `annotations/<template_id>.json` exists for a discovered template,
  `src/templates/box_detector.py` looks for long horizontal "sign here"
  rule lines (morphological opening + contour filtering) and places a
  candidate box directly above each one. The result is cached back to
  `annotations/<template_id>.json` so detection only ever runs once per
  template — subsequent runs (including a fresh checkout with new
  templates dropped into `image/`) reuse the cached annotation. If a
  template has no such lines at all, a generic lower-right fallback box is
  used so the pipeline never crashes on an unannotated template.

To add a 10th template: drop its image into any subfolder of `image/` and
either let auto-detection run once, or hand-author its annotation file
(fastest way: temporarily overlay a coordinate grid on the image — see the
`_grid_debug` pattern used during development — and read off box corners).

## Determinism & reproducibility

Every random draw anywhere in the pipeline comes from an RNG whose seed is
`sha256(master_seed | sample_index | stage_name)` (`src/utils/random_utils.py`),
never from a shared/global RNG. Consequences:

* The same `(seed, config)` always produces byte-identical PNGs and
  semantically identical JSON, regardless of `--workers` or scheduling order
  (verified in `tests/test_end_to_end.py`, and by hand: a `workers=1` run
  and a `workers=4` run of the same seed produce `cmp`-identical PNGs).
* Every individual augmentation effect's own `seed` field in its metadata
  record is independently derivable/overridable — set `augmentation.<name>.seed`
  explicitly in config to pin one specific effect while leaving everything
  else seed-derived.
* `output/resolved_config.yaml` captures the exact fully-resolved
  configuration used for a run, so it can be handed to `--config` later to
  reproduce that run exactly (given the same `--seed`).

## Validation

`ValidationEngine` runs (by default) after every sample and checks:
metadata schema completeness, the signature was actually detected, its
polygon is non-degenerate and geometrically valid, every bounding box is
well-formed, boxes lie on the page (a warning, or an error under
`validation.strict: true`), no `NaN`/`Inf` leaked into the JSON, and the
difficulty score/tier are exactly reproducible from their own recorded
components. Per-sample pass/fail rolls up into
`output/generation_summary.json`. Disable with `generation.run_validation: false`.

## Visualization

`--save-visualization` writes `output/visualizations/<id>_viz.png` per
sample: the full rendered document with the target box (green), detected
bounding box (blue), and detected polygon (red) overlaid; a crop of the
signature field; the reconstructed detected-ink mask; a coverage-metrics
readout; and a difficulty-component bar chart.

## Testing

```bash
python -m pytest -q
```

80 tests covering geometry math (coverage/containment/IoU/margin
utilization), the exact difficulty formula (including weight-sum
validation and clamping), seed derivation/independence, placement
(determinism, aspect-ratio preservation, the minimum-height floor,
misplacement gating), signature/template discovery against the real
bundled assets (including the multi-script named signer pool), ink
detection (including the printed-rule-line false-positive guard), metadata
validation, full end-to-end reproducibility, and the case_type-driven
verification scenarios (`tests/test_verification_cases.py`: registry
determinism, ground truth for all 12 codes, multi-script signer handling,
and backward compatibility with the non-case-type path).

## Extending the pipeline

* **New augmentation effect:** add a function to
  `src/augmentation/document_effects.py` or `signature_effects.py`, a field
  to `AugmentationsConfig` in `src/config/schema.py`, and a branch in
  `AugmentationEngine.apply_to_document`/`apply_to_signature`.
* **New template:** drop an image into `image/`; annotate manually or let
  auto-detection + caching handle it.
* **New signature source:** drop images anywhere under `dataset/`
  (optionally with a `metadata.csv`); no code changes needed.
* **Different difficulty calibration:** override `difficulty.*` weights/
  thresholds in a config (must still sum to 1.0 — enforced by the schema).