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"