Prokaryotic Immunity Term Prediction

SCOPING PIPELINE

Prokaryotic Immunity Term Prediction

Bottom line: Scoped, with a first code unit built and nothing yet connected
to it. Anti-phage defense predictors report broad family calls such as
CRISPR-Cas, CBASS or Thoeris, and a family label alone is not a safe basis
for a precise GO annotation. In April 2026 we added a small translation layer
(src/ai_gene_review/defense_go/) that gives each defense family a stable ID,
resolves label aliases, and records per family whether a GO term can be
suggested automatically. The registry covers five families: CRISPR-Cas maps to
GO:0099048 and restriction-modification to GO:0009307, while abortive infection,
CBASS and Thoeris are deliberately review-only because the families are too
mechanistically diverse for one term. The layer has 5 targeted tests, but no
predictor or export code calls it yet, and wiring it into the prediction
pipeline, writing PredictionReview output, and adding more families are all
still to do.

Overview

This project is about increasing automation for predicting precise biology-first GO terms for
prokaryotic immunity systems.

The immediate unit here does not try to solve end-to-end annotation. It adds the missing translation
layer between broad defense-system calls and review-ready term suggestions. In practice, the current
source being translated is family-level output from the prokaryotic immunity predictor, which emits
calls such as CRISPR-Cas, restriction-modification, CBASS, Thoeris, and abortive infection.

The goal is to make those outputs usable for precise review by:

This keeps immunity-term prediction centered on the biology while still allowing multiple upstream
tools or predictors to plug into the same GO policy layer later.

Why This Exists

The current predictor can often say that something belongs to a broad defense family, but broad
family labels are not yet a good direct input to GO curation.

There are three different problems mixed together if we do not separate the layers:

  1. Family recognition
  2. Stable immunity-system identity and synonym handling
  3. Precise term-prediction policy

Those should not live as ad hoc conditionals inside one particular predictor or one particular
database parser.

This project creates an extraction-ready translation layer that owns the second and third layers.

Initial Stable Family IDs

The first registry version includes:

The ID layer is the important part. It gives us a stable target that later tools can consume
without depending on whatever exact family string the predictor or external database emitted.

Initial GO Policy

The current registry is intentionally conservative.

Families with automatic GO mappings:

Families currently left unmapped at the automatic layer:

These remain review-only because the family labels are currently too broad to support reliable,
family-wide automatic GO assignment in this repo.

Integration Plan

This project does not yet wire the term-prediction layer into the prokaryotic immunity predictor
branch. That is intentional.

The intended integration path is:

  1. Predictor emits normalized family calls and confidence
  2. ai_gene_review.defense_go.wrap_prediction(...) resolves them to stable IDs and mapping policy
  3. AIGR export code turns automatic mappings into review-ready term suggestions
  4. Review-only families remain visible to curators with explicit notes instead of silent omission

Keeping those steps separate makes the project biology-first while still leaving room to support
multiple upstream predictors and databases later.

Implementation

The translation layer lives in src/ai_gene_review/defense_go/. The API is intentionally narrow:
an upstream tool emits a family label plus optional confidence; the layer resolves it to a stable
family record and returns either automatic GO suggestions or review-only notes saying why automatic
mapping is not yet allowed. Today the intended upstream source is the prokaryotic immunity predictor
branch, but the same layer could later absorb DefenseFinder, PADLOC, CasFinder, or learned models
without changing the downstream GO policy interface.

File Role
src/ai_gene_review/defense_go/models.py Typed models for defense families, family predictions, GO mapping suggestions
src/ai_gene_review/defense_go/registry.yaml Versioned source-of-truth registry: stable family IDs, aliases, GO mappings, review notes
src/ai_gene_review/defense_go/registry.py Loader and resolver for the registry
tests/test_defense_go.py Tests for alias resolution, automatic mappings, unmapped families, registry safety 
uv run ruff check src/ai_gene_review/defense_go tests/test_defense_go.py
uv run pytest tests/test_defense_go.py

Status

Completed in this unit:

Deferred:

Slides