Configuration

On this page

RouterConfig
Presets
EmbeddingConfig
ScoringConfig
ExecutionConfig
CacheConfig
FeedbackConfig
ObservabilityConfig
Enumerations
SimilarityMetric
ExecutionMode
AggregationStrategy
ConfidenceLevel
LogLevel
Next steps

All configuration lives in router/config as a tree of dataclasses rooted at RouterConfig. Pass a fully or partially customized RouterConfig to HierarchicalRouter(config=...); any sub-config left as default uses the dataclass field defaults shown below.

Python · 7 lines

from zerda.router import RouterConfig, ScoringConfig, ExecutionConfig, ExecutionMode

config = RouterConfig(
    scoring=ScoringConfig(semantic_weight=0.8, keyword_weight=0.2, llm_weight=0.0),
    execution=ExecutionConfig(mode=ExecutionMode.SEQUENTIAL),
)
router = HierarchicalRouter(config=config)

RouterConfig

The single entry point aggregating every sub-config, plus top-level LLM fallback and no-match behavior settings.

Field	Type	Default	Purpose
`embedding`	`EmbeddingConfig`	`EmbeddingConfig()`	Embedding model settings.
`scoring`	`ScoringConfig`	`ScoringConfig()`	Hybrid scorer weights and confidence thresholds.
`execution`	`ExecutionConfig`	`ExecutionConfig()`	How matched routes are executed.
`cache`	`CacheConfig`	`CacheConfig()`	Route-decision cache behavior.
`feedback`	`FeedbackConfig`	`FeedbackConfig()`	Adaptive feedback loop behavior.
`observability`	`ObservabilityConfig`	`ObservabilityConfig()`	Logging, tracing, metrics.
`llm_model`	`Optional[str]`	`None`	Model name/endpoint passed to `LLMScorer`. If unset, no LLM fallback scorer is built.
`llm_api_key`	`Optional[str]`	`None`	API key passed to `LLMScorer`'s `openai.OpenAI` client.
`raise_on_no_match`	`bool`	`False`	If `True`, `route_query` raises `LookupError` when no route matches (and no fallback handler is set). If `False`, returns a failed `RoutingResult` instead.

Presets

Two classmethods construct commonly-used configurations:

RouterConfig.fast() — optimized for latency: scoring.top_k = 1, execution.mode = ExecutionMode.SINGLE, cache.enabled = True.

RouterConfig.accurate() — optimized for accuracy: scoring.top_k = 3, execution.mode = ExecutionMode.PARALLEL, scoring.llm_weight = 0.20, scoring.semantic_weight = 0.60.

Python

router = HierarchicalRouter(config=RouterConfig.fast())

EmbeddingConfig

Controls the embedding model used for semantic scoring.

Field	Type	Default	Purpose
`model_name`	`str`	`"sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"`	Model name passed to `SentenceTransformer(...)`.
`batch_size`	`int`	`32`	Batch size used in `encode_batch`.
`cache_embeddings`	`bool`	`True`	Documented as controlling embedding caching; the flag is a declared field, but `EmbeddingProvider`'s actual `use_cache` parameter defaults independently per-call (`encode`/`encode_batch` default `use_cache=True`) rather than reading this field directly — verify against your version if you depend on this being wired through.
`normalize_embeddings`	`bool`	`True`	Documented as controlling L2 normalization; `EmbeddingProvider.encode` calls `self._model.encode(..., normalize_embeddings=True)` unconditionally rather than referencing this field — same caveat as above.

[!WARNING] Fields not directly read Static analysis of routing/pipeline.py shows EmbeddingProvider hard-codes normalize_embeddings=True in its calls to SentenceTransformer.encode, rather than consulting EmbeddingConfig.normalize_embeddings. Likewise, cache usage defaults are controlled by each method's own use_cache parameter, not read from EmbeddingConfig.cache_embeddings. These fields exist on the dataclass but are not observed to be consumed by EmbeddingProvider in the analyzed source — documented here explicitly rather than assumed to work, per this documentation's no-hallucination policy.

ScoringConfig

Weights and thresholds for the hybrid scorer.

Field	Type	Default	Purpose
`semantic_weight`	`float`	`0.70`	Relative weight of embedding similarity.
`keyword_weight`	`float`	`0.20`	Relative weight of keyword signals.
`llm_weight`	`float`	`0.10`	Relative weight of the optional LLM scorer (only applied if `RouterConfig.llm_model` is set).
`similarity_metric`	`SimilarityMetric`	`COSINE`	Which similarity function `SemanticScorer` uses.
`high_confidence_threshold`	`float`	`0.85`	Combined score at/above which confidence is `HIGH`.
`medium_confidence_threshold`	`float`	`0.60`	Combined score at/above which confidence is `MEDIUM`.
`fallback_confidence_threshold`	`float`	`0.40`	Combined score at/above which confidence is `LOW`; below this it's `NONE`, and it's also the trigger point for invoking the LLM scorer.
`top_k`	`int`	`5`	Number of candidate routes surfaced by the pipeline (post-scoring).

The three weight fields are normalized to sum to 1 inside HybridScorer.__init__ — you don't need to make them sum to 1 yourself, but their ratios to each other determine relative influence.

ExecutionConfig

Controls how matched routes are executed.

Field	Type	Default	Purpose
`mode`	`ExecutionMode`	`SINGLE`	`SINGLE`, `SEQUENTIAL`, or `PARALLEL`.
`aggregation`	`AggregationStrategy`	`FIRST_WINS`	Used to select the aggregator (`FirstWinsAggregator` vs `MergeAggregator`) when `HierarchicalRouter` is constructed. Only `"merge"` maps to `MergeAggregator`; any other value (including `VOTING`) falls back to `FirstWinsAggregator` in the analyzed source — there is no dedicated voting-aggregator implementation.
`parallel_timeout`	`float`	`10.0`	Seconds before parallel execution (`ThreadPoolExecutor.as_completed` / `asyncio.wait_for`) times out.
`max_retries`	`int`	`2`	Max attempts per handler call (`_with_retry`).
`retry_delay`	`float`	`0.5`	Seconds slept between retry attempts.
`retry_on_exceptions`	`List[str]`	`["RuntimeError", "TimeoutError"]`	Substrings checked against `HandlerResponse.error`; a retry only proceeds if one of these substrings appears in the error message (see `_with_retry`).

[!WARNING] AggregationStrategy.VOTING is declared but not implemented AggregationStrategy.VOTING = "voting" exists as an enum value, but HierarchicalRouter.__init__'s aggregator-selection logic only checks self._cfg.execution.aggregation.value == "merge"; any other value (including "voting") results in FirstWinsAggregator being used. No VotingAggregator class exists in the analyzed source.

CacheConfig

Controls the route-decision cache (CacheManager).

Field	Type	Default	Purpose
`enabled`	`bool`	`True`	Master on/off switch for `CacheManager.get_decision` / `set_decision`.
`ttl_seconds`	`int`	`300`	Time-to-live for cached route decisions.
`max_size`	`int`	`1000`	Max entries before LRU eviction.
`embedding_cache`	`bool`	`True`	Declared field for enabling the embedding cache; note the embedding cache in `EmbeddingProvider` is a separate, always-on dict cache not observed to read this flag directly — see the `EmbeddingConfig` warning above for the same caveat pattern.
`embedding_ttl`	`int`	`3600`	Declared TTL for embedding cache entries; `EmbeddingProvider`'s internal cache dict has no TTL/eviction logic in the analyzed source (it is only cleared in full via `clear_cache()`), so this field's effect could not be confirmed from the implementation.

FeedbackConfig

Controls the adaptive feedback loop (FeedbackEngine).

Field	Type	Default	Purpose
`enabled`	`bool`	`True`	Master on/off switch — `record()` and `apply_biases()` both no-op when `False`.
`score_decay`	`float`	`0.05`	Declared field described as controlling per-tick score shift; `FeedbackEngine` uses a separate `alpha` constructor parameter (default `0.1`) for its EMA update rather than reading `score_decay` — not observed to be consumed in the analyzed source.
`min_samples_to_adapt`	`int`	`10`	Minimum `n_samples` a route needs before `apply_biases` will update its `score_bias`.
`persist_path`	`Optional[str]`	`None`	JSON file path for `FeedbackEngine.save()` / auto-load on construction, and for `HierarchicalRouter.__exit__`'s auto-save.

ObservabilityConfig

Controls logging, tracing, and metrics.

Field	Type	Default	Purpose
`log_level`	`LogLevel`	`INFO`	Passed to `logging.getLogger(...).setLevel(...)` in `RouterLogger`.
`structured_logging`	`bool`	`True`	If `True`, log lines are emitted as single-line JSON via `_JsonFormatter`; otherwise a standard human-readable formatter is used.
`enable_tracing`	`bool`	`True`	Declared field; `RoutingTrace` objects are constructed and populated unconditionally by `RoutingPipeline.run` in the analyzed source — this flag was not observed to gate trace construction.
`metrics_window`	`int`	`1000`	Max length of the rolling-window deques in `MetricsCollector` (latencies, confidences, matches) and the cap applied to per-route latency lists.
`slow_route_ms`	`float`	`500.0`	Threshold above which `RouterLogger.log_routing_decision` emits a `slow_route_detected` warning.

Enumerations

SimilarityMetric

Value	Meaning
`COSINE`	Cosine similarity (`SemanticScorer._cosine`).
`DOT_PRODUCT`	Raw dot product — assumes inputs are already L2-normalized (`SemanticScorer._dot_product`).
`EUCLIDEAN`	Euclidean distance converted to a similarity via `1 / (1 + distance)` (`SemanticScorer._euclidean_to_similarity`).

ExecutionMode

Value	Meaning
`SINGLE`	Execute only the best-ranked candidate.
`SEQUENTIAL`	Try candidates in ranked order, stop at first success.
`PARALLEL`	Execute all candidates concurrently, then aggregate.

AggregationStrategy

Value	Meaning
`FIRST_WINS`	Return the first successful response (default; also the fallback for any unrecognized value).
`VOTING`	Declared but not implemented as a distinct aggregator — see the warning under `ExecutionConfig` above.
`MERGE`	Merge all successful responses' `content` into a list (`MergeAggregator`).

ConfidenceLevel

Value	Meaning
`HIGH`	Score ≥ `high_confidence_threshold` — route directly.
`MEDIUM`	Score ≥ `medium_confidence_threshold` — route, typically with a note.
`LOW`	Score ≥ `fallback_confidence_threshold` — route via LLM fallback territory.
`NONE`	Below all thresholds — global fallback / no-match path.

LogLevel

DEBUG, INFO, WARNING, ERROR — maps 1:1 to Python's logging level names via getattr(logging, cfg.log_level.value, logging.INFO).

Next steps

See Advanced Usage for streaming, tool chaining, and feedback-tuning walkthroughs, or the API Reference for exhaustive per-class documentation.