Python SDK

Use the official `omtx` package to submit diligence and Hub jobs, upload artifacts, 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="550e8400-e29b-41d4-a716-446655440000",
    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="550e8400-e29b-41d4-a716-446655440000",
    n=1000,
    sample_seed=42,
)
nonbinders = client.load_nonbinders(
    protein_uuid="550e8400-e29b-41d4-a716-446655440000",
    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="550e8400-e29b-41d4-a716-446655440000",
)
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.
  • Use client.jobs.history(...) filters when you want separate Hub and Diligence activity views.
  • 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"])