Skip to content

A curated collection of practical AI projects implementing OCR systems, RAG, AI agents, and other AI use cases.

6.7 KB
Raw Blame
"""GitHub tools the agent can call, plus the OpenAI-style schemas that
describe them to the model.

v1 scope: one fixed repo (GITHUB_REPO, "owner/name") and a personal access
token (GITHUB_TOKEN). Enough to run "check recent changes, flag issues,
summarize" end to end. Letting the spoken instruction name a different repo
is a natural follow-up once this is working.
"""
import os

import requests

API_ROOT = "https://api.github.com"


def _repo() -> str:
    repo = os.environ.get("GITHUB_REPO")
    if not repo:
        raise RuntimeError("GITHUB_REPO is not set (expected 'owner/name'). Check your .env file.")
    return repo


def _headers() -> dict:
    token = os.environ.get("GITHUB_TOKEN")
    if not token:
        raise RuntimeError("GITHUB_TOKEN is not set. Check your .env file.")
    return {
        "Authorization": f"Bearer {token}",
        "Accept": "application/vnd.github+json",
        "X-GitHub-Api-Version": "2022-11-28",
    }


def _request(method: str, path: str, **kwargs) -> dict:
    response = requests.request(method, f"{API_ROOT}{path}", headers=_headers(), timeout=30, **kwargs)
    if not response.ok:
        raise RuntimeError(f"GitHub API {method} {path} failed ({response.status_code}): {response.text[:300]}")
    return response.json() if response.text else {}


def list_recent_commits(count: int = 5) -> dict:
    """List the most recent commits on the repo's default branch."""
    count = max(1, min(count, 20))
    data = _request("GET", f"/repos/{_repo()}/commits", params={"per_page": count})
    return {
        "commits": [
            {
                "sha": c["sha"][:10],
                "message": c["commit"]["message"].splitlines()[0],
                "author": (c["commit"]["author"] or {}).get("name"),
                "date": (c["commit"]["author"] or {}).get("date"),
                "url": c["html_url"],
            }
            for c in data
        ]
    }


def get_commit_diff(sha: str) -> dict:
    """Get the file-level diff for one commit, to see what actually changed."""
    data = _request("GET", f"/repos/{_repo()}/commits/{sha}")
    files = data.get("files", [])
    return {
        "sha": sha,
        "message": data.get("commit", {}).get("message", ""),
        "files": [
            {
                "filename": f.get("filename"),
                "status": f.get("status"),
                "additions": f.get("additions"),
                "deletions": f.get("deletions"),
                # Truncate long patches so a big diff doesn't blow the context budget.
                "patch": (f.get("patch") or "")[:4000],
            }
            for f in files
        ],
    }


def list_open_issues(count: int = 10) -> dict:
    """List open issues (pull requests are excluded)."""
    count = max(1, min(count, 30))
    data = _request("GET", f"/repos/{_repo()}/issues", params={"state": "open", "per_page": count})
    return {
        "issues": [
            {"number": i["number"], "title": i["title"], "url": i["html_url"]}
            for i in data
            if "pull_request" not in i
        ]
    }


def create_issue(title: str, body: str = "") -> dict:
    """Open a new GitHub issue."""
    data = _request("POST", f"/repos/{_repo()}/issues", json={"title": title, "body": body})
    return {"number": data["number"], "url": data["html_url"]}


def add_comment(issue_number: int, body: str) -> dict:
    """Add a comment to an existing issue or pull request."""
    data = _request("POST", f"/repos/{_repo()}/issues/{issue_number}/comments", json={"body": body})
    return {"url": data["html_url"]}


TOOL_FUNCTIONS = {
    "list_recent_commits": list_recent_commits,
    "get_commit_diff": get_commit_diff,
    "list_open_issues": list_open_issues,
    "create_issue": create_issue,
    "add_comment": add_comment,
}

TOOL_SCHEMAS = [
    {
        "type": "function",
        "function": {
            "name": "list_recent_commits",
            "description": "List the most recent commits on the repo's default branch.",
            "parameters": {
                "type": "object",
                "properties": {
                    "count": {
                        "type": "integer",
                        "description": "How many commits to return (max 20).",
                        "default": 5,
                    }
                },
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "get_commit_diff",
            "description": "Get the file-level diff (patch) for one commit, to inspect what changed.",
            "parameters": {
                "type": "object",
                "properties": {
                    "sha": {"type": "string", "description": "The commit SHA to inspect."}
                },
                "required": ["sha"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "list_open_issues",
            "description": "List currently open issues in the repo (pull requests excluded).",
            "parameters": {
                "type": "object",
                "properties": {
                    "count": {
                        "type": "integer",
                        "description": "How many issues to return (max 30).",
                        "default": 10,
                    }
                },
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "create_issue",
            "description": (
                "Open a new GitHub issue. Use this for anything the spoken request asks "
                "to flag or track, after you've actually inspected the relevant code."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "title": {"type": "string", "description": "Short issue title."},
                    "body": {
                        "type": "string",
                        "description": "Issue description — what was found and why it matters.",
                    },
                },
                "required": ["title"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "add_comment",
            "description": "Add a comment to an existing issue or pull request.",
            "parameters": {
                "type": "object",
                "properties": {
                    "issue_number": {
                        "type": "integer",
                        "description": "The issue or PR number to comment on.",
                    },
                    "body": {"type": "string", "description": "Comment text."},
                },
                "required": ["issue_number", "body"],
            },
        },
    },
]