Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
# 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