pr-reviewer/README.md

# pr-reviewer

A local dashboard that pulls open PRs from your GitHub org, reviews each one with a Fireworks model using the BLOCK / FIX / NIT / QUESTION skill format, and lets you request revisions or post the review to GitHub as yourself.

A background worker pre-reviews non-draft PRs on an interval, so a review is usually ready the moment you open one in the queue. You still decide whether and how to post; nothing is ever posted automatically.

Everything runs on your machine. This is a local, single-user tool. It is not deployed anywhere, so there is no AWS stack, no CI deploy path, and secrets live only in a local `.env` (gitignored). Your GitHub token and Fireworks key stay in the backend and never reach the browser.

## Setup

```bash
cp .env.example .env      # then fill in FIREWORKS_API_KEY (and GITHUB_TOKEN if not using gh CLI)
./run.sh
```

Open http://127.0.0.1:8765

## Auth

- **GitHub**: leave `GITHUB_TOKEN` blank to use your local `gh auth token`, or set a token. Reviews are posted as whoever the token belongs to, so use the token for the account you want to appear as the reviewer.

  A **fine-grained personal access token** is recommended (least privilege). Set the resource owner to `Sea-Haven-Industries` and grant only these repository permissions:

  | Permission | Level | Why |
  |---|---|---|
  | Pull requests | Read and write | read PR data and submit the review |
  | Contents | Read-only | fetch the PR diff |
  | Metadata | Read-only | mandatory (auto-added) |

  Give it access to all repositories you review (the search silently skips any it can't see). Fine-grained tokens are single-owner, so this token only covers the `Sea-Haven-Industries` org, which is all this tool searches; an org owner may need to approve the token before it works. A classic PAT with `repo` scope also works but is broader than needed.
- **Fireworks**: set `FIREWORKS_API_KEY`. Change `FIREWORKS_MODEL` in `.env` to swap models.

## How it works

1. **Background worker** polls your filter (`PR_SEARCH_FILTER`) every `POLL_INTERVAL` seconds and pre-reviews any new or changed non-draft PR, caching the result. The queue shows each PR's status: `reviewing`, `ready`, `error`, or `closed`. **Refresh now** forces an immediate poll.
2. **Open a PR** — if its review is `ready`, it appears instantly. Otherwise you see its status, and you can **Run review now** on demand.
3. **Request revision** re-runs the review with your notes folded in as a trusted instruction, separate from the untrusted diff.
4. **Post review to GitHub** submits it as a PR review. You confirm the event type (COMMENT / APPROVE / REQUEST_CHANGES) and can edit the body first.

### Auto-review worker

- Reviews are cached in a local SQLite file (`CACHE_DB`, default `pr_cache.db` in the repo root, gitignored) so they survive restarts and aren't recomputed for unchanged PRs.
- Change detection is two-level: a PR is skipped if its `updated_at` hasn't moved since the last review, and even when it has, the diff's SHA-256 is compared so a comment-only bump doesn't burn tokens.
- Drafts are skipped. Failed reviews are retried on later cycles up to `MAX_REVIEW_ATTEMPTS`, then left until the PR changes. Rate-limit (HTTP 429) responses back off and retry.
- `WORKER_CONCURRENCY` controls how many PRs are reviewed in parallel per cycle (default 2).

## The @mention rule

Any PR whose author login is in `MENTION_AUTHORS` (default `openswe`) gets an `@author` mention prepended to the review summary. Add more logins comma-separated.

## Notes

- The diff is treated as untrusted input; the model is instructed to ignore any embedded instructions.
- Cached reviews persist in a local SQLite file. This is a single-user local tool, not a shared service.
- Large diffs are truncated at `MAX_DIFF_BYTES` to control token cost.

## Configuration

Set in `.env` (see `.env.example`). Beyond the GitHub/Fireworks keys:

| Var | Default | Purpose |
|---|---|---|
| `POLL_INTERVAL` | `300` | seconds between background poll cycles |
| `WORKER_CONCURRENCY` | `2` | PRs reviewed in parallel per cycle |
| `MAX_REVIEW_ATTEMPTS` | `3` | error retries before giving up until the PR changes |
| `MAX_PRS` | `100` | cap on PRs pulled per cycle (GitHub search page max) |
| `CACHE_DB` | `pr_cache.db` | SQLite cache path (absolute, repo root by default) |

## Layout

```
app/
  config.py          settings from .env
  github_client.py   search PRs, fetch diffs, post reviews
  reviewer.py        Fireworks call + skill format + markdown rendering
  store.py           SQLite cache of pre-computed reviews
  worker.py          background poll + auto-review (run_cycle)
  main.py            FastAPI endpoints (incl. /api/reviews, /api/refresh)
static/
  index.html         the dashboard
```