pragent/pilot/README.md

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. opencode_review.py checks out the PR head in a sanitized temporary directory and runs the review agent. 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	Review orchestration implementation
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	Hostile-checkout containment and agent execution
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:

   {"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 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
LANGFUSE_HOST + keys	unset	Enables telemetry; unset is a no-op

Tests

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.