learningcircuit--local-deep-research/docs/AI_Code_Reviewer_Setup.md

# AI Code Reviewer Setup Guide

This guide explains how to set up the automated AI PR review system using OpenRouter to analyze pull requests with your choice of AI model.

## Overview

The AI Code Reviewer provides automated, comprehensive code reviews covering:
- **Security** 🔒 - Hardcoded secrets, SQL injection, XSS, authentication issues, input validation
- **Performance** ⚡ - Inefficient algorithms, N+1 queries, memory issues, blocking operations
- **Code Quality** 🎨 - Readability, maintainability, error handling, naming conventions
- **Best Practices** 📋 - Coding standards, proper patterns, type safety, dead code

The review is posted as a single comprehensive comment on your pull request.

## Setup Instructions

### 1. Get OpenRouter API Key

1. Go to [OpenRouter.ai](https://openrouter.ai/)
2. Sign up or log in
3. Navigate to API Keys section
4. Create a new API key
5. Copy the key (it starts with `sk-or-v1-...`)

### 2. Add API Key to GitHub Secrets

1. Go to your GitHub repository
2. Navigate to **Settings** → **Secrets and variables** → **Actions**
3. Click **New repository secret**
4. Name it: `OPENROUTER_API_KEY`
5. Paste your OpenRouter API key
6. Click **Add secret**

### 3. Configure Workflow (Optional)

The workflow is pre-configured with sensible defaults. You can override them **without editing the workflow** by adding GitHub **repository variables** (not secrets):

1. Go to your repository → **Settings** → **Secrets and variables** → **Actions**
2. Open the **Variables** tab → **New repository variable**
3. Add any of:

- **AI_REVIEW_MODELS**: Comma-separated list of models. Each model runs the reviewer independently, so you get one review per model in a single combined comment (see [Multiple reviewers](#multiple-reviewers)). When unset, falls back to `AI_MODEL`, then to the built-in default.
- **AI_MODEL**: A single model (see [OpenRouter models](https://openrouter.ai/models)). Used by the reviewer when `AI_REVIEW_MODELS` is unset, and also by the release-notes workflow. Default: `moonshotai/kimi-k2-thinking`.
- **AI_TEMPERATURE**: Adjust randomness (default: `0.1` for consistent reviews)
- **AI_MAX_TOKENS**: Maximum response length (default: `64000`)
- **MAX_DIFF_SIZE**: Maximum diff size in bytes (default: `800000` / 800KB)

#### Multiple reviewers

Set **AI_REVIEW_MODELS** to a comma-separated list to have several models review the same diff. For example:

```
minimax/minimax-m3, z-ai/glm-5.2
```

Notes:
- Separate models with **commas** (spaces around them are fine and trimmed). A space-separated value is treated as a *single* model name and will fail.
- Each model is shown anonymously as **Reviewer 1**, **Reviewer 2**, … (the model→reviewer mapping appears only in the workflow logs), so readers judge the feedback rather than the model.
- All reviews are collected into one sticky PR comment. Labels are unioned across reviewers; if `FAIL_ON_REQUESTED_CHANGES` is enabled, the workflow fails when **any** reviewer requests changes. This is deliberately "any" rather than a majority vote — a single model catching a real blocker shouldn't be outvoted — and it only takes effect when you opt into `FAIL_ON_REQUESTED_CHANGES` (off by default). A reviewer that errors out (rather than returning a verdict) never counts as a "fail"; it just shows a note in its section.
- Models run **in parallel**, so the job's wall-clock is the slowest single review rather than the sum. Each model still makes its own set of GitHub API calls for context, so a very long list means many concurrent calls; two or three models are well within limits.

## Usage

### Triggering AI Reviews

To trigger an AI review on a PR:

1. Go to the PR page
2. Click **Labels**
3. Add the label: `ai_code_review`

The review will automatically start and post results as a comment when complete.

### Re-running Reviews

To re-run the AI review after making changes:

1. Remove the `ai_code_review` label
2. Add the `ai_code_review` label again

This will generate a fresh review of the current PR state.

## Review Results

The AI posts a comprehensive comment analyzing your code across all focus areas. The review is meant to assist human reviewers, not replace them.

## Cost Estimation

Costs vary by model, but most code-focused models on OpenRouter are very affordable:
- Typical small PR (< 1000 lines): $0.001 - $0.01
- Large PR (1000-5000 lines): $0.01 - $0.05

Check [OpenRouter pricing](https://openrouter.ai/models) for specific model costs.

## Customization

### Changing the Review Focus

The review prompt lives in `ai-reviewer.sh`, which the workflow downloads at run time from the [Friendly-AI-Reviewer](https://github.com/LearningCircuit/Friendly-AI-Reviewer) repository (see the "Download AI reviewer script" step in `.github/workflows/ai-code-reviewer.yml`) — it is **not** stored in this repo. The current focus areas are:
- Security (secrets, injection attacks, authentication)
- Performance (algorithms, queries, memory)
- Code Quality (readability, maintainability, error handling)
- Best Practices (standards, patterns, type safety)

To adjust them, edit the prompt in that repository (or fork it and point the workflow's download step at your fork).

## Troubleshooting

### Reviews Not Running

- Ensure the `ai_code_review` label is added (not just present)
- Check that `OPENROUTER_API_KEY` secret is correctly configured
- Verify GitHub Actions permissions are properly set

### API Errors

- Check OpenRouter API key validity
- Verify OpenRouter account has sufficient credits
- Review GitHub Actions logs for specific error messages

### Diff Too Large Error

If you get a "Diff is too large" error:
- Split your PR into smaller, focused changes
- Or increase `MAX_DIFF_SIZE` in the workflow file
- Default limit is 800KB (~200K tokens)

## Security Considerations

- API keys are stored securely in GitHub Secrets and passed via environment variables
- Reviews only run when the `ai_code_review` label is manually added
- All API calls are made through secure HTTPS connections
- Code diffs are sent to OpenRouter/AI provider - review their data policies
- The workflow has minimal permissions (read contents, write PR comments)

## Support

For issues with:
- **OpenRouter API**: Check [OpenRouter documentation](https://openrouter.ai/docs)
- **GitHub Actions**: Check [GitHub Actions documentation](https://docs.github.com/en/actions)
- **Workflow issues**: Review the GitHub Actions logs for specific error details