A deterministic, intent-aware re-ranking engine with a React prototype UI. Demonstrates how contextual intent signals — time of day, viewer profile, energy level, device — can reshape content recommendations without ML, personalization, or randomness.
Prototype — built to demonstrate systems thinking and backend architecture, not a production service.
Interactive UI: https://dist-pied-one-60.vercel.app
- Home: Parent-intent wizard flow with kid browse, content detail, PIN gate
/demo: Interactive re-ranking demo with tweakable signals, multi-platform catalogs, and live scoring formula
Python Backend: Fully implemented with 168 passing tests
Note: The frontend uses mock data and is not connected to the backend API. The backend runs locally via
uvicorn.
Problem: Parents spend ~10 min/day manually filtering content. Streaming recommendations optimize for engagement, not parental intent.
Solution: A re-ranking layer that sits between retrieval and presentation. Parents express context once ("it's bedtime"), and the system adapts — deterministically, explainably, with no ML required.
Key capabilities:
- Rules-first intent translation (keyword mapping, time-of-day inference)
- Soft-constraint re-ranking (intent boosts items but never filters them)
- Multiplier-based scoring with transparent formula display
- Prophecy Agent for time-aware scheduling (auto-switch to bedtime mode at 8 PM)
- Multi-platform support (Streaming, Music, E-Commerce)
- Structured explanations for every ranking decision
- Optional LLM fallback (off by default, env-var gated)
The /demo page is a portfolio-grade interactive demo showing the engine's re-ranking behavior across platforms.
| Feature | Description |
|---|---|
| Platform Tabs | Switch between Streaming, Music, and E-Commerce catalogs (8 items each) |
| Context Presets | 4 presets per platform (e.g., Bedtime, Solo Morning, Family Weekend, Focus Session) |
| Signal Sliders | 5 tweakable signals: Time of Day, Viewer Profile, Energy Intent, Device, Prophecy Schedule |
| Before / After | Side-by-side view showing engagement-only vs. intent-adjusted ranking |
| Scoring Formula | Live code-style display showing the multiplier breakdown for any item |
| Prophecy Agent | Mock scheduling indicator with countdown timer |
The demo uses a multiplier-based scoring formula:
final_score = base_engagement_score
× time_multiplier // time-of-day → calm/active preference
× viewer_multiplier // kids/family/adult content matching
× energy_multiplier // energy intent alignment
× device_multiplier // runtime fit for device size
× prophecy_boost // scheduled preference amplification
+ diversity_penalty // penalizes genre repetition
// Hard constraint
if (maturity === "adult" && viewer === "kids") → BLOCKED (score = 0)
| Screen | Description |
|---|---|
 |
Multi-platform demo with signal sliders and before/after ranking |
 |
Live multiplier breakdown for a selected item |
 |
Music platform with wind-down context |
┌──────────────────────────────────────────────────────────────────────────────┐
│ INTENT ENGINE ARCHITECTURE │
└──────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────┐
│ USER / PARENT UI │
│ Intent Setup · Kid Browse · Demo │
└───────────────┬─────────────────┘
│
┌───────────────▼─────────────────┐
│ CONTEXT SIGNALS │
│ Time · Viewer · Energy · Device │
└───────────────┬─────────────────┘
│
┌─────────────────────┴──────────────────────┐
│ │
┌─────────▼──────────┐ ┌────────────▼───────────┐
│ SIMPLE MODE │ │ ADVANCED MODE │
│ │ │ │
│ IntentTranslator │ │ IntentParser │
│ (keyword mapping) │ │ (text classification) │
│ ↓ │ │ ↓ │
│ IntentRanker │ │ RankingEngine │
│ (soft constraints) │ │ (multi-factor) │
└─────────┬──────────┘ └────────────┬───────────┘
│ │
└─────────────────────┬──────────────────────┘
│
┌───────────────▼─────────────────┐
│ MULTIPLIER SCORING LAYER │
│ │
│ base × time × viewer × energy │
│ × device × prophecy + diversity │
│ │
│ Hard constraints: maturity gates │
└───────────────┬─────────────────┘
│
┌───────────────▼─────────────────┐
│ PROPHECY AGENT │
│ Time-aware intent scheduling │
│ Auto-switch · Shift prediction │
└───────────────┬─────────────────┘
│
┌───────────────▼─────────────────┐
│ RANKED OUTPUT │
│ Items + scores + explanations │
│ + latency breakdown │
└─────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Demo.tsx (page) │
│ State: activePlatform · activeContext · signalOverrides │
│ useMemo: rankWithSignals(catalog, signals) → rankedItems │
├──────────┬──────────────────────────────┬───────────────────────┤
│ LEFT │ CENTER │ RIGHT │
│ │ │ │
│ Context │ ┌─────────┐ ┌────────────┐ │ Signal Sliders │
│ Switcher │ │ Before │ │ After │ │ (5 signals, 0-1) │
│ (vertical│ │ column │ │ column │ │ │
│ 4 cards)│ │(engage- │ │ (intent- │ │ Scoring Formula │
│ │ │ ment) │ │ adjusted) │ │ (live multiplier │
│ Prophecy │ └─────────┘ └────────────┘ │ breakdown) │
│ Agent │ │ │
└──────────┴──────────────────────────────┴───────────────────────┘
▲ PlatformTabs (Streaming · Music · E-Commerce)
intent-engine/
├── backend/ # Python backend (FastAPI + ranking engine)
│ ├── intent_engine/
│ │ ├── schemas.py # Pydantic models (Intent, Item, RankedItem, etc.)
│ │ ├── rules_translator.py # Rules-first intent translator
│ │ ├── simple_ranker.py # Soft-constraint re-ranker
│ │ ├── intent_parser.py # Free-text intent classifier
│ │ ├── ranking_engine.py # Multi-factor ranker with diversity
│ │ ├── prophecy_agent.py # Time-aware intent scheduling
│ │ ├── llm_adapter.py # Optional LLM adapter (OFF by default)
│ │ └── api.py # FastAPI REST API
│ ├── tests/ # 168 tests, all passing
│ ├── scripts/ # Demo scripts
│ └── demo_prophecy.py # Prophecy Agent demo
├── frontend/ # React UI prototype
│ ├── src/
│ │ ├── pages/
│ │ │ └── Demo.tsx # Interactive re-ranking demo page
│ │ ├── components/demo/
│ │ │ ├── PlatformTabs.tsx # Streaming / Music / E-Commerce tabs
│ │ │ ├── ContextSwitcher.tsx # Vertical context preset selector
│ │ │ ├── SignalSliders.tsx # 5 tweakable signal weight sliders
│ │ │ ├── ScoringFormula.tsx # Live multiplier formula display
│ │ │ ├── ProphecyAgent.tsx # Scheduling indicator with countdown
│ │ │ └── ContentCard.tsx # Item card with score badge + hover
│ │ └── data/
│ │ ├── demoPlatforms.ts # 3 catalogs + signal configs + ranking
│ │ └── demoContent.ts # Legacy streaming-only data
│ └── package.json
├── docs/
│ └── screenshots/ # UI screenshots for documentation
└── README.md # This file
cd backend
pip install -r requirements.txt
# Run tests
pytest tests/ -v
# Start API server
uvicorn intent_engine.api:app --reload
# Run demos
python -m scripts.demo_runner
python demo_prophecy.pycd frontend
npm install
npm run devOpens on http://localhost:5173. Visit /demo for the interactive re-ranking demo.
The /rank endpoint accepts a mode field:
| Mode | Pipeline | Use Case |
|---|---|---|
simple |
IntentTranslator + IntentRanker | Lightweight keyword/preference matching |
advanced (default) |
IntentParser + RankingEngine | Multi-factor scoring with diversity guardrails |
Time-aware intent scheduling that predicts and automates intent shifts:
from intent_engine.prophecy_agent import ProphecyAgent, IntentSchedule, TimeContext
from datetime import datetime, time
agent = ProphecyAgent()
agent.add_schedule(IntentSchedule(
time_context=TimeContext.BEDTIME,
start_time=time(20, 0),
end_time=time(22, 0),
intent_template={"energyLevel": 15, "tone": "soothing"},
))
# 15 minutes before bedtime — get a proactive suggestion
suggestion = agent.should_suggest_intent_shift(datetime(2026, 2, 20, 19, 50))Problem: Parents spend 10 min/day manually filtering content for kids.
Solution: Set intent once, auto-switch on schedule — set it and forget it.
Impact: Reducing friction on parent profiles by even 2% churn translates to ~$180M annual revenue opportunity for a platform at Netflix scale.
- Determinism — same input, same output, every time
- Soft constraints — intent re-ranks, never filters
- Explainability — every score has a human-readable reason
- Rules first — no LLM dependency; LLM is optional and off by default
- Safe defaults — unknown input degrades gracefully to base-score ordering
- Safety first — hard constraints (age ratings) apply before any ranking logic
Intent Setup — The parent sets context once: time of day (auto-detected), energy level, and age range. No configuration fatigue — the system infers reasonable defaults, and the parent only overrides what matters. This is the "set it and forget it" entry point.
Curated Home — Content rows are re-ranked by the intent engine. "Top picks for your kids" reflects the active intent — not pure engagement scores. The parent sees curated rows that match their stated context, with energy and age badges on every card for transparency.
Kid Browse — The child's view is a Netflix-style hero + category rows experience. Content is pre-filtered and ranked by the intent layer before the child ever sees it. Categories like "STEM Adventures," "Calm & Bedtime Stories," and "Feelings & Empathy" are dynamically weighted based on the parent's intent — not hard-coded.
Content Detail — Every recommendation is explainable. The "Why we picked this" panel surfaces the ranking rationale: age-appropriate science concepts, encourages curiosity, promotes critical thinking. This builds parental trust — the system isn't a black box.
PIN Gate — Parent controls are gated behind a 4-digit PIN, keeping the child's experience uninterrupted. Simple, familiar pattern — no friction for parents, no access for kids.
Parent Controls — Fine-grained preferences: prioritize educational content, lower stimulation mode, weekly rotation. Session settings include viewing time limits and "end on a calm note" — the system suggests calming content as the session timer winds down. The Trust & Safety card reinforces the value proposition: no ads, no autoplay escalation, content reviewed for age-appropriateness.
Re-Ranking Demo — Streaming / Bedtime — Same 8-item catalog, two columns: engagement-only (left) vs. intent-adjusted (right). At bedtime with a kids viewer profile, Bluey S4 jumps from #8 to #1 (+7 positions). Dark Season 3 (TV-MA) drops to the bottom — the viewer multiplier gates adult content without hard-filtering it. The right panel shows 5 signal sliders that update rankings in real-time: drag any slider and watch items re-sort instantly. The scoring formula box shows the exact multiplier math for the #1 item.
Scoring Formula — Transparent Math — Every ranking decision is decomposable. For Bluey S4: base(0.58) x time(0.91) x viewer(1.20) x energy(0.90) x device(1.10) x prophecy(1.32) = 0.83. No black-box ML — each multiplier maps to a single signal slider. An engineer can trace any ranking anomaly back to exactly which signal caused it. This is the kind of observability that makes debugging recommendation systems tractable at scale.
Music Platform — Wind Down — The same engine works across verticals. Switching to Music with a "Wind Down" context: Sleep Stories Podcast stays #1 (high calm score + prophecy boost), but Morning Jazz moves up past Deep Focus — the time multiplier favors familiar, relaxed content over pure ambient. The architecture is platform-agnostic: swap the catalog and signal configs, keep the same scoring pipeline.
E-Commerce — Baby Shower Gifts — Intent-aware ranking isn't just for media. With viewer set to "kids" for gift-buying context: Organic Baby Blanket and Kids Art Kit jump to the top. Noise-Canceling Headphones and Smart Watch Pro are BLOCKED — adult-maturity items gated by the viewer signal. Board Game Collection (family-friendly) gets a +4 boost. The same multiplier formula drives it: viewer(1.20) for kids items vs. viewer(0.00) for adult items. One engine, three verticals, same transparent math.
Built by Jeremiah Walters (GitHub) — exploring how thoughtful systems design can make streaming better for families.
MIT