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

github_context_tools/tools/factory.py

@@ -0,0 +1,90 @@
+"""
+GitHub API tools for fetching code review context.
+
+Call ``make_tools()`` once with an authenticated token to get a list of
+plain callables. Pass them directly to any agent framework's tool registry.
+The token is captured in a closure and never appears in any tool signature.
+
+Usage::
+
+    from github_context_tools import make_tools
+
+    tools = make_tools(token="ghp_...")  # or omit to read from GH_TOKEN / GITHUB_TOKEN env var
+
+    # Pass to any agent framework
+    agent.run(tools=tools)
+"""
+
+from collections.abc import Callable
+
+import httpx
+
+from github_context_tools._request import make_requester
+from github_context_tools.tools.code import make_code_tools
+from github_context_tools.tools.conventions import make_conventions_tools
+from github_context_tools.tools.history import make_history_tools
+from github_context_tools.tools.issues import make_issues_tools
+from github_context_tools.tools.pr import make_pr_tools
+
+
+def make_tools(
+    token: str | None = None,
+    http_client: httpx.Client | None = None,
+    include: set[str] | None = None,
+    exclude: set[str] | None = None,
+) -> list[Callable]:
+    """
+    Return a list of GitHub API tool functions bound to the given token.
+
+    Each tool is a plain callable with a clean signature — no token, no
+    client object. Safe to call concurrently; each call opens and closes
+    its own HTTP connection.
+
+    :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.
+    :param include: If provided, only tools whose names are in this set are
+                    returned. Raises ValueError if any name is not recognised.
+    :param exclude: If provided, tools whose names are in this set are removed
+                    from the result. Raises ValueError if any name is not
+                    recognised. When both include and exclude are given,
+                    exclusions are applied after inclusions.
+    """
+    if include is not None and exclude is not None and include.issubset(exclude):
+        raise ValueError(
+            "include and exclude are mutually exclusive: every tool in "
+            f"include {sorted(include)} is also in exclude {sorted(exclude)}, "
+            "which would return no tools."
+        )
+
+    get_json, get_text, post_json = make_requester(token, http_client)
+    all_tools = [
+        *make_pr_tools(get_json, get_text, post_json),
+        *make_code_tools(get_json, get_text, post_json),
+        *make_history_tools(get_json, get_text, post_json),
+        *make_issues_tools(get_json, get_text, post_json),
+        *make_conventions_tools(get_json, get_text, post_json),
+    ]
+
+    if include is None and exclude is None:
+        return all_tools
+
+    all_names = {t.__name__ for t in all_tools}
+
+    if include is not None:
+        unknown = include - all_names
+        if unknown:
+            raise ValueError(f"Unknown tool names in include: {sorted(unknown)}")
+
+    if exclude is not None:
+        unknown = exclude - all_names
+        if unknown:
+            raise ValueError(f"Unknown tool names in exclude: {sorted(unknown)}")
+
+    return [
+        t for t in all_tools
+        if (include is None or t.__name__ in include)
+        and (exclude is None or t.__name__ not in exclude)
+    ]

github_context_tools/tools/history.py

@@ -0,0 +1,192 @@
+from collections.abc import Callable
+from typing import Annotated
+
+from git_unified_diff_parse import DiffParser
+
+from github_context_tools._utils import validate_repo
+from github_context_tools.models import BlameEntry, CommitDiff, CommitSummary
+
+_BLAME_QUERY = """
+    query($owner: String!, $repo: String!, $expr: String!, $path: String!) {
+        repository(owner: $owner, name: $repo) {
+            object(expression: $expr) {
+                ... on Commit {
+                    blame(path: $path) {
+                        ranges {
+                            startingLine
+                            endingLine
+                            age
+                            commit {
+                                oid
+                                message
+                                commitUrl
+                                author { name date }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+"""
+
+
+def _blame_entries_from_response(data: dict) -> list[BlameEntry]:
+    if "errors" in data:
+        messages = ", ".join(e.get("message", "unknown") for e in data["errors"])
+        raise ValueError(f"GraphQL error from GitHub: {messages}")
+    try:
+        ranges = data["data"]["repository"]["object"]["blame"]["ranges"]
+    except (KeyError, TypeError) as e:
+        raise ValueError(
+            "Unexpected GraphQL response shape — the file or ref may not exist"
+        ) from e
+    return [
+        BlameEntry(
+            start_line=r["startingLine"],
+            end_line=r["endingLine"],
+            sha=r["commit"]["oid"],
+            message=r["commit"]["message"].splitlines()[0],
+            author=r["commit"]["author"]["name"],
+            date=r["commit"]["author"]["date"],
+            commit_url=r["commit"]["commitUrl"],
+            age=r["age"],
+        )
+        for r in ranges
+    ]
+
+
+def make_history_tools(get_json, get_text, post_json) -> list[Callable]:
+    def get_file_commit_history(
+        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'"
+        ],
+        max_commits: Annotated[int, "Maximum number of commits per page"] = 10,
+        page: Annotated[int, "Page number for pagination (1-indexed)"] = 1,
+        sha: Annotated[
+            str,
+            "Branch name, tag, or SHA to start listing from. Defaults to the repo's default branch",
+        ] = "",
+        author: Annotated[
+            str, "Filter by GitHub username or email address of the commit author"
+        ] = "",
+        since: Annotated[
+            str,
+            "Only include commits after this ISO 8601 timestamp, e.g. '2024-01-01T00:00:00Z'",
+        ] = "",
+        until: Annotated[
+            str,
+            "Only include commits before this ISO 8601 timestamp, e.g. '2024-12-31T23:59:59Z'",
+        ] = "",
+    ) -> Annotated[
+        list[CommitSummary],
+        (
+            "Recent commits that touched the file, newest-first. Each entry contains: "
+            "sha (full commit SHA), "
+            "message (first line of the commit message), "
+            "author (git author name), "
+            "date (ISO 8601 authored timestamp), "
+            "html_url (browser link to the commit on GitHub), "
+            "parents (list of parent SHAs — more than one parent indicates a merge commit)."
+        ),
+    ]:
+        """Fetch the commit history for a specific file."""
+        validate_repo(repo)
+        params = f"path={path}&per_page={max_commits}&page={page}"
+        if sha:
+            params += f"&sha={sha}"
+        if author:
+            params += f"&author={author}"
+        if since:
+            params += f"&since={since}"
+        if until:
+            params += f"&until={until}"
+        data = get_json(f"/repos/{repo}/commits?{params}")
+        results = []
+        for item in data:
+            commit = item["commit"]
+            git_author = commit.get("author") or {}
+            parents = tuple(p["sha"] for p in item.get("parents", []))
+            results.append(
+                CommitSummary(
+                    sha=item["sha"],
+                    message=commit["message"].splitlines()[0],
+                    author=git_author.get("name", ""),
+                    date=git_author.get("date", ""),
+                    html_url=item.get("html_url", ""),
+                    parents=parents,
+                )
+            )
+        return results
+
+    def get_commit_diff(
+        repo: Annotated[str, "Repository in 'owner/name' format, e.g. 'acme/backend'"],
+        commit_sha: Annotated[str, "Full or abbreviated commit SHA"],
+    ) -> Annotated[
+        CommitDiff,
+        (
+            "Parsed diff for the commit. Fields: "
+            "sha (the commit SHA), "
+            "diff (tuple of ChangedFile objects, one per file touched). "
+            "Each ChangedFile has: old_path (path before the change, None for added files), "
+            "new_path (path after the change, None for deleted files), "
+            "status (one of 'added', 'modified', 'removed', 'renamed', 'copied'), "
+            "is_binary (True for binary files — hunks will be empty), "
+            "hunks (list of DiffHunk objects). "
+            "Each DiffHunk has: header (raw @@ line), old_start, old_count, new_start, new_count, "
+            "lines (list of DiffLine). "
+            "Each DiffLine has: content (line text), is_addition, is_deletion, is_context (bool flags), "
+            "new_line_number, old_line_number (None on the side where the line doesn't exist)."
+        ),
+    ]:
+        """Fetch and parse the diff introduced by a single commit."""
+        validate_repo(repo)
+        diff_text = get_text(
+            f"/repos/{repo}/commits/{commit_sha}",
+            headers={"Accept": "application/vnd.github.diff"},
+        )
+        return CommitDiff(
+            sha=commit_sha,
+            diff=tuple(DiffParser().parse(diff_text)),
+        )
+
+    def get_blame(
+        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, "Branch name, tag, or commit SHA to blame at"],
+    ) -> Annotated[
+        list[BlameEntry],
+        (
+            "Blame ranges for the entire file, one entry per contiguous block of lines last touched "
+            "by the same commit. Each BlameEntry has: "
+            "start_line, end_line (1-indexed, inclusive line range covered by this entry), "
+            "sha (commit SHA that last modified these lines), "
+            "message (first line of that commit's message), "
+            "author (git author name), "
+            "date (ISO 8601 authored timestamp), "
+            "commit_url (browser link to the commit on GitHub), "
+            "age (recency score 1–10 relative to other changes in this file: 1 = most recent, 10 = oldest)."
+        ),
+    ]:
+        """Fetch git blame for an entire file via the GitHub GraphQL API."""
+        validate_repo(repo)
+        owner, repo_name = repo.split("/", 1)
+        return _blame_entries_from_response(
+            post_json(
+                "/graphql",
+                body={
+                    "query": _BLAME_QUERY,
+                    "variables": {
+                        "owner": owner,
+                        "repo": repo_name,
+                        "expr": ref,
+                        "path": path,
+                    },
+                },
+            )
+        )
+
+    return [get_file_commit_history, get_commit_diff, get_blame]

github_context_tools/tools/issues.py

@@ -0,0 +1,55 @@
+from collections.abc import Callable
+from typing import Annotated
+
+from github_context_tools._utils import validate_repo
+from github_context_tools.models import Issue, IssueComment
+
+
+def make_issues_tools(get_json, _get_text, _post_json) -> list[Callable]:
+    def get_linked_issue(
+        repo: Annotated[str, "Repository in 'owner/name' format, e.g. 'acme/backend'"],
+        issue_number: Annotated[int, "GitHub issue number, e.g. 42"],
+    ) -> Annotated[
+        Issue,
+        (
+            "GitHub issue with fields: "
+            "number (issue number), "
+            "title, "
+            "body (issue description text), "
+            "author (GitHub login of the issue creator), "
+            "state ('open' or 'closed'), "
+            "state_reason (why it was closed: 'completed', 'not_planned', 'reopened', or null), "
+            "labels (tuple of label name strings), "
+            "created_at (ISO 8601 timestamp), "
+            "closed_at (ISO 8601 timestamp or null), "
+            "comments (tuple of IssueComment objects). "
+            "Each IssueComment has: author (GitHub login), body (comment text), "
+            "created_at (ISO 8601 timestamp), html_url (link to the comment)."
+        ),
+    ]:
+        """Fetch a GitHub issue and its comments by issue number."""
+        validate_repo(repo)
+        data = get_json(f"/repos/{repo}/issues/{issue_number}")
+        comments_data = get_json(f"/repos/{repo}/issues/{issue_number}/comments")
+        return Issue(
+            number=data["number"],
+            title=data["title"],
+            body=data["body"] or "",
+            author=data["user"]["login"],
+            state=data["state"],
+            state_reason=data.get("state_reason"),
+            labels=tuple(lb["name"] for lb in data.get("labels", [])),
+            created_at=data["created_at"],
+            closed_at=data.get("closed_at"),
+            comments=tuple(
+                IssueComment(
+                    author=c["user"]["login"],
+                    body=c["body"],
+                    created_at=c["created_at"],
+                    html_url=c["html_url"],
+                )
+                for c in comments_data
+            ),
+        )
+
+    return [get_linked_issue]

github_context_tools/tools/pr.py

@@ -0,0 +1,159 @@
+from collections.abc import Callable
+from typing import Annotated
+
+from git_unified_diff_parse import DiffParser
+
+from github_context_tools._utils import parse_pr_url
+from github_context_tools.models import PRComment, PRDescription, PRDiff, PRMetadata
+
+
+def make_pr_tools(get_json, get_text, _post_json) -> list[Callable]:
+    def get_pr_metadata(
+        pr_url: Annotated[
+            str, "Full GitHub PR URL, e.g. 'https://github.com/owner/repo/pull/123'"
+        ],
+    ) -> Annotated[
+        PRMetadata,
+        (
+            "Pull request metadata with fields: repo (owner/name), pr_number, title, description,"
+            " author (GitHub login), base_branch, head_branch, base_sha, head_sha, html_url,"
+            " state ('open' or 'closed'), commits (count), changed_files (count),"
+            " additions (line count), deletions (line count)"
+        ),
+    ]:
+        """Fetch pull request metadata."""
+        owner, repo, pr_number = parse_pr_url(pr_url)
+        repo_full = f"{owner}/{repo}"
+        pr_data = get_json(f"/repos/{repo_full}/pulls/{pr_number}")
+        return PRMetadata(
+            repo=repo_full,
+            pr_number=pr_data["number"],
+            title=pr_data["title"],
+            description=pr_data["body"] or "",
+            author=pr_data["user"]["login"],
+            base_branch=pr_data["base"]["ref"],
+            head_branch=pr_data["head"]["ref"],
+            base_sha=pr_data["base"]["sha"],
+            head_sha=pr_data["head"]["sha"],
+            html_url=pr_data["html_url"],
+            state=pr_data["state"],
+            commits=pr_data["commits"],
+            changed_files=pr_data["changed_files"],
+            additions=pr_data["additions"],
+            deletions=pr_data["deletions"],
+        )
+
+    def get_parsed_pr_diff(
+        pr_url: Annotated[
+            str, "Full GitHub PR URL, e.g. 'https://github.com/owner/repo/pull/123'"
+        ],
+    ) -> Annotated[
+        PRDiff,
+        (
+            "Parsed PR diff with fields: repo (owner/name), diff (tuple of ChangedFile objects)."
+            " Each ChangedFile has: old_path, new_path, hunks (list of diff hunks)."
+            " Each hunk has: old_start, old_count, new_start, new_count, lines (list of DiffLine)."
+            " Each DiffLine has: kind ('added', 'removed', or 'context') and content (line text)."
+        ),
+    ]:
+        """Fetch and parse the pull request diff."""
+        owner, repo, pr_number = parse_pr_url(pr_url)
+        repo_full = f"{owner}/{repo}"
+        diff_text = get_text(
+            f"/repos/{repo_full}/pulls/{pr_number}",
+            headers={"Accept": "application/vnd.github.diff"},
+        )
+        return PRDiff(
+            repo=repo_full,
+            diff=tuple(DiffParser().parse(diff_text)),
+        )
+
+    def get_pr_description(
+        pr_url: Annotated[
+            str, "Full GitHub PR URL, e.g. 'https://github.com/owner/repo/pull/123'"
+        ],
+    ) -> Annotated[
+        PRDescription,
+        "PR description with fields: title (str), body (str, the full PR description text), labels (tuple of label name strings)",
+    ]:
+        """Fetch the pull request title, description body, and labels."""
+        owner, repo, pr_number = parse_pr_url(pr_url)
+        repo_full = f"{owner}/{repo}"
+        data = get_json(f"/repos/{repo_full}/pulls/{pr_number}")
+        return PRDescription(
+            title=data["title"],
+            body=data["body"] or "",
+            labels=tuple(label["name"] for label in data.get("labels", [])),
+        )
+
+    def get_pr_comments(
+        pr_url: Annotated[
+            str, "Full GitHub PR URL, e.g. 'https://github.com/owner/repo/pull/123'"
+        ],
+    ) -> Annotated[
+        list[PRComment],
+        (
+            "All comments on the pull request as a list of PRComment objects."
+            " Each PRComment has: author (GitHub login), body (comment text), created_at (ISO timestamp),"
+            " is_review_comment (True for inline file comments, False for PR-level conversation comments),"
+            " html_url (link to the comment)."
+            " For review comments (is_review_comment=True): path (file path), line (line number on the diff side),"
+            " side ('RIGHT' for additions, 'LEFT' for deletions), original_line (line number on the base commit),"
+            " original_side, start_line (first line for multi-line comments), start_side,"
+            " diff_hunk (surrounding diff context), commit_id (SHA of commit the comment was made on),"
+            " in_reply_to_id (ID of parent comment for replies, None for top-level)."
+            " For issue comments (is_review_comment=False): path, line, side, original_line, original_side,"
+            " start_line, start_side, diff_hunk, commit_id, in_reply_to_id are all None."
+        ),
+    ]:
+        """Fetch all existing comments on a pull request."""
+        owner, repo, pr_number = parse_pr_url(pr_url)
+        repo_full = f"{owner}/{repo}"
+        # Inline review comments attached to a specific file and line.
+        review_comments = get_json(f"/repos/{repo_full}/pulls/{pr_number}/comments")
+        # Every PR is also an issue in GitHub's data model and shares the same number.
+        # PR-level conversation comments (not tied to a file) are exposed via the Issues API.
+        issue_comments = get_json(f"/repos/{repo_full}/issues/{pr_number}/comments")
+        comments = [
+            PRComment(
+                author=c["user"]["login"],
+                body=c["body"],
+                created_at=c["created_at"],
+                path=c.get("path"),
+                line=c.get("line"),
+                side=c.get("side"),
+                original_line=c.get("original_line"),
+                original_side=c.get("original_side"),
+                start_line=c.get("start_line"),
+                start_side=c.get("start_side"),
+                diff_hunk=c.get("diff_hunk"),
+                commit_id=c.get("commit_id"),
+                in_reply_to_id=c.get("in_reply_to_id"),
+                html_url=c.get("html_url"),
+                is_review_comment=True,
+            )
+            for c in review_comments
+        ]
+        comments += [
+            PRComment(
+                author=c["user"]["login"],
+                body=c["body"],
+                created_at=c["created_at"],
+                path=None,
+                line=None,
+                side=None,
+                original_line=None,
+                original_side=None,
+                start_line=None,
+                start_side=None,
+                diff_hunk=None,
+                commit_id=None,
+                in_reply_to_id=None,
+                html_url=c.get("html_url"),
+                is_review_comment=False,
+            )
+            for c in issue_comments
+        ]
+        return comments
+
+    return [get_pr_metadata, get_parsed_pr_diff, get_pr_description, get_pr_comments]

github_context_tools-0.1.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: github-context-tools
+Version: 0.1.0
+Summary: Typed GitHub API tools for fetching context in LLM-based workflows
+Project-URL: Homepage, https://github.com/kruthis123/github-context-tools
+Project-URL: Repository, https://github.com/kruthis123/github-context-tools
+Project-URL: Bug Tracker, https://github.com/kruthis123/github-context-tools/issues
+Project-URL: Changelog, https://github.com/kruthis123/github-context-tools/blob/main/CHANGELOG.md
+Author-email: Kruthi Shiva Kumar <kruthis2601@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Kruthi Shiva Kumar
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+License-File: LICENSE
+Keywords: code-review,context,diff,github,llm,pull-request
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: git-unified-diff-parse>=0.1.1
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# github-context-tools
+
+Typed GitHub API tools that give LLMs structured access to pull requests, code, history, and issues.
+
+## Installation
+
+```bash
+pip install github-context-tools
+```
+
+## Quickstart
+
+```python
+from github_context_tools import make_tools
+
+tools = make_tools(token="ghp_...")  # or set GH_TOKEN / GITHUB_TOKEN env var
+
+# Pass the list to your agent framework's tool registry
+agent.run(tools=tools)
+```
+
+## How it works
+
+`make_tools()` returns a list of plain Python functions. You pass that list directly to your agent framework's tool registry — no adapters or glue code needed.
+
+Each tool is fully typed using `Annotated[type, "description"]` on every parameter and return value. Agent frameworks (Anthropic SDK, LangChain, OpenAI, etc.) read these annotations to automatically generate tool schemas, so the LLM always knows what each tool does, what to pass in, and what to expect back.
+
+## Available tools
+
+### Pull requests
+
+| Tool | Description | Returns |
+|---|---|---|
+| [`get_pr_metadata`](https://github.com/kruthis123/github-context-tools/blob/master/src/github_context_tools/tools/pr.py#L11) | Title, author, branch names, SHAs, state, and change stats for a PR | `PRMetadata` |
+| [`get_parsed_pr_diff`](https://github.com/kruthis123/github-context-tools/blob/master/src/github_context_tools/tools/pr.py#L46) | Structured diff of every file changed in a PR, broken into hunks and individual lines | `PRDiff` |
+| [`get_pr_description`](https://github.com/kruthis123/github-context-tools/blob/master/src/github_context_tools/tools/pr.py#L71) | Title, body, and labels of a PR | `PRDescription` |
+| [`get_pr_comments`](https://github.com/kruthis123/github-context-tools/blob/master/src/github_context_tools/tools/pr.py#L89) | All inline review comments and conversation comments on a PR | `list[PRComment]` |
+
+### Code
+
+| Tool | Description | Returns |
+|---|---|---|
+| [`get_file_at_ref`](https://github.com/kruthis123/github-context-tools/blob/master/src/github_context_tools/tools/code.py#L85) | Contents of a file at any branch, tag, or commit SHA | `FileContent` |
+| [`get_directory_tree`](https://github.com/kruthis123/github-context-tools/blob/master/src/github_context_tools/tools/code.py#L115) | Recursive file tree for a repo or subdirectory at a given ref | `dict` |
+| [`search_codebase`](https://github.com/kruthis123/github-context-tools/blob/master/src/github_context_tools/tools/code.py#L142) | Search a repo by content, file path, filename, or symbol name | `list[SearchResult]` |
+| [`get_sibling_files`](https://github.com/kruthis123/github-context-tools/blob/master/src/github_context_tools/tools/code.py#L189) | All other files in the same directory as a given file | `list[str]` |
+
+### History
+
+| Tool | Description | Returns |
+|---|---|---|
+| [`get_file_commit_history`](https://github.com/kruthis123/github-context-tools/blob/master/src/github_context_tools/tools/history.py#L60) | Recent commits that touched a file, newest-first. Supports filtering by author, date range, and branch | `list[CommitSummary]` |
+| [`get_commit_diff`](https://github.com/kruthis123/github-context-tools/blob/master/src/github_context_tools/tools/history.py#L123) | Structured diff introduced by a single commit | `CommitDiff` |
+| [`get_blame`](https://github.com/kruthis123/github-context-tools/blob/master/src/github_context_tools/tools/history.py#L154) | Blame ranges for an entire file, each annotated with the commit, author, and a recency score | `list[BlameEntry]` |
+
+### Issues
+
+| Tool | Description | Returns |
+|---|---|---|
+| [`get_linked_issue`](https://github.com/kruthis123/github-context-tools/blob/master/src/github_context_tools/tools/issues.py#L9) | Title, body, author, labels, state, and comments for a GitHub issue | `Issue` |
+
+### Conventions
+
+| Tool | Description | Returns |
+|---|---|---|
+| [`get_repo_conventions`](https://github.com/kruthis123/github-context-tools/blob/master/src/github_context_tools/tools/conventions.py#L36) | Contents of well-known convention and context files from the default branch (`CONTRIBUTING.md`, `CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `.cursorrules`, `.github/copilot-instructions.md`, `docs/architecture.md`, `docs/ARCHITECTURE.md`, `docs/development.md`, `DEVELOPMENT.md`) | `RepoConventions` |
+
+## Selecting tools
+
+By default `make_tools()` returns all 13 tools. Use `include` or `exclude` to control which tools are registered with your agent.
+
+**Include only the tools you need:**
+
+```python
+tools = make_tools(
+    token="ghp_...",
+    include={"get_pr_metadata", "get_parsed_pr_diff", "get_pr_comments"},
+)
+```
+
+**Exclude tools you don't want:**
+
+```python
+tools = make_tools(
+    token="ghp_...",
+    exclude={"get_blame", "search_codebase"},
+)
+```
+
+Both parameters accept a `set[str]` of tool names (the function names listed in the [Available tools](#available-tools) table). Unrecognised names raise a `ValueError` immediately.
+
+## Authentication
+
+Pass a token directly or set an environment variable:
+
+```bash
+export GH_TOKEN=ghp_...
+# or
+export GITHUB_TOKEN=ghp_...
+```
+
+```python
+tools = make_tools(token="ghp_...")
+```
+
+### Required token scopes
+
+Use a classic personal access token (PAT) with the following scopes:
+
+| Scope | Required for |
+|---|---|
+| `repo` | All tools on **private** repositories |
+| `public_repo` | All tools on **public** repositories only |
+
+Fine-grained PATs work too. Grant **read-only** access to the following permissions on the target repositories:
+
+| Permission | Required for |
+|---|---|
+| Contents | `get_file_at_ref`, `get_directory_tree`, `get_sibling_files`, `get_repo_conventions` |
+| Pull requests | `get_pr_metadata`, `get_parsed_pr_diff`, `get_pr_description`, `get_pr_comments` |
+| Issues | `get_linked_issue` |
+| Metadata | Required by GitHub for all repository access (granted automatically) |
+
+`get_file_commit_history`, `get_commit_diff`, and `get_blame` use the Commits and GraphQL APIs, which are covered by the Contents and Metadata permissions above.
+
+The token is captured in a closure and never appears in any tool signature, so it is never exposed to the LLM or included in generated schemas.
+
+## License
+
+[MIT](https://github.com/kruthis123/github-context-tools/blob/master/LICENSE)