Opulist

Search Venues

Search for venues using natural language. Handles vibe queries ("moody cocktail bar"), category_slug filters, price tiers, design/atmosphere concepts, and specific food/drink items ("burger", "lobster roll", "craft cocktails"). Menu items are matched against venue menus. IMPORTANT: Always include the city in the query string (e.g. "romantic rooftop bars in Atlanta") or pass it as the city parameter. Returns ranked venue results with menu matches when relevant.

Find Similar

Find venues similar to a given venue. Uses a blended score of embedding similarity, design profile overlap, photo tag overlap, and metadata matching. Use when the user says "more like that", "similar to X", or wants alternatives.

Get Venue Details

Get full details about a specific venue - photos, design profile, atmosphere, cuisines, features, and more. Use when the user asks about a specific place or wants to know more about a venue from a previous search.

Browse City

Get an overview of what venues are available in a city. Returns category_slug breakdown, popular neighborhoods, and top Siren Spot picks. Use when the user asks "what's in [city]?" or wants to explore a destination.

Compare Venues

Compare 2–3 Opulist venues side by side (vibe, price, neighborhood, category, menu, Siren Spot, editorial take). Pass venue slugs or ids. Use when the user is deciding between specific places ("which of these should I pick?"). For discovery use search_venues / find_similar.

Whats Near

Find Opulist venues near a given venue (by slug or id), ordered by distance. Use for "what else is around here?" / itinerary planning ("what's near {venue}?"). Radial search from the seed venue - does not take a free-text address.

Get User Profile

Get the current user's full taste profile, preferences, and recent bookmarks. Use this when you need to understand what the user likes - for personalized recommendations, "more like what I usually save", or when they reference their bookmarks/saved places. Do NOT call this on every turn - only when the conversation needs personal context.

Search Saved Venues

Search the signed-in user's OWN saved venues (their bookmarks) by city, category, and/or free text. Use when the user asks about THEIR saves with criteria - e.g. "my Middle Eastern spots in Atlanta", "wine bars I saved in NYC", "my saved venues in Austin". Scans ALL their saves, not just recent ones. For a general taste profile use get_user_profile; for discovering NEW venues (not yet saved) use search_venues.

Recommend For Me

Personalized venue recommendations for the signed-in user, weighted by their taste profile and saves. Call with NO query for 'where should I go?' surprise-me recs (from what they've saved), or WITH a vibe/occasion query ('moody date-night', 'natural wine') to scope recs to that intent. Optionally pass a city. Use for 'recommend me somewhere', 'where should I go tonight'. For a general taste summary use get_user_profile; for non-personalized discovery use search_venues.