Command line interface

Command Line Interface to interact with the Ersilia Model Hub

1. Fetch Command

Fetch an Ersilia model to run it locally. Ersilia defaults to using Docker images of the models to avoid system-related problems, your Docker engine needs to be active to allow this. Docker images run containers completely isolated from your system so they will not interfere with any installation you have. Otherwise, models can be fetched from source, i.e, from a local, cloned or downloaded repository. In this case, a conda environment is created to install the necessary packages for the model to run. 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.

Option / Argument	Type	Default Value	Description
<MODEL_ID> (argument)	String	Required	The model ID to be fetched. Cn either be the eos identifier or the slug identifier.
--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_s3	Flag	False	Fetch the given model, from source, using the model's code archive maintained on Ersilia's S3 storage servers.
--from_dockerhub	Flag	True	Fetch the given model using its Docker image maintained in Ersilia's public DockerHub registry.
--version	String	latest	Version of the model to fetch, used when fetching from DockerHub. Only for testing purposes.
--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_fastapi	Flag	True	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. 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 (overwrite)	This flag is useful from an efficiency perspective. When fetching a model from source, 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

---

2. Serve Command

This command serves a specified model as an API.

Option / Argument	Type	Default Value	Description
<MODEL_ID> (argument)	String	Required	The model ID to be served. Cn either be the eos identifier or the slug identifier.
--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 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.
--tracking-use-case	String	local	If --track is true, this command allows specification of the tracking use case. Current options are: local, hosted, self-service and test.
--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	Required
-i, --input	String	None	Pass the input for the model as a .csv file with only one column with header.
-o, --output	String	None	Specify the file to save the model predictions. This can be a CSV or H5.
-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.

---

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, if no model is already served.
--n_samples, -n	Integer	5	Specify 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	--simple	Simple inputs only contain the SMILES, while complete inputs also include InChIKey and the molecule's name.
--random / --predefined	Flag	--random	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	--local	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	--less	Print more or less information about the catalog. With less (default) only the identifier and slug are displayed. Otherwise, the following fields are displayed: identifier, slug, title, task, output, output shape, and model source. These flags work with both local and hub context.
--card	Flag	<MODEL_ID>	Displays the card for the specified model identifier. The requested model does not need to be available locally.
--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.

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_ID> (argument)	String	Required	The model ID to test, either eos identifier or slug.
--from_dir	String	None	Local directory where the model is stored.
--from_github	Flag	True	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	latest	Specify the version of the model to fetch, especially useful when fetching from DockerHub.
--inspect	Flag	False	Run inspection tests for further model diagnostics.
--surface	Flag	False	Additional flag for testing, similar to deep checks.
--shallow	Flag	False	Run shallow tests (e.g., container size, output consistency).
--deep	Flag	False	Run deep tests (e.g., computational performance checks).
--report_path	String	<MODEL_ID>_test.json	Specify the file path to output the test report in JSON format. Automatically set to the root from where the command is called.
--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