Distributing Predictors

Because Sharing is Caring

Predictors are designed to be shared. Whether you choose to open-source your predictor or distribute it within your organization, here are some general guidelines:

Packaging Predictors

INCOMPLETE.

You can use NatML Hub to generate a template predictor package that already has this layout, saving you time.

Publishing on Hub

All public predictors on NatML Hub must pass a review process to ensure that they meet developer experience and performance standards. Below are the criteria used in the review process:

Developer Experience

The foundational principle in designing the developer experience is to reduce cognitive load. The developer should not have to learn many--or ideally, any--new concepts in order to use your predictor.

Try to keep the number of public methods in your predictor at a minimum. Ideally, there should only be one public method: Predict.

The README should be the entrypoint for developers. Keeping in line with the considerations above, the README should very quickly discuss how the predictor is used, with code snippets.

Most developers will simply not read the README, so keeping it short and sweet would increase their chances of actually reading it.

API Design

NatML predictors have a typical usage pattern:

1. Create the predictor.

2. Call predict with one or more features.

3. Use the output(s) directly, or call a post-processing method on the output(s).

Predictors must not deviate from this usage pattern. Specifically, the predictor must not have any public methods for feature pre- or post-processing.

Finally, all public methods must be annotated with JSDoc documentation. This is critical for developers to know how to use different methods in your classes.

Most code editors have intellisense which automatically display the docs to the developer. This significantly increases developer productivity.