parlai.core.worlds

Worlds are the basic environments which 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.

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.

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

class parlai.core.worlds.World(opt: 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: Opt, agents=None, shared=None)

parley()

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

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

share()

Share the world.

clone()

Create a duplicate of the world.

get_agents()

Return the list of agents.

get_task_agent()

Return task agent, if applicable.

get_model_agent()

Return model agent, if applicable.

get_acts()

Return the last act of each agent.

get_time()

Return total training time.

get_total_exs()

Return total amount of examples seen by world.

get_total_epochs()

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

get_total_parleys()

Return total number of parleys.

num_examples()

Return the number of examples.

Always 0 in the abstract world.

num_episodes()

Return the number of episodes.

Always 0 in the abstract world.

reset()

Reset all agents in the world, and world statistics.

reset_agents()

Reset all agents in the world.

reset_metrics()

Reset metrics for all agents.

shutdown()

Perform any cleanup, if appropriate.

update_counters()

Update how many epochs have completed.

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

Bases: 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.

classmethod add_cmdline_args(parser: ParlaiParser, partial_opt: Optional[Opt] = None) → ParlaiParser

Return the parser as-is.

Self-chat-specific world flags can be added here.

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

get_task_agent()

Return task agent.

get_model_agent()

Return model agent, if applicable.

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.

report()

Report all metrics of all subagents.

num_examples()

Return number of examples.

num_episodes()

Return number of episodes.

shutdown()

Shutdown each agent.

update_counters()

Ensure all counters are synchronized across threads.

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

Bases: World

Basic world where each agent gets a turn in a round-robin fashion.

Each agent receives as input the actions of all other agents since its last act().

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

parley()

Perform a turn for every agent.

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

get_task_agent()

Return task agent.

get_model_agent()

Return model agent.

epoch_done()

Return if the epoch is done for any subagent.

episode_done()

Return if the episode is done for any subagent.

report()

Report metrics for all subagents.

shutdown()

Shutdown each agent.

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

Bases: World

Container for multiple worlds.

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: Opt, agents=None, shared=None, default_world=None)

num_examples()

Return sum of each subworld’s number of examples.

num_episodes()

Return sum of each subworld’s number of episodes.

get_agents()

Return the agents in the current subworld.

get_task_agent()

Not possible/well-defined in this setting.

get_model_agent()

Not implemented.

get_acts()

Return the acts in the current subworld.

share()

Share all the subworlds.

epoch_done()

Return if all the subworlds are done.

parley_init()

Update the current subworld.

If we are in the middle of an episode, keep the same world and finish this episode. If we have finished this episode, pick a new world (either in a random or round-robin fashion).

parley()

Parley the current subworld.

display()

Display all subworlds.

report()

Report aggregate metrics across all subworlds.

reset()

Reset all subworlds.

reset_metrics()

Reset metrics in all subworlds.

update_counters()

Update how many epochs have completed.

class parlai.core.worlds.BatchWorld(opt: Opt, world)

Bases: World

BatchWorld contains many copies of the same world.

Create 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, or MultiWorld.

__init__(opt: Opt, world)

batch_observe(index, batch_actions, index_acting)

Observe corresponding actions in all subworlds.

batch_act(agent_idx, batch_observation)

Act in all subworlds.

parley()

Parley in all subworlds.

Usually with ref:batch_act and ref:batch_observe.

display()

Display the full batch.

num_examples()

Return the number of examples for the root world.

num_episodes()

Return the number of episodes for the root world.

get_total_exs()

Return the total number of processed episodes in the root world.

getID()

Return the ID of the root world.

get_agents()

Return the agents of the root world.

get_task_agent()

Return task agent of the root world.

get_model_agent()

Return model agent of the root world.

episode_done()

Return whether the episode is done.

A batch world is never finished, so this always returns False.

epoch_done()

Return if the epoch is done in the root world.

report()

Report metrics for the root world.

reset()

Reset the root world, and all copies.

reset_metrics()

Reset metrics in the root world.

shutdown()

Shutdown each world.

class parlai.core.worlds.DynamicBatchWorld(opt: Opt, world: Union[DialogPartnerWorld, MultiWorld])

Bases: World

__init__(opt: Opt, world: Union[DialogPartnerWorld, MultiWorld])

shutdown()

Shutdown each world.

reset()

Reset all agents in the world, and world statistics.

reset_metrics()

Reset metrics for all 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.

num_examples()

Return the number of examples.

Always 0 in the abstract world.

num_episodes()

Return the number of episodes.

Always 0 in the abstract world.

parley()

Perform one step of actions for the agents in the world.

This is empty in the base class.

get_total_exs()

Return total amount of examples seen by world.

get_total_epochs()

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

class parlai.core.worlds.BackgroundDriverWorld(opt: Opt, world: World)

Bases: World

__init__(opt: Opt, world: World)

reset()

Reset all subworlds.

reset_metrics()

Reset metrics in all subworlds.

get_task_agent()

Return task agent, if applicable.

get_model_agent()

Return model agent, if applicable.

num_examples()

Return the number of examples.

Always 0 in the abstract world.

num_episodes()

Return the number of episodes.

Always 0 in the abstract world.

parley()

Perform one step of actions for the agents in the world.

This is empty in the base class.

get_total_exs()

Return total amount of examples seen by world.

get_total_epochs()

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

shutdown()

Perform any cleanup, if appropriate.

class parlai.core.worlds.BackgroundWorkerDynamicBatchWorld(opt: Opt, model_agent=None, process_queue=None)

Bases: DynamicBatchWorld

__init__(opt: Opt, model_agent=None, process_queue=None)

parlai.core.worlds.create_task_world(opt: Opt, user_agents, default_world=None)

Instantiate a world with the supplied options and user agents.

(A world factory.)

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

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