cytario-app-sdk

A small CLI for registering Cytario analysis applications in an OCI Distribution v1.1 registry (e.g. Harbor 2.13+).

Cytario's "app catalog" is our concept, not the registry's: an analysis application is a container image plus a metadata document (the app-definition) that declares the app's parameter schema, input/output roles, and consumer / maintainer groups. The SDK attaches the app-definition to the container image as an OCI Referrer — a manifest with artifactType: application/vnd.cytario.app-definition.v1+json whose subject points at the container image's manifest digest. The Cytario catalog adapter discovers app-definitions via GET /v2/<name>/referrers/<image-digest> and never needs a Harbor-specific API.

Install

pip install cytario-app-sdk
cytario-app-sdk --help

Or with uv:

uv tool install cytario-app-sdk

Quick start

cytario-app-sdk --registry https://harbor.example.com \
  --user 'robot$cytario-catalog' \
  --secret <robot-token> \
  register examples/cellseg.yaml

Connection settings (registry endpoint, user, secret) can be supplied on the command line or via a YAML config file consumed by typer-config:

# cytario-app-sdk.yaml
registry: https://harbor.example.com
user: robot$cytario-catalog
secret: <robot-token>

cytario-app-sdk --config cytario-app-sdk.yaml register examples/cellseg.yaml

Validate an app-definition without pushing anything:

cytario-app-sdk --config cytario-app-sdk.yaml register --dry-run examples/cellseg.yaml

Registering an app

# examples/cellseg.yaml
schemaVersion: 1
name: cellseg
display: Cell Segmentation
description: Runs Cellpose on a 16-bit OME-TIFF.
image:
  repository: cytario/cellseg
  tag: "1.0.0"
parameterSchema:
  type: object
  properties:
    diameter:
      type: number
      default: 30
  required: []
inputRoles:
  - name: image
    mediaTypes:
      - image/tiff
outputRoles:
  - name: segmentation
    mediaTypes:
      - application/vnd.cytario.label-mask
groups:
  consumers:
    - cellbio-team
  maintainers:
    - imaging-platform

register resolves the container image manifest (by tag or digest), builds the app-definition artifact, pushes it as a blob, and pushes an OCI image manifest with subject set to the container image descriptor. The catalog adapter picks it up via the Referrers API; no Harbor-specific calls are made.

Development

This project uses uv and targets Python 3.10+.

uv sync                          # install deps into .venv
uv run cytario-app-sdk --help    # run the CLI
uv run ruff check --fix && uv run ruff format
uv run pytest

See CONTRIBUTING.md for the full contributor guide and the Releases page for release history. Versions are cut automatically with python-semantic-release — in no-commit mode, so no release commits land on main.

License

Released under the MIT License. By contributing, you agree that your contributions will be licensed under the MIT License.