evoseer-utils 0.1.0__tar.gz

evoseer_utils-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.1
+Name: evoseer-utils
+Version: 0.1.0
+Summary: Shared library for mutation management across modules
+Author: Your Name
+Author-email: your.email@example.com
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: pydantic (>=2.0,<3.0)
+Description-Content-Type: text/markdown
+
+# Mutation Library
+
+Shared library for mutation management across modules.
+
+## Components
+
+### `DbConnection` - Singleton DB connection
+```python
+from libs import DbConnection
+
+DbConnection.set_db_path("mutations.db")
+conn = DbConnection.get_connection()
+```
+
+### `Mutation` - Pydantic model with DB integration
+
+#### States
+- `"full"`: Has both id and (chrom, pos, ref, alt)
+- `"miss_id"`: Has coordinates, missing id
+- `"miss_attributes"`: Has id, missing coordinates
+
+#### Creation patterns
+
+```python
+# With coordinates (lazy load id)
+mut = Mutation(chrom=17, pos=7577548, ref="C", alt="T")
+
+# With id (lazy load attributes)
+mut = Mutation(id=123)
+
+# With both
+mut = Mutation(id=123, chrom=17, pos=7577548, ref="C", alt="T")
+```
+
+#### Methods
+
+**Instance methods:**
+```python
+mut.fetch_id_from_db()           # Get id from coordinates
+mut.fetch_attributes_from_db()   # Get coordinates from id
+mut.ensure_in_db()              # Create if missing, return id
+```
+
+**Class methods (batch):**
+```python
+Mutation.fetch_ids_from_db_batch(mutations)
+Mutation.fetch_attributes_from_db_batch(mutations)
+Mutation.ensure_in_db_batch(mutations)
+```
+
+## Usage in modules with OutputDescription (fully automatic)
+
+`OutputDescription` is a base class that provides automatic DB insertion for module outputs.
+
+```python
+from pydantic import Field
+from typing import ClassVar, List
+from libs import OutputDescription, DbConnection, Mutation
+
+class MyModuleOutput(OutputDescription):
+    table_name: ClassVar[str] = "tool_mymodule"
+    db_fields: ClassVar[List[str]] = ["my_score", "my_prediction"]
+
+    my_score: float = Field(..., description="Module score")
+    my_prediction: str = Field(..., description="Prediction")
+
+# Setup
+DbConnection.set_db_path("mutations.db")
+
+# Single insertion (automatic table creation + mutation insertion)
+output = MyModuleOutput(
+    mutation=Mutation(chrom=17, pos=7577548, ref="C", alt="T"),
+    version="1.0.0",  # Required field (free text)
+    my_score=0.85,
+    my_prediction="pathogenic"
+)
+output.insert_to_db()  # Creates table if needed, ensures mutation exists, inserts
+
+# Batch insertion
+outputs = [...]
+MyModuleOutput.insert_batch_to_db(outputs)
+```
+
+**What happens automatically:**
+- Table creation with correct SQL types (inferred from Python types)
+- Mutation insertion/lookup
+- Index creation on mutation_id
+- `version` field automatically added to table and insertion
+- INSERT OR REPLACE (idempotent)
+
+**Note:** `version` field is required in all OutputDescription subclasses. Format is free text.
+
+## Chromosome encoding
+
+- Autosomes: `1-22`
+- X: `23`
+- Y: `24`
+
+Helper functions:
+
+```python
+from libs.src.mutations import chrom_to_int, int_to_chrom
+
+chrom_to_int("chr17")  # 17
+chrom_to_int("chrX")  # 23
+int_to_chrom(23)  # "chrX"
+```
+
+## Tests
+
+```bash
+# From project root
+.venv/bin/python3 libs/tests/test_mutations_lib.py
+
+# Or use the test runner
+libs/tests/run_tests.sh
+```
+
+## Examples
+
+```bash
+python3 example_mutations_lib.py
+python3 modules/boostdm/output_description_example.py
+```
+

evoseer_utils-0.1.0/README.md

@@ -0,0 +1,124 @@
+# Mutation Library
+
+Shared library for mutation management across modules.
+
+## Components
+
+### `DbConnection` - Singleton DB connection
+```python
+from libs import DbConnection
+
+DbConnection.set_db_path("mutations.db")
+conn = DbConnection.get_connection()
+```
+
+### `Mutation` - Pydantic model with DB integration
+
+#### States
+- `"full"`: Has both id and (chrom, pos, ref, alt)
+- `"miss_id"`: Has coordinates, missing id
+- `"miss_attributes"`: Has id, missing coordinates
+
+#### Creation patterns
+
+```python
+# With coordinates (lazy load id)
+mut = Mutation(chrom=17, pos=7577548, ref="C", alt="T")
+
+# With id (lazy load attributes)
+mut = Mutation(id=123)
+
+# With both
+mut = Mutation(id=123, chrom=17, pos=7577548, ref="C", alt="T")
+```
+
+#### Methods
+
+**Instance methods:**
+```python
+mut.fetch_id_from_db()           # Get id from coordinates
+mut.fetch_attributes_from_db()   # Get coordinates from id
+mut.ensure_in_db()              # Create if missing, return id
+```
+
+**Class methods (batch):**
+```python
+Mutation.fetch_ids_from_db_batch(mutations)
+Mutation.fetch_attributes_from_db_batch(mutations)
+Mutation.ensure_in_db_batch(mutations)
+```
+
+## Usage in modules with OutputDescription (fully automatic)
+
+`OutputDescription` is a base class that provides automatic DB insertion for module outputs.
+
+```python
+from pydantic import Field
+from typing import ClassVar, List
+from libs import OutputDescription, DbConnection, Mutation
+
+class MyModuleOutput(OutputDescription):
+    table_name: ClassVar[str] = "tool_mymodule"
+    db_fields: ClassVar[List[str]] = ["my_score", "my_prediction"]
+
+    my_score: float = Field(..., description="Module score")
+    my_prediction: str = Field(..., description="Prediction")
+
+# Setup
+DbConnection.set_db_path("mutations.db")
+
+# Single insertion (automatic table creation + mutation insertion)
+output = MyModuleOutput(
+    mutation=Mutation(chrom=17, pos=7577548, ref="C", alt="T"),
+    version="1.0.0",  # Required field (free text)
+    my_score=0.85,
+    my_prediction="pathogenic"
+)
+output.insert_to_db()  # Creates table if needed, ensures mutation exists, inserts
+
+# Batch insertion
+outputs = [...]
+MyModuleOutput.insert_batch_to_db(outputs)
+```
+
+**What happens automatically:**
+- Table creation with correct SQL types (inferred from Python types)
+- Mutation insertion/lookup
+- Index creation on mutation_id
+- `version` field automatically added to table and insertion
+- INSERT OR REPLACE (idempotent)
+
+**Note:** `version` field is required in all OutputDescription subclasses. Format is free text.
+
+## Chromosome encoding
+
+- Autosomes: `1-22`
+- X: `23`
+- Y: `24`
+
+Helper functions:
+
+```python
+from libs.src.mutations import chrom_to_int, int_to_chrom
+
+chrom_to_int("chr17")  # 17
+chrom_to_int("chrX")  # 23
+int_to_chrom(23)  # "chrX"
+```
+
+## Tests
+
+```bash
+# From project root
+.venv/bin/python3 libs/tests/test_mutations_lib.py
+
+# Or use the test runner
+libs/tests/run_tests.sh
+```
+
+## Examples
+
+```bash
+python3 example_mutations_lib.py
+python3 modules/boostdm/output_description_example.py
+```

evoseer_utils-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[tool.poetry]
+name = "evoseer-utils"
+version = "0.1.0"
+description = "Shared library for mutation management across modules"
+authors = ["Your Name <your.email@example.com>"]
+readme = "README.md"
+packages = [{include = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+pydantic = "^2.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+ruff = "^0.8"
+pre-commit = "^4.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--strict-markers",
+    "--tb=short",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "N",   # pep8-naming
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]  # Allow unused imports in __init__.py
+"tests/*" = ["D"]         # Disable docstring requirements in tests

evoseer_utils-0.1.0/src/__init__.py

@@ -0,0 +1,5 @@
+from src.db_connection import DbConnection
+from src.mutations import Mutation
+from src.output_description import OutputDescription
+
+__all__ = ["DbConnection", "Mutation", "OutputDescription"]

evoseer_utils-0.1.0/src/db_connection.py

@@ -0,0 +1,80 @@
+"""
+Gestion de la connexion à la base de données SQLite (singleton)
+"""
+
+import sqlite3
+from pathlib import Path
+from typing import Optional
+
+
+class DbConnection:
+    """
+    Singleton pour gérer la connexion à la base de données SQLite
+
+    Usage:
+        DbConnection.set_db_path("mutations.db")
+        conn = DbConnection.get_connection()
+    """
+
+    _instance: Optional["DbConnection"] = None
+    _connection: Optional[sqlite3.Connection] = None
+    _db_path: Optional[str] = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    @classmethod
+    def set_db_path(cls, db_path: str) -> None:
+        """
+        Configure le chemin vers la base de données
+
+        Args:
+            db_path: Chemin vers le fichier SQLite
+        """
+        if cls._db_path != db_path:
+            # Fermer l'ancienne connexion si elle existe
+            if cls._connection is not None:
+                cls._connection.close()
+                cls._connection = None
+
+            cls._db_path = db_path
+
+    @classmethod
+    def get_connection(cls) -> sqlite3.Connection:
+        """
+        Retourne la connexion SQLite (crée si nécessaire)
+
+        Returns:
+            Connexion SQLite
+
+        Raises:
+            RuntimeError: Si le chemin DB n'a pas été configuré
+        """
+        if cls._db_path is None:
+            raise RuntimeError("Database path not set. Call DbConnection.set_db_path() first.")
+
+        if not Path(cls._db_path).exists():
+            raise FileNotFoundError(
+                f"Database file not found: {cls._db_path}. " f"Run init_database.py first."
+            )
+
+        # Créer la connexion si elle n'existe pas
+        if cls._connection is None:
+            cls._connection = sqlite3.connect(cls._db_path)
+            cls._connection.row_factory = sqlite3.Row  # Accès par nom de colonne
+
+        return cls._connection
+
+    @classmethod
+    def close(cls) -> None:
+        """Ferme la connexion à la base de données"""
+        if cls._connection is not None:
+            cls._connection.close()
+            cls._connection = None
+
+    @classmethod
+    def is_configured(cls) -> bool:
+        """Vérifie si la connexion est configurée"""
+        return cls._db_path is not None

evoseer_utils-0.1.0/src/mutations.py

@@ -0,0 +1,406 @@
+"""
+Modèle Pydantic pour les mutations génomiques
+"""
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, field_validator, model_validator
+
+from .db_connection import DbConnection
+
+
+def chrom_to_int(chrom_str: str) -> Optional[int]:
+    """Convertit chr1-chr22, chrX, chrY en 1-24"""
+    chrom_str = str(chrom_str).upper().replace("chr", "")
+    if chrom_str == "X":
+        return 23
+    elif chrom_str == "Y":
+        return 24
+    elif chrom_str in ["M", "MT"]:
+        return None
+    else:
+        try:
+            return int(chrom_str)
+        except ValueError:
+            return None
+
+
+def int_to_chrom(chrom_int: int) -> str:
+    """Convertit 1-24 en chr1-chr22, chrX, chrY"""
+    if chrom_int == 23:
+        return "chrX"
+    elif chrom_int == 24:
+        return "chrY"
+    else:
+        return f"chr{chrom_int}"
+
+
+class Mutation(BaseModel):
+    """
+    Modèle pour une mutation génomique
+
+    Attributs:
+        id: ID de la mutation dans la DB (auto-généré)
+        chrom: Chromosome (1-22, 23=X, 24=Y)
+        pos: Position génomique
+        ref: Allèle de référence
+        alt: Allèle alternatif
+
+    Validation:
+        - Soit id est fourni
+        - Soit (chrom, pos, ref, alt) sont tous fournis
+        - Soit les deux
+
+    Usage:
+        # Avec ID seulement (lazy load des attributs)
+        mutation = Mutation(id=123)
+        mutation.fetch_attributes_from_db()
+
+        # Avec coordonnées (lazy load de l'ID)
+        mutation = Mutation(chrom=17, pos=7577548, ref="C", alt="T")
+        mutation.fetch_id_from_db()
+
+        # Avec tout
+        mutation = Mutation(id=123, chrom=17, pos=7577548, ref="C", alt="T")
+    """
+
+    id: Optional[int] = None
+    chrom: Optional[int] = None
+    pos: Optional[int] = None
+    ref: Optional[str] = None
+    alt: Optional[str] = None
+
+    @field_validator("chrom", mode="before")
+    @classmethod
+    def normalize_chrom(cls, v):
+        return chrom_to_int(v)
+
+    @model_validator(mode="after")
+    def validate_mutation(self):
+        """
+        Valide qu'on a soit id, soit (chrom, pos, ref, alt), soit les deux
+        """
+        has_id = self.id is not None
+        has_coords = all(
+            [
+                self.chrom is not None,
+                self.pos is not None,
+                self.ref is not None,
+                self.alt is not None,
+            ]
+        )
+
+        if not has_id and not has_coords:
+            raise ValueError("Must provide either 'id' or all of (chrom, pos, ref, alt)")
+
+        # Vérifier que si on a des coordonnées partielles, elles sont complètes
+        coord_fields = [self.chrom, self.pos, self.ref, self.alt]
+        partial_coords = any(f is not None for f in coord_fields)
+
+        if partial_coords and not has_coords:
+            raise ValueError("If providing coordinates, must provide all of (chrom, pos, ref, alt)")
+
+        return self
+
+    @property
+    def state(self) -> Literal["full", "miss_id", "miss_attributes"]:
+        """
+        Retourne l'état de la mutation
+
+        Returns:
+            - "full": id et attributs présents
+            - "miss_id": attributs présents, id manquant
+            - "miss_attributes": id présent, attributs manquants
+        """
+        has_id = self.id is not None
+        has_coords = all(
+            [
+                self.chrom is not None,
+                self.pos is not None,
+                self.ref is not None,
+                self.alt is not None,
+            ]
+        )
+
+        if has_id and has_coords:
+            return "full"
+        elif has_coords:
+            return "miss_id"
+        else:
+            return "miss_attributes"
+
+    def fetch_id_from_db(self) -> Optional[int]:
+        """
+        Récupère l'ID de la mutation depuis la DB via (chrom, pos, ref, alt)
+        Met à jour self.id si trouvé
+
+        Returns:
+            ID de la mutation ou None si non trouvée
+
+        Raises:
+            ValueError: Si les coordonnées ne sont pas complètes
+        """
+        if self.state == "miss_attributes":
+            raise ValueError("Cannot fetch ID: coordinates (chrom, pos, ref, alt) are required")
+
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        cursor.execute(
+            """
+            SELECT id FROM mutations
+            WHERE chrom=? AND pos=? AND ref=? AND alt=?
+        """,
+            (self.chrom, self.pos, self.ref, self.alt),
+        )
+
+        result = cursor.fetchone()
+        if result:
+            self.id = result["id"]
+            return self.id
+
+        return None
+
+    def fetch_attributes_from_db(self) -> bool:
+        """
+        Récupère les attributs de la mutation depuis la DB via l'ID
+        Met à jour (chrom, pos, ref, alt) si trouvés
+
+        Returns:
+            True si trouvé, False sinon
+
+        Raises:
+            ValueError: Si l'ID n'est pas fourni
+        """
+        if self.id is None:
+            raise ValueError("Cannot fetch attributes: id is required")
+
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        cursor.execute(
+            """
+            SELECT chrom, pos, ref, alt FROM mutations
+            WHERE id=?
+        """,
+            (self.id,),
+        )
+
+        result = cursor.fetchone()
+        if result:
+            self.chrom = result["chrom"]
+            self.pos = result["pos"]
+            self.ref = result["ref"]
+            self.alt = result["alt"]
+            return True
+
+        return False
+
+    def ensure_in_db(self, annotate: bool = True) -> int:
+        """
+        S'assure que la mutation existe dans la DB (crée si nécessaire)
+        Met à jour self.id
+
+        Args:
+            annotate: Si True, annote automatiquement avec le contexte génomique
+
+        Returns:
+            ID de la mutation
+
+        Raises:
+            ValueError: Si les coordonnées ne sont pas complètes
+        """
+        if self.state == "miss_attributes":
+            raise ValueError("Cannot ensure in DB: coordinates (chrom, pos, ref, alt) are required")
+
+        # Si on a déjà l'ID, on vérifie qu'il existe
+        if self.id is not None:
+            conn = DbConnection.get_connection()
+            cursor = conn.cursor()
+            cursor.execute("SELECT id FROM mutations WHERE id=?", (self.id,))
+            if cursor.fetchone():
+                return self.id
+
+        # Sinon, chercher par coordonnées
+        existing_id = self.fetch_id_from_db()
+        if existing_id is not None:
+            return existing_id
+
+        # Si pas trouvé, créer
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        cursor.execute(
+            """
+            INSERT INTO mutations (chrom, pos, ref, alt)
+            VALUES (?, ?, ?, ?)
+        """,
+            (self.chrom, self.pos, self.ref, self.alt),
+        )
+
+        self.id = cursor.lastrowid
+
+        # Annoter si demandé
+        if annotate:
+            self._annotate_mutation()
+
+        conn.commit()
+        return self.id
+
+    def _annotate_mutation(self) -> None:
+        """
+        Annote la mutation avec le contexte génomique
+        (méthode interne, appelée par ensure_in_db)
+        """
+        if self.id is None or self.chrom is None or self.pos is None:
+            return
+
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        # Supprimer les anciennes annotations
+        cursor.execute("DELETE FROM mutation_annotations WHERE mutation_id = ?", (self.id,))
+
+        # Trouver les features qui chevauchent
+        cursor.execute(
+            """
+            SELECT gf.id
+            FROM genomic_features gf
+            JOIN genes g ON gf.gene_id = g.id
+            WHERE g.chrom = ? AND gf.feature_start <= ? AND gf.feature_end >= ?
+        """,
+            (self.chrom, self.pos, self.pos),
+        )
+
+        feature_ids = [row["id"] for row in cursor.fetchall()]
+
+        if feature_ids:
+            for feature_id in feature_ids:
+                cursor.execute(
+                    """
+                    INSERT INTO mutation_annotations (mutation_id, feature_id)
+                    VALUES (?, ?)
+                """,
+                    (self.id, feature_id),
+                )
+        else:
+            # Intergenic
+            cursor.execute(
+                """
+                INSERT INTO mutation_annotations (mutation_id, feature_id)
+                VALUES (?, NULL)
+            """,
+                (self.id,),
+            )
+
+    @classmethod
+    def fetch_ids_from_db_batch(cls, mutations: list["Mutation"]) -> None:
+        """
+        Récupère les IDs pour un batch de mutations (modifie en place)
+
+        Args:
+            mutations: Liste de mutations (doivent avoir chrom, pos, ref, alt)
+
+        Raises:
+            ValueError: Si une mutation n'a pas de coordonnées complètes
+        """
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        for mutation in mutations:
+            if mutation.state == "miss_attributes":
+                raise ValueError(f"Mutation {mutation} missing coordinates")
+
+            cursor.execute(
+                """
+                SELECT id FROM mutations
+                WHERE chrom=? AND pos=? AND ref=? AND alt=?
+            """,
+                (mutation.chrom, mutation.pos, mutation.ref, mutation.alt),
+            )
+
+            result = cursor.fetchone()
+            if result:
+                mutation.id = result["id"]
+
+    @classmethod
+    def fetch_attributes_from_db_batch(cls, mutations: list["Mutation"]) -> None:
+        """
+        Récupère les attributs pour un batch de mutations (modifie en place)
+
+        Args:
+            mutations: Liste de mutations (doivent avoir id)
+
+        Raises:
+            ValueError: Si une mutation n'a pas d'ID
+        """
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        for mutation in mutations:
+            if mutation.id is None:
+                raise ValueError(f"Mutation {mutation} missing id")
+
+            cursor.execute(
+                """
+                SELECT chrom, pos, ref, alt FROM mutations
+                WHERE id=?
+            """,
+                (mutation.id,),
+            )
+
+            result = cursor.fetchone()
+            if result:
+                mutation.chrom = result["chrom"]
+                mutation.pos = result["pos"]
+                mutation.ref = result["ref"]
+                mutation.alt = result["alt"]
+
+    @classmethod
+    def ensure_in_db_batch(cls, mutations: list["Mutation"], annotate: bool = True) -> None:
+        """
+        S'assure que toutes les mutations existent dans la DB (crée si nécessaire)
+        Modifie les mutations en place pour ajouter les IDs
+
+        Args:
+            mutations: Liste de mutations (doivent avoir chrom, pos, ref, alt)
+            annotate: Si True, annote automatiquement avec le contexte génomique
+
+        Raises:
+            ValueError: Si une mutation n'a pas de coordonnées complètes
+        """
+        # D'abord, essayer de récupérer les IDs existants
+        cls.fetch_ids_from_db_batch(mutations)
+
+        # Créer les mutations qui n'existent pas
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        for mutation in mutations:
+            if mutation.id is None:
+                # Créer la mutation
+                cursor.execute(
+                    """
+                    INSERT INTO mutations (chrom, pos, ref, alt)
+                    VALUES (?, ?, ?, ?)
+                """,
+                    (mutation.chrom, mutation.pos, mutation.ref, mutation.alt),
+                )
+
+                mutation.id = cursor.lastrowid
+
+                # Annoter si demandé
+                if annotate:
+                    mutation._annotate_mutation()
+
+        conn.commit()
+
+    def __repr__(self) -> str:
+        if self.state == "full":
+            chrom_str = int_to_chrom(self.chrom)
+            return f"Mutation(id={self.id}, {chrom_str}:{self.pos} {self.ref}>{self.alt})"
+        elif self.state == "miss_id":
+            chrom_str = int_to_chrom(self.chrom)
+            return f"Mutation({chrom_str}:{self.pos} {self.ref}>{self.alt}, id=?)"
+        else:
+            return f"Mutation(id={self.id}, coords=?)"

evoseer_utils-0.1.0/src/output_description.py

@@ -0,0 +1,131 @@
+from typing import ClassVar, Optional, get_type_hints
+
+from pydantic import BaseModel
+
+from src.db_connection import DbConnection
+from src.mutations import Mutation
+
+
+class OutputDescription(BaseModel):
+    mutation: Mutation
+    version: ClassVar[str]
+
+    _table_name: ClassVar[str]
+    db_fields: ClassVar[list[str]]
+
+    @property
+    def table_name(self) -> str:
+        # we do that because it allows automatic views based on "annot_" prefix
+        return "annot_" + self._table_name
+
+    @classmethod
+    def _get_all_db_fields(cls) -> list[str]:
+        # Always include version automatically
+        return ["version"] + cls.db_fields
+
+    @classmethod
+    def _python_type_to_sql(cls, python_type: type) -> str:
+        type_map = {
+            int: "INTEGER",
+            float: "REAL",
+            str: "TEXT",
+            bool: "INTEGER",
+        }
+        # Handle Optional types
+        origin = getattr(python_type, "__origin__", None)
+        if origin is type(None) or str(python_type).startswith("typing.Union"):
+            args = getattr(python_type, "__args__", ())
+            if args:
+                python_type = args[0] if args[0] is not type(None) else args[1]
+
+        return type_map.get(python_type, "TEXT")
+
+    @classmethod
+    def _ensure_table_exists(cls, table_name: str) -> None:
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        type_hints = get_type_hints(cls)
+        columns = ["id INTEGER PRIMARY KEY AUTOINCREMENT", "mutation_id INTEGER NOT NULL UNIQUE"]
+
+        for field_name in cls._get_all_db_fields():
+            field_type = type_hints.get(field_name, str)
+            sql_type = cls._python_type_to_sql(field_type)
+            columns.append(f"{field_name} {sql_type}")
+
+        columns.append("FOREIGN KEY (mutation_id) REFERENCES mutations(id) ON DELETE CASCADE")
+
+        cursor.execute(f"""
+            CREATE TABLE IF NOT EXISTS {table_name} (
+                {', '.join(columns)}
+            )
+        """)
+
+        cursor.execute(f"""
+            CREATE INDEX IF NOT EXISTS idx_{table_name}_mutation
+            ON {table_name}(mutation_id)
+        """)
+
+        conn.commit()
+
+    def insert_to_db(self, table_name: Optional[str] = None) -> None:
+        if table_name is None:
+            table_name = self.table_name
+
+        self._ensure_table_exists(table_name)
+        self.mutation.ensure_in_db()
+
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        all_fields = self._get_all_db_fields()
+        fields = ["mutation_id"] + all_fields
+        values = [self.mutation.id] + [getattr(self, field) for field in all_fields]
+
+        placeholders = ", ".join(["?"] * len(values))
+
+        cursor.execute(
+            f"""
+            INSERT OR REPLACE INTO {table_name}
+            ({', '.join(fields)})
+            VALUES ({placeholders})
+        """,
+            values,
+        )
+
+        conn.commit()
+
+    @classmethod
+    def insert_batch_to_db(
+        cls, outputs: list["OutputDescription"], table_name: Optional[str] = None
+    ) -> None:
+        if table_name is None:
+            table_name = cls.table_name
+
+        cls._ensure_table_exists(table_name)
+
+        mutations = [output.mutation for output in outputs]
+        Mutation.ensure_in_db_batch(mutations)
+
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        all_fields = cls._get_all_db_fields()
+        fields = ["mutation_id"] + all_fields
+        placeholders = ", ".join(["?"] * len(fields))
+
+        values_list = []
+        for output in outputs:
+            values = [output.mutation.id] + [getattr(output, field) for field in all_fields]
+            values_list.append(values)
+
+        cursor.executemany(
+            f"""
+            INSERT OR REPLACE INTO {table_name}
+            ({', '.join(fields)})
+            VALUES ({placeholders})
+        """,
+            values_list,
+        )
+
+        conn.commit()