Metadata-Version: 2.4
Name: agent-blackbox-jep
Version: 0.2.0a2
Summary: Experimental JEP/HJS/JAC runtime blackbox recorder for agent workflow 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

Runtime blackbox recorder for agent workflows using **JEP events**, **HJS evidence references**, and **JAC declared dependency chains**.

> Experimental implementation seed.
>
> Agent Blackbox supports incident review and chain reconstruction.
> It does **not** determine legal liability, factual truth, regulatory compliance, or moral responsibility.

---

## What This Is

Agent Blackbox records structured execution traces for agent workflows.

For each traced operation it can record:

- who executed the operation;
- when it happened;
- input/output/error digests;
- a JEP v0.6-style event;
- a JAC v0.5-style dependency edge;
- optional HJS-style evidence references;
- a local JSONL blackbox log;
- an incident review report.

It is designed to help operators answer:

```text
What happened?
Which event failed?
Which prior event was this based on?
Which declared dependency path led here?
Which evidence references are available for review?
```

It is **not** designed to answer:

```text
Who is legally liable?
Who is morally at fault?
Was the system compliant?
Was the model correct?
Was the log complete?
```

---

## Relationship to JEP / HJS / JAC

```text
JEP = atomic signed judgment events
HJS = accountability receipts, archive/privacy/evidence lifecycle
JAC = declared dependency and accountability chains
Agent Blackbox = runtime trace recorder and incident review utility
```

Aligned with:

- JEP v0.6: https://github.com/hjs-spec/jep-v06
- JEP API v0.6: https://github.com/hjs-spec/jep-api
- HJS v0.5: https://github.com/hjs-spec/hjs-05
- JAC v0.5: https://github.com/hjs-spec/jac-agent-02

Public drafts:

- JEP-Core: https://datatracker.ietf.org/doc/draft-wang-jep-judgment-event-protocol/
- HJS: https://datatracker.ietf.org/doc/draft-wang-hjs-accountability/
- JAC: https://datatracker.ietf.org/doc/draft-wang-jac/

---

## Core Features

| Feature | Description |
|---|---|
| Trace decorator | Wrap agent functions and record runtime events |
| JEP-style event | Emits JEP v0.6-style J/D/T/V event objects |
| JAC chain extension | Uses `ext["https://jac.org/chain"]` instead of deprecated `task_based_on` |
| HJS evidence refs | Records input/output/error digests as evidence references |
| 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 agent-blackbox-jep==0.2.0a2
```

The PyPI distribution is named `agent-blackbox-jep` because `agent-blackbox` is unavailable on PyPI. Python imports remain `agent_blackbox`, and the CLI commands remain `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"])
```

---

## JAC v0.5 Chain Extension

Agent Blackbox does not use the deprecated top-level `task_based_on` field.

It uses:

```json
{
  "ext": {
    "https://jac.org/chain": {
      "based_on": "sha256:...",
      "based_on_type": "jep-event",
      "relation": "derived-from",
      "observed_log_assumption": "partial"
    }
  },
  "ext_crit": ["https://jac.org/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

A valid Agent Blackbox trace means a local runtime event was recorded and structurally linked.

It does not prove:

- legal liability;
- factual causality;
- regulatory compliance;
- complete-log availability;
- model correctness;
- moral responsibility.

A valid signature proves integrity of the event under the local key used by this library.

It does not prove the underlying claim is true.

---

## Status

```text
Version: 0.2.0a2
Status: experimental implementation seed
```

---

## License

MIT

## Runtime and verification notes

See [HARDENING.md](HARDENING.md) for supported behavior, regression checks, and compatibility boundaries.
