pvr-inox-radar

Files (11)

• SKILL.md
• sample_radar.json · assets/
• sample_seatlayout.json · assets/
• api-notes.md · references/
• status-colors.md · references/
• geocode.py · scripts/
• pvr_client.py · scripts/
• radar.py · scripts/
• render_map.py · scripts/
• selftest.py · scripts/
• star_invitation.py · scripts/

SKILL.md (first lines)

# pvr-inox-radar

Turn a movie-night ask into one HTML map of PVR INOX shows, with verified
seats-together counts for the shortlist and a deep link into PVR's own
booking page on every chip.

## Iron rules first

- **Politeness.** The client enforces a minimum 0.6s gap between API calls,
  strictly sequential. A 403 or 429 means the upstream blocked us: STOP the
  whole run, tell the user, never retry in the same turn (the cooldown is 15
  minutes and persists across processes). Never hit the API in parallel.
  Seat maps are fetched only for the top shortlisted shows, never in bulk.
- **Read-only.** Never book, hold, or poll. The user buys tickets themselves
  on pvrcinemas.com; every show links straight into PVR's seat page.
- **Credit.** Client engineering adapted from notprashanth/pvr-inox-mcp
  (MIT); see LICENSE. Never claim this project discovered the API.

## Parse the query

Extract from the user's ask:

- **Film**: title substring ("Dune"). Optional; omit to list everything.
- **Format**: IMAX, 4DX, ATMOS, LASER, GOLD, INSIGNIA, PLAYHOUSE,
  DIRECTOR'S CUT, ICE. Optional.
- **Date**: run `date` first, then resolve weekday words to YYYY-MM-DD in
  IST ("Saturday" means the coming Saturday in IST, not local time).
- **Time window**: evening = 18:00 to 23:59, night = 20:00 onward,
  matinee = before 17:00. Pass as --time-from / --time-to (24h IST).
  Relative asks ("starting in the next 30 to 90 minutes", "something we
  can leave for now") are computed from `date` in IST: now+30min to
  now+90min, rounded to minutes.
- **Party size**: "4 seats together" means --party-size 4.
- **Seat tier**: "recliners", "recliner seats", "loungers" means
  --tier recliner (or the asked word). This counts seats only inside
  matching priced rows (mixed halls name them, e.g. RECLINER ROWS) and
  counts whole halls only for recliner-native houses (Director's Cut,
  INSIGNIA, LUXE, Gold). For tier asks also pass --seat-detail 6 or more:
  a mixed hall's recliners are invisible until its seat map is opened, and
  the map honestly drops verified halls that have no such tier
  (meta.excluded_by_tier says how many).
- **Price**: "under Rs 500" means --max-price 500; "cheapest" means
  --sort cheapest. Prices live ONLY inside seat maps (show listings carry
  none), so pass --seat-detail 8 for price asks and say that unverified
  shows carry no price rather than a guessed one. The map's Price column
  shows "from Rs N": the matched tier's per-ticket gross, or the hall's
  cheapest tier (convenience fee and GST are extra at checkout).
- **Origin**: a locality ("Sector 56 Gurgaon") or a bare city ("Gurugram").
  After resolving it (geocode or city centre), STATE the resolved place and
  coordinates in one line before running ("Using Sector 56, Gurugram at
  28.44, 77.06; say so if that is wrong") so the user can correct the
  location. The map labels this origin as "You: <label>"; if the user
  corrects it, geocode the new place and re-run.
- **City**: usually implied by the locality. If genuinely ambiguous, restate
  the task in one line and ask ONE question instead of guessing.

## When to geocode

Only when the user names a locality finer than a city. Run once and reuse:

    python3 scripts/geocode.py "Sector 56, Gurugram"

It prints one JSON object: `{"lat": ..., "lng": ..., "display_name": ...,
"source": "nominatim", "cached": true|false}` (cached; at most 1 Nominatim
request per second). A bare city name skips geocoding entirely: radar.py
resolves city-centre coordinates itself. Never geocode in a loop.

## Run the radar

    python3 scripts/radar.py --city Gurugram --lat 28.42 --lng 77.09 \
      --origin-label "Sector 56 Gurgaon" --origin-source geocode \
      --movie "Dune" --format IMAX --date 2026-08-22 \
      --time-from 18:00 --party-size 4 --seat-detail 4 > radar.json

Flag guidance:

- --lat/--lng plus --origin-label/--origin-source: pass the geocoded
  coordinates and label; omit all four for a bare city (city centre is used).
  --origin-source takes exactly two values: "geocode" when the coordinates
  came from geocode.py, "caller" (the default) when the user supplied
  coordinates directly.
- --max-km: defaults to 6 km with caller coordinates and no format, else
  60 km (a premium format is a city-level resource). Widen it when the user
  says "anywhere in the city" or results are thin.
- --seat-detail N: seat maps are fetched for the top N shows only (default
  3, cap 8, 0 disables). Raise it when the user cares a lot about exact
  seats; every increment is one more paced API call.
- Expect the run to take about 15 to 25 seconds on cold caches: calls are
  deliberately spaced 0.6s apart and real network latency adds on top. That
  is the politeness budget, not a bug.
- Exit codes: 0 = answer (including partial and closed-date answers),
  2 = usage (bad flags, a city PVR does not serve, or a city with no
  published coordinates: pass --lat and --lng), 3 = blocked before any
  results, 4 = unexpected (including call-ceiling exhaustion before any
  results existed). Stdout is always one JSON document; logs go to stderr.

## Render and open

    python3 scripts/render_map.py --in radar.json --out map.html

Open map.html in the user's browser. Also give a compact ranked summary in
chat (top 3 to 5 shows: venue, time, format, seats-together verdict, drive
estimate, deep link) so the answer survives without the map.

Name the output per query so maps do not clobber each other:
map-<movie-or-all>-<date>.html (e.g. map-awarapan-2026-08-21.html). One
HTML answers one QUERY: an all-films ask is one map holding every film;
a movie ask is one map for that film.

**Ratings (fetch by DEFAULT for any ask that names a film, and for the
top 3 to 5 films of an all-films ask; skip only if the user says skip):**
the scripts never fetch ratings and need no API key; YOU look them up.
After the radar run, take the distinct film titles from radar.json, look
up each rating with your own web search (IMDb preferred; say the source
you actually found; third-party mirrors misreport, prefer imdb.com
itself), then render with them; rated films appear as a strip under the
stats and as a table column:

    python3 scripts/render_map.py --in radar.json --out map.html \

From karanb192/pvr-inox-radar, MIT.