Metadata-Version: 2.4
Name: evidentloop
Version: 0.1.0a3
Summary: Traceable code review artifacts for local Git diffs
License-Expression: MIT
Project-URL: Homepage, https://github.com/evidentloop/evidentloop
Project-URL: Repository, https://github.com/evidentloop/evidentloop
Project-URL: Issues, https://github.com/evidentloop/evidentloop/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2>=3.1
Requires-Dist: jsonschema>=4.23
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Dynamic: license-file

<h1 align="center">EvidentLoop</h1>

<p align="center"><strong>Turn local Git diffs into evidence-backed, traceable audit reports.</strong></p>

<p align="center">
  <a href="https://github.com/evidentloop/evidentloop/blob/main/README.md">English</a> ·
  <a href="https://github.com/evidentloop/evidentloop/blob/main/README.zh-CN.md">简体中文</a>
</p>

<p align="center">
  <img alt="Status: Alpha" src="https://img.shields.io/badge/status-alpha-F59E0B">
  <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-3776AB">
  <img alt="Audit schema 0.5" src="https://img.shields.io/badge/audit%20schema-0.5-0F766E">
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/evidentloop/evidentloop/main/docs/assets/evidentloop-hero-sketch.jpg" width="620" alt="A local Git diff flowing through evidence checks into a report and human decision">
</p>

Use EvidentLoop to inspect a local Git diff, trace each finding to the changed lines, record a human decision, and explicitly verify a later fix.

Your coding agent makes the judgment. EvidentLoop validates the result and saves the evidence in a self-contained HTML report with its JSON record. The result stays traceable without being presented as proof that the code is safe.

Prefer to see the report first? [Jump to the real audit evidence](#real-audit-evidence).

## Quick start

Requirements: Git, Python 3.10 or newer, uv, Node.js/npx for Skill installation, and a coding agent with Skill support.

```bash
# Try the bundled offline demo
uvx evidentloop demo

# Install the CLI and Skill
uv tool install evidentloop
npx skills@latest add evidentloop/evidentloop --skill evidentloop -g
evidentloop doctor
```

`pipx install evidentloop` is the CLI fallback.

Inside the Git repository to inspect, ask your coding agent:

```text
Use EvidentLoop to audit my staged changes and generate the HTML report.
```

<a name="real-audit-evidence"></a>

## Real audit evidence

<picture>
  <source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/evidentloop/evidentloop/main/docs/assets/evidentloop-report-loop.png">
  <img alt="A representative EvidentLoop report showing a finding, complete diff, browser-local decision, and comment" src="https://raw.githubusercontent.com/evidentloop/evidentloop/main/docs/assets/evidentloop-report-loop.gif">
</picture>

<p align="center"><em>Representative schema 0.5 report · decision and comment · Alpha UI in Simplified Chinese</em></p>

The animation uses a representative schema `0.5` report generated by the current renderer to show a finding, its complete diff, and a local decision with a comment. The separate [self-audit report](https://evidentloop.github.io/evidentloop/examples/evidentloop-dogfood-v05/audit.html) covers 43/43 files and ends `complete / pass_candidate` with 0 findings. It proves report generation, validation, and rendering for that range. The public evidence does not yet include a real two-diff fix-verification run.

## How it works

![EvidentLoop lifecycle from a local diff to a validated report, human decision, and explicit next-diff fix verification](https://raw.githubusercontent.com/evidentloop/evidentloop/main/docs/assets/evidentloop-lifecycle.svg)

- **Review a complete diff.** Your coding agent returns its judgment; EvidentLoop validates the result and renders one self-contained report.
- **Revise the report, not the code.** Feedback on the same diff updates only the existing report and JSON record without asking the model to review again.
- **Verify a later diff explicitly.** A source report, chosen finding, and claim start a new full-diff review. Old reports remain unchanged and EvidentLoop does not guess finding matches.

## Output

| File | Purpose |
|---|---|
| `audit.json` | Validated audit record linking Git changes, findings, decisions, and report lineage. |
| `audit.html` | Self-contained report showing the result, relevant diff, and browser-local decisions. |
| `audit-feedback.jsonl` | Optional machine-readable decision export for a coding agent. |

Pending feedback stays in each viewer's browser until copied or downloaded. The HTML can be shared after redaction, but it is not a multi-user review service.

## Alpha scope

| Supported | Not supported |
|---|---|
| Local Git staged, unstaged, ref, and range diffs | Folder diffs, file-only review, or remote PR URLs |
| Added, modified, deleted, renamed, and binary-file metadata | Automatic fixes or command execution |
| Schema `0.5`, exact changed-line evidence, and same-diff report revision | Automatic model re-review from feedback |
| Explicit next-diff verification from a source report, finding, and claim | Automatic finding matching or inferred repair from disappearance |
| Complete, partial, failed, and inconclusive states | Silent stale-feedback merging or cross-workspace report search |

## Integration and development

Use EvidentLoop through the Skill as a standalone product; no other workflow is required. Integrators can follow the `prepare -> external review -> finalize` path in [AI host integration](https://github.com/evidentloop/evidentloop/blob/main/docs/ai-host-integration.md), use the public API in `evidentloop.api`, and rely on `diff_version` plus `report_version` for artifact identity.

For local development:

```bash
python -m pip install -e '.[dev]'
python -m pytest -q
python -m ruff check .
python -m build
```

References: [Pages](https://evidentloop.github.io/evidentloop/) · [V0 scope](https://github.com/evidentloop/evidentloop/blob/main/docs/v0-scope.md) · [Data model](https://github.com/evidentloop/evidentloop/blob/main/docs/data-model.md) · [AI host integration](https://github.com/evidentloop/evidentloop/blob/main/docs/ai-host-integration.md)

Alpha feedback and bug reports are welcome in [GitHub Issues](https://github.com/evidentloop/evidentloop/issues).

## License

Licensed under the [MIT License](https://github.com/evidentloop/evidentloop/blob/main/LICENSE).
