VenuNite Events

{
  "type": "object",
  "properties": {
    "query_text": {
      "type": "string",
      "description": "Free-text vibe description extracted from the user's query. Keep it short — e.g. 'chill jazz' or 'loud rock club'. Omit when the user's request is purely geographic / tag-based (e.g. 'any comedy shows tonight near me')."
    },
    "place_name": {
      "type": "string",
      "description": "Human-readable location if the user mentioned one: 'Westminster, CO' or 'Five Points Denver'. Prefer this over lat/lng when you have a name. Always include the state abbrev when the city name is ambiguous."
    },
    "center_lat": {
      "type": "number",
      "description": "Latitude (only if you already have precise coordinates — otherwise pass place_name)."
    },
    "center_lng": {
      "type": "number",
      "description": "Longitude (paired with center_lat)."
    },
    "radius_miles": {
      "type": "number",
      "description": "Search radius in miles. OMIT this field to let the server pick a density-aware default: 5mi in dense metros (Chicago, NYC), 15mi suburban, 25mi rural. Only pass an explicit value when the user's phrasing implies a specific scope:\n  - 'walking distance' / 'on my block' → 2-3\n  - 'near me' in a dense downtown or neighborhood → 5-7\n  - 'near me' in a suburb → 10-15\n  - 'metro area' / 'anywhere in <city>' → 25-30\n  - rural 'near me' or 'within driving distance' → 25-50\n\nFor a user who says 'things to do tonight' in Lincolnwood, Chicago, or any other dense-urban location: omit this field. Passing 15 there pulls events from 8-10 miles away in other neighborhoods, which is worse than the density-aware default.\n\nMax 500. Use 'local_only: true' instead of a small radius when you're unsure of local density.",
      "default": null
    },
    "local_only": {
      "type": "boolean",
      "description": "Set true when the user's query implies 'in my immediate area' — 'what's on my block', 'nearby tonight', 'close by'. The server clamps the effective radius to a neighborhood-scale max based on local density (≤10mi urban, ≤30mi suburban, ≤50mi rural), even if radius_miles is larger. Prefer this over guessing a small radius — the server knows the density of the area and you don't.",
      "default": false
    },
    "max_cost": {
      "type": "number",
      "description": "Upper bound on event cost in USD. 'cheap' ≈ 15, 'affordable' ≈ 30, 'under $X' → X. Leave unset if the user didn't constrain price."
    },
    "min_cost": {
      "type": "number",
      "description": "Lower bound on event cost. Rarely useful — only set when the user explicitly excluded free events."
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "music",
          "karaoke",
          "sports",
          "comedy",
          "theater",
          "trivia-games",
          "food-drink",
          "arts-culture",
          "community"
        ]
      },
      "description": "Event category(s). Map the user's intent: 'live music' → music, 'standup' → comedy, 'trivia night' → trivia-games, 'art opening' → arts-culture. 'anything to do' → omit (no category filter)."
    },
    "vibe_tags": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "chill",
          "casual",
          "lively",
          "rowdy",
          "intimate",
          "loud",
          "upscale",
          "scene-y",
          "romantic",
          "date-spot",
          "group-friendly",
          "solo-friendly",
          "family-friendly",
          "queer-friendly",
          "late-night",
          "happy-hour",
          "brunch-spot",
          "daytime",
          "all-ages",
          "18-plus",
          "21-plus",
          "dive-bar",
          "cocktail-bar",
          "wine-bar",
          "brewery",
          "winery",
          "distillery",
          "coffeehouse",
          "listening-room",
          "dance-club",
          "lounge",
          "sports-bar",
          "theater",
          "concert-hall",
          "amphitheater",
          "arena",
          "arts-center",
          "art-gallery",
          "rooftop",
          "outdoor",
          "restaurant-venue",
          "church-venue",
          "warehouse",
          "historic",
          "open-mic",
          "karaoke",
          "trivia",
          "comedy-focused",
          "drag-shows"
        ]
      },
      "description": "Canonical vibe vocabulary. Include tags the user explicitly or strongly implied. IMPORTANT: the tags `queer-friendly`, `family-friendly`, `all-ages`, `18-plus`, `21-plus` are HARD filters — only include them when the user's query explicitly asked for that property. Including `family-friendly` for a user who just said 'something fun tonight' will exclude most venues."
    },
    "date_start": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 start of the search window. Default: now. For 'tonight' pass now. For 'this weekend' pass the upcoming Saturday midnight."
    },
    "date_end": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 end of the search window. Default: 14 days from date_start. 'Tonight' → date_start + 6 hours. 'Next weekend' → date_start + 2 days."
    },
    "limit": {
      "type": "integer",
      "description": "Number of events to return. Default 20. Prefer small (5-10) when the user asked for a single recommendation.",
      "default": 20,
      "minimum": 1,
      "maximum": 100
    },
    "max_events_per_venue": {
      "type": "integer",
      "description": "Per-venue diversity cap. Default 1 — each venue contributes at most one event, giving a diverse 'what's on' feed. Raise to 3-5 for 'what's on at <specific venue>' queries where the user expects multiple shows from the same room.",
      "default": 1,
      "minimum": 1,
      "maximum": 20
    }
  },
  "additionalProperties": false
}