docs/normalization.md

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.

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).

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.

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.

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.

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.

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

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}")