recommendations

Files (4)

• SKILL.md
• api-reference.md · references/
• context-patterns.md · references/
• presentation-patterns.md · references/

SKILL.md (first lines)

# Recommendations

Personalized recommendations through the TasteRay API.

## Goal

When making recommendations or reviewing recommendation-related code—whether API integrations, context building, or presentation logic—**your goal is to achieve a 10/10 score**.

Score all work on a 0-10 scale based on adherence to the principles and techniques in this skill. Provide your assessment as **X/10** with specific feedback on what's working and what needs improvement to reach 10/10.

A 10/10 means the work:
- Embodies the core principle (understanding precedes recommendation)
- Builds rich context before calling the API
- Presents recommendations with personalized explanations
- Handles edge cases gracefully (low confidence, rate limits, errors)
- Avoids all anti-patterns

Iterate until you reach 10/10.

---

## Core Principle

**Understanding precedes recommendation.**

Great recommendations come from deep understanding of the person—their preferences, constraints, history, and context. Never call the API without first building meaningful context from the conversation.

Key insight: A recommendation is only as good as the context that informed it.

---

## API Overview

The TasteRay Recommendation API provides personalized recommendations across multiple verticals.

### Base URL

```
https://api.tasteray.com
```

### Authentication

All requests require an API key in the header:

```
X-API-Key: your-api-key
```

### Core Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/recommend` | POST | Get personalized recommendations |
| `/v1/explain` | POST | Get detailed explanation for a single item |
| `/v1/usage` | GET | Check quota and usage statistics |

See: [API Reference](./references/api-reference.md)

---

## The Recommendation Flow

Every recommendation follows this pattern:

```
1. Build context from conversation
   ↓
2. Call POST /v1/recommend
   ↓
3. Interpret confidence scores
   ↓
4. Present with personalized explanations
   ↓
5. Iterate based on feedback
```

### Step 1: Build Context

Extract from the conversation:

- **preferences**: Explicit likes/dislikes and taste patterns
- **profile**: Psychological profile text (from elicitation skill)
- **constraints**: Hard requirements (budget, dietary, location, etc.)
- **history**: Past items they've liked or disliked

### Step 2: Call the API

```json
POST /v1/recommend
{
  "vertical": "movies",
  "context": {
    "preferences": ["dark comedies", "complex characters"],
    "profile": "Values authenticity and depth. Drawn to stories about outsiders...",
    "constraints": {"max_length_minutes": 120},
    "history": [
      {"item": "Parasite", "rating": 5},
      {"item": "The Lobster", "rating": 4}
    ]
  },
  "count": 5
}
```

### Step 3: Interpret Confidence

| Score | Meaning | Action |
|-------|---------|--------|
| 0.9+ | Strong match | Lead with this recommendation |
| 0.7-0.9 | Good match | Present with confidence |
| 0.5-0.7 | Moderate match | Include caveats, explain why it might not fit |
| <0.5 | Weak match | Omit or explain significant uncertainty |

### Step 4: Present Recommendations

Don't just list items. Personalize the explanation:

**Bad:**

From tasteray/skills, MIT.

More from tasteray/skills