@camstack/addon-detection-pipeline 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,638 @@
+import * as _camstack_types from '@camstack/types';
+import { StepDefinition, ModelFormat, IPipelineExecutorProvider, IScopedLogger, IEventBus, ConfigUISchema, PipelineEngineChoice, PipelineSchema, AvailableEngine, PipelineDefaultStep, PipelineConfig, InferenceCapabilities, ModelAvailability, PipelineRunInput, FrameResult, FrameInput, DetectorOutput, PipelineTemplate, PipelineTemplateStep, ConfigUISchemaWithValues, IAddonResolver, BaseAddon, ProviderRegistration, ModelCatalogEntry } from '@camstack/types';
+export { PoolModelConfig, PostprocessorType, StepDefinition } from '@camstack/types';
+
+/**
+ * Pipeline step classes — each step implements IPipelineStep.
+ *
+ * `definition` holds the static metadata (models, labels, postprocessor, etc.).
+ * `getConfigSchema()` declares per-step settings (class filters, thresholds)
+ * that the UI renders dynamically and that can be overridden per-run.
+ */
+
+/** Compat: flat array of StepDefinition for existing consumers */
+declare const ALL_STEPS: readonly StepDefinition[];
+/**
+ * Look up a step definition by ID (compat shortcut).
+ * @throws if the step ID is not registered.
+ */
+declare function getStepDefinition(stepId: string): StepDefinition;
+/**
+ * Get the default model ID for a step given the current model format.
+ * Selects the smallest model that supports the format.
+ * Falls back to StepDefinition.defaultModelId if no format-specific model found.
+ */
+declare function getDefaultModelForFormat(stepId: string, format: ModelFormat): string;
+
+type BatchMode$1 = 'none' | 'list' | 'window';
+/**
+ * Per-runtime pool tuning surfaced through addon-detection-pipeline
+ * settings. All fields optional — undefined means "use the runtime
+ * default resolved in `engine-factory`".
+ */
+interface PoolTuning {
+    readonly batchMode?: BatchMode$1;
+    readonly windowMs?: number;
+    readonly maxBatchSize?: number;
+    readonly numStreams?: number;
+    readonly intraOpThreads?: number;
+}
+
+declare class DetectionPipelineProvider implements IPipelineExecutorProvider {
+    private readonly modelsDir;
+    private readonly eventBus;
+    /**
+     * Closure that returns the addon's config schema. Injected by the addon
+     * class at construction so the provider can serve `getDetectionConfigSchema`
+     * directly. The addon owns both pieces — no public setter needed.
+     */
+    private readonly detectionConfigSchemaSource;
+    /**
+     * Executor tuning forwarded to the `EngineFactory`. Exposes
+     * `concurrency` (Python inference-pool worker threads) plus the
+     * per-runtime batch tuning (`tuning`). Undefined fields fall back
+     * to runtime defaults — see engine-factory.ts.
+     *
+     * `pythonPath` is the absolute path to the embedded Python (resolved
+     * once by the addon class via `ctx.deps.ensurePython()`); required
+     * whenever `runtime: 'python'` is selected. `pythonAddonDir` points
+     * to this addon's `python/` dir at runtime — used to locate the
+     * `requirements*.txt` files that drive lazy backend installs.
+     */
+    private readonly executorOptions;
+    private engineFactory;
+    private executor;
+    private currentSteps;
+    private currentEngine;
+    private readonly log;
+    /** Addon context — ctx.api resolves lazily (direct caller created after boot) */
+    private addonCtx;
+    /**
+     * Per-device {@link DeviceProxy} cache used for zone gating at the
+     * runtime path. Reads `state.zones.value` + `state.zoneRules.value`
+     * synchronously per frame so detections inside an `exclude` zone
+     * never reach the tracker downstream — saves the tracking + event
+     * cost on top of the analytics-side filter.
+     */
+    private readonly deviceProxies;
+    private readonly proxyUnsubs;
+    /** Initialization lock — ensures only one init runs at a time; concurrent callers await the same promise */
+    private initPromise;
+    /**
+     * Last logged "step configured" signature — used to dedupe the
+     * per-step debug trail so it only fires on actual config CHANGE
+     * (not on every frame). `runPipeline` is called once per decoded
+     * frame (up to detectionFps × N cameras), so even at debug level
+     * the per-step dump produced ~50 lines/sec/camera and drowned the
+     * Cluster log viewer.
+     */
+    private lastStepsSignature;
+    /**
+     * True once the engine + models are fully ready for inference. No
+     * longer gates runtime dispatch (Phase 4 removed the legacy `runFrame`
+     * which read this flag); kept as a diagnostic the admin UI / tests
+     * surface via the future `isReady()` helper.
+     */
+    private ready;
+    /**
+     * Warm cache for benchmark engine-override runs.
+     *
+     * Each override rebuild costs a full Python pool spin-up (~300-500ms)
+     * plus the per-model load. Benchmark tabs iterate up to 800× against
+     * the same override (e.g. yolov9s / coreml / all) — paying that spin-up
+     * each iteration dwarfs actual inference time.
+     *
+     * When the same override engine is requested within `OVERRIDE_CACHE_TTL_MS`,
+     * we reuse the prior transient factory. Hitting a different override
+     * or exceeding the TTL disposes the cache and spins a new factory.
+     * The prior "main" factory (`priorFactory`) is still restored so
+     * runtime dispatch (camera frames) keeps its own resident engine.
+     */
+    private overrideCache;
+    private overrideCacheTimer;
+    private static readonly OVERRIDE_CACHE_TTL_MS;
+    /** Read the addon settings store (all keys). */
+    private readonly readStore;
+    /** Write a patch to the addon settings store. */
+    private readonly writeStore;
+    /** Read per-device settings. */
+    private readonly readDeviceStore;
+    constructor(settings: {
+        readAddonStore(): Promise<Record<string, unknown>>;
+        writeAddonStore(patch: Record<string, unknown>): Promise<void>;
+        readDeviceStore?(deviceId: number): Promise<Record<string, unknown>>;
+    }, modelsDir: string, logger: IScopedLogger, eventBus?: IEventBus | null, 
+    /**
+     * Closure that returns the addon's config schema. Injected by the addon
+     * class at construction so the provider can serve `getDetectionConfigSchema`
+     * directly. The addon owns both pieces — no public setter needed.
+     */
+    detectionConfigSchemaSource?: (() => ConfigUISchema) | null, 
+    /**
+     * Executor tuning forwarded to the `EngineFactory`. Exposes
+     * `concurrency` (Python inference-pool worker threads) plus the
+     * per-runtime batch tuning (`tuning`). Undefined fields fall back
+     * to runtime defaults — see engine-factory.ts.
+     *
+     * `pythonPath` is the absolute path to the embedded Python (resolved
+     * once by the addon class via `ctx.deps.ensurePython()`); required
+     * whenever `runtime: 'python'` is selected. `pythonAddonDir` points
+     * to this addon's `python/` dir at runtime — used to locate the
+     * `requirements*.txt` files that drive lazy backend installs.
+     */
+    executorOptions?: {
+        concurrency?: number;
+        tuning?: PoolTuning;
+        pythonPath?: string;
+        pythonAddonDir?: string;
+        numWorkers?: number;
+    });
+    /** Load persisted engine choice. Call after construction. */
+    init(): Promise<void>;
+    /**
+     * Lazy-install the pip requirements file matching `engine.backend` into
+     * the embedded Python before the inference pool spawns. No-op for
+     * `runtime: 'node'`, for backends with no requirements file on disk,
+     * or before the addon context has been wired (warm-pool race window).
+     *
+     * Idempotent — `installPythonRequirements` short-circuits on a hash
+     * marker, so back-to-back EngineFactory rebuilds (benchmark overrides,
+     * tuning respawns) skip the pip subprocess after the first install.
+     */
+    private ensureBackendDeps;
+    /**
+     * Warm the Python inference pool up-front so consumers that hit
+     * `runPipeline` on the first frame don't race the pool's spawn
+     * (`SharedInferencePool: not initialized`). Called from the addon's
+     * `onInitialize` so `BaseAddon.autoEmitReadiness` fires `ready`
+     * only after the pool is actually callable — consumers that
+     * `awaitReady('pipeline-executor', {node:…})` now get a true
+     * "callable" signal, not a "process started" signal.
+     *
+     * Idempotent: delegates to `ensureEngineFactory` which short-circuits
+     * on a warmed pool.
+     */
+    warmPool(): Promise<void>;
+    /** True when the engine + model pool are fully warmed and inference-ready. */
+    isReady(): boolean;
+    /** Detect the best inference engine for this platform. */
+    private static detectBestEngine;
+    /** Store the addon context. ctx.api is a lazy getter resolved at call time. */
+    setApi(addonCtx: unknown): Promise<void>;
+    getSchema(engine?: PipelineEngineChoice): Promise<PipelineSchema>;
+    getAvailableEngines(): Promise<PipelineEngineChoice[]>;
+    getAvailableEnginesWithDevices(): AvailableEngine[];
+    getDefaultSteps(engine: PipelineEngineChoice): Promise<PipelineDefaultStep[]>;
+    getGlobalSteps(): Promise<PipelineDefaultStep[] | null>;
+    getGlobalPipelineConfig(): Promise<PipelineConfig | null>;
+    getSelectedEngine(): Promise<PipelineEngineChoice>;
+    getOrchestratorConfigSchema(): Promise<ConfigUISchema>;
+    getCapabilities(_forceRefresh?: boolean): Promise<InferenceCapabilities>;
+    getAddonModels(input: {
+        addonId: string;
+    }): Promise<readonly ModelAvailability[]>;
+    getDetectionConfigSchema(): Promise<ConfigUISchema | null>;
+    downloadModel(input: {
+        modelId: string;
+        format: ModelFormat;
+        addonId: string;
+    }): Promise<{
+        filePath: string;
+        sizeMB: number;
+        durationMs: number;
+    }>;
+    deleteModel(input: {
+        modelId: string;
+        format: ModelFormat;
+        addonId: string;
+    }): Promise<{
+        success: true;
+    }>;
+    runPipeline(input: PipelineRunInput, onProgress?: (message: string) => void): Promise<FrameResult>;
+    /**
+     * Apply a benchmark engine override (mirroring the body of `runPipeline`
+     * lines 863-953). Swaps `currentEngine` / `engineFactory` / `executor`
+     * to the override's warm factory and returns a restore function the
+     * caller MUST invoke in `finally`. When `override` is undefined or
+     * matches the current engine, this is a no-op and the restore function
+     * does nothing — same shape so callers don't need a conditional path.
+     *
+     * Used by both `runPipeline` (single-frame benchmark) and
+     * `runPipelineBatch` (batched fast path). Without this, the batch
+     * path silently ignored `input.engine` and ran the user's override
+     * against the addon's saved engine — making the override matrix in
+     * the bench UI a no-op for batchSize > 1.
+     */
+    private applyEngineOverride;
+    /**
+     * Schedule eviction of the override cache after `OVERRIDE_CACHE_TTL_MS`
+     * of idleness. Rescheduling resets the timer so an active benchmark
+     * keeps its warm factory alive until iterations stop arriving.
+     */
+    private scheduleOverrideCacheEviction;
+    private evictOverrideCache;
+    /** Convert PipelineStepInput[] → PipelineDefaultStep[] by enriching from StepDefinitions */
+    private inputStepsToPipelineSteps;
+    /**
+     * Single-flight gate around `ensureModelsForSteps`. Concurrent
+     * callers (every camera that fires motion in the same window calls
+     * `runPipeline` → `ensureModelsForSteps`) share the same in-flight
+     * promise instead of each racing into `loadAdditional`. Without this
+     * the pool gets the SAME model loaded N times under N distinct
+     * pool indices because every caller saw `isLoadedWithModel === false`
+     * before any of them committed via `stepToLoaded.set`.
+     */
+    private modelLoadInFlight;
+    /** Ensure all models needed by steps are downloaded and loaded in the engine pool. */
+    private ensureModelsForSteps;
+    /** Download a model with retry + exponential backoff */
+    private downloadWithRetry;
+    /** Parse JPEG/PNG dimensions without decoding the full image */
+    private getJpegDimensions;
+    /** Fast JPEG dimension parsing from SOF marker (no external deps) */
+    private parseJpegDimensions;
+    detect(input: {
+        addonId: string;
+        frame: FrameInput;
+        config?: Record<string, unknown>;
+    }): Promise<DetectorOutput>;
+    /**
+     * Batched run — dispatches N raw frames against the same loaded
+     * single-step model in one IPC round-trip via
+     * `EngineFactory.batchInferRaw`. Falls back to N parallel
+     * `runPipeline` calls when the fast path's preconditions don't hold
+     * (multi-step tree, crop children, JPEG-only frames, Node ONNX
+     * factory). Returns one minimally-shaped `FrameResult` per input
+     * frame in input order.
+     *
+     * Used by `scripts/bench-scrypted-style.mts` for the
+     * Scrypted-equivalent benchmark — Scrypted's `detectObjects(media,
+     * {batch})` collapses N requests into one call too, so bypassing
+     * the per-call IPC overhead is what makes the comparison fair.
+     */
+    runPipelineBatch(input: {
+        readonly steps: readonly _camstack_types.PipelineStepInput[];
+        readonly engine?: PipelineEngineChoice;
+        readonly frames: readonly FrameInput[];
+        readonly deviceId?: number;
+        readonly sessionId?: string;
+    }): Promise<{
+        readonly results: readonly FrameResult[];
+    }>;
+    private runPipelineBatchImpl;
+    listReferenceImages(): Promise<Array<{
+        id: string;
+        filename: string;
+        sizeKB: number;
+    }>>;
+    getReferenceImage(input: {
+        filename: string;
+    }): Promise<{
+        base64: string;
+        filename: string;
+    } | null>;
+    private resolveRefImagesDir;
+    listTemplates(): Promise<PipelineTemplate[]>;
+    saveTemplate(input: {
+        name: string;
+        steps: readonly PipelineTemplateStep[];
+        engine: PipelineEngineChoice;
+    }): Promise<PipelineTemplate>;
+    updateTemplate(input: {
+        id: string;
+        name?: string;
+        steps?: readonly PipelineTemplateStep[];
+    }): Promise<PipelineTemplate>;
+    deleteTemplate(input: {
+        id: string;
+    }): Promise<void>;
+    getDeviceSettingsContribution(_input: {
+        deviceId: number;
+    }): Promise<ConfigUISchemaWithValues | null>;
+    getDeviceLiveContribution(_input: {
+        deviceId: number;
+    }): Promise<ConfigUISchemaWithValues | null>;
+    applyDeviceSettingsPatch(_input: {
+        deviceId: number;
+        patch: Record<string, unknown>;
+    }): Promise<{
+        success: true;
+    }>;
+    getAddonResolver(): Promise<IAddonResolver>;
+    shutdown(): Promise<void>;
+    /**
+     * Resolve and cache a {@link DeviceProxy} for the given camera. Pins
+     * the `state.zones` + `state.zoneRules` slice handles so `.value`
+     * stays warm via the kernel runtime-state mirror, and runtime gate
+     * reads in `runPipeline` are sync (zero per-frame round-trip).
+     * Returns null when the addon context isn't available — the gate
+     * falls back to "no filtering" instead of blocking inference.
+     */
+    private ensureDeviceProxy;
+    private releaseDeviceProxy;
+    /**
+     * Apply detection-stage zone rules to a {@link FrameResult}. Drops
+     * first-level detections whose center lies in an `exclude` rule's
+     * zones (or, in whitelist mode, isn't in any `include` rule's
+     * zones), and any `detail` children whose `parentId` references a
+     * dropped first-level. Returns the original result unchanged when
+     * the gate has nothing to filter (no zones, no rules, or no
+     * detections).
+     */
+    private gateDetectionsByZoneRules;
+    cacheFrameInPool(input: {
+        readonly data: Uint8Array;
+        readonly width: number;
+        readonly height: number;
+        readonly format: 'rgb' | 'bgr' | 'gray';
+    }): Promise<{
+        frameId: number;
+        width: number;
+        height: number;
+    }>;
+    inferCached(input: {
+        readonly stepId: string;
+        readonly frameId: number;
+    }): Promise<Record<string, unknown>>;
+    uncacheFrame(input: {
+        readonly frameId: number;
+    }): Promise<void>;
+    getEffectiveTuning(): Promise<{
+        batchMode: string;
+        windowMs: number;
+        maxBatchSize: number;
+        concurrency: number;
+    }>;
+    /**
+     * Ensure the engine factory + inference pool is initialized.
+     * Does NOT require global steps — used by benchmark/test paths that provide their own steps.
+     * If global steps exist, initializes with them. Otherwise, creates an empty pool.
+     */
+    private ensureEngineFactory;
+    private ensureExecutor;
+    /** Actual initialization — download models, create engine, load pool. Called once. */
+    private doInitialize;
+    /**
+     * Phase 2b — resolve the engine from the addon's new schema-backed
+     * fields (`engineRuntime`, `engineBackend`, `engineDevice`). Fallback
+     * to the legacy `KEY_ENGINE` JSON blob for pre-migration stores.
+     * Returns null when neither source has anything; the caller keeps
+     * whatever `detectBestEngine()` picked at construction.
+     */
+    private loadEngine;
+    /**
+     * Synchronous availability probe for a Python inference backend. Runs a
+     * short `python3 -c "import <mod>"` with a 3s timeout. Used at
+     * `loadEngine` time to reject a persisted backend choice the Python
+     * interpreter on this host can't actually import — without this the
+     * detection-pipeline child process exits with code 1 the moment
+     * `inference_pool.py` hits its `from openvino.runtime import Core`.
+     */
+    private static isPythonBackendAvailable;
+    /**
+     * Re-run the platform probe for the inference engine and persist the
+     * result into the addon's own global-settings keys. Because those
+     * fields are declared `requiresRestart: true`, the
+     * `updateGlobalSettings` pathway auto-schedules an addon restart —
+     * here we do the write directly via the settings store and trigger
+     * restart manually through the addons cap.
+     *
+     * Returns the chosen engine so the UI can confirm the pick without a
+     * second round-trip.
+     */
+    /**
+     * Phase 2c — flat per-addonId map holding the video-pipeline step
+     * config (`modelId` / `settings`). No `enabled` field: whether an
+     * addon step runs is a capability-binding concern, not a
+     * pipeline-config one. Replaces the orchestrator's per-agent
+     * `addonDefaults`. The map is the source of truth; the tree consumed
+     * by the executor (`PipelineDefaultStep[]`) is materialised from
+     * this map + catalog compat at read time (not done in this commit —
+     * phase 2f wires the resolver through).
+     */
+    getVideoPipelineSteps(): Promise<Record<string, {
+        modelId: string;
+        settings: Readonly<Record<string, unknown>>;
+    }>>;
+    setVideoPipelineSteps(input: {
+        readonly steps: Record<string, {
+            modelId: string;
+            settings: Readonly<Record<string, unknown>>;
+        }>;
+    }): Promise<{
+        success: true;
+    }>;
+    listLoadedEngines(): Promise<readonly {
+        engineKey: string;
+        engine: PipelineEngineChoice;
+        modelsLoaded: readonly string[];
+        inUseByCameras: readonly number[];
+        kind: 'runtime' | 'warm-override';
+        poolPid: number | null;
+        idleMs: number | null;
+        idleTtlMs: number | null;
+    }[]>;
+    spinEngine(input: {
+        engine: PipelineEngineChoice;
+    }): Promise<{
+        success: true;
+    }>;
+    killEngine(input: {
+        engine: PipelineEngineChoice;
+        force?: boolean;
+    }): Promise<{
+        success: boolean;
+        reason?: string;
+    }>;
+    reprobeEngine(): Promise<PipelineEngineChoice>;
+    getReferenceAudioFiles(): Promise<readonly {
+        filename: string;
+        sizeKb: number;
+    }[]>;
+    getReferenceAudio(input: {
+        filename: string;
+    }): Promise<{
+        base64: string;
+    }>;
+    getAudioCapabilities(): Promise<{
+        activeBackend: string;
+        availableBackends: readonly {
+            id: string;
+            name: string;
+            description: string;
+            available: boolean;
+            rawLabels?: readonly string[];
+        }[];
+        sampleRate: number;
+        chunkDurationMs: number;
+    }>;
+    runAudioTest(input: {
+        addonId: string;
+        modelId: string;
+        filename?: string;
+        settings?: Record<string, unknown>;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+        frame?: _camstack_types.AudioResult;
+    }>;
+}
+
+/**
+ * Select the best inference engine for the current platform.
+ * Order: CoreML (macOS ARM) > CUDA (NVIDIA) > OpenVINO (Intel) > CPU
+ */
+type EngineRuntime = 'node' | 'python';
+type BatchMode = 'none' | 'list' | 'window';
+interface DetectionPipelineConfig {
+    /**
+     * Python inference-pool worker concurrency.
+     * `0` = runtime-aware auto default (resolved in engine-factory):
+     *   coreml: 1 — matrix bench shows >1 hurts (CoreML serializes per-context).
+     *   onnxruntime: 4 — InferenceSession.run is thread-safe; scales with cores.
+     *   openvino: 1 — OV runtime manages internal infer-request pool.
+     * Non-zero values override the auto default.
+     */
+    readonly concurrency: number;
+    /**
+     * Pool batch dispatch strategy. Set per-backend; defaults injected by
+     * `getGlobalSettings(overlay)` based on `engineBackend`.
+     *   - 'none'   : one predict_fn per item (no batching)
+     *   - 'list'   : MSG_INFER_BATCH dispatched as `model.predict([{},{}...])`
+     *   - 'window' : per-model accumulator coalesces concurrent MSG_INFER_RAW
+     *                calls within `windowMs`, flushes via single batched predict.
+     */
+    readonly batchMode: BatchMode | '';
+    /** Window-mode accumulator flush window (ms). Only honored when batchMode='window'. 0 = auto. */
+    readonly windowMs: number;
+    /** Max items per batched predict call. Only honored when batchMode!='none'. 0 = auto. */
+    readonly maxBatchSize: number;
+    /** OpenVINO num_streams hint. 0 = auto. */
+    readonly numStreams: number;
+    /** ONNX Runtime intra-op thread count. 0 = auto. */
+    readonly intraOpThreads: number;
+    /**
+     * Number of independent Python subprocess workers in the inference
+     * pool. Each worker holds its own MLModel copy + predict context;
+     * inference dispatches round-robin across them. 0 = runtime-aware
+     * default (CoreML: 2 — required to lift the single-context ANE cap
+     * on multi-camera workloads; non-CoreML backends: 1, since they
+     * manage their own internal parallelism). Model load/unload
+     * propagate to all workers, so RAM cost scales linearly with
+     * `numWorkers × modelSize`.
+     */
+    readonly numWorkers: number;
+    /** Chain level 1 — Python vs Node host runtime. */
+    readonly engineRuntime: EngineRuntime;
+    /** Chain level 2 — backend within the runtime. */
+    readonly engineBackend: string;
+    /** Chain level 3 — hardware device within the backend. */
+    readonly engineDevice: string;
+    /**
+     * Readable snapshot of the last-probed platform-best engine. Format:
+     * `"runtime/backend/device"`. Set by `reprobeEngine()`; the UI shows
+     * it next to the cascade as a hint + provides a "Re-probe" button.
+     */
+    readonly probedBestEngine: string;
+}
+/** Derive the model-format from a backend value. Called by the provider. */
+declare function backendToFormat(backend: string): 'onnx' | 'coreml' | 'openvino';
+declare class DetectionPipelineAddon extends BaseAddon<DetectionPipelineConfig> {
+    private provider;
+    private engineMetricsTimer;
+    /** Snapshot-equality cache for engine-metrics emit. Most ticks
+     *  the engine inventory is unchanged (no model load/unload), so
+     *  we skip the bus emit and let the heartbeat re-emit at
+     *  ENGINE_METRICS_HEARTBEAT_MS for liveness. */
+    private lastEmittedEngineSnapshot;
+    /**
+     * Last-applied tuning snapshot, taken at the end of `onInitialize`
+     * and refreshed at the end of `onConfigChanged`. Lets the change
+     * handler diff the current config against the snapshot and decide
+     * whether a pool respawn is necessary — most config edits (engine
+     * cascade, audio settings) don't touch the tuning fields and don't
+     * deserve a multi-second model reload.
+     */
+    private lastAppliedPoolConfig;
+    /**
+     * Embedded Python path resolved once at boot via
+     * `ctx.deps.ensurePython()`. Empty string means the download failed
+     * or `runtime: 'node'` was selected — the provider's
+     * `ensureBackendDeps` and EngineFactory's `initPythonPool` raise a
+     * clear error in that case.
+     */
+    private pythonPath;
+    /**
+     * Absolute path to the addon's bundled `python/` dir (resolved once
+     * at boot), passed through to the provider so per-backend
+     * `requirements-<runtime>.txt` files can be located at lazy-install
+     * time.
+     */
+    private pythonAddonDir;
+    constructor();
+    protected globalSettingsSchema(): _camstack_types.ConfigUISchema;
+    /**
+     * Override to inject dynamic backend + device options based on the
+     * currently-stored runtime + backend. The base schema ships with
+     * placeholder lists; here we replace them with the valid subset for
+     * whatever the operator has picked. Combined with `immediate: true`
+     * on the selects, the UI can refetch after each change and see the
+     * next level's options narrow down.
+     */
+    getGlobalSettings(overlay?: Record<string, unknown>): Promise<ConfigUISchemaWithValues>;
+    /**
+     * Ask the platform-probe cap which backends are actually installable
+     * on this node (checks for `openvino`, `coremltools`, `onnxruntime`
+     * Python modules + hardware presence). Returns a subset of the static
+     * catalog; an empty list signals the probe wasn't available so the
+     * caller should fall back to the full catalog rather than hiding
+     * every option.
+     */
+    private resolveAvailableBackends;
+    /**
+     * Resolve the effective pool tuning for the configured backend.
+     *
+     * Reads `TUNING_DEFAULTS[backend]` and ignores any persisted override
+     * for `concurrency / batchMode / windowMs / maxBatchSize / numStreams /
+     * intraOpThreads`. Stored values are quietly discarded so an old
+     * suboptimal user-override (saved when the UI exposed these knobs)
+     * cannot resurrect itself after a restart.
+     *
+     * The matrix sweep (`bench-pool-matrix.py` + `bench-coreml-patterns.py`)
+     * already chose the best per-backend combo; the operator no longer has
+     * a reason to disagree.
+     */
+    private resolveBackendTuning;
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    /**
+     * Emit a single `pipeline.engine-metrics-snapshot` event with the
+     * current engine inventory for this node. Source of truth is the
+     * provider's `listLoadedEngines` method (same data the cap returns).
+     */
+    private emitEngineMetricsSnapshot;
+    getModelCatalog(): ModelCatalogEntry[];
+    protected onShutdown(): Promise<void>;
+    /**
+     * Snapshot the pool-bound subset of the EFFECTIVE tuning (post-
+     * `resolveBackendTuning`). Stored config values for these fields are
+     * ignored, so this snapshot only changes when `engineBackend` flips
+     * onto a different `TUNING_DEFAULTS` row.
+     */
+    private snapshotPoolConfig;
+    private poolConfigChanged;
+    /**
+     * BaseAddon calls `onConfigChanged` after every settings write.
+     * Group-runner addons can't honour the schema's `requiresRestart:
+     * true` flag (the restart cap returns "process not found" for
+     * processes spawned in a kernel group worker). To make tuning
+     * changes actually take effect, watch the pool-bound subset and
+     * respawn the provider in place when it flips.
+     *
+     * Engine cascade (`engineRuntime/Backend/Device`) and audio
+     * settings don't require this — those still rely on the addon
+     * lifecycle (engineFactory rebuild on next runPipeline).
+     */
+    protected onConfigChanged(): Promise<void>;
+}
+
+export { ALL_STEPS, DetectionPipelineProvider, backendToFormat, DetectionPipelineAddon as default, getDefaultModelForFormat, getStepDefinition };