Text.Sentiment.Backend behaviour (Text v0.5.0)

Behaviour for sentiment-analysis backends.

Two backends are shipped with text:

Text.Sentiment.Backends.Lexicon (default) — fast, deterministic, multilingual lexicon-based scoring. Always available.
Text.Sentiment.Backends.Bumblebee (optional) — neural sentiment via Bumblebee and a pre-trained multilingual transformer (XLM-RoBERTa). Higher quality but requires a model download and the optional :bumblebee dep.

Routing is controlled by the :backend option to Text.Sentiment.analyze/2 (and label/2), or globally via the :sentiment_backend application configuration:

# config/config.exs
config :text, :sentiment_backend, Text.Sentiment.Backends.Bumblebee

Custom backends can be supplied by implementing this behaviour.

Summary

Types

result()

The structured result every backend returns.

Callbacks

analyze(t, keyword)

Returns a sentiment result for text.

Functions

resolve(options)

Returns the backend module currently configured for use.

Types

result()

@type result() :: %{
  :label => :positive | :negative | :neutral,
  :compound => float(),
  optional(:sum) => float(),
  optional(:tokens) => non_neg_integer(),
  optional(:matched) => non_neg_integer(),
  optional(:language) => atom() | nil,
  optional(:backend) => module(),
  optional(:model) => String.t(),
  optional(:scores) => %{required(atom()) => float()}
}

The structured result every backend returns.

Callbacks

analyze(t, keyword)

@callback analyze(
  String.t(),
  keyword()
) :: result()

Returns a sentiment result for text.

Backends are free to interpret options however they see fit, but every backend must:

Accept any UTF-8 binary as input.
Always return a map with at least :label and :compound.
Either accept the standard :language option (atom, string, or Localize.LanguageTag — see Text.Language.normalize/1) or document loudly that they ignore it.

Functions

resolve(options)

@spec resolve(keyword()) :: module()

Returns the backend module currently configured for use.

The resolution order is:

The :backend keyword option, if present.
The application config value at Application.get_env(:text, :sentiment_backend).
The default — Text.Sentiment.Backends.Lexicon.

Examples

iex> Text.Sentiment.Backend.resolve([])
Text.Sentiment.Backends.Lexicon

iex> Text.Sentiment.Backend.resolve(backend: Text.Sentiment.Backends.Lexicon)
Text.Sentiment.Backends.Lexicon