Identifying the Source of a Git Checkout in the Hiring-Agent Repository

The interviewstreet/hiring-agent project identifies the source of a Git checkout by extracting the candidate's GitHub username from their resume, querying the GitHub API for public repositories, and using an LLM to validate the top seven most relevant projects based on commit history.

The Hiring-Agent automates technical candidate screening by connecting PDF resumes to actual code contributions. When identifying the source of a Git checkout, the system traces the provenance of code repositories through a multi-stage pipeline that combines regular expression parsing, REST API calls, and generative AI classification.

Resume Parsing and Username Extraction

The pipeline begins in pdf.py, which converts resume PDFs into Markdown format. The github.py module then scans this text to isolate the candidate's GitHub handle using pattern matching.

The extract_github_username function implements a strict regex to capture handles from both URLs and @mentions:

# In github.py

import re

def extract_github_username(text: str) -> str | None:
    # Simple regex to capture a GitHub username from a URL or @handle

    match = re.search(r"(?:github\.com/|@)([A-Za-z0-9-]+)", text)
    return match.group(1) if match else None

This extraction step is critical because it provides the canonical identifier used for all subsequent GitHub API queries.

GitHub API Retrieval and Repository Validation

Once the username is isolated, the fetch_user_repos function in github.py authenticates with the GitHub REST API to retrieve the candidate's public repository metadata. The implementation targets the /users/{username}/repos endpoint and supports optional token-based authentication for higher rate limits.

import httpx

GITHUB_API = "https://api.github.com"

def fetch_user_repos(username: str, token: str | None = None) -> list[dict]:
    url = f"{GITHUB_API}/users/{username}/repos"
    headers = {"Authorization": f"token {token}"} if token else {}
    resp = httpx.get(url, headers=headers, timeout=10)
    resp.raise_for_status()
    return resp.json()

This function returns the raw repository list, including metadata such as language, star count, and commit activity, which feeds into the downstream selection logic.

LLM-Powered Project Classification and Source Attribution

After retrieving the repository list, the system must determine which projects represent the candidate's most significant work. The select_top_projects function in github.py orchestrates this by rendering the github_project_selection.jinja template and invoking the LLM provider defined in models.py (either GeminiProvider or OllamaProvider).

The template enforces strict selection criteria: exactly seven unique repositories meeting a minimum commit threshold (typically 10 commits). The LLM evaluates contribution statistics, primary languages, and project relevance to make the final determination.

from models import LLMProvider

def select_top_projects(repos: list[dict], provider: LLMProvider) -> list[dict]:
    prompt = provider.render_template(
        "github_project_selection.jinja",
        repos=repos,
        required_count=7,
        min_commits=10,
    )
    response = provider.chat(prompt)
    # The provider normalizes the response into a list of selected repo names

    selected_names = provider.parse_selection(response)
    return [repo for repo in repos if repo["name"] in selected_names]

The selected repositories are then attached to the candidate's profile in evaluator.py, completing the source identification workflow and enabling automated scoring based on authentic GitHub contributions.

Configuration and Rate Limiting

API authentication credentials are managed through config.py and environment variables defined in .env.example. The GITHUB_TOKEN variable is optional but recommended to avoid rate limiting when processing high volumes of candidate profiles.

Summary

• Resume extraction in pdf.py and github.py uses regex pattern matching to isolate GitHub usernames from unstructured PDF text.
• API orchestration in github.py calls the /users/{username}/repos endpoint via httpx to fetch public repository metadata.
• LLM validation through models.py providers ensures exactly seven repositories are selected based on commit thresholds and project relevance.
• Downstream attribution in evaluator.py links the validated repositories to candidate profiles for technical assessment.

Frequently Asked Questions

How does the Hiring-Agent extract GitHub usernames from unstructured resume text?

The system uses the extract_github_username function in github.py with a regular expression that matches both github.com/ URLs and @ handle mentions. This pattern captures alphanumeric strings and hyphens following either delimiter, returning the first valid match found in the Markdown-converted resume content.

What GitHub API endpoints are used to retrieve repository data?

The fetch_user_repos function targets the /users/{username}/repos endpoint to list public repositories. It also accesses /users/{username} for profile metadata when needed. Both endpoints support optional Bearer token authentication via the Authorization header to increase rate limits from 60 to 5,000 requests per hour.

Why does the system limit selection to exactly seven repositories?

The constraint of seven repositories is enforced by the github_project_selection.jinja template and the select_top_projects function to ensure evaluators focus on the most substantial contributions without overwhelming the scoring pipeline. This threshold balances comprehensiveness with processing efficiency while filtering out toy projects or forks with minimal commit activity.

How does the Hiring-Agent handle GitHub API rate limits during bulk processing?

The system checks for the GITHUB_TOKEN environment variable defined in config.py and .env.example. When present, the token is passed to httpx headers in fetch_user_repos, upgrading the authentication tier and preventing throttling during high-volume candidate processing. Without a token, the system operates at the unauthenticated rate limit of 60 requests per hour.

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