---
license: mit
library_name: DecoderTCR
tags:
  - biology
  - protein
  - t-cell-receptor
  - peptide-mhc
---

# DecoderTCR

DecoderTCR scores TCR and peptide-MHC sequence complexes and designs peptide candidates. This private staging repository contains six exact ESM-C model artifacts and two gene-input datasets for use with the DecoderTCR 1.5.0 Python package.

## Models

| Exact model ID | Size | Sequence convention |
|---|---:|---|
| `decodertcr@1.5.0:300M` | 300M | V2 |
| `decodertcr@1.5.0:600M` | 600M | V2 |
| `decodertcr@1.5.0:6B` | 6B | V2 |
| `decodertcr@0.3.0:300M` | 300M | V1 |
| `decodertcr@0.3.0:600M` | 600M | V1 |
| `decodertcr@0.3.0:6B` | 6B | V1 |

Use exact IDs. There is no implicit model or short alias. See the [V2 manifest](registry/releases/decodertcr/1.5.0/manifest.json) and [V1 manifest](registry/releases/decodertcr/0.3.0/manifest.json) for artifact identities and member metadata.

## Install and access

Use Python 3.12 and the accompanying DecoderTCR 1.5.0 source checkout. From that checkout, install the locked runtime dependencies:

```bash
uv sync --locked --no-dev
```

Authenticate with a Hugging Face account that can read this private repository. Use the Hugging Face CLI login flow or provide `HF_TOKEN` securely. Do not store a token in the checkout.

## Basic use

Load one model and reuse the returned `LoadedModel`. The explicit registry URI selects this repository without a local mirror.

```python
import DecoderTCR as dt

registry = "hf://Decoder-CHI/DecoderTCR-staging/registry"
model_id = "decodertcr@1.5.0:300M"

loaded = dt.load(model_id, device="cuda", registry=registry)
rows = dt.dataset("demo-gene-pairs@1.0.0", registry=registry)

scores = loaded.score(rows.iloc[:3])

context = rows.iloc[0]
profile = dt.peptide_profile(context, 9, model=loaded)
candidates = dt.design_peptides(
    context,
    9,
    model=loaded,
    n=10,
    seed=42,
)
```

`dt.models(registry=registry)` and `dt.datasets(registry=registry)` list available entries without downloading model weights. Gene preparation follows the selected model's V1 or V2 sequence convention.

## Datasets

These datasets are evaluation or usage inputs. They are not identified as model training datasets.

| Exact dataset ID | Rows | Purpose |
|---|---:|---|
| `demo-gene-pairs@1.0.0` | 30 | Small gene-input example |
| `immrep23-public-inputs@1.0.0` | 3,484 | IMMREP23 evaluation inputs |

See the [demo manifest](registry/datasets/demo-gene-pairs@1.0.0/manifest.json), [demo CSV](registry/datasets/demo-gene-pairs@1.0.0/data.csv), [IMMREP23 manifest](registry/datasets/immrep23-public-inputs@1.0.0/manifest.json), and [IMMREP23 CSV](registry/datasets/immrep23-public-inputs@1.0.0/data.csv).

## Interpretation and limitations

DecoderTCR reports peptide pseudo-log-likelihood scores. Higher values are more model-favored for the supplied complex, but they are not calibrated binding probabilities. Scoring masks the complete peptide simultaneously and averages true-residue log probabilities over the full model vocabulary. Peptide profiles normalize probabilities over the standard 20 amino acids.

The package supports model-aware human reconstruction, explicit class II pairs, and V2 mouse reconstruction. Reconstruction support defines sequence preparation. It does not establish predictive validation for mouse complexes or the added human class II pairs.

Use these models for research scoring, ranking, feature analysis, and candidate generation. They are not clinical models and should not be used for diagnosis, treatment decisions, or patient risk assessment. No benchmark result or training-corpus claim is provided by this repository.

## License and data terms

Each of the six model members includes MIT license text in its release manifest. That license applies to the corresponding model artifact. Dataset records, benchmark inputs, and reconstruction references retain their own attribution and usage terms. The model license does not relicense those materials.