feat: mAP scoring for bounding box evaluation (#89)

[Divya-Bhargavi]

Issue

Closes #89

Description of changes

Adds Mean Average Precision (mAP) scoring for bounding box evaluation within the stickler
framework, enabling users to measure how accurately a model locates information on a page.

This builds on the rich-value pattern and the PostComparisonAccumulator aggregate
infrastructure introduced in #98 (now merged into dev / released in v0.4.0), so it targets
dev directly.

What's included

• BBoxIoUComparator — computes Intersection over Union between two bounding boxes.
  Supports [[x1,y1],[x2,y2]] and [x1,y1,x2,y2] formats with coordinate normalization.
  Registered in the comparator registry and exported from stickler.comparators.
• MAPCalculator — mirrors ConfidenceCalculator's calculator/accumulator split:
  extract_from_dicts() joins field_comparisons with ground-truth and prediction boxes
  into keyed pairs; compute_metrics() produces per-field IoU/precision/recall/F1/AP plus
  overall mean AP and coverage.
• BBoxMAPAccumulator — a PostComparisonAccumulator (name bbox_map_metrics) for bulk
  evaluation, with get_state/load_state/merge_state for checkpointing and distributed
  runs. The base-class docstring already reserved this name for the planned implementation.
• Rich-value _bbox extraction — bounding boxes ride on the underscore rich-value
  pattern (_value/_confidence/_bbox) and land in field extras via get_all_extras();
  no changes to the rich-value helper were needed.
• compare_with() wiring — pre-extracts ground_truth_bboxes and prediction_bboxes
  into the result (mirroring prediction_confidences) so the accumulator can join both
  sides. A single-document add_bbox_metrics=True sanity-check path is also provided.
• 43 tests — comparator math, calculator logic, accumulator + state round-trip/merge,
  bulk integration (including coexistence with ConfidenceAccumulator), single-doc path.
• Documentation — docs/docs/Advanced/bbox-map-metrics.md and an updated comparators
  guide.

Usage (bulk — recommended)

from stickler.structured_object_evaluator.bulk_structured_model_evaluator import (
    BulkStructuredModelEvaluator,
)
from stickler.structured_object_evaluator.models.bbox_map_accumulator import (
    BBoxMAPAccumulator,
)

evaluator = BulkStructuredModelEvaluator(
    accumulators=[BBoxMAPAccumulator(iou_threshold=0.5)],
)
for gt, pred in dataset:
    evaluator.update(gt, pred)

metrics = evaluator.compute().accumulator_metrics["bbox_map_metrics"]
print(metrics["mean_ap"])

Bounding boxes are provided via the rich-value pattern:

gt = Invoice.from_json({
    "vendor": {"_value": "Acme", "_bbox": [[10, 20], [200, 50]]},
})
pred = Invoice.from_json({
    "vendor": {"_value": "Acme", "_bbox": [[12, 18], [198, 52]], "_confidence": 0.9},
})

Testing

• 43 new tests, all passing.
• Full suite: 1119 passed, 2 skipped (baseline 1076 on dev + 43 new), no regressions.
• ruff check passes on all changed files.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute
this contribution, under the terms of your choice.