.env.example

# Core
PLUGIN_TYPE=generic
LOG_LEVEL=INFO

# RabbitMQ
RABBITMQ_HOST=localhost
RABBITMQ_USER=alkemio-admin
RABBITMQ_PASSWORD=alkemio!
RABBITMQ_PORT=5672
RABBITMQ_QUEUE=virtual-contributor-engine-generic
RABBITMQ_RESULT_QUEUE=virtual-contributor-invoke-engine-result
RABBITMQ_EVENT_BUS_EXCHANGE=event-bus
RABBITMQ_RESULT_ROUTING_KEY=invoke-engine-result

# ChromaDB
VECTOR_DB_HOST=localhost
VECTOR_DB_PORT=8765
VECTOR_DB_CREDENTIALS=
# Distance function for vector similarity: cosine, l2, or ip
VECTOR_DB_DISTANCE_FN=cosine

# Query embedding safety: the query adapter owns exactly these attempts. The
# standard OpenAI SDK query view has retries disabled; document ingestion keeps
# its frozen client/retry/backoff policy. Startup logs only these five values.
EMBEDDINGS_QUERY_MAX_UTF8_BYTES=32768
QUERY_REWRITE_MAX_UTF8_BYTES=4096
EMBEDDINGS_MAX_ATTEMPTS=3
EMBEDDINGS_ATTEMPT_TIMEOUT_SECONDS=20
EMBEDDINGS_TOTAL_DEADLINE_SECONDS=45

# LLM — provider-agnostic configuration
# Supported providers: mistral, openai, anthropic
LLM_PROVIDER=mistral
LLM_API_KEY=
# Default: mistral-large-latest / gpt-4o / claude-sonnet-4-6
LLM_MODEL=
# Set for local models (e.g., http://localhost:8000/v1)
LLM_BASE_URL=
# 0.0–2.0 (optional)
LLM_TEMPERATURE=
# >0 (optional)
LLM_MAX_TOKENS=
# 0.0–1.0 (optional)
LLM_TOP_P=
# Seconds
LLM_TIMEOUT=120

# LLM — backward compatibility (still works for Mistral)
MISTRAL_API_KEY=
MISTRAL_SMALL_MODEL_NAME=mistral-small-latest

# LLM — per-plugin overrides (optional, prefix with PLUGIN_NAME_)
# Example: GUIDANCE_LLM_PROVIDER=openai, GUIDANCE_LLM_API_KEY=sk-...

# Summarization LLM — optional separate model for document/BoK summarization
# All three required to activate; if any missing, main LLM is used
SUMMARIZE_LLM_PROVIDER=
SUMMARIZE_LLM_MODEL=
SUMMARIZE_LLM_API_KEY=
# Optional: base URL override for summarization (e.g., different port for a local model)
SUMMARIZE_LLM_BASE_URL=
# Optional tuning (defaults: temperature=0.3 when active, timeout=LLM_TIMEOUT)
SUMMARIZE_LLM_TEMPERATURE=
SUMMARIZE_LLM_TIMEOUT=

# BoK LLM — optional separate model for body-of-knowledge summarization
# Needs large context window. Falls back to summarize LLM, then main LLM.
BOK_LLM_PROVIDER=
BOK_LLM_MODEL=
BOK_LLM_API_KEY=
BOK_LLM_BASE_URL=
BOK_LLM_TEMPERATURE=
BOK_LLM_TIMEOUT=

# Per-plugin retrieval parameters
EXPERT_N_RESULTS=5
EXPERT_MIN_SCORE=0.3
# Hierarchical Expert retrieval is opt-in. Each eligible request runs Stage 1
# over overview/summary entries, keeps only specific subspace routes (a
# root-only route uses flat retrieval), then scopes detail to 1–3 branches.
# Keep false until the target collection has been re-ingested with hierarchy
# metadata and the human rollout gates are complete.
EXPERT_HIERARCHICAL_RETRIEVAL_ENABLED=false
EXPERT_HIERARCHY_MAX_BRANCHES=3
# Display names are separately opt-in and model-visible only after the RG-05P
# provider-processing gate. Retrieval scoping does not require disclosure.
# Set hierarchy retrieval false for flat retrieval; set this false independently
# to omit model-visible hierarchy names while scoped retrieval remains available.
EXPERT_HIERARCHY_DISPLAY_NAMES_ENABLED=false
GUIDANCE_N_RESULTS=5
GUIDANCE_MIN_SCORE=0.3

# Context budget — max chars of retrieved context passed to LLM
MAX_CONTEXT_CHARS=20000

# Optional answering-only controls (leave commented to preserve provider defaults)
# ANSWERING_LLM_TEMPERATURE=0.2
# ANSWERING_CHAIN_OF_THOUGHT_ENABLED=true
# Re-ranking — re-orders retrieved chunks by lexical overlap with the query
# before context assembly. OFF by default: it changes what every answer is
# grounded in. Disabling it restores prior behaviour exactly.
# Runs in-process with no network call and no extra dependency.
RERANK_ENABLED=false
# Candidates fetched when re-ranking is on (must be >= RERANK_TOP_K).
RERANK_CANDIDATE_N=20
# Candidates kept after re-ranking, passed to context assembly.
RERANK_TOP_K=5
# Lexical share of the blend: 1.0 is pure keyword, 0.0 is pure vector.
# 0.0 is the fine-grained rollback — ordering is provably unchanged while the
# stage stays wired. Keep above 0.5: at exactly 0.5 the blend cannot promote a
# chunk that matches the query's words but has the worst vector distance.
RERANK_LEXICAL_WEIGHT=0.6
# Adaptive routing — classifies each question and scales retrieval to it.
# OFF by default: it changes how much evidence every answer is built from, and
# can skip retrieval entirely for small talk. Classification is rule-based and
# runs in-process — no model, no network call, no extra dependency.
ROUTING_ENABLED=false
# Retrieval width for a direct lookup. Keep at or below RETRIEVAL_N_RESULTS so
# a simple query never becomes slower than it is today.
ROUTING_SIMPLE_N_RESULTS=3
# Width and budget for a comparative or multi-hop question. The budget must
# move with the width: at a 9000-char chunk size the default 20000-char budget
# admits only 2 chunks, so widening retrieval alone delivers the same context.
ROUTING_COMPLEX_N_RESULTS=10
ROUTING_COMPLEX_CONTEXT_CHARS=40000
# Faithfulness validation — logs a warning when an answer asserts something
# after retrieval returned NOTHING, which is the one case provably unsupported
# without a model or citations. Observation only: the answer a member receives
# is never changed, delayed, or withheld. Runs in-process, no network call, no
# dependency. OFF by default.
FAITHFULNESS_VALIDATION_ENABLED=false

# Summarization threshold — docs with >= this many chunks get summarized
SUMMARY_CHUNK_THRESHOLD=4

# Embeddings (expert, guidance, ingest plugins)
EMBEDDINGS_API_KEY=
EMBEDDINGS_ENDPOINT=https://api.scaleway.ai/v1
EMBEDDINGS_MODEL_NAME=qwen3-embedding-8b

# Ingest pipeline
CHUNK_SIZE=2000
# Permitted range: CHUNK_SIZE 1-100000, CHUNK_OVERLAP 0 to CHUNK_SIZE/2
CHUNK_OVERLAP=400
# Runtime reads INGEST_BATCH_SIZE (BaseConfig.ingest_batch_size); a bare
# BATCH_SIZE is ignored and ingestion silently uses the code default of 5.
INGEST_BATCH_SIZE=20
SUMMARY_LENGTH=2500

# Health server
HEALTH_PORT=8080

# Ingest Space only
API_ENDPOINT_PRIVATE_GRAPHQL=http://localhost:3000/api/private/non-interactive/graphql
AUTH_ORY_KRATOS_PUBLIC_BASE_URL=http://localhost:3000/ory/kratos/public
AUTH_ADMIN_EMAIL=master-admin@alkem.io
AUTH_ADMIN_PASSWORD=master-password

# OpenAI Assistant only
RUN_POLL_TIMEOUT_SECONDS=300

# Ingest Website only
PROCESS_PAGES_LIMIT=20