interviewstreet/hiring-agent

Purpose and entry points

Hiring Agent is a Python 3.11+ CLI pipeline that ranks resume PDFs for a selected role. Its main entry point is score.py, invoked with a PDF and required --role; it also scaffolds new role bundles via --init-role. The pipeline produces a structured evaluation with category scores, evidence, bonuses, and deductions.

Paths: score.py, roles.py, roles/software_engineering_intern/role.json

Orchestration and lifecycle

score.py coordinates the full workflow: parse PDF, optionally enrich from GitHub, evaluate against the role rubric, print a report, and—when development mode is enabled—cache intermediate data and append a role-specific CSV. config.py centralizes development-mode behavior and model/provider resolution.

Paths: score.py, config.py, evaluator.py

PDF ingestion and resume structuring

PDF content crosses an untrusted-document boundary before LLM use. pymupdf_rag.py extracts pages into Markdown-like text using PyMuPDF; pdf.py partitions content into resume sections and sends each section through prompt-driven LLM extraction. The assembled output is a typed JSON Resume-style representation, normalized from potentially loose model JSON.

Paths: pymupdf_rag.py, pdf.py, models.py, transform.py

Prompt and schema boundary

Extraction is controlled by Jinja templates per resume section, while typed models define expected LLM/provider interfaces and resume structures. This is the key boundary between probabilistic LLM responses and application data: templates constrain output, response cleanup occurs in the LLM layer, and transformation/schema logic makes it usable downstream.

Paths: prompts/template_manager.py, prompts/templates/basics.jinja, prompts/templates/projects.jinja, llm_utils.py, models.py

GitHub enrichment

If the parsed resume exposes a GitHub profile, the enrichment stage fetches profile and repository signals, classifies projects, and uses an LLM prompt to select exactly seven meaningful repositories subject to contribution criteria. GitHub is an optional external dependency; GITHUB_TOKEN improves API rate limits, and development mode caches fetched results.

Paths: github.py, prompts/templates/github_project_selection.jinja, score.py

Role-driven evaluation

Evaluation is not hardcoded to one rubric. evaluator.py loads the selected role bundle and asks the LLM to apply its criteria and fairness constraints. role.json drives categories, weight maxima, bonuses, deductions, score bounds, reporting fields, and CSV columns; role-specific Jinja files provide the scoring system message and criteria.

Paths: evaluator.py, roles.py, roles/software_engineering_intern/role.json, roles/software_engineering_intern/criteria.jinja

LLM providers and infrastructure

The application supports local Ollama and hosted Google Gemini via OpenAI-compatible endpoints behind a shared provider abstraction. providers.json maps models to provider base URLs, required API-key environment variables, and model parameters; DEFAULT_MODEL selects a configured model. Ollama runs locally (default model is gemma4:latest), while Gemini requires GEMINI_API_KEY.

Paths: providers.json, config.py, models.py, llm_utils.py