Itinerary Planner

Travel itinerary and trip-planning engine for tour builders, travel apps and concierge bots: heuristic day-by-day itinerary generation plus budget, packing and pacing helpers. build turns a...

itinerary-planner

Travel itinerary and trip-planning engine for tour builders, travel apps and concierge bots. Heuristic day-by-day itinerary generation plus budget, packing and pacing helpers — packaged as a Leumas "intelligent microservice" adapter pack.

Every tool has a deterministic heuristic-template core (embedded interest / climate / budget tables) that works fully offline with no model. The generative tools (build, dayPlan) optionally enrich their narrative summary with an LLM when one is reachable (via ../_shared/llm.js) and silently fall back to the template otherwise. Results carry mode: 'heuristic' | 'llm'.

Tools

Tool	Input	Returns
`build`	`{ destination, days, interests, pace?, options? }`	Full day-by-day plan: each day themed to an interest with morning/afternoon/evening time-blocked activities + meal slots and a rest cadence.
`dayPlan`	`{ destination?, interests, options? }`	A single themed, time-blocked day schedule.
`budgetEstimate`	`{ days, style, options? }`	Per-day and total per-person cost by style (shoestring/budget/mid/comfort/luxury) with lodging/food/transport/activities/misc breakdown.
`packingList`	`{ destination?, season?, days?, options? }`	Categorized packing checklist tailored to destination climate, season and trip length.
`paceCheck`	`{ plan, pace?, options? }`	Evaluates whether each day is under/well/over-packed vs the pace and flags days to rebalance.
`mustSeeByInterest`	`{ interests, options? }`	Curated must-do activity archetypes + categories per interest, plus a merged top-picks list.

Interests

history, art, food, nature, adventure, relaxation, nightlife, shopping, architecture, family, and a general fallback. Unknown tags fall back to general highlights. Interests accept an array or a comma-separated string.

Pace & style

pace: relaxed (2 activities/day + downtime) · moderate (3) · packed (4).
style (budget): shoestring · budget · mid · comfort · luxury — per-person USD/day tables.

Usage

import trip from './index.js';

trip.adapters.build({ destination: 'Kyoto', days: 4, interests: ['history', 'food', 'nature'], pace: 'moderate' });
// -> { mode:'heuristic', destination:'Kyoto', days:4, plan:[ {day:1, theme:'History & heritage', blocks:[...]}, ... ] }

trip.adapters.budgetEstimate({ days: 4, style: 'mid' });
// -> { total:1140, perDayTotal:245, breakdown:{ lodging:{...}, food:{...}, ... } }

trip.adapters.packingList({ destination: 'Iceland', season: 'winter', days: 6 });
// -> climate:'cold', categories:{ clothing:[...], climate:['Insulated jacket', ...], ... }

Deterministic: pass options.seed to make activity selection reproducible.

DRY boundary

New capability — a travel/itinerary planner. It deliberately does not overlap:

datetime / ical — generic date math and calendar-file generation (this owns trip scheduling logic).
geo — distance/geocoding primitives (this uses only light name-keyword climate inference).
finance / invoice — money math (this owns the travel-style cost estimation tables).

Self-contained: Node built-ins only, zero npm deps. The only cross-pack import is ../_shared/llm.js for optional narrative enrichment. Cost figures are per-person planning estimates, not live prices.