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
webhook_server.py	HTTP ingress, signature verification, opt-in gate, concurrency
review_config.py	Trusted base-branch opt-in policy; transport injected for tests
gitea_client.py	HTTP transport adapter and repository-scoped client
ai_review.py	Compatibility facade and review orchestration
model_client.py	Anthropic-compatible model adapter and response text extraction
opencode_review.py	Hostile-checkout containment and agent execution
diff_compress.py	Diff compression and prior-review extraction
feedback*.py	Feedback persistence, harvesting, analysis, and Langfuse scores
langfuse_trace.py	Fail-open Langfuse ingestion and cost metadata
cost_model.py	Provider price catalog and equivalent-cost calculations
eval_*.py	Dataset bootstrap, evaluators, and behavioral scoring

ai_review.py remains the stable import surface for existing workflow and webhook deployments. New code should put policy, adapters, and pure transforms in the focused modules above rather than adding unrelated functions there.

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 use mocked transports and local fixtures. They do not require Gitea, Langfuse, a model endpoint, or network access.