contradict-text 0.1.0

Semantic contradiction detection for text pairs using NLI models

contradict-text

Semantic contradiction detection for text pairs using NLI models.

Built for RAG pipelines, fact-checking workflows, and any use case where you need to know if two passages conflict with each other.

How it works

1. Topic filter embeds both texts and computes cosine similarity. If the similarity is below a configurable threshold (default 0.5), the pair is skipped and returned as neutral without calling the NLI model.
2. NLI classification passes similar pairs to a Natural Language Inference model that returns one of contradiction, entailment, or neutral, along with a confidence score.

This two-step design keeps inference fast: unrelated pairs never reach the expensive NLI step.

Installation

pip install contradict-text

Requires Python 3.10+.

Note: The PyPI package is contradict-text but the Python import name is contradict.

Quick start

from contradict import ContradictionDetector

detector = ContradictionDetector()

result = detector.check(
    "Rituximab is highly effective for refractory pemphigus vulgaris.",
    "Rituximab shows no significant benefit over standard therapy in PV.",
)
print(result.label)            # "contradiction"
print(result.score)            # e.g. 0.91
print(result.topic_similarity) # e.g. 0.83
print(result.is_contradiction) # True

Scanning a list of texts

scan() checks every pair in a list and returns only the contradicting ones: useful for comparing retrieved chunks in a RAG pipeline.

results = detector.scan(
    texts=[chunk["content"] for chunk in retrieved_docs],
    sources=[chunk["path"] for chunk in retrieved_docs],
)

for r in results:
    print(f"{r.source_a}  vs  {r.source_b} - score: {r.score:.2f}")

scan() runs in O(n²) time over the number of texts, so keep lists reasonably small or pre-filter with your own retriever. Passing sources is optional; if omitted, source_a and source_b will be None. If provided, sources must have the same length as texts.

Configuration

detector = ContradictionDetector(
    nli_model="cross-encoder/nli-deberta-v3-small",  # any HuggingFace NLI model
    embed_model="BAAI/bge-small-en-v1.5",            # any sentence-transformers model
    topic_threshold=0.5,                             # raise to be more selective
)

Parameter	Default	Description
nli_model	cross-encoder/nli-deberta-v3-small	HuggingFace NLI model used for classification
embed_model	BAAI/bge-small-en-v1.5	Sentence-transformers model used for topic similarity
topic_threshold	0.5	Minimum cosine similarity required before running NLI

ContradictionResult fields

Field	Type	Description
text_a	str	First input text
text_b	str	Second input text
label	str	"contradiction", "entailment", or "neutral"
score	float	NLI confidence (0–1); 0.0 when NLI was skipped
topic_similarity	float	Cosine similarity between the two embeddings
source_a	str | None	Optional identifier for the source of text_a
source_b	str | None	Optional identifier for the source of text_b
nli_skipped	bool	True when topic similarity was below threshold and NLI was not run
is_contradiction	bool	Convenience property: True when label == "contradiction"

Development

pip install -e ".[dev]"
pytest

License

Apache 2.0