Design and document a contract for the structure of a Dioptra plugin

[keithmanville]

In order to import plugins from a git repository we need to document and define the expected structure of a plugin repository and any assumptions being made.

This is a planning and design task. The finalized Dioptra plugin contract will eventually be part of the Dioptra documentation once the import and sync features are implemented.

• [x] The contract is drafted in a document in the Dioptra google drive
• [x] Once finalized the documentation is attached to this issue.

[keithmanville]

This documents the structure and assumptions made in an external git repository containing dioptra plugin(s). This is a draft representing our current thinking. It will likely be refined as we work on the implementation.

The source of a dioptra plugin can be a git repository or a file upload.

• For a git repo the plugin is specified by a URI https://github.com/user/repo.git@branch:/path/to/plugins Where the @branch and :/path/to/plugins are optional. If they are not provided, the default branch is used and the default path is the root of the repository.
• In the case of a file upload, it is an archive file (e.g. tar.gz or zip).

The import and sync workflows will look for a dioptra.toml file in the root of the git repository (or optionally, the provided path in the URI). The dioptra.toml provides the configuration of the dioptra plugins present in this repository. We chose toml as the preferred config file format because it is human readable and writable and is part of the Python standard library.

This is a rough example of what the dioptra.toml file could look like for a simple hello_world plugin:

[plugins]

[plugins.hello_world]
path = "./hello_world" # recursively find all .py files

[[plugins.hello_world.tasks]]
name = "hello.greet"
description = "Print a greeting"

input_params = [
  { name = "greeting", type = "image" },
  { name = "name", type = "string" },
]
output_params = [ { name = "message", type = "string" } ]

[param_types]

# not relevant to the hello world example, but demonstrates how we could specify a custom structure
image = { structure = { list = ["int", "int", "int"], required = true } }

[entrypoints]

[entrypoints.greetings]
task_graph = "./entrypoints/hello-world.yaml"
plugins = [ "hello_world" ]

Note: we plan to use the same import and sync system for entrypoints in the future, but that functionality will not be included in the initial implementation.