Configuration¶

This page is a reference for all tunable parameters. Read the subsystem pages (Agent Loop, Embedding Algebra, Context Composition, Research Engine) first to understand what each parameter controls.

Every numeric threshold lives in a single frozen configuration hierarchy at config/config.py. No module defines its own magic numbers. Runtime overrides use LETHE_* environment variables, and defaults are documented in .env.example. This design --- one file, frozen at startup, validated in __post_init__ --- makes behavior fully auditable and prevents the drift that occurs when thresholds scatter across modules.

Common tuning scenarios:

• Research stops too early --- lower termination_psi_threshold in SearchConfig, or raise budget_alpha to slow pressure
• Context misses relevant evidence --- lower ppr_damping (more exploration) or raise ppr_top_k (more candidates)
• Agent loops too long --- lower budget_iterations or convergence_term_threshold
• Evidence too noisy --- raise similar_to_creation_threshold or semantic_dedup_threshold

The configuration is organized into eleven sub-configs, each governing a distinct subsystem.

flowchart TB
    ROOT["Config"]
    NEO["Neo4jConfig<br/>graph database"]
    EMB_S["EmbedServerConfig<br/>embedding model"]
    LLM_S["LLMServerConfig<br/>reasoning model"]
    SXNG["SearXNGConfig<br/>metasearch"]
    TERM["TerminationConfig<br/>budget + convergence"]
    EMB["EmbedConfig<br/>algebra thresholds"]
    CTX["ContextConfig<br/>PPR + knapsack"]
    THINK["ThinkingBudgetConfig<br/>adaptive reasoning"]
    SEARCH["SearchConfig<br/>research engine"]
    MEDIA["MediaConfig<br/>browser + STT"]
    NLI["NliConfig<br/>DeBERTa NLI"]

    ROOT --> NEO
    ROOT --> EMB_S
    ROOT --> LLM_S
    ROOT --> SXNG
    ROOT --> TERM
    ROOT --> EMB
    ROOT --> CTX
    ROOT --> THINK
    ROOT --> SEARCH
    ROOT --> MEDIA
    ROOT --> NLI

Service Connection¶

Neo4jConfig¶

EmbedServerConfig¶

LLMServerConfig¶

SearXNGConfig¶

Budget and Termination¶

TerminationConfig¶

Controls the smooth budget pressure curve and convergence-based early stopping.

The budget curve \(c(t) = (e^{\alpha t} - 1)/(e^{\alpha} - 1)\) shapes pressure algebraically. With \(\alpha = 4.0\), the system operates at less than 20% pressure through the first half of its budget.

ThinkingBudgetConfig¶

Thinking budget is interpolated between min and max based on novelty, then reduced by budget pressure via BudgetManager.adjust_thinking_budget.

Embedding Algebra¶

EmbedConfig¶

The quantitative control plane (Embedding Algebra). The LLM never sees these values.

Context Composition¶

ContextConfig¶

Web Research Engine¶

SearchConfig¶

Controls the continuous zero-LLM web research pipeline: discover URLs via SearXNG, stream fetch+embed in a sliding window, score pages by goal alignment and novelty, and terminate via spectral convergence.

MediaConfig¶

NliConfig¶

Parameter Interactions¶

Parameters do not operate in isolation. Several groups interact to produce emergent behavior, and adjusting one without understanding its neighbors can produce counterintuitive results.

Termination sensitivity¶

The most common tuning scenario is adjusting how quickly or slowly the agent terminates. Three parameters jointly control this:

• budget_alpha (TerminationConfig) shapes the pressure curve. Higher values delay pressure onset but create a steeper ramp near exhaustion. At \(\alpha = 4.0\) (default), pressure stays below 20% through the first half of the budget.
• convergence_term_threshold (TerminationConfig) is the \(\psi\) gate. At 0.82 (default), termination requires either strong convergence-plateau or heavy resource pressure (LETHE_CONVERGENCE_TERM_THRESHOLD).

These interact multiplicatively through \(\psi\): budget_alpha controls when pressure appears and convergence_term_threshold sets the exit bar. Convergence weights are module-level constants (CONVERGENCE_WEIGHTS for the agent loop, SEARCH_CONVERGENCE_WEIGHTS for research).

Context quality vs. breadth¶

Two parameter groups trade off what evidence the LLM sees each iteration:

• ppr_damping and ppr_top_k (ContextConfig) control exploration scope. Lower damping (\(< 0.85\)) spreads PPR probability more widely, surfacing distant nodes. Higher ppr_top_k admits more candidates to scoring. Both increase breadth.
• scoring_ga_weight (ContextConfig) and adagres_beta_min/max (ContextConfig) control how candidates are scored and deduplicated. Higher GA weight favors goal-relevant content; higher \(\beta\) penalizes redundancy more aggressively. Both increase focus at the expense of breadth.

The entropy-adaptive scoring automatically mediates: when PPR produces a uniform distribution (high entropy — many equally-reachable nodes), the blend shifts toward goal alignment to compensate for PPR's lack of discrimination; when PPR concentrates on a few nodes (low entropy), PPR dominates because its signal is decisive.

Research aggressiveness¶

The research engine has its own budget and termination, independent of the agent loop:

• Research has no hard page budget — termination is driven purely by convergence algebra and time/session pressure.
• max_inflight (SearchConfig) controls parallelism in the sliding window. Higher values increase throughput but waste more compute on early termination.
• termination_psi_threshold (SearchConfig) at 0.7 is intentionally lower than the agent loop's 0.82 --- research terminates faster because each web page is a cheap, independent sample.

The agent loop's budget_alpha and current pressure propagate to the research engine as session_pressure, which increases research's budget pressure. Late-session research terminates faster even if its own page budget is not exhausted.

Evidence quality gates¶

Three thresholds form a pipeline that filters what enters the graph:

• evidence_ga_floor (EmbedConfig, 0.62) --- the soft-gate midpoint for evidence scoring. Chunks with GA well below this receive near-zero strength but are not dropped.
• semantic_dedup_threshold (EmbedConfig, 0.95) --- chunks semantically similar to existing evidence are skipped. Lowering this aggressively deduplicates but risks discarding complementary findings.
• similar_to_creation_threshold (EmbedConfig, 0.55) --- controls the density of the semantic graph. Lower values create more SIMILAR_TO edges, giving PPR more cross-topic paths but risking clique saturation.

These three should move together. If you lower evidence_ga_floor (admitting more evidence), you may want to raise semantic_dedup_threshold to compensate for the increased volume.

Validation¶

All configuration is validated at construction time via __post_init__. Invariants include:

• Convergence weights must have exactly 3 elements summing to 1.0
• Strength floor must be less than ceiling
• Budget alpha must be non-negative
• Thinking budget min must be less than max
• If token budget is set, thinking budget max must be less than it

Invalid configurations raise ValueError at startup, not at runtime.

Not all parameters have environment variable overrides — some module-level constants (like _STABILITY_EMA_ALPHA in embed/signals.py) require editing code directly.