revive MMIF consumer spec as a CLI contract #412

Because

We have been talking about what a "consumer" is since clamsproject/clams-python#93 and never settled it. The only written spec is documentation/consumer-tutorial.rst from 2020, and it describes a web app for the Galaxy appliance (port 5000, /display route, Dockerfile). The appliance is gone, and the page is excluded from the docs build in conf.py. So at the moment we have no spec at all.

Meanwhile, consumers kept coming, and none of them follows the old page; For example, we now have mmif summarize as a first-party tool shipped with mmif-python, and visaid-builder is a CLI package by @owencking that bake-swt-visaid runs right after SWT. In both cases, what we built and used was a stable command line, not HTTP services.

So I think we start from defining a clear behavioral contract for consumers as part of this repo, rather than trying to maintain a python class in clams-python. Plus, right now all the consumer in action need mmif-python only anyway. It also sits well next to plugins.rst, which is the same kind of document.

proposal

A new page, documentation/consumers.rst, replaces the old documentation/consumer-tutorial.rst, and document the behaviroal expectations of MMIF consumers. Namely;

1. a consumer takes one MMIF and creates one artifact that is not MMIF. Looping over many MMIF files is not the responsibilty of a consumer, and users can easily write shell scripts to do that as long as the consumer provides a stable interface. "Collection consumers" (processing many MMIF files into one artifact such as evaluation, image-similarity visualization) is out of scope for now.
2. the entry point is consume.py at the consumer source tree root, with a consume(mmif, **params) function that does no file I/O on the input and output, and a CLI around it; python consume.py [IN_MMIF] [-o OUT] [-c CONFIG].
3. two standard options; --document ID to select a document (if many exist), and --document-location REF to give the full path or URL of its file, because the location in a MMIF is where the file was when the apps ran, and the consumer may be running in a different environment with different file locations.
4. only the artifact goes to STDOUT, and the exit status is non-zero when no artifact is created. A missing file is a failure only when the consumer must read it; when the artifact only refers to it (e.g., an HTML video player on a VideoDocument), it should be a warning.
5. the README lists the document and annotation types the consumer reads, and the consumer checks them before the main work. No assumption about document types; a TimeFrame can be on a VideoDocument or an AudioDocument.
6. repos in the org use the consumer- prefix.

Things I don't think we need for now; a ClamsConsumer base class (ClamsApp assumes MMIF output, which consumers don't have), a common HTTP interface (the reason for it was Galaxy; we might revisit this once we have a better understanding of the use cases like data converter as a web service), and mmif consume subcommand with plugin discovery (I thought of it, then realized it's overkill until we have several consumers).

I've been trying this on a prototype timeline visualizer (consumer-viz-timeframes), implementing basic argparser functionality with common flags (like --document-location). Once the common interface is more stable and universal, we can add it as part of mmif-python (maybe or maybe not as a mmif consume-like subcommand). For now, the goal is to have a clear documentation page that describes the expectation.

Done when

• documentation/consumers.rst is in the toctree
• documentation/consumer-tutorial.rst and its exclude line in conf.py are removed
• common CLI flags are discussed and experimented in prototype consumers, and later promoted to the SDK

Additional context

No response