Recording Module#
The recording system in Mesa-LLM provides comprehensive tools for capturing, analyzing, and visualizing simulation events. It enables researchers and developers to record all agent behavior, communications, decisions, and state changes for post-simulation analysis, debugging, and research insights.
Usage Examples#
Basic Recording Setup#
from mesa_llm.recording.record_model import record_model
from mesa import Model
@record_model(output_dir="my_recordings", auto_save_interval=50)
class MyModel(Model):
def __init__(self, **kwargs):
super().__init__(**kwargs)
# Model initialization
# Recorder automatically attached after __init__
def step(self):
super().step()
# Step events automatically recorded
# Save recording manually
model = MyModel()
model.run_simulation()
model.save_recording("final_simulation.json")
Manual Recorder Integration#
from mesa_llm.recording.simulation_recorder import SimulationRecorder
from mesa_llm.llm_agent import LLMAgent
class MyAgent(LLMAgent):
def __init__(self, model, **kwargs):
super().__init__(model, **kwargs)
def step(self):
# Automatic recording of observations, plans, actions
obs = self.generate_obs()
plan = self.reasoning.plan(obs=obs)
self.apply_plan(plan)
class MyModel(Model):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.recorder = SimulationRecorder(
model=self,
output_dir="recordings",
auto_save_interval=100
)
# Attach to agents
for agent in self.agents:
if hasattr(agent, 'recorder'):
agent.recorder = self.recorder
Custom Event Recording#
def step(self):
# Record custom domain-specific events
if hasattr(self, 'recorder'):
self.recorder.record_event(
event_type="negotiation_result",
content={
"participants": [self.unique_id, other_agent.unique_id],
"outcome": "agreement_reached",
"terms": self.negotiation_terms
},
agent_id=self.unique_id,
metadata={"negotiation_round": self.round_number}
)
Analysis and Visualization#
from mesa_llm.recording.agent_analysis import AgentViewer, quick_agent_view
# Interactive exploration
viewer = AgentViewer("recordings/simulation_abc123_20240101_120000.json")
viewer.interactive_mode()
# Quick specific views
quick_agent_view("recording.json", agent_id=5, view_type="timeline")
quick_agent_view("recording.json", agent_id=5, view_type="conversations")
quick_agent_view("recording.json", agent_id=5, view_type="decisions")
quick_agent_view("recording.json", view_type="info") # Simulation overview
Event Type Categories#
Agent Events:
observation - Environmental perception and state awareness
plan - Reasoning output and decision-making processes
action - Tool execution and environment interaction
message - Agent-to-agent communication
state_change - Internal agent state modifications
Model Events:
simulation_start - Recording initialization
simulation_end - Recording completion with status
step_start - Beginning of simulation step
step_end - Completion of simulation step
Custom Events:
Domain-specific events can be recorded with custom event_type strings
Useful for tracking domain logic, negotiations, transactions, etc.
Export and Integration#
# Export specific agent data
recorder = model.recorder
agent_data = recorder.export_agent_memory(agent_id=1)
# Get recording statistics
stats = recorder.get_stats()
print(f"Total events: {stats['total_events']}")
print(f"Active agents: {stats['unique_agents']}")
# Filter events for analysis
observations = recorder.get_events_by_type("observation")
step_events = recorder.get_events_by_step(10)
Core Components#
Comprehensive simulation recorder for mesa-llm simulations.
This module provides tools to record all simulation events for post-analysis, including agent observations, plans, actions, messages, and state changes.
- class SimulationEvent(event_id: str, timestamp: datetime, step: int, agent_id: int | None, event_type: str, content: dict[str, Any], metadata: dict[str, Any])[source]#
Bases:
objectDataclass representing a single recorded event in the simulation with complete context and metadata.
- Attributes:
event_id (str) - Unique identifier for this event
timestamp (datetime) - UTC timestamp when event occurred
step (int) - Simulation step number
agent_id (int | None) - Agent associated with event (None for model events)
event_type (str) - Type of event (observation, plan, action, message, state_change, etc.)
content (dict) - Event-specific data and information
metadata (dict) - Additional contextual metadata
- class SimulationRecorder(model, output_dir: str = 'recordings', record_state_changes: bool = True, auto_save_interval: int | None = None)[source]#
Bases:
objectCentralized recorder for capturing all simulation events for post-analysis. It captures agent observations, plans, actions, messages, state changes, etc. as well as model-level events and transitions.
- Attributes:
model - Reference to the Mesa model being recorded
events - List of all recorded SimulationEvent objects
simulation_id - Unique identifier for this recording session
start_time - Recording start timestamp
simulation_metadata - Recording metadata and statistics
Initialize the simulation recorder.
- Parameters:
model (Model) - Mesa model instance to record
output_dir (str) - Directory for saving recordings (default: “recordings”)
record_state_changes (bool) - Whether to track agent state changes (default: True)
auto_save_interval (int | None) - Automatic save frequency in events (default: None)
- events: list[SimulationEvent]#
- record_event(event_type: str, content: dict[str, Any] | str | None = None, agent_id: int | None = None, metadata: dict[str, Any] | None = None, recipient_ids: list[int] | None = None)[source]#
Record a simulation event.
- Args:
event_type: Type of event to record (observation, plan, action, message, state_change, etc.) content: Event content as dict or string agent_id: ID of the agent associated with this event metadata: Additional metadata for the event recipient_ids: List of recipient IDs for message events
- get_agent_events(agent_id: int) list[SimulationEvent][source]#
Get all events for a specific agent.
- get_events_by_type(event_type: str) list[SimulationEvent][source]#
Get all events of a specific type.
- get_events_by_step(step: int) list[SimulationEvent][source]#
Get all events from a specific simulation step.
- export_agent_memory(agent_id: int) dict[str, Any][source]#
Export agent memory state for external analysis.
Model recording integration#
Class decorator that instruments a Mesa Model subclass with a SimulationRecorder.
Usage:
from mesa_llm.recording.record_model import record_model
@record_model
class MyModel(Model):
...
The decorator will:
1. Instantiate a SimulationRecorder after the model’s original __init__ completes and assign it to self.recorder.
2. Attach the same recorder to every agent that exposes a recorder attribute (e.g., subclasses of LLMAgent).
3. Wrap the model’s step method to automatically record step_start and step_end events and ensure late-added agents also receive the recorder.
4. Provide a convenience save_recording method on the model for persisting the captured simulation events.
Parameters#
- **kwargs
Any keyword arguments are forwarded directly to
SimulationRecorderwhen it is created. This allows callers to customize output directory, auto-save intervals, or disable certain event types:@record_model(output_dir="recordings", auto_save_interval=100) class MyModel(Model): ...
- record_model(cls: type[Model] | None = None, **kwargs) Callable[[type[Model]], type[Model]] | type[Model][source]#
Class decorator that automatically instruments Mesa Model subclasses with SimulationRecorder functionality. Provides seamless integration without manual recorder setup.
- Features:
Automatically creates and attaches SimulationRecorder after model initialization
Attaches recorder to all LLMAgent instances in the model
Wraps model.step() to record step start/end events
Provides save_recording() convenience method
Registers automatic save on program exit
- Parameters:
cls (type[Model] | None) - The Model class to decorate. If None, returns a wrapper for use as a decorator with kwargs.
kwargs - Forwarded to SimulationRecorder constructor for customization
Analysis utilities#
Enhanced agent viewer for recorded mesa-llm simulations with rich formatting.
This module provides comprehensive analysis and visualization tools for exploring recorded simulation data, including agent behavior, conversations, decision-making processes, and simulation metadata. Compatible with both legacy and enhanced simulation recorder formats.