lecrapaud 0.19.0__py3-none-any.whl → 0.22.6__py3-none-any.whl

lecrapaud/config.py

@@ -4,8 +4,6 @@ from dotenv import load_dotenv
 load_dotenv(override=False)
 
 PYTHON_ENV = os.getenv("PYTHON_ENV")
-REDIS_URL = os.getenv("REDIS_URL", "redis://localhost:6379")
-EXPERIMENT_ID = os.getenv("EXPERIMENT_ID")
 LOGGING_LEVEL = os.getenv("LOGGING_LEVEL", "INFO")
 
 DB_USER = (
@@ -32,5 +30,19 @@ DB_URI: str = (
 )
 OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
 LECRAPAUD_LOGFILE = os.getenv("LECRAPAUD_LOGFILE")
-LECRAPAUD_LOCAL = os.getenv("LECRAPAUD_LOCAL", False)
 LECRAPAUD_TABLE_PREFIX = os.getenv("LECRAPAUD_TABLE_PREFIX", "lecrapaud")
+LECRAPAUD_OPTIMIZATION_BACKEND = os.getenv(
+    "LECRAPAUD_OPTIMIZATION_BACKEND", "hyperopt"
+).lower()
+
+SENTRY_DSN = os.getenv("SENTRY_DSN")
+
+try:
+    SENTRY_TRACES_SAMPLE_RATE = float(os.getenv("SENTRY_TRACES_SAMPLE_RATE", "0"))
+except ValueError:
+    SENTRY_TRACES_SAMPLE_RATE = 0.0
+
+try:
+    SENTRY_PROFILES_SAMPLE_RATE = float(os.getenv("SENTRY_PROFILES_SAMPLE_RATE", "0"))
+except ValueError:
+    SENTRY_PROFILES_SAMPLE_RATE = 0.0

lecrapaud/db/alembic/versions/2025_10_25_0635-07e303521594_add_unique_constraint_to_score.py

@@ -0,0 +1,39 @@
+"""add unique constraint to score
+
+Revision ID: 07e303521594
+Revises: 8b11c1ba982e
+Create Date: 2025-10-25 06:35:57.950929
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from lecrapaud.config import LECRAPAUD_TABLE_PREFIX
+
+# revision identifiers, used by Alembic.
+revision: str = "07e303521594"
+down_revision: Union[str, None] = "8b11c1ba982e"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_unique_constraint(
+        "unique_score_per_model_training",
+        f"{LECRAPAUD_TABLE_PREFIX}_scores",
+        ["model_training_id"],
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_constraint(
+        "unique_score_per_model_training",
+        f"{LECRAPAUD_TABLE_PREFIX}_scores",
+        type_="unique",
+    )
+    # ### end Alembic commands ###

lecrapaud/db/alembic/versions/2025_10_26_1727-033e0f7eca4f_merge_score_and_model_trainings_into_.py

@@ -0,0 +1,264 @@
+"""merge score and model_trainings into model_selection_scores
+
+Revision ID: 033e0f7eca4f
+Revises: 07e303521594
+Create Date: 2025-10-26 17:27:30.400473
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from lecrapaud.config import LECRAPAUD_TABLE_PREFIX
+
+# revision identifiers, used by Alembic.
+revision: str = "033e0f7eca4f"
+down_revision: Union[str, None] = "07e303521594"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    # Check if table exists using inspector
+    from sqlalchemy import inspect
+    inspector = inspect(op.get_bind())
+    existing_tables = inspector.get_table_names()
+    
+    if f"{LECRAPAUD_TABLE_PREFIX}_model_selection_scores" not in existing_tables:
+        op.create_table(
+            f"{LECRAPAUD_TABLE_PREFIX}_model_selection_scores",
+            sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
+            sa.Column(
+                "created_at",
+                sa.TIMESTAMP(timezone=True),
+                server_default=sa.text("now()"),
+                nullable=False,
+            ),
+            sa.Column(
+                "updated_at",
+                sa.TIMESTAMP(timezone=True),
+                server_default=sa.text("now()"),
+                nullable=False,
+            ),
+            sa.Column("best_params", sa.JSON(), nullable=True),
+            sa.Column("model_path", sa.String(length=255), nullable=True),
+            sa.Column("training_time", sa.Integer(), nullable=True),
+            sa.Column("model_id", sa.BigInteger(), nullable=False),
+            sa.Column("model_selection_id", sa.BigInteger(), nullable=False),
+            sa.Column("eval_data_std", sa.Float(), nullable=True),
+            sa.Column("rmse", sa.Float(), nullable=True),
+            sa.Column("rmse_std_ratio", sa.Float(), nullable=True),
+            sa.Column("mae", sa.Float(), nullable=True),
+            sa.Column("mape", sa.Float(), nullable=True),
+            sa.Column("mam", sa.Float(), nullable=True),
+            sa.Column("mad", sa.Float(), nullable=True),
+            sa.Column("mae_mam_ratio", sa.Float(), nullable=True),
+            sa.Column("mae_mad_ratio", sa.Float(), nullable=True),
+            sa.Column("r2", sa.Float(), nullable=True),
+            sa.Column("logloss", sa.Float(), nullable=True),
+            sa.Column("accuracy", sa.Float(), nullable=True),
+            sa.Column("precision", sa.Float(), nullable=True),
+            sa.Column("recall", sa.Float(), nullable=True),
+            sa.Column("f1", sa.Float(), nullable=True),
+            sa.Column("roc_auc", sa.Float(), nullable=True),
+            sa.Column("avg_precision", sa.Float(), nullable=True),
+            sa.Column("thresholds", sa.JSON(), nullable=True),
+            sa.Column("precision_at_threshold", sa.Float(), nullable=True),
+            sa.Column("recall_at_threshold", sa.Float(), nullable=True),
+            sa.Column("f1_at_threshold", sa.Float(), nullable=True),
+            sa.ForeignKeyConstraint(
+                ["model_id"],
+                [f"{LECRAPAUD_TABLE_PREFIX}_models.id"],
+            ),
+            sa.ForeignKeyConstraint(
+                ["model_selection_id"],
+                [f"{LECRAPAUD_TABLE_PREFIX}_model_selections.id"],
+                ondelete="CASCADE",
+            ),
+            sa.PrimaryKeyConstraint("id"),
+            sa.UniqueConstraint(
+                "model_id",
+                "model_selection_id",
+                name="uq_model_selection_score_composite",
+            ),
+        )
+        op.create_index(
+            op.f("ix_model_selection_scores_id"),
+            f"{LECRAPAUD_TABLE_PREFIX}_model_selection_scores",
+            ["id"],
+            unique=False,
+        )
+
+    # Migrate existing data from model_trainings and scores to model_selection_scores
+    op.execute(
+        f"""
+        INSERT INTO {LECRAPAUD_TABLE_PREFIX}_model_selection_scores (
+            created_at, updated_at, best_params, model_path, training_time, 
+            model_id, model_selection_id,
+            eval_data_std, rmse, rmse_std_ratio, mae, mape, mam, mad, 
+            mae_mam_ratio, mae_mad_ratio, r2, logloss, accuracy, `precision`, 
+            recall, f1, roc_auc, avg_precision, thresholds, 
+            precision_at_threshold, recall_at_threshold, f1_at_threshold
+        )
+        SELECT 
+            mt.created_at, 
+            mt.updated_at, 
+            mt.best_params, 
+            mt.model_path, 
+            COALESCE(mt.training_time, s.training_time) as training_time,
+            mt.model_id, 
+            mt.model_selection_id,
+            s.eval_data_std, s.rmse, s.rmse_std_ratio, s.mae, s.mape, 
+            s.mam, s.mad, s.mae_mam_ratio, s.mae_mad_ratio, s.r2, 
+            s.logloss, s.accuracy, s.`precision`, s.recall, s.f1, 
+            s.roc_auc, s.avg_precision, s.thresholds,
+            s.precision_at_threshold, s.recall_at_threshold, s.f1_at_threshold
+        FROM {LECRAPAUD_TABLE_PREFIX}_model_trainings mt
+        LEFT JOIN {LECRAPAUD_TABLE_PREFIX}_scores s ON s.model_training_id = mt.id
+    """
+    )
+
+    # Drop the old tables
+    op.drop_table(f"{LECRAPAUD_TABLE_PREFIX}_scores")
+    op.drop_table(f"{LECRAPAUD_TABLE_PREFIX}_model_trainings")
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    # Recreate the old tables
+    op.create_table(
+        f"{LECRAPAUD_TABLE_PREFIX}_model_trainings",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column(
+            "created_at",
+            sa.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column("best_params", sa.JSON(), nullable=True),
+        sa.Column("model_path", sa.String(length=255), nullable=True),
+        sa.Column("training_time", sa.Integer(), nullable=True),
+        sa.Column("model_id", sa.BigInteger(), nullable=False),
+        sa.Column("model_selection_id", sa.BigInteger(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["model_id"],
+            [f"{LECRAPAUD_TABLE_PREFIX}_models.id"],
+        ),
+        sa.ForeignKeyConstraint(
+            ["model_selection_id"],
+            [f"{LECRAPAUD_TABLE_PREFIX}_model_selections.id"],
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint(
+            "model_id", "model_selection_id", name="uq_model_training_composite"
+        ),
+    )
+    op.create_index(
+        op.f("ix_model_trainings_id"),
+        f"{LECRAPAUD_TABLE_PREFIX}_model_trainings",
+        ["id"],
+        unique=False,
+    )
+
+    op.create_table(
+        f"{LECRAPAUD_TABLE_PREFIX}_scores",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column(
+            "created_at",
+            sa.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.TIMESTAMP(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column("type", sa.String(length=50), nullable=False),
+        sa.Column("training_time", sa.Integer(), nullable=True),
+        sa.Column("eval_data_std", sa.Float(), nullable=True),
+        sa.Column("rmse", sa.Float(), nullable=True),
+        sa.Column("rmse_std_ratio", sa.Float(), nullable=True),
+        sa.Column("mae", sa.Float(), nullable=True),
+        sa.Column("mape", sa.Float(), nullable=True),
+        sa.Column("mam", sa.Float(), nullable=True),
+        sa.Column("mad", sa.Float(), nullable=True),
+        sa.Column("mae_mam_ratio", sa.Float(), nullable=True),
+        sa.Column("mae_mad_ratio", sa.Float(), nullable=True),
+        sa.Column("r2", sa.Float(), nullable=True),
+        sa.Column("logloss", sa.Float(), nullable=True),
+        sa.Column("accuracy", sa.Float(), nullable=True),
+        sa.Column("precision", sa.Float(), nullable=True),
+        sa.Column("recall", sa.Float(), nullable=True),
+        sa.Column("f1", sa.Float(), nullable=True),
+        sa.Column("roc_auc", sa.Float(), nullable=True),
+        sa.Column("avg_precision", sa.Float(), nullable=True),
+        sa.Column("thresholds", sa.JSON(), nullable=True),
+        sa.Column("precision_at_threshold", sa.Float(), nullable=True),
+        sa.Column("recall_at_threshold", sa.Float(), nullable=True),
+        sa.Column("f1_at_threshold", sa.Float(), nullable=True),
+        sa.Column("model_training_id", sa.BigInteger(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["model_training_id"],
+            [f"{LECRAPAUD_TABLE_PREFIX}_model_trainings.id"],
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint(
+            "model_training_id", name="unique_score_per_model_training"
+        ),
+    )
+    op.create_index(
+        op.f("ix_scores_id"), f"{LECRAPAUD_TABLE_PREFIX}_scores", ["id"], unique=False
+    )
+
+    # Migrate data back (note: we'll lose the type column data, defaulting to 'testset')
+    op.execute(
+        f"""
+        INSERT INTO {LECRAPAUD_TABLE_PREFIX}_model_trainings (
+            id, created_at, updated_at, best_params, model_path, 
+            training_time, model_id, model_selection_id
+        )
+        SELECT 
+            id, created_at, updated_at, best_params, model_path, 
+            training_time, model_id, model_selection_id
+        FROM {LECRAPAUD_TABLE_PREFIX}_model_selection_scores
+    """
+    )
+
+    op.execute(
+        f"""
+        INSERT INTO {LECRAPAUD_TABLE_PREFIX}_scores (
+            created_at, updated_at, type, training_time, eval_data_std, 
+            rmse, rmse_std_ratio, mae, mape, mam, mad, mae_mam_ratio, 
+            mae_mad_ratio, r2, logloss, accuracy, `precision`, recall, 
+            f1, roc_auc, avg_precision, thresholds, precision_at_threshold,
+            recall_at_threshold, f1_at_threshold, model_training_id
+        )
+        SELECT 
+            created_at, updated_at, 'testset', training_time, eval_data_std, 
+            rmse, rmse_std_ratio, mae, mape, mam, mad, mae_mam_ratio, 
+            mae_mad_ratio, r2, logloss, accuracy, precision, recall, 
+            f1, roc_auc, avg_precision, thresholds, precision_at_threshold,
+            recall_at_threshold, f1_at_threshold, id
+        FROM {LECRAPAUD_TABLE_PREFIX}_model_selection_scores
+    """
+    )
+
+    op.drop_index(
+        op.f("ix_model_selection_scores_id"),
+        table_name=f"{LECRAPAUD_TABLE_PREFIX}_model_selection_scores",
+    )
+    op.drop_table(f"{LECRAPAUD_TABLE_PREFIX}_model_selection_scores")
+    # ### end Alembic commands ###

lecrapaud/db/alembic/versions/2025_10_28_2006-0a8fb7826e9b_add_number_of_targets_and_remove_other_.py

@@ -0,0 +1,75 @@
+"""add number_of_targets and remove other fields from experiments
+
+Revision ID: 0a8fb7826e9b
+Revises: 033e0f7eca4f
+Create Date: 2025-10-28 20:06:54.792631
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import mysql
+from lecrapaud.config import LECRAPAUD_TABLE_PREFIX
+
+# revision identifiers, used by Alembic.
+revision: str = "0a8fb7826e9b"
+down_revision: Union[str, None] = "033e0f7eca4f"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column(
+        f"{LECRAPAUD_TABLE_PREFIX}_experiments",
+        sa.Column("number_of_targets", sa.Integer(), nullable=True),
+    )
+    op.drop_column(f"{LECRAPAUD_TABLE_PREFIX}_experiments", "corr_threshold")
+    op.drop_column(f"{LECRAPAUD_TABLE_PREFIX}_experiments", "max_features")
+    op.drop_column(f"{LECRAPAUD_TABLE_PREFIX}_experiments", "percentile")
+    op.drop_column(f"{LECRAPAUD_TABLE_PREFIX}_experiments", "type")
+    op.drop_index(
+        op.f("ix_model_selection_scores_id"),
+        table_name=f"{LECRAPAUD_TABLE_PREFIX}_model_selection_scores",
+    )
+    op.create_index(
+        op.f("ix_model_selection_scores_id"),
+        f"{LECRAPAUD_TABLE_PREFIX}_model_selection_scores",
+        ["id"],
+        unique=False,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(
+        op.f("ix_lecrapaud_model_selection_scores_id"),
+        table_name=f"{LECRAPAUD_TABLE_PREFIX}_model_selection_scores",
+    )
+    op.create_index(
+        op.f("ix_model_selection_scores_id"),
+        f"{LECRAPAUD_TABLE_PREFIX}_model_selection_scores",
+        ["id"],
+        unique=False,
+    )
+    op.add_column(
+        f"{LECRAPAUD_TABLE_PREFIX}_experiments",
+        sa.Column("type", mysql.VARCHAR(length=50), nullable=False),
+    )
+    op.add_column(
+        f"{LECRAPAUD_TABLE_PREFIX}_experiments",
+        sa.Column("percentile", mysql.FLOAT(), nullable=False),
+    )
+    op.add_column(
+        f"{LECRAPAUD_TABLE_PREFIX}_experiments",
+        sa.Column("max_features", mysql.INTEGER(), autoincrement=False, nullable=False),
+    )
+    op.add_column(
+        f"{LECRAPAUD_TABLE_PREFIX}_experiments",
+        sa.Column("corr_threshold", mysql.FLOAT(), nullable=False),
+    )
+    op.drop_column(f"{LECRAPAUD_TABLE_PREFIX}_experiments", "number_of_targets")
+    # ### end Alembic commands ###

lecrapaud/db/models/__init__.py

@@ -4,9 +4,8 @@ from lecrapaud.db.models.feature_selection_rank import FeatureSelectionRank
 from lecrapaud.db.models.feature_selection import FeatureSelection
 from lecrapaud.db.models.feature import Feature
 from lecrapaud.db.models.model_selection import ModelSelection
-from lecrapaud.db.models.model_training import ModelTraining
 from lecrapaud.db.models.model import Model
-from lecrapaud.db.models.score import Score
+from lecrapaud.db.models.model_selection_score import ModelSelectionScore
 from lecrapaud.db.models.target import Target
 
 __all__ = [
@@ -16,8 +15,7 @@ __all__ = [
     'FeatureSelection',
     'Feature',
     'ModelSelection',
-    'ModelTraining',
     'Model',
-    'Score',
+    'ModelSelectionScore',
     'Target',
 ]

lecrapaud/db/models/base.py

@@ -10,24 +10,27 @@ from sqlalchemy.orm.attributes import InstrumentedAttribute
 from lecrapaud.db.session import get_db
 from sqlalchemy.ext.declarative import declared_attr
 from sqlalchemy.dialects.mysql import insert as mysql_insert
+from sqlalchemy import UniqueConstraint
+from sqlalchemy.inspection import inspect as sqlalchemy_inspect
 from lecrapaud.config import LECRAPAUD_TABLE_PREFIX
 
 
 def with_db(func):
     """Decorator to provide a database session to the wrapped function.
-    
+
     If a db parameter is already provided, it will be used. Otherwise,
     a new session will be created and automatically managed.
     """
+
     @wraps(func)
     def wrapper(*args, **kwargs):
         if "db" in kwargs and kwargs["db"] is not None:
             return func(*args, **kwargs)
-            
+
         with get_db() as db:
             kwargs["db"] = db
             return func(*args, **kwargs)
-            
+
     return wrapper
 
 
@@ -106,51 +109,6 @@ class Base(DeclarativeBase):
             ]
         return results
 
-    @classmethod
-    @with_db
-    def upsert_bulk(cls, db=None, match_fields: list[str] = None, **kwargs):
-        """
-        Performs a bulk upsert into the database using ON DUPLICATE KEY UPDATE.
-
-        Args:
-            db (Session): SQLAlchemy DB session
-            match_fields (list[str]): Fields to match on for deduplication
-            **kwargs: Column-wise keyword arguments (field_name=[...])
-        """
-        # Ensure all provided fields have values of equal length
-        value_lengths = [len(v) for v in kwargs.values()]
-        if not value_lengths or len(set(value_lengths)) != 1:
-            raise ValueError(
-                "All field values must be non-empty lists of the same length."
-            )
-
-        # Convert column-wise kwargs to row-wise list of dicts
-        items = [dict(zip(kwargs.keys(), row)) for row in zip(*kwargs.values())]
-        if not items:
-            return
-
-        stmt = mysql_insert(cls.__table__).values(items)
-
-        # Default to primary keys if match_fields not provided
-        if not match_fields:
-            match_fields = [col.name for col in cls.__table__.primary_key.columns]
-
-        # Ensure all columns to be updated are in the insert
-        update_dict = {
-            c.name: stmt.inserted[c.name]
-            for c in cls.__table__.columns
-            if c.name not in match_fields and c.name in items[0]
-        }
-
-        if not update_dict:
-            # Avoid triggering ON DUPLICATE KEY UPDATE with empty dict
-            db.execute(stmt.prefix_with("IGNORE"))
-        else:
-            upsert_stmt = stmt.on_duplicate_key_update(**update_dict)
-            db.execute(upsert_stmt)
-
-        db.commit()
-
     @classmethod
     @with_db
     def filter(cls, db=None, **kwargs):
@@ -198,33 +156,126 @@ class Base(DeclarativeBase):
 
     @classmethod
     @with_db
-    def upsert(cls, match_fields: list[str], db=None, **kwargs):
+    def upsert(cls, db=None, **kwargs):
         """
-        Upsert an instance of the model: update if found, else create.
+        Upsert an instance of the model using MySQL's ON DUPLICATE KEY UPDATE.
 
-        :param match_fields: list of field names to use for matching
         :param kwargs: all fields for creation or update
         """
-        filters = [
-            getattr(cls, field) == kwargs[field]
-            for field in match_fields
-            if field in kwargs
-        ]
+        # If an ID is provided and row exists, fall back to a standard update
+        instance_id = kwargs.get("id")
+        if instance_id is not None:
+            instance = db.get(cls, instance_id)
+            if instance:
+                for key, value in kwargs.items():
+                    if key == "id":
+                        continue
+                    setattr(instance, key, value)
+                db.commit()
+                db.refresh(instance)
+                return instance
+
+        # Use INSERT ... ON DUPLICATE KEY UPDATE
+        stmt = mysql_insert(cls.__table__).values(**kwargs)
+        stmt = stmt.on_duplicate_key_update(
+            **{k: v for k, v in kwargs.items() if k != "id"}
+        )
 
-        instance = db.query(cls).filter(*filters).first()
+        result = db.execute(stmt)
+        db.commit()
 
-        if instance:
-            for key, value in kwargs.items():
-                if key != "id":
-                    setattr(instance, key, value)
+        # Get the instance - either the newly inserted or updated one
+        # If updated, lastrowid is 0, so we need to query
+        if result.lastrowid and result.lastrowid > 0:
+            # New insert
+            instance = db.get(cls, result.lastrowid)
         else:
-            instance = cls(**kwargs)
-            db.add(instance)
+            # Updated - need to find it using unique constraint fields
+            mapper = sqlalchemy_inspect(cls)
+            instance = None
+
+            for constraint in mapper.mapped_table.constraints:
+                if isinstance(constraint, UniqueConstraint):
+                    col_names = [col.name for col in constraint.columns]
+                    if all(name in kwargs for name in col_names):
+                        filters = [
+                            getattr(cls, col_name) == kwargs[col_name]
+                            for col_name in col_names
+                        ]
+                        instance = db.query(cls).filter(*filters).first()
+                        if instance:
+                            break
+
+            # Check for single column unique constraints
+            if not instance:
+                for col in mapper.mapped_table.columns:
+                    if col.unique and col.name in kwargs:
+                        instance = (
+                            db.query(cls)
+                            .filter(getattr(cls, col.name) == kwargs[col.name])
+                            .first()
+                        )
+                        if instance:
+                            break
+
+            # If still not found, try to find by all kwargs (excluding None values)
+            if not instance:
+                instance = (
+                    db.query(cls)
+                    .filter_by(
+                        **{
+                            k: v
+                            for k, v in kwargs.items()
+                            if v is not None and k != "id"
+                        }
+                    )
+                    .first()
+                )
+
+        if instance:
+            db.refresh(instance)
 
-        db.commit()
-        db.refresh(instance)
         return instance
 
+    @classmethod
+    @with_db
+    def bulk_upsert(cls, rows: list[dict] = None, db=None, **kwargs):
+        """
+        Performs a bulk upsert into the database using ON DUPLICATE KEY UPDATE.
+
+        Args:
+            rows (list[dict]): List of dictionaries representing rows to upsert
+            db (Session): SQLAlchemy DB session
+            **kwargs: Column-wise keyword arguments (field_name=[...]) for backwards compatibility
+        """
+        # Handle both new format (rows) and legacy format (kwargs)
+        if rows is None and kwargs:
+            # Legacy format: convert column-wise kwargs to row-wise list of dicts
+            value_lengths = [len(v) for v in kwargs.values()]
+            if not value_lengths or len(set(value_lengths)) != 1:
+                raise ValueError(
+                    "All field values must be non-empty lists of the same length."
+                )
+            rows = [dict(zip(kwargs.keys(), row)) for row in zip(*kwargs.values())]
+
+        if not rows:
+            return 0
+
+        BATCH_SIZE = 200
+        total_affected = 0
+
+        for i in range(0, len(rows), BATCH_SIZE):
+            batch = rows[i : i + BATCH_SIZE]
+            stmt = mysql_insert(cls.__table__).values(batch)
+            stmt = stmt.on_duplicate_key_update(
+                **{key: stmt.inserted[key] for key in batch[0] if key != "id"}
+            )
+            result = db.execute(stmt)
+            total_affected += result.rowcount
+
+        db.commit()
+        return total_affected
+
     @classmethod
     @with_db
     def delete(cls, id: int, db=None):