Skip to content

GT tier assignment

The final step in refresh detection. Only runs when needs_gt=True. Decides whether the keyword goes into the urgent tier-1 GT queue or the deferred tier-2 GT queue, given GT's ~1M keywords/month capacity ceiling.

What it is

if needs_gt:
    is_spike = surge_strength > 0 and surge_consistency >= 1.3
    if gt_priority >= 4.0 or is_spike:
        gt_tier = 1            # urgent
    else:
        gt_tier = 2            # deferred

Stored as gt_tier: 1 or gt_tier: 2 inside the refresh-signals JSON. GKP has no tier — it's higher capacity and operates on a single priority queue.

Tier Trigger What extract_gt.py does
1 (urgent) gt_priority ≥ 4.0 OR single-spike consistency (≥ 1.3) Pulled in the next GT extraction cycle, ahead of tier-2
2 (deferred) Otherwise needs-GT Pulled when capacity allows, after tier 1 is drained
(absent) needs_gt=False No GT request — the key is omitted entirely from meta

How it's computed

At processing.py:KB-ANCHOR:refresh-gt-tier-assignment. The is_spike short-circuit predates the explicit consistency multiplier but reuses the same threshold (1.3); both reflect the "single-spike → fast verification" intent from the consistency multiplier decision.

Why this choice

The 4.0 cutoff is capacity-derived. GT extraction is throughput-bound: SearchAPI has a hard rate limit, and the per-cycle GT budget (per src/extract_gt.py KB-ANCHOR:gt-tier-caps-per-run) is sized so that tier-1 keywords drain within one extraction cycle. Picking 4.0 (rather than 5.0 or 3.0) keeps the daily tier-1 population at roughly the size the budget can absorb — higher would starve real urgencies of attention; lower would push the queue past capacity and degrade tier-1 timeliness.

Single-spike override exists because a 1-of-3 surge is a high-suspicion event even at moderate score — the rest of the keyword's signals could be quiet (just a fresh surge against an otherwise stable backdrop), keeping gt_priority below 4.0 numerically, but the suspicion itself is enough to jump the queue. Without this override, single spikes would languish in tier 2 and bot incursions would take a full extra cycle to verify.

Edge cases

  • needs_gt=False — the tier assignment block doesn't execute; the gt_tier key is absent from the meta JSON (not null). Consumers must check for key presence, not value.
  • GKP-only keywords — never carry a gt_tier; the extract_gt.py consumer's filter needs_gt=True AND gt_tier=1 naturally excludes them.
  • Tie-breaking inside tier 1 — gt_tier is binary; ordering inside a tier falls to gt_priority (descending) inside the extractor's queue logic.

See also