Skip to main content

Design notes

These notes record the reasoning behind the embedded version (v0.1). The full original is docs/embedded-v0.1.md in the repository.

The starting point​

The demo recreates two ClaimPilot claim screens, loads several hundred synthetic claims from our own database, and puts an assistant beside them. It is convincing precisely because we control everything on the page. The goal was the same assistant dropped into someone else's claims system (.NET, React, Angular) without rebuilding it each time and without taking a copy of their claims.

The claim comes from the page​

The host page has already loaded the claim to render it. It sends us that same object with each message. A real claim document is about 10 KB (the largest measured was 22 KB), so sending it with each message costs nothing, and it buys four things at once:

  • It can only ever be the claim on screen. Not a promise: nothing else is sent.
  • Read-only by construction. There is no host API for us to call, so nothing to misuse.
  • No authentication of our own for claim access. The host already decided this user may see this claim.
  • Nothing stored. We hold no claim at rest, which answers the first question any insurer's security review asks.
A trap in scoping

Passing us the user's session token plus a claim reference would not achieve this. That grants access to every claim the user may see. The restriction comes from sending only one claim or, later, from a short-lived token that names the claim rather than the user.

The order it was built in​

  1. Make the demo the first host. The claim page already loaded the claim to render it, so it hands that object to the assistant. A redundant fetch disappeared, and the widget was integrated by an application that is not the widget.
  2. Relax the claim contract. It went from 32 of 33 top-level fields required to 8. This decides how hard everything after it feels for a host.
  3. Let the claim arrive in the request. ChatRequest.claim beside claimId, resolved to a Claim before anything downstream runs.
  4. Do the same for voice. The claim travels in the opening clientConfig frame, beside the Prompt Lab overrides.
  5. Make the claims database optional. DATABASE_PROVIDER=none: one codebase, another configuration.
  6. Make panel highlighting optional. The tool is offered only when the caller says it can perform it.
  7. Package the UI as a web component, with the property-upgrade pattern so script order cannot lose a claim.
  8. Put a credential and an origin list on the endpoint. For the model budget, not claim access.

Everything else (prompts, capabilities, tools, the safety layer, voice, the gateway) was untouched.

Deliberately deferred​

Documents (v0.2). A document is metadata plus a written summary today. Real document text needs one host endpoint and is the genuinely hard part: a forty-page medical report does not fit in a prompt, so it needs extraction, possibly OCR, and either chunked retrieval or summarising on the way in. It does not compromise statelessness.

Cross-claim history (v0.2). The fraud check looks within one claim; a claims person notices in the first ten minutes. It needs a second host interface returning the claimant's other claims.

Writing anything (v0.3). A diary note, a task, a letter, a payment. Here the host really does provide the tools, one per action, because only the host system can enforce a handler's authority limit, validate the change and record it for audit.

Reads integrate at one boundary, and are ours. Writes integrate per action, and are theirs.

Open risks​

  • The prompts assume a claim shape. Nineteen playbooks were written against generated data. A host with terser diaries or no SLA rules gets quietly worse answers.
  • There are no evals. Before several hosts depend on this, a small scored set per capability becomes the only way to tell whether a mapping is good enough or a prompt change helped.
  • Voice is not stateless the way text is. It holds two connections for the length of a call.
  • Claim content still leaves the host's estate. Statelessness answers "do you store our claims"; it does not answer "where does the text go".
  • The audit trail belongs to the host, written against the claim in its own system.
  • Lead time, not code. A new endpoint inside an insurer means change control and a security review. If documents are on the roadmap, start that conversation early.