ersilia.api package

Subpackages

• ersilia.api.commands package
  • Submodules
  • ersilia.api.commands.catalog module
    • catalog()
  • ersilia.api.commands.close module
    • close()
  • ersilia.api.commands.delete module
    • delete()
  • ersilia.api.commands.example module
    • example()
  • ersilia.api.commands.fetch module
    • fetch()
  • ersilia.api.commands.info module
    • info()
  • ersilia.api.commands.is_fetched module
    • is_fetched()
  • ersilia.api.commands.run module
    • run()
    • validate_input_output_types()
  • ersilia.api.commands.serve module
    • serve()
  • Module contents
    • ersilia_ali()

Submodules

ersilia.api.create_api module

class ersilia.api.create_api.ErsiliaAPIModel(model_id, verbose=False)

Bases: object

Python API wrapper for interacting with Ersilia Model Hub models.

This class provides a programmatic interface to run, serve, fetch, and manage machine learning models from the Ersilia Model Hub. It wraps the existing CLI-based functionality in a clean Pythonic interface and supports use in context managers.

Parameters:

model_id (str) – The unique identifier of the model to be managed and executed.

fetch():

Downloads the specified model and its dependencies from DockerHub.

serve():

Serves the specified model locally to prepare for inference.

run(input, output, batch_size):

Runs the model on the given input and writes predictions to the output file.

close():

Terminates the model server and cleans up associated resources.

info():

Prints metadata and technical details about the specified model.

example(file_name, simple, random, n_samples, deterministic):

Generates example input files for the model.

delete():

Deletes the specified model and its local artifacts.

__enter__():

Context manager entry — automatically serves the model.

__exit__(exc_type, exc_value, traceback):

Context manager exit — automatically closes the served model.

Usage Example

-------------

>>> from ersilia.api.create_api import ErsiliaAPI

>>> molecular_weight = ErsiliaAPI("eos3b5e")

>>> molecular_weight.fetch()

>>> molecular_weight.serve()

>>> with molecular_weight as model:

>>>     model.info()

close()

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

Parameters:

(str) (model_id)

Returns:

str

Return type:

Confirmation message on success or warning message on failure.

Raises:

RuntimeError – If no model was served in the current session.:

delete()

Deletes a specified model from local storage.

Parameters:

model_id (str) – ID of the model to delete.

Returns:

Confirmation message on success or warning message on failure.

Return type:

str

Raises:

RuntimeError – If the model cannot be deleted.

example(simple, random, n_samples, deterministic)

This command can sample inputs for a given model.

Parameters:

• model (The model ID to be served. Can either be the eos identifier or the slug identifier.)

• file_name (File name where the examples should be saved.)

• simple (Simple inputs only contain the SMILES, while complete inputs also include InChIKey and the molecule's name.)

• 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.)

• n_samples (Specify the number of example inputs to generate for the given model.)

• deterministic (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.)

Returns:

• Function (The exmaple command function to be used by the API.)

• Str (Error message if no model was served in the current session.)

fetch(verbose=None)

Fetches an Ersilia model to run it locally.

This command allows users to fetch a specified model from the model hub (dockerhub, repo, s3 etc…).

Returns:

• Function (The fetch command function to be used by the API.)

• Str (Confirmation message on success or warning message on failure.)

Raises:

RuntimeError – If both BentoML and FastAPI are used together.:

info()

Provides information about a specified model.

This command allows users to get detailed information about a current active session, including information about Model Identifiers, Code and Parameters, Docker Hub link and Architectures.

Parameters:

(str) (model_id)

Returns:

• function (The info command function to be used by the API.)

• str (Confirmation message on success or warning message on failure.)

Raises:

RuntimeError – If no model was served in the current session.:

is_docker()

Checks if Docker is running locally by calling docker info.

Returns:

True if Docker is running, False otherwise.

Return type:

bool

is_fetched()

Checks whether the model has been successfully fetched.

Return type:

Echo Message indicating fetch status.

run(input, output, batch_size=1000)

Runs the current model on a list of SMILES strings and returns the prediction as a pandas data frame.

Parameters:

• input (a list or a path to a CSV file containing SMILES strings.)

• output (path to the output file where predictions will be saved.)

• batch_size (number of SMILES to process per batch)

Returns:

The run command function to be used by the API. A pandas df with the predictions.

Return type:

function

serve(verbose=None)

Serves a specified model as an API.

Parameters:

• model (The model ID to be served. Can either be the eos identifier or the slug identifier.)

• port (The port to use when creating a model server. If unspecified, Ersilia looks for empty ports to use on the user's system.)

• track (Whether the model's runs should be tracked to monitor model and system performance.)

• tracking_use_case (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 (Toggle Redis-based local caching on or off. If enabled, the results from model APIs will be cached for 7 days.)

• local_cache_only (Specifies to fetch stored model results from local cache. The local caching system is powered by Redis.)

• cloud_cache_only (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 (Specifies to fetch stored model results from both local and cloud cache. More details are given in a dump CLI.)

• max_cache_memory_frac (Sets the maximum fraction of memory to use by Redis for caching. Recommended value 0.2-0.7.)

Return type:

Model ID, URL, SRV, Session, SRV, Session, Caching Mode Status, Local Cache Status, Tracking Status

Raises:

• RuntimeError – If the model/URL is not valid or not found,:

• or if the maximum cache memory fraction is outside of the recommended range. –

class ersilia.api.create_api.ErsiliaCatalog(verbose=False)

Bases: object

This class enables users to browse and retrieve information about all models available in the Ersilia Hub. It is designed for general catalog-level operations and is not tied to any specific model instance. Use this class when you want to explore the hub, list available models,

Typical usage includes listing the model catalog via the catalog() method, which mirrors the CLI behavior but returns a structured DataFrame for programmatic use.

catalog(hub=False, file_name=None, browser=False, more=False, card=False, model=None, as_json=False, verbose=False)

API-compatible version of the catalog command with echo-based output. :param hub: If True, fetch the catalog from the hub.

If False, fetch the catalog from the local directory.

Parameters:

• file_name (str or None, default=None) – If specified, write the catalog to this file.

• browser (bool, default=False) – Unused in current version; reserved for future.

• more (bool, default=False) – If True, show more detail in catalog.

• card (bool, default=False) – If True, display the model card for a given model.

• model (str or None, default=None) – The model ID for which to display metadata.

• as_json (bool, default=False) – If True, return JSON output instead of a formatted table.

• verbose (bool, default=False) – If True, enable verbose logging.

Returns:

A DataFrame containing the last two columns of the model catalog. Also prints the full catalog as a table or JSON to the terminal, depending on as_json.

Return type:

pandas.DataFrame or dict or None

ersilia.api.echo module

class ersilia.api.echo.Silencer

Bases: object

A class to manage the silencing of CLI output.

silence_file

Path to the silence file.

Type:

str

is_silence()

Checks if the CLI output is silenced.

speak()

Enables CLI output.

silence()

Disables CLI output.

is_silence()

Checks if the CLI output is silenced.

Returns:

True if the CLI output is silenced, False otherwise.

Return type:

bool

silence()

Disables CLI output.

speak()

Enables CLI output.

ersilia.api.echo.echo(text, **styles)

Prints styled text to the CLI, optionally with emojis, unless silenced.

Parameters:

• text (str) – The text to be printed.

• **styles (dict) – Additional styling options for the text.

Return type:

None

Module contents

class ersilia.api.ErsiliaCatalog(verbose=False)

Bases: object

This class enables users to browse and retrieve information about all models available in the Ersilia Hub. It is designed for general catalog-level operations and is not tied to any specific model instance. Use this class when you want to explore the hub, list available models,

Typical usage includes listing the model catalog via the catalog() method, which mirrors the CLI behavior but returns a structured DataFrame for programmatic use.

catalog(hub=False, file_name=None, browser=False, more=False, card=False, model=None, as_json=False, verbose=False)

API-compatible version of the catalog command with echo-based output. :param hub: If True, fetch the catalog from the hub.

If False, fetch the catalog from the local directory.

Parameters:

• file_name (str or None, default=None) – If specified, write the catalog to this file.

• browser (bool, default=False) – Unused in current version; reserved for future.

• more (bool, default=False) – If True, show more detail in catalog.

• card (bool, default=False) – If True, display the model card for a given model.

• model (str or None, default=None) – The model ID for which to display metadata.

• as_json (bool, default=False) – If True, return JSON output instead of a formatted table.

• verbose (bool, default=False) – If True, enable verbose logging.

Returns:

A DataFrame containing the last two columns of the model catalog. Also prints the full catalog as a table or JSON to the terminal, depending on as_json.

Return type:

pandas.DataFrame or dict or None

ersilia.api.ErsiliaModel

alias of ErsiliaAPIModel