RAGConfig, RerankerConfig, RerankMode

core.rag_config.RAGConfig, core.rag_config.RerankerConfig, core.rag_config.RerankMode

Overview

This module defines the two configuration dataclasses and one enum that control every tunable aspect of the pipeline. See the Configuration guide for a field-by-field reference table with defaults and recommended presets — this page focuses on the exact API surface (signatures, validation behavior, methods).

RAGConfig

Exact signature

@dataclass
class RAGConfig:
    chunk_size: int = 512
    overlap: int = 128
    top_k: int = 5
    min_score: float = 0.0
    enable_reranking: bool = False
    rerank_mode: str = "heuristic"
    rerank_top_k: Optional[int] = None
    rerank_original_weight: float = 0.40
    rerank_llm_weight: float = 0.40
    rerank_diversity_weight: float = 0.10
    rerank_length_weight: float = 0.10
    enable_prompt_routing: bool = True
    prompt_language: Optional[str] = None
    include_few_shot: bool = True
    context_max_length: int = 4000
    enable_retrieval_cache: bool = True
    cache_maxsize: int = 256
    cache_ttl: float = 300.0
    ingest_batch_size: int = 64

Being a plain @dataclass (no __post_init__), invalid values are not caught at construction time — you must call validate() explicitly, or rely on BaseRAGSystem.__init__/RAGSystem.__init__ doing it for you.

validate()

def validate(self) -> None

Algorithm

Checks, in order (first failure raises immediately):

1. chunk_size <= 0 → ValueError("❌ chunk_size must be positive")
2. overlap < 0 → ValueError("❌ overlap cannot be negative")
3. top_k <= 0 → ValueError("❌top_k must be positive") (note: no space after ❌ in this particular message, as in source)
4. overlap >= chunk_size → ValueError("❌ overlap must be smaller than chunk_size")
5. rerank_mode not in ("heuristic", "llm", "hybrid") → ValueError("❌ rerank_mode must be 'heuristic' or 'llm' or 'hybrid'")
6. Sum of the four rerank_*_weight fields outside [0.99, 1.01] → ValueError(f"❌ Rerank weights must sum to 1.0 (got {weights:.2f})")

Raises

ValueError — see conditions above. Not a core.exceptions.FennecError subclass.

Returns

None — mutates nothing; purely a validation gate.

Examples

Basic (valid config):

from core import RAGConfig
cfg = RAGConfig()
cfg.validate()   # no exception

Invalid overlap:

cfg = RAGConfig(chunk_size=100, overlap=150)
cfg.validate()
# ValueError: ❌ overlap must be smaller than chunk_size

Invalid rerank mode string:

cfg = RAGConfig(rerank_mode="fuzzy")
cfg.validate()
# ValueError: ❌ rerank_mode must be 'heuristic' or 'llm' or 'hybrid'

Invalid weight sum:

cfg = RAGConfig(rerank_original_weight=0.9, rerank_llm_weight=0.5)
cfg.validate()
# ValueError: ❌ Rerank weights must sum to 1.0 (got 1.60)

Production usage — validating user-supplied overrides before constructing a RAGSystem:

cfg = RAGConfig(**user_supplied_overrides)
try:
    cfg.validate()
except ValueError as e:
    raise SystemExit(f"Invalid RAG configuration: {e}")

RerankMode

class RerankMode(Enum):
    HEURISTIC = "heuristic"
    LLM       = "llm"
    HYBRID    = "hybrid"

A plain string-valued Enum (not str, Enum), so RerankMode.HEURISTIC == "heuristic" is False — comparisons must use RerankMode.HEURISTIC.value == "heuristic" or RerankMode("heuristic") == RerankMode.HEURISTIC.

RerankerConfig

Exact signature

@dataclass
class RerankerConfig:
    mode: RerankMode = RerankMode.HEURISTIC
    top_k: Optional[int] = None
    original_score_weight: float = 0.40
    llm_score_weight: float = 0.40
    diversity_weight: float = 0.10
    length_weight: float = 0.10
    llm_eval_language: str = "ar"
    ideal_min_words: int = 30
    ideal_max_words: int = 300
    dedup_enabled: bool = True
    dedup_threshold: float = 0.85

    def __post_init__(self) -> None: ...
    def effective_weights(self, mode: RerankMode) -> Dict[str, float]: ...

__post_init__

Runs automatically after every construction (standard dataclass behavior). Sums the four weight fields and raises ValueError(f"❌ Weights must sum to 1.0 (got {total:.3f})") if outside [0.99, 1.01]. Unlike RAGConfig, this validation happens automatically — you never need to call it manually.

Raises

ValueError — weight sum out of range.

effective_weights

def effective_weights(self, mode: RerankMode) -> Dict[str, float]

Returns mode-adjusted, normalized weights as a Dict[str, float] with keys orig, llm, len, div.

Algorithm

• If mode == RerankMode.HEURISTIC: orig = original_score_weight + llm_score_weight (the LLM weight is folded in since heuristic mode makes no LLM calls), llm = 0.0, len = length_weight, div = diversity_weight.
• Otherwise (LLM or HYBRID): returns the four weights unchanged, keyed as orig/llm/len/div.

Returns

Dict[str, float] with exactly the keys orig, llm, len, div.

Examples

Basic:

from zerda.rag.core import RerankerConfig, RerankMode

rc = RerankerConfig()
print(rc.effective_weights(RerankMode.HEURISTIC))
# {'orig': 0.8, 'llm': 0.0, 'len': 0.1, 'div': 0.1}

print(rc.effective_weights(RerankMode.LLM))
# {'orig': 0.4, 'llm': 0.4, 'len': 0.1, 'div': 0.1}

Custom weighting for hybrid mode:

rc = RerankerConfig(
    mode=RerankMode.HYBRID,
    original_score_weight=0.25,
    llm_score_weight=0.55,
    diversity_weight=0.10,
    length_weight=0.10,
)
print(rc.effective_weights(RerankMode.HYBRID))
# {'orig': 0.25, 'llm': 0.55, 'len': 0.1, 'div': 0.1}

Error — weights don't sum to 1.0:

RerankerConfig(original_score_weight=0.5, llm_score_weight=0.5,
               diversity_weight=0.2, length_weight=0.2)
# ValueError: ❌ Weights must sum to 1.0 (got 1.400)

Thread safety

Both dataclasses are plain data containers with no locking; treat instances as effectively immutable once constructed and validated, especially if shared across threads.

Related APIs

• Configuration guide — full field reference and recommended presets.
• Reranker — the consumer of RerankerConfig and effective_weights().
• RAGSystem — constructs a RerankerConfig from RAGConfig's rerank_* fields.