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.

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