P3: personalization core — event log + taste engine + section engine + agent pass + API + frontend

- db.py: guarded P3 tables (swipe_events/sections/section_items/taste_profile/
  agent_runs), one-time event seeding from swipes, append_event round math
- taste.py: deterministic taste engine (action x round x recency weights,
  n/(n+3) shrink, ramp w=min(.85,N/60), percentile norm, agent adjustments
  +/-10, points + source-labeled breakdown + tank bands)
- sections.py: compose/read/exhaust/forge — 2 wildcards + <=5 returns
  (<=2 nopes, surprising only) + remainder new, <=4/family, >=3 price
  bands w/ repair, returns maybe>like>nope, last-two-section exclusion,
  ondemand/strict modes
- agentpass.py: mock (deterministic) / live (OpenRouter, one retry) /
  fallback; strict payload schema; --print-summary/--dry-run
- api.py: GET /api/section, POST /api/section/forge, GET /api/trends,
  POST /api/agent/run, POST /api/prefs; P3 payload fields (points, tank,
  slot, round_next, points_breakdown); events stamped with section_id
- frontend: section buffer + progress pill, report screen + forge + mode
  toggle, WILDCARD/SECOND LOOK bands, tank gauges (list + dossier), dossier
  Why-this-rank, real Trends tab, /api/deck fallback for pre-P3 API, sw v2
- selfcheck: 9 new P3 checks (25/25 green)
This commit is contained in:
Torres
2026-11-10 23:16:32 -04:00
parent 8060852b83
commit 04463cadcd
8 changed files with 2504 additions and 26 deletions

View File

@@ -13,14 +13,17 @@ on; frozen in the task brief):
family, score, year, seller_type, extras (array of strings),
decision (null|'like'|'maybe'|'nope'), first_seen}
"""
import datetime
import json
import os
from fastapi import FastAPI, HTTPException, Query
from fastapi.responses import FileResponse, JSONResponse, RedirectResponse
from . import agentpass as agmod
from . import db as dbmod
from . import importer as imp
from . import sections as secmod
ACTIONS = ('like', 'nope', 'maybe')
@@ -73,6 +76,14 @@ def get_conn(app):
return conn
def utcnow():
return datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None)
def live_configured():
return bool(os.environ.get('OPENROUTER_API_KEY'))
def set_pref(conn, key, value):
conn.execute(
"INSERT INTO prefs (key, value) VALUES (?, ?) "
@@ -149,6 +160,23 @@ def build_payload(img_dir):
return _payload
# --- P3 listing payload (additive over the P2 contract) --------------------
def build_p3_payload(img_dir):
base = build_payload(img_dir)
def _payload(conn, engine, row, slot=None, include_breakdown=False):
p = base(conn, row)
p['points'] = engine.points(row['id'])
p['tank'] = engine.tank(row['id'])
p['slot'] = slot
p['round_next'] = engine.round_next(row['id'])
p['points_breakdown'] = (engine.breakdown(row['id'])
if include_breakdown else None)
return p
return _payload
# --- app factory ----------------------------------------------------------
def create_app(db_path, img_dir, state_dir=None):
@@ -166,6 +194,7 @@ def create_app(db_path, img_dir, state_dir=None):
app.state.static_dir = static_dir
app.state.icons_dir = icons_dir
payload = build_payload(app.state.img_dir)
p3_payload = build_p3_payload(app.state.img_dir)
# -- meta -----------------------------------------------------------
@@ -225,6 +254,7 @@ def create_app(db_path, img_dir, state_dir=None):
cur = parse_cursor(cursor)
conn = get_conn(app)
try:
engine = secmod.build_engine(conn, now=utcnow())
if cur is None:
rows = conn.execute(DECK_SELECT + DECK_ORDER + ' LIMIT ?',
(limit,)).fetchall()
@@ -232,7 +262,7 @@ def create_app(db_path, img_dir, state_dir=None):
rows = conn.execute(
DECK_SELECT + cursor_clause() + DECK_ORDER + ' LIMIT ?',
(cur[0], cur[0], cur[1], cur[1], cur[2], limit)).fetchall()
items = [payload(conn, r) for r in rows]
items = [p3_payload(conn, engine, r) for r in rows]
next_cursor = None
remaining = 0
if rows:
@@ -256,6 +286,10 @@ def create_app(db_path, img_dir, state_dir=None):
if not isinstance(listing_id, int) or action not in ACTIONS:
raise HTTPException(status_code=400,
detail='body must be {listing_id:int, action:like|nope|maybe}')
# optional P3: section this verdict happened in (NULL for list edits)
section_id = body.get('section_id')
if not isinstance(section_id, int):
section_id = None
conn = get_conn(app)
try:
row = conn.execute('SELECT id FROM listings WHERE id=?',
@@ -269,11 +303,17 @@ def create_app(db_path, img_dir, state_dir=None):
ON CONFLICT(listing_id) DO UPDATE SET
action=excluded.action, updated_at=excluded.updated_at''',
(listing_id, action, now, now))
# P3: append the learning event (round = prior events + 1)
round_ = dbmod.append_event(conn, listing_id, action, section_id,
now)
conn.commit()
stored = conn.execute(
'SELECT listing_id, action, created_at, updated_at'
' FROM swipes WHERE listing_id=?', (listing_id,)).fetchone()
return dict(stored)
result = dict(stored)
result['round'] = round_
result['section_id'] = section_id
return result
finally:
conn.close()
@@ -307,6 +347,7 @@ def create_app(db_path, img_dir, state_dir=None):
params.append('%' + escaped + '%')
conn = get_conn(app)
try:
engine = secmod.build_engine(conn, now=utcnow())
total = conn.execute(
'SELECT COUNT(*) AS n FROM listings l'
' LEFT JOIN swipes s ON s.listing_id = l.id'
@@ -316,7 +357,8 @@ def create_app(db_path, img_dir, state_dir=None):
' LEFT JOIN swipes s ON s.listing_id = l.id'
' WHERE ' + where + ' ORDER BY ' + LIST_SORTS[sort] +
' LIMIT ? OFFSET ?', params + [limit, offset]).fetchall()
return {'items': [payload(conn, r) for r in rows], 'total': total}
return {'items': [p3_payload(conn, engine, r) for r in rows],
'total': total}
finally:
conn.close()
@@ -324,13 +366,14 @@ def create_app(db_path, img_dir, state_dir=None):
def listing(listing_id: int):
conn = get_conn(app)
try:
engine = secmod.build_engine(conn, now=utcnow())
row = conn.execute(
'SELECT l.*, s.action AS decision FROM listings l'
' LEFT JOIN swipes s ON s.listing_id = l.id'
' WHERE l.id=?', (listing_id,)).fetchone()
if not row:
raise HTTPException(status_code=404, detail='unknown listing')
return payload(conn, row)
return p3_payload(conn, engine, row, include_breakdown=True)
finally:
conn.close()
@@ -357,6 +400,228 @@ def create_app(db_path, img_dir, state_dir=None):
finally:
conn.close()
# -- P3: sections ----------------------------------------------------
def section_state(conn, sec, note=None):
"""Shared body for GET /api/section and POST /api/section/forge."""
now = utcnow()
engine = secmod.build_engine(conn, now=now)
data = secmod.read_section(conn, sec, now)
sec = conn.execute('SELECT * FROM sections WHERE id=?',
(sec['id'],)).fetchone()
mode = get_pref(conn, 'forge_mode', 'ondemand')
items = [p3_payload(conn, engine, r, slot=r['slot'],
include_breakdown=True)
for r in data['items']]
data['items'] = items
data['mode'] = mode
data['can_forge'] = (mode != 'strict'
or secmod.fresh_profile_exists(conn, sec))
data['counts'] = secmod.section_counts(conn, sec)
prof = secmod.latest_profile(conn)
data['read_info'] = {
'events': engine.n_events,
'profile_version': prof['version'] if prof else None,
'profile_source': prof['source'] if prof else None,
'profile_at': prof['created_at'] if prof else None,
}
if note:
data['note'] = note
return data
@app.get('/api/section')
def get_section():
conn = get_conn(app)
try:
sec = secmod.get_current_section(conn)
if sec is None:
# first-ever read composes a cold section
prof = secmod.latest_profile(conn)
engine = secmod.build_engine(conn, prof, now=utcnow())
sec = secmod.compose_section(
conn, engine, size=25,
profile_version=prof['version'] if prof else None,
note='cold compose (first read)')
return section_state(conn, sec)
finally:
conn.close()
@app.post('/api/section/forge')
def forge(body: dict):
size = body.get('size', 25)
if not isinstance(size, int) or not 1 <= size <= 100:
raise HTTPException(status_code=400,
detail='size must be an int 1..100')
conn = get_conn(app)
try:
mode = get_pref(conn, 'forge_mode', 'ondemand')
sec = secmod.get_current_section(conn)
note = None
if mode == 'strict':
if not secmod.fresh_profile_exists(conn, sec):
raise HTTPException(
status_code=409, detail=(
'strict mode: no fresh agent pass since this '
'section — the nightly read provides it'))
note = 'strict: forged on the fresh pass'
else:
# on-demand: agent pass between sections (mock when the
# live key is not configured; live failures fall back)
src = 'live' if live_configured() else 'mock'
res = agmod.run_pass(app.state.db_path, source=src)
note = ('pass %s v%d' % (res['source'],
res['profile_version']))
if res['source'] == 'fallback':
note += ' (agent offline — last read used)'
if sec is not None:
secmod.close_section(conn, sec, utcnow())
prof = secmod.latest_profile(conn)
engine = secmod.build_engine(conn, prof, now=utcnow())
newsec = secmod.compose_section(
conn, engine, size=size,
profile_version=prof['version'] if prof else None,
note=note)
return section_state(conn, newsec, note=note)
finally:
conn.close()
# -- P3: trends ------------------------------------------------------
@app.get('/api/trends')
def trends():
conn = get_conn(app)
try:
prof = secmod.latest_profile(conn)
profile = None
if prof:
payload_prof = {}
try:
payload_prof = json.loads(prof['payload'])
except ValueError:
payload_prof = {}
maker = conn.execute(
'SELECT * FROM agent_runs WHERE profile_version=?'
' ORDER BY id DESC LIMIT 1', (prof['version'],)
).fetchone()
profile = {
'version': prof['version'],
'source': prof['source'],
'created_at': prof['created_at'],
'model': maker['model'] if maker else None,
'lead': payload_prof.get('lead', ''),
'leanings': payload_prof.get('leanings', [])[:8],
'changes': payload_prof.get('changes', []),
'chips': payload_prof.get('chips', []),
}
per = {}
for action in ('like', 'maybe', 'nope'):
per[action] = conn.execute(
'SELECT COUNT(*) AS n FROM swipes WHERE action=?',
(action,)).fetchone()['n']
decided = per['like'] + per['maybe'] + per['nope']
events = conn.execute(
'SELECT listing_id, action FROM swipe_events ORDER BY id'
).fetchall()
prev = {}
flips = 0
for ev in events:
if ev['listing_id'] in prev and prev[ev['listing_id']] != ev[
'action']:
flips += 1
prev[ev['listing_id']] = ev['action']
ret_placed = conn.execute(
"SELECT COUNT(*) AS n FROM section_items "
"WHERE slot='return'").fetchone()['n']
ret_struck = conn.execute(
"""SELECT COUNT(DISTINCT e.listing_id) AS n
FROM swipe_events e
JOIN section_items si
ON si.section_id = e.section_id
AND si.listing_id = e.listing_id
WHERE si.slot='return'""").fetchone()['n']
wild_placed = conn.execute(
"SELECT COUNT(*) AS n FROM section_items "
"WHERE slot='wildcard'").fetchone()['n']
wild_hits = conn.execute(
"""SELECT COUNT(DISTINCT e.listing_id) AS n
FROM swipe_events e
JOIN section_items si
ON si.section_id = e.section_id
AND si.listing_id = e.listing_id
WHERE si.slot='wildcard' AND e.action IN ('like','maybe')"""
).fetchone()['n']
last_run = None
row = conn.execute(
'SELECT * FROM agent_runs ORDER BY id DESC LIMIT 1'
).fetchone()
if row:
last_run = {
'started_at': row['started_at'],
'finished_at': row['finished_at'],
'ok': bool(row['ok']),
'source': row['source'],
'model': row['model'],
'cost_note': row['cost_note'],
'profile_version': row['profile_version'],
}
return {
'profile': profile,
'stats': {
'decided': decided,
'likes': per['like'],
'maybes': per['maybe'],
'nopes': per['nope'],
'hit_rate': (per['like'] / decided) if decided else None,
'hit_rate_plus_maybe': (
(per['like'] + per['maybe']) / decided
if decided else None),
'returns_placed': ret_placed,
'returns_re_struck': ret_struck,
'wildcards_placed': wild_placed,
'wildcards_hit': wild_hits,
'flips': flips,
},
'last_run': last_run,
'cold_start': decided < 10,
'forge_mode': get_pref(conn, 'forge_mode', 'ondemand'),
}
finally:
conn.close()
# -- P3: agent pass trigger ------------------------------------------
@app.post('/api/agent/run')
def agent_run(body: dict):
source = body.get('source', 'mock') if isinstance(body, dict) else 'mock'
if source not in ('mock', 'live'):
raise HTTPException(status_code=400,
detail='source must be mock|live')
if source == 'live' and not live_configured():
raise HTTPException(
status_code=400,
detail='live pass not configured (OPENROUTER_API_KEY unset)')
model = body.get('model') if isinstance(body, dict) else None
res = agmod.run_pass(app.state.db_path, source=source, model=model)
return res
# -- prefs (P3 forge_mode toggle persistence) -------------------------
@app.post('/api/prefs')
def set_pref_endpoint(body: dict):
key = body.get('key')
value = body.get('value')
allowed = {'forge_mode': ('ondemand', 'strict')}
if key not in allowed or value not in allowed[key]:
raise HTTPException(status_code=400,
detail='unknown or invalid pref')
conn = get_conn(app)
try:
set_pref(conn, key, value)
conn.commit()
return {'key': key, 'value': value}
finally:
conn.close()
# -- images + static -------------------------------------------------
@app.get('/img/{listing_id}')