Pull Request

Issue Reference

Closes #296

Description of Changes

Removes the three ConfusionMatrixCalculator methods that nothing reaches, and the three StructuredModel wrappers that were their only way in. Nothing that runs today changes: before this change all six had zero executed lines across the full suite.

Changes Made

• confusion_matrix_calculator.py: delete calculate_list_confusion_matrix (lines 38-159), calculate_nested_field_metrics (244-556) and calculate_single_nested_field_metrics (557-650). With the blank line between them that is the 530 lines from the re-verification comment. Drop the HungarianHelper, NonMatchesHelper and List imports, which only those methods used, and the "and lists of structured models" clause from the class docstring. The file goes from 650 to 117 lines. ruff format also strips the trailing whitespace from 9 blank docstring lines in the kept code, the cleanup the refactor: remove deprecated ComparableField(aggregate=) parameter (#226) #293 review set aside for Delete the superseded ConfusionMatrixCalculator nested and list methods (329 dead lines) and their StructuredModel wrappers #296.
• structured_model.py: delete the wrappers _calculate_list_confusion_matrix (:1504), _calculate_nested_field_metrics (:1526) and _calculate_single_nested_field_metrics (:1558), 80 lines.
• docs/structured_model_REFACTORING.md: drop the three rows from the Code Location Mapping table (378-380), and the two removed names from the "Legacy private methods are kept as delegating shims" paragraph (:159), which said they still exist.
• src/stickler/algorithms/README.md and the HungarianMatcher.calculate_metrics docstring: both said ConfusionMatrixCalculator accepts a score up to 1e-10 under the threshold. That tolerant test lived in the deleted calculate_nested_field_metrics (old line 324). The method that remains, classify_field_for_confusion_matrix, uses a bare similarity >= threshold, so both now name only ThresholdHelper and ComparisonHelper, which do use the tolerant test.

No test changes.

Why These Changes Are Needed

These methods are a superseded copy of the list and nested metrics that StructuredListComparator computes today. They were kept as backward-compatibility shims, and nothing in the repository uses them any more. Removing them takes about 610 lines of unexecuted code out of the metrics path, and leaves one _calculate_nested_field_metrics instead of two.

Reachability check

Line numbers are on dev at 70e9afb. Each name was searched with git grep -n over the whole checkout: src/, tests/, examples/ (including all 11 notebooks), docs/ and CHANGELOG.md. A search for indirect access (getattr/hasattr/mock.patch on these names, or the names as string literals) found none. Executed statements come from coverage json after a full coverage run -m pytest tests/ on unmodified dev.

The three calculator methods only call each other, the three wrappers are their only entry points, and the wrappers have no callers.

The one call that looks like a caller is structured_list_comparator.py:82, self._calculate_nested_field_metrics(...). StructuredListComparator does not inherit from StructuredModel (class StructuredListComparator: at :21), so that call resolves to its own method at :209, which this PR keeps. It also passes five arguments, including matched_pairs; the wrapper took four.

None of the six is public API. None is exported from any __init__.py or __all__. The API reference renders StructuredModel through mkdocstrings with filters: ["!^_[^_]", "^_compare$"] (docs/mkdocs.yml), so the underscore wrappers never appeared there, and no ::: directive renders ConfusionMatrixCalculator. The only docs that listed them were the refactoring notes edited here.

Deliberately kept

• StructuredListComparator._calculate_nested_field_metrics (structured_list_comparator.py:209): the live namesake, called from :82. 15/15 statements executed before and after.
• ConfusionMatrixCalculator.__init__ and classify_field_for_confusion_matrix: live through structured_list_comparator.py:511 calling StructuredModel._classify_field_for_confusion_matrix (:1482), which calls classify_field_for_confusion_matrix. Statements executed, the same before and after: classify_field_for_confusion_matrix 26/29, __init__ 1/1. ConfusionMatrixBuilder.calculator also constructs a ConfusionMatrixCalculator and needs only __init__.
• The _classify_field_for_confusion_matrix wrapper and its row in the refactoring notes.

Testing

• Unit tests added/updated (none needed: the issue requires no test changes)
• Integration tests added/updated
• Manual testing completed
• All existing tests pass (apart from 6 tests that need the POSIX-only signal.SIGALRM, plus two timing tests that fail only under coverage tracing; details below)

Run on Windows, Python 3.12.5, uv sync --frozen --extra llm --no-group docs (CI also installs the bert extra; its torch stack was not installed for this run). inspect.getfile(stickler) pointed at this checkout's src/stickler/__init__.py.

uv run coverage run -m pytest tests/
uv run coverage report
uv run coverage json

Missed statements in src/ drop by exactly 164 (1174 to 1010), which is the body statement count of the six methods (29 + 100 + 26 + 3 x 3).

Failures, the same 8 on both sides:

• 6 tests in test_realistic_deep_nesting.py: AttributeError: module 'signal' has no attribute 'SIGALRM' (Windows has no SIGALRM). Linux CI runs them.
• Two timing tests that fail under coverage tracing: test_deep_nesting_6_levels.py::test_performance_with_deep_nesting (35 s budget, 78.8 s on this branch) and test_performance_benchmark.py::test_performance_simple_comparison (5 ms budget; 12.1 ms on dev, 5.3 ms on this branch). Without coverage both pass on this branch: uv run pytest tests/structured_object_evaluator/test_performance_benchmark.py tests/structured_object_evaluator/test_deep_nesting_6_levels.py gives 12 passed.

Lint:

uv run ruff check .

The same 16 findings before and after, all in examples/notebooks/*.ipynb and examples/scripts/llm_comparator_demo.py. None are in src/ or tests/. On the three changed Python files, uv run ruff check passes and uv run ruff format --check reports them already formatted. The repo configures no type checker.

Reviewers

@sromoam

Checklist

• Code follows the project's coding standards
• Self-review of code completed
• Documentation updated (if applicable)
• CHANGELOG.md entry added under [Unreleased], or not needed because
  nothing user-visible changed (see RELEASING.md): dead-code removal, no entry
• Tests added/updated for new functionality (no new functionality)
• All CI checks are passing
• Ready for review

Additional Notes

• Line numbers in structured_model.py have moved since the re-verification comment (:1203 and :1229 there). On current dev, the kept wrapper is at :1482 and the removed ones are at :1504, :1526 and :1558.
• fix: report refused list elements with field comparison rules #364 edits src/stickler/algorithms/README.md a few lines below the sentence changed here. The two changes do not touch the same lines.

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