feat(v1.1): item 9 — batch formula v2 compose rewrite (AMENDS the frozen '<=5 returns' rule)

Allocator now: reserved returns (>=2 whenever eligible stock exists,
role order, surprising-gate on reserved nope slots, cap-4 family) ->
wildcards (2) -> fresh (remainder, capped at 23; wilds draw from the
fresh pool without consuming fresh slots) -> fill returns to size (role
order, <=2 re-nopes total, two-pass family cap: 4 preferred, 8 rescue for
fill slots only). MAX_RETURNS dies; FRESH_CAP=23, MIN_RETURNS=2,
RETURN_FILL_FAMILY_CAP=8 land. Rich day = 21 fresh + 2 second looks +
2 wildcards (the sign-off shape); dry day fills to 25 with returns; 0/0/0
composes an empty section; shortfalls are never padded.

Docs: module docstring, RANKING.md section recipe and DATA-MODEL returns
eligibility rewritten to the v1.1 contract (+ rubric_debug pref noted).

Selfcheck: A1-A8 compose matrix on deterministic staged pools (21/2/2
rich; 5 fresh + 20 SL fill incl. wild-from-fresh derivation; 21/2/2
sign-off; 12-return dry with <=2 nopes + LAST_TWO re-compose; 40 fresh ->
23+2 then the 15 leftover with zero overlap; 0/0/0 empty; family-cap 8
fill rescue; rested/gate-blocked re-nope rules). Pool-honest note: the
spec's A2 '5 fresh + 18 returns + 2 wild' assumed 7 fresh listings —
wildcards are by definition never-swiped, so a 5-fresh day reads 5 fresh
total (3 new + 2 wild) + 20 second looks.
This commit is contained in:
Torres
2026-11-13 13:53:33 -04:00
parent a1455aade4
commit 2160ba6ce8
4 changed files with 352 additions and 25 deletions

View File

@@ -1,8 +1,12 @@
"""Bike-Tinder P3 section engine — compose / read / exhaust / forge.
The deck is one finite SECTION at a time (default 25 cards):
2 wildcards + <=5 returns (<=2 nopes, "surprising" only) + remainder new,
per docs/RANKING.md + docs/DATA-MODEL.md "P3 additions".
v1.1 batch formula (amends the frozen "<=5 returns" rule — one-shot,
re-nope and one-return rules unchanged): every batch targets 25 cards =
fresh first (up to 23 slots) + >=2 second looks whenever eligible stock
exists + the 2 wildcard slots; when fresh < the remainder, second looks
FILL the batch up to 25 (family cap relaxes to 8 for fill returns only).
Fresh exhausted -> returns-only batches; returns exhausted -> fresh-only;
both -> an empty composed section (the loud empty state, item 8).
Pinned order within a section (position 1 first):
new (points DESC) -> returns (maybe > like > nope, points DESC within
@@ -11,10 +15,12 @@ Pinned order within a section (position 1 first):
wildcard stretches sit at the back. (Wildcard placement inside the deck
is not pinned anywhere in the frozen docs — noted in the P3 report.)
Constraints: <=4 per non-NULL family per section; >=3 price bands when the
pool allows (soft repair swaps new-slot items within the final list).
A re-nope (round>=2 nope event) rests an item: no more second looks.
Rounds cap at 2 for influence (taste.py); returns are offered once.
Constraints: <=4 per non-NULL family per section (fill-return slots relax
to <=8); >=3 price bands when the pool allows (soft repair swaps new-slot
items within the final list). <=2 re-nope returns per batch (reserved
nope slots must be "surprising"). A re-nope (round>=2 nope event) rests
an item: no more second looks. Rounds cap at 2 for influence (taste.py);
returns are offered once.
Modes: 'ondemand' (default) — forge runs the agent pass then composes;
'strict' — forge refuses (409) unless a taste_profile strictly newer than
@@ -26,9 +32,11 @@ from . import taste as tastemod
from .taste import NOPE
FAMILY_CAP = 4
MAX_RETURNS = 5
RETURN_FILL_FAMILY_CAP = 8
MAX_RETURN_NOPES = 2
WILDCARDS = 2
FRESH_CAP = 23
MIN_RETURNS = 2
DEFAULT_SIZE = 25
MIN_BANDS = 3
@@ -262,6 +270,11 @@ def compose_section(conn, engine, size=DEFAULT_SIZE, profile_version=None,
Caller closes/reports any prior section first. `engine` scores the
candidates (a TasteEngine over active listings + events + profile).
v1.1 slot math (see module docstring; this amends the frozen "<=5
returns" rule): reserved returns (>=2 when eligible stock exists) ->
wildcards (2) -> fresh (capped at 23) -> fill returns to `size`
(family cap 4 preferred, 8 rescue; <=2 re-nopes total).
"""
import datetime
now = now or datetime.datetime.now(datetime.timezone.utc).replace(
@@ -297,18 +310,18 @@ def compose_section(conn, engine, size=DEFAULT_SIZE, profile_version=None,
top_bands = {tastemod.price_band(r['price_num']) for r in top3
if tastemod.price_band(r['price_num']) is not None}
# 2) returns: maybe > like > nope, points DESC within role; nopes must be
# "surprising" (points >=55 or net-positive family); <=5, <=2 nopes.
# Budget: wildcards keep their 2 slots; returns never push the
# section past `size`.
wanted_rets = min(MAX_RETURNS, max(0, size - min(WILDCARDS, size)))
# 2) reserved returns: the >=2 guarantee (role order maybe > like > nope,
# points DESC within role). Nopes must be "surprising" for RESERVED
# slots only (points >=55 or net-positive family); <=2 re-nope
# returns per batch overall; family cap 4 applies here.
role_order = {'maybe': 0, 'like': 1, 'nope': 2}
ret_ordered = sorted(ret_cands, reverse=True,
key=lambda r: (-role_order.get(r['verdict'], 9),
_points_key(engine, r)))
rets = []
nope_count = 0
for cand in sorted(ret_cands, reverse=True,
key=lambda r: (-role_order.get(r['verdict'], 9),
_points_key(engine, r))):
if len(rets) >= wanted_rets:
for cand in ret_ordered:
if len(rets) >= min(MIN_RETURNS, size):
break
fam = cand['family']
if fam and fam_count.get(fam, 0) >= FAMILY_CAP:
@@ -325,7 +338,8 @@ def compose_section(conn, engine, size=DEFAULT_SIZE, profile_version=None,
if fam:
fam_count[fam] = fam_count.get(fam, 0) + 1
# 3) wildcards: min(2, size), preferred different family AND price band
# 3) wildcards: min(2, remaining slots), preferred different family AND
# price band (existing novel/preferred pick, unchanged)
liked_ids = [r['listing_id'] for r in conn.execute(
"SELECT listing_id FROM swipes WHERE action='like'")]
nov = novelty(rows_by_id, liked_ids,
@@ -339,7 +353,7 @@ def compose_section(conn, engine, size=DEFAULT_SIZE, profile_version=None,
and (tastemod.price_band(r['price_num']) is None
or tastemod.price_band(r['price_num']) not in top_bands)]
n_wilds = min(WILDCARDS, size)
n_wilds = min(WILDCARDS, max(0, size - len(rets)))
wilds = []
avail = sorted([r for r in wild_cands if r['id'] not in picked_ids],
key=wild_key)
@@ -355,12 +369,41 @@ def compose_section(conn, engine, size=DEFAULT_SIZE, profile_version=None,
picked_ids.add(cand['id'])
if fam:
fam_count[fam] = fam_count.get(fam, 0) + 1
n_wilds = len(wilds) # pool shortfall reverts to new
n_wilds = len(wilds) # pool shortfall reverts to fresh/fill
# 4) new fills the remainder of the section (size - returns - wildcards)
want_new = max(0, size - len(rets) - n_wilds)
# 4) fresh fills the remainder (size - returns - wildcards), never
# beyond FRESH_CAP. Wildcards draw from the fresh pool but do NOT
# count against the fresh-slot cap (25 - 0 - 2 = 23 new + 2 wild on
# a returns-free rich day; 21 new + 2 wild + 2 returns when both
# guarantees hold — the sign-off shape). Pool-limited by what the
# wildcard pick left in new_cands; a dry wild pool reverts slots.
want_new = min(size - len(rets) - len(wilds), FRESH_CAP,
max(0, len(new_cands) - len(wilds)))
picked_new = pick_new(engine, new_cands, want_new, fam_count, picked_ids)
# 5) fill returns to size: role order; re-nope cap <=2 total (reserved
# included, no surprising gate here); two-pass family cap — prefer
# <=4, rescue pass relaxes to <=8 for FILL slots only (fresh picks
# and reserved returns keep 4). Deterministic: role order, points
# DESC within role.
for pass_cap in (FAMILY_CAP, RETURN_FILL_FAMILY_CAP):
for cand in ret_ordered:
if len(rets) >= size - len(picked_new) - n_wilds:
break
if cand['id'] in picked_ids:
continue
fam = cand['family']
if fam and fam_count.get(fam, 0) >= pass_cap:
continue
if cand['verdict'] == NOPE and nope_count >= MAX_RETURN_NOPES:
continue
rets.append(cand)
picked_ids.add(cand['id'])
if cand['verdict'] == NOPE:
nope_count += 1
if fam:
fam_count[fam] = fam_count.get(fam, 0) + 1
# final pinned order: new -> returns -> wildcards
ordered = list(picked_new) + rets + wilds