src/ad_creative_env/models.py

"""Image-model selection + promotion policy (logic; the data lives in config.py)."""

import os

from .config import PINNED_IMAGE_MODEL, PROMOTABLE_MODELS


def resolve_image_model(explicit: str | None = None) -> str:
    """Model slug to generate with: explicit arg > AD_IMAGE_MODEL env > pinned default.

    Called at env construction. AD_IMAGE_MODEL is a MODEL SLUG override (not an API
    key); the key is passed separately to the provider.
    """
    return explicit or os.environ.get("AD_IMAGE_MODEL") or PINNED_IMAGE_MODEL


def is_promotable(slug: str) -> bool:
    """True if the slug is a pinned immutable target eligible for eval promotion.

    Passed to Cache.promote() as the eligibility guard so only allowlisted
    dated/immutable models can be frozen into the reproducible eval tier.
    """
    return slug in PROMOTABLE_MODELS