isaura 2.1.16

A lake of precalculated properties of biomedical entities based on the Ersilia Model Hub

Ersilia’s Precalculation Store

Fast, reproducible access to precalculated model outputs from the Ersilia Model Hub — with a CLI and Python API built for batch workflows.

Quickstart · CLI · Python API · Configuration · Docs · Contributing

---

Why Isaura?

Isaura is Ersilia’s precalculation store: it precomputes and persistently stores model outputs so researchers can retrieve results instantly instead of repeatedly running expensive inference. This delivers a major research speed-up—especially in low-resource settings where compute, bandwidth, or infrastructure are limited—by turning repeated calculations into reusable shared artifacts. To support equitable access, Ersilia also provides free access to public precalculations, making high-value model outputs available even when local compute isn’t.

Isaura provides a structured store for model results so you can:

• ⚡ Skip recomputation by reusing precalculated outputs
• 🧱 Keep artifacts versioned and organized (model → version → bucket/project)
• 📦 Store and retrieve results via S3-compatible object storage (MinIO)
• 🔎 Enable fast retrieval using its fast engine developed on top of duckdb and for ANN uses vector search / indexing components (Milvus + NN service)

If you’re integrating Ersilia with Isaura, you typically (check Ersilia Model Hub for more info here):

1. run once (generate/store), then
2. subsequent runs become fast (retrieve).

---

Architecture (high level)

• 📝 Write: CLI / Python API → MinIO Precomputed outputs are stored as chunked artifacts (e.g., Parquet) under model_id/version, and Isaura updates lightweight registries (index/metadata/bloom) for deduplication and fast lookup.

• 📥 Read(exact): CLI / Python API → DuckDB query on MinIO → results Inputs are matched against the index, then the corresponding rows are fetched directly from the stored chunks.

• ⚡ Read (approx / ANN, optional): CLI / Python API → NN service (+ Milvus) → nearest match → exact fetch from MinIO For unseen inputs, the NN service finds the closest indexed compound(s); Isaura then retrieves the corresponding stored result from MinIO.

See the deep dive: How it works →

---

Quickstart

1) Install dependencies & setup env

We recommend using uv.

git clone https://github.com/ersilia-os/isaura.git
cd isaura
uv sync
source .venv/bin/activate
# if you have conda env
# use uv as below
uv pip install -e . 

2) Start local services (Docker required)

isaura engine --start

Local dashboards

• MinIO Console: http://localhost:9001

Default MinIO credentials (local dev):

Username: minioadmin123
Password: minioadmin1234

---

CLI

Common commands

Write (store outputs)

isaura write -i data/ersilia_output.csv -m eos8a4x -v v2 -pn myproject --access public

Read (retrieve outputs)

isaura read -i data/inputs.csv -m eos8a4x -v v2 -pn myproject -o data/outputs.csv

Copy artifacts to local directory

isaura copy -m eos8a4x -v v1 -pn myproject -o ~/Documents/isaura-backup/

Inspect available entries

isaura inspect -m eos8a4x -v v1 -o reports/available.csv

---

Python API

from isaura.manage import IsauraWriter, IsauraReader

Write the precalculation

writer = IsauraWriter(
    input_csv="data/input.csv",
    model_id="eos8a4x",
    model_version="v1",
    bucket="my-project",
    access="public",
)
writer.write()

Read the stored calculation

reader = IsauraReader(
    model_id="eos8a4x",
    model_version="v1",
    bucket="my-project",
    input_csv="data/query.csv",
    approximate=False,
)
reader.read(output_csv="results.csv")

More examples for CLI and API usage: API and CLI usage

---

Configuration

Isaura reads configuration from environment variables.

Recommended: .env

Create a .env file in the repo root:

MINIO_ENDPOINT=http://127.0.0.1:9000
NNS_ENDPOINT=http://127.0.0.1:8080
DEFAULT_BUCKET_NAME=isaura-public
DEFAULT_PRIVATE_BUCKET_NAME=isaura-private

Cloud credentials (optional)

export MINIO_CLOUD_AK="<access_key>"
export MINIO_CLOUD_SK="<secret_key>"

export MINIO_PRIV_CLOUD_AK="<access_key>"
export MINIO_PRIV_CLOUD_SK="<secret_key>"

You can define those credentials in the .env as well

See the full list: CONFIGURATION

---

MinIO Client (optional but recommended)

Install mc to manage buckets:

brew install minio/stable/mc   # macOS
# or Linux:
curl -O https://dl.min.io/client/mc/release/linux-amd64/mc && chmod +x mc && sudo mv mc /usr/local/bin/

Configure alias:

mc alias set local http://localhost:9000 minioadmin123 minioadmin1234
mc ls local

---

Docs

• 📘 How it works: here
• ⚙️ Configuration: here
• 🧰 CLI and API reference: here
• 🧪 Benchmark: here
• 🩹 Troubleshooting / recovery: here

---

Contributing

PRs are welcome. Please run format + lint before pushing:

uv run ruff format .

If you’re changing CLI behavior, please update here.

---

About the Ersilia Open Source Initiative

The Ersilia Open Source Initiative is a tech-nonprofit organization fueling sustainable research in the Global South. Ersilia's main asset is the Ersilia Model Hub, an open-source repository of AI/ML models for antimicrobial drug discovery.