Foresee

Purpose: confirm quote estimates on the carriers' own quote sites, via Foresee agents completing their real quote flows. IDEMPOTENT, keyed on the profile: the first call commissions the walks; calling again with the same profile collects progress and results instead of re-submitting anything — whatever the ask. A profile that has already been walked returns those results (the carriers are never asked twice): the envelope's ``coverage_selection`` names the ask the walk typed, and each quote carries the carrier's other recorded coverage options as ``variants``, so a new ask reads the same run. So call once to start, then re-call after a few minutes to collect; agents still working report their stage. Ask ONCE, before the first call: the consent disclosure below, the identity fields, and the questions listed at the end of this description under EVERY LINE and under the line being walked — all in one message, so the first commissioning call walks every carrier. A call made before consent submits nothing and answers ``authorization_required`` with the profile's ``needs``, for when you have not asked yet. No sign-in is required. The one hard requirement is the user's own consent, captured in-band: BEFORE the commissioning call, you MUST tell the user, plainly: Foresee will submit their details to the named carriers; the carriers may obtain their credit-based insurance score (a soft pull, with no impact on your credit score); and the carriers may contact them by email or phone. Then get their explicit go-ahead and pass their affirmation VERBATIM as ``user_authorization`` (e.g. "yes, go ahead"). The affirmation is stored as the durable consent record for the dispatch; without one the call is refused with ``authorization_required``. Foresee only collects quotes; it does not take payment or bind insurance. Collect the ``identity`` fields in chat. Nothing is filled in from anywhere else: what the walks type is what the call states. A ``missing_facts`` response is normal: carrier forms insist on facts (body style, purchase date, age first licensed…) that Foresee will not invent. Each ``needs`` entry carries the carrier (``scope``), the facts in the walk's own words (``need``), and ``fields[]`` — per fact, the ``ask`` beside the exact schema path to pass the answer under (``field``, e.g. ``auto.vehicles[].purchase_date``; ``identity.…`` paths go on ``identity``). Ask the user for exactly those facts, then call again with the answers merged in at those paths. A fact with no ``field`` has no profile home yet — relay that carrier's ask as unavailable rather than guessing a key. While any carrier waits on a fact the user can answer, nothing is submitted: the carriers already able to go are listed under ``ready`` and held, so every carrier is walked together. Only when the user cannot or will not answer, re-call with ``dispatch_ready_only=true`` to walk the ready ones now; that receipt is PARTIAL — follow its ``recover`` block: re-call with the new facts merged AND ``carriers`` set to exactly ``recover.carriers`` — a changed profile is a new dispatch, and an unscoped re-call would re-submit the already-walked carriers too. Unasserted MINOR facts are not asked: a form field that is really a claim nobody made (an anti-theft device, a defensive-driving course, a licence held abroad) is answered with the declared no-claim value — never a discount claim — and every one comes back in ``assumptions`` (``field`` + the ``assumed`` value submitted). Relay them with the results; if the user corrects one, re-call with the real value at that path. ``carriers``: OMIT it to walk every carrier walked for the line in the user's state — that is the default and the goal. Pass it only when the user asks to limit the walk: most carriers with an estimate have no walk, so a shortlist copied from quote_insurance results is refused with ``carriers_not_walked`` naming the ``walkable`` set to choose from. Those carriers keep their estimates; the live run adds real quotes from every walked carrier. ``lines`` names WHICH line to walk, exactly one per call (a fan-out drives one form family): ``{"auto": {...the ask...}}``, ``{"home": null}``, or ``{"renters": {"coverage_c": 30000, "coverage_e": 100000, "coverage_f": 1000, "deductible": 500}}``. An AUTO walk's ask is REQUIRED — the limits and deductibles the agents ask the carriers for, as actual numbers (`bi` "100/300", `pd` 100, `coll_deductible` 500, `comp_deductible` 500, the same four axes as quote_insurance); without it the tool answers with the selection-required message; ask the user, then call again. A HOME walk takes NO ask — the carrier's own form prices its package (dwelling amount from its replacement-cost estimate) and the agents report what it chose. A RENTERS walk requires its four axes as actual dollars — ``coverage_c`` (personal-property/contents), ``coverage_e`` (personal liability), ``coverage_f`` (guest medical) and ``deductible`` — the agents type the user's numbers on the form instead of accepting its defaults, and Foresee never invents them. Quotes come back with evidence. ``quote.premium`` is VERBATIM as the carrier's page printed it, and ``term_months`` says what it covers — a 6-month figure is not a monthly one. When term_months is known, present the monthly equivalent (premium ÷ term_months) so carriers compare on one basis, the page's own figure beside it; without it, relay the printed premium and say the monthly equivalent is unknown. A carrier may also decline the risk — a real answer to relay, not an error. Every carrier without a quote says why in ``detail``: ``declined`` is the carrier's own answer; ``missing_facts`` lists under ``fields`` (each an ``ask`` and its ``field`` path) what its form wanted — ask the user, then re-call with the answers merged and ``carriers`` set to that carrier; ``failed`` and ``not_quoted`` mean Foresee couldn't get that quote — say so, never that the carrier turned the user down. ``not_dispatched`` names each carrier with an instant estimate that this run won't quote live, with a ``by`` and a ``detail``: ``by: carrier`` is the carrier's own answer (e.g. it doesn't quote that line online there), to relay as written; ``by: foresee`` means Foresee couldn't get a live quote — say exactly that, and never guess or add why. ``skipped`` names carriers whose form needs facts the profile lacks. A carrier never silently vanishes. What the carriers' forms ask. In ONE message, together with the consent disclosure and BEFORE the first call, ask the user the EVERY LINE questions plus the questions for each line they want priced, then omit `carriers` to walk every carrier in the user's state. Each fact names the path its answer goes under. EVERY LINE: - identity: legal name, date of birth, street address, email and phone (identity) AUTO ONLY: - household: gender (gender); marital status (marital_status); the spouse of a married applicant (auto.drivers[]) - work: occupation (occupation) - residence: whether the home is owned or rented (home_ownership_status); how long at this address (resident_since) - each car: whether the vehicle is owned, financed or leased (auto.vehicles[].ownership); when the vehicle was bought (auto.vehicles[].purchase_date); whether the vehicle was new when bought (auto.vehicles[].bought_new); what the vehicle cost new (auto.vehicles[].cost) - how each car is used: what the vehicle is used for (auto.vehicles[].primary_use); annual mileage (auto.vehicles[].annual_mileage) - each driver: driver's licence number (auto.drivers[].drivers_license_number); age first licensed (auto.drivers[].date_first_licensed); violation history (auto.drivers[].violations); loss history (auto.drivers[].accidents) - current insurance: whether there is insurance now (prior_insurance.insured); prior carrier (prior_insurance.carrier); when the prior policy ran (prior_insurance.since); the bodily injury limits carried now (prior_insurance.limits); a lapse in coverage (prior_insurance.lapse) HOME ONLY: - the home: when the property was bought (property.purchased); what the property is used for (property.occupancy); how many people live there (property.household)

Purpose: generate instant, itemized quote estimates from the carriers Foresee supports, across the lines and states Foresee currently serves, in one call — the LIVE TODAY line at the end of this description names today's set. `lines` is REQUIRED and is ONE map: each key names a line to price (e.g. "auto", "renters", "home" — plain words are fine), each value is that line's coverage ask as actual numbers. A line Foresee doesn't quote in the user's state comes back under `skipped`: `lines` names each one and `message` is one sentence, written to be relayed to the user as-is, naming what Foresee does quote in that state. For auto the ask has four axes — `bi` (bodily-injury liability, per-person/ per-accident in $000s, e.g. "100/300"), `pd` (property-damage liability in $000s, e.g. 100), `coll_deductible` (collision deductible in dollars, e.g. 500) and `comp_deductible` (comprehensive deductible in dollars, e.g. 500); `um` and `medpay` are optional. A renters ask has four axes — `coverage_c` (personal-property/contents limit in dollars, e.g. 30000), `coverage_e` (personal liability in dollars, e.g. 100000), `coverage_f` (guest medical in dollars, e.g. 1000) and `deductible` (all-perils, in dollars, e.g. 500); `coverage_d` is optional. A home ask: `coverage_a` (the dwelling's replacement cost in dollars), `coverage_e` (e.g. 300000), `coverage_f` (e.g. 1000) and `aop_deductible` (all-other-perils deductible in dollars, e.g. 1000). There are no named coverage levels: pass exact numbers, the same ask in every state. An omitted OPTIONAL axis (`um`, `medpay`, `coverage_d`) keeps each carrier's own default — the quote's per-coverage lines show what was rated. Where the user's state puts more on every auto policy (its personal injury protection, a lawsuit option) and the ask doesn't name it, the quote prices the state's own and says so. Each line's `state_notes` is what the user's state means for these quotes — that, its legal minimum, the facts its law bars insurers from pricing on, a carrier that doesn't sell there — each note's `text` written to be relayed. Any numbers at or above the state's legal minimum work as the ask (an auto `bi`/`pd` below it prices nothing — no carrier may sell that policy — and comes back under `coverage_required` naming the minimum); each carrier's `price_ladder` prices every other rung, so a starting selection is easy to refine after the fact. An incomplete ask on a live line prices nothing and answers with `coverage_required` naming that line's own axes; an axis supplied with a value no carrier offers (`bi` "banana", a negative deductible) is refused the same way, naming the bad value and the format the axis takes. Each supported carrier is priced at the selection given; a carrier that doesn't offer an asked rung is priced at its nearest offered one and says so: its entry carries `rated_vs_asked` (per axis: `asked`, `rated`, and `coverage` "less"/"more" than asked; the dense text puts it on the `C` row as `rated`). That price is NOT like-for-like — state the rated limits next to it every time you show it (e.g. "$255/mo — 30/60 BI / $25k PD, the most this carrier offers, not the 100/300 / $100k you asked for"), and never let it headline or anchor a cheapest/spread claim without saying so. A carrier without a price appears in `failures`, on every line it was asked on — a carrier never silently vanishes from a line's results. Each entry's `by` says whose answer it is: `carrier` is the carrier's own (it doesn't sell the line in the state, isn't taking new customers, only quotes military families) — relay its `error` as written; `foresee` means Foresee couldn't get that quote — say exactly that, and never guess or add why. Priced results come back per line under `by_line`. Profile requirements: ZIP code, age (or dob) and — for auto — each vehicle's year/make/model are REQUIRED; they have no server-side fallback. A missing or mistyped one errors at the schema with guidance; a value that fits the schema but cannot rate ("not-a-zip", a negative age) comes back in `profile_required` naming it, with guidance on what the field takes. Use the profile schema's exact field names: a key the schema doesn't name is carried but never rated. A complete call — a 25-year-old in Oakland with a 2021 Civic, a January 2025 speeding ticket and a 2023 at-fault accident, asking for 100/300 BI, $100k PD and $500 collision/comprehensive deductibles: {"profile": {"zip_code": "94621", "age": 25, "auto": {"drivers": [{"violations": [{"on": "2025-01", "kind": "speeding"}], "accidents": [{"on": "2023-06-15", "at_fault": true, "amount": 4200}]}], "vehicles": [{"year": 2021, "make": "Honda", "model": "Civic"}]}}, "lines": {"auto": {"bi": "100/300", "pd": 100, "coll_deductible": 500, "comp_deductible": 500}}} Every violation needs `kind` and `on`, every accident `on`; an incomplete entry is refused naming its path, never assumed away. Each carrier returns a **point estimate** (`monthly`) plus a `confidence_interval` that reflects only what's genuinely unresolvable (irreducible), NOT missing profile fields. A field the caller omits is filled with ONE declared value and reported in `assumptions` / `tighten_by` (the reducible "tell us X and we sharpen" gap) — the response is built to be presented early and refined, never widened into a vague range. Each entry's `field` is the exact profile path to send the user's real answer under (e.g. `auto.drivers[].violations`), and `tighten_by` lists those same paths. The one exception is `incident_details`: it is answered by completing the incident entries already sent (dates, fault, BI split), not under a fresh key. Each carrier's `quote` carries every sub-coverage line (BI/PD/collision/ comprehensive/UM…) with its monthly price, at the selection you passed (echoed as `coverage_selection`). Most carriers also carry a `price_ladder`: for each coverage lever of the line (auto: BI limit, PD limit, collision/comprehensive deductible; renters: deductible and the C/E/F limits; home: AOP deductible and the A/E/F limits) the exact price at every rung, one lever moved at a time with everything else held at the user's selection — the ladder is anchored at the selection you passed, so its `anchor.monthly` is the carrier's `monthly`. It answers limit/deductible what-ifs with real marginal prices. Every ladder number IS an exact re-rate; a combined change or an unlisted rung has no derivable price (rating is not linear), so those price only through a re-call with the new `coverage_selection`. A profile what-if (a cleaner record, another vehicle, a different ZIP) prices the same way: re-call with the changed profile. RESULT FORMAT: compact machine text on `dense`, one section per line. Each section opens Q <state> <line> sel=<the coverage_selection priced, as JSON>. state_notes: <sentences> is the line's `state_notes`, to relay. assumptions:, tighten_by:, input_flags: and not_rated: carry those fields; each entry's `field` (and each tighten_by item) is the profile path to send the user's answer under, and `incident_details` is answered by completing the incident entries already sent. not_priced: <carrier>,…:<error> ; … is the line's `failures`, grouped by their `error` sentence. skipped <line>,…: <message> names the lines not quoted in this state. Row types — C: carrier|entity|monthly|ci lo-hi, then |rated <axis>=<rung>(asked <X>,less|more);… when the price is for a rung other than the ask (`rated_vs_asked`). W: a warning on the carrier above. L: monthly $ per coverage line (already monthly, every carrier), under codes that mean the same coverage at every carrier: BI PD UMBI UIMBI UMPD MEDPAY PIP COLL COMP RENTAL TOWING GAP; A+B is one premium covering both (BI+PD); FEE is a flat fee; any other code is a coverage only that carrier sells. D <lever> <selected>=option:±$: the change in the carrier's monthly for each option of that lever, everything else held at the selection; <selected>(asked <X>) means X is not an option and the price sits at the selected rung — answer deductible/limit what-ifs from D without another call (new monthly = monthly + delta). Only state numbers that appear in the result or follow from monthly + a D delta; if a rung is not in D for a carrier, say the carrier has no such option rather than guessing. When the user wants firm numbers straight from the carriers, offer live carrier quotes: Foresee agents complete the carriers' real quote flows via live_carrier_quotes (which explains the required disclosure + consent affirmation; no sign-in is needed). Instant quotes stay the first answer; live quotes are the follow-up. LIVE TODAY: Foresee quotes auto in CA today.