vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

swarm-controller: read a repo's review rules from its default branch

Browse source 
`GET /api/review-classifier/rules?repo=owner/name` reads
`.hyperhive/review-classifier.yml` or `.json` from the repo's default
branch with the controller's forge token, on every request, and answers
the classifications in the try-out POST's shape, plus the file, the
branch and the commit it was read at. The swarm UI's try-out page loads
them into its editor (#5134).

The file is one `classifications` list of the try-out's `Classification`.
A missing file, both files, a parse error, any unknown key, an empty list
or more than ten entries is a problem+json error, never a pass. The
checks the POST makes on its classifications move into one function both
paths call.

The doc names the file and its schema, replacing the placeholders, and
documents the route.

Part of #5096.
This commit is contained in:
atlas 2026-10-12 08:12:38 +02:00 • committed by mara
commit 16c7c249ef
6 changed files with 624 additions and 55 deletions
Download patch file Download diff file Expand all files Collapse all files

50
docs/swarm/review-classifier.md
View file

@ -18,23 +18,31 @@ that reviewer.
## Repo configuration
A repo opts in with a config file in a `.hyperhive/` directory at its root,
in YAML or JSON. The classifier always reads it from the repo's **default
branch**, never from the PR, so a PR can't edit the rules it's judged by.
A repo opts in with a rules file at its root, in YAML as
`.hyperhive/review-classifier.yml` or in JSON as
`.hyperhive/review-classifier.json`. It holds one of the two; with both, the
rules don't load. `swarm-controller` always reads the file from the repo's
**default branch**, never from the PR, so a PR can't edit the rules it's
judged by. It reads it with its own forge token on every load, with no cache,
so a rule merged to the default branch counts from the next load on.
Each classification has:
The file holds one key, `classifications`: a list of one to ten entries, each
with exactly these four keys:
- a **name**, short and unique in the repo, shown in the result table
- a **description**: the yes/no question the model answers about the PR
- a **certainty threshold** from 0 to 100
- a **polarity**: _positive_ means a match is the wanted outcome, and
_negative_ means a match is a violation
- `name`: short and unique in the repo, shown in the result table
- `description`: the yes/no question the model answers about the PR
- `threshold`: the certainty, 0 to 100, a verdict needs to count
- `polarity`: `positive` means a match is the wanted outcome, and
`negative` means a match is a violation
An illustrative example. The file name and every field name in it are
placeholders, not a fixed schema:
Any other key, at the top or in an entry, is an error: a misspelt key fails
the load instead of vanishing. An empty list, more than ten entries, an empty
name or description, and two entries with one name are errors too. Nothing
falls back to a pass: a repo whose file doesn't load has no rules.
An example:
```yaml
# illustrative only: file name and field names aren't fixed
classifications:
- name: datetime
description: All datetimes carry time zone information.
@ -241,6 +249,24 @@ and sends it to the classifier as one queue request on
stays open. The controller keeps the result in memory for an hour; there is no
run store.
`GET /api/review-classifier/rules?repo=owner/name` returns the repo's own
rules, for the page to load into its editor; a run posts them like typed
ones. The route answers:
- **200** with `path` (the file read), `branch` (the default branch),
`commit` (the commit the route read the file at) and `classifications`, in
the file's order and in the POST's shape
- **400** for a `repo` that's missing or not `owner/name`
- **404** for a repo the forge doesn't know, a repo with no commit, or a
default branch with neither file
- **422** for both files on the default branch, or a file that doesn't parse
or breaks a rule from [Repo configuration](#repo-configuration); the
`detail` names the file and what's wrong
- **503** when this host has no forge token yet, or the forge failed or
didn't answer within two minutes
Every error is problem+json with the reason in `detail`.
When it's ready, **open a PR** has the service account push a branch that
adds the classification to the repo's config, with you, the swarm UI user,
as commit author. The page then links you to the forge's new-PR page for