# 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...


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

```js
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.


---
Source: shared/engines/adapters/domain/itinerary-planner/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/itinerary-planner