adaptive-pricing/projects/coulomb-pricing/observatory/models.py

from __future__ import annotations

from dataclasses import dataclass
from decimal import Decimal
from typing import Literal

CostCategory = Literal["fixed", "variable"]
MemberStatus = Literal["active", "churned", "paused"]
PricingModelStatus = Literal["active", "candidate", "retired"]


@dataclass(frozen=True)
class Product:
    id: str
    name: str
    lifecycle_phase: str
    currency: str
    description: str
    active_pricing_model_id: str


@dataclass(frozen=True)
class PricingModel:
    id: str
    name: str
    model_type: str
    lifecycle_phase: str
    currency: str
    access_fee_amount: Decimal
    access_fee_cadence: str
    status: PricingModelStatus


@dataclass(frozen=True)
class CostEntry:
    id: str
    name: str
    category: CostCategory
    amount: Decimal
    currency: str
    cadence: str
    allocation: str


@dataclass(frozen=True)
class RevenueEntry:
    id: str
    period: str
    gross_amount: Decimal
    fees_amount: Decimal
    refunds_amount: Decimal
    net_amount: Decimal
    currency: str
    source: str


@dataclass(frozen=True)
class MembershipRecord:
    id: str
    status: MemberStatus
    joined_at: str
    plan_id: str
    churned_at: str | None = None


@dataclass(frozen=True)
class EconomicsSnapshot:
    period: str
    currency: str
    active_members: int
    monthly_revenue: Decimal
    monthly_cost: Decimal
    cost_per_member: Decimal
    gross_margin: Decimal
    gross_margin_pct: Decimal
    pricing_model_count: int
    revenue_source: str