# How to Configure the Hiring-Agent for a New Project

> Configure the hiring-agent for your new project. Set up your LLM provider Ollama or Gemini, adjust model settings, and customize prompts for efficient candidate screening.

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

---

**To configure the hiring-agent for a new project, copy `.env.example` to `.env`, select your LLM provider (Ollama or Gemini) and model, adjust provider settings in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), and optionally customize Jinja templates in `prompts/templates/` for project-specific evaluation criteria.**

The InterviewStreet hiring-agent is a modular pipeline that extracts résumé data, enriches it with GitHub signals, and evaluates candidates using an LLM backend. Whether you are screening engineers for a backend-heavy role or assessing frontend specialists, you must configure the hiring-agent to match your specific requirements. This guide walks through the exact steps and source files needed to adapt the system for any new project.

## Environment Setup and Credentials

Start by copying the example environment file and defining your runtime parameters.

Run the following command in your project root:

```bash
cp .env.example .env

```

Edit `.env` to set the **LLM provider**, model name, and optional API keys:

```text
LLM_PROVIDER=ollama                # or "gemini"

DEFAULT_MODEL=gemma3:4b            # model name for Ollama

GEMINI_API_KEY=your_key_here       # required if using Gemini

GITHUB_TOKEN=your_github_token    # optional, improves API rate limits

```

These **environment variables** are read by [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) (which toggles `DEVELOPMENT_MODE`) and by [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) when constructing the appropriate provider wrapper.

## Select and Configure the LLM Provider

The hiring-agent supports multiple backends through a unified interface defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py). Choose one of the following providers based on your infrastructure.

### Ollama Configuration

To run locally using Ollama:

1. Set `LLM_PROVIDER=ollama` in `.env`.
2. Set `DEFAULT_MODEL` to the name of a model you have pulled (e.g., `gemma3:4b`).
3. Ensure the model is available locally:

```bash
ollama pull gemma3:4b

```

The `OllamaProvider` class in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) wraps the `ollama.chat` method to stream responses into the pipeline. According to the InterviewStreet source code, this provider calls `ollama.chat` under the hood to handle text generation.

### Gemini Configuration

To use Google’s Gemini API:

1. Set `LLM_PROVIDER=gemini` in `.env`.
2. Provide your `GEMINI_API_KEY`.
3. The `GeminiProvider` class in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) adapts Google Gemini API responses to the unified interface used by [`prompt.py`](https://github.com/interviewstreet/hiring-agent/blob/main/prompt.py) and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).

Helper functions in [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) initialize these providers and clean raw LLM responses before they reach the scoring logic.

## Customize Prompts and Scoring Criteria

Each pipeline stage—PDF extraction, GitHub enrichment, and final evaluation—uses **Jinja templates** stored in `prompts/templates/`. To capture project-specific terminology or adjust scoring weights, modify these templates.

To add a new evaluation criterion (for example, "Leadership"):

1. Edit `prompts/templates/resume_evaluation_criteria.jinja` or create a new file in the same directory.
2. Register the template in [`prompts/template_manager.py`](https://github.com/interviewstreet/hiring-agent/blob/main/prompts/template_manager.py) so that [`prompt.py`](https://github.com/interviewstreet/hiring-agent/blob/main/prompt.py) can load it by name.
3. Update the JSON structure to include your new category:

```jinja
{# prompts/templates/resume_evaluation_criteria.jinja #}

{% raw %}
{
  "categories": [
    {"name": "open_source", "weight": 0.25},
    {"name": "self_projects", "weight": 0.25},
    {"name": "production",   "weight": 0.25},
    {"name": "technical_skills","weight": 0.20},
    {"name": "leadership",   "weight": 0.05}
  ]
}
{% endraw %}

```

The [`prompt.py`](https://github.com/interviewstreet/hiring-agent/blob/main/prompt.py) dispatcher selects the appropriate template for each step, allowing you to tailor the evaluation to specific competencies without altering core pipeline logic in [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).

## Development Mode and Pipeline Execution

Before running candidates through the system, decide whether to enable debugging features.

In [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the `DEVELOPMENT_MODE` flag controls whether the pipeline caches intermediate JSON results and exports CSV files for inspection. Set this to `True` during setup and `False` for production runs to avoid writing temporary files.

Execute the full workflow with:

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

```

With your configuration in place, the pipeline will:

1. Convert the PDF to Markdown via [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) (using [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py)).
2. Parse résumé sections using the LLM prompts defined in your templates.
3. Enrich the profile with GitHub data via [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py).
4. Evaluate the candidate via [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) using your custom scoring rules.
5. Output a human-readable summary and (if `DEVELOPMENT_MODE=True`) a CSV row via [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py).

## Summary

- **Copy `.env.example` to `.env`** and set `LLM_PROVIDER`, `DEFAULT_MODEL`, and optional API keys to initialize the backend.
- **Configure providers** in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) by selecting `OllamaProvider` for local models or `GeminiProvider` for cloud APIs.
- **Customize evaluation logic** by editing Jinja templates in `prompts/templates/` and registering them in [`template_manager.py`](https://github.com/interviewstreet/hiring-agent/blob/main/template_manager.py).
- **Toggle `DEVELOPMENT_MODE`** in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) to enable debugging caches during setup.
- **Run the pipeline** with `python score.py <resume.pdf>` to process candidates end-to-end.

## Frequently Asked Questions

### Do I need a GitHub token to configure the hiring-agent?

No, a GitHub token is optional. However, providing `GITHUB_TOKEN` in your `.env` file significantly improves API rate limits when [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) fetches repository and profile data for candidate enrichment. Without it, you may encounter throttling during bulk processing.

### Can I use a custom local LLM endpoint other than Ollama?

The current architecture in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) defines specific wrappers for `OllamaProvider` and `GeminiProvider`. To use a different local endpoint, you would need to create a new provider class in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) that implements the same interface and update [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) to initialize it based on a new `LLM_PROVIDER` value.

### Where do I modify the scoring weights for candidate evaluation?

Scoring weights are defined in the Jinja templates under `prompts/templates/` (specifically `resume_evaluation_criteria.jinja`). After editing the weights or adding new categories, ensure the template is registered in [`template_manager.py`](https://github.com/interviewstreet/hiring-agent/blob/main/template_manager.py) so that [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) can load the updated criteria during the assessment phase.

### How do I switch between development and production mode?

Set the `DEVELOPMENT_MODE` variable in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) to `True` for development (enables caching and CSV exports) or `False` for production. In production mode, [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) suppresses temporary file writes and runs the pipeline without intermediate debugging artifacts.