# Expected Output Format from the Hiring-Agent's Analysis: Structure and Schema

> Understand the hiring agent's output format. Discover the structured JSON schema, overall scores, category breakdowns, and actionable feedback for your analysis.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: api-reference
- Published: 2026-07-04

---

**The hiring-agent produces a human-readable terminal report featuring an overall score out of 120, detailed category breakdowns, bonus points, deductions, and actionable feedback, generated from a structured JSON schema defined in the [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) file.**

The interviewstreet/hiring-agent is an open-source resume evaluation tool that analyzes PDF resumes using Large Language Models (LLMs). Understanding the expected output format from the hiring-agent's analysis is essential for integrating the tool into hiring workflows, parsing results programmatically, or customizing the evaluation display.

## Architecture of the Output Pipeline

The end-to-end pipeline orchestrated in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) processes candidate data through distinct stages before rendering the final report.

### Resume Extraction and Enrichment

First, `PDFHandler.extract_json_from_pdf()` in [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) converts the PDF into a structured `JSONResume` object. Optionally, `fetch_and_display_github_info()` in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) appends public repository data and profile information to enrich the evaluation context.

### LLM Evaluation and Schema Validation

The `ResumeEvaluator.evaluate_resume()` method constructs a structured prompt and sends it to the configured LLM (Ollama or Gemini). The model returns a JSON payload that strictly conforms to the `EvaluationData` Pydantic schema defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), ensuring type-safe validation of all scores, evidence text, and feedback categories.

### Terminal Formatting and Rendering

Finally, `print_evaluation_results()` in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) consumes the validated `EvaluationData` object and renders the formatted output to **stdout**. The calculation logic—handling category score caps, bonus point limits, and the absolute maximum of 120 points—resides in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) lines 41-70 and 78-130.

## Structure of the Terminal Output Report

The formatted report uses visual separators, emoji prefixes, and aligned columns to maximize readability in terminal environments:

- **Overall Score**: Displayed as `🎯 OVERALL SCORE: <total>/<max>` where the maximum possible is 120 points
- **Detailed Scores**: Four evaluated categories with individual caps:
  - `open_source` (35 points maximum)
  - `self_projects` (30 points maximum)
  - `production` (25 points maximum)
  - `technical_skills` (10 points maximum)
- **Bonus Points**: `⭐ BONUS POINTS: <total>` with descriptive breakdown
- **Deductions**: `⚠️ DEDUCTIONS: -<total>` accompanied by specific reasons
- **Key Strengths**: Numbered list of up to 5 strengths extracted from the evaluation
- **Areas for Improvement**: Numbered list of up to 5 specific suggestions

## Capturing and Parsing the Output

To generate the standard terminal report, execute the main pipeline:

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

```

Typical output appears as:

```

================================================================================
📊 RESUME EVALUATION RESULTS FOR: Jane Doe
================================================================================

🎯 OVERALL SCORE: 92.5/115

📈 DETAILED SCORES:
------------------------------------------------------------
🌐 Open Source:          32/35
   Evidence: Contributed to 3 open‑source libraries

🚀 Self Projects:        28/30
   Evidence: Built a personal CI/CD tool

🏢 Production Experience: 20/25
   Evidence: 2 years as backend engineer

💻 Technical Skills:     9/10
   Evidence: Strong Go, Python, Docker skills

⭐ BONUS POINTS: 5
------------------------------
   Extra credit for community mentorship

⚠️  DEDUCTIONS: -3
------------------------------
   Minor gaps in cloud architecture knowledge

✅ KEY STRENGTHS:
------------------------------
  1. Consistent delivery of high‑quality code
  2. Passion for open source

🔧 AREAS FOR IMPROVEMENT:
------------------------------
  1. Deepen AWS/GCP expertise

```

### Accessing Raw JSON Data

For programmatic integration, access the underlying `EvaluationData` object before formatting:

```python
from score import _evaluate_resume, PDFHandler

pdf = PDFHandler()
resume = pdf.extract_json_from_pdf("resume.pdf")
eval_data = _evaluate_resume(resume)

# Serialize to JSON

print(eval_data.json(indent=2))

```

## Core Files Defining the Output Format

| File | Function | Responsibility |
|------|----------|----------------|
| [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) | `print_evaluation_results()` | Renders human-readable terminal output with emoji separators |
| [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) | `EvaluationData` schema | Defines Pydantic models for JSON validation and structure |
| [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) | `evaluate_resume()` | Wraps LLM calls and parses responses into `EvaluationData` |
| [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) | `PDFHandler` class | Extracts `JSONResume` from PDF inputs |
| [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) | `fetch_and_display_github_info()` | Enriches resume data with public GitHub metrics |

## Summary

- The hiring-agent outputs a terminal-formatted report with emoji separators, aligned columns, and visual boundaries for immediate human review
- Raw structured data conforms to the `EvaluationData` Pydantic schema defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), enabling machine parsing
- The scoring system caps at 120 total points across four categories (open source, self projects, production, technical skills) plus bonuses minus deductions
- Calculation logic in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) enforces category maximums and handles score capping automatically
- Both CLI terminal output and programmatic JSON access are supported through the same pipeline

## Frequently Asked Questions

### What is the maximum possible score in the hiring-agent's evaluation?

The maximum total score is **120 points**, calculated from four category maximums (35 + 30 + 25 + 10 = 100) plus possible bonus points, minus any deductions. The calculation logic in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) lines 41-70 enforces caps on individual categories and ensures the final total never exceeds 120.

### Can I extract the evaluation results as JSON instead of terminal text?

Yes. The `EvaluationData` object returned by `_evaluate_resume()` in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) can be serialized using the `.json()` method. This Pydantic model defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) contains all category scores, evidence text, bonus details, deductions, strengths, and improvement areas in a structured format suitable for API responses or database storage.

### Which file handles the formatting of the terminal output?

The `print_evaluation_results()` function in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) handles all terminal-specific formatting, including emoji prefixes (`🎯`, `⭐`, `⚠️`), separator lines (`====`), and the visual layout of scores and feedback. This function consumes the validated `EvaluationData` object and prints directly to stdout.

### How does the hiring-agent calculate the overall score?

The system sums the four category scores (capped at their respective maximums), adds any bonus points, and subtracts deductions. The `EvaluationData` schema in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) defines these fields, while the display logic in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) handles the arithmetic and enforces the 120-point global maximum, ensuring consistent scoring across all evaluations.