278 lines
4.5 KiB
Markdown
278 lines
4.5 KiB
Markdown
# 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.
|