# How Bonus Points and Deductions Work in Hiring Agent Scoring

> Understand how Hiring Agent awards bonus points for excellence and applies deductions for shortcomings to calculate final scores. Maximize your understanding of the scoring system.

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

---

**Hiring Agent adds up to 20 bonus points for exceptional achievements and subtracts deductions for deficiencies, combining these with category scores to produce a final composite score capped at the maximum possible threshold.**

The `interviewstreet/hiring-agent` repository implements a nuanced evaluation system that grades technical candidates across multiple dimensions. Understanding how **bonus points** and **deductions** modify the base category scores is essential for interpreting evaluation results and integrating the scoring API into your hiring pipeline.

## Understanding Bonus Points and Deductions in Hiring Agent

### Bonus Points Structure

In [`main/models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/main/models.py), the `BonusPoints` class defines how extra credit is awarded. The `total` field accepts values between **0 and 20**, representing points added to the raw category scores. The `breakdown` field stores a free-form string explaining the specific achievements that earned the bonus, such as exceptional open-source contributions or leadership roles.

### Deductions Structure

Also defined in [`main/models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/main/models.py), the `Deductions` class penalizes missing or substandard items. The `total` field stores a positive integer representing points to subtract, while the `reasons` field documents the justification—for example, "Missing portfolio link" or "Incomplete technical documentation." These points are subtracted from the sum of category scores and bonus points.

## The Scoring Algorithm in score.py

The `print_evaluation_results` function in [`main/score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/main/score.py) implements a four-step calculation:

1. **Calculate capped category scores** for Open-Source, Self-Projects, Production, and Technical Skills.
2. **Add bonus points** from `evaluation.bonus_points.total` to the running sum.
3. **Subtract deductions** using `evaluation.deductions.total` from the total.
4. **Clamp the result** to the maximum possible overall score, defined as `max_score + 20` (accounting for the 20-point bonus cap).

The final output displays the composite score alongside the bonus and deduction breakdowns.

## Code Implementation Examples

### Creating Evaluation Data with Custom Scoring

You can construct `EvaluationData` objects directly for testing or integration purposes:

```python
from models import (
    CategoryScore,
    Scores,
    BonusPoints,
    Deductions,
    EvaluationData,
)

# Define capped category scores

scores = Scores(
    open_source=CategoryScore(score=30, max=35, evidence="Contributed to 3 OSS projects"),
    self_projects=CategoryScore(score=25, max=30, evidence="Built 2 personal apps"),
    production=CategoryScore(score=20, max=25, evidence="2 years at Acme Corp"),
    technical_skills=CategoryScore(score=8, max=10, evidence="Proficient in Python, Go")
)

# Award up to 20 bonus points

bonus = BonusPoints(total=12, breakdown="Extra points for open-source leadership")

# Apply deductions (stored as positive, applied as negative)

deductions = Deductions(total=3, reasons="Missing portfolio link")

# Assemble evaluation

evaluation = EvaluationData(
    scores=scores,
    bonus_points=bonus,
    deductions=deductions,
    key_strengths=["Strong problem-solving", "Team player"],
    areas_for_improvement=["Documentation", "Testing"]
)

```

### Running Evaluations from the Command Line

For standard usage, process résumés through the CLI:

```bash
python score.py path/to/candidate_resume.pdf

```

The script extracts content, invokes the LLM evaluator, and prints formatted results including the bonus and deduction details.

## Summary

- **Bonus points** are defined in [`main/models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/main/models.py) with a hard cap of 20 points and require a textual breakdown of achievements.
- **Deductions** subtract from the total score and include documented reasons for the penalty.
- The scoring pipeline in [`main/score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/main/score.py) applies bonuses additively and deductions subtractively before clamping to the maximum threshold.
- Both components integrate into the `EvaluationData` structure returned by the LLM evaluator.

## Frequently Asked Questions

### What is the maximum number of bonus points in Hiring Agent?

The `BonusPoints` class enforces a maximum of **20 points** via validation logic in [`main/models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/main/models.py). This limit ensures the bonus system remains a secondary modifier rather than overriding the core category evaluation.

### How are deductions represented in the data model?

Deductions store the point value as a **positive integer** in the `total` field but are applied as a negative value during the final calculation in `print_evaluation_results`. The `reasons` field provides transparency for why points were removed.

### Can the final score exceed the standard maximum?

Yes, but only by the bonus cap. The final score clamps to `max_score + 20`, meaning if a candidate scores perfectly across all categories and receives 20 bonus points, they achieve the theoretical maximum.

### Where does the EvaluationData object originate?

The `EvaluationData` object containing scores, bonuses, and deductions is generated by the LLM evaluator (typically in [`main/evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/main/evaluator.py)) and consumed by the scoring logic in [`main/score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/main/score.py) to produce the final composite grade.