# Parameters Accepted by Functions in github.py: Complete API Reference

> Explore parameters accepted by functions in github.py for authenticated API access, profile parsing, and repository analysis. Learn about GitHub URLs, query dictionaries, and Pydantic models.

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

---

**The [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) module in the interviewstreet/hiring-agent repository defines eleven distinct functions that accept parameters including GitHub URLs, optional query dictionaries, Pydantic models, and contributor data lists, enabling authenticated API access, profile parsing, repository analysis, and LLM-powered project selection.**

The [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) file serves as the core integration layer for the Hiring Agent application, handling all interactions with the GitHub API. Understanding the parameters accepted by functions in github.py is essential for customizing candidate profile retrieval, implementing caching strategies, or extending the repository analysis logic. Each function is strictly typed (where applicable) and designed to process raw GitHub data into structured outputs suitable for recruiter evaluation.

## Private API Helper Functions

The module includes two private helper functions that handle caching and low-level HTTP requests to the GitHub API.

### `_create_cache_filename`

This utility generates deterministic cache keys based on API endpoints. According to the source code in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) lines 18-26, it accepts:

- **`api_url: str`** – The full GitHub API endpoint URL.
- **`params: dict | None`** – Optional dictionary of query parameters (e.g., `{"per_page": 30}`). Defaults to `None`.

The function returns a hashed string suitable for filesystem caching.

### `_fetch_github_api`

Located at lines 29-63 in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), this function handles authenticated GET requests and rate-limit management. It accepts:

- **`api_url`** – The target GitHub API endpoint as a string.
- **`params`** – Optional dictionary of query parameters (default: `None`).

It returns a tuple of `(status_code, data)` and automatically handles token authentication via environment variables. When `DEVELOPMENT_MODE` is enabled in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), it caches responses using the `_create_cache_filename` logic.

## Profile Extraction Functions

These functions parse GitHub URLs and hydrate them with API data.

### `extract_github_username`

Implemented in lines 116-138, this function extracts clean usernames from various GitHub URL formats. It accepts:

- **`github_url: str`** – Any GitHub profile URL (e.g., `https://github.com/username`) or plain username string.

It returns an `Optional[str]` containing the username, or `None` if extraction fails.

### `fetch_github_profile`

Defined in lines 141-176, this function retrieves full profile metadata. It accepts:

- **`github_url: str`** – Profile URL or username string.

Internally, it delegates to `extract_github_username` and `_fetch_github_api`, returning a `GitHubProfile` Pydantic model (defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)) or `None` on error.

## Repository and Contribution Analysis

These functions analyze code contributions and repository metadata.

### `fetch_repo_contributors`

Located at lines 202-215, this function queries the GitHub `/contributors` endpoint. It accepts:

- **`owner: str`** – The repository owner username.
- **`repo_name: str`** – The repository name.

It returns `list[dict]` containing raw contributor objects, or an empty list on failure.

### `fetch_contributions_count`

Found at lines 187-199, this calculates contribution statistics. It accepts:

- **`owner: str`** – The repository owner username.
- **`contributors_data`** – A list of contributor dictionaries (typically from `fetch_repo_contributors`).

It calculates the owner's contribution count and the total contributions for the repository.

### `fetch_all_github_repos`

This major function spans lines 218-299 and aggregates comprehensive repository data. It accepts:

- **`github_url: str`** – Profile URL or username.
- **`max_repos: int`** – Upper bound on repositories to fetch (default: `100`).

The function filters out low-impact forks, gathers contributor statistics via `fetch_repo_contributors`, and returns `List[Dict]` containing enriched project data suitable for LLM processing.

## JSON Generation and Data Transformation

These functions convert internal models and repository data into JSON-serializable dictionaries.

### `generate_profile_json`

At lines 310-329, this function serializes profile data. It accepts:

- **`profile: GitHubProfile`** – The Pydantic model returned by `fetch_github_profile`.

It returns a `Dict` ready for JSON output, flattening nested model fields.

### `generate_projects_json`

Implemented in lines 334-422, this function processes repository data and triggers LLM-based project selection. It accepts:

- **`projects: List[Dict]`** – List of project dictionaries from `fetch_all_github_repos`.

It filters out projects with zero author commits, formats the data, and returns a curated list of the top 7 unique projects. This function interacts with [`prompts/template_manager.py`](https://github.com/interviewstreet/hiring-agent/blob/main/prompts/template_manager.py) for LLM prompt rendering.

## Orchestration and CLI Entry Points

High-level functions that coordinate the entire data pipeline.

### `fetch_and_display_github_info`

Located at lines 459-477, this is the primary orchestration function. It accepts:

- **`github_url: str`** – Profile URL or username.

It internally calls `fetch_github_profile`, `fetch_all_github_repos`, and the JSON generation functions, returning a unified `Dict` containing both profile and curated projects data.

### `main`

The CLI entry point at lines 484-496 accepts:

- **`github_url`** – Profile URL or username (no type hint in source).

It delegates to `fetch_and_display_github_info` and pretty-prints the final JSON result to stdout.

## Code Examples

Here are practical implementations for common use cases:

```python
from github import (
    fetch_github_profile,
    fetch_all_github_repos,
    generate_projects_json,
    extract_github_username,
)

# Extract username and fetch profile

username = extract_github_username("https://github.com/PavitKaur05")
profile = fetch_github_profile(username)

# Retrieve top 50 repositories with contributor stats

repos = fetch_all_github_repos("PavitKaur05", max_repos=50)

# Generate LLM-curated project selection

top_projects = generate_projects_json(repos)
print(f"Selected {len(top_projects)} key projects")

```

For direct API access using the internal helper:

```python
from github import _fetch_github_api

# Fetch with pagination parameters

status, data = _fetch_github_api(
    "https://api.github.com/users/octocat/repos",
    params={"per_page": 5, "page": 1}
)
print(f"Status: {status}, Repos found: {len(data) if data else 0}")

```

## Summary

- **[`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)** contains eleven functions accepting parameters ranging from simple URL strings to complex data structures like `GitHubProfile` models and contributor lists.
- **Private helpers** (`_create_cache_filename`, `_fetch_github_api`) handle authentication, caching, and rate-limiting, accepting `api_url` and optional `params` dictionaries.
- **Profile functions** (`extract_github_username`, `fetch_github_profile`) accept `github_url` strings and return structured data or `None`.
- **Repository analysis** requires `owner` and `repo_name` strings, with `fetch_all_github_repos` additionally accepting `max_repos` (default 100).
- **JSON generators** accept Pydantic models or dictionary lists, preparing data for LLM consumption and final output.
- **Orchestration functions** provide single-entry convenience, accepting a `github_url` and coordinating the full data pipeline.

## Frequently Asked Questions

### What type hints are used for the parameters in github.py?

Most functions use strict type hints (e.g., `api_url: str`, `max_repos: int = 100`), though some internal parameters like `contributors_data` and the `main` function's `github_url` lack explicit typing. The codebase uses `Optional[str]` and `Optional[GitHubProfile]` to indicate nullable return types.

### How does the caching mechanism work with `_create_cache_filename`?

The function at lines 18-26 generates a deterministic hash based on the `api_url` and `params` dictionary. When `DEVELOPMENT_MODE` is enabled in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), `_fetch_github_api` uses this filename to cache API responses locally, preventing redundant network calls during development.

### Can I customize the number of repositories fetched by `fetch_all_github_repos`?

Yes, the function accepts the `max_repos` parameter with a default value of 100. You can specify any integer value to limit API pagination. For example, `fetch_all_github_repos("username", max_repos=20)` returns at most 20 repositories after filtering out low-impact forks.

### What is the relationship between `fetch_repo_contributors` and `fetch_contributions_count`?

`fetch_repo_contributors` (lines 202-215) accepts `owner` and `repo_name` parameters to fetch raw contributor data from the GitHub API. This data is then passed as the `contributors_data` parameter to `fetch_contributions_count` (lines 187-199), which calculates the specific contribution metrics for the repository owner.