Metadata-Version: 2.4
Name: pebra
Version: 0.1.0
Summary: Pre-Edit Benefit-Risk Assessment for coding agents — a deterministic, hexagonal decision controller.
Author: PEBRA contributors
License-Expression: Apache-2.0 AND MIT
Project-URL: Homepage, https://github.com/Rajioba1/pebra
Project-URL: Repository, https://github.com/Rajioba1/pebra
Project-URL: Issues, https://github.com/Rajioba1/pebra/issues
Project-URL: Releases, https://github.com/Rajioba1/pebra/releases
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: pebra/dashboard/static/vendor/uplot.LICENSE.txt
Requires-Dist: numpy
Requires-Dist: scikit-learn>=1.2
Requires-Dist: cryptography
Requires-Dist: mapie
Requires-Dist: bandit
Requires-Dist: pyyaml
Requires-Dist: fastapi
Requires-Dist: starlette
Requires-Dist: uvicorn
Requires-Dist: jinja2
Requires-Dist: mcp<2,>=1.0
Requires-Dist: textual<9,>=8.2
Provides-Extra: bench
Requires-Dist: pandas; extra == "bench"
Requires-Dist: scipy; extra == "bench"
Requires-Dist: matplotlib; extra == "bench"
Requires-Dist: seaborn; extra == "bench"
Provides-Extra: bench-szz
Requires-Dist: pydriller; extra == "bench-szz"
Provides-Extra: bench-agent
Requires-Dist: swebench; extra == "bench-agent"
Provides-Extra: bench-external
Requires-Dist: datasets; extra == "bench-external"
Provides-Extra: ui-e2e
Requires-Dist: playwright; extra == "ui-e2e"
Requires-Dist: pytest-playwright; extra == "ui-e2e"
Provides-Extra: agent-ab
Requires-Dist: anthropic>=0.30; extra == "agent-ab"
Dynamic: license-file

# PEBRA

PEBRA is a **Pre-Edit Benefit-Risk Assessment** controller for coding agents.

It evaluates a proposed code edit before the agent applies it, returns a deterministic decision and
math packet, verifies the actual post-edit diff against the approved envelope, records outcomes, and
uses measured calibration data to promote learned facts for future assessments.

## Current Capabilities

- Pre-edit `assess` with expected loss, expected utility, RAU, edit confidence, and ordered gates.
- Post-edit `verify` against the approved safe scope and required checks.
- Candidate-bound pre-edit enforcement: an impactful host edit must produce the same normalized file
  contents as the patch that was assessed; same repository/HEAD/path alone is not sufficient.
- Outcome recording, shadow learning, promotion, scorecards, and learned-fact reapplication.
- Read-only local Risk Observatory dashboard for assessment, calibration, learning, and graph state.
- Explicit graph-engine setup and diagnostics through `pebra setup-graph` and `pebra doctor`.
- CodeGraph-backed evidence:
  - per-symbol fan-in;
  - DELETE file fan-in roll-up;
  - MODIFY graph-wide blast over callers/references/implementers/subclasses;
  - contract-surface metadata for interface/base-class edits;
  - containing class/namespace/module hierarchy roll-up;
  - file metadata / parse-error confidence penalties;
  - bounded revised-candidate refinement: cheap deterministic ranking first, then one materialized
    before/after graph by default. Structural continuity adjusts only the exact owner-scoped risk
    event; RAU remains authoritative. Set `PEBRA_GRAPH_REFINEMENT=0` to disable this path.
- Benchmark harnesses for math-oracle validation and deterministic learning-loop wiring proof.
- True CLI-boundary e2e lanes, including a gated external C# repo lane.

## Install For Development

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .
```

The graph engine is explicit, not a pip dependency:

```powershell
pebra setup-graph --fix
pebra doctor
```

`assess` never silently installs external binaries.

The **benefit signal** (multi-language complexity + maintainability index) is likewise an explicit
external binary — [`rust-code-analysis`](https://github.com/mozilla/rust-code-analysis) (MPL-2.0),
invoked as a subprocess. Build it from git (crates.io's release does not compile against current
tree-sitter):

```powershell
cargo install --git https://github.com/mozilla/rust-code-analysis `
  --rev 37e5d83c056c8cbf827223d5814a93c5218df1a9 rust-code-analysis-cli
```

Point PEBRA at it via `PEBRA_RCA_BIN` or ensure it is on `PATH`. PEBRA accepts runtime version
`0.0.25` when Cargo install metadata identifies the pinned source revision. For a copied or packaged
binary without Cargo metadata, set `PEBRA_RCA_SHA256` to its expected lowercase SHA-256. Live experiment
metadata records the executable SHA-256 and refuses to resume a run with a different fingerprint.
Cargo metadata is install provenance, not tamper-proof byte attestation. For copied binaries, shared
machines, or any environment where local binary replacement is in scope, set `PEBRA_RCA_SHA256`; an
explicit hash is authoritative and a mismatch disables RCA benefit evidence even when Cargo metadata
matches.
When absent or version-mismatched, benefit evidence fails
safe to *projected* (no maintainability credit) — it never blocks an assessment and never affects risk.
Supported languages: Python, JavaScript/JSX, TypeScript/TSX, Java, Rust, C/C++.

## Basic Workflow

```text
assess proposed edit -> agent decides -> apply edit -> verify actual diff ->
finalize trusted outcome -> future assess uses promoted learned snapshot
```

Example command surface:

```powershell
pebra assess request.json --json
pebra verify --assessment-id <assessment_id> --json
pebra record-outcome --assessment-id <assessment_id> --status completed --detail '{"actual_success": true}'
pebra learn --assessment-id <assessment_id>
pebra promote --repo-root <repo_root>
# Preferred host path: one idempotent record + measure + gated-promotion operation.
pebra finalize-outcome --trusted-outcome-file outcome.json --repo-root <repo_root> --json
pebra scorecard --repo-root <repo_root>
pebra dashboard --port 4500 --open
pebra capabilities --repo-root <repo_root>
```

`outcome.json` contains `assessment_id`, terminal `status`, and an optional `detail` object. The
`finalize-outcome` command is host-only: MCP outcome reports are retained for lifecycle telemetry but
their self-reported learning labels are censored. The legacy three-command sequence remains available
for diagnosis and manual operation.

## Agent Enforcement

Install the repository protocol for either host. Add `--with-hook` when you want pre-edit interception,
not only instructions:

```powershell
pebra agent-init --target claude --repo-root . --with-hook
pebra agent-init --target codex --repo-root . --with-hook
pebra capabilities --repo-root .
```

The guarantees are deliberately different:

| Host surface | Reported mode | Guarantee |
|---|---|---|
| Claude Code PreToolUse hook | `configured_enforcing` | Exact enabled hook config, matching gate capability handshake, graph, and Git HEAD were observed. Candidate-bound checks deny or ask before supported structured edits; this does not prove the host invoked every event. |
| Codex repo-local hook | `best_effort` | Candidate-bound gate logic is installed, but repo-local hook loading remains host-dependent. |
| MCP tools | `advisory_only` | Assess/verify tools are available, but MCP alone does not intercept another host's writes. |

If graph or Git HEAD evidence is unavailable, an installed gate remains fail-open by policy and
`capabilities` reports `degraded_fail_open`. The Claude hook also emits the degradation warning as a
non-blocking system message. Repository-local and user-level `disableAllHooks` settings also degrade
the reported posture. This is observable configuration, not proof that a host or managed policy invoked
every event.

`trusted_actor_required` is a protocol boundary, not OS-level identity authentication. PEBRA does
not expose risk acceptance through MCP, and interactive acceptance requires a terminal. A process
with arbitrary shell access under the same OS account can still invoke local trusted-host surfaces
or simulate a terminal. Use a separately privileged host or operator account when resistance to an
adversarial agent is required.

For a candidate that changes multiple files, enforcement requires one complete `apply_patch` event containing
the complete assessed candidate. Structured single-file edits must be assessed as separate single-file
candidates; one file cannot reuse approval for part of a multi-file candidate.

The dashboard is read-only. On a loopback bind (`localhost`, `127.0.0.1`, `::1`) the default is
token-free for local convenience; `--auth token` forces a bearer token when you want the old locked
path. Any non-loopback bind requires a token.

```powershell
# normal local browser UX
pebra dashboard --port 4500 --open

# venv-safe form if the `pebra` console script is not on PATH yet
python -m pebra dashboard --port 4500 --open

# force bearer auth even on loopback
pebra dashboard --port 4500 --auth token

# expose beyond loopback only with a token
pebra dashboard --host 0.0.0.0 --port 4500 --auth token
```

It exposes five browser views: overview, score history, calibration, learned facts, and CodeGraph
hotspots. Graph views are fail-soft when no trusted graph index is bound to the launched repo, and
graph routes are repo-scoped to avoid replaying one repo's graph under another repo id.

## Validation

```powershell
.\.venv\Scripts\nox.exe -s tests lint e2e-fast
```

Dashboard/e2e lanes:

```powershell
.\.venv\Scripts\python.exe -m pytest tests/integration/test_dashboard_server.py tests/integration/test_dashboard_cli.py -q
.\.venv\Scripts\python.exe -m pytest e2e/features/dashboard/test_dashboard_metrics_visual.py -q
.\.venv\Scripts\nox.exe -s e2e-learning
.\.venv\Scripts\nox.exe -s e2e-ui
```

External real-repo graph lane:

```powershell
$env:E2E_EXTERNAL='1'
$env:E2E_TEMPLATE_BLUEPRINT_REPO='C:\Users\RajLord_new\Desktop\avalonia_template'
.\.venv\Scripts\nox.exe -s e2e-external
```

Benchmark lanes:

```powershell
.\.venv\Scripts\nox.exe -s bench-math
.\.venv\Scripts\nox.exe -s bench-flow
```

## More Docs

- [Contributing and development setup](CONTRIBUTING.md)
- [True e2e suite](e2e/README.md)
- [Benchmarks](benchmarks/README.md)
- [Learning-loop wiring benchmark](benchmarks/flow/wiring/README.md)
