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

> Learn how interviewstreet/hiring-agent identifies Git checkout sources by extracting GitHub usernames from resumes and validating projects with an LLM. Boost your candidate vetting process.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: internals
- Published: 2026-07-13

---

**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`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), which converts resume PDFs into Markdown format. The [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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:

```python

# 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`](https://github.com/interviewstreet/hiring-agent/blob/main/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.

```python
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`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) orchestrates this by rendering the `github_project_selection.jinja` template and invoking the LLM provider defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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.

```python
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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) and [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) uses regex pattern matching to isolate GitHub usernames from unstructured PDF text.
- **API orchestration** in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) calls the `/users/{username}/repos` endpoint via `httpx` to fetch public repository metadata.
- **LLM validation** through [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) providers ensures exactly seven repositories are selected based on commit thresholds and project relevance.
- **Downstream attribution** in [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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.