ZerdaZerda

config module

On this page

Overview

Defines a tree of @dataclass-decorated configuration objects, all wrapped under one root: ContextEngineConfig. None of these classes have any methods beyond what @dataclass generates automatically, except ContextEngineConfig, which adds three convenience properties for backward compatibility.

LengthCounter

Python
LengthCounter = Callable[[str], int]

A type alias, not a class. Any function matching this signature (e.g. char_counter or the output of make_token_counter) can be passed wherever a LengthCounter is expected.

QueryAnalyzerConfig

Python · 7 lines
@dataclass
class QueryAnalyzerConfig:
    budget_low:    int = 800
    budget_medium: int = 2000
    budget_high:   int = 4000
    custom_entities: List[str] = field(default_factory=list)
    arabic_threshold: float = 0.3

No validation is performed on construction — e.g., setting budget_low > budget_high is allowed and will silently produce confusing budget assignments.

RetrieverConfig

Python · 11 lines
@dataclass
class RetrieverConfig:
    top_k:                int   = 20
    vector_weight:        float = 0.60
    keyword_weight:       float = 0.30
    metadata_weight:      float = 0.10
    use_vector:           bool  = True
    use_keyword:          bool  = True
    use_metadata:         bool  = False
    metadata_filters:     Dict[str, str] = field(default_factory=dict)
    min_vector_score:     float = 0.0

FilterConfig

Python · 12 lines
@dataclass
class FilterConfig:
    dedup_method:         str   = "hash"
    prefix_length:        int   = 100
    semantic_sim_threshold: float = 0.92
    min_chunk_length:     int   = 20
    max_chunk_length:     int   = 4000
    noise_patterns:       List[str] = field(default_factory=lambda: [
        r"^\s*$",
        r"^[\.\-\_\*]{5,}$",
        r"^\s*(page|صفحة)\s*\d+\s*$",
    ])

noise_patterns are matched with re.match (anchored at the start) in ChunkFilter, against the stripped chunk text. Patterns are compiled once at ChunkFilter.__init__ time.

RankingConfig

Python · 8 lines
@dataclass
class RankingConfig:
    weight_vector_score:   float = 0.40
    weight_keyword_score:  float = 0.25
    weight_source_quality: float = 0.20
    weight_recency:        float = 0.10
    weight_position:       float = 0.05
    max_chunks_to_rank:    int   = 15

ComposerConfig

Python · 11 lines
@dataclass
class ComposerConfig:
    max_context_length:   int   = 2000
    separator:            str   = "\n---\n"
    template:             str   = "arabic"
    include_scores:       bool  = False
    include_metadata:     bool  = False
    include_sources:      bool  = True
    group_by_source:      bool  = False
    summarize_long_chunks: bool = False
    min_compression_chars: int  = 50

Valid template values accepted by SmartContextComposer: "arabic", "english", "minimal", "structured". Passing any other string does not raise — SmartContextComposer.__init__ falls back to "arabic" via _TEMPLATES.get(self.cfg.template, _TEMPLATES["arabic"]).

GuardConfig

Python · 9 lines
@dataclass
class GuardConfig:
    enabled:                  bool  = True
    min_context_length:       int   = 10
    max_context_length:       int   = 8000
    check_empty:              bool  = True
    check_relevance:          bool  = False
    relevance_threshold:      float = 0.10
    check_source_coverage:    bool  = True

CacheConfig

Python · 5 lines
@dataclass
class CacheConfig:
    enabled:      bool = True
    max_size:     int  = 256
    ttl_seconds:  int  = 300

ContextEngineConfig

Python · 12 lines
@dataclass
class ContextEngineConfig:
    query_analyzer: QueryAnalyzerConfig = field(default_factory=QueryAnalyzerConfig)
    retriever:      RetrieverConfig     = field(default_factory=RetrieverConfig)
    filter_cfg:     FilterConfig        = field(default_factory=FilterConfig)
    ranking:        RankingConfig       = field(default_factory=RankingConfig)
    composer:       ComposerConfig      = field(default_factory=ComposerConfig)
    guard:          GuardConfig         = field(default_factory=GuardConfig)
    cache:          CacheConfig         = field(default_factory=CacheConfig)
    language:       str  = "auto"
    enable_adaptive: bool = True
    multi_turn:      bool = True

Properties

max_context_length

Python · 4 lines
@property
def max_context_length(self) -> int: ...
@max_context_length.setter
def max_context_length(self, v: int): ...

Proxies directly to self.composer.max_context_length. Reading or writing config.max_context_length is exactly equivalent to config.composer.max_context_length.

separator (read-only)

Python · 2 lines
@property
def separator(self) -> str: ...

Proxies to self.composer.separator. There is no setter — attempting config.separator = "..." raises AttributeError: can't set attribute.

template (read-only)

Python · 2 lines
@property
def template(self) -> str: ...

Proxies to self.composer.template. Also has no setter.

ContextConfig

Python
ContextConfig = ContextEngineConfig

A plain assignment, not a subclass. ContextConfig is ContextEngineConfig evaluates to True. Both names construct identical objects.

Examples

Basic — defaults:

Python · 2 lines
from zerda.context import ContextEngineConfig
cfg = ContextEngineConfig()

Intermediate — nested overrides:

Python · 4 lines
cfg = ContextEngineConfig()
cfg.retriever.top_k = 50
cfg.guard.check_relevance = True
cfg.composer.template = "structured"

Advanced — fully custom construction:

Python · 8 lines
from zerda.context import (
    ContextEngineConfig, RetrieverConfig, ComposerConfig, GuardConfig,
)
cfg = ContextEngineConfig(
    retriever = RetrieverConfig(top_k=30, use_metadata=True),
    composer  = ComposerConfig(template="english", include_scores=True),
    guard     = GuardConfig(max_context_length=12000),
)

Error handling — read-only property:

Python · 5 lines
cfg = ContextEngineConfig()
try:
    cfg.template = "minimal"   # raises AttributeError — use cfg.composer.template instead
except AttributeError as e:
    print(e)

Production usage — via legacy proxy property:

Python · 3 lines
cfg = ContextEngineConfig()
cfg.max_context_length = 6000   # equivalent to cfg.composer.max_context_length = 6000
assert cfg.composer.max_context_length == 6000

← Back to API overview

Related pages