# What Is the Main Entry Point for the Hiring Agent Pipeline?

> Discover the main entry point for the Hiring Agent pipeline at score.py's main(pdf_path) function. Orchestrate PDF ingestion and fairness evaluation effortlessly.

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

---

**The main entry point for the Hiring Agent pipeline is the `main(pdf_path)` function in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), which orchestrates the complete workflow from PDF ingestion to fairness-aware evaluation when invoked via the command line or imported programmatically.**

The `interviewstreet/hiring-agent` repository implements an automated resume evaluation system. Understanding the main entry point for the Hiring Agent pipeline is essential for developers integrating this tool into CI workflows or extending its capabilities. The entire process is coordinated through a single orchestrator module that handles document conversion, LLM-based extraction, GitHub profile enrichment, and structured scoring.

## The Orchestrator Module: score.py

The definitive entry point resides in the [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) module at the repository root. This file defines the `main(pdf_path)` function that drives the entire evaluation pipeline, along with a `__main__` block that enables direct script execution.

When [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) is run as a script, the `__main__` block parses command-line arguments and passes the PDF path to `main(pdf_path)`, triggering the full workflow. This design provides both a CLI interface for end-users and a clean programmatic API for integration into larger systems.

## Step-by-Step Pipeline Execution

The `main(pdf_path)` function coordinates five distinct stages implemented across specialized modules:

**1. PDF to Markdown Conversion**
The pipeline begins by converting the input PDF into section-wise Markdown. This process utilizes [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) for low-level page extraction and [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) for section segmentation and structuring.

**2. LLM-Based Resume Extraction**
The [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) module invokes the language model using Jinja templates stored in `prompts/templates/` to parse the Markdown content. This produces a structured **JSONResume** object defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), standardizing candidate information for downstream processing.

**3. GitHub Profile Enrichment**
The [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) module fetches the candidate’s GitHub profile and repository data. It then prompts the LLM to identify and select the top seven most relevant projects, enriching the resume data with verifiable technical contributions.

**4. Fairness-Aware Evaluation**
The [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) module applies fairness-aware scoring rules to the enriched resume data. This component ensures consistent, unbiased assessment of candidate qualifications against predefined criteria.

**5. Orchestration and Output**
Finally, [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) aggregates results from all stages, prints a human-readable summary to stdout, and manages output persistence. When `DEVELOPMENT_MODE=True` is configured in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the system also writes results to `resume_evaluations.csv` in the project root.

## How to Invoke the Pipeline

### Command-Line Execution

For direct command-line usage, execute the [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) script with a PDF path argument:

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

```

The `__main__` block automatically handles argument parsing and invokes `main(pdf_path)` to process the document.

### Programmatic Integration

For integration into Python applications or test suites, import the `main` function directly:

```python
from score import main

pdf_file = "resume.pdf"
evaluation = main(pdf_file)  # Returns the structured evaluation object

# Note: Human-readable summary is printed automatically by main()

```

This approach returns the evaluation object while preserving the console output generated by the orchestrator.

## Development Mode and Artifact Generation

When operating in development environments, set the environment variable before execution:

```bash
export DEVELOPMENT_MODE=True
python score.py resume.pdf

```

With `DEVELOPMENT_MODE` enabled, the pipeline appends evaluation results to `resume_evaluations.csv` in the project root, facilitating batch analysis, debugging, and result caching across multiple candidate assessments.

## Summary

- The **`main(pdf_path)`** function in **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)** serves as the canonical main entry point for the Hiring Agent pipeline.
- Execution can be triggered via CLI (`python score.py <pdf_path>`) or by importing and calling `main()` directly in Python code.
- The pipeline processes resumes through Markdown conversion, LLM-based **JSONResume** extraction, GitHub enrichment (top 7 projects), and fairness-aware evaluation via [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).
- Setting **`DEVELOPMENT_MODE=True`** enables CSV output to `resume_evaluations.csv` for development and analysis workflows.

## Frequently Asked Questions

### What file contains the main entry point for the Hiring Agent pipeline?

The **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)** module at the repository root contains the main entry point. It defines the `main(pdf_path)` function and the `__main__` CLI block that parses command-line arguments and initiates the complete evaluation workflow, coordinating calls to [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).

### How do I run the Hiring Agent pipeline from the command line?

Execute **`python score.py path/to/resume.pdf`** from the project root directory. The `__main__` block in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) handles argument parsing and validates the file path before calling `main(pdf_path)` to begin processing.

### Can I import the Hiring Agent pipeline as a Python module?

Yes. Import the **`main`** function from [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) and pass a PDF path string: `from score import main; result = main("resume.pdf")`. This returns the structured evaluation object while the orchestrator automatically prints the human-readable summary to stdout.

### What happens when DEVELOPMENT_MODE is enabled?

When **`DEVELOPMENT_MODE=True`** is set in the environment or [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the pipeline writes evaluation results to **`resume_evaluations.csv`** in the project root. This enables batch processing analysis, result caching across multiple runs, and debugging of the fairness-aware scoring implemented in [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).