Check a draft against its sources

A model that answers from retrieved sources can still add a claim the sources never make. This example checks a draft against its sources before your user sees it. Use it in a retrieval pipeline, after the answer is written and before it is shown.

How it works

The context is JSON with the user’s question, the sources you retrieved and the draft answer. The keys are yours to choose. One binary decision, grounded, asks whether the sources establish every factual claim in the draft. yes means every fact is stated in the sources or follows directly from them. no means at least one fact is missing from the sources or contradicts them.

Try it

Open this recipe in the playground to run it without an account. The sources there say refunds cover the unused months only. The draft promises a full refund within 14 days, even after a year of use. To run it from your code, set SQWISH_API_KEY as in the quickstart, then send this request:

from sqwishai import OneHot

with OneHot() as client:  # reads SQWISH_API_KEY
    result = client.decide(
        model="kettei-core",
        context={
            "question": "Can I get my money back if I cancel my annual plan?",
            "sources": [
                "Refunds are issued within 14 days of a cancellation request.",
                "Annual plans can be cancelled at any time from the Billing page. Refunds cover the unused months only.",
            ],
            "draft": "You can cancel your annual plan any time from Billing, and you'll get a full refund within 14 days, even after a year of use.",
        },
        decisions=[
            {
                "id": "grounded",
                "kind": "binary",
                "question": "Can the supplied sources establish every factual claim in the draft?",
                "outcomes": {
                    "yes": "Every fact in the draft is stated in the sources or follows directly from them.",
                    "no": "At least one fact in the draft is missing from the sources or contradicts them.",
                },
            },
        ],
    )

import { OneHot } from "sqwishai";

const client = new OneHot(); // reads SQWISH_API_KEY
const result = await client.decide({
  "model": "kettei-core",
  "context": {
    "question": "Can I get my money back if I cancel my annual plan?",
    "sources": [
      "Refunds are issued within 14 days of a cancellation request.",
      "Annual plans can be cancelled at any time from the Billing page. Refunds cover the unused months only."
    ],
    "draft": "You can cancel your annual plan any time from Billing, and you'll get a full refund within 14 days, even after a year of use."
  },
  "decisions": [
    {
      "id": "grounded",
      "kind": "binary",
      "question": "Can the supplied sources establish every factual claim in the draft?",
      "outcomes": {
        "yes": "Every fact in the draft is stated in the sources or follows directly from them.",
        "no": "At least one fact in the draft is missing from the sources or contradicts them."
      }
    }
  ]
});

curl --fail-with-body --silent --show-error https://api.sqwish.ai/v1/decide \
  -H "Authorization: Bearer $SQWISH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "kettei-core",
  "context": {
    "question": "Can I get my money back if I cancel my annual plan?",
    "sources": [
      "Refunds are issued within 14 days of a cancellation request.",
      "Annual plans can be cancelled at any time from the Billing page. Refunds cover the unused months only."
    ],
    "draft": "You can cancel your annual plan any time from Billing, and you'll get a full refund within 14 days, even after a year of use."
  },
  "decisions": [
    {
      "id": "grounded",
      "kind": "binary",
      "question": "Can the supplied sources establish every factual claim in the draft?",
      "outcomes": {
        "yes": "Every fact in the draft is stated in the sources or follows directly from them.",
        "no": "At least one fact in the draft is missing from the sources or contradicts them."
      }
    }
  ]
}
JSON

Act on the answer

p_grounded = result["decisions"]["grounded"]["probabilities"]["yes"]

if p_grounded < 0.7:  # a starting point: check what it does to your block rate
    ...  # block the draft, or rewrite it

const pGrounded = result.decisions.grounded.probabilities.yes;

if (pGrounded < 0.7) { // a starting point: check what it does to your block rate
  // block the draft, or rewrite it
}

A missed unsupported claim usually costs more than a false alarm, so start at 0.7 rather than 0.5. Then check how many drafts that blocks.

Adapt it to your data

It works best on one claim at a time, which is how it was measured. The sample draft makes two claims: that you can cancel any time, and that you get a full refund. For a longer answer:

Split the draft into sentences, and split a sentence again if it makes several claims.
Check each claim against the same sources, as the draft, in a request of its own.
Block the answer if any claim’s probability of yes is below your threshold.

Python

from sqwishai import OneHot

sources = [
    "Refunds are issued within 14 days of a cancellation request.",
    "Annual plans can be cancelled at any time from the Billing page. Refunds cover the unused months only.",
]
claims = [
    "You can cancel your annual plan any time from Billing.",
    "You'll get a full refund within 14 days, even after a year of use.",
]
grounded = {
    "id": "grounded", "kind": "binary",
    "question": "Can the supplied sources establish every factual claim in the draft?",
    "outcomes": {
        "yes": "Every fact in the draft is stated in the sources or follows directly from them.",
        "no": "At least one fact in the draft is missing from the sources or contradicts them.",
    },
}

with OneHot() as client:
    answers = [client.decide(context={"sources": sources, "draft": claim}, decisions=[grounded])
               for claim in claims]

unsupported = [claim for claim, answer in zip(claims, answers)
               if answer["decisions"]["grounded"]["probabilities"]["yes"] < 0.7]

You can also check every claim in one request: put the claims under keys in the context, and ask one decision per claim that names its key. You pay for the sources once. Decisions in one request can affect each other’s answers, though, so one claim can change the answer for another.

What to watch

Drafts marked supported that contain a claim the sources never make.
What “supported” means. It means these sources state it, not that the sources are true.
Long drafts checked in one go. Split them into claims first.

How well it works

Measured with kettei-core on 651 examples from a public dataset, it chose the right answer 79.0% of the time. Always picking the most common answer scores 53.9%. Your own data will differ, so measure it on examples of yours before you rely on it (improve a decision).

Full results

Dataset: AttributionBench (Apache-2.0).
Sample: 651 rows, 651 measured decisions.
Decisions measured: grounded.
Wording: tuned.

Measure	Value	Range
Accuracy (higher is better)	0.7896	0.7573 to 0.8203
Log loss (lower is better)	0.5072	0.4455 to 0.566
Brier score (lower is better)	0.323	0.2796 to 0.3651
Calibration error (lower is better)	0.0766	0.0508 to 0.1091

Always picking the most common answer has an accuracy of 0.5392, and guessing by how common each answer is has a log loss of 0.6901.These are past results on one dataset, not a promise of accuracy on yours.

It was measured one claim at a time, which is how that dataset asks the question.

Next steps

Grade how well each passage answers the query: choose the sources before the answer is written.
Improve a decision: measure it on your own answers and make it more accurate.
API reference: every field in the request and the answer.

Overview

Triage and routing

Agents

Retrieval and answer quality