Skip to content

Python client

The japanfold package on PyPI is a Python API and a command-line tool over the same calls. It needs Python 3.9 or newer and nothing outside the standard library.

pip install japanfold
export JAPANFOLD_API_KEY=jf_live_...      # from https://japanfold.aiand.com/account/token
import japanfold as jf

r = jf.run("boltz2", "complex.yaml", diffusion_samples=5)   # blocks until done
r.path      # this input's files, under the model's own file names
r.metrics   # one dict per ranked output, best first
r.cost      # dollars billed for the job

job = jf.submit("esmfold2", "MKTAYIAKQRQISFVKSHFSRQ")       # returns once admitted
print(job.id)                                              # jf.Job(id).result() later
r = job.result()

for r in jf.map("boltz2", ["a.yaml", "b.yaml"], max_parallel=4):   # in input order
    print(r.error or r.path)

That is the whole API: run, submit, map, Job, Result and Error. The client knows no model: any id japanfold models lists works, and every keyword other than name, out, timeout and max_parallel is that model's parameter, sent as given. The input is a file path, the text itself (FASTA, YAML, a sequence, a PDB/mmCIF, pdb:1ABC) or a dict sent as YAML; a path-shaped string that names no file raises FileNotFoundError instead of being billed.

Results land in ./japanfold/<name>/ (out= changes the parent), where the name is name=, else the input file's stem, else the job id. Running the same call again reads that directory back without a request, and a resubmit after a crash gets the same job back rather than a second bill. map returns a failed or refused input as r.error and carries on; a 401 or 402 raises at once, and leaving the loop early cancels the jobs still running. run and job.result() raise jf.Error. Progress goes to the japanfold logger at INFO.

japanfold run MODEL INPUT --param key=value is the same call from the shell.

Coming from Modal

On Modal you deploy a function and call it. On JapanFold the model is already deployed, so the function becomes a model id and its arguments become the input and keyword parameters:

Modal JapanFold
fold.remote(x) jf.run(model, x, **params)
fold.map(xs) jf.map(model, xs, **params)
call = fold.spawn(x) then call.get() job = jf.submit(model, x) then job.result()
modal.FunctionCall.from_id(id).get() jf.Job(id).result()
the files your function wrote to a volume r.path, under the model's own file names
the dict your function returned r.metrics, one per ranked output

What you no longer write: the image, the weights download and cache, the GPU choice, warm-up and retries. Your own steps around the call, database writes and post-processing, stay as they are. map keeps going past a failed input (r.error) instead of raising and losing the batch.

The command line

The same package installs japanfold. japanfold models lists every model and design protocol, japanfold run MODEL INPUT --param key=value runs any of them, and japanfold -h shows the rest. The commands and exit codes are on the PyPI page.