Pin a plugin

You run the plugin yourself, then add it to the plugins list of Quivr’s configuration file so Quivr calls it.

Prerequisites

The plugin runs at an address Quivr’s processes can reach, and quivr plugin test certifies it.
You can edit the JSON configuration file that QUIVR_CONFIG names, and restart Quivr. In the local stack, make dev writes that file for you; see Build your first plugin for the local shortcut.

Steps

Copy the manifest next to Quivr

Quivr reads the plugin’s quivr-plugin.yaml at startup, so it needs the exact file the plugin was built from. Copy it where every Quivr process can read it, for example /etc/quivr/plugins/acme-markdown/quivr-plugin.yaml.

Add the pin

Add one object per plugin to plugins in the configuration of every api, worker and migrate process:

QUIVR_CONFIG

{
  "plugins": [
    {
      "manifest": "/etc/quivr/plugins/acme-markdown/quivr-plugin.yaml",
      "endpoint": "http://127.0.0.1:9900",
      "configuration": {"max_sections": 32},
      "routes": [{"media_type": "text/markdown", "mode": "required"}]
    }
  ]
}

manifest and endpoint are always required. configuration is validated against the schema the manifest declares under configuration.schema. The other fields depend on the plugin’s type:

Type	Add	Rule
Normalizer	`routes`: the media types Quivr sends to it	Each is one the manifest declares, and a media type goes to one plugin only. `mode` is `required` (the default) or `optional`, which lets a `text/*` file fall back to plain text when the plugin fails.
Connector	nothing	Every kind the manifest declares becomes available. A kind has one provider. The endpoint must use `https://` unless it is on loopback, because requests carry credentials.
Ingestion	`spaces`: `{"<space id>": "served"}`, plus any `"evaluation"` spaces	Exactly one space is served. A deployment pins one ingestion plugin.
Retrieval	nothing	A deployment pins one retrieval plugin, and it answers every search.
Alert rule	optionally `kinds`: the alert kinds this deployment accepts	Subscriptions name the plugin by `plugin_id` and `version`.

The configuration reference lists every field of a pin.

Restart Quivr

Restart the api and worker processes. Each validates every pin before it serves: the manifest, the compatibility ranges, the configuration, routes and conflicts between pins. An invalid pin stops startup and lists every problem with its path, for example /plugins/0/configuration. Quivr does not contact the plugin at startup, so a plugin that is down does not stop Quivr.

Check it worked

An operator key with the plugins:admin action reads what the deployment registered:

curl -s "$QUIVR_API_URL/v0/admin/plugins" -H "Authorization: Bearer $QUIVR_OPERATOR_KEY"

Each registration shows the plugin’s id, version, endpoint, manifest digest, the roles it serves and its state. GET /v0/admin/plugins/plan shows the active Pipeline Plan: which plugin serves each media type, alert rule, connector kind, ingestion and retrieval. Then exercise the plugin: ingest a file of a routed type, create an instance of a new connector kind, or run a search. To change plugins later without a restart, see Switch plugins without restarting.

Troubleshooting

Symptom	Cause	Fix
Work waits with `plugin_unavailable`	Quivr cannot reach the plugin, or the plugin serves a different manifest than the pinned one	Start the plugin at `endpoint`. After editing `quivr-plugin.yaml`, restart the plugin and Quivr so both use the same file.
Startup fails with `incompatible_plugin_api`	The manifest’s `plugin_api` range does not admit the version its Contributions need	Widen the range, for example `>=0.3.0 <0.4.0` for a connector
Startup fails with `kind_conflict`, `ingestion_conflict` or `retrieval_conflict`	Two pins provide the same connector kind, or a second ingestion or retrieval plugin	Keep one provider
A Subscription is refused with `422 unsupported_evaluator`	No pinned alert rule has that `plugin_id` and `version`	Pin it, or fix the Subscription’s `evaluator`

Get started

Plugins

Guides

Pin a plugin

Prerequisites

Steps

Check it worked

Troubleshooting

​Prerequisites

​Steps

​Check it worked

​Troubleshooting

Prerequisites

Steps

Check it worked

Troubleshooting