Skip to content

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

4.6 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Event time-decay validation and engine parameter translation."""

from __future__ import annotations

import math
import re
from dataclasses import dataclass
from datetime import datetime, timezone
from numbers import Real
from typing import Any, Optional

from openviking.utils.time_utils import format_iso8601, parse_iso_datetime

# This curve is an internal ranking contract; it is intentionally not part of
# ov.conf or ovcli.conf.
EVENT_TIME_DECAY_SCALE = "7d"
EVENT_TIME_DECAY_DECAY = 0.5
# Match VikingDB's date_time duration limit: 3000 years of 365 days.
MAX_DURATION_MS = 3000 * 365 * 24 * 60 * 60 * 1000

_DURATION_RE = re.compile(r"^(0|[0-9]+[mhd])$")
_DURATION_MULTIPLIERS_MS = {
    "m": 60 * 1000,
    "h": 60 * 60 * 1000,
    "d": 24 * 60 * 60 * 1000,
}


def parse_duration_ms(value: Any, *, parameter_name: str = "duration") -> int:
    """Parse ``0`` or a non-negative integer duration with m/h/d units."""
    if not isinstance(value, str) or not _DURATION_RE.fullmatch(value):
        raise ValueError(
            f"{parameter_name} must be '0' or a non-negative integer followed by m, h, or d"
        )
    if value == "0":
        return 0
    duration_ms = int(value[:-1]) * _DURATION_MULTIPLIERS_MS[value[-1]]
    if duration_ms > MAX_DURATION_MS:
        raise ValueError(f"{parameter_name} exceeds the maximum duration of 1095000d")
    return duration_ms


def validate_event_time_decay_request(protection: Any) -> None:
    """Validate the optional protection period without changing score thresholds."""
    if protection is None:
        return
    parse_duration_ms(protection, parameter_name="events_time_decay_protection")


def _datetime_to_epoch_ms(value: Any) -> float:
    if isinstance(value, bool):
        raise ValueError("time value must not be boolean")
    if isinstance(value, Real):
        result = float(value)
        if not math.isfinite(result):
            raise ValueError("time value must be finite")
        return result
    if isinstance(value, str):
        value = parse_iso_datetime(value)
    if isinstance(value, datetime):
        if value.tzinfo is None:
            value = value.replace(tzinfo=timezone.utc)
        return value.timestamp() * 1000.0
    raise ValueError("time value must be an epoch millisecond number or ISO 8601 string")


@dataclass(frozen=True)
class TimeDecayFusionSpec:
    """Compiled score-fusion parameters for event time decay."""

    field: str
    origin_ms: float
    offset_ms: int
    scale_ms: int
    decay: float

    def __post_init__(self) -> None:
        # Validate request constants before translating them for each backend.
        if self.scale_ms <= 0:
            raise ValueError("time-decay scale must be greater than zero")
        if not 0.0 < self.decay < 1.0:
            raise ValueError("time-decay decay must be in (0, 1)")
        object.__setattr__(self, "origin_ms", _datetime_to_epoch_ms(self.origin_ms))


def build_time_decay_fusion_spec(
    *,
    protection: str,
    origin: Optional[datetime] = None,
    field: str = "updated_at",
) -> TimeDecayFusionSpec:
    """Compile the fixed event time-decay curve for one retrieval request."""
    return TimeDecayFusionSpec(
        field=field,
        origin_ms=origin or datetime.now(timezone.utc),
        offset_ms=parse_duration_ms(protection, parameter_name="events_time_decay_protection"),
        scale_ms=parse_duration_ms(EVENT_TIME_DECAY_SCALE, parameter_name="time-decay scale"),
        decay=EVENT_TIME_DECAY_DECAY,
    )


def build_time_decay_post_process_ops(
    *,
    protection: str,
    origin: Optional[datetime] = None,
    field: str = "updated_at",
) -> list[dict[str, Any]]:
    """Build the fixed VikingDB score-fusion operator for event results."""
    protection_ms = parse_duration_ms(protection, parameter_name="events_time_decay_protection")
    addition = {
        "factor": 1,
        "base_value_from": "decay_func",
        "field": field,
        "func": "exp",
        "origin": format_iso8601(origin or datetime.now(timezone.utc)),
        "scale": EVENT_TIME_DECAY_SCALE,
        "decay": EVENT_TIME_DECAY_DECAY,
    }
    # VikingDB defaults an omitted offset to zero but rejects explicit zero
    # durations (including "0m", "0h", and "0d").
    if protection_ms > 0:
        addition["offset"] = protection

    return [
        {
            "op": "score_fusion",
            "fusion_by": "multiply",
            "normalize_for_origin_score": {"enable": False},
            "normalize_for_addition_score": {"enable": False},
            "addition_score": [addition],
        }
    ]