# How the Hiring-Agent Enriches GitHub Repositories with Extracted Information

> Learn how the Hiring-Agent enriches GitHub repositories by extracting profile data, calculating metrics, classifying projects, and using an LLM for candidate evaluation. Optimize your hiring process today.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: how-to-guide
- Published: 2026-07-19

---

**The Hiring-Agent enriches GitHub repositories by fetching profile data and repository metadata, calculating contribution metrics, classifying projects by type, and using an LLM to curate the most impressive projects for candidate evaluation.**

The interviewstreet/hiring-agent project automates candidate portfolio analysis by transforming raw GitHub API data into structured, recruitment-ready profiles. This open-source tool combines REST API aggregation, custom analytics, and large-language-model reasoning to enrich GitHub repositories with extracted information including contribution counts, technology tags, and project significance rankings.

## Multi-Stage Enrichment Pipeline

The enrichment process follows a deterministic pipeline defined primarily in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), progressing from raw data ingestion to structured metadata augmentation.

### Profile Retrieval and Validation

The entry point `fetch_github_profile()` orchestrates initial data capture in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) (lines 41-70). This function first extracts the username via `extract_github_username()`, then delegates the authenticated API call to `_fetch_github_api()`. The returned JSON is validated against the `GitHubProfile` Pydantic model defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) (lines 52-68), ensuring type-safe access to fields like followers, public repositories, and bio information before downstream processing.

### Repository Enumeration and Contribution Analysis

The `fetch_all_github_repos()` function queries the GitHub REST API `users/:username/repos` endpoint, handling pagination and filtering low-impact forks (github.py, lines 18-30). For each repository, the system:

- Invokes `fetch_repo_contributors()` to retrieve the full contributors list (github.py, lines 2-15)
- Calls `fetch_contributions_count()` to compute both the author's specific commit count and the total commit volume (github.py, lines 87-99)
- Classifies the **project type** as either `open_source` or `self_project` based on contributor thresholds (github.py, lines 46-48)

### Metadata Augmentation

Each repository dictionary is extended with computed fields within the `fetch_all_github_repos()` construction block (github.py, lines 50-78):

- `technologies`: Derived from the repository's primary language
- `contributor_count`, `author_commit_count`, `total_commit_count`: Aggregated contribution metrics
- `github_details`: Nested object containing stars, forks, topics, issue counts, repository size, and archival status

### Ranking and Classification

After enumeration, the project list undergoes sorting by star count using `projects.sort(key=lambda x: x["github_details"]["stars"], reverse=True)` and generates summary statistics distinguishing open-source contributions from personal projects (github.py, lines 80-88).

## LLM-Driven Project Curation

Beyond raw metrics, the Hiring-Agent employs an LLM to identify the most recruitment-relevant repositories from the enriched dataset.

### Prompt Engineering and Provider Selection

The enriched repository list is serialized to JSON and injected into the `github_project_selection.jinja` template via `TemplateManager` (github.py, lines 60-66). The `initialize_llm_provider()` function in [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) (lines 40-62) dynamically selects between **Ollama** or **Gemini** providers based on the `DEFAULT_MODEL` configuration defined in [`prompt.py`](https://github.com/interviewstreet/hiring-agent/blob/main/prompt.py).

### Response Parsing and Fallback Mechanisms

The LLM receives a system prompt describing recruitment criteria and returns a curated list of the most impressive projects. The response undergoes cleansing via `extract_json_from_response()` to isolate valid JSON. The system implements duplicate detection and a robust fallback: if the LLM returns malformed data, the pipeline automatically selects the first 7 repositories from the star-sorted list (github.py, lines 90-136).

## Final Aggregation and Output

The `fetch_and_display_github_info()` function orchestrates the terminal stage, combining the validated profile data (`generate_profile_json`) with the curated project selection (`generate_projects_json`) into a unified dictionary consumable by downstream resume-building components (github.py, lines 58-78).

## Implementation Examples

Practical usage of the enrichment pipeline:

```python
from github import fetch_and_display_github_info

# Enrich the GitHub profile for a candidate

result = fetch_and_display_github_info("https://github.com/PavitKaur05")

# Result structure:

#   - "profile": Basic fields (username, followers, bio)

#   - "projects": Up to 7 curated projects with enriched metadata

#   - "total_projects": Count after LLM selection

print(result)

```

For raw repository data without LLM filtering:

```python
from github import fetch_all_github_repos

repos = fetch_all_github_repos("https://github.com/PavitKaur05", max_repos=20)
for repo in repos[:5]:
    print(repo["name"], repo["github_details"]["stars"])

```

## Summary

- **Multi-stage pipeline**: The Hiring-Agent processes GitHub data through profile retrieval, repository enumeration, metric calculation, and LLM-based curation defined in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py).
- **Rich metadata extraction**: Each repository receives augmented fields including contributor counts, commit statistics, technology tags, and GitHub-specific details (stars, forks, topics) within the `github_details` object.
- **Intelligent classification**: Projects are categorized as `open_source` or `self_project` based on contributor analysis, then ranked by popularity metrics.
- **Robust fallback**: The system defaults to the top 7 starred repositories if LLM processing fails, ensuring reliable output.
- **Type-safe architecture**: Pydantic models (`GitHubProfile` in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)) validate all incoming API data before processing.

## Frequently Asked Questions

### What specific GitHub metrics does the Hiring-Agent extract for each repository?

The system extracts contributor counts via `fetch_repo_contributors()`, author-specific commit counts and total volume via `fetch_contributions_count()`, primary language (mapped to technologies), and repository metadata including stars, forks, topics, issue counts, size, and archival status. These metrics are assembled in the `github_details` object within each project dictionary during the enrichment phase in `fetch_all_github_repos()`.

### How does the Hiring-Agent determine if a project is open-source or a personal project?

The classification logic in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) (lines 46-48) examines the contributor count returned by `fetch_repo_contributors()`. Repositories exceeding a contributor threshold are labeled `open_source`, while those with fewer contributors are categorized as `self_project`, distinguishing between collaborative and individual work.

### Which LLM providers does the Hiring-Agent support for project selection?

According to [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) (lines 40-62), the `initialize_llm_provider()` function supports both **Ollama** (for local inference) and **Gemini** (Google's API). The selection is determined by the `DEFAULT_MODEL` configuration constant defined in [`prompt.py`](https://github.com/interviewstreet/hiring-agent/blob/main/prompt.py).

### What happens if the LLM returns invalid or empty data during project selection?

The pipeline implements a defensive fallback in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) (lines 90-136). If `extract_json_from_response()` fails to parse valid JSON or the LLM returns malformed data, the system automatically defaults to the first 7 repositories from the star-sorted list, ensuring the enrichment process completes successfully.