#!/usr/bin/env python3
"""
planner.py — Phase 2: full itinerary generation, single-day regeneration, and
post-processing (endpoint snapping, map-pin de-stacking) for a planned trip.
Used by the roadtrip-webapp (imported via the skill submodule's scripts/
directory on sys.path, same as routes.py) and callable standalone for testing.
Public API
----------
live_mode() -> bool
True when ANTHROPIC_API_KEY is set and the anthropic package is importable.
generate_trip(payload, live, on_progress=None, log_fn=None) -> dict
Full flow: plan (live or demo) + schema defaults + endpoint/pin fixups.
This is the one call the webapp needs — pass it a form payload and get
back a tripData dict ready for generate.py to render.
plan_live(payload, region, on_progress=None, log_fn=None) -> dict
One streaming Claude call, framed by SKILL.md + reference.md, that emits
the full tripData JSON. `on_progress` receives {"step"|"expectedChars"|
"charsReceived": ...} events a caller can use to drive a progress UI.
plan_demo(payload, region, on_progress=None) -> dict
Offline fallback: serve the closest curated sample tripData.
regenerate_day(trip, day_index, comment_body, log_fn=None) -> dict
Rewrite a single day of an existing trip per a commenter's request.
remove_city(trip, day_start, day_end, city_name="", log_fn=None) -> dict
Trip edit: delete one overnight stop's days, regenerate the single joined
driving day (one model call), then resequence dates, refresh totals and —
where a real forecast covers the new dates — weather. Mutates only after
the model call succeeds; raises on an invalid span or model failure.
set_nights(trip, day_start, day_end, city_name, nights, log_fn=None) -> dict
Trip edit: change how long one overnight stop lasts. The city's run of
days is rewritten as `nights` days by one model call (arrival driving leg
preserved verbatim), then the same deterministic cascade as remove_city
runs (dates, totals, lodging nights, weather). Same atomicity contract.
revise_stay(trip, day_start, day_end, city_name, instruction, nights=None,
log_fn=None) -> dict
Trip edit: rewrite one stay per a free-text traveler request, optionally
resizing it in the same single model call. Same guards/cascade/atomicity.
fix_endpoints(trip, start, destination) -> None
Snap the first/last stop coordinates to the real start/destination.
despread_stops(trip) -> None
Nudge/re-geocode stops whose coordinates collide so map pins separate.
refresh_trip_weather(trip) -> dict
Replace each day's weather with a real forecast (source="forecast") or, past
the forecast window, a seasonal climatology average (source="climatology").
Called on generate and when a trip page is opened. Best-effort.
weather_advisories(trip) -> list[dict|None]
Per-day weather advisories (deterministic, no model call), aligned with
trip['days']: None, or {severity, source, condition, message}. Only days
with a provenance tag get one; language follows trip['lang'].
geocode(query, timeout=3.0) -> {"lat","lng"} | None
geocode_near(query, lat, lng, timeout=3.0) -> {"lat","lng"} | None
Best-effort Photon geocoding (free, no key), the latter biased to a locale.
"""
import datetime
import functools
import json
import math
import os
import re
import sys
import time
import urllib.parse
import urllib.request
_HERE = os.path.dirname(os.path.abspath(__file__))
_ROOT = os.path.normpath(os.path.join(_HERE, ".."))
_ASSETS = os.path.join(_ROOT, "assets")
# Allow importing routes/helper (siblings in scripts/)
if _HERE not in sys.path:
sys.path.insert(0, _HERE)
import helper as _helper # noqa: E402
import routes as _routes # noqa: E402 (haversine_km, extract_json, payload_to_text)
_MODEL = os.environ.get("ROADTRIP_MODEL", "claude-sonnet-4-6")
def live_mode():
if not os.environ.get("ANTHROPIC_API_KEY"):
return False
try:
import anthropic # noqa: F401
return True
except Exception:
return False
def _read_doc(name):
try:
with open(os.path.join(_ROOT, name), "r", encoding="utf-8") as f:
return f.read()
except OSError as e:
print("[warn] could not read skill doc %s: %s" % (name, e), file=sys.stderr)
return ""
SKILL_MD = _read_doc("SKILL.md")
REFERENCE_MD = _read_doc("reference.md")
# curated sample itineraries used as the offline/no-key fallback
SAMPLE_FILES = {
"sw": "tripData.example.json",
"tahoe": "tripData.tahoe.json",
"pnw": "tripData.pnw.json",
"chicago": "tripData.chicago.json",
}
# --------------------------------------------------------------------------- #
# Geocoding / post-processing
# --------------------------------------------------------------------------- #
@functools.lru_cache(maxsize=2048)
def _geocode_cached(key, timeout):
"""Cached implementation — keyed on the normalised query string."""
res = None
try:
url = "https://photon.komoot.io/api/?limit=1&lang=en&q=" + urllib.parse.quote(key)
req = urllib.request.Request(url, headers={"User-Agent": "roadtrip-navigator/1.0"})
with urllib.request.urlopen(req, timeout=timeout) as r:
d = json.loads(r.read().decode())
feats = d.get("features") or []
if feats and feats[0].get("geometry"):
c = feats[0]["geometry"]["coordinates"] # [lng, lat]
res = {"lat": round(c[1], 5), "lng": round(c[0], 5)}
except Exception as e:
print("[warn] geocode failed for %r: %s" % (key, e), file=sys.stderr)
return res
def geocode(query, timeout=3.0):
"""Best-effort geocode via Photon (free, no key). Returns {lat,lng} or None."""
if not query:
return None
return _geocode_cached(query.strip().lower(), timeout)
def fix_endpoints(trip, start, destination):
"""Snap the first stop to the real start and the last stop to the real
destination, so the map endpoints are correct even if the model's coords drift."""
try:
days = trip.get("days") or []
if start and days and (days[0].get("stops")):
g = geocode(start if "," in start else start + ", USA")
if g:
days[0]["stops"][0]["lat"] = g["lat"]
days[0]["stops"][0]["lng"] = g["lng"]
if destination and days and (days[-1].get("stops")):
g = geocode(destination if "," in destination else destination + ", USA")
if g:
days[-1]["stops"][-1]["lat"] = g["lat"]
days[-1]["stops"][-1]["lng"] = g["lng"]
except Exception as e:
print("[warn] fix_endpoints failed:", e, file=sys.stderr)
@functools.lru_cache(maxsize=2048)
def _geocode_near_cached(key, lat, lon, timeout):
"""Geocode biased toward (lat, lon) so a name like 'Old Faithful' resolves
near the trip's own cluster instead of a same-named place elsewhere."""
res = None
try:
url = ("https://photon.komoot.io/api/?limit=1&lang=en&lat=%s&lon=%s&q=%s"
% (lat, lon, urllib.parse.quote(key)))
req = urllib.request.Request(url, headers={"User-Agent": "roadtrip-navigator/1.0"})
with urllib.request.urlopen(req, timeout=timeout) as r:
d = json.loads(r.read().decode())
feats = d.get("features") or []
if feats and feats[0].get("geometry"):
c = feats[0]["geometry"]["coordinates"] # [lng, lat]
res = {"lat": round(c[1], 5), "lng": round(c[0], 5)}
except Exception as e:
print("[warn] biased geocode failed for %r: %s" % (key, e), file=sys.stderr)
return res
def geocode_near(query, lat, lng, timeout=3.0):
"""Best-effort name geocode, biased toward (lat, lng). Returns {lat,lng} or None."""
if not query:
return None
return _geocode_near_cached(query.strip().lower(), round(lat, 2), round(lng, 2), timeout)
def despread_stops(trip):
"""Keep map markers from stacking.
Only the first/last stops are geocoded (see fix_endpoints); the model's
coordinates for the stops in between are frequently identical for several
places in a dense area (e.g. many Yellowstone viewpoints sharing the park's
coordinates), so those pins pile up and never separate, even when zoomed in.
For every stop whose coordinates are missing or land within ~120m of one
we've already placed, re-geocode it by name (biased to the local cluster);
if that fails or still collides, nudge it onto a small deterministic ring
around the cluster centre so each stop becomes a distinct, separable pin.
Stops that are already distinct are left untouched.
"""
days = trip.get("days") or []
def valid(s):
la, ln = s.get("lat"), s.get("lng")
return isinstance(la, (int, float)) and isinstance(ln, (int, float)) and (la or ln)
fallback_center = next(((s["lat"], s["lng"])
for d in days for s in (d.get("stops") or []) if valid(s)), None)
if not fallback_center:
return # no usable coordinates at all — nothing to do
placed = [] # accepted (lat, lng) so far
def collides(la, ln):
return any(_routes.haversine_km(la, ln, p[0], p[1]) < 0.12 for p in placed) # ~120m
nudges = 0
for day in days:
for stop in (day.get("stops") or []):
if valid(stop) and not collides(stop["lat"], stop["lng"]):
placed.append((stop["lat"], stop["lng"]))
continue
cla, cln = placed[-1] if placed else fallback_center # bias to local cluster
fixed = None
g = geocode_near(stop.get("name", ""), cla, cln)
if g and _routes.haversine_km(g["lat"], g["lng"], cla, cln) <= 150 and not collides(g["lat"], g["lng"]):
fixed = (g["lat"], g["lng"]) # real, distinct location
if fixed is None: # last resort: spread on a small ring
nudges += 1
ang = math.radians(nudges * 137.5) # golden angle → even spread
r = min(0.02 + 0.012 * nudges, 0.08) # ~2-9 km, capped
fixed = (round(cla + r * math.sin(ang), 5), round(cln + r * math.cos(ang), 5))
stop["lat"], stop["lng"] = fixed[0], fixed[1]
placed.append(fixed)
# --------------------------------------------------------------------------- #
# Full itinerary generation (phase 2)
# --------------------------------------------------------------------------- #
# Framing that adapts the multi-step agent skill to this single-shot JSON endpoint.
SKILL_SYSTEM_FRAMING = (
"You are RoadTrip Navigator, an expert North American road-trip planner.\n"
"The two documents below are your skill's source of truth — SKILL.md (your "
"workflow, planning rules, and honesty boundaries) and reference.md "
"(tripData schema, reliability grading, region cues, tool routing). Follow "
"their planning intelligence: daily-drive pacing, overnight logic, "
"reservation lead times and the correct booking system, fuel/EV reasoning, "
"seasonal closures, cross-border rules, and reliability grading.\n\n"
"EXECUTION CONTEXT — read carefully: you are running as a single-shot JSON "
"endpoint, NOT the full agent. You CANNOT call tools, scripts, or web "
"search, and you must not emit the skill's shell commands or step-by-step "
"narration. Wherever the skill would call a tool or look something up, make "
"your best expert estimate and grade it honestly (verified/reference/"
"estimate) per reference.md. Your ENTIRE output is the single tripData JSON "
"object specified in the user message — nothing else."
)
def build_messages(payload, region):
"""Return (system_blocks, user_text). The skill brain drives planning via a
cached system prompt; the user message carries the live inputs and the exact
renderer output contract (the tripData schema generate.py consumes)."""
system = [
{"type": "text", "text": SKILL_SYSTEM_FRAMING},
{"type": "text", "text": "===== SKILL.md =====\n" + SKILL_MD},
# one cache breakpoint at the end of the static prefix caches all of the
# framing + SKILL.md + reference.md across requests (they never change
# until this module's version changes).
{"type": "text", "text": "===== reference.md =====\n" + REFERENCE_MD,
"cache_control": {"type": "ephemeral"}},
]
return system, build_user(payload, region)
def build_user(payload, region):
schema = """{
"title": str, "subtitle": str, "dateRange": str, "travelers": str,
"vehicle": {"type": "gas|EV|RV", "model": str, "mpg": int|null, "rangeMiles": int|null},
"loopType": "loop|one-way", "totalMiles": int, "drivingDays": int,
"region": "desert|coast|forest|autumn|mountain",
"units": {"distance":"mi","temp":"F","currency":"USD|CAD|MXN|CNY"},
"days": [{"date":"MM/DD","title":str,"from":str,"to":str,"driveMiles":int,
"driveTime":"Xh YYm","overnight":str|null,"timezoneNote":str?,
"weather":{"icon":"sunny|partly-cloudy|cloudy|rain|snow|storm|windy|fog","high":int,"low":int},
"stops":[{"name":str,"type":"park|hike|scenic|city|tour|food|lodging","lat":float,"lng":float,
"timedEntry":bool?,"ticket":str?,
"admission":{"status":"free|included|paid|unknown","label":str?,
"price":{"amount":number,"currency":str,
"unit":"person|vehicle|group|booking|total",
"reliability":"verified|reference|estimate"}?}?,"note":str}],
"fuelCharging":[{"name":str,"type":"gas|charge","lat":float,"lng":float,"powerKW":int?,"note":str}],
"meal":{"name":str,"perPerson":int},"risks":[str]}],
"lodging":[{"name":str,"area":str,"nights":int,"pricePerNight":int,"rating":str,"booked":false}],
"bookingCountdown":[{"item":str,"bookBy":"YYYY-MM-DD","where":str,
"category":"attraction|restaurant|hotel",
"price":{"amount":number,"currency":str,
"unit":"person|night|vehicle|group|booking|total",
"reliability":"verified|reference|estimate"}?,
"priority":"high|medium|low","note":str}],
"budget":{"currency":"USD|CAD|MXN|CNY","items":[{"label":str,"amount":int,"reliability":"verified|reference|estimate"}],
"total":int,"perPerson":int},
"tips":[str], "disclaimer":str, "generationDate":"YYYY-MM-DD",
"crossings":[{"from":"US|CA|MX","to":"US|CA|MX","day":int}]
}"""
user = json.dumps({k: v for k, v in payload.items() if v and k != "route"}, ensure_ascii=False)
eff = payload.get("efficiency")
if (payload.get("vehicle") or "").lower() == "ev":
rng_in = _as_positive_number(payload.get("rangeMiles"))
energy_rule = ("- The EV travels about %s miles per kWh. Estimate a realistic current public "
"DC fast-charging price (per kWh, in the trip's currency) YOURSELF from typical regional rates (the user "
"won't know it) and compute the charging budget; show the assumed price in the "
"budget line label.\n" % (eff or "3.3"))
rng_txt = ("%d" % rng_in) if rng_in else "your best estimate for a typical mainstream EV (~280)"
energy_rule += (
"- EV RANGE: set vehicle.rangeMiles to %s (the battery table uses it).\n"
"- EV OVERNIGHT CHARGING: every overnight stop (each day's destination) MUST have "
"a charging option in that day's fuelCharging — a DC fast charger in that town, or "
"the hotel's destination charging, placed at/near the destination coordinates — so "
"the car starts each morning near a full charge. This is required; a day whose "
"destination has no charging entry is a planning error. Do NOT pre-place MID-ROUTE "
"charging stops — the app fills those in automatically (evenly spaced along each "
"day) after generation, so any you add would just be replaced. (In Chinese "
"itineraries, name the overnight entry with 过夜充电.)\n" % rng_txt)
else:
energy_rule = ("- The vehicle averages about %s MPG. Estimate realistic current gas prices "
"(per gallon or litre, in the trip's currency) YOURSELF for the regions on the route (the user won't know them) and "
"compute the fuel budget (total miles / MPG x price); show the assumed price in "
"the budget line label.\n" % (eff or "26"))
lang_rule = ""
if (payload.get("lang") or "").lower().startswith("zh"):
lang_rule = ("- Write ALL human-readable text (title, subtitle, notes, risks, tips, "
"labels, meal/lodging names where natural) in Simplified Chinese. "
"Keep JSON keys and enum values (type/reliability/icon/priority) in English, "
"and keep place names recognizable (Chinese with English in parentheses is fine).\n")
# Trip shape is the user's explicit choice — round trip vs one way — and is
# independent of the day count (5 days can be either). Honor it exactly.
trip_type = (payload.get("tripType") or "").lower()
trip_rule = ""
if trip_type in ("round", "roundtrip", "return", "loop"):
trip_rule = ("- TRIP SHAPE: ROUND TRIP. The route MUST return to the starting point by the "
"final day; set \"loopType\":\"loop\". Pace the days so the loop closes within the "
"requested number of days (plan the turnaround around the halfway day).\n")
elif trip_type in ("oneway", "one-way", "one_way", "single"):
trip_rule = ("- TRIP SHAPE: ONE WAY. The route ends at the destination and does NOT return to "
"the start; set \"loopType\":\"one-way\". Use the full number of days progressing "
"from start toward the destination (no return leg).\n")
# If the user already picked one of the two candidate routes (phase 1), pin the
# detailed plan to that route's waypoints so we expand exactly what they chose.
route = payload.get("route") or {}
wps = route.get("waypoints") or []
route_rule = ""
if wps:
pts = " -> ".join(
"%s (%.4f, %.4f)" % (w.get("name", "?"), w["lat"], w["lng"])
for w in wps
if isinstance(w.get("lat"), (int, float)) and isinstance(w.get("lng"), (int, float)))
if pts:
route_rule = ("- CHOSEN ROUTE: the user already picked \"%s\". Build the detailed "
"day-by-day itinerary ALONG this route, visiting these major waypoints in "
"order: %s. You may add sensible intermediate stops, but keep this overall "
"path and its endpoints.\n" % (route.get("label") or "the selected route", pts))
# Apply your skill's planning rules (SKILL.md + reference.md, in the system
# prompt) to these inputs, then emit ONLY the tripData JSON. The rules below
# are the renderer's output contract + this request's runtime parameters —
# they are NOT a re-statement of how to plan (that lives in the skill).
return (
"Plan a realistic, drivable itinerary — applying your skill's rules — for "
"these inputs:\n" + user + "\n\n"
"TODAY is " + time.strftime("%Y-%m-%d") + ". Region visual hint: " + region + ".\n\n"
"Runtime parameters for THIS request:\n"
+ energy_rule + lang_rule + trip_rule + route_rule +
"\nOutput contract (the renderer consumes this exact shape):\n"
"- Output ONLY a single JSON object matching this schema — no prose, no markdown fences:\n"
+ schema + "\n"
'- Strict JSON: any double quote inside a string value must be escaped as \\".\n'
"- Every stop and fuel/charge point needs real, accurate decimal lat/lng; Day 1's first "
"stop MUST be the exact start and the final stop MUST be the destination.\n"
"- 'dateRange' and 'drivingDays' must match the requested number of days; set 'region' to "
"the best visual match.\n"
"- budget.total must equal the sum of budget.items and budget.perPerson = total / travelers; "
"grade every line verified/reference/estimate.\n"
"- Currency: price the ENTIRE budget in the currency of the country the trip drives in, "
"and set units.currency AND budget.currency to its code (US→USD, Canada→CAD, "
"Mexico→MXN, China→CNY). NEVER convert amounts into another currency — a trip "
"entirely within China prices every line in CNY yuan. Cross-border US/CA/MX trips keep "
"the existing USD convention with local-currency notes.\n"
"- Every bookingCountdown item should include price when supportable: hotels per night, "
"restaurants per person, and attraction tickets/permits when required. Use amount 0 for "
"free reservations; use the trip currency's ISO code unless the item is explicitly priced "
"locally, and omit price rather than inventing an unsupported exact live price.\n"
"- Every planned park/hike/scenic/tour stop MUST include admission. Use status 'free' when "
"the planned visit has no admission charge, 'included' when a park or attraction pass "
"already covers it, 'paid' when a ticket/fee is required, and 'unknown' only when whether "
"payment is required cannot be determined. For 'paid', include admission.price only when "
"supportable; otherwise omit it so the view says the price is unavailable. Do not infer an "
"individual stop price from an aggregate budget line.\n"
"- No reservation 'bookBy' date may be before today.\n"
"- Include \"crossings\" ONLY if the route crosses a US/Canada/Mexico border: one entry "
"per crossing in driving order, with the trip day number it happens on; omit the key "
"entirely for domestic trips. Do NOT write any other border/customs content — the "
"checklists and duty-free amounts are generated downstream from official rule tables.\n"
"- Fill 'disclaimer' with a note to verify against official sources.\n"
"Return JSON only."
)
_STRICT_JSON_NUDGE = (
"\n\nRETRY NOTICE: your previous response was not parseable JSON. Return "
"STRICT JSON this time — most importantly, any double quote inside a "
"string value must be escaped as \\\"."
)
def _log_bad_json(where, text, err, stop_reason=None):
"""Preserve the evidence when model JSON fails to parse: the error, the
stop_reason and the text around the failure position go to stderr, so
server logs show the root cause instead of a bare JSONDecodeError."""
pos = getattr(err, "pos", None)
ctx = ""
if isinstance(pos, int):
lo, hi = max(0, pos - 200), min(len(text), pos + 200)
ctx = " … context @%d: %r" % (pos, text[lo:hi])
print("[warn] %s: unparseable model JSON (%s; stop_reason=%s; %d chars)%s"
% (where, err, stop_reason, len(text), ctx), file=sys.stderr)
def _parse_with_retry(text, retry_fn, where, stop_reason=None):
"""extract_json with one second chance: on failure, log the evidence and
let `retry_fn() -> (text, stop_reason)` ask the model again (a JSON slip
is a dice roll — one retry removes almost all user-visible failures)."""
try:
return _routes.extract_json(text)
except Exception as e:
_log_bad_json(where, text, e, stop_reason)
text2, stop2 = retry_fn()
try:
return _routes.extract_json(text2)
except Exception as e:
_log_bad_json(where + " (retry)", text2, e, stop2)
raise
def plan_live(payload, region, on_progress=None, log_fn=None):
"""Live phase-2 generation: one streaming Claude call framed by the skill's
own docs (plus one automatic retry if the response isn't parseable JSON).
`on_progress(event)` (if given) is called with small dicts as JSON
streams in so a caller can reflect progress:
- {"expectedChars": n} once, before streaming starts
- {"charsReceived": n} on every chunk (fine-grained ETA signal)
- {"step": idx} when a coarse phase threshold is crossed
`log_fn(usage)` (if given) receives each call's token-usage object."""
import anthropic
# Bounded timeout + one retry: generation is the ONE model call with no
# offline fallback, so a single dropped/slow connection (common behind a
# proxy) must not fail the whole plan — restart the stream once instead.
client = anthropic.Anthropic(timeout=180.0, max_retries=0)
system, prompt = build_messages(payload, region)
def emit(event):
if on_progress:
on_progress(event)
emit({"step": 1})
# advance status as the JSON streams in (token-count milestones = real signal).
# Expected length scales with day count so the thresholds — and therefore the
# ETA derived from charsReceived/expectedChars — stay meaningful for both a
# quick 2-day trip and a sprawling 3-week one.
try:
n_days = max(1, min(21, int(payload.get("days") or 5)))
except (TypeError, ValueError):
n_days = 5
expected_chars = n_days * 1100 # e.g. 5d→5500, 7d→7700, 14d→15400
thresholds = [
(int(expected_chars * 0.15), 2), # route (~15% in)
(int(expected_chars * 0.37), 3), # segment (~37% in)
(int(expected_chars * 0.67), 4), # budget/research (~67% in)
]
emit({"expectedChars": expected_chars})
def stream_once(p):
text = ""
with client.messages.stream(model=_MODEL, max_tokens=16000, system=system,
messages=[{"role": "user", "content": p}]) as stream:
for chunk in stream.text_stream:
text += chunk
emit({"charsReceived": len(text)})
for n, step in thresholds:
if len(text) >= n:
emit({"step": step})
final = stream.get_final_message() # carries the authoritative token usage
if log_fn:
log_fn(final.usage)
return text, getattr(final, "stop_reason", None)
def stream_first(p):
last = None
for attempt in range(2):
try:
return stream_once(p)
except Exception as e: # dropped/slow connection — restart once
last = e
print("[warn] plan_live stream attempt %d failed: %s"
% (attempt + 1, e), file=sys.stderr)
emit({"charsReceived": 0}) # reset the progress bar for the retry
raise last
text, stop = stream_first(prompt)
return _parse_with_retry(
text, lambda: stream_once(prompt + _STRICT_JSON_NUDGE), "plan_live", stop)
def plan_demo(payload, region, on_progress=None):
"""No API key: serve the closest curated demo so the page always works."""
dest = (payload.get("destination", "") + " " + payload.get("start", "")).lower()
if any(w in dest for w in ["tahoe", "sacramento", "sierra"]):
fn = "tripData.tahoe.json"
elif any(w in dest for w in ["vancouver", "canada", "whistler", "seattle", "bc"]):
fn = "tripData.pnw.json"
elif any(w in dest for w in ["chicago", "illinois", "indiana dunes", "starved rock", "oak park"]):
fn = "tripData.chicago.json"
else:
fn = "tripData.example.json"
with open(os.path.join(_ASSETS, fn), "r", encoding="utf-8") as f:
trip = json.load(f)
# walk the status steps so the UX is visible
for i in range(1, 5):
if on_progress:
on_progress({"step": i})
time.sleep(1.0)
trip["_demoNote"] = ("Demo mode: showing a curated sample itinerary. Set an "
"ANTHROPIC_API_KEY to generate a fresh plan for your exact input.")
# reflect the user's framing where harmless
if payload.get("start") or payload.get("destination"):
trip["subtitle"] = (trip.get("subtitle", "") +
" · (demo sample for: %s)" % _routes.payload_to_text(payload))
return trip
def generate_trip(payload, live, on_progress=None, log_fn=None):
"""The one call a caller needs: plan (live or demo), stamp schema defaults
(language, generation date, disclaimer), and apply endpoint/pin post-
processing. Returns a tripData dict ready for generate.py to render."""
region = payload.get("region")
if not region:
try:
region = _helper.analyze(_routes.payload_to_text(payload))["slots"].get("region")
except Exception:
region = None
region = region or "desert"
if live:
trip = plan_live(payload, region, on_progress=on_progress, log_fn=log_fn)
else:
trip = plan_demo(payload, region, on_progress=on_progress)
# Stamp the generation language so shared pages render in the same language.
trip_lang = (payload.get("lang") or "en").lower()
trip["lang"] = "zh" if trip_lang.startswith("zh") else "en"
trip.setdefault("generationDate", time.strftime("%Y-%m-%d"))
if trip["lang"] == "zh":
trip.setdefault("disclaimer",
"内容由 AI 整理,可能存在偏差——出行前请以官方渠道核实"
"营业时间、价格、预订及道路/边境状况。")
else:
trip.setdefault("disclaimer",
"AI-assembled and may be out of date — verify hours, prices, "
"reservations and road/border conditions with official sources.")
if live:
fix_endpoints(trip, payload.get("start"), payload.get("destination"))
despread_stops(trip) # stop coincident map pins from stacking (see docstring)
# Replace the model's guessed weather with a real forecast (or seasonal
# average past the forecast window) now that stop coordinates are settled.
# Best-effort: a failure here leaves the model's estimate untouched.
refresh_trip_weather(trip)
if live:
# Single-source-of-truth pass: every hard number the model was forced
# to guess is replaced by the same tools/ clients the agent workflow
# uses — routing first (real miles feed the fuel and EV math), then
# energy economics, booking deadlines, lodging links, border rules and
# the route-comparison table. Each step is best-effort and leaves the
# model's estimate in place on failure. Demo trips are curated
# fixtures and keep their hand-checked numbers.
refresh_trip_routing(trip)
refresh_trip_fuel(trip, efficiency=payload.get("efficiency"))
autofill_ev_charging(trip, log_fn=log_fn) # place mid-route DC charging
refresh_trip_ev_corridor(trip)
refresh_trip_countdown(trip)
refresh_trip_lodging_links(trip)
refresh_trip_border(trip)
refresh_trip_route_options(trip, payload)
return trip
def _regenerate_day_with_instruction(trip, day_index, instruction, log_fn=None):
"""Single-shot model call that rewrites one trip day per `instruction`
(a complete sentence describing the change). Shared by regenerate_day
(comments) and remove_city (trip editing). Raises on failure."""
import anthropic
client = anthropic.Anthropic()
days = trip.get("days") or []
day = days[day_index]
days_summary = "\n".join(
"Day %d (%s): %s [%s → %s]" % (
i + 1, d.get("date", ""), d.get("title", ""),
d.get("from", ""), d.get("to", ""))
for i, d in enumerate(days)
)
prev_to = days[day_index - 1].get("to", "") if day_index > 0 else ""
next_from = days[day_index + 1].get("from", "") if day_index + 1 < len(days) else ""
continuity = ""
if prev_to:
continuity += "The previous day (Day %d) ends at '%s'. " % (day_index, prev_to)
if next_from:
continuity += "The next day (Day %d) starts at '%s'. " % (day_index + 2, next_from)
schema = (
'{"date":str,"title":str,"from":str,"to":str,"driveMiles":int,"driveTime":str,'
'"overnight":str|null,"timezoneNote":str?,'
'"weather":{"icon":"sunny|partly-cloudy|cloudy|rain|snow|storm|windy|fog","high":int,"low":int},'
'"stops":[{"name":str,"type":"park|hike|scenic|city|tour|food|lodging",'
'"lat":float,"lng":float,"admission":{"status":"free|included|paid|unknown",'
'"label":str?,"price":{"amount":number,"currency":str,"unit":'
'"person|vehicle|group|booking|total","reliability":'
'"verified|reference|estimate"}?}?,"note":str}],'
'"fuelCharging":[{"name":str,"type":"gas|charge","lat":float,"lng":float,"note":str}],'
'"meal":{"name":str,"perPerson":int},"risks":[str]}'
)
prompt = (
"You are updating one day of an existing road trip itinerary.\n\n"
"Trip: %s\n"
"All days (for continuity context):\n%s\n\n"
"Current Day %d:\n%s\n\n"
"%s\n\n"
"Rewrite ONLY Day %d to honour this request. %s"
"Keep the same 'date' value. Use accurate lat/lng for all stops and include admission "
"status for every park/hike/scenic/tour stop. "
"Output ONLY the JSON object for this single day — no prose, no markdown "
"fences; any double quote inside a string value must be escaped as \\\":\n%s\n"
"Return JSON only."
) % (
trip.get("title", ""),
days_summary,
day_index + 1,
json.dumps(day, ensure_ascii=False, indent=2),
instruction,
day_index + 1,
continuity,
schema,
)
def create_once(p):
msg = client.messages.create(
model=_MODEL, max_tokens=4000,
messages=[{"role": "user", "content": p}])
t = "".join(b.text for b in msg.content if getattr(b, "type", None) == "text")
if log_fn:
log_fn(msg.usage)
return t, getattr(msg, "stop_reason", None)
text, stop = create_once(prompt)
new_day = _parse_with_retry(
text, lambda: create_once(prompt + _STRICT_JSON_NUDGE),
"regenerate_day", stop)
# Preserve the original date so the calendar doesn't drift.
new_day["date"] = day.get("date", new_day.get("date", ""))
return new_day
def _heal_day_coords(trip):
"""Repair days whose stop coordinates collapsed to ~one point — a generation
mis-geocode common on the RETURN leg of long out-and-back loops (e.g. a
拉萨→西宁 day with every stop pinned near Lhasa). Re-anchor each broken day's
first/last stop from the same city seen with SOUND coordinates elsewhere in
the trip, so the EV corridor can position chargers on it at all. Best-effort,
in place; returns how many days were healed. Sound trips are a no-op."""
days = trip.get("days") or []
def pts_of(d):
return [s for s in (d.get("stops") or [])
if isinstance(s.get("lat"), (int, float))
and isinstance(s.get("lng"), (int, float))]
def spread(pts, d):
miles = _as_positive_number(d.get("driveMiles"))
return bool(miles) and len(pts) >= 2 and _routes.haversine_km(
pts[0]["lat"], pts[0]["lng"], pts[-1]["lat"], pts[-1]["lng"]
) >= 0.25 * miles * 1.609
def city_key(name):
# Match a city across days despite annotations: "西宁 (Xining)(再返北京)"
# and "西宁 (Xining)" and "西宁,青海" all key on their leading token.
s = name or ""
for sep in ("(", "(", ",", ","):
s = s.split(sep)[0]
return s.strip()
# Learn each city's coordinate from days whose own stops are well spread.
city_coord = {}
for d in days:
pts = pts_of(d)
if not spread(pts, d):
continue
for city, s in ((d.get("from"), pts[0]), (d.get("to"), pts[-1])):
key = city_key(city)
if key:
city_coord.setdefault(key, (s["lat"], s["lng"]))
# Heal an endpoint stop only when it sits FAR from where its own city really
# is (a mis-geocode is off by a whole region, ~1000+ km) — never for a
# legitimate day whose sights spread up to ~150 km. Keeps sound days untouched.
FAR_KM = 300.0
healed = 0
for d in days:
pts = pts_of(d)
if not pts:
continue
endpoints = [(pts[-1], d.get("to"))]
if len(pts) >= 2:
endpoints.append((pts[0], d.get("from")))
fixed = False
for stop, city in endpoints:
c = city_coord.get(city_key(city))
if c and _routes.haversine_km(stop["lat"], stop["lng"], c[0], c[1]) > FAR_KM:
stop["lat"], stop["lng"] = c[0], c[1]
fixed = True
healed += 1 if fixed else 0
return healed
def _prev_day_end(trip, day_index):
"""(lat, lng) where the previous day ended — this day's true starting point,
used to anchor charger fractions. None for day 0 or when no earlier day has
usable stop coordinates."""
for d in reversed((trip.get("days") or [])[:max(0, day_index)]):
pts = [(s.get("lat"), s.get("lng")) for s in (d.get("stops") or [])
if isinstance(s.get("lat"), (int, float))
and isinstance(s.get("lng"), (int, float))]
if pts:
return pts[-1]
return None
def _interp_day_coord(day, origin, frac):
"""A (lat, lng) at `frac` (0..1) along the day's straight-line route from
`origin` (yesterday's end) to the day's last stop — the SAME straight-line
model _day_charge_frac uses to POSITION a charger. A stop placed here lands
at ~`frac` of the day, letting the backend guarantee even charger spacing
rather than trusting the model's geographic precision. None when the day's
endpoints lack usable coordinates."""
pts = [(s.get("lat"), s.get("lng")) for s in (day.get("stops") or [])
if isinstance(s.get("lat"), (int, float))
and isinstance(s.get("lng"), (int, float))]
start = origin or (pts[0] if pts else None)
end = pts[-1] if pts else None
if not start or not end:
return None
return (start[0] + frac * (end[0] - start[0]),
start[1] + frac * (end[1] - start[1]))
def _name_charging_points(trip, day_index, coords, log_fn=None):
"""Ask the model for a real DC-fast-charging place name near each (lat, lng)
in `coords` (driving order). Returns names aligned with `coords`, "" where it
can't name one; [] on total failure. Best-effort only — the coordinates (and
thus the feasibility) are the backend's; the model merely labels them."""
if not coords:
return []
import anthropic
days = trip.get("days") or []
day = days[day_index]
origin = day.get("from") or (days[day_index - 1].get("to", "") if day_index else "")
miles = _as_positive_number(day.get("driveMiles")) or 0
n = len(coords) + 1
lines = []
for i, c in enumerate(coords):
approx = round(miles * (i + 1) / n) if miles else 0
where = (" (~%d mi into the day)" % approx) if approx else ""
lines.append("%d. near latitude %.4f, longitude %.4f%s" % (i + 1, c[0], c[1], where))
zh = any("一" <= ch <= "鿿"
for ch in ((trip.get("title") or "") + origin + (day.get("to") or "")))
lang_line = ("Reply in Chinese; write 中途 (not 途中) for mid-route wording."
if zh else "Reply in English.")
prompt = (
"An EV road-trip day drives from '%s' to '%s' (about %s miles). For EACH of "
"these points on that route (in driving order), name a SPECIFIC real DC "
"fast-charging stop near it — a named highway service-area charging station "
"or a branded supercharger/DC-fast site — on the actual road between origin "
"and destination:\n%s\n\n"
"Give the specific STATION name (e.g. a '<place> 服务区/充电站' or a supercharger "
"site), NOT just the bare city name, and with no coordinates or distances. %s "
'Output ONLY {"names":[ ... ]} — exactly %d strings, one per point, in order. '
"No prose, no markdown."
% (origin, day.get("to", ""), day.get("driveMiles", "?"),
"\n".join(lines), lang_line, len(coords)))
# Naming is best-effort and often runs behind a flaky proxy, so bound each
# request and retry once — a single network blip must not leave every stop
# with the generic fallback name. The coordinates (feasibility) are already
# the backend's, so a total failure is cosmetic, not broken.
for attempt in range(2):
try:
client = anthropic.Anthropic(timeout=40.0, max_retries=0)
def create_once(p):
msg = client.messages.create(model=_MODEL, max_tokens=800,
messages=[{"role": "user", "content": p}])
t = "".join(b.text for b in msg.content
if getattr(b, "type", None) == "text")
if log_fn:
log_fn(msg.usage)
return t, getattr(msg, "stop_reason", None)
text, stop = create_once(prompt)
data = _parse_with_retry(text, lambda: create_once(prompt + _STRICT_JSON_NUDGE),
"name_charging", stop)
names = data.get("names") if isinstance(data, dict) else data
if isinstance(names, list):
return [(_s(x).strip() if not isinstance(x, (dict, list)) else "")
for x in names]
return []
except Exception as e:
print("[warn] name_charging attempt %d failed: %s" % (attempt + 1, e),
file=sys.stderr)
return []
def _place_day_mids(trip, day_index, max_gap, log_fn=None):
"""Replace ONE day's mid-route DC fast charging with evenly-spaced,
backend-placed stops so no charger-to-charger gap exceeds `max_gap` miles —
feasibility is the backend's (interpolated coordinates), the model only NAMES
each stop. The overnight/destination charger and slow (Level-2) top-ups are
kept. No-op when the day is short enough for one charge, or its coordinates
are too degenerate to interpolate."""
day = (trip.get("days") or [])[day_index]
miles = _as_positive_number(day.get("driveMiles"))
if not miles or miles <= max_gap:
return # short day — no mid stop needed
n = int(math.ceil(miles / max_gap)) # n equal pieces ⇒ n−1 mid stops
prev_end = _prev_day_end(trip, day_index)
pts = [(s.get("lat"), s.get("lng")) for s in (day.get("stops") or [])
if isinstance(s.get("lat"), (int, float))
and isinstance(s.get("lng"), (int, float))]
start = prev_end or (pts[0] if pts else None)
end = pts[-1] if pts else None
# Unreliable geometry (span far short of the drive = mis-geocoding) can't be
# interpolated on, and the corridor couldn't position a charger there anyway.
if not start or not end or \
_routes.haversine_km(start[0], start[1], end[0], end[1]) < 0.25 * miles * 1.609:
return
coords = [_interp_day_coord(day, prev_end, j / float(n)) for j in range(1, n)]
if any(c is None for c in coords):
return
names = _name_charging_points(trip, day_index, coords, log_fn=log_fn)
zh = any("一" <= ch <= "鿿" for ch in (trip.get("title") or ""))
generic = "中途快充点" if zh else "DC fast charging"
note = "中途补电" if zh else "mid-route top-up"
# Keep the overnight/destination charger and any slow (Level-2) top-up; DROP
# every other DC-fast stop (the mid-route set we're replacing). Decide by NAME
# + distance to the day's end, not by fraction — a stale stop left over from a
# mis-geocoded day has an unusable coordinate no fraction check would flag.
kept = []
for f in (day.get("fuelCharging") or []):
nm = (f.get("name") or "")
kw = f.get("powerKW")
fast = isinstance(kw, (int, float)) and kw >= 50
overnight = ("过夜" in nm) or ("overnight" in nm.lower())
fla, fln = f.get("lat"), f.get("lng")
near_dest = (isinstance(fla, (int, float)) and isinstance(fln, (int, float))
and _routes.haversine_km(fla, fln, end[0], end[1]) <= 20) # ~12 mi
if not fast or overnight or near_dest:
kept.append(f) # slow top-up, overnight, or the arrival charger
# Real model name when we got one; otherwise a NUMBERED generic so a naming
# failure still yields distinct rows, not N identical "中途快充点".
new_mids = [{"name": (names[i] if i < len(names) and names[i]
else "%s %d" % (generic, i + 1)),
"type": "charge", "lat": c[0], "lng": c[1],
"powerKW": 120, "note": note}
for i, c in enumerate(coords)]
day["fuelCharging"] = kept + new_mids
def autofill_ev_charging(trip, log_fn=None):
"""Place evenly-spaced mid-route DC fast charging on every EV day that needs
it, so the whole trip is drivable with no manual step and no charger-to-charger
gap beyond a safe fraction of range. Coordinates are repaired first (for
mis-geocoded return legs). Best-effort and in place; a no-op for non-EV trips
or an unknown range. Returns the trip."""
vehicle = trip.get("vehicle") or {}
if (vehicle.get("type") or "").lower() != "ev":
return trip
rng = _as_positive_number(vehicle.get("rangeMiles"))
if not rng:
return trip
_heal_day_coords(trip)
# From a full charge the car safely covers (maxChargeSoC − minSoC = 80)% of
# range; hold a margin under that so straight-line/road slippage can't tip a
# gap over the feasibility edge.
max_gap = 0.82 * 0.8 * rng
for i in range(len(trip.get("days") or [])):
try:
_place_day_mids(trip, i, max_gap, log_fn=log_fn)
except Exception as e:
print("[warn] autofill_ev_charging day %d: %s" % (i, e), file=sys.stderr)
return trip
def regenerate_day(trip, day_index, comment_body, log_fn=None):
"""Ask the AI to rewrite a single trip day based on a commenter's suggestion.
Only the targeted day is regenerated; all other days remain unchanged.
Returns the updated day dict (same schema as an element of trip["days"]).
Raises on failure so callers can decide whether to surface or swallow the error.
"""
return _regenerate_day_with_instruction(
trip, day_index,
"A traveler requests this change: \"%s\"" % comment_body,
log_fn=log_fn)
def _s(v):
"""Text of a possibly-null model field. `str(None)` would leak the literal
"None" into match strings and rendered entries."""
return "" if v is None else str(v)
def _coerce_miles(v):
"""Model mileage as an int. Accepts 150, 150.0, "150", "150 mi"; rejects
booleans (isinstance(True, int) is True) and anything unparseable."""
if isinstance(v, bool):
return None
if isinstance(v, (int, float)):
return int(v)
m = re.search(r"-?\d+(?:\.\d+)?", _s(v))
return int(float(m.group())) if m else None
def _stay_lodging(trip, city_name):
"""The lodging entry for a stay's city, or None. Cheap name/area match —
same heuristic as _set_lodging_nights."""
if not (city_name or "").strip() or not isinstance(trip.get("lodging"), list):
return None
needle = city_name.strip().lower()
core = needle.split(",")[0].strip()
word = re.compile(r"\b%s\b" % re.escape(core)) if core else None
for l in trip["lodging"]:
t = ("%s %s" % (_s(l.get("name")), _s(l.get("area")))).lower()
if needle in t or (word and word.search(t)):
return l
return None
def _stop_key(name):
"""'Antelope Canyon (guided tour)' -> 'antelope canyon' — the part of a stop
name that a booking entry is likely to echo."""
s = re.sub(r"\(.*?\)", " ", str(name or "")).lower()
s = re.sub(r"[^\w\s]", " ", s)
s = re.sub(r"\s+", " ", s).strip()
return s if len(s) >= 6 else ""
def _stay_bookings(trip, city_name, span_days=None):
"""Booking-countdown entries belonging to a stay.
Matched by the city name OR by any stop in the stay's days — plenty of
bookings never name the town ("Antelope Canyon guided tour" belongs to the
Page stay), and those are exactly the ones travelers ask to drop."""
if not isinstance(trip.get("bookingCountdown"), list):
return []
needles = []
if (city_name or "").strip():
needle = city_name.strip().lower()
needles.append(needle)
core = needle.split(",")[0].strip()
if core:
needles.append(core)
for d in (span_days or []):
for s in (d.get("stops") or []):
k = _stop_key(s.get("name"))
if k:
needles.append(k)
out = []
for b in trip["bookingCountdown"]:
t = ("%s %s" % (_s(b.get("item")), _s(b.get("where")))).lower()
if any(n in t for n in needles):
out.append(b)
return out
def _regenerate_span_with_instruction(trip, day_start, day_end, out_count,
instruction, city_name="", log_fn=None):
"""Single-shot model call that rewrites a run of consecutive days as
EXACTLY `out_count` replacement days per `instruction`. The wire format is
an object — {"days": [...], "lodging"?: {...}, "bookingCountdown"?: [...]} —
so a request like "swap that hotel" or "skip the permit" can also update the
trip-level sections that belong to this stay.
Returns (new_days, lodging_or_None, bookings_or_None); raises on failure or
day-count mismatch."""
import anthropic
client = anthropic.Anthropic()
days = trip.get("days") or []
span = days[day_start:day_end + 1]
cur_lodging = _stay_lodging(trip, city_name)
cur_bookings = _stay_bookings(trip, city_name, span)
days_summary = "\n".join(
"Day %d (%s): %s [%s → %s]" % (
i + 1, d.get("date", ""), d.get("title", ""),
d.get("from", ""), d.get("to", ""))
for i, d in enumerate(days)
)
prev_to = days[day_start - 1].get("to", "") if day_start > 0 else ""
next_from = days[day_end + 1].get("from", "") if day_end + 1 < len(days) else ""
continuity = ""
if prev_to:
continuity += "The day before this run ends at '%s'. " % prev_to
if next_from:
continuity += "The day after this run starts at '%s'. " % next_from
day_schema = (
'{"date":str,"title":str,"from":str,"to":str,"driveMiles":int,"driveTime":str,'
'"overnight":str|null,"timezoneNote":str?,'
'"weather":{"icon":"sunny|partly-cloudy|cloudy|rain|snow|storm|windy|fog","high":int,"low":int},'
'"stops":[{"name":str,"type":"park|hike|scenic|city|tour|food|lodging",'
'"lat":float,"lng":float,"admission":{"status":"free|included|paid|unknown",'
'"label":str?,"price":{"amount":number,"currency":str,"unit":'
'"person|vehicle|group|booking|total","reliability":'
'"verified|reference|estimate"}?}?,"note":str}],'
'"fuelCharging":[{"name":str,"type":"gas|charge","lat":float,"lng":float,"note":str}],'
'"meal":{"name":str,"perPerson":int},"risks":[str]}'
)
# Trip-level sections that belong to this stay: hand them over so requests
# like "swap that hotel" or "drop the tour booking" can actually land.
extras, extra_schema = "", ""
if cur_lodging is not None:
extras += ("\nThis stay's lodging entry:\n%s\n"
% json.dumps(cur_lodging, ensure_ascii=False))
extra_schema += (
',\n "lodging": {"name":str,"area":str,"pricePerNight":int,"rating":str}'
" // OPTIONAL — include ONLY if the request changes where they sleep"
" (a different hotel, cheaper, closer). Omit 'nights' and 'booked'.")
if cur_bookings:
extras += ("\nThis stay's booking-countdown entries:\n%s\n"
% json.dumps(cur_bookings, ensure_ascii=False))
extra_schema += (
',\n "bookingCountdown": [{"item":str,"bookBy":"YYYY-MM-DD","where":str,'
'"category":"attraction|restaurant|hotel",'
'"price":{"amount":number,"currency":str,"unit":'
'"person|night|vehicle|group|booking|total",'
'"reliability":"verified|reference|estimate"}?, '
'"priority":"high|medium|low","note":str}]'
" // OPTIONAL — include ONLY if the request changes what must be"
" reserved for this stay; return the FULL replacement list for it"
" (empty list = drop them all). No bookBy date before today.")
prompt = (
"You are updating a run of consecutive days in an existing road trip itinerary.\n\n"
"Trip: %s\nTODAY is %s.\n"
"All days (for continuity context):\n%s\n\n"
"Current run — Days %d to %d:\n%s\n%s\n"
"%s\n\n"
"Rewrite ONLY this run, as EXACTLY %d day(s) total. %s"
"You MAY update this run's driving distance/time, stops, meals, fuel/charging, "
"risks%s — whatever the request calls for. Use accurate lat/lng for all stops and "
"include admission status for every park/hike/scenic/tour stop.\n"
"Output ONLY a JSON object — no prose, no markdown fences; any double quote "
'inside a string value must be escaped as \\". Shape:\n'
'{\n "days": [day, ...] // EXACTLY %d element(s)%s\n}\n'
"Each day matches: %s\n"
"Return JSON only."
) % (
trip.get("title", ""),
time.strftime("%Y-%m-%d"),
days_summary,
day_start + 1, day_end + 1,
json.dumps(span, ensure_ascii=False, indent=2),
extras,
instruction,
out_count,
continuity,
(", the hotel and the bookings for this stay"
if (cur_lodging is not None or cur_bookings) else ""),
out_count,
extra_schema,
day_schema,
)
def create_once(p):
msg = client.messages.create(
model=_MODEL, max_tokens=min(16000, 2500 + 2600 * out_count),
messages=[{"role": "user", "content": p}])
t = "".join(b.text for b in msg.content if getattr(b, "type", None) == "text")
if log_fn:
log_fn(msg.usage)
return t, getattr(msg, "stop_reason", None)
text, stop = create_once(prompt)
got = _parse_with_retry(
text, lambda: create_once(prompt + _STRICT_JSON_NUDGE),
"regenerate_span", stop)
new_days = got.get("days") if isinstance(got, dict) else None
if (not isinstance(new_days, list) or len(new_days) != out_count
or not all(isinstance(d, dict) for d in new_days)):
raise ValueError("model returned %s day(s) for the run, expected %d"
% (len(new_days) if isinstance(new_days, list) else "no",
out_count))
new_lodging = got.get("lodging")
if not isinstance(new_lodging, dict) or not new_lodging.get("name"):
new_lodging = None
new_bookings = got.get("bookingCountdown")
if not isinstance(new_bookings, list) or not all(
isinstance(b, dict) and b.get("item") for b in new_bookings):
new_bookings = None
return new_days, new_lodging, new_bookings
# --------------------------------------------------------------------------- #
# Trip editing (phase 3): remove one overnight stop from an existing trip
# --------------------------------------------------------------------------- #
def _trip_start_date(trip):
"""datetime.date of Day 1, or None when it can't be derived. Month/day come
from days[0].date ('MM/DD'); the year from dateRange ('YYYY-MM-DD ~ …'),
falling back to generationDate."""
days = trip.get("days") or []
if not days:
return None
m = re.match(r"^\s*(\d{1,2})/(\d{1,2})", str(days[0].get("date") or ""))
if not m:
return None
year = None
for field in ("dateRange", "generationDate"):
ym = re.match(r"\s*(\d{4})-", str(trip.get(field) or ""))
if ym:
year = int(ym.group(1))
break
if not year:
return None
try:
return datetime.date(year, int(m.group(1)), int(m.group(2)))
except ValueError:
return None
def _resequence_dates(trip):
"""Rewrite every day's 'MM/DD' date as Day1+k and rebuild dateRange.
Returns the per-day ISO dates (aligned with trip['days']), or None when
the trip's dates can't be parsed — nothing is changed in that case."""
start = _trip_start_date(trip)
if not start:
return None
iso = []
for k, d in enumerate(trip.get("days") or []):
cur = start + datetime.timedelta(days=k)
d["date"] = cur.strftime("%m/%d")
iso.append(cur.strftime("%Y-%m-%d"))
if iso:
trip["dateRange"] = "%s ~ %s" % (iso[0], iso[-1])
return iso
def _weather_forecast(lat, lng):
"""Real per-day forecast via tools/weather_client (NWS, free, no key).
Returns the client's dict, or None on any failure — trip editing must keep
working fully offline."""
try:
if _ROOT not in sys.path:
sys.path.insert(0, _ROOT)
from tools import weather_client
return weather_client.forecast(lat, lng)
except Exception as e:
print("[warn] weather refresh unavailable: %s" % e, file=sys.stderr)
return None
def _climatology(lat, lng, iso_date):
"""Seasonal 'typical for the date' via tools/weather_client. Best-effort."""
try:
if _ROOT not in sys.path:
sys.path.insert(0, _ROOT)
from tools import weather_client
y, mo, dy = iso_date.split("-")
return weather_client.climatology(lat, lng, mo, dy)
except Exception as e:
print("[warn] climatology unavailable: %s" % e, file=sys.stderr)
return None
def _apply_weather(day, data, source, iso_date):
"""Stamp a day's weather from a forecast/climatology `data` dict and tag its
provenance so the UI (and the advisory engine) can tell a real forecast from
a seasonal average. Never invents fields the source didn't provide."""
w = day.get("weather") or {}
w["icon"] = data.get("icon") or w.get("icon") or "partly-cloudy"
if isinstance(data.get("high"), (int, float)):
w["high"] = int(data["high"])
if isinstance(data.get("low"), (int, float)):
w["low"] = int(data["low"])
# Provenance + the extra signals the advisory engine (PR②) will use.
w["source"] = source # "forecast" | "climatology"
w["asOf"] = iso_date
for k in ("precipProb", "windMph", "wetShare", "summary"):
if data.get(k) is not None:
w[k] = data[k]
day["weather"] = w
def _refresh_weather(trip, first_idx, iso_dates):
"""Refresh weather for days [first_idx..] whose calendar dates are known.
For each such day: a real forecast if the date is within the forecast
window (tagged source="forecast"), else a seasonal climatology average
(source="climatology"). Days the model estimated and we couldn't improve
keep their values untagged. Best-effort, never raises."""
if not iso_dates:
return
days = trip.get("days") or []
fc_cache, clim_cache = {}, {}
for i in range(max(first_idx, 0), len(days)):
if i >= len(iso_dates):
break
d = days[i]
iso = iso_dates[i]
stop = next((s for s in reversed(d.get("stops") or [])
if isinstance(s.get("lat"), (int, float))
and isinstance(s.get("lng"), (int, float))), None)
if not stop or not iso:
continue
key = (round(stop["lat"], 1), round(stop["lng"], 1))
if key not in fc_cache:
fc_cache[key] = _weather_forecast(stop["lat"], stop["lng"]) or {}
fc = fc_cache[key]
hit = None
if fc.get("source") in ("nws", "open-meteo"):
hit = next((x for x in (fc.get("days") or [])
if x.get("date") == iso), None)
if hit:
_apply_weather(d, hit, "forecast", iso)
continue
# Beyond the forecast window (or no live data) — fall back to seasonal.
ck = (key, iso[5:]) # cache by lat/lng + MM-DD
if ck not in clim_cache:
clim_cache[ck] = _climatology(stop["lat"], stop["lng"], iso)
clim = clim_cache[ck]
if clim:
_apply_weather(d, clim, "climatology", iso)
def refresh_trip_weather(trip):
"""Refresh the whole trip's weather from real forecasts / seasonal averages,
computing each day's calendar date itself. This is what the webapp calls when
a trip is generated or opened, so the page shows real weather instead of the
model's guess. Best-effort, never raises; returns the trip."""
start = _trip_start_date(trip)
days = trip.get("days") or []
if start and days:
iso = [(start + datetime.timedelta(days=k)).isoformat()
for k in range(len(days))]
_refresh_weather(trip, 0, iso)
return trip
# --------------------------------------------------------------------------- #
# Weather advisories (deterministic — no model call)
# --------------------------------------------------------------------------- #
# Phrase bank, keyed (icon-or-condition, has_outdoor_activity). Two source
# voices: a real forecast speaks in the future ("expect…"), a climatology
# average speaks in tendencies ("this stretch is typically…"). Kept in the
# skill so both language variants live next to the planning logic.
_ADVICE = {
"en": {
"storm": ("Thunderstorms in the forecast — lightning and flash-flood risk.",
"Thunderstorms are typical here this time of year."),
"snow": ("Snow in the forecast — roads and high trails may be affected.",
"Snow is common here this season — check road status."),
"rain": ("Rain likely — trails get slick and slot canyons flood fast.",
"This stretch is often wet this time of year."),
"wind": ("Strong wind expected — dust, and dicey driving for high-profile vehicles.",
"Strong afternoon wind is typical here this season."),
"heat": ("Extreme heat expected — start early, carry far more water than feels necessary.",
"This region is typically very hot this time of year."),
"cold": ("Hard freeze expected — plan for ice and short daylight.",
"Nights are typically below freezing here this season."),
"hike_suffix": " Consider moving the hike, or keep it to the morning.",
"reslot_suffix": " No outdoor plans that day, so it mostly affects the drive.",
"verify": " Re-check the official forecast the day before you go.",
},
"zh": {
"storm": ("预报有雷暴——注意雷击和山洪风险。",
"这个季节这一带通常多雷暴。"),
"snow": ("预报有降雪——道路和高海拔步道可能受影响。",
"这个季节这里常有降雪——请查路况。"),
"rain": ("预计有雨——步道湿滑,狭缝峡谷易突发山洪。",
"这个季节这一段通常偏湿。"),
"wind": ("预计大风——扬尘,高车身车辆行车需谨慎。",
"这个季节这里午后通常有大风。"),
"heat": ("预计极端高温——尽早出发,带比你以为需要的多得多的水。",
"这个季节这一区域通常非常炎热。"),
"cold": ("预计严重霜冻——注意结冰和白昼短。",
"这个季节这里夜间通常低于冰点。"),
"hike_suffix": " 可考虑把徒步改期,或只安排在上午。",
"reslot_suffix": " 这天没有户外行程,主要影响的是驾驶。",
"verify": " 出发前一天请以官方预报再核实一次。",
},
}
_HEAT_HIGH = 100 # °F daytime high that counts as "extreme heat"
_COLD_LOW = 25 # °F overnight low that counts as a hard freeze
_WIND_MPH = 35 # sustained/gust max that counts as "strong wind"
_WET_PROB = 60 # forecast precip-probability that counts as "rain likely"
_OUTDOOR_TYPES = ("hike", "park")
def _day_condition(w):
"""Reduce a day's weather dict to one advisory key, or None if unremarkable.
Order = severity: storm > snow > heat > cold > wind > rain."""
icon = w.get("icon")
if icon == "storm":
return "storm"
if icon == "snow":
return "snow"
hi, lo = w.get("high"), w.get("low")
if isinstance(hi, (int, float)) and hi >= _HEAT_HIGH:
return "heat"
if isinstance(lo, (int, float)) and lo <= _COLD_LOW:
return "cold"
if isinstance(w.get("windMph"), (int, float)) and w["windMph"] >= _WIND_MPH:
return "wind"
if icon == "rain" or (isinstance(w.get("precipProb"), (int, float))
and w["precipProb"] >= _WET_PROB):
return "rain"
return None
def _has_outdoor(day):
return any(s.get("type") in _OUTDOOR_TYPES for s in (day.get("stops") or []))
def weather_advisories(trip):
"""Per-day weather advisories for a trip — deterministic, no model call.
Returns a list aligned with trip['days']; each item is None (nothing worth
flagging) or {severity, source, message}. severity is "high" when notable
weather coincides with an outdoor day, else "info". Only days whose weather
carries a provenance tag (source == "forecast"|"climatology", set by
refresh_trip_weather) get an advisory — the model's own estimate is never
reliable enough to warn on. Language follows trip['lang']."""
lang = "zh" if str(trip.get("lang", "")).lower().startswith("zh") else "en"
bank = _ADVICE[lang]
out = []
for day in (trip.get("days") or []):
w = day.get("weather") or {}
source = w.get("source")
cond = _day_condition(w) if source in ("forecast", "climatology") else None
if not cond:
out.append(None)
continue
forecast_msg, climate_msg = bank[cond]
msg = forecast_msg if source == "forecast" else climate_msg
outdoor = _has_outdoor(day)
msg += bank["hike_suffix"] if outdoor else bank["reslot_suffix"]
if source == "forecast":
msg += bank["verify"]
out.append({
"severity": "high" if outdoor else "info",
"source": source,
"condition": cond,
"message": msg,
})
return out
def _mi(day):
"""driveMiles as an int, tolerating missing/garbage model values."""
return _coerce_miles(day.get("driveMiles")) or 0
def _set_lodging_nights(trip, city_name, nights):
"""Keep the lodging list consistent with a stay-length change: entries
referencing the city get the new night count (same cheap matching as
_drop_city_references)."""
if not (city_name or "").strip() or not isinstance(trip.get("lodging"), list):
return
needle = city_name.strip().lower()
core = needle.split(",")[0].strip()
word = re.compile(r"\b%s\b" % re.escape(core)) if core else None
for l in trip["lodging"]:
t = ("%s %s" % (_s(l.get("name")), _s(l.get("area")))).lower()
if needle in t or (word and word.search(t)):
l["nights"] = nights
def _drop_city_references(trip, city_name):
"""Drop lodging / booking-countdown lines that reference the removed city,
so the visible page doesn't keep advertising a hotel we no longer stay at."""
if not (city_name or "").strip():
return
needle = city_name.strip().lower()
core = needle.split(",")[0].strip()
word = re.compile(r"\b%s\b" % re.escape(core)) if core else None
def refers(text):
t = (text or "").lower()
return needle in t or bool(word and word.search(t))
if isinstance(trip.get("lodging"), list):
trip["lodging"] = [l for l in trip["lodging"]
if not refers("%s %s" % (_s(l.get("name")), _s(l.get("area"))))]
if isinstance(trip.get("bookingCountdown"), list):
trip["bookingCountdown"] = [b for b in trip["bookingCountdown"]
if not refers("%s %s" % (_s(b.get("item")), _s(b.get("where"))))]
def remove_city(trip, day_start, day_end, city_name="", log_fn=None):
"""Remove one overnight stop (days [day_start..day_end], 0-based inclusive)
from an existing trip and stitch the itinerary back together.
One model call rewrites the joined driving day (previous overnight → the
removed stop's successor); everything else is deterministic: later days
shift earlier, drivingDays/totalMiles/dateRange are recomputed, lodging and
booking-countdown lines for the removed city are dropped, and weather is
refreshed from a real forecast where one covers the shifted dates.
The trip's first and last day can never be removed. The trip dict is only
mutated after the model call succeeds, so a failed edit never leaves a
half-edited trip for callers to persist.
"""
days = trip.get("days") or []
n = len(days)
if n < 3:
raise ValueError("trip is too short to edit")
if not (1 <= day_start <= day_end <= n - 2):
raise ValueError("span must keep the trip's first and last day")
old_day_count = n
old_total_miles = trip.get("totalMiles") if isinstance(
trip.get("totalMiles"), (int, float)) else 0
join_idx = day_end + 1
join_day = days[join_idx]
prev_day = days[day_start - 1]
new_from = prev_day.get("overnight") or prev_day.get("to") or ""
old_to = join_day.get("to") or ""
removed = (city_name or days[day_start].get("overnight")
or join_day.get("from") or "that stop")
instruction = (
"The overnight stop '%s' has been REMOVED from the trip. This day "
"previously drove '%s' -> '%s'. Rewrite it as ONE day driving DIRECTLY "
"from '%s' to '%s': recompute driveMiles and driveTime realistically for "
"that direct route, choose stops and fuel/charging along the direct route "
"only, and do not route through or mention '%s'."
% (removed, join_day.get("from", ""), old_to, new_from, old_to, removed)
)
new_join = _regenerate_day_with_instruction(trip, join_idx, instruction, log_fn=log_fn)
# The model rewrote the leg's content; its endpoints are ours to enforce.
new_join["from"] = new_from
new_join["to"] = old_to
new_join["overnight"] = join_day.get("overnight")
removed_miles = sum(_mi(d) for d in days[day_start:join_idx + 1])
trip["days"] = days[:day_start] + [new_join] + days[join_idx + 1:]
trip["drivingDays"] = len(trip["days"])
if isinstance(trip.get("totalMiles"), (int, float)):
delta = _mi(new_join) - removed_miles
trip["totalMiles"] = max(0, int(trip["totalMiles"]) + delta)
iso = _resequence_dates(trip)
_drop_city_references(trip, city_name)
_recompute_budget(trip, old_day_count, old_total_miles)
_refresh_weather(trip, day_start, iso)
despread_stops(trip) # the rewritten day may introduce coincident pins
return trip
def set_nights(trip, day_start, day_end, city_name, nights, log_fn=None):
"""Change how long one overnight stop lasts: the city's run of days
[day_start..day_end] is rewritten as `nights` days by one model call, then
the same deterministic cascade as remove_city runs (dates, totals, lodging
night counts, weather, pin de-stacking).
Unlike remove_city, a run anchored to the trip's FIRST day is editable —
the arrival day always survives with its driving leg preserved verbatim;
only the stay length changes. The trip's final day stays untouched.
The trip dict is mutated only after the model call succeeds, so a failed
edit never leaves a half-edited trip for callers to persist.
"""
days = trip.get("days") or []
n = len(days)
if n < 2:
raise ValueError("trip is too short to edit")
if not (0 <= day_start <= day_end <= n - 2):
raise ValueError("span must lie before the trip's final day")
try:
nights = int(nights)
except (TypeError, ValueError):
raise ValueError("invalid night count")
current = day_end - day_start + 1
if not (1 <= nights <= 7):
raise ValueError("nights must be between 1 and 7")
if nights == current:
raise ValueError("stay is already %d night(s) long" % current)
if n - current + nights > 21:
raise ValueError("trip would exceed 21 days")
return _replan_stay(trip, day_start, day_end, city_name, nights, "", log_fn)
def _replan_stay(trip, day_start, day_end, city_name, out_count, extra_request, log_fn):
"""Shared engine behind set_nights / revise_stay: rewrite one stay's run as
`out_count` days via a single model call (honoring an optional traveler
request), then run the deterministic cascade. Callers own the validation."""
days = trip.get("days") or []
arrival = days[day_start]
city = city_name or arrival.get("overnight") or "that stop"
current = day_end - day_start + 1
parts = []
if out_count != current:
parts.append("The traveler changed the stay at '%s' from %d to %d night(s)."
% (city, current, out_count))
else:
parts.append("The traveler wants this %d-night stay at '%s' replanned."
% (current, city))
if extra_request:
parts.append("Traveler request — honor it as the top priority: \"%s\"."
% extra_request)
parts.append(
"Replan this run: the FIRST day still drives '%s' -> '%s' (currently "
"%s mi, %s) — keep those endpoints, but its sightseeing, and therefore "
"its distance and time, may change; every other day stays local around "
"'%s'. Redistribute the area's best sights across the new length — drop "
"the least essential ones when shrinking, add worthwhile nearby ones "
"when growing."
% (arrival.get("from", ""), arrival.get("to", ""),
arrival.get("driveMiles", "?"), arrival.get("driveTime", "?"),
city))
instruction = " ".join(parts)
old_day_count = len(days)
old_total_miles = trip.get("totalMiles") if isinstance(
trip.get("totalMiles"), (int, float)) else 0
old_span = days[day_start:day_end + 1]
stale_bookings = _stay_bookings(trip, city, old_span)
new_run, new_lodging, new_bookings = _regenerate_span_with_instruction(
trip, day_start, day_end, out_count, instruction,
city_name=city, log_fn=log_fn)
# Anchors are ours to enforce: the stay's identity (overnight) and where the
# arrival leg starts and ends. Its distance/time may now change — a scenic
# detour on the way in must show up in the mileage, not be silently reverted.
overnight = arrival.get("overnight")
for k, d in enumerate(new_run):
d["overnight"] = overnight
if k == 0:
d["from"] = arrival.get("from", "")
d["to"] = arrival.get("to", "")
miles = _coerce_miles(d.get("driveMiles"))
d["driveMiles"] = miles if miles is not None else arrival.get("driveMiles")
drive_time = _s(d.get("driveTime")).strip()
d["driveTime"] = drive_time or arrival.get("driveTime")
# Day 1 of the trip anchors date resequencing — when the run is
# start-anchored the model's date must never displace the calendar.
d["date"] = arrival.get("date", d.get("date", ""))
else:
d["from"] = overnight or d.get("from", "")
d["to"] = overnight or d.get("to", "")
old_miles = sum(_mi(d) for d in days[day_start:day_end + 1])
trip["days"] = days[:day_start] + new_run + days[day_end + 1:]
trip["drivingDays"] = len(trip["days"])
if isinstance(trip.get("totalMiles"), (int, float)):
delta = sum(_mi(d) for d in new_run) - old_miles
trip["totalMiles"] = max(0, int(trip["totalMiles"]) + delta)
_apply_stay_lodging(trip, city, new_lodging, out_count)
_apply_stay_bookings(trip, stale_bookings, new_bookings)
if out_count != current:
_set_lodging_nights(trip, city, out_count)
iso = _resequence_dates(trip)
_recompute_budget(trip, old_day_count, old_total_miles)
_refresh_weather(trip, day_start, iso)
despread_stops(trip)
return trip
def _apply_stay_lodging(trip, city_name, new_lodging, nights):
"""Swap in the model's replacement hotel for this stay. The night count
stays ours (it follows the edit, not the model) and `booked` resets to
False — it's a different property. No-op when the model proposed none."""
if not new_lodging:
return
cur = _stay_lodging(trip, city_name)
entry = {
"name": _s(new_lodging.get("name")).strip()[:120],
"area": _s(new_lodging.get("area") or (cur or {}).get("area") or city_name)[:120],
"nights": nights,
"booked": False,
}
price = new_lodging.get("pricePerNight")
if isinstance(price, (int, float)) and price >= 0:
entry["pricePerNight"] = int(price)
elif cur and "pricePerNight" in cur:
entry["pricePerNight"] = cur["pricePerNight"]
rating = _s(new_lodging.get("rating")).strip()
if rating:
entry["rating"] = rating[:16]
elif cur and cur.get("rating"):
entry["rating"] = cur["rating"]
if cur is not None:
cur.clear()
cur.update(entry)
else:
trip.setdefault("lodging", []).append(entry)
def _apply_stay_bookings(trip, stale, new_bookings):
"""Replace this stay's booking-countdown entries (`stale`, matched BEFORE the
days were spliced) with the model's list — an empty list means the request
dropped them. No-op when the model omitted the key, so unrelated bookings are
never disturbed."""
if new_bookings is None or not isinstance(trip.get("bookingCountdown"), list):
return
keep = [b for b in trip["bookingCountdown"] if b not in stale]
cleaned = []
for b in new_bookings:
item = _s(b.get("item")).strip()
if not item:
continue
entry = {"item": item[:160],
"bookBy": _s(b.get("bookBy")).strip()[:10],
"where": _s(b.get("where")).strip()[:120],
"priority": (b.get("priority")
if b.get("priority") in ("high", "medium", "low")
else "medium")}
category = b.get("category")
if category in ("attraction", "restaurant", "hotel"):
entry["category"] = category
raw_price = b.get("price")
if isinstance(raw_price, dict):
amount = raw_price.get("amount")
if (isinstance(amount, (int, float)) and not isinstance(amount, bool)
and amount >= 0):
price = {"amount": round(amount, 2)}
currency = _s(raw_price.get("currency")).strip().upper()[:3]
if currency:
price["currency"] = currency
unit = raw_price.get("unit")
if unit in ("person", "night", "vehicle", "group", "booking", "total"):
price["unit"] = unit
reliability = raw_price.get("reliability")
if reliability in ("verified", "reference", "estimate"):
price["reliability"] = reliability
entry["price"] = price
note = _s(b.get("note")).strip()
if note:
entry["note"] = note[:240]
cleaned.append(entry)
trip["bookingCountdown"] = keep + cleaned
# --------------------------------------------------------------------------- #
# Budget recomputation (deterministic — no model call)
# --------------------------------------------------------------------------- #
_LODGING_WORDS = ("lodging", "hotel", "accommodation", "stay",
"\u4f4f\u5bbf", "\u9152\u5e97") # 住宿 / 酒店
_FUEL_WORDS = ("fuel", "gas", "gasoline", "charging", "electricity",
"\u71c3\u6cb9", "\u6cb9\u8d39", "\u52a0\u6cb9",
"\u5145\u7535", "\u7535\u8d39") # 燃油/油费/加油/充电/电费
_DAYS_RE = re.compile(r"(\d+)\s*(days?|\u5929)", re.I) # "7 days" / "7 天"
_NIGHTS_RE = re.compile(r"(\d+)\s*(nights?|\u665a)", re.I) # "6 nights" / "6 晚"
_MILES_RE = re.compile(r"([\d,]+)\s*(mi\b|miles?|km\b|\u82f1\u91cc|\u516c\u91cc)", re.I)
def _travelers_count(trip):
"""'2 adults' -> 2; '2 adults + 1 kid' -> 3. Falls back to 1."""
nums = [int(n) for n in re.findall(r"\d+", str(trip.get("travelers") or ""))]
return sum(nums) if nums else 1
def _sub_first_number(text, pattern, value):
"""Rewrite the first number matched by `pattern` (a 2-group regex whose
group(1) is the number) with `value`, keeping the unit intact."""
text = _s(text)
m = pattern.search(text)
if not m:
return text
fmt = "{:,}".format(value) if "," in m.group(1) else str(value)
return text[:m.start(1)] + fmt + text[m.end(1):]
def _lodging_total(trip):
total = 0
for l in (trip.get("lodging") or []):
price, nights = l.get("pricePerNight"), l.get("nights")
if isinstance(price, (int, float)) and isinstance(nights, (int, float)):
total += int(price) * int(nights)
return total
def _recompute_budget(trip, old_days, old_miles):
"""Bring the budget back in line with an edited trip. Deterministic:
* lodging line -> recomputed from the lodging list (authoritative after
a hotel swap or a night-count change)
* fuel line -> scaled by new/old total miles
* "N days" line -> scaled by new/old day count (food, rental car, ...)
* anything else -> untouched (park passes, tours, misc)
Labels carrying a night/day/mile count are rewritten to match. Totals and
per-person are always recomputed from the item list. Best-effort: any item
it cannot interpret is left exactly as it was.
"""
budget = trip.get("budget")
if not isinstance(budget, dict) or not isinstance(budget.get("items"), list):
return
new_days = len(trip.get("days") or []) or old_days
new_miles = trip.get("totalMiles")
if not isinstance(new_miles, (int, float)):
new_miles = old_miles
nights_total = sum(int(l.get("nights") or 0) for l in (trip.get("lodging") or []))
for item in budget["items"]:
label = _s(item.get("label")) # normalized once; never touch the raw value
low = label.lower()
amount = _coerce_miles(item.get("amount")) # ints, floats and "186"
if amount is None:
continue
if any(w in low for w in _LODGING_WORDS):
total = _lodging_total(trip)
if total > 0:
item["amount"] = total
if nights_total:
item["label"] = _sub_first_number(label, _NIGHTS_RE, nights_total)
continue
if any(w in low for w in _FUEL_WORDS):
if old_miles and new_miles and old_miles > 0:
item["amount"] = max(0, int(round(amount * float(new_miles) / old_miles)))
item["label"] = _sub_first_number(label, _MILES_RE, int(new_miles))
continue
if _DAYS_RE.search(label) and old_days > 0 and new_days != old_days:
item["amount"] = max(0, int(round(amount * float(new_days) / old_days)))
item["label"] = _sub_first_number(label, _DAYS_RE, new_days)
_retotal_budget(trip, budget)
def _retotal_budget(trip, budget):
"""Recompute budget.total / budget.perPerson from the item list."""
total = sum(a for a in (_coerce_miles(i.get("amount")) for i in budget["items"])
if a is not None)
budget["total"] = total
budget["perPerson"] = int(round(total / max(1, _travelers_count(trip))))
# --------------------------------------------------------------------------- #
# Fuel / EV backfill (deterministic — no model call)
# --------------------------------------------------------------------------- #
# Visual region theme -> fuel_client price-region key (rough prior; the label
# always shows the assumed price and the reliability stays "estimate").
_FUEL_REGION = {"desert": "southwest", "mountain": "mountain", "coast": "west",
"forest": "pacificnw", "autumn": "northeast"}
def _as_positive_number(x):
try:
v = float(x)
except (TypeError, ValueError):
return None
return v if v > 0 else None
def refresh_trip_fuel(trip, efficiency=None):
"""Replace the model's guessed fuel/charging budget line with the same
deterministic math the agent workflow gets from tools/fuel_client — one
source of truth for energy economics across the skill and the webapp.
`efficiency` is the user's stated MPG (gas/RV) or mi-per-kWh (EV); falls
back to the trip's vehicle block, then the client defaults. Best-effort,
never raises; returns the trip."""
try:
if _ROOT not in sys.path:
sys.path.insert(0, _ROOT)
from tools import fuel_client
miles = _as_positive_number(trip.get("totalMiles"))
budget = trip.get("budget")
if miles is None or not isinstance(budget, dict) \
or not isinstance(budget.get("items"), list):
return trip
cur = str(budget.get("currency")
or (trip.get("units") or {}).get("currency") or "USD").upper()
if cur != "USD":
# fuel_client's price priors are US-only — for a non-USD trip the
# model's own local-currency estimate is the better number; keep it.
return trip
vehicle = trip.get("vehicle") or {}
vtype = (vehicle.get("type") or "gas").lower()
eff = _as_positive_number(efficiency)
zh = (trip.get("lang") == "zh")
if vtype == "ev":
per_kwh = eff or fuel_client.EV_MI_PER_KWH
data = fuel_client.ev_cost(int(miles), mi_per_kwh=per_kwh)
label = ("充电(约 %d 英里 · %g 英里/千瓦时 · $%.2f/千瓦时)"
% (miles, data["miPerKWh"], data["pricePerKWh"])
if zh else data["label"])
else:
mpg = eff or _as_positive_number(vehicle.get("mpg")) \
or (10 if vtype == "rv" else 26)
region = _FUEL_REGION.get(trip.get("region"), "us")
data = fuel_client.gas_cost(int(miles), mpg, region=region)
label = ("燃油(约 %d 英里 · %g MPG · $%.2f/加仑)"
% (miles, data["mpg"], data["pricePerGal"])
if zh else data["label"])
item = next((i for i in budget["items"]
if any(w in _s(i.get("label")).lower() for w in _FUEL_WORDS)),
None)
if item is None:
item = {}
budget["items"].append(item)
item["label"] = label
item["amount"] = int(round(data["cost"]))
item["reliability"] = "estimate"
item["source"] = "fuel_client"
_retotal_budget(trip, budget)
except Exception as e:
print("[warn] fuel backfill unavailable: %s" % e, file=sys.stderr)
return trip
def _day_charge_frac(day, charger, origin=None):
"""Position of a charge stop along a day's drive (0..1) from coordinates —
straight-line apportioning between the day's origin and its last stop.
`origin` is where the day really starts (the previous day's end); a day's
stop list often begins at the first *sight*, not at the overnight town, so
without it a charger near the first sight would look like frac≈0. Falls
back to the day's first stop. None when coordinates are missing,
degenerate, or implausible for the day's mileage (a mis-geocoded endpoint,
or an out-and-back day)."""
try:
pts = [(s.get("lat"), s.get("lng")) for s in (day.get("stops") or [])
if isinstance(s.get("lat"), (int, float)) and isinstance(s.get("lng"), (int, float))]
cla, cln = charger.get("lat"), charger.get("lng")
if not isinstance(cla, (int, float)) or not isinstance(cln, (int, float)):
return None
start = origin or (pts[0] if pts else None)
end = pts[-1] if pts else None
if not start or not end:
return None
# Sanity: a day that drives N miles should have endpoints a meaningful
# fraction of that apart — otherwise the geocodes can't be trusted to
# place a charger along the leg.
miles = _as_positive_number(day.get("driveMiles"))
span_km = _routes.haversine_km(start[0], start[1], end[0], end[1])
if miles and span_km < 0.25 * miles * 1.609:
# The day's own stop geocodes are unreliable. When the origin
# anchor (yesterday's end) is sound, fall back to distance-from-
# origin over road miles — slightly early-biased (crow-fly ≤ road),
# which is the safe direction for charge planning.
if origin is None:
return None
frac = _routes.haversine_km(start[0], start[1], cla, cln) / (miles * 1.609)
return max(0.0, min(0.95, frac))
a = _routes.haversine_km(start[0], start[1], cla, cln)
b = _routes.haversine_km(cla, cln, end[0], end[1])
if a + b <= 0:
return None
return a / (a + b)
except Exception:
return None
def refresh_trip_ev_corridor(trip):
"""Fill trip['evPlan'] for an EV trip from tools/charging_client.corridor —
per-leg state-of-charge from the days' driveMiles and charge stops. Charge
stops positioned mid-route (by their coordinates) split the day into
charger-to-charger sub-legs; stops at/near the destination count as the
arrival charger, as before. Purely computational (no network). Respects an
existing evPlan (agent- or demo-built). Best-effort, never raises; returns
the trip."""
try:
vehicle = trip.get("vehicle") or {}
if (vehicle.get("type") or "").lower() != "ev" or trip.get("evPlan"):
return trip
rng = _as_positive_number(vehicle.get("rangeMiles"))
if rng is None:
return trip
legs = []
prev_end = None # where yesterday ended = today's true origin
for i, d in enumerate(trip.get("days") or []):
day_pts = [(s.get("lat"), s.get("lng")) for s in (d.get("stops") or [])
if isinstance(s.get("lat"), (int, float))
and isinstance(s.get("lng"), (int, float))]
miles = _as_positive_number(d.get("driveMiles"))
if miles is None:
if day_pts:
prev_end = day_pts[-1]
continue
chargers = [f for f in (d.get("fuelCharging") or [])
if (f.get("type") or "").lower() == "charge"]
mids, at_dest = [], []
for f in chargers:
kw = f.get("powerKW")
# Only DC-fast stops can be mid-leg splitters — a Level-2 /
# hotel charger (< 50 kW) is an overnight top-up, wherever its
# pin happens to sit along the day.
fast = isinstance(kw, (int, float)) and kw >= 50
frac = _day_charge_frac(d, f, prev_end) if fast else None
# A fast charger splits the day unless it sits within ~30 mi of
# either end (that's the origin/destination charger). An ABSOLUTE
# margin, not a fixed fraction, keeps a real mid stop ~150 mi
# before the end of a very long day from being mistaken for the
# arrival charger (a 1030 mi day's 6th of 7 stops lands at 0.86).
margin = min(0.4, 30.0 / miles) if miles else 0.06
if frac is not None and margin < frac < 1 - margin:
mids.append({"name": f.get("name"),
"powerKW": kw, "frac": frac})
else:
# slow charger, no/degenerate coordinates, or at the ends
# of the day — counts as the arrival charger
at_dest.append(f)
mids.sort(key=lambda s: s["frac"])
kws = [f.get("powerKW") for f in at_dest
if isinstance(f.get("powerKW"), (int, float))]
legs.append({"to": d.get("to") or d.get("overnight") or d.get("title"),
"miles": miles,
"charger": bool(at_dest),
"chargerKW": int(max(kws)) if kws else None,
"dayIndex": i,
"stops": mids})
if day_pts:
prev_end = day_pts[-1]
if not legs:
return trip
if _ROOT not in sys.path:
sys.path.insert(0, _ROOT)
from tools import charging_client
plan = charging_client.corridor(legs, rng)
if plan.get("legs"):
trip["evPlan"] = plan
except Exception as e:
print("[warn] EV corridor backfill unavailable: %s" % e, file=sys.stderr)
return trip
def refresh_trip_routing(trip):
"""Replace the model's guessed per-day driving miles/times with real OSRM
routing over each day's stop coordinates (tools/routing_client — the same
engine the agent workflow uses). Day N's route starts from day N-1's last
stop so overnights chain correctly. All-or-nothing: only "osrm" results are
applied (the client's great-circle fallback is cruder than the model's own
guess), and the first failure abandons the whole pass so day miles and
totalMiles never drift apart. Best-effort, never raises; returns the trip."""
try:
if _ROOT not in sys.path:
sys.path.insert(0, _ROOT)
from tools import routing_client
days = trip.get("days") or []
updates, prev_last = {}, None
for i, d in enumerate(days):
pts = [(s["lat"], s["lng"]) for s in (d.get("stops") or [])
if isinstance(s.get("lat"), (int, float))
and isinstance(s.get("lng"), (int, float))]
wps = ([prev_last] if prev_last else []) + pts
if pts:
prev_last = pts[-1]
if len(wps) < 2:
continue # layover / missing coords — keep model value
r = routing_client.route(wps)
if r.get("source") != "osrm":
return trip # OSRM unreachable — keep ALL model values
updates[i] = (int(round(r["miles"])), r["driveTime"])
if not updates:
return trip
total = 0
for i, d in enumerate(days):
if i in updates:
d["driveMiles"], d["driveTime"] = updates[i]
d["driveSource"] = "osrm"
total += d.get("driveMiles") or 0
if total > 0:
trip["totalMiles"] = int(round(total))
except Exception as e:
print("[warn] routing backfill unavailable: %s" % e, file=sys.stderr)
return trip
# Booking-countdown label keywords -> parks_client release-rule key. Ordered:
# first match wins, so the more specific rules come before the generic ones
# ("wilderness permit" must not hit the timed-entry "permit" keyword).
_COUNTDOWN_RULES = (
("campground", ("campground", "campsite", "camping", "营地", "露营")),
("in-park-lodge", ("lodge", "旅馆", "山庄")),
("wilderness-permit", ("wilderness", "荒野")),
("timed-entry", ("timed entry", "timed-entry", "permit", "预约", "许可")),
("one-way-rental", ("rental", "租车")),
)
def refresh_trip_countdown(trip, today=None):
"""Re-derive every recognizable bookingCountdown deadline from
tools/parks_client's release-window rules — hard dates from code, not model
recall. Items whose label matches no known rule keep the model's date. The
trip start date stands in for each item's arrival day (booking earlier
never hurts). Best-effort, never raises; returns the trip."""
try:
if _ROOT not in sys.path:
sys.path.insert(0, _ROOT)
from tools import parks_client
start = _trip_start_date(trip)
if not start:
return trip
arrival = start.isoformat()
for item in (trip.get("bookingCountdown") or []):
label = _s(item.get("item")).lower()
rule = next((r for r, words in _COUNTDOWN_RULES
if any(w in label for w in words)), None)
if not rule:
continue
bb = parks_client.book_by(arrival, rule, today)
if bb:
item["bookBy"] = bb
item["source"] = "parks_client"
except Exception as e:
print("[warn] countdown backfill unavailable: %s" % e, file=sys.stderr)
return trip
def refresh_trip_lodging_links(trip):
"""Attach tools/lodging_client search links to each lodging entry so the
rendered page deep-links to the booking platforms instead of showing a
dead-end name. Pure link building (no network). Never raises."""
try:
if _ROOT not in sys.path:
sys.path.insert(0, _ROOT)
from tools import lodging_client
for l in (trip.get("lodging") or []):
place = ", ".join(x for x in (_s(l.get("name")).strip(),
_s(l.get("area")).strip()) if x)
if place and not l.get("links"):
l["links"] = lodging_client.search_links(place)
except Exception as e:
print("[warn] lodging links unavailable: %s" % e, file=sys.stderr)
return trip
_COUNTRIES = ("US", "CA", "MX")
def refresh_trip_border(trip):
"""Build trip['crossBorder'] from the model-declared crossing sequence
(trip['crossings']: [{"from","to","day"}]) via tools/border_client — the
documents/insurance/customs/units checklists come from the rule tables, not
model recall. When the sequence re-enters the home country and both
crossing days are known, tools/customs_client adds the duty-free personal
exemption. The model only supplies the structure; every hard fact comes
from the tools. Best-effort, never raises; returns the trip."""
try:
crossings = trip.get("crossings")
if not crossings or trip.get("crossBorder"):
return trip
seq = []
for c in crossings:
f = _s(c.get("from")).strip().upper()
t = _s(c.get("to")).strip().upper()
if f in _COUNTRIES and t in _COUNTRIES and f != t:
seq.append((f, t, False))
if not seq:
return trip
if _ROOT not in sys.path:
sys.path.insert(0, _ROOT)
from tools import border_client, customs_client
trip["crossBorder"] = border_client.trip_section(seq)
home = seq[0][0]
out_day = crossings[0].get("day")
ret = next((c for c in crossings[1:]
if _s(c.get("to")).strip().upper() == home), None)
if ret is not None and isinstance(out_day, (int, float)) \
and isinstance(ret.get("day"), (int, float)):
hours = max(0, float(ret["day"]) - float(out_day)) * 24
trip["crossBorder"]["dutyFree"] = \
customs_client.personal_exemption(home, hours)
except Exception as e:
print("[warn] border backfill unavailable: %s" % e, file=sys.stderr)
return trip
def refresh_trip_route_options(trip, payload):
"""Populate routeOptions[] (the route-comparison table) from the phase-1
candidates via helper.compare_routes — the drive-intensity rating is code,
not model prose. The chosen row gets the trip's own post-routing miles and
computed budget total as its estCost; the road not taken keeps the phase-1
sketch numbers. Needs the webapp to pass both candidates as
payload['routes']; skips silently otherwise. Never raises."""
try:
routes = payload.get("routes") or []
if len(routes) < 2 or trip.get("routeOptions"):
return trip
chosen_label = _s((payload.get("route") or {}).get("label"))
opts = []
for r in routes:
wps = [_s(w.get("name")) for w in (r.get("waypoints") or [])
if w.get("name")]
opts.append({"name": _s(r.get("label")) or "Route",
"miles": r.get("totalMiles"),
"days": r.get("drivingDays"),
"highlights": ", ".join(wps[:4]),
"chosen": bool(chosen_label)
and _s(r.get("label")) == chosen_label})
chosen = next((o for o in opts if o["chosen"]), None)
if chosen:
if isinstance(trip.get("totalMiles"), (int, float)):
chosen["miles"] = trip["totalMiles"]
total = (trip.get("budget") or {}).get("total")
if isinstance(total, (int, float)):
chosen["estCost"] = total
trip["routeOptions"] = _helper.compare_routes(
opts, party=_s(trip.get("travelers")))["routeOptions"]
except Exception as e:
print("[warn] route options unavailable: %s" % e, file=sys.stderr)
return trip
def revise_stay(trip, day_start, day_end, city_name, instruction, nights=None, log_fn=None):
"""Free-text trip edit: rewrite one overnight stop's days per the traveler's
request ("don't want that hotel", "more hiking, less driving"), optionally
resizing the stay in the same single model call.
`instruction` is required (capped at 500 chars — it is embedded into the
prompt). `nights=None` or equal to the current length keeps the stay length;
otherwise the same rules as set_nights apply (1-7 nights, trip <= 21 days).
Same span guards, anchor enforcement, deterministic cascade and atomicity
contract as the other edit operations.
"""
days = trip.get("days") or []
n = len(days)
if n < 2:
raise ValueError("trip is too short to edit")
if not (0 <= day_start <= day_end <= n - 2):
raise ValueError("span must lie before the trip's final day")
text = (instruction or "").strip()[:500]
if not text:
raise ValueError("an instruction is required")
current = day_end - day_start + 1
if nights is None:
out_count = current
else:
try:
out_count = int(nights)
except (TypeError, ValueError):
raise ValueError("invalid night count")
if not (1 <= out_count <= 7):
raise ValueError("nights must be between 1 and 7")
if n - current + out_count > 21:
raise ValueError("trip would exceed 21 days")
return _replan_stay(trip, day_start, day_end, city_name, out_count, text, log_fn)