Skip to content

Scoring Utilities

scoring

Utility functions for score calculations.

This module provides helper functions for score normalization and weighted averaging.

Functions

clamp_score 
clamp_score(value, min_value=0.0, max_value=100.0)

Clamp a score value to a specified range.

Ensures the score stays within valid bounds by applying min/max constraints.

Parameters:

Name Type Description Default
value float

The score value to clamp.

 required
min_value float

Minimum allowed value (default: 0.0).

 0.0
max_value float

Maximum allowed value (default: 100.0).

 100.0

Returns:

Type Description
float

Clamped value between min_value and max_value (inclusive).
Example 
clamp_score(150.0)  # Returns 100.0
clamp_score(-10.0)  # Returns 0.0
clamp_score(75.5)   # Returns 75.5
Source code in at_scorer/utils/scoring.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
def clamp_score(value: float, min_value: float = 0.0, max_value: float = 100.0) -> float:
    """Clamp a score value to a specified range.

    Ensures the score stays within valid bounds by applying min/max constraints.

    Args:
        value: The score value to clamp.
        min_value: Minimum allowed value (default: 0.0).
        max_value: Maximum allowed value (default: 100.0).

    Returns:
        Clamped value between min_value and max_value (inclusive).

    Example:
        ```python
        clamp_score(150.0)  # Returns 100.0
        clamp_score(-10.0)  # Returns 0.0
        clamp_score(75.5)   # Returns 75.5
        ```
    """
    return max(min_value, min(max_value, value))
weighted_score 
weighted_score(scores, weights)

Calculate a weighted average score from multiple category scores.

Computes a weighted average of scores where each score is multiplied by its corresponding weight, then normalized by the total weight. The result is scaled to 0-100 range.

Parameters:

Name Type Description Default
scores dict[str, float]

Dictionary mapping category names to their scores (0.0-1.0 range).

 required
weights dict[str, float]

Dictionary mapping category names to their weights. Weights are normalized automatically, so they don't need to sum to 1.0.

 required

Returns:

Type Description
float

Weighted average score scaled to 0-100 range.
Example 
scores = {"keyword": 0.8, "skills": 0.9}
weights = {"keyword": 0.4, "skills": 0.6}
result = weighted_score(scores, weights)  # Returns ~85.0
Source code in at_scorer/utils/scoring.py 
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
def weighted_score(scores: dict[str, float], weights: dict[str, float]) -> float:
    """Calculate a weighted average score from multiple category scores.

    Computes a weighted average of scores where each score is multiplied by its
    corresponding weight, then normalized by the total weight. The result is
    scaled to 0-100 range.

    Args:
        scores: Dictionary mapping category names to their scores (0.0-1.0 range).
        weights: Dictionary mapping category names to their weights. Weights are
            normalized automatically, so they don't need to sum to 1.0.

    Returns:
        Weighted average score scaled to 0-100 range.

    Example:
        ```python
        scores = {"keyword": 0.8, "skills": 0.9}
        weights = {"keyword": 0.4, "skills": 0.6}
        result = weighted_score(scores, weights)  # Returns ~85.0
        ```
    """
    total_weight = sum(weights.values()) or 1.0
    accum = 0.0
    for key, weight in weights.items():
        accum += scores.get(key, 0.0) * weight
    return (accum / total_weight) * 100.0