refactor: generalize recommendation pipeline — candidate → rank → render stages #80

New Issue

alvis · 2026-04-16T15:25:11Z

alvis commented

2026-04-16 15:25:11 +00:00

Motivation

The current recommender mixes candidate fetching, feature extraction, policy selection, and tip serving in one function. As we add AI-generated tips, multiple signal sources, and more policies, this becomes unmaintainable.

Design

Split POST /recommend into a staged pipeline:

1. CandidateGenerator[] → Signal[]     (pluggable sources)
2. FeatureExtractor → FeatureVector[]   (per-candidate features + global context)
3. RankingPolicy → scored candidates    (bandit, ML model, heuristic)
4. TipRenderer → final tip text         (pass-through, LLM polish, template)
5. DeliveryDecision → serve or defer     (timing, quiet hours, fatigue)

Each stage is an interface. Pipeline composition is config-driven.

Tasks

Define CandidateGenerator, FeatureExtractor, RankingPolicy, TipRenderer interfaces
Refactor existing code into these stages (no behavior change)
Pipeline config: which generators, which policy, which renderer
Shadow pipeline support (run two full pipelines, compare outputs)
Metrics per stage (latency, candidate count, score distribution)
ADR for pipeline architecture

## Motivation The current recommender mixes candidate fetching, feature extraction, policy selection, and tip serving in one function. As we add AI-generated tips, multiple signal sources, and more policies, this becomes unmaintainable. ## Design Split `POST /recommend` into a staged pipeline: ``` 1. CandidateGenerator[] → Signal[] (pluggable sources) 2. FeatureExtractor → FeatureVector[] (per-candidate features + global context) 3. RankingPolicy → scored candidates (bandit, ML model, heuristic) 4. TipRenderer → final tip text (pass-through, LLM polish, template) 5. DeliveryDecision → serve or defer (timing, quiet hours, fatigue) ``` Each stage is an interface. Pipeline composition is config-driven. ## Tasks - [ ] Define `CandidateGenerator`, `FeatureExtractor`, `RankingPolicy`, `TipRenderer` interfaces - [ ] Refactor existing code into these stages (no behavior change) - [ ] Pipeline config: which generators, which policy, which renderer - [ ] Shadow pipeline support (run two full pipelines, compare outputs) - [ ] Metrics per stage (latency, candidate count, score distribution) - [ ] ADR for pipeline architecture

alvis added this to the M2 — AI tips + multi-source signals milestone 2026-04-16 15:25:11 +00:00

alvis closed this issue

2026-04-17 14:22:49 +00:00

alvis referenced this issue from a commit

2026-04-24 15:10:18 +00:00

feat: M2 AI tips — LiteLLM gateway, context assembler, end-to-end generation pipeline

alvis referenced this issue from a commit

2026-05-12 15:37:06 +00:00

chore(m2): close out remaining loose ends (#80, #86, #90)

Sign in to join this conversation.