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).
parlai.core.worlds.validate(observation)

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

parlai.core.worlds.display_messages(msgs)

Returns a string describing the set of messages provided

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

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

parley()

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

getID()

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

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.

get_agents()

Return the list of agents.

get_acts()

Return the last act of each agent.

__enter__()

Empty enter provided for use with with statement.

e.g:

with World() as world:
    for n in range(10):
        n.parley()
__exit__(exc_type, exc_value, exc_traceback)

After with statement, call shutdown.

save_agents()

Saves all of the agents in the world by calling their respective save() methods.

synchronize()

Can be used to synchronize processes.

shutdown()

Performs any cleanup, if appropriate.

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

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 agent.

parley()

Agent 0 goes first. Alternate between the two agents.

episode_done()

Only the first agent indicates when the episode is done.

epoch_done()

Only the first agent indicates when the epoch is done.

shutdown()

Shutdown each agent.

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

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.

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.ExecutableWorld(opt, agents=None, shared=None)

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_world()

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

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).

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.MultiWorld(opt, agents=None, shared=None)

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.

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.

class parlai.core.worlds.BatchWorld(opt, 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.

shutdown()

Shutdown each world.

class parlai.core.worlds.HogwildProcess(tid, world, opt, agents, sem, fin, term, cnt)

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

run()

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

class parlai.core.worlds.HogwildWorld(world_class, opt, agents)

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).
parley()

Queue one item to be processed.

synchronize()

Sync barrier: will wait until all queued examples are processed.

shutdown()

Set shutdown flag and wake threads up to close themselves

parlai.core.worlds.create_task(opt, user_agents)

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.