# How to Use the CLI for End-to-End Resume Scoring with Hiring Agent

> Learn to use the Hiring Agent CLI for end-to-end resume scoring. This powerful tool extracts, enriches, and scores PDFs with a single command for structured evaluations.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: how-to-guide
- Published: 2026-07-11

---

**The Hiring Agent CLI provides a single command that orchestrates a multi-stage pipeline to extract, enrich, and score resume PDFs, outputting structured evaluations via `python score.py /path/to/resume.pdf`.**

The `interviewstreet/hiring-agent` repository delivers a complete open-source solution for automated technical candidate evaluation. Using the **CLI for end-to-end resume scoring**, you can process a PDF through extraction, GitHub enrichment, and fairness-aware assessment in one seamless operation. This guide covers the exact commands, environment configuration, and pipeline architecture implemented in the source code.

## Prerequisites and Installation

Before executing the pipeline, install the required dependencies from the repository root:

```bash
pip install -r requirements.txt

```

The system supports two LLM providers: **Ollama** for local inference and **Gemini** for Google's API access. Configure your environment variables based on your chosen backend.

## Running the End-to-End Scoring Pipeline

### Command-Line Usage

Execute the complete pipeline using the entry point in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py):

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

```

This command triggers the full orchestration chain, which sequentially invokes [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) for text extraction, [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) for structural parsing, [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) for data enrichment, and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) for final scoring.

### Environment Configuration

Set the following variables before execution:

```bash
export LLM_PROVIDER=ollama          # or 'gemini'

export DEFAULT_MODEL=gemma3:4b      # any model available to your provider

export DEVELOPMENT_MODE=True        # optional: enables JSON caching

```

When `DEVELOPMENT_MODE=True` (defined in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py)), [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) caches intermediate JSON results to avoid redundant LLM calls during iterative development.

## Understanding the Pipeline Stages

The CLI implements a four-stage architecture that transforms raw PDFs into structured evaluations.

### Stage 1: PDF Text Extraction

First, [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) uses **PyMuPDF** to convert PDF pages into Markdown-like text. This raw content passes to [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), which prompts the LLM using **Jinja templates** from the `prompts/` directory to extract structured resume sections including Basics, Experience, and Projects.

### Stage 2: GitHub Profile Enrichment

If the extracted "Basics" section contains a GitHub username, [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) automatically fetches the profile and repositories. The module classifies projects and prompts the LLM to select the top 7 most relevant contributions, enriching the candidate's technical portfolio before scoring.

### Stage 3: Fairness-Aware Evaluation

The [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) module implements a strict, fairness-constrained scoring algorithm. It computes category scores across four dimensions:

- **Open-source** contributions
- **Self-projects** quality
- **Production** experience
- **Technical skills** assessment

The evaluator applies specific bonuses and deductions, then generates an explainable report using criteria encoded in the `prompts/` directory templates.

### Stage 4: Result Orchestration and Output

Finally, [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) aggregates all intermediate results. It prints a human-readable summary to stdout:

```

===== Resume Evaluation =====
Open-source: 8.5
Self-projects: 7.0
Production: 9.0
Technical skills: 8.0
Bonus: +0.5
Deductions: -0.2
Overall score: 32.8 / 40

```

Optionally, it appends results to `resume_evaluations.csv` for bulk processing workflows.

## Programmatic Integration

Beyond the CLI, instantiate the pipeline directly in Python using the `ScoreRunner` class:

```python
from score import ScoreRunner

runner = ScoreRunner()
result = runner.run("/path/to/resume.pdf")

print(result.summary())

# Access full structured data via result.json

```

This approach uses the same environment variables and caching logic as the command-line interface, allowing integration into larger applications or automated workflows. The `ScoreRunner` class handles provider initialization through [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) and manages Pydantic schemas defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py).

## Summary

- The **Hiring Agent CLI** centralizes resume processing in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), providing a single entry point for complex multi-stage evaluation.
- The pipeline automatically extracts PDF content via [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py), structures it through [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), enriches GitHub data via [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), and scores fairly using [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).
- Configure **LLM providers** (`ollama` or `gemini`) and **development mode caching** through environment variables before execution.
- Use `python score.py /path/to/resume.pdf` for immediate CLI results, or import `ScoreRunner` for programmatic access.
- All prompt templates and evaluation criteria reside in the `prompts/` directory, with Pydantic models and provider abstractions defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) and [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py).

## Frequently Asked Questions

### What LLM providers does the Hiring Agent CLI support?

The CLI supports **Ollama** for local model inference and **Gemini** for Google's API access. Set `LLM_PROVIDER` to either `ollama` or `gemini`, and specify your model via `DEFAULT_MODEL` (e.g., `gemma3:4b` for Ollama). The provider initialization logic resides in [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py), with model abstractions defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py).

### How does the CLI handle caching during development?

When `DEVELOPMENT_MODE=True` in your environment, [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) caches intermediate JSON results to disk. This prevents redundant PDF extraction and LLM calls during iterative testing. The flag is defined in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) and checked during the orchestration phase in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py).

### Can I use the scoring logic without the CLI?

Yes. Import `ScoreRunner` from [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) to execute the pipeline programmatically. The class exposes a `run()` method that accepts a file path and returns an object containing both `summary()` for human-readable output and `json` for structured data. This uses identical logic to the CLI without requiring subprocess calls.

### Where are the evaluation criteria defined?

Evaluation criteria are encoded as **Jinja templates** in the `prompts/` directory. The [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) module loads these templates to construct LLM prompts that enforce fairness constraints and specific scoring rubrics across open-source, self-projects, production, and technical skills categories.