embedflow 0.1.1__tar.gz → 0.3.0__tar.gz

embedflow-0.3.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## v0.3.0 — Pinecone backend
+
+- Added a read-only Pinecone backend for existing dense indexes.
+- Added host targeting, index-name resolution, namespace-aware retrieval, and
+  metadata or external-document text resolution.
+- Added Pinecone status/audit integration, optional dependency packaging, and
+  unit/integration smoke fixtures.
+
+## v0.2.0 — pgvector backend
+
+- Added a read-only pgvector backend for existing PostgreSQL vector tables.
+- Added cosine, Euclidean/L2, and inner-product retrieval with safe SQL
+  identifier composition.
+- Added pgvector table auditing, optional transaction-local HNSW/IVFFlat
+  settings, Docker example, and numerical/SQL-safety tests.
+
+## v0.1.0 — initial public release
+
+- Candidate-compatibility analysis and Mode A evaluation workflows.
+- Frozen T2-v1 finite-tail diagnostic with explicit empirical-warning language.
+- FAISS and Qdrant index adapters.
+- Persistent target-vector cache and progressive materialization queue.
+- FastAPI service, search/status/prewarm endpoints, and dashboard.
+- Latency telemetry, economics projections, report generation, and demos.
+- Public packaging, examples, tests, CI configuration, and contributor docs.
+
+This is an early open-source release. See the limitations in the README and
+`docs/concepts.md` before using it for a production migration.

{embedflow-0.1.1 → embedflow-0.3.0}/CITATION.cff

@@ -2,7 +2,7 @@ cff-version: 1.2.0
 title: "EmbedFlow: Upgrading Legacy Embeddings Without Full Upfront Re-Embedding"
 message: "If EmbedFlow contributes to your work, please cite this software release."
 type: software
-version: 0.1.1
+version: 0.3.0
 date-released: 2026-09-06
 repository-code: "https://github.com/arnsri33/embedflow"
 url: "https://github.com/arnsri33/embedflow"

{embedflow-0.1.1 → embedflow-0.3.0}/CONTRIBUTING.md

@@ -11,7 +11,7 @@ python -m pip install -e '.[dev]'
 ```
 
 Optional integrations can be installed with `.[faiss]`, `.[qdrant]`,
-`.[models]`, or `.[dashboard]`.
+`.[pgvector]`, `.[pinecone]`, `.[models]`, or `.[dashboard]`.
 
 ## Checks before opening a pull request
 

{embedflow-0.1.1 → embedflow-0.3.0}/MANIFEST.in

@@ -1,10 +1,11 @@
 include README.md README_PYPI.md LICENSE CHANGELOG.md CONTRIBUTING.md SECURITY.md CITATION.cff requirements.txt requirements-dev.txt
 recursive-include docs *
-recursive-include examples *.md *.yaml *.json *.jsonl *.py
+recursive-include examples *.md *.yaml *.json *.jsonl *.py *.sql *.sh
 recursive-include scripts *.sh *.py
 recursive-include frozen *.md *.sha256
 prune .github
 prune tests
+prune examples/*/runtime
 global-exclude __pycache__
 global-exclude *.py[cod]
 global-exclude *.index *.npy *.npz *.sqlite *.sqlite3 *.db

{embedflow-0.1.1 → embedflow-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: embedflow
-Version: 0.1.1
+Version: 0.3.0
 Summary: Progressive embedding-model migration over existing vector indexes.
 Author: Arnav Srivastav
 License-Expression: AGPL-3.0-only
@@ -8,7 +8,7 @@ Project-URL: Homepage, https://embedflow.org
 Project-URL: Repository, https://github.com/arnsri33/embedflow
 Project-URL: Documentation, https://github.com/arnsri33/embedflow#readme
 Project-URL: Issues, https://github.com/arnsri33/embedflow/issues
-Keywords: embeddings,vector-search,rag,information-retrieval,faiss,qdrant
+Keywords: embeddings,vector-search,rag,information-retrieval,faiss,qdrant,pgvector,pinecone
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -27,9 +27,13 @@ Provides-Extra: faiss
 Requires-Dist: faiss-cpu>=1.8.0; extra == "faiss"
 Provides-Extra: qdrant
 Requires-Dist: qdrant-client>=1.9; extra == "qdrant"
+Provides-Extra: pgvector
+Requires-Dist: psycopg[binary]>=3.2; extra == "pgvector"
+Provides-Extra: pinecone
+Requires-Dist: pinecone>=6.0; extra == "pinecone"
 Provides-Extra: models
-Requires-Dist: huggingface-hub>=0.20; extra == "models"
-Requires-Dist: transformers>=4.45; extra == "models"
+Requires-Dist: huggingface-hub<1.0,>=0.34; extra == "models"
+Requires-Dist: transformers<5.0,>=4.45; extra == "models"
 Requires-Dist: sentence-transformers>=3.0; extra == "models"
 Requires-Dist: torch>=2.2; extra == "models"
 Provides-Extra: dashboard
@@ -39,8 +43,10 @@ Requires-Dist: pydantic>=2.0; extra == "dashboard"
 Provides-Extra: all
 Requires-Dist: faiss-cpu>=1.8.0; extra == "all"
 Requires-Dist: qdrant-client>=1.9; extra == "all"
-Requires-Dist: huggingface-hub>=0.20; extra == "all"
-Requires-Dist: transformers>=4.45; extra == "all"
+Requires-Dist: psycopg[binary]>=3.2; extra == "all"
+Requires-Dist: pinecone>=6.0; extra == "all"
+Requires-Dist: huggingface-hub<1.0,>=0.34; extra == "all"
+Requires-Dist: transformers<5.0,>=4.45; extra == "all"
 Requires-Dist: sentence-transformers>=3.0; extra == "all"
 Requires-Dist: torch>=2.2; extra == "all"
 Requires-Dist: fastapi>=0.100; extra == "all"
@@ -59,7 +65,7 @@ Dynamic: license-file
 EmbedFlow lets a new embedding model serve over candidates from an existing
 vector index while target document vectors are materialized progressively. It
 supports migration analysis, persistent caching, background work, FAISS,
-Qdrant, a CLI, and FastAPI.
+Qdrant, pgvector, Pinecone, a CLI, and FastAPI.
 
 The full project README and architecture diagram are on
 <https://github.com/arnsri33/embedflow>.
@@ -76,6 +82,18 @@ For FAISS and the dashboard:
 python -m pip install "embedflow[faiss,dashboard]"
 ```
 
+For an existing PostgreSQL/pgvector table:
+
+```bash
+python -m pip install "embedflow[pgvector]"
+```
+
+For an existing Pinecone dense index:
+
+```bash
+python -m pip install "embedflow[pinecone]"
+```
+
 Qdrant and model-runtime extras are documented in the
 [installation guide](https://github.com/arnsri33/embedflow/blob/main/docs/installation.md).
 For model-backed analysis, install `embedflow[faiss,models,dashboard]`.
@@ -176,9 +194,13 @@ for definitions and reproduction details.
 | --- | --- |
 | FAISS | Supported |
 | Qdrant | Supported |
+| pgvector | Supported |
+| Pinecone | Supported |
 
-See the [FAISS guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/faiss.md)
-and [Qdrant guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/qdrant.md).
+See the [FAISS guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/faiss.md),
+[Qdrant guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/qdrant.md),
+and [pgvector guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/pgvector.md),
+and [Pinecone guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/pinecone.md).
 
 ## CLI
 
@@ -188,7 +210,7 @@ embedflow analyze --help
 embedflow serve --config ./embedflow.yaml
 embedflow status --config ./embedflow.yaml
 embedflow registry list
-embedflow economics --corpus-size 1000000000 --docs-per-second 106.98 --gpu-price 3.29
+embedflow economics --corpus-size 1000000000 --docs-per-second 100 --gpu-price 3.29
 embedflow doctor --config ./embedflow.yaml
 ```
 
@@ -198,7 +220,7 @@ cover the remaining commands and endpoints.
 
 ## Status
 
-EmbedFlow v0.1.0 is an alpha release for research and early real-world
+EmbedFlow v0.3.0 is an alpha release for research and early real-world
 testing. T2-v1 is an empirical finite-tail diagnostic, partial rankings can
 differ from fully warm target reranking, and ANN fidelity needs a reference
 comparison to audit.

{embedflow-0.1.1 → embedflow-0.3.0}/README.md

@@ -7,7 +7,7 @@
 EmbedFlow lets a new embedding model serve over candidates from an existing
 vector index while target document vectors are materialized progressively. It
 supports migration analysis, persistent caching, background work, and serving
-through FAISS, Qdrant, a CLI, and FastAPI.
+through FAISS, Qdrant, pgvector, Pinecone, a CLI, and FastAPI.
 
 [Quickstart](#try-it) · [Documentation](#documentation) · [Research](#research)
 
@@ -52,6 +52,12 @@ For FAISS and the dashboard, add the optional integrations:
 python -m pip install "embedflow[faiss,dashboard]"
 ```
 
+For an existing Pinecone dense index:
+
+```bash
+python -m pip install "embedflow[pinecone]"
+```
+
 Qdrant and model-runtime extras are documented in
 [`docs/installation.md`](https://github.com/arnsri33/embedflow/blob/main/docs/installation.md).
 For model-backed analysis, install `embedflow[faiss,models,dashboard]`.
@@ -189,11 +195,15 @@ is measured separately and is `UNKNOWN` until an exact reference is supplied.
 | --- | --- |
 | FAISS | Supported |
 | Qdrant | Supported |
+| pgvector | Supported |
+| Pinecone | Supported |
 
 Backend-specific setup and examples:
 
 - [FAISS](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/faiss.md)
 - [Qdrant](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/qdrant.md)
+- [pgvector](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/pgvector.md)
+- [Pinecone](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/pinecone.md)
 - [Adding a backend](https://github.com/arnsri33/embedflow/blob/main/CONTRIBUTING.md)
 
 ## CLI
@@ -204,7 +214,7 @@ embedflow analyze --help
 embedflow serve --config ./embedflow.yaml
 embedflow status --config ./embedflow.yaml
 embedflow registry list
-embedflow economics --corpus-size 1000000000 --docs-per-second 106.98 --gpu-price 3.29
+embedflow economics --corpus-size 1000000000 --docs-per-second 100 --gpu-price 3.29
 embedflow doctor --config ./embedflow.yaml
 ```
 
@@ -228,7 +238,7 @@ OpenAPI documentation; see
 
 ## Status
 
-EmbedFlow v0.1.0 is an alpha release for research and early real-world
+EmbedFlow v0.3.0 is an alpha release for research and early real-world
 testing.
 
 - T2-v1 reports an empirical finite-tail diagnostic.

{embedflow-0.1.1 → embedflow-0.3.0}/README_PYPI.md

@@ -5,7 +5,7 @@
 EmbedFlow lets a new embedding model serve over candidates from an existing
 vector index while target document vectors are materialized progressively. It
 supports migration analysis, persistent caching, background work, FAISS,
-Qdrant, a CLI, and FastAPI.
+Qdrant, pgvector, Pinecone, a CLI, and FastAPI.
 
 The full project README and architecture diagram are on
 <https://github.com/arnsri33/embedflow>.
@@ -22,6 +22,18 @@ For FAISS and the dashboard:
 python -m pip install "embedflow[faiss,dashboard]"
 ```
 
+For an existing PostgreSQL/pgvector table:
+
+```bash
+python -m pip install "embedflow[pgvector]"
+```
+
+For an existing Pinecone dense index:
+
+```bash
+python -m pip install "embedflow[pinecone]"
+```
+
 Qdrant and model-runtime extras are documented in the
 [installation guide](https://github.com/arnsri33/embedflow/blob/main/docs/installation.md).
 For model-backed analysis, install `embedflow[faiss,models,dashboard]`.
@@ -122,9 +134,13 @@ for definitions and reproduction details.
 | --- | --- |
 | FAISS | Supported |
 | Qdrant | Supported |
+| pgvector | Supported |
+| Pinecone | Supported |
 
-See the [FAISS guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/faiss.md)
-and [Qdrant guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/qdrant.md).
+See the [FAISS guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/faiss.md),
+[Qdrant guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/qdrant.md),
+and [pgvector guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/pgvector.md),
+and [Pinecone guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/pinecone.md).
 
 ## CLI
 
@@ -134,7 +150,7 @@ embedflow analyze --help
 embedflow serve --config ./embedflow.yaml
 embedflow status --config ./embedflow.yaml
 embedflow registry list
-embedflow economics --corpus-size 1000000000 --docs-per-second 106.98 --gpu-price 3.29
+embedflow economics --corpus-size 1000000000 --docs-per-second 100 --gpu-price 3.29
 embedflow doctor --config ./embedflow.yaml
 ```
 
@@ -144,7 +160,7 @@ cover the remaining commands and endpoints.
 
 ## Status
 
-EmbedFlow v0.1.0 is an alpha release for research and early real-world
+EmbedFlow v0.3.0 is an alpha release for research and early real-world
 testing. T2-v1 is an empirical finite-tail diagnostic, partial rankings can
 differ from fully warm target reranking, and ANN fidelity needs a reference
 comparison to audit.

{embedflow-0.1.1 → embedflow-0.3.0}/docs/api.md

@@ -13,8 +13,8 @@ Interactive OpenAPI documentation is available at
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| GET | `/health` | Process and backend health |
-| GET | `/status` | Cache, queue, model, and migration state |
+| GET | `/health` | Lightweight process liveness |
+| GET | `/status` | Cache, queue, model, migration, and backend metadata |
 | POST | `/search` | Source retrieval and target reranking |
 | POST | `/analyze` | Run or retrieve migration analysis |
 | POST | `/prewarm` | Queue document materialization |
@@ -48,6 +48,12 @@ The response includes the result list and migration fields such as:
 request. A partial response scores the available target vectors; it can differ
 from the fully warm ranking.
 
+`/status` includes safe backend metadata. For pgvector this names the
+schema/table and vector contract; for Pinecone it names the host/index,
+namespace, dimension, metric, and safe vector counts. Neither backend returns
+the DSN, API key, or credentials;
+`/health` remains a compact liveness response for probes and load balancers.
+
 ## Errors
 
 Validation errors use FastAPI/Pydantic's normal JSON response. Backend,

{embedflow-0.1.1 → embedflow-0.3.0}/docs/cli.md

@@ -52,7 +52,7 @@ Registry matching uses model contracts and corpus identity. See
 ```bash
 embedflow economics \
   --corpus-size 1000000000 \
-  --docs-per-second 106.98 \
+  --docs-per-second 100 \
   --gpu-price 3.29
 embedflow doctor --config ./embedflow.yaml
 embedflow demo

{embedflow-0.1.1 → embedflow-0.3.0}/docs/configuration.md

@@ -14,12 +14,16 @@ target:
   device: cuda
 
 index:
-  backend: faiss                 # faiss or qdrant
+  backend: faiss                 # faiss, qdrant, pgvector, or pinecone
   path: ./legacy.index
   ids: ./legacy.index.ids.json   # FAISS sidecar
   metric: cosine
   nprobe: 64
   # Qdrant fields: url, collection, vector_name, api_key_env
+  # pgvector fields: dsn_env, schema, table, id_column, vector_column, text_column
+  #                 hnsw_ef_search, ivfflat_probes
+  # Pinecone fields: host (preferred) or index_name, api_key_env, namespace,
+  #                  text_metadata_field
 
 documents:
   path: ./documents.jsonl
@@ -78,6 +82,19 @@ EMBEDFLOW_INDEX_URL
 EMBEDFLOW_INDEX_COLLECTION
 EMBEDFLOW_INDEX_VECTOR_NAME
 EMBEDFLOW_QDRANT_API_KEY_ENV
+EMBEDFLOW_PGVECTOR_DSN_ENV
+EMBEDFLOW_PGVECTOR_SCHEMA
+EMBEDFLOW_PGVECTOR_TABLE
+EMBEDFLOW_PGVECTOR_ID_COLUMN
+EMBEDFLOW_PGVECTOR_VECTOR_COLUMN
+EMBEDFLOW_PGVECTOR_TEXT_COLUMN
+EMBEDFLOW_PGVECTOR_HNSW_EF_SEARCH
+EMBEDFLOW_PGVECTOR_IVFFLAT_PROBES
+EMBEDFLOW_PINECONE_HOST
+EMBEDFLOW_PINECONE_INDEX_NAME
+EMBEDFLOW_PINECONE_NAMESPACE
+EMBEDFLOW_PINECONE_TEXT_METADATA_FIELD
+EMBEDFLOW_PINECONE_API_KEY_ENV
 EMBEDFLOW_INDEX_NPROBE
 EMBEDFLOW_DOCUMENTS_PATH
 EMBEDFLOW_CACHE_PATH

{embedflow-0.1.1 → embedflow-0.3.0}/docs/economics.md

@@ -6,7 +6,7 @@ throughput and GPU price supplied by the user:
 ```bash
 embedflow economics \
   --corpus-size 1000000000 \
-  --docs-per-second 106.98 \
+  --docs-per-second 100 \
   --gpu-price 3.29
 ```
 

{embedflow-0.1.1 → embedflow-0.3.0}/docs/installation.md

@@ -30,6 +30,8 @@ python -m pip install -e .
 | --- | --- |
 | `faiss` | FAISS source-index adapter |
 | `qdrant` | Qdrant client and adapter |
+| `pgvector` | Psycopg 3 binary driver and pgvector adapter |
+| `pinecone` | Official Pinecone Python SDK and adapter |
 | `models` | PyTorch, Transformers, Sentence Transformers, and Hub client |
 | `dashboard` | FastAPI, Uvicorn, and Pydantic |
 | `dev` | Pytest, Ruff, and build tooling |
@@ -52,6 +54,18 @@ with `index.url`; a user-owned cloud or remote server can use an API key named
 by `index.api_key_env`. Keep the key in the environment. See
 [`integrations/qdrant.md`](integrations/qdrant.md).
 
+## PostgreSQL / pgvector
+
+Install the optional adapter with `python -m pip install "embedflow[pgvector]"`.
+The adapter connects to an existing table and reads the DSN from the
+environment; see [`integrations/pgvector.md`](integrations/pgvector.md).
+
+## Pinecone
+
+Install the optional adapter with `python -m pip install "embedflow[pinecone]"`.
+Set `PINECONE_API_KEY` in the environment and configure an existing dense
+index host; see [`integrations/pinecone.md`](integrations/pinecone.md).
+
 ## CPU and GPU
 
 The deterministic demo runs on CPU. Real model serving accepts `--device cpu`

embedflow-0.3.0/docs/integrations/pgvector.md

@@ -0,0 +1,140 @@
+# PostgreSQL / pgvector
+
+EmbedFlow can read candidates from an existing PostgreSQL table that uses the
+[pgvector](https://github.com/pgvector/pgvector) extension. The adapter uses
+the shared `VectorIndex` interface, so analysis, serving, cache warming, and
+the API follow the same path as FAISS and Qdrant.
+
+## Install
+
+```bash
+python -m pip install "embedflow[pgvector]"
+```
+
+The extra installs Psycopg 3 with its binary distribution. The base
+`embedflow` install does not import or require PostgreSQL dependencies.
+
+## Connection and table layout
+
+Keep the DSN in an environment variable:
+
+```bash
+export EMBEDFLOW_PGVECTOR_DSN='postgresql://user:password@localhost:5432/app'
+```
+
+Example configuration:
+
+```yaml
+source:
+  model: sentence-transformers/all-MiniLM-L6-v2
+  device: cpu
+
+target:
+  model: Qwen/Qwen3-Embedding-0.6B
+  device: cpu
+
+index:
+  backend: pgvector
+  dsn_env: EMBEDFLOW_PGVECTOR_DSN
+  schema: public
+  table: documents
+  id_column: id
+  vector_column: embedding
+  text_column: content
+  metric: cosine
+  # hnsw_ef_search: 100
+  # ivfflat_probes: 20
+
+documents:
+  # Omit this file when text_column is present in the table. A separate
+  # JSONL document store can be supplied when the table stores IDs only.
+  path: ./documents.jsonl
+  id_field: id
+  text_field: text
+```
+
+When `documents.path` does not exist, EmbedFlow resolves candidate text from
+`text_column` in the configured table. If a JSONL file exists, it remains the
+document store and the pgvector table is used for vectors and IDs. The adapter
+only reads the table during ordinary `analyze`, `serve`, `search`, `status`,
+and `audit-index` operations; it does not create extensions, indexes, tables,
+or modify rows.
+
+The ID column may be an integer, bigint, UUID, or text type. IDs are normalized
+to EmbedFlow's canonical string representation without numeric coercion.
+The configured vector dimension is checked against `vector(n)` where available
+and against a bounded non-null row for unbounded `vector` columns.
+
+## Metrics and score direction
+
+Supported metrics are `cosine`, `l2`/`euclidean`, and
+`inner_product`/`dot`. pgvector's distance operators are converted to the
+EmbedFlow convention where larger scores rank first:
+
+| EmbedFlow metric | pgvector operator | Internal score |
+| --- | --- | --- |
+| cosine | `<=>` | `1 - distance` |
+| l2 / euclidean | `<->` | `-distance` |
+| inner_product / dot | `<#>` | `-distance` |
+
+The last conversion accounts for pgvector's negative inner-product operator.
+
+## ANN settings
+
+EmbedFlow never creates or changes an ANN index. If configured, `hnsw_ef_search`
+and `ivfflat_probes` are applied with transaction-local `set_config` calls for
+the retrieval query. Omit them to use the database/index defaults. The
+`metadata()` and `audit-index` output reports configured settings and detected
+valid HNSW/IVFFlat indexes when PostgreSQL exposes them.
+
+## Commands
+
+```bash
+embedflow analyze --config embedflow.yaml
+embedflow serve --config embedflow.yaml
+embedflow search --config embedflow.yaml "what causes auroras?"
+embedflow status --config embedflow.yaml
+embedflow audit-index --config embedflow.yaml
+```
+
+`audit-index` checks table and column presence, pgvector type and dimension,
+NULL vectors, duplicate canonical IDs, a retrieval probe, and available ANN
+metadata. A successful connection is not an ANN recall audit; use an exact
+reference comparison when fidelity matters.
+
+## Local example
+
+The repository includes a small Docker example that creates a disposable
+pgvector table and index:
+
+```bash
+cd examples/pgvector
+docker compose up -d
+export EMBEDFLOW_PGVECTOR_DSN='postgresql://embedflow:embedflow@localhost:5432/embedflow'
+./run_demo.sh
+```
+
+The example is for local testing only. It contains no credentials for a real
+service and does not represent a production database configuration.
+
+## Troubleshooting
+
+- `pgvector support requires psycopg`: install `embedflow[pgvector]` in the
+  active environment.
+- `DSN not found`: export the variable named by `index.dsn_env`.
+- `table ... was not found`: check the schema/table spelling and database.
+- `is not a pgvector column`: install/enable the extension in the database and
+  point `vector_column` at a `vector` column.
+- Dimension mismatch: set `source.dimension` to the encoder's dimension and
+  verify the table's vector type.
+- Authentication errors are redacted in EmbedFlow output; inspect PostgreSQL
+  server logs without pasting passwords into issue reports.
+
+## Limitations
+
+The adapter currently exposes the common table layout and no arbitrary SQL
+filters. Metadata filtering will follow the shared backend interface when that
+interface gains a portable filter contract. Connection operations on one
+adapter are serialized; applications needing a larger pool can create several
+sessions behind their own pool. ANN health is reported as `UNKNOWN` unless a
+reference comparison is run.