parlai.chat_service

ParlAI’s chat service functionality.

Chat Service Core

parlai.chat_service.core.agents

class parlai.chat_service.core.agents.ChatServiceAgent(opt, manager, receiver_id, task_id)

Bases: Agent, ABC

Base class for a person on a chat serivce that can act in a ParlAI world.

__init__(opt, manager, receiver_id, task_id)

property data

ChatServiceAgent data property.

abstract observe(act)

Send an agent a message through the manager.

abstract put_data(message)

Put data into the message queue if it hasn’t already been seen.

set_stored_data()

Gets agent state data from manager.

get_new_act_message()

Get a new act message if one exists, return None otherwise.

act()

Pulls a message from the message queue.

If none exist returns None.

act_blocking(timeout=None)

Repeatedly loop until we retrieve a message from the queue.

episode_done()

Return whether or not this agent believes the conversation to be done.

parlai.chat_service.core.core.chat_service_manager

class parlai.chat_service.core.chat_service_manager.AgentState(service_id: int, overworld_agent: ChatServiceAgent)

Bases: object

Keep track of Agent State.

State includes which is the “active” agent - i.e., which agent in which world do we message, etc.

__init__(service_id: int, overworld_agent: ChatServiceAgent)

get_active_agent() → ChatServiceAgent

Return active messenger agent.

Returns

a ChatServiceAgent, which corresponds to the active agent for this agent state.

set_active_agent(active_agent: ChatServiceAgent)

Set active agent for this agent.

Parameters

active_agent – A ChatServiceAgent, the new active agent for this given agent state

get_overworld_agent() → ChatServiceAgent

Return overworld messenger agent.

Returns

a ChatServiceAgent, which corresponds agent object in the overworld

get_id() → int

Return the agent’s ID.

Returns

int agent’s service ID

has_task(task_id: str) → bool

Determine if an agent is in a task.

Parameters

task_id – task id

Returns

if agent is in that task.

get_agent_for_task(task_id: str) → Optional[ChatServiceAgent]

Return ChatServiceAgent for given task id.

For each “player”, a separate agent is created for each task. This returns the appropriate MessengerAgent given the task id

Parameters

task_id – task id

Returns

ChatServiceAgent object associated with the given task

assign_agent_to_task(agent: ChatServiceAgent, task_id: str)

Mark agent in task.

Parameters

• agent – ChatServiceAgent object to mark in task

• task_id – string task name

class parlai.chat_service.core.chat_service_manager.ChatServiceManager(opt: Opt)

Bases: ABC

class ChatServiceMessageSender

Bases: ABC

ChatServiceMessageSender is a wrapper around requests that simplifies the the process of sending content.

abstract send_read(receiver_id: int)

Send read receipt to agent at receiver_id.

abstract typing_on(receiver_id: int, persona_id: Optional[str] = None)

Send typing on msg to agent at receiver_id.

__init__(opt: Opt)

Create a ChatServiceManager using the given setup options.

abstract parse_additional_args(opt: Opt)

Parse any other service specific args here.

abstract restructure_message(message: Dict[str, Any]) → Dict[str, Any]

Use this function to restructure the message into the provided format.

returns the appropriate message.

add_agent_to_pool(agent: AgentState, world_type: str = 'default')

Add the agent to pool.

Parameters

• agent – AgentState object

• world_type – Name of world whose pool should now contain agent

remove_agent_from_pool(agent: AgentState, world_type: str = 'default', mark_removed: bool = True)

Remove agent from the pool.

Parameters

• agent – AgentState object

• world_type – world name

• mark_removed – whether to mark an agent as removed from the pool

get_agent_state(agent_id: int) → Optional[AgentState]

Return agent state.

Parameters

agent_id – agent identifier

Returns

AgentState object if agent_id is being tracked, else None

abstract setup_server()

Prepare the Chat Service server for handling messages.

abstract setup_socket()

Set up socket to start communicating to workers.

init_new_state()

Prepare for new run.

Initialize everything in the agent, task, and thread states

start_new_run()

Begin new run.

check_timeout_in_pool(world_type: str, agent_pool: List[AgentState], max_time_in_pool: int, backup_task: Optional[str] = None)

Check for timed-out agents in pool.

Parameters

• world_type – world type

• agent_pool – list of AgentStates

• max_time_in_pool – maximum time allowed for agent to be in pool

• backup_task – backup_task to start if we reach a timeout in the original pool

start_task()

Begin handling task.

Periodically check to see when enough agents are in the agent pool to start an instance of the task. Continue doing this until the desired number of conversations is had.

shutdown()

Handle any client shutdown cleanup.

abstract observe_message(receiver_id: int, text: str, quick_replies: Optional[List[str]] = None, persona_id: Optional[str] = None)

Send a message through the message manager.

Parameters

• receiver_id – identifier for agent to send message to

• text – text to send

• quick_replies – list of quick replies

• persona_id – identifier of persona

mark_removed(agent_id: int, pageid: int)

Mark the agent as removed from the pool.

Can be overriden to change other metadata linked to agent removal.

Parameters

• agent_id – int agent psid

• pageid – int page id

after_agent_removed(agent_id: int)

Perform any changes to metadata on agent removal.

override if extra bookkeeping must be done when removing agent

observe_payload(receiver_id: str, data: Dict[Any, Any], quick_replies: Optional[List[str]] = None, persona_id: Optional[str] = None)

Send a payload through the message manager.

Parameters

• receiver_id – int identifier for agent to send message to

• data – object data to send

• quick_replies – list of quick replies

• persona_id – identifier of persona

upload_attachment(payload: Dict[str, str]) → str

Upload an attachment and return an attachment ID.

Parameters

payload –

dict with the following format:

{‘type’: <TYPE>, ‘url’: <URL>} or {‘type’: <TYPE>, ‘filename’: <FILENAME>, ‘format’: <FILEFORMAT>}. For example, {‘type’: ‘image’, ‘filename’: ‘test.png’, ‘format’: ‘png’}

Returns

attachment id associated with attachment.

parlai.chat_service.core.socket

class parlai.chat_service.core.socket.ChatServiceMessageSocket(server_url, port, message_callback)

Bases: object

ChatServiceMessageSocket is a wrapper around websocket to forward messages from the remote server to the ChatServiceManager.

__init__(server_url, port, message_callback)

server_url: url at which the server is to be run port: port for the socket to operate on message_callback: function to be called on incoming message objects (format: message_callback(self, data))

parlai.chat_service.core.world_runner

class parlai.chat_service.core.world_runner.ChatServiceWorldRunner(opt, world_path, max_workers, manager, is_debug=False)

Bases: object

World Runner.

Launches worlds, overworlds, etc. Helper for ChatServiceManager.

__init__(opt, world_path, max_workers, manager, is_debug=False)

shutdown()

Shutdown the world runner.

launch_task_world(task_name, world_name, agents)

Launch a task world.

Return the job’s future.

Parameters

• task_name – string. the name of the job thread

• world_name – string. the name of the task world in the module file

• agents – list. the list of agents to install in the world

Returns

the Futures object corresponding to this launched task

launch_overworld(task_name, overworld_name, onboard_map, overworld_agent)

Launch an overworld and a subsequent onboarding world.

Return the job’s future

Parameters

• task_name – string. the name of the job thread

• overworld_name – string. the name of the overworld in the module file

• onboard_map – map. a mapping of overworld return values to the names of onboarding worlds in the module file.

• overworld_agent – The agent to run the overworld with

Returns

the Futures object corresponding to running the overworld

Services

Browser Chat

parlai.chat_service.services.browser_chat.agents

class parlai.chat_service.services.browser_chat.agents.BrowserAgent(opt, manager, receiver_id, task_id)

Bases: WebsocketAgent

parlai.chat_service.services.browser_chat.browser_manager

class parlai.chat_service.services.browser_chat.browser_manager.BrowserManager(opt)

Bases: WebsocketManager

Chat Service manager that runs chat service tasks using a local browser to send and receive messages.

Messenger

parlai.chat_service.services.messenger.agents

class parlai.chat_service.services.messenger.agents.MessengerAgent(opt, manager, task_id, receiver_id, page_id)

Bases: ChatServiceAgent

Base class for a person on messenger that can act in a ParlAI world.

__init__(opt, manager, task_id, receiver_id, page_id)

observe(act)

Send an agent a message through the mturk manager.

observe_typing_on(persona_id=None)

Allow agent to observe typing indicator.

put_data(messenger_data)

Put data into the message queue if it hasn’t already been seen.

act(timeout=None)

Pulls a message from the message queue.

If none exist returns None unless the timeout has expired.

shutdown()

Perform any final cleanup if needed.

parlai.chat_service.services.messenger.message_sender

parlai.chat_service.services.messenger.message_sender.create_attachment(payload)

Create a simple url-based attachment.

parlai.chat_service.services.messenger.message_sender.create_reply_option(title, payload='')

Create a quick reply option.

Takes in display title and optionally extra custom data.

parlai.chat_service.services.messenger.message_sender.create_text_message(text, quick_replies=None)

Return a list of text messages from the given text.

If the message is too long it is split into multiple messages. quick_replies should be a list of options made with create_reply_option.

parlai.chat_service.services.messenger.message_sender.create_attachment_message(attachment_item, quick_replies=None)

Create a message list made with only an attachment.

quick_replies should be a list of options made with create_reply_option.

class parlai.chat_service.services.messenger.message_sender.MessageSender(secret_token)

Bases: object

MesageSender is a wrapper around the facebook messenger requests that simplifies the process of sending content.

__init__(secret_token)

server_url: url at which the server is to be run port: port for the socket to operate on message_callback: function to be called on incoming message objects (format: message_callback(self, data))

send_fb_payload(receiver_id, payload, quick_replies=None, persona_id=None)

Sends a payload to messenger, processes it if we can.

send_fb_message(receiver_id, message, is_response, quick_replies=None, persona_id=None)

Sends a message directly to messenger.

create_persona(name, image_url)

Creates a new persona and returns persona_id.

delete_persona(persona_id)

Deletes the persona.

upload_fb_attachment(payload)

Uploads an attachment using the Attachment Upload API and returns an attachment ID.

parlai.chat_service.services.messenger.messenger_manager

Messenger Manager Module.

Contains implementation of the MessengerManager, which helps run ParlAI via FB Messenger.

class parlai.chat_service.services.messenger.messenger_manager.MessengerManager(opt)

Bases: ChatServiceManager

Manages interactions between agents on messenger as well as direct interactions between agents and the messenger overworld.

__init__(opt)

Create an MessengerManager using the given setup options.

parse_additional_args(opt)

Parse any other service specific args here.

restructure_message(message)

Use this function to restructure the message into the provided format.

returns the appropriate message.

mark_removed(agent_id, pageid)

Mark the agent as removed from the pool.

Can be overridden to change other metadata linked to agent removal.

Parameters

• agent_id – int agent psid

• pageid – int page id

after_agent_removed(agent_id)

Perform any changes to metadata on agent removal.

override if extra bookkeeping must be done when removing agent

setup_server()

Prepare the Messenger server for handling messages.

get_app_token()

Find and return an app access token.

setup_socket()

Set up socket to start communicating to workers.

observe_message(receiver_id, text, quick_replies=None, persona_id=None)

Send a message through the message manager.

Parameters

• receiver_id – int identifier for agent to send message to

• text – string text to send

• quick_replies – list of quick replies

• persona_id – identifier of persona

observe_payload(receiver_id, data, quick_replies=None, persona_id=None)

Send a payload through the message manager.

Parameters

• receiver_id – int identifier for agent to send message to

• data – object data to send

• quick_replies – list of quick replies

• persona_id – identifier of persona

upload_attachment(payload)

Upload an attachment and return an attachment ID.

Parameters

payload –

dict with the following format:

{‘type’: <TYPE>, ‘url’: <URL>} or {‘type’: <TYPE>, ‘filename’: <FILENAME>, ‘format’: <FILEFORMAT>}. For example, {‘type’: ‘image’, ‘filename’: ‘test.png’, ‘format’: ‘png’}

parlai.chat_service.services.messenger.worlds

class parlai.chat_service.services.messenger.worlds.SimpleMessengerOverworld(opt, agent)

Bases: World

Passthrough world to spawn task worlds of only one type.

Demos of more advanced overworld functionality exist in the overworld demo

__init__(opt, agent)

episode_done()

Whether the episode is done or not.

parley()

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

This is empty in the base class.

class parlai.chat_service.services.messenger.worlds.OnboardWorld(opt, agent)

Bases: World

__init__(opt, agent)

parley()

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

This is empty in the base class.

episode_done()

Whether the episode is done or not.

shutdown()

Perform any cleanup, if appropriate.

Terminal Chat

parlai.chat_service.services.terminal_chat.agents

class parlai.chat_service.services.terminal_chat.agents.TerminalAgent(opt, manager, receiver_id, task_id)

Bases: WebsocketAgent

parlai.chat_service.services.terminal_chat.terminal_manager

class parlai.chat_service.services.terminal_chat.terminal_manager.TerminalManager(opt)

Bases: WebsocketManager

Chat Service manager that runs chat service tasks using terminal to send and receive messages.

Websocket

parlai.chat_service.services.websocket.agents

class parlai.chat_service.services.websocket.agents.WebsocketAgent(opt, manager, receiver_id, task_id)

Bases: ChatServiceAgent

Class for a person that can act in a ParlAI world via websockets.

__init__(opt, manager, receiver_id, task_id)

observe(act)

Send an agent a message through the websocket manager.

Only attachments of type image are currently supported. In the case of images, the resultant message will have a text field which will be a base 64 encoded image and mime_type which will be an image mime type.

Args:

act: dict. If act contain an payload key, then a dict should be

provided for the value in payload. Otherwise, act should be a dict with the key text for the message. For the pyaload dict, this agent expects a type key, which specifies whether or not the attachment is an image. If the attachment is an image, a data key must be specified with a base 64 encoded image. A quick_replies key can be provided with a list of string quick replies for any message

put_data(message)

Put data into the message queue.

Args:

message: dict. An incoming websocket message. See the chat_services

README for the message structure.

parlai.chat_service.services.websocket.sockets

class parlai.chat_service.services.websocket.sockets.MessageSocketHandler(*args, **kwargs)

Bases: WebSocketHandler

__init__(*args, **kwargs)

open()

Opens a websocket and assigns a random UUID that is stored in the class-level subs variable.

on_close()

Runs when a socket is closed.

on_message(message_text)

Callback that runs when a new message is received from a client See the chat_service README for the resultant message structure.

Args:

message_text: A stringified JSON object with a text or attachment key.

text should contain a string message and attachment is a dict. See WebsocketAgent.put_data for more information about the attachment dict structure.

check_origin(origin)

Override to enable support for allowing alternate origins.

The origin argument is the value of the Origin HTTP header, the url responsible for initiating this request. This method is not called for clients that do not send this header; such requests are always allowed (because all browsers that implement WebSockets support this header, and non-browser clients do not have the same cross-site security concerns).

Should return True to accept the request or False to reject it. By default, rejects all requests with an origin on a host other than this one.

This is a security protection against cross site scripting attacks on browsers, since WebSockets are allowed to bypass the usual same-origin policies and don’t use CORS headers.

Warning

This is an important security measure; don’t disable it without understanding the security implications. In particular, if your authentication is cookie-based, you must either restrict the origins allowed by check_origin() or implement your own XSRF-like protection for websocket connections. See these articles for more.

To accept all cross-origin traffic (which was the default prior to Tornado 4.0), simply override this method to always return True:

def check_origin(self, origin):
    return True

To allow connections from any subdomain of your site, you might do something like:

def check_origin(self, origin):
    parsed_origin = urllib.parse.urlparse(origin)
    return parsed_origin.netloc.endswith(".mydomain.com")

New in version 4.0.

parlai.chat_service.services.websocket.websocket_manager

Websocket Manager Module Contains implementation of the WebsocketManager which helps run ParlAI via websockets.

class parlai.chat_service.services.websocket.websocket_manager.WebsocketManager(opt)

Bases: ChatServiceManager

Manages interactions between agents on a websocket as well as direct interactions between agents and an overworld.

class MessageSender

Bases: ChatServiceMessageSender

send_read(receiver_id)

Send read receipt to agent at receiver_id.

typing_on(receiver_id, persona_id=None)

Send typing on msg to agent at receiver_id.

__init__(opt)

Create a WebsocketManager using the given setup options.

parse_additional_args(opt)

Parse any other service specific args here.

start_task()

Begin handling task.

shutdown()

Defined to shutown the tornado application.

observe_message(socket_id, message, quick_replies=None)

Send a message through the message manager.

Parameters

• socket_id – int identifier for agent socket to send message to

• message – (str) message to send through the socket.

• quick_replies – (list) list of strings to send as quick replies.

Returns a tornado future for tracking the write_message action.

observe_payload(socket_id, payload, quick_replies=None)

Send a message through the message manager.

Parameters

• socket_id – int identifier for agent socket to send message to

• payload –

  (dict) payload to send through the socket. The mandatory keys are:

  ’type’: (str) Type of the payload (e.g. ‘image’) ‘data’: str. base64 encoded content If ‘type’ is ‘image’, the ‘mime_type’ (str) key can be provided to specify the Mime type of the image

Returns a tornado future for tracking the write_message action.

restructure_message(message)

This is to restructure a new message to conform to the message structure defined in the chat_service README.

setup_server()

Prepare the Chat Service server for handling messages.

setup_socket()

Set up socket to start communicating to workers.

Utilities

parlai.chat_service.utils.config

Config Utils.

class parlai.chat_service.utils.config.WorldConfig(world_name, onboarding_name, task_name, max_time_in_pool, agents_required, backup_task)

Bases: tuple

agents_required

Alias for field number 4

backup_task

Alias for field number 5

max_time_in_pool

Alias for field number 3

onboarding_name

Alias for field number 1

task_name

Alias for field number 2

world_name

Alias for field number 0

parlai.chat_service.utils.config.parse_configuration_file(config_path)

Read the config file for an experiment to get ParlAI settings.

Parameters

config_path – path to config

Returns

parsed configuration dictionary

parlai.chat_service.utils.image

Image-based utils for chat services.

class parlai.chat_service.utils.image.ImageLicense(username: str, image_url: str, image_license: str, image_license_url: str)

Bases: object

Representation of image license information.

__init__(username: str, image_url: str, image_license: str, image_license_url: str)

class parlai.chat_service.utils.image.ImageInformation(image_id: str, image_location_id: str, image: Union[PIL.Image, str])

Bases: object

Representation of image information.

__init__(image_id: str, image_location_id: str, image: Union[PIL.Image, str])

When image is str, it is a serialized; need to deserialize.

offload_state() → Dict[str, str]

Return serialized state.

Return state_dict

serialized state that can be used in json.dumps

class parlai.chat_service.utils.image.ImageFeaturesGenerator(opt: Opt, shared: Optional[TShared] = None)

Bases: object

Features generator for images.

Uses ParlAI Image Loader.

__init__(opt: Opt, shared: Optional[TShared] = None)

get_image_features(image_id: str, image: PIL.Image) → Tensor

Get image features for given image id and Image.

Parameters

• image_id – id for image

• image – PIL Image object

Return image_features

Image Features Tensor

exception parlai.chat_service.utils.image.ObjectionableContentError

Bases: Exception

Error if an image is objectionable.

parlai.chat_service.utils.logging

Logging utils for Chat Services.

parlai.chat_service.utils.misc

Miscellaneous utils for chat services.

class parlai.chat_service.utils.misc.TaskState(task_name, world_name, agents, is_overworld=False, world_type=None)

Bases: object

Wrapper for an agent running on a Worker.

__init__(task_name, world_name, agents, is_overworld=False, world_type=None)

parlai.chat_service.utils.misc.get_world_module(world_path)

Import the module specified by the world_path.

parlai.chat_service.utils.misc.get_world_fn_attr(world_module, world_name, fn_name, raise_if_missing=True)

Import and return the function from world.

Parameters

• world_module – module. a python module encompassing the worlds

• world_name – string. the name of the world in the module

• fn_name – string. the name of the function in the world

• raise_if_missing – bool. if true, raise error if function not found

Returns

the function, if defined by the world.

parlai.chat_service.utils.misc.get_eligibility_fn(world_module, world_name)

Get eligibility function for a world.

Parameters

• world_module – module. a python module encompassing the worlds

• world_name – string. the name of the world in the module

Returns

the eligibility function if available, else None

parlai.chat_service.utils.misc.get_assign_roles_fn(world_module, world_name)

Get assign roles function for a world.

Parameters

• world_module – module. a python module encompassing the worlds

• world_name – string. the name of the world in the module

Returns

the assign roles function if available, else None

parlai.chat_service.utils.misc.default_assign_roles_fn(agents)

Assign agent role.

Default role assignment.

Param

list of agents

class parlai.chat_service.utils.misc.SafetyDetectionResult(value)

Bases: Enum

Result of identfying offensive language in a response.

SAFE: the message is safe BLOCKLIST: the message contains a word from the blocklist UNSAFE: the message is deemed unsafe by the safety classifier

class parlai.chat_service.utils.misc.ReportResult(value)

Bases: Enum

Result of filing a report.

FAILURE: a player timed out while reporting, or it was an accidental report BLOCK: a player is blocked, for having been reported > 1 times SUCCESS: a successful report BOT: the offending agent was the bot

class parlai.chat_service.utils.misc.UploadImageResult(value)

Bases: Enum

Result of uploading an image.

SUCCESS: user successfully uploaded an image OBJECTIONABLE: the image contains objectionable content ERROR: there was an error

class parlai.chat_service.utils.misc.PersonalInfoDetector

Bases: object

Detects whether a string contains any of the following personal information datapoints using regular expressions:

• credit card

• phone number

• email

• SSN

__init__()

class parlai.chat_service.utils.misc.DictFrequencies(freqs)

Bases: object

Dict freqs.

__init__(freqs)

parlai.chat_service.utils.server

parlai.chat_service.utils.timeout

class parlai.chat_service.utils.timeout.TimeoutUtils

Bases: object

Provide interface for getting an agent’s act with timeout.

static get_timeout_act(agent: Agent, timeout: int = 120, quick_replies: Optional[List[str]] = None) → Optional[Message]

Return an agent’s act, with a specified timeout.

Parameters

• agent – Agent who is acting

• timeout – how long to wait

• quick_replies – If given, agent’s message MUST be one of the quick replies

Returns

An act dictionary if no timeout; else, None