Skip to main content
A plugin provides one or more Contributions, each of one of five types. Pick the type from the question you want to answer for Quivr.

Normalizer

How do I read this kind of file?

Connector

What did this source publish since last time?

Ingestion

How do I cut and embed this article?

Retrieval

Which passages answer this search, in what order?

Alert rule

Does this article match these alerts?
Every type is served over HTTP under /v0/contributions/<type>, and every manifest below passes quivr plugin inspect. The plugin protocol reference lists every request and response field.

Normalizer

quivr-plugin.yaml
Quivr never sends the file inline: the request carries a short-lived signed URL, its size and its SHA-256. An answer Quivr rejects, or a TerminalError, quarantines the Version with a diagnostic; a plugin that is down only delays it. Walk through one in Build your first plugin.

Connector

quivr-plugin.yaml
Quivr keeps the instances, schedules, checkpoints, encrypted credentials and health. The plugin is stateless: it gets its last checkpoint and the decrypted credential in each request, and returns items plus the next checkpoint. Quivr moves the checkpoint only after the items are stored. See Write a connector or receive pushed records.

Ingestion

quivr-plugin.yaml
A deployment can pin several ingestion plugins and route source media types to them; Quivr does not segment or embed anything itself. See Write an ingestion plugin.

Retrieval

quivr-plugin.yaml
The plugin never queries the index and never sees a candidate the caller may not read: Quivr applies access control and withdrawals before it serves candidates. See Write a retrieval plugin.

Alert rule

quivr-plugin.yaml
expression_schema is the shape of the queries your rule understands; Quivr refuses a Saved Query that does not fit it when the alert is created. See Write an alert rule.

What every plugin does

Whatever its type, a plugin follows the same few rules. The plugin protocol reference states them field by field.

Ship a manifest

Every plugin ships a quivr-plugin.yaml that declares its identity, version, compatibility ranges, Contributions and limits:
quivr-plugin.yaml
The operator gives Quivr the same file when they pin or register the plugin. Before each call, Quivr checks that the plugin reports, on GET /v0/discovery, the expected identity, version and manifest_digest: the SHA-256 of that file. This catches a plugin started with a different manifest; the digest is reported by the plugin, so it does not verify the plugin’s code. The plugin manifest reference lists every field.

Version the plugin and the protocol

Two version numbers matter. The plugin’s own version is SemVer; bump it when its output changes, because documents record which version produced them. The Plugin API version is the version of the protocol itself. A plugin declares the range it supports in compatibility.plugin_api and reports the version it implements on GET /v0/discovery. Quivr uses that version, provided Quivr supports it and it falls inside the declared range. A minor Plugin API version only adds to the previous one, so a plugin built for an earlier minor keeps working.

Give the same answer to the same request

Quivr retries calls and replays them during rebuilds, so a plugin must answer the same thing to the same request. Normalizer, segment_and_embed and alert rule requests carry an idempotency_key that stays the same across retries of the same logical call, so a plugin can recognise a retry. For normalizer and ingestion answers, Quivr keeps the first answer it recorded and flags a different one as a conflict. For alerts, it keeps the first match it recorded for a document version and ignores later decisions about it. A plugin must not rely on local state to remember Quivr’s progress: a connector gets its last checkpoint back in each request, and a normalizer gets a signed link to the file it reads. It may still cache models or results, as core-ingest caches the vectors it computed.

Pass the Contract Runner

quivr plugin test is the Contract Runner. It starts your plugin, calls every route over HTTP with the protocol’s test cases and your own, and judges each answer with the engine’s own validation code. It also replays calls to check determinism, sends invalid requests and enforces the declared deadlines. It looks for fixture credentials and configured secret values in the answers it sees and, when it started the plugin, in the plugin’s output. CERTIFIED means your plugin speaks the protocol correctly; it does not check that its answers are good for your content. It needs no running Quivr deployment, so it runs in any language’s CI, though your plugin may still need its own external services.

Use an SDK

Any language that serves HTTP can implement the protocol. Two SDKs handle routing, validation, errors and the digest for you: quivr plugin init supplies Python normalizer, subscription and pull or push connector starters. There are no Go starters, and no Python ingestion or retrieval starters, because those need a language module setup or a chosen vector model or search strategy; use the SDKs directly.

Next

Build your first plugin

A normalizer from an empty folder to a local Quivr.

Pin a plugin

The configuration that makes Quivr call each type.