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

Installation

Install the published distribution:

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:

pip install -e .

Basic Usage

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:

{
  "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:

agent-blackbox review sha256:...

Show a chain tree:

agent-blackbox tree sha256:...

Verify an event:

agent-blackbox verify sha256:...

Boundary Statement

New events use Core 0.7 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 for the packaged implementation.

License

MIT

Runtime and verification notes

See HARDENING.md for event extensions, key handling and import compatibility.