Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python
14.8 KB
Raw Blame
"""
Token usage tracking service for monitoring LLM API consumption and budget enforcement.
"""

import logging
from datetime import date, datetime, timedelta
from typing import Tuple, Optional, Dict, List

from sqlalchemy import func, extract

from src.database import db
from src.models.token_usage import TokenUsage
from src.models.user import User
from src.utils.localization import format_percent, translate

logger = logging.getLogger(__name__)


class TokenTracker:
    """Service for recording and checking token usage."""

    OPERATION_TYPES = [
        'summarization',
        'chat',
        'title_generation',
        'event_extraction',
        'query_routing',
        'query_enrichment',
        'embedding',
    ]

    # Token magnitudes and per-token costs differ by orders of magnitude
    # between LLM completions and embedding calls, so dashboards must keep
    # them in separate visualizations. Anything in EMBEDDING_OPERATIONS is
    # bucketed apart from LLM usage.
    EMBEDDING_OPERATIONS = frozenset({'embedding'})

    @classmethod
    def is_embedding_op(cls, operation_type):
        return operation_type in cls.EMBEDDING_OPERATIONS

    def record_usage(
        self,
        user_id: int,
        operation_type: str,
        prompt_tokens: int,
        completion_tokens: int,
        total_tokens: int,
        model_name: str = None,
        cost: float = None,
        cached_tokens: int = 0,
        cache_write_tokens: int = 0
    ):
        """
        Record token usage - upserts into daily aggregate.

        Args:
            user_id: User ID who made the request
            operation_type: Type of operation (summarization, chat, etc.)
            prompt_tokens: Number of input tokens
            completion_tokens: Number of output tokens
            total_tokens: Total tokens (prompt + completion)
            model_name: Name of the model used
            cost: API cost if available (e.g., from OpenRouter)
            cached_tokens: Prompt tokens served from a prefix cache (cache reads)
            cache_write_tokens: Prompt tokens written into the cache on this call
        """
        try:
            today = date.today()

            # Find or create today's record for this user/operation
            usage = TokenUsage.query.filter_by(
                user_id=user_id,
                date=today,
                operation_type=operation_type
            ).first()

            if usage:
                # Update existing record
                usage.prompt_tokens += prompt_tokens
                usage.completion_tokens += completion_tokens
                usage.total_tokens += total_tokens
                usage.cached_tokens = (usage.cached_tokens or 0) + (cached_tokens or 0)
                usage.cache_write_tokens = (usage.cache_write_tokens or 0) + (cache_write_tokens or 0)
                usage.request_count += 1
                if cost:
                    usage.cost += cost
                if model_name:
                    usage.model_name = model_name  # Update to latest model used
            else:
                # Create new record
                usage = TokenUsage(
                    user_id=user_id,
                    date=today,
                    operation_type=operation_type,
                    prompt_tokens=prompt_tokens,
                    completion_tokens=completion_tokens,
                    total_tokens=total_tokens,
                    cached_tokens=cached_tokens or 0,
                    cache_write_tokens=cache_write_tokens or 0,
                    request_count=1,
                    model_name=model_name,
                    cost=cost or 0.0
                )
                db.session.add(usage)

            db.session.commit()
            logger.debug(f"Recorded {total_tokens} tokens for user {user_id}, operation {operation_type}")
            return usage

        except Exception as e:
            logger.error(f"Failed to record token usage: {e}")
            db.session.rollback()
            return None

    def get_monthly_usage(self, user_id: int, year: int = None, month: int = None) -> int:
        """Get total tokens used by a user in a given month."""
        if year is None:
            year = date.today().year
        if month is None:
            month = date.today().month

        result = db.session.query(func.sum(TokenUsage.total_tokens)).filter(
            TokenUsage.user_id == user_id,
            extract('year', TokenUsage.date) == year,
            extract('month', TokenUsage.date) == month
        ).scalar()

        return result or 0

    def get_monthly_cost(self, user_id: int, year: int = None, month: int = None) -> float:
        """Get total cost for a user in a given month."""
        if year is None:
            year = date.today().year
        if month is None:
            month = date.today().month

        result = db.session.query(func.sum(TokenUsage.cost)).filter(
            TokenUsage.user_id == user_id,
            extract('year', TokenUsage.date) == year,
            extract('month', TokenUsage.date) == month
        ).scalar()

        return result or 0.0

    def check_budget(self, user_id: int) -> Tuple[bool, float, Optional[str]]:
        """
        Check if user is within budget.

        Returns:
            (can_proceed, usage_percentage, message)
            - can_proceed: False if hard cap (100%) reached
            - usage_percentage: 0-100+
            - message: Warning/error message if applicable
        """
        try:
            user = db.session.get(User, user_id)
            if not user or not user.monthly_token_budget:
                return (True, 0, None)  # No budget = unlimited

            current_usage = self.get_monthly_usage(user_id)
            budget = user.monthly_token_budget
            percentage = (current_usage / budget) * 100

            # In the user's interface language: the exceeded message is
            # shown to them as the error of the blocked request.
            language = user.ui_language
            if percentage >= 100:
                return (False, percentage, translate(
                    'server.budget.tokenExceeded', language,
                    percent=format_percent(percentage, language)))
            elif percentage >= 80:
                return (True, percentage, translate(
                    'server.budget.tokenWarning', language,
                    percent=format_percent(percentage, language)))
            else:
                return (True, percentage, None)

        except Exception as e:
            logger.error(f"Failed to check budget for user {user_id}: {e}")
            # Fail open - allow the request if we can't check
            return (True, 0, None)

    def get_daily_stats(self, days: int = 30, user_id: int = None) -> List[Dict]:
        """Get daily token usage for charts.

        Each entry includes both a combined total and per-bucket totals
        ('llm_tokens'/'llm_cost' vs 'embedding_tokens'/'embedding_cost') so
        dashboards can render the two streams as independent series.
        """
        start_date = date.today() - timedelta(days=days - 1)

        query = db.session.query(
            TokenUsage.date,
            TokenUsage.operation_type,
            func.sum(TokenUsage.total_tokens).label('tokens'),
            func.sum(TokenUsage.cost).label('cost'),
            func.sum(TokenUsage.cached_tokens).label('cached_tokens'),
            func.sum(TokenUsage.cache_write_tokens).label('cache_write_tokens')
        ).filter(TokenUsage.date >= start_date)

        if user_id:
            query = query.filter(TokenUsage.user_id == user_id)

        results = query.group_by(TokenUsage.date, TokenUsage.operation_type).all()

        # Organize by date
        stats = {}
        for r in results:
            date_str = r.date.isoformat()
            if date_str not in stats:
                stats[date_str] = {
                    'date': date_str,
                    'total': 0,
                    'cost': 0.0,
                    'llm_tokens': 0,
                    'llm_cost': 0.0,
                    'embedding_tokens': 0,
                    'embedding_cost': 0.0,
                    'cached_tokens': 0,
                    'cache_write_tokens': 0,
                    'by_operation': {},
                }
            tokens = r.tokens or 0
            cost = r.cost or 0
            stats[date_str]['total'] += tokens
            stats[date_str]['cost'] += cost
            stats[date_str]['cached_tokens'] += r.cached_tokens or 0
            stats[date_str]['cache_write_tokens'] += r.cache_write_tokens or 0
            if self.is_embedding_op(r.operation_type):
                stats[date_str]['embedding_tokens'] += tokens
                stats[date_str]['embedding_cost'] += cost
            else:
                stats[date_str]['llm_tokens'] += tokens
                stats[date_str]['llm_cost'] += cost
            stats[date_str]['by_operation'][r.operation_type] = tokens

        # Fill in missing dates with zeros
        all_dates = []
        current = start_date
        while current <= date.today():
            date_str = current.isoformat()
            if date_str not in stats:
                stats[date_str] = {
                    'date': date_str,
                    'total': 0,
                    'cost': 0.0,
                    'llm_tokens': 0,
                    'llm_cost': 0.0,
                    'embedding_tokens': 0,
                    'embedding_cost': 0.0,
                    'cached_tokens': 0,
                    'cache_write_tokens': 0,
                    'by_operation': {},
                }
            all_dates.append(date_str)
            current += timedelta(days=1)

        return [stats[d] for d in sorted(all_dates)]

    def get_monthly_stats(self, months: int = 12) -> List[Dict]:
        """Get monthly token usage for charts.

        Each month includes both combined totals and per-bucket totals
        (LLM vs embedding) so the two streams can be visualised separately.
        """
        results = db.session.query(
            extract('year', TokenUsage.date).label('year'),
            extract('month', TokenUsage.date).label('month'),
            TokenUsage.operation_type,
            func.sum(TokenUsage.total_tokens).label('tokens'),
            func.sum(TokenUsage.cost).label('cost'),
            func.sum(TokenUsage.cached_tokens).label('cached_tokens'),
            func.sum(TokenUsage.cache_write_tokens).label('cache_write_tokens')
        ).group_by('year', 'month', TokenUsage.operation_type).order_by('year', 'month').all()

        buckets = {}
        for r in results:
            key = (int(r.year), int(r.month))
            if key not in buckets:
                buckets[key] = {
                    'year': key[0],
                    'month': key[1],
                    'tokens': 0,
                    'cost': 0.0,
                    'llm_tokens': 0,
                    'llm_cost': 0.0,
                    'embedding_tokens': 0,
                    'embedding_cost': 0.0,
                    'cached_tokens': 0,
                    'cache_write_tokens': 0,
                }
            tokens = r.tokens or 0
            cost = r.cost or 0
            buckets[key]['tokens'] += tokens
            buckets[key]['cost'] += cost
            buckets[key]['cached_tokens'] += r.cached_tokens or 0
            buckets[key]['cache_write_tokens'] += r.cache_write_tokens or 0
            if self.is_embedding_op(r.operation_type):
                buckets[key]['embedding_tokens'] += tokens
                buckets[key]['embedding_cost'] += cost
            else:
                buckets[key]['llm_tokens'] += tokens
                buckets[key]['llm_cost'] += cost

        # The last N calendar months up to this one, with zeros for months
        # without usage, so charts keep an even axis and the last entry is
        # always the current month (it used to be the last month WITH usage).
        today = date.today()
        out = []
        y, m = today.year, today.month
        for _ in range(max(months, 1)):
            out.append(buckets.get((y, m)) or {
                'year': y, 'month': m, 'tokens': 0, 'cost': 0.0,
                'llm_tokens': 0, 'llm_cost': 0.0, 'embedding_tokens': 0, 'embedding_cost': 0.0,
                'cached_tokens': 0, 'cache_write_tokens': 0,
            })
            y, m = (y, m - 1) if m > 1 else (y - 1, 12)
        return list(reversed(out))

    def get_user_stats(self) -> List[Dict]:
        """Get per-user token usage breakdown for current month."""
        today = date.today()

        results = db.session.query(
            User.id,
            User.username,
            User.monthly_token_budget,
            func.sum(TokenUsage.total_tokens).label('usage'),
            func.sum(TokenUsage.cost).label('cost')
        ).outerjoin(
            TokenUsage,
            (User.id == TokenUsage.user_id) &
            (extract('year', TokenUsage.date) == today.year) &
            (extract('month', TokenUsage.date) == today.month)
        ).group_by(User.id).all()

        return [
            {
                'user_id': r.id,
                'username': r.username,
                'monthly_budget': r.monthly_token_budget,
                'current_usage': r.usage or 0,
                'cost': r.cost or 0,
                'percentage': ((r.usage or 0) / r.monthly_token_budget * 100)
                              if r.monthly_token_budget else 0
            }
            for r in results
        ]

    def get_today_usage(self, user_id: int = None) -> Dict:
        """Get today's token usage, split into LLM and embedding buckets."""
        today = date.today()

        query = db.session.query(
            TokenUsage.operation_type,
            func.sum(TokenUsage.total_tokens).label('tokens'),
            func.sum(TokenUsage.cost).label('cost'),
            func.sum(TokenUsage.cached_tokens).label('cached_tokens'),
            func.sum(TokenUsage.cache_write_tokens).label('cache_write_tokens')
        ).filter(TokenUsage.date == today)

        if user_id:
            query = query.filter(TokenUsage.user_id == user_id)

        rows = query.group_by(TokenUsage.operation_type).all()

        out = {
            'tokens': 0,
            'cost': 0.0,
            'llm_tokens': 0,
            'llm_cost': 0.0,
            'embedding_tokens': 0,
            'embedding_cost': 0.0,
            'cached_tokens': 0,
            'cache_write_tokens': 0,
        }
        for r in rows:
            tokens = r.tokens or 0
            cost = r.cost or 0
            out['tokens'] += tokens
            out['cost'] += cost
            out['cached_tokens'] += r.cached_tokens or 0
            out['cache_write_tokens'] += r.cache_write_tokens or 0
            if self.is_embedding_op(r.operation_type):
                out['embedding_tokens'] += tokens
                out['embedding_cost'] += cost
            else:
                out['llm_tokens'] += tokens
                out['llm_cost'] += cost
        return out


# Singleton instance
token_tracker = TokenTracker()