Bellona Defensive Agent Sandbox

Bellona is a simulation-only Python framework for studying how a defensive agent can preserve memory, reason about ambiguous events, recommend proportional protective responses, and remain human-governed.

It is intentionally designed as a public-safe portfolio project. It does not control hardware, weapons, drones, radio equipment, industrial systems, production networks, or safety-critical infrastructure. All actions are reversible state changes inside a toy protected-space simulation.

30-second summary

Bellona demonstrates a small but complete agent loop:

Event -> Assessment -> Doctrine -> Recommendation -> Authorization -> Audit -> Memory -> Report

The interesting part is not raw model size. The interesting part is the control pattern:

• persistent agent state
• episodic memory
• deterministic doctrine/policy checks
• proportional response recommendations
• human approval gates for high-risk recommendations
• append-only JSONL audit records
• static HTML reports for reviewer-friendly decision traces
• named simulation scenarios for repeatable demos
• tests for safety boundaries and state continuity

Architecture

flowchart LR
    A[Toy Event] --> B[ProtectedSpaceArena.assess]
    B --> C[ThreatAssessment]
    C --> D[DoctrineEngine.recommend]
    D --> E[Recommendation]
    E --> F[DoctrineEngine.authorize]
    F --> G{Allowed?}
    G -->|Yes, simulation only| H[ProtectedSpaceArena.apply]
    G -->|Human gate / denied| I[Pending / no external effect]
    H --> J[AuditLog JSONL]
    I --> J
    J --> K[EpisodicMemory]
    K --> L[Atomic StateStore]
    J --> M[Static HTML Report]

Loading

Core modules:

src/bellona_sandbox/
  agent.py          # Orchestrates assessment, doctrine, memory, and audit
  arena.py          # Toy protected-space simulation
  audit.py          # JSONL audit log writer/reader
  doctrine.py       # Bounded defensive policy logic
  memory.py         # Small persistent episodic memory
  models.py         # Dataclasses and enums
  scenarios.py      # Named portfolio demo scenarios
  state.py          # Atomic JSON state persistence
  report.py         # Static HTML scenario report generator
  cli.py            # Demo command line interface

Quick start

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .[dev]
pytest
bellona-demo --scenario boundary_probe --report .bellona/report.html

Demo scenarios

Run a named scenario and produce a static HTML report:

bellona-demo --scenario boundary_probe --report .bellona/report.html

Example output:

Bellona scenario: Boundary probe
A repeated abstract probe crosses the simulation boundary. Bellona records evidence first, then increases passive posture when the pattern becomes credible.

[1/2] Event: repeated boundary touch against simulated perimeter
    Assessment: suspicious (confidence=0.61)
    Recommendation: record_evidence
    Risk: low
    Human approval required: false
    Authorized in sandbox: true
    Rationale: Suspicious activity should be documented before escalation.
    Arena: Evidence recorded in simulated sector.
    Audit: .bellona/audit.jsonl

[2/2] Event: same source pattern repeats with stronger protected-space signal
    Assessment: credible (confidence=0.77)
    Recommendation: harden_posture
    Risk: medium
    Human approval required: false
    Authorized in sandbox: true
    Rationale: Credible risk exists, but passive hardening is sufficient in the sandbox.
    Arena: Simulated defensive posture increased.
    Audit: .bellona/audit.jsonl

HTML report: .bellona/report.html

Available scenarios:

• benign_noise — low-confidence event; Bellona observes only
• boundary_probe — suspicious pattern becomes credible; Bellona records evidence before hardening
• outside_watch — event outside the protected space; Bellona notifies without escalation
• active_intrusion — high-risk toy event; Bellona triggers the human approval gate

You can also run a custom single event:

bellona-demo --summary "toy anomaly near protected boundary" --signal 0.72

Reviewer-friendly report

The --report flag writes a dependency-free HTML report that summarizes the scenario, each assessment, the recommendation, authorization status, evidence, doctrine notes, and simulated arena result. This is useful for interviews because the reviewer can see the complete decision trace without reading JSONL logs.

open .bellona/report.html  # macOS
xdg-open .bellona/report.html  # Linux

See docs/sample_terminal_demo.md for a copy-paste demo transcript.

Why this matters

Agentic systems are easy to demo and hard to govern. Bellona focuses on the less flashy but more important layer: how an agent remembers context, explains recommendations, records evidence, refuses unsafe escalation, and preserves a human approval boundary.

This makes the repository useful as a small architecture sample for applied AI, AI safety, simulation engineering, defensive decision support, and audit-focused automation work.

Safety model

Bellona can recommend simulated defensive actions such as:

• observe
• notify operator
• record evidence
• increase simulated protective posture
• record a high-risk recommendation as pending human review
• recover simulated state

Bellona cannot perform external actions. The DoctrineEngine rejects recommendations that:

• affect external targets
• bypass human approval when required
• lack audit notes
• attempt simulated isolation without human approval

See docs/safety_model.md and SECURITY.md.

Why this is portfolio-safe

This repository focuses on agent architecture, not operational capability. The public artifact demonstrates how to structure a bounded, inspectable, persistent agent without connecting it to real systems.

The project intentionally omits:

• weapon control
• autonomous engagement
• RF/EM control
• drone interception or takeover
• cyber offensive tooling
• live network scanning or exploitation
• real countermeasure execution
• adapters to production or safety-critical systems

What this demonstrates to reviewers

• Python package structure with CLI entry points
• dataclass-based domain modeling
• deterministic policy engines
• simulation design
• persistent state and bounded memory
• append-only audit logging
• human-supervised escalation pattern
• testable safety boundaries
• clear technical documentation

Portfolio framing

Resume-safe summary:

Built a Python defensive-agent simulation framework with persistent state, episodic memory, deterministic policy checks, proportional response recommendations, JSONL audit logging, named demo scenarios, and human-supervised escalation gates.

A longer version is available in docs/resume_blurb.md. Interview and LinkedIn framing are available in docs/portfolio_pitch.md.

Development

pip install -e .[dev]
pytest
ruff check .

GitHub Actions config is included in .github/workflows/ci.yml.

License

MIT License. See LICENSE.