How the Hiring Agent Selects Top 7 GitHub Repositories: Algorithm Breakdown

The Hiring Agent combines deterministic preprocessing with a constrained LLM prompt to select exactly seven unique GitHub projects, using star count as the initial filter and author commit count as a quality threshold before filling any gaps from the pre-sorted repository list.

The interviewstreet/hiring-agent project implements a hybrid selection algorithm that merges traditional data sorting with large language model reasoning to identify a candidate's most impressive contributions. Understanding how this GitHub project selection algorithm works requires examining three distinct phases implemented across specific source files.

Phase 1: Fetching and Sorting Repositories by Popularity

The algorithm begins in github.py with deterministic data gathering. The fetch_all_github_repos function (lines 18‑84) retrieves all public repositories for a candidate via the GitHub API and enriches each entry with contribution statistics including author_commit_count, total_commit_count, and star count.

Once collected, the repository list undergoes immediate preprocessing. The code sorts all projects descending by github_details.stars at lines 80‑85, ensuring the most popular repositories appear first. This star-based ranking serves as the foundational ordering that persists throughout the selection process.

Phase 2: Guiding the LLM with Hard-Coded Selection Rules

After preprocessing, the system prepares data for AI evaluation. The generate_projects_json function converts the sorted repository list into a JSON string (projects_json) and renders the github_project_selection.jinja template located in prompts/templates/.

This template encodes strict selection criteria:

• Author commit threshold: Projects must have author_commit_count ≥ 4
• Exact count requirement: The LLM must select exactly seven unique projects (no duplicates allowed)
• Priority weighting: Higher preference for repositories with significant author commits and popular open-source contributions

The LLM call occurs at github.py:L61‑89, where a system message explicitly reinforces the rules: "CRITICAL: You must select exactly 7 UNIQUE projects - no duplicates allowed." This constraint ensures the model respects the hard requirements regardless of the candidate's repository diversity.

Phase 3: Deduplication and Fallback Safeguards

The final phase handles response parsing and integrity enforcement. When the LLM returns its selection (lines 94‑131), the algorithm first attempts to parse the JSON array of chosen projects.

Deduplication happens at github.py:L140‑166 using a seen_names set that tracks project identifiers, keeping only the first occurrence of each repository name. If the LLM returns fewer than seven distinct projects after deduplication, the algorithm executes a fill-up logic: it pulls additional repositories from the pre-sorted projects_data list (the star-sorted collection from Phase 1) until reaching exactly seven entries.

A robust fallback mechanism exists at lines 190‑216. If the LLM response is malformed or cannot be parsed, the system immediately returns the first seven entries from projects_data, guaranteeing deterministic output even when the AI component fails.

Code Implementation Example

The following excerpt from github.py demonstrates how the system message constrains the LLM to enforce the unique project requirement:

system_msg = {
    "role": "system",
    "content": (
        "You are an expert technical recruiter analyzing GitHub repositories to identify "
        "the most impressive projects. CRITICAL: You must select exactly 7 UNIQUE projects "
        "- no duplicates allowed. Each project must be different from the others."
    ),
}
user_msg = {"role": "user", "content": prompt}   # `prompt` is the rendered template

response = provider.chat(
    model=DEFAULT_MODEL, 
    messages=[system_msg, user_msg], 
    **model_params
)

The combination of template rules and system-level instructions creates a constrained generation environment that minimizes hallucination while allowing the LLM to apply recruiting expertise to the pre-filtered repository list.

Summary

• The selection process operates in three phases: deterministic fetching and sorting, LLM evaluation with hard constraints, and post-processing with deduplication.
• Repositories are initially sorted by star count in descending order at github.py:L80‑85, establishing a popularity-based baseline.
• The LLM must respect an author commit threshold of ≥ 4 and select exactly seven unique projects, enforced by the github_project_selection.jinja template and system messages.
• Deduplication logic using seen_names (at github.py:L140‑166) removes any duplicate entries returned by the model.
• A fallback mechanism at github.py:L190‑216 returns the top seven starred repositories if the LLM response is unparsable or incomplete.

Frequently Asked Questions

What minimum contribution threshold must a project meet to be considered?

According to the github_project_selection.jinja template, a repository must have an author_commit_count of at least four commits to qualify for selection. This threshold ensures the candidate has made substantial contributions rather than minor patches to the codebase.

How does the algorithm prevent the same repository from appearing multiple times?

The post-processing logic at github.py:L140‑166 implements a seen_names set that tracks previously encountered project names during iteration. When parsing the LLM response, the code skips any project whose name already exists in the set, effectively deduplicating the final list before applying the fill-up logic.

What happens if the LLM selects fewer than seven projects?

If deduplication reduces the count below seven, the algorithm automatically fills the remaining slots from the projects_data list (the repositories pre-sorted by star count). This fill-up logic continues until exactly seven projects are included or no additional qualifying repositories remain, ensuring consistent output regardless of LLM behavior.

Where is the core selection logic implemented?

The primary implementation resides in github.py, specifically between lines 18‑216, which handles fetching, LLM prompting, and post-processing. The selection criteria rules are defined in prompts/templates/github_project_selection.jinja, while data models supporting the profile structure are found in models.py.

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