agent-blackbox-jep 0.2.0a2__tar.gz

agent_blackbox_jep-0.2.0a2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jep-protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_blackbox_jep-0.2.0a2/NOTICE.md

@@ -0,0 +1,11 @@
+# Notice
+
+Agent Blackbox is an experimental JEP/HJS/JAC runtime trace recorder.
+
+It supports incident review and declared chain reconstruction.
+
+It does not determine legal liability, factual truth, regulatory compliance, complete-log availability, model correctness, or moral responsibility.
+
+Internet-Draft text and excerpts are governed by the IETF Trust Legal Provisions and BCP 78 / BCP 79.
+
+Implementation code, examples, and tests are provided under the repository license unless otherwise stated.

agent_blackbox_jep-0.2.0a2/PKG-INFO

@@ -0,0 +1,264 @@
+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.

agent_blackbox_jep-0.2.0a2/README.md

@@ -0,0 +1,238 @@
+# 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.

agent_blackbox_jep-0.2.0a2/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-blackbox-jep"
+version = "0.2.0a2"
+description = "Experimental JEP/HJS/JAC runtime blackbox recorder for agent workflow incident review"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "HJS Spec", email = "signal@humanjudgment.org" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "PyNaCl>=1.6.2,<2",
+    "cryptography>=41.0.0",
+    "rfc8785>=0.1.4,<1",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+]
+
+[project.scripts]
+agent-blackbox = "agent_blackbox.cli:main"
+blame-finder = "agent_blackbox.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 88
+
+[tool.ruff]
+line-length = 88

agent_blackbox_jep-0.2.0a2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_blackbox_jep-0.2.0a2/src/agent_blackbox/__init__.py

@@ -0,0 +1,17 @@
+"""Agent Blackbox: JEP/HJS/JAC runtime trace recorder."""
+
+from .core import AgentBlackbox, TraceRecord, IncidentReview
+from .jep import JEPEvent, Verb, JAC_CHAIN_EXT
+
+# Backward-compatible alias for older examples.
+BlameFinder = AgentBlackbox
+
+__all__ = [
+    "AgentBlackbox",
+    "BlameFinder",
+    "TraceRecord",
+    "IncidentReview",
+    "JEPEvent",
+    "Verb",
+    "JAC_CHAIN_EXT",
+]

agent_blackbox_jep-0.2.0a2/src/agent_blackbox/cli.py

@@ -0,0 +1,51 @@
+"""CLI for Agent Blackbox."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .core import AgentBlackbox
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Agent Blackbox incident review utility")
+    parser.add_argument("--storage", default="./blackbox_logs", help="Blackbox log directory")
+
+    sub = parser.add_subparsers(dest="command")
+
+    review = sub.add_parser("review", help="Review an incident event hash")
+    review.add_argument("event_hash")
+
+    # Backward-compatible alias.
+    blame = sub.add_parser("blame", help="Alias for review")
+    blame.add_argument("event_hash")
+
+    tree = sub.add_parser("tree", help="Show declared dependency tree")
+    tree.add_argument("event_hash")
+
+    verify = sub.add_parser("verify", help="Verify a locally recorded event")
+    verify.add_argument("event_hash")
+
+    return parser
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    blackbox = AgentBlackbox(storage=args.storage)
+
+    # This CLI operates on in-memory events in the current process for the alpha.
+    # Future versions will load persisted JSONL logs into the index.
+    if args.command in {"review", "blame"}:
+        print(json.dumps(blackbox.review_incident(args.event_hash), indent=2))
+    elif args.command == "tree":
+        print(json.dumps(blackbox.get_causality_tree(args.event_hash), indent=2))
+    elif args.command == "verify":
+        print(json.dumps({"valid": blackbox.verify_event(args.event_hash)}, indent=2))
+    else:
+        build_parser().print_help()
+
+
+if __name__ == "__main__":
+    main()