Skip to content

Conflict-Aware Knowledge Checks

ConflictAwareKnowledgeGuard validates proposed facts before they enter a retrieval store. It is designed for user facts, signed facts, passport claims, and curated KB updates where contradictory inserts must be stopped before they become retrievable context.

The guard works with GroundTruthStore and VectorGroundTruthStore:

  • same-key value changes are blocked by default
  • explicit contradiction references in metadata are blocked before write
  • optional semantic contradiction scoring can warn or block against the current store contents
  • reports use keys, references, and hashes only; raw fact text is not serialized
  • unsafe metadata keys are stripped before a permitted write
from director_ai import ConflictAwareKnowledgeGuard, GroundTruthStore, KnowledgeFact

store = GroundTruthStore()
store.add_fact("refund_policy", "Refunds are available within 30 days.")

guard = ConflictAwareKnowledgeGuard(store)
result = guard.add_fact(
    KnowledgeFact(
        key="refund_policy",
        value="Refunds are never available.",
        metadata={"claim_id": "claim-refund"},
    )
)

assert result.decision == "block"
assert store.facts["refund_policy"] == "Refunds are available within 30 days."

Semantic Scoring

Pass score_fn(existing, incoming) -> float when the deployment has a calibrated NLI, rule, or domain verifier for contradiction scoring. Scores must be finite and in [0, 1]. Values above warn_threshold produce warn; values above block_threshold produce block.

guard = ConflictAwareKnowledgeGuard(
    store,
    score_fn=contradiction_score,
    warn_threshold=0.6,
    block_threshold=0.9,
)

Explicit References

Metadata can declare a contradiction target by key, claim id, signed-fact id, passport-claim id, source id, or external id:

result = guard.add_fact(
    KnowledgeFact(
        key="policy_v2",
        value="Refunds are unavailable after delivery confirmation.",
        metadata={"contradicts": "claim-refund-v1"},
    )
)

The guard returns block when the target is already present. For vector stores, this happens before VectorGroundTruthStore.add_fact(), so the fact is not embedded and the store's post-write conflict ledger is not polluted by rejected input.

Full API

director_ai.core.retrieval.conflict_guard.KnowledgeFact dataclass 

KnowledgeFact(key: str, value: str, tenant_id: str = '', metadata: Mapping[str, Any] = dict())

Fact proposed for insertion into a retrieval store.

__post_init__ 

__post_init__() -> None

Validate fact fields and normalise tenant-safe metadata.

director_ai.core.retrieval.conflict_guard.KnowledgeConflict dataclass 

KnowledgeConflict(conflict_type: str, incoming_key: str, existing_key: str, incoming_hash: str, existing_hash: str, score: float, evidence_refs: tuple[str, ...], reason: str)

Tenant-safe conflict report for an incoming KB fact.

__post_init__ 

__post_init__() -> None

Validate conflict type, score, and evidence references.

to_dict 

to_dict() -> dict[str, Any]

Return a JSON-safe report without raw fact text.

director_ai.core.retrieval.conflict_guard.KnowledgeConflictCheck dataclass 

KnowledgeConflictCheck(decision: str, incoming_key: str, tenant_id: str, incoming_hash: str, conflicts: tuple[KnowledgeConflict, ...] = tuple(), evidence_refs: tuple[str, ...] = tuple())

Pre-ingestion decision for one proposed fact.

blocked property 

blocked: bool

Return True when the proposed fact must not enter retrieval.

__post_init__ 

__post_init__() -> None

Validate the decision and freeze conflict/reference tuples.

to_dict 

to_dict() -> dict[str, Any]

Return a JSON-safe decision payload without raw fact text.

director_ai.core.retrieval.conflict_guard.ConflictAwareKnowledgeGuard 

ConflictAwareKnowledgeGuard(store: GroundTruthStore, *, score_fn: Callable[[str, str], float] | None = None, warn_threshold: float = 0.65, block_threshold: float = 0.85, block_on_same_key_mismatch: bool = True, block_on_explicit_contradiction: bool = True)

Validate incoming facts before they are admitted to retrieval.

Initialise conflict thresholds and store integration policy.

check_fact 

check_fact(fact: KnowledgeFact) -> KnowledgeConflictCheck

Check whether fact can enter the configured store.

add_fact 

add_fact(fact: KnowledgeFact) -> KnowledgeConflictCheck

Check and add fact only when the pre-ingestion decision permits it.