repzo 1.0.292 → 1.0.293

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

@@ -0,0 +1,249 @@
+openapi: 3.0.3
+info:
+  title: Repzo API - AI Object Detection Settings
+  version: 1.0.0
+  description: |
+    **Analyze defaults** — the per-namespace bag of analysis knobs that seeds
+    the dashboard's *Analyze session* dialog, so a team fixes its preferred
+    confidence / clustering / reclassify / size-gate values once instead of
+    re-tuning them on every run. The same document is the DRIFT BASELINE on
+    the analysis-result screen: when a session carries no detection category
+    (or none of the category's `model_settings` matches the analysis's model
+    version), the screen compares the analysis's stored config against these
+    defaults to show what would change on a re-run.
+
+    **One logical document per `company_namespace`** (keyed from the caller's
+    token — never sent in the body). `GET` NEVER 404s: an untouched namespace
+    answers `is_default: true` with an empty `analyze_config`, so clients can
+    always seed a form from the response. `POST` upserts (`PUT`/`PATCH` behave
+    identically) and `DELETE` restores factory defaults by dropping the
+    document — the path id is ignored, since there is only ever one document
+    (the dashboard calls `DELETE /ai-object-detection-settings/defaults`).
+
+    **Writes.** `analyze_config` is a free-form bag of analysis knobs
+    (`conf_threshold`, `cluster_eps_m`, `plane_merge`, `reclassify_labels`,
+    `size_gate`, `inference_concurrency`, …) — deliberately not filtered
+    against a fixed key list, exactly like the analyze endpoint's own
+    `config`, which merges over the engine defaults and picks the keys it
+    knows. That way the saved defaults round-trip whatever the Analyze dialog
+    can set. VALUES are strict: every knob must be a finite number or a
+    boolean (`null` is skipped, meaning "fall back"), anything else is
+    rejected with `400`, and the bag is capped at 200 keys. The known knob
+    names are the scene engine's `SceneMathConfig` (documented on
+    `ai-object-detection-inference`).
+
+    **Not to be confused with** `ai-object-detection-detection-settings`,
+    which holds the CAPTURE / frame-quality / election / session-gate knobs
+    the MOBILE app pulls on session start. This service is dashboard-only and
+    never reaches the device. Admin-facing. No query parameters are honoured
+    on any method; responses are single objects, never paginated.
+servers:
+  - url: https://sv.api.repzo.me
+security:
+  - ApiKeyAuth: []
+  - JwtAuth: []
+paths:
+  /ai-object-detection-settings:
+    get:
+      summary: Read the namespace's saved analyze defaults
+      description: |
+        Never 404s — an untouched namespace answers `is_default: true` with an
+        empty `analyze_config`. Query parameters are ignored.
+      operationId: findAiObjectDetectionSettings
+      responses:
+        "200":
+          description: The namespace's analyze defaults (or the empty default state).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AnalyzeDefaults"
+    post:
+      summary: Save the namespace's analyze defaults
+      description: |
+        Upserts the single document for the caller's namespace and returns the
+        fresh read. Keys are NOT filtered against a fixed list (the bag must
+        round-trip whatever the Analyze dialog can set); every VALUE must be a
+        finite number or a boolean — `null` knobs are skipped, anything else is
+        rejected with `400`. The bag is capped at 200 keys.
+      operationId: createAiObjectDetectionSettings
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AnalyzeDefaultsCreateBody"
+      responses:
+        "201":
+          description: The saved defaults, re-read after the upsert.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AnalyzeDefaults"
+        "400":
+          description: "`analyze_config` is missing/not an object, a knob holds a non-numeric, non-boolean value, or the bag exceeds 200 keys."
+  /ai-object-detection-settings/{id}:
+    get:
+      summary: Read the analyze defaults (id ignored)
+      description: One logical document per namespace — this mirrors the collection read.
+      operationId: getAiObjectDetectionSettings
+      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/AnalyzeDefaults"
+    put:
+      summary: Save the analyze defaults (id ignored)
+      description: Identical to POST — upserts the namespace's single document.
+      operationId: updateAiObjectDetectionSettings
+      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/AnalyzeDefaultsWrite"
+      responses:
+        "200":
+          description: The saved defaults, re-read after the upsert.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AnalyzeDefaults"
+        "400":
+          description: "`analyze_config` is missing/not an object, or a knob holds a non-numeric, non-boolean value."
+    patch:
+      summary: Save the analyze defaults (identical to PUT)
+      operationId: patchAiObjectDetectionSettings
+      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/AnalyzeDefaultsWrite"
+      responses:
+        "200":
+          description: The saved defaults, re-read after the upsert.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AnalyzeDefaults"
+        "400":
+          description: "`analyze_config` is missing/not an object, or a knob holds a non-numeric, non-boolean value."
+    delete:
+      summary: Restore factory defaults
+      description: |
+        Drops the namespace's overrides document. The id is ignored — the
+        dashboard calls `DELETE /ai-object-detection-settings/defaults`.
+      operationId: removeAiObjectDetectionSettings
+      parameters:
+        - in: path
+          name: id
+          required: true
+          description: "Ignored — any value works (the dashboard sends `defaults`)."
+          schema: { type: string }
+          example: defaults
+      responses:
+        "200":
+          description: "The empty default state (`_id: null`, `is_default: true`, `analyze_config: {}`, `updatedAt: null`)."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AnalyzeDefaults"
+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:
+    AnalyzeConfig:
+      type: object
+      description: |
+        Partial bag of analysis knobs. Values must be numbers or booleans;
+        absent knobs fall back to the engine defaults at analyze time, and
+        keys the analyze pipeline does not know are simply ignored there.
+        Known keys are the scene engine's `SceneMathConfig` (depth sampling
+        `min_depth_m` / `max_depth_m` / `conf_threshold` / `front_percentile`
+        / `shelf_tolerance_m`, clustering `cluster_eps_m` / `plane_merge` /
+        `plane_merge_iou` / `plane_merge_depth_delta_m`, the `reclassify_*`
+        and `size_gate*` families, the `shelf_*` composition knobs, point
+        cloud `build_point_cloud` / `pc_stride` / `pc_voxel_size_m`, RANSAC
+        `ransac_*`) plus `inference_concurrency`.
+      additionalProperties:
+        oneOf:
+          - type: number
+          - type: boolean
+      example:
+        conf_threshold: 0.35
+        cluster_eps_m: 0.08
+        plane_merge: true
+        reclassify_labels: true
+        size_gate: true
+        inference_concurrency: 4
+    AnalyzeDefaults:
+      type: object
+      description: Response of every method — the projected defaults document.
+      properties:
+        _id:
+          type: string
+          nullable: true
+          description: "`null` while the namespace has never saved defaults."
+        is_default:
+          type: boolean
+          description: true = nothing saved; the client falls back to the engine defaults.
+        analyze_config:
+          $ref: "#/components/schemas/AnalyzeConfig"
+        updatedAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: "When the defaults were last saved; `null` when `is_default`."
+    AnalyzeDefaultsWrite:
+      type: object
+      description: PUT / PATCH body — the same single document is upserted.
+      required: [analyze_config]
+      properties:
+        analyze_config:
+          $ref: "#/components/schemas/AnalyzeConfig"
+    AnalyzeDefaultsCreateBody:
+      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/AnalyzeDefaultsWrite"
+        - 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.