Metadata-Version: 2.4
Name: cytario-app-sdk
Version: 2.0.0
Summary: CLI for registering Cytario analysis applications in an OCI Distribution v1.1 registry
Project-URL: Homepage, https://github.com/cytario/cytario-app-sdk
Project-URL: Repository, https://github.com/cytario/cytario-app-sdk
Project-URL: Issues, https://github.com/cytario/cytario-app-sdk/issues
Project-URL: Changelog, https://github.com/cytario/cytario-app-sdk/releases
Author: Cytario
License-Expression: MIT
License-File: LICENSE
Keywords: app-definition,catalog,cytario,distribution-spec,harbor,oci,referrer
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer-config[yaml]>=1.4
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# cytario-app-sdk

[![PyPI version](https://img.shields.io/pypi/v/cytario-app-sdk.svg)](https://pypi.org/project/cytario-app-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/cytario-app-sdk.svg)](https://pypi.org/project/cytario-app-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/cytario/cytario-app-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/cytario/cytario-app-sdk/actions/workflows/ci.yml)
[![Release](https://github.com/cytario/cytario-app-sdk/actions/workflows/release.yml/badge.svg)](https://github.com/cytario/cytario-app-sdk/actions/workflows/release.yml)

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 and input/output data roles. The SDK
attaches the app-definition to the container image as an **OCI Image Format
annotation** (`org.cytario.appdef.v1`) on the image manifest, then PUTs the
manifest back under its original tag. Because the annotation is part of the
manifest content, the manifest's immutable content digest binds the definition
to the exact image — pinning the image by digest also pins the definition. The
Cytario runtime fetches the manifest via `GET /v2/<name>/manifests/<ref>` and
reads the definition from its annotations; no Harbor-specific API is used.

Application access (who may see/run an app, who may edit its saved configs) is
not part of the app-definition. Entitlement is governed by the catalog
connection's access scope on the Cytario side, not by anything carried in the
registry image.

## Install

```bash
pip install cytario-app-sdk
cytario-app-sdk --help
```

Or with [`uv`](https://docs.astral.sh/uv/):

```bash
uv tool install cytario-app-sdk
```

## Quick start

```bash
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][typer-config]:

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

[typer-config]: https://github.com/maxb2/typer-config

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

Validate an app-definition without pushing anything:

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

## Registering an app

```yaml
# 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
```

`register` fetches the container image manifest (by tag or digest), builds the
app-definition document, attaches it as the `org.cytario.appdef.v1` annotation
on the manifest, and PUTs the manifest back under the original tag. The new
manifest digest (returned by the registry) pins both the image and the
definition. The Cytario runtime reads the annotation back via
`GET /v2/<name>/manifests/<ref>`; no Harbor-specific calls are made.

## Development

This project uses [`uv`](https://docs.astral.sh/uv/) and targets Python 3.10+.

```bash
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](CONTRIBUTING.md) for the full contributor guide and the
[Releases page][releases] for release history. Versions are cut automatically
with [python-semantic-release][psr] — in no-commit mode, so no release commits
land on `main`.

[releases]: https://github.com/cytario/cytario-app-sdk/releases
[psr]: https://github.com/python-semantic-release/python-semantic-release

## License

Released under the [MIT License](LICENSE). By contributing, you agree that
your contributions will be licensed under the MIT License.
