tv shows to tv series

CONTEXT.md

@@ -0,0 +1,277 @@
+# 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.