# How the Score Capping Mechanism Prevents Exceeding Maximum Values in Hiring-Agent

> Learn how Hiring Agent's score capping mechanism uses min comparisons to prevent exceeding maximum values at category and aggregate levels, ensuring accurate résumé evaluations.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: internals
- Published: 2026-06-27

---

**The score capping mechanism in Hiring-Agent enforces hard ceilings at both the individual category level and the final aggregate level, using `min()` comparisons and conditional checks in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) to ensure no résumé evaluation exceeds its defined maximums.**

The `interviewstreet/hiring-agent` repository evaluates résumés across multiple dimensions including Open Source contributions and Technical Skills. To maintain realistic ratings, the **score capping mechanism** implements dual safeguards that limit both individual category scores and the overall total, preventing calculation errors or bonus inflation from producing impossible values.

## Per-Category Score Capping in score.py

The system defines hard ceilings for each evaluation dimension in the `category_maxes` dictionary. When `print_evaluation_results` processes the evaluation, it clamps each raw score using `min()` before displaying it.

The category maximums are:

- **Open Source**: 35 points
- **Self Projects**: 30 points
- **Production Experience**: 25 points
- **Technical Skills**: 10 points

In [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), the Open Source block (lines 88-92) implements this as:

```python
os_score = evaluation.scores.open_source
capped_score = min(os_score.score, category_maxes["open_source"])
print(f"🌐 Open Source: {capped_score}/{os_score.max}")

```

Identical logic appears for Self Projects (lines 96-102), Production Experience (lines 106-110), and Technical Skills (lines 115-121).

## Overall Score Capping and Bonus Limits

After summing category totals and applying bonus or deduction points, the code validates against the theoretical maximum. The cap is calculated as `max_score + 20`, representing the 100 base points across all categories plus a 20-point bonus allowance.

At lines 66-69 in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), the enforcement logic reads:

```python
max_possible_score = max_score + 20  # 120 (100 categories + 20 bonus)

if total_score > max_possible_score:
    total_score = max_possible_score
    print(f"⚠️  Warning: Total score capped at maximum possible value")

```

This ensures the final aggregate never exceeds 120 points, regardless of bonus inflation.

## Supporting Implementation Files

The capping mechanism relies on data structures defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), which provides the score objects accessed by the clamping code. The [`transform.py`](https://github.com/interviewstreet/hiring-agent/blob/main/transform.py) module converts raw evaluation results into the `EvaluationData` object consumed by `print_evaluation_results`, while [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) generates the initial raw scores that undergo capping in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py).

## Summary

- The **score capping mechanism** applies dual safeguards in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py): per-category caps and an overall aggregate cap.
- Per-category capping uses `min(raw_score, category_max)` at lines 88-121 to clamp Open Source (35), Self Projects (30), Production Experience (25), and Technical Skills (10).
- The overall cap limits totals to `max_score + 20` (120 points) at lines 66-69, triggering a warning when enforced.
- Supporting infrastructure resides in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), [`transform.py`](https://github.com/interviewstreet/hiring-agent/blob/main/transform.py), and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).

## Frequently Asked Questions

### What is the maximum possible score in Hiring-Agent?

The theoretical maximum is **120 points**, calculated as the sum of all category maximums (100 points) plus a 20-point bonus buffer. This is enforced in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) at lines 66-69 where the code caps `total_score` at `max_score + 20`.

### How does the per-category score cap work?

Each category has a hard ceiling stored in the `category_maxes` dictionary. When processing results, the code calculates `min(os_score.score, category_maxes["open_source"])` (and equivalents for other categories at lines 88-121) to ensure the displayed value never exceeds the defined maximum for that dimension.

### What happens when the total score exceeds the maximum?

When the aggregated score surpasses `max_score + 20`, the system forcibly sets `total_score` to that limit and prints a warning message: "⚠️ Warning: Total score capped at maximum possible value". This prevents bonus calculations or edge cases from producing impossible final ratings.

### Which file contains the score capping logic?

The core capping logic resides in **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)**, specifically within the `print_evaluation_results` function. Lines 88-121 handle per-category capping, while lines 66-69 manage the overall aggregate cap. Supporting data structures are defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py).