# 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

```json
{
  "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

```json
[
  {
    "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

```json
{
  "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.