How the Bonus Points and Deductions System Works in the Hiring Agent

The Hiring Agent applies a hard-capped category scoring system that adds up to 20 bonus points and subtracts deductions from the total, then clamps the final result to a theoretical maximum of 120 points.

The interviewstreet/hiring-agent repository implements a transparent résumé evaluation engine that balances quantitative category scores with manual adjustments. Understanding how the bonus points and deductions system interacts with core scoring categories ensures fair candidate assessments. The implementation relies on Pydantic models defined in main/models.py and calculation logic centralized in main/score.py.

Core Category Scoring with Hard Caps

The evaluation begins by iterating over four categories defined in the EvaluationData.scores model: open_source, self_projects, production, and technical_skills. In main/score.py (lines 45‑50), the system sums each category's score after applying an initial cap against the model-defined max:

for category_name, category_data in evaluation.scores.model_dump().items():
    category_score = min(category_data["score"], category_data["max"])
    total_score += category_score
    max_score   += category_data["max"]

However, stricter hard caps are enforced in main/score.py (lines 80‑85) to prevent any single dimension from inflating the overall result:

• open_source: 35 points
• self_projects: 30 points
• production: 25 points
• technical_skills: 10 points

These hard caps are applied when displaying detailed results (lines 87‑122), ensuring the visualized score never exceeds the cap even if raw evidence suggests higher values.

Bonus Points Configuration

The BonusPoints model in main/models.py (lines 31‑34) enforces a strict ceiling using Pydantic validation:

class BonusPoints(BaseModel):
    total: float = Field(ge=0, le=20,
                        description="Total bonus points")
    breakdown: str = Field(description="Breakdown of bonus points")

During calculation, main/score.py checks for the existence of a bonus_points object and adds its total to the running score (lines 58‑60):

if hasattr(evaluation, "bonus_points") and evaluation.bonus_points:
    total_score += evaluation.bonus_points.total

The breakdown string is rendered in the final output (lines 126‑130) to maintain transparency regarding why extra points were awarded.

Deductions Implementation

Deductions follow a similar pattern but use inverse arithmetic. The Deductions model in main/models.py (lines 36‑42) stores values as positive numbers while documenting the semantic intent:

class Deductions(BaseModel):
    total: float = Field(ge=0,
                         description="Total deduction points (stored as positive, applied as negative)")
    reasons: str = Field(description="Reasons for deductions")

The application logic in main/score.py (lines 62‑64) subtracts this value from the accumulated total:

if hasattr(evaluation, "deductions") and evaluation.deductions:
    total_score -= evaluation.deductions.total

Reasons are displayed under a dedicated "DEDUCTIONS" heading in the final report to provide clear justification for score reductions.

Overall Score Capping and Final Calculation

After applying bonuses and deductions, the system enforces a final boundary. The theoretical maximum equals the sum of category maximums (100 points) plus the 20-point bonus ceiling:

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

if total_score > max_possible_score:
    total_score = max_possible_score

This ensures the final displayed score (formatted as OVERALL SCORE: <total>/<max_score> at lines 71‑73) never exceeds the calibrated maximum, even if bonus points would otherwise push it higher. Additionally, main/transform.py (lines 716‑720) records bonus data during CSV transformation for audit trails.

Complete Evaluation Example

The following snippet demonstrates the runtime flow using the actual models and scoring logic:

from main.models import EvaluationData, Scores, CategoryScore, BonusPoints, Deductions
from main.score import print_evaluation_results

# Construct evaluation with bonus and deduction adjustments

evaluation = EvaluationData(
    scores=Scores(
        open_source=CategoryScore(score=38, max=35, evidence="10 repos, 5 starred"),
        self_projects=CategoryScore(score=28, max=30, evidence="Personal app"),
        production=CategoryScore(score=24, max=25, evidence="2 years at Acme"),
        technical_skills=CategoryScore(score=9, max=10, evidence="Python, Go")
    ),
    bonus_points=BonusPoints(
        total=12, 
        breakdown="+5 for conference talks, +7 for open-source maintainer"
    ),
    deductions=Deductions(
        total=3, 
        reasons="Missing portfolio link"
    ),
    key_strengths=["Strong algorithmic thinking"],
    areas_for_improvement=["Better CI/CD exposure"]
)

# Execute scoring and display results

print_evaluation_results(evaluation, candidate_name="Alice")

This mirrors the production implementation in main/score.py, showing how the 12 bonus points increase the total while the 3-point deduction reduces it, subject to the 120-point overall cap.

Summary

• Four core categories are scored and capped individually before bonuses apply, with hard limits ranging from 10 to 35 points per category.
• Bonus points are capped at 20 points total via Pydantic validation in main/models.py and added unconditionally if present in the evaluation object.
• Deductions are stored as positive values in the model but subtracted arithmetically during final calculation in main/score.py.
• Final clamping ensures the overall score never exceeds the sum of category maximums plus the 20-point bonus ceiling (120 points total).
• Transparency is maintained through breakdown strings for bonuses and reason fields for deductions, both rendered in the final output.

Frequently Asked Questions

What is the maximum possible score in the Hiring Agent?

The absolute maximum is 120 points, calculated as the sum of category maximums (100 points across four categories) plus the 20-point bonus ceiling defined in the BonusPoints model. Even if raw calculations exceed this value, the final clamping logic in main/score.py forces the total down to this limit.

How are bonus points validated before application?

Validation occurs at the model level in main/models.py using Pydantic's Field(ge=0, le=20) constraint, which rejects any BonusPoints instantiation with a total outside the 0‑20 range. This prevents human reviewers from accidentally assigning excessive bonus values during manual evaluation entry.

Can deductions reduce a candidate's score below zero?

While the Deductions model enforces ge=0 (non-negative storage), the subtraction logic in main/score.py could theoretically result in negative totals if deductions exceed accumulated category scores. However, the practical minimum is constrained by the requirement that candidates must have some base score to evaluate before deductions are applied.

Where are the category hard caps defined?

The hard caps (35, 30, 25, and 10 points) are hard-coded as conditional logic in main/score.py (lines 80‑85), separate from the max values stored in the CategoryScore model. This dual-layer capping system allows the model to accept higher raw scores while the presentation layer enforces stricter limits during final evaluation display.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}