Write a normalizer

git clone https://github.com/The-Vibe-Company/quivr-v2
cd quivr-v2
go build -o bin/quivr ./cmd/quivr
export PATH="$PWD/bin:$PATH"
QUIVR_REPO=$PWD

cd ..
quivr plugin init field-notes
cd field-notes
python3 -m venv .venv && . .venv/bin/activate
pip install -e "$QUIVR_REPO/sdks/python" -e .

python3 -m unittest discover -s tests                # unit tests, in process
quivr plugin inspect .                               # validate quivr-plugin.yaml
quivr plugin dev --fixture fixtures/sample.json      # run it and replay one fixture

quivr plugin dev: response valid: 4 Parts, 0 Relations, 0 warnings; the engine's Manifest validation accepts it

id: field-notes                   # lowercase; the name the Version's provenance shows
version: 0.1.0                    # SemVer; bump it when the output changes
compatibility:
  engine: ">=0.1.0 <0.2.0"
  plugin_api: ">=0.1.0 <0.2.0"
contributions:
  normalizer:
    media_types: [text/markdown]  # exact types; Quivr routes only the ones it is configured to route
    timeout_ms: 10000             # Quivr caps it at 2 minutes
    retry:
      max_attempts: 3             # RetryableError or timeout attempts before quarantine (capped at 5)
    limits:                       # optional
      max_parts: 256
      max_response_bytes: 4194304
configuration:
  schema: {type: object, ...}     # JSON Schema of the configuration the operator pins
extensions:                       # namespaces you own, with a JSON Schema per version
  field-notes.outline:
    "1": {type: object, ...}
run:
  command: [python3, -m, field_notes]

@plugin.normalizer
def normalize(invocation: Invocation) -> NormalizerResponse:
    data = invocation.read_input()                  # bytes, verified against size and SHA-256
    config = invocation.configuration               # already validated against your schema
    ...
    return NormalizerResponse(
        manifest=ManifestContent(parts=[Part(key="body", role="body", content=TextContent(text=text))]),
        warnings=[ResponseWarning(code="something_skipped", message="…")] or None,
    )

quivr plugin test --report contract-report.json

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

quivr plugin dev --port 9900 ../field-notes          # terminal 1, from the plugin's virtualenv
QUIVR_NORMALIZER=$PWD/../field-notes make dev        # terminal 2, in the quivr-v2 checkout

API=http://127.0.0.1:<api_port>; KEY=<API key>; FILE=notes.md; TYPE=text/markdown
SIZE=$(wc -c < "$FILE" | tr -d ' '); SHA=$(shasum -a 256 "$FILE" | cut -d' ' -f1)
CORPUS=$(curl -s -X POST "$API/v0/corpora" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Field notes","idempotency_key":"field-notes-corpus"}' | jq -r .corpus_id)

curl -s -X POST "$API/v0/uploads" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"size_bytes\":$SIZE,\"sha256\":\"$SHA\",\"media_type\":\"$TYPE\"}" > upload.json
BLOB=$(jq -r '.blob_id // empty' upload.json)   # set when these bytes are already a verified Blob
if [ -z "$BLOB" ]; then
  HEADERS=(); while IFS= read -r h; do HEADERS+=(-H "$h"); done \
    < <(jq -r '.upload_headers // {} | to_entries[] | "\(.key): \(.value)"' upload.json)
  curl -s -X PUT "${HEADERS[@]}" --data-binary @"$FILE" "$(jq -r .upload_url upload.json)"
  BLOB=$(curl -s -X POST "$API/v0/uploads/$(jq -r .upload_id upload.json)/confirm" -H "Authorization: Bearer $KEY" | jq -r .blob_id)
fi

RECEIPT=$(curl -s -X POST "$API/v0/records" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"idempotency_key\":\"notes-v1\",\"source\":{\"corpus_id\":\"$CORPUS\",\"namespace\":\"notes\",\"record_key\":\"notes\"},
       \"content\":{\"kind\":\"blob\",\"blob_id\":\"$BLOB\",\"media_type\":\"$TYPE\"}}" | jq -r .receipt_id)

{"code": "normalizer_failed", "message": "…", "retryable": false,
 "plugin": "field-notes", "contribution": "normalizer", "invocation_id": "inv_…"}

curl -s -X POST "$API/v0/search" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"query\":\"water levels\",\"corpus_ids\":[\"$CORPUS\"],\"mode\":\"lexical\"}" | jq '.items[] | {record_id, version_id, part_key}'

"extensions": {
  "field-notes.outline": {"schema_version": "1", "data": {"heading_count": 3, "heading_levels": ["h1", "h2"]}}
},
"provenance": {
  "producer": "…the client or Connector Instance that submitted the Blob…",
  "source_blob_ids": ["blob_…"],
  "normalization": {
    "plugin_id": "field-notes",
    "plugin_version": "0.1.0",
    "plugin_api": "0.1.0",
    "contribution": "normalizer",
    "invocation_id": "inv_…",
    "idempotency_key": "…",
    "input_sha256": "…"
  }
}