repzo 1.0.292 → 1.0.293

package/src/oas/ai-object-detection-session-election.yaml

@@ -0,0 +1,193 @@
+openapi: 3.0.3
+info:
+  title: Repzo API - AI Object Detection Session Election
+  version: 1.0.0
+  description: |
+    Materializes an election-playground result as a NEW object-detection
+    session. The dashboard's election playground simulates stack-then-elect
+    frame election over a session captured in the AR app's election-debug mode
+    (every stacked frame uploaded); this endpoint saves the elected subset as
+    a real session so it can go through the normal analysis pipeline.
+
+    **What it does.** The source session document is cloned — `device`,
+    `capture_settings`, `coverage_m2`, `client` and `status` copied,
+    `session_id` suffixed `-E<n>` (n = 1 + prior elections of that source)
+    and `source_session` set for provenance. The elected tasks are first
+    SCREENED against the namespace detection-settings ERROR tier in capture
+    order (`sharpness`, `tracking`, `too_near`/`too_far`, `yaw_delta`/
+    `pitch_delta`/`roll_delta` vs the previous kept frame); excluded frames
+    stay on the source session (they keep counting toward coverage) and are
+    listed under `election_excluded`. The surviving tasks are duplicated onto
+    the new session referencing the SAME media blobs (no image/depth copies)
+    with annotation state reset, so inference re-runs from scratch.
+
+    **Session gates & verdict.** `rejection_reasons` collects the session
+    gates that fired — `coverage_below_target` (device `coverage_m2` below the
+    configured target), `jump_detected` (adjacent kept frames farther apart
+    than a frame footprint, unless `allow_jump`), `too_many_elected` (kept
+    frames exceed coverage / avg footprint × allowance). `session_score` is
+    the average frame quality over ALL frames of the source session (0..1)
+    and `session_verdict` is `rejected` when any gate fired, else banded from
+    the score (`excellent` / `good` / `acceptable`). A `rejected` verdict
+    also suppresses the category auto-analysis on upload-complete.
+
+    **Who calls it & lifecycle.** Admin / API-key callers from the dashboard.
+    Create-only — `find`/`get`/`update`/`patch`/`remove` return 405. The new
+    row lives in the regular `ai-object-detection-session` collection
+    (namespace-scoped via the caller's token; `company_namespace` is
+    server-injected) and is read/managed through that service.
+servers:
+  - url: https://sv.api.repzo.me
+security:
+  - ApiKeyAuth: []
+  - JwtAuth: []
+paths:
+  /ai-object-detection-session-election:
+    post:
+      summary: Save an elected frame subset as a new session
+      description: >-
+        Clones the source session and the chosen tasks (after error-tier
+        screening) into a new session with the same media references and a
+        fresh annotation state. Returns the new session document.
+      operationId: createAiObjectDetectionSessionElection
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ElectionRequest"
+      responses:
+        "201":
+          description: The newly created session document (a regular `ai-object-detection-session` row).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ElectedSession"
+        "400":
+          description: >-
+            Missing `session`, empty `task_ids`, more than 500 task ids, task
+            ids that do not belong to the source session, or every elected
+            frame fails the error-tier limits (nothing to materialize).
+        "404":
+          description: Source session not found in the caller's namespace.
+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:
+    ElectionRequest:
+      type: object
+      required: [session, task_ids]
+      properties:
+        session:
+          type: string
+          description: Source `ai-object-detection-session` `_id`.
+        task_ids:
+          type: array
+          minItems: 1
+          maxItems: 500
+          items: { type: string }
+          description: >-
+            Elected task `_id`s — must all belong to the source session.
+        config_snapshot:
+          type: object
+          additionalProperties: true
+          description: >-
+            Optional playground formula parameters used for this election.
+            Accepted for provenance only — not persisted on the session.
+        company_namespace:
+          type: array
+          items: { type: string }
+          description: Optional tenant namespace override for SDK callers.
+    UserRef:
+      type: object
+      description: Compact actor reference (rep or admin).
+      properties:
+        _id: { type: string }
+        type: { type: string, enum: [admin, rep] }
+        name: { type: string }
+        rep: { type: string }
+        admin: { type: string }
+    ElectedSession:
+      type: object
+      description: >-
+        The materialized session — a regular `ai-object-detection-session`
+        document (see that service's `SessionSchema` for every field); the
+        election-specific fields are always present here.
+      properties:
+        _id: { type: string }
+        session_id:
+          type: string
+          description: "Source id with an election suffix, e.g. `AB12CD34-E1`."
+        source_session:
+          type: string
+          description: The source session `_id` (provenance).
+        status:
+          type: string
+          enum:
+            [open, uploaded, infer_in_progress, inferred, rearbitrating, failed]
+          description: Copied from the source session.
+        device: { type: object, additionalProperties: true }
+        capture_settings: { type: object, additionalProperties: true }
+        coverage_m2:
+          type: number
+          description: Copied from the source (total coverage INCLUDES the excluded frames).
+        client: { type: string }
+        session_score:
+          type: number
+          description: Average frame quality over ALL frames of the source session, 0..1.
+        session_verdict:
+          type: string
+          enum: [excellent, good, acceptable, rejected]
+        rejection_reasons:
+          type: array
+          items:
+            type: string
+            enum: [coverage_below_target, jump_detected, too_many_elected]
+        election_excluded:
+          type: array
+          description: Error-tier frames excluded from the clone.
+          items:
+            type: object
+            properties:
+              task: { type: string }
+              violations:
+                type: array
+                items:
+                  type: string
+                  enum:
+                    [
+                      sharpness,
+                      tracking,
+                      too_near,
+                      too_far,
+                      yaw_delta,
+                      pitch_delta,
+                      roll_delta,
+                    ]
+        frames_total: { type: number }
+        frames_accepted: { type: number }
+        tasks_count: { type: number }
+        detections_count: { type: number }
+        objects_count: { type: number }
+        creator:
+          $ref: "#/components/schemas/UserRef"
+        disabled: { type: boolean }
+        company_namespace:
+          type: array
+          items: { type: string }
+          description: Tenant key. Server-injected — never accept from clients.
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }

package/src/oas/ai-object-detection-session-insight.yaml

@@ -0,0 +1,418 @@
+openapi: 3.0.3
+info:
+  title: Repzo API - AI Object Detection Session Insight
+  version: 1.0.0
+  description: |
+    **Session insight** — retail shelf intelligence computed ON READ from a
+    shelf-scan session's latest successful analysis (or an explicit analysis
+    id). Nothing is persisted or cached: edits to the analysis, the labels or
+    their product links reflect on the next request.
+
+    **What it derives.** Facings are the FRONT-ROW shelved objects of the
+    analysis's stored board-first shelf composition (composed on the fly for
+    legacy analyses that predate it), laid out along the scene's shelf axis û.
+    From them:
+    - `shelves[]` — facing counts, Σ linear cm, occupied span, utilization.
+    - `share_of_shelf` — rollup rows per vocabulary kind: `by_label` always;
+      `by_label_group` / `by_brand` / `by_category` / `by_subcategory` /
+      `by_product` appear only when the scene's labels LINK to entities of
+      that kind (links live on `ai-object-detection-label`).
+    - `blocking` — "merchandised together?": maximal same-shelf runs of a
+      group's facings, merged vertically across adjacent shelves when their
+      u-intervals overlap; interrupting labels are ranked.
+    - `objects` (`include_objects=true`) — planogram-style facing dump per
+      shelf, positions re-based to each shelf's left edge (cm).
+    - `adjacency` (`include_adjacency=true`) — who stands next to whom.
+
+    **Questions (POST).** Up to 20 free-text or structured questions answered
+    in order. Intent = share_of_shelf / blocking / adjacency; the target
+    resolves by id → exact name → substring → fuzzy tokens against the
+    scene's vocabulary; unresolved answers carry `reason` + `suggestions`.
+    Each answer includes a human-readable `narrative`.
+
+    **Config.** `default_facing_width_m` substitutes facings with no measured
+    size; `block_min_overlap_m` / `block_overlap_frac` tune the vertical
+    block merge. (`min_shelf_gap_m` / `shelf_gap_height_factor` are echoed
+    for contract compatibility — shelf levels now come from the analysis's
+    stored composition, tuned via the analysis `shelf_*` settings.)
+
+    Positions are metres (AR world frame); product sizes centimetres.
+    Namespace-scoped via the caller's token; read-only (PUT/PATCH/DELETE are
+    rejected). Admins read any session; a REP token reads only insights of
+    sessions THAT REP scanned (the mobile Retail Insights screen's read).
+servers:
+  - url: https://sv.api.repzo.me
+security:
+  - ApiKeyAuth: []
+  - JwtAuth: []
+paths:
+  /ai-object-detection-session-insight:
+    get:
+      summary: Compute the insight for a session / analysis
+      operationId: findAiObjectDetectionSessionInsight
+      parameters:
+        - in: query
+          name: session
+          description: "Session `_id` — reads its LATEST successful analysis. One of `session` / `analysis` is required."
+          schema: { type: string }
+        - in: query
+          name: analysis
+          description: "Explicit analysis `_id` (must have `status: success`)."
+          schema: { type: string }
+        - in: query
+          name: include_objects
+          description: "Add the planogram-style facing dump per shelf (only the literal `true` is honoured)."
+          schema: { type: boolean }
+        - in: query
+          name: include_adjacency
+          description: "Add label-level neighbour counts (only the literal `true` is honoured)."
+          schema: { type: boolean }
+      responses:
+        "200":
+          description: The freshly computed insight payload (a single object — not paginated).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SessionInsight"
+        "400":
+          description: Neither session nor analysis given, or the analysis is not successful.
+        "403":
+          description: A REP token asked for a session that rep did not scan.
+        "404":
+          description: No matching analysis (or the session has no successful analysis yet).
+    post:
+      summary: Compute the insight and answer questions
+      operationId: createAiObjectDetectionSessionInsight
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                session:
+                  type: string
+                  description: "Session `_id` — one of `session` / `analysis` is required."
+                analysis: { type: string }
+                questions:
+                  type: array
+                  maxItems: 20
+                  description: Free-text strings and/or structured questions, answered in order.
+                  items:
+                    oneOf:
+                      - type: string
+                      - $ref: "#/components/schemas/InsightQuestion"
+                config:
+                  $ref: "#/components/schemas/InsightConfig"
+                include_objects: { type: boolean }
+                include_adjacency: { type: boolean }
+      responses:
+        "201":
+          description: "The insight payload plus `answers[]` (one per question, in order)."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SessionInsight"
+        "400":
+          description: "Neither session nor analysis given, more than 20 questions, or the analysis is not successful."
+        "403":
+          description: A REP token asked for a session that rep did not scan.
+        "404":
+          description: No matching analysis (or the session has no successful analysis yet).
+  /ai-object-detection-session-insight/{id}:
+    get:
+      summary: Compute the insight for a session (deep link)
+      description: The path id is read as a SESSION id.
+      operationId: getAiObjectDetectionSessionInsight
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: The freshly computed insight payload.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SessionInsight"
+        "403":
+          description: A REP token asked for a session that rep did not scan.
+        "404":
+          description: The session has no successful analysis yet.
+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:
+    InsightConfig:
+      type: object
+      description: All optional — invalid values fall back to the defaults.
+      properties:
+        min_shelf_gap_m:
+          type: number
+          default: 0.06
+          description: Echoed for compatibility — shelf levels come from the stored composition.
+        shelf_gap_height_factor:
+          type: number
+          default: 0.35
+          description: Echoed for compatibility.
+        default_facing_width_m:
+          type: number
+          default: 0.08
+          description: Fallback facing width (m) when a facing has no measured size.
+        block_min_overlap_m:
+          type: number
+          default: 0.03
+          description: Vertical block merge — required axis overlap (m) between adjacent-shelf runs…
+        block_overlap_frac:
+          type: number
+          default: 0.5
+          description: "…or this fraction of the narrower run's width, whichever is smaller."
+    InsightQuestion:
+      type: object
+      required: [type, target]
+      properties:
+        type:
+          type: string
+          enum: [share_of_shelf, blocking, adjacency]
+        target:
+          type: object
+          description: Resolved by `id` first, then exact name, then fuzzy match.
+          properties:
+            kind:
+              type: string
+              enum: [label, label_group, brand, category, subcategory, product]
+            id: { type: string }
+            name: { type: string }
+    InsightShareRow:
+      type: object
+      properties:
+        key: { type: string }
+        kind:
+          type: string
+          enum: [label, label_group, brand, category, subcategory, product]
+        name: { type: string }
+        facings: { type: number }
+        linear_cm: { type: number }
+        area_cm2: { type: number }
+        facing_share:
+          { type: number, description: 0..1 of all detected facings. }
+        linear_share: { type: number }
+        area_share: { type: number }
+        shelves:
+          type: array
+          items:
+            type: object
+            properties:
+              shelf_index: { type: number }
+              facings: { type: number }
+              linear_cm: { type: number }
+              linear_share_of_shelf: { type: number }
+        labels:
+          type: array
+          items:
+            type: object
+            properties:
+              label_id: { type: string }
+              label_name: { type: string }
+              facings: { type: number }
+    InsightBlocking:
+      type: object
+      properties:
+        key: { type: string }
+        name: { type: string }
+        narrative: { type: string }
+        present: { type: boolean }
+        facings: { type: number }
+        labels_present:
+          type: array
+          items:
+            type: object
+            properties:
+              label_id: { type: string }
+              label_name: { type: string }
+              facings: { type: number }
+        blocks_count: { type: number }
+        is_single_block:
+          type: boolean
+          description: True when every facing of the group sits in ONE contiguous block.
+        largest_block_facings: { type: number }
+        largest_block_share: { type: number }
+        blocks:
+          type: array
+          items:
+            type: object
+            properties:
+              shelves:
+                type: array
+                items: { type: number }
+              facings: { type: number }
+              runs:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    shelf_index: { type: number }
+                    t0: { type: number, description: Left edge along û (m). }
+                    t1: { type: number }
+                    facings: { type: number }
+                    facing_ids:
+                      type: array
+                      items: { type: string }
+        interrupters:
+          type: array
+          description: Foreign labels breaking the block, ranked by interrupting facings.
+          items:
+            type: object
+            properties:
+              label_id: { type: string }
+              label_name: { type: string }
+              facings: { type: number }
+        shelves_spanned:
+          type: array
+          items: { type: number }
+    SessionInsight:
+      type: object
+      properties:
+        session: { type: string }
+        analysis: { type: string }
+        model_version: { type: string }
+        analysis_finished_at: { type: number }
+        computed_at:
+          type: number
+          description: Unix ms — always freshly computed, never cached.
+        config_used:
+          $ref: "#/components/schemas/InsightConfig"
+        scene:
+          type: object
+          properties:
+            facings_placed: { type: number }
+            objects_skipped:
+              type: number
+              description: Analysis objects not counted as facings (back rows / unshelved).
+            shelf_count: { type: number }
+            axis:
+              type: object
+              description: Unit shelf-axis direction û in the horizontal plane.
+              properties:
+                dir_x: { type: number }
+                dir_z: { type: number }
+        totals:
+          type: object
+          properties:
+            facings: { type: number }
+            linear_cm: { type: number }
+            area_cm2: { type: number }
+        shelves:
+          type: array
+          items:
+            type: object
+            properties:
+              index: { type: number, description: 0 = bottom shelf. }
+              y_base_m:
+                { type: number, description: Board level (m, AR world frame). }
+              facings: { type: number }
+              linear_cm: { type: number }
+              span_cm: { type: number }
+              utilization:
+                type: number
+                description: linear_cm / span_cm — how much of the used span is product.
+        share_of_shelf:
+          type: object
+          description: "Keys: `by_label` always; `by_label_group` / `by_brand` / `by_category` / `by_subcategory` / `by_product` only when links exist."
+          additionalProperties:
+            type: array
+            items:
+              $ref: "#/components/schemas/InsightShareRow"
+        blocking:
+          type: object
+          description: Same keys as share_of_shelf; rows only for present groups.
+          additionalProperties:
+            type: array
+            items:
+              $ref: "#/components/schemas/InsightBlocking"
+        objects:
+          type: array
+          description: "Only with `include_objects=true` — facings left→right per shelf."
+          items:
+            type: object
+            properties:
+              shelf_index: { type: number }
+              facings:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id: { type: string }
+                    label_id: { type: string }
+                    label_name: { type: string }
+                    position: { type: number }
+                    from_cm:
+                      type: number
+                      description: Re-based to the shelf's left-most facing.
+                    to_cm: { type: number }
+                    w_cm: { type: number }
+                    h_cm: { type: number }
+                    confidence: { type: number }
+        adjacency:
+          type: array
+          description: "Only with `include_adjacency=true`."
+          items:
+            type: object
+            properties:
+              label_id: { type: string }
+              label_name: { type: string }
+              neighbors:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    label_id: { type: string }
+                    label_name: { type: string }
+                    count: { type: number }
+        answers:
+          type: array
+          description: Present on POST responses only — one per question, in order.
+          items:
+            type: object
+            properties:
+              question:
+                oneOf:
+                  - type: string
+                  - $ref: "#/components/schemas/InsightQuestion"
+              type:
+                type: string
+                enum: [share_of_shelf, blocking, adjacency]
+              resolved: { type: boolean }
+              reason: { type: string }
+              suggestions:
+                type: array
+                items: { type: string }
+              target:
+                type: object
+                properties:
+                  kind: { type: string }
+                  name: { type: string }
+                  label_ids:
+                    type: array
+                    items: { type: string }
+              result:
+                description: Share row, blocking result, or neighbour list per the question type.
+                oneOf:
+                  - $ref: "#/components/schemas/InsightShareRow"
+                  - $ref: "#/components/schemas/InsightBlocking"
+                  - type: object
+              narrative: { type: string }