Configuration

All runtime settings for every LIS 3 service live in a single root module, config.py. This page explains how configuration is loaded and lists the environment variables you can set, grouped by concern. See Installation for how to lay down a .env file.

How configuration works

config.py centralizes configuration for all services. Each service's local config.py imports the module-level singletons from the root module and re-exports them — no service defines its own settings independently.

The module defines two kinds of config objects:

• Seven pydantic-settings classes (DBConfig, AppConfig, EngineConfig, GatewayConfig, MemoryConfig, RAGConfig, ImageAnalysisConfig). These load from .env.shared, then .env, then the real OS environment.
• Two frozen pydantic models (STTConfig, TTSConfig). These are built explicitly from os.getenv(...) at import time.

All configs are instantiated as module-level singletons at import: DB_CONFIG, APP_CONFIG, ENGINE_CONFIG, GATEWAY_CONFIG, MEMORY_CONFIG, RAG_CONFIG, IMAGE_ANALYSIS_CONFIG, STT_CONFIG, TTS_CONFIG. VLM_CONFIG is an alias — it is the same object as IMAGE_ANALYSIS_CONFIG, not a copy.

Load order and precedence

For the seven settings classes, the shared SettingsConfigDict sets env_file=(".env.shared", ".env"), case_sensitive=False, and extra="ignore":

• .env.shared is read first, then .env overrides it for overlapping keys.
• Real OS environment variables override both files.
• Variable matching is case-insensitive; unknown keys are silently ignored.

All fields have defaults, so a fully unset environment still yields a working (localhost-oriented) config. Malformed numeric values for the STT/TTS helpers fall back to the default rather than raising.

note

STTConfig and TTSConfig are not settings classes — they are built from os.getenv(...) at import. As a result they read only real process environment variables and ignore .env / .env.shared. Env is read once at import time, so mutating os.environ afterward has no effect on any singleton.

Config classes

Class	Primary env prefix	Key settings
DBConfig	PG*, DB_POOL_MAX	Postgres host/db/user/password/sslmode/channel binding, pool size
AppConfig	LOG_*, CHAT_ENGINE_*, GATEWAY_*, IMAGE_ANALYSIS_*	Logging, aggregate host/port for engine/gateway/image-analysis, DB-on-startup flag
EngineConfig	mostly unprefixed shared vars (GUARD_*, LLM_*, RAG_URL, MEMORY_URL, TTS_*); CHAT_ENGINE_* for host/port/context	Guard, LoRA, LLM, RAG, image analysis, memory, TTS (+ OmniVoice fallback), context window, idle timeout, attachment path
GatewayConfig	CHAT_ENGINE_*, STT_WS_URL, TTS_WS_URL, GATEWAY_*	Upstream engine HTTP/WS, STT WS, single TTS WS, proxy timeout, API token, bind host/port
MemoryConfig	MEMORY_*	Memory LLM endpoint/token/timeouts, consolidation params, embeddings, transcript/injection budgets, dedup thresholds
RAGConfig	RAG_*, QDRANT_*	Query-rewrite LLM, embeddings, Qdrant, reranker, score floor/confidence, per-complexity token budgets
ImageAnalysisConfig	IMAGE_ANALYSIS_*, VLM_*	VLM model id/device, vLLM backend URL/timeout, image size/token limits, warmup image, allowed MIME types
STTConfig	STT_*	STT WS protocol constants, Whisper model/device, audio format, VAD/timing, decoding params
TTSConfig	TTS_*, SNAC_*, VLLM_*	TTS WS protocol, Orpheus + SNAC vLLM model, synthesis defaults/limits, SNAC token layout, built-in voices

Environment variables

The blocks below list the most common variables and their code defaults. Every variable is optional.

Ports and bind hosts

CHAT_ENGINE_HOST=localhost
CHAT_ENGINE_PORT=8050
GATEWAY_HOST=0.0.0.0
GATEWAY_PORT=8040
IMAGE_ANALYSIS_PORT=8012

Database

Connection is assembled from discrete libpq-style variables; there is no single connection-string variable.

PGHOST=localhost
PGDATABASE=lis
PGUSER=lis
PGPASSWORD=
PGSSLMODE=require
PGCHANNELBINDING=require
DB_POOL_MAX=10

Logging

LOG_LEVEL=INFO
LOG_FORMAT=%(asctime)s %(levelname)-8s %(name)s  %(message)s

LLM (conversation engine)

LLM_URL=https://core-llm.nezlamna-online.education/api/generate
LLM_MODEL=default
LLM_API_TOKEN=
LLM_TIMEOUT_SEC=120.0
LLM_TEMPERATURE=0.3
LLM_MAX_TOKENS=1024
GUARD_URL=http://localhost:4915/v1/chat/completions
GUARD_MODEL=Qwen/Qwen3Guard-Gen-0.6B
GUARD_TIMEOUT_SEC=5.0
LORA_CHECK_URL=https://core-llm.nezlamna-online.education/api/lora/check
LORA_CHECK_TIMEOUT_SEC=10.0
LORA_CHECK_API_TOKEN=

Gateway API key

GATEWAY_API_TOKEN=
GATEWAY_PROXY_TIMEOUT_SEC=120.0
CHAT_ENGINE_HTTP_URL=http://localhost:8050
CHAT_ENGINE_WS_URL=ws://localhost:8050/message_pipeline

External services

The engine, memory, and RAG services call these downstream endpoints. The gateway relays to a single TTS WebSocket (8014); the OmniVoice fallback (8015) exists only in the engine, so primary/fallback TTS selection is a conversation-engine concern.

RAG_URL=http://localhost:8051/retrieve
RAG_TIMEOUT_SEC=30.0
MEMORY_URL=http://localhost:8052
MEMORY_TIMEOUT_SEC=10.0
STT_WS_URL=ws://localhost:8010/ws/stt
TTS_WS_URL=ws://localhost:8014/ws/tts
TTS_TIMEOUT_SEC=60.0
TTS_OMNIVOICE_WS_URL=ws://localhost:8015/ws/tts
TTS_OMNIVOICE_TIMEOUT_SEC=120.0
IMAGE_ANALYSIS_URL=http://localhost:8012/analyze
IMAGE_ANALYSIS_TIMEOUT_SEC=15.0
VLM_BASE_URL=http://localhost:8013
VLM_BACKEND_TIMEOUT_SEC=30.0
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=
RAG_RERANKER_URL=http://localhost:8081
MEMORY_EMBED_URL=http://localhost:8016
RAG_EMBED_URL=http://localhost:8016

note

The embeddings service defaults to http://localhost:8016 in both MemoryConfig and RAGConfig (via MEMORY_EMBED_URL / RAG_EMBED_URL, legacy EMBED_URL).

Attachment storage

ATTACHMENT_STORAGE_BASE_PATH=./attachment_storage

Additionally, the TTS service reads voice data from <project_root>/data/voice_profiles.json and <project_root>/data/voice_prompt_cache.json (defined by the PATHS object, not env vars).

Legacy aliases

Many fields accept older environment names for backward compatibility, resolved via AliasChoices (the first present name wins; primary names take precedence over legacy fallbacks):

Primary	Legacy alias(es)
CHAT_ENGINE_HOST / CHAT_ENGINE_PORT	LIVE_HOST / LIVE_PORT
CHAT_ENGINE_HTTP_URL / CHAT_ENGINE_WS_URL	LIVE_HTTP_URL / LIVE_WS_URL
CHAT_ENGINE_CONTEXT_WINDOW	LIVE_CONTEXT_WINDOW
GATEWAY_HOST / GATEWAY_PORT / GATEWAY_PROXY_TIMEOUT_SEC	MAIN_HOST / MAIN_PORT / MAIN_PROXY_TIMEOUT_SEC
IMAGE_ANALYSIS_PORT	VLM_PORT
IMAGE_ANALYSIS_URL / IMAGE_ANALYSIS_TIMEOUT_SEC	VLM_URL, ORCH_VLM_URL / VLM_TIMEOUT_SEC, ORCH_VLM_TIMEOUT_SEC
IMAGE_ANALYSIS_MODEL_ID / IMAGE_ANALYSIS_DEVICE	VLM_MODEL_ID / VLM_DEVICE
MEMORY_LLM_* / RAG_LLM_*	shared LLM_ENDPOINT, LLM_API_TOKEN, LLM_TIMEOUT_SEC
MEMORY_EMBED_URL / RAG_EMBED_URL	shared EMBED_URL
LORA_CHECK_API_TOKEN	LLM_API_TOKEN

VLM_CONFIG is retained as an alias of IMAGE_ANALYSIS_CONFIG, and EngineConfig.vlm_url / vlm_timeout_sec are read-only properties mirroring image_analysis_url / image_analysis_timeout_sec.

Startup and auth flags

warning

Two settings change behavior at startup — set them deliberately:

• GATEWAY_API_TOKEN (default empty). When empty, gateway API-key authentication is disabled — every request is accepted. Set a non-empty token to enforce API-key auth in any shared or production deployment.
• ENABLE_DB_ON_STARTUP (default True). When true, the DB connection pool is opened at startup. Set it to false for local development without a running Postgres instance.

STT and TTS timing

STT timing fields accept a millisecond variable (e.g. STT_ENDPOINT_SILENCE_MS) or a legacy fallback, and the resolved value is floored to a documented minimum. Common STT/TTS defaults:

Setting	Env	Default
STT model	STT_MODEL_NAME	large-v3
STT device	STT_DEVICE	cuda
STT sample rate	STT_SAMPLE_RATE	16000
STT endpoint silence	STT_ENDPOINT_SILENCE_MS	0.65s (floor 0.2s)
STT max utterance	STT_MAX_UTTERANCE_MS	30.0s (floor 5.0s)
STT max concurrent sessions	STT_MAX_CONCURRENT_SESSIONS	4
TTS model	TTS_MODEL_ID	canopylabs/orpheus-3b-0.1-ft
SNAC codec model	SNAC_MODEL_ID	hubertsiuzdak/snac_24khz
TTS sample rate	TTS_SAMPLE_RATE	24000
TTS default voice	TTS_DEFAULT_VOICE_ID	tara
TTS GPU memory util	TTS_GPU_MEM_UTIL	0.4
TTS max concurrent synthesis	TTS_MAX_CONCURRENT_SYNTHESIS	1

Built-in TTS voices: tara, leah, jess, leo, dan, mia, zac, zoe.

note

The TTS backend on port 8014 is a self-hosted Orpheus + SNAC vLLM model. There are no ElevenLabs settings anywhere in config.py.