DirectorConfig¶

Dataclass-based configuration with environment variable, YAML file, and named profile loaders. All fields have sensible defaults.

Loading Configuration¶

Environment VariablesYAML FileNamed Profile

from director_ai.core.config import DirectorConfig

config = DirectorConfig.from_env()

All fields map to DIRECTOR_<FIELD> env vars:

DIRECTOR_COHERENCE_THRESHOLD=0.6
DIRECTOR_HARD_LIMIT=0.5
DIRECTOR_USE_NLI=true
DIRECTOR_NLI_MODEL=lytang/MiniCheck-DeBERTa-L
DIRECTOR_LLM_PROVIDER=openai
DIRECTOR_VECTOR_BACKEND=chroma
DIRECTOR_METRICS_ENABLED=true

config = DirectorConfig.from_yaml("config.yaml")

coherence_threshold: 0.6
hard_limit: 0.5
use_nli: true
nli_model: "lytang/MiniCheck-DeBERTa-L"
vector_backend: chroma
chroma_persist_dir: "./data/chroma"
metrics_enabled: true

config = DirectorConfig.from_profile("thorough")

Profiles¶

Profile	NLI	Threshold	Candidates	Metrics	Use Case
`fast`	Off	0.5	1	Off	Development, prototyping
`thorough`	On	0.6	3	On	Production default
`research`	On	0.7	5	On	Evaluation, benchmarking
`medical`	On	0.30	3	On	Healthcare (measured on PubMedQA)
`finance`	On	0.30	3	On	Financial services (measured on FinanceBench)
`legal`	On	0.30	3	On	Legal document review
`creative`	Off	0.40	3	On	Creative writing (low halt rate)
`customer_support`	Off	0.55	3	On	Support agents
`summarization`	On	0.15	3	On	Document summarization
`lite`	Off	0.50	1	Off	Zero-dependency fast path

Building Components from Config¶

config = DirectorConfig.from_profile("thorough")

# Build a scorer with all config settings applied
scorer = config.build_scorer(store=my_store)

# Build a vector store from config
store = config.build_store()

Field Reference¶

Scoring¶

Field	Type	Default	Description
`coherence_threshold`	`float`	`0.6`	Minimum coherence to approve
`hard_limit`	`float`	`0.5`	Safety kernel emergency stop
`soft_limit`	`float`	`0.6`	Warning zone threshold
`use_nli`	`bool`	`False`	Enable DeBERTa NLI model
`nli_model`	`str`	`"yaxili96/FactCG-DeBERTa-v3-Large"`	HuggingFace model ID
`max_candidates`	`int`	`3`	LLM candidates to generate
`history_window`	`int`	`5`	Rolling history size
`scorer_backend`	`str`	`"deberta"`	`deberta`, `onnx`, `minicheck`, `hybrid`, `lite`, `rust`

LLM Provider¶

Field	Type	Default	Description
`llm_provider`	`str`	`"mock"`	`mock`, `openai`, `anthropic`, `huggingface`, `local`
`llm_api_url`	`str`	`""`	API endpoint (for `local` provider)
`llm_api_key`	`str`	`""`	API key (for cloud providers)
`llm_model`	`str`	`""`	Model name
`llm_temperature`	`float`	`0.8`	Sampling temperature
`llm_max_tokens`	`int`	`512`	Maximum tokens per response

LLM-as-Judge¶

Privacy

When enabled, user prompts and responses are sent to the configured external LLM. Do not enable in privacy-sensitive deployments without user consent.

Field	Type	Default	Description
`llm_judge_enabled`	`bool`	`False`	Enable LLM escalation
`llm_judge_confidence_threshold`	`float`	`0.3`	Softmax margin for escalation
`llm_judge_provider`	`str`	`""`	`"openai"`, `"anthropic"`, or `"local"`
`llm_judge_model`	`str`	`""`	Model name for judge
`privacy_mode`	`bool`	`False`	Redact PII before sending

Vector Store¶

Field	Type	Default	Description
`vector_backend`	`str`	`"memory"`	`"memory"` or `"chroma"`
`embedding_model`	`str`	`"BAAI/bge-large-en-v1.5"`	Embedding model ID
`chroma_collection`	`str`	`"director_ai"`	ChromaDB collection name
`chroma_persist_dir`	`str`	`""`	Persistence directory (empty = in-memory)
`reranker_enabled`	`bool`	`True`	Enable cross-encoder reranking
`reranker_model`	`str`	`"cross-encoder/ms-marco-MiniLM-L-6-v2"`	Reranker model

Server¶

Field	Type	Default	Description
`server_host`	`str`	`"0.0.0.0"`	Bind address
`server_port`	`int`	`8080`	Port
`server_workers`	`int`	`1`	Uvicorn worker count
`cors_origins`	`str`	`""`	CORS allowed origins
`metrics_enabled`	`bool`	`True`	Enable Prometheus metrics
`log_level`	`str`	`"INFO"`	Logging level
`log_json`	`bool`	`False`	Structured JSON logging

Caching¶

Field	Type	Default	Description
`cache_size`	`int`	`1024`	LRU cache max entries
`cache_ttl`	`float`	`300.0`	Cache entry TTL (seconds)
`redis_url`	`str`	`""`	Redis URL for distributed caching

Injection Detection¶

Field	Type	Default	Description
`injection_detection_enabled`	`bool`	`False`	Enable two-stage injection detection
`injection_threshold`	`float`	`0.7`	Combined score above which injection is flagged
`injection_drift_threshold`	`float`	`0.6`	Per-claim calibrated divergence above which = "drifted"
`injection_claim_threshold`	`float`	`0.75`	Divergence + low traceability = "injected"
`injection_baseline_divergence`	`float`	`0.4`	Expected normal intent divergence for on-topic responses
`injection_stage1_weight`	`float`	`0.3`	Weight of InputSanitizer score in combined score

DIRECTOR_INJECTION_DETECTION_ENABLED=true
DIRECTOR_INJECTION_THRESHOLD=0.7

Full API¶

director_ai.core.config.DirectorConfig `dataclass` ¶

DirectorConfig(mode: str = 'auto', dry_run: bool = False, production_mode: bool = False, hardened: bool = False, cost_tracking_enabled: bool = False, coherence_threshold: float = 0.6, hard_limit: float = 0.5, soft_limit: float = 0.6, use_nli: bool = False, scorer_model: str = '', allow_domain_only_scorer_model: bool = False, allow_custom_scorer_model: bool = False, nli_model: str = 'yaxili96/FactCG-DeBERTa-v3-Large', nli_model_artifact_uri: str = '', nli_model_revision: str = '0430e3509dbd28d2dff7a117c0eae25359ff3e80', nli_max_length: int = 512, max_candidates: int = 3, history_window: int = 5, llm_provider: str = 'mock', llm_api_url: str = '', llm_api_key: str = '', llm_model: str = '', llm_temperature: float = 0.8, llm_max_tokens: int = 512, llm_judge_enabled: bool = False, llm_judge_confidence_threshold: float = 0.3, llm_judge_provider: str = '', llm_judge_model: str = '', llm_judge_local_model: str = '', privacy_mode: bool = False, scorer_backend: str = 'auto', nli_devices: str = '', vector_backend: str = 'memory', embedding_model: str = 'BAAI/bge-large-en-v1.5', embedding_model_revision: str = 'd4aa6901d3a41ba39fb536a557fa166f842b0e09', embedding_base_url: str = '', embedding_api_key: str = '', embedding_timeout_s: float = 10.0, embedding_vector_size: int = 384, remanentia_base_url: str = 'http://127.0.0.1:8001', remanentia_timeout_s: float = 5.0, remanentia_source: str = '', chroma_collection: str = 'director_ai', chroma_persist_dir: str = '', hybrid_retrieval: bool = True, reranker_enabled: bool = True, reranker_model: str = 'cross-encoder/ms-marco-MiniLM-L-6-v2', reranker_model_revision: str = 'c5ee24cb16019beea0893ab7796b1df96625c6b8', reranker_top_k_multiplier: int = 3, retrieval_abstention_threshold: float = 0.3, parent_child_enabled: bool = False, parent_chunk_size: int = 2048, child_chunk_size: int = 256, adaptive_retrieval_enabled: bool = False, adaptive_retrieval_threshold: float = 0.5, hyde_enabled: bool = False, hyde_prompt_template: str = '', query_decomposition_enabled: bool = False, query_decomposition_strategy: str = 'heuristic', contextual_compression_enabled: bool = False, contextual_compression_strategy: str = 'heuristic', multi_vector_enabled: bool = False, multi_vector_representations: str = 'content,summary,title', redis_url: str = '', redis_prefix: str = 'dai:', cache_size: int = 1024, cache_ttl: float = 300.0, server_host: str = '0.0.0.0', server_port: int = 8080, server_workers: int = 1, cors_origins: str = '', onnx_path: str = '', onnx_batch_size: int = 16, onnx_flush_timeout_ms: float = 10.0, batch_max_concurrency: int = 4, review_queue_enabled: bool = False, review_queue_max_batch: int = 32, review_queue_flush_timeout_ms: float = 10.0, metrics_enabled: bool = True, log_level: str = 'INFO', log_json: bool = False, otel_enabled: bool = False, audit_log_path: str = '', audit_postgres_url: str = '', compliance_db_path: str = '', feedback_db_path: str = '', tenant_routing: bool = False, rate_limit_enabled: bool = False, sanitize_inputs: bool = True, sanitizer_block_threshold: float = 0.8, redact_pii: bool = False, injection_detection_enabled: bool = False, injection_threshold: float = 0.7, injection_drift_threshold: float = 0.6, injection_claim_threshold: float = 0.75, injection_baseline_divergence: float = 0.4, injection_stage1_weight: float = 0.3, w_logic: float = 0.0, w_fact: float = 0.0, metrics_require_auth: bool = True, rate_limit_rpm: int = 0, rate_limit_strict: bool = False, api_keys: list[str] = list(), api_key_tenant_map: str = '', knowledge_write_require_auth: bool = False, knowledge_write_require_tenant_binding: bool = True, knowledge_write_require_signature: bool = False, knowledge_write_hmac_keys: str = '', stats_backend: str = 'prometheus', stats_db_path: str = '~/.director-ai/stats.db', source_endpoint_enabled: bool = True, source_repository_url: str = 'https://github.com/anulum/director-ai', license_key: str = '', license_file: str = '', nli_fact_inner_agg: str = 'max', nli_fact_outer_agg: str = 'max', nli_logic_inner_agg: str = 'max', nli_logic_outer_agg: str = 'max', nli_premise_ratio: float = 0.4, nli_fact_retrieval_top_k: int = 3, nli_use_prompt_as_premise: bool = False, nli_summarization_baseline: float = 0.2, nli_claim_coverage_enabled: bool = True, nli_claim_support_threshold: float = 0.6, nli_claim_coverage_alpha: float = 0.4, adaptive_threshold_enabled: bool = True, threshold_summarization: float = 0.72, threshold_qa: float = 0.69, threshold_fact_check: float = 0.56, threshold_rag: float = 0.78, threshold_dialogue: float = 0.68, nli_chunk_overlap_ratio: float = 0.5, nli_qa_premise_ratio: float = 0.7, nli_confidence_weighted_agg: bool = True, lora_adapter_path: str = '', meta_classifier_path: str = '', grpc_max_message_mb: int = 4, grpc_deadline_seconds: float = 30.0, profile: str = 'default', extra: dict[str, str] = dict(), _REDACTED_FIELDS: frozenset[str] = frozenset({'llm_api_key', 'embedding_api_key', 'api_keys', 'api_key_tenant_map', 'knowledge_write_hmac_keys', 'audit_postgres_url', 'redis_url'}))

Central configuration for Director-Class AI.

Parameters:

Name	Type	Default
`coherence_threshold`	`float — minimum coherence to approve (0.0-1.0).`	`0.6`
`hard_limit`	`float — safety kernel emergency stop threshold.`	`0.5`
`use_nli`	`bool — enable DeBERTa NLI model for logical divergence.`	`False`
`nli_model`	`str — HuggingFace model ID for NLI.`	`'yaxili96/FactCG-DeBERTa-v3-Large'`
`max_candidates`	`int — number of LLM candidates to generate.`	`3`
`history_window`	`int — scorer rolling history size.`	`5`
`llm_provider`	`str — LLM backend name.`	`'mock'`
`llm_api_url`	`str — API endpoint URL (for "local" provider).`	`''`
`llm_api_key`	`str — API key (for cloud providers).`	`''`
`llm_model`	`str — model name for cloud providers.`	`''`
`llm_temperature`	`float — sampling temperature.`	`0.8`
`llm_max_tokens`	`int — maximum tokens per response.`	`512`
`vector_backend`	`str — "memory" or "chroma".`	`'memory'`
`chroma_collection`	`str — ChromaDB collection name.`	`'director_ai'`
`chroma_persist_dir`	`str — ChromaDB persistence directory (None=in-memory).`	`''`
`onnx_path`	`str — directory with exported ONNX model (for scorer_backend="onnx").`	`''`
`server_host`	`str — FastAPI server bind address.`	`'0.0.0.0'`
`server_port`	`int — FastAPI server port.`	`8080`
`server_workers`	`int — Uvicorn worker count.`	`1`
`batch_max_concurrency`	`int — max concurrent batch requests.`	`4`
`metrics_enabled`	`bool — enable Prometheus-style metrics collection.`	`True`
`log_level`	`str — logging level.`	`'INFO'`
`log_json`	`bool — structured JSON logging.`	`False`

from_env `classmethod` ¶

from_env(prefix: str = 'DIRECTOR_') -> DirectorConfig

Load configuration from environment variables.

Reads DIRECTOR_<FIELD> env vars (case-insensitive field matching). Example: DIRECTOR_COHERENCE_THRESHOLD=0.7

from_yaml `classmethod` ¶

from_yaml(path: str) -> DirectorConfig

Load configuration from a YAML file.

Falls back to JSON parsing if PyYAML is not installed.

from_profile `classmethod` ¶

from_profile(name: str) -> DirectorConfig

Load a predefined profile.

Profiles

"fast" — heuristic scoring only, no NLI model, low latency.
"thorough" — NLI + RAG scoring, higher accuracy.
"research" — NLI + RAG + reranker, all scoring modules enabled.

profile_metadata `classmethod` ¶

profile_metadata(name: str) -> ProfileMetadata

Return validation and dependency metadata for a built-in profile.

list_profile_metadata `classmethod` ¶

list_profile_metadata() -> tuple[ProfileMetadata, ...]

Return metadata for all built-in profiles in display order.

configure_logging ¶

configure_logging() -> None

Apply log_level and log_json settings to the DirectorAI logger hierarchy.

build_store ¶

build_store()

Construct a VectorGroundTruthStore from config fields.

In general mode, returns a bare GroundTruthStore (no vector backend). In grounded and auto modes, builds the full vector pipeline.

build_scorer ¶

build_scorer(store=None)

Construct a CoherenceScorer wired to all relevant config fields.

to_dict ¶

to_dict() -> dict

Serialize to a plain dict (safe for JSON/API responses).