Connectors

Overview

Connectors are a mechanism that allows integrating custom components into the DeepPavlov Agent's pipeline. The connectors' code is a part of Agent's container.

Types of Connectors

Connectors can be integrated into the pipeline as either a Python class or as an HTTP service. While you can freely use any of these, however, we strongly recommend you to implement large components (especially neural-network based) as HTTP services because it is better to keep Agent's container fast, lightweight and errorless. These connectors are generic; you can use them to connect your custom components into the DeepPavlov Agent's pipeline.

Python-Based

Python connector generally is a Python class with a method send. It can be either a model, neural network or rule-based, or an implementation of some transport protocols. Python Connectors block the other Agent's operations, so Python Connector as a rule-based Skill Selector is a good choice while a Python Connector as an annotator is not.

HTTP-Based

We have two different connectors for HTTP protocol as a built-in ones. Single sample and batchifying. Of course you can send a batch of samples to your model using single sample connector, but in this case you should form the batch with proper dialog formatter. Batchifying connector will form batch from samples, available at the time, but can’t guarantee actual batch size, only it’s maximum size.

Built-In Connectors

In addition to the generic connectors, we provide a number of purpose-specific connectors.

ConfidenceResponseSelectorConnector

This connector provides a simple response selection functionality. It chooses a best hypothesis based on its confidence parameter. In order to use it, you should consider a few things:

* You don't need to define a dialog formatter (if you use built-in state manager)
* You need to ensure, that all of your skills (or services with assighed ``add_hypothesis`` SM method) provides a ``confidence`` value somehow
* It returns a chosen hypothesis, so you don't need to define output formatter as well
* No special configuration parameters are needed

So the basic configuration for it is very simple:

{"response_selector": {
    "connector": {
        "protocol": "python",
        "class_name": "ConfidenceResponseSelectorConnector"
    },
    "state_manager_method": "add_bot_utterance",
    "previous_services": ["place previous skill names here"]
}}

PredefinedTextConnector

This connector can be used in order to provide a simple way to answer in time, or in case of errors in your pipeline. It returns a basic parameters, which can be used to form a proper bot utterance.

* ``text`` parameter will be a body of a bot utterance
* Additionally, you can provide an ``annotations`` parameter, in case if you need to have a certain annotations for further dialog
* There is no need to configure a dialog and response formatters

This example configuration represents simple last chance service:

{"last_chance_service": {
    "connector": {
        "protocol": "python",
        "class_name": "PredefinedTextConnector",
        "response_text": "Sorry, something went wrong inside. Please tell me, what did you say."
        "annotations": {"ner": "place your annotations here"}
    },
    "state_manager_method": "add_bot_utterance_last_chance",
    "tags": ["last_chance"]
}}

PredefinedOutputConnector

This connector is quite similar to PredefinedTextConnector. It returns a predefined values, but instead of fixed text and annotations keys, it can be configured to return any arbitrary json compatible data structure. The main purpose of this connector class is testing of pipeline routing, formatting or outputs. You can make a dummy service, which will imitate (in terms of structure) the response of desired model. This connector have only one initialisation parameter:

* ``output`` - list or dict, which will be passed to agent's callback as payload

This example configuration represents a dummy service, representing skill:

{"skill": {
    "connector": {
        "protocol": "python",
        "class_name": "PredefinedOutputConnector",
        "output": [{"text": "Hypotheses1", "confidence": 1}]
    },
    "dialog_formatter": "place your dialog formatter here",
    "response_formatter": "place your response formatter here",
    "state_manager_method": "add_hypothesis",
    "previous_services": ["list of the previous_services"]
}}

But you can imitate any skill type with this connector.

Resources

• Connectors - Agent @ ReadTheDocs