pr_reviewer/README.md

# PR Reviewer

Automated pull request review system using [CrewAI](https://crewai.com) Flows and MCP (Model Context Protocol) tools.

Performs three parallel reviews — code quality, security, and infrastructure — then synthesizes a consolidated report via a REST API.

## Features

- **Code Review** — style, best practices, maintainability (powered by Semgrep)
- **Security Review** — vulnerabilities, injection risks, auth issues (powered by Trivy)
- **Infrastructure Review** — Dockerfiles, Kubernetes manifests, IaC (powered by Hadolint + Checkov)
- **Summarisation** — merges all three reviews into a single actionable report
- **REST API** — FastAPI endpoints for health check and review trigger
- **Dockerized** — multi-stage build with all tools bundled

## Architecture

```
POST /api/v1/review
        │
        ▼
  CodeReviewFlow (CrewAI Flow)
        │
   ┌────┼──────────────┐
   ▼    ▼              ▼
 Code  Security     Infra
Review  Review      Review
   │     │            │
   └─────┼────────────┘
         ▼
   Summariser
         │
         ▼
   JSON Response
```

LLM-agnostic via CrewAI's LLM abstraction — works with OpenAI, Anthropic, or Ollama.

## Quick Start

### Prerequisites

- Docker
- An LLM provider (OpenAI API key, Anthropic key, or a running Ollama instance)

### Setup

```bash
cp .env.example .env
# Edit .env with your LLM provider details
```

### Run

```bash
docker compose up
```

Server starts at `http://localhost:8000`.

### Test

```bash
# Health check
curl http://localhost:8000/api/v1/health

# Trigger a review
curl -X POST http://localhost:8000/api/v1/review \
  -H "Content-Type: application/json" \
  -d '{
    "pr_id": "123",
    "title": "Add user authentication",
    "repo": {"name": "myapp/backend", "url": "https://github.com/myapp/backend"},
    "source": {"branch": "feature/auth"},
    "target": {"branch": "main"},
    "files": [
      {
        "path": "auth.py",
        "status": "added",
        "content": "def login(user, pwd):\n    if user == \"admin\" and pwd == \"admin\":\n        return True",
        "additions": 3,
        "deletions": 0
      }
    ]
  }'
```

## API

### `GET /api/v1/health`

Returns service status.

```json
{"status": "healthy", "service": "pr-reviewer"}
```

### `POST /api/v1/review`

Triggers a full PR review.

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pr_id` | string | yes | PR identifier |
| `title` | string | yes | PR title |
| `description` | string | no | PR description |
| `repo.name` | string | yes | Repository name |
| `repo.url` | string | yes | Repository URL |
| `source.branch` | string | yes | Source branch |
| `source.commit` | string | no | Source commit SHA |
| `target.branch` | string | yes | Target branch |
| `target.commit` | string | no | Target commit SHA |
| `files[]` | array | no | Changed files |
| `files[].path` | string | yes | File path |
| `files[].content` | string | no | File contents |
| `files[].status` | string | yes | `added`, `modified`, `removed` |
| `files[].additions` | int | no | Lines added |
| `files[].deletions` | int | no | Lines removed |
| `files[].patch` | string | no | Unified diff |
| `context.code_review` | string | no | Code review guidelines override |
| `context.security_review` | string | no | Security review guidelines override |
| `context.infra_review` | string | no | Infrastructure review guidelines override |

**Response:**

```json
{
  "review_id": "uuid",
  "status": "completed",
  "timestamp": "2024-01-01T00:00:00Z",
  "results": {
    "code_review": "...",
    "security_review": "...",
    "infra_review": "...",
    "summary": "..."
  },
  "metadata": {
    "processing_time_seconds": 290.22,
    "pr_id": "123",
    "repo": {"name": "myapp/backend", "url": "https://github.com/myapp/backend"}
  }
}
```

## Configuration

All configuration via environment variables in `.env`:

| Variable | Default | Description |
|----------|---------|-------------|
| `LLM_MODEL` | (required) | Model name (e.g. `gpt-4`, `gemma4:31b-cloud`) |
| `LLM_PROVIDER` | (required) | `openai`, `anthropic`, or `ollama` |
| `LLM_BASE_URL` | — | API base URL |
| `LLM_API_KEY` | — | API key (not needed for Ollama) |
| `TOTAL_FLOW_TIMEOUT` | `600` | Max seconds for full review |
| `PER_CREW_TIMEOUT` | `300` | Max seconds per crew |
| `LOG_LEVEL` | `INFO` | Logging level |

## Development

```bash
# Install deps
uv pip install -e ".[dev]"

# Run tests
pytest tests/

# Run server locally
uvicorn src.pr_reviewer.main:app --reload
```

## Project Structure

```
├── config/               # Shared agent/task YAML configs
├── contexts/             # Default review guidelines (markdown)
├── crews/                # Crew definitions (code, security, infra, summariser)
├── mcp_servers/          # MCP tool wrappers (Hadolint, Checkov)
├── src/pr_reviewer/      # Core application code
│   ├── main.py           # FastAPI app
│   ├── flow.py           # CrewAI Flow orchestration
│   ├── state.py          # Pydantic state models
│   ├── llm.py            # LLM factory
│   └── context.py        # Context resolution
├── tests/                # Unit and integration tests
├── docker-compose.yaml
├── Dockerfile
└── pyproject.toml
```