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

> Discover how the Hiring Agent algorithm selects top 7 GitHub repos. Learn about its deterministic preprocessing, LLM prompts, star count, and author commit count filtering.

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

---

**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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) demonstrates how the system message constrains the LLM to enforce the unique project requirement:

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