Parameter Glossary

Logical repository identifier used to scope indexing, retrieval, and tool routing. In multi-repo setups this is the namespace key that keeps embeddings, sparse indexes, and metadata partitions separated so queries do not leak across projects. Keep this value stable and aligned with your repository registry (repos.json or equivalent), because mismatched names can produce empty retrievals or cross-repo contamination. Use deterministic naming conventions when onboarding new repositories.

Shows the complete container inventory on the host, not just running containers, and is the baseline view for operational triage. Including exited and paused containers is important for RAG stacks because indexing, ETL, and monitoring jobs often run intermittently and leave failure signals only in stopped containers. This view supports lifecycle actions and log inspection across the entire service graph, making it easier to diagnose dependency failures and startup order issues. Regular review also helps prevent resource waste from abandoned containers.

Maximum wait time for start, stop, or restart operations before the control layer marks the action as timed out. This setting protects UI/API responsiveness when containers hang during bootstrap, health checks, or shutdown hooks. If set too low, normal slow starts appear as failures; if set too high, real faults surface too late and block automation. Choose a value slightly above observed p95 action latency for your heaviest service profile and revisit after infrastructure changes.

Upper bound for how long the system waits when requesting container listings from the Docker API. This mainly protects control-plane responsiveness in environments with many containers, remote contexts, or overloaded Docker daemons. Higher values reduce false timeout errors during heavy load, while lower values fail fast and keep UIs responsive when the daemon is unhealthy. Tune it from observed list latency, not guesswork, and monitor for growth as your service count increases.

Groups Docker operational controls such as startup and shutdown waits plus logging defaults. These settings act as reliability levers for the full RAG system, influencing failure-detection speed, incident observability, and safe handling of stateful services. Conservative values reduce false positives but can hide hangs; aggressive values fail fast but add noise on slower hosts. Recalibrate after hardware changes or when adding new infrastructure components.

Represents whether the app can currently communicate with the Docker daemon. Healthy status is a prerequisite for lifecycle actions such as starting retrieval dependencies, reading logs, and running local eval loops. Flapping status often indicates daemon overload, socket permission issues, or host runtime instability rather than app-level logic errors. Treat this as a hard preflight signal before expensive indexing jobs.

Sets the maximum time allowed for each Docker status probe. Low values surface daemon failures quickly but can create false negatives under CPU, disk, or socket contention; high values reduce noise but delay detection of real outages. In retrieval pipelines this directly affects whether preflight checks pass before ingestion and evaluation tasks begin. Choose a value slightly above observed probe latency at peak local load.

Adds timestamps to container output so events can be correlated across services in a single RAG request path. This is critical when tracing latency between ingestion, embedding calls, vector writes, and generation. Without timestamps, parallel service events are easy to misorder and root-cause analysis takes longer. Keep timestamps enabled for shared and production-like environments, and normalize timezone handling in downstream log tools.

Controls how long the orchestrator waits for compose shutdown to complete before treating stop as failed. In RAG stacks this protects stateful services such as Postgres and vector stores, which need time to flush write-ahead logs and close files cleanly. If set too low, forced termination can leave partial writes, slower recovery, or integrity checks on restart; if set too high, rollback and local iteration become sluggish. Tune this from measured shutdown duration under heavy ingest and keep headroom for worst-case disk latency.

Defined set of infrastructure containers that provide the core substrate for retrieval and operations: vector-capable storage, graph reasoning storage, metrics, logs, and alerting. Treat this as a dependency graph rather than a flat list, because failures in observability services can hide problems in retrieval services and vice versa. Healthy operation requires both data-plane services (for query/index workloads) and control-plane services (for telemetry and incident response). Managing this group consistently is essential for predictable RAG behavior in production.

Defines the maximum wait for infrastructure startup readiness. During first boot or after image updates, pulls, migrations, and service warm-up can dominate startup time in a RAG environment. If the timeout is too short, healthy services may be marked failed before they pass health checks; if too long, real boot failures surface late and slow feedback loops. Set this from observed cold-start timings and revisit it when adding heavy dependencies such as observability or graph services.

Caps how many repository-specific keywords are retained for routing and scoring. The cap controls a core tradeoff: higher values increase topical coverage for broad repositories, while lower values reduce memory, indexing overhead, and ranking noise from generic terms. In multi-repo RAG, this directly affects router entropy and can change which repos are considered candidates for a query. Tune by repository size and lexical diversity, then verify with routing confusion metrics. If you observe cross-repo false positives, reducing this cap is often more effective than simply raising keyword boost.

JSON mapping of intent classes to architecture-layer boosts applied during ranking (for example, giving UI queries a slight preference toward frontend paths). These values should act as soft priors, not hard filters: start small, measure retrieval quality on a fixed evaluation set, then adjust incrementally. Oversized bonuses can dominate semantic evidence and break cross-layer questions (for example, UI symptoms caused by backend schema changes). Keep boosts interpretable, version them with config changes, and retune after major repo reorganizations.

Sets how many trailing log lines are fetched per container when debugging retrieval workflows. Smaller tails keep UI and CLI feedback fast for routine checks, while larger tails help reconstruct multi-step failures across chunking, embedding, indexing, and query handling. Extremely large tails increase I/O and can bury the newest signal in historical noise. Use a conservative default and temporarily raise the value during incident analysis.

Credential used to authenticate requests to the MCP HTTP endpoint. Treat this as a production secret: store it in environment configuration, transmit it through the Authorization header, and rotate it regularly. If this key is unset while the endpoint is exposed beyond localhost, any client that can reach the server may be able to enumerate tools or execute calls. Pair API-key checks with network controls (bind host, reverse proxy, TLS termination) and explicit 401/403 behavior so failures are observable and do not silently fall back to anonymous access.

This override applies to MCP tool-invocation paths, where requests are structured and often latency-sensitive. A lighter model can be sufficient for tool selection and argument construction, reducing spend without degrading end-to-end quality. Prioritize schema adherence and tool-call reliability over open-ended generation fluency in this channel. Validate with tool-call success rate, argument validity, and recovery behavior after tool errors. If tool use regresses while chat quality remains stable, this override is the first place to inspect.

Network interface address used by the MCP HTTP server process. Use `127.0.0.1` for local-only development, `0.0.0.0` only when you intentionally accept remote traffic, and a specific private IP when binding to one interface behind a proxy. This setting controls reachability and blast radius more than performance. A common hardening pattern is localhost bind plus reverse proxy ingress, so authentication, TLS, and request limits are enforced at the edge while the MCP process remains private.

Path segment for the MCP HTTP endpoint (for example `/mcp`). Clients, gateways, and reverse proxies must agree on this route exactly; mismatches are a common cause of silent connection failures where the server is up but tools are never discovered. Use a stable, version-aware path when multiple environments or gateway rules coexist (for example `/v1/mcp`). If you rewrite paths at the proxy layer, test both health checks and tool invocation end-to-end to ensure the canonical route still maps correctly.

TCP port the MCP HTTP server listens on. Choose a non-privileged port (typically above 1024), avoid collisions with existing services, and keep dev/staging/prod conventions consistent so client configs remain portable. Port selection is operationally important for firewalls, container mappings, and service discovery. When fronted by a reverse proxy, the internal port can stay private while external traffic arrives on standard TLS ports; in that setup, verify that health checks and MCP requests are routed to the intended backend port.

Canonical endpoint URL that clients use to reach the MCP server, including scheme, host, optional port, and path. This should represent the externally reachable address, not necessarily the local bind address. In proxy deployments, the correct value is often the public HTTPS URL while the service itself listens on internal HTTP. Keep this value environment-specific and explicit, because incorrect scheme, path, or host settings can look like protocol errors even when the server is healthy.

Displays available Model Context Protocol transport paths (for example stdio and HTTP) that external clients can use to call tools. This status is operationally important because transport availability directly affects agent connectivity, tool latency, and failure modes. A service can look healthy while MCP ingress is degraded, so this row helps isolate protocol-level outages from model/runtime issues. Track it with auth and request telemetry to detect broken integrations early, especially when multiple clients share one tool server.

Comma-separated path fragments that apply ranking lift when matched by candidate file paths. Use this to favor high-signal code zones (such as src/, app/, services/) and de-emphasize noisy regions (generated assets, fixtures, vendored code) without excluding them entirely. Keep boost effects moderate and evaluate on held-out queries so path heuristics complement semantic retrieval instead of overriding it. Revisit boosts whenever folder structure changes, otherwise ranking quality can drift over time.

Enables repository-specific indexing overrides instead of forcing one global chunking/tokenization profile across all codebases. This matters in multi-repo environments because docs-heavy repos, polyglot monorepos, and tight service repos have different optimal settings for chunk size, overlap, tokenizer mode, and metadata extraction. Treat per-repo indexing like a policy layer: keep a safe global default, then introduce targeted overrides where measured retrieval metrics justify deviation. The main operational risk is configuration drift, so changes should be versioned, reviewed, and validated with repo-scoped eval suites before rollout.

Base endpoint for your Qdrant cluster, used by the retriever for collection management, upserts, and nearest-neighbor search queries. Correct URL and protocol selection (HTTP vs HTTPS, auth headers, cloud endpoint shape) is critical because retrieval latency and availability depend directly on this connection path. When running hybrid search, failures here can silently degrade system behavior to sparse-only retrieval unless you monitor fallback paths explicitly. Treat this as an infrastructure dependency: verify connectivity, TLS, and collection schema compatibility during startup and after deploys.

Connection URI for Redis, used by checkpointing/session persistence layers (for example LangGraph state) and other short-latency shared state. The URL encodes host, port, optional credentials, and database index, so misconfiguration can cause silent state divergence across environments. In production, use TLS-enabled endpoints, explicit auth, and per-environment DB isolation. If Redis is unavailable and your app supports stateless fallback, expect reduced resumability and weaker multi-step continuity.

Filesystem path to the active repository root used by local indexers, parsers, and file-system-backed tools. This should resolve to a real, readable directory containing the source tree expected by your retrieval/index pipelines. Relative-path ambiguity is a common failure mode in CI and containerized jobs, so prefer explicit absolute paths and startup validation (exists, is_dir, permission checks). Keep this synchronized with REPO and any root overrides to avoid indexing one project while querying another.

Comma-separated routing hints used before full retrieval to decide which repository should get additional candidate budget. Treat these as high-signal domain anchors (product names, subsystem terms, protocol vocabulary), not generic words, because broad keywords inflate false-positive routing and raise latency. In practice, keep the list compact, inspect query logs regularly, and update when repository boundaries or naming conventions change. Good keyword curation improves first-pass corpus selection and reduces wasted retrieval work in multi-repo deployments.

Absolute filesystem root for this logical repository corpus. The indexer resolves discovery, chunking, and file identity relative to this path, so a wrong root silently drops relevant files or ingests unrelated directories. Use canonical stable paths (avoid transient mounts/symlink ambiguity), and keep corpus boundaries intentional so reindexing stays deterministic over time. When onboarding new repos, verify path coverage with a dry-run file inventory before first production indexing.

Explicit override for repository root detection. Use this when automatic root discovery (walking upward for .git, pyproject.toml, etc.) is unreliable, such as nested workspaces, bind-mounted containers, or unusual mono-repo layouts. Setting a fixed root reduces ambiguity in path resolution and prevents accidental indexing of parent directories. The override should point to the canonical project root shared by both index-time and query-time components.

ANTHROPIC_API_KEY is the credential used to authenticate calls to Claude models when your stack routes generation or evaluation through Anthropic. Treat it as a high-sensitivity secret: keep it in server-side environment management, never expose it in browser bundles, and rotate it quickly after suspected leakage. In multi-provider RAG systems, isolate provider keys so usage attribution, cost controls, and incident response remain auditable per vendor. The key only grants access; model behavior and spend still depend on explicit model choice, token budgets, and request-level safety settings.

Automatically derives and applies embedding dimension from the selected model metadata. This prevents a frequent failure mode where generated vectors and index schema use different sizes, which causes insert errors or invalid retrieval behavior. The safeguard is especially important when switching providers or testing multiple embedding models in one environment. Keep model catalog metadata current so automatic dimension mapping remains trustworthy.

This override applies a different model only for chat UX, letting you optimize interactivity without changing global generation defaults. A common pattern is faster chat responses for iteration while retaining a stronger model for offline or API workflows. Keep prompts and guardrails aligned across channels to avoid unexplained behavioral drift. Capture active channel model in telemetry so user feedback can be mapped to the correct configuration. If chat answers differ from API answers, check this override before changing retrieval or prompting.

This override selects a model specifically for CLI sessions, which are usually iterative and speed-sensitive. Using a smaller or local model here can improve developer feedback loops while keeping production channels on a higher-capability model. Keep retrieval stack and system prompts aligned across channels so CLI debugging reflects real behavior. Log the active CLI model in run metadata to make test results reproducible. Use this for workflow optimization, not as an untracked fork of application behavior.

Specifies the provider model ID used for cloud reranking, such as a Cohere, Voyage, or Jina reranker family variant. This parameter directly controls tradeoffs between multilingual support, context length handling, pricing, and latency. Model IDs are provider-scoped, so the same string is not portable across providers; keep explicit provider-model pairing in configuration and tests. When changing models, re-baseline ranking metrics and failure behavior because score distributions and calibration can shift materially even when APIs look identical.

Credential used to authorize requests to Cohere services when reranking is delegated to Cohere. Operationally, this key controls access, billing attribution, and rate-limit scope, so treat it as a secret and load it from secure environment configuration rather than source code. If missing or invalid, rerank calls fail and your retrieval stack may silently degrade to unre-ranked ordering depending on fallback behavior. In production, pair this setting with key rotation policy, request logging, and explicit health checks on the rerank path.

Per-minute call-rate guardrail for Cohere reranking. This threshold is mainly a cost and stability control: rerankers are high-value but can become the most expensive or latency-sensitive part of the retrieval pipeline if invoked on every request and every rewrite iteration. Alerts at this layer help detect loops, duplicated calls, and missing cache reuse before bills spike or tail latency grows. Tune the limit against expected traffic, candidate set size, and cache hit rate, then review it after any retrieval strategy changes.

Model identifier used for Cohere reranking, determining ranking quality, latency, context limits, and price profile. Different rerank models can reorder the same candidate set very differently, so this setting directly affects answer precision even when retrieval inputs are unchanged. Keep model choice explicit and version-aware, and validate on representative queries whenever you switch models. In production pipelines, model changes should be treated like relevance changes and rolled out with A/B or offline evaluation rather than ad hoc edits.

Controls whether each chunk is embedded independently or with neighboring document context. Contextual strategies reduce ambiguity for short or repetitive chunks and can improve recall on long-form technical questions, but they increase token usage and indexing latency. Late chunking variants further improve semantic continuity by encoding wider spans before chunk-level pooling, at higher memory cost. Choose mode using retrieval metrics from your own corpus rather than generic defaults.

CHAT_DEFAULT_MODEL sets the model used when a chat request does not specify an override. This becomes your system-wide policy baseline for latency, cost, context length, and reasoning quality, so changing it affects nearly every conversation. In multi-provider setups, pair the default with explicit routing and fallback rules so quota or outage events do not silently shift quality. Revisit this setting after major model releases and benchmark updates, but decide with workload-specific evals instead of generic leaderboard performance.

Selects the embedding engine used for indexing and query encoding, such as deterministic test vectors, hosted APIs, or local inference servers. Backend selection determines retrieval quality, latency profile, operating cost, and reproducibility across environments. Deterministic backends are useful for CI baselines, but production relevance tuning should rely on real semantic models. Version backend choice together with preprocessing and model IDs to avoid evaluation drift.

Controls how many chunks are embedded in each request or inference pass. Larger batches usually improve throughput by reducing per-request overhead and increasing accelerator utilization, but they raise peak memory pressure and can hit rate or timeout limits. Smaller batches are safer on constrained hosts and unstable networks but increase total indexing time. Tune this setting from observed throughput and error rates, not fixed defaults.

Enables reuse of previously computed embeddings for identical normalized text, reducing repeated compute and API spend during reindex cycles. Cache hits are most beneficial when rerunning ingestion on mostly stable corpora or during iterative chunking tests. Cache keys should include model identifier, model revision, and preprocessing policy to prevent stale vectors from contaminating retrieval quality comparisons. Disable cache only when validating backend or model changes end-to-end.

This health signal means the full embedding contract used at query time matches the contract used to build the index, including provider, model identity, vector dimensionality, tokenizer behavior, and any text prefix or suffix transforms. When it is true, vector similarity scores are mathematically comparable and ranking quality is trustworthy. It also keeps offline evaluations meaningful because runs are measured in the same vector space. Treat this as a deployment gate: if you change embedding settings, rebuild before serving production queries. A persistent match state is one of the most important controls for preventing silent retrieval regressions.

Defines vector dimensionality in the index and must match model output exactly. Larger dimensions can preserve more semantic detail and improve hard-case recall, but they increase memory, storage, and approximate-nearest-neighbor compute cost. Smaller dimensions reduce cost and can speed search, especially when using embeddings designed for compression. Treat this as a quality-versus-efficiency control and rebenchmark whenever dimension changes.

Specifies what to do when a chunk exceeds the embedding model token limit. Simple end truncation is fast but can drop key evidence that appears later in long documents; middle-aware or hierarchical approaches retain broader coverage at higher preprocessing cost. Poor truncation policy introduces positional bias toward document openings and can lower grounding quality at answer time. Combine this setting with chunk-size policy so overlength chunks are uncommon.

This controls how many times the system retries a failed embedding call before marking the operation failed. It protects indexing from transient failures such as short network interruptions, temporary overload, and bursty rate-limit responses. Too few retries makes jobs brittle; too many retries can mask persistent faults and dramatically increase end-to-end indexing time. Pair this setting with exponential backoff and jitter so workers do not retry in synchronized waves. Track retry exhaustion in telemetry and fix root causes rather than continually raising the retry ceiling.

This sets the maximum token count sent to the embedding model for each chunk. Content beyond the limit is truncated, so the value directly controls how much semantic evidence is preserved in each vector. Higher limits can improve recall for long code blocks and docs, but they increase indexing cost, latency, and the chance of mixing multiple topics into one embedding. Lower limits are cheaper and often cleaner semantically, but can drop critical tail context. Tune this against your chunk size distribution and monitor truncation rate so most chunks fit without clipping.

This names the OpenAI embedding model used for indexing and query encoding when the OpenAI provider is selected. Model choice sets the quality, speed, vector shape options, and cost profile that downstream retrieval depends on. Because embedding spaces are model-specific, changing this value after indexing requires a full rebuild to keep similarity search valid. Treat model upgrades as versioned infrastructure changes: pin model ids, benchmark on your query set, and roll forward only with measured quality and latency impact. Avoid ad hoc switching between runs.

This selects the embedding backend family and therefore the core operating mode of retrieval: hosted API providers versus local inference runtimes. The choice drives quality, cost, privacy boundaries, tokenizer behavior, dimensionality, and operational dependencies such as network availability or local model files. Switching type usually changes vector space and requires reindexing to preserve ranking validity. Decide type at architecture level by balancing security and compliance constraints against latency and budget. Record provider and model together in index metadata so deployments remain reproducible.

This optional string is prepended to every text before embedding, commonly used to label role intent such as query or document. Stable prefixes can improve alignment by providing consistent task context to the embedding model. Because the prefix becomes part of the token sequence, changing it shifts vector geometry and requires reindexing for valid comparison. Keep prefixes short, explicit, and versioned; long or frequently edited prompt templates introduce drift and make experiments hard to reproduce. Evaluate prefix changes with offline relevance metrics before rollout.

This optional string is appended to each text before embedding, useful for consistent delimiters or lightweight schema hints across heterogeneous content. Suffixes influence tokenization and final vector placement, so changing them invalidates direct comparability with previously indexed vectors and requires reindexing. Use compact, stable suffixes and avoid large boilerplate tails that can drown out meaningful content in short chunks. Document suffix policy in index metadata so retrieval regressions can be traced to preprocessing changes quickly. Treat suffix design as part of your embedding contract, not cosmetic formatting.

This is the maximum wait time for an embedding request before the call is treated as failed. It defines how long indexing workers can block on slow upstream responses and strongly affects throughput under load. If timeout is too low, valid requests fail and trigger unnecessary retries; if too high, stuck calls reduce parallelism and delay incident detection. Tune this with retry count, concurrency, and observed p95 and p99 latency, not mean latency alone. Separate timeout profiles for interactive queries versus bulk indexing jobs when possible.

A mismatch means the active embedding configuration no longer matches the vectors already stored in your index. Different models or preprocessing pipelines produce different coordinate systems, so nearest-neighbor comparison becomes unreliable even when the text looks similar. Typical symptoms are irrelevant top hits, unstable rankings, and sudden metric collapse after config changes. In production, treat this as a critical error state. The safe recovery path is either restoring the original embedding settings or fully re-embedding and reindexing the corpus with the new settings.

This selects the exact model used by the configured enrichment backend. It is the main lever on the quality versus cost versus throughput tradeoff for generated summaries and keywords. Higher-capability models can improve semantic signals for reranking and explanation quality, while lighter models reduce expense and indexing time. Even without changing embeddings, enrichment model swaps can shift retrieval outcomes, so they should be benchmarked and version-controlled. Pin model ids and evaluate outputs on representative repositories before adopting changes in production pipelines.

Selects the local Ollama model used for enrichment steps such as code-card expansion, metadata extraction, and structure-aware summaries before retrieval. This choice is a quality versus latency tradeoff: larger coder models usually produce richer symbols and relationships, while smaller models reduce indexing time and hardware pressure. Keep the selected model pinned to an explicit tag so enrichment output stays reproducible across rebuilds. In production, validate the model on a fixed enrichment sample set and monitor drift in extracted fields after model upgrades.

This is the primary model used to synthesize answers from retrieved context, and it dominates quality, latency, and cost behavior. Choose it with workload-specific evaluation sets, not leaderboard intuition, because retrieval quality and prompt structure can change model rankings. Version model IDs explicitly so experiments are reproducible and regressions can be traced. Re-evaluate whenever provider releases shift default behavior, even if API names stay stable. Good retrieval can still underperform if the generation model is misaligned with your task style and response requirements.

`GEN_MODEL_OLLAMA` selects the concrete local model tag used when generation is routed through Ollama instead of a hosted provider. In this configuration family, the default is `qwen3-coder:30b`, and changing it directly affects response quality, latency, memory pressure, and token-context behavior for all generation calls that use the Ollama path. Use explicit model tags and keep them consistent across environments so evaluation runs remain reproducible and regressions can be traced to model changes rather than retrieval or prompt drift. When updating this value, validate compatibility with your configured context and timeout settings before promoting to shared environments.

This key authenticates calls to Google Gemini and related APIs, so it should be managed as a production secret. In RAG systems, key misuse can create unexpected spend, quota exhaustion, or unauthorized access patterns that degrade service quality. Store it in a secret manager, scope permissions minimally, and rotate on schedule or incident. Never expose it in client code, logs, or prompt artifacts. Add per-key monitoring and alerting so abnormal traffic is detected before it impacts retrieval and generation pipelines.

This override controls model selection for HTTP/API traffic, where SLOs, concurrency, and cost controls are usually stricter than interactive internal use. It enables channel-specific governance, such as serving public endpoints with stable low-variance models while reserving premium models for internal workflows. Treat changes here as API behavior changes and validate with canary rollouts. Align timeout and retry policies to the chosen model because latency profile varies significantly by provider and model class. Clear fallback order prevents unpredictable responses during upstream incidents.

Secret credential used by LangSmith/LangChain telemetry clients to authenticate trace ingestion. If this key is missing, invalid, or scoped incorrectly, remote traces can fail even when local app behavior appears normal. Treat it like production infrastructure credentials: store in a secret manager, inject at runtime, rotate periodically, and never hardcode in repo files. In high-volume RAG services, validate key presence during startup so tracing failures are explicit instead of silently dropping observability data. Key hygiene here is foundational to reliable debugging and compliance.

Credential used by the runtime to authenticate trace and evaluation events sent to LangSmith. In RAG systems, this key ties each retrieval and generation span to a project so you can debug relevance misses, latency spikes, and hallucination regressions with full trace context. Treat it as production secret material: scope it to the minimum workspace, rotate it regularly, and keep separate keys for development, staging, and production to avoid cross-environment data bleed. If this value is missing or invalid, your app can still answer queries, but observability pipelines lose critical evidence for tuning retrieval, reranking, and prompt behavior.

Authentication token used when exporting trace telemetry to Langtrace services. For RAG/search systems, this key gates whether query rewrites, retrieval spans, reranker decisions, and response-generation timing are actually persisted for debugging and quality analysis. Keep it in a secret manager, never in checked-in config, and rotate on a predictable cadence because observability keys often leak through ad hoc scripts and local shells. When trace ingestion drops unexpectedly, verify this key first, then confirm it matches the configured host and project identifier.

Sets the upper token bound for documents passed into late chunking or long-context embedding before chunk-level extraction. This guardrail protects indexing jobs from memory spikes and long-tail latency when very large files enter the corpus. If set too low, you lose cross-section context that late chunking is intended to preserve; if set too high, throughput can collapse on constrained hardware. Calibrate this cap from real document-length percentiles and backend context limits.

Base checkpoint that LoRA adapters are trained against and later mounted on during reranking inference. Adapter weights are architecture-specific, so changing the base model after training usually invalidates existing adapters and can silently degrade ranking quality if not caught. Pin this value explicitly, record it in experiment metadata, and keep train/infer parity to make evaluation deltas trustworthy. In practice, base-model drift is a common root cause of non-reproducible reranker performance.

This specifies the local embedding model (usually SentenceTransformers or Hugging Face) used when running without hosted embedding APIs. It is a core quality and performance lever: larger models often improve semantic recall but consume more memory and index slower. Different local models also use different dimensions and training objectives, so changing models requires reindexing. Pin exact model revisions to avoid drift across machines and CI jobs. Use your own benchmark queries to choose a model, since leaderboard rank alone may not match your codebase or domain vocabulary.

Ollama request timeout is the hard client-side budget for a full generation call, including model warmup, first-token delay, and decode time. Set it too low and valid long-context responses fail prematurely; set it too high and stalled calls tie up worker capacity and degrade system responsiveness. Calibrate timeout from observed p95/p99 latency per model and hardware profile, and revisit after model swaps or context-window changes. Use streaming plus clear retry/abort policy so timeout behavior remains predictable during spikes.

Maximum allowed silent gap (in seconds) between streamed tokens/chunks from the local Ollama endpoint before Crucible treats the response as stalled and aborts the request. This protects the UI from hanging indefinitely when a socket is half-open or a backend worker dies mid-generation. Set it too low and you will cut off valid long-prefill responses on larger context windows; set it too high and users wait too long on dead streams. Tune this together with network proxy timeouts and model size so cancellation behavior is fast but not trigger-happy.

This sets the MLX-compatible embedding model used on Apple Silicon. MLX uses Metal-optimized kernels, so it can provide strong local throughput for private or offline indexing pipelines. As with every embedding backend, the model id and dimension define the vector space; changing either requires full reindexing to keep search comparable. Quantized variants can reduce memory and speed up inference, but you should validate recall on representative queries before adopting them broadly. Record model id and quantization in index metadata for reproducible builds.

Model assignments define which model handles each pipeline stage (rewrite, embedding, reranking, generation, and evaluation). This mapping is operationally critical because stage-level mismatches can silently degrade quality: for example, embeddings with incompatible dimensions or generation models with insufficient context windows. Keep assignments explicit so you can audit cost, latency, and safety policy per task instead of per request. In practice, treat this table as a routing contract and version it with your evaluation suite to catch regressions when providers or model defaults change.

Netlify API key is a privileged credential used to trigger deployments and administrative site actions through automation. Treat it as a high-risk secret: use least privilege where possible, rotate on schedule, and store only in a managed secret system (never in repo or client-side bundles). Operationally, deployment failures from invalid or expired keys often look like generic API errors, so explicit key-health checks are worth adding to CI. For incident response, maintain clear ownership and revocation procedures because compromised deploy credentials can alter production content quickly.

Ollama `num_ctx` sets the maximum context tokens used per generation request, directly affecting both quality headroom and memory footprint. Higher values let you include more retrieved evidence and longer instructions, but they increase KV-cache pressure and can reduce throughput on constrained hardware. Tune this parameter from measured prompt composition (system + query + retrieved chunks + expected answer) rather than guessing. If requests regularly approach the ceiling, improve chunk selection and compression before simply raising `num_ctx`, because blindly increasing window size can destabilize latency.

Base URL Crucible uses to reach Ollama over HTTP for local-model inference (for example, endpoints such as `/api/chat`, `/api/generate`, and `/api/tags`). This value controls where requests are sent from the app backend, so incorrect hostnames, ports, or path prefixes cause immediate model-routing failures. For remote or containerized setups, use a reachable address from the process that runs Crucible, not just from your browser. When multiple OpenAI-compatible backends are in play, keep this endpoint explicit so provider routing and debugging stay deterministic.

Secret credential used by Crucible to authenticate OpenAI API requests for generation, embedding, or other provider-backed operations. Treat this as server-side sensitive configuration: never embed it in client bundles, logs, screenshots, or shared notebooks. If requests intermittently fail with auth errors, verify key scope, organization/project binding, and environment injection path before changing models. Rotation, secret scanning, and least-privilege operational controls are mandatory once this runs outside local-only testing.

Advanced endpoint override for OpenAI-compatible APIs. Use this when routing Crucible through alternative backends such as Azure-hosted deployments, vLLM, or internal gateway proxies that implement OpenAI-style request/response contracts. Base URL mismatches are a common root cause of 404/401 errors because SDK path composition, versioning, and auth headers differ across providers. Keep this setting paired with explicit model/provider assignments so you can trace which endpoint handled each request during failures.

Specifies the pretrained foundation model that LoRA adapters are attached to. Tokenizer vocabulary, context length behavior, architecture names, and module layout all come from this base model, so changing it after training usually invalidates existing adapters. Treat this as an ABI contract for fine-tuning: adapter weights, target modules, and optimizer state are only portable when the base model family and revision are compatible. Pin exact model revisions to make evaluation and rollback deterministic.

Points to the model artifact location used by the agent pipeline (local directory, checkpoint file, or hub identifier). This path determines what tokenizer/config/weights are loaded and where resumed training continues from. Use immutable, versioned paths for reproducibility and avoid ambiguous symlinks in production pipelines. For LoRA workflows, clearly separate base-model path from adapter output path so promotion and rollback do not accidentally mix incompatible artifacts.

Filesystem location of the active reranker checkpoint or adapter bundle used at inference time. This path is effectively a deployment control: whichever artifact is loaded here defines live ranking behavior. Use stable, versioned directories and atomically swap symlinks or folder names to avoid partial reads during update windows. In adapter-based pipelines, keep base model version and adapter metadata aligned so path changes do not silently load incompatible weights.

Filesystem path to the reranker checkpoint directory used at inference time. This value should point to an immutable artifact location once a model is promoted to production, with explicit versioning (`model-vYYYYMMDD-HHMM` style) rather than a floating path. Relative paths are convenient for local development, while production should prefer absolute, volume-backed paths with integrity checks. Startup should fail fast if the path is missing required files (weights, tokenizer, config), because silent fallback behavior can produce hard-to-debug ranking regressions.

LLM used for semantic knowledge-graph extraction when KG mode is set to LLM-based extraction. This model is responsible for entity detection, relation typing, and canonicalization decisions that become graph nodes and edges, so it directly controls graph quality and downstream traversal precision. Prefer models that are stable on structured extraction, handle long technical context, and support deterministic formatting or schema-constrained outputs. In practice, tune temperature low, enforce strict relation schemas, and validate extracted triples before write-back; weaker models can over-generate relations, confuse entity aliases, or miss cross-sentence links.

Credential used for Voyage-hosted embedding and reranking requests when Voyage is selected as the provider. Without a valid key, embedding generation and cloud reranking calls fail at request time, so retrieval can silently degrade to stale vectors or fallback behavior depending on your pipeline. Operationally, keep this key scoped per environment, rotate it on a schedule, and monitor request failures and quota usage. Pair key management with health checks that verify embedding and reranker endpoints separately, since one can fail while the other still responds.

Target vector dimensionality for Voyage embeddings. This value must match both the selected Voyage embedding model output and the configured vector index schema; mismatches typically cause upsert failures or silent search-quality regressions if vectors are transformed incorrectly. Higher dimensions can improve semantic separation on hard queries, but they also increase index size, memory pressure, and distance-computation cost. Any dimension change is a schema change in practice: create a new collection/index and re-embed content rather than mixing vectors produced under different dimensions.

Selects which Voyage embedding model generates vectors for indexing and retrieval. The model choice determines embedding behavior (for example code bias vs. general text behavior), output dimensionality, and operational cost/latency characteristics, so it directly affects both relevance quality and infra footprint. Change this deliberately and evaluate with a fixed benchmark query set. Because model changes alter vector semantics, switching models should be treated as a reindex event: regenerate vectors, rebuild the index, and compare recall@k, reranked precision, and p95 latency before promoting to production.

Model identifier used for Voyage second-stage reranking. After initial retrieval returns candidates, the reranker rescoring step estimates query-document relevance more precisely and reorders the shortlist. This usually improves top-result precision, especially for nuanced or code-heavy intent. The tradeoff is cost and latency per request proportional to candidate volume. Tune reranker usage together with candidate count (top_k before rerank) and timeout budget; too many candidates can overrun latency targets, while too few can starve the reranker of useful alternatives.

BM25_B is the length-normalization parameter in BM25 and controls how strongly long chunks are penalized compared with short chunks. Higher values increase normalization, which helps when long documents accumulate incidental term matches; lower values reduce that penalty and can help when key evidence naturally lives in larger files. In hybrid retrieval this parameter shapes sparse scores before fusion with dense vectors, so it directly affects which lexical results survive into reranking. Tune b with mixed query types, including exact identifiers and natural-language requests, to avoid overfitting one retrieval mode.

BM25_K1 controls term-frequency saturation, meaning how much repeated occurrences of a term continue to increase sparse relevance. Lower values make scoring closer to binary presence and reduce repetition bias; higher values reward repetition more strongly, which can help when repetition is genuinely informative. In code search, overly high k1 can over-rank boilerplate-heavy files, while very low k1 can under-rank dense implementation chunks. Tune k1 jointly with b and tokenizer configuration, then validate on both exact-match and intent-style queries.

BM25_STEMMER_LANG chooses the stemming or morphological normalization profile applied before sparse indexing. Correct language normalization improves recall by unifying inflected word forms, while incorrect stemming can collapse distinct technical terms and reduce precision. Multilingual corpora often need language-aware analyzers by field rather than one global stemmer, especially when prose and code identifiers coexist. Any change here requires reindexing and targeted multilingual relevance checks because token statistics and BM25 behavior shift across the entire corpus.

BM25_TOKENIZER determines how text is split into sparse terms, and this often has a larger impact than small parameter tweaks. Conservative tokenization preserves exact symbols and identifier fragments useful for code retrieval, while aggressive normalization helps natural-language matching. The right choice depends on corpus composition: APIs and filenames benefit from symbol-aware token boundaries, whereas narrative documents benefit from linguistic normalization. Because tokenizer behavior changes term frequencies and document lengths, retune BM25 parameters after tokenizer changes instead of carrying old values forward.

Inspect tokenized vocabulary from BM25 sparse index. Shows term frequencies for debugging. Use cases: verify code identifiers preserved, check stemmer behavior, identify noise terms, debug zero-result queries. Vocabulary reflects tokenizer: whitespace (exact, best for code), stemmer (normalized, best for prose), standard (balanced). Large vocabularies (>100K) indicate insufficient stopword filtering.

Weight assigned to BM25 (sparse lexical) scores during hybrid search fusion. BM25 excels at exact keyword matches - variable names, function names, error codes, technical terms. Higher weights (0.5-0.7) prioritize keyword precision, favoring exact matches over semantic similarity. Lower weights (0.2-0.4) defer to dense embeddings, better for conceptual queries. The fusion formula is: final_score = (BM25_WEIGHT × bm25_score) + (VECTOR_WEIGHT × dense_score). Sweet spot: 0.4-0.5 for balanced hybrid retrieval. Use 0.5-0.6 when users search with specific identifiers (e.g., "getUserById function" or "AuthenticationError exception"). Use 0.3-0.4 for natural language queries (e.g., "how does authentication work?"). The two weights should sum to approximately 1.0 for normalized scoring, though this isn't strictly enforced. Symptom of too high: Semantic matches are buried under keyword matches. Symptom of too low: Exact identifier matches rank poorly despite containing query terms. Production systems often A/B test 0.4 vs 0.5 to optimize for their user query patterns. Code search typically needs higher BM25 weight than document search. • Range: 0.2-0.7 (typical) • Keyword-heavy: 0.5-0.6 (function names, error codes) • Balanced: 0.4-0.5 (recommended for mixed queries) • Semantic-heavy: 0.3-0.4 (conceptual questions) • Should sum with VECTOR_WEIGHT to ~1.0 • Affects: Hybrid fusion ranking, keyword vs semantic balance

CARD_SEARCH_ENABLED determines whether card-based semantic matching participates in retrieval and score fusion. When enabled, high-level module summaries can bridge user intent phrasing that does not share exact tokens with underlying code chunks. This usually improves exploratory and architecture queries, but it also adds ranking work and can raise false positives if cards are stale or low quality. Keep it enabled when card enrichment is regularly refreshed, and disable it for strict lexical debugging where deterministic exact-match behavior is preferred.

Enables a separate retrieval path over generated chunk summaries, so the system can match intent-level language even when the query does not contain exact identifiers. This usually improves recall for architectural or behavioral questions, but only if summaries were generated during indexing and kept in sync with source updates. Turning it on adds another retrieval pass, so latency and token/compute cost can rise slightly depending on your backend. Best practice is to enable it with careful score balancing so summary matches expand candidate recall without replacing strong exact matches.

Defines how many top retrieved items count toward success during evaluation metrics like Hit@K. Lower values enforce strict precision and expose ranking weaknesses, while higher values emphasize recall and can hide poor ordering if the answer appears late. Keep this aligned with your production retrieval depth so offline metrics predict real behavior. When tuning, inspect both aggregate Hit@K and position-sensitive metrics so you do not optimize for lenient success criteria alone.

Sets how many results survive final fusion and reranking before response generation or UI display. Larger values increase recall and diversity but can dilute evidence quality and consume more context budget; smaller values improve focus and latency but risk dropping key context. Tune this together with reranker quality and chunk size so returned sets remain both relevant and compact. In practice, this parameter strongly influences answer stability because it controls the evidence frontier given to the model.

GRAPH_SEARCH_ENABLED is the master switch for whether graph retrieval participates in the final evidence set. When enabled, the system can combine semantic similarity, lexical signals, and structural graph relationships, which usually improves multi-hop and cross-file question coverage. When disabled, behavior becomes a simpler dense-plus-sparse retrieval baseline with lower operational complexity. This flag is useful for incident isolation and A/B testing because it lets you measure graph contribution directly against non-graph retrieval. Keep a tested fallback profile so the system can degrade gracefully if graph infrastructure is unavailable.

GRAPH_SEARCH_MODE chooses the graph retrieval strategy, typically between chunk-centric traversal and entity-centric traversal. Chunk mode usually gives stronger grounding for answer generation because ranking starts from chunk-level evidence that maps directly into prompts. Entity mode can be useful for ontology-heavy or architecture questions, but it is more sensitive to entity extraction quality and linking consistency. This setting should match how your graph was built; mismatching mode to graph design often looks like low recall with correct infrastructure. Treat mode choice as a retrieval architecture decision, then tune hops and weights inside that chosen mode.

GRAPH_SEARCH_TOP_K controls how many graph candidates are kept before downstream fusion and reranking. Increasing top-k usually improves recall because more potentially useful graph evidence survives early pruning, but it also raises latency and can inflate reranker and generation token costs. If top-k is too small, graph retrieval appears weak even when the graph is high quality because relevant nodes are dropped prematurely. If it is too large, weaker graph neighbors can crowd the context budget and reduce final answer precision. Tune this setting with both retrieval metrics and end-to-end answer quality, and keep it aligned with final context assembly limits.

Sets how many retrieved candidates are retained after fusion or reranking before final answer synthesis in a LangGraph-style workflow. This parameter directly balances recall against context noise and token cost: larger values preserve more potentially useful evidence, while smaller values reduce latency and hallucination surface from marginal passages. Effective tuning depends on corpus redundancy and reranker quality, so evaluate with answer-level metrics rather than retrieval-only metrics. Keep this aligned with model context limits and downstream prompt design to avoid passing excess low-value text. In multi-stage graphs, final_k should be considered with earlier retrieval breadth settings.

Limits how many alternate query rewrites are generated inside the LangGraph answer path. Additional rewrites can significantly improve recall on ambiguous or underspecified user questions by exploring lexical variants and sub-intents, but each rewrite adds model calls, retrieval fan-out, and dedup work. Set this based on latency budget and observed marginal gain per rewrite, not on a fixed preference for larger numbers. Practical deployments combine a moderate cap with early-stop heuristics when rewrites become near-duplicates. This keeps retrieval expansion useful instead of turning into cost-heavy redundancy.

LoRA scaling factor that determines how strongly adapter updates influence the frozen base reranker during training and inference. The effective adaptation strength is tied to alpha relative to rank, so increasing alpha without considering rank can over-amplify updates and destabilize relevance calibration. In ranking-focused fine-tuning, this value is best tuned with validation metrics that emphasize ordering quality, not just loss reduction. Use conservative increments and track metric movement on hard negatives to avoid overfitting narrow retrieval patterns.

Constant "k" parameter in Reciprocal Rank Fusion (RRF) formula used to merge results from multiple query rewrites. RRF formula: score = sum(1 / (k + rank_i)) across all query variants. Higher M values (60-100) compress rank differences, treating top-10 and top-20 results more equally. Lower M values (20-40) emphasize top-ranked results, creating steeper rank penalties. Sweet spot: 50-60 for balanced fusion. This is the standard RRF constant used in most production systems. Use 40-50 for more emphasis on top results (good when rewrites are high quality). Use 60-80 for smoother fusion (good when rewrites produce diverse rankings). The parameter is called "M" in code but represents the "k" constant in academic RRF papers. RRF fusion happens when MQ_REWRITES > 1: each query variant retrieves results, then RRF merges them by summing reciprocal ranks. Example with M=60: rank-1 result scores 1/61=0.016, rank-10 scores 1/70=0.014. Higher M reduces the gap. This parameter rarely needs tuning - default of 60 works well for most use cases. • Standard range: 40-80 • Emphasize top results: 40-50 • Balanced: 50-60 (recommended, RRF default) • Smooth fusion: 60-80 • Formula: score = sum(1 / (M + rank)) for each query variant • Only matters when: MQ_REWRITES > 1 (multi-query enabled)

Sets how many alternative query phrasings are generated before retrieval. Each rewrite typically executes the full retrieval stack (sparse/vector/graph + fusion), so increasing this value can recover documents missed by the original wording but grows latency and token cost almost linearly. In practice, treat it as a recall budget: start low, measure unique-relevant-document gain per extra rewrite, and stop when marginal gain flattens. Keep the original query in the candidate set to prevent rewrite drift, and pair this with reranking so noisy rewrites do not dominate final context selection.

Enables generation of additional query variants (rewrites, paraphrases, or decomposition prompts) before retrieval. This can significantly improve recall on underspecified or ambiguous user questions by increasing lexical and semantic coverage, especially in heterogeneous code-and-doc corpora. The tradeoff is extra latency, more candidate noise, and higher token or API cost if expansions are not constrained. Production tuning usually combines expansion with caps on variant count, deduplication, and reranker gating so recall gains do not overwhelm precision.

Controls LoRA adapter scaling (commonly applied as `alpha / rank`). Higher alpha increases the effective strength of adapter updates and can speed adaptation, but it also raises the risk of overshooting or overfitting on narrow datasets. Lower alpha makes updates conservative and may underfit unless training runs longer. Treat alpha as a stability/capacity dial coupled to rank and learning rate; when rank changes, revisit alpha instead of keeping a fixed absolute value.

Interpolation weight used when combining the reranker score with upstream hybrid retrieval score. In practical terms, this is the control for how much the final ranking trusts pairwise relevance modeling versus the broader BM25+dense candidate order. Raising alpha usually improves precision for well-formed queries, but if it is set too high the system can overfit to reranker biases and underweight lexical exact-match evidence. Tune it with fixed query sets and report both quality metrics (nDCG, MRR, grounded answer rate) and latency to avoid hidden regressions.

Legacy alias for `TRIBRID_RERANKER_ALPHA`. This is the blend weight that determines how strongly reranker scores influence final ordering versus first-stage retrieval scores. Higher values make the cross-encoder (or learned reranker) dominate; lower values preserve sparse/dense retrieval priors. Tune `alpha` with a fixed evaluation set and monitor both ranking quality and stability by query segment (short keyword queries, long natural-language questions, and code-specific lookups). If alpha is too high, reranker noise can overfit to lexical artifacts; if too low, reranking cost is paid without meaningful ranking gains.

BM25_TOKENIZER_RESOLVED captures the effective tokenizer and analyzer configuration after defaults, overrides, and language settings are merged. This matters because the configured value may not match the analyzer actually used at index time. Use the resolved setting as ground truth when debugging unexpected retrieval shifts or mismatch between environments. When ranking changes after deploy, inspect this resolved configuration first and run analyzer explain checks on representative strings before deciding whether reindexing or parameter retuning is needed.

When enabled, indexing skips dense embedding generation and vector-store writes, leaving retrieval fully lexical (BM25/FTS). This is useful for fast local iteration, constrained CI environments, or deployments where vector infrastructure is unavailable. The tradeoff is predictable: lower indexing cost and simpler ops, but weaker semantic recall for paraphrases and concept-level matches. Use this mode when exact term matching dominates your workload (file names, identifiers, error strings), and disable it for natural-language-heavy corpora where semantic expansion materially improves first-pass recall.

Master toggle for lexical retrieval. When enabled, keyword scoring (BM25/FTS) is available for exact-term matching and can run standalone or alongside dense retrieval in hybrid ranking. When disabled, the pipeline depends on non-lexical retrieval paths, which can miss exact symbols, file names, and rare identifiers. Keep this on for most code and technical corpora; turn it off only when you intentionally want dense-only behavior or are isolating retrieval regressions. Evaluate this setting with query sets containing both natural-language and exact-token intents.

Selects which lexical backend executes sparse retrieval. In practice this governs tokenization behavior, ranking details, index build/maintenance cost, and query features available to the stack. Built-in Postgres FTS offers broad compatibility and simple operations; BM25-focused extensions such as pg_search can improve relevance control and performance for search-heavy workloads. Choose engine based on operational constraints first (extensions allowed, migration path, observability), then benchmark with your real query distribution because ranking differences can be substantial.

Enables a path-oriented fallback when normal sparse matching underperforms. This fallback is useful for developer queries dominated by file names, module paths, package hierarchies, and extension filters where standard tokenization may fragment intent. A good fallback parses separators like '/', '.', '-', and '_' to recover high-signal path terms, then issues a targeted lexical query. Keep it enabled for codebases and monorepos; disable only if it introduces false positives in prose-heavy corpora.

Upper bound on tokens included when building file-path fallback queries. This prevents overly long path-like inputs from exploding into broad lexical queries that hurt latency and precision. Lower values improve stability and reduce noisy matches in large repositories; higher values may recover deeper paths but can over-bias common directory names. Tune with realistic path queries and monitor both candidate set size and top-k relevance, not just hit counts.

Turns on lexical-match highlighting metadata (for example snippets or emphasized terms) in sparse retrieval results. This is mainly an observability feature: it helps you verify why a chunk matched, debug tokenizer behavior, and explain ranking decisions to users. Highlight generation can add query-time overhead, so many teams enable it in debug and evaluation environments, then gate it in production by route or role. Keep it on while tuning sparse relevance and parsing modes.

Determines how sparse queries are parsed before scoring. Typical modes map to plain-term parsing, phrase parsing, or boolean/operator-aware parsing, and each mode changes recall/precision behavior substantially. Plain mode is safest for general user input, phrase mode tightens precision for exact multi-token intent, and boolean mode provides expert control but can degrade results when syntax is malformed. Choose a default that matches user sophistication, then expose advanced modes for debugging and power workflows.

Caps how many lexical terms the relaxer is allowed to keep when strict sparse retrieval underperforms. In practice, this guardrail prevents fallback BM25 queries from ballooning into broad, low-precision searches that return mostly boilerplate. Lower values preserve precision and faster query plans; higher values improve zero-result recovery but increase latency and term-noise risk. Tune it together with `SPARSE_SEARCH_RELAX_ON_EMPTY`, `SPARSE_SEARCH_TOP_K`, and fusion weights so expanded sparse candidates still rerank cleanly against vector hits.

Enables automatic lexical fallback when the first sparse retrieval pass returns empty or unusably small results. This is a production safety valve for user-facing search: instead of failing hard on exact-term mismatch, the system broadens sparse matching and gives reranking another candidate pool to work with. Keep it on for interactive workloads unless you require strict deterministic matching for evaluation. The quality of this fallback depends on your relax limits, sparse top-k, and how aggressively sparse scores are weighted in hybrid fusion.

Controls how many BM25 candidates are fetched before fusion or reranking. Raising top-k generally improves recall for exact identifiers, logs, and error codes, but it also increases scoring cost and can dilute precision if downstream reranking is weak. In hybrid pipelines, a healthy top-k gives the fusion stage enough lexical evidence without overwhelming vector candidates. Calibrate with latency budgets and evaluate at fixed query sets (recall@k, nDCG, and p95 query time) rather than guessing from single queries.

TOPK_DENSE sets how many semantic candidates are pulled from the dense index before fusion. In practice, this controls the recall ceiling for meaning-based matches: if it is too low, relevant chunks can be dropped before reranking ever sees them; if it is too high, latency and downstream rerank cost grow quickly. Tune it against your corpus distribution and query mix by tracking recall@k, answer grounding rate, and p95 latency together, not in isolation. A common pattern is to increase TOPK_DENSE when user questions are abstract or paraphrased, then counterbalance compute by tightening reranker depth or pruning thresholds later in the pipeline.

TOPK_SPARSE sets how many lexical candidates are retrieved from sparse scoring (BM25-style) before hybrid fusion. This value is critical for exact-match behavior such as identifiers, SKU-like tokens, config names, and error strings that dense embeddings can blur. If TOPK_SPARSE is too low, precision may look good while recall silently collapses on keyword-heavy workloads; if too high, you can over-admit noisy boilerplate and increase rerank pressure. Evaluate it jointly with tokenizer configuration and fusion weights so sparse evidence remains a strong but not dominant signal.

Master toggle for dense semantic retrieval. When enabled, the pipeline performs embedding-based nearest-neighbor search and contributes those candidates to fusion/reranking; when disabled, retrieval relies on non-vector channels (for example sparse lexical and graph signals). Disabling can be useful for controlled debugging, cost isolation, or outage mitigation, but it usually reduces semantic recall on paraphrased questions. Treat this flag as a diagnostic switch: compare answer grounding and recall metrics with and without vector search to quantify how much semantic retrieval contributes for your dataset.

Number of dense-vector candidates fetched before fusion and reranking. Top-K is a primary recall/latency lever: increasing it broadens candidate coverage and can rescue relevant passages that would otherwise be missed, but raises search and reranker cost. Too small a Top-K can make downstream reranking ineffective because the right candidates never enter the pool; too large a Top-K can flood reranking with low-value items and slow responses. Tune this jointly with reranker Top-N and fusion weights, and evaluate with recall@k, MRR/NDCG, and p95 latency rather than a single metric.

Selects whether reranking is enabled and which execution path is used (local/learning, cloud, or off). Reranking usually improves top-k precision by re-scoring candidate passages with a stronger cross-encoder or specialized model, but it adds latency and cost. Local mode reduces network dependency and can enable adaptive training loops; cloud mode simplifies model management but depends on provider reliability and quotas; off is fastest but may reduce answer quality on ambiguous queries. Choose mode per SLA and workload profile.

Provider identifier used by the cloud reranker configuration layer (for example, values surfaced from `models.json`). Keep this value aligned with your model catalog so UI selections resolve to valid API credentials, base URLs, and model IDs at runtime. A provider mismatch often fails late (during request dispatch), so validate provider-model compatibility at config load time when possible. In multi-provider setups, this key is the routing pivot that determines which API semantics and reliability envelope apply to the same query workload.

Determines which external vendor handles reranking when cloud mode is enabled. Provider choice affects auth, rate limits, billing units, token limits, and model availability, so swapping providers is a behavior change, not just a credential change. Keep provider-specific defaults explicit (timeouts, top-N caps, retry policy) and validate with provider-specific regression queries. For production stability, monitor provider error classes separately so fallback rules can distinguish auth/config issues from transient throttling.

Limits how many first-pass candidates are sent into the cloud reranker. This is the main quality-cost control for API reranking: higher Top-N usually improves final precision/recall at the expense of latency and request cost. Tune it jointly with first-stage retrieval depth; a small Top-N can hide relevant documents before reranking ever sees them, while an oversized Top-N can waste budget on obvious non-matches. Start from an empirically measured knee point (quality gain flattening vs latency growth) rather than a fixed default.

Selects the execution stack used to train and serve the learning-based reranker. In this project, backend choice determines hardware assumptions, supported model formats, and how adapters are loaded during inference, so it directly affects throughput, reproducibility, and operational complexity. Keep the backend consistent across training and deployment environments whenever possible, or validate compatibility boundaries before shipping adapters. If performance or stability regresses, backend mismatch is one of the first places to investigate.

Default studio preset loaded when the learning-reranker workspace opens, controlling which panes and diagnostics are immediately visible. Although it does not change model weights, it changes operator behavior by determining whether users start from metric dashboards, logs, or inspectors, which affects how quickly failures are diagnosed. Good defaults reduce setup friction and increase consistency across experiments, especially when multiple engineers tune reranker training. Choose a preset that exposes the minimum signals needed for safe decision-making in your typical workflow.

Number of micro-batches whose gradients are accumulated before each optimizer update during reranker training. Increasing this value raises effective batch size without requiring equivalent VRAM, which can stabilize ranking-objective learning but also slows update frequency and may require learning-rate retuning. For RAG rerankers, this parameter is most useful when negatives are hard and memory is constrained, because larger effective batches improve signal diversity per update. Tune it jointly with global batch size, learning rate, and training time budget rather than in isolation.

Idle-time model eviction threshold for the local MLX reranker. When this timer is greater than zero, the reranker is unloaded after inactivity so RAM/VRAM can be reclaimed for other work; when set to zero, the model stays resident and avoids cold-start reload latency. This is a classic memory-latency tradeoff: aggressive unloading helps constrained laptops, while persistent residency is better for frequent back-to-back reranks. Tune this using actual interaction cadence, not defaults: if people pause briefly between trials, use a longer window to avoid repeated thrash from unload/reload cycles.

UI layout system used by the reranker studio, which governs pane docking behavior, state persistence, and interaction performance for high-density training dashboards. While this is not a retrieval algorithm parameter, it impacts operational efficiency because poor layout ergonomics slow inspection of ranking metrics, error cases, and training logs. Prefer the engine that gives stable panel persistence and low interaction overhead on your target hardware and browser stack. Keep layout configuration versioned so team workflows remain consistent across releases.

Controls whether studio logs are rendered as terminal-like streaming output or structured JSON views. Terminal rendering is better for real-time operational monitoring during active training, while JSON rendering is better for filtering, programmatic analysis, and postmortem debugging of failed runs. The best choice depends on whether your primary task is live supervision or forensic inspection of reranker behavior. Standardizing this setting across teams improves reproducibility of debugging workflows and incident handoffs.

Dropout probability applied inside LoRA adapter paths during reranker fine-tuning. This acts as regularization against overfitting on narrow training pairs, especially when mined positives and negatives are repetitive or domain-skewed. Too little dropout can produce brittle rankers that fail on unseen queries, while too much can underfit and flatten relevance separation. Tune with validation sets that include both in-domain and near-domain queries so improvements generalize beyond the training distribution.

Adapter rank determines the capacity of LoRA updates layered onto the base reranker. Higher rank can capture richer relevance transformations and improve difficult ranking tasks, but it increases memory, training cost, and overfitting risk if data volume is limited. Lower rank is cheaper and often sufficient for moderate domain adaptation, especially when base model quality is already high. Select rank by balancing retrieval-quality gains against training budget and inference latency targets, then confirm with held-out ranking benchmarks.

List of model submodules that receive LoRA adapters, such as attention projections or selected feed-forward layers. This setting determines where adaptation capacity is concentrated, which changes both ranking quality and compute cost more than many scalar hyperparameters. Targeting only key attention paths is efficient for many reranker tasks, while expanding to more modules can help domain shift at the expense of memory and optimization complexity. Treat module selection as an architectural choice and benchmark it with the same rigor as rank or learning rate.

`LEARNING_RERANKER_NEGATIVE_RATIO` controls how many negative `(query, document)` pairs are generated per positive pair during learning-reranker training (default `5`, range `1`-`20`). Higher ratios usually improve separation between relevant and non-relevant candidates, but they also increase training time, GPU memory usage, and the risk of overfitting to easy negatives if sampling quality is poor. Lower ratios train faster and can be sufficient when negatives are already hard and diverse, but may leave the reranker under-discriminative on near-miss results. Treat this as a quality-versus-cost dial and tune it alongside hard-negative mining strategy and dev-set ranking metrics.

`LEARNING_RERANKER_PROMOTE_EPSILON` sets the minimum dev-metric delta required before a newly trained reranker is allowed to replace the active baseline (range `0.0`-`1.0`, default `0.0`). This threshold is a noise guard: if metric gains are smaller than epsilon, the run is treated as statistically or operationally insignificant and promotion should be blocked. Small nonzero values (for example around `0.001`-`0.005` depending on metric stability) reduce churn from random variation, label noise, and temporary data drift. Calibrate epsilon from repeated baseline evaluations so promotion decisions reflect durable quality changes rather than measurement jitter.

`LEARNING_RERANKER_PROMOTE_IF_IMPROVES` is the hard promotion gate for learning-reranker training. When set to `1` (default), a successful training job promotes the candidate artifact only if the primary dev metric exceeds the current baseline by at least `LEARNING_RERANKER_PROMOTE_EPSILON`; when set to `0`, every successful run can overwrite the active path. Keeping this enabled is safer in continuous-training loops because it preserves model stability during noisy data windows and imperfect labeling periods. Disable it only for controlled experiments with manual review and explicit rollback procedures.

`LEARNING_RERANKER_SHOW_SETUP_ROW` controls whether the setup summary row is visible above the training studio dock layout (`1` = shown, `0` = collapsed; default `0`). This row provides quick context about run configuration and can reduce navigation overhead when comparing experiments, especially in dense training sessions. Hiding it increases available workspace for logs, visualizer output, and inspection panels, which can be better on smaller displays. Use `1` when onboarding or debugging configuration drift, and `0` when users already know the setup and need maximal panel real estate.

`LEARNING_RERANKER_STUDIO_BOTTOM_PANEL_PCT` sets the default height of the studio bottom dock as a percentage of total workspace (default `28`, allowed range `18`-`45`). This value directly affects how much vertical space is reserved for outputs like logs, diagnostics, and timeline-style visual traces versus the primary training controls. Lower percentages prioritize top-level controls and inspectors, while higher percentages favor continuous monitoring and detailed log reading. Keep the value within the configured bounds to avoid layout crowding and ensure predictable behavior across desktop and smaller laptop resolutions.

`LEARNING_RERANKER_STUDIO_LEFT_PANEL_PCT` sets the default width of the left dock in the learning-reranker studio (default `20`, allowed range `15`-`35`). In practice, this controls how much horizontal space is allocated to setup/navigation controls before content-heavy panes such as logs, charts, or inspectors take over. Smaller values increase room for analysis panels and visualizer outputs, while larger values improve readability of configuration forms and parameter groups. Tune this with real workflows and screen sizes so key controls remain visible without forcing excessive panel toggling.

Controls how much horizontal space the right-side inspector gets in Learning Reranker Studio. This panel usually contains high-context diagnostics (metric chips, run metadata, and explanation details), so shrinking it too aggressively can hide critical state and force extra toggling. Increasing it improves readability for dense diagnostics, but steals width from query/result panes and can reduce comparison speed. Treat this as a task-fit control: wider for debugging and failure analysis, narrower for rapid iterative edits. Keep it coordinated with left/bottom panel widths so the core training and ranking context remains visible at the same time.

Defines how often trainer telemetry is emitted in optimizer-step units. Lower values (for example 1-2) produce smoother live curves and faster anomaly detection, but increase event traffic, UI render pressure, and log volume. Higher values reduce overhead and can stabilize weak machines, but hide short-lived instability such as gradient spikes or transient loss explosions. In practice, use tighter intervals while tuning a new objective or dataset, then relax interval size once behavior is stable. This parameter directly shapes observability quality, so tune it with both monitoring fidelity and system cost in mind.

Maximum number of telemetry samples retained in visualizer history. Larger buffers preserve long-run context and make regression trend analysis easier, but cost more memory and increase render work for each frame. Smaller buffers keep UI responsiveness high and reduce browser/GPU pressure, but can hide earlier failure modes and make long-cycle debugging harder. Choose this alongside telemetry interval: frequent logging plus very large point caps can overload rendering, so prefer either light decimation or moderate caps for sustained real-time sessions.

Global multiplier for animation energy in the visualizer (camera drift, particle movement, transitions). Raising intensity can make state changes easier to notice in brief glances, but also increases motion load and may amplify distraction or simulator sickness for some users. Lower values reduce GPU demand and improve readability during metric-heavy debugging. Treat this as an ergonomics control, not just aesthetics: adjust based on session type (live monitoring vs deep analysis), user preference, and machine capability.

Quality preset for the Neural Visualizer rendering pipeline (for example balanced, cinematic, ultra). Higher tiers usually increase shader complexity, sampling, and post-processing fidelity, which can improve visual clarity but consume more GPU time and reduce frame stability under load. Lower tiers trade visual polish for deterministic interaction and lower power use. Tune this based on objective: use high quality for demos or screenshots, and balanced/lower settings during prolonged optimization sessions where low-latency interaction matters more than effects.

Accessibility-first switch that lowers or disables non-essential motion effects in the visualizer. With this enabled, transitions become calmer and less visually aggressive, which helps users sensitive to animation and can also reduce compute overhead on weaker devices. This should be treated as a functional comfort setting, not a cosmetic option. In most interfaces, the best behavior is to respect OS-level `prefers-reduced-motion` by default and let users override explicitly when they want richer motion.

Selects the rendering backend used by the visualizer (`auto`, `webgpu`, `webgl2`, or `canvas2d`). `auto` should be the default because runtime capability detection can choose the strongest stable backend on each machine. `webgpu` typically offers the best throughput and future-proof compute features on supported browsers. `webgl2` is a mature fallback with broad compatibility. `canvas2d` provides maximum reach but lowest rendering sophistication. Use explicit backend overrides mainly for debugging platform-specific rendering bugs or enforcing predictable behavior in controlled environments.

Toggles the vector-field overlay used to visualize local direction and intensity of motion in the reranker trajectory view. With this enabled, you can quickly see whether updates are converging smoothly, rotating around a basin, or oscillating in conflicting directions, which is useful when tuning learning rate and regularization. Disable it when you need maximum rendering throughput or a cleaner presentation for non-technical review. Treat this as a diagnostic rendering layer: it does not change model training, only how training dynamics are interpreted.

Sets the visualizer's target frame rate for animation updates. Higher FPS improves motion smoothness and makes subtle directional changes easier to perceive, but increases GPU/CPU pressure and can reduce responsiveness on constrained machines. Lower FPS is often preferable for remote sessions, multi-monitor setups, or long diagnostics where thermal and fan limits matter. This parameter only affects rendering cadence, not training quality or optimization math, so tune it for operator comfort and stable observability.

Shows the running best objective value observed so far (typically lowest training loss), not merely the most recent step. That distinction matters: endpoint values can look improved by noise, while best-so-far tracks the strongest checkpoint candidate seen during the run. Use this signal to decide when to snapshot, compare runs, or gate promotion. If best-so-far plateaus while live loss jitters, optimization may be near saturation; if best-so-far regresses after schedule changes, your training dynamics may have destabilized even if the latest point appears acceptable.

What this control changes Color mode changes only hue/intensity encoding for the trajectory points. It does not change x/y projection and it does not change terrain height. In the code path, geometry is computed first and color is assigned later in projectPoints(..., intensityMode). Mode = absolute (where am I doing well?) Each point is colored from normalized train loss at that step. Lower loss maps toward the better/cooler side of the palette, higher loss toward the worse/warmer side. This is the easiest way to answer "which regions of this run were strong vs weak?" In this implementation, color is mostly loss with a smaller gradient-norm blend so structure remains visible when loss is locally flat. Mode = delta (am I improving right now?) Each point is colored from first difference versus the previous point: prev_loss - current_loss. Positive delta means local improvement; negative delta means local regression. This surfaces "learning" vs "thrashing" even when absolute loss is jagged because of mini-batch stochasticity. Interpretation rule Use absolute when comparing quality across run regions. Use delta when diagnosing local optimizer behavior, schedule transitions, or instability. Code path web/src/components/RerankerTraining/NeuralVisualizerCore.tsx -> projectPoints(... intensityMode ...)

What the last chip means The last=... chip is the most recent observed training loss sample. It is a snapshot of where the run ended, not a guarantee of best quality. Why last can be worse than best Mini-batch SGD is stochastic, so per-step loss is noisy and non-monotonic. Learning-rate schedules can also change local dynamics (for example warmup, cosine phases, or restart boundaries). Because of this, the terminal sample can sit above the minimum even in healthy runs. How to read best vs last together Treat best as the optimization floor reached during the run, and last as the endpoint state at stop time. The gap between them is a diagnostic signal for late-stage instability, schedule transitions, or insufficient checkpoint selection policy. Practical rule Do not evaluate run quality from endpoint alone. Compare both chips and use checkpointing policy that can restore the best observed state when needed.

When enabled, the visualizer auto-follows the newest telemetry point and keeps the viewport anchored to current training time. This is best for active monitoring because you immediately see drift, spikes, or convergence stalls as they happen. When disabled, you get stable playback/scrubbing for postmortem analysis without auto-jumps. Live mode is most useful when paired with short telemetry intervals and a capped point buffer; otherwise, frequent updates can push rendering work too high and reduce interaction smoothness on lower-end GPUs.

Controls timeline scrubbing in the learning-reranker visualizer so you can freeze playback at a specific training step and inspect how states evolved up to that point. In practice, this is the forensic control for diagnosing instability: you can pause on the first divergence, then compare score movement, gradient behavior, and rank ordering changes before and after that moment. When scrubbing is active, you are prioritizing deterministic inspection over live monitoring, which is usually the right mode for post-run root-cause analysis. Use this when best-checkpoint and last-checkpoint behavior disagree, or when live playback hides short transient failures.

Defines how much recent history is retained in live trajectory playback, expressed as seconds of visual tail. A shorter tail emphasizes immediate motion and makes rapid shifts easier to see, while a longer tail preserves context and makes drift patterns easier to diagnose over time. If this is too small, users may misinterpret stable long-term movement as abrupt noise; if too large, the display can become visually dense and harder to parse at speed. Tune this together with target FPS so temporal context and animation smoothness stay balanced on your hardware.

`RERANKER_TRAIN_PRIMARY_K_OVERRIDE` chooses the evaluation cutoff used by @k metrics (for example MRR@k or nDCG@k) when deciding what counts as the run's primary score. Implementation-wise, this determines how deep into the ranked candidate list the trainer looks before scoring success, so smaller k values enforce top-of-list precision while larger k values reward broader coverage deeper in the list. This should be aligned with product behavior: if users only inspect a handful of retrieved chunks, a large k can make offline metrics look strong while real UX still feels weak.

`RERANKER_TRAIN_PRIMARY_METRIC_OVERRIDE` sets which single ranking metric is treated as the run's decision metric for model selection and run comparison. In practical pipeline terms, this changes which checkpoint is tagged as best and which headline score determines whether a training run is considered an improvement. The metric choice should match your relevance labeling regime: MRR emphasizes first-hit speed, nDCG captures graded ordering quality across top-k, and MAP emphasizes precision across many relevant items. Overriding this can be useful for targeted experiments, but if changed too often it reduces comparability across historical runs.

`RERANKER_TRAIN_RECOMMENDED_METRIC` is the auto-selected north-star ranking metric that the training system uses by default to summarize model quality for this corpus. Under the hood, the recommendation should be driven by label structure (single relevant item vs multiple relevant items vs graded relevance), so the selected metric reflects the actual retrieval objective instead of a generic score. This is important for implementation consistency: using one stable primary metric across runs keeps checkpoint selection, dashboards, and regression alerts aligned, and prevents metric switching from masking performance regressions on real queries.

`RERANK_BACKEND` selects which reranking engine is used after initial candidate retrieval and fusion, effectively deciding where the relevance model executes (hosted API, local model runtime, or disabled path). Implementation-wise this affects latency profile, token/input limits, operational cost, and failure modes: cloud backends usually offer strong model quality with network dependency, while local backends trade setup complexity for tighter control and offline capability. Keeping this setting explicit is important for reproducibility, because evaluation scores and production behavior can shift materially when backend model families, truncation behavior, or inference constraints differ.

`RERANK_INPUT_SNIPPET_CHARS` caps how many characters from each retrieved chunk are forwarded into reranker scoring. In implementation terms, this is a throughput and quality guardrail: smaller snippets reduce request size and latency, but risk truncating decisive evidence; larger snippets preserve context at the cost of higher tokenization load, longer inference, and potentially provider-side input-limit errors. The right value should be based on corpus structure and query style, then validated with offline ranking metrics plus p95 latency and cost tracking so you can find the smallest snippet size that preserves relevance quality.

Toggles hot-reload behavior when the reranker model path changes at runtime. In development this shortens iteration loops because newly trained adapters can be activated without restarting the service. In production, uncontrolled auto-reload can introduce jitter, temporary cache invalidation, and model consistency issues across replicas. If enabled, pair it with health checks and staged rollout logic so reload events do not degrade retrieval latency or answer stability.

Legacy alias for `TRIBRID_RERANKER_RELOAD_ON_CHANGE`. When enabled, the service reloads reranker artifacts after path/config changes without a full process restart. This shortens iteration time and can reduce deployment friction, but reload behavior must be atomic: load into a shadow instance, run health checks, then swap pointers only on success. Without atomicity, mid-request model swaps can produce inconsistent scores. In production, pair this flag with file-watch debounce, checksum validation, and structured reload events so rollbacks are safe and observable.

Selects where second-stage relevance scoring runs: disabled, local learning reranker, or external cloud reranker. Backend choice changes both ranking behavior and operational constraints, because cross-encoder reranking improves precision but adds per-query compute and latency. Cloud backends usually provide stronger out-of-the-box quality, while local backends give tighter cost control, privacy, and reproducibility. Treat this as an evaluation knob: compare answer accuracy, NDCG/Recall@k, and p95 latency on the same query set before standardizing one backend.

Inference micro-batch size for reranker scoring over candidate documents. Larger batches can increase throughput and reduce per-item overhead on GPU, but memory pressure grows quickly with longer inputs and higher top-N. If this value is too aggressive you will see OOMs, allocator fragmentation, or latency spikes from retries and paging. Production tuning should sweep batch size jointly with max sequence length and candidate count, because these three parameters multiply into total token compute.

Batch size for inference-time reranking. Larger batches improve hardware utilization and reduce per-item overhead, but increase peak memory and can raise tail latency if queues back up. Smaller batches reduce memory pressure and can improve responsiveness for interactive workloads, but may lower throughput. Tune this parameter against your real document-length distribution, not synthetic short text, because sequence length and batch size interact multiplicatively in transformer memory usage. For production, pair with dynamic batching windows and per-request latency SLOs.

Maximum token budget for each query-document pair at rerank time. This parameter directly controls truncation behavior: small values improve speed and memory, while large values preserve long-context evidence at higher cost. For code and technical retrieval, quality gains usually plateau after a certain length unless queries depend on long-range context. Evaluate max length using long-tail queries, because overly short truncation tends to hide failures that only appear on long files and verbose documentation.

Maximum token length for each `(query, candidate)` pair passed to the reranker at inference time. This value directly controls memory cost and latency, and indirectly affects ranking quality because aggressive truncation can remove decisive evidence near the end of long passages. For code search, moderate lengths often work well because relevant signals are concentrated around function signatures or nearby comments; for policy or documentation corpora, you may need a larger ceiling. Tune together with chunk size and overlap so that important evidence lands inside the reranker window instead of being truncated away.

Global switch for reranking behavior, typically `none`, `learning`, or `cloud`. Use `none` for lowest latency baselines, `learning` for locally trainable behavior, and `cloud` for managed cross-encoder quality with external dependencies. Because this mode changes the scoring path after retrieval, it can change user-visible answers even when retrieval is identical. Lock this setting per environment and benchmark each mode against shared evaluation sets before promoting to production.

Maximum wait time for cloud reranker requests before failing fast. This parameter protects end-to-end request latency and prevents queue pileups during provider slowdowns, but setting it too low can create false negatives under transient network variance. Tune timeout with retry policy and user-facing SLA in mind; timeout alone is not enough without fallback strategy (for example, use first-stage ranking when reranker times out). Track timeout rate by provider/model so you can distinguish systemic misconfiguration from temporary upstream degradation.

Upper bound on how many retrieved candidates are passed into the reranker stage. Higher Top-N usually improves recall headroom because more borderline candidates are reconsidered, but reranker cost grows roughly linearly with this value. If set too low, relevant documents never reach reranking; if set too high, latency and GPU utilization can explode for little quality gain. Choose Top-N by plotting quality-latency curves and selecting the smallest value that keeps recall stable on hard queries.

Legacy alias for TRIBRID_RERANKER_TOPN. This setting controls how many fused retrieval candidates are forwarded into the reranker stage, where a heavier model re-evaluates relevance using richer query-document interactions. Higher values can improve final ranking quality on ambiguous or multi-intent questions because the reranker sees a wider candidate pool, but latency and inference cost usually scale with this number. In practice, tune this with an evaluation set: if top results are often "nearly right" but miss exact intent, increase Top-N; if quality plateaus while response time rises, lower it. Keep Top-N high enough to preserve recall before reranking, but not so high that reranking dominates end-to-end p95 latency.

`RERANKER_TRAIN_MAX_LENGTH` is the explicit training-example token ceiling for reranker fine-tuning, and it controls how much joint query-context evidence the model can score in one forward pass. For this codepath, larger values can improve relevance discrimination on long passages, but they also increase per-step compute, reduce feasible batch size, and can force heavier gradient accumulation to stay within memory limits. Use it with a measurement loop: watch training throughput, memory headroom, and validation ranking metrics together, because pushing max length without enough optimization budget often slows training more than it improves retrieval quality.

Whether to clear previously mined triplets before a new mining run. Enabling reset gives a clean dataset snapshot and avoids mixing stale and fresh negatives, which is useful for controlled experiments. Disabling reset preserves historical data and can improve coverage, but it also increases the risk of drift and duplicate/noisy samples. Use this setting with explicit dataset versioning so you can reproduce training results and roll back when mining quality drops.

Controls whether previously mined triplets are deleted before starting a new mining run. Enabling reset gives a clean dataset boundary, which is useful for reproducible experiments and preventing old sampling bias from contaminating new runs. Disabling reset accumulates data over time, which can improve coverage but risks drift and duplicate-heavy training sets. In production pipelines, snapshot the prior triplet file before reset and log the run ID, commit SHA, and mining parameters so you can audit exactly what data was used to train each model version.

Number of training examples processed per optimization step during learning-reranker fine-tuning. Larger batches can improve gradient stability and throughput on strong hardware, but they increase memory pressure and can destabilize local/containerized setups if oversized. Smaller batches are safer for constrained environments and can be paired with gradient accumulation to emulate larger effective batch sizes. Tune batch size together with learning rate and sequence length, since all three interact with convergence speed and overfitting risk.

Defines how many full passes over the reranker training dataset are executed. More epochs can improve fit on stable, representative triplets, but excessive epochs on small or noisy data usually reduce generalization and hurt real query performance. Use held-out validation queries and early stopping signals rather than only training loss to choose this value. As your mined data grows or distribution shifts, retune epochs because the optimal point moves with dataset size and difficulty.

Learning rate for reranker fine-tuning updates. It controls update magnitude and is often the highest-impact training hyperparameter: too high causes unstable loss and catastrophic drift, too low undertrains and wastes epochs. Choose LR jointly with batch size, adapter rank, and warmup schedule, and validate using ranking metrics rather than loss alone. For reranker adaptation, conservative starting values with short sweeps are usually safer than aggressive defaults.

`RERANKER_TRAIN_MAXLEN` sets the tokenizer-level cap used when building reranker training pairs, so every query-document pair is truncated to this maximum length before it reaches the cross-encoder. In implementation terms, this is one of the strongest memory controls in the training loop because self-attention cost grows roughly with sequence length squared; increasing this value can quickly push GPU/MLX memory over the limit and trigger OOM exits. In practice, treat this as a budget knob: start lower for stability, then raise only if error analysis shows that relevant evidence is being cut off and ranking quality is bottlenecked by truncation rather than model capacity.

Negative-sampling policy used when generating triplets for reranker training. Random negatives are stable but often weak; semi-hard negatives improve discrimination without overwhelming optimization; hard negatives are highest signal but can inject false negatives and noise if mining quality is low. The right mode depends on corpus ambiguity and label fidelity, so teams typically stage mining as a curriculum (random to semi-hard to hard) with periodic audit sets. Treat this as a data-quality lever first and a model-quality lever second.

Legacy alias for triplet mining strategy selection (`random`, `semi-hard`, `hard`). This setting controls the difficulty of negative examples used to train the reranker. `random` negatives are fast but often too easy; `hard` negatives maximize discrimination pressure but can inject label noise and instability; `semi-hard` is usually the best production default because it balances signal strength and training robustness. Treat mining mode as a data curriculum parameter and re-evaluate it whenever your corpus changes materially.

`RERANKER_WARMUP_RATIO` defines what fraction of total optimization steps uses a gradual learning-rate ramp before entering the main scheduler phase. In this training stack, warmup protects early updates when the reranker head and backbone are still unstable, reducing gradient spikes and divergence risk that can otherwise corrupt the first checkpoints. Operationally, this value interacts with total step count: short runs need a smaller warmup fraction so useful learning starts early, while longer runs can tolerate a larger warmup to improve stability. Tune it together with batch size and base LR, because warmup that is too short can destabilize training, while warmup that is too long can waste compute on underpowered updates.

BASELINE_PATH is where evaluation baselines are stored so retrieval and generation changes can be compared to a stable reference over time. A strong baseline captures both quality metrics and operational behavior, including ranking quality, grounding rate, latency, and abstention behavior. Store immutable run identifiers with dataset version and config hash so regressions can be traced to exact parameter changes. Without baseline discipline, tuning often produces short-term wins on narrow queries while silently degrading difficult slices that matter in production.

Selects the baseline run used for before versus after comparison so changes are interpreted causally instead of anecdotally. Good comparisons require the same dataset, similar traffic assumptions, and a captured config snapshot for both runs; otherwise score deltas are hard to trust. Use this diff to isolate which parameter changes correlate with quality movement and latency shifts. In practice, this is the fastest way to confirm whether a tuning experiment actually improved retrieval quality or just moved metrics around.

This view is where run-level metrics become actionable diagnosis. It should connect aggregate scores such as Hit@K and MRR to per-question traces, retrieved contexts, and model outputs so regressions can be explained instead of merely detected. The most useful workflow is to segment failures by retrieval miss, ranking miss, or generation miss, then map each bucket to a config change. Treat this tab as the decision surface for promotion or rollback of RAG configuration updates.

Controls whether evaluation uses multi-query expansion, where one prompt is rewritten into several retrieval queries to improve recall under wording variation. Enable this when production also uses multi-query, otherwise eval results can be overly optimistic or pessimistic compared with real traffic. The gain usually comes from broader evidence discovery, but cost and latency scale with rewrite count and dedup work. Measure marginal benefit per extra rewrite and stop when added queries no longer improve quality.

Streams execution details for each evaluation item so run outcomes can be audited and reproduced. Useful logs include rewritten queries, retrieved document identifiers, ranking scores, latency breakdowns, and any fallback path chosen by the system. This visibility is critical when a summary metric drops but the failure mode is unclear. Persisting these logs with run IDs and config hashes turns the terminal from a debugging aid into durable evaluation evidence.

Golden path points to the curated evaluation file used for repeatable quality checks. This dataset should represent real user intents and include expected retrieval or answer signals so regressions are detectable after any model or retrieval change. Treat it as versioned test data and expand it when new failure modes appear in production. Run it automatically during configuration and model rollout workflows to prevent silent quality drift. A disciplined golden set is the fastest way to compare fusion, chunking, and model changes on equal ground.

Score bias applied to backend and data-access layers when intent classification indicates retrieval, API, indexing, or storage questions. It improves ranking for service, route, and data pipeline code when users ask how the system fetches or transforms information. Because this weight can overpower semantic relevance, tune it with side-by-side evaluations on UI and backend query slices to avoid over-routing everything to server code. In well-structured repos, this parameter is a high-leverage control for making architectural answers faster and more precise.

Master toggle for emitting runtime metrics from the application. When enabled, the process publishes counters, gauges, and histograms used for dashboards, alerting, and SLO tracking; when disabled, you lose quantitative visibility into throughput, error rates, latency distributions, and retrieval quality trends. Enable this in any shared or production-like environment, then gate high-cardinality labels to control cost. The goal is not just observability but fast diagnosis: metrics should let you correlate parameter changes (retrieval thresholds, rewrites, model routing) with concrete performance and reliability shifts.

Identifies the run treated as the current or after system state in analysis. All charts and comparisons should resolve from this immutable run record, including config snapshot, dataset version, and code revision. Without a clearly defined primary run, metric interpretation drifts and rollback decisions become ambiguous. Operationally, this key anchors evaluation governance by making one run the explicit source of truth for release decisions.

`RUN_EVAL_ANALYSIS` triggers the end-to-end evaluation pass for the current RAG configuration, executing the full question set through retrieval, reranking, and answer generation, then computing aggregate quality metrics. From an implementation perspective, this is the guardrail step that turns configuration changes into measurable evidence: it should produce repeatable run artifacts (scores, traces, and run metadata) so regressions can be diagnosed instead of guessed. Use it whenever retrieval weights, reranker settings, chunking, or prompt strategy changes, and interpret results slice-by-slice rather than only by one global average so failures on difficult query classes are not hidden.

Determines how many evaluation questions are executed in a run, trading speed for statistical confidence. Small samples are useful for rapid iteration but have higher variance and can mask edge-case regressions; larger samples stabilize ranking and generation signals before release. Use fixed seeds and stable sampling policy so repeated quick runs remain comparable. A strong workflow is quick sampled checks during tuning, followed by full-suite confirmation before shipping configuration changes.

This temperature is used for direct chat turns with no retrieval context attached. It is intentionally independent from retrieval-mode temperature so you can keep grounded answers conservative while allowing freer ideation in non-retrieval conversation. In deployment terms, this split lets you run two sampling policies inside one chat product: evidence-constrained behavior for grounded questions and creativity-oriented behavior for open-ended drafting. Recommended practice is to validate no-retrieval temperature with prompt categories that do not need factual anchoring (brainstorming, rewriting, tone variation) and keep guardrails strong for policy-sensitive topics where higher randomness can increase unsafe or inconsistent outputs.

Advanced RAG tuning controls how lexical, vector, reranker, and metadata signals are combined after initial retrieval. This is where you adjust fusion weights, score bonuses, candidate expansion, and iteration limits, so small changes can move hit-rate and latency in opposite directions. Treat these parameters as an evaluation loop: freeze a representative query set, change one knob at a time, and compare recall at k, ranking quality, grounded answer rate, and p95 latency against baseline. If weighting is too aggressive, one signal dominates and recall collapses on edge cases; if too weak, ranking becomes noisy and expensive.

`ALERT_INCLUDE_RESOLVED` controls whether the alert pipeline emits a second notification when an incident transitions from firing to resolved. In this stack, keeping it enabled (`1`, default) gives on-call responders explicit closure signals, which helps reconcile incident timelines and downstream ticket automation. Disabling it (`0`) reduces message volume but removes recovery-state visibility, so unresolved-looking alerts can persist in chat channels or incident tools even after the condition clears. Use `1` when you rely on auditability and MTTR measurement, and only disable it if notification fatigue is materially harming response quality.

`ALERT_NOTIFY_SEVERITIES` is the final severity allowlist applied before outbound notification fan-out, using a comma-separated vocabulary such as `critical,warning`. The configured values must match the exact severity labels emitted upstream, otherwise valid alerts can be silently filtered out at dispatch time. With the default `critical,warning`, the system typically captures high-urgency incidents while limiting low-signal noise; adding `info` expands coverage but increases paging and webhook traffic. Treat this setting as an operations policy control: tune it against real incident outcomes, not just raw alert counts.

ALERT_WEBHOOK_TIMEOUT defines how long the system waits for an outbound alert webhook before treating delivery as failed. In RAG operations this prevents indexing, tracing, or incident pipelines from stalling when third-party endpoints degrade. Set it from real latency percentiles: high enough for normal network jitter, low enough to preserve queue health and fast failure detection during outages. This value works best with idempotent payloads, retry backoff, and dead-letter handling so timeouts become controlled recovery signals instead of duplicate alert storms.

CHAT_CONFIDENCE_THRESHOLD sets the minimum confidence required before returning a normal answer path instead of fallback or abstention. Raising this threshold reduces unsupported responses and improves precision, but increases abstains and can make the assistant feel less responsive. Lowering it improves answer coverage while increasing the risk of weakly grounded outputs. Select the threshold from precision-recall tradeoffs on your own workload, and use stricter values for high-risk intents where incorrect answers are expensive.

AST_OVERLAP_LINES sets how many source lines are repeated between adjacent syntax-aware chunks when code is segmented by AST boundaries. Overlap preserves boundary context such as imports, signatures, decorators, and class state that might otherwise be split and become harder to retrieve. Too little overlap reduces recall on cross-boundary queries; too much overlap bloats the index, increases near-duplicates, and can bias scoring toward repeated context. Start with a small overlap and tune using real code-search prompts that depend on boundary continuity, then track recall improvement versus index growth and latency.

Automatically derives routing and retrieval keywords from repository content so the system can bootstrap sparse relevance signals without full manual curation. In RAG this is especially useful for new repos or rapidly changing codebases where static keyword lists become stale. A strong auto-generation pipeline should normalize identifiers, remove boilerplate terms, and preserve domain-specific phrases that improve query-to-repo routing. Treat generated keywords as a candidate set that can be audited and refined, not as immutable truth. Quality usually improves when automatic extraction is combined with a small manually maintained allowlist and blocklist.

Automatically indexes conversation turns into the Recall corpus after responses complete, enabling retrieval over prior chat content. This converts conversational history into searchable artifacts so later turns can recover earlier decisions, constraints, and unresolved threads. Auto-indexing improves continuity but can add background load and memory noise if every turn is stored verbatim. In production, combine it with retention rules, deduplication, and evaluation sets that test both immediate follow-up recall and long-session drift to ensure memory helps more than it distracts.

Controls whether Crucible automatically launches a browser tab when the local server starts. It improves developer ergonomics in interactive desktop workflows, but should normally be disabled for CI, SSH sessions, containers, and remote hosts where GUI launch attempts are noisy or impossible. Keep this off in production-like startup scripts to avoid side effects and process-blocking behavior. In short: enable for local convenience, disable for automation and infrastructure.

TRACE_AUTO_LS controls whether the UI should automatically open a LangSmith run view after request completion. It does not change retrieval quality directly, but it changes debugging speed by reducing the friction between an anomalous response and its trace evidence. Keep it enabled in active tuning sessions where fast trace inspection matters, and disable it in high-throughput workflows where constant context switching is distracting. If this flag is enabled while external tracing is disabled, the expected behavior should degrade gracefully to local trace views rather than broken deep-links.

AUTO_COLIMA controls whether local runtime automation should start Colima when container dependencies are required but not already running. This is useful for RAG development setups that rely on local vector databases, model services, or ingestion workers in Docker-compatible containers. Enabling it reduces manual setup friction and failed starts, but can hide resource costs if virtualization launches unexpectedly on constrained laptops. Keep it enabled for full-stack local workflows and disabled in managed environments where process lifecycle is controlled by external orchestration.

CHAT_AUTO_SCROLL controls whether the interface automatically follows newly streamed tokens and messages. Enabling it improves live readability for active back-and-forth use, but can interrupt users who are reviewing earlier citations, logs, or traces while a response is still streaming. In RAG interfaces this tradeoff directly affects trust workflows, because users often need to inspect evidence while generation continues. A strong behavior pattern is auto-scroll by default with pause-on-user-scroll, so real-time flow and manual review both remain usable.

CARD_BONUS controls how much score uplift is applied when a result aligns with card-level semantic summaries. This acts as a prior that high-level module intent should influence final ranking alongside lexical and dense evidence. A moderate bonus can lift architecturally relevant chunks that otherwise rank too low; an excessive bonus can overpower direct evidence and drift results toward generic summaries. Calibrate the bonus using grounded answer metrics and citation quality, not only top-k retrieval gain.

CARDS_MAX sets how many semantic summary cards are loaded as auxiliary evidence during ranking. Increasing this value can improve coverage for architecture and feature-discovery questions, but it also introduces candidate noise and additional latency if too many weakly related cards are considered. Lower values keep ranking focused and faster, but can miss long-tail modules that only surface in summaries. Tune this limit by query segment and measure both grounded-answer quality and p95 latency so card coverage does not overwhelm precision.

Represents the combined control surface for chat behavior: model choice, retrieval parameters, generation limits, and reasoning options. These settings should be treated as a coupled system rather than independent toggles, because changes in one area often shift quality or latency elsewhere. For example, increasing retrieved context may require lower output limits or different prompts to keep responses focused. The most reliable way to tune this bundle is benchmark-driven iteration against your real tasks, with clear measurements for answer quality, citation quality, latency, and cost.

CHAT_HISTORY defines how conversation context is persisted and restored across sessions. Persistent history improves follow-up quality and reduces repeated setup, but it also expands privacy responsibilities because prompts, retrieved passages, and outputs may contain sensitive information. If storage is browser localStorage, treat it as convenience persistence, not secure archival storage, and provide clear controls for clearing or disabling history. Retention policy and visibility should be explicit so users understand what context is remembered and why.

Enables token-by-token delivery instead of waiting for a complete response. Streaming reduces perceived latency and gives users immediate feedback, which is especially useful when retrieval and reasoning steps produce longer answers. It also changes system design requirements: your frontend and gateway must support incremental events, cancellation, and partial-output rendering. If your deployment path does not reliably support SSE-style transport, disabling streaming can simplify operations at the expense of slower perceived responsiveness.

GRAPH_CHUNK_ENTITY_EXPANSION_ENABLED controls whether chunk retrieval expands through entity-to-chunk relationships after initial seed hits are found. Enabling it usually improves recall on questions where relevant evidence is distributed across files that mention the same functions, classes, or symbols but are not textually similar. The tradeoff is a larger candidate set, higher latency, and possible semantic drift when entity extraction is noisy. This works best when entity linking quality is good and graph edges are corpus-scoped, and it is less helpful when the graph is sparse or inconsistent. Treat it as a recall lever that should be tuned together with max hops, expansion weight, and graph top-k.

GRAPH_CHUNK_ENTITY_EXPANSION_WEIGHT sets how strongly entity-expanded chunks influence final graph candidates relative to original seed chunks. Lower values keep rankings anchored to direct semantic matches, while higher values favor graph-discovered neighbors that may add cross-file context. In production, this is usually a calibration setting rather than a one-time constant, because optimal values differ by query type and graph quality. If set too high, hub entities can dominate and reduce precision; if too low, expansion has little practical effect and recall gains disappear. Evaluate this setting on judged queries using both retrieval metrics and grounded answer quality, not retrieval metrics alone.

GRAPH_CHUNK_NEIGHBOR_WINDOW defines how many adjacent chunks around each seed chunk are included through NEXT_CHUNK style links. This improves local coherence by pulling surrounding code or prose that often contains signatures, setup, and constraints needed for correct answers. Small windows usually increase answer quality with modest cost, while large windows quickly add repetitive context and token overhead. The ideal value depends on your chunk size and overlap strategy: smaller chunks typically benefit from a slightly larger neighbor window. Tune it by tracking grounded answer rate and prompt-token growth together so recall gains do not come from avoidable context inflation.

Specifies how much content is repeated between adjacent chunks. Overlap reduces boundary loss by ensuring entities, arguments, or code flow that cross a split still appear in at least one retrievable unit. Too little overlap hurts recall near chunk edges; too much overlap bloats the index, increases embedding cost, and can bias retrieval toward duplicated text. The right value depends on document structure and query style, so measure retrieval hit quality and index growth together rather than tuning overlap in isolation.

GRAPH_CHUNK_SEED_OVERFETCH determines how many extra seed candidates are fetched before corpus-level filtering or later-stage pruning is applied. In shared graph infrastructure, overfetching is often required because early ranking runs across more data than the target corpus and many candidates are removed downstream. If this multiplier is too low, final candidate sets can be underfilled and recall drops sharply on selective corpora. If it is too high, query cost and latency increase with little quality benefit. A practical approach is to monitor candidate survival rate after filtering and set overfetch so expected survivors consistently exceed your graph top-k target.

Sets the target size of each chunk before embedding. Larger chunks preserve more local context and can help complex synthesis, but they reduce granularity and may retrieve irrelevant text; smaller chunks improve precision and reranking flexibility but risk fragmenting meaning. In code and technical corpora, chunk size should be tuned with overlap, tokenizer behavior, and model context limits as a single budget problem. The best value is empirical: run retrieval evaluations on your actual question set and choose the smallest size that preserves answer completeness.

Controls whether chunk summaries are generated with richer, model-assisted metadata by default. Enriched summaries can add intent, entities, API surface hints, and semantic cues that improve retrieval and reranking beyond raw embeddings alone. The trade-off is higher indexing cost and longer build times, especially on large repositories. Enable enrichment when search quality and explainability matter more than ingestion speed, and disable it for rapid iteration pipelines where you need frequent low-cost reindexing.

Additive weight applied after score fusion when a hit came from chunk-summary retrieval instead of raw chunk text. In practice this controls whether conceptual matches such as intent, behavior, or API purpose can compete with exact-token matches from code. Raise it when summaries are high quality but consistently rank below noisy lexical matches; lower it when vague summaries outrank precise chunks and hurt answer grounding. Tune this together with your fusion method and evaluation set, because the same numeric bonus has very different effects depending on score normalization and corpus size.

Defines how source content is segmented before embedding and indexing, which is one of the highest-impact choices in a RAG pipeline. Syntax-aware strategies preserve logical units like functions or classes and usually improve precision for code queries, while simpler fixed or greedy splits are faster and more robust for mixed or noisy inputs. Hybrid strategies often perform best operationally because they retain structure when parsing succeeds and fall back gracefully when it does not. Any strategy change should trigger reindexing and evaluation because embeddings, recall patterns, and reranker behavior all shift together.

Maintenance action that removes generated Python bytecode caches to force modules to be recompiled on next import. This helps resolve stale-module behavior after refactors, branch switches, or path changes where cached artifacts can mask current source behavior during local development. It is generally safe because only derived cache files are removed, not source files or dependency environments. In RAG service development, clearing bytecode is a practical reset step before retesting backend reload or import-related failures.

Applies language-aware formatting to fenced code blocks in chat responses. This does not change model quality directly, but it strongly affects human review speed and error detection in code-focused RAG workflows. Highlighting is most valuable when answers include multi-file patches, stack traces, or mixed-language snippets, because visual structure makes semantics easier to scan. The main trade-off is rendering overhead on very long transcripts, so teams handling large streamed outputs often combine highlighting with virtualized rendering and selective expansion.

Code cards are enriched semantic representations of chunks that capture purpose, main symbols, side effects, and likely usage context in a compact form. They act as a retrieval-friendly abstraction layer: dense and hybrid retrievers can match the card text when raw source is too low-level or verbose for the user query. High-quality cards improve intent routing, candidate filtering, and explanation quality during answer generation. Because cards are derived artifacts, they should be regenerated when major code changes occur so retrieval stays aligned with current behavior.

INDEXING is the end-to-end process that converts raw corpus files into retrieval-ready artifacts such as chunks, sparse signals, dense vectors, and optional graph structures. It is corpus-scoped, so each corpus can have distinct embeddings, tokenization behavior, and graph topology. Most quality-affecting changes to chunking, embedding models, and sparse analyzers require reindexing before they influence query results. In practice, indexing quality determines the ceiling for retrieval quality, while query-time tuning only reshapes what indexing already captured. Treat indexing as a reproducible pipeline with versioned settings so retrieval behavior is explainable across releases.

Named Colima VM profile used when local container orchestration is auto-managed. Profiles let you isolate Docker runtime settings such as CPU, memory, disk, architecture, and Kubernetes enablement for different workloads, which is useful when RAG indexing, database services, and inference tasks compete for resources. Setting the profile explicitly improves reproducibility across machines and avoids accidental coupling to a default profile tuned for another project. When startup or runtime behavior is inconsistent, profile drift is one of the first things to check.

INCLUDE_COMMUNITIES enables community-level graph expansion, allowing retrieval to include nodes that are topologically related even when direct edges to seeds are limited. This is particularly helpful for broad architectural or subsystem questions where relevant evidence is distributed across many entities. The tradeoff is that community expansion can increase thematic noise for narrow fact queries, so it should be paired with stricter reranking and context limits. Community detection quality strongly affects outcomes, making graph construction and clustering parameters part of retrieval quality control. Use this setting when recall across related modules matters more than strict locality.

Safety-net confidence gate: proceed when at least one candidate clears this threshold, even if aggregate gates fail. It is designed to reduce false abstentions when retrieval returns one strong hit plus several weak ones, which is common in sparse or highly specific technical queries. Setting it too low increases hallucination risk by allowing weak singleton matches; setting it too high cancels its rescue value and causes unnecessary rewrites or no-answer outcomes. Tune it using failure analysis that separates true misses from ranking noise.

Average confidence over the top five candidates, used as a stability gate before accepting retrieval or triggering rewrite loops. Compared with top-1 thresholds, this metric is less sensitive to one lucky match and better reflects whether the candidate set is broadly usable for grounded generation. Raising it improves answer reliability but increases rewrite frequency and cost; lowering it reduces retries but can pass low-coherence sets into generation. Use it as your main control for balancing relevance quality against latency and token spend.

Primary acceptance gate for the best-ranked candidate. If the top result exceeds this threshold, the system can short-circuit additional rewrite or expansion steps, reducing latency and cost. Lower values increase answer rate but make the system more likely to trust brittle single hits; higher values enforce stricter precision and can over-trigger retries. The best operating point depends on your tolerance for false positives versus abstentions, so tune with labeled evals rather than intuition.

Reports runtime health of service containers as `running/total`, giving a quick signal for partial outages and startup drift. This value is most useful when combined with health probes: a container can be running but still unready, degraded, or failing dependencies. Use the metric to distinguish control-plane issues (containers not up) from application issues (containers up but unhealthy). In incident response, this row should be read alongside logs and readiness checks, not as a standalone pass/fail.

Shows which corpus is currently active, which is effectively your retrieval boundary and isolation unit. Corpus selection determines which embeddings, sparse indexes, graph nodes, and metadata filters participate in search. A wrong active corpus often looks like 'the model got worse' when the real issue is cross-dataset mismatch or stale index scope. In multi-tenant or multi-project setups, this indicator is critical for preventing accidental cross-context retrieval and for auditing data separation.

Provides the top-level instruction contract that shapes the assistant’s behavior across every turn. In RAG systems, this is where you encode non-negotiable rules such as citation requirements, abstention behavior for low-confidence retrieval, formatting expectations, and scope boundaries. Small prompt edits can cause large behavioral shifts, so treat system prompts as versioned configuration with evaluation gates, not ad hoc text. Stable prompts plus measured rollout reduce regressions when you change models, retrieval strategy, or tool integrations.