Decoder-CHI/DecoderTCR-staging

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 and V1 manifest 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:

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.

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, demo CSV, IMMREP23 manifest, and IMMREP23 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.