repzo 1.0.292 → 1.0.293

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

@@ -0,0 +1,349 @@
+openapi: 3.0.3
+info:
+  title: Repzo API - AI Object Detection Mission
+  version: 1.0.0
+  description: |
+    **Missions** group planogram metrics (`/ai-object-detection-metric`)
+    with a WEIGHT each — the mission score is the weighted mean of the
+    metrics' effective result scores (0..1). A metric without a result on an
+    analysis counts as 0 (a demanded check that never ran must not score as
+    passed). Missions are grouped into mission SETS
+    (`/ai-object-detection-mission-set`) which assignment rules attach to
+    clients; a session started FROM a mission carries the mission's optional
+    detection `category`, which drives the auto-analysis.
+
+    **Scores read.** `GET ?scores_for=<analysisId>` resolves the assignment
+    rules against that analysis's session CLIENT and returns every enabled
+    mission with `assigned` (attached via a rule), `via_sets`,
+    `requirement_mode` (the strictest demand the matched rules place on it —
+    `not_required` / `submission_required` / `completion_required`; absent
+    when unassigned), the weighted `score` 0..1, `min_score` + `completed`
+    (a NON-ZERO score ≥ min_score; a zero score never completes — checks
+    that never ran are not achievements; `min_score` is the mission's
+    optional completion threshold, default 0) and the per-metric breakdown
+    (weight, effective score, `missing`). Resolution happens at read time —
+    recalculations and rule edits are reflected immediately, nothing is
+    persisted on the client. The STORED per-session outcome lives in
+    `/ai-object-detection-mission-results`.
+
+    **Validation.** Create AND update require `metrics` with at least one
+    row of `{ metric: <valid id>, weight: <number ≥ 0> }`; `min_score` must
+    be within 0..1 when given; `category` must be a valid id, or `null`/""
+    to clear it. Every violation is listed in one 400.
+
+    **Multi-tenancy & lifecycle.** Scoped by `company_namespace` (injected
+    from the caller's token; SDK callers may pass an explicit value on
+    create), soft-deleted via `disabled`. `enabled: false` hides the
+    mission from evaluation and `scores_for`. `PATCH` is not supported
+    (400 — use `PUT`). Admin-facing.
+servers:
+  - url: https://sv.api.repzo.me
+security:
+  - ApiKeyAuth: []
+  - JwtAuth: []
+paths:
+  /ai-object-detection-mission:
+    get:
+      summary: List missions (or resolved scores for an analysis)
+      operationId: findMission
+      parameters:
+        - in: query
+          name: _id
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: name
+          description: Exact name match.
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: search
+          description: Case-insensitive substring search on `name`.
+          schema: { type: string }
+        - in: query
+          name: enabled
+          schema: { type: boolean }
+        - in: query
+          name: disabled
+          description: "Include soft-deleted missions (`true`) or only live ones (`false`). Omitted = no filter."
+          schema: { type: boolean }
+        - in: query
+          name: from_updatedAt
+          schema: { type: number }
+        - in: query
+          name: to_updatedAt
+          schema: { type: number }
+        - in: query
+          name: from_createdAt
+          schema: { type: number }
+        - in: query
+          name: to_createdAt
+          schema: { type: number }
+        - in: query
+          name: scores_for
+          description: |
+            Analysis _id — returns RESOLVED MISSION SCORES for it instead of
+            documents (see `MissionScores`). `completed` = a NON-ZERO score ≥
+            the mission's min_score (computed at read, never stamped). All
+            other filters and pagination are ignored in this mode.
+          schema: { type: string }
+        - in: query
+          name: per_page
+          schema: { type: integer, minimum: 1 }
+        - in: query
+          name: page
+          schema: { type: integer, minimum: 1 }
+      responses:
+        "200":
+          description: "Paginated documents (newest `_id` first), or `MissionScores` when `scores_for` is given."
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: "#/components/schemas/MissionFindResult"
+                  - $ref: "#/components/schemas/MissionScores"
+    post:
+      summary: Create a mission
+      operationId: createMission
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MissionCreateBody"
+      responses:
+        "201":
+          description: The created document.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Mission"
+        "400":
+          description: Validation failed — the message lists every violation.
+  /ai-object-detection-mission/{id}:
+    get:
+      summary: Get a mission
+      operationId: getMission
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: The document.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Mission"
+        "400":
+          description: Not found.
+    put:
+      summary: Update a mission (re-validated)
+      description: "Same validation as create — `metrics` (≥ 1 row) is required again. `category: null` clears the category; omitting it leaves the stored value. Set `disabled: true` to soft-delete."
+      operationId: updateMission
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MissionUpdateBody"
+      responses:
+        "200":
+          description: The updated document.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Mission"
+        "400":
+          description: Validation failed.
+        "404":
+          description: Not found.
+    delete:
+      summary: Soft-delete a mission
+      operationId: removeMission
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: The disabled document.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Mission"
+        "404":
+          description: Not found.
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: api-key
+    JwtAuth:
+      type: apiKey
+      in: header
+      name: Authorization
+  schemas:
+    UserStamp:
+      type: object
+      description: "Who created / last edited the document (server-stamped from the token)."
+      properties:
+        _id: { type: string }
+        name: { type: string }
+        type:
+          type: string
+          enum: [admin, rep, client, tenant]
+        admin: { type: string }
+        rep: { type: string }
+        client: { type: string }
+        tenant: { type: string }
+    MissionMetricRow:
+      type: object
+      required: [metric, weight]
+      properties:
+        metric:
+          type: string
+          description: Metric id (`/ai-object-detection-metric`).
+        weight:
+          type: number
+          minimum: 0
+          description: Weight in the weighted mean.
+    MissionFields:
+      type: object
+      properties:
+        name: { type: string }
+        description: { type: string }
+        metrics:
+          type: array
+          minItems: 1
+          description: "Weighted metric rows — the mission's composition (required, ≥ 1 row)."
+          items:
+            $ref: "#/components/schemas/MissionMetricRow"
+        min_score:
+          type: number
+          minimum: 0
+          maximum: 1
+          default: 0
+          description: 'Optional completion threshold: the mission counts as COMPLETED on an analysis when its NON-ZERO weighted score ≥ this. 0 (default) = any non-zero score completes. null/"" = leave default.'
+        category:
+          type: string
+          nullable: true
+          description: "Optional detection category (`/ai-object-detection-category`). The mobile stamps it on a session started FROM this mission, so the category pipeline drives the auto-analysis. null clears it."
+        enabled: { type: boolean, default: true }
+    MissionCreateBody:
+      allOf:
+        - $ref: "#/components/schemas/MissionFields"
+        - type: object
+          required: [name, metrics]
+          properties:
+            company_namespace:
+              type: array
+              items: { type: string }
+              description: Optional tenant namespace override for SDK callers.
+    MissionUpdateBody:
+      allOf:
+        - $ref: "#/components/schemas/MissionFields"
+        - type: object
+          required: [metrics]
+          properties:
+            disabled:
+              type: boolean
+              description: Soft-delete flag.
+    Mission:
+      allOf:
+        - $ref: "#/components/schemas/MissionFields"
+        - type: object
+          properties:
+            _id: { type: string }
+            disabled: { type: boolean }
+            creator:
+              $ref: "#/components/schemas/UserStamp"
+            editor:
+              $ref: "#/components/schemas/UserStamp"
+            company_namespace:
+              type: array
+              items: { type: string }
+            createdAt: { type: string, format: date-time }
+            updatedAt: { type: string, format: date-time }
+    MissionScores:
+      type: object
+      description: "Response of `GET ?scores_for=<analysisId>` — every enabled mission scored against the analysis, assigned ones first, then by name."
+      properties:
+        analysis: { type: string }
+        client:
+          type: string
+          nullable: true
+          description: The analysis's session client (null when the session has none).
+        missions:
+          type: array
+          items:
+            type: object
+            properties:
+              _id: { type: string }
+              name: { type: string }
+              assigned:
+                type: boolean
+                description: An enabled assignment rule attaches a set containing this mission to the client.
+              via_sets:
+                type: array
+                items: { type: string }
+                description: Names of the assigned sets this mission arrived through.
+              requirement_mode:
+                type: string
+                enum: [not_required, submission_required, completion_required]
+                description: Strictest demand the matched rules place on it; absent when unassigned.
+              score:
+                type: number
+                description: Weighted mean 0..1 of the metrics' effective scores (missing metrics count 0).
+              min_score: { type: number }
+              completed:
+                type: boolean
+                description: NON-ZERO score ≥ min_score.
+              metrics:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    metric: { type: string }
+                    name:
+                      type: string
+                      description: Metric-name snapshot from its result (absent when missing).
+                    weight: { type: number }
+                    score:
+                      type: number
+                      description: Effective 0..1 score of the metric's result; absent when missing.
+                    missing:
+                      type: boolean
+                      description: The metric has no result on this analysis.
+    MissionFindResult:
+      type: object
+      description: Standard paginated result envelope.
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/Mission"
+        total_result: { type: number }
+        current_count: { type: number }
+        total_pages: { type: number }
+        current_page: { type: number }
+        per_page: { type: number }
+        first_page_url: { type: string }
+        last_page_url: { type: string }
+        next_page_url: { type: string, nullable: true }
+        prev_page_url: { type: string, nullable: true }
+        path: { type: string }

package/src/oas/ai-object-detection-model-version-epoch.yaml

@@ -0,0 +1,214 @@
+openapi: 3.0.3
+info:
+  title: Repzo API - Object Detection Model Version Epochs
+  version: 1.0.0
+  description: |
+    Per-epoch training telemetry for one object-detection model version — the
+    series behind the training curves.
+
+    **Where the rows come from.** They are NOT written through this service.
+    The Ultralytics training run (the "Run on agent" snippet from
+    `ai-object-detection-model-version-train-agent`) streams metrics to
+    `POST /ul-hub/v1/models/:id` on every epoch via the Ultralytics HUB client;
+    that ingest de-slashes Ultralytics' native keys (`train/box_loss` →
+    `train_loss_metrics.box_loss`, `metrics/mAP50-95(B)` →
+    `performance_metrics.mAP50_95_B`) and upserts one row per epoch index. This
+    service is strictly READ-ONLY — create/update/patch/remove all return 400.
+
+    **Who calls it.** Back-office admins via the dashboard's version detail
+    screen (Metrics tab). Scoped by `company_namespace[]`.
+
+    **Shape of the response.** `find` is NOT paginated: a curve needs every
+    point and a run is bounded (hundreds of epochs at most), so the full series
+    is returned in `_index` order alongside a derived `summary` (best epoch,
+    best vs final metrics, architecture cost, final generalization gap).
+    `per_page` / `page` / `sort` are ignored. The summary is computed on read,
+    so versions trained before this endpoint existed summarize correctly too.
+
+    **Key relationships.** `model_version` → `ai-object-detection-model-version`.
+    The same best-epoch roll-up is snapshotted onto that version's `metrics` /
+    `model_stats` when its weights upload completes.
+servers:
+  - url: https://sv.api.repzo.me
+security:
+  - ApiKeyAuth: []
+  - JwtAuth: []
+paths:
+  /ai-object-detection-model-version-epoch:
+    get:
+      summary: List every reported epoch of one training run
+      description: |
+        Returns the full epoch series for `model_version`, ordered by `_index`
+        ascending, plus a derived `summary`. Not paginated.
+      operationId: findAiObjectDetectionModelVersionEpochs
+      parameters:
+        - in: query
+          name: model_version
+          required: true
+          description: |
+            The `ai-object-detection-model-version` `_id` whose run to read.
+            Required — epochs are only meaningful per version (400 without it).
+          schema: { type: string }
+          example: 6a6e0687de060479c01c9e49
+        - in: query
+          name: _id
+          description: "Filter to specific epoch row id(s). Pass once or as `?_id[]=...`."
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: _index
+          description: Filter to one or more epoch indexes (0-based).
+          schema:
+            oneOf:
+              - type: integer
+                minimum: 0
+              - type: array
+                items: { type: integer, minimum: 0 }
+        - in: query
+          name: type
+          description: Payload kind reported by the trainer. Only `metrics` today.
+          schema: { type: string, enum: [metrics] }
+        - in: query
+          name: disabled
+          description: Include disabled rows. Defaults to `false`.
+          schema: { type: boolean, default: false }
+      responses:
+        "200":
+          description: The ordered epoch series and its derived summary.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EpochFindResult"
+        "400":
+          description: "`model_version` was not supplied."
+  /ai-object-detection-model-version-epoch/{id}:
+    get:
+      summary: Get one epoch row
+      operationId: getAiObjectDetectionModelVersionEpoch
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: The epoch document.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EpochSchema"
+        "400":
+          description: No epoch with that id.
+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:
+    LossMetrics:
+      type: object
+      description: Ultralytics loss components for one epoch.
+      properties:
+        box_loss: { type: number, description: Bounding-box regression loss. }
+        cls_loss: { type: number, description: Classification loss. }
+        dfl_loss: { type: number, description: Distribution focal loss. }
+    PerformanceMetrics:
+      type: object
+      description: |
+        Validation metrics for one epoch. The `_B` suffix is Ultralytics' own —
+        it denotes the Box (detection) task, as opposed to segmentation/pose.
+      properties:
+        precision_B: { type: number }
+        recall_B: { type: number }
+        mAP50_B:
+          type: number
+          description: mAP at IoU 0.50 — the lenient, headline number.
+        mAP50_95_B:
+          type: number
+          description: |
+            mAP averaged over IoU 0.50:0.95 — the strict number `best.pt` is
+            selected on.
+    ModelStats:
+      type: object
+      description: |
+        Architecture cost. Ultralytics reports it only on some epochs, so it can
+        be absent on any individual row.
+      properties:
+        parameters: { type: integer, description: Total weight count. }
+        GFLOPs: { type: number, description: Forward-pass cost per image. }
+        speed_PyTorch_ms:
+          type: number
+          description: Per-image PyTorch inference latency measured during validation.
+    EpochSchema:
+      type: object
+      properties:
+        _id: { type: string }
+        _index:
+          {
+            type: integer,
+            description: "0-based epoch number; unique per `model_version`.",
+          }
+        model_version: { type: string }
+        type: { type: string, enum: [metrics] }
+        train_loss_metrics: { $ref: "#/components/schemas/LossMetrics" }
+        val_loss_metrics: { $ref: "#/components/schemas/LossMetrics" }
+        performance_metrics: { $ref: "#/components/schemas/PerformanceMetrics" }
+        model_stats: { $ref: "#/components/schemas/ModelStats" }
+        disabled: { type: boolean }
+        company_namespace: { type: array, items: { type: string } }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+    EpochPerformanceRollup:
+      type: object
+      properties:
+        mAP50: { type: number }
+        mAP50_95: { type: number }
+        precision: { type: number }
+        recall: { type: number }
+    EpochSummary:
+      type: object
+      description: Derived on read from the returned series.
+      properties:
+        epochs_reported:
+          type: integer
+          description: |
+            How many epochs the trainer has reported so far — less than the
+            configured `epochs` while a run is still in flight.
+        best_epoch:
+          type: integer
+          description: "`_index` of the highest-mAP50-95 epoch — what `best.pt` holds."
+        best: { $ref: "#/components/schemas/EpochPerformanceRollup" }
+        final:
+          allOf:
+            - $ref: "#/components/schemas/EpochPerformanceRollup"
+            - description: Last reported epoch — diverges from `best` when the run overfit.
+        model_stats: { $ref: "#/components/schemas/ModelStats" }
+        final_generalization_gap:
+          type: number
+          description: |
+            Total validation loss minus total training loss at the final epoch.
+            Positive and widening is the classic overfitting signature — the run
+            kept fitting the training set while validation stopped improving.
+    EpochFindResult:
+      type: object
+      properties:
+        data:
+          type: array
+          description: Every reported epoch, ascending by `_index`.
+          items: { $ref: "#/components/schemas/EpochSchema" }
+        total_result: { type: integer }
+        summary: { $ref: "#/components/schemas/EpochSummary" }

package/src/oas/ai-object-detection-model-version-train-agent.yaml

@@ -0,0 +1,88 @@
+openapi: 3.0.3
+info:
+  title: Repzo API - AI Object Detection Model Version Train Agent
+  version: 1.0.0
+  description: |
+    Returns a **YOLO / Ultralytics bootstrap code snippet** for a given
+    `ai-object-detection-model-version` — the script a self-hosted trainer runs to
+    train against Repzo's own server (via the `ul-hub` Ultralytics-Hub-compatible
+    endpoints). The response is a list of ordered `steps[]`, each a
+    `code_message` to paste into a terminal / notebook: (1) `pip install` the
+    pinned ultralytics release, (2) point the HUB client at Repzo, `hub.login`
+    with an API key and `YOLO("<hub>/models/<version-id>").train()` — which
+    resolves the version's `initial_weight`, dataset zip and `train_settings`,
+    streams per-epoch metrics into `ai-object-detection-model-version-epoch`
+    and uploads `best.pt` / `last.pt` (flipping the version to `trained`), and
+    (3) POST the run's plots, `results.csv` and `args.yaml` to
+    `/ul-hub/v1/models/{id}/upload?type=artifacts`, because the HUB client sends
+    only weights.
+
+    **The ultralytics version is pinned, deliberately.** Release `8.4.115`
+    deleted the `ultralytics.hub` package: models no longer load from HUB URLs
+    and training no longer manages HUB sessions or heartbeats. This whole flow
+    rides that client, so on `8.4.115+` the script fails at import and no
+    results are ever reported. The snippet installs `ultralytics==8.4.114` (the
+    last release shipping the client) and surfaces it as `ultralytics_version`;
+    it must not be "upgraded" with `-U`.
+
+    **Who calls it.** Back-office admins setting up training. Stateless — it
+    only reads the model version. Only `GET /{id}` (`get`) is implemented —
+    `find`, `create`, `update`, `patch`, `remove` return 400. Scoped by
+    `company_namespace[]` through the version lookup.
+servers:
+  - url: https://sv.api.repzo.me
+security:
+  - ApiKeyAuth: []
+  - JwtAuth: []
+paths:
+  /ai-object-detection-model-version-train-agent/{id}:
+    get:
+      summary: Get the training bootstrap snippet for a version
+      description: "`{id}` is the `ai-object-detection-model-version` id. The snippet embeds that id, the version's `initial_weight`, and the Repzo `ul-hub` base URLs."
+      operationId: getAiObjectDetectionTrainAgent
+      parameters:
+        [{ in: path, name: id, required: true, schema: { type: string } }]
+      responses:
+        "200":
+          description: The bootstrap steps for training the model version.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/TrainAgentSnippet" }
+        "400":
+          description: "Model version not found (or the caller tried `find`/`create`/`update`/`patch`/`remove`)."
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      {
+        type: apiKey,
+        in: header,
+        name: api-key,
+        description: "Server-issued API key. Also `x-api-key` header or `?apiKey=` query.",
+      }
+    JwtAuth:
+      {
+        type: apiKey,
+        in: header,
+        name: Authorization,
+        description: "Raw JWT — no `Bearer ` prefix. From `POST /authenticate`.",
+      }
+  schemas:
+    TrainAgentStep:
+      type: object
+      required: [code_message]
+      properties:
+        code_message:
+          type: string
+          description: A ready-to-run shell / Python snippet (multi-line).
+    TrainAgentSnippet:
+      type: object
+      required: [steps]
+      properties:
+        steps:
+          type: array
+          description: "Ordered: pin-install ultralytics, train against Repzo's ul-hub, upload plots + args."
+          items: { $ref: "#/components/schemas/TrainAgentStep" }
+        ultralytics_version:
+          type: string
+          description: "The pinned ultralytics release the snippet installs (currently `8.4.114`)."
+          example: "8.4.114"