Scenarios#

What is a Scenario?#

A scenario contains the specification and implementation of all of the elements of a classification task in which we want to train agents. An example of such a task is the code validation problem, where a problem statement together with a purported solution is given, and the task is to determine whether the solution is correct.

The main components of a scenario are:

  • Datasets. The train and test datasets, which contain all instances of the task.

  • Environment. The environment in which the agents interact. Crucially, this specifies the message space in which agents exchange messages.

  • Agents. The agents that interact in the environment. These should be trainable models that take as input a task instance and the sequence of messages exchanged so far, and output a message to send to the other agent, and potentially a decision.

TensorDict or Pure Text Scenario?#

There are two types of scenario depending on how the agent models are implemented.

  1. :term:`TensorDict`-based scenarios. These scenarios are those where the agents are locally run neural networks, so we need to pass around PyTorch tensors. The data structures used are based on PyTorch’s TensorDict objects. The environment and agents are based on TorchRL components.

  2. Pure text scenarios. These scenarios are those where the agents are text-based models accessed by an API. In this case we need to pass around strings, rather than tensors. The data structures used are similar to TensorDict, but contain nested dictionaries of Numpy string arrays, as implemented in the NestedArrayDict class.

The trainer used must be compatible with the scenario type. See TensorDict or Pure Text Trainer? for more information.

Base Classes#

Base classes for all elements that make up a scenario are found in the nip.scenario_base module. This contains the following sub-modules:

nip.scenario_base.data

Base classes for handling data.

nip.scenario_base.environment

Base class for the RL environment.

nip.scenario_base.agents

Base classes for building agents.

nip.scenario_base.pretrained_models

Base classes for dealing with pretrained models for transfer learning.

nip.scenario_base.rollout_analysis

Base classes for analysing rollouts.

nip.scenario_base.rollout_samples

Base class for rollouts sampled during a run and saved to W&B.

Available Scenarios#

Implementations of scenarios are placed in their own modules. The following scenarios are available:

nip.graph_isomorphism

All components for the graph isomorphism task.

nip.image_classification

All components for the image classification task.

nip.code_validation

All components for the code validation task.

Scenario Hyper-Parameters#

Each scenario may have its own hyper-parameters, which are sub-parameter objects living in the main HyperParameters object. See nip.parameters.scenario for more information.

How scenarios get instantiated (nip.factory)#

Every scenario implementation registers its derived classes with nip.factory.register_scenario_class(). When the experiment gets run the nip.factory.build_scenario_instance() function is called, which creates instances of the classes defined in the scenario, according to some initialisation logic. These instances are stored in a nip.factory.ScenarioInstance object, which is passed to the trainer.

nip.factory

A factory function for the components of an experiment scenario.