Five jobs a plugin can do
On this page, a passage is a short piece of a document, and a vector is a list of numbers that captures what a passage means, so Quivr can find passages close in meaning to a search. Quivr does the bookkeeping that must work the same for everyone, and asks plugins for the decisions that depend on your content: In words: Quivr keeps your documents, their earlier versions, who may read them, and the schedules and retries of all its work. It asks plugins what a source published, how to read a file, how to cut and compare text, which passages answer a search, and which alerts a document matches. Each job is one plugin type:
A plugin lists the jobs it does in its manifest, the file that describes it. There, each job is called a Contribution, and its type is one of the five above. Most plugins provide one Contribution, but one plugin can provide several of different types: a plugin for one service could both collect its items (
connector) and read its file format (normalizer). Quivr ships a plugin for each job; First-party plugins lists them.
What Quivr checks, and what it cannot
Quivr checks every answer before it records anything. It checks the shape of the JSON, the limits the plugin declared, and that the answer fits the request: for example, one vector of the right size for each passage. An answer that fails is refused, and nothing from it is recorded: the document is set aside with a diagnostic (quarantined), the search returns an error, or the call is retried. These checks cannot tell whether an answer is right. A plugin that reads the wrong text from a PDF, or ranks results badly, still passes them. They also do not make plugin code safe to run. A plugin runs with whatever access its process has, and it sees the text Quivr sends it. Install plugins you trust, and try their output on your own content before you rely on it.Who runs what
Quivr sends alerts as webhooks: HTTP requests to an address in your system, your webhook receiver. You run Quivr and every plugin. Quivr sends your plugins what their job needs, and a plugin may send it on to an outside service: In words:- Your application sends documents and searches to Quivr’s API. Sources can also push items to the same API.
- Quivr’s API and worker keep everything in their own database, file storage and search index. If you use a managed service for one of these, your documents are stored there.
- Quivr sends plugins what their job needs: document text, a short-lived link to a file, or a search. Plugins return their answers to Quivr. A connector calls its source itself and returns the items it collected to Quivr.
- A plugin may call an external model service, such as a hosted embedding model or a classifier, and send it text.
- Alerts go to your webhook receiver as identifiers, without document text. Your receiver reads the match or the document through the API if it needs more.
Add a plugin
Quivr does not install, start or scale plugins. You run each one and tell Quivr where it is:- Choose from First-party plugins, or write your own.
- Run the plugin as a process, container or hosted service that Quivr’s API and worker can reach. A plugin that reads or uploads files must also reach Quivr’s file storage, because files travel through short-lived links.
- Give Quivr its manifest and address. Pin it in the startup configuration and restart Quivr, or register and activate it while Quivr runs, with no restart.
make dev starts the default plugins for you.
If a plugin is down, background work that needs it waits, and Quivr retries until the plugin is back. A search that needs it fails with 503 instead of returning an empty list. An update a source pushes to Quivr also gets 503, and the source must send it again. Plan-pinned ingestion work already tied to a plugin version you have since replaced is the exception: it stops after a set number of tries, 10 by default, with a diagnostic that names the plugin. Upgrade or switch a plugin explains that case. Alert evaluations keep retrying until the old rule is back, unless you explicitly retire unavailable evaluations.
Write your own
Any language that serves HTTP can implement a plugin, and the Python and Go SDKs handle the protocol for you.quivr plugin test checks a plugin against the contract before you install it. Plugin types explains each type and the rules every plugin follows:
- Ship a manifest that describes the plugin.
- Version the plugin and the protocol.
- Give the same answer to the same request.
- Pass the Contract Runner.
- Use an SDK.
Next
Plugin types
What each type does, when Quivr calls it, and the rules every plugin follows.
Build your first plugin
From an empty folder to a plugin that makes a new file format searchable.