ZerdaZerda

Configuration

On this page

Configuration is driven by two dataclasses, both defined with Python's @dataclass decorator: RAGConfig (pipeline-wide) and RerankerConfig (re-ranking-specific). RAGSystem builds a RerankerConfig internally from the rerank_* fields of RAGConfig — you normally only need to construct RAGConfig.

RAGConfig fields

Chunking

FieldTypeDefaultPurpose
chunk_sizeint512Target size of each text chunk (unit is caller-defined — RAGSystem itself never reads this field directly; it is passed to your chunker only if your chunker reads it from the config you supply).
overlapint128Overlap between consecutive chunks. Must be smaller than chunk_size (enforced by validate()).

Retrieval

FieldTypeDefaultPurpose
top_kint5Default number of chunks returned by retrieve() when no top_k argument is passed.
min_scorefloat0.0Passed to vector_db.search(..., score_threshold=min_score) as the minimum relevance score.

Reranking

FieldTypeDefaultPurpose
enable_rerankingboolFalseWhether RAGSystem constructs a Reranker and applies it after retrieval.
rerank_modestr"heuristic"One of "heuristic", "llm", "hybrid" — converted to a RerankMode enum member internally.
rerank_top_kOptional[int]NoneNumber of results kept after reranking. None means "same as the retrieval top_k".
rerank_original_weightfloat0.40Weight of the original vector-DB score in the composite rerank score.
rerank_llm_weightfloat0.40Weight of the LLM relevance score (only used in llm/hybrid modes; folded into rerank_original_weight automatically in heuristic mode).
rerank_diversity_weightfloat0.10Weight of the diversity/term-overlap bonus.
rerank_length_weightfloat0.10Weight of the "optimal length" bonus.

[!WARNING] Weights must sum to ~1.0 RAGConfig.validate() raises ValueError if rerank_original_weight + rerank_llm_weight + rerank_diversity_weight + rerank_length_weight is outside [0.99, 1.01].

Prompt routing

FieldTypeDefaultPurpose
enable_prompt_routingboolTrueWhether RAGSystem builds a PromptRouter (used only when no custom prompt was passed to RAGSystem).
prompt_languageOptional[str]NoneNot read anywhere in RAGSystem's constructor or methods in the analyzed source — language is instead resolved per-call via the language parameter of generate()/ask(), defaulting to auto-detection. Documented here for completeness; its runtime effect could not be confirmed.
include_few_shotboolTruePassed to PromptRouter(include_few_shot=...) — controls whether few-shot examples are injected into prompts.

Context

FieldTypeDefaultPurpose
context_max_lengthint4000Not read anywhere inside RAGSystem in the analyzed source. It exists for use by a caller-supplied context_manager that chooses to honor it.

Retrieval cache

FieldTypeDefaultPurpose
enable_retrieval_cacheboolTrueWhether RAGSystem constructs a RetrievalCache.
cache_maxsizeint256Max number of distinct (query, top_k) entries kept in the LRU cache.
cache_ttlfloat300.0Seconds before a cached entry expires. If <= 0, RAGSystem passes ttl=None to RetrievalCache (no expiry).

Batch ingestion

FieldTypeDefaultPurpose
ingest_batch_sizeint64Not read anywhere inside RAGSystem.add_documents / aadd_documents in the analyzed source — documented for completeness; no batching behavior driven by this field could be confirmed.

RAGConfig.validate()

Raises ValueError (not a core.exceptions subclass) if:

  • chunk_size <= 0
  • overlap < 0
  • top_k <= 0
  • overlap >= chunk_size
  • rerank_mode not in ("heuristic", "llm", "hybrid")
  • The four rerank_*_weight fields don't sum to ~1.0

BaseRAGSystem.__init__ calls self.config.validate() automatically, so invalid configs fail fast at construction time.

Python · 5 lines
from zerda.rag.core import RAGConfig

cfg = RAGConfig(chunk_size=1000, overlap=1200)  # overlap >= chunk_size
cfg.validate()
# ValueError: ❌ overlap must be smaller than chunk_size

RerankerConfig fields

Constructed internally by RAGSystem from the rerank_* RAGConfig fields, or directly if you use Reranker standalone.

FieldTypeDefaultPurpose
modeRerankModeRerankMode.HEURISTICReranking strategy.
top_kOptional[int]NoneResults kept after reranking.
original_score_weightfloat0.40See above.
llm_score_weightfloat0.40See above.
diversity_weightfloat0.10See above.
length_weightfloat0.10See above.
llm_eval_languagestr"ar"Language of the LLM relevance-scoring prompt: "ar" or "en".
ideal_min_wordsint30Lower bound of the "ideal" chunk length (word count) used for the length bonus.
ideal_max_wordsint300Upper bound of the "ideal" chunk length.
dedup_enabledboolTrueWhether near-duplicate chunks are filtered before scoring.
dedup_thresholdfloat0.85Jaccard similarity (word-set overlap) at/above which two chunks are treated as duplicates.

__post_init__ raises ValueError if the four weight fields don't sum to [0.99, 1.01] — the same check as RAGConfig.validate(), applied automatically at construction time (dataclasses call __post_init__ after __init__).

RerankMode enum

Python · 4 lines
class RerankMode(Enum):
    HEURISTIC = "heuristic"   # fast, no LLM
    LLM       = "llm"         # accurate, uses LLM
    HYBRID    = "hybrid"      # combination

effective_weights(mode)

RerankerConfig.effective_weights(mode) returns a Dict[str, float] with keys orig, llm, len, div. In HEURISTIC mode, llm_score_weight is folded into orig (since there is no LLM call to weight), and llm is returned as 0.0. In LLM/HYBRID mode, weights are returned unchanged. Reranker calls this method internally rather than reading the raw config fields directly — see Reranker internal workflow.

Fast, offline-friendly (default-ish)

Python · 5 lines
RAGConfig(
    enable_reranking=False,
    enable_prompt_routing=True,
    enable_retrieval_cache=True,
)

Highest quality, LLM-heavy

Python · 8 lines
RAGConfig(
    enable_reranking=True,
    rerank_mode="hybrid",
    rerank_original_weight=0.3,
    rerank_llm_weight=0.5,
    rerank_diversity_weight=0.1,
    rerank_length_weight=0.1,
)

No caching (always fresh results — e.g. rapidly changing corpus)

Python
RAGConfig(enable_retrieval_cache=False)

See also: RerankerConfig best practices and RetrievalCache.

Related pages