core.worlds

This class defines the basic environments that define how agents interact with one another.

World(object) provides a generic parent class, including __enter__ and __exit__ statements which allow you to guarantee that the shutdown method is called and KeyboardInterrupts are less noisy (if desired).

DialogPartnerWorld(World) provides a two-agent turn-based dialog setting.

MultiAgentDialogWorld(World) provides a multi-agent setting.

MultiWorld(World) creates a set of environments (worlds) for the same agent to multitask over, a different environment will be chosen per episode.

HogwildWorld(World) is a container that creates another world within itself for every thread, in order to have separate simulated environments for each one. Each world gets its own agents initialized using the share() parameters from the original agents.

BatchWorld(World) is a container for doing minibatch training over a world by collecting batches of N copies of the environment (each with different state).

All worlds are initialized with the following parameters:

opt – contains any options needed to set up the agent. This generally contains
all command-line arguments recognized from core.params, as well as other options that might be set through the framework to enable certain modes.
agents – the set of agents that should be attached to the world,
e.g. for DialogPartnerWorld this could be the teacher (that defines the task/dataset) and the learner agent. This is ignored in the case of sharing, and the shared parameter is used instead to initalize agents.
shared (optional) – if not None, contains any shared data used to construct
this particular instantiation of the world. This data might have been initialized by another world, so that different agents can share the same data (possibly in different Processes).
class parlai.core.worlds.BatchWorld(opt, world)

Bases: parlai.core.worlds.World

Creates a separate world for each item in the batch, sharing the parameters for each. The underlying world(s) it is batching can be either DialogPartnerWorld, MultiAgentWorld, ExecutableWorld or MultiWorld.

__init__(opt, world)

Initialize self. See help(type(self)) for accurate signature.

display()

Returns a string describing the current state of the world.

Useful for monitoring and debugging. By default, display the messages between the agents.

episode_done()

Whether the episode is done or not.

epoch_done()

Whether the epoch is done or not.

Not all worlds have the notion of an epoch, but this is useful for fixed training, validation or test sets.

getID()

Return the name of the world, typically the task the world encodes.

get_total_exs()

Return total amount of examples seen by world.

parley()

The main method, that does one step of actions for the agents in the world. This is empty in the base class.

shutdown()

Shutdown each world.

class parlai.core.worlds.DialogPartnerWorld(opt, agents, shared=None)

Bases: parlai.core.worlds.World

Simple world for two agents communicating synchronously.

This basic world switches back and forth between two agents, giving each agent one chance to speak per turn and passing that back to the other one.

__init__(opt, agents, shared=None)

Initialize self. See help(type(self)) for accurate signature.

episode_done()

Only the first agent indicates when the episode is done.

epoch_done()

Only the first agent indicates when the epoch is done.

parley()

Agent 0 goes first. Alternate between the two agents.

shutdown()

Shutdown each agent.

class parlai.core.worlds.ExecutableWorld(opt, agents=None, shared=None)

Bases: parlai.core.worlds.MultiAgentDialogWorld

A world where messages from agents can be interpreted as _actions_ in the world which result in changes in the environment (are executed). Hence a grounded simulation can be implemented rather than just dialogue between agents.

__init__(opt, agents=None, shared=None)

Initialize self. See help(type(self)) for accurate signature.

execute(agent, act)

An executable world class should implement this function, otherwise the actions do not do anything (and it is the same as MultiAgentDialogWorld).

init_world()

An executable world class should implement this function, otherwise the actions do not do anything (and it is the same as MultiAgentDialogWorld).

observe(agent, act)

An executable world class should implement this function, otherwise the observations for each agent are just the messages from other agents and not confitioned on the world at all (and it is thus the same as MultiAgentDialogWorld).

parley()

For each agent: act, execute and observe actions in world

class parlai.core.worlds.HogwildProcess(tid, opt, shared, sync)

Bases: multiprocessing.context.Process

Process child used for HogwildWorld. Each HogwildProcess contain its own unique World.

__init__(tid, opt, shared, sync)

Initialize self. See help(type(self)) for accurate signature.

run()

Runs normal parley loop for as many examples as this thread can get ahold of via the semaphore queued_sem.

class parlai.core.worlds.HogwildWorld(opt, world)

Bases: parlai.core.worlds.World

Creates a separate world for each thread (process).

Maintains a few shared objects to keep track of state:

  • A Semaphore which represents queued examples to be processed. Every call of parley increments this counter; every time a Process claims an example, it decrements this counter.
  • A Condition variable which notifies when there are no more queued examples.
  • A boolean Value which represents whether the inner worlds should shutdown.
  • An integer Value which contains the number of unprocessed examples queued (acquiring the semaphore only claims them–this counter is decremented once the processing is complete).
__init__(opt, world)

Initialize self. See help(type(self)) for accurate signature.

display()

Returns a string describing the current state of the world.

Useful for monitoring and debugging. By default, display the messages between the agents.

episode_done()

Whether the episode is done or not.

epoch_done()

Whether the epoch is done or not.

Not all worlds have the notion of an epoch, but this is useful for fixed training, validation or test sets.

getID()

Return the name of the world, typically the task the world encodes.

get_total_epochs()

Return total amount of epochs on which the world has trained.

get_total_exs()

Return total amount of examples seen by world.

parley()

Queue one item to be processed.

shutdown()

Set shutdown flag and wake threads up to close themselves.

class parlai.core.worlds.MultiAgentDialogWorld(opt, agents, shared=None)

Bases: parlai.core.worlds.World

Basic world where each agent gets a turn in a round-robin fashion, receiving as input the actions of all other agents since that agent last acted.

__init__(opt, agents, shared=None)

Initialize self. See help(type(self)) for accurate signature.

episode_done()

Whether the episode is done or not.

epoch_done()

Whether the epoch is done or not.

Not all worlds have the notion of an epoch, but this is useful for fixed training, validation or test sets.

parley()

For each agent, get an observation of the last action each of the other agents took. Then take an action yourself.

shutdown()

Shutdown each agent.

class parlai.core.worlds.MultiWorld(opt, agents=None, shared=None, default_world=None)

Bases: parlai.core.worlds.World

Container for a set of worlds where each world gets a turn in a round-robin fashion. The same user_agents are placed in each, though each world may contain additional agents according to the task that world represents.

__init__(opt, agents=None, shared=None, default_world=None)

Initialize self. See help(type(self)) for accurate signature.

display()

Returns a string describing the current state of the world.

Useful for monitoring and debugging. By default, display the messages between the agents.

epoch_done()

Whether the epoch is done or not.

Not all worlds have the notion of an epoch, but this is useful for fixed training, validation or test sets.

get_acts()

Return the last act of each agent.

get_agents()

Return the list of agents.

parley()

The main method, that does one step of actions for the agents in the world. This is empty in the base class.

class parlai.core.worlds.World(opt, agents=None, shared=None)

Bases: object

Empty parent providing null definitions of API functions for Worlds. All children can override these to provide more detailed functionality.

__init__(opt, agents=None, shared=None)

Initialize self. See help(type(self)) for accurate signature.

display()

Returns a string describing the current state of the world.

Useful for monitoring and debugging. By default, display the messages between the agents.

episode_done()

Whether the episode is done or not.

epoch_done()

Whether the epoch is done or not.

Not all worlds have the notion of an epoch, but this is useful for fixed training, validation or test sets.

getID()

Return the name of the world, typically the task the world encodes.

get_acts()

Return the last act of each agent.

get_agents()

Return the list of agents.

get_time()

Return total training time

get_total_epochs()

Return total amount of epochs on which the world has trained.

get_total_exs()

Return total amount of examples seen by world.

parley()

The main method, that does one step of actions for the agents in the world. This is empty in the base class.

shutdown()

Perform any cleanup, if appropriate.

update_counters()

Update how many epochs have completed

parlai.core.worlds.create_task(opt, user_agents, default_world=None)

Creates a world + task_agents (aka a task) assuming opt['task']="task_dir:teacher_class:options" e.g. "babi:Task1k:1" or "#babi-1k" or "#QA", see parlai/tasks/tasks.py and see parlai/tasks/task_list.py for list of tasks.

parlai.core.worlds.override_opts_in_shared(table, overrides)

Looks recursively for opt dictionaries within shared dict and overrides any key-value pairs with pairs from the overrides dict.

parlai.core.worlds.validate(observation)

Make sure the observation table is valid, or raise an error.