Python SDK

Use the official `omtx` package to submit diligence and Hub jobs, upload artifacts, request signed artifact URLs, and request shard access from Python.

Install

pipBash
pip install omtx
Quick startPython
from omtx import OmClient

client = OmClient(api_key="YOUR_API_KEY")

profile = client.users.profile()
print("Available Wallet Credits (cents):", profile["available_credits"])

health = client.status()
print("API version:", health["version"])

catalog = client.datasets.catalog()
print("Public datasets available:", catalog["catalog"]["count"])

gene_keys = client.diligence.list_gene_keys()
print("Sample gene keys:", [item["gene_key"] for item in gene_keys["items"][:5]])
Full SDK Tutorial

Data access helpers

Combined loading (recommended for training sets)Python
loaded = client.load_data(
    protein_uuid="0d64fb6a-8a66-50ad-82b6-fabee8bb1516",
    binders=50000,
    nonbinder_multiplier=5,  # default
    # nonbinders=200000,      # optional explicit override
    sample_seed=42,
)
binders = loaded["binders"]
nonbinders = loaded["nonbinders"]
print("Rows loaded:", len(binders), len(nonbinders))
binders.show(top_n=24)  # defaults: smiles + binding_score
Separate pool loading (explicit control)Python
binders = client.load_binders(
    protein_uuid="0d64fb6a-8a66-50ad-82b6-fabee8bb1516",
    n=1000,
    sample_seed=42,
)
nonbinders = client.load_nonbinders(
    protein_uuid="0d64fb6a-8a66-50ad-82b6-fabee8bb1516",
    n=10000,
    sample_seed=42,
)
# Omit n (or set n=None) to load the full pool.
print("Rows loaded:", len(binders), len(nonbinders))
binders.show(top_n=24)  # defaults: smiles + binding_score
Manual shard export (advanced)Python
urls = client.binders.urls(
    protein_uuid="0d64fb6a-8a66-50ad-82b6-fabee8bb1516",
)
print("Binder shard URLs:", len(urls["binder_urls"]))
print("Non-binder shard URLs:", len(urls["non_binder_urls"]))

Diligence jobs

Submit and waitPython
job = client.diligence.deep_diligence(
    query="BRAF clinical inhibitor landscape",
    preset="quick",
)

result = client.jobs.wait(
    job_id=job["job_id"],
    result_endpoint="/v2/jobs/deep-diligence/{job_id}",
    poll_interval=5,
    timeout=1800,
)

print("Claims:", result["result"]["total_claims"])

SDK Notes

  • Idempotency keys are generated automatically for POST and PUT calls. Diligence helpers also accept idempotency_key= when you want to reuse a specific key.
  • Use client.jobs.wait() for asynchronous diligence calls that return job_id.
  • Diligence wrappers include search, gather, and crawl in addition to deep_diligence/synthesize_report.
  • client.hub.submit(...) lets you start any active public Hub model from the SDK.
  • Upload files with client.artifacts.upload(...) before starting Hub workflows that use uploaded structures.
  • For larger uploaded files, use client.artifacts.upload_via_signed_url(...).
  • For large result files, use client.jobs.get_artifact_url(...) instead of inlining artifact bytes.
  • Use client.jobs.history(limit=...) and cursor to page through recent jobs chronologically.
  • client.status() is the primary health helper.
  • load_data(...) loads binders and non-binders in one call (binders required, non-binders default to 5x multiplier).
  • load_binders(...) and load_nonbinders(...) are the primary dataframe loaders for separate training pools.
  • If n is omitted (or n=None), loaders pull the full pool; sampling occurs only when n is set.
  • OmData.show(...) uses smiles and binding_score by default.
  • For selectivity ranking, pass sort_by="selectivity_score".
  • OmData.show(...) displays inline in notebooks and returns None after successful display to avoid duplicate rendering.
  • binders.urls(...) returns flat binder_urls / non_binder_urls lists for quick iteration.
  • Use the client as a context manager to close sessions automatically.

Hub jobs and artifacts

Hub launch from uploaded structurePython
artifact = client.artifacts.upload("target.pdb")

job = client.hub.diffdock(
    protein_artifact_id=artifact["artifact_id"],
    ligand_smiles="CCO",
    idempotency_key="diffdock-demo-20260316",
)

status = client.jobs.wait(job["job_id"], poll_interval=5, timeout=1800)
print(status["job_type"], status["status"])
Large artifact flow via signed URLsPython
artifact = client.artifacts.upload_via_signed_url("target.cif")

job = client.hub.rfd3(
    pdb_artifact_id=artifact["artifact_id"],
    design_mode="monomer",
    contig="120",
    idempotency_key="rfd3-demo-20260331",
)

url_info = client.jobs.get_artifact_url(
    job["job_id"],
    "outputs/results.json",
)
print(url_info["download_url"])