README.md

---
license: other
license_name: om-lula-community-license-1.3
license_link: LICENSE
pipeline_tag: other
extra_gated_heading: Request access to LULA-2 weights
extra_gated_description: Access requests are reviewed individually by Om Therapeutics.
extra_gated_button_content: Submit request for review
extra_gated_prompt: |
  For testing without downloading model weights, use hosted LULA at https://omtx.ai
  and contact dmc@omtx.ai to request tester Wallet Credits.

  Downloading or using these materials is governed by the Om LULA Community
  License 1.3. Submitting this form does not grant access or any commercial
  rights. Commercial use outside Permitted Om Fulfillment requires a separate
  written Om commercial license.
extra_gated_fields:
  Company or institution: text
  Work email: text
  Intended access type:
    type: select
    options:
      - Non-commercial research or teaching
      - Limited non-production evaluation or benchmarking
      - Commercial discovery or production use
      - Fine-tuning or derivative model development
      - Other
  Target, project, and planned workflow: text
  I have read and agree to the current Om LULA Community License: checkbox
  I understand that approval does not grant commercial rights beyond that license: checkbox
  I understand that commercial use outside Permitted Om Fulfillment requires a separate written Om commercial license: checkbox
tags:
  - biology
  - drug-discovery
  - small-molecule-discovery
  - protein-ligand
  - binding-affinity
  - open-weight
  - lula-2
---

> **License notice.** By downloading, accessing, using, distributing, or
> creating a derivative of LULA-2, you agree to the [Om LULA Community License
> 1.3](LICENSE). LULA-2 is open-weight, not OSI open source. It may be used for
> research, evaluation, benchmarking, teaching, local inference, local
> fine-tuning, and Permitted Om Fulfillment Use. Commercial local/open-weight
> use outside Om Fulfillment, hosted API/SaaS access, resale, paid support or
> deployment, product bundling, and competing model services require a separate
> written Om commercial license. You may not publish, distribute, or make
> available raw or bulk LULA-2 Outputs, including scores, predictions, rankings,
> embeddings, screened molecule lists, or benchmark datasets, unless Om gives
> prior written approval. Public disclosure rights are limited to
> customer-derived experimental data, analyses, conclusions, and reports from
> molecules purchased through Om Fulfillment. For commercial licensing, contact
> dmc@omtx.ai.

# LULA-2

LULA-2 is an Om cross-attention protein-ligand scorer. It takes an amino-acid
protein sequence and ligand SMILES, then returns a probability-like binding
score and within-batch ranks. The local scorer does not require a protein
structure, docking, or folding step.

This repository contains the LULA-2 open-weight checkpoint, model
configuration, inference-window configuration, and a release manifest with byte
counts and SHA256 hashes. It does not bundle third-party pretrained encoders;
the SDK downloads ESM-2 and ChemBERTa from Hugging Face at first use. See
[NOTICE](NOTICE).

## Benchmark Snapshot

![LULA-2 public no-structure benchmark](https://huggingface.co/omtx/lula-2/resolve/main/assets/lula2-public-no-structure-benchmark.png)

On public no-structure protein-ligand benchmark data covering 503 proteins and
14,139 protein-ligand pairs, LULA-2 ranked known binders ahead of non-binders
substantially better than Boltz2.

| Metric | LULA-2 | Boltz2 |
| --- | ---: | ---: |
| Pooled AUROC | 0.819 | 0.543 |
| Pooled AUPRC | 0.900 | 0.735 |
| Pooled BEDROC20 | 0.969 | 0.843 |
| Per-target AUROC wins | 123 | 57 |

The per-target AUROC comparison uses the 190 targets that had both binder and
non-binder examples; 10 additional targets were ties. For this benchmark,
"no-structure" means the selected proteins had no close experimental PDB
sequence match at audit time (<40% sequence identity). This is a ranking
benchmark only. It does not mean LULA-2 identifies a binding site or explains
the binding mechanism, and some ligands in the benchmark also appear in the
training data. Read this as a public ranking benchmark, not a test of entirely
new chemistry.

## Example Workflows

LULA-2 is designed for a simple customer workflow: start from a protein
sequence, score candidate molecules, rank the most promising structures, and
decide what to order or validate next. The examples below show how Om presents
that workflow across benchmarking, validation, target coverage, and model
interpretability.

### Public No-Structure Benchmark

![Public no-structure benchmark summary](https://huggingface.co/omtx/lula-2/resolve/main/assets/examples/public-no-structure-benchmark.png)

A visual summary of the 503-protein benchmark above. The key takeaway is that
LULA-2 can rank likely binders from sequence and SMILES alone, without requiring
a target structure, docking run, or folding step.

### Sequence-To-Validation Example

![Sequence-to-validation example](https://huggingface.co/omtx/lula-2/resolve/main/assets/examples/sequence-to-validation-example.png)

A validation example from an earlier Om model, showing the intended path from
sequence-first predictions to experimentally tested molecules. The same product
loop applies to LULA-2: score molecules, choose a set, order or validate them,
then use the results to improve the next round.

### Target-Family Coverage

![Target-family coverage](https://huggingface.co/omtx/lula-2/resolve/main/assets/examples/target-family-coverage.png)

An example of how Om summarizes performance across protein families. This helps
teams decide where a model is strongest and where additional customer-specific
fine-tuning or validation data may be useful.

### Interpretable Ranking Signals

![Interpretable ranking signals](https://huggingface.co/omtx/lula-2/resolve/main/assets/examples/interpretable-ranking-signals.png)

An example of how LULA attention can be inspected after scoring. These views
can help scientists review model behavior, but they should be treated as
interpretability signals rather than guaranteed binding-site or mechanism
predictions.

## Files

- `model/best.pt` - LULA-2 cross-attention checkpoint.
- `model/model_config.json` - architecture and encoder dimensions.
- `model/inference_config.json` - protein-windowing and tokenizer settings.
- `release_manifest.json` - public checksum manifest verified by the SDK.
- `examples/` - small local scoring and fine-tuning examples.
- `notebooks/lula2_quickstart.ipynb` - notebook quickstart.

## Install And Download

Use `omtx[lula]>=2.0.20`, the first Om SDK release with LULA-2 local scoring
and fine-tuning support.

```bash
pip install "omtx[lula]>=2.0.20"
hf auth login
omtx lula download --model lula2
omtx lula verify --model lula2
```

[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/omtx-ai/omtx/blob/main/examples/notebooks/lula_explicit_smiles.ipynb)

Full workflow cookbooks:
[`LULA Score To Order`](https://github.com/omtx-ai/omtx/blob/main/cookbooks/lula-score-to-order.md),
[`Om Accessible Space To Order`](https://colab.research.google.com/github/omtx-ai/omtx/blob/main/examples/notebooks/lula_om_space_to_order.ipynb), and
[`Explicit SMILES`](https://colab.research.google.com/github/omtx-ai/omtx/blob/main/examples/notebooks/lula_explicit_smiles.ipynb).

To verify a local checkout of this repository without downloading from Hugging
Face:

```bash
omtx lula verify --model-root . --model lula2
```

## Score

```bash
omtx lula score \
  --model lula2 \
  --protein examples/protein.fasta \
  --smiles examples/molecules.smi
```

```python
from pathlib import Path
from omtx.lula import load_model


def read_fasta(path: str) -> str:
    return "".join(
        line.strip()
        for line in Path(path).read_text().splitlines()
        if line and not line.startswith(">")
    )

model = load_model("lula2")
records = model.score(
    protein_sequence=read_fasta("examples/protein.fasta"),
    smiles=["CC(=O)Nc1nnc(s1)S(N)(=O)=O", "CC(=O)OC1=CC=CC=C1C(=O)O"],
)
for row in sorted(records, key=lambda item: item["rank"]):
    print(row["rank"], f"{row['score']:.6f}", row["smiles"])
```

## Common Workflows

Use `smiles=[...]` when you want to score molecules you already have. This is
local open-weight scoring after model and encoder setup.

```python
from omtx.lula import load_model

protein_sequence = "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQANN"
smiles = [
    "CCOc1ccc2nc(S(N)(=O)=O)sc2c1",
    "Cn1ccnc1CCNCc1cn(-c2ccc(F)c(Cl)c2)nn1",
    "CCO",
]

model = load_model("lula2")
scores = model.score(protein_sequence=protein_sequence, smiles=smiles)
```

Use `source="om"` and a Wallet Credit tier when you want Om to return orderable
molecules from Om Accessible Space. This requires an Om API key. For local
open-weight scoring, the SDK fetches the authenticated molecule slice without
sending your protein sequence to Om.

```python
from omtx import OmClient
from omtx.lula import load_model

protein_sequence = "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQANN"

with OmClient(api_key="your-api-key") as client:
    model = load_model("lula2")
    scores = model.score(
        protein_sequence=protein_sequence,
        source="om",
        tier=50,
        n=50000,
        client=client,
    )
```

Only Om Accessible Space rows include `source_metadata` and can be ordered
directly with Wallet Credits:

```python
from uuid import uuid4
from omtx import OmClient

selected = sorted(scores, key=lambda row: row["score"], reverse=True)[:96]

with OmClient(api_key="your-api-key") as client:
    order = client.molecules.order(
        items=selected,
        shipping_address_id="your-shipping-address-id",
        idempotency_key=f"order-round-1-{uuid4()}",
    )
```

### Om Accessible Space Without LULA

Install `omtx>=2.0.23` when using the molecule-only helpers.

You can also fetch Om Accessible Space molecules, score or filter them with your
own tools, and order selected rows through Om:

```python
from omtx import OmClient

with OmClient(api_key="your-api-key") as client:
    pool = client.molecules.accessible_space(
        tier=50,
        n=50000,
        seed=123,
        idempotency_key="target-a-om-space-slice-1",
    )

    # smiles is a plain list[str], one SMILES per molecule.
    smiles = client.molecules.smiles(pool)

    # scores must be a same-length list[float], one score per SMILES.
    scores = score_with_your_model(smiles)

    # with_scores adds your scores back to the orderable Om rows.
    scored_rows = client.molecules.with_scores(pool, scores)

    selected = sorted(scored_rows, key=lambda row: row["score"], reverse=True)[:96]

    order = client.molecules.order(
        items=selected,
        shipping_address_id="your-shipping-address-id",
        idempotency_key="molecule-order-1",
    )
```

The SDK keeps the Om order metadata needed to revalidate fixed Wallet Credit
price and route fulfillment internally. This path still requires an Om API key
and Wallet Credits, but it does not require LULA scoring.

## Fine-Tune With Customer Data

The fine-tuning API is intentionally simple: input base checkpoint plus customer
CSV, output a new checkpoint directory. The CSV must contain exactly the
customer's labeled examples, with these required columns:

```csv
target_id,protein_sequence,smiles,label,split
```

`split` is required. Use `train` for training rows and `test` for the customer
holdout. The SDK rejects train/test duplicate target-protein-SMILES examples and
requires both positive and negative labels in each split.

Default LULA-2 fine-tuning uses 10 epochs, learning rate `1e-5`, batch size 64,
and saves an intermediate checkpoint every epoch plus `final/`. The pretrained
protein and ligand encoders stay frozen. The trainable surface is the LULA-2
adapter, attention-pooling, and scoring-head layer set.

```bash
omtx lula finetune examples/finetune_customer.csv \
  --model lula2 \
  --out lula2-finetuned-ca2

omtx lula score \
  --model lula2 \
  --model-root lula2-finetuned-ca2/final \
  --protein examples/protein.fasta \
  --smiles examples/molecules.smi
```

Programmatic use:

```python
from omtx.lula import finetune_lula

result = finetune_lula(
    "examples/finetune_customer.csv",
    model_id="lula2",
    out="lula2-finetuned-ca2",
)
print(result.final_model_root)
print(result.metrics)
```

## Local Data Behavior

After the weights and third-party encoders are downloaded, local scoring and
fine-tuning run on the user's machine. Protein sequences, SMILES, labels, and
fine-tuned checkpoints are not uploaded by the SDK scoring or fine-tuning
commands.

Hosted Om scoring is a separate product surface.

## Free to Use With Om Fulfillment

You may use LULA-2 locally, including local fine-tuning, to select, prioritize,
order, and test molecules through Om.

If you purchase molecules through Om Fulfillment, you may use the resulting
customer-derived experimental data, assay results, validation data, analyses,
conclusions, and reports internally and commercially for your own discovery
programs, subject to the License and the applicable Om fulfillment, platform, or
enterprise agreement.

You may not resell LULA-2, host it as an API/SaaS, provide LULA-powered services
to third parties, or use LULA-2 as a free internal commercial screening engine
while ordering or testing outside Om. Those uses require a separate Om
commercial license.

You own your targets, compounds, and Customer-Derived Om Fulfillment Data,
subject to the applicable Om fulfillment, platform, or enterprise agreement.
This does not include a right to publish raw or bulk LULA-2 Outputs, scores,
predictions, rankings, embeddings, screened molecule lists, virtual screening
results, or benchmark datasets without Om's prior written approval.

## Score To Order

Use [`LULA Score To Order`](https://github.com/omtx-ai/omtx/blob/main/cookbooks/lula-score-to-order.md)
for hosted LULA-2 Om Accessible Space scoring, local open-weight scoring,
shipping address lookup, and Wallet Credits-funded Molecule Fulfillment orders.

## License

Weights are released under the **Om LULA Community License 1.3**. By downloading,
accessing, using, distributing, or creating a derivative of LULA-2, you agree to
that license. See `LICENSE` for the full terms and `NOTICE` for third-party
components.

Summary (the `LICENSE` file governs):

- **Allowed without a separate paid model license** - non-commercial research,
  evaluation, benchmarking, teaching, security testing, local inference, local
  fine-tuning, non-commercial demos, using LULA-2 to select, prioritize, order,
  test, or generate data through Om, and use or publication of Customer-Derived
  Om Fulfillment Data as allowed by the License and the applicable Om agreement.
- **Output publication restriction** - raw or bulk LULA-2 Outputs, including
  scores, predictions, rankings, embeddings, screened molecule lists, virtual
  screening results, or benchmark datasets, may not be published, distributed, or
  made available without Om's prior written approval.
- **Requires a separate Om commercial license** - commercial use of local/open-
  weight LULA-2 itself outside Om Fulfillment, commercial screening or
  production discovery not fulfilled through Om, self-hosting, monetized hosting,
  paid API/SaaS access, reselling model access, support/deployment, third-party
  services, bundling LULA-2 into a paid product, or building a competing model
  API around Om weights.
- **Commercial licensing contact** - email dmc@omtx.ai.
- **Publication attribution required** - permitted public papers, preprints,
  reports, or presentations using Customer-Derived Om Fulfillment Data must cite
  Om Therapeutics Inc. LULA-2, checkpoint `maxcontext_v2_epoch_3656`, and the
  Hugging Face model page.

## Release Manifest

The SDK verifies every file listed in `release_manifest.json` before loading the
model. The manifest intentionally lists only public-safe files needed for local
inference and fine-tuning.