intentkit 0.6.13.dev2__py3-none-any.whl → 0.8.17__py3-none-any.whl

intentkit/models/credit.py

@@ -1,14 +1,15 @@
 import logging
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from decimal import ROUND_HALF_UP, Decimal
 from enum import Enum
-from typing import Annotated, Any, Dict, List, Optional, Tuple
+from typing import Annotated, Any
 
 from epyxid import XID
 from fastapi import HTTPException
 from intentkit.models.app_setting import AppSetting
 from intentkit.models.base import Base
 from intentkit.models.db import get_session
+from intentkit.utils.error import IntentKitAPIError
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 from sqlalchemy import (
     ARRAY,
@@ -26,6 +27,9 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 logger = logging.getLogger(__name__)
 
+# Precision constant for 4 decimal places
+FOURPLACES = Decimal("0.0001")
+
 
 class CreditType(str, Enum):
     """Credit type is used in db column names, do not change it."""
@@ -57,6 +61,7 @@ DEFAULT_PLATFORM_ACCOUNT_VOICE = "platform_voice"
 DEFAULT_PLATFORM_ACCOUNT_KNOWLEDGE = "platform_knowledge"
 DEFAULT_PLATFORM_ACCOUNT_FEE = "platform_fee"
 DEFAULT_PLATFORM_ACCOUNT_DEV = "platform_dev"
+DEFAULT_PLATFORM_ACCOUNT_WITHDRAW = "platform_withdraw"
 
 
 class CreditAccountTable(Base):
@@ -114,6 +119,47 @@ class CreditAccountTable(Base):
         String,
         nullable=True,
     )
+    # Total statistics fields
+    total_income = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=False,
+    )
+    total_free_income = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=False,
+    )
+    total_reward_income = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=False,
+    )
+    total_permanent_income = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=False,
+    )
+    total_expense = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=False,
+    )
+    total_free_expense = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=False,
+    )
+    total_reward_expense = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=False,
+    )
+    total_permanent_expense = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=False,
+    )
     created_at = Column(
         DateTime(timezone=True),
         nullable=False,
@@ -123,7 +169,7 @@ class CreditAccountTable(Base):
         DateTime(timezone=True),
         nullable=False,
         server_default=func.now(),
-        onupdate=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(UTC),
     )
 
 
@@ -175,17 +221,74 @@ class CreditAccount(BaseModel):
         Field(default=Decimal("0"), description="Credits added through top-ups"),
     ]
     income_at: Annotated[
-        Optional[datetime],
+        datetime | None,
         Field(None, description="Timestamp of the last income transaction"),
     ]
     expense_at: Annotated[
-        Optional[datetime],
+        datetime | None,
         Field(None, description="Timestamp of the last expense transaction"),
     ]
     last_event_id: Annotated[
-        Optional[str],
+        str | None,
         Field(None, description="ID of the last event that modified this account"),
     ]
+    # Total statistics fields
+    total_income: Annotated[
+        Decimal,
+        Field(
+            default=Decimal("0"),
+            description="Total income from all credit transactions",
+        ),
+    ]
+    total_free_income: Annotated[
+        Decimal,
+        Field(
+            default=Decimal("0"),
+            description="Total income from free credit transactions",
+        ),
+    ]
+    total_reward_income: Annotated[
+        Decimal,
+        Field(
+            default=Decimal("0"),
+            description="Total income from reward credit transactions",
+        ),
+    ]
+    total_permanent_income: Annotated[
+        Decimal,
+        Field(
+            default=Decimal("0"),
+            description="Total income from permanent credit transactions",
+        ),
+    ]
+    total_expense: Annotated[
+        Decimal,
+        Field(
+            default=Decimal("0"),
+            description="Total expense from all credit transactions",
+        ),
+    ]
+    total_free_expense: Annotated[
+        Decimal,
+        Field(
+            default=Decimal("0"),
+            description="Total expense from free credit transactions",
+        ),
+    ]
+    total_reward_expense: Annotated[
+        Decimal,
+        Field(
+            default=Decimal("0"),
+            description="Total expense from reward credit transactions",
+        ),
+    ]
+    total_permanent_expense: Annotated[
+        Decimal,
+        Field(
+            default=Decimal("0"),
+            description="Total expense from permanent credit transactions",
+        ),
+    ]
     created_at: Annotated[
         datetime, Field(description="Timestamp when this account was created")
     ]
@@ -194,14 +297,26 @@ class CreditAccount(BaseModel):
     ]
 
     @field_validator(
-        "free_quota", "refill_amount", "free_credits", "reward_credits", "credits"
+        "free_quota",
+        "refill_amount",
+        "free_credits",
+        "reward_credits",
+        "credits",
+        "total_income",
+        "total_free_income",
+        "total_reward_income",
+        "total_permanent_income",
+        "total_expense",
+        "total_free_expense",
+        "total_reward_expense",
+        "total_permanent_expense",
     )
     @classmethod
     def round_decimal(cls, v: Any) -> Decimal:
         """Round decimal values to 4 decimal places."""
         if isinstance(v, Decimal):
             return v.quantize(Decimal("0.0001"), rounding=ROUND_HALF_UP)
-        elif isinstance(v, (int, float)):
+        elif isinstance(v, int | float):
             return Decimal(str(v)).quantize(Decimal("0.0001"), rounding=ROUND_HALF_UP)
         return v
 
@@ -233,7 +348,11 @@ class CreditAccount(BaseModel):
         )
         result = await session.scalar(stmt)
         if not result:
-            raise HTTPException(status_code=404, detail="Credit account not found")
+            raise IntentKitAPIError(
+                status_code=404,
+                key="CreditAccountNotFound",
+                message="Credit account not found",
+            )
         return cls.model_validate(result)
 
     @classmethod
@@ -294,19 +413,38 @@ class CreditAccount(BaseModel):
         owner_id: str,
         credit_type: CreditType,
         amount: Decimal,
-        event_id: Optional[str] = None,
+        event_id: str | None = None,
     ) -> "CreditAccount":
         """Deduct credits from an account. Not checking balance"""
         # check first, create if not exists
         await cls.get_or_create_in_session(session, owner_type, owner_id)
 
+        # Quantize the amount to ensure proper precision
+        quantized_amount = amount.quantize(FOURPLACES, rounding=ROUND_HALF_UP)
         values_dict = {
-            credit_type.value: getattr(CreditAccountTable, credit_type.value) - amount,
-            "expense_at": datetime.now(timezone.utc),
+            credit_type.value: getattr(CreditAccountTable, credit_type.value)
+            - quantized_amount,
+            "expense_at": datetime.now(UTC),
+            # Update total expense statistics
+            "total_expense": CreditAccountTable.total_expense + quantized_amount,
         }
         if event_id:
             values_dict["last_event_id"] = event_id
 
+        # Update corresponding statistics fields based on credit type
+        if credit_type == CreditType.FREE:
+            values_dict["total_free_expense"] = (
+                CreditAccountTable.total_free_expense + quantized_amount
+            )
+        elif credit_type == CreditType.REWARD:
+            values_dict["total_reward_expense"] = (
+                CreditAccountTable.total_reward_expense + quantized_amount
+            )
+        elif credit_type == CreditType.PERMANENT:
+            values_dict["total_permanent_expense"] = (
+                CreditAccountTable.total_permanent_expense + quantized_amount
+            )
+
         stmt = (
             update(CreditAccountTable)
             .where(
@@ -318,7 +456,11 @@ class CreditAccount(BaseModel):
         )
         res = await session.scalar(stmt)
         if not res:
-            raise HTTPException(status_code=500, detail="Failed to expense credits")
+            raise IntentKitAPIError(
+                status_code=500,
+                key="CreditExpenseFailed",
+                message="Failed to expense credits",
+            )
         return cls.model_validate(res)
 
     @classmethod
@@ -328,8 +470,8 @@ class CreditAccount(BaseModel):
         owner_type: OwnerType,
         owner_id: str,
         amount: Decimal,
-        event_id: Optional[str] = None,
-    ) -> Tuple["CreditAccount", Dict[CreditType, Decimal]]:
+        event_id: str | None = None,
+    ) -> tuple["CreditAccount", dict[CreditType, Decimal]]:
         """Expense credits and return account and credit type.
         We are not checking balance here, since a conversation may have
         multiple expenses, we can't interrupt the conversation.
@@ -348,31 +490,62 @@ class CreditAccount(BaseModel):
         else:
             if account.free_credits > 0:
                 details[CreditType.FREE] = account.free_credits
-                amount_left -= account.free_credits
+                amount_left = (amount_left - account.free_credits).quantize(
+                    FOURPLACES, rounding=ROUND_HALF_UP
+                )
             if amount_left <= account.reward_credits:
                 details[CreditType.REWARD] = amount_left
                 amount_left = Decimal("0")
             else:
                 if account.reward_credits > 0:
                     details[CreditType.REWARD] = account.reward_credits
-                    amount_left -= account.reward_credits
+                    amount_left = (amount_left - account.reward_credits).quantize(
+                        FOURPLACES, rounding=ROUND_HALF_UP
+                    )
                 details[CreditType.PERMANENT] = amount_left
 
         # Create values dict based on what's in details, defaulting to 0 for missing keys
         values_dict = {
-            "expense_at": datetime.now(timezone.utc),
+            "expense_at": datetime.now(UTC),
         }
         if event_id:
             values_dict["last_event_id"] = event_id
 
+        # Calculate total expense for statistics
+        total_expense_amount = Decimal("0")
+
         # Add credit type values only if they exist in details
         for credit_type in [CreditType.FREE, CreditType.REWARD, CreditType.PERMANENT]:
             if credit_type in details:
+                # Quantize the amount to ensure proper precision
+                quantized_amount = details[credit_type].quantize(
+                    FOURPLACES, rounding=ROUND_HALF_UP
+                )
                 values_dict[credit_type.value] = (
-                    getattr(CreditAccountTable, credit_type.value)
-                    - details[credit_type]
+                    getattr(CreditAccountTable, credit_type.value) - quantized_amount
                 )
 
+                # Update corresponding statistics fields
+                total_expense_amount += quantized_amount
+                if credit_type == CreditType.FREE:
+                    values_dict["total_free_expense"] = (
+                        CreditAccountTable.total_free_expense + quantized_amount
+                    )
+                elif credit_type == CreditType.REWARD:
+                    values_dict["total_reward_expense"] = (
+                        CreditAccountTable.total_reward_expense + quantized_amount
+                    )
+                elif credit_type == CreditType.PERMANENT:
+                    values_dict["total_permanent_expense"] = (
+                        CreditAccountTable.total_permanent_expense + quantized_amount
+                    )
+
+        # Update total expense if there was any expense
+        if total_expense_amount > 0:
+            values_dict["total_expense"] = (
+                CreditAccountTable.total_expense + total_expense_amount
+            )
+
         stmt = (
             update(CreditAccountTable)
             .where(
@@ -384,7 +557,11 @@ class CreditAccount(BaseModel):
         )
         res = await session.scalar(stmt)
         if not res:
-            raise HTTPException(status_code=500, detail="Failed to expense credits")
+            raise IntentKitAPIError(
+                status_code=500,
+                key="CreditExpenseFailed",
+                message="Failed to expense credits",
+            )
         return cls.model_validate(res), details
 
     def has_sufficient_credits(self, amount: Decimal) -> bool:
@@ -404,20 +581,51 @@ class CreditAccount(BaseModel):
         session: AsyncSession,
         owner_type: OwnerType,
         owner_id: str,
-        amount: Decimal,
-        credit_type: CreditType,
-        event_id: Optional[str] = None,
+        amount_details: dict[CreditType, Decimal],
+        event_id: str | None = None,
     ) -> "CreditAccount":
         # check first, create if not exists
         await cls.get_or_create_in_session(session, owner_type, owner_id)
         # income
         values_dict = {
-            credit_type.value: getattr(CreditAccountTable, credit_type.value) + amount,
-            "income_at": datetime.now(timezone.utc),
+            "income_at": datetime.now(UTC),
         }
         if event_id:
             values_dict["last_event_id"] = event_id
 
+        # Calculate total income for statistics
+        total_income_amount = Decimal("0")
+
+        # Add credit type values based on amount_details
+        for credit_type, amount in amount_details.items():
+            if amount > 0:
+                # Quantize the amount to ensure 4 decimal places precision
+                quantized_amount = amount.quantize(FOURPLACES, rounding=ROUND_HALF_UP)
+                values_dict[credit_type.value] = (
+                    getattr(CreditAccountTable, credit_type.value) + quantized_amount
+                )
+
+                # Update corresponding statistics fields
+                total_income_amount += quantized_amount
+                if credit_type == CreditType.FREE:
+                    values_dict["total_free_income"] = (
+                        CreditAccountTable.total_free_income + quantized_amount
+                    )
+                elif credit_type == CreditType.REWARD:
+                    values_dict["total_reward_income"] = (
+                        CreditAccountTable.total_reward_income + quantized_amount
+                    )
+                elif credit_type == CreditType.PERMANENT:
+                    values_dict["total_permanent_income"] = (
+                        CreditAccountTable.total_permanent_income + quantized_amount
+                    )
+
+        # Update total income if there was any income
+        if total_income_amount > 0:
+            values_dict["total_income"] = (
+                CreditAccountTable.total_income + total_income_amount
+            )
+
         stmt = (
             update(CreditAccountTable)
             .where(
@@ -438,8 +646,8 @@ class CreditAccount(BaseModel):
         session: AsyncSession,
         owner_type: OwnerType,
         owner_id: str,
-        free_quota: Optional[Decimal] = None,
-        refill_amount: Optional[Decimal] = None,
+        free_quota: Decimal | None = None,
+        refill_amount: Decimal | None = None,
     ) -> "CreditAccount":
         """Get an existing credit account or create a new one if it doesn't exist.
 
@@ -479,9 +687,19 @@ class CreditAccount(BaseModel):
             free_credits=free_quota,
             reward_credits=0.0,
             credits=0.0,
-            income_at=datetime.now(timezone.utc),
+            income_at=datetime.now(UTC),
             expense_at=None,
             last_event_id=event_id if owner_type == OwnerType.USER else None,
+            # Initialize new statistics fields
+            # For USER accounts, initial free_quota counts as income
+            total_income=free_quota,
+            total_free_income=free_quota,
+            total_reward_income=0.0,
+            total_permanent_income=0.0,
+            total_expense=0.0,
+            total_free_expense=0.0,
+            total_reward_expense=0.0,
+            total_permanent_expense=0.0,
         )
         # Platform virtual accounts have fixed IDs, same as owner_id
         if owner_type == OwnerType.PLATFORM:
@@ -515,6 +733,7 @@ class CreditAccount(BaseModel):
                 balance_after=free_quota,
                 base_amount=free_quota,
                 base_original_amount=free_quota,
+                base_free_amount=free_quota,
                 free_amount=free_quota,  # Set free_amount since this is a free credit refill
                 reward_amount=Decimal("0"),  # No reward credits involved
                 permanent_amount=Decimal("0"),  # No permanent credits involved
@@ -530,10 +749,13 @@ class CreditAccount(BaseModel):
                 id=str(XID()),
                 account_id=account.id,
                 event_id=event_id,
-                tx_type=TransactionType.RECHARGE,
+                tx_type=TransactionType.REFILL,
                 credit_debit=CreditDebit.CREDIT,
                 change_amount=free_quota,
                 credit_type=CreditType.FREE,
+                free_amount=free_quota,
+                reward_amount=Decimal("0"),
+                permanent_amount=Decimal("0"),
             )
             session.add(user_tx)
 
@@ -546,6 +768,9 @@ class CreditAccount(BaseModel):
                 credit_debit=CreditDebit.DEBIT,
                 change_amount=free_quota,
                 credit_type=CreditType.FREE,
+                free_amount=free_quota,
+                reward_amount=Decimal("0"),
+                permanent_amount=Decimal("0"),
             )
             session.add(platform_tx)
 
@@ -556,8 +781,8 @@ class CreditAccount(BaseModel):
         cls,
         session: AsyncSession,
         user_id: str,
-        free_quota: Optional[Decimal] = None,
-        refill_amount: Optional[Decimal] = None,
+        free_quota: Decimal | None = None,
+        refill_amount: Decimal | None = None,
         upstream_tx_id: str = "",
         note: str = "",
     ) -> "CreditAccount":
@@ -609,6 +834,10 @@ class CreditAccount(BaseModel):
         if not note:
             raise ValueError("Quota update requires a note explaining the reason")
 
+        # Quantize values to ensure proper precision (4 decimal places)
+        free_quota = free_quota.quantize(FOURPLACES, rounding=ROUND_HALF_UP)
+        refill_amount = refill_amount.quantize(FOURPLACES, rounding=ROUND_HALF_UP)
+
         # Update the free_quota field
         stmt = (
             update(CreditAccountTable)
@@ -650,6 +879,7 @@ class EventType(str, Enum):
     REFUND = "refund"
     ADJUSTMENT = "adjustment"
     REFILL = "refill"
+    WITHDRAW = "withdraw"
     # Sync with RewardType values
     REWARD = "reward"
     EVENT_REWARD = "event_reward"
@@ -794,6 +1024,21 @@ class CreditEventTable(Base):
         default=0,
         nullable=True,
     )
+    base_free_amount = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=True,
+    )
+    base_reward_amount = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=True,
+    )
+    base_permanent_amount = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=True,
+    )
     fee_platform_amount = Column(
         Numeric(22, 4),
         default=0,
@@ -902,34 +1147,34 @@ class CreditEvent(BaseModel):
     ]
     event_type: Annotated[EventType, Field(description="Type of the event")]
     user_id: Annotated[
-        Optional[str], Field(None, description="ID of the user if applicable")
+        str | None, Field(None, description="ID of the user if applicable")
     ]
     upstream_type: Annotated[
         UpstreamType, Field(description="Type of upstream transaction")
     ]
     upstream_tx_id: Annotated[str, Field(description="Upstream transaction ID if any")]
     agent_id: Annotated[
-        Optional[str], Field(None, description="ID of the agent if applicable")
+        str | None, Field(None, description="ID of the agent if applicable")
     ]
     agent_wallet_address: Annotated[
-        Optional[str],
+        str | None,
         Field(None, description="Wallet address of the agent if applicable"),
     ]
     start_message_id: Annotated[
-        Optional[str],
+        str | None,
         Field(None, description="ID of the starting message if applicable"),
     ]
     message_id: Annotated[
-        Optional[str], Field(None, description="ID of the message if applicable")
+        str | None, Field(None, description="ID of the message if applicable")
     ]
     model: Annotated[
-        Optional[str], Field(None, description="LLM model used if applicable")
+        str | None, Field(None, description="LLM model used if applicable")
     ]
     skill_call_id: Annotated[
-        Optional[str], Field(None, description="ID of the skill call if applicable")
+        str | None, Field(None, description="ID of the skill call if applicable")
     ]
     skill_name: Annotated[
-        Optional[str], Field(None, description="Name of the skill if applicable")
+        str | None, Field(None, description="Name of the skill if applicable")
     ]
     direction: Annotated[Direction, Field(description="Direction of the credit flow")]
     total_amount: Annotated[
@@ -941,11 +1186,11 @@ class CreditEvent(BaseModel):
     ]
     credit_type: Annotated[CreditType, Field(description="Type of credits involved")]
     credit_types: Annotated[
-        Optional[List[CreditType]],
+        list[CreditType] | None,
         Field(default=None, description="Array of credit types involved"),
     ]
     balance_after: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(None, description="Account total balance after the transaction"),
     ]
     base_amount: Annotated[
@@ -953,103 +1198,115 @@ class CreditEvent(BaseModel):
         Field(default=Decimal("0"), description="Base amount of credits involved"),
     ]
     base_discount_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(default=Decimal("0"), description="Base discount amount"),
     ]
     base_original_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(default=Decimal("0"), description="Base original amount"),
     ]
     base_llm_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(default=Decimal("0"), description="Base LLM cost amount"),
     ]
     base_skill_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(default=Decimal("0"), description="Base skill cost amount"),
     ]
+    base_free_amount: Annotated[
+        Decimal | None,
+        Field(default=Decimal("0"), description="Base free credit amount"),
+    ]
+    base_reward_amount: Annotated[
+        Decimal | None,
+        Field(default=Decimal("0"), description="Base reward credit amount"),
+    ]
+    base_permanent_amount: Annotated[
+        Decimal | None,
+        Field(default=Decimal("0"), description="Base permanent credit amount"),
+    ]
     fee_platform_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(default=Decimal("0"), description="Platform fee amount"),
     ]
     fee_platform_free_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(
             default=Decimal("0"), description="Platform fee amount from free credits"
         ),
     ]
     fee_platform_reward_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(
             default=Decimal("0"), description="Platform fee amount from reward credits"
         ),
     ]
     fee_platform_permanent_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(
             default=Decimal("0"),
             description="Platform fee amount from permanent credits",
         ),
     ]
     fee_dev_account: Annotated[
-        Optional[str], Field(None, description="Developer account ID receiving fee")
+        str | None, Field(None, description="Developer account ID receiving fee")
     ]
     fee_dev_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(default=Decimal("0"), description="Developer fee amount"),
     ]
     fee_dev_free_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(
             default=Decimal("0"), description="Developer fee amount from free credits"
         ),
     ]
     fee_dev_reward_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(
             default=Decimal("0"), description="Developer fee amount from reward credits"
         ),
     ]
     fee_dev_permanent_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(
             default=Decimal("0"),
             description="Developer fee amount from permanent credits",
         ),
     ]
     fee_agent_account: Annotated[
-        Optional[str], Field(None, description="Agent account ID receiving fee")
+        str | None, Field(None, description="Agent account ID receiving fee")
     ]
     fee_agent_amount: Annotated[
-        Optional[Decimal], Field(default=Decimal("0"), description="Agent fee amount")
+        Decimal | None, Field(default=Decimal("0"), description="Agent fee amount")
     ]
     fee_agent_free_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(default=Decimal("0"), description="Agent fee amount from free credits"),
     ]
     fee_agent_reward_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(default=Decimal("0"), description="Agent fee amount from reward credits"),
     ]
     fee_agent_permanent_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(
             default=Decimal("0"), description="Agent fee amount from permanent credits"
         ),
     ]
     free_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(default=Decimal("0"), description="Free credit amount involved"),
     ]
     reward_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(default=Decimal("0"), description="Reward credit amount involved"),
     ]
     permanent_amount: Annotated[
-        Optional[Decimal],
+        Decimal | None,
         Field(default=Decimal("0"), description="Permanent credit amount involved"),
     ]
-    note: Annotated[Optional[str], Field(None, description="Additional notes")]
+    note: Annotated[str | None, Field(None, description="Additional notes")]
     created_at: Annotated[
         datetime, Field(description="Timestamp when this event was created")
     ]
@@ -1062,6 +1319,9 @@ class CreditEvent(BaseModel):
         "base_original_amount",
         "base_llm_amount",
         "base_skill_amount",
+        "base_free_amount",
+        "base_reward_amount",
+        "base_permanent_amount",
         "fee_platform_amount",
         "fee_platform_free_amount",
         "fee_platform_reward_amount",
@@ -1079,13 +1339,13 @@ class CreditEvent(BaseModel):
         "permanent_amount",
     )
     @classmethod
-    def round_decimal(cls, v: Any) -> Optional[Decimal]:
+    def round_decimal(cls, v: Any) -> Decimal | None:
         """Round decimal values to 4 decimal places."""
         if v is None:
             return None
         if isinstance(v, Decimal):
             return v.quantize(Decimal("0.0001"), rounding=ROUND_HALF_UP)
-        elif isinstance(v, (int, float)):
+        elif isinstance(v, int | float):
             return Decimal(str(v)).quantize(Decimal("0.0001"), rounding=ROUND_HALF_UP)
         return v
 
@@ -1133,6 +1393,7 @@ class TransactionType(str, Enum):
     REFUND = "refund"
     ADJUSTMENT = "adjustment"
     REFILL = "refill"
+    WITHDRAW = "withdraw"
     # Sync with RewardType values
     REWARD = "reward"
     EVENT_REWARD = "event_reward"
@@ -1183,6 +1444,21 @@ class CreditTransactionTable(Base):
         default=0,
         nullable=False,
     )
+    free_amount = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=False,
+    )
+    reward_amount = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=False,
+    )
+    permanent_amount = Column(
+        Numeric(22, 4),
+        default=0,
+        nullable=False,
+    )
     credit_type = Column(
         String,
         nullable=False,
@@ -1223,14 +1499,28 @@ class CreditTransaction(BaseModel):
     change_amount: Annotated[
         Decimal, Field(default=Decimal("0"), description="Amount of credits changed")
     ]
+    free_amount: Annotated[
+        Decimal,
+        Field(default=Decimal("0"), description="Amount of free credits changed"),
+    ]
+    reward_amount: Annotated[
+        Decimal,
+        Field(default=Decimal("0"), description="Amount of reward credits changed"),
+    ]
+    permanent_amount: Annotated[
+        Decimal,
+        Field(default=Decimal("0"), description="Amount of permanent credits changed"),
+    ]
 
-    @field_validator("change_amount")
+    @field_validator(
+        "change_amount", "free_amount", "reward_amount", "permanent_amount"
+    )
     @classmethod
     def round_decimal(cls, v: Any) -> Decimal:
         """Round decimal values to 4 decimal places."""
         if isinstance(v, Decimal):
             return v.quantize(Decimal("0.0001"), rounding=ROUND_HALF_UP)
-        elif isinstance(v, (int, float)):
+        elif isinstance(v, int | float):
             return Decimal(str(v)).quantize(Decimal("0.0001"), rounding=ROUND_HALF_UP)
         return v
 
@@ -1295,7 +1585,7 @@ class CreditPriceTable(Base):
         DateTime(timezone=True),
         nullable=False,
         server_default=func.now(),
-        onupdate=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(UTC),
     )
 
 
@@ -1333,7 +1623,7 @@ class CreditPrice(BaseModel):
         """Round decimal values to 4 decimal places."""
         if isinstance(v, Decimal):
             return v.quantize(Decimal("0.0001"), rounding=ROUND_HALF_UP)
-        elif isinstance(v, (int, float)):
+        elif isinstance(v, int | float):
             return Decimal(str(v)).quantize(Decimal("0.0001"), rounding=ROUND_HALF_UP)
         return v
 
@@ -1410,13 +1700,11 @@ class CreditPriceLog(BaseModel):
         """Round decimal values to 4 decimal places."""
         if isinstance(v, Decimal):
             return v.quantize(Decimal("0.0001"), rounding=ROUND_HALF_UP)
-        elif isinstance(v, (int, float)):
+        elif isinstance(v, int | float):
             return Decimal(str(v)).quantize(Decimal("0.0001"), rounding=ROUND_HALF_UP)
         return v
 
-    note: Annotated[
-        Optional[str], Field(None, description="Note about the modification")
-    ]
+    note: Annotated[str | None, Field(None, description="Note about the modification")]
     modified_by: Annotated[
         str, Field(description="ID of the user who made the modification")
     ]