@camstack/types 1.2.315 → 1.2.317

package/dist/pipeline/best-settings/demand.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Detection demand per inference device, for the Best settings recommender
+ * (D745). Pure.
+ *
+ * Demand is inferences per second a device must sustain:
+ *
+ *  - a camera PINNED to a device charges its full rate to that device;
+ *  - an ALWAYS-ON camera charges its rate to its standing node, split over
+ *    that node's eligible devices by balancer weight (the device tier rotates
+ *    ties, so the weight share is the long-run split);
+ *  - ON-MOTION cameras are placed per session anywhere in the cluster, so
+ *    they are charged by how many sessions a device has really carried at
+ *    once: the observed 24 h peak of attached sessions on that device, minus
+ *    the always-on cameras it already counts, filled with the highest
+ *    on-motion rates. A device observed for less than 24 h (the hub
+ *    restarted) falls back to a fixed estimate — a quarter of the on-motion
+ *    cameras, at least two, spread evenly over the nodes and by weight over a
+ *    node's devices — and the plan says so.
+ *
+ * Every device must also fit the single fastest camera that can land on it:
+ * one session cannot be split across devices.
+ */
+import type { DeviceDemand } from './plan-schemas.js';
+/** How a camera's detection runs. `disabled` cameras charge nothing. */
+export type BestSettingsDetectionMode = 'always-on' | 'on-motion' | 'disabled';
+/** One camera's detection load. */
+export interface BestSettingsCameraLoad {
+    readonly deviceId: number;
+    readonly mode: BestSettingsDetectionMode;
+    /** Detection frames per second while a session runs. */
+    readonly fps: number;
+    /** False when only the camera's own (onboard) detector runs — no pipeline root. */
+    readonly runsPipelineRoot: boolean;
+    /** The node an always-on camera stands on; null when not placed (on-motion). */
+    readonly standingNodeId: string | null;
+    /** An operator pin of this camera to one `(node, device)`. */
+    readonly devicePin: {
+        readonly nodeId: string;
+        readonly deviceKey: string;
+    } | null;
+}
+/** A device the balancer may place a session on. */
+export interface BestSettingsEligibleDevice {
+    readonly nodeId: string;
+    readonly deviceKey: string;
+    readonly weight: number;
+}
+/** The observed peak of concurrent sessions on one device. */
+export interface ObservedDevicePeak {
+    readonly nodeId: string;
+    /** `''` = the node's sessions as a whole (a single-device node reports no per-device rows). */
+    readonly deviceKey: string;
+    /** Most sessions attached at once in the window. */
+    readonly peakSessions: number;
+    /** How long the device has been observed (ms) — the window is complete at 24 h. */
+    readonly observedForMs: number;
+}
+/** The on-motion load model's knobs. */
+export interface DemandOptions {
+    /** Share of on-motion cameras assumed concurrent when there is no full observation. */
+    readonly onMotionConcurrency: number;
+    /** Minimum concurrent on-motion sessions assumed (capped at the camera count). */
+    readonly onMotionMinConcurrent: number;
+}
+export declare const DEFAULT_DEMAND_OPTIONS: DemandOptions;
+/** A full observation window. */
+export declare const OBSERVATION_WINDOW_MS: number;
+/** Concurrent on-motion sessions assumed cluster-wide without an observation. */
+export declare function estimatedConcurrentSessions(cameraCount: number, options: DemandOptions): number;
+/**
+ * Demand on every eligible device of the cluster.
+ */
+export declare function estimateDeviceDemand(input: {
+    readonly cameras: readonly BestSettingsCameraLoad[];
+    readonly eligible: readonly BestSettingsEligibleDevice[];
+    readonly peaks: readonly ObservedDevicePeak[];
+    readonly options?: DemandOptions;
+}): readonly DeviceDemand[];

package/dist/pipeline/best-settings/detector-performance.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Measured YOLOv9 detector latency per hardware class × accelerator, and the
+ * person accuracy each model reaches at its shipped floor — the data the Best
+ * settings recommender picks from (D745).
+ *
+ * Transcribed from `docs/benchmarks/detector-latency.json` (latency) and
+ * `docs/benchmarks/model-floors.json` (person precision / recall at the
+ * shipped floor). `__tests__/detector-performance.spec.ts` holds both tables
+ * equal to those files, so a re-measurement replaces the JSON and this file
+ * together. Only the YOLOv9 t/s/m family is here: the cluster runs ONE family
+ * (YOLOv9 — the one that runs well on every accelerator class measured), and
+ * tier c is not offered (a few recall points for 25–50 % more latency).
+ */
+import type { AcceleratorKind, HardwareClassId } from './plan-schemas.js';
+/** One measured (or derived) latency cell. */
+export interface DetectorLatencyCell {
+    /** Single-request median latency. */
+    readonly p50Ms: number;
+    /** Throughput ceiling of one accelerator running only this model. */
+    readonly fps: number;
+    /** False for a cell derived from another column (scaled), not measured. */
+    readonly measured: boolean;
+}
+/** `modelId → cell` for one (hardware class, accelerator) column. */
+export type DetectorLatencyColumn = Readonly<Record<string, DetectorLatencyCell>>;
+/** The latency table: hardware class → accelerator → column. */
+export type DetectorPerfTable = Readonly<Partial<Record<HardwareClassId, Readonly<Partial<Record<AcceleratorKind, DetectorLatencyColumn>>>>>>;
+/** Person precision / recall of one model at its shipped person floor. */
+export interface DetectorAccuracy {
+    readonly personPrecision: number;
+    readonly personRecall: number;
+}
+export declare const DETECTOR_PERF: DetectorPerfTable;
+export declare const DETECTOR_ACCURACY: Readonly<Record<string, DetectorAccuracy>>;

package/dist/pipeline/best-settings/hardware-class.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Static hardware classification for the Best settings recommender (D745).
+ *
+ * A node is classified from the facts its platform probe already reports —
+ * `cpuModel`, `arch`, `gpu`, `npu` — never from a benchmark. The class picks a
+ * column of the measured latency table (`detector-performance.ts`); a node
+ * whose CPU matches no measured class is `unknown` and the recommender leaves
+ * it alone, saying so.
+ *
+ * `cpuModel` is the host's CPU string even inside Docker (`os.cpus()`), which
+ * is why it is the discriminator: "Intel(R) Core(TM) Ultra 7 265K",
+ * "Intel(R) N100", "Apple M2", "Apple M3 Pro".
+ */
+import type { HardwareInfo } from '../../interfaces/platform.js';
+import type { AcceleratorKind, HardwareClassId } from './plan-schemas.js';
+/** Apple silicon generation and variant, parsed from `cpuModel`. */
+export interface AppleChip {
+    readonly generation: number;
+    readonly variant: 'base' | 'pro' | 'max' | 'ultra';
+}
+/** How a node was classified. */
+export interface HardwareClassification {
+    readonly hardwareClass: HardwareClassId;
+    /** The CPU string the class was read from, for the plan's reasons. */
+    readonly cpuModel: string;
+    readonly apple?: AppleChip;
+}
+/**
+ * Classify a node. Apple base chips (M1–M4) map to the measured M2 column, the
+ * Pro/Max/Ultra chips to the measured M3 Pro column — the M2 was measured at
+ * 1.0–1.2× the M3 Pro on the Neural Engine, so the generation inside a variant
+ * matters less than the column's own error.
+ */
+export declare function classifyInferenceHardware(hw: HardwareInfo): HardwareClassification;
+/**
+ * The accelerator kind of one of a node's device keys (`openvino:npu`,
+ * `openvino:gpu`, `coreml:all`, `edgetpu:usb`, `cpu`, `onnx:cpu`, …). `null`
+ * for a key this table has no column for.
+ */
+export declare function acceleratorKindOf(deviceKey: string, hw: HardwareInfo): AcceleratorKind | null;

package/dist/pipeline/best-settings/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Best settings (D745): the static-hardware × measured-latency × demand
+ * recommender of ONE detector family for the whole cluster, and the shapes of
+ * its plan. See `recommend.ts`.
+ */
+export * from './hardware-class.js';
+export * from './detector-performance.js';
+export * from './demand.js';
+export * from './recommend.js';
+export * from './plan-schemas.js';