File size: 5,434 Bytes
31f3902 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 | # Normalization Module
This module implements normalization functions for various signals used in neural network trust updates.
## Overview
The normalization module ensures that different signals are properly scaled to be within the same range [0,1] before they are combined. This promotes stability and predictability in the system.
## Components
### CrossCheckType Enum
Defines the types of cross-check signals:
- COSINE_SIMILARITY
- GENERAL_SCORE
### Key Functions
#### `normalize_logic_check`
Normalizes a binary logic check signal.
```python
def normalize_logic_check(raw_logic_check_value: any) -> float:
"""
Normalize a binary logic check value to 0.0 or 1.0.
Args:
raw_logic_check_value: Raw logic check value (should be interpretable as 0 or 1)
Returns:
Normalized value (0.0 or 1.0)
Raises:
ValueError: If input cannot be interpreted as binary
"""
```
#### `normalize_cross_check`
Normalizes a cross-check signal (e.g., similarity score).
```python
def normalize_cross_check(
cross_check_value: float, type: CrossCheckType, max_possible_value: Optional[float] = None
) -> float:
"""
Normalize a cross-check signal to the [0,1] range.
Args:
cross_check_value: Raw cross-check value
type: Type of cross-check (cosine similarity or general score)
max_possible_value: Maximum possible value (required for GENERAL_SCORE)
Returns:
Normalized value in [0,1]
Raises:
ValueError: If max_possible_value is not provided for GENERAL_SCORE
"""
```
#### `normalize_corroboration_signal`
Normalizes a corroboration signal using an exponential saturation function.
```python
def normalize_corroboration_signal(num_corroborators: int, kappa: float) -> float:
"""
Normalize a corroboration signal using an exponential saturation function.
Args:
num_corroborators: Number of corroborators (non-negative)
kappa: Positive constant controlling saturation rate
Returns:
Normalized value in [0,1]
Raises:
ValueError: If num_corroborators is negative or kappa is not positive
"""
```
#### `min_max_scale`
Generic min-max scaling function.
```python
def min_max_scale(value: float, current_min: float, current_max: float) -> float:
"""
Scale a value using min-max normalization.
Args:
value: Value to scale
current_min: Minimum value in the range
current_max: Maximum value in the range
Returns:
Scaled value in [0,1]
"""
```
#### `calculate_trust_delta`
Combines normalized signals into a single update value.
```python
def calculate_trust_delta(
logic_check_norm: float,
cross_check_norm: float,
corroboration_norm: float,
alpha: float,
beta: float,
gamma: float
) -> float:
"""
Calculate a trust update from normalized signals.
Args:
logic_check_norm: Normalized logic check [0,1]
cross_check_norm: Normalized cross-check [0,1]
corroboration_norm: Normalized corroboration [0,1]
alpha: Weight for logic check
beta: Weight for cross-check
gamma: Weight for corroboration
Returns:
Trust delta in [0,1] (if weights sum to ≤1)
"""
```
### SignalTracker Class
Maintains running min/max values for dynamic normalization.
```python
class SignalTracker:
"""
Track signal statistics for dynamic normalization.
Attributes:
min_value: Minimum observed value
max_value: Maximum observed value
Methods:
update(value): Update statistics with a new value
get_normalized(value): Get normalized version of a value
"""
```
## Mathematical Details
For logic check (binary signal):
- Output is either 0.0 or 1.0
For cross-check (cosine similarity):
- Rescaled via $(c+1)/2$ to map [-1,1] to [0,1]
For cross-check (general score):
- Normalized by dividing by max possible value and clipping to [0,1]
For corroboration signal:
- $\text{Corroboration} = 1 - \exp(-\kappa \cdot n_{\text{corroborators}})$
For min-max scaling:
- $\hat{x} = \frac{x - \min}{\max - \min}$
For trust delta:
- $\Delta T = \alpha L + \beta C + \gamma R$
- If $L,C,R \in [0,1]$ and $\alpha, \beta, \gamma$ are non-negative and sum to $\leq 1$, then $\Delta T \in [0,1]$
## Usage Example
```python
from snow_spike.normalization import normalize_logic_check, normalize_cross_check
from snow_spike.normalization import normalize_corroboration_signal, calculate_trust_delta
from snow_spike.utils.common import CrossCheckType
# Normalize logic check (binary)
logic_check = 1
logic_norm = normalize_logic_check(logic_check)
print(f"Normalized logic check: {logic_norm}")
# Normalize cross-check (cosine similarity)
cosine_sim = 0.75
cross_norm = normalize_cross_check(cosine_sim, CrossCheckType.COSINE_SIMILARITY)
print(f"Normalized cross-check: {cross_norm}")
# Normalize corroboration signal
num_corroborators = 5
kappa = 0.5
corr_norm = normalize_corroboration_signal(num_corroborators, kappa)
print(f"Normalized corroboration: {corr_norm}")
# Combine signals to calculate trust delta
alpha, beta, gamma = 0.3, 0.4, 0.3 # Weights sum to 1.0
delta_t = calculate_trust_delta(logic_norm, cross_norm, corr_norm, alpha, beta, gamma)
print(f"Trust delta: {delta_t}")
```
|