Recipe catalog / causal-language-strength

Grade the strength of causal language

How strong is the causal claim in the wording of statement, from no relationship claimed to causation stated as fact?

You are checking abstracts, press releases, or summaries of studies for causal overreach, so that wording can be compared with what the study design supports.

Explore this recipe interactively · Source and implementation guide

Use causal-language-strength 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 { causalLanguageStrength } from 'jev-recipes/causal-language-strength';

const result = await causalLanguageStrength({
  "statement": "Adolescents who reported more screen time in the hour before bed also reported poorer sleep quality (r = 0.31, p < .001). Because the data are cross-sectional, our design does not permit causal conclusions.",
  "minConfidence": 0.8
});
console.log(result);

Input contract

{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "statement": {
        "type": "string"
      },
      "minConfidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "required": [
      "statement"
    ]
  },
  "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"
        ]
      },
      "score": {
        "type": "number",
        "minimum": 0
      },
      "level": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
      },
      "confidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "probabilities": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      },
      "causality": {
        "type": "string",
        "enum": [
          "none",
          "association",
          "suggestive",
          "hedged",
          "asserted"
        ]
      }
    },
    "required": [
      "model",
      "usage",
      "status",
      "score",
      "level",
      "confidence",
      "probabilities",
      "causality"
    ],
    "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 causal-language-strength.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "status": "ready",
  "score": 1.09,
  "level": 1,
  "confidence": 0.9,
  "probabilities": {
    "0": 0.01,
    "1": 0.9,
    "2": 0.08,
    "3": 0.01,
    "4": 0
  },
  "causality": "association"
}

Evaluation evidence

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

Limitations

• Grades the wording only. It does not know the study design and cannot say whether the causal strength is warranted.
• Judges one statement at a time; a paper that hedges in the discussion and asserts in the abstract must be checked sentence by sentence.
• Distinguishes causal from associational language, not true from false; a strongly asserted claim can be correct.

Related recipes

• causal-attribution: Use causal-attribution to label whether an explanation blames the person or the situation, rather than how strongly any causal link is asserted.
• uncertainty-expression: Use uncertainty-expression to grade how hedged a statement is overall, rather than the strength of its causal claim specifically.