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(query: str) -> ReviewResult

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

aprocess()¶

result = await agent.aprocess(query: 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 StreamingKernel oversight.

Uses sliding window, trend detection, and hard/soft halt from StreamingKernel. Yields (token, coherence) tuples. Halting stops future tokens but does not retract delivered ones.

Experimental. The coherence scores of correct and hallucinated partial text overlap, so the halt cannot yet 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 underlying signal overlap. Use the response-level scorer for production gating until calibrated.