@trillboards/edge-sdk 0.2.4 → 0.2.6

package/dist/keepAwake.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keepAwakeCommand = keepAwakeCommand;
+exports.startKeepAwake = startKeepAwake;
+const child_process_1 = require("child_process");
+/** Build the platform command (exported for tests — pure). */
+function keepAwakeCommand(platform, pid) {
+    if (platform === 'darwin') {
+        return { cmd: 'caffeinate', args: ['-i', '-w', String(pid)] };
+    }
+    if (platform === 'win32') {
+        const script = `$sig='[DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint esFlags);';` +
+            `Add-Type -MemberDefinition $sig -Name P -Namespace TrillboardsKeepAwake;` +
+            `while (Get-Process -Id ${pid} -ErrorAction SilentlyContinue) {` +
+            `[TrillboardsKeepAwake.P]::SetThreadExecutionState([uint32]'0x80000001') | Out-Null;` +
+            `Start-Sleep -Seconds 50 }`;
+        return { cmd: 'powershell', args: ['-NoProfile', '-NonInteractive', '-Command', script] };
+    }
+    return null;
+}
+function startKeepAwake(platform = process.platform, pid = process.pid, spawner = child_process_1.spawn) {
+    const command = keepAwakeCommand(platform, pid);
+    if (!command)
+        return { child: null, stop: () => undefined };
+    let child = null;
+    try {
+        child = spawner(command.cmd, command.args, { stdio: 'ignore' });
+        // Never let the helper hold the event loop open or crash the connector.
+        child.unref();
+        child.on('error', () => {
+            child = null;
+        });
+    }
+    catch {
+        child = null;
+    }
+    if (child) {
+        console.log('Keep-awake active: this computer will not sleep while sensing runs.');
+    }
+    const stop = () => {
+        if (child && !child.killed) {
+            try {
+                child.kill();
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    };
+    // Release on clean exit; the pid-watch (win32) / -w pid (darwin) covers crashes.
+    process.once('exit', stop);
+    return { child, stop };
+}
+//# sourceMappingURL=keepAwake.js.map

package/dist/keepAwake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keepAwake.js","sourceRoot":"","sources":["../src/keepAwake.ts"],"names":[],"mappings":";;AA8BA,4CAiBC;AAED,wCAmCC;AApFD,iDAAyD;AA6BzD,8DAA8D;AAC9D,SAAgB,gBAAgB,CAC9B,QAAyB,EACzB,GAAW;IAEX,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IAChE,CAAC;IACD,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,MAAM,MAAM,GACV,sGAAsG;YACtG,0EAA0E;YAC1E,0BAA0B,GAAG,mCAAmC;YAChE,qFAAqF;YACrF,2BAA2B,CAAC;QAC9B,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAgB,cAAc,CAC5B,WAA4B,OAAO,CAAC,QAAQ,EAC5C,MAAc,OAAO,CAAC,GAAG,EACzB,UAAwB,qBAAK;IAE7B,MAAM,OAAO,GAAG,gBAAgB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAChD,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;IAE5D,IAAI,KAAK,GAAwB,IAAI,CAAC;IACtC,IAAI,CAAC;QACH,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QAChE,wEAAwE;QACxE,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACrB,KAAK,GAAG,IAAI,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,GAAG,IAAI,CAAC;IACf,CAAC;IACD,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CAAC,GAAG,CAAC,qEAAqE,CAAC,CAAC;IACrF,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,CAAC;YAAC,MAAM,CAAC;gBACP,kBAAkB;YACpB,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IACF,iFAAiF;IACjF,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC3B,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC"}

package/dist/legacyRecorderProfile.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Conservative defaults for DVR/NVR feeds. Recorders tend to have fewer RTSP
+ * session slots and slower/noisier codec startup than standalone IP cameras,
+ * so setup marks them and runtime applies this profile automatically.
+ */
+export declare const LEGACY_RECORDER_RUNTIME_PROFILE: {
+    readonly timeoutUs: 18000000;
+    readonly openValidationAttempts: 6;
+    readonly transientRetryDelayMs: 2000;
+    readonly feedStaggerMs: 15000;
+    readonly maxFeedStaggerMs: 90000;
+    readonly cameraHealthFailureGraceCount: 5;
+};
+export type CameraSourceType = 'recorder' | 'direct_url' | undefined;
+export declare function legacyRecorderRtspOptions(sourceType: CameraSourceType): {
+    timeoutUs?: number;
+    openValidationAttempts?: number;
+    transientRetryDelayMs?: number;
+};
+//# sourceMappingURL=legacyRecorderProfile.d.ts.map

package/dist/legacyRecorderProfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacyRecorderProfile.d.ts","sourceRoot":"","sources":["../src/legacyRecorderProfile.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,+BAA+B;;;;;;;CAOlC,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,CAAC;AAErE,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,gBAAgB,GAAG;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAOA"}

package/dist/legacyRecorderProfile.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_RECORDER_RUNTIME_PROFILE = void 0;
+exports.legacyRecorderRtspOptions = legacyRecorderRtspOptions;
+/**
+ * Conservative defaults for DVR/NVR feeds. Recorders tend to have fewer RTSP
+ * session slots and slower/noisier codec startup than standalone IP cameras,
+ * so setup marks them and runtime applies this profile automatically.
+ */
+exports.LEGACY_RECORDER_RUNTIME_PROFILE = {
+    timeoutUs: 18000000,
+    openValidationAttempts: 6,
+    transientRetryDelayMs: 2000,
+    feedStaggerMs: 15000,
+    maxFeedStaggerMs: 90000,
+    cameraHealthFailureGraceCount: 5,
+};
+function legacyRecorderRtspOptions(sourceType) {
+    if (sourceType !== 'recorder')
+        return {};
+    return {
+        timeoutUs: exports.LEGACY_RECORDER_RUNTIME_PROFILE.timeoutUs,
+        openValidationAttempts: exports.LEGACY_RECORDER_RUNTIME_PROFILE.openValidationAttempts,
+        transientRetryDelayMs: exports.LEGACY_RECORDER_RUNTIME_PROFILE.transientRetryDelayMs,
+    };
+}
+//# sourceMappingURL=legacyRecorderProfile.js.map

package/dist/legacyRecorderProfile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacyRecorderProfile.js","sourceRoot":"","sources":["../src/legacyRecorderProfile.ts"],"names":[],"mappings":";;;AAgBA,8DAWC;AA3BD;;;;GAIG;AACU,QAAA,+BAA+B,GAAG;IAC7C,SAAS,EAAE,QAAU;IACrB,sBAAsB,EAAE,CAAC;IACzB,qBAAqB,EAAE,IAAK;IAC5B,aAAa,EAAE,KAAM;IACrB,gBAAgB,EAAE,KAAM;IACxB,6BAA6B,EAAE,CAAC;CACxB,CAAC;AAIX,SAAgB,yBAAyB,CAAC,UAA4B;IAKpE,IAAI,UAAU,KAAK,UAAU;QAAE,OAAO,EAAE,CAAC;IACzC,OAAO;QACL,SAAS,EAAE,uCAA+B,CAAC,SAAS;QACpD,sBAAsB,EAAE,uCAA+B,CAAC,sBAAsB;QAC9E,qBAAqB,EAAE,uCAA+B,CAAC,qBAAqB;KAC7E,CAAC;AACJ,CAAC"}

package/dist/localInferenceSchema.d.ts

@@ -0,0 +1,132 @@
+/**
+ * localInferenceSchema — the route-addressable JSON Schema + prompt the
+ * on-device VLM (LiteRtVlmProvider) is constrained to. This is the subset of
+ * the cloud `buildProfileDrivenJsonSchema` contract that drives OFV →
+ * Sense-Anything routes → WhatsApp: the DEFAULT audience profile fields
+ * (sensingProfileService CLOUD_EMIT_AUDIENCE_FIELDS) + the scalar scene fields.
+ *
+ * ── WHY PLAIN-COMPLETION + NON-NULLABLE (the on-device runtime reality):
+ * LiteRT-LM (`litert-lm serve` 0.13.1) exposes constrained TOOL-CALLING, but its
+ * ANTLR FC tool-call parser 500s whenever Gemma 4 E2B serializes a string with
+ * the special `<|"|>` quote token instead of a literal `"`. That happens
+ * reproducibly on whole classes of frames — measured 0/5 on an empty-room frame
+ * across EVERY tool-call shape (full schema, no-free-text, temp 0.8, even
+ * `response_format`). Empty scenes dominate real CCTV, so tool-calling is not
+ * viable. The SAME frame returns clean, valid JSON via PLAIN completion (no
+ * tools) — measured 8/8 — because the `<|"|>` token is injected only by the
+ * tool-call/constrained path. So LiteRtVlmProvider renders THIS schema as a
+ * human-readable key list, asks for a bare JSON object, and validates the result
+ * client-side (required keys + enum membership) with a retry. That is where the
+ * structured-output GUARANTEE comes from now — client validation, not the
+ * (broken) server grammar. Keep every field NON-nullable with a sentinel value
+ * ('none'/'unclear'/''/0) for "no people"; the localInferenceSchema.test.ts
+ * guard fails the build if a nullable type/enum is reintroduced.
+ *
+ * ── WHY THE FIELD SET IS A PROPERTY OF THE PROFILE (not a global constant):
+ * an SOP/operator profile asks an operational question about the operator's OWN
+ * venue, and the 12 DOOH audience fields answer none of it — two of them
+ * (`scene_description`, `audience_engagement_narrative`) are free-text paragraphs
+ * the model must DECODE on every frame. MEASURED through this exact code on an
+ * M4 Max, real kitchen frame at production capture params (640x480 JPEG q70),
+ * arms INTERLEAVED so machine load lands on both equally:
+ *
+ *   delegate   12 DOOH + 4 operator      operator set (7 keys)     ratio
+ *   CPU        39.22 s/frame (n=4)       25.68 s/frame (n=4)       1.53x
+ *   GPU        10.66 s/frame (n=5)        9.81 s/frame (n=5)       1.09x
+ *
+ * The GPU win is small because litert-lm pins the VISION encoder to CPU
+ * (openai_handler.py `vision_backend = Backend.CPU()`), so image encode is a
+ * fixed per-frame floor no schema can shrink; on the CPU delegate — every host
+ * with no usable GPU delegate — decode is the bill and the lean set is worth
+ * 1.53x. ACCURACY also moved the right way on that run: against the frame's
+ * ground truth the operator set scored 16/16 and the 16-key set 12/16, the
+ * 16-key arm answering `gloves_worn: true` on a scene where only SOME staff are
+ * gloved while the lean arm answered `false`. (On GPU both scored 15/20 — no
+ * accuracy difference there.) Latency is therefore a secondary reason to split
+ * the sets; the primary ones are asking the operator's question instead of a
+ * media buyer's, and keeping `audience_ethnicity` off a camera pointed at the
+ * customer's own staff. See LocalSchemaFieldSet.
+ *
+ * NOTE: the connector SUPPLIES `source='vlm_edge'` and `captured_at` itself
+ * (provenance + time are not the model's to decide) — they are deliberately NOT
+ * in this schema. The server additionally forces provenance `local_connector`
+ * on the preAnalyzed ingest path (gated OUT of the sold bidstream).
+ */
+/**
+ * A custom operator (Sense-Anything) field from the deployed profile's
+ * `metrics_schema`. The connector fetches these from the server
+ * (`GET /v2/earner/cameras/sensing-profile`) so the on-device VLM emits the SAME
+ * operator-declared fields the cloud VLM does — reaching parity with
+ * `buildProfileDrivenJsonSchema` (otherwise an alert keyed on e.g. `queue_length`
+ * never fires on-device because Gemma was never told to emit it).
+ */
+export interface ProfileField {
+    field: string;
+    /** Profile field type (sensingIntentService MetricsSchemaEntrySchema). */
+    type: 'counter' | 'gauge' | 'boolean' | 'enum' | 'category' | 'string' | 'list' | 'distribution' | 'hidden';
+    enum_options?: string[];
+    description?: string;
+    example_outputs?: Array<string | number | boolean>;
+}
+/**
+ * Which DEFAULT field block the on-device schema carries. This is a property of
+ * the DEPLOYED PROFILE, resolved from the profile's own self-describing type
+ * (`sensing_profiles.profile_type`) — see localSensing.fieldSetForProfileType.
+ *
+ *  - `'audience'` — a DOOH screen/audience-measurement profile (the seeded
+ *    builtins: retail_full_v1, convenience_store_v1, transit_hub_v1, …), and the
+ *    default when NO profile is deployed. These exist to describe the AUDIENCE
+ *    in front of a screen for a media buyer, so they carry the full cloud-parity
+ *    audience block (the 12 fields below).
+ *  - `'operator'` — a Sense-Anything profile (`profile_type='custom_intent'`;
+ *    147 of the 157 active profiles as of 2026-08-11). The operator asked a
+ *    specific question about their OWN venue ("is everyone handling food wearing
+ *    gloves?"). The DOOH audience block answers nothing they asked and costs
+ *    1.09-1.53x the per-frame latency depending on delegate (see the file
+ *    header), so an operator profile emits its OWN declared fields plus the
+ *    minimal presence primitives — nothing else.
+ */
+export type LocalSchemaFieldSet = 'audience' | 'operator';
+export interface LocalSensingSchemaOptions {
+    /**
+     * Which default field block to emit. Defaults to `'audience'` — the DOOH
+     * contract, and the correct answer when no profile is deployed.
+     */
+    fieldSet?: LocalSchemaFieldSet;
+    /** Extra operator (Sense-Anything) field keys to also request, e.g. ['queue_length']. */
+    extraBooleanFields?: string[];
+    extraCounterFields?: string[];
+    /**
+     * Typed custom profile fields (preferred) — the active Sense-Anything profile's
+     * `metrics_schema`. Each is appended to the constrained schema with the right
+     * JSON type so Gemma emits it and the operator's route can evaluate it.
+     */
+    extraFields?: ProfileField[];
+}
+/**
+ * Build the JSON Schema the on-device model is asked to fill (rendered as a
+ * readable key list by LiteRtVlmProvider, validated client-side). All fields
+ * non-nullable + required — see the file header for why null is forbidden.
+ *
+ * ONE builder, parameterized by `fieldSet` — an audience/DOOH profile gets the
+ * full 12; a Sense-Anything (operator) profile gets the presence primitives plus
+ * its own declared fields, and never `audience_ethnicity`.
+ */
+export declare function buildLocalSensingSchema(options?: LocalSensingSchemaOptions): Record<string, unknown>;
+/**
+ * The analysis prompt (mirrors audienceVisionService buildProfileDrivenPrompt's
+ * role). When the active Sense-Anything profile declares custom fields, append a
+ * terse instruction for each so Gemma knows what to observe — the on-device
+ * equivalent of the cloud profile-driven prompt. Kept lean (the verbose cloud
+ * phrasing reliably destabilized the on-device decode — see file header).
+ *
+ * `fieldSet` must match the schema's: the audience prompt tells Gemma which
+ * SENTINEL to use for each audience_* field on an empty scene, and on the
+ * operator path those fields do not exist, so repeating that instruction would
+ * spend decode budget describing keys the model must not emit.
+ */
+export declare function buildLocalSensingPrompt(options?: {
+    fieldSet?: LocalSchemaFieldSet;
+    extraFields?: ProfileField[];
+}): string;
+//# sourceMappingURL=localInferenceSchema.d.ts.map

package/dist/localInferenceSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localInferenceSchema.d.ts","sourceRoot":"","sources":["../src/localInferenceSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,cAAc,GAAG,QAAQ,CAAC;IAC5G,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,UAAU,CAAC;AAE1D,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,yFAAyF;IACzF,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B;;;;OAIG;IACH,WAAW,CAAC,EAAE,YAAY,EAAE,CAAC;CAC9B;AAqID;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,yBAA8B,GACtC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgCzB;AAyBD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAAC,WAAW,CAAC,EAAE,YAAY,EAAE,CAAA;CAAO,GAC7E,MAAM,CAeR"}

package/dist/localInferenceSchema.js

@@ -0,0 +1,274 @@
+"use strict";
+/**
+ * localInferenceSchema — the route-addressable JSON Schema + prompt the
+ * on-device VLM (LiteRtVlmProvider) is constrained to. This is the subset of
+ * the cloud `buildProfileDrivenJsonSchema` contract that drives OFV →
+ * Sense-Anything routes → WhatsApp: the DEFAULT audience profile fields
+ * (sensingProfileService CLOUD_EMIT_AUDIENCE_FIELDS) + the scalar scene fields.
+ *
+ * ── WHY PLAIN-COMPLETION + NON-NULLABLE (the on-device runtime reality):
+ * LiteRT-LM (`litert-lm serve` 0.13.1) exposes constrained TOOL-CALLING, but its
+ * ANTLR FC tool-call parser 500s whenever Gemma 4 E2B serializes a string with
+ * the special `<|"|>` quote token instead of a literal `"`. That happens
+ * reproducibly on whole classes of frames — measured 0/5 on an empty-room frame
+ * across EVERY tool-call shape (full schema, no-free-text, temp 0.8, even
+ * `response_format`). Empty scenes dominate real CCTV, so tool-calling is not
+ * viable. The SAME frame returns clean, valid JSON via PLAIN completion (no
+ * tools) — measured 8/8 — because the `<|"|>` token is injected only by the
+ * tool-call/constrained path. So LiteRtVlmProvider renders THIS schema as a
+ * human-readable key list, asks for a bare JSON object, and validates the result
+ * client-side (required keys + enum membership) with a retry. That is where the
+ * structured-output GUARANTEE comes from now — client validation, not the
+ * (broken) server grammar. Keep every field NON-nullable with a sentinel value
+ * ('none'/'unclear'/''/0) for "no people"; the localInferenceSchema.test.ts
+ * guard fails the build if a nullable type/enum is reintroduced.
+ *
+ * ── WHY THE FIELD SET IS A PROPERTY OF THE PROFILE (not a global constant):
+ * an SOP/operator profile asks an operational question about the operator's OWN
+ * venue, and the 12 DOOH audience fields answer none of it — two of them
+ * (`scene_description`, `audience_engagement_narrative`) are free-text paragraphs
+ * the model must DECODE on every frame. MEASURED through this exact code on an
+ * M4 Max, real kitchen frame at production capture params (640x480 JPEG q70),
+ * arms INTERLEAVED so machine load lands on both equally:
+ *
+ *   delegate   12 DOOH + 4 operator      operator set (7 keys)     ratio
+ *   CPU        39.22 s/frame (n=4)       25.68 s/frame (n=4)       1.53x
+ *   GPU        10.66 s/frame (n=5)        9.81 s/frame (n=5)       1.09x
+ *
+ * The GPU win is small because litert-lm pins the VISION encoder to CPU
+ * (openai_handler.py `vision_backend = Backend.CPU()`), so image encode is a
+ * fixed per-frame floor no schema can shrink; on the CPU delegate — every host
+ * with no usable GPU delegate — decode is the bill and the lean set is worth
+ * 1.53x. ACCURACY also moved the right way on that run: against the frame's
+ * ground truth the operator set scored 16/16 and the 16-key set 12/16, the
+ * 16-key arm answering `gloves_worn: true` on a scene where only SOME staff are
+ * gloved while the lean arm answered `false`. (On GPU both scored 15/20 — no
+ * accuracy difference there.) Latency is therefore a secondary reason to split
+ * the sets; the primary ones are asking the operator's question instead of a
+ * media buyer's, and keeping `audience_ethnicity` off a camera pointed at the
+ * customer's own staff. See LocalSchemaFieldSet.
+ *
+ * NOTE: the connector SUPPLIES `source='vlm_edge'` and `captured_at` itself
+ * (provenance + time are not the model's to decide) — they are deliberately NOT
+ * in this schema. The server additionally forces provenance `local_connector`
+ * on the preAnalyzed ingest path (gated OUT of the sold bidstream).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildLocalSensingSchema = buildLocalSensingSchema;
+exports.buildLocalSensingPrompt = buildLocalSensingPrompt;
+/**
+ * The presence primitives EVERY profile reports, whatever its field set. They
+ * are the connector's floor:
+ *   - `people_present` / `person_count` are what the server's preAnalyzed
+ *     handler grades the observation on (earner-misc.analyzeAudienceFrame reads
+ *     `preAnalyzed.people_present === true || Number(preAnalyzed.person_count) >= 1`
+ *     to mark it decisionable `screen_audience`), so dropping them would
+ *     silently downgrade every local observation;
+ *   - `confidence` is the model's own certainty and rides the unified contract.
+ * They are also what keeps `localSensing.isAlertWorthy` able to tell an empty
+ * scene from a busy one on the lean operator path.
+ */
+const PRESENCE_PRIMITIVE_ORDER = ['people_present', 'person_count', 'confidence'];
+/**
+ * The DOOH/audience field set, in the exact order the prompt renders it. Order
+ * is load-bearing only in that it is the wire order Gemma was benchmarked
+ * against — keep it stable unless you re-measure.
+ */
+const AUDIENCE_FIELD_ORDER = [
+    'audience_group_composition',
+    'audience_intent_stage',
+    'audience_activity_macro',
+    'audience_ethnicity',
+    'audience_engagement_narrative',
+    'person_count',
+    'crowd_density',
+    'safety_concern',
+    'scene_description',
+    'ad_receptivity_score',
+    'people_present',
+    'confidence',
+];
+/**
+ * The property spec for every DEFAULT field, declared ONCE. `buildLocalSensingSchema`
+ * composes a field set out of this table rather than forking into two builders.
+ * All non-nullable — see the file header for why null is forbidden.
+ */
+const DEFAULT_FIELD_PROPS = {
+    // DEFAULT audience profile fields (route-addressable enums). Each enum that
+    // had no "no people" member in the cloud contract gains a 'none' sentinel
+    // so the model never has to emit null when the scene is empty.
+    audience_group_composition: {
+        type: 'string',
+        enum: ['solo', 'couple', 'family', 'friend_group', 'work_team', 'mixed', 'none'],
+    },
+    audience_intent_stage: {
+        type: 'string',
+        enum: ['browsing', 'researching', 'comparing', 'ready_to_buy', 'post_purchase', 'none'],
+    },
+    audience_activity_macro: {
+        type: 'string',
+        enum: [
+            'focused_work', 'personal_downtime', 'social_dwell', 'transactional',
+            'decision_making', 'passing_through', 'queueing', 'none',
+        ],
+    },
+    audience_ethnicity: {
+        type: 'string',
+        enum: [
+            'asian', 'black', 'hispanic', 'middle_eastern', 'south_asian',
+            'southeast_asian', 'white', 'mixed', 'other', 'unclear',
+        ],
+    },
+    // One-sentence advertiser-actionable summary; "" when no people present.
+    audience_engagement_narrative: { type: 'string' },
+    // Scene-level fields the CLOUD VLM ALWAYS emits (an empty room is
+    // scene_description="…", crowd_density="empty", person_count=0).
+    person_count: { type: 'integer' },
+    crowd_density: {
+        type: 'string',
+        enum: ['empty', 'sparse', 'moderate', 'crowded', 'very_crowded'],
+    },
+    safety_concern: { type: 'boolean' },
+    scene_description: { type: 'string' },
+    // Receptivity in [0,1]; 0 when no people present (non-nullable — see header).
+    ad_receptivity_score: { type: 'number' },
+    people_present: { type: 'boolean' },
+    confidence: { type: 'number' },
+};
+/**
+ * NEVER asked of an OPERATOR (Sense-Anything) profile, at any cost — not as a
+ * default field and not via a profile's own `metrics_schema`.
+ *
+ * `audience_ethnicity` is a DOOH REACH metric: it exists so a media buyer can
+ * describe the anonymous audience walking past a screen, and it is legal-approved
+ * for exactly that. An SOP/compliance deployment points the SAME camera at the
+ * customer's OWN EMPLOYEES, where an ethnicity estimate has no operator use and
+ * is a straight liability. So the operator path drops it entirely rather than
+ * relying on a profile never happening to declare it.
+ */
+const OPERATOR_FORBIDDEN_FIELDS = new Set(['audience_ethnicity']);
+/** Map a profile field's type → its JSON-schema property (non-nullable). */
+function profileFieldToSchemaProp(f) {
+    switch (f.type) {
+        case 'hidden':
+            return null; // internal — never asked of the model
+        case 'counter':
+            return { type: 'integer' };
+        case 'gauge':
+            return { type: 'number' };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'enum':
+        case 'category':
+            if (Array.isArray(f.enum_options) && f.enum_options.length >= 1) {
+                return { type: 'string', enum: f.enum_options };
+            }
+            return { type: 'string' };
+        case 'list':
+            return { type: 'array', items: { type: 'string' } };
+        case 'distribution':
+            // Cloud declares distribution as a record-of-number (z.record(string,number)),
+            // e.g. age_distribution / gender_split — keep it an object on-device so
+            // route/fan-out parity holds (NOT a scalar string).
+            return { type: 'object', additionalProperties: { type: 'number' } };
+        case 'string':
+        default:
+            return { type: 'string' };
+    }
+}
+/** Fresh copy of a default field spec (callers must never share the enum arrays). */
+function cloneDefaultProp(key) {
+    const spec = DEFAULT_FIELD_PROPS[key];
+    return Array.isArray(spec.enum) ? { ...spec, enum: [...spec.enum] } : { ...spec };
+}
+/**
+ * Build the JSON Schema the on-device model is asked to fill (rendered as a
+ * readable key list by LiteRtVlmProvider, validated client-side). All fields
+ * non-nullable + required — see the file header for why null is forbidden.
+ *
+ * ONE builder, parameterized by `fieldSet` — an audience/DOOH profile gets the
+ * full 12; a Sense-Anything (operator) profile gets the presence primitives plus
+ * its own declared fields, and never `audience_ethnicity`.
+ */
+function buildLocalSensingSchema(options = {}) {
+    const fieldSet = options.fieldSet === 'operator' ? 'operator' : 'audience';
+    const defaults = fieldSet === 'operator' ? PRESENCE_PRIMITIVE_ORDER : AUDIENCE_FIELD_ORDER;
+    const properties = {};
+    // Every field is required — client-side validation rejects (and retries) any
+    // generation that drops a key or emits an out-of-enum value.
+    const required = [];
+    for (const key of defaults) {
+        properties[key] = cloneDefaultProp(key);
+        required.push(key);
+    }
+    // Operator (Sense-Anything) custom fields — also NON-nullable + required so a
+    // queue_length / shelf_empty style alert field survives the on-device grammar.
+    const addField = (key, prop) => {
+        if (!key || key in properties)
+            return; // never override a default field
+        if (fieldSet === 'operator' && OPERATOR_FORBIDDEN_FIELDS.has(key))
+            return;
+        properties[key] = prop;
+        required.push(key);
+    };
+    for (const f of options.extraBooleanFields || [])
+        addField(f, { type: 'boolean' });
+    for (const f of options.extraCounterFields || [])
+        addField(f, { type: 'integer' });
+    // Typed profile fields (the preferred path — from the deployed profile's metrics_schema).
+    for (const f of options.extraFields || []) {
+        if (!f || typeof f.field !== 'string')
+            continue;
+        const prop = profileFieldToSchemaProp(f);
+        if (prop)
+            addField(f.field, prop);
+    }
+    return { type: 'object', properties, required };
+}
+/**
+ * Render the operator's custom-field instructions for the prompt (shared by both
+ * field sets). On the operator path a forbidden field is skipped here too, so the
+ * prompt can never ask for a key the schema refuses to carry.
+ */
+function renderCustomFieldInstructions(extraFields, fieldSet) {
+    const customs = (extraFields || []).filter((f) => f && f.field && f.type !== 'hidden'
+        && !(fieldSet === 'operator' && OPERATOR_FORBIDDEN_FIELDS.has(f.field)));
+    if (customs.length === 0)
+        return null;
+    return customs
+        .map((f) => {
+        const desc = (f.description || '').replace(/\s+/g, ' ').trim().slice(0, 120);
+        return `- ${f.field}: ${desc || f.type}`;
+    })
+        .join(' ');
+}
+/**
+ * The analysis prompt (mirrors audienceVisionService buildProfileDrivenPrompt's
+ * role). When the active Sense-Anything profile declares custom fields, append a
+ * terse instruction for each so Gemma knows what to observe — the on-device
+ * equivalent of the cloud profile-driven prompt. Kept lean (the verbose cloud
+ * phrasing reliably destabilized the on-device decode — see file header).
+ *
+ * `fieldSet` must match the schema's: the audience prompt tells Gemma which
+ * SENTINEL to use for each audience_* field on an empty scene, and on the
+ * operator path those fields do not exist, so repeating that instruction would
+ * spend decode budget describing keys the model must not emit.
+ */
+function buildLocalSensingPrompt(options = {}) {
+    const fieldSet = options.fieldSet === 'operator' ? 'operator' : 'audience';
+    const base = fieldSet === 'operator'
+        ? 'You are watching one frame from a venue camera. Count distinct people ' +
+            '(person_count); people_present=true if any human is visible; confidence is your ' +
+            '0-1 certainty. Report only what is VISIBLE in this frame. Anonymous aggregate ' +
+            'measurement only — face DETECTION not recognition.'
+        : 'You are a behavioral intelligence analyst observing one frame from a screen at a retail ' +
+            'venue. Count distinct people (person_count); people_present=true if any human is visible. ' +
+            'When NO people are present use "none"/"unclear" for audience_* enums, "" for ' +
+            'audience_engagement_narrative, 0 for ad_receptivity_score. Anonymous aggregate measurement ' +
+            'only — face DETECTION not recognition.';
+    const lines = renderCustomFieldInstructions(options.extraFields, fieldSet);
+    if (!lines)
+        return base;
+    return `${base} Also report these operator-requested fields from the image: ${lines}`;
+}
+//# sourceMappingURL=localInferenceSchema.js.map

package/dist/localInferenceSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localInferenceSchema.js","sourceRoot":"","sources":["../src/localInferenceSchema.ts"],"names":[],"mappings":"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"}

package/dist/localSenseE2eHarness.d.ts

@@ -0,0 +1,101 @@
+/** A schema-conforming, route-addressable default-profile result with a person. */
+export interface StubGemmaResultOptions {
+    personCount?: number;
+    peoplePresent?: boolean;
+    /** Extra/override keys merged onto the base result (e.g. operator custom fields). */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Build a DEFAULT-schema-conforming structured result with a person present.
+ * Matches buildLocalSensingSchema()'s required keys + enum members exactly, so
+ * LiteRtVlmProvider's client-side validation passes on the first attempt. This
+ * is the object the stub VLM "infers" — it must look like real Gemma output.
+ */
+export declare function buildStubGemmaResult(options?: StubGemmaResultOptions): Record<string, unknown>;
+/**
+ * Wrap a structured result in the OpenAI chat-completions envelope litert-lm
+ * serve returns (choices[0].message.content is the minified JSON string).
+ */
+export declare function buildStubChatCompletion(result: Record<string, unknown>): Record<string, unknown>;
+export interface StubVlmServer {
+    /** The base URL the connector should point at (http://127.0.0.1:<port>). */
+    baseUrl: string;
+    port: number;
+    /** Number of /v1/chat/completions calls served (for assertions). */
+    getChatCalls(): number;
+    /** The `model` id each /v1/chat/completions call was posted under, in order. */
+    getChatModels(): string[];
+    close(): Promise<void>;
+}
+export interface CreateStubVlmServerOptions {
+    /** Result the stub "infers" for every frame. Default: a 2-person scene. */
+    result?: Record<string, unknown>;
+    /** Bind host. Default 127.0.0.1 (loopback only — never expose a fake model). */
+    host?: string;
+    /** Port. Default 0 (ephemeral). Pass 9379 to mirror the real serve port. */
+    port?: number;
+    /**
+     * Model ids `GET /v1/models` advertises. Default: the single CPU id. Pass both
+     * ids (`['gemma-4-E2B-it.litertlm', 'gemma-4-E2B-it.litertlm,gpu']`) to mirror
+     * a real litert-lm 0.13.1 serve, which advertises its GPU delegate as a
+     * SEPARATE model id — that is what LiteRtVlmProvider resolves against.
+     */
+    modelIds?: string[];
+}
+/**
+ * Start a fake `litert-lm serve` (OpenAI-compatible) on loopback. Answers:
+ *   GET  /v1/models             → 200 (health probe)
+ *   POST /v1/chat/completions   → 200 {choices:[{message:{content:<json>}}]}
+ * Any other path → 404. Resolves once listening (baseUrl/port populated).
+ */
+export declare function createStubVlmServer(options?: CreateStubVlmServerOptions): Promise<StubVlmServer>;
+/** One captured preAnalyzed ingest POST. */
+export interface CapturedIngest {
+    preAnalyzed: Record<string, unknown> | null;
+    deviceToken: string | null;
+    hasImage: boolean;
+    capturedAt: number | null;
+    raw: Record<string, unknown> | null;
+}
+export interface IngestCaptureServer {
+    /** The apiBaseUrl the connector should use (http://127.0.0.1:<port>). */
+    baseUrl: string;
+    port: number;
+    /** Every captured /v2/earner/audience-analyze POST, in order. */
+    getCaptured(): CapturedIngest[];
+    close(): Promise<void>;
+}
+export interface CreateIngestCaptureServerOptions {
+    host?: string;
+    port?: number;
+    /**
+     * Profile returned by GET /v2/earner/cameras/sensing-profile. Default: a body
+     * with no custom fields so the connector keeps the DEFAULT schema. (Shape
+     * mirrors SensingProfileClient's expected response.)
+     */
+    profileBody?: Record<string, unknown>;
+}
+/**
+ * Start a fake Trillboards API on loopback that the connector's
+ * AudienceAnalyzeClient + SensingProfileClient talk to. Captures preAnalyzed
+ * ingests; serves an (empty by default) sensing profile.
+ *   POST /v2/earner/audience-analyze        → 200, captures preAnalyzed
+ *   GET  /v2/earner/cameras/sensing-profile → 200 {profile}
+ * Any other path → 404.
+ */
+export declare function createIngestCaptureServer(options?: CreateIngestCaptureServerOptions): Promise<IngestCaptureServer>;
+export interface PersonAssertion {
+    ok: boolean;
+    reason: string;
+    personCount: number | null;
+    peoplePresent: boolean | null;
+}
+/**
+ * E2E acceptance over the captured ingests: at least one preAnalyzed result
+ * indicates a PERSON — person_count>=1 OR people_present===true. Returns a
+ * structured verdict (ok + a human-readable reason) the runner turns into an
+ * exit code. The provenance the connector stamps (source='vlm_edge') is also
+ * asserted so a result that bypassed the connector can't satisfy the gate.
+ */
+export declare function assertPreAnalyzedHasPerson(captured: CapturedIngest[]): PersonAssertion;
+//# sourceMappingURL=localSenseE2eHarness.d.ts.map

package/dist/localSenseE2eHarness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localSenseE2eHarness.d.ts","sourceRoot":"","sources":["../src/localSenseE2eHarness.ts"],"names":[],"mappings":"AA8BA,mFAAmF;AACnF,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBzB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAahG;AAED,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,YAAY,IAAI,MAAM,CAAC;IACvB,gFAAgF;IAChF,aAAa,IAAI,MAAM,EAAE,CAAC;IAC1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,0BAA0B;IACzC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,aAAa,CAAC,CAmDxB;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,WAAW,IAAI,cAAc,EAAE,CAAC;IAChC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,gCAAgC;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,gCAAqC,GAC7C,OAAO,CAAC,mBAAmB,CAAC,CA6D9B;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,eAAe,CAmCtF"}