omtx 2.0.0

Python SDK for Om

OMTX Python SDK

Minimal Python client for the OMTX Gateway.

Core scope:

• Submit diligence jobs
• Poll job status/results
• Request subscription-gated shard URLs
• Load entitlement-scoped data into an OmDataFrame (Polars-backed)

Installation

Core SDK:

pip install omtx

Quick Start

from omtx import OmClient

with OmClient() as client:
    print(client.status())

    job = client.diligence.deep_diligence(
        query="CRISPR applications in cancer therapy",
        preset="quick",
    )

    result = client.jobs.wait(
        job["job_id"],
        result_endpoint="/v2/jobs/deep-diligence/{job_id}",
    )
    print(result.get("result", {}).get("total_claims"))

Setup

export OMTX_API_KEY="your-api-key"

The SDK targets https://api.omtx.ai.

For develop/staging testing, override the base URL explicitly:

from omtx import OmClient

with OmClient(
    api_key="your-api-key",
    base_url="https://develop-api.omtx.ai",
) as client:
    print(client.status())

Or with env:

export OMTX_BASE_URL="https://develop-api.omtx.ai"

When a non-production host is used, the SDK emits a warning.

Data Access

One-shot data loading:

data = client.load_data(
    protein_uuid="550e8400-e29b-41d4-a716-446655440000",
    binders=1000,
    non_binders=10000,
)
print(data.shape)
data.show(top_n=24)

Manual shard export (advanced use):

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"]))
print("First binder URL:", urls["binder_urls"][0] if urls["binder_urls"] else None)

Generated proteins available now:

protein_uuids = client.datasets.generated_protein_uuids()
print("Generated protein UUIDs:", protein_uuids[:5])

Module-level convenience:

import omtx as om

data = om.load_data(
    protein_uuid="550e8400-e29b-41d4-a716-446655440000",
    binders=1000,
    non_binders=10000,
)
print(data.shape)

Idempotency

• Every non-GET call gets an idempotency key automatically.
• All diligence POST helpers accept idempotency_key=... for explicit retry control.

Helper Surface

• diligence.deep_diligence(query, preset=None, idempotency_key=None, **kwargs)
• diligence.synthesize_report(gene_key, idempotency_key=None)
• diligence.search(query, idempotency_key=None)
• diligence.gather(query, idempotency_key=None)
• diligence.crawl(url, max_pages=5, idempotency_key=None)
• diligence.list_gene_keys()
• jobs.history(...), jobs.status(job_id), jobs.wait(job_id, ...)
• binders.get_shards(...)
• binders.urls(...)
• load_data(...)
• datasets.catalog()
• datasets.generated_protein_uuids()
• status()
• users.profile()

Route policy:

• /v2/diligence/getTargetDiligenceReport remains an alias route and is not a separate SDK helper.
• /v2/rag/search is intentionally not exposed in the SDK.

Migration

Breaking changes in 2.0.0:

• OMTXClient removed.
• OmClient is now the only supported client class.
• Legacy pricing helpers removed from SDK surface.
• Legacy binder batch-cost helper removed from SDK surface.
• Shard access now resolves latest accessible dataset by protein_uuid.
• client.status() is the primary health helper.
• load_data(...) now returns OmDataFrame with .show(...) convenience rendering.
• Flat shard URL aliases are available as binder_urls / non_binder_urls.
• Core SDK runtime includes polars + rdkit.

Migration mapping (1.x -> 2.x):

• from omtx import OMTXClient -> from omtx import OmClient
• OMTXClient(...) -> OmClient(...)

Breaking changes in 1.0.0:

• binders.get(...) removed from core SDK.
• binders.iter(...) removed from core SDK.
• pandas removed from required dependencies.

Migration mapping (0.x -> 1.x):

• binders.get(...) -> client.load_data(...) or binders.get_shards(...)
• binders.iter(...) -> binders.get_shards(...) + application-level streaming
• pip install omtx (with pandas) -> pip install omtx (with polars + rdkit)

Full details: see MIGRATION.md.

Requirements

• Python >=3.9
• OMTX API key

License

MIT. See LICENSE.