hermes-toolkit 0.1.0__py3-none-any.whl

hermes/__init__.py

@@ -0,0 +1,10 @@
+"""HERMES: a toolkit for the multi-agent simulation of emergent communication and languages."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("hermes-toolkit")
+except PackageNotFoundError:  # running from a source checkout, not installed
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

hermes/agent.py

@@ -0,0 +1,49 @@
+#####################################################
+#                                                   #
+# Agent                                             #
+#                                                   #
+#####################################################
+
+import hermes.globals
+import hermes.utils
+import warnings
+
+class Agent():
+    """
+    The base class of a HERMES agent. 
+    """
+
+    def __init__(self, configuration):
+        """Initialisation of agents upon creation."""
+        self.configuration = {**hermes.globals.EXPERIMENT_DEFAULT_CONFIGURATION, **configuration}
+
+    def prepare_for_interaction(self):
+        warnings.warn('No method implemented for preparing agents before interaction.')
+        pass
+
+class SingleWordAgent(Agent):
+
+    def __init__(self, configuration):
+
+        self.vocabulary = []
+        self.used_word = None
+        self.invented_word = None
+        self.adopted_word = None
+
+        super().__init__(configuration)
+
+    def add_word(self, meaning, form=None, score=0.5):
+        """Add a new word to vocabulary."""
+
+        if form is None:
+            form = hermes.utils.make_new_form()
+
+        word = [form, meaning, score]
+        self.vocabulary.append(word)
+
+        return word
+
+    def prepare_for_interaction(self):
+        self.used_word = None
+        self.invented_word = None
+        self.adopted_word = None

hermes/alignment.py

@@ -0,0 +1,13 @@
+
+class AlignmentStrategy():
+    pass
+
+class NoAlignment(AlignmentStrategy):
+    """Run no alignment"""
+
+    def run_after_success(self, process, interaction, upper_bound=1.0, lower_bound=0.0):
+        pass
+
+    def run_after_failure(self, process, interaction, lower_bound=0.0):
+        pass
+

hermes/experiment.py

@@ -0,0 +1,158 @@
+###########################################################
+#                                                         #
+# Experiment                                              #
+#                                                         #
+###########################################################
+
+import hermes.globals
+import random
+import matplotlib.pyplot as plt
+import sys
+import importlib
+import numpy as np
+import pickle
+import alive_progress
+
+
+class Experiment():
+    """The HERMES experiment class."""
+
+    def __init__(self, population=None, world=None, configuration={}):
+        """Initialize the experiment, optionally passing a population and a world object,
+        otherwise retrieve population_class and world_class from configuration."""
+
+        # The configuration passed to the experiment is merged with the default configuration.
+        self.configuration = {**hermes.globals.EXPERIMENT_DEFAULT_CONFIGURATION, **configuration}
+        self.phase = None
+
+        # When device is passed in experiment configuration, use it globally
+        if 'device' in self.configuration:
+            hermes.globals.DEVICE = self.configuration['device']
+        else:
+            self.configuration['device'] = hermes.globals.DEVICE
+
+        # The population is created
+        if population is not None:
+            self.population = population
+            class_name = type(population).__qualname__
+            module_name =  type(population).__module__
+            self.configuration['population_class'] = (class_name, module_name)
+        else:
+            class_name, module_name = self.configuration['population_class']
+            module = importlib.import_module(module_name)
+            population_class = getattr(module, class_name)
+            self.population = population_class(self.configuration)
+
+        # The world is created
+        if world is not None:
+            self.world = world
+            class_name = type(world).__qualname__
+            module_name = type(world).__module__
+            self.configuration['world_class'] = (class_name, module_name)
+        else:
+            class_name, module_name = self.configuration['world_class']
+            module = importlib.import_module(module_name)
+            world_class = getattr(module, class_name)
+            self.world = world_class(self.configuration)
+
+        # No current interaction yet
+        self.current_interaction = None
+
+        # Instantiate monitors to record experiment data
+        self.active_monitors = {}
+        for (class_name, module_name) in self.configuration['monitors']:
+            module = importlib.import_module(module_name)
+            monitor_class = getattr(module, class_name)
+            monitor_instance = monitor_class()
+            self.active_monitors[class_name] = monitor_instance
+
+        if 'logger_class' in self.configuration:
+            class_name, module_name = self.configuration['logger_class']
+            module = importlib.import_module(module_name)
+            logger_class = getattr(module, class_name)
+            self.logger = logger_class(self.configuration, self.active_monitors)
+        else:
+            self.logger = None
+
+
+    def run_interaction(self, phase='train', verbose=False):
+        """ Create a new interaction, make it happen and record the outcome. """
+
+        # Set phase of experiment
+        self.phase = phase
+
+        # Determine interaction type and create interaction
+        self.current_interaction = self.create_new_interaction()
+
+        # Run actual interaction
+        self.current_interaction.run(phase=self.phase, verbose=verbose)
+
+        # Record outcome
+        for active_monitor in self.active_monitors.values():
+            active_monitor.record(self.current_interaction)
+
+
+    def create_new_interaction(self):
+        """Instantiate a new interaction instance, based on a type randomly chosen from the interaction_classes list specified in the configuration."""
+        class_name, module_name = random.choice(self.configuration['interaction_classes'])
+        module = importlib.import_module(module_name)
+        interaction_class = getattr(module, class_name)
+        return interaction_class(self)
+
+
+    def run_series(self, nr_of_interactions, show_alive_progress=True, phase='train', verbose=False):
+        """Run a series of interactions."""
+        if show_alive_progress == True:
+            with alive_progress.alive_bar(nr_of_interactions, force_tty=True) as bar:
+                for i in range(nr_of_interactions):
+                    self.run_interaction(phase=phase, verbose = verbose)
+                    bar()
+        else:
+            for i in range(nr_of_interactions):
+                if (i + 1) % 100 == 0:
+                    print(f'Interaction {i+1}')
+                self.run_interaction(phase=phase, verbose=verbose)
+                sys.stdout.flush()
+
+        if self.logger is not None:
+            self.logger.save_monitors()
+
+
+    def plot_outcome(self):
+        """Plot the results of an experiment in terms of the data that the active monitors collected throughout the experiment."""
+        experiment_plotpoints = {}
+        for name, monitor in self.active_monitors.items():
+            if hasattr(monitor, 'line_name'):
+                monitor.make_plot_points(window_size=self.configuration['plot_window_size'])
+                experiment_plotpoints[name] = monitor.plot_points
+
+        fig, axes = plt.subplots(len(experiment_plotpoints.keys()), figsize=(5, 7), sharex=True)
+
+        if not (isinstance(axes, list) or isinstance(axes, np.ndarray)):
+            axes = [axes]
+
+        for i, key in enumerate(experiment_plotpoints.keys()):
+            ax = axes[i]
+
+            for line, points in experiment_plotpoints[key].items():
+                ax.plot(points.keys(), points.values(), label=line)
+            ax.set_title(key)
+            ax.grid()
+            ax.legend()
+
+        plt.show()
+
+    def save_population(self):
+        self.population.save("./xp_outputs/")
+
+    def load_population(self, path):
+        self.population.load(path)
+
+    def store(self, filename):
+        """Store experiment object under filename."""
+        with open(filename, 'wb') as output:  # Overwrites any existing file.
+            pickle.dump(self, output, -1)
+
+    def flush_all_monitors(self):
+        for monitor in self.active_monitors.values():
+            monitor.flush()

hermes/globals.py

@@ -0,0 +1,51 @@
+###########################
+#                         #
+# Hermes global variables #
+#                         #
+###########################
+
+# Default experiment configuration
+EXPERIMENT_DEFAULT_CONFIGURATION = {
+    'agent_class': ('Agent', 'hermes.agent'),
+    'world_class': ('EntityWorld', 'hermes.world'),
+    'population_class': ('UniformPopulation', 'hermes.population'),
+    'interaction_classes': [("DescribeAndPointInteraction", "hermes.interaction")],
+    'monitors': [('TraceInteractionSuccess', 'hermes.monitoring')],
+    'alignment_strategy': ('NoAlignment', 'hermes.alignment'),
+    'population_size': 10,
+    'plot_window_size': 100
+    }
+
+# Torch device for GPU use.
+#
+# PyTorch is an optional dependency. The core framework is pure Python; only
+# experiments with neurally grounded agents need torch, which is installed with
+#     pip install "hermes-toolkit[torch]"
+# When torch is not installed, DEVICE is None and torch-based agents are
+# unavailable, but the rest of the framework still imports and runs.
+#
+# Device selection is defensive on purpose: this runs at import time, so an
+# unexpected failure here would make `import hermes` fail for everyone rather
+# than fall back to CPU.
+
+try:
+    import torch
+except ImportError:                                 # pragma: no cover
+    torch = None
+    DEVICE = None
+else:
+    def _select_device():
+        """Return the best available torch device, falling back to CPU."""
+        try:
+            if torch.cuda.is_available():
+                return torch.device("cuda")
+        except Exception:
+            pass
+        try:
+            if torch.backends.mps.is_available():
+                return torch.device("mps")
+        except Exception:
+            pass
+        return torch.device("cpu")
+
+    DEVICE = _select_device()

hermes/interaction.py

@@ -0,0 +1,128 @@
+###########################################
+#                                         #
+# Interaction                             #
+#                                         #
+###########################################
+
+import hermes.process
+import importlib
+import hermes.alignment
+
+class Interaction:
+    """ General interaction class. """
+
+    def __init__(self, experiment):
+        self.experiment = experiment
+        self.configuration = experiment.configuration
+        self.interacting_agents = []
+        self.succeeded = None
+
+        alignment_strategy = self.configuration['alignment_strategy']
+        if alignment_strategy is not None and alignment_strategy != []:
+            class_name, module_name = self.configuration['alignment_strategy']
+            module = importlib.import_module(module_name)
+            alignment_class = getattr(module, class_name)
+            self.alignment_strategy = alignment_class()
+        else:
+            self.alignment_strategy = hermes.alignment.NoAlignment()
+
+class DescribeAndPointInteraction(Interaction):
+    """Interaction class for description-and-point interactions."""
+    def __init__(self, experiment, speaker_process_class=('DescriptionProcess', 'hermes.process'), listener_process_class=('PointingProcess', 'hermes.process')):
+
+        # Call init method of superclass
+        super().__init__(experiment)
+
+        self.speaker_process_class = speaker_process_class
+        self.listener_process_class = listener_process_class
+
+        # Select the interacting agents for the experiment, one speaker and one listener, prepare them interaction
+        self.select_interacting_agents()
+        self.speaker.prepare_for_interaction()
+        self.listener.prepare_for_interaction()
+
+        # Load scene
+        self.load_scene()
+
+        self.make_processes()
+
+    def make_processes(self):
+        # Set speaker process
+        speaker_process_class_name, speaker_process_module_name = self.speaker_process_class
+        speaker_process_module = importlib.import_module(speaker_process_module_name)
+        speaker_process_class = getattr(speaker_process_module, speaker_process_class_name)
+        self.speaker_process = speaker_process_class(self.speaker, self.speaker_scene, self.speaker_target, self)
+        self.speaker.processes = [self.speaker_process]
+
+        # Set listener process
+        listener_process_class_name, listener_process_module_name = self.listener_process_class
+        listener_process_module = importlib.import_module(listener_process_module_name)
+        listener_process_class = getattr(listener_process_module, listener_process_class_name)
+        self.listener_process = listener_process_class(self.listener, self.listener_scene, self)
+        self.listener.processes = [self.listener_process]
+                                   
+    def load_scene(self):
+        scene, target = self.experiment.world.sample_scene_with_target(self.configuration, split=self.experiment.phase)
+        self.speaker_scene = scene
+        self.speaker_target = target # gold target
+        self.listener_scene = scene 
+        self.listener_target = target # gold target
+
+    def select_interacting_agents(self):
+        self.interacting_agents = self.experiment.population.sample_agents(2)
+        self.speaker = self.interacting_agents[0]
+        self.listener = self.interacting_agents[1]
+
+    def run(self, phase='train', verbose=False):
+        """Defines the interaction script."""
+
+        # Run description task speaker:
+        self.speaker_process.run(phase)
+        spoken_utterance = self.speaker_process.utterance
+
+        # print(f'Speaker says: {spoken_utterance}')
+
+        # Run pointing task listener
+        self.listener_process.run(spoken_utterance)
+
+        # Determine interaction success
+        self.determine_communicative_success()
+
+        if verbose:
+            if self.succeeded == True:
+                print(f'Interaction succeeded!!!')
+            else:
+                print("Interaction failed...")
+                if hasattr(self.speaker_process.agent, "invented_word"):
+                    if self.speaker_process.agent.invented_word is not None:
+                        print(f'(speaker)...')
+                    else:
+                        print(f'(listener)...')
+
+        # Run adoption/reward policy
+        if phase == 'train':
+            self.learn()
+
+
+    def learn(self):
+        """Run the alignment strategy after success or failure, passing the speaker and listener processes.
+
+        Repair behaviour such as adopting an unknown word belongs in the
+        alignment strategy, not here: an `AlignmentStrategy` subclass decides
+        what each agent does once the outcome of the interaction is known.
+        """
+        if self.succeeded is True:
+            self.alignment_strategy.run_after_success(self.speaker_process, self)
+            self.alignment_strategy.run_after_success(self.listener_process, self)
+
+        else:
+            self.alignment_strategy.run_after_failure(self.speaker_process, self)
+            self.alignment_strategy.run_after_failure(self.listener_process, self)
+
+
+    def determine_communicative_success(self):
+        """Determine communicative success of interaction."""
+        if self.listener_process.hypothesised_target == self.listener_target:
+            self.succeeded = True
+        else:
+            self.succeeded = False

hermes/logging.py

@@ -0,0 +1,114 @@
+import shutil
+import json
+import time
+import os
+import pandas as pd
+
+from pathlib import Path
+
+
+#####################################################
+#                                                   #
+# Utils                                             #
+#                                                   #
+#####################################################
+
+BASE_OUTPUT_DIR = './xp_outputs'
+WANDB_OUTPUT_DIR = './outputs'
+
+
+def make_output_dirs(cfg):
+    base_output_path = Path(BASE_OUTPUT_DIR)
+    if not base_output_path.exists():
+        print(f"Creating directory at '{BASE_OUTPUT_DIR}' for logging experiements.")
+        os.makedirs(base_output_path)
+
+    model_dir = base_output_path / cfg['xp_name']
+    if not model_dir.exists():
+        curr_run = 1
+    else:
+        # If a directory with the same xp_name exists, find the run number of the new xp by looking at existing run folders
+        exst_run_nums = [
+            int(str(folder.name).split('run')[1]) 
+            for folder in model_dir.iterdir() 
+            if str(folder.name).startswith('run')]
+
+        if len(exst_run_nums) == 0:
+            curr_run = 1
+        else:
+            curr_run = max(exst_run_nums) + 1
+
+    # Create run directory
+    while True:
+        run_dir = model_dir / f'run{curr_run}'
+        # check every time we create one if another was created by a parallel process
+        try:
+            os.makedirs(run_dir)
+        except FileExistsError:
+            curr_run += 1
+        else:
+            break
+
+    return run_dir
+
+def write_config(run_directory, cfg):
+    with open(os.path.join(run_directory, 'args.txt'), 'w') as f:
+        f.write(str(time.time()) + '\n')
+
+        # Write the git repo id
+        # commit_hash = Repo(
+        #     search_parent_directories=True).head.object.hexsha
+        # f.write(
+        #     "Running with git commit " + str(commit_hash) + '\n')
+
+        str_cfg = {key: str(val) for key, val in cfg.items()}
+
+        # Write the config
+        f.write("Configuration:\n")
+        f.write(json.dumps(str_cfg, indent=4))
+
+        # Write which files were modified since the last commit
+        # mod_files = get_modified_files()
+        # f.write("\nModified files since last commit:\n")
+        # f.write('\n'.join(str(i) for i in mod_files))
+
+    # Save code
+    # compress_python_files(os.path.join(run_directory, 'code.zip'))
+
+#####################################################
+#                                                   #
+# Logger                                            #
+#                                                   #
+#####################################################
+
+class Logger:
+    """
+    Class to handle the logging of experiments locally. 
+    """
+    def __init__(self, configuration, monitors):
+        assert 'xp_name' in configuration, "To log the experiment, define the experiment's name with the 'xp_name' entry."
+
+        self.configuration = configuration
+        self.monitors = monitors
+
+        self.log_directory = make_output_dirs(configuration)
+        print('Logging XP in directory:', self.log_directory)
+
+        write_config(self.log_directory, configuration)
+
+    def save_monitors(self):
+        data = []
+        for m in self.monitors.values():
+            m.make_plot_points(self.configuration["plot_window_size"])
+
+            data.append(pd.DataFrame(m.plot_points))
+
+        data = pd.concat(data, axis=1)
+
+        data.to_csv(self.log_directory / 'monitor_data.csv')
+
+
+
+
+
+

hermes/monitoring.py

@@ -0,0 +1,58 @@
+###########################################################
+#                                                         #
+# Monitoring                                              #
+#                                                         #
+###########################################################
+
+import warnings
+from itertools import islice
+import numpy as np
+
+from hermes.interaction import Interaction
+
+
+class Monitor():
+    """General HERMES monitoring class"""
+
+    def __init__(self):
+        #Empty data traces upon initialisation:
+        self.data = []
+        self.plot_points = {}
+
+        self.line_name = "plot_points"
+
+    def flush(self):
+        self.data = []
+        self.plot_points = {}
+
+    def record(self):
+        """A monitor class defines a method for recording data."""
+        warnings.warn(f"Please implement a record_trace method for {type(self).__name__}")
+
+    def make_plot_points(self, window_size=100):
+        """Applies a sliding window to collected data that can be used for plotting."""
+        self.plot_points = {self.line_name: {}}
+        generator = fixed_step_window(self.data, window_size)
+        for w in generator:
+            self.plot_points[self.line_name][w[0]] = np.mean(w[1])
+
+
+def fixed_step_window(seq, n=2):
+    for i in range(0, len(seq), n):
+        yield i+n, seq[i: i+n]
+
+
+class TraceInteractionSuccess(Monitor):
+    """Monitor for tracing the success of interactions."""
+
+    def __init__(self, line_name="success"):
+        super().__init__()
+
+        self.line_name = line_name
+
+    def record(self, interaction: Interaction):
+        """Record 1 if interaction succeeded, 0 otherwise."""
+        if interaction.succeeded:
+            self.data.append(1)
+        else:
+            self.data.append(0)

hermes/population.py

@@ -0,0 +1,51 @@
+###########################
+#                         #
+# Populations             #
+#                         #
+###########################
+
+import hermes.globals
+import importlib
+import sys
+import random
+
+
+class Population():
+    """The HERMES population class."""
+    def __init__(self, configuration):
+        self.configuration = {**hermes.globals.EXPERIMENT_DEFAULT_CONFIGURATION, **configuration}
+
+    def agent_list(self):
+        """Return all agents in the population in a list data structure."""
+        raise NotImplementedError("Please implement an 'agent_list' method for your 'Population' class.")
+
+    def save(self, path):
+        """Save the agents' learnt representations to the give path."""
+        raise NotImplementedError("Please implement a 'save' method for your 'Population' class.")
+
+    def load(self, path):
+        """Load saved representations."""
+        raise NotImplementedError("Please implement a 'load' method for your 'Population' class.")
+
+class UniformPopulation(Population):
+    """A population where agents interact with other agents with a uniform probability."""
+
+    def __init__(self, configuration):
+        #Call initialisation method of super class:
+        super().__init__(configuration)
+
+        #Get agent class from configuration
+        class_name, module_name = self.configuration['agent_class']
+        module = importlib.import_module(module_name)
+        agent_class = getattr(module, class_name)
+
+        #Create list of agents of agent_class
+        self.agents = [agent_class(self.configuration) for i in range(configuration['population_size'])]
+
+    def sample_agents(self, nr_of_agents=2):
+        """Return two randomly sampled agents from the population."""
+
+        return random.sample(self.agents, nr_of_agents)
+
+    def agent_list(self):
+        return self.agents

hermes/process.py

@@ -0,0 +1,54 @@
+###########################################
+#                                         #
+# Process.                                #
+#                                         #
+###########################################
+
+class Process:
+    """The HERMES Process class."""
+
+    def __init__(self, agent, interaction):
+        self.agent = agent
+        self.interaction = interaction
+
+
+class DescriptionProcess(Process):
+    """Given a context of entities, describe a given target entity."""
+
+    def __init__(self, agent, scene, target, interaction):
+        # Call initialisation method of super class
+        super().__init__(agent, interaction)
+
+        # Reset fields relevant to a description process upon its initialisation
+        self.scene = scene
+        self.target = target
+        self.utterance = None
+        self.applied_cxns = []
+        self.competitors = []
+
+
+    def run(self, phase):
+        """Run description process."""
+
+        self.utterance = self.agent.formulate(self.target, self.scene)
+        if self.utterance is None and phase != 'test':
+            self.utterance = self.agent.invent(self.target, self.scene)
+
+
+class PointingProcess(Process):
+    """Given an utterance in a scene, point to the referent referred to by the utterance."""
+
+    def __init__(self, agent, scene, interaction):
+        # Call initialisation method of super class
+        super().__init__(agent, interaction)
+
+        self.scene = scene
+        self.observed_utterance = None
+        self.hypothesised_target = None
+
+    def run(self, utterance):
+        """Run pointing task: comprehend utterance and retrieve entity in the scene. Return target index."""
+
+        # Set process utterance to utterance and run comprehension
+        self.observed_utterance = utterance
+        self.hypothesised_target = self.agent.comprehend(utterance, self.scene)

hermes/utils.py

@@ -0,0 +1,19 @@
+#####################################################
+#                                                   #
+# Utility funcitons for the hermes framework        #
+#                                                   #
+#####################################################
+
+import random
+
+CONSONANTS = ['b', 'c', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'm', 'n', 'p', 'q', 'r', 's', 't', 'v', 'w', 'x', 'z']
+VOWELS = ['a', 'e', 'i', 'o', 'u', 'y']
+
+def make_new_form(template=['C','V','C','V','C','V','C','V', 'C', 'V']):
+    word_characters = []
+    for type in template:
+        if type == 'C':
+            word_characters.append(random.choice(CONSONANTS))
+        else:
+            word_characters.append(random.choice(VOWELS))
+    return ''.join(word_characters)

hermes/world.py

@@ -0,0 +1,81 @@
+#####################################################
+#                                                   #
+# World                                             #
+#                                                   #
+#####################################################
+
+import random
+import numpy as np
+import hermes.globals
+import warnings
+
+class World:
+    """The HERMES world class."""
+
+    def __init__(self, configuration):
+        self.configuration = {**hermes.globals.EXPERIMENT_DEFAULT_CONFIGURATION, **configuration}
+
+    def sample_scene_with_target(self):
+        warnings.warn("Please implement the 'sample_scene_with_target' method the 'World' class.")
+    
+
+class NamingGameWorld(World):
+    """A class for naming game worlds: each entity is an individual and there are no classes."""
+
+    def __init__(self, entities, configuration):
+        """Initialize the entity world."""
+
+        # Call the initialisation method of the super class, passing on the configuration
+        super().__init__(configuration)
+
+        # Set train_entities, val_entities and test_entities
+        self.entities = entities
+
+    def sample_scene_with_target(self, configuration):
+        "Sample scene with target."
+        
+        scene_size = configuration['scene_size']
+        scene = random.sample(self.entities, scene_size)
+        target = random.choice(scene)
+        
+        return scene, target
+
+class EntityWorld(World):
+    """A class for worlds that consist of entities, where each entity belongs to a 'category' and a scene
+    typically does contain two entities of the same category."""
+
+    def __init__(self, train_entities_per_category, val_entities_per_category=None, test_entities_per_category=None, configuration={'scene_size': 5}):
+        """Create a grounded naming game world."""
+
+        super().__init__(configuration)
+
+        self.train_entities_per_category = train_entities_per_category
+        self.val_entities_per_category = val_entities_per_category
+        self.test_entities_per_category = test_entities_per_category
+
+
+    def sample_scene_with_target(self, configuration, split='train'):
+        "Sample scene with unique target."
+
+        # Choose right split
+        entities_per_category = None
+        if split == 'train':
+            entities_per_category = self.train_entities_per_category
+        elif split == 'val':
+            entities_per_category = self.val_entities_per_category
+        elif split == 'test':
+            entities_per_category = self.test_entities_per_category        
+
+        # Sample unique categories to appear in scene
+        nr_of_categories_in_world = len(entities_per_category)
+        scene_size = configuration['scene_size']
+        scene_categories = random.sample(list(range(nr_of_categories_in_world)), scene_size)
+
+        # Create scene
+        scene = []
+        for category in scene_categories:
+            scene.append(random.choice(entities_per_category[category]))
+
+        # Then sample target from scene
+        target = random.choice(scene)
+        return scene, target

hermes_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: hermes-toolkit
+Version: 0.1.0
+Summary: A toolkit for the multi-agent simulation of emergent communication and languages.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://gitlab.ai.vub.ac.be/ehai/hermes
+Project-URL: Repository, https://gitlab.ai.vub.ac.be/ehai/hermes
+Project-URL: Issues, https://gitlab.ai.vub.ac.be/ehai/hermes/-/issues
+Keywords: emergent communication,language games,language evolution,multi-agent simulation,agent-based modelling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: alive-progress
+Provides-Extra: torch
+Requires-Dist: torch; extra == "torch"
+Provides-Extra: logging
+Requires-Dist: pandas; extra == "logging"
+Provides-Extra: all
+Requires-Dist: torch; extra == "all"
+Requires-Dist: pandas; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# HERMES
+
+*A toolkit for the multi-agent simulation of emergent communication and languages.*
+
+HERMES provides the building blocks for running language games: populations of
+agents, worlds that supply the entities agents talk about, interaction scripts
+that define who says what to whom, alignment strategies that update agents after
+each interaction, and monitors that record how the emerging language develops
+over time.
+
+## Installation
+
+```bash
+pip install hermes-toolkit
+```
+
+The core framework is pure Python. Experiments with neurally grounded agents
+additionally need PyTorch, and the experiment logger needs pandas:
+
+```bash
+pip install "hermes-toolkit[all]"      # torch + pandas
+pip install "hermes-toolkit[torch]"    # torch only
+```
+
+The distribution is named `hermes-toolkit`, but the package is imported as
+`hermes`:
+
+```python
+import hermes
+from hermes.experiment import Experiment
+```
+
+## Getting started
+
+Worked examples live in [`docs/source/tutorials`](docs/source/tutorials):
+
+- `hermes_naming_game.ipynb` — a basic naming game
+- `hermes_grounded_naming_game.ipynb` — a naming game grounded in images
+- `hermes-MARL-concept-learning.ipynb` — concept learning with neural agents
+- `hermes_naming_game_pyfcg.ipynb` — integration with FCG
+
+## Core concepts
+
+| Component | Role |
+|---|---|
+| `Agent` | Holds a vocabulary and whatever machinery it needs to produce and interpret utterances |
+| `Population` | Determines which agents interact with one another |
+| `World` | Supplies the scenes and entities agents communicate about |
+| `Interaction` | The script of a single communicative exchange |
+| `Process` | One participant's contribution to an interaction (describing, pointing, drawing, ...) |
+| `AlignmentStrategy` | How agents update after success or failure |
+| `Monitor` | Records a measure over the course of an experiment |
+| `Experiment` | Ties the above together and runs series of interactions |
+
+Experiments are configured with a dictionary; each component is given as a
+`(class_name, module_name)` pair, so your own subclasses drop in without
+changing the framework.
+
+## Citation
+
+If you use HERMES in academic work, please cite it. A `CITATION.cff` file will
+be added with the first tagged release.
+
+## Contributing
+
+The `main` branch is protected — please create a feature branch for your
+contribution and open a merge request against `main`.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).

hermes_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+hermes/__init__.py,sha256=52GvXk3jf7Wi20T2qEO30ji8lUqsoX16wPj1FlaEJTo,347
+hermes/agent.py,sha256=FfvcR5JZSOZkTBPLBrNUUVj8DBEi9NTZMZR00IGAygA,1379
+hermes/alignment.py,sha256=OCv1l5qvp1msnJMqa7hcsciqAdaSkwiDACnxWOpnwnQ,293
+hermes/experiment.py,sha256=H31Cx_NNINsbnPips_m1odzfuhBz4UH7hYI0ecx6ABE,6394
+hermes/globals.py,sha256=8ZGAbqLS5kvYrit3N8mzvhROrnfaFix25t4HTh6Gco4,1801
+hermes/interaction.py,sha256=aRn6_HyLyNmj7qa_K21K0R5GLgj4FHkVRGxyP6GPsXY,5398
+hermes/logging.py,sha256=Xc5oKheVEWked-c5meIsChDRGSKsIjC4ipxjHJk0N1k,3489
+hermes/monitoring.py,sha256=UBbdsaDDIhfuamndwjmSR7-CAmVkqIPvoo2aLI303vQ,1769
+hermes/population.py,sha256=jQ2yq-8s6FFeeaHyezROfGq8KGIuGiP2daDxZG-X9WU,1835
+hermes/process.py,sha256=tifMHK-vrxwfeK9YtTfRmRDvUtk_SqJD0KtUeEDjA6c,1857
+hermes/utils.py,sha256=9eD88PZEY-tt1m3D3PC_i_S0Ok8OnHgJ7SZ2HTTdg0w,759
+hermes/world.py,sha256=rZgyQaTBudYsVr1u7UVfo8WSFMpkxnNuAxLanxY7QTM,3060
+hermes_toolkit-0.1.0.dist-info/licenses/LICENSE,sha256=zL8bSaRwYIf1q6vtu_bAHVA0BmOPekGZIui_VF4ZMoE,11344
+hermes_toolkit-0.1.0.dist-info/METADATA,sha256=N2cmpNgalOvTPH3iPt_Fd9w1dwX2VDGOFmHzhw79HnU,3943
+hermes_toolkit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+hermes_toolkit-0.1.0.dist-info/top_level.txt,sha256=1TupzjD_10P0-QWmHdzyxP4OXHKizFdjhlf91BcdH28,7
+hermes_toolkit-0.1.0.dist-info/RECORD,,

hermes_toolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hermes_toolkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Paul Van Eecke
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

hermes_toolkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hermes