Fact engine

The Fact Engine verifies factual claims against a supplied context using deterministic methods first. The deterministic verdict is authoritative; any LLM fallback is recorded as an advisory check and can never overwrite the deterministic outcome.

Features

TF-IDF semantic similarity — no LLM needed.
Keyword overlap analysis — fast and deterministic.
Entity matching — numbers, dates, names.
Citation extraction — with relevance scoring.
Negation detection — catch contradictions.
Advisory-only LLM fallback — invoked only when deterministic confidence is below min_confidence, and its result is stored in advisory_checks.

Usage

from qwed_sdk import QWEDClient

client = QWEDClient(api_key="qwed_...")

result = client.verify_fact(
    claim="The company was founded in 2020.",
    context="Acme Corp was founded in 2020 by John Smith in San Francisco."
)

print(result.status)                              # "VERIFIED"
print(result.proof_ref)                           # "sha256:..."
print(result.developer_fields["deterministic_confidence"])  # 0.94
print(result.citations)                           # [{"sentence": "...", "relevance": 0.98}]

Result contract

The Fact Engine returns a DiagnosticResult. The deterministic verdict maps to a diagnostic status as follows:

Deterministic verdict	`DiagnosticResult.status`	Notes
`SUPPORTED`	`VERIFIED`	Emits a `proof_ref` bound to the deterministic evidence.
`REFUTED` (via negation)	`BLOCKED`	Fail-closed — refutation is treated as a block.
`NEUTRAL`	`UNVERIFIABLE`	Neither supported nor refuted by the context.
`INSUFFICIENT_EVIDENCE`	`UNVERIFIABLE`	Not enough overlap to decide.
Empty claim or context	`UNVERIFIABLE`	Returns `constraint_id: fact_verifier.empty_input`.
Pipeline error	`BLOCKED`	Unexpected errors fail closed rather than silently pass.

Confidence is exposed via developer_fields.deterministic_confidence and is never verdict-deciding — the mapping above is based on the deterministic verdict alone.

Scoring methods

Method	What it checks	Weight	Advisory only
Semantic similarity	TF-IDF cosine distance	0.25	No
Keyword overlap	Shared important words	0.20	No
Entity match	Numbers, dates, names	0.35	No
Negation conflict	Contradicting statements	0.20	No
LLM fallback	Model reasoning	—	Yes

methods_used in the result reflects this shape — each entry carries an advisory_only flag so callers can tell deterministic contributions from advisory ones.

Advisory-only LLM fallback

When the deterministic confidence is below min_confidence and a provider is configured, the engine calls an LLM for additional analysis. The LLM output is recorded in advisory_checks and does not change the returned status:

{
  "status": "UNVERIFIABLE",
  "engine": "Fact",
  "advisory_checks": [
    {"name": "tfidf_similarity", "score": 0.62, "threshold": 0.75},
    {"name": "llm_reasoning", "advisory_only": True, "text": "..."},
    {"name": "llm_confidence", "advisory_only": True, "value": 0.71}
  ],
  "developer_fields": {"deterministic_confidence": 0.62}
}

This preserves the guarantee from the 3-tier engine classification: the Fact engine’s deterministic path can emit VERIFIED with a proof_ref, but a heuristic or LLM signal alone can never do so.

Batch verification

BatchFactVerifier summaries are counted by diagnostic status:

summary = batch.verify_many(claims, context=context)
print(summary["verified"])      # count of VERIFIED items
print(summary["unverifiable"])  # NEUTRAL / INSUFFICIENT / empty
print(summary["blocked"])       # REFUTED or pipeline errors

Overview

Core Engines

Analysis Engines

Specialized Engines

Features

Usage

Result contract

Scoring methods

Advisory-only LLM fallback

Batch verification

​Features

​Usage

​Result contract

​Scoring methods

​Advisory-only LLM fallback

​Batch verification

Features

Usage

Result contract

Scoring methods

Advisory-only LLM fallback

Batch verification