Deployment Strategies for the Hiring-Agent: Local, Docker, and Cloud Deployment Guide

The interviewstreet/hiring-agent supports four primary deployment patterns—local CLI execution, Docker containers, serverless functions, and CI/CD pipelines—enabled by environment-driven configuration in config.py and modular pipeline orchestration in score.py.

The hiring-agent is an open-source resume scoring pipeline that evaluates candidate PDFs using Large Language Models (LLMs) and GitHub profile enrichment. Its architecture is deliberately provider-agnostic, allowing you to switch between a local Ollama server and the hosted Google Gemini service purely through environment variables, making it deployable across development laptops, containerized environments, and serverless platforms without modifying core logic.

Local CLI Execution

Running the pipeline directly on a developer machine is the fastest way to validate resumes or debug the scoring logic. According to the interviewstreet/hiring-agent source code, score.py orchestrates the workflow by sequentially importing and executing modules: pdf.py for text extraction, llm_utils.py for provider initialization, github.py for profile enrichment, and evaluator.py for fairness-focused scoring.

Configuration is handled through environment variables defined in a .env file, which config.py loads at runtime. Set LLM_PROVIDER to ollama or gemini, specify the DEFAULT_MODEL (e.g., gemma3:4b), and optionally provide GEMINI_API_KEY or GITHUB_TOKEN to improve rate limits.

# Clone and install dependencies

git clone https://github.com/interviewstreet/hiring-agent
cd hiring-agent
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Configure environment

cat > .env <<EOF
LLM_PROVIDER=ollama          # or "gemini"

DEFAULT_MODEL=gemma3:4b      # Ollama model name

GEMINI_API_KEY=YOUR_KEY      # only needed for Gemini

GITHUB_TOKEN=YOUR_TOKEN      # optional, improves rate-limit

EOF

# Execute the pipeline

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

Docker Containerization

Containerizing the hiring-agent ensures consistent execution across machines and simplifies deployment to Kubernetes or Amazon ECS. The container packages Python 3.11, all dependencies from requirements.txt, and the score.py entry point, accepting the same environment variables at runtime as the local CLI.

Create a Dockerfile in the repository root that installs dependencies and sets the default entry point:

FROM python:3.11-slim

WORKDIR /app
COPY . /app
RUN pip install --no-cache-dir -r requirements.txt

ENV LLM_PROVIDER=ollama \
    DEFAULT_MODEL=gemma3:4b

ENTRYPOINT ["python","score.py"]

Build and run the image while injecting secrets and mounting resume volumes:

docker build -t hiring-agent .
docker run --rm \
  -e GITHUB_TOKEN=$GITHUB_TOKEN \
  -e GEMINI_API_KEY=$GEMINI_API_KEY \
  -v /local/resumes:/data \
  hiring-agent /data/resume.pdf

Serverless and Function-as-a-Service

For on-demand evaluations that scale automatically with request volume, wrap the pipeline in a serverless handler such as AWS Lambda, Google Cloud Functions, or Azure Functions. The handler receives a PDF via API Gateway or object-store trigger, executes the scoring pipeline, and returns a JSON-formatted evaluation.

Keep the deployment bundle under your provider’s size limit (approximately 50 MB zipped). When using Ollama, ensure the server is reachable via a VPC endpoint or proxy, or switch to Gemini to avoid local LLM infrastructure dependencies. The same environment variables (LLM_PROVIDER, DEFAULT_MODEL, GEMINI_API_KEY) configure the provider within the function context.

CI/CD Pipeline Integration

Integrate the hiring-agent into GitHub Actions to automatically validate resume parsing logic on every pull request or to gate contributions against schema regressions. The workflow installs dependencies, sets environment variables using the repository's secrets, and executes score.py against a sample PDF in your test suite.

Add the following workflow file to .github/workflows/score.yml:

name: Resume Scoring CI
on: [push, pull_request]
jobs:
  test-score:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install deps
        run: pip install -r requirements.txt
      - name: Prepare env
        run: |
          echo "LLM_PROVIDER=ollama" >> $GITHUB_ENV
          echo "DEFAULT_MODEL=gemma3:4b" >> $GITHUB_ENV
      - name: Run scoring on sample PDF
        run: python score.py tests/sample.pdf

This pattern validates that changes to prompts/, evaluator.py, or models.py do not break the end-to-end scoring contract.

Configuration Architecture and Provider Abstraction

As implemented in interviewstreet/hiring-agent, the portability across deployment strategies relies on a centralized configuration system. config.py loads the DEVELOPMENT_MODE flag and standardizes access to LLM_PROVIDER, DEFAULT_MODEL, GEMINI_API_KEY, and GITHUB_TOKEN. models.py defines the abstract LLM provider interface and concrete implementations (OllamaProvider and GeminiProvider), while llm_utils.py handles provider initialization and response normalization.

This abstraction allows the same score.py logic to execute against a local GPU via Ollama or against Google's API by changing a single environment variable, with no conditional logic polluting the pipeline stages.

Summary

• Local CLI execution requires only Python 3.11, a virtual environment, and a .env file to run score.py directly for rapid prototyping according to the interviewstreet/hiring-agent source code.
• Docker containers package the entire runtime, enabling consistent deployments across development, staging, and production environments.
• Serverless functions support event-driven scaling but require attention to bundle size limits and network connectivity for local LLM providers.
• CI/CD integration uses GitHub Actions to perform automated regression testing against sample resumes on every code change.
• Environment-driven configuration via config.py and the provider abstraction in models.py makes all four strategies interchangeable without code modification.

Frequently Asked Questions

Can I run the hiring-agent without internet access?

No, unless you use the Ollama provider for LLM inference and disable GitHub enrichment by omitting the GITHUB_TOKEN. The pipeline requires network access to fetch GitHub profile data in github.py and to reach either the Ollama server (typically localhost or VPC) or the Gemini API endpoint.

How do I switch between Ollama and Gemini without changing code?

Set the LLM_PROVIDER environment variable to ollama or gemini and restart the application. config.py reads this variable, and llm_utils.py instantiates the corresponding provider class from models.py (OllamaProvider or GeminiProvider) at runtime. For Gemini, you must also provide GEMINI_API_KEY.

What is the maximum PDF file size for serverless deployments?

Serverless platforms like AWS Lambda impose a 50 MB limit on the deployment package and a 6 MB payload limit for synchronous API Gateway invocations. If your PDFs exceed this, store them in S3 and trigger the Lambda via S3 events, or use Docker-based container deployments which support larger file sizes.

Is the scoring logic customizable for different roles?

Yes. The evaluation criteria reside in the prompts/ directory as Jinja2 templates and within evaluator.py. You can modify these templates to adjust how the LLM extracts skills or how the final score is calculated without altering the deployment configuration in score.py or config.py.

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