StructuredModel Advanced Functionality: Technical Deep Dive

Table of Contents

1. Overview
2. Core Recursive Engine
3. Field Dispatch System
4. Specialized Comparison Handlers
5. Hungarian Matching Integration
6. Score Aggregation and Percolation
7. Threshold-Gated Recursion
8. Performance Optimizations
9. Debugging and Troubleshooting

Overview

This document provides a technical deep-dive into the core recursive logic of StructuredModel's comparison system. It's intended for developers who need to understand, modify, debug, or extend the complex internal functions that power the comparison engine.

The system is built around several "monster functions" that handle the complexity of comparing nested, heterogeneous data structures while maintaining both performance and accuracy.

Core Recursive Engine

compare_recursive(self, other: 'StructuredModel') -> dict

This is the heart of the comparison system - a single-traversal engine that gathers both similarity scores and confusion matrix data in one pass.

Function Signature and Purpose

def compare_recursive(self, other: 'StructuredModel') -> dict:
    """The ONE clean recursive function that handles everything.

    Enhanced to capture BOTH confusion matrix metrics AND similarity scores
    in a single traversal to eliminate double traversal inefficiency.
    """

Internal Structure

result = {
    "overall": {
        "tp": 0, "fa": 0, "fd": 0, "fp": 0, "tn": 0, "fn": 0,
        "similarity_score": 0.0,
        "all_fields_matched": False
    },
    "fields": {},
    "non_matches": []
}

Key Innovations

1. Single Traversal Optimization: Instead of multiple passes through the object structure, all data gathering happens in one recursive descent.

2. Dual-Purpose Processing: Each field comparison returns both:

3. Confusion matrix metrics (TP, FP, FN, etc.)

4. Similarity scores for aggregation

5. Score Percolation Variables:

   total_score = 0.0
   total_weight = 0.0  
   threshold_matched_fields = set()
   

Processing Loop

for field_name in self.__class__.model_fields:
    if field_name == 'extra_fields':
        continue

    gt_val = getattr(self, field_name)
    pred_val = getattr(other, field_name, None)

    # Enhanced dispatch returns both metrics AND scores
    field_result = self._dispatch_field_comparison(field_name, gt_val, pred_val)

    result["fields"][field_name] = field_result

    # Simple aggregation to overall metrics
    self._aggregate_to_overall(field_result, result["overall"])

    # Score percolation - aggregate scores upward
    if "similarity_score" in field_result and "weight" in field_result:
        weight = field_result["weight"]
        threshold_applied_score = field_result["threshold_applied_score"]
        total_score += threshold_applied_score * weight
        total_weight += weight

        # Track threshold-matched fields
        info = self._get_comparison_info(field_name)
        if field_result["raw_similarity_score"] >= info.threshold:
            threshold_matched_fields.add(field_name)

Final Score Calculation

# Calculate overall similarity score from percolated scores
if total_weight > 0:
    result["overall"]["similarity_score"] = total_score / total_weight

# Determine all_fields_matched
model_fields_for_comparison = set(self.__class__.model_fields.keys()) - {'extra_fields'}
result["overall"]["all_fields_matched"] = len(threshold_matched_fields) == len(model_fields_for_comparison)

Field Dispatch System

_dispatch_field_comparison(self, field_name: str, gt_val: Any, pred_val: Any) -> dict

This function routes each field to the appropriate comparison handler based on its type and content. It uses Python's match statements for clean, efficient dispatch.

Key Responsibilities

1. Type Detection: Determines field type (primitive, list, nested object)
2. Null Handling: Manages various null/empty states
3. Configuration Retrieval: Gets field-specific comparison settings
4. Handler Routing: Dispatches to appropriate specialized handler

Match-Based Type Detection

# Get field configuration for scoring
info = self._get_comparison_info(field_name)
weight = info.weight
threshold = info.threshold

# Check if this field is ANY list type
is_list_field = self._is_list_field(field_name)

# Get null states and hierarchical needs
gt_is_null = self._is_truly_null(gt_val)
pred_is_null = self._is_truly_null(pred_val)
gt_needs_hierarchy = self._should_use_hierarchical_structure(gt_val, field_name)
pred_needs_hierarchy = self._should_use_hierarchical_structure(pred_val, field_name)

List Field Dispatch with Match Statements

if is_list_field:
    list_result = self._handle_list_field_dispatch(gt_val, pred_val, weight)
    if list_result is not None:
        return list_result

Primitive Null Handling

if not (gt_needs_hierarchy or pred_needs_hierarchy):
    gt_effectively_null_prim = self._is_effectively_null_for_primitives(gt_val)
    pred_effectively_null_prim = self._is_effectively_null_for_primitives(pred_val)

    match (gt_effectively_null_prim, pred_effectively_null_prim):
        case (True, True):
            return self._create_true_negative_result(weight)
        case (True, False):
            return self._create_false_alarm_result(weight)
        case (False, True):
            return self._create_false_negative_result(weight)
        case _:
            # Both non-null, continue to type-based dispatch
            pass

Type-Based Handler Selection

# Type-based dispatch
if isinstance(gt_val, (str, int, float)) and isinstance(pred_val, (str, int, float)):
    return self._compare_primitive_with_scores(gt_val, pred_val, field_name)
elif isinstance(gt_val, list) and isinstance(pred_val, list):
    # Check if this should be structured list
    if gt_val and isinstance(gt_val[0], StructuredModel):
        return self._compare_struct_list_with_scores(gt_val, pred_val, field_name)
    else:
        return self._compare_primitive_list_with_scores(gt_val, pred_val, field_name)
elif isinstance(gt_val, StructuredModel) and isinstance(pred_val, StructuredModel):
    # For recursive StructuredModel comparison
    recursive_result = gt_val.compare_recursive(pred_val)  # PURE RECURSION

    # Add scoring information to the recursive result
    raw_score = recursive_result["overall"].get("similarity_score", 0.0)
    threshold_applied_score = raw_score if raw_score >= threshold or not info.clip_under_threshold else 0.0

    recursive_result["raw_similarity_score"] = raw_score
    recursive_result["similarity_score"] = raw_score
    recursive_result["threshold_applied_score"] = threshold_applied_score
    recursive_result["weight"] = weight

    return recursive_result
else:
    # Mismatched types
    return {
        "overall": {"tp": 0, "fa": 0, "fd": 1, "fp": 1, "tn": 0, "fn": 0},
        "fields": {},
        "raw_similarity_score": 0.0,
        "similarity_score": 0.0,
        "threshold_applied_score": 0.0,
        "weight": weight
    }

Specialized Comparison Handlers

_compare_primitive_with_scores(self, gt_val: Any, pred_val: Any, field_name: str) -> dict

Handles simple field comparisons (strings, numbers, dates) with integrated scoring and metrics.

Key Features

1. Comparator Application: Uses configured comparator (Levenshtein, exact, etc.)
2. Threshold-Based Classification: Converts similarity to binary metrics
3. Configurable Clipping: Respects clip_under_threshold settings

Implementation

def _compare_primitive_with_scores(self, gt_val: Any, pred_val: Any, field_name: str) -> dict:
    info = self.__class__._get_comparison_info(field_name)
    raw_similarity = info.comparator.compare(gt_val, pred_val)
    weight = info.weight
    threshold = info.threshold

    # For binary classification metrics, always use threshold
    if raw_similarity >= threshold:
        metrics = {"tp": 1, "fa": 0, "fd": 0, "fp": 0, "tn": 0, "fn": 0}
        threshold_applied_score = raw_similarity
    else:
        metrics = {"tp": 0, "fa": 0, "fd": 1, "fp": 1, "tn": 0, "fn": 0}
        # For score calculation, respect clip_under_threshold setting
        threshold_applied_score = 0.0 if info.clip_under_threshold else raw_similarity

    # Return hierarchical structure for consistency
    return {
        "overall": metrics,
        "fields": {},
        "raw_similarity_score": raw_similarity,
        "similarity_score": raw_similarity,
        "threshold_applied_score": threshold_applied_score,
        "weight": weight
    }

_compare_primitive_list_with_scores(self, gt_list: List[Any], pred_list: List[Any], field_name: str) -> dict

Handles lists of primitive values (strings, numbers) using Hungarian matching.

Critical Design Decision: Universal Hierarchical Structure

This method returns a hierarchical structure {"overall": {...}, "fields": {...}} even for primitive lists to maintain API consistency across all field types.

Rationale: - Consistency: All list fields use the same access pattern: cm["fields"][name]["overall"] - Test Compatibility: Multiple test files expect this pattern for both primitive and structured lists - Predictable API: Consumers don't need to check field type before accessing metrics

Empty/Null Handling

# CRITICAL FIX: Handle None values before checking length
if gt_list is None:
    gt_list = []
if pred_list is None:
    pred_list = []

# Handle empty/null list cases first - FIXED: Empty lists should be TN=1
if len(gt_list) == 0 and len(pred_list) == 0:
    # Both empty lists should be TN=1
    return {
        "overall": {"tp": 0, "fa": 0, "fd": 0, "fp": 0, "tn": 1, "fn": 0},
        "fields": {},  # Empty for primitive lists
        "raw_similarity_score": 1.0,  # Perfect match
        "similarity_score": 1.0,
        "threshold_applied_score": 1.0,
        "weight": weight
    }

Hungarian Matching Integration

# For primitive lists, use the comparison logic from _compare_unordered_lists
comparator = info.comparator
match_result = self._compare_unordered_lists(gt_list, pred_list, comparator, threshold)

# Extract the counts from the match result
tp = match_result.get("tp", 0)
fd = match_result.get("fd", 0) 
fa = match_result.get("fa", 0)
fn = match_result.get("fn", 0)

# Use the overall_score from the match result for raw similarity
raw_similarity = match_result.get("overall_score", 0.0)

# CRITICAL FIX: For lists, we NEVER clip under threshold - partial matches are important
threshold_applied_score = raw_similarity  # Always use raw score for lists

_compare_struct_list_with_scores(self, gt_list: List['StructuredModel'], pred_list: List['StructuredModel'], field_name: str) -> dict

This is the most complex handler, dealing with lists of structured objects. It implements sophisticated object-level and field-level analysis.

Critical Design Principle: Object-Level vs Field-Level Separation

• List-level metrics count OBJECTS, not individual fields
• Field-level details are kept separate for hierarchical analysis
• Tests expect TP=3 for 3 matched objects, not TP=9 for 3 objects × 3 fields each

Empty Case Handling with Match Statements

def _handle_struct_list_empty_cases(self, gt_list: List['StructuredModel'], pred_list: List['StructuredModel'], weight: float) -> dict:
    # Normalize None to empty lists for consistent handling
    gt_len = len(gt_list or [])
    pred_len = len(pred_list or [])

    match (gt_len, pred_len):
        case (0, 0):
            # Both empty lists → True Negative
            return {
                "overall": {"tp": 0, "fa": 0, "fd": 0, "fp": 0, "tn": 1, "fn": 0},
                "fields": {},
                "raw_similarity_score": 1.0,
                "similarity_score": 1.0,
                "threshold_applied_score": 1.0,
                "weight": weight
            }
        case (0, pred_len):
            # GT empty, pred has items → False Alarms
            return {
                "overall": {"tp": 0, "fa": pred_len, "fd": 0, "fp": pred_len, "tn": 0, "fn": 0},
                "fields": {},
                "raw_similarity_score": 0.0,
                "similarity_score": 0.0,
                "threshold_applied_score": 0.0,
                "weight": weight
            }
        case (gt_len, 0):
            # GT has items, pred empty → False Negatives
            return {
                "overall": {"tp": 0, "fa": 0, "fd": 0, "fp": 0, "tn": 0, "fn": gt_len},
                "fields": {},
                "raw_similarity_score": 0.0,
                "similarity_score": 0.0,
                "threshold_applied_score": 0.0,
                "weight": weight
            }
        case _:
            # Both non-empty, continue processing
            return None

Object-Level Metrics Calculation

def _calculate_object_level_metrics(self, gt_list: List['StructuredModel'], pred_list: List['StructuredModel'], match_threshold: float) -> tuple:
    # Use Hungarian matching for OBJECT-LEVEL counts
    hungarian_helper = HungarianHelper()
    matched_pairs = hungarian_helper.get_matched_pairs_with_scores(gt_list, pred_list)

    # Count OBJECTS, not individual fields
    tp_objects = 0  # Objects with similarity >= match_threshold
    fd_objects = 0  # Objects with similarity < match_threshold
    for gt_idx, pred_idx, similarity in matched_pairs:
        if similarity >= match_threshold:
            tp_objects += 1
        else:
            fd_objects += 1

    # Count unmatched objects
    matched_gt_indices = {idx for idx, _, _ in matched_pairs}
    matched_pred_indices = {idx for _, idx, _ in matched_pairs}
    fn_objects = len(gt_list) - len(matched_gt_indices)  # Unmatched GT objects
    fa_objects = len(pred_list) - len(matched_pred_indices)  # Unmatched pred objects

    # Build list-level metrics counting OBJECTS (not fields)
    object_level_metrics = {
        "tp": tp_objects,
        "fa": fa_objects,  
        "fd": fd_objects,
        "fp": fa_objects + fd_objects,  # Total false positives
        "tn": 0,  # No true negatives at object level for non-empty lists
        "fn": fn_objects
    }

    return object_level_metrics, matched_pairs, matched_gt_indices, matched_pred_indices

Field-Level Details Generation (Threshold-Gated Recursion)

The system only generates detailed field analysis for object pairs that meet the similarity threshold. This is a key performance optimization.

# Get field-level details for nested structure (but DON'T aggregate to list level)
# THRESHOLD-GATED RECURSION: Only generate field details for good matches
field_details = {}
if gt_list and isinstance(gt_list[0], StructuredModel):
    model_class = gt_list[0].__class__

    # Only create field structure if we have good matches (>= match_threshold)
    has_good_matches = any(sim >= match_threshold for _, _, sim in matched_pairs)
    has_unmatched = (len(matched_gt_indices) < len(gt_list)) or (len(matched_pred_indices) < len(pred_list))

    # Only generate field details if we have good matches OR unmatched objects
    if has_good_matches or has_unmatched:
        for sub_field_name in model_class.model_fields:
            if sub_field_name == 'extra_fields':
                continue

            # Check if this field is a List[StructuredModel] that needs hierarchical treatment
            field_info = model_class.model_fields.get(sub_field_name)
            is_hierarchical_field = (field_info and model_class._is_structured_field_type(field_info))

            if is_hierarchical_field:
                # Handle nested List[StructuredModel] fields with aggregation across matched pairs
                # ... [complex hierarchical processing logic]
            else:
                # Handle primitive fields - aggregate across all matched objects
                sub_field_metrics = {"tp": 0, "fa": 0, "fd": 0, "fp": 0, "tn": 0, "fn": 0}

                # THRESHOLD-GATED: Only process matched pairs above match_threshold
                for gt_idx, pred_idx, similarity in matched_pairs:
                    if similarity >= match_threshold and gt_idx < len(gt_list) and pred_idx < len(pred_list):
                        gt_item = gt_list[gt_idx]
                        pred_item = pred_list[pred_idx]
                        gt_sub_value = getattr(gt_item, sub_field_name)
                        pred_sub_value = getattr(pred_item, sub_field_name)

                        # Regular field - use flat classification
                        field_classification = gt_item._classify_field_for_confusion_matrix(sub_field_name, pred_sub_value)

                        # Aggregate field metrics across all objects
                        for metric in ["tp", "fa", "fd", "fp", "tn", "fn"]:
                            sub_field_metrics[metric] += field_classification.get(metric, 0)

Hungarian Matching Integration

The _compare_unordered_lists() Method

This method implements the core Hungarian matching algorithm through the HungarianHelper and ComparisonHelper classes.

Key Algorithm Features

1. Optimal Bipartite Matching: Finds the best possible pairing between lists
2. Similarity-Based: Uses actual similarity scores, not just binary match/no-match
3. Handles Unequal Lengths: Gracefully manages lists of different sizes
4. Threshold-Based Classification: Separates matches from false discoveries

Implementation Strategy

# Use HungarianHelper for Hungarian matching operations
hungarian_helper = HungarianHelper()

# Use the appropriate comparator based on item types
if all(isinstance(item, StructuredModel) for item in list1[:1]) and all(isinstance(item, StructuredModel) for item in list2[:1]):
    # For StructuredModel lists, use match_threshold for object-level classification
    model_class = list1[0].__class__
    match_threshold = getattr(model_class, 'match_threshold', 0.7)
    classification_threshold = match_threshold

    # Use HungarianHelper for StructuredModel matching
    matched_pairs = hungarian_helper.get_matched_pairs_with_scores(list1, list2)
else:
    # Use the provided comparator for other types
    from stickler.algorithms.hungarian import HungarianMatcher
    # Use match_threshold=0.0 to capture ALL matches, not just those above threshold
    hungarian = HungarianMatcher(comparator, match_threshold=0.0)
    classification_threshold = threshold

    # Get detailed metrics from HungarianMatcher
    metrics = hungarian.calculate_metrics(list1, list2)
    matched_pairs = metrics["matched_pairs"]

Threshold-Based Classification

# Apply threshold logic to classify matches
tp = 0  # True positives (score >= threshold)
fd = 0  # False discoveries (score < threshold, including 0)

for i, j, score in matched_pairs:
    # Use ThresholdHelper for consistent threshold checking
    if ThresholdHelper.is_above_threshold(score, classification_threshold):
        tp += 1
    else:
        # All matches below threshold are False Discoveries, including 0.0 scores
        fd += 1

# False alarms are unmatched prediction items
fa = len(list2) - len(matched_pairs)

# False negatives are unmatched ground truth items  
fn = len(list1) - len(matched_pairs)

# Total false positives include both false discoveries and false alarms
fp = fd + fa

Overall Score Calculation

# Calculate overall score considering ALL similarities, not just those above threshold
if not matched_pairs:
    overall_score = 0.0
else:
    # Average similarity across all matched pairs (regardless of threshold)
    total_similarity = sum(score for _, _, score in matched_pairs)
    avg_similarity = total_similarity / len(matched_pairs)

    # Scale by coverage ratio (matched pairs / max list size)
    max_items = max(len(list1), len(list2))
    coverage_ratio = len(matched_pairs) / max_items if max_items > 0 else 1.0
    overall_score = avg_similarity * coverage_ratio

Score Aggregation and Percolation

The Percolation System

The system uses a "percolation" approach where scores bubble up from leaf fields to parent objects, eventually reaching the top-level overall score.

Score Types

1. Raw Similarity Score: Direct output from comparators (0.0 to 1.0)
2. Similarity Score: Same as raw score, maintained for consistency
3. Threshold Applied Score: Raw score with threshold clipping applied based on clip_under_threshold setting

Weight-Based Aggregation

# Score percolation variables
total_score = 0.0
total_weight = 0.0
threshold_matched_fields = set()

for field_name in self.__class__.model_fields:
    # ... field processing ...

    # Score percolation - aggregate scores upward
    if "similarity_score" in field_result and "weight" in field_result:
        weight = field_result["weight"]
        threshold_applied_score = field_result["threshold_applied_score"]
        total_score += threshold_applied_score * weight
        total_weight += weight

        # Track threshold-matched fields
        info = self._get_comparison_info(field_name)
        if field_result["raw_similarity_score"] >= info.threshold:
            threshold_matched_fields.add(field_name)

# Calculate overall similarity score from percolated scores
if total_weight > 0:
    result["overall"]["similarity_score"] = total_score / total_weight

all_fields_matched Determination

# Determine all_fields_matched
model_fields_for_comparison = set(self.__class__.model_fields.keys()) - {'extra_fields'}
result["overall"]["all_fields_matched"] = len(threshold_matched_fields) == len(model_fields_for_comparison)

Aggregation Helper: _aggregate_to_overall()

def _aggregate_to_overall(self, field_result: dict, overall: dict) -> None:
    """Simple aggregation to overall metrics."""
    for metric in ["tp", "fa", "fd", "fp", "tn", "fn"]:
        if isinstance(field_result, dict):
            if metric in field_result:
                overall[metric] += field_result[metric]
            elif "overall" in field_result and metric in field_result["overall"]:
                overall[metric] += field_result["overall"][metric]

Threshold-Gated Recursion

The Optimization Strategy

For performance reasons, the system only performs detailed recursive analysis on object pairs that meet a minimum similarity threshold. Poor matches are treated as atomic failures.

Implementation in List Processing

# THRESHOLD-GATED RECURSION: Only perform recursive field analysis for object pairs
# with similarity >= StructuredModel.match_threshold. Poor matches and unmatched 
# items are treated as atomic units.

match_threshold = getattr(model_class, 'match_threshold', 0.7)

# For each field in the nested model
for field_name in model_class.model_fields:
    # ... initialization ...

    # THRESHOLD-GATED RECURSION: Only process pairs that meet the match_threshold
    for gt_idx, pred_idx, similarity_score in matched_pairs_with_scores:
        if gt_idx < len(gt_list) and pred_idx < len(pred_list):
            gt_item = gt_list[gt_idx]
            pred_item = pred_list[pred_idx]

            # Handle floating point precision issues
            is_above_threshold = similarity_score >= match_threshold or abs(similarity_score - match_threshold) < 1e-10

            # Only perform recursive field analysis if similarity meets threshold
            if is_above_threshold:
                # ... perform detailed field analysis ...
            else:
                # Skip recursive analysis for pairs below threshold
                # These will be handled as FD at the object level
                pass

Benefits

1. Performance: Avoids expensive recursion for obviously poor matches
2. Focus: Concentrates detailed analysis on promising matches
3. Scalability: Handles large lists more efficiently
4. Precision: Maintains accuracy by still counting object-level metrics

Performance Optimizations

Single Traversal Architecture

The biggest performance gain comes from the single-traversal design:

Before (Multiple Passes): 1. First pass: Calculate similarity scores 2. Second pass: Generate confusion matrix 3. Third pass: Collect non-matches 4. Result: 3× traversal cost

After (Single Pass): 1. One pass: Calculate scores AND confusion matrix AND collect non-matches 2. Result: 1× traversal cost with identical functionality

Lazy Evaluation

# Add optional features using already-computed recursive result
if include_confusion_matrix:
    confusion_matrix = recursive_result

    # Add derived metrics if requested
    if add_derived_metrics:
        confusion_matrix = self._add_derived_metrics_to_result(confusion_matrix)

    result["confusion_matrix"] = confusion_matrix

# Add optional non-match documentation
if document_non_matches:
    non_matches = recursive_result.get("non_matches", [])
    if not non_matches:  # Fallback to legacy method if needed
        non_matches = self._collect_non_matches(other)
        non_matches = [nm.model_dump() for nm in non_matches]
    result["non_matches"] = non_matches

Memory Efficiency

1. Hierarchical Results: Results maintain object structure without flattening
2. Streaming Processing: Process fields one at a time rather than loading all into memory
3. Efficient Data Structures: Use sets for tracking rather than lists where possible

Hungarian Algorithm Optimization

The Hungarian algorithm runs in O(n³) time, which is optimal for the assignment problem. The implementation optimizations include:

1. Early Termination: Stop when optimal assignment is found
2. Sparse Matrix Handling: Efficiently handle cases with many zero similarities
3. Threshold Pre-filtering: Use match_threshold=0.0 to capture all potential matches

Debugging and Troubleshooting

Common Issues and Solutions

1. Incorrect Similarity Scores

• Symptom: Scores don't match expectations
• Check: Field-level comparator configuration
• Debug: Add logging to _compare_primitive_with_scores()

2. Confusion Matrix Inconsistencies

• Symptom: TP + FP ≠ expected totals
• Check: Object vs field-level counting in list handlers
• Debug: Verify _calculate_object_level_metrics() logic

3. Performance Issues

• Symptom: Slow comparison on large objects
• Check: Threshold-gated recursion settings
• Debug: Profile compare_recursive() with timing

4. Memory Usage

• Symptom: High memory consumption
• Check: Result structure depth and breadth
• Debug: Monitor object creation in recursive calls

Debugging Helper Methods

def _debug_field_comparison(self, field_name: str, gt_val: Any, pred_val: Any):
    """Add this method for debugging field comparisons."""
    info = self._get_comparison_info(field_name)
    print(f"Field: {field_name}")
    print(f"  GT Value: {gt_val}")
    print(f"  Pred Value: {pred_val}")
    print(f"  Comparator: {info.comparator.__class__.__name__}")
    print(f"  Threshold: {info.threshold}")
    print(f"  Weight: {info.weight}")

    # Add to dispatch method for detailed logging
    result = self._dispatch_field_comparison(field_name, gt_val, pred_val)
    print(f"  Result: {result}")
    return result

Testing Complex Scenarios

For testing the monster functions, focus on:

1. Edge Cases: Empty lists, None values, type mismatches
2. Scale Testing: Large nested structures, deep recursion
3. Performance Testing: Time and memory usage under load
4. Correctness Testing: Known ground truth comparisons

Profiling Guidelines

import cProfile
import pstats

def profile_comparison(model1, model2):
    """Profile a comparison operation."""
    profiler = cProfile.Profile()
    profiler.enable()

    # Perform the comparison
    result = model1.compare_with(model2, include_confusion_matrix=True)

    profiler.disable()

    # Generate stats
    stats = pstats.Stats(profiler)
    stats.sort_stats('cumulative')
    stats.print_stats(20)  # Top 20 functions

    return result

Key Performance Metrics to Monitor

1. Function Call Counts: Track calls to recursive methods
2. Memory Allocation: Monitor object creation in loops
3. Hungarian Algorithm Performance: O(n³) scaling behavior
4. Threshold Gate Effectiveness: Ratio of processed vs skipped recursions

Code Maintenance Guidelines

When modifying the monster functions, follow these principles:

1. Preserve Single Traversal: Ensure all optimizations maintain one-pass processing
2. Maintain API Consistency: Keep hierarchical result structures intact
3. Document Design Decisions: Explain any performance vs accuracy trade-offs
4. Test Edge Cases: Verify behavior with empty/null/mismatched data
5. Profile Changes: Measure performance impact of modifications

Conclusion

The StructuredModel comparison system represents a sophisticated balance of performance, accuracy, and maintainability. The "monster functions" implement complex algorithms while maintaining clean, testable interfaces.

Key takeaways for developers:

• Single Traversal: The core optimization that makes everything else possible
• Type-Based Dispatch: Clean separation of concerns for different data types
• Hungarian Matching: Optimal list comparison with O(n³) complexity
• Threshold Gating: Performance optimization for deep recursion scenarios
• Hierarchical Results: Maintains interpretable structure at all levels

Understanding these principles will enable effective debugging, optimization, and extension of the comparison system.