picoflow.io Docs

DecisionHotelFlow tutorial

1. A sixteen-turn live replay

Start with a recorded provider-backed journey through invalid values, a cross-step correction, typed routing, reviewed search results, an empty-result recovery, and a completed reservation.

Read this first. It is a complete, passing run of the sixteen-turn live scenario with HOTEL_FLOW_CURRENT_DATE frozen to 2027-07-15. The run used the real OpenAI chat provider and TypeSafe Jev decision provider. Wording and confirmation numbers may vary; saved state, routing, grounded results, and completion are the durable contracts.

Run it yourself

cd pico-demo
npm run test:decision-hotel-flow

The test sends every request through one session, semantically judges every response, and verifies the active step and final state. It is skipped unless PICOFLOW_KEY, OPENAI_API_KEY, and TYPESAFE_API_KEY are available. A skipped test is not live evidence.

Captured live transcript

  1. 1 · Router → dates

    You
    Hi
    Bot

    Please provide the check-in and checkout dates for your stay in Portland.

  2. 2 · Dates · correction

    You
    February 30, 2027 through March 5, 2027
    Bot

    February 30, 2027, is not a valid date. Please provide a valid check-in date after the current date (July 15, 2027) and a valid checkout date after the check-in date.

  3. 3 · Dates → budget

    You
    August 1 through August 8, 2027
    Bot

    Could you please share your budget for the hotel stay per night?

  4. 4 · Budget · correction

    You
    minimum 800 and maximum 500 per night
    Bot

    You mentioned a minimum budget that is higher than the maximum budget. Could you please clarify the correct range for your nightly hotel budget?

  5. 5 · Budget → room type

    You
    maximum 700 per night, with no minimum
    Bot

    Could you please tell me your preferred room type: one bed, two beds, or suite?

  6. 6 · Room type → amenities

    You
    a suite
    Bot

    Which hotel amenities do you require? For example, free WiFi, free parking, breakfast, a pool, or a fitness center.

  7. 7 · Cross-step date correction

    You
    Actually change my dates to August 3 through August 9, 2027
    Bot

    Which hotel amenities do you require? For example, free WiFi, free parking, breakfast, a pool, or a fitness center.

  8. 8 · Amenities → distance

    You
    free wifi and free parking
    Bot

    What is the maximum distance in miles you’re willing to travel from Portland airport and Portland city center? If there’s no limit, please let me know.

  9. 9 · Distance → review

    You
    distance does not matter
    Bot

    Current Portland hotel criteria:

    • Dates: 2027-08-03 to 2027-08-09
    • Nightly budget: no minimum to $700
    • Room type: suite
    • Amenities: freeWiFi, freeParking
    • Distance: no preference

    Tell me what to revise, or say “search” when ready.

  10. 10 · Criteria review

    You
    show my criteria
    Bot

    Current Portland hotel criteria:

    • Dates: 2027-08-03 to 2027-08-09
    • Nightly budget: no minimum to $700
    • Room type: suite
    • Amenities: freeWiFi, freeParking
    • Distance: no preference

    Tell me what to revise, or say “search” when ready.

  11. 11 · Readiness → search → presentation review

    You
    search
    Bot

    Here are the available hotels with their total prices in U.S. currency:

    1. Hampton Inn & Suites Portland Tigard - Total: $3810.60
    2. Hilton Garden Inn Portland Airport - Total: $4204.80
    3. Hilton Garden Inn Beaverton - Total: $3350.70
    4. Hampton Inn Sherwood Portland - Total: $3547.80

    You may book a hotel by its name or number, or revise your dates, budget, room type, amenities, or distance preferences. Please let me know how you’d like to proceed!

  12. 12 · Present → budget revision

    You
    change maximum budget to 500 per night
    Bot

    Current Portland hotel criteria:

    • Dates: 2027-08-03 to 2027-08-09
    • Nightly budget: no minimum to $500
    • Room type: suite
    • Amenities: freeWiFi, freeParking
    • Distance: no preference

    Tell me what to revise, or say “search” when ready.

  13. 13 · Empty search → router

    You
    search
    Bot

    No hotels matched all current criteria. Tell me whether to revise budget, room type, amenities, or distance.

  14. 14 · Budget revision → review

    You
    change maximum budget to 750 per night
    Bot

    Current Portland hotel criteria:

    • Dates: 2027-08-03 to 2027-08-09
    • Nightly budget: no minimum to $750
    • Room type: suite
    • Amenities: freeWiFi, freeParking
    • Distance: no preference

    Tell me what to revise, or say “search” when ready.

  15. 15 · Second reviewed presentation

    You
    search
    Bot

    Here are the current matching hotels:

    1. Hampton Inn & Suites Portland Tigard - Total: $3,810.60
    2. Hilton Garden Inn Portland Airport - Total: $4,204.80
    3. Hilton Garden Inn Beaverton - Total: $3,350.70
    4. Hampton Inn Sherwood Portland - Total: $3,547.80

    You may book a hotel by name or number, or you can revise the search criteria such as dates, budget, room type, amenities, or distance.

  16. 16 · Present → completed · completed

    You
    book hotel 1
    Bot

    Hampton Inn & Suites Portland Tigard is booked with confirmation #613373. Thank you for choosing Hilton.

The successful replay recorded 22 decision calls and 30220 decision tokens, separately from 12953 chat-model tokens. These are one run's observations, not a price or performance benchmark.

What the replay proves

TurnsObserved contract
1–6The router selects criterion owners; invalid calendar and budget values remain with their owner.
7A date correction made while amenities are active reaches DateRangeStep, then returns to amenities in the same turn.
9–11The normalized record can be reviewed, then passes the decision gate before search and grounded presentation.
12–15A budget revision produces an empty result, remains recoverable, then produces a new reviewed result set.
16The selected hotel is resolved against saved results, an exact confirmation is returned, and the session completes.

One successful replay does not establish general routing or judge accuracy. The deterministic contract in lesson 7 covers branches and outages; a labeled evaluation set is still required to calibrate production thresholds.

Next

2. Designing a decision-backed workflow maps the state and execution boundaries behind the replay.