SADIE¶

Algorithmic antibody and TCR sequence annotation tool that performs numbering (IMGT/Kabat/Chothia), region identification, germline gene assignment, and species detection from amino acid sequences.

License: MIT · Molecules: antibody, tcr · Tasks: annotation

Actions: predict · Variants: 1

At a glance¶

Use it when

You need standardized numbering and region annotation as a preprocessing step before feeding antibody sequences to language models (AbLang2, IgBERT, IgT5)
You need to extract CDR sequences from antibody variable domains for clustering, diversity analysis, or CDR-focused model training
You need germline V-gene and J-gene assignment with identity percentages for assessing somatic hypermutation levels or guiding humanization strategies
You are processing a mixed repertoire dataset and need to identify chain types, species of origin, and light chain isotype (kappa vs lambda) for each sequence
You need to parse scFv constructs to identify VH and VL domain boundaries for downstream analysis with paired-chain models
You need consistent positional numbering across antibodies from different sources to enable accurate position-by-position comparison
You are building an automated antibody engineering pipeline and need a reliable annotation step that feeds into structure prediction, embedding, or design tools

Strengths

Combined numbering, region annotation, germline assignment, and species detection in a single API call -- no need to run separate tools for each annotation task
Supports all major antibody numbering schemes (IMGT, Kabat, Chothia) and CDR definitions (IMGT, Kabat, Chothia, AbM, Contact, SCDR) in a single configurable parameter
Broadest chain type coverage: antibody heavy chains (H), kappa (K) and lambda (L) light chains, and all four TCR chain types (alpha, beta, gamma, delta)
scFv domain parsing (scfv=True parameter) automatically identifies and annotates both VH and VL domains within a single-chain construct, essential for CAR-T and bispecific antibody analysis
Extremely lightweight: CPU-only inference with minimal resources (0.125 CPU, 1 GB RAM), making it the most cost-effective model in this catalog for preprocessing
Germline V-gene and J-gene assignment with identity percentages enables somatic hypermutation burden assessment and humanization analysis
HMM-based species detection identifies the organism of origin, useful for classifying sequences from multi-species antibody discovery campaigns

Limitations

Annotation-only tool with no embedding, scoring, or generation capabilities -- produces structured annotations, not numerical representations for ML models
May not distinguish VHH-specific hallmark positions when processing nanobody sequences as H chains, potentially misannotating camelid-specific framework features
Germline gene databases may not be updated to include the latest IMGT reference sets, potentially affecting accuracy for rare or newly discovered germline genes
Software tool without a peer-reviewed publication, which may limit citation in academic contexts and makes independent validation harder to assess
No batch optimization for very large datasets (NGS scale, millions of sequences); each sequence requires a separate API call
Single action (predict) with no customization of output format or selective annotation -- always returns the full annotation set
TCR gamma/delta annotation is supported but less extensively validated than alpha/beta annotation

Reach for something else when

You need numerical embeddings or representations of antibody sequences for ML tasks -- use AbLang2, IgBERT, or IgT5 for language model embeddings
You need to predict 3D antibody structures -- use AbodyBuilder3, ImmuneBuilder, or ImmuneFold for structure prediction
You need sequence generation, restoration, or scoring -- use AbLang2 or IgBERT, which provide generate and log_prob actions
You need to design antibody sequences conditioned on structure -- use AntiFold for structure-based inverse folding
You need developability property predictions -- use DeepViscosity for antibody viscosity or TemBERTure for thermostability
You need gold-standard IMGT numbering for regulatory submissions -- consider IMGT/DomainGapAlign for official IMGT validation
You need to process millions of sequences at NGS scale with minimal latency -- consider local tools like ANARCI or IgBLAST for high-throughput batch processing

API & schema¶

Call an action with POST /api/v1/{slug}/{action} — the request envelope is {"items": [...], "params": {...}} and a success returns {"results": [...]}. See the HTTP API page for the base URL, error shape, and full contract.

`predict`¶

Call it

curl -X POST http://127.0.0.1:8000/api/v1/sadie/predict \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIE"
    }
  ]
}'

Request — SADIEPredictRequest

Field	Type	Required	Constraints	Description
`params`	SADIEPredictRequestParams	no		Optional parameters controlling this action (defaults are used when omitted).
`items`	list[SADIEPredictRequestItem]	yes		Batch of inputs to process in a single request. Up to 8 sequences per request.

Nested types

SADIENumbering

Allowed values: imgt, kabat, chothia

SADIEPredictRequestItem

Field	Type	Required	Constraints	Description
`sequence`	string	yes	len 1–2048	An antibody or TCR sequence in single-letter amino-acid codes.

SADIEPredictRequestParams

Field	Type	Required	Constraints	Description
`region_assign`	SADIERegion	no	default `imgt`	Region definition used to assign CDR and framework boundaries (imgt, kabat, chothia, abm, contact, or scdr).
`scheme`	SADIENumbering	no	default `chothia`	Residue numbering scheme applied to the annotated sequence (imgt, kabat, or chothia).
`scfv`	boolean	no	default `False`	When true, parse the input as a single-chain variable fragment (scFv) containing two linked domains.
`allowed_chain`	list[string]	no	default `['H', 'K', 'L']`	Chain types to consider during annotation (H=heavy, K=kappa, L=lambda, A/B/G/D=TCR chains).

SADIERegion

Allowed values: imgt, kabat, chothia, abm, contact, scdr

Raw JSON Schema

{
  "$defs": {
    "SADIENumbering": {
      "enum": [
        "imgt",
        "kabat",
        "chothia"
      ],
      "title": "SADIENumbering",
      "type": "string"
    },
    "SADIEPredictRequestItem": {
      "additionalProperties": false,
      "description": "Single sequence item for SADIE prediction.",
      "properties": {
        "sequence": {
          "description": "An antibody or TCR sequence in single-letter amino-acid codes.",
          "maxLength": 2048,
          "minLength": 1,
          "title": "Sequence",
          "type": "string"
        }
      },
      "required": [
        "sequence"
      ],
      "title": "SADIEPredictRequestItem",
      "type": "object"
    },
    "SADIEPredictRequestParams": {
      "additionalProperties": false,
      "properties": {
        "region_assign": {
          "$ref": "#/$defs/SADIERegion",
          "default": "imgt",
          "description": "Region definition used to assign CDR and framework boundaries (imgt, kabat, chothia, abm, contact, or scdr)."
        },
        "scheme": {
          "$ref": "#/$defs/SADIENumbering",
          "default": "chothia",
          "description": "Residue numbering scheme applied to the annotated sequence (imgt, kabat, or chothia)."
        },
        "scfv": {
          "default": false,
          "description": "When true, parse the input as a single-chain variable fragment (scFv) containing two linked domains.",
          "title": "Scfv",
          "type": "boolean"
        },
        "allowed_chain": {
          "description": "Chain types to consider during annotation (H=heavy, K=kappa, L=lambda, A/B/G/D=TCR chains).",
          "items": {
            "type": "string"
          },
          "title": "Allowed Chain",
          "type": "array",
          "default": [
            "H",
            "K",
            "L"
          ]
        }
      },
      "title": "SADIEPredictRequestParams",
      "type": "object"
    },
    "SADIERegion": {
      "enum": [
        "imgt",
        "kabat",
        "chothia",
        "abm",
        "contact",
        "scdr"
      ],
      "title": "SADIERegion",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "Batch prediction request for SADIE.",
  "properties": {
    "params": {
      "$ref": "#/$defs/SADIEPredictRequestParams",
      "description": "Optional parameters controlling this action (defaults are used when omitted)."
    },
    "items": {
      "description": "Batch of inputs to process in a single request. Up to 8 sequences per request.",
      "items": {
        "$ref": "#/$defs/SADIEPredictRequestItem"
      },
      "title": "Items",
      "type": "array"
    }
  },
  "required": [
    "items"
  ],
  "title": "SADIEPredictRequest",
  "type": "object"
}

Response — SADIEPredictResponse

Field	Type	Required	Constraints	Description
`results`	list[SADIEPredictResponseResult]	yes		Per-input results, returned in the same order as the request items.

Nested types

SADIEPredictResponseResult

Field	Type	Required	Description
`domain_no`	integer	yes	Zero-based index of this domain within the input sequence (scFv inputs yield multiple domains).
`hmm_species`	string	yes	Species identified by HMM profile matching against the reference database.
`chain_type`	string	yes	Detected chain type: H (heavy), K (kappa), L (lambda), or A/B/G/D (TCR chains).
`e_value`	number	yes	HMM alignment E-value; lower values indicate a more confident domain identification.
`score`	number	yes	HMM alignment bit score; higher values indicate a better match to the reference HMM.
`identity_species`	string	yes	Species assigned by sequence identity comparison against the germline reference database.
`v_gene`	string	yes	Closest germline V-gene assignment (e.g. IGHV3-23*01).
`v_identity`	number	yes	Percent identity of the input sequence to the assigned V-gene.
`j_gene`	string	yes	Closest germline J-gene assignment (e.g. IGHJ4*02).
`j_identity`	number	yes	Percent identity of the input sequence to the assigned J-gene.
`Chain`	string	yes	Chain identifier used for this domain (H, K, L, A, B, G, or D).
`Numbering`	list[integer]	yes	Per-residue position numbers assigned according to the selected numbering scheme.
`Insertion`	list[string]	yes	Per-residue insertion codes paired with the numbering (empty string when no insertion).
`scheme`	string	yes	Numbering scheme applied to this domain (imgt, kabat, or chothia).
`region_definition`	string	yes	Region definition used to assign CDR and framework boundaries.
`fwr1_aa_gaps`	string	yes	Framework 1 (FWR1) amino-acid sequence including alignment gap characters.
`fwr1_aa_no_gaps`	string	yes	Framework 1 (FWR1) amino-acid sequence with alignment gaps removed.
`cdr1_aa_gaps`	string	yes	CDR1 amino-acid sequence including alignment gap characters.
`cdr1_aa_no_gaps`	string	yes	CDR1 amino-acid sequence with alignment gaps removed.
`fwr2_aa_gaps`	string	yes	Framework 2 (FWR2) amino-acid sequence including alignment gap characters.
`fwr2_aa_no_gaps`	string	yes	Framework 2 (FWR2) amino-acid sequence with alignment gaps removed.
`cdr2_aa_gaps`	string	yes	CDR2 amino-acid sequence including alignment gap characters.
`cdr2_aa_no_gaps`	string	yes	CDR2 amino-acid sequence with alignment gaps removed.
`fwr3_aa_gaps`	string	yes	Framework 3 (FWR3) amino-acid sequence including alignment gap characters.
`fwr3_aa_no_gaps`	string	yes	Framework 3 (FWR3) amino-acid sequence with alignment gaps removed.
`cdr3_aa_gaps`	string	yes	CDR3 amino-acid sequence including alignment gap characters.
`cdr3_aa_no_gaps`	string	yes	CDR3 amino-acid sequence with alignment gaps removed.
`fwr4_aa_gaps`	string	yes	Framework 4 (FWR4) amino-acid sequence including alignment gap characters.
`fwr4_aa_no_gaps`	string	yes	Framework 4 (FWR4) amino-acid sequence with alignment gaps removed.
`leader`	string	yes	Residues N-terminal to FWR1 that fall outside the annotated variable domain.
`follow`	string	yes	Residues C-terminal to FWR4 that fall outside the annotated variable domain.

Raw JSON Schema

{
  "$defs": {
    "SADIEPredictResponseResult": {
      "properties": {
        "domain_no": {
          "description": "Zero-based index of this domain within the input sequence (scFv inputs yield multiple domains).",
          "title": "Domain No",
          "type": "integer"
        },
        "hmm_species": {
          "description": "Species identified by HMM profile matching against the reference database.",
          "title": "Hmm Species",
          "type": "string"
        },
        "chain_type": {
          "description": "Detected chain type: H (heavy), K (kappa), L (lambda), or A/B/G/D (TCR chains).",
          "title": "Chain Type",
          "type": "string"
        },
        "e_value": {
          "description": "HMM alignment E-value; lower values indicate a more confident domain identification.",
          "title": "E Value",
          "type": "number"
        },
        "score": {
          "description": "HMM alignment bit score; higher values indicate a better match to the reference HMM.",
          "title": "Score",
          "type": "number"
        },
        "identity_species": {
          "description": "Species assigned by sequence identity comparison against the germline reference database.",
          "title": "Identity Species",
          "type": "string"
        },
        "v_gene": {
          "description": "Closest germline V-gene assignment (e.g. IGHV3-23*01).",
          "title": "V Gene",
          "type": "string"
        },
        "v_identity": {
          "description": "Percent identity of the input sequence to the assigned V-gene.",
          "title": "V Identity",
          "type": "number"
        },
        "j_gene": {
          "description": "Closest germline J-gene assignment (e.g. IGHJ4*02).",
          "title": "J Gene",
          "type": "string"
        },
        "j_identity": {
          "description": "Percent identity of the input sequence to the assigned J-gene.",
          "title": "J Identity",
          "type": "number"
        },
        "Chain": {
          "description": "Chain identifier used for this domain (H, K, L, A, B, G, or D).",
          "title": "Chain",
          "type": "string"
        },
        "Numbering": {
          "description": "Per-residue position numbers assigned according to the selected numbering scheme.",
          "items": {
            "type": "integer"
          },
          "title": "Numbering",
          "type": "array"
        },
        "Insertion": {
          "description": "Per-residue insertion codes paired with the numbering (empty string when no insertion).",
          "items": {
            "type": "string"
          },
          "title": "Insertion",
          "type": "array"
        },
        "scheme": {
          "description": "Numbering scheme applied to this domain (imgt, kabat, or chothia).",
          "title": "Scheme",
          "type": "string"
        },
        "region_definition": {
          "description": "Region definition used to assign CDR and framework boundaries.",
          "title": "Region Definition",
          "type": "string"
        },
        "fwr1_aa_gaps": {
          "description": "Framework 1 (FWR1) amino-acid sequence including alignment gap characters.",
          "title": "Fwr1 Aa Gaps",
          "type": "string"
        },
        "fwr1_aa_no_gaps": {
          "description": "Framework 1 (FWR1) amino-acid sequence with alignment gaps removed.",
          "title": "Fwr1 Aa No Gaps",
          "type": "string"
        },
        "cdr1_aa_gaps": {
          "description": "CDR1 amino-acid sequence including alignment gap characters.",
          "title": "Cdr1 Aa Gaps",
          "type": "string"
        },
        "cdr1_aa_no_gaps": {
          "description": "CDR1 amino-acid sequence with alignment gaps removed.",
          "title": "Cdr1 Aa No Gaps",
          "type": "string"
        },
        "fwr2_aa_gaps": {
          "description": "Framework 2 (FWR2) amino-acid sequence including alignment gap characters.",
          "title": "Fwr2 Aa Gaps",
          "type": "string"
        },
        "fwr2_aa_no_gaps": {
          "description": "Framework 2 (FWR2) amino-acid sequence with alignment gaps removed.",
          "title": "Fwr2 Aa No Gaps",
          "type": "string"
        },
        "cdr2_aa_gaps": {
          "description": "CDR2 amino-acid sequence including alignment gap characters.",
          "title": "Cdr2 Aa Gaps",
          "type": "string"
        },
        "cdr2_aa_no_gaps": {
          "description": "CDR2 amino-acid sequence with alignment gaps removed.",
          "title": "Cdr2 Aa No Gaps",
          "type": "string"
        },
        "fwr3_aa_gaps": {
          "description": "Framework 3 (FWR3) amino-acid sequence including alignment gap characters.",
          "title": "Fwr3 Aa Gaps",
          "type": "string"
        },
        "fwr3_aa_no_gaps": {
          "description": "Framework 3 (FWR3) amino-acid sequence with alignment gaps removed.",
          "title": "Fwr3 Aa No Gaps",
          "type": "string"
        },
        "cdr3_aa_gaps": {
          "description": "CDR3 amino-acid sequence including alignment gap characters.",
          "title": "Cdr3 Aa Gaps",
          "type": "string"
        },
        "cdr3_aa_no_gaps": {
          "description": "CDR3 amino-acid sequence with alignment gaps removed.",
          "title": "Cdr3 Aa No Gaps",
          "type": "string"
        },
        "fwr4_aa_gaps": {
          "description": "Framework 4 (FWR4) amino-acid sequence including alignment gap characters.",
          "title": "Fwr4 Aa Gaps",
          "type": "string"
        },
        "fwr4_aa_no_gaps": {
          "description": "Framework 4 (FWR4) amino-acid sequence with alignment gaps removed.",
          "title": "Fwr4 Aa No Gaps",
          "type": "string"
        },
        "leader": {
          "description": "Residues N-terminal to FWR1 that fall outside the annotated variable domain.",
          "title": "Leader",
          "type": "string"
        },
        "follow": {
          "description": "Residues C-terminal to FWR4 that fall outside the annotated variable domain.",
          "title": "Follow",
          "type": "string"
        }
      },
      "required": [
        "domain_no",
        "hmm_species",
        "chain_type",
        "e_value",
        "score",
        "identity_species",
        "v_gene",
        "v_identity",
        "j_gene",
        "j_identity",
        "Chain",
        "Numbering",
        "Insertion",
        "scheme",
        "region_definition",
        "fwr1_aa_gaps",
        "fwr1_aa_no_gaps",
        "cdr1_aa_gaps",
        "cdr1_aa_no_gaps",
        "fwr2_aa_gaps",
        "fwr2_aa_no_gaps",
        "cdr2_aa_gaps",
        "cdr2_aa_no_gaps",
        "fwr3_aa_gaps",
        "fwr3_aa_no_gaps",
        "cdr3_aa_gaps",
        "cdr3_aa_no_gaps",
        "fwr4_aa_gaps",
        "fwr4_aa_no_gaps",
        "leader",
        "follow"
      ],
      "title": "SADIEPredictResponseResult",
      "type": "object"
    }
  },
  "properties": {
    "results": {
      "description": "Per-input results, returned in the same order as the request items.",
      "items": {
        "$ref": "#/$defs/SADIEPredictResponseResult"
      },
      "title": "Results",
      "type": "array"
    }
  },
  "required": [
    "results"
  ],
  "title": "SADIEPredictResponse",
  "type": "object"
}

Usage¶

One-line summary: Algorithmic antibody and TCR sequence annotation tool that performs numbering (IMGT/Kabat/Chothia), region identification, germline gene assignment, and species detection from amino acid sequences.

Overview¶

SADIE (Sequencing Analysis and Data Library for Immunoinformatics Exploration) is an antibody sequence analysis and annotation tool developed by Willis. Unlike the language models in this catalog, SADIE is an algorithmic tool that uses HMM-based alignment to identify immunoglobulin and TCR domains, assign standardized residue numbering, annotate framework and CDR regions, and identify germline V and J gene segments.

SADIE serves as a critical preprocessing step in antibody engineering pipelines. It supports multiple numbering schemes (IMGT, Kabat, Chothia) and region definitions (IMGT, Kabat, Chothia, AbM, Contact, SCDR), handles antibody heavy chains, kappa and lambda light chains, all four TCR chain types, and single-chain variable fragments (scFv).

Architecture¶

Property	Value
Architecture	Algorithmic (HMM-based alignment)
Method	HMMER-based domain identification and numbering
Input	Amino acid sequences (antibody or TCR)
Max sequence length	2048 residues
Chain support	H, K, L (antibody); A, B, G, D (TCR)
License	MIT

Capabilities & Limitations¶

CAN be used for: - Antibody variable domain numbering (IMGT, Kabat, Chothia schemes) - CDR and framework region identification (6 region definitions) - Germline V-gene and J-gene assignment with identity scores - Species detection (HMM-based and identity-based) - Chain type identification (heavy, kappa, lambda, TCR alpha/beta/gamma/delta) - scFv domain parsing - E-value-based alignment quality assessment

CANNOT be used for: - Sequence embedding (use AbLang2, IgBERT, or IgT5) - Sequence generation or completion (use AbLang2 or IgBERT generate) - Log-probability scoring (use AbLang2 or IgBERT log_prob) - Non-immunoglobulin/non-TCR proteins - 3D structure prediction

Other considerations: - Runs on CPU only with minimal resource requirements - Batch size capped at 8 sequences per request - Processes sequences independently (no batch-level analysis) - Requires Pydantic v1 compatibility (library constraint)

Usage Examples¶

# Predict -- annotate an antibody heavy chain
from models.sadie.schema import (
    SADIEPredictRequest,
    SADIEPredictRequestItem,
    SADIEPredictRequestParams,
)

predict_request = SADIEPredictRequest(
    params=SADIEPredictRequestParams(
        scheme="chothia",
        region_assign="imgt",
        scfv=False,
        allowed_chain=["H", "K", "L"],
    ),
    items=[
        SADIEPredictRequestItem(
            sequence="QVQLVQSGAEVKKPGASVKVSCKASGYTFTSYGISWVRQAPGQGLEWMGWISAYNGNTNYAQKLQGRVTMTTDTSTSTAYMELRSLRSDDTAVYYCARDGYSSGYYGMDVWGQGTTVTVSS",
        ),
    ],
)

# Annotate with IMGT numbering and Kabat region definitions
predict_imgt = SADIEPredictRequest(
    params=SADIEPredictRequestParams(
        scheme="imgt",
        region_assign="kabat",
    ),
    items=[
        SADIEPredictRequestItem(
            sequence="DIQMTQSPSSVSASVGDRVTITCRASQSIGSFLAWYQQKPGKAPKLLIYEASTLKPGVPSRFSGSGSGTDFTLTISSLQPEDFANYYCHQYAAYPWTFGGGTKVEIK",
        ),
    ],
)

# Parse an scFv sequence
predict_scfv = SADIEPredictRequest(
    params=SADIEPredictRequestParams(
        scfv=True,
    ),
    items=[
        SADIEPredictRequestItem(
            sequence="QVQLVQSGAEVKKPGASVKVSCKASGYTFTSYGISWVRQAPGQGLEWMGWISAYNGNTNYAQKLQGRVTMTTDTSTSTAYMELSSLRSEDTAVYYCARDGYSSGYYGMDVWGQGTTVTVSSGGGGSGGGGSGGGGSDIQMTQSPSSVSASVGDRVTITCRASQSIGSFLAWYQQKPGKAPKLLIYEASTLKPGVPSRFSGSGSGTDFTLTISSLQPEDFANYYCHQYAAYPWTFGGGTKVEIK",
        ),
    ],
)

Architecture & training¶

Architecture¶

Model Type & Innovation¶

SADIE (Sequencing Analysis and Data Library for Immunoinformatics Exploration) is an algorithmic antibody sequence analysis tool -- not a neural network model. It performs antibody numbering, domain identification, germline gene assignment, and region annotation using hidden Markov model (HMM) based alignment to reference databases.

The key innovation of SADIE is its unified interface for antibody and TCR sequence annotation, combining multiple numbering schemes (IMGT, Kabat, Chothia) and region definitions (IMGT, Kabat, Chothia, AbM, Contact, SCDR) into a single analysis pipeline. SADIE processes sequences through HMM alignment to identify domains, assign numbering, and extract framework and CDR region boundaries.

Unlike the language models in this catalog (AbLang2, IgBERT, IgT5), SADIE does not produce embeddings or learn representations from data. It applies rule-based numbering schemes and HMM-based gene assignment to annotate sequences with structured metadata.

Algorithm Components¶

Component	Method
Domain identification	HMM alignment (HMMER-based)
Numbering	IMGT, Kabat, or Chothia scheme
Region assignment	IMGT, Kabat, Chothia, AbM, Contact, or SCDR
Germline assignment	V-gene and J-gene identification with identity scores
Species detection	HMM-based species classification
Chain type	Heavy (H), Kappa (K), Lambda (L), TCR chains (A, B, G, D)

Input Processing¶

Property	Details
Input type	Single amino acid sequence per item
Max sequence length	2048 residues
Batch size	8 sequences
Validation	Extended amino acid alphabet
scFv support	Optional (`scfv=True`) for single-chain variable fragment sequences

SADIE can process raw sequences without prior numbering or annotation. It handles both antibody and TCR sequences, identifying the chain type automatically.

Performance & Benchmarks¶

Published Benchmarks¶

SADIE is a sequence analysis tool rather than a predictive model; its accuracy depends on the quality of the underlying HMM profiles and reference databases.

Key characteristics: - Domain identification relies on HMMER E-values; high E-values indicate poor matches - Germline assignment accuracy depends on the completeness of the reference germline database - Numbering accuracy follows the definitions of each scheme exactly

BioLM Verification Results¶

The BioLM implementation uses the sadie-antibody PyPI package (v1.0.6). Numerical verification is performed against golden reference outputs:

Metric	Threshold	Status
Relative tolerance	1e-5	PASS

Tests cover the predict action with default parameters.

Comparison to Alternatives¶

Tool	Type	Key Advantage	Key Disadvantage
SADIE (this)	Annotation tool	Unified interface, multiple schemes	Python library dependency
ANARCI	Numbering tool	Widely adopted, standalone	Numbering only, no germline assignment
IMGT/DomainGapAlign	Web tool	Gold standard for IMGT numbering	Web-based, not programmatic
AbNum	Numbering tool	Fast, standalone	Limited to numbering
IgBLAST	Alignment tool	NCBI-backed, comprehensive	Requires BLAST installation, more complex output

Strengths & Limitations¶

Pros¶

Multiple numbering schemes in a single tool (IMGT, Kabat, Chothia)
Multiple region definitions (IMGT, Kabat, Chothia, AbM, Contact, SCDR)
Germline V-gene and J-gene identification with identity scores
Species and chain type detection
TCR support (alpha, beta, gamma, delta chains)
scFv support for single-chain variable fragments
CPU-only, minimal resource requirements (0.125 cores, 1 GB memory)
MIT licensed

Cons¶

Not a predictive model -- no embeddings, no generation, no scoring
Depends on HMM reference databases (may not cover all species or synthetic sequences)
Single sequence processing (no batch parallelization within SADIE)
Requires Pydantic v1 compatibility (SADIE library constraint)
Cannot handle non-antibody/non-TCR proteins

Known Failure Modes¶

Non-immunoglobulin sequences: SADIE expects antibody or TCR sequences; other proteins will fail or produce high E-values
Highly engineered sequences: Synthetic antibodies with many non-germline mutations may receive poor germline assignments
Incomplete variable domains: Truncated sequences missing framework regions may fail domain identification
Novel species: Sequences from species not in the reference database will receive approximate species assignments

Implementation Details¶

Inference Pipeline¶

Request
  |-- 1. Validate sequences (alphabet, length)
  |-- 2. Parse parameters (scheme, region_assign, scfv, allowed_chain)
  |-- 3. For each sequence:
  |     |-- Create Renumbering instance with specified scheme/region
  |     |-- Run HMM alignment via run_single()
  |     |-- Extract domain, numbering, germline, and region annotations
  |     |-- Convert to SADIEPredictResponseResult
  |-- 4. Return SADIEPredictResponse

Memory & Compute Profile¶

Property	Value
GPU	None (CPU only)
Memory	1 GB
CPU	0.125 cores
Batch size	8

SADIE is the most lightweight model/tool in this catalog, requiring minimal compute resources.

Determinism & Reproducibility¶

SADIE is fully deterministic -- the same input always produces the same output. HMM alignment scores are computed analytically, not stochastically.

Caching Behavior¶

Response caching is handled outside the model container. The cache key is determined by the request payload (sequence, scheme, region, scfv, allowed_chain).

Versions & Changelog¶

Version	Date	Changes
v1	2025-01-30	Initial implementation with predict action

Biology¶

Molecule Coverage¶

Primary Molecule Type(s)¶

SADIE is designed for antibody and T-cell receptor (TCR) sequence annotation. It processes amino acid sequences and identifies immunoglobulin/TCR domains, assigns numbering according to standard schemes, and annotates framework and complementarity-determining regions.

SADIE handles the following chain types:

Heavy chains (H): Full or partial variable domain sequences. SADIE identifies FWR1-4 and CDR1-3 boundaries, assigns germline V and J genes, and provides numbering.
Kappa light chains (K): Variable domain annotation with kappa-specific germline assignment.
Lambda light chains (L): Variable domain annotation with lambda-specific germline assignment.
TCR alpha chains (A): T-cell receptor alpha chain annotation.
TCR beta chains (B): T-cell receptor beta chain annotation.
TCR gamma chains (G): T-cell receptor gamma chain annotation.
TCR delta chains (D): T-cell receptor delta chain annotation.

Cross-Applicability¶

Molecule Type	Applicability	Evidence	Caveats
Antibody heavy chains	High	Primary use case	Supports H chain fully
Antibody light chains (kappa/lambda)	High	Primary use case	Supports K and L chains
TCR chains (alpha/beta/gamma/delta)	High	Supported via `allowed_chain` parameter	TCR-specific HMM profiles
Nanobodies (VHH)	Moderate	Processed as H chains	May not distinguish VHH-specific hallmark positions
scFv sequences	High	Supported via `scfv=True` parameter	Both VH and VL domains identified in a single sequence
General proteins	Not applicable	Annotation tool for immunoglobulins/TCRs only	Will fail or produce meaningless results

Biological Problems Addressed¶

Antibody Sequence Numbering¶

Problem: Antibody variable domain sequences vary in length, particularly in CDR loops. Comparing sequences across different antibodies requires a consistent numbering system that aligns corresponding positions. Multiple numbering schemes exist (IMGT, Kabat, Chothia), each with different conventions, and researchers need to convert between them.

How SADIE helps: The predict action assigns positional numbers to each residue according to the selected numbering scheme (IMGT, Kabat, or Chothia). The output includes both the numbering and insertion codes, enabling precise position-by-position comparison across antibodies.

Biological meaning: Numbered positions correspond to structurally equivalent locations across antibodies. For example, IMGT position 104 is always the conserved cysteine forming the intra-domain disulfide bond, regardless of the specific antibody sequence. This structural correspondence is the foundation for comparative antibody analysis.

Region Identification¶

Problem: Identifying framework regions (FWR1-4) and complementarity-determining regions (CDR1-3) is essential for antibody engineering. CDR definitions vary across schemes -- IMGT, Kabat, Chothia, AbM, Contact, and SCDR all define different boundaries for the CDR loops. Manually applying these definitions is error-prone.

How SADIE helps: The predict action outputs the amino acid sequences of each region (FWR1, CDR1, FWR2, CDR2, FWR3, CDR3, FWR4) both with gaps (aligned to the numbering scheme) and without gaps (raw sequence). The region_assign parameter selects which CDR definition to use.

Biological meaning: CDR loops are the primary determinants of antigen binding specificity. Different CDR definitions capture different structural boundaries -- Chothia defines CDRs based on canonical loop structures, Kabat defines them based on sequence variability, IMGT uses a standardized system based on the IMGT unique numbering, AbM is a hybrid approach, and Contact defines CDRs based on antigen contact analysis. The choice of definition affects downstream engineering decisions.

Germline Gene Assignment¶

Problem: Determining which germline V and J gene segments encode an antibody variable domain is critical for understanding the antibody's developmental origin, assessing somatic hypermutation burden, and guiding humanization efforts.

How SADIE helps: The predict action identifies the closest V-gene and J-gene matches along with identity percentages (v_identity, j_identity). It also reports the species of origin (hmm_species, identity_species) and alignment quality metrics (e_value, score).

Biological meaning: The V-gene identity percentage indicates how much somatic hypermutation has occurred relative to the germline. High V-gene identity (>95%) suggests a naive or minimally matured antibody, while lower identity (80-90%) indicates extensive affinity maturation. J-gene assignment helps define the junction region at the CDR3 boundary.

scFv Domain Parsing¶

Problem: Single-chain variable fragments (scFvs) contain both VH and VL domains connected by a peptide linker. Identifying the boundaries of each domain and parsing them separately is necessary for downstream analysis.

How SADIE helps: When scfv=True is set, SADIE identifies both VH and VL domains within a single input sequence, annotating each domain independently.

Biological meaning: scFv constructs are widely used in therapeutic antibody formats (e.g., CAR-T cells, bispecific antibodies). Automated domain parsing enables high-throughput analysis of scFv libraries.

Applied Use Cases¶

SADIE is used as a preprocessing step in antibody engineering pipelines:

Antibody repertoire analysis: Number and annotate thousands of sequences from NGS data for downstream statistical analysis (published)
Humanization assessment: Compare germline gene assignments and mutation patterns between species (published)
CDR extraction: Extract CDR sequences for clustering, diversity analysis, or input to CDR-focused models (published)
Quality control: Validate antibody sequences and identify truncated or mis-annotated sequences (published)
Multi-model pipeline preprocessing: Annotate sequences before passing to AbLang2, IgBERT, or IgT5 for embedding (anticipated)

Complementary Models¶

SADIE serves as a preprocessing tool that feeds into other models in this catalog:

AbLang2: Use SADIE to extract and number variable domains, then AbLang2 for embedding and scoring
IgBERT/IgT5: Use SADIE for annotation, then IgBERT/IgT5 for embedding
Nanobodies / VHH: Use SADIE to identify VHH domains, then the unpaired IgBERT or IgT5 variant for embedding

Typical multi-model workflows: 1. Use SADIE predict to annotate and number sequences 2. Use germline assignment and CDR extraction for quality filtering 3. Feed annotated variable domains into embedding models (AbLang2, IgBERT, IgT5) 4. Use embedding models for downstream analysis (clustering, scoring, design)

Alternative Tools¶

Alternative	Advantage Over SADIE	Disadvantage vs SADIE
ANARCI	Widely adopted, standalone C implementation	Numbering only, no germline assignment, no region parsing
IMGT/DomainGapAlign	Gold standard IMGT numbering	Web-based, not programmatically accessible at scale
IgBLAST	NCBI-backed, comprehensive alignment	Complex output, requires local BLAST installation
AbNumber	Fast numbering	Limited to numbering, fewer scheme options

When to choose SADIE: Use SADIE when you need combined numbering, region annotation, germline assignment, and species detection in a single API call, especially as part of an automated pipeline.

When to choose alternatives: Consider ANARCI for standalone numbering in local environments; consider IMGT/DomainGapAlign for gold-standard IMGT validation; consider IgBLAST for comprehensive alignment analysis.

Biological Background¶

The adaptive immune system generates an enormous diversity of antigen receptors -- antibodies (immunoglobulins) and T-cell receptors (TCRs) -- to recognize and respond to pathogens. Each receptor molecule contains variable domains that determine binding specificity.

Antibody structure: Antibody variable domains consist of a conserved beta-sheet framework supporting hypervariable loops (CDRs). The framework provides structural stability, while the CDRs form the antigen-binding surface. Residue positions within the variable domain are structurally conserved across different antibodies, enabling standardized numbering systems.

Numbering schemes: Several numbering systems have been developed to provide consistent position labels across antibodies: - IMGT: International ImMunoGeneTics numbering (Lefranc, 1999). Positions 1-128 for variable domains, with standardized gap positions. The most systematic and species-independent scheme. - Kabat: Based on sequence variability analysis (Wu & Kabat, 1970). Historically the most widely used scheme, with CDR definitions based on sequence hypervariability. - Chothia: Based on structural loop definitions (Chothia & Lesk, 1987). CDR boundaries correspond to canonical loop structures observed in crystal structures. - AbM (Oxford Molecular): A hybrid combining Kabat and Chothia CDR definitions. - Contact: Based on crystal structure analysis of antigen contacts (MacCallum et al., 1996). - SCDR: Standardized CDR definition.

V(D)J recombination and germline genes: Antibody variable domains are encoded by rearranged germline gene segments. The heavy chain uses V (variable), D (diversity), and J (joining) gene segments; the light chain uses V and J segments. Identifying these germline genes is essential for understanding antibody development and engineering.

Key terminology: - Numbering scheme: A system for assigning consistent position labels to residues in antibody variable domains. - CDR (Complementarity-Determining Region): Hypervariable loops that contact the antigen. Three per chain (CDR1, CDR2, CDR3). - Framework region (FWR): Conserved beta-sheet regions flanking the CDRs. Four per chain (FWR1, FWR2, FWR3, FWR4). - Germline gene: The inherited, un-rearranged gene segment encoding a portion of the variable domain. - E-value: Statistical measure of alignment quality from HMM search; lower values indicate better matches. - scFv (single-chain variable fragment): An antibody format where VH and VL are connected by a peptide linker.

Sources & license¶

License: MIT (text)

Papers

SADIE: Sequencing Analysis and Data library for Immunoinformatics Exploration — Software tool — no peer-reviewed paper published. Available via GitHub and PyPI.

Source repositories

github: https://github.com/jwillis0720/sadie
pypi: https://pypi.org/project/sadie-antibody/

Cite

@software{willis2022sadie,
  title={SADIE: Sequencing Analysis and Data Library for Immunoinformatics Exploration},
  author={Willis, Jordan R and Sincomb, Troy M and Kibet, Caleb K},
  year={2022},
  url={https://github.com/jwillis0720/sadie}
}

SADIE¶

At a glance¶

API & schema¶

predict¶

Usage¶

Overview¶

Architecture¶

Capabilities & Limitations¶

Usage Examples¶

Architecture & training¶

Architecture¶

Model Type & Innovation¶

Algorithm Components¶

Input Processing¶

Performance & Benchmarks¶

Published Benchmarks¶

BioLM Verification Results¶

Comparison to Alternatives¶

Strengths & Limitations¶

Pros¶

Cons¶

Known Failure Modes¶

Implementation Details¶

Inference Pipeline¶

Memory & Compute Profile¶

Determinism & Reproducibility¶

Caching Behavior¶

Versions & Changelog¶

Biology¶

Molecule Coverage¶

Primary Molecule Type(s)¶

Cross-Applicability¶

Biological Problems Addressed¶

Antibody Sequence Numbering¶

Region Identification¶

Germline Gene Assignment¶

scFv Domain Parsing¶

Applied Use Cases¶

Related Models¶

Complementary Models¶

Alternative Tools¶

Biological Background¶

Sources & license¶

`predict`¶