Skip to main content
A described alert fires when a new article fits a description such as “Labour strikes at ports and harbours”, whatever words or language the article uses. An external classifier, TypeSafe’s Jev, reads each new article and scores how well it fits. Described alerts are part of the first-party alerts plugin, next to keyword alerts.
To judge an article, the plugin sends its title, its text (up to about 48 KB), its Source Namespace and any mapped metadata to TypeSafe’s API. Without a TypeSafe key, described alerts are off and nothing is sent.

​
Prerequisites

  • An operator has turned described alerts on (below).
  • Everything the keyword alerts guide needs: an API key with monitoring:write and a webhook destination.

​
Write a description

Describe the subject of the articles you want in one or two plain sentences, 3 to 1000 characters. Write one alert per subject, and say what fits rather than what does not: the classifier reads negations literally. English descriptions work best, and they also find articles in other languages.

​
Save the alert

The expression holds the description. sources is optional: it limits the alert to some Source Namespaces, and articles from other sources are never sent to the classifier.
Create a Saved Query with this expression and a Subscription with the alerts evaluator, as for a keyword alert. The Subscription’s configuration can set a threshold:
The classifier returns a score from 0 to 1, the probability that the article fits. The article matches when its score reaches the threshold: 0.5 by default, between 0.2 and 0.95. Raise it for fewer, surer alerts.

​
Read what matched

The Match’s evidence names the classifier, its model, the score and the Parts it read:
truncated: true means the article was longer than what is sent, so the classifier saw only its beginning.

​
Timing and cost

A described alert waits until the article’s vectors are attached, a few seconds after it is searchable. Set {"wait_for_enrichment": false} in the Subscription’s configuration to decide at once, and on a deployment that never computes vectors. Each new article costs one TypeSafe request for all described alerts together, whatever their number or owners; Quivr asks each distinct description once. A request is split only when it would exceed TypeSafe’s size limit. Every new article is judged against every active described alert that watches its source. When TypeSafe is down or rate-limited, the alerts wait and are retried; keyword alerts on the same article wait too. When the key is refused, only the described alerts wait, and the plugin log says why. An alert is never dropped.

​
Turn them on

These steps are for the operator who runs Quivr.
  1. Put the key in the alerts plugin’s environment: TYPESAFE_API_KEY=<your key>. Never put it in Quivr’s configuration, in logs or in a repository.
  2. List the kind in the alerts pin of Quivr’s configuration:
    QUIVR_CONFIG
  3. Restart the plugin and Quivr. The plugin logs at startup whether described alerts are enabled.
Without a key, pin "kinds": ["keywords"]: a described alert is then refused at creation with 422 invalid_expression. With the local stack, make dev offers described alerts only when TYPESAFE_API_KEY is set in its environment.