ersilia.serve package¶

Subpackages¶

ersilia.serve.environment package

Submodules¶

ersilia.serve.api module¶

class ersilia.serve.api.Api(model_id, url, api_name, save_to_lake, config_json)[source]¶

Bases: object

Class to interact with the API for a given model.

Parameters:

model_id (str) – The ID of the model.
url (str) – The URL of the API.
api_name (str) – The name of the API.
save_to_lake (bool) – Whether to save results to the data lake.
config_json (dict) – Configuration in JSON format.

Examples

api = Api(
    model_id="eosxxxx",
    url="http://0.0.0.0:25512/",
    api_name="run",
    save_to_lake=True,
    config_json={},
)
result = api.post(
    input="input.json",
    output="output.csv",
    batch_size=10,
)

meta()[source]¶

Get metadata from the output adapter.

Returns:: Metadata information.
Return type:: dict

post(input, output, batch_size)[source]¶

Post input data to the API and get the result.

Parameters:

input (str) – The input data file or data.
output (str) – The output data file.
batch_size (int) – The batch size for processing.

Yields:

dict – The result of the API call.

post_amenable_to_h5(input, output, batch_size)[source]¶

Post input data to the API and get the result, handling HDF5 serialization.

Parameters:

input (str) – The input data file or data.
output (str) – The output data file.
batch_size (int) – The batch size for processing.

Yields:

dict – The result of the API call.

post_only_calculations(input, output, batch_size)[source]¶

Post input data to the API and get the result, performing only calculations.

Parameters:

input (str) – The input data file or data.
output (str) – The output data file.
batch_size (int) – The batch size for processing.

Yields:

dict – The result of the API call.

post_only_reads(input, output, batch_size)[source]¶

Post input data to the API and get the result, performing only reads.

Parameters:

input (str) – The input data file or data.
output (str) – The output data file.
batch_size (int) – The batch size for processing.

Yields:

dict – The result of the API call.

post_unique_input(input, output, batch_size)[source]¶

Post unique input data to the API and get the result.

Parameters:

input (str) – The input data file or data.
output (str) – The output data file.
batch_size (int) – The batch size for processing.

Yields:

dict – The result of the API call.

ersilia.serve.autoservice module¶

class ersilia.serve.autoservice.AutoService(model_id, service_class=None, config_json=None, preferred_port=None, url=None)[source]¶

Bases: ErsiliaBase

Class to automatically determine and manage the service for a given model.

This class is responsible for selecting the appropriate service to run a model based on its configuration. A “service” in this context refers to the environment or platform where the model will be executed, such as a system bundle, virtual environment, Conda environment, Docker image, or a hosted service.

The class can automatically decide which service to use based on the availability and configuration of the model. It also provides methods to start, stop, and manage the service, as well as to interact with the model’s APIs.

Parameters:

model_id (str) – The ID of the model.
service_class (str, optional) – The class of the service.
config_json (dict, optional) – Configuration in JSON format.
preferred_port (int, optional) – The preferred port for the service.
url (str, optional) – The URL of the service.

Examples

service = AutoService(
    model_id="model123", config_json={}
)
service.serve()

api(api_name, input, output=None, batch_size=100)[source]¶

Call an API for the model.

Parameters:

api_name (str) – The name of the API.
input (str) – The input data file or data.
output (str, optional) – The output data file.
batch_size (int, optional) – The batch size for processing.

Yields:

dict – The result of the API call.

clean_before_serving()[source]¶: Clean processes before serving.

clean_docker_containers()[source]¶: Clean Docker containers if necessary.

clean_temp_dir()[source]¶: Clean the temporary directory.

close()[source]¶: Close the service.

get_apis()[source]¶

Get the list of APIs available for the model.

Returns:: List of API names.
Return type:: list

is_available()[source]¶

Check if the service is available.

Returns:: True if the service is available, False otherwise.
Return type:: bool

is_served()[source]¶

Check if the service is currently being served.

Returns:: True if the service is being served, False otherwise.
Return type:: bool

serve()[source]¶: Serve the application.

ersilia.serve.schema module¶

class ersilia.serve.schema.ApiSchema(model_id, config_json)[source]¶

Bases: ErsiliaBase

Class to manage and interact with the API schema for a given model.

An API schema defines the structure of the input and output data for the APIs of a model. It includes information about the types and shapes of the data fields, as well as any metadata associated with them. This class provides methods to retrieve and manipulate the schema, check for HDF5 serializability, and generate empty representations of the input and output data.

Parameters:

model_id (str) – The ID of the model.
config_json (dict) – Configuration in JSON format.

empty() → dict[source]¶

Get an empty input and output representation for all APIs.

Returns:: An empty input and output representation for all APIs.
Return type:: dict

empty_by_api(api_name: str) → dict[source]¶

Get an empty input and output representation for a specific API.

Parameters:: api_name (str) – The name of the API.
Returns:: An empty input and output representation for the specified API.
Return type:: dict

empty_by_field(field: dict) → list[source]¶

Get an empty representation for a specific field.

Parameters:: field (dict) – The field schema.
Returns:: An empty representation of the field.
Return type:: list

empty_input_by_api(api_name: str) → dict[source]¶

Get an empty input representation for a specific API.

Parameters:: api_name (str) – The name of the API.
Returns:: An empty input representation for the specified API.
Return type:: dict

empty_output_by_api(api_name: str) → dict[source]¶

Get an empty output representation for a specific API.

Parameters:: api_name (str) – The name of the API.
Returns:: An empty output representation for the specified API.
Return type:: dict

get() → dict[source]¶

Get the schema data.

Returns:: The schema data.
Return type:: dict

get_apis() → list[source]¶

Get the list of APIs available for the model.

Returns:: List of API names.
Return type:: list

get_meta() → dict[source]¶

Get the metadata for all APIs.

Returns:: The metadata for all APIs.
Return type:: dict

get_meta_by_api(api_name: str) → dict[source]¶

Get the metadata for a specific API.

Parameters:: api_name (str) – The name of the API.
Returns:: The metadata for the specified API.
Return type:: dict

get_output_by_api(api_name: str) → dict[source]¶

Get the output schema for a specific API.

Parameters:: api_name (str) – The name of the API.
Returns:: The output schema for the specified API.
Return type:: dict

get_schema_by_api(api_name: str) → dict[source]¶

Get the schema for a specific API.

Parameters:: api_name (str) – The name of the API.
Returns:: The schema for the specified API.
Return type:: dict

is_h5_serializable(api_name: str) → bool[source]¶

Check if the output schema for a specific API is HDF5 serializable.

Parameters:: api_name (str) – The name of the API.
Returns:: True if the output schema is HDF5 serializable, False otherwise.
Return type:: bool

isfile() → bool[source]¶

Check if the schema file exists.

Returns:: True if the schema file exists, False otherwise.
Return type:: bool

property schema: dict¶

Get the schema data.

Returns:: The schema data.
Return type:: dict

ersilia.serve.services module¶

class ersilia.serve.services.BaseServing(model_id, config_json=None, preferred_port=None, url=None)[source]¶

Bases: ErsiliaBase

Base class for serving models.

Parameters:

model_id (str) – The ID of the model to be served.
config_json (dict, optional) – Configuration settings in JSON format.
preferred_port (int, optional) – Preferred port for serving the model.
url (str, optional) – URL for the served model.

class ersilia.serve.services.CondaEnvironmentService(model_id, config_json=None, preferred_port=None, url=None)[source]¶

Bases: _LocalService

Service class for managing Conda environment models.

Parameters:

model_id (str) – The ID of the model to be served.
config_json (dict, optional) – Configuration settings in JSON format.
preferred_port (int, optional) – Preferred port for serving the model.
url (str, optional) – URL for the served model.

api(api_name, input)[source]¶

Call an API with the given name and input.

Parameters:

api_name (str) – Name of the API to call.
input (dict) – Input data for the API.

Returns:

Response from the API.

Return type:

dict

close()[source]¶: Close the Conda environment service.

is_available()[source]¶

Check if the Conda environment service is available.

Returns:: True if the service is available, False otherwise.
Return type:: bool

static is_single_model_without_conda()[source]¶

Check if there is a single model without conda.

Returns:: True if conda is not installed, False otherwise.
Return type:: bool

serve()[source]¶: Serve the model using the Conda environment service.

class ersilia.serve.services.DockerImageService(model_id, config_json=None, preferred_port=None, url=None)[source]¶

Bases: BaseServing

Service class for managing Docker image models.

Parameters:

model_id (str) – The ID of the model to be served.
config_json (dict, optional) – Configuration settings in JSON format.
preferred_port (int, optional) – Preferred port for serving the model.
url (str, optional) – URL for the served model.

api(api_name, input)[source]¶

Call an API with the given name and input.

Parameters:

api_name (str) – Name of the API to call.
input (dict) – Input data for the API.

Returns:

Response from the API.

Return type:

dict

close()[source]¶: Close the Docker image service.

is_available()[source]¶

Check if the Docker image service is available.

Returns:: True if the service is available, False otherwise.
Return type:: bool

serve()[source]¶: Serve the model using the Docker image service.

class ersilia.serve.services.DummyService(model_id, config_json=None, preferred_port=None, url=None)[source]¶

Bases: BaseServing

Dummy service class for testing purposes.

Parameters:

model_id (str) – The ID of the model to be served.
config_json (dict, optional) – Configuration settings in JSON format.
preferred_port (int, optional) – Preferred port for serving the model.
url (str, optional) – URL for the served model.

api(api_name, input)[source]¶

Call an API with the given name and input.

Parameters:

api_name (str) – Name of the API to call.
input (dict) – Input data for the API.

Returns:

Response from the API.

Return type:

dict

close()[source]¶: Close the dummy service.

is_available()[source]¶

Check if the dummy service is available.

Returns:: True if the service is available, False otherwise.
Return type:: bool

serve()[source]¶: Serve the model using the dummy service.

class ersilia.serve.services.HostedService(model_id, config_json=None, preferred_port=None, url=None)[source]¶

Bases: BaseServing

Service class for managing hosted models.

Parameters:

model_id (str) – The ID of the model to be served.
config_json (dict, optional) – Configuration settings in JSON format.
preferred_port (int, optional) – Preferred port for serving the model.
url (str, optional) – URL for the served model.

api(api_name: str, input: dict) → dict[source]¶

Call an API with the given name and input.

Parameters:

api_name (str) – Name of the API to call.
input (dict) – Input data for the API.

Returns:

Response from the API.

Return type:

dict

close()[source]¶: Close the hosted service.

is_available() → bool[source]¶

Check if the hosted service is available.

Returns:: True if the service is available, False otherwise.
Return type:: bool

is_url_available(url)[source]¶

Check if the given URL is available.

Parameters:: url (str) – The URL to check.
Returns:: True if the URL is available, False otherwise.
Return type:: bool

serve()[source]¶: Serve the model using the hosted service.

class ersilia.serve.services.PipInstalledService(model_id, config_json=None, preferred_port=None, url=None)[source]¶

Bases: BaseServing

Service class for managing pip-installed models.

Parameters:

model_id (str) – The ID of the model to be served.
config_json (dict, optional) – Configuration settings in JSON format.
preferred_port (int, optional) – Preferred port for serving the model.
url (str, optional) – URL for the served model.

api(api_name, input)[source]¶

Call an API with the given name and input.

Parameters:

api_name (str) – Name of the API to call.
input (dict) – Input data for the API.

Returns:

Response from the API.

Return type:

dict

close()[source]¶: Close the pip-installed service.

is_available()[source]¶

Check if the pip-installed service is available.

Returns:: True if the service is available, False otherwise.
Return type:: bool

serve()[source]¶: Serve the model using the pip-installed service.

class ersilia.serve.services.PulledDockerImageService(model_id, config_json=None, preferred_port=None, url=None)[source]¶

Bases: BaseServing

Service class for managing Docker image models pulled from a registry.

Parameters:

model_id (str) – The ID of the model to be served.
config_json (dict, optional) – Configuration settings in JSON format.
preferred_port (int, optional) – Preferred port for serving the model.
url (str, optional) – URL for the served model.

api(api_name: str, input: dict) → dict[source]¶

Call an API with the given name and input.

Parameters:

api_name (str) – Name of the API to call.
input (dict) – Input data for the API.

Returns:

Response from the API.

Return type:

dict

close()[source]¶: Close the Docker image service by stopping and removing the container.

is_available() → bool[source]¶

Check if the Docker image service is available.

Returns:: True if the service is available, False otherwise.
Return type:: bool

is_url_available(url)[source]¶

Check if the given URL is available.

Parameters:: url (str) – The URL to check.
Returns:: True if the URL is available, False otherwise.
Return type:: bool

serve()[source]¶: Serve the model using the Docker image service.

class ersilia.serve.services.SystemBundleService(model_id, config_json=None, preferred_port=None, url=None)[source]¶

Bases: _LocalService

Service class for managing system bundle models.

Parameters:

model_id (str) – The ID of the model to be served.
config_json (dict, optional) – Configuration settings in JSON format.
preferred_port (int, optional) – Preferred port for serving the model.
url (str, optional) – URL for the served model.

api(api_name, input)[source]¶

Call an API with the given name and input.

Parameters:

api_name (str) – Name of the API to call.
input (dict) – Input data for the API.

Returns:

Response from the API.

Return type:

dict

close()[source]¶: Close the system bundle service.

is_available()[source]¶

Check if the system bundle service is available.

Returns:: True if the service is available, False otherwise.
Return type:: bool

serve()[source]¶: Serve the model using the system bundle service.

class ersilia.serve.services.VenvEnvironmentService(model_id, config_json=None, preferred_port=None, url=None)[source]¶

Bases: _LocalService

Service class for managing virtual environment models.

Parameters:

model_id (str) – The ID of the model to be served.
config_json (dict, optional) – Configuration settings in JSON format.
preferred_port (int, optional) – Preferred port for serving the model.
url (str, optional) – URL for the served model.

api(api_name, input)[source]¶

Call an API with the given name and input.

Parameters:

api_name (str) – Name of the API to call.
input (dict) – Input data for the API.

Returns:

Response from the API.

Return type:

dict

close()[source]¶: Close the virtual environment service.

is_available()[source]¶

Check if the virtual environment service is available.

Returns:: True if the service is available, False otherwise.
Return type:: bool

serve()[source]¶: Serve the model using the virtual environment service.

ersilia.serve.standard_api module¶

class ersilia.serve.standard_api.StandardCSVRunApi(model_id, url, config_json=None)[source]¶

Bases: ErsiliaBase

Class for running standard CSV API. An API that performs few checks on the input data.

Parameters:

model_id (str) – The ID of the model to be used.
url (str) – The URL of the API.
config_json (dict, optional) – Configuration settings in JSON format.

Examples

async async_serialize_to_json_one_column(input_data)[source]¶

Asynchronously serialize data to JSON with one column.

Parameters:: input_data (str) – The input data file path.
Returns:: The serialized JSON data.
Return type:: list

get_expected_output_header()[source]¶

Calculate the expected output header from the predefined example files or the standard output file.

Returns:: Returns the header which is a list of column names, or None if the header could not be determined.
Return type:: List | None

get_identifier_object_by_input_type()[source]¶

Get the identifier object by input type.

Returns:: The identifier object.
Return type:: object

get_list_from_csv(input_data)[source]¶

Get a list from a CSV file.

Parameters:: input_data (str) – The input data file path.
Returns:: The list of data from the CSV file.
Return type:: list

is_amenable(output_data)[source]¶

Check if the output data is amenable for a standard run.

Parameters:: output_data (str) – The output data to check.
Returns:: True if the output data is amenable for a standard run, False otherwise.
Return type:: bool

is_input_type_standardizable()[source]¶

Check if the input type is standardizable.

Returns:: True if the input type is standardizable, False otherwise.
Return type:: bool

is_output_csv_file(output_data)[source]¶

Check if the output data is a CSV file.

Parameters:: output_data (str) – The output data to check.
Returns:: True if the output data is a CSV file, False otherwise.
Return type:: bool

is_output_type_standardizable()[source]¶

Check if the output type is standardizable.

Returns:: True if the output type is standardizable, False otherwise.
Return type:: bool

parse_smiles_list(input_data)[source]¶

Parse a list of SMILES strings.

Parameters:: input_data (list) – List of SMILES strings.
Returns:: List of dictionaries containing encoded SMILES strings.
Return type:: list

parse_smiles_string(input)[source]¶

Parse a single SMILES string.

Parameters:: input (str) – A SMILES string.
Returns:: List containing a dictionary with the encoded SMILES string.
Return type:: list

post(input, output, output_source='local-only')[source]¶

Post input data to the API and get the output data. And store the output data if needed.

Parameters:

input (str | list) – Input data which can be a file path, a SMILES string, or a list of SMILES strings.
output (str) – Path to the output CSV file.
output_source (OutputSource, optional) – Source of the output data. Default is OutputSource.LOCAL_ONLY.

Returns:

Path to the output CSV file if successful, None otherwise.

Return type:

str | None

serialize_to_csv(input_data, result, output_data)[source]¶

Serialize input data and result to a CSV file.

Parameters:

input_data (list) – List of dictionaries containing input data.
result (list) – List of dictionaries containing result data.
output_data (str) – Path to the output CSV file.

Returns:

Path to the output CSV file.

Return type:

str

serialize_to_json(input_data)[source]¶

Serialize input data to JSON format.

Parameters:: input_data (str | list) – Input data which can be a file path, a SMILES string, or a list of SMILES strings.
Returns:: List of dictionaries containing serialized input data.
Return type:: list

serialize_to_json_one_column(input_data)[source]¶

Serialize data to JSON with one column.

Parameters:: input_data (str) – The input data file path.
Returns:: The serialized JSON data.
Return type:: list

serialize_to_json_three_columns(input_data)[source]¶

Serialize data to JSON with three columns.

Parameters:: input_data (str) – The input data file path.
Returns:: The serialized JSON data.
Return type:: list

serialize_to_json_two_columns(input_data)[source]¶

Serialize data to JSON with two columns.

Parameters:: input_data (str) – The input data file path.
Returns:: The serialized JSON data.
Return type:: list

ersilia.serve package¶

Subpackages¶

Submodules¶

ersilia.serve.api module¶

ersilia.serve.autoservice module¶

ersilia.serve.schema module¶

ersilia.serve.services module¶

ersilia.serve.standard_api module¶

Module contents¶