Recipe catalog / uncertainty-expression

Label expressed certainty about a claim

Label categorical, qualified, or unresolved wording about a supplied claim without inferring internal confidence.

You need to label expressed certainty or hedging about one claim without an external truth assessment.

Explore this recipe interactively · Source and implementation guide

Use uncertainty-expression in TypeScript

Install with npm install jev-recipes. Requires Node.js 22.9 or newer and ES modules. Set TYPESAFE_API_KEY in your server environment for live calls, which send input to TypeSafe and use API quota. See the installation guide.

import { uncertaintyExpression } from 'jev-recipes/uncertainty-expression';

const result = await uncertaintyExpression({
  "claim": "The service outage was caused by the deployment.",
  "response": "The deployment probably caused the outage, but the logs do not rule out other causes."
});
console.log(result);

Input contract

Field	Type	Needed
claim	string	Required
response	string	Required
context	string	Optional
minConfidence	number	Optional

Full input and result schemas

{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "claim": {
        "type": "string",
        "description": "One proposition whose expressed certainty should be labeled."
      },
      "response": {
        "type": "string",
        "description": "The response whose own wording about the claim should be labeled."
      },
      "context": {
        "type": "string",
        "description": "Supplied context needed to resolve references and conditions in the response."
      },
      "minConfidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "required": [
      "claim",
      "response"
    ]
  },
  "result": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "model": {
        "type": "string"
      },
      "usage": {
        "type": "object",
        "properties": {
          "input_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "output_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "input_tokens",
          "output_tokens"
        ],
        "additionalProperties": false
      },
      "status": {
        "type": "string",
        "enum": [
          "ready",
          "review"
        ]
      },
      "verdict": {
        "type": "string",
        "enum": [
          "categorical",
          "qualified",
          "uncertain",
          "not_addressed",
          "unclear"
        ]
      },
      "confidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "probabilities": {
        "type": "object",
        "propertyNames": {
          "type": "string",
          "enum": [
            "categorical",
            "qualified",
            "uncertain",
            "not_addressed",
            "unclear"
          ]
        },
        "additionalProperties": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "required": [
          "categorical",
          "qualified",
          "uncertain",
          "not_addressed",
          "unclear"
        ]
      }
    },
    "required": [
      "model",
      "usage",
      "status",
      "verdict",
      "confidence",
      "probabilities"
    ],
    "additionalProperties": false
  }
}

Saved example result

This hand-authored response demonstrates the contract. It is not a model accuracy measurement. Run it without an API key: npx jev-recipes demo uncertainty-expression.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "status": "ready",
  "verdict": "qualified",
  "confidence": 0.96,
  "probabilities": {
    "categorical": 0.01,
    "qualified": 0.96,
    "uncertain": 0.01,
    "not_addressed": 0.01,
    "unclear": 0.01
  }
}

Evaluation evidence

Fixture only

No verified live accuracy measurement is available. Evaluate representative cases before using this decision in your workflow.

Use the evaluation guide to measure this decision on your own labeled cases.

Limitations

Labels wording about one proposition, not internal confidence, truth, calibration, or evidential support.
The result confidence describes the annotation decision. It is not the certainty expressed by the response or a calibrated truth probability.
Uncertain is a substantive label and can be ready. Only unclear or confidence below the threshold requires review.

Related recipes

certainty-match: Use certainty-match to compare a draft's certainty with a supplied evidence assessment.
claim-stance: Use claim-stance to label affirmation or denial separately from the strength of commitment.
verify: Use verify to check supplied evidence for a claim; expressed certainty is not evidence of truth.