.env.example

COMPOSE_PROJECT_NAME=retrieval-agent
COMPOSE_DOMAIN=retrieval.local.itkdev.dk

# Required — must match RAG_EXTERNAL_RETRIEVAL_API_KEY in Open WebUI
API_KEY=change-me

# Qdrant connection. QDRANT_INDEX is the single physical collection populated
# by the external ingestion service (Phase 3 schema: payload.content +
# payload.meta.collection_name). The legacy QDRANT_COLLECTION_PREFIX /
# QDRANT_MULTITENANCY pair has been retired.
QDRANT_URI=http://qdrant:6333
QDRANT_API_KEY=
QDRANT_INDEX=ingestion_files

# Embedding — must match what the ingestion service used at index time.
# EMBEDDING_PREFIX_QUERY is the query-side prefix only (e5: "query: " on
# queries, "passage: " on documents; bge-m3: empty). Renamed from the older
# EMBEDDING_QUERY_PREFIX. Quote to preserve the trailing space.
EMBEDDING_MODEL=intfloat/multilingual-e5-large
EMBEDDING_API_BASE_URL=https://embed.itkdev.dk/v1
EMBEDDING_API_KEY=123456789
EMBEDDING_PREFIX_QUERY="query: "

# Hybrid search. Two paths depending on the configured collection:
#   * If it carries a `text-sparse` named vector, retrieval uses Qdrant's
#     native Query API with prefetch + RRF fusion (server-side). The sparse
#     query embedder runs in-process via fastembed — see SPARSE_QUERY_* below.
#   * If it doesn't, retrieval falls back to client-side BM25 RRF (scrolls the
#     filtered collection — only viable for small scopes).
ENABLE_HYBRID_SEARCH=false
HYBRID_BM25_WEIGHT=0.3
BM25_CACHE_TTL_SECONDS=300
BM25_MAX_DOCS=10000

# Sparse query embedder. Used only when ENABLE_HYBRID_SEARCH=true AND the
# configured collection has a sparse named vector. The model must match what
# the ingestion service used for sparse indexing. Set provider=none to
# disable the sparse stage cleanly (forces dense-only on the native path).
SPARSE_QUERY_PROVIDER=fastembed
SPARSE_QUERY_MODEL=Qdrant/bm42-all-minilm-l6-v2-attentions

# Cross-encoder reranking
ENABLE_RERANKING=false
RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2
RERANKER_API_BASE_URL=https://embed.itkdev.dk
RERANKER_API_KEY=
# How the cross-encoder ranking combines with the retrieval (dense/hybrid) ranking.
# rrf = Reciprocal Rank Fusion — keeps a strong dense hit the cross-encoder underranks
# (prevents the reranker from burying a top dense result). replace = cross-encoder
# score only (older behaviour). RERANK_RRF_K is the RRF constant (higher = flatter).
RERANK_FUSION=rrf
RERANK_RRF_K=60
INITIAL_RETRIEVAL_MULTIPLIER=3

# Query generation from messages (linear pipeline; agentic pipeline uses system prompt)
ENABLE_QUERY_GENERATION=true
# RETRIEVAL_QUERY_GENERATION_PROMPT_TEMPLATE — default (English) is built-in;
# the Danish example below shows how to override it. Placeholders use
# string.Template syntax: $current_date and $chat_history (no Python {}).
#
# RETRIEVAL_QUERY_GENERATION_PROMPT_TEMPLATE="### Retningslinjer for søgning:
# - Basér forespørgsler **udelukkende på brugerens spørgsmål og informationsbehov**.
#   Brug assistentens svar kun til kontekst og disambiguation (f.eks. til at forstå hvad
#   'det', 'den anden' refererer til).
# - Generér forespørgsler som naturlige sætninger der fanger den semantiske betydning af
#   brugerens informationsbehov.
# - Omformuler samtale-referencer ('det', 'den anden', 'hvad med') til selvstændige,
#   fuldstændige forespørgsler.
# - Hver forespørgsel skal dække en forskellig vinkel for at maksimere dækningen af
#   relevante dokumenter.
# - Hvis brugerens besked tydeligt ikke kræver dokumentsøgning (f.eks. hilsner), søg med
#   en tom liste.
# - Svar på samtalens primære sprog; brug dansk som standard."

# Agentic RAG
ENABLE_AGENTIC_RAG=false
AGENT_MODEL=gpt-4o-mini
AGENT_API_BASE_URL=http://litellm:4000/v1
AGENT_API_KEY=
AGENT_MAX_ITERATIONS=3
AGENT_TOOL_PREVIEW_CHARS=200
AGENT_STRICT_TOOLS=true
AGENT_TIMEOUT=60
# Agentic recall — decoupled from request.k (Open WebUI's top_k) so a small
# top_k doesn't starve the agent's grading pool. AGENT_FETCH_K is the
# internal candidate pool per query (vector + BM25 each). AGENT_PREVIEW_K
# bounds how many previews are sent back to the LLM per retrieve call to
# keep the agent's context window under control across iterations.
AGENT_FETCH_K=20
AGENT_PREVIEW_K=5
AGENT_CONVERSATION_HISTORY_MESSAGES=4
# Always run a deterministic retrieval pass with the user's original query
# (before the agent rewrites it) and merge it with the agent's own retrievals.
# Guards recall against query-rewrite drift, e.g. when an upstream
# RETRIEVAL_QUERY_GENERATION_PROMPT_TEMPLATE pushes keyword/web-search phrasing.
AGENT_INCLUDE_RAW_QUERY=true
# AGENT_SYSTEM_PROMPT="You are a retrieval specialist for a RAG system. Your job is to find the most
# relevant documents for a user's information needs by searching a vector database.
#
# ## Query Analysis Guidelines
# - Generate 1-2 search queries optimized for semantic vector search.
# - Base queries on the **user's questions and information needs only**. Use assistant
#   responses solely for context and disambiguation (e.g. resolving 'this', 'that',
#   'the one you mentioned').
# - Generate queries as natural-language phrases that capture the semantic meaning of the
#   user's information need.
# - Reformulate conversational references into standalone, self-contained queries.
# - If the user's message clearly needs no document retrieval (e.g. greetings, small talk),
#   call the retrieve tool with an empty list to signal no results needed.
# - Respond in the same language as the user's messages.
#
# ## Retrieval Strategy
# 1. SEARCH — call the retrieve tool with your optimized queries.
# 2. ACCEPT the results if **any** returned document is on-topic for the user's question,
#    even partially. Partial coverage is expected — the downstream LLM will synthesize
#    the answer.
# 3. RETRY only if the results are **completely off-topic** (none of the returned documents
#    relate to the query at all). Rewrite the query to be more specific and try again
#    (up to 3 attempts total). Do not retry just because the answer is not explicitly
#    stated — relevant context is enough.
#
# Keep queries concise and focused. Prefer a single well-crafted query over multiple
# overlapping ones."

# ----- Observability -----
# LOG_LEVEL is the primary verbosity dial (root logger; third-party libs
# follow it). At DEBUG you get resolved/generated queries, per retrieve-round
# agent queries, per-query candidate counts + top scores, the "N retrieve
# rounds (retry occurred)" line, per-step token usage, and the full LLM request
# payload (app.llm logger). The httpcore/openai DEBUG wire firehose is pinned to
# an INFO floor so DEBUG stays readable; httpx's "HTTP Request" INFO lines remain.
LOG_LEVEL=INFO
# Per-namespace override for the service's own loggers ('app.*'), applied on top
# of LOG_LEVEL. Set to DEBUG for verbose app logs (queries, scores, token usage,
# LLM payloads) without the third-party DEBUG flood (httpcore/httpx/openai).
# Empty inherits LOG_LEVEL.
LOG_LEVEL_APP=
# text = human-readable single line; json = one JSON object per line for Loki.
LOG_FORMAT=text
# Expose Prometheus counters/histograms at GET /metrics. Bearer-authenticated
# with the same API_KEY as /search (the scrape job must send the token). false
# → endpoint returns 404; instrumentation always runs regardless.
METRICS_ENABLED=true

# Server
HOST=0.0.0.0
PORT=8000