Configuration System
Relevant source files
The following files were used as context for generating this wiki page:
The Configuration System in KnowledgeVault is a robust, environment-driven framework designed to manage the application's runtime behavior, external service integrations, and security parameters. It utilizes a hierarchical approach where settings are derived from environment variables, .env files, and hardcoded defaults, ensuring flexibility across development and production environments.
This system centralizes critical parameters for the RAG (Retrieval-Augmented Generation) pipeline, including LLM connection strings, vector search thresholds, and document processing strategies. It also enforces security boundaries by validating sensitive tokens and secrets during the application startup phase.
Sources: backend/app/config.py:1-20, README.md:1-50
Architecture and Data Flow
The configuration architecture is built on Pydantic's BaseSettings, which allows for type-safe validation and automatic casting of environment variables. The system acts as a single source of truth for both the backend FastAPI services and the frontend React application (via specialized API endpoints).
Configuration Loading Hierarchy
The system follows a specific precedence order when resolving configuration values:
- Environment Variables: Direct system environment variables (highest precedence).
- .env File: Key-value pairs defined in a local
.envfile. - Hardcoded Defaults: Sensible defaults defined within the
Settingsclass.
The diagram shows how configuration values flow from source to application components.
Sources: backend/app/config.py:25-30, INSTALLATION.md:350-400
Key Configuration Categories
LLM and Embedding Services
The project relies on external providers like Ollama or Harrier TEI for inference and vector embeddings. The configuration defines the endpoints and models used for these critical paths.
| Option | Type | Default | Description |
|---|---|---|---|
ollama_chat_url | string | http://host.docker.internal:11434 | Endpoint for chat LLM (Ollama). |
ollama_embedding_url | string | http://harrier-embed:8080/v1/embeddings | Endpoint for embeddings (TEI). |
chat_model | string | gemma-4-26b-a4b-it-apex | Primary chat model name. |
embedding_model | string | microsoft/harrier-oss-v1-0.6b | Primary embedding model. |
embedding_dim | integer | 1024 | Vector dimension for the embedding model. |
Sources: backend/app/config.py:38-55, README.md:120-150
RAG Pipeline and Retrieval
The system provides granular control over the retrieval process, including hybrid search weights and reranking thresholds.
- Hybrid Search: Combines BM25 (keyword) and dense vector search using Reciprocal Rank Fusion (RRF).
- Reranking: Utilizes a cross-encoder to refine top results after initial vector retrieval.
- Multi-Scale Indexing: Indexes chunks at multiple sizes (e.g., 768 and 1536 characters) to improve recall.
Sources: backend/app/config.py:115-150, backend/app/config.py:200-220
Security and Authentication
The configuration enforces strict security policies, especially regarding JWT secrets and admin tokens.
The diagram illustrates the mandatory security checks performed during the configuration initialization.
Sources: backend/app/config.py:615-635, INSTALLATION.md:550-580
Validation and Integrity Logic
The system includes complex validation logic to ensure the application does not start with invalid or insecure parameters.
Critical Validators
- Security Defaults: The
reject_insecure_defaultsmethod prevents the application from starting ifJWT_SECRET_KEYis left as the default or ifADMIN_SECRET_TOKENis missing while multi-user mode is enabled. - Resource Bounds: Validators like
validate_ingestion_queue_max_sizeandvalidate_memory_store_pool_sizeprevent resource exhaustion by enforcing minimum and maximum values for internal queues and connection pools. - Path Normalization: The
app_root_pathis normalized to handle deployments behind reverse proxies that strip prefixes.
@model_validator(mode="after")
def reject_insecure_defaults(self) -> "Settings":
"""Refuse startup if security-critical secrets use default values."""
if self.users_enabled and (not self.jwt_secret_key.strip() or self.jwt_secret_key == "change-me-to-a-random-64-char-string"):
raise ValueError("JWT_SECRET_KEY must be changed from the default when USERS_ENABLED=True.")
return self
Sources: backend/app/config.py:460-480, backend/app/config.py:615-625
API Integration
The configuration is exposed to the frontend and administrators via specific API routes.
Settings Endpoints
- GET
/api/settings: Returns the current runtime settings to the UI. This includes metadata about "effective sources" (whether a value came from a.envfile, environment variable, or default). - PUT
/api/settings: Allows authorized administrators to update specific settings (e.g.,chunk_size_chars,retrieval_top_k) at runtime. - GET
/api/settings/connection: A diagnostic endpoint that tests the connectivity between the backend and configured LLM/Embedding services.
Sources: frontend/src/lib/api.ts:250-320, README.md:380-400
Feature Flags and Subsystems
Several project subsystems are controlled via master switches in the configuration:
| Feature Flag | Default | Description |
|---|---|---|
wiki_enabled | True | Enables the Wiki / Knowledge Compiler subsystem. |
kms_enabled | True | Enables the Knowledge Management System for curated entries. |
hybrid_search_enabled | True | Toggles between pure vector search and hybrid vector+FTS search. |
users_enabled | True | Enables multi-user JWT authentication vs. single-admin mode. |
Sources: backend/app/config.py:328-350, backend/app/api/routes/wiki.py:30-40
Summary
The Configuration System is the backbone of KnowledgeVault's operational stability. By leveraging Pydantic's validation and a clear environment-based hierarchy, it provides developers with a safe and flexible way to tune the RAG pipeline. Its strict adherence to security validation at startup ensures that production deployments remain protected against common misconfigurations.