diff --git a/CHANGELOG.md b/CHANGELOG.md index 80b9e9d..da7debc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Documentation + +- **Validator engine status** section in `README.md` and `CodeProjectAiOptions` XML doc remarks rewritten to hard-confirm Blue Onyx as a supported backend (no separate plugin needed — point `Validators::BaseUrl` at the Blue Onyx host and the existing CPAI plugin handles it). Verified end-to-end by an operator on 2026-05-01. Also documented the concrete performance caveat: Blue Onyx GPU acceleration is available only via its Windows EXE/service distribution; the Docker image is CPU-only and slower than CPAI's CUDA-enabled Docker image on the same hardware. Closes #12 (the original "add Blue Onyx validator" ask reduces to docs work since the existing plugin already handles it). + ## [1.0.1] — 2026-05-01 Maintenance release — operator-reported MQTT bugs from the v1.0.0 parity-window debugging session, plus docs accuracy fixes. No breaking config changes; one operator-action item (rename `PUSHOVER__APITOKEN` → `PUSHOVER__APPTOKEN` in `.env` and update Seq/Loki queries keyed on `EventId` → `FrigateEventId`). diff --git a/README.md b/README.md index 8aa2aff..7bfccba 100644 --- a/README.md +++ b/README.md @@ -97,13 +97,30 @@ A full example config lives at `config/appsettings.Example.json`. A minimal exce ## Validator engine status -FrigateRelay ships with one validator plugin today — **CodeProject.AI** — but **active CodeProject.AI development has stopped upstream** (see the project README on GitHub). Existing installs against current and older CPAI versions still work, and the plugin is **API-compatible with [Blue Onyx](https://github.com/MikeLud/CodeProject.AI-Custom-IPcam-Models/discussions)**, so most operators won't notice in the short term. Don't pick CPAI for a *new* setup without checking these alternatives first: +FrigateRelay ships with one validator plugin today — **CodeProject.AI** — but **active CodeProject.AI development has stopped upstream**. The plugin's request shape (`POST /v1/vision/detection`) is also the API exposed by **[Blue Onyx](https://github.com/xnorpx/blue-onyx)**, so the existing plugin is the supported path to either backend. + +### Supported backends (verified) + +- **CodeProject.AI** — the historical default. Existing installs (current and older versions) keep working with no FrigateRelay change. +- **Blue Onyx** — verified working through the existing `FrigateRelay.Plugins.CodeProjectAi` plugin with **no code change**, only a config swap. Point your validator's `BaseUrl` at the Blue Onyx host and port: + ```jsonc + "Validators": { + "Person": { + "Type": "CodeProjectAi", // plugin type — same plugin, different backend + "BaseUrl": "http://blueonyx-host:32168", + "MinConfidence": 0.5, + "OnError": "FailClosed" + } + } + ``` + **Performance caveat:** Blue Onyx supports NVIDIA GPU acceleration **only via its Windows EXE/service distribution**. The Docker image is CPU-only — slower than CPAI's CUDA-enabled Docker image on the same hardware. Acceptable for event-driven validation in the FrigateRelay pipeline (sub-real-time, one inference per matched event); operators with high event rates and no Windows GPU host should benchmark before swapping. + +### Future backends (v1.1 roadmap) -- **Blue Onyx** (#12) — drop-in API-compatible replacement for CPAI. Likely usable through the existing `FrigateRelay.Plugins.CodeProjectAi` plugin unchanged today; a dedicated `FrigateRelay.Plugins.BlueOnyx` plugin is on the v1.1 roadmap. -- **Roboflow Inference / RF-DETR** (#13) — a different detection model architecture; needs its own plugin (planned for v1.1). -- **DOODS2** (#14) — TFLite / TensorFlow / YOLOv5 detector hub; needs its own plugin (planned for v1.1). +- **Roboflow Inference / RF-DETR** (#13) — different detection model architecture; needs its own plugin. +- **DOODS2** (#14) — TFLite / TensorFlow / YOLOv5 detector hub; needs its own plugin. -The CPAI plugin is **not marked obsolete** — older CPAI installs and Blue Onyx-via-CPAI-API users still need it. The deprecation is about the upstream service, not the plugin contract. +The CPAI plugin is **not marked obsolete** — both CPAI users and Blue Onyx users depend on it. The deprecation is about the upstream CodeProject.AI *service*, not the plugin contract or the API shape. ## Migrating from FrigateMQTTProcessingService diff --git a/src/FrigateRelay.Plugins.CodeProjectAi/CodeProjectAiOptions.cs b/src/FrigateRelay.Plugins.CodeProjectAi/CodeProjectAiOptions.cs index 0c99a3f..2702b1f 100644 --- a/src/FrigateRelay.Plugins.CodeProjectAi/CodeProjectAiOptions.cs +++ b/src/FrigateRelay.Plugins.CodeProjectAi/CodeProjectAiOptions.cs @@ -15,13 +15,29 @@ namespace FrigateRelay.Plugins.CodeProjectAi; /// + (CONTEXT-7 D2 / D3). /// /// -/// Upstream status note. Active CodeProject.AI development has stopped -/// upstream. This plugin remains supported because (a) older CPAI installs still work, and -/// (b) the plugin's /v1/vision/detection request shape is API-compatible with -/// Blue Onyx, -/// so existing users on either backend should keep using it. Operators standing up a -/// new validator setup are encouraged to evaluate alternatives — see the -/// "Validator engine status" section in the project README. +/// Backend support. This plugin works against two server-side backends +/// that share the POST /v1/vision/detection request shape: +/// +/// +/// +/// +/// CodeProject.AI — the historical default. Active upstream development +/// has stopped, but current and older installs continue to work unchanged. +/// +/// +/// +/// +/// Blue Onyx — +/// verified working through this plugin with no code change; only +/// needs to point at the Blue Onyx host. Note that NVIDIA GPU acceleration is available +/// only via Blue Onyx's Windows EXE/service distribution; the Docker image is CPU-only. +/// +/// +/// +/// +/// See the "Validator engine status" section in the project README for the full +/// alternative-backends roadmap (Roboflow Inference, DOODS2 — each needs its own plugin +/// since the API shapes differ from CPAI/Blue Onyx). /// /// public sealed class CodeProjectAiOptions