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

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:

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:

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

This command triggers the full orchestration chain, which sequentially invokes pymupdf_rag.py for text extraction, pdf.py for structural parsing, github.py for data enrichment, and evaluator.py for final scoring.

Environment Configuration

Set the following variables before execution:

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), 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 uses PyMuPDF to convert PDF pages into Markdown-like text. This raw content passes to 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 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 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 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:

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 and manages Pydantic schemas defined in models.py.

Summary

• The Hiring Agent CLI centralizes resume processing in score.py, providing a single entry point for complex multi-stage evaluation.
• The pipeline automatically extracts PDF content via pymupdf_rag.py, structures it through pdf.py, enriches GitHub data via github.py, and scores fairly using 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 and 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, with model abstractions defined in models.py.

How does the CLI handle caching during development?

When DEVELOPMENT_MODE=True in your environment, 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 and checked during the orchestration phase in score.py.

Can I use the scoring logic without the CLI?

Yes. Import ScoreRunner from 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 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.

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