Claude
91 lines
4.4 KiB
Markdown
91 lines
4.4 KiB
Markdown
# pragent pilot
|
|
|
|
The pilot is a central, stdlib-only Gitea webhook service. It reviews opted-in
|
|
pull requests with an on-network model, posts inline findings, and emits review
|
|
telemetry to Langfuse. The service is fail-open: a review failure is reported
|
|
as a PR comment and does not block CI.
|
|
|
|
## Runtime flow
|
|
|
|
1. Gitea sends a signed `pull_request` webhook.
|
|
2. `webhook_server.py` validates the request, checks the base branch's
|
|
`.pr-review.json` for `"enabled": true`, and claims `(repo, PR, SHA)`.
|
|
3. `ai_review.review_pr()` fetches the diff, trusted config, and prior reviews.
|
|
4. `review/opencode.py` coordinates the isolated review. Workspace preparation,
|
|
lens configuration, and finding synthesis live in focused sibling modules.
|
|
The legacy Ollama-compatible path is still available through
|
|
`PRAGENT_ENGINE`.
|
|
5. The review output is parsed and normalized, valid post-change line anchors
|
|
are separated from summary-only findings, and Gitea receives the result.
|
|
6. `langfuse_trace.py` records usage, cost basis, findings, and evaluation
|
|
scores when Langfuse credentials are configured.
|
|
|
|
## Module map
|
|
|
|
| Module | Responsibility |
|
|
|---|---|
|
|
| `entrypoints/webhook.py` | HTTP ingress, signature verification, opt-in gate, concurrency |
|
|
| `review/config.py` | Trusted base-branch opt-in policy; transport injected for tests |
|
|
| `entrypoints/gitea.py` | HTTP transport adapter and repository-scoped client |
|
|
| `review/ai_review.py` | Small public review facade |
|
|
| `review/pipeline.py` | Review orchestration, runtime wiring, and compatibility symbols |
|
|
| `review/analysis.py` | Prompt construction, token attribution, and cost helpers |
|
|
| `review/output.py` | Finding parsing, anchor validation, and Markdown rendering |
|
|
| `review/configuration.py` | Repository config parsing, filtering, and prior-review context |
|
|
| `review/adapters.py` | Gitea/model transport and review publishing |
|
|
| `ai_review.py` | Compatibility shim for existing imports and CI execution |
|
|
| `review/model.py` | Anthropic-compatible model adapter and response text extraction |
|
|
| `review/opencode.py` | Compatibility seam and review orchestration |
|
|
| `review/opencode_workspace.py` | Archive extraction, sanitization, brief, and factory setup |
|
|
| `review/opencode_lens_config.py` | Reviewer lens configuration and selection |
|
|
| `review/opencode_synthesis.py` | Lens finding normalization, deduplication, and summary synthesis |
|
|
| `review/diff.py` | Diff compression and prior-review extraction |
|
|
| `feedback/*.py` | Feedback persistence, harvesting, analysis, and Langfuse scores |
|
|
| `observability/langfuse.py` | Fail-open Langfuse ingestion and cost metadata |
|
|
| `observability/cost.py` | Provider price catalog and equivalent-cost calculations |
|
|
| `evaluation/*.py` | Dataset bootstrap, evaluators, and behavioral scoring |
|
|
|
|
The top-level `.py` files are intentionally thin compatibility shims. They keep
|
|
existing workflow commands and imports stable while the implementations live in
|
|
the focused packages above. New code belongs in those packages, not in a shim.
|
|
|
|
## Onboard a repository
|
|
|
|
1. Add `pragent-bot` as a Write collaborator.
|
|
2. Commit this file to the default branch:
|
|
|
|
```json
|
|
{"enabled": true}
|
|
```
|
|
|
|
3. Open or update a pull request.
|
|
|
|
No per-repository workflow, secret, or label is required for the central
|
|
webhook path. See [`README-webhook.md`](README-webhook.md) for deployment,
|
|
security, and webhook registration details.
|
|
|
|
## Configuration
|
|
|
|
| Variable | Default | Purpose |
|
|
|---|---:|---|
|
|
| `GITEA_API` | in-cluster URL | Gitea API base URL |
|
|
| `PRAGENT_BOT_TOKEN` | — | Bot credential |
|
|
| `OLLAMA_URL` / `OLLAMA_MODEL` | headroom / `glm-5.2:cloud` | Legacy model path |
|
|
| `PRAGENT_ENGINE` | `opencode` | `opencode` or legacy model path |
|
|
| `DIFF_MAX_CHARS` | `150000` | Diff input cap |
|
|
| `PRAGENT_MAX_CONCURRENT_REVIEWS` | `2` | Process concurrency bound |
|
|
| `PRAGENT_MAX_REVIEW_STEPS` | `20` | Maximum completed model iterations per review |
|
|
| `PRAGENT_MAX_REVIEW_TOKENS` | `120000` | Maximum cumulative tokens per review |
|
|
| `PRAGENT_MAX_REVIEW_OUTPUT_TOKENS` | `20000` | Maximum generated tokens per review |
|
|
| `LANGFUSE_HOST` + keys | unset | Enables telemetry; unset is a no-op |
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
python3 -m pytest tests -q
|
|
```
|
|
|
|
Tests are grouped under `tests/pilot/*_tests/`, matching the source domains.
|
|
They use mocked transports and local fixtures and do not require Gitea,
|
|
Langfuse, a model endpoint, or network access.
|