parlai.core.agents

Common Abstract classes for many agents.

This module provides a set of basic agents:

Agent(object) base class for all other agents, implements the observe() method which receives an observation/action dict and the act() method which returns a dict in response.

Teacher(Agent) also implements the report() method for returning metrics. All ParlAI tasks implement the Teacher class.

MultiTaskTeacher(Teacher) creates a set of teachers based on a task string passed to the Teacher, creating multiple teachers within it and alternating between them.

All agents 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.

shared (optional) – if not None, contains any shared data used to construct this particular instantiation of the agent. This data might have been initialized by another agent, so that different agents can share the same data (possibly in different Processes).

This module also provides a utility method:

create_task_agents(str): instantiate task-specific agents (e.g. a teacher) from a given task string (e.g. ‘babi:task1k:1’ or ‘squad’). Used by MultiTaskTeacher.

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

Bases: object

Base class for all other agents.

__init__(opt: Opt, shared=None)

observe(observation)

Receive an observation/action dict.

act()

Return an observation/action dict based upon given observation.

getID()

Return the agent ID.

epoch_done()

Return whether the epoch is done or not.

Return type

boolean

reset()

Reset the agent, clearing its observation.

Many subclasses implement additional reset logic.

reset_metrics()

Reset any metrics reported by this agent.

This is called to indicate metrics should start fresh, and is typically called between loggings or after a report().

save(path=None)

Save any parameters needed to recreate this agent from loaded parameters.

Default implementation is no-op, but many subagents implement this logic.

clone()

Make a shared copy of this agent.

Should be the same as using create_agent_from_shared(.), but slightly easier.

share()

Share any parameters needed to create a shared version of this agent.

Default implementation shares the class and the opt, but most agents will want to also add model weights, teacher data, etc. This especially useful for avoiding providing pointers to large objects to all agents in a batch.

shutdown()

Perform any final cleanup if needed.

respond(text_or_message: Union[str, Message], **other_message_fields) → str

An agent convenience function which calls the act() and provides a string response to a text or message field.

Parameters

• text_or_message (Union[str, Message]) – A string for the ‘text’ field or a message which MUST comprise of the ‘text’ field apart from other fields.

• other_message_fields (kwargs) – Provide fields for the message in the form of keyword arguments.

Returns

Agent’s response to the message.

Return type

str

batch_respond(messages: List[Message]) → List[str]

An agent convenience function which calls the batch_act() and provides a batch response to a list of messages.

Parameters

messages (List[Message]) – A list of messages each of which MUST comprise of the ‘text’ field apart from other fields.

Returns

Agent’s batch response to the messages.

Return type

List[str]

classmethod upgrade_opt(opt_from_disk: Opt)

Upgrade legacy options when loading an opt file from disk.

This is primarily made available to provide a safe space to handle backwards-compatible behavior. For example, perhaps we introduce a new option today, which wasn’t previously available. We can have the argument have a new default, but fall back to the “legacy” compatibility behavior if the option doesn’t exist.

upgrade_opt provides an opportunity for such checks for backwards compatibility. It is called shortly after loading the opt file from disk, and is called before the Agent is initialized.

Other possible examples include:

1. Renaming an option,

2. Deprecating an old option,

3. Splitting coupled behavior, etc.

Implementations of upgrade_opt should conform to high standards, due to the risk of these methods becoming complicated and difficult to reason about. We recommend the following behaviors:

1. upgrade_opt should only be used to provide backwards compatibility. Other behavior should find a different location. 2. Children should always call the parent’s upgrade_opt first. 3. upgrade_opt should always warn when an option was overwritten. 4. Include comments annotating the date and purpose of each upgrade. 5. Add an integration test which ensures your old work behaves appropriately.

Parameters

opt_from_disk (Opt) – The opt file, as loaded from the .opt file on disk.

Returns

The modified options

Return type

Opt

parlai.core.agents.compare_init_model_opts(opt: Opt, curr_opt: Opt)

Print loud warning when init_model opts differ from previous configuration.

parlai.core.agents.create_agent_from_model_file(model_file, opt_overrides=None)

Load agent from model file if it exists.

Parameters

opt_overrides – An optional dict of option overrides can also be provided.

Returns

The agent

parlai.core.agents.create_agent_from_opt_file(opt: Opt)

Load agent options and module from file if opt file exists.

Checks to see if file exists opt[‘model_file’] + “.opt”; if so, load up the options from the file and use that to create an agent, loading the model type from that file and overriding any options specified in that file when instantiating the agent.

If that file does not exist, return None.

parlai.core.agents.create_agent(opt: Opt, requireModelExists=False)

Create an agent from the options model, model_params and model_file.

The input is either of the form parlai.agents.ir_baseline.agents:IrBaselineAgent (i.e. the path followed by the class name) or else just ir_baseline which assumes the path above, and a class name suffixed with ‘Agent’.

If model-file is available in the options this function can also attempt to load the model from that location instead. This avoids having to specify all the other options necessary to set up the model including its name as they are all loaded from the options file if it exists (the file opt[‘model_file’] + ‘.opt’ must exist and contain a pickled or json dict containing the model’s options).

parlai.core.agents.create_agent_from_shared(shared_agent)

Instantiate an agent from the default shared params.

Parameters

shared_agent – should include an opt dictionary and agent class, along with whatever other parameters the agent needs to instantiate.

parlai.core.agents.create_agents_from_shared(shared)

Create agents based on shared data.

Parameters

shared – list of dict objects created by calling e.g. [a.share() for a in agents].

Returns a list of instantiated agents.