picoflow.io Docs

HotelFlow tutorial

1. A fourteen-turn live replay

Start with a recorded booking conversation: collection, a search refinement, two exact comparison tables, return to selection, and a completed reservation.

Read this first. It is a complete, passing model-backed run of the fourteen-turn scenario with HOTEL_FLOW_CURRENT_DATE frozen to 2027-07-15. The collection wording can vary; the local catalogue, date policy, price calculations, direct comparison tables, and completion flag are the durable contracts.

Run it yourself

cd pico-demo
npm run test:hotel-flow

With OPENAI_API_KEY and PICOFLOW_KEY in .env, this starts the demo application, sends every scenario request through one session, semantically judges the replies, and inspects the final durable state. Without credentials, Node reports the live scenario as skipped.

Captured live transcript

  1. 1 · Explore

    You
    Hi
    Bot

    Welcome! I can help you plan and book a Hilton stay in the Portland, Oregon metropolitan area only.

    Are you looking to book a hotel in or around Portland, OR?

  2. 2 · Explore

    You
    yes
    Bot

    Wonderful—I’d be happy to help you with a stay in the Portland, OR area!

    First, what date or date range are you planning to stay?

    • Today’s date (for booking rules) is July 15, 2027, so:
      • Your check-in date must be after July 15, 2027
      • Your check-out date must be after your check-in date

    You can give your dates in any of these ways, for example:

    • 7/20 to 7/23
    • August 1–3
    • 7/21, 7/23, 7/25 to 7/27 (multiple individual days and ranges)
    • “Change my dates to July 18 to July 22”

    Please share your intended dates, and I’ll record them.

  3. 3 · Explore

    You
    8/1/2027 to 8/8/2027
    Bot

    Great, I’ve noted your stay as:

    • Check-in: August 1, 2027
    • Check-out: August 8, 2027

    This covers the nights of: 8/1, 8/2, 8/3, 8/4, 8/5, 8/6, 8/7.

    Next, what price range per night would you like for your hotel?

    You can tell me any of these:

    • “Between $150 and $300 per night”
    • Max $250
    • Min $200, no maximum”
    • “I don’t care about price range”

    Once you share that, I’ll record it and move on to room type.

  4. 4 · Explore

    You
    max 700
    Bot

    Got it—I’ll set your price range to:

    • Min: no minimum
    • Max: $700 per night

    Next, do you have a preferred room type? Options include:

    • One bed
    • Two beds
    • Suite
    • Or: “I don’t care about room type”

    What would you prefer?

  5. 5 · Explore

    You
    suite
    Bot

    Perfect, I’ll note your preferred room type as a suite.

    So far your preferences are:

    • Dates: 8/1/2027 to 8/8/2027
    • Price per night: max $700
    • Room type: Suite

    Next, do you have any desired amenities?

    Here are some popular options you can choose from (you can pick as many as you like):

    • Free WiFi
    • Free breakfast
    • Free parking
    • Airport shuttle
    • Pet-friendly
    • Indoor pool
    • On-site restaurant
    • Fitness center

    You can also mention others like: room service, EV charging, digital key, business center, etc.
    Tell me what matters to you, or say “no preference” if you’re flexible.

  6. 6 · Explore

    You
    free wifi, parking
    Bot

    Wonderful, I’ll add those to your preferences.

    Mapped amenities:

    • Free WiFi
    • Free parking

    Your current search criteria:

    • Dates: 8/1/2027 to 8/8/2027
    • Price per night: max $700
    • Room type: Suite
    • Amenities: Free WiFi, Free parking

    Do you care how close the hotel is to anything, in miles?

    • Distance to Portland Airport (PDX) (e.g., “within 5 miles”)
    • Distance to city center/downtown Portland (e.g., “within 2 miles”)

    You can say things like:

    • “Airport 5 miles, city center 2 miles”
    • “Only care about downtown, within 3 miles”
    • “No preference for distance”
  7. 7 · Explore → Present

    You
    none
    Bot

    Here are the hotels available for you to choose from:

    1. Hampton Inn & Suites Portland Tigard

      • Total price is: $4,410.90
    2. Hilton Garden Inn Portland Airport

      • Total price is: $4,867.20
    3. Hilton Garden Inn Beaverton

      • Total price is: $3,878.55
    4. Hampton Inn Sherwood Portland

      • Total price is: $4,106.70

    You can:

    • Book a hotel by typing the name or number presented above.
    • Re-run the entire search if you want to change any criteria.
    • Compare hotel features.

    Please let me know what you’d like to do!

  8. 8 · Present

    You
    search
    Bot

    Here are the hotels we found:

    1. Hampton Inn & Suites Portland Tigard - total price is: $4,410.90
    2. Hilton Garden Inn Portland Airport - total price is: $4,867.20
    3. Hilton Garden Inn Beaverton - total price is: $3,878.55
    4. Hampton Inn Sherwood Portland - total price is: $4,106.70

    Please choose one of the following options:

    • Type the number or name of the hotel to book.
    • Type “re-run search” or similar phrases to search again.
    • Type “compare hotel” or similar phrases to compare hotel features.
  9. 9 · Explore → Present

    You
    change to a 2 bed rooms, search
    Bot

    Here are the hotels we found:

    1. Hampton Inn & Suites Portland Tigard

      • Total price is: $2,822.98
    2. Hampton Inn Portland-Airport

      • Total price is: $3,236.69
    3. Hilton Garden Inn Portland Airport

      • Total price is: $3,115.01
    4. Hilton Garden Inn Beaverton

      • Total price is: $2,482.27
    5. Hampton Inn Portland/Clackamas

      • Total price is: $2,798.64
    6. Tru by Hilton Aloha Beaverton

      • Total price is: $2,822.98
    7. Hampton Inn Portland East

      • Total price is: $2,895.98
    8. Hampton Inn Sherwood Portland

      • Total price is: $2,628.29
    9. Hilton Garden Inn Wilsonville Portland

      • Total price is: $2,968.99

    Please choose a number to book a hotel, or type the hotel name. You can also:

    a. Book a hotel by typing the name or number presented above. b. Re-run the entire search with new criteria. c. Compare hotel features.

    Let me know what you’d like to do!

  10. 10 · Present → Compare

    You
    compare hotel 2,5,8 on price
    Bot
    Features Hotel 1 Hotel 2 Hotel 3
    hotelName Hampton Inn Portland-Airport Hampton Inn Portland/Clackamas Hampton Inn Sherwood Portland
    2027-08-01 $440.50 $380.88 $357.70
    2027-08-02 $440.50 $380.88 $357.70
    2027-08-03 $383.04 $331.20 $311.04
    2027-08-04 $383.04 $331.20 $311.04
    2027-08-05 $383.04 $331.20 $311.04
    2027-08-06 $383.04 $331.20 $311.04
    2027-08-07 $383.04 $331.20 $311.04
    total $3,236.69 $2,798.64 $2,628.29

    Another comparison or ready to book?

  11. 11 · Compare

    You
    compare on amenities
    Bot
    Features Hotel 1 Hotel 2 Hotel 3
    hotelName Hampton Inn Portland-Airport Hampton Inn Portland/Clackamas Hampton Inn Sherwood Portland
    connectingRooms
    freeBreakfast
    freeParking
    freeWiFi
    nonSmoking
    digitalKey
    airportShuttle
    streaming
    fitnessCenter
    petFriendly
    businessCenter
    evCharging
    indoorPool
    meetingRoom

    Another comparison or ready to book?

  12. 12 · Compare

    You
    compare hotels 2,5 on price
    Bot
    Features Hotel 1 Hotel 2
    hotelName Hampton Inn Portland-Airport Hampton Inn Portland/Clackamas
    2027-08-01 $440.50 $380.88
    2027-08-02 $440.50 $380.88
    2027-08-03 $383.04 $331.20
    2027-08-04 $383.04 $331.20
    2027-08-05 $383.04 $331.20
    2027-08-06 $383.04 $331.20
    2027-08-07 $383.04 $331.20
    total $3,236.69 $2,798.64

    Another comparison or ready to book?

  13. 13 · Compare → Present

    You
    resume booking
    Bot

    Here are the hotels available for you to choose from:

    1. Hampton Inn & Suites Portland Tigard - total price is: $2,822.98
    2. Hampton Inn Portland-Airport - total price is: $3,236.69
    3. Hilton Garden Inn Portland Airport - total price is: $3,115.01
    4. Hilton Garden Inn Beaverton - total price is: $2,482.27
    5. Hampton Inn Portland/Clackamas - total price is: $2,798.64
    6. Tru by Hilton Aloha Beaverton - total price is: $2,822.98
    7. Hampton Inn Portland East - total price is: $2,895.98
    8. Hampton Inn Sherwood Portland - total price is: $2,628.29
    9. Hilton Garden Inn Wilsonville Portland - total price is: $2,968.99

    Please pick a number to book a hotel, or you can:

    • Type the hotel name or number to book a hotel.
    • Re-run the search with different criteria.
    • Compare hotel features.
  14. 14 · Present → completed · completed

    You
    8
    Bot

    Your hotel is booked with confirmation #: 934145. Thank you for choosing Hilton!

The final response sets completed: true. The current cursor is the terminal step, so a client should start a new session for another reservation.

What to compare when your replay differs

PointContract
Turns 1–7Collection is Portland-only and dates remain after the frozen current date.
Turn 9The refined two-bed search produces the current result set.
Turns 10–12Comparisons are application-rendered Markdown tables, not model-invented prices.
Turn 14A confirmation is generated and the session completes.

Next

2. Designing a multi-stage workflow maps the reachable steps and return paths behind the replay.