CoherenceAgent¶

Integrated orchestrator that combines a generator, scorer, ground truth store, and safety kernel into a single process() call. Handles candidate generation, scoring, fallback, and output interlock.

Usage¶

from director_ai import CoherenceAgent

agent = CoherenceAgent(
    use_nli=True,
    fallback="retrieval",
)

result = agent.process("What is the refund policy?")
print(result.output)
print(result.coherence.score if result.coherence else None)

Constructor Parameters¶

Parameter	Type	Default	Description
`llm_api_url`	`str \\| None`	`None`	Direct URL to OpenAI-compatible endpoint
`use_nli`	`bool \\| None`	`None`	Enable NLI model scoring
`provider`	`str \\| None`	`None`	`"openai"` or `"anthropic"` (reads API key from env)
`fallback`	`str \\| None`	`None`	Fallback mode: `"retrieval"`, `"disclaimer"`, `None`
`disclaimer_prefix`	`str`	`"[Unverified] "`	Prefix for disclaimer fallback text

Mutual exclusivity

llm_api_url and provider are mutually exclusive. Use one or the other.

Methods¶

process()¶

result = agent.process(prompt: str) -> ReviewResult

Generate candidates, score them, return the best approved response (or fallback).

aprocess()¶

result = await agent.aprocess(prompt: str) -> ReviewResult

Async variant of process().

stream()¶

async for token, score in agent.stream(prompt: str, tenant_id: str = ""):
    print(token, end="")

Async streaming with real-time coherence monitoring. Yields (token, coherence_score) tuples.

Fallback Modes¶

Mode	Behavior
`None`	Reject if all candidates fail — returns empty response with `halted=True`
`"retrieval"`	Return KB context when all candidates fail
`"disclaimer"`	Prepend warning to the best-rejected candidate

# Retrieval fallback
agent = CoherenceAgent(fallback="retrieval")
result = agent.process("What is the refund policy?")
if result.halted:
    print("Fell back to KB retrieval")

# Disclaimer fallback
agent = CoherenceAgent(fallback="disclaimer")
result = agent.process("What is the refund policy?")
# Response prefixed with "[Unverified] ..."

Full API¶

director_ai.core.agent.CoherenceAgent ¶

CoherenceAgent(llm_api_url: str | None = None, use_nli: bool | None = None, provider: str | None = None, fallback: str | None = None, disclaimer_prefix: str = '[Unverified] ', api_key: str | None = None, production_mode: bool = False, llm_max_tokens: int = 128, llm_temperature: float = 0.8, max_candidates: int = 3, *, _scorer: CoherenceScorer | None = None, _store: GroundTruthStore | None = None, containment_guard: ContainmentGuard | None = None, containment_anchor: RealityAnchor | None = None, grounding_hook: GroundingHook | None = None, passport_verifier: PassportVerifier | None = None, physical_action_mode: str = 'warn', allow_physical_action_blocking: bool = False, contradiction_halt: ContradictionHalt | None = None, correctness_feedback: RemanentiaCorrectnessClient | None = None)

Integrated coherence-verification agent.

Orchestrates: - Generator: Candidate response generation (test or real LLM). - Scorer: Weighted NLI divergence scoring. - Ground Truth Store: RAG-based fact retrieval. - Safety Kernel: Output interlock.

Parameters:

Name	Type	Description	Default
`llm_api_url`	`str \| None — direct URL to OpenAI-compatible endpoint.`		`None`
`use_nli`	`bool \| None — enable NLI model scoring.`		`None`
`provider`	`str \| None — "openai" or "anthropic". Reads API key from env.`	Mutually exclusive with llm_api_url.	`None`
`production_mode`	`bool — require an explicit real LLM generator.`		`False`
`max_candidates`	`int — how many candidate responses the generator produces`	per prompt (passed as `n` to `generate_candidates`); the best-scoring approved candidate is emitted. Sourced from `DirectorConfig.max_candidates` at the server/CLI/gRPC construction sites.	`3`

process ¶

process(prompt: str, tenant_id: str = '', cancel_event: Event | None = None) -> ReviewResult

Process a prompt end-to-end and return the verified output.

verify_physical_action ¶

verify_physical_action(action: PhysicalAction, *, tenant_id: str = '') -> GroundingVerdict

Screen a proposed physical action against the configured grounding hook.

Raises :class:RuntimeError if no hook is configured — callers opt in explicitly.

verify_passport ¶

verify_passport(passport: CrossOrgPassport) -> PassportVerdict

Run the configured passport verifier against passport.

Raises :class:RuntimeError when no verifier is attached.

aprocess `async` ¶

aprocess(prompt: str, tenant_id: str = '', cancel_event: Event | None = None) -> ReviewResult

Async version of :meth:process via run_in_executor.

stream `async` ¶

stream(prompt: str, tenant_id: str = '') -> AsyncIterator[tuple[str, float]]

Stream tokens with real-time halt oversight.

Yields (token, coherence) tuples. Halting stops future tokens but does not retract delivered ones.

With a configured :class:ContradictionHalt (streaming_contradiction_halt=True) each completed claim is scored by P(contradiction) against retrieved grounding facts and the stream halts on genuine contradiction — the calibrated real-time mechanism (false-halt 1.48% over 135 grounded passages at threshold 0.2; see benchmarks/results/streaming_contradiction_halt_base.json and the streaming guide).

Without it, halting falls back to the coherence signal (StreamingKernel sliding window, trend detection, hard/soft halt), which remains experimental: coherence scores of correct and hallucinated partial text overlap, so that path cannot separate them without a high false-halt rate (see benchmarks/streaming_false_halt_bench.py). Coherence is re-scored only at claim boundaries via :class:StreamingCoherenceGate to avoid scoring half-finished sentences, but this does not resolve the signal overlap — enable the contradiction halt or use the response-level scorer for production gating.