How to Configure the Hiring-Agent for a New Project

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, 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:

cp .env.example .env

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

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 (which toggles DEVELOPMENT_MODE) and by 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. 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:

ollama pull gemma3:4b

The OllamaProvider class in 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 adapts Google Gemini API responses to the unified interface used by prompt.py and evaluator.py.

Helper functions in 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 so that prompt.py can load it by name.
3. Update the JSON structure to include your new category:

{# 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 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.

Development Mode and Pipeline Execution

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

In 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:

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

With your configuration in place, the pipeline will:

1. Convert the PDF to Markdown via pdf.py (using 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.
4. Evaluate the candidate via evaluator.py using your custom scoring rules.
5. Output a human-readable summary and (if DEVELOPMENT_MODE=True) a CSV row via 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 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.
• Toggle DEVELOPMENT_MODE in 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 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 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 that implements the same interface and update 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 so that 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 to True for development (enables caching and CSV exports) or False for production. In production mode, score.py suppresses temporary file writes and runs the pipeline without intermediate debugging artifacts.

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