spb/ai-atlas

1"""Event semantics — deterministic, database-free rules shared by the writer and `aia canonicalize events`.23Three clocks on every change event:4    occurred_at  = coalesce(effective_at, observed_at)   when the thing happened (release date, price effective date)5    observed_at                                          when a connector saw it6    recorded_at                                          when the row was written78`is_backfill` separates *history being loaded* from *news*: the "+N in 24 h" counters, /changes and the pulse feed only count live9(non-backfill) events; timelines and /asof use every event.10"""11from __future__ import annotations1213from datetime import datetime, timedelta14from typing import Any1516BACKFILL_LAG_DAYS = 317RELEASE_LIKE = {"RELEASE", "ANNOUNCEMENT", "NEW_MODEL", "VERSION_RELEASED"}181920def classify_backfill(event_type: str, effective_at: datetime | None, observed_at: datetime, *, is_first_run: bool = False,21                      entity_first_seen: datetime | None = None) -> bool:22    """True when the event describes something that happened well before we observed it.2324    * `effective_at` more than BACKFILL_LAG_DAYS before `observed_at` → backfill (an old release date being loaded);25    * the connector run is the connector's first successful run → backfill (initial corpus, not news);26    * NEW_* events for an entity whose first-seen hint (release/publication date) predates observation by more than the lag → backfill.27    """28    if is_first_run:29        return True30    lag = timedelta(days=BACKFILL_LAG_DAYS)31    if effective_at is not None and observed_at is not None and _aware(effective_at) < _aware(observed_at) - lag:32        return True33    if event_type.startswith("NEW_") and entity_first_seen is not None and observed_at is not None and _aware(entity_first_seen) < _aware(observed_at) - lag:34        return True35    return False363738def group_key_for(event_type: str, entity_id: str | None, effective_at: datetime | None, observed_at: datetime | None) -> str | None:39    """One release seen in several documents (blog post, docs page, hub listing, provider listing) groups under one key per entity × month."""40    if event_type not in RELEASE_LIKE or not entity_id:41        return None42    when = effective_at or observed_at43    if when is None:44        return None45    return f"release:{entity_id}:{when.strftime('%Y-%m')}"464748def _aware(dt: datetime) -> datetime:49    from datetime import UTC5051    return dt if dt.tzinfo is not None else dt.replace(tzinfo=UTC)525354# ---------------------------------------------------------------------------------------------- importance (0 minor … 3 major)55def _num(v: Any) -> float | None:56    if isinstance(v, bool):57        return None58    if isinstance(v, (int, float)):59        return float(v)60    if isinstance(v, str):61        try:62            return float(v.replace(",", ""))63        except ValueError:64            return None65    return None666768def _price_change_ratio(old: Any, new: Any) -> float:69    """Largest relative move among input/output per-million prices (0 when unknown)."""70    if not isinstance(old, dict) or not isinstance(new, dict):71        a, b = _num(old), _num(new)72        return abs(b - a) / a if a and b is not None and a > 0 else 0.073    best = 0.074    for k in ("input_per_mtok", "output_per_mtok", "cached_input_per_mtok"):75        a, b = _num(old.get(k)), _num(new.get(k))76        if a is not None and b is not None and a > 0:77            best = max(best, abs(b - a) / a)78        elif a in (None, 0) and b:79            best = max(best, 1.0)   # newly priced / free → paid counts as a full move80    return best818283def importance_for(event_type: str, entity_type: str | None, old: Any = None, new: Any = None, *, tier: int = 2, org_model_count: int = 0,84                   openness: str | None = None, leader_change: bool = False, default: int = 2) -> int:85    """Deterministic importance:86        artifact events 0 · model_family events 1 · metadata corrections (PROPERTY_CHANGED) 087        frontier-model release (organisation with ≥ 3 models, source tier ≤ 2) 3 · open-weight release 3 · other NEW_MODEL 288        price change ≥ 50 % → 3, ≥ 20 % → 2, else 1 · context ≥ 5× → 3 (shrink → 1) · deprecation / retirement 3 · benchmark leader change 289    Tier > 2 sources lose one point (never below 0)."""90    et = event_type.upper()91    if entity_type == "artifact":92        return 093    if entity_type == "model_family":94        return min(1, default)95    if et == "PROPERTY_CHANGED":96        return 097    if et == "PRICE_CHANGED":98        ratio = _price_change_ratio(old, new)99        imp = 3 if ratio >= 0.5 else 2 if ratio >= 0.2 else 1100    elif et == "CONTEXT_CHANGED":101        a, b = _num(old), _num(new)102        if a and b and a > 0:103            imp = 3 if b / a >= 5 else 1 if b < a else 2104        else:105            imp = 2106    elif et in ("DEPRECATION_ANNOUNCED", "RETIREMENT_ANNOUNCED"):107        imp = 3108    elif et == "STATUS_CHANGED":109        imp = 3 if str(new).lower() in ("deprecated", "retired", "discontinued") else 2110    elif et == "OPENNESS_CHANGED":111        imp = 3 if str(new).startswith("open") else 2112    elif et == "NEW_MODEL":113        if openness and str(openness).startswith("open"):114            imp = 3115        elif org_model_count >= 3 and tier <= 2:116            imp = 3117        else:118            imp = 2119    elif et in ("BENCHMARK_LEADER_CHANGED",) or (et.startswith("BENCHMARK") and leader_change):120        imp = 2121    else:122        imp = default123    if tier > 2:124        imp -= 1125    return max(0, min(3, imp))126127128__all__ = ["BACKFILL_LAG_DAYS", "RELEASE_LIKE", "classify_backfill", "group_key_for", "importance_for"]129