recommender/CONTEXT.md

TV Show Recommendation System (Self-Hosted, Multi-Agent)

🎯 Purpose

This document provides complete context for AI agents and developers to build and evolve a local, self-hosted TV show recommendation system.

The system is designed to:

• Prioritize current user intent over historical behavior
• Use multi-agent architecture
• Generate, evaluate, and organize recommendations
• Handle 50–100 candidate series per request

---

🧠 Core Principles

1. Context over history

   • Do NOT persist long-term taste profiles
   • Every request must be evaluated independently

2. Generation ≠ Evaluation

   • Candidate generation and ranking must be separated

3. High recall → aggressive filtering

   • Generate many candidates (50–100)
   • Filter and rank later

4. Structured communication between agents

   • All agents must exchange structured data (JSON-like)

5. Deterministic where possible

   • Interpretation and ranking should be consistent

---

🏗️ System Overview

User Input
   ↓
[1] Interpreter Agent
   ↓
[2] Retrieval Agent
   ↓
[3] Ranking Agent
   ↓
[4] Curator Agent

---

1. 🧾 Interpreter Agent

Goal

Convert raw user input into structured data.

Input

Free-form user text describing:

• Liked series
• Disliked series
• Preferences (themes, tone, characters)
• Constraints (things to avoid)

Output Schema

{
  "liked": ["string"],
  "disliked": ["string"],
  "themes": ["string"],
  "character_preferences": ["string"],
  "tone": ["string"],
  "avoid": ["string"]
}

Requirements

• Normalize terminology (e.g., "spy" → "espionage")
• Infer implicit preferences
• Detect contradictions
• Be deterministic (low temperature)

---

2. 🔎 Retrieval Agent

Goal

Generate a large and diverse pool (50–100) of candidate TV series.

Strategy: LLM Generation

• Generate candidate series from structured input
• Focus on diversity and coverage (high LLM temperature)

Output Schema

[
  {
    "title": "string",
    "metadata": {
      "themes": [],
      "tone": [],
      "tags": []
    }
  }
]

Constraints

• Do NOT use external APIs
• Favor recall over precision

---

3. ⚖️ Ranking Agent

Goal

Categorize candidates into 4 confidence levels using relative comparison.

Categories

• Definitely Like
• Might Like
• Questionable
• Will Not Like

Method

Step 1: Pre-filter

• Remove obvious mismatches
• Enforce "avoid" constraints

Step 2: Pairwise Comparison

• Compare candidates relative to each other and input

Step 3: Tagging

• Assign each show to one of the four categories

Output Schema

{
  "definitely_like": ["title"],
  "might_like": ["title"],
  "questionable": ["title"],
  "will_not_like": ["title"]
}

Requirements

• Keep logic simple and consistent
• Be deterministic (low temperature)

---

4. 🎯 Curator Agent

Goal

Produce a clean, user-facing recommendation output.

Responsibilities

• Group series by category
• Provide short explanations
• Ensure readability

Output Example

Definitely Like:
- Show A → reason

Might Like:
- Show B → reason

---

🔁 Feedback Loop (Re-Ranking Only)

Goal

Improve ranking without storing long-term user preferences.

Inputs

• External summaries, reviews, or insights
• User-provided feedback from other sources

Behavior

• Adjust ranking dynamically
• Re-rank existing candidates
• Do NOT persist user taste

---

⚙️ Agent Configuration

Temperature Guidelines

• Interpreter: Low
• Retrieval: Medium/High
• Ranking: Low
• Curator: Medium

Rules

• Agents must be stateless
• Pass all required context explicitly
• No hidden memory

---

🧱 Project Structure

/agents
  interpreter
  retrieval
  ranking
  curator

/pipelines
  recommendation_flow

---

🚫 Non-Goals

• No persistent taste model
• No long-term user profiling

---

🧭 Implementation Notes for AI Agents

When extending or modifying this system:

1. Do NOT introduce long-term memory of user preferences
2. Do NOT merge agent responsibilities
3. Always preserve structured input/output between agents
4. Prefer simplicity over overengineering
5. Ensure ranking remains interpretable and consistent

---

✅ Summary

This system is a stateless, multi-agent recommendation pipeline focused on:

• Strong alignment with current input
• High candidate diversity
• Structured filtering and ranking
• Scalable handling of large candidate sets

The architecture is intentionally simple, modular, and extensible.