Track overview

A twenty-turn preliminary quote that separates conversational collection from eligibility, rating, exact presentation, correction, re-rating, and contact consent.

HomeInsuranceQuoteFlow is the regulated-money example. It borrows HotelFlow’s multi-stage journey and named memories, then applies a stricter boundary: the model collects and explains facts, while application code owns eligibility, reason codes, quote IDs, premiums, option validation, and re-rating.

The implementation lives in pico-demo/src/myflow/home-insurance-flow, and its complete twenty-turn scenario lives in pico-demo/test/home-insurance-flow.

Journey

Collection stages are model-guided. The review gate and deterministic rating make the authoritative application and all monetary output explicit; corrections travel back to the state owner.

There are ten registered steps. Qualification, property, and risk share home-quote-intake, because corrections often cross those boundaries. Coverage, review, quote presentation, contact, referral, and termination use separate memory namespaces. The long intake namespace is the only one with summary compaction.

Structured facts remain in the state of the step that owns them. ReviewStep reads those states to build a complete summary and routes corrections back to the owner. It does not keep a second application object that could drift.

The ten registered steps

Step	Primary job	Durable state it owns	Memory policy
`QualificationStep`	Location, occupancy, effective date	`qualification`	Shared `home-quote-intake`
`PropertyStep`	Building, roof, and systems	`property`	Shared `home-quote-intake`
`RiskStep`	Claims, hazards, protections	`risk`	Shared `home-quote-intake`
`CoverageStep`	Limits, deductible, endorsements	`coverage`	Isolated coverage history
`ReviewStep`	Authoritative summary and correction routing	`confirmedAt`	Isolated review history
`RateQuoteStep`	Eligibility, referral, or quote calculation	`quoteResult`	No model or chat memory
`PresentQuoteStep`	Exact options, comparisons, re-rating, selection	`presentedQuoteId`, `selectedOption`	Erased on entry
`ContactStep`	Consent-gated optional contact details	`contact`	Isolated contact history
`ReferralStep`	Explain a code-owned referral decision	—	Isolated referral history
`TerminateSessionStep`	Close and mark the session complete	`_prompt`	Isolated terminal history

Deterministic quote boundary

The local, versioned quote-config.json contains fictional demo products, factors, discounts, referral thresholds, and supported values. Zod validates it at module load. RatingEngine consumes the four authoritative input states and returns one of:

eligible, with Essential, Enhanced, and Premier options;
referral, with code-owned review reasons and no premiums; or
unsupported, with no fabricated quote.

RateQuoteStep is a LogicStep, so no model call decides the result. Quote tables are generated by QuotePresenter. A presentation tool normally returns them with direct(...); an onResponse() fallback returns the same deterministic Markdown if the provider responds with prose instead of emitting the render tool.

Changing the deductible writes the validated value back to CoverageStep and runs the rating logic again. The input-derived quote ID changes, the old selection is cleared, and only IDs from the new option set can be selected.

Safety and retention

The flow repeatedly labels its output a preliminary, non-binding estimate. It does not bind coverage, issue a policy, accept payment, or request Social Security, payment-card, bank, or birth-date data. Contact information is collected only after an option is selected and the customer explicitly consents. Phone and street address remain optional, and declined consent stores null contact fields.

Sessions idle for thirty minutes are rejected by onRestoreSessionDoc(). This keeps an abandoned application from resuming indefinitely with old quote inputs.

The seven lessons

A twenty-turn live replay — see the completed interaction first, including rendered initial and re-rated quote tables.
Designing a quote journey — turn a regulated quote into reachable stages and explicit state ownership.
Prompt files and bounded collection — compose role and stage prompts, inject authoritative state, and validate tool data.
Deterministic eligibility and rating — keep money, decision reasons, and product rules outside the model.
Memory namespaces and expiry — share intake context where corrections need it, erase narrow stages, and reject stale sessions.
Correct, re-rate, and return — send a correction to its owner and invalidate selections when an input changes.
Exact quote tables and response fallback — use direct(...) for code-owned tables and cover the model-free crossing path.

Run the twenty-turn live test

From pico-demo:

npm run test:home-insurance-flow

With OPENAI_API_KEY and PICOFLOW_KEY, the command runs all twenty live turns and grades each response semantically. It also reads the final SQLite session document and asserts the corrected four-year roof, the re-rated $5,000 deductible, the current Enhanced selection, explicit contact consent, and completed status.

Without live credentials, or with the live path explicitly disabled, the same command still runs the deterministic rating, referral, and re-rating tests:

The test loads provider credentials from .env; when they are absent, its live scenario is skipped.

The quote configuration is deliberately fictional. Replace it with filed products, approved rules, authorization, auditing, and real service integrations before using this pattern for an actual insurer.

Start with 1. A twenty-turn live replay.