API Reference

This document provides a comprehensive reference for the key modules and classes in the Casino of Life framework. Use this as a quick reference when building your applications.

Module: casino_of_life.agents

Class: DynamicAgent

The primary agent class for training AI in retro fighting games.

Constructor Parameters

Parameter	Type	Default	Description
env	RetroEnv	Required	The game environment
policy	str	"PPO"	RL algorithm to use ("PPO", "A2C", "DQN", "SAC")
learning_rate	float	0.0003	Learning rate for policy optimization
name	str	None	Optional name for the agent
reward_evaluator	BaseRewardEvaluator	None	Custom reward evaluator
frame_stack	int	4	Number of frames to stack for observation
gamma	float	0.99	Discount factor for future rewards
initial_policy	object	None	Pre-trained policy to start from

Methods

Method	Parameters	Return Type	Description
train	timesteps: int, callback=None	dict	Train the agent for specified timesteps
evaluate	episodes: int, detailed=False	float or dict	Evaluate agent performance
save	filename: str	None	Save agent to disk
load	filename: str	None	Load agent from disk
predict	observation	tuple	Get action from current observation
set_parameters	params: dict	None	Update agent parameters
get_parameters	None	dict	Get current agent parameters

Class: CaballoLoko

The natural language interface for training guidance.

Constructor Parameters

Parameter	Type	Default	Description
language_model	str	"default"	Language model to use
max_history	int	10	Maximum conversation history to retain

Methods

Method	Parameters	Return Type	Description
chat	message: str	str	Send message and get response
get_training_config	message: str	dict	Convert message to training config
get_history	None	list	Get conversation history
clear_history	None	None	Clear conversation history

Class: HierarchicalAgent

Agent with hierarchical policy structure for complex behaviors.

Constructor Parameters

Parameter	Type	Default	Description
env	RetroEnv	Required	The game environment
high_level_policy	HighLevelPolicy	Required	Strategy selection policy
low_level_policies	dict	Required	Action execution policies

Methods

Method	Parameters	Return Type	Description
train	timesteps: int	dict	Train both policy levels
predict	observation	tuple	Get action using hierarchical decision

Module: casino_of_life.environment

Class: RetroEnv

The game environment that wraps Stable-Retro for fighting games.

Constructor Parameters

Parameter	Type	Default	Description
game	str	Required	Game ROM to use (e.g., "MortalKombatII-Genesis")
state	str	"tournament"	Initial game state
players	int	2	Number of players (1 or 2)
character	str	None	Player character to use
observation_type	str	"grayscale"	Observation processing type

Methods

Method	Parameters	Return Type	Description
step	action	tuple	Execute action and return next state
reset	None	ndarray	Reset environment to initial state
render	mode="human"	ndarray	Render current frame
close	None	None	Close environment and free resources
clone	**kwargs	RetroEnv	Create copy of environment with new parameters
get_action_space	None	Space	Get available action space
get_observation_space	None	Space	Get observation space

Module: casino_of_life.reward_evaluators

Class: BaseRewardEvaluator

Abstract base class for reward evaluators.

Methods

Method	Parameters	Return Type	Description
evaluate	state, next_state, action, info	float	Calculate reward value
reset	None	None	Reset internal state

Class: BasicRewardEvaluator

Standard reward evaluator for fighting games.

Constructor Parameters

Parameter	Type	Default	Description
health_reward	float	1.0	Reward for maintaining health
damage_penalty	float	-1.0	Penalty for taking damage
hit_reward	float	0.5	Reward for landing hits
block_reward	float	0.2	Reward for successful blocks
move_penalty	float	-0.01	Penalty to discourage button mashing

Class: MultiObjectiveRewardEvaluator

Combines multiple reward evaluators.

Constructor Parameters

Parameter	Type	Default	Description
evaluators	list	Required	List of reward evaluator instances
weights	list	None	Optional weights for each evaluator

Module: casino_of_life.training

Class: TrainingManager

Manages the training process for agents.

Constructor Parameters

Parameter	Type	Default	Description
agent	DynamicAgent	Required	Agent to train
web_hooks	dict	None	Optional web dashboard integration

Methods

Method	Parameters	Return Type	Description
train	timesteps, eval_frequency, save_frequency	dict	Run training with evaluation and saving
evaluate	episodes	dict	Evaluate current agent
save_checkpoint	filename=None	str	Save training checkpoint
load_checkpoint	filename	None	Load training checkpoint

Class: CurriculumTrainer

Implements curriculum learning for progressive difficulty.

Constructor Parameters

Parameter	Type	Default	Description
agent	DynamicAgent	Required	Agent to train
curriculum	list	Required	List of curriculum stages
evaluation_frequency	int	5000	Steps between evaluations

Methods

Method	Parameters	Return Type	Description
train	None	dict	Run full curriculum training
train_stage	stage	bool	Train on a specific curriculum stage

Class: SelfPlayTrainer

Implements self-play training with progressive sampling.

Constructor Parameters

Parameter	Type	Default	Description
env	RetroEnv	Required	Game environment
initial_agent	DynamicAgent	Required	Starting agent
checkpoint_frequency	int	10000	Steps between model checkpoints
opponent_sampling	dict	Required	Sampling probabilities
total_timesteps	int	Required	Total training steps

Methods

Method	Parameters	Return Type	Description
train	None	dict	Run self-play training
sample_opponent	None	DynamicAgent	Sample opponent from history

Module: casino_of_life.web

Class: TrainingServer

Web server for monitoring and controlling training.

Constructor Parameters

Parameter	Type	Default	Description
host	str	"localhost"	Server host
port	int	8080	Server port
dashboard_config	DashboardConfig	None	Dashboard configuration
security_config	SecurityConfig	None	Security settings

Methods

Method	Parameters	Return Type	Description
start	None	None	Start web server
stop	None	None	Stop web server
register_agent	agent, agent_id	None	Register agent for monitoring
start_training	config	str	Start new training session
stop_training	training_id	None	Stop training session
get_status	training_id	dict	Get training status

Class: DashboardConfig

Configuration for the web dashboard.

Constructor Parameters

Parameter	Type	Default	Description
theme	str	"light"	Dashboard theme
default_view	str	"overview"	Default dashboard view
refresh_rate	int	5	Update frequency in seconds
custom_metrics	list	None	Additional metrics to display

Module: casino_of_life.evaluation

Class: TournamentEvaluator

Evaluates multiple agents in tournament format.

Constructor Parameters

Parameter	Type	Default	Description
agents	list	Required	List of agents to compete
matches_per_pair	int	10	Number of matches between each pair
evaluation_metrics	list	None	Metrics to track

Methods

Method	Parameters	Return Type	Description
run_tournament	None	dict	Run full tournament
run_match	agent1, agent2	dict	Run single match between agents
display_results	None	None	Display tournament results

Module: casino_of_life.data

Class: DemonstrationRecorder

Records gameplay demonstrations for imitation learning.