Metadata-Version: 2.4
Name: agent-blackbox-jep
Version: 0.3.0a4
Summary: Alpha recorder for signed JEP events, evidence digests and incident review
Author-email: HJS Spec <signal@humanjudgment.org>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: PyNaCl<2,>=1.6.2
Requires-Dist: cryptography>=41.0.0
Requires-Dist: rfc8785<1,>=0.1.4
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

# Agent Blackbox

Alpha recorder for agent workflows. Wrap a function, store signed event records
with evidence digests and declared links, then inspect an incident or verify
local record integrity.

## Core Features

| Feature | Description |
|---|---|
| Trace decorator | Wrap agent functions and record runtime events |
| JEP-style event | Emits JEP Core 0.7-style J/D/T/V event objects with stable Event Identity |
| Declared links | Records parent relationships for incident review |
| Evidence digests | Records input/output/error digests |
| Local blackbox log | Stores JSONL event records for later review |
| Incident review | Reconstructs declared chain fragments around an incident |
| Integrity check | Verifies event hashes and Ed25519 signatures generated by this library |

## Installation

Install the published distribution:

```bash
pip install --pre agent-blackbox-jep
```

The distribution is `agent-blackbox-jep`, the Python import is `agent_blackbox`,
and the CLI commands are `agent-blackbox` and `blame-finder`.

For local development:

```bash
pip install -e .
```

---

## Basic Usage

```python
from agent_blackbox import AgentBlackbox

blackbox = AgentBlackbox(storage="./blackbox_logs")

@blackbox.trace(agent_name="CoderAgent")
def write_code(requirement: str) -> str:
    return "print('hello world')"

result = write_code("write a hello world")

# Review the latest event
event_hash = list(blackbox.events.keys())[-1]
report = blackbox.review_incident(event_hash)

print(report["candidate_failure_node"])
print(report["chain"])
```

---

## Incident Review Output

Example:

```json
{
  "incident": "sha256:...",
  "candidate_failure_node": "CoderAgent",
  "diagnostic_summary": "The selected event has status failed. Review declared parents and evidence references.",
  "review_score": 0.72,
  "chain": [
    {
      "event_hash": "sha256:...",
      "agent": "PlannerAgent",
      "status": "success"
    },
    {
      "event_hash": "sha256:...",
      "agent": "CoderAgent",
      "status": "failed"
    }
  ],
  "boundary": {
    "not_legal_liability": true,
    "not_factual_causality_proof": true,
    "not_compliance_determination": true
  }
}
```

---

## CLI

Review an incident:

```bash
agent-blackbox review sha256:...
```

Show a chain tree:

```bash
agent-blackbox tree sha256:...
```

Verify an event:

```bash
agent-blackbox verify sha256:...
```

---

## Boundary Statement

New events use [Core 0.7](https://github.com/hjs-spec/jep-core#current-contract)
with Event Identity `(who,id)`. Event Hash identifies the exact signed artifact
and is the lookup key in the local store. The trace decorator records judgments;
D/T/V events require explicit creation with their required fields.

Verification checks event integrity under the recorder's local key and the recorded
links. It does not establish factual causality, legal responsibility or log
completeness. See the [current alpha releases](https://github.com/hjs-spec/Agent-Blackbox/releases)
for the packaged implementation.

## License

MIT

## Runtime and verification notes

See [HARDENING.md](HARDENING.md) for event extensions, key handling and import compatibility.
