Metadata-Version: 2.4
Name: pathproof-ai
Version: 0.2.0rc1
Summary: Local-first assurance and observability for AI agents
Author: Bassam Alkarishy
License: 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

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


> **Release status:** `0.2.0rc1` is a public release candidate for testing.
> It is not yet a stable production release.


Current MVP version: **0.1.2**

PathProof is a local-first Python library for monitoring, evaluating, and enforcing policies on AI-agent runs.

## Quick start

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

```python
from pathproof import AgentMonitor, Policy

policy = Policy(
    allowed_tools={"verify_customer", "search_orders", "create_ticket"},
    max_tool_calls=10,
)

monitor = AgentMonitor(
    agent_name="support_agent",
    version="0.1.0",
    policy=policy,
)

with monitor.run(task="Resolve customer complaint") as run:
    run.tool_call(
        name="verify_customer",
        arguments={"customer_id": "C-102"},
        function=lambda customer_id: {"verified": True},
    )
    run.record_output({"status": "resolved"})

report = run.evaluate()
print(report.to_text())
```

## Included in v0.1

- Run and event recording
- Tool-call monitoring
- Policy checks
- Repeated-call detection
- Missing-prerequisite detection
- Human-approval gates
- Trust score with explanations
- Text and JSON reports
- In-memory, JSON, and SQLite storage
- Basic run comparison

## Easier tool wrapping

```python
with monitor.run(task="Demo") as run:
    @run.tool()
    def search(query: str):
        return {"results": [query]}

    result = search(query="agent assurance")
    run.record_output(result)
```

Runtime limits are enforced before an extra step or tool call in warning, approval, and blocking modes. Tool failures can be explicitly marked as handled with `run.handle_tool_failure(...)`.


## Evidence bundles (v0.1.3)

```python
bundle = run.evidence()
assert bundle.verify()
bundle.to_json()
```

The bundle fingerprints the complete run and evaluation. Any later payload change causes verification to fail. This is tamper evidence, not yet a digital signature or legal certificate.

## Regression cases (v0.1.3)

```python
case = run.regression_case(name="Prevent repeated search")
case.save("regressions/repeated-search.json")

result = check_regression(case, candidate_report)
assert result.passed
```

## Deeper comparisons

`compare_runs()` now detects tool and step sequence changes, new or removed tools, new failure classes, new policy violations, and trust-score changes.


## Causal evidence graph

PathProof now links steps, tool requests, tool results, and outputs. It can distinguish a successful-looking output from an unsafe execution path.


## Development installation

```bash
python -m pip install -e ".[dev]"
python -m pytest
```

## Privacy

PathProof is local-first. It does not require a cloud service and does not
transmit recorded data by default. Review stored inputs, outputs, and tool
arguments before using it with sensitive information.

## Important limitation

PathProof provides technical monitoring, evidence, and configurable policy
enforcement. It does not by itself certify that an AI decision is legally,
ethically, or factually correct.
