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

The 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 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 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, 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, 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) 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 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:

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:

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 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, _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.

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