Metadata-Version: 2.4
Name: agent-evidence-observer
Version: 0.1.0
Summary: Record brokered agent writes and check selected native reports offline
Author: Sankalp Gilda
License-Expression: Apache-2.0
Project-URL: Documentation, https://github.com/probityai/probity/blob/main/packages/observer/docs/INSTALLATION.md
Project-URL: Source, https://github.com/probityai/probity/tree/main/packages/observer
Project-URL: Issues, https://github.com/probityai/probity/issues
Project-URL: Agent guide, https://github.com/probityai/probity/blob/main/packages/observer/llms.txt
Keywords: ai-agents,observability,audit-logs,provenance,attestation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Logging
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography<51,>=46
Requires-Dist: rfc8785==0.1.4
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Requires-Dist: hypothesis<7,>=6; extra == "test"
Requires-Dist: jsonschema<5,>=4; extra == "test"
Provides-Extra: inspect
Requires-Dist: inspect-ai==0.3.273; extra == "inspect"
Provides-Extra: witness
Requires-Dist: jcs-admit==0.1.0; extra == "witness"
Provides-Extra: cover
Requires-Dist: coverage<8,>=7.10; extra == "cover"
Provides-Extra: done
Requires-Dist: jcs-admit==0.1.0; extra == "done"
Requires-Dist: probity-verify>=0.2.0; extra == "done"
Dynamic: license-file

# Agent Evidence Observer (prototype)

[![PyPI](https://img.shields.io/pypi/v/agent-evidence-observer.svg)](https://pypi.org/project/agent-evidence-observer/)
[![Downloads (PePy)](https://static.pepy.tech/badge/agent-evidence-observer)](https://pepy.tech/projects/agent-evidence-observer)

Record brokered agent writes and check selected native framework reports offline.

Use it in agent harnesses and evaluation pipelines that need replayable action records or a consumer gate for retained reports.

Install the root package: `pip install agent-evidence-observer==0.1.0`.

## Quick start

Run the demo from the released package. You need Python 3.12 or later and [`uv`](https://docs.astral.sh/uv/); there is nothing to clone.

```sh
uvx agent-evidence-observer==0.1.0 demo ./sample-run
uvx agent-evidence-observer==0.1.0 verify ./sample-run
```

The two commands print:

```text
{"noDetectedGap": "true", "retryReplayed": "true", "status": "verified", "witnessScope": "PEER"}
{"noDetectedGap": "true", "status": "verified", "witnessScope": "PEER"}
```

`sample-run/` now holds the signed packet, the history, the public keys and the file tree. The demo
writes a file, retries it, and the retry returns the first effect. `noDetectedGap` means the broker's
file-tree snapshots found no change it did not make. It does not mean every agent effect was seen.
To run from a pinned source checkout instead, see [Run the source quick start](https://github.com/probityai/probity/blob/main/packages/observer/docs/INSTALLATION.md#run-the-source-quick-start).

## Status

The root distribution is version 0.1.0. Every record says `witnessScope: PEER`: the witness key runs on the same
host under the same operator, so the records show what this broker saw, not what an independent
observer saw. Linux runs can launch a fixed probe, or a Python script given to `run-workload`, under
bubblewrap with only the broker's socket exposed. `launch-agent` runs an unmodified agent in docker or
apptainer and records, from outside it, every program it ran and every file it changed. It does not use
bubblewrap, which cannot start on hosts with `apparmor_restrict_unprivileged_userns=1` such as Ubuntu 24.04.
`agent-evidence-witness` runs a separately operated witness: a record it co-signs verifies as `EXTERNAL`
when the reader pins a different operator for the witness key. It needs the `witness` extra, which is not yet
in a released wheel.

## Documentation

Start with [worked examples](https://github.com/probityai/probity/blob/main/packages/observer/docs/README.md) to follow a practical question,
then open its technical reference for commands and exact evidence.

| page | read it for |
| --- | --- |
| [Start a project](https://github.com/new?template_name=evidence-starter&template_owner=probityai) | a template that records a write with this package and checks it with probity-verify, pinned and in CI |
| [Component tour](https://github.com/probityai/probity/blob/main/packages/observer/docs/OVERVIEW.md) | every part of the prototype in one paragraph each, with links: ticket service, replay, evaluation history, A2A, AAE, protected dispatch |
| <a name="run-the-demo"></a>[Running the demo](https://github.com/probityai/probity/blob/main/packages/observer/docs/RUNNING.md) | the full install with tests, and what each output field means |
| <a name="claim-and-trust-boundary"></a><a name="tests-and-remaining-gaps"></a><a name="linux-boundary-gate"></a><a name="consumer-admission"></a><a name="roadmap"></a>[Design, trust boundary and roadmap](https://github.com/probityai/probity/blob/main/packages/observer/docs/DESIGN.md) | what each mechanism checks and does not establish, the Linux boundary gate, recovery, consumer admission, and the roadmap |
| [Agent launcher](https://github.com/probityai/probity/blob/main/packages/observer/docs/AGENT-LAUNCHER.md) | run an unmodified agent with three outside sensors and check its claims with probity-verify |
| [Isolated producer](https://github.com/probityai/probity/blob/main/packages/observer/docs/ISOLATED-PRODUCER.md) | the acceptance criteria for running an unmodified agent behind the broker |
| [Brokered workload](https://github.com/probityai/probity/blob/main/packages/observer/docs/WORKLOAD.md) | run a Python script behind the write broker with `run-workload`, then check it offline with `verify-workload` |
| [Witness ledger](https://github.com/probityai/probity/blob/main/packages/observer/docs/WITNESS-LEDGER.md) | signed begin and terminal receipts, and how a reader checks them |
| [Separately operated witness](https://github.com/probityai/probity/blob/main/packages/observer/docs/WITNESS-SERVER.md) | run a witness on another host, co-sign records 2-of-2, and catch a witness that forks its log |
| [Installation and profile selection](https://github.com/probityai/probity/blob/main/packages/observer/docs/INSTALLATION.md) | choose the root wheel, a separate profile wheel or a selected source reader; runtime requirements and installed examples |
| [Release the root package](https://github.com/probityai/probity/blob/main/packages/observer/docs/RELEASING.md) | qualify a wheel and source distribution, then publish with a bound source tag |
| [Atomic native reader](https://github.com/probityai/probity/blob/main/packages/observer/docs/ATOMIC-NATIVE-READER.md) | install an offline reader for selected native delegation runs and their refusal controls |
| [Witnessed run selection](https://github.com/probityai/probity/blob/main/packages/observer/docs/WITNESSED-RUN-SELECTION.md) | check a selected run against consumer-retained opening and closing checkpoints |
| [Approved refund retries](https://github.com/probityai/probity/blob/main/packages/observer/docs/APS-REFUND-RETRIES.md) | run the APS approval and local SQLite example, then check retries and refusals with a separately installed reader |
| [Refund handoff conformance](https://github.com/probityai/probity/blob/main/packages/observer/docs/REFUND-HANDOFF-CONFORMANCE.md) | verify admission, recovery, handoff, effect and reconciliation bindings against 80 public vectors |

## License

Apache License 2.0; see [LICENSE](https://github.com/probityai/probity/blob/main/packages/observer/LICENSE).
