o2o-site-AEO/solution/backend/common/cost.py

"""사이트 1건 생성 원가 미터 — **$1 예산을 코드로 강제한다.**

★ 제품 제약: **업소 1곳의 사이트를 만드는 데 드는 외부 API 비용은 $1(1,400원)을 넘으면 안 된다.**
  이 모듈은 그 예산을 "문서에 적힌 목표" 가 아니라 **호출을 막는 가드**로 만든다.

  쓰는 법 — 사이트 1건 = 미터 1개:

      meter = CostMeter(place_id=42)
      meter.guard(Provider.PERPLEXITY, calls=1, tokens=3000)     # 호출 "전" 에 물어본다
      ...실제 호출...
      meter.charge(Provider.PERPLEXITY, calls=1, tokens=3100)    # 호출 "후" 에 실측을 적는다

  `guard()` 가 BudgetExceeded 를 던지면 **그 호출은 하지 않는다.** 이미 쓴 돈은 못 돌려받지만
  다음 호출을 막아 손실이 선형으로 늘어나는 것을 끊는다.

비용 리스크 순서(큰 것부터): Gemini(사진 장수에 비례) > Perplexity(토큰+요청 요금) > Kakao(건당 2원).
"""

from dataclasses import dataclass, field
from enum import Enum

from common.logger import LOG

# ── 예산 ────────────────────────────────────────────────────────
USD_KRW = 1400.0              # 환산 환율. 실제 청구 환율과 다를 수 있다.
SITE_BUDGET_KRW = 1400.0      # ★ 사이트 1건당 상한 = $1
# 예산의 몇 %까지 차면 경고를 남길지. 넘겨도 막지는 않는다 — 막는 건 100% 지점이다.
WARN_RATIO = 0.7


class Provider(Enum):
    PERPLEXITY = "perplexity"
    KAKAO = "kakao"
    GEMINI = "gemini"
    TOUR_API = "tour_api"
    OPEN_METEO = "open_meteo"
    THREADS = "threads"


@dataclass(frozen=True)
class Rate:
    """공급자별 단가(원 기준).

    confirmed=False 는 **아직 공식 단가표로 확인하지 않은 추정치**라는 뜻이다.
    추정치로 예산을 계산하면 "예산 안" 이라는 결론 자체가 추정이 된다 —
    실제 배치를 돌리기 전에 `assert_rates_confirmed()` 로 막는다.
    """

    per_call_krw: float = 0.0       # 호출 1건당 고정비
    per_search_krw: float = 0.0     # 검색 1회당 (Perplexity 는 토큰과 별도 과금)
    per_1k_token_krw: float = 0.0   # 토큰 1,000개당
    per_image_krw: float = 0.0      # 이미지 1장당
    confirmed: bool = False
    source: str = ""


# ── 단가표 ──────────────────────────────────────────────────────
# ★ 확정된 것만 confirmed=True 다. 나머지는 자리만 잡아둔 추정치이므로
#   공식 단가표를 확인해서 교체하기 전에는 실배치를 돌리면 안 된다.
RATES: dict[Provider, Rate] = {
    Provider.THREADS: Rate(confirmed=False, source="공개 과금 미확인 — API_USAGE 5절; 계정 계약비는 별도"),
    # 레포에 확정값이 있다(.env.example): 키워드/카테고리 검색 2원, 좌표 변환 0.5원.
    # 좌표 변환은 per_call 로 따로 세지 않고 호출측이 kakao_coord 로 구분해 넘긴다.
    Provider.KAKAO: Rate(
        per_call_krw=2.0,
        confirmed=True,
        source=".env.example — 키워드/카테고리 검색 2원 (무료 쿼터 초과분)",
    ),
    # Sonar 기본 search_context_size=low: 요청 $5/1K + 입력/출력 각각 $1/1M.
    # 2026-08-28 환산(USD_KRW=1,400)이다. 내부 검색 횟수에는 별도 요금이 없다.
    Provider.PERPLEXITY: Rate(
        per_call_krw=7.0,
        per_1k_token_krw=1.4,
        confirmed=True,
        source="https://docs.perplexity.ai/docs/getting-started/pricing — Sonar low context",
    ),
    # ★ 미확인 — Google AI Studio 단가표 확인 후 교체할 것.
    Provider.GEMINI: Rate(
        per_image_krw=1.0,
        per_1k_token_krw=0.5,
        confirmed=False,
        source="추정치",
    ),
    # 공공데이터·무료.
    Provider.TOUR_API: Rate(confirmed=True, source="공공데이터포털 무료(일 트래픽 제한)"),
    Provider.OPEN_METEO: Rate(confirmed=True, source="무료, 키 불필요"),
}

# 카카오 좌표 변환은 키워드 검색보다 4배 싸다 — 같은 공급자지만 단가가 다르다.
KAKAO_COORD_KRW = 0.5


class BudgetExceeded(Exception):
    """사이트 1건 예산을 넘겼다. 호출측은 **더 호출하지 말고** 작업을 중단한다."""

    def __init__(self, place_id: int | None, spent_krw: float, would_add_krw: float):
        self.place_id = place_id
        self.spent_krw = spent_krw
        self.would_add_krw = would_add_krw
        super().__init__(
            f"사이트 원가 예산 초과 (place_id={place_id}): "
            f"이미 {spent_krw:.1f}원 + 이번 {would_add_krw:.1f}원 > 상한 {SITE_BUDGET_KRW:.0f}원"
        )


class UnconfirmedRate(Exception):
    """추정 단가로 실배치를 돌리려 했다."""


def assert_rates_confirmed(*providers: Provider) -> None:
    """실배치 직전에 호출한다. 추정 단가가 섞여 있으면 막는다.

    ★ 이걸 건너뛰면 "예산 안에 들어온다" 는 결론이 추정 위에 서게 된다.
    """
    bad = [p for p in (providers or tuple(RATES)) if not RATES[p].confirmed]
    if bad:
        names = ", ".join(p.value for p in bad)
        raise UnconfirmedRate(
            f"단가 미확인: {names} — 공식 단가표로 RATES 를 교체한 뒤에 배치를 돌려라"
        )


def estimate_krw(
    provider: Provider,
    *,
    calls: int = 0,
    searches: int = 0,
    tokens: int = 0,
    images: int = 0,
    kakao_coord_calls: int = 0,
) -> float:
    """이번 호출의 원가(원)를 계산한다. 실측이든 예상이든 같은 식을 쓴다."""
    rate = RATES[provider]
    krw = (
        rate.per_call_krw * calls
        + rate.per_search_krw * searches
        + rate.per_1k_token_krw * (tokens / 1000.0)
        + rate.per_image_krw * images
    )
    if provider is Provider.KAKAO:
        krw += KAKAO_COORD_KRW * kakao_coord_calls
    return krw


@dataclass
class CostMeter:
    """사이트 1건(업소 1곳)의 원가 누적기. **미터 1개 = 사이트 1건**이다."""

    place_id: int | None = None
    budget_krw: float = SITE_BUDGET_KRW
    spent_krw: float = 0.0
    by_provider: dict[str, float] = field(default_factory=dict)
    calls: int = 0
    _warned: bool = False

    @property
    def remaining_krw(self) -> float:
        return max(0.0, self.budget_krw - self.spent_krw)

    @property
    def spent_usd(self) -> float:
        return self.spent_krw / USD_KRW

    def guard(self, provider: Provider, **units) -> float:
        """호출 **전** 에 예산을 확인한다. 넘으면 BudgetExceeded — 호출하지 마라.

        돌려주는 값은 이번 호출의 예상 원가(원)다.
        """
        krw = estimate_krw(provider, **units)
        if self.spent_krw + krw > self.budget_krw:
            raise BudgetExceeded(self.place_id, self.spent_krw, krw)
        return krw

    def charge(self, provider: Provider, **units) -> float:
        """호출 **후** 에 실측 사용량을 적는다. 적고 나서 예산을 넘었으면 예외를 던진다.

        ★ 이미 나간 호출은 되돌릴 수 없다 — 예외의 목적은 **다음 호출을 막는 것**이다.
        """
        krw = estimate_krw(provider, **units)
        self.spent_krw += krw
        self.calls += 1
        self.by_provider[provider.value] = self.by_provider.get(provider.value, 0.0) + krw

        if not self._warned and self.spent_krw >= self.budget_krw * WARN_RATIO:
            self._warned = True
            LOG.w(
                f"[cost] place_id={self.place_id} 예산 {WARN_RATIO:.0%} 소진 — "
                f"{self.spent_krw:.1f}/{self.budget_krw:.0f}원"
            )
        if self.spent_krw > self.budget_krw:
            LOG.w(f"[cost] place_id={self.place_id} 예산 초과 — {self.summary()}")
            raise BudgetExceeded(self.place_id, self.spent_krw - krw, krw)
        return krw

    def summary(self) -> str:
        parts = " ".join(f"{k}={v:.1f}원" for k, v in sorted(self.by_provider.items()))
        return (
            f"place_id={self.place_id} 합계={self.spent_krw:.1f}원(${self.spent_usd:.3f}) "
            f"호출={self.calls}건 상한={self.budget_krw:.0f}원 [{parts}]"
        )