Metadata-Version: 2.4
Name: pathproof-ai
Version: 0.2.0rc2
Summary: Local-first assurance and observability for AI agents
Author: Bassam Alkarishy
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/BeboBebo007/pathproof-ai
Project-URL: Documentation, https://github.com/BeboBebo007/pathproof-ai#readme
Project-URL: Issues, https://github.com/BeboBebo007/pathproof-ai/issues
Keywords: ai-agents,observability,assurance,guardrails,evaluation
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# PathProof

[![PyPI version](https://img.shields.io/pypi/v/pathproof-ai.svg)](https://pypi.org/project/pathproof-ai/)
[![Python versions](https://img.shields.io/pypi/pyversions/pathproof-ai.svg)](https://pypi.org/project/pathproof-ai/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Tests](https://github.com/BeboBebo007/pathproof-ai/actions/workflows/tests.yml/badge.svg)](https://github.com/BeboBebo007/pathproof-ai/actions/workflows/tests.yml)

**Evidence-driven execution-path assurance for AI agents.**

> PathProof verifies the execution path of AI agents — not filesystem paths.

PathProof is a local-first Python library for monitoring agent runs, enforcing runtime policies,
detecting unsafe execution paths, and producing evidence that explains how an output was reached.

## Current status

- Current release candidate: `0.2.0rc2`
- Public release candidate; suitable for evaluation, prototyping, and controlled internal testing
- Not yet recommended as the sole control layer for production-critical or regulated systems

## Why PathProof

An AI agent may produce a plausible result while taking an unsafe path to get there. PathProof checks the operational path: tool calls, prerequisites, approvals, policy limits, recovery after failures, and the causal chain behind the final output.

## Core capabilities

- Run and event recording
- Tool-call monitoring
- Policy enforcement, call limits, prerequisites, and approval gates
- Failure classification and explainable trust scoring
- Text and JSON reports
- Memory, JSON, and SQLite storage
- Evidence fingerprints and evidence bundles
- Run comparison and regression checks
- Causal evidence graphs and unsafe-path detection

## Installation

```bash
pip install pathproof-ai
```

For this release candidate:

```bash
pip install pathproof-ai==0.2.0rc2
```

## Quick start

```python
from pathproof import AgentMonitor

monitor = AgentMonitor("support-agent")
run = monitor.run("Answer a customer request")
run.record_output({"answer": "Request completed"})
run.close()
report = run.evaluate()
print(report.status, report.trust_score)
```

Expected output:

```text
passed 100
```

## What PathProof proves

PathProof can provide technical evidence that declared runtime policies were checked, recorded steps followed a traceable sequence, observed tool calls and outputs were captured, known failure conditions were detected, and the final output followed a recorded causal path.

## What PathProof does not prove

PathProof does not by itself prove factual correctness, ethical correctness, legal compliance, absence of hidden bias, real-world safety, legal admissibility of evidence, or cryptographic authenticity unless an external signing layer is added.

PathProof should be used as one assurance layer within a broader governance and safety system.

## Local-first design

PathProof does not require an external service by default. Run data can remain on the user's machine or inside the organization's own environment.

## Testing

The test suite runs automatically on Python 3.10, 3.11, 3.12, and 3.13.

```bash
python -m pytest -q
```

## Project links

- Source: https://github.com/BeboBebo007/pathproof-ai
- Issues: https://github.com/BeboBebo007/pathproof-ai/issues
- PyPI: https://pypi.org/project/pathproof-ai/

## License

Apache License 2.0.
