Skip to content

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

12.1 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0

"""
Model usage related DataSources.

This file provides two categories of DataSource APIs:
1) DomainStats (pull): `ModelUsageDataSource.read_model_usage()` reads aggregated cumulative
   usage from in-process model instances / shared token trackers. This is used by
   `ModelUsageCollector` which converts cumulative stats into Prometheus Counters via deltas.
   The Service-backed pull snapshot is node-scoped: Account and Cluster trackers are aggregated
   without adding an Account label. Standalone callers without a Service retain Cluster fallback.
2) Event (push): `VLMEventDataSource`, `EmbeddingEventDataSource`, and
   `RerankEventDataSource` emit per-call events.
   These events are published to the shared observability event bus and consumed by metrics
   collectors and Usage/Audit subscribers.

Account attribution for VLM usage is provided by the event-based `openviking_vlm_*` metrics,
which carry the Account context on each call. The pull metrics intentionally remain aggregate.

Note: DataSources are not allowed to write into MetricRegistry directly in this architecture.
They only emit events or expose read APIs. Collectors are the only writers.
"""

from __future__ import annotations

from typing import Any, Callable

from openviking.metrics.core.base import ReadEnvelope

from .base import DomainStatsMetricDataSource, EventMetricDataSource


class ModelUsageDataSource(DomainStatsMetricDataSource):
    """
    DomainStats source for aggregated model usage.

    The return value is intentionally aligned with `TokenUsageTracker.to_dict()`:
    - usage_by_model[model_name].usage_by_provider[provider] contains cumulative counters:
      prompt_tokens, completion_tokens, total_tokens, call_count
    """

    def __init__(self, *, config_provider: Callable[[], Any], service: Any = None) -> None:
        """
        Args:
            config_provider: Fallback provider to obtain OpenVikingConfig when `service` is absent.
            service: Optional server service instance. When provided, we prefer its in-memory
                config to avoid reloading configuration from disk.
        """
        self._config_provider = config_provider
        self._service = service

    def read_model_usage(self) -> ReadEnvelope[dict[str, dict]]:
        """
        Read cumulative model usage for configured model types.

        Returns:
            A dict keyed by model_type: "vlm" / "embedding" / "rerank".
            Each value contains:
            - "available": whether fresh usage data for that type was obtained
            - "usage_by_model": normalized cumulative usage payload, empty when unavailable

        Notes:
            - This method is best-effort: it skips types that are not configured/available.
            - It must not create additional long-lived clients except where unavoidable.
              (Rerank currently uses RerankClient.from_config to access the shared token tracker.)
        """
        config_env = self.safe_read(
            lambda: getattr(self._service, "_config", None) or self._config_provider(),
            default=None,
        )
        if not config_env.ok or config_env.value is None:
            return ReadEnvelope(
                ok=False,
                value={},
                error_type=config_env.error_type,
                error_message=config_env.error_message,
            )
        config = config_env.value

        result: dict[str, dict[str, object]] = {
            "vlm": {"available": False, "usage_by_model": {}},
            "embedding": {"available": False, "usage_by_model": {}},
            "rerank": {"available": False, "usage_by_model": {}},
        }

        try:
            if self._service is None:
                from openviking.config.vlm import ClusterVLMResolver

                vlm = ClusterVLMResolver(lambda: config).get_vlm_sync().get_vlm_instance()
                usage = vlm.get_token_usage()
            else:
                resolver = getattr(self._service, "vlm_resolver", None)
                if resolver is None:
                    raise RuntimeError("Account VLM resolver is not initialized")
                usage = resolver.get_node_token_usage()
            result["vlm"] = {
                "available": True,
                "usage_by_model": _extract_usage_by_model(usage, self),
            }
        except Exception:
            pass

        try:
            from openviking.models.embedder.base import _get_token_tracker

            if self._service is None:
                # Keep the legacy aggregate tracker only for standalone callers
                # that do not provide a Service/AccountEmbeddingProvider.
                usage = _get_token_tracker().to_dict()
            else:
                provider = getattr(self._service, "embedding_provider", None)
                if provider is None:
                    raise RuntimeError("Account embedding provider is not initialized")
                usage = provider.get_total_token_usage()
            result["embedding"] = {
                "available": True,
                "usage_by_model": _extract_usage_by_model(usage, self),
            }
        except Exception:
            pass

        try:
            rerank_cfg = getattr(config, "rerank", None)
            if rerank_cfg is not None and rerank_cfg.is_available():
                from openviking.models.rerank.base import get_shared_rerank_token_usage

                result["rerank"] = {
                    "available": True,
                    "usage_by_model": _extract_usage_by_model(
                        get_shared_rerank_token_usage(),
                        self,
                    ),
                }
        except Exception:
            pass

        return ReadEnvelope(ok=True, value=result)


class VLMEventDataSource(EventMetricDataSource):
    """
    Event datasource for per-call VLM usage events.

    The payload emitted here is intentionally narrow and collector-facing: model identity, token
    counts, latency, and optional account context.
    """

    @staticmethod
    def record_call(
        *,
        provider: str,
        model_name: str,
        duration_seconds: float,
        prompt_tokens: int,
        completion_tokens: int,
        error_code: str = "OK",
        account_id: str | None = None,
        source_type: str | None = None,
    ) -> None:
        """
        Emit one VLM call event with model identity, latency, token usage, error code, and account context.

        The caller is expected to provide already-normalized provider/model identifiers and the
        final token counts that should be reflected in Prometheus usage metrics.
        """
        EventMetricDataSource._emit(
            "vlm.call",
            {
                "provider": str(provider),
                "model_name": str(model_name),
                "duration_seconds": float(duration_seconds),
                "prompt_tokens": int(prompt_tokens),
                "completion_tokens": int(completion_tokens),
                "error_code": str(error_code or "unknown"),
                "account_id": None if account_id is None else str(account_id),
                "source_type": source_type,
            },
        )


class EmbeddingEventDataSource(EventMetricDataSource):
    """
    Event datasource for embedding request outcomes.

    Success and error outcomes are modeled as separate event names so collectors can produce the
    appropriate request, latency, and error-code series without inspecting exception objects.
    """

    @staticmethod
    def record_call(
        *,
        provider: str,
        model_name: str,
        duration_seconds: float,
        prompt_tokens: int,
        completion_tokens: int,
        error_code: str = "OK",
        account_id: str | None = None,
        source_type: str | None = None,
    ) -> None:
        """Emit one embedding provider call with tokens, latency, and optional account context."""
        EventMetricDataSource._emit(
            "embedding.call",
            {
                "provider": str(provider),
                "model_name": str(model_name),
                "duration_seconds": float(duration_seconds),
                "prompt_tokens": int(prompt_tokens),
                "completion_tokens": int(completion_tokens),
                "error_code": str(error_code or "unknown"),
                "account_id": None if account_id is None else str(account_id),
                "source_type": source_type,
            },
        )

    @staticmethod
    def record_success(*, latency_seconds: float, account_id: str | None = None) -> None:
        """
        Emit an embedding success event with the observed end-to-end latency.

        The latency is expected to cover the full embedding workflow segment that the caller wants
        reflected in metrics, not just the raw provider round-trip time.
        """
        EventMetricDataSource._emit(
            "embedding.success",
            {
                "latency_seconds": float(latency_seconds),
                "account_id": None if account_id is None else str(account_id),
            },
        )

    @staticmethod
    def record_error(*, error_code: str, account_id: str | None = None) -> None:
        """
        Emit an embedding error event with a normalized error code label.

        Callers should translate provider- or worker-specific failures into bounded error codes
        before invoking this datasource.
        """
        EventMetricDataSource._emit(
            "embedding.error",
            {
                "error_code": str(error_code or "unknown"),
                "account_id": None if account_id is None else str(account_id),
            },
        )


class RerankEventDataSource(EventMetricDataSource):
    """Event datasource for per-call rerank usage events."""

    @staticmethod
    def record_call(
        *,
        provider: str,
        model_name: str,
        duration_seconds: float,
        prompt_tokens: int,
        completion_tokens: int,
        account_id: str | None = None,
    ) -> None:
        """Emit one rerank provider call with tokens, latency, and optional account context."""
        EventMetricDataSource._emit(
            "rerank.call",
            {
                "provider": str(provider),
                "model_name": str(model_name),
                "duration_seconds": float(duration_seconds),
                "prompt_tokens": int(prompt_tokens),
                "completion_tokens": int(completion_tokens),
                "account_id": None if account_id is None else str(account_id),
            },
        )


def _extract_usage_by_model(token_usage: dict, datasource: DomainStatsMetricDataSource) -> dict:
    """
    Extract and normalize a `usage_by_model` mapping from TokenUsageTracker-like payloads.

    The helper keeps only the counters required by `ModelUsageCollector` and normalizes model and
    provider keys into stable non-empty strings.
    """
    token_usage = datasource.as_dict(token_usage)
    usage_by_model = datasource.as_dict(token_usage.get("usage_by_model"))
    normalized: dict[str, dict] = {}
    for model_name, model_payload in usage_by_model.items():
        model_key = datasource.normalize_str(model_name)
        normalized_model = datasource.as_dict(model_payload)
        usage_by_provider = datasource.as_dict(normalized_model.get("usage_by_provider"))
        normalized_providers: dict[str, dict] = {}
        for provider_name, provider_payload in usage_by_provider.items():
            provider_key = datasource.normalize_str(provider_name)
            provider_dict = datasource.as_dict(provider_payload)
            normalized_providers[provider_key] = {
                "prompt_tokens": datasource.as_int(provider_dict.get("prompt_tokens"), default=0),
                "completion_tokens": datasource.as_int(
                    provider_dict.get("completion_tokens"), default=0
                ),
                "total_tokens": datasource.as_int(provider_dict.get("total_tokens"), default=0),
                "call_count": datasource.as_int(provider_dict.get("call_count"), default=0),
            }
        normalized[model_key] = {
            "usage_by_provider": normalized_providers,
        }
    return normalized