🤖 Automated AST-Aware PR Review Bot

Caution

⚠️ EXPERIMENTAL & UNTESTED — WORK IN PROGRESS

This repository is an active Work-In-Progress (WIP) and is currently untested in live environments.

• Experimental Software: The AST parsing logic, token funnel filtering, prompt generation, and GitHub REST API comment handlers are experimental and subject to rapid iteration.
• Not for Users or Production Webhooks: This bot is not intended for production CI/CD pipelines, public repository webhooks, or critical review gates.
• Use at Your Own Risk: Webhook handlers and LLM review prompts have not undergone live end-to-end security audits or load testing. Automated reviews may produce inaccurate feedback or high LLM token consumption if deployed unchecked.

An asynchronous FastAPI webhook service that receives GitHub Pull Request events, applies a cost-funnel filter to discard non-code/lock files, parses unified diff hunks, extracts enclosing function scopes using Python's ast module, performs targeted LLM reviews with strict Pydantic schemas and bounded concurrency, and posts batched inline comments via GitHub's REST Reviews API.

Tech Stack

• ⚡ Backend: Python 3.10+, FastAPI, Uvicorn
• 🌳 Parsing: Python standard library ast, re, pathlib, hmac, hashlib
• 🤖 LLM Integration: OpenAI API (structured parsing via Pydantic)
• 🌐 HTTP Client: httpx (async)
• 🧪 Testing: pytest, pytest-asyncio
• 🐳 Deployment: Docker

Quick Start

1. Clone and install dependencies:

   git clone <repo-url>
   cd pr-review-bot
   pip install -r requirements.txt

2. Configure environment:

   cp .env.example .env
   # Edit .env with your actual secrets

3. Run the server:

   uvicorn app.main:app --reload

4. Run with Docker:

   docker build -t pr-review-bot .
   docker run -p 8000:8000 --env-file .env pr-review-bot

Project Structure

pr-review-bot/
├── app/
│   ├── main.py                  # FastAPI app entrypoint & router mounting
│   ├── config.py                # Environment configuration & secrets
│   ├── api/
│   │   └── webhook.py           # HMAC verification & POST /webhook handler
│   ├── core/                    # Pure deterministic logic (Zero I/O)
│   │   ├── filter.py            # File filtering (lockfiles, assets, extensions)
│   │   ├── diff_parser.py       # Unified diff parser & new line number extractor
│   │   └── ast_parser.py        # AST traversal & enclosing scope extractor
│   ├── services/                # I/O & External integrations
│   │   ├── github.py            # GitHub API client (diffs, files, batch reviews)
│   │   ├── llm.py               # Async LLM reviewer with bounded concurrency
│   │   └── orchestrator.py      # Background task orchestrating the full pipeline
│   └── models/
│       └── review.py            # Pydantic schemas (ReviewItem, ReviewResponse)
├── tests/
├── .env.example
├── Dockerfile
├── requirements.txt
└── README.md

Running Tests

pytest tests/ -v