Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

8.3 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""VLM Token usage monitoring data structures"""

import threading
from dataclasses import dataclass, field
from datetime import datetime
from functools import wraps
from typing import Dict, Optional

from openviking.utils.time_utils import format_iso8601, parse_iso_datetime


@dataclass
class TokenUsage:
    """Token usage statistics"""

    prompt_tokens: int = 0
    completion_tokens: int = 0
    total_tokens: int = 0
    call_count: int = 0
    last_updated: datetime = field(default_factory=datetime.now)

    def update(self, prompt_tokens: int, completion_tokens: int) -> None:
        """Update token usage

        Args:
            prompt_tokens: Number of input tokens
            completion_tokens: Number of output tokens
        """
        self.prompt_tokens += prompt_tokens
        self.completion_tokens += completion_tokens
        self.total_tokens = self.prompt_tokens + self.completion_tokens
        self.call_count += 1
        self.last_updated = datetime.now()

    def reset(self) -> None:
        """Reset token usage statistics"""
        self.prompt_tokens = 0
        self.completion_tokens = 0
        self.total_tokens = 0
        self.call_count = 0
        self.last_updated = datetime.now()

    def to_dict(self) -> Dict:
        """Convert to dictionary format

        Returns:
            Token usage dictionary
        """
        return {
            "prompt_tokens": self.prompt_tokens,
            "completion_tokens": self.completion_tokens,
            "total_tokens": self.total_tokens,
            "call_count": self.call_count,
            "last_updated": format_iso8601(self.last_updated),
        }

    def __str__(self) -> str:
        return (
            f"TokenUsage(prompt={self.prompt_tokens}, "
            f"completion={self.completion_tokens}, "
            f"total={self.total_tokens}, "
            f"calls={self.call_count})"
        )


@dataclass
class ModelTokenUsage:
    """Token usage statistics by model"""

    model_name: str
    total_usage: TokenUsage = field(default_factory=TokenUsage)
    usage_by_provider: Dict[str, TokenUsage] = field(default_factory=dict)

    def update(self, provider: str, prompt_tokens: int, completion_tokens: int) -> None:
        """Update token usage for specified provider

        Args:
            provider: Provider name (openai, volcengine)
            prompt_tokens: Number of input tokens
            completion_tokens: Number of output tokens
        """
        # Update total usage
        self.total_usage.update(prompt_tokens, completion_tokens)

        # Update provider usage
        if provider not in self.usage_by_provider:
            self.usage_by_provider[provider] = TokenUsage()

        self.usage_by_provider[provider].update(prompt_tokens, completion_tokens)

    def get_provider_usage(self, provider: str) -> Optional[TokenUsage]:
        """Get token usage for specified provider

        Args:
            provider: Provider name

        Returns:
            TokenUsage object, or None if provider doesn't exist
        """
        return self.usage_by_provider.get(provider)

    def to_dict(self) -> Dict:
        """Convert to dictionary format

        Returns:
            Token usage statistics in dictionary format
        """
        result = {
            "model_name": self.model_name,
            "total_usage": self.total_usage.to_dict(),
            "usage_by_provider": {},
        }

        for provider, usage in self.usage_by_provider.items():
            result["usage_by_provider"][provider] = usage.to_dict()

        return result

    def __str__(self) -> str:
        providers = ", ".join(
            [
                f"{provider}: {usage.total_tokens}"
                for provider, usage in self.usage_by_provider.items()
            ]
        )
        return f"ModelTokenUsage(model={self.model_name}, total={self.total_usage.total_tokens}, providers=[{providers}])"


def _locked(method):
    @wraps(method)
    def call(self, *args, **kwargs):
        with self._lock:
            return method(self, *args, **kwargs)

    return call


def _add_usage(total: TokenUsage, usage: TokenUsage) -> None:
    total.last_updated = (
        max(total.last_updated, usage.last_updated) if total.call_count else usage.last_updated
    )
    total.prompt_tokens += usage.prompt_tokens
    total.completion_tokens += usage.completion_tokens
    total.total_tokens += usage.total_tokens
    total.call_count += usage.call_count


class TokenUsageTracker:
    """Token usage tracker"""

    def __init__(self):
        self._usage_by_model: Dict[str, ModelTokenUsage] = {}
        self._lock = threading.RLock()

    @_locked
    def update(
        self, model_name: str, provider: str, prompt_tokens: int, completion_tokens: int
    ) -> None:
        """Update token usage

        Args:
            model_name: Model name
            provider: Provider name
            prompt_tokens: Number of input tokens
            completion_tokens: Number of output tokens
        """
        if model_name not in self._usage_by_model:
            self._usage_by_model[model_name] = ModelTokenUsage(model_name)

        self._usage_by_model[model_name].update(provider, prompt_tokens, completion_tokens)

    @_locked
    def get_model_usage(self, model_name: str) -> Optional[ModelTokenUsage]:
        """Get token usage for specified model

        Args:
            model_name: Model name

        Returns:
            ModelTokenUsage object, or None if model doesn't exist
        """
        return self._usage_by_model.get(model_name)

    @_locked
    def get_all_usage(self) -> Dict[str, ModelTokenUsage]:
        """Get token usage for all models

        Returns:
            Token usage dictionary by model
        """
        return self._usage_by_model.copy()

    @_locked
    def get_total_usage(self) -> TokenUsage:
        """Get total token usage

        Returns:
            Total token usage statistics
        """
        total = TokenUsage()
        for model_usage in self._usage_by_model.values():
            _add_usage(total, model_usage.total_usage)

        return total

    @_locked
    def reset(self) -> None:
        """Reset all token usage statistics"""
        self._usage_by_model.clear()

    @_locked
    def to_dict(self) -> Dict:
        """Convert to dictionary format

        Returns:
            Token usage statistics in dictionary format
        """
        result = {
            "total_usage": self.get_total_usage().to_dict(),
            "usage_by_model": {},
        }

        for model_name, model_usage in self._usage_by_model.items():
            result["usage_by_model"][model_name] = model_usage.to_dict()

        return result

    @_locked
    def __str__(self) -> str:
        models = ", ".join(
            [
                f"{model}: {usage.total_usage.total_tokens}"
                for model, usage in self._usage_by_model.items()
            ]
        )
        total = self.get_total_usage()
        return f"TokenUsageTracker(total={total.total_tokens}, models=[{models}])"

    @staticmethod
    def merge(*trackers: "TokenUsageTracker") -> "TokenUsageTracker":
        """Merge multiple TokenUsageTracker instances into one.

        Args:
            *trackers: One or more TokenUsageTracker instances to merge

        Returns:
            New TokenUsageTracker with merged data
        """
        merged = TokenUsageTracker()

        for tracker in trackers:
            # Snapshot under the writer's lock; never iterate a live model map.
            for model_name, model_usage in tracker.to_dict()["usage_by_model"].items():
                model = merged._usage_by_model.setdefault(model_name, ModelTokenUsage(model_name))
                for provider_name, counts in model_usage["usage_by_provider"].items():
                    usage = TokenUsage(
                        **{
                            **counts,
                            "last_updated": parse_iso_datetime(counts["last_updated"]).replace(
                                tzinfo=None
                            ),
                        }
                    )
                    provider = model.usage_by_provider.setdefault(provider_name, TokenUsage())
                    _add_usage(provider, usage)
                    _add_usage(model.total_usage, usage)

        return merged