Skip to content

Improve error handling and type hints across validator and miner modules #225

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sm4rtdev wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Improve error handling and type hints across validator and miner modules #225

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5a8c127
Improve error handling and type hints across validator and miner modules
sm4rtdev Dec 25, 2025
a0b33c3
Merge branch 'main' into refactor/improve-error-handling
sm4rtdev Dec 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
215 changes: 215 additions & 0 deletions IMPROVEMENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,215 @@
# Code Quality Improvements

## Overview

This PR introduces comprehensive improvements to error handling, type hints, and documentation across key modules of the Affine project. These changes enhance code reliability, maintainability, and developer experience.

## Changes Summary

This PR includes improvements to 4 key modules:
1. `affine/src/validator/weight_setter.py` - Weight processing and on-chain setting
2. `affine/core/miners.py` - Miner information queries
3. `affine/src/validator/main.py` - Validator service error handling
4. `affine/src/scorer/scorer.py` - Scoring algorithm documentation

## Detailed Improvements

### 1. Enhanced Error Handling in `affine/src/validator/weight_setter.py`

**Problem**: The weight setter used generic `Exception` catching, making it difficult to handle specific error cases and provide meaningful error messages.

**Solution**:
- Introduced custom exception classes: `WeightProcessingError` and `WeightSettingError`
- Added specific exception handling for network errors (`NetworkError`, `ConnectionError`, `TimeoutError`)
- Improved error messages with context about what operation failed
- Added validation for `burn_percentage` parameter (must be 0.0-1.0)
- Enhanced logging with more detailed error information
- Added comprehensive docstrings with parameter descriptions and return types

**Benefits**:
- Better error diagnostics for debugging weight setting issues
- More robust handling of network failures with proper retry logic
- Clearer error messages for operators and developers
- Type safety improvements with proper exception chaining
- Improved code maintainability with detailed documentation

**Code Example**:
```python
# Before: Generic exception handling
except Exception as e:
logger.error(f"Error: {e}")

# After: Specific exception types with context
except (NetworkError, ConnectionError, TimeoutError) as e:
logger.error(f"Network error setting weights: {e}")
raise WeightSettingError(f"Failed after {max_retries} attempts") from e
```

### 2. Improved Error Handling in `affine/core/miners.py`

**Problem**: The miner query function used generic exception handling and lacked proper validation, making it difficult to diagnose issues when fetching miner information.

**Solution**:
- Introduced `MinerQueryError` exception class for miner-specific errors
- Added validation for UID bounds checking
- Improved error handling for JSON parsing errors
- Enhanced chute info fetching with specific network error handling
- Added better logging with debug/trace levels for troubleshooting
- Improved type hints with proper Optional types and Any for metagraph
- Added comprehensive docstrings with examples

**Benefits**:
- More reliable miner information retrieval
- Better error messages when blockchain queries fail
- Improved debugging capabilities with detailed logging
- Type safety with proper exception handling
- Better developer experience with clear documentation

**Code Example**:
```python
# Before: Generic exception catching
except Exception as e:
logger.trace(f"Failed: {e}")
return None

# After: Specific error handling with context
except (KeyError, IndexError, ValueError) as e:
logger.debug(f"Data parsing error for miner uid={uid}: {e}")
return None
except NetworkError as e:
logger.debug(f"Network error fetching chute info: {e}")
return None
```

### 3. Enhanced Error Handling in `affine/src/validator/main.py`

**Problem**: The validator service used generic exception handling, making it difficult to distinguish between network errors and other types of failures.

**Solution**:
- Added specific exception handling for network errors (`NetworkError`, `ConnectionError`, `TimeoutError`) in weight and config fetching
- Improved wallet loading error handling with specific exception types (`FileNotFoundError`, `KeyError`)
- Enhanced error messages with more context
- Better separation of network errors from other unexpected errors
- Added proper exception chaining for debugging

**Benefits**:
- Better diagnostics for network-related issues
- More accurate error reporting for operators
- Improved retry logic understanding (network errors vs other errors)
- Enhanced debugging capabilities

**Code Example**:
```python
# Before: Generic exception handling
except Exception as e:
logger.error(f"Error fetching weights: {e}")

# After: Specific network error handling
except (NetworkError, ConnectionError, TimeoutError) as e:
logger.error(f"Network error fetching weights: {e}")
# Retry logic for network errors
except Exception as e:
logger.error(f"Unexpected error: {e}", exc_info=True)
```

### 4. Enhanced Documentation in `affine/src/scorer/scorer.py`

**Problem**: The `calculate_scores` method lacked detailed documentation about the scoring algorithm stages and expected data formats.

**Solution**:
- Added comprehensive docstring explaining the four-stage scoring algorithm
- Documented expected input data formats
- Added detailed return value descriptions
- Improved type hints (changed `list` to `List[str]` for environments)
- Added exception documentation

**Benefits**:
- Better understanding of the scoring algorithm for developers
- Clearer API documentation
- Improved type safety
- Easier onboarding for new contributors

## Technical Details

### Exception Hierarchy

The improvements introduce a clear exception hierarchy:

```
AffineError (base)
├── WeightProcessingError
├── WeightSettingError
└── MinerQueryError
```

This allows for:
- Specific error handling at different levels
- Better error messages with context
- Proper exception chaining for debugging

### Type Safety Improvements

- Added proper `Optional` type hints where values can be None
- Enhanced function signatures with return type annotations
- Improved parameter type hints for better IDE support
- Changed generic `list` to `List[str]` for better type checking

### Logging Enhancements

- Added debug-level logging for non-critical errors
- Improved trace-level logging for detailed debugging
- Better error context in log messages
- More informative error messages with operation context

## Testing Recommendations

1. **Weight Setter**:
- Test with invalid `burn_percentage` values (should raise `WeightProcessingError`)
- Test network failure scenarios (should raise `WeightSettingError`)
- Test with empty or invalid weight data

2. **Miner Queries**:
- Test with invalid UIDs (should handle gracefully)
- Test with network failures during chute info fetching
- Test with malformed commit data

3. **Validator Service**:
- Test weight fetching with network failures
- Test config fetching with API errors
- Test wallet loading with invalid credentials

4. **Scorer**:
- Test with empty environments list
- Test with invalid scoring_data format
- Verify all four stages execute correctly

## Backward Compatibility

All changes are backward compatible:
- No breaking changes to public APIs
- Exception types are subclasses of existing base classes
- Function signatures remain compatible (only added Optional types and improved type hints)
- All existing code will continue to work

## Performance Impact

These improvements have minimal performance impact:
- Exception handling overhead is negligible
- Additional logging only occurs on errors (debug/trace levels)
- Type hints are compile-time only (no runtime overhead)
- Improved error handling may actually improve performance by avoiding unnecessary retries

## Future Improvements

Potential follow-up improvements:
1. Add retry logic with exponential backoff for network operations
2. Implement circuit breaker pattern for external API calls
3. Add metrics/monitoring for error rates
4. Create comprehensive unit tests for error scenarios
5. Add integration tests for the complete validator workflow
6. Implement structured logging with correlation IDs

## Contribution

Contribution by Gittensor, learn more at https://gittensor.io/

Loading