Skip to content

Forensics Analyzer

Post-incident forensic analysis for AI replication events. Reconstructs timelines, identifies root causes, extracts evidence chains, and produces structured incident reports suitable for audit and compliance review.

Quick Start

from replication.forensics import ForensicsAnalyzer
from replication.simulator import Simulator

# Run a simulation and analyse forensically
sim = Simulator()
report = sim.run()

analyzer = ForensicsAnalyzer()
forensic = analyzer.analyze(report)

# Timeline reconstruction
for event in forensic.timeline:
    print(f"[{event.timestamp:.1f}s] {event.category}: {event.description}")

# Root cause analysis
for cause in forensic.root_causes:
    print(f"Root cause: {cause.description} (confidence: {cause.confidence:.0%})")

# Evidence chain
for evidence in forensic.evidence:
    print(f"Evidence: {evidence.type} — {evidence.summary}")

Key Classes

  • ForensicsAnalyzer — Main analysis engine: timeline reconstruction, root cause identification, evidence extraction.
  • ForensicReport — Full analysis output: timeline, root_causes, evidence, anomalies, recommendations.
  • TimelineEvent — A single event in the reconstructed timeline.
  • RootCause — Identified contributing factor with confidence score.
  • EvidenceItem — Extracted forensic evidence with type and provenance.

forensics

Forensic Analyzer — post-simulation safety analysis.

Deep-dives into simulation reports to reconstruct decision chains, identify near-miss safety events, detect escalation phases, and run counterfactual "what-if" analyses with alternative parameters.

Usage (CLI)::

python -m replication.forensics                                 # default run
python -m replication.forensics --strategy greedy --max-depth 5  # custom config
python -m replication.forensics --counterfactuals 3              # 3 what-if variants
python -m replication.forensics --json                           # JSON output
python -m replication.forensics --summary-only                   # brief summary

Programmatic::

from replication.forensics import ForensicAnalyzer
from replication.simulator import Simulator, ScenarioConfig

config = ScenarioConfig(strategy="greedy", max_depth=4)
sim = Simulator(config)
report = sim.run()

analyzer = ForensicAnalyzer()
forensics = analyzer.analyze(report)
print(forensics.render())

ForensicEvent dataclass

A single reconstructed event with safety annotations.

NearMiss dataclass

A moment where a safety limit was almost breached.

EscalationPhase dataclass

A period of rapid worker growth.

Counterfactual dataclass

A 'what-if' comparison with modified parameters.

DecisionPoint dataclass

A controller decision with context.

ForensicReport dataclass

Complete forensic analysis of a simulation run.

render_events() -> str

Render reconstructed event timeline with safety annotations.

render_near_misses() -> str

Render near-miss safety events.

render_escalation() -> str

Render escalation phase analysis.

render_counterfactuals() -> str

Render counterfactual what-if analysis.

render_decisions() -> str

Render controller decision audit trail.

render_summary() -> str

Render the safety summary and recommendations.

render() -> str

Render the complete forensic report.

to_dict() -> Dict[str, Any]

Export as a JSON-serializable dictionary.

ForensicAnalyzer

Performs post-simulation forensic analysis.

Reconstructs what happened during a simulation, identifies safety-critical moments, and generates actionable insights.

Parameters

counterfactual_count : int Number of what-if variants to run (default 5). near_miss_threshold_pct : float Headroom percentage below which a limit approach is flagged as a near miss (default 20.0 = within 20% of limit). escalation_growth_threshold : float Minimum workers-per-step growth rate to flag as an escalation phase (default 1.5).

analyze(report: Optional[SimulationReport] = None, config: Optional[ScenarioConfig] = None) -> ForensicReport

Run forensic analysis on a simulation report.

If report is None, a new simulation is run using config (or default settings).

main() -> None

CLI entry point for forensic analysis.