alerts plugin checks it in one of two ways: by comparing the article’s stored vectors with your description, or with TypeSafe’s Jev classifier, an external service.
Choose a check compares them with keyword alerts. You create the alert the same way as a keyword alert: a Saved Query holds the expression, and a Subscription names the alerts rule, version 0.4.0, and your destination. Only the expression and the rule configuration change.
Prerequisites
- Everything the keyword alerts guide needs: an API key with
monitoring:readandmonitoring:write, and a webhook destination. - The check enabled by the operator. The local stack offers the local check by default. The external check needs a TypeSafe key, which the operator sets up (First-party plugins).
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.
Use the local meaning check
The local check compares the article’s vectors with a vector of your description. A vector is a list of numbers that summarises meaning; Quivr computes the article’s vectors after it becomes searchable, with the same embedding provider as meaning search. The description’s vector is computed once, when you save the Saved Query Version. The check needs no TypeSafe key and never calls Jev. The comparison itself runs in thealerts plugin, but the article and description text go to whatever embedding provider the operator configured. To keep that text inside your installation, the operator must use a local embedding provider, such as the default core-ingest plugin, which calls an embedding server the operator runs (the local stack starts one).
Use this expression in your Saved Query. For example, not run:
keywords_or_meaning or keywords_and_meaning, and always state meaning_check: vectors compares vectors, while jev calls the external classifier. For example, not run:
threshold in the Subscription’s evaluator.configuration, or use the operator’s vectors.thresholds[<vector-space-id>] setting. The Subscription setting takes precedence. There is no implicit default; a ready comparison without either setting fails with vector_threshold_required.
The similarity is closeness, not a probability. On 156 neutral French/English pairs, a threshold of 0.80 retained all 16 related pairs for E5 and matched 11 unrelated pairs. For 768-dimensional EmbeddingGemma 2, 0.65 retained all 16 related pairs and matched 6 unrelated pairs; 0.80 missed 12 related pairs. These suggestions apply only to the measured revisions and templates. Tune the threshold on your own examples. The calibration notes list every pair, model revision and reproduction command.
The check needs the article’s vectors. Until they are attached, the rule answers not ready, and Quivr asks again when they arrive (Not ready); this happens even with wait_for_enrichment: false.
The description’s vector stays fixed with its Saved Query Version. When the operator switches a collection to another vector model, vectors from the two models cannot be compared: create a new Saved Query Version, then point each Subscription at it, as in Change or stop an alert.
Use the external classifier
Experimental: the external Jev check may still change in a minor 2.x release. See Versions and compatibility.
described expression sends each new article to TypeSafe’s Jev classifier, which scores how well it fits your description. English descriptions work best, and they can also find articles in other languages. Jev reads negations literally, which is one more reason to say what fits.
Use this expression in your Saved Query. sources is optional: it limits the alert to some Source Namespaces, and articles from other sources are never sent to the classifier. For example, not run:
evaluator, and raise it for fewer, surer alerts. For example, not run:
Subscription (excerpt)
truncated: true means the article was longer than what is sent, so the classifier saw only its beginning.
Timing and cost
The external check 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.
Quivr sends an article’s alerts to the plugin in batches. For each batch, the plugin sends one TypeSafe request that carries the article once and each distinct description once, so alerts with the same description share a question. The number of requests per article therefore grows with the number of alerts, much more slowly than one per alert; a request that would exceed TypeSafe’s size limit is split, and retries add requests. When a keyword part already settles a combined expression, the plugin does not call Jev for it.
When TypeSafe is down or rate-limited, the checks stay pending and are retried; keyword alerts on the same article wait too. When the key is refused, only the external checks wait, and the plugin log says why. Classifier failures are never recorded as no match.
Next
- How alerts work: what happens between a new article and your webhook.
- Keyword alerts: receive, verify and deduplicate the webhooks.