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. 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:

   {"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
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

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.