Standardize predict() method signatures across Score implementations

[endymion]

Problem

During validation system implementation, I discovered inconsistent predict() method signatures across different Score implementations:

Current Signatures Found:

1. Standard signature (intended): predict(self, context, model_input: Score.Input)
2. Legacy signature: predict(self, model_input: Score.Input)
3. Keyword-only signature: predict(self, *, context, model_input: Score.Input)

Examples in Codebase:

Legacy signature examples:

• plexus/processors/RelevantWindowsTranscriptFilter_test.py:19
• Various test mock implementations

Standard signature examples:

• Abstract method definition in Score.py:576
• Most production Score implementations

Keyword-only signature examples:

• Some test implementations

Impact

• Inconsistent API: Different calling conventions confuse developers
• Maintenance burden: Need to support multiple signatures
• Error-prone: Easy to call methods incorrectly
• Documentation clarity: Unclear which signature is "correct"

Proposed Solution

1. Standardize on: predict(self, context, model_input: Score.Input) -> Union[Score.Result, List[Score.Result]]

   • This matches the abstract method definition
   • Provides context for future extensibility
   • Most implementations already use this

2. Migration plan:

   • Update legacy implementations to standard signature
   • Add deprecation warnings for old signatures (optional)
   • Update tests and documentation
   • Consider adding linting rules to prevent regression

3. Files to update:

   • Test mock classes in plexus/processors/RelevantWindowsTranscriptFilter_test.py
   • Any other legacy implementations found via codebase search

Current Workaround

The validation system now includes compatibility handling for all three signatures using signature inspection and argument adaptation. While this works, it adds complexity and should be temporary.

Next Steps

1. Search codebase for all predict() method implementations
2. Identify which ones need updating
3. Create migration plan with backward compatibility considerations
4. Update implementations systematically
5. Remove compatibility code once migration is complete

This standardization will improve code consistency, reduce maintenance burden, and make the API clearer for developers.

[endymion]

Specific Complexity Added to Score.py

The signature inconsistency has forced us to add significant complexity to the validation system in Score.py. Here's the specific code that could be simplified:

Current Complex Implementation (Score.py:636-672)

def validated_predict(*args, **kwargs):
    # Handle different predict method signatures:
    # 1. predict(context, model_input) - standard signature
    # 2. predict(model_input) - legacy signature  
    # 3. predict(*, context, model_input) - keyword-only signature
    
    try:
        # Try calling with original arguments
        results = original_predict(*args, **kwargs)
    except TypeError as e:
        # If that fails, try to adapt the call based on signature inspection
        import inspect
        sig = inspect.signature(original_predict)
        
        # Check if this is a legacy single-argument predict method
        if len(sig.parameters) == 1:
            # Legacy signature: predict(model_input)
            if len(args) == 2:
                # Called with (context, model_input), use just model_input
                results = original_predict(args[1])
            elif len(args) == 1:
                # Called with (model_input), pass through
                results = original_predict(args[0])
            elif 'model_input' in kwargs:
                # Called with keyword args
                results = original_predict(kwargs['model_input'])
            else:
                # Re-raise original error if we can't adapt
                raise e
        else:
            # Standard signature but different calling convention
            if len(args) == 2:
                # Try keyword-only arguments
                results = original_predict(context=args[0], model_input=args[1])
            else:
                # Re-raise original error
                raise e
    
    # Apply validation logic...

What This Could Be With Standardized Signatures

def validated_predict(context, model_input):
    # Simple, clean call - no signature detection needed
    results = original_predict(context, model_input)
    
    # Apply validation logic...

Complexity Removed

1. No dynamic signature inspection - eliminates inspect.signature() overhead
2. No try/catch error handling - eliminates TypeError handling complexity
3. No argument adaptation logic - eliminates complex parameter mapping
4. No import overhead - eliminates runtime import inspect
5. Cleaner, more maintainable code - reduces from ~40 lines to ~5 lines
6. Better performance - removes runtime signature analysis
7. Easier debugging - eliminates complex call stack adaptations

Performance Impact

The current implementation adds overhead to every single predict() call across the entire Plexus system:

• Signature inspection on first call per method
• Exception handling on every incompatible call
• Dynamic argument remapping

With standardized signatures, this becomes a simple, direct method call.

Maintenance Benefits

• Easier to understand - no complex compatibility layer
• Easier to debug - straightforward call stack
• Easier to extend - no need to update compatibility logic
• Easier to test - no edge cases around signature adaptation

This complexity exists purely to maintain backward compatibility with inconsistent signatures. Standardizing would eliminate it entirely.