repzo 1.0.291 → 1.0.293

package/src/oas/ai-object-detection-detection-settings.yaml

@@ -0,0 +1,410 @@
+openapi: 3.0.3
+info:
+  title: Repzo API - AI Object Detection Detection Settings
+  version: 1.0.0
+  description: |
+    **Unified detection settings** — the per-namespace configuration of the
+    AR shelf-scan CAPTURE pipeline: how the mobile app captures frames
+    (`capture`: mode, rate, resolution, torch, exposure lock), the two-tier
+    per-frame quality limits (`frame`: sharpness, yaw/pitch/roll deltas,
+    depth variation, distance, tracking score — each with a `warn` bound that
+    only shows guidance and an `error` bound that excludes the frame from
+    election while it still counts toward coverage), the frame-election
+    formula (`election`: coverage target, sliver fraction, redundancy exponent
+    and quality weights) and the session acceptance gates (`session`:
+    coverage target, jump tolerance, elected-frame budget, verdict score
+    bands). It is the single source of truth for knobs that used to live
+    scattered across the mobile validator, the election engine and the
+    backend session gates.
+
+    **Who calls it.** The MOBILE app pulls `GET` on session start with a rep
+    token (reads are open to any authenticated scope); the dashboard (admin)
+    writes. The auto-seeded permission grid governs per-scope access.
+
+    **Multi-tenancy & lifecycle.** One logical document per
+    `company_namespace` (keyed from the caller's token — never sent in the
+    body; unique index). The stored document holds only PARTIAL OVERRIDES
+    over the engine defaults (`DEFAULT_DETECTION_CONFIG`); every read returns
+    the MERGED result (`config`) alongside the raw `overrides`, so partial
+    overrides stay partial and new engine defaults reach every namespace
+    automatically. `GET` never 404s — an untouched namespace answers
+    `is_default: true` with the pure defaults. `POST` upserts (`PUT` / `PATCH`
+    behave identically and ignore the path id) and REPLACES the stored
+    overrides object wholesale (it is not merged into previously saved
+    overrides — send the complete set you want kept). `DELETE` resets to the
+    factory defaults by dropping the document (id ignored) and answers only
+    `{ is_default: true, config }`. No query parameters are honoured;
+    responses are single objects, never paginated.
+
+    **Relationships.** Frames submitted by the app stamp
+    `frame_meta.detection_settings_polled_at` on their
+    `ai-object-detection-task` so an analysis can tell which settings a
+    capture ran under; the backend election
+    (`ai-object-detection-session-election`) enforces the same `frame` /
+    `election` / `session` values server-side.
+
+    **Not to be confused with** `ai-object-detection-settings`, which stores
+    the dashboard-only ANALYZE defaults (scene-math knobs) and never reaches
+    the device.
+servers:
+  - url: https://sv.api.repzo.me
+security:
+  - ApiKeyAuth: []
+  - JwtAuth: []
+paths:
+  /ai-object-detection-detection-settings:
+    get:
+      summary: Read the namespace's merged detection config
+      description: |
+        Returns the engine defaults deep-merged with the namespace's saved
+        overrides, plus the raw overrides. Never 404s. Query parameters are
+        ignored. This is what the mobile app pulls on session start.
+      operationId: findAiObjectDetectionDetectionSettings
+      responses:
+        "200":
+          description: The merged detection config (or the pure defaults when nothing is saved).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DetectionSettings"
+    post:
+      summary: Save the namespace's detection overrides
+      description: |
+        Upserts the single document for the caller's namespace, REPLACING the
+        stored overrides object with `config`, and returns the fresh merged
+        read. `config` must be an object (else `400`); any subset of the
+        `DetectionConfig` tree is accepted and deep-merged over the defaults
+        on read.
+      operationId: createAiObjectDetectionDetectionSettings
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DetectionSettingsCreateBody"
+      responses:
+        "201":
+          description: The merged config, re-read after the upsert.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DetectionSettings"
+        "400":
+          description: "`config` is missing or not an object."
+  /ai-object-detection-detection-settings/{id}:
+    get:
+      summary: Read the merged detection config (id ignored)
+      description: One logical document per namespace — this mirrors the collection read.
+      operationId: getAiObjectDetectionDetectionSettings
+      parameters:
+        - in: path
+          name: id
+          required: true
+          description: Ignored — there is a single document per namespace.
+          schema: { type: string }
+      responses:
+        "200":
+          description: Same shape as the collection read.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DetectionSettings"
+    put:
+      summary: Save the detection overrides (id ignored)
+      description: Identical to POST — upserts the namespace's single document.
+      operationId: updateAiObjectDetectionDetectionSettings
+      parameters:
+        - in: path
+          name: id
+          required: true
+          description: Ignored — the namespace keys the document.
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DetectionSettingsWrite"
+      responses:
+        "200":
+          description: The merged config, re-read after the upsert.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DetectionSettings"
+        "400":
+          description: "`config` is missing or not an object."
+    patch:
+      summary: Save the detection overrides (identical to PUT)
+      operationId: patchAiObjectDetectionDetectionSettings
+      parameters:
+        - in: path
+          name: id
+          required: true
+          description: Ignored — the namespace keys the document.
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DetectionSettingsWrite"
+      responses:
+        "200":
+          description: The merged config, re-read after the upsert.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DetectionSettings"
+        "400":
+          description: "`config` is missing or not an object."
+    delete:
+      summary: Reset to the factory defaults
+      description: |
+        Drops the namespace's overrides document. The id is ignored. Note the
+        reduced response shape — only `is_default` and the default `config`.
+      operationId: removeAiObjectDetectionDetectionSettings
+      parameters:
+        - in: path
+          name: id
+          required: true
+          description: Ignored — any value works.
+          schema: { type: string }
+          example: defaults
+      responses:
+        "200":
+          description: Reset acknowledgement with the pure engine defaults.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DetectionSettingsResetResult"
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: api-key
+      description: |
+        Server-issued API key. Also accepted via the `x-api-key` header or the
+        `?apiKey=` query parameter as fallbacks.
+    JwtAuth:
+      type: apiKey
+      in: header
+      name: Authorization
+      description: |
+        Raw JWT in the `Authorization` header — **no `Bearer ` prefix**.
+        Obtained from `POST /authenticate` (admin / rep / client login).
+  schemas:
+    WarnError:
+      type: object
+      description: |
+        Two-tier frame limit. `warn` = guidance shown on the device, frame
+        still usable; `error` = frame excluded from election (it still counts
+        toward the coverage total). `warn` is always the softer bound.
+      required: [warn, error]
+      properties:
+        warn: { type: number }
+        error: { type: number }
+    CaptureConfig:
+      type: object
+      properties:
+        mode:
+          type: string
+          enum: [stack_elect, continuous, burst]
+          default: stack_elect
+        rate_hz:
+          type: number
+          default: 4
+          description: Capture rate, frames per second.
+        resolution:
+          type: string
+          enum: [medium, high, max]
+          default: max
+        stack_timeout_s:
+          type: number
+          default: 30
+          description: Seconds before a stack-elect capture times out.
+        sweep_guide:
+          type: boolean
+          default: true
+          description: Show the sweep guide overlay.
+        torch:
+          type: boolean
+          default: true
+        exposure_lock:
+          type: boolean
+          default: true
+    FrameConfig:
+      type: object
+      description: Per-frame quality limits, each a `WarnError` pair.
+      properties:
+        min_sharpness:
+          allOf:
+            - $ref: "#/components/schemas/WarnError"
+          description: "Variance-of-Laplacian sharpness floor. `warn` = live-guidance floor, `error` = election hard floor (the blur limit). Default `{ warn: 200, error: 50 }`."
+        max_yaw_delta_deg:
+          allOf:
+            - $ref: "#/components/schemas/WarnError"
+          description: "Degrees. Default `{ warn: 18, error: 30 }`."
+        max_pitch_delta_deg:
+          allOf:
+            - $ref: "#/components/schemas/WarnError"
+          description: "Degrees. Default `{ warn: 15, error: 28 }`."
+        max_roll_delta_deg:
+          allOf:
+            - $ref: "#/components/schemas/WarnError"
+          description: "Degrees. Default `{ warn: 12, error: 25 }`."
+        max_depth_variation_m:
+          allOf:
+            - $ref: "#/components/schemas/WarnError"
+          description: "Metres. Default `{ warn: 0.8, error: 1.5 }`."
+        min_distance_m:
+          allOf:
+            - $ref: "#/components/schemas/WarnError"
+          description: "Metres — `error` is the NEARER bound (worse). Default `{ warn: 0.5, error: 0.3 }`."
+        max_distance_m:
+          allOf:
+            - $ref: "#/components/schemas/WarnError"
+          description: "Metres — `error` is the FARTHER bound (worse). Default `{ warn: 2.0, error: 3.0 }`."
+        min_tracking_score:
+          allOf:
+            - $ref: "#/components/schemas/WarnError"
+          description: "0..100. Default `{ warn: 60, error: 35 }`."
+    ElectionConfig:
+      type: object
+      properties:
+        cover_target:
+          type: number
+          default: 0.985
+          description: Stop electing at this union coverage (0..1).
+        sliver_frac:
+          type: number
+          default: 0.02
+          description: Ignore gains under this fraction of a median footprint.
+        gain_exp:
+          type: number
+          default: 1.5
+          description: "Redundancy penalty exponent (score = quality · gain^exp)."
+        w_sharp:
+          type: number
+          default: 0.4
+          description: Quality geometric-mean weight — sharpness.
+        w_depth:
+          type: number
+          default: 0.3
+          description: Quality geometric-mean weight — depth.
+        w_track:
+          type: number
+          default: 0.2
+          description: Quality geometric-mean weight — tracking.
+        w_lux:
+          type: number
+          default: 0.1
+          description: Quality geometric-mean weight — lux.
+    SessionScoreBands:
+      type: object
+      description: "Average-quality verdict bands; below `acceptable` = rejected."
+      properties:
+        excellent: { type: number, default: 0.8 }
+        good: { type: number, default: 0.65 }
+        acceptable: { type: number, default: 0.45 }
+    SessionConfig:
+      type: object
+      properties:
+        coverage_target_m2:
+          type: number
+          default: 0.5
+          description: Reject when the device-reported covered area (m²) is below this.
+        allow_jump:
+          type: boolean
+          default: false
+          description: When false, a spatial jump (after removing error frames) rejects the session.
+        elected_allowance:
+          type: number
+          default: 1.6
+          description: "Elected-count budget: ceil(total_area / avg_frame_area × allowance). More elected frames than that rejects the session."
+        score:
+          $ref: "#/components/schemas/SessionScoreBands"
+    DetectionConfig:
+      type: object
+      description: The full merged detection config (defaults deep-merged with the namespace overrides).
+      properties:
+        capture:
+          $ref: "#/components/schemas/CaptureConfig"
+        frame:
+          $ref: "#/components/schemas/FrameConfig"
+        election:
+          $ref: "#/components/schemas/ElectionConfig"
+        session:
+          $ref: "#/components/schemas/SessionConfig"
+    DetectionConfigOverrides:
+      type: object
+      description: |
+        Deep-partial subset of `DetectionConfig`. Objects merge recursively
+        over the defaults, scalars replace (a `WarnError` may carry only
+        `warn` or only `error`). Unknown keys are kept by the merge so the
+        config can grow.
+      properties:
+        capture:
+          $ref: "#/components/schemas/CaptureConfig"
+        frame:
+          $ref: "#/components/schemas/FrameConfig"
+        election:
+          $ref: "#/components/schemas/ElectionConfig"
+        session:
+          $ref: "#/components/schemas/SessionConfig"
+      example:
+        capture: { torch: false }
+        frame: { min_sharpness: { error: 80 } }
+        session: { coverage_target_m2: 0.8 }
+    DetectionSettings:
+      type: object
+      description: Response of find / get / create / update / patch.
+      properties:
+        _id:
+          type: string
+          nullable: true
+          description: "`null` while the namespace has never saved overrides."
+        is_default:
+          type: boolean
+          description: "true = no overrides saved; `config` is the pure engine default."
+        config:
+          $ref: "#/components/schemas/DetectionConfig"
+        overrides:
+          allOf:
+            - $ref: "#/components/schemas/DetectionConfigOverrides"
+          description: "The raw saved overrides (`{}` when `is_default`)."
+        updatedAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: "When the overrides were last saved; `null` when `is_default`."
+    DetectionSettingsWrite:
+      type: object
+      description: PUT / PATCH body — the same single document is upserted.
+      required: [config]
+      properties:
+        config:
+          $ref: "#/components/schemas/DetectionConfigOverrides"
+    DetectionSettingsCreateBody:
+      description: |
+        POST body. The tenant key is taken from the caller's token; the
+        optional `company_namespace` exists for SDK-call uniformity and is not
+        read by this endpoint.
+      allOf:
+        - $ref: "#/components/schemas/DetectionSettingsWrite"
+        - type: object
+          properties:
+            company_namespace:
+              type: array
+              items: { type: string }
+              description: Optional tenant namespace override for SDK callers. Not read by this endpoint — the document is keyed from the caller's token namespace.
+    DetectionSettingsResetResult:
+      type: object
+      description: "DELETE response — note there is no `_id` / `overrides` / `updatedAt`."
+      properties:
+        is_default:
+          type: boolean
+          enum: [true]
+        config:
+          $ref: "#/components/schemas/DetectionConfig"