Negative feedback and regret

"""Negative feedback and regret: which recommended exposures go with unsubscribes and hides?

Simulates a content recommender over three weeks. Each user (the entity) is served items on
autoplay, feed and search, and gets push and email notifications; every one is an event
with features surface:<s>, category:<c>, optional trait:<clickbait|repeat|off_taste|new_creator>,
and notif:burst on a push that is the 3rd or later push within one hour.

Two regret effects:
  unsubscribe     one-shot (repeatable=False), lag minutes to days
  return_or_hide  repeatable, lag of minutes ("not interested", hide)

Hidden ground truth (per exposure, noisy-OR):
  unsubscribe:    notif:burst 0.05, trait:clickbait 0.02   (plus a small background rate)
  return_or_hide: trait:off_taste 0.15, trait:clickbait 0.08, trait:repeat 0.04
Distractor: surface:autoplay is the most common exposure overall and causes nothing.
Confounder: heavy users get more pushes (so more bursts) and more of everything else.
New-creator items are promoted through push, so trait:new_creator rides along with bursts.

Learning: a regret event with an explicit reason ("not interested because...", an unsubscribe
survey) is feedback on the exposure it names; the rest are observe(); exposures whose window
passes without regret are settled as negative evidence.

Run:
    pip install heapdb
    python 0008-negative-feedback-and-regret.py
"""

from __future__ import annotations

import math
import random
from collections import Counter

from heapdb import ExponentialDecay, HeapDB, LogNormalKernel, format_result

M, H, D = 60.0, 3600.0, 86400.0
SEED = 8
N_USERS = 900
DAYS = 21

TRUTH = {
    "unsubscribe": {"notif:burst": 0.05, "trait:clickbait": 0.02},
    "return_or_hide": {"trait:off_taste": 0.15, "trait:clickbait": 0.08, "trait:repeat": 0.04},
}
SEEDED = ("notif:burst", "trait:clickbait")
BACKGROUND_UNSUB = 0.03          # per user over the period, for reasons outside the stream
LABELED = {"unsubscribe": 0.3, "return_or_hide": 0.4}   # share with an explicit reason
CATEGORIES = ["news", "sports", "music", "cooking", "gaming", "finance"]


def pick_traits(rng: random.Random, push: bool) -> set[str]:
    t = set()
    if rng.random() < 0.06:
        t.add("trait:clickbait")
    if rng.random() < 0.10:
        t.add("trait:repeat")
    if rng.random() < 0.08:
        t.add("trait:off_taste")
    if rng.random() < (0.35 if push else 0.10):   # new creators are promoted via push
        t.add("trait:new_creator")
    return t


def simulate(rng: random.Random):
    """Return (events, outcomes). events: (user, t, type, features, key);
    outcomes: (t, user, effect, key of the triggering exposure or None)."""
    events, outcomes = [], []
    n_heavy = 0
    for u in range(N_USERS):
        user = f"user-{u:04d}"
        heavy = rng.random() < 0.3
        n_heavy += heavy
        evs = []
        for day in range(DAYS):
            # Sessions: heavy users come back more often.
            for _ in range(rng.choice([2, 3, 4]) if heavy else rng.choice([0, 0, 1, 1, 2])):
                ts = day * D + rng.uniform(7, 23) * H
                for j in range(rng.randint(4, 8)):
                    r = rng.random()
                    surface = "autoplay" if r < 0.5 else "feed" if r < 0.92 else "search"
                    feats = {f"surface:{surface}", f"category:{rng.choice(CATEGORIES)}"}
                    feats |= pick_traits(rng, False)
                    evs.append((ts + j * rng.uniform(2, 6) * M, "impression", feats))
            # Pushes: heavy users get more, and sometimes a burst of 3-4 within an hour.
            n_push = rng.choice([1, 2, 2, 3]) if heavy else rng.choice([0, 0, 1])
            burst = rng.random() < (0.25 if heavy else 0.06)
            base = day * D + rng.uniform(9, 20) * H
            times = sorted(base + rng.uniform(0, 8) * H for _ in range(n_push))
            if burst:
                times += [base + k * rng.uniform(8, 18) * M for k in range(rng.choice([3, 4]))]
            times.sort()
            for i, t in enumerate(times):
                feats = {"surface:push", f"category:{rng.choice(CATEGORIES)}"}
                feats |= pick_traits(rng, True)
                if sum(1 for t2 in times[: i + 1] if t - t2 <= H) >= 3:
                    feats.add("notif:burst")
                evs.append((t, "notification", feats))
            if rng.random() < 0.5:
                feats = {"surface:email", f"category:{rng.choice(CATEGORIES)}"}
                evs.append((day * D + 7 * H, "notification", feats | pick_traits(rng, False)))
        evs.sort(key=lambda e: e[0])

        # Outcomes from the hidden truth.
        unsub_t, unsub_key = math.inf, None
        for i, (t, typ, feats) in enumerate(evs):
            for f in sorted(feats):
                if rng.random() < TRUTH["unsubscribe"].get(f, 0.0):
                    when = t + math.exp(rng.gauss(math.log(4 * H), 1.0))
                    if when < unsub_t:
                        unsub_t, unsub_key = when, i
            if typ == "impression":
                for f in sorted(feats):
                    if rng.random() < TRUTH["return_or_hide"].get(f, 0.0):
                        outcomes.append((t + rng.expovariate(math.log(2) / (15 * M)), user,
                                         "return_or_hide", (user, i)))
                        break
        if rng.random() < BACKGROUND_UNSUB:
            when = rng.uniform(0, DAYS * D)
            if when < unsub_t:
                unsub_t, unsub_key = when, None
        keyed = list(enumerate(evs))
        if unsub_t < math.inf:
            outcomes.append((unsub_t, user, "unsubscribe",
                             None if unsub_key is None else (user, unsub_key)))
            # No more pushes or emails once a user has unsubscribed.
            keyed = [(k, e) for k, e in keyed if e[1] != "notification" or e[0] <= unsub_t]
        events += [(user, t, typ, feats, (user, k)) for k, (t, typ, feats) in keyed]
    outcomes = [o for o in outcomes if o[0] <= DAYS * D + 2 * D]
    outcomes.sort(key=lambda o: (o[0], o[1], o[2]))
    return events, outcomes, n_heavy


def make_db() -> HeapDB:
    db = HeapDB(bucket_seconds=6 * H)
    db.register_effect("unsubscribe", LogNormalKernel(median=4 * H, sigma=1.0),
                       default_prior=(1, 9), leak=0.05, repeatable=False)
    db.register_effect("return_or_hide", ExponentialDecay(half_life=15 * M),
                       default_prior=(1, 9), leak=0.05, cause_types={"impression"})
    for eff in db.effects:
        # The user asked for it: search results are rarely regretted.
        db.add_rule(eff, "search-low", lambda e: "surface:search" in e.features, 0.3)
    return db


def main() -> None:
    rng = random.Random(SEED)
    events, outcomes, n_heavy = simulate(rng)
    db = make_db()
    ids = {}
    for user, t, typ, feats, key in events:
        ids[key] = db.insert(user, t, typ, feats).id

    n_fb = Counter()
    for t, user, eff, key in outcomes:
        if key is not None and key in ids and rng.random() < LABELED[eff]:
            # Explicit reason: confirm the exposure it names, then record the occurrence
            # with an infinite leak (no soft credit) so settle() knows the effect happened.
            db.feedback(user, eff, at_time=t, confirmed_event_id=ids[key])
            db.observe(user, eff, t, leak=math.inf)
            n_fb[eff] += 1
        else:
            db.observe(user, eff, t)
    settled = db.settle(DAYS * D + 30 * D)

    n_out = Counter(o[2] for o in outcomes)
    exposure = Counter(f for e in events for f in e[3])
    print("SCENARIO")
    print(f"  {len(events):,} exposures for {N_USERS} users ({n_heavy} heavy) over {DAYS} days")
    for eff in ("unsubscribe", "return_or_hide"):
        print(f"  {eff}: {n_out[eff]} occurrences, {n_fb[eff]} with an explicit reason (feedback), "
              f"{n_out[eff] - n_fb[eff]} observed")
    per = settled.per_effect
    print(f"  settle: exposures whose window passed without regret: {per['unsubscribe']:,} "
          f"(unsubscribe), {per['return_or_hide']:,} (return_or_hide)")

    # One unsubscribe, explained: the first whose top suspect is a burst push.
    pick = None
    for t, user, eff, key in outcomes:
        if eff != "unsubscribe":
            continue
        res = db.top_causes(user, "unsubscribe", t, k=3, explain=True)
        if res.top is not None and "notif:burst" in res.top.event.features \
                and "trait:new_creator" in res.top.event.features:
            pick = (user, t, res)
            break
    print()
    print("ONE UNSUBSCRIBE, EXPLAINED")
    if pick is not None:
        print(format_result(pick[2]))

    print()
    print("ACROSS ALL USERS: links of 'unsubscribe' (top 8)")
    rep = db.link_report("unsubscribe", min_support=20)
    print(f"  {'feature':<22} {'mean':>6} {'90% CI':>15} {'lift':>6} {'exposures':>10}")
    for r in list(rep)[:8]:
        print(f"  {r.feature:<22} {r.strength:>6.3f} [{r.lo:.3f}, {r.hi:.3f}] {r.lift:>6.2f} "
              f"{exposure[r.feature]:>10,}")

    print()
    print("GUARDRAIL TABLE: feature_risk of candidate exposures (population links)")
    candidates = [
        ("push in a burst", "notification", {"surface:push", "notif:burst", "category:news"}),
        ("clickbait feed item", "impression", {"surface:feed", "trait:clickbait", "category:news"}),
        ("new-creator feed item", "impression", {"surface:feed", "trait:new_creator", "category:news"}),
        ("off-taste autoplay", "impression", {"surface:autoplay", "trait:off_taste", "category:news"}),
        ("single push", "notification", {"surface:push", "category:news"}),
        ("autoplay item", "impression", {"surface:autoplay", "category:news"}),
        ("email digest", "notification", {"surface:email", "category:news"}),
    ]
    print(f"  {'candidate':<24} {'unsubscribe':>11} {'hide':>7} {'regret':>7}")
    rows = []
    for name, typ, feats in candidates:
        u = db.feature_risk("unsubscribe", feats, type=typ)
        h = db.feature_risk("return_or_hide", feats, type=typ)   # notifications: not a hide cause
        rows.append((u, name, h, 1 - (1 - u) * (1 - h)))
    for u, name, h, regret in sorted(rows, reverse=True):
        print(f"  {name:<24} {u:>11.3f} {h:>7.3f} {regret:>7.3f}")
    print("  sorted by unsubscribe risk; regret = 1 - (1 - unsubscribe) x (1 - hide);")
    print("  hide is 0 for notifications (only impressions can be hidden)")

    # Single-feature unsubscribe risk over every surface and trait.
    singles = sorted({f for e in events for f in e[3]
                      if f.startswith(("surface:", "trait:", "notif:"))})
    risk = sorted(((db.feature_risk("unsubscribe", {f}), f) for f in singles), reverse=True)
    order = [f for _, f in risk]
    top = exposure.most_common(1)[0][0]
    nc = order.index("trait:new_creator") + 1
    nc_lift = rep.row("trait:new_creator").lift
    print()
    print("CHECK")
    print(f"  unsubscribe risk, {len(order)} surface/trait/notif features: #1 {order[0]} {risk[0][0]:.3f}, "
          f"#2 {order[1]} {risk[1][0]:.3f}, #3 {order[2]} {risk[2][0]:.3f}")
    print(f"  most common exposure {top} ranks #{order.index(top) + 1} of those {len(order)}; "
          f"trait:new_creator (no true effect) ranks #{nc}, lift {nc_lift:.2f}")
    ok = set(order[:2]) == set(SEEDED)
    print(f"  seeded causes {' + '.join(SEEDED)} in top 2: {'yes' if ok else 'NO'}")
    if not ok:
        raise SystemExit(1)


if __name__ == "__main__":
    main()