github-context-tools 0.1.0__tar.gz

github_context_tools-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run tests
+        run: uv run pytest

github_context_tools-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

github_context_tools-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Environment & secrets
+.env
+.env.*
+*.env
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*.pyo
+.mypy_cache/
+.ruff_cache/
+
+# Test & coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+
+# macOS
+.DS_Store
+
+# Claude
+.claude

github_context_tools-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-23
+
+### Added
+- `make_tools()` factory returning all tools as plain annotated callables
+- **PR entry points**: `get_pr_metadata`, `get_parsed_pr_diff`
+- **PR intent**: `get_pr_description`, `get_pr_comments`
+- **Code understanding**: `get_file_at_ref`, `get_directory_tree`, `search_codebase`, `get_sibling_files`
+- **History**: `get_file_commit_history`, `get_commit_diff`, `get_blame`
+- **Issues**: `get_linked_issue`
+- **Conventions**: `get_repo_conventions`
+- Structured output models: `PRMetadata`, `PRDiff`, `PRDescription`, `PRComment`, `FileContent`, `SearchResult`, `CommitSummary`, `CommitDiff`, `BlameEntry`, `Issue`, `IssueComment`, `RepoConventions`
+- Typed exceptions: `GitHubAPIError`, `NotFoundError`, `AuthenticationError`, `RateLimitError`
+- Token resolution from `GH_TOKEN` / `GITHUB_TOKEN` environment variables

github_context_tools-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+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.

github_context_tools-0.1.0/PKG-INFO

@@ -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)

github_context_tools-0.1.0/README.md

@@ -0,0 +1,130 @@
+# 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)