tools.github_tools module

GitHub API tools using per-user OAuth tokens.

Provides repository, issue, PR, gist, notification, and code-search operations via the GitHub REST API. Requires the user to have connected their GitHub account via the OAuth flow (connect_service tool).

async tools.github_tools.github_list_repos(visibility='all', sort='updated', per_page=20, page=1, ctx=None)[source]

List the authenticated user’s GitHub repositories as a JSON string.

Tool handler backing the github_list_repos tool. Fetches the current user’s repositories with optional visibility/sort filters and pagination, returning a JSON-encoded {"count", "repos"} payload of compacted repository summaries.

Interactions: obtains the user’s token via _get_token() (which calls oauth_manager.require_oauth_token() against Redis), issues a GET /user/repos through _gh_request(), and maps results through _fmt_repo(). Registered in the module TOOLS list and dispatched by the tool execution layer via tool_loader.py; not called directly by other Python modules.

Parameters:

  • visibility (str) – Repository visibility filter ("all", "public", or "private").

  • sort (str) – Sort order ("created", "updated", "pushed", or "full_name").

  • per_page (int) – Results per page; clamped to a maximum of 100.

  • page (int) – 1-based page number.

  • ctx (ToolContext | None) – The tool invocation context providing Redis and user identity.

Returns:

A JSON string of {"count", "repos"} on success; the OAuthNotConnected message when GitHub is not linked; or a JSON-encoded error dict on API failure.

Return type:

str

async tools.github_tools.github_search_code(query, per_page=10, page=1, ctx=None)[source]

Search code across GitHub repositories and return matches as JSON.

Tool handler backing the github_search_code tool. Runs a GitHub code search using GitHub’s query syntax (supporting qualifiers like repo:, language:, path:) and returns a JSON-encoded {"total_count", "items"} payload where each item is reduced to its name, path, repository, and URL.

Interactions: obtains the user’s token via _get_token() (Redis-backed OAuth lookup) and issues a GET /search/code through _gh_request(). Registered in the module TOOLS list and dispatched by the tool execution layer via tool_loader.py; not called directly by other Python modules.

Parameters:

  • query (str) – GitHub code-search query string with optional qualifiers.

  • per_page (int) – Results per page; clamped to a maximum of 100.

  • page (int) – 1-based page number.

  • ctx (ToolContext | None) – The tool invocation context providing Redis and user identity.

Returns:

A JSON string of {"total_count", "items"} on success; the OAuthNotConnected message when GitHub is not linked; or a JSON-encoded error dict on API failure.

Return type:

str

async tools.github_tools.github_create_issue(owner, repo, title, body='', labels=None, assignees=None, ctx=None)[source]

Create a new issue on a GitHub repository and return it as JSON.

Tool handler backing the github_create_issue tool. Builds the issue payload from the title plus optional body, labels, and assignees, posts it, and returns the created issue in compacted form.

Interactions: obtains the user’s token via _get_token() (Redis-backed OAuth lookup), issues a POST /repos/{owner}/{repo}/issues through _gh_request(), and formats the result with _fmt_issue(). Registered in the module TOOLS list and dispatched by the tool execution layer via tool_loader.py; not called directly by other Python modules.

Parameters:

  • owner (str) – Repository owner (user or organization).

  • repo (str) – Repository name.

  • title (str) – Issue title.

  • body (str) – Optional issue body in Markdown; omitted from the payload if empty.

  • labels (list[str] | None) – Optional list of label names to apply.

  • assignees (list[str] | None) – Optional list of usernames to assign.

  • ctx (ToolContext | None) – The tool invocation context providing Redis and user identity.

Returns:

A JSON string of the created issue summary on success; the OAuthNotConnected message when GitHub is not linked; or a JSON-encoded error dict on API failure.

Return type:

str

async tools.github_tools.github_list_issues(owner, repo, state='open', labels='', per_page=20, page=1, ctx=None)[source]

List issues on a GitHub repository as a JSON string.

Tool handler backing the github_list_issues tool. Fetches issues filtered by state and (optionally) a comma-separated label list, with pagination, returning a JSON-encoded {"count", "issues"} payload of compacted issue summaries. Note that the GitHub issues endpoint also includes pull requests.

Interactions: obtains the user’s token via _get_token() (Redis-backed OAuth lookup), issues a GET /repos/{owner}/{repo}/issues through _gh_request(), and maps results through _fmt_issue(). Registered in the module TOOLS list and dispatched by the tool execution layer via tool_loader.py; not called directly by other Python modules.

Parameters:

  • owner (str) – Repository owner.

  • repo (str) – Repository name.

  • state (str) – Issue state filter ("open", "closed", or "all").

  • labels (str) – Optional comma-separated label names to filter by; omitted when empty.

  • per_page (int) – Results per page; clamped to a maximum of 100.

  • page (int) – 1-based page number.

  • ctx (ToolContext | None) – The tool invocation context providing Redis and user identity.

Returns:

A JSON string of {"count", "issues"} on success; the OAuthNotConnected message when GitHub is not linked; or a JSON-encoded error dict on API failure.

Return type:

str

async tools.github_tools.github_list_pull_requests(owner, repo, state='open', sort='created', per_page=20, page=1, ctx=None)[source]

List pull requests on a GitHub repository as a JSON string.

Tool handler backing the github_list_pull_requests tool. Fetches PRs filtered by state and ordered by the requested sort, with pagination, returning a JSON-encoded {"count", "pull_requests"} payload of compacted PR summaries.

Interactions: obtains the user’s token via _get_token() (Redis-backed OAuth lookup), issues a GET /repos/{owner}/{repo}/pulls through _gh_request(), and maps results through _fmt_pr(). Registered in the module TOOLS list and dispatched by the tool execution layer via tool_loader.py; not called directly by other Python modules.

Parameters:

  • owner (str) – Repository owner.

  • repo (str) – Repository name.

  • state (str) – PR state filter ("open", "closed", or "all").

  • sort (str) – Sort order ("created", "updated", "popularity", or "long-running").

  • per_page (int) – Results per page; clamped to a maximum of 100.

  • page (int) – 1-based page number.

  • ctx (ToolContext | None) – The tool invocation context providing Redis and user identity.

Returns:

A JSON string of {"count", "pull_requests"} on success; the OAuthNotConnected message when GitHub is not linked; or a JSON-encoded error dict on API failure.

Return type:

str

async tools.github_tools.github_get_pull_request(owner, repo, pull_number, include_diff=False, ctx=None)[source]

Fetch a single pull request (optionally with its diff) as JSON.

Tool handler backing the github_get_pull_request tool. Returns the compacted PR summary plus a body excerpt (first 2000 chars), and when include_diff is set, appends up to the first 8000 characters of the unified diff fetched with the application/vnd.github.v3.diff media type.

Interactions: obtains the user’s token via _get_token() (Redis-backed OAuth lookup), issues a GET /repos/{owner}/{repo}/pulls/{pull_number} through _gh_request() and formats it with _fmt_pr(); for the diff it opens a separate aiohttp.ClientSession and re-requests the same PR URL with the diff Accept header. Registered in the module TOOLS list and dispatched by the tool execution layer via tool_loader.py; not called directly by other Python modules.

Parameters:

  • owner (str) – Repository owner.

  • repo (str) – Repository name.

  • pull_number (int) – The pull request number.

  • include_diff (bool) – When True, include a truncated unified diff under the "diff" key (only added if the diff request returns HTTP 200).

  • ctx (ToolContext | None) – The tool invocation context providing Redis and user identity.

Returns:

A JSON string of the PR summary (with body and optional diff) on success; the OAuthNotConnected message when GitHub is not linked; or a JSON-encoded error dict on API failure.

Return type:

str

async tools.github_tools.github_create_gist(description, files, public=False, ctx=None)[source]

Create a GitHub Gist from one or more named files and return it as JSON.

Tool handler backing the github_create_gist tool. Wraps each filename -> content entry into the GitHub gist file structure, creates the gist, and returns a compact summary of the result.

Interactions: obtains the user’s token via _get_token() (Redis-backed OAuth lookup) and issues a POST /gists through _gh_request(). Registered in the module TOOLS list and dispatched by the tool execution layer via tool_loader.py; not called directly by other Python modules.

Parameters:

  • description (str) – Human-readable description of the gist.

  • files (dict[str, str]) – Mapping of filename to file content; each becomes one gist file.

  • public (bool) – Whether the gist is publicly visible (defaults to False).

  • ctx (ToolContext | None) – The tool invocation context providing Redis and user identity.

Returns:

A JSON string with the new gist’s id, url, description, public flag, files (filenames), and created_at on success; the OAuthNotConnected message when GitHub is not linked; or a JSON-encoded error dict on API failure.

Return type:

str

async tools.github_tools.github_get_file(owner, repo, path, ref='', ctx=None)[source]

Fetch a repository file’s contents or a directory listing as JSON.

Tool handler backing the github_get_file tool. For a file, decodes the base64 payload to UTF-8 (replacing undecodable bytes, falling back to "(binary file)" on failure) and returns the first 16000 characters of content with metadata. For a directory, returns a listing of its entries. An optional ref pins the lookup to a branch, tag, or commit SHA.

Interactions: obtains the user’s token via _get_token() (Redis-backed OAuth lookup), issues a GET /repos/{owner}/{repo}/contents/{path} through _gh_request(), and uses the standard-library base64 to decode file content. Registered in the module TOOLS list and dispatched by the tool execution layer via tool_loader.py; not called directly by other Python modules.

Parameters:

  • owner (str) – Repository owner.

  • repo (str) – Repository name.

  • path (str) – File or directory path within the repository.

  • ref (str) – Optional branch, tag, or commit SHA; defaults to the repo’s default branch when empty.

  • ctx (ToolContext | None) – The tool invocation context providing Redis and user identity.

Returns:

A JSON string of file metadata and truncated content for a file; a {"type": "directory", "entries": [...]} listing for a directory; the OAuthNotConnected message when GitHub is not linked; or a JSON-encoded error dict on API failure.

Return type:

str

async tools.github_tools.github_list_notifications(all_notifications=False, per_page=20, page=1, ctx=None)[source]

List the user’s GitHub notifications as a JSON string.

Tool handler backing the github_list_notifications tool. Returns a JSON-encoded {"count", "notifications"} payload of compacted notification threads (id, reason, unread flag, subject title/type, repository, and timestamp). By default only unread notifications are returned unless all_notifications is set.

Interactions: obtains the user’s token via _get_token() (Redis-backed OAuth lookup) and issues a GET /notifications through _gh_request(). Registered in the module TOOLS list and dispatched by the tool execution layer via tool_loader.py; not called directly by other Python modules.

Parameters:

  • all_notifications (bool) – When True, include read notifications as well; sent to the API as the lowercased all query parameter.

  • per_page (int) – Results per page; clamped to a maximum of 50.

  • page (int) – 1-based page number.

  • ctx (ToolContext | None) – The tool invocation context providing Redis and user identity.

Returns:

A JSON string of {"count", "notifications"} on success; the OAuthNotConnected message when GitHub is not linked; or a JSON-encoded error dict on API failure.

Return type:

str

async tools.github_tools.github_star_repo(owner, repo, star=True, ctx=None)[source]

Star or unstar a GitHub repository and return the outcome as JSON.

Tool handler backing the github_star_repo tool. Issues a PUT to star or a DELETE to unstar the given repository, then reports the action taken.

Interactions: obtains the user’s token via _get_token() (Redis-backed OAuth lookup) and issues a PUT/DELETE /user/starred/{owner}/{repo} through _gh_request() (a successful call returns HTTP 204). Registered in the module TOOLS list and dispatched by the tool execution layer via tool_loader.py; not called directly by other Python modules.

Parameters:

  • owner (str) – Repository owner.

  • repo (str) – Repository name.

  • star (bool) – True to star the repo, False to unstar it.

  • ctx (ToolContext | None) – The tool invocation context providing Redis and user identity.

Returns:

A JSON string {"status": "success", "action", "repo"} on success; the OAuthNotConnected message when GitHub is not linked; or a JSON-encoded error dict on API failure.

Return type:

str