• 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

• 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

"Based on your preferences, I recommend Parasite."

"Given your appreciation for dark comedies with complex characters, Parasite would be a strong match. It has that same outsider perspective you responded to in The Lobster, but with sharper social commentary."

• "That's not quite right" → Ask what's missing
• "Tell me more about X" → Call

  /v1/explain

• "Something different" → Adjust constraints and re-query

"preferences": [
  "dark comedies",
  "complex anti-heroes",
  "slow-burn narratives",
  "dislikes: jump scares",
  "dislikes: predictable endings"
]

• "I love X" → positive preference
• "I can't stand X" → negative preference (prefix with "dislikes:")
• "Something like X" → reference point
• "Not too X" → constraint or negative preference

"history": [
  {"item": "The Grand Budapest Hotel", "rating": 5},
  {"item": "Transformers", "rating": 1},
  {"item": "Moonlight", "rating": 4}
]

• Include both positive and negative examples
• Maximum 50 items (API limit)
• More recent items are weighted higher
• Include item identifiers when available (IMDB ID, etc.)

• Genre preferences (and anti-preferences)
• Pacing preferences (slow burn vs. action-packed)
• Era preferences (classic, modern, contemporary)
• Language/subtitle comfort
• Mood they're seeking

{
  "max_length_minutes": 120,
  "release_year_min": 2010,
  "exclude_genres": ["horror", "musical"],
  "languages": ["en", "fr"],
  "streaming_services": ["netflix", "hulu"]
}

• Cuisine preferences and adventurousness
• Price sensitivity
• Dietary restrictions (must capture accurately)
• Occasion context (date night, business, casual)
• Ambiance preferences

{
  "location": {"lat": 37.7749, "lng": -122.4194, "radius_miles": 5},
  "price_range": [2, 3],
  "dietary": ["vegetarian-options"],
  "open_now": true
}

• Use case and context
• Quality vs. price tradeoff
• Brand affinities and aversions
• Feature priorities
• Aesthetic preferences

{
  "max_price": 500,
  "category": "headphones",
  "brand_exclude": ["beats"],
  "features_required": ["noise-cancelling", "wireless"]
}

• Travel style (adventure, relaxation, cultural)
• Comfort level with unfamiliarity
• Activity preferences
• Social context (solo, couple, family)
• Previous destinations (loved and disliked)

{
  "budget_per_day": 200,
  "dates": {"start": "2024-06-01", "end": "2024-06-14"},
  "accessibility": ["wheelchair-accessible"],
  "climate": "warm",
  "visa_free_for": "US"
}

• Career values and priorities
• Work style preferences
• Growth vs. stability orientation
• Culture fit signals
• Skills and experience level

{
  "location": "San Francisco",
  "remote": "hybrid",
  "salary_min": 150000,
  "experience_level": "senior",
  "company_size": ["startup", "mid"]
}

"This is a strong match for you. [Item] aligns well with your preference for [specific trait]."

"[Item] should work well. It has [positive trait], though it's [caveat] which might not be exactly what you're looking for."

"This one's a bit of a stretch, but [Item] might surprise you. It's [trait], which you haven't explicitly mentioned, but based on [pattern] you might appreciate it."

Generally omit, or: "If you're feeling adventurous, [Item] is quite different from your usual preferences, but [reason for including]."

1. The match - Why this fits their stated preferences
2. The connection - How it relates to items they've liked
3. The caveat - Any potential misalignment (if applicable)

/v1/explain

POST /v1/explain
{
  "vertical": "movies",
  "item": "Parasite",
  "context": { /* same context */ }
}

"What about that recommendation missed the mark? Too [X]? Not enough [Y]?"

"Let me try a different angle. If we set aside [previous focus], what are you actually in the mood for?"

• Formative experiences that shape taste
• Emotional patterns that resonate in content
• Identity themes (agency, communion, redemption)

• Core priorities that should be reflected in recommendations
• What makes something feel "right"

• Patterns that might influence reception
• Topics or themes to handle carefully

1. Use elicitation skill to understand the person
2. Summarize findings in profile text
3. Call recommendation API with rich context
4. Present recommendations that connect to their story

429 Too Many Requests

• Check

  Retry-After

  header for wait time
• Queue requests if hitting limits
• Consider caching frequent queries

401 Unauthorized

• Verify API key is set correctly
• Check key hasn't expired
• Ensure key has appropriate permissions

500+

• Implement exponential backoff
• Have fallback behavior (graceful degradation)
• Log for debugging

• API Reference - Full endpoint documentation, parameters, responses
• Context Patterns - Building effective recommendation context
• Presentation Patterns - Confidence interpretation, explanation structure