pr_reviewer/README.md

# PR Reviewer

An automated pull request review system using CrewAI and MCP (Model Context Protocol).

## Overview

This system provides automated code, security, and infrastructure reviews for pull requests using a multi-agent approach. It leverages CrewAI for orchestrating specialized review agents and MCP (Model Context Protocol) for integrating with various static analysis tools.

## Features

- **Code Review**: Uses Semgrep (via MCP) to check code quality, best practices, and maintainability
- **Security Review**: Uses Trivy (native MCP) to identify security vulnerabilities
- **Infrastructure Review**: Uses Hadolint and Checkov (via MCP wrappers) to review Dockerfiles and Kubernetes manifests
- **Contextual Review**: Incorporates customizable guidelines for code, security, and infrastructure reviews
- **Automated Orchestration**: Uses CrewAI Flows to manage the review process
- **REST API**: FastAPI endpoint for triggering reviews
- **Containerized**: Docker support for easy deployment

## Architecture

The system follows a modular architecture with:
- State management using Pydantic models
- LLM factory for flexible provider support (OpenAI, Anthropic, Ollama)
- Context resolution system for incorporating review guidelines
- Crew-based implementation for each review type (code, security, infrastructure)
- MCP server integrations for static analysis tools
- Flow-based orchestration for managing the review process
- RESTful API for integration with CI/CD systems

## Installation

### Prerequisites
- Python 3.10-3.13
- UV package manager
- Git
- Docker (optional, for containerized deployment)

### Local Development
1. Clone the repository
2. Install UV package manager: `curl -LsSf https://astral.sh/uv/install.sh | sh`
3. Activate UV environment: `source $HOME/.local/bin/env`
4. Create virtual environment: `uv venv .venv`
5. Activate virtual environment: `source .venv/bin/activate`
6. Install dependencies: `uv pip install -e .`
7. Configure environment variables (see `.env.example`)

### Docker Deployment
1. Build the Docker image: `docker build -t pr-reviewer .`
2. Run the container: `docker run -p 8000:8000 --env-file .env pr-reviewer`

## Usage

### API Endpoints

#### Health Check
```bash
GET /api/v1/health
```
Returns the health status of the service.

#### Trigger PR Review
```bash
POST /api/v1/review
```
Initiates a pull request review.

Request Body:
```json
{
  "pr_id": "123",
  "title": "Add new feature",
  "description": "This PR adds a new feature to the application",
  "repo": {
    "name": "my-repo",
    "url": "https://github.com/user/my-repo"
  },
  "source": {
    "branch": "feature/new-feature",
    "commit": "abc123"
  },
  "target": {
    "branch": "main",
    "commit": "def456"
  },
  "files": [
    {
      "path": "src/main.py",
      "content": "print('Hello World')",
      "status": "modified",
      "additions": 1,
      "deletions": 0
    }
  ],
  "context": {
    "code_review": "Follow PEP8 guidelines",
    "security_review": "Check for SQL injection vulnerabilities",
    "infra_review": "Ensure Dockerfile follows best practices"
  }
}
```

Response:
```json
{
  "review_id": "uuid-string",
  "status": "completed",
  "timestamp": "2023-05-08T10:00:00Z",
  "results": {
    "code_review": "Code review results...",
    "security_review": "Security review results...",
    "infra_review": "Infrastructure review results...",
    "summary": "Synthesized review summary..."
  },
  "metadata": {
    "processing_time_seconds": 45.2,
    "pr_id": "123",
    "repo": {
      "name": "my-repo",
      "url": "https://github.com/user/my-repo"
    }
  }
}
```

## Configuration

### Environment Variables
See `.env.example` for detailed configuration options.

### Context Files
Default review guidelines are located in `contexts/defaults/`:
- `code_review.md`: Coding practice guidelines
- `security_review.md`: Security guidelines
- `infra_review.md`: Infrastructure guidelines

These can be overridden via the API context parameter.

## Development

### Running Tests
```bash
# Run unit tests
pytest

# Run tests with coverage
pytest --cov=src.pr_reviewer

# Run specific test categories
pytest tests/unit/
pytest tests/integration/
```

### Code Style
The project uses Black for code formatting and Flake8 for linting.

Run formatting:
```bash
black src/
```

Run linting:
```bash
flake8 src/
```

## Deployment

### Kubernetes
Kubernetes manifests are available in the `k8s/` directory:
- Secret for LLM configuration
- Deployment for the PR Reviewer service
- Service for exposing the API

### Gitea Actions
GitHub Actions workflow for CI/CD is available in `.gitea/workflows/deploy.yaml`.

## License
MIT

## Contributing
1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a pull request