quivr-plugin.yaml, the manifest a plugin ships. It is written in YAML and validated as the equivalent JSON value against plugin-manifest.schema.json; quivr plugin inspect checks it the way the engine does. Unknown fields are rejected.
Identity and compatibility
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | At most 64 characters. |
version | string | yes | SemVer 2.0.0. At most 128 characters. |
description | string | no | 1 to 1024 characters. |
compatibility | object | yes | — |
compatibility.engine | string | yes | Whitespace-separated comparators that must all hold; operators >=, >, <=, <, = (none means =); versions are MAJOR.MINOR.PATCH. At most 128 characters. |
compatibility.plugin_api | string | yes | Whitespace-separated comparators that must all hold; operators >=, >, <=, <, = (none means =); versions are MAJOR.MINOR.PATCH. At most 128 characters. |
Normalizer
| Field | Type | Required | Description |
|---|---|---|---|
contributions.normalizer | object | no | — |
contributions.normalizer.media_types | array of string | yes | Exact Blob media types (no wildcards or parameters) this normalizer accepts; startup configuration routes them. 1 to 32 items. |
contributions.normalizer.timeout_ms | integer | no | 1000 to 300000. Default 30000. |
contributions.normalizer.retry | object | no | Retry intent for plugin-declared retryable errors; the engine may cap it. |
contributions.normalizer.retry.max_attempts | integer | yes | 1 to 10. Default 3. |
contributions.normalizer.limits | object | no | — |
contributions.normalizer.limits.max_response_bytes | integer | no | 1024 to 16777216. Default 4194304. |
contributions.normalizer.limits.max_parts | integer | no | 1 to 256. Default 256. |
Alert rule (subscription)
| Field | Type | Required | Description |
|---|---|---|---|
contributions.subscription | object | no | An alert rule, since Plugin API 0.2: decides whether one Record Version matches each Saved Query expression of a batch. |
contributions.subscription.expression_schema | object or boolean | yes | JSON Schema 2020-12 of the Saved Query expression (a JSON object) this rule interprets. The core validates Saved Query Versions against it. Discriminate several alert kinds with a oneOf over a kind property. |
contributions.subscription.configuration_schema | object or boolean | no | JSON Schema 2020-12 of the per-Subscription evaluator configuration (a JSON object). Absent: any object. Distinct from the installer configuration under configuration.schema. |
contributions.subscription.max_batch_size | integer | no | Most evaluations one request carries; the core splits a larger batch into several requests. 1 to 256. Default 32. |
contributions.subscription.timeout_ms | integer | no | 1000 to 300000. Default 30000. |
contributions.subscription.retry | object | no | Retry intent for plugin-declared retryable errors; the engine may cap it. |
contributions.subscription.retry.max_attempts | integer | yes | 1 to 10. Default 3. |
contributions.subscription.limits | object | no | — |
contributions.subscription.limits.max_response_bytes | integer | no | 1024 to 16777216. Default 4194304. |
contributions.subscription.vectors | reserved | no | Reserved: a document that sets it is rejected. |
Connector
| Field | Type | Required | Description |
|---|---|---|---|
contributions.connector | object | no | Source collectors, since Plugin API 0.3: fetch pages of new or changed items from a source after an opaque checkpoint. The core keeps Connector Instances, schedules, checkpoints, credentials and health. |
contributions.connector.kinds | map of object | yes | Connector kinds this plugin provides, by kind name. 1 to 32 entries. |
contributions.connector.kinds.<name>.description | string | no | 1 to 1024 characters. |
contributions.connector.kinds.<name>.config_schema | object or boolean | yes | JSON Schema 2020-12 of the Connector Instance configuration (a JSON object). |
contributions.connector.kinds.<name>.credential_schema | object or boolean | no | JSON Schema 2020-12 of the Deposited Credential (a JSON object). Absent: the kind takes no credential. |
contributions.connector.kinds.<name>.credential_required | boolean | no | Since Plugin API 0.3.1. Whether an instance needs a Deposited Credential before it runs. false: the credential is optional, and an instance without one is invoked with a null credential. Only meaningful with credential_schema. Default true. |
contributions.connector.kinds.<name>.default_interval_seconds | integer | yes | Polling interval of a new Connector Instance when it does not set one. 60 to 86400. |
contributions.connector.kinds.<name>.modes | array of pull, push | no | pull: the core schedules fetch. push, since Plugin API 0.5: the core relays the deliveries a source sends to the instance’s public webhook route to receive, and returns the plugin’s answer to the source. A push kind also declares pull: polling stays the fallback. Default ["pull"]. |
contributions.connector.timeout_ms | integer | no | 1000 to 120000. Default 30000. |
contributions.connector.limits | object | no | — |
contributions.connector.limits.max_response_bytes | integer | no | 1024 to 16777216. Default 4194304. |
contributions.connector.limits.max_items | integer | no | 1 to 1000. Default 100. |
contributions.connector.limits.max_checkpoint_bytes | integer | no | Largest checkpoint, serialized as compact JSON, the core accepts from this plugin (since Plugin API 0.3.1). 1024 to 1048576. Default 65536. |
contributions.connector.attachments | object | no | Since Plugin API 0.4: items may carry attachments. The core asks for each attachment’s size and SHA-256 (describe_attachment), issues an upload grant and has the plugin upload the bytes against it (upload_attachment). Without this block a page with attachments is refused. |
contributions.connector.attachments.max_bytes | integer | no | Largest attachment the plugin uploads; it can only lower the engine’s 25 MiB cap. 1 to 26214400. Default 26214400. |
contributions.connector.attachments.timeout_ms | integer | no | Deadline of one describe_attachment or upload_attachment invocation. 1000 to 120000. Default 120000. |
Ingestion
| Field | Type | Required | Description |
|---|---|---|---|
contributions.ingestion | object | no | Segmentation and embedding, since Plugin API 0.6: cut one Record Version’s text Parts into segments and embed each segment in the vector spaces the plugin owns (segment_and_embed), and encode a query into one of those spaces (embed_query). The core keeps the index, the registry of spaces, authorization, withdrawal and projection generations. |
contributions.ingestion.spaces | map of object | yes | The vector spaces this plugin owns, by space id. A deployment enables some of them: one served, the others for evaluation. 1 to 8 entries. |
contributions.ingestion.spaces.<name>.version | string | yes | Bumped whenever the vectors change: a new model, new weights, a new input template. |
contributions.ingestion.spaces.<name>.model | string | yes | The model that produces the vectors, for people and reports. 1 to 256 characters. |
contributions.ingestion.spaces.<name>.dimensions | integer | yes | 1 to 4096. |
contributions.ingestion.spaces.<name>.metric | cosine, dot, l2 | yes | The distance the index uses for this space. |
contributions.ingestion.spaces.<name>.indexes | array of text | yes | Modalities of the content this space embeds. Plugin API 0.6 knows only text. |
contributions.ingestion.spaces.<name>.query_modalities | array of text | yes | Modalities of the queries embed_query encodes into this space. Plugin API 0.6 knows only text. |
contributions.ingestion.spaces.<name>.description | string | no | 1 to 1024 characters. |
contributions.ingestion.timeout_ms | integer | no | Deadline of one segment_and_embed invocation. 1000 to 300000. Default 30000. |
contributions.ingestion.query_timeout_ms | integer | no | Deadline of one embed_query invocation; a search waits for it. 100 to 10000. Default 2000. |
contributions.ingestion.limits | object | no | — |
contributions.ingestion.limits.max_segments | integer | no | Most segments one Record Version yields. 1 to 1024. Default 256. |
contributions.ingestion.limits.max_response_bytes | integer | no | 1024 to 16777216. Default 16777216. |
Retrieval
| Field | Type | Required | Description |
|---|---|---|---|
contributions.retrieval | object | no | Search, since Plugin API 0.7: answer one search in rounds. Each round the plugin either asks the core for candidates (keyword, vector on a named space, hybrid) or returns the final ranking, chosen only among candidates the core served in this search. The core keeps the index, encodes queries with each space’s owner, and applies authorization, withdrawal and generation routing before serving any candidate. |
contributions.retrieval.profiles | map of object | yes | The search profiles this plugin answers, by name; default is required and answers a search that names no profile. 1 to 8 entries. |
contributions.retrieval.profiles.<name>.description | string | no | 1 to 1024 characters. |
contributions.retrieval.profiles.<name>.max_latency_ms | integer | yes | Deadline of one whole search under this profile, every round and every candidate request included. The core stops a search that runs longer and answers search_deadline_exceeded. 50 to 10000. |
contributions.retrieval.profiles.<name>.max_cost_cents | number | yes | Most paid spend one search may report in usage.cost_cents (for example a re-ranking or rewriting API); 0 for a profile without paid calls. 0 to 100. |
contributions.retrieval.limits | object | no | — |
contributions.retrieval.limits.max_rounds | integer | no | Most rounds of one search; the last round must return a ranking. 1 to 3. Default 3. |
contributions.retrieval.limits.max_requests | integer | no | Most candidate requests of one round. 1 to 8. Default 4. |
contributions.retrieval.limits.max_candidates | integer | no | Largest k of one candidate request. 1 to 100. Default 50. |
contributions.retrieval.limits.max_response_bytes | integer | no | 1024 to 4194304. Default 1048576. |
Reserved contributions
| Field | Type | Required | Description |
|---|---|---|---|
contributions.enricher | reserved | no | Reserved: a document that sets it is rejected. |
contributions.validator | reserved | no | Reserved: a document that sets it is rejected. |
contributions.projector | reserved | no | Reserved: a document that sets it is rejected. |
contributions.retriever | reserved | no | Reserved: a document that sets it is rejected. |
Configuration, secrets and extensions
| Field | Type | Required | Description |
|---|---|---|---|
configuration | object | no | — |
configuration.schema | object or boolean | yes | JSON Schema 2020-12 for the plugin configuration the installer supplies. |
secrets | array of object | no | At most 32 items. |
extensions | map of map of object or boolean | no | Extension namespaces the plugin owns, each mapping schema versions to JSON Schema 2020-12. Every namespace must equal the plugin id or start with the plugin id followed by a dot. At most 32 entries. |
Local development
| Field | Type | Required | Description |
|---|---|---|---|
run | object | no | Language-neutral local development command (argv, no shell). |
run.command | array of string | yes | — |
Other fields
| Field | Type | Required | Description |
|---|---|---|---|
secrets[].name | string | yes | — |
secrets[].description | string | no | 1 to 1024 characters. |
secrets[].required | boolean | no | Default true. |