Command line interface

Command Line Interface to interact with the Ersilia Model Hub

The table details all the commands availabe in Ersilia's CLI.

1. Fetch Command

Fetch a given Ersilia model. Ersilia is smart enough to decide how to fetch this model, ie either using its Docker image, or from source - in most cases, if your Docker engine is active, a model is fetched using its image. However, this behavior can be overridden. When a model is re-fetched, Ersilia deletes all artifacts related to it, but for the sake of efficiency, the user is prompted to override this behavior when running this command.

Option / Argument	Type	Default Value	Description
model (argument)	String	Required	The model ID to be fetched.
--from_dir	String	None	Fetch the given model, from source, using a local path provided on the user's system. The path can be relative or absolute.
--from_github	Flag	False	Fetch the given model, from source, by cloning the GitHub repository of the model on the user's system.
--from_dockerhub	Flag	False	Fetch the given model using its Docker image maintained in Ersilia's public DockerHub registry
--version	String	None	Version of the model to fetch, used when fetching from DockerHub.
--from_s3	Flag	False	Fetch the given model, from source, using the model's code archive maintained on Ersilia's S3 storage servers.
--from_hosted	Flag	False	Fetch the given model, using the URL where the model is hosted. This only creates a basic folder structure for the model, and the model is not actually downloaded.
--with_bentoml	Flag	False	This is a developer specific command and most users will not need to use it. This command fetches a model from source, and packs it using BentoML. For that to happen, the model source needs to follow a specific structure. During model contribution and troubleshooting, it is often useful to fetch a model again, however one may not want to rebuild the model's environment, in which case it can be useful to combine this flag with the --reuse flag.
--with_fastapi	Flag	False	This is a developer specific command and most users will not need to use it. This command fetches a model from source, and packs it using Ersilia Pack, using FastAPI. For that to happen, the model source needs to follow a specific structure. During model contribution and troubleshooting, it is often useful to fetch a model again, however one may not want to rebuild the model's environment, in which case it can be useful to combine this flag with the --reuse flag.
--overwrite/--reuse	Boolean	True	This flag is useful from an efficiency perspective. When fetching a model from source or S3, a conda environment is created, which can be retained and reused, or overwritten, when re-fetching a model.

Example:

$ ersilia fetch eosxxxx --from_github/--from_dockerhub/--from_s3/--from_hosted

$ ersilia fetch eosxxxx --from_github/--from_dockerhub/--from_s3/--from_hosted --overwrite --with_fastapi/--with_bentoml

---

2. Serve Command

This command serves a specified model as an API.

Option / Argument	Type	Default Value	Description
model (argument)	String	Required	The model ID to be served.
--port / -p	Integer	None	The port to use when creating a model server. If unspecified, Ersilia looks for empty ports to use on the user's system.
--track / -t	Flag	False	Whether the model's runs should be tracked to monitor for model and system performance. This telemetry data can be uploaded to S3 if the appropriate credentials are provided. Currently only Ersilia developers and other Ersilia tools have that privilege
--enable-local-cache/--disable-local-cache	Flag	True	Toggle Redis based local caching on or off. If it enabled the results from model APIs will be cached for 7 days.
--max-cache-memory-frac	Float	None	Sets the maximum fraction of memory to use by Redis for caching. Recommened value 0.2-0.7.
--local-cache-only	Bool	False	Specifies to fetch stored model results from local cache. The local caching system is powered by Redis.
--cloud-cache-only	Bool	False	Specifies to fetch stored model results from cloud cache. This allows to fetch model precalculated results in csv file in Ersilia model output format.
--cache-only	Bool	False	Specifies to fetch stored model results from both local and cloud cache. More details are give in a dump CLI.

Examples:

$ ersilia serve eosxxxx --no-cache --port 12450

$ ersilia serve eosxxxx --max-cache-memory-frac 0.5

---

3. Run Command

This command runs a specified model with given inputs and outputs in the shell where the model gets served.

Option / Argument	Type	Default Value	Description
-i, --input	String	Required	Specify the input file, which must be a CSV. Alternatively a single SMILES input can be specified. The input file should ideally have a header. This is a required flag to run a model with an input.
-o, --output	String	None	Specify the file to save the model predictions. This can be a CSV, TSV, or JSON file. If flag is optional and if not specified, output is printed on the user's terminal in JSON format.
-b, --batch_size	Integer	100	Specify the batch size for generating model predictions. By default, Ersilia works with batch size of 100 inputs.
--as_table / -t	Flag	False	Print the model predictions in an ASCII table on the terminal, optionally as required.

---

Example:

$ ersilia run -i input.csv -o output.csv --batch_size 1000 --as_table

4. Example Command

This command can sample inputs for a given model. By default, the command expects a model to be served in the current shell, otherwise a model needs to be explicitly specified. By default, five examples will be sampled for the model and displayed on the user's terminal. This behavior can be customized with relevant flags.

Option / Argument	Type	Default Value	Description
model (argument)	String	None	Optional model ID for which to generate examples.
--n_samples, -n	Integer	5	NuSpecify the number of example inputs to generate for the given model.
--file_name, -f	String	None	File name where the examples should be saved.
--simple / --complete	Flag	True (simple)	Simple inputs only contain essential information such as input SMILES, while complete inputs contain the InChIKey and other fields such as the molecule's name.
--random / --predefined	Flag	True	If the model source contains an example input file, when the predefined flag is set, then inputs are sampled from that file. Only the number of samples present in the file are returned, especially if --n_samples is greater than that number. By default, Ersilia samples inputs randomly.
--deterministic	Flag	False	Used to generate examples data deterministically instead of random sampling. This allows when every time you run with example command with this flag you get the same types of examples.

Example:

$ ersilia example -n 10 --file_name examples.csv

---

5. Catalog Command

List the catalog of Ersilia models. By default, this command only shows the catalog of models available locally on a user's system, in an ASCII table on the user's terminal.

Option / Argument	Type	Default Value	Description
--hub/--local	Flag	False	Toggle between showing models available in the model hub or locally.
--file_name, -f	String	None	Write the requested catalog to a given file.
--more / --less	Flag	False	Print more or less information about the catalog. When less information is requested, only the identifier and slug are displayed. Otherwise, the following fields are displayed: identifier, slug, title, task, input shape, output, output shape, and model source. These flags work with both local and hub context.
--card	Flag	False	Displays the card for the specified model identifier. The requested model does not need to be available locally. Presently, only a single model can be requested.
--as-json /--as-table	Flag	False	Displays the catalog in JSON format on the user's terminal. This may be helpful for downstream processing task. The default behavior to display the catalog in a tabular format. These flags can be used both in the local and hub context.
model (argument)	String	Optional	Model ID for which to display the model card when using the --card flag.

Examples:

$ ersilia catalog

$ ersilia catalog --more --hub

$ ersilia catalog --card eosxxxx --as-json

6. Delete Command

This command deletes a specified model from the local storage. You can delete a specific model by providing its ID or remove all locally available models using the --all flag.

Option / Argument	Type	Default Value	Description
model (argument)	String	Optional	The model ID to delete.
--all	Flag	False	When provided, deletes all locally available models.

Examples:

$ ersilia delete eosxxxx

$ ersilia delete --all

---

7. Close Command

This command closes the current session of the served model and cleans up any associated resources.

Option / Argument	Type	Default Value	Description
(No additional options)			Just run the command to close the session.

Example:

$ ersilia close

---

8. Dump Command

This command used to fetch cached precalculation from the cloud and the local Redis system depending on the flag specified in the serve command 2. Serve Command. Note that fetching sample size of <= 50,000 from a cloud is not recommended as it is expensive.

Option / Argument	Type	Default Value	Description
-n/--n_samples	Integer	-1	The sample size to for the cache we want fetch either from a cloud or from a local. Its is -1 by default which indicates fetch all stored cached results.
-o/--output/output	String	None	The path of the csv file to store the fetched cached results. Currently this CLI only supports csv as its output.

Example:

$ ersilia dump -o my_output.csv

 ersilia dump -n 100000 -o my_output.csv

9. Test Command

This command tests a model and produces performance metrics, allowing you to specify various options such as the source from which to fetch the model, and the depth of the testing process.

Option / Argument	Type	Default Value	Description
model (argument)	String	Required	The model ID to test.
--from_dir	String	None	Local directory where the model is stored.
--from_github	Flag	False	Fetch the model directly from GitHub.
--from_dockerhub	Flag	False	Force fetching the model from DockerHub.
--from_s3	Flag	False	Force fetching the model from an AWS S3 bucket.
--version	String	None	Specify the version of the model to fetch, especially useful when fetching from DockerHub.
--shallow	Flag	False	Run shallow tests (e.g., container size, output consistency).
--deep	Flag	False	Run deep tests (e.g., computational performance checks).
--surface	Flag	False	Additional flag for testing, similar to deep checks.
--inspect	Flag	False	Run inspection tests for further model diagnostics.
--report_path	String	None	Specify the file path to output the test report in JSON format.
--clean	Flag	False	Clean up the temporary folder after testing.

Examples:

Basic Testing (local model):

$ ersilia test eosxxxx --from_dir /path/to/model

Testing with Different Sources:

$ ersilia test eosxxxx --from_github/--from_dockerhub/--from_s3

Testing with Specific Levels:

$ ersilia test eosxxxx --surface/--shallow/--deep