Installation · Usage · Code Quality · API Documentation · Output Orientation · For Developers · License
Ersilia-Pack is a FastAPI-based package designed to seamlessly serve your Ersilia model repository. It provides a comprehensive suite of APIs to monitor, execute, and manage model jobs, alongside detailed metadata support.
Enhanced caching control via cache_mode:
-
The /run endpoint now accepts a new cache_mode parameter (alongside fetch_cache, save_cache, and cache_only) so you can fine-tune exactly how results are saved to Redis, fetched from Redis, or forced through compute-only logic. This makes it easy to switch between full caching, fetch-only, save-only, or bypassing the cache altogether without touching your client code.
-
Resilient Redis operations with safe fallbacks All Redis calls (
HMGET,HSET,GET,SETEX, pipeline expirations) are now wrapped in try/except blocks that log warnings on failure, keep the configured REDIS_EXPIRATION, and silently fall back to computing.
Install the package directly from GitHub:
pip install git+https://github.com/ersilia-os/ersilia-pack.gitValidate your model repository structure by running:
ersilia_model_lint --repo_path $REPO_PATHPack your model repository—supporting pip, conda, or both—using:
ersilia_model_pack --repo_path $REPO_PATH --bundles_repo_path $BUNDLE_PATHFor models with conda dependencies, specify a particular conda environment:
ersilia_model_pack --repo_path $REPO_PATH --bundles_repo_path $BUNDLE_PATH --conda_env_name $CONDA_ENVAfter packaging, serve the application with:
ersilia_model_serve --bundle_path $BUNDLE_PATH --port $PORTTo keep our codebase clean and consistent, we use pre-commit hooks alongside Ruff as our linter/formatter.
Make sure you have Python 3.8+ and pip installed, then:
pip install pre-commit ruff| Category | Endpoint | Path | Description |
|---|---|---|---|
| Core | Swagger UI | /docs |
Interactive API interface with custom styling and title. |
| ReDoc | /redoc |
Alternative documentation view with a comprehensive layout. | |
| Health Check | /healthz |
Returns system status (CPU, memory, circuit breaker stats). | |
| Base URL | / |
Displays basic info (model identifier and slug). | |
| Job Management | Submit Job | /job/submit |
Accepts input data, queues an async job, returns a unique job ID. |
| Job Status | /job/status/{job_id} |
Check the current status of a job (pending, completed, failed). | |
| Job Result | /job/result/{job_id} |
Retrieve output of a completed job; if unfinished, returns current status only. | |
| Reset Jobs | /jobs/reset |
Clears all job records (should be secured in production). | |
| Metadata | Complete Metadata | /card |
Retrieves all model metadata (name, title, description). |
| Specific Metadata Field | /card/{field} |
Fetches a specific metadata field; errors if field not found. | |
| Run | Example Input | /run/example/input |
Provides sample input data for testing. |
| Example Output | /run/example/output |
Returns sample output data to demonstrate expected responses. | |
| Input Columns | /run/columns/input |
Lists the input data headers. | |
| Output Columns | /run/columns/output |
Lists the output data headers. | |
| Execute Job (sync) | /run |
Processes input data synchronously and returns computed results. | |
| Model Information | Model Status | /models/status |
Provides details on model version, runtime environment, and worker statuses. |
API responses are always provided in JSON format, following the Pandas DataFrame orient syntax. Supported output orientations include:
- records: Each row is output as a dictionary.
- split: Returns separate lists for index, columns, and data.
- columns: Outputs a dictionary with column names as keys and lists of values as entries.
- index: Outputs a dictionary with indices mapping to corresponding row data.
- values: Outputs a list of lists, with each sublist representing a row.
For more details, please refer to the Pandas to_json documentation.
| Feature | Description |
|---|---|
| Interactive API Documentation | Offers both Swagger UI and ReDoc interfaces with custom styling and titles, ensuring a user-friendly API exploration experience. |
| Asynchronous Job Processing | Supports submission and execution of jobs asynchronously. Users receive a unique job ID and can track job status and results, with robust error handling. |
| Real-time Health Monitoring | Monitors system performance—including CPU and memory usage and circuit breaker metrics—to ensure reliable service operations. |
| Flexible Metadata Access | Provides endpoints to retrieve complete metadata or specific metadata fields, offering a clear view of model details such as name, title, and description. |
| Comprehensive Run Endpoints | Facilitates example data retrieval for both input and output, along with dynamic job execution, enabling easy testing and validation of model predictions. |
| Multiple Output Formats | Supports various output orientations (records, split, columns, index, and values) based on Pandas DataFrame to_json syntax, allowing flexible JSON responses. |
-
Input Handling:
Currently, only"Compound"and"Single"input types are supported. To accommodate additional types, update the schemas within thetemplates/input_schemasdirectory. -
Best Practices:
Follow standard FastAPI conventions. Ensure that any new features are well-documented and thoroughly tested. -
Extensibility:
The modular design of Ersilia-Pack allows you to easily integrate new endpoints and custom logic to extend functionality as needed.
This project is licensed under the GNU General Public License v3.0.