github-context-tools 0.1.0__py3-none-any.whl

github_context_tools/__init__.py

@@ -0,0 +1,70 @@
+"""
+github-context-tools
+====================
+A collection of GitHub API tools for fetching context for LLM-based workflows.
+
+Quickstart::
+
+    from github_context_tools import make_tools
+
+    tools = make_tools(token="ghp_...")  # or set GH_TOKEN env var
+
+    # Pass the list to your agent framework's tool registry
+    agent.run(tools=tools)
+"""
+
+from importlib.metadata import version as _version
+
+__version__ = _version("github-context-tools")
+
+from github_context_tools.tools.factory import make_tools
+from github_context_tools.models import (
+    PRMetadata,
+    PRDiff,
+    PRDescription,
+    PRComment,
+    FileContent,
+    SearchResult,
+    TextMatch,
+    CommitSummary,
+    CommitDiff,
+    BlameEntry,
+    Issue,
+    IssueComment,
+    RepoConventions,
+)
+from github_context_tools.exceptions import (
+    GitHubAPIError,
+    NotFoundError,
+    AuthenticationError,
+    RateLimitError,
+)
+
+__all__ = [
+    # Factory
+    "make_tools",
+    # PR entry points
+    "PRMetadata",
+    "PRDiff",
+    # PR intent
+    "PRDescription",
+    "PRComment",
+    # Code understanding
+    "FileContent",
+    "SearchResult",
+    "TextMatch",
+    # History
+    "CommitSummary",
+    "CommitDiff",
+    "BlameEntry",
+    # Issues
+    "Issue",
+    "IssueComment",
+    # Conventions
+    "RepoConventions",
+    # Exceptions
+    "GitHubAPIError",
+    "NotFoundError",
+    "AuthenticationError",
+    "RateLimitError",
+]

github_context_tools/_request.py

@@ -0,0 +1,106 @@
+import os
+from typing import Any
+
+import httpx
+
+from github_context_tools.exceptions import (
+    AuthenticationError,
+    GitHubAPIError,
+    NotFoundError,
+    RateLimitError,
+)
+
+GITHUB_API_BASE = "https://api.github.com"
+
+_HTTP_ERRORS: dict[int, tuple[type[GitHubAPIError], str]] = {
+    401: (AuthenticationError, "Authentication failed — check your token"),
+    403: (AuthenticationError, "Permission denied — token may lack required scopes"),
+    404: (NotFoundError, "Resource not found"),
+    429: (RateLimitError, "GitHub API rate limit exceeded"),
+}
+
+
+def _resolve_token(token: str | None) -> str:
+    resolved = token or os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
+    if not resolved:
+        raise ValueError(
+            "No GitHub token provided. Pass token= to make_tools() or set the "
+            "GH_TOKEN / GITHUB_TOKEN environment variable."
+        )
+    return resolved
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    try:
+        detail = response.json().get("message", "")
+    except Exception:
+        detail = ""
+    msg = f"{detail} ({response.url})" if detail else str(response.url)
+    exc_class, prefix = _HTTP_ERRORS.get(
+        response.status_code,
+        (GitHubAPIError, f"GitHub API error {response.status_code}"),
+    )
+    raise exc_class(f"{prefix}: {msg}", status_code=response.status_code)
+
+
+def make_requester(token: str | None = None, http_client: httpx.Client | None = None):
+    """
+    Returns a (get_json, get_text, post_json) triple of callables that share a
+    resolved token and a single Client per make_requester call.
+
+    The Client is thread-safe; concurrent tool calls from a thread pool work
+    correctly without any additional synchronisation.
+
+    :param token: GitHub personal access token. If omitted, reads from the
+                  GH_TOKEN or GITHUB_TOKEN environment variable.
+    :param http_client: Optional httpx.Client instance. Use this to configure
+                        SSL settings, proxies, timeouts, etc. If omitted, a new
+                        client is created.
+    """
+    resolved = _resolve_token(token)
+    if http_client is not None:
+        client = http_client
+    else:
+        client = httpx.Client()
+
+    default_headers = {
+        "Authorization": f"Bearer {resolved}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+
+    def _url(path: str) -> str:
+        return path if path.startswith("https://") else f"{GITHUB_API_BASE}{path}"
+
+    def _get(path: str, *, headers: dict[str, str] | None = None) -> httpx.Response:
+        merged = {**default_headers, **(headers or {})}
+        response = client.get(_url(path), headers=merged)
+        _raise_for_status(response)
+        return response
+
+    def _post(
+        path: str, body: dict[str, Any], *, headers: dict[str, str] | None = None
+    ) -> httpx.Response:
+        merged = {
+            **default_headers,
+            "Content-Type": "application/json",
+            **(headers or {}),
+        }
+        response = client.post(_url(path), json=body, headers=merged)
+        _raise_for_status(response)
+        return response
+
+    def get_json(path: str, *, headers: dict[str, str] | None = None) -> Any:
+        return _get(path, headers=headers).json()
+
+    def get_text(path: str, *, headers: dict[str, str] | None = None) -> str:
+        return _get(path, headers=headers).text
+
+    def post_json(
+        path: str, body: dict[str, Any], *, headers: dict[str, str] | None = None
+    ) -> Any:
+        return _post(path, body, headers=headers).json()
+
+    return get_json, get_text, post_json

github_context_tools/_utils.py

@@ -0,0 +1,25 @@
+import re
+
+
+_PR_URL_RE = re.compile(
+    r"https://github\.com/(?P<owner>[^/]+)/(?P<repo>[^/]+)/pull/(?P<number>\d+)"
+)
+
+
+def parse_pr_url(pr_url: str) -> tuple[str, str, int]:
+    """Return (owner, repo, pr_number) from a GitHub PR URL."""
+    m = _PR_URL_RE.match(pr_url.rstrip("/"))
+    if not m:
+        raise ValueError(
+            f"Invalid GitHub PR URL: {pr_url!r}. "
+            "Expected format: https://github.com/owner/repo/pull/123"
+        )
+    return m.group("owner"), m.group("repo"), int(m.group("number"))
+
+
+def validate_repo(repo: str) -> None:
+    """Raise ValueError if repo is not in 'owner/name' format."""
+    if "/" not in repo or repo.startswith("/") or repo.endswith("/"):
+        raise ValueError(
+            f"Invalid repo format: {repo!r}. Expected 'owner/name', e.g. 'acme/backend'"
+        )

github_context_tools/exceptions.py

@@ -0,0 +1,18 @@
+class GitHubAPIError(Exception):
+    """Raised when the GitHub API returns an unexpected error."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class NotFoundError(GitHubAPIError):
+    """Raised when the requested resource does not exist (HTTP 404)."""
+
+
+class AuthenticationError(GitHubAPIError):
+    """Raised when the token is missing, invalid, or lacks required scopes (HTTP 401/403)."""
+
+
+class RateLimitError(GitHubAPIError):
+    """Raised when the GitHub API rate limit is exceeded (HTTP 429)."""

github_context_tools/models.py

@@ -0,0 +1,157 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from git_unified_diff_parse import ChangedFile
+
+
+# ── PR entry-point results ────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class PRMetadata:
+    repo:          str  # "owner/name"
+    pr_number:     int
+    title:         str
+    description:   str
+    author:        str  # GitHub login
+    base_branch:   str
+    head_branch:   str
+    base_sha:      str
+    head_sha:      str
+    html_url:      str
+    state:         str  # "open" or "closed"
+    commits:       int
+    changed_files: int
+    additions:     int
+    deletions:     int
+
+
+@dataclass(frozen=True)
+class PRDiff:
+    repo: str  # "owner/name"
+    diff: tuple[ChangedFile, ...]
+
+
+# ── Group 1: Code understanding ───────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class FileContent:
+    # Decoded file content. None when the file exceeds GitHub's 1MB inline limit.
+    content:      Optional[str]
+    # Direct download URL. Present when the file is too large for inline delivery.
+    download_url: Optional[str]
+
+
+@dataclass(frozen=True)
+class TextMatch:
+    fragment: str
+    matches:  tuple[tuple[str, tuple[int, int]], ...]  # (matched_text, (start, end))
+
+
+@dataclass(frozen=True)
+class SearchResult:
+    path:         str
+    filename:     str
+    html_url:     str
+    sha:          str
+    language:     Optional[str]
+    score:        float
+    line_numbers: tuple[str, ...]
+    text_matches: tuple[TextMatch, ...]
+    # Kept for backwards compatibility — first fragment from text_matches, or empty string
+    snippet:      str
+
+
+# ── Group 2: History ──────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class CommitSummary:
+    sha:      str
+    message:  str
+    author:   str
+    date:     str
+    html_url: str
+    parents:  tuple[str, ...]  # parent SHAs; len > 1 means merge commit
+
+
+@dataclass(frozen=True)
+class CommitDiff:
+    sha:  str
+    diff: tuple[ChangedFile, ...]
+
+
+@dataclass(frozen=True)
+class BlameEntry:
+    start_line:  int
+    end_line:    int
+    sha:         str
+    message:     str
+    author:      str
+    date:        str
+    commit_url:  str
+    age:         int  # 1 (newest) to 10 (oldest) relative to other changes in the file
+
+
+# ── Group 3: PR intent ────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class PRDescription:
+    title:  str
+    body:   str
+    labels: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class PRComment:
+    author:            str
+    body:              str
+    created_at:        str
+    path:              Optional[str]
+    # Line number on the side of the diff specified by `side`.
+    line:              Optional[int]
+    # "RIGHT" = new file (addition side), "LEFT" = old file (deletion side).
+    # None for non-review (conversation) comments.
+    side:              Optional[str]
+    # Line number in the file before the PR's changes (base commit).
+    original_line:     Optional[int]
+    original_side:     Optional[str]
+    # For multi-line comments: the first line and its side.
+    start_line:        Optional[int]
+    start_side:        Optional[str]
+    # Surrounding diff context at the point the comment was made.
+    diff_hunk:         Optional[str]
+    # SHA of the commit the comment was made on — None if made on a stale commit.
+    commit_id:         Optional[str]
+    # ID of the parent comment; set for replies in a thread, None for top-level.
+    in_reply_to_id:    Optional[int]
+    html_url:          Optional[str]
+    is_review_comment: bool
+
+
+@dataclass(frozen=True)
+class IssueComment:
+    author:     str
+    body:       str
+    created_at: str
+    html_url:   str
+
+
+@dataclass(frozen=True)
+class Issue:
+    number:       int
+    title:        str
+    body:         str
+    author:       str
+    state:        str
+    state_reason: Optional[str]  # "completed", "not_planned", "reopened", or None
+    labels:       tuple[str, ...]
+    created_at:   str
+    closed_at:    Optional[str]
+    comments:     tuple[IssueComment, ...]
+
+
+# ── Group 4: Conventions ──────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class RepoConventions:
+    """Keys are filenames (e.g. 'CONTRIBUTING.md'), values are file contents."""
+    files: tuple[tuple[str, str], ...]

github_context_tools/tools/__init__.py

@@ -0,0 +1,3 @@
+from github_context_tools.tools.factory import make_tools
+
+__all__ = ["make_tools"]

github_context_tools/tools/code.py

@@ -0,0 +1,211 @@
+from base64 import b64decode
+from collections.abc import Callable
+from typing import Annotated
+
+from github_context_tools._utils import validate_repo
+from github_context_tools.models import FileContent, SearchResult, TextMatch
+
+
+def _is_sibling(item_path: str, item_type: str, directory: str, exclude: str) -> bool:
+    if item_type != "blob" or item_path == exclude:
+        return False
+    if directory:
+        prefix = directory + "/"
+        return item_path.startswith(prefix) and "/" not in item_path[len(prefix):]
+    return "/" not in item_path
+
+
+def _build_tree(items: list[dict], path_prefix: str) -> dict:
+    tree: dict = {}
+    for item in items:
+        if path_prefix and not item["path"].startswith(path_prefix):
+            continue
+        parts = item["path"].split("/")
+        node = tree
+        for part in parts[:-1]:
+            node = node.setdefault(part, {})
+        if item["type"] == "blob":
+            node[parts[-1]] = "blob"
+    return tree
+
+
+def _build_search_query(repo: str, path: str | None, filename: str | None, symbol: str | None, content: str | None) -> str:
+    if not any([path, filename, symbol, content]):
+        raise ValueError("At least one of path, filename, symbol, or content must be provided")
+    # The classic GitHub code search API uses free-text terms for content/symbol matching.
+    # `filename:` and `path:` are supported qualifiers; `content:` and `symbol:` are not —
+    # they must be passed as plain search terms instead.
+    qualifiers = [f"repo:{repo}"]
+    terms = []
+    if path:
+        qualifiers.append(f"path:{path}")
+    if filename:
+        qualifiers.append(f"filename:{filename}")
+    if symbol:
+        terms.append(symbol)
+    if content:
+        terms.append(content)
+    return "+".join(terms + qualifiers)
+
+
+def _parse_text_matches(raw: list[dict]) -> tuple[TextMatch, ...]:
+    return tuple(
+        TextMatch(
+            fragment=m.get("fragment", ""),
+            matches=tuple(
+                (hit["text"], (hit["indices"][0], hit["indices"][1]))
+                for hit in m.get("matches", [])
+            ),
+        )
+        for m in raw
+    )
+
+
+def _search_results_from_response(data: dict) -> list[SearchResult]:
+    results = []
+    for item in data.get("items", []):
+        text_matches = _parse_text_matches(item.get("text_matches", []))
+        results.append(
+            SearchResult(
+                path=item["path"],
+                filename=item["name"],
+                html_url=item["html_url"],
+                sha=item["sha"],
+                language=item.get("language"),
+                score=item.get("score", 0.0),
+                line_numbers=tuple(item.get("line_numbers") or []),
+                text_matches=text_matches,
+                snippet=text_matches[0].fragment if text_matches else "",
+            )
+        )
+    return results
+
+
+def make_code_tools(get_json, _get_text, _post_json) -> list[Callable]:
+    def get_file_at_ref(
+        repo: Annotated[str, "Repository in 'owner/name' format, e.g. 'acme/backend'"],
+        path: Annotated[
+            str, "File path relative to the repo root, e.g. 'src/auth/oauth.py'"
+        ],
+        ref: Annotated[str, "Any git ref — branch name, tag, or commit SHA"],
+    ) -> Annotated[
+        FileContent,
+        (
+            "File content with fields: content (str with decoded file text, None if file exceeds GitHub's 1MB inline limit),"
+            " download_url (direct download URL, present when content is None for large files, otherwise may also be set)."
+            " Always check content first; fall back to download_url if content is None."
+        ),
+    ]:
+        """Fetch the content of a file at any git ref.
+
+        For files under 1MB, content is returned inline.
+        For larger files, content is None and download_url is provided instead.
+        """
+        validate_repo(repo)
+        data = get_json(f"/repos/{repo}/contents/{path}?ref={ref}")
+        if "content" in data:
+            return FileContent(
+                content=b64decode(data["content"]).decode("utf-8"),
+                download_url=data.get("download_url"),
+            )
+        if data.get("download_url"):
+            return FileContent(content=None, download_url=data["download_url"])
+        raise ValueError(f"Unable to fetch content for {path!r} at ref {ref!r}")
+
+    def get_directory_tree(
+        repo: Annotated[str, "Repository in 'owner/name' format, e.g. 'acme/backend'"],
+        ref: Annotated[str, "Any git ref — branch name, tag, or commit SHA"],
+        path: Annotated[
+            str,
+            "Directory path to filter by, e.g. 'src/auth'. Pass empty string for the full repo tree",
+        ] = "",
+    ) -> Annotated[
+        dict,
+        (
+            "Nested dict representing the directory tree rooted at the given path."
+            " Directories are dicts mapping entry names to their children."
+            " Files are the string 'blob'."
+            " Example: {'src': {'auth': {'oauth.py': 'blob', 'token.py': 'blob'}, 'utils.py': 'blob'}}."
+            " Pass an empty string for path to get the full repo tree."
+        ),
+    ]:
+        """List the file tree for a directory (or the whole repo) at a given ref.
+
+        Returns a nested dict where each directory is a dict of its children and
+        each file is the string 'blob'. Example:
+        {'src': {'auth': {'oauth.py': 'blob', 'token.py': 'blob'}, 'utils.py': 'blob'}}
+        """
+        validate_repo(repo)
+        data = get_json(f"/repos/{repo}/git/trees/{ref}?recursive=1")
+        return _build_tree(data["tree"], path)
+
+    def search_codebase(
+        repo: Annotated[str, "Repository in 'owner/name' format, e.g. 'acme/backend'"],
+        path: Annotated[
+            str | None,
+            "Filter by file path or glob pattern, e.g. 'src/auth' or '*.py'. Matches anywhere in the file path",
+        ] = None,
+        filename: Annotated[
+            str | None,
+            "Filter by exact filename, e.g. 'conftest.py' or 'README.md'",
+        ] = None,
+        symbol: Annotated[
+            str | None,
+            "Search term to find a function, method, or class by name, e.g. 'WithContext' or 'OAuthHandler'. Used as a free-text search term.",
+        ] = None,
+        content: Annotated[
+            str | None,
+            "Search term to find files containing this string, e.g. a variable name, string literal, or import. Used as a free-text search term.",
+        ] = None,
+    ) -> Annotated[
+        list[SearchResult],
+        (
+            "List of SearchResult objects, each with fields:"
+            " path (file path relative to repo root),"
+            " filename (just the file name, e.g. 'oauth.py'),"
+            " html_url (GitHub web URL to view the file),"
+            " sha (git blob SHA of the file),"
+            " language (detected programming language, or None),"
+            " score (relevance score from GitHub),"
+            " line_numbers (tuple of line number strings where matches occur),"
+            " text_matches (tuple of TextMatch objects, each with: fragment (code snippet),"
+            " matches (tuple of (matched_text, (start_index, end_index)) pairs)),"
+            " snippet (first fragment from text_matches for convenience, or empty string)."
+        ),
+    ]:
+        """Search the repository by path, filename, symbol, or content.
+        At least one of path, filename, symbol, or content must be provided.
+        Rate-limited to 10 requests per minute for authenticated users.
+        """
+        validate_repo(repo)
+        q = _build_search_query(repo, path, filename, symbol, content)
+        return _search_results_from_response(
+            get_json(
+                f"/search/code?q={q}",
+                headers={"Accept": "application/vnd.github.text-match+json"},
+            )
+        )
+
+    def get_sibling_files(
+        repo: Annotated[str, "Repository in 'owner/name' format, e.g. 'acme/backend'"],
+        path: Annotated[str, "Path of the changed file, e.g. 'src/auth/oauth.py'"],
+        ref: Annotated[str, "Any git ref — branch name, tag, or commit SHA"],
+    ) -> Annotated[
+        list[str],
+        (
+            "List of file paths (strings) for other files in the same directory as the given path."
+            " The given file itself is excluded. Paths are relative to the repo root,"
+            " e.g. ['src/auth/token.py', 'src/auth/utils.py']."
+        ),
+    ]:
+        """List sibling files in the same directory as the given file."""
+        validate_repo(repo)
+        directory = path.rsplit("/", 1)[0] if "/" in path else ""
+        data = get_json(f"/repos/{repo}/git/trees/{ref}?recursive=1")
+        return [
+            item["path"]
+            for item in data["tree"]
+            if _is_sibling(item["path"], item["type"], directory, path)
+        ]
+
+    return [get_file_at_ref, get_directory_tree, search_codebase, get_sibling_files]

github_context_tools/tools/conventions.py

@@ -0,0 +1,53 @@
+from base64 import b64decode
+from collections.abc import Callable
+from typing import Annotated
+
+from github_context_tools._utils import validate_repo
+from github_context_tools.models import RepoConventions
+
+_CONVENTION_CANDIDATES = [
+    "CONTRIBUTING.md",
+    "CLAUDE.md",
+    "AGENTS.md",
+    ".cursor/rules",
+    ".cursorrules",
+    ".github/copilot-instructions.md",
+    "docs/architecture.md",
+    "docs/ARCHITECTURE.md",
+    "docs/development.md",
+    "DEVELOPMENT.md",
+]
+
+
+def _fetch_convention_files(get_json, repo: str) -> list[tuple[str, str]]:
+    found = []
+    for candidate in _CONVENTION_CANDIDATES:
+        try:
+            content = b64decode(
+                get_json(f"/repos/{repo}/contents/{candidate}")["content"]
+            ).decode("utf-8")
+            found.append((candidate, content))
+        except Exception:
+            pass
+    return found
+
+
+def make_conventions_tools(get_json, _get_text, _post_json) -> list[Callable]:
+    def get_repo_conventions(
+        repo: Annotated[str, "Repository in 'owner/name' format, e.g. 'acme/backend'"],
+    ) -> Annotated[
+        RepoConventions,
+        (
+            "Contents of well-known convention and context files found in the repo's default branch. "
+            "Files that do not exist are silently skipped. "
+            "Returns a tuple of (filename, content) pairs for any of: "
+            "CONTRIBUTING.md, CLAUDE.md, AGENTS.md, .cursor/rules, .cursorrules, "
+            ".github/copilot-instructions.md, docs/architecture.md, docs/ARCHITECTURE.md, "
+            "docs/development.md, DEVELOPMENT.md."
+        ),
+    ]:
+        """Fetch well-known convention and context files from the repo's default branch."""
+        validate_repo(repo)
+        return RepoConventions(files=tuple(_fetch_convention_files(get_json, repo)))
+
+    return [get_repo_conventions]