Configuration Reference

On this page

ContextEngineConfig (root)
QueryAnalyzerConfig
RetrieverConfig
FilterConfig
RankingConfig
ComposerConfig
GuardConfig
CacheConfig
LengthCounter

All configuration lives in config.py as a tree of @dataclass definitions rooted at ContextEngineConfig. Every sub-config has a sensible default, so ContextEngineConfig() works with zero arguments.

Python · 6 lines

from zerda.context import ContextEngineConfig

config = ContextEngineConfig()
config.retriever.top_k = 30
config.composer.template = "structured"
config.guard.check_relevance = True

`ContextEngineConfig` (root)

Field	Type	Default	Purpose
`query_analyzer`	`QueryAnalyzerConfig`	new instance	See below
`retriever`	`RetrieverConfig`	new instance	See below
`filter_cfg`	`FilterConfig`	new instance	See below
`ranking`	`RankingConfig`	new instance	See below
`composer`	`ComposerConfig`	new instance	See below
`guard`	`GuardConfig`	new instance	See below
`cache`	`CacheConfig`	new instance	See below
`language`	`str`	`"auto"`	Documented values: `"auto"`, `"ar"`, `"en"`. Note: grepping the implementation, this field is not actually read anywhere outside of being stored — language detection is performed per-query by `RuleBasedQueryAnalyzer` regardless of this setting.
`enable_adaptive`	`bool`	`True`	Gates whether `AdaptiveLearningSystem.record()` and `.suggest_budget()` do anything.
`multi_turn`	`bool`	`True`	Gates whether `ContextEngine` creates a `ConversationHistory` and uses it for query enrichment.

It also exposes three backward-compatible properties that proxy into composer:

max_context_length (get/set) → composer.max_context_length
separator (get only) → composer.separator
template (get only) → composer.template

ContextConfig is a plain alias: ContextConfig = ContextEngineConfig. They are the same class.

`QueryAnalyzerConfig`

Field	Type	Default	Purpose
`budget_low`	`int`	`800`	Context budget (chars) assigned to `QueryComplexity.LOW` queries
`budget_medium`	`int`	`2000`	Context budget assigned to `QueryComplexity.MEDIUM` queries
`budget_high`	`int`	`4000`	Context budget assigned to `QueryComplexity.HIGH` queries
`custom_entities`	`List[str]`	`[]`	Domain-specific terms always recognized as entities if present in the query (case-insensitive substring match)
`arabic_threshold`	`float`	`0.3`	Minimum ratio of Arabic characters to non-space characters for a query to be classified as Arabic

`RetrieverConfig`

Field	Type	Default	Purpose
`top_k`	`int`	`20`	Number of results requested from the hybrid retriever before filtering/ranking
`vector_weight`	`float`	`0.60`	Weight of vector similarity in the hybrid composite score
`keyword_weight`	`float`	`0.30`	Weight of BM25 score in the hybrid composite score
`metadata_weight`	`float`	`0.10`	Weight of metadata-match score in the hybrid composite score
`use_vector`	`bool`	`True`	Enable/disable the vector retrieval branch
`use_keyword`	`bool`	`True`	Enable/disable the BM25 keyword retrieval branch
`use_metadata`	`bool`	`False`	Enable/disable the metadata-filter retrieval branch (also requires `filters` to be passed at call time)
`metadata_filters`	`Dict[str, str]`	`{}`	Stored but not read by any code path inspected — actual filters are passed per-call to `retrieve(..., filters=...)` instead
`min_vector_score`	`float`	`0.0`	Minimum cosine similarity for a vector hit to be kept

[!WARNING] metadata_filters vs. per-call filters RetrieverConfig.metadata_filters exists as a field but is never referenced by retriever.py, engine.py, or pipeline.py. The filters that actually take effect are the ones passed as the metadata_filters argument to ContextEngine.run(), which flow into HybridRetriever.retrieve(filters=...). Don't rely on the config field.

`FilterConfig`

Field	Type	Default	Purpose
`dedup_method`	`str`	`"hash"`	Documented values: `"hash"`, `"prefix"`, `"semantic"`. Note: `ChunkFilter.filter()` always performs hash-based dedup (`_dedup_hash`) regardless of this value — it is not branched on anywhere in `pipeline.py`. Semantic dedup is available, but only via the separate `filter_with_embeddings()` method, not gated by this field.
`prefix_length`	`int`	`100`	Used only by the legacy `legacy_compat.PrefixDeduplication`, not by `ChunkFilter`
`semantic_sim_threshold`	`float`	`0.92`	Cosine similarity threshold above which two chunks are considered semantic duplicates, used by `ChunkFilter._dedup_semantic` (called from `filter_with_embeddings`)
`min_chunk_length`	`int`	`20`	Chunks shorter than this (characters) are dropped
`max_chunk_length`	`int`	`4000`	Chunks longer than this (characters) are dropped
`noise_patterns`	`List[str]`	3 regexes (blank lines, divider lines, page-number lines, in Arabic and English)	Any chunk whose stripped text fully matches one of these regexes (via `re.match`) is treated as noise and removed

`RankingConfig`

Field	Type	Default	Purpose
`weight_vector_score`	`float`	`0.40`	Weight of vector similarity in `CompositeRanker`'s score
`weight_keyword_score`	`float`	`0.25`	Weight of a keyword-overlap boost (fraction of query keywords found in chunk text)
`weight_source_quality`	`float`	`0.20`	Weight of normalized `SourceQuality` (0–1)
`weight_recency`	`float`	`0.10`	Weight of `ScoredChunk.recency_score` (you must populate this yourself — nothing in the package sets it automatically)
`weight_position`	`float`	`0.05`	Weight of a position score that decays by `0.01` per unit of `retrieval_rank`
`max_chunks_to_rank`	`int`	`15`	Maximum chunks kept after ranking, passed on to the composer

[!NOTE] Weights don't have to sum to 1.0 The implementation never normalizes these weights — it computes a plain weighted sum. If you change weights without checking the total, the resulting composite_score scale will shift accordingly. This mostly matters if you compare scores across different configurations.

`ComposerConfig`

Field	Type	Default	Purpose
`max_context_length`	`int`	`2000`	Default budget (characters) if no per-query budget overrides it
`separator`	`str`	`"\n---\n"`	String inserted between formatted chunks
`template`	`str`	`"arabic"`	One of `"arabic"`, `"english"`, `"minimal"`, `"structured"` — selects a `ContextTemplate` (see `api/pipeline`)
`include_scores`	`bool`	`False`	If `True`, uses the template's `chunk_fmt_score` variant, embedding the composite score in each chunk's header
`include_metadata`	`bool`	`False`	If `True`, appends up to 5 metadata key/value pairs after each chunk
`include_sources`	`bool`	`True`	Stored but not read anywhere in `pipeline` — all four built-in templates always include a source label regardless of this flag
`group_by_source`	`bool`	`False`	If `True`, groups chunks by `.source` before formatting, ordering groups by their best chunk's score
`summarize_long_chunks`	`bool`	`False`	Stored but not implemented anywhere — see Architecture
`min_compression_chars`	`int`	`50`	Stored but not referenced by any code path inspected (note: `legacy_compat.GreedyCompression` has its own separate hardcoded `MIN_CONTENT_LENGTH = 50`, which is not wired to this config field)

`GuardConfig`

Field	Type	Default	Purpose
`enabled`	`bool`	`True`	Master switch; if `False`, `ContextGuard.validate()` always returns `(True, [])` immediately
`min_context_length`	`int`	`10`	Below this many characters, the guard fails (`passed=False`)
`max_context_length`	`int`	`8000`	Above this, the guard adds a warning but does not fail
`check_empty`	`bool`	`True`	If `True` and the context is blank/whitespace-only, the guard fails immediately with `["context is empty ⚠"]`, short-circuiting the remaining checks
`check_relevance`	`bool`	`False`	Requires an `embed_fn` to be passed to `ContextGuard.__init__`; if enabled without one, this check is silently skipped (no error)
`relevance_threshold`	`float`	`0.10`	Minimum cosine similarity between query and context embeddings for the relevance check to pass
`check_source_coverage`	`bool`	`True`	Adds a (non-failing) warning if no `[Source: ...]`/`[المصدر: ...]`-style marker or `---` separator is found in the context

`CacheConfig`

Field	Type	Default	Purpose
`enabled`	`bool`	`True`	If `True`, `ContextEngine` constructs a `ContextCache`; if `False`, caching is skipped entirely (no cache object is created)
`max_size`	`int`	`256`	Maximum number of distinct queries cached (LRU eviction)
`ttl_seconds`	`int`	`300`	Cache entries older than this are treated as a miss and evicted on next access

`LengthCounter`

Not a dataclass — a type alias: LengthCounter = Callable[[str], int]. Used wherever the codebase needs to measure "length" abstractly (characters by default via char_counter, or tokens via make_token_counter).

Configuration Reference

ContextEngineConfig (root)

QueryAnalyzerConfig

RetrieverConfig

FilterConfig

RankingConfig

ComposerConfig

GuardConfig

CacheConfig

LengthCounter

Related pages