.env.example

# RAG Modulo Environment Configuration Template
#
# 🚀 QUICK START:
# 1. Copy this file: cp .env.example .env
# 2. Run setup helper: make setup-env
# 3. Fill in the 🔐 CRITICAL values below
# 4. Test with: make validate-env
#
# DO NOT commit .env to version control

# ================================
# 🔐 CRITICAL SECRETS (Required - Get from team/docs)
# ================================
# Get JWT secret: openssl rand -hex 32
JWT_SECRET_KEY=generate_with_openssl_rand_hex_32

# Get from IBM Cloud > Watson AI > Credentials
WATSONX_APIKEY=get_from_ibm_cloud_watsonx_credentials
WATSONX_INSTANCE_ID=get_from_ibm_cloud_watsonx_service_details
WATSONX_URL=https://us-south.ml.cloud.ibm.com

# Get from https://platform.openai.com/api-keys
OPENAI_API_KEY=get_from_openai_platform_api_keys

# Get from https://console.anthropic.com/settings/keys
ANTHROPIC_API_KEY=get_from_anthropic_console_api_keys

# ================================
# PROJECT CONFIGURATION
# ================================
PROJECT_NAME=rag-modulo
PYTHON_VERSION=3.11

# ================================
# DATABASE CONFIGURATION
# ================================
COLLECTIONDB_USER=rag_modulo_user
COLLECTIONDB_PASS=rag_modulo_password
COLLECTIONDB_HOST=localhost
COLLECTIONDB_PORT=5433
COLLECTIONDB_NAME=rag_modulo

# ================================
# MINIO/S3 STORAGE (Required for Milvus)
# ================================
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin

# ================================
# MILVUS VECTOR DATABASE
# ================================
MILVUS_HOST=milvus-standalone
MILVUS_PORT=19530
MILVUS_USER=MILVUS_USER
MILVUS_PASSWORD=MILVUS_PASSWORD

# ================================
# AUTHENTICATION (OIDC)
# ================================
OIDC_DISCOVERY_ENDPOINT=https://prepiam.ice.ibmcloud.com/v1.0/endpoint/default/.well-known/openid-configuration
OIDC_AUTH_URL=https://prepiam.ice.ibmcloud.com/v1.0/endpoint/default/authorize
OIDC_TOKEN_URL=https://prepiam.ice.ibmcloud.com/v1.0/endpoint/default/token
OIDC_USERINFO_ENDPOINT=https://prepiam.ice.ibmcloud.com/v1.0/endpoint/default/userinfo
FRONTEND_URL=http://localhost:3000

# ================================
# IBM INTEGRATION
# ================================
IBM_CLIENT_ID=your_ibm_client_id_here
IBM_CLIENT_SECRET=your_ibm_client_secret_here

# ================================
# LLM CONFIGURATION
# ================================
LLM_PROVIDER=watsonx
RAG_LLM=ibm/granite-3-8b-instruct
MAX_NEW_TOKENS=500
MIN_NEW_TOKENS=200
TEMPERATURE=0.7
TOP_P=0.95
TOP_K=5
REPETITION_PENALTY=1.1

# ================================
# MLFLOW EXPERIMENT TRACKING
# ================================
MLFLOW_TRACKING_USERNAME=admin
MLFLOW_TRACKING_PASSWORD=password
MLFLOW_TRACKING_URI=http://rag-modulo-mlflow-server-1:5000

# ================================
# VECTOR DATABASE OPTIONS
# ================================
VECTOR_DB=milvus
EMBEDDING_MODEL=sentence-transformers/all-minilm-l6-v2
EMBEDDING_DIM=384

# ================================
# APPLICATION SETTINGS
# ================================
LOG_LEVEL=INFO
RUNTIME_EVAL=false
DATA_DIR=/path/to/your/data/directory

# ================================
# DEVELOPMENT/TESTING SETTINGS
# ================================
# When SKIP_AUTH=true, both backend and frontend bypass IBM OIDC Auth
# Mock user ID and token are still maintained for session purposes
SKIP_AUTH=false
MOCK_TOKEN=dev-0000-0000-0000

# ================================
# CHUNKING CONFIGURATION
# ================================
CHUNKING_STRATEGY=fixed
MIN_CHUNK_SIZE=100
MAX_CHUNK_SIZE=400
CHUNK_OVERLAP=10

# ================================
# IBM DOCLING DOCUMENT PROCESSING
# ================================
# Enable IBM Docling for advanced document processing (PDF, DOCX, PPTX, HTML)
# Provides AI-powered table extraction, layout analysis, and reading order detection
ENABLE_DOCLING=true
DOCLING_FALLBACK_ENABLED=true

# Use Docling's HybridChunker for token-aware chunking
# When true: Uses HybridChunker with accurate token counting
# When false: Uses RAG Modulo's chunking strategies (CHUNKING_STRATEGY)
USE_DOCLING_CHUNKER=true

# Tokenizer model for HybridChunker token counting
# Should match embedding model family for accurate token counts
# Default: ibm-granite/granite-embedding-english-r2 (matches IBM Slate/Granite embeddings)
# Alternative: sentence-transformers/all-MiniLM-L6-v2 (default Docling tokenizer)
CHUNKING_TOKENIZER_MODEL=ibm-granite/granite-embedding-english-r2

# Maximum tokens per chunk for HybridChunker
# Default 400 provides safety margin (78% of IBM Slate's 512 token limit)
# Allows 112 tokens for metadata and special tokens (CLS, SEP, etc.)
CHUNKING_MAX_TOKENS=400

# ================================
# RETRIEVAL SETTINGS
# ================================
RETRIEVAL_TYPE=vector
VECTOR_WEIGHT=0.7
KEYWORD_WEIGHT=0.3

# Number of documents to retrieve from vector DB
# Default: 10 (optimal balance of quality and speed)
# - Captures 95-97% of relevant docs
# - 50% faster than retrieving 20 docs
# - Use 5 for fastest queries, 20 for maximum recall
NUMBER_OF_RESULTS=10

# ================================
# RERANKING SETTINGS
# ================================
# Enable LLM-based reranking for improved relevance
ENABLE_RERANKING=true
RERANKER_TYPE=llm

# Number of top documents to return after reranking
# Default: 5 (recommended for optimal quality)
# - Reranks all retrieved docs (10), returns top 5
# - Balances context quality with LLM token limits
# - Use null to return all reranked documents
RERANKER_TOP_K=5

# Batch size for concurrent LLM reranking (default: 10)
# Larger batches = fewer LLM calls but higher memory usage
RERANKER_BATCH_SIZE=10

# ================================
# CONTAINER IMAGES (Optional)
# ================================
BACKEND_IMAGE=ghcr.io/manavgup/rag_modulo/backend:latest
FRONTEND_IMAGE=ghcr.io/manavgup/rag_modulo/frontend:latest
TEST_IMAGE=ghcr.io/manavgup/rag_modulo/backend:latest

# ================================
# MCP SERVER CONFIGURATION
# ================================
# MCP server exposes RAG Modulo tools via Model Context Protocol
# Transport type: stdio (for Claude Desktop), sse (web clients), http (API clients)
MCP_SERVER_TRANSPORT=stdio
# Port for SSE/HTTP transports (ignored for stdio)
MCP_SERVER_PORT=8080
# Base URL for RAG Modulo REST API (called by MCP tools)
# Local development: http://localhost:8000 (default)
# Docker Compose: http://backend:8000
# Kubernetes: http://backend-service:8000 (or your service name)
RAG_API_BASE_URL=http://localhost:8000

# ================================
# SPIFFE/SPIRE IDENTITY (Agent/Machine Identity)
# ================================
# Enable SPIFFE workload identity for agents and services
# See: https://spiffe.io/docs/latest/spire-about/spire-concepts/
SPIFFE_ENABLED=false

# Authentication mode for migration (disabled|optional|preferred|required)
# - disabled: No SPIFFE support (current default)
# - optional: Accept both user JWT and SPIFFE JWT-SVID
# - preferred: Prefer SPIFFE, log warning on legacy JWT
# - required: Only SPIFFE JWT-SVIDs accepted for workloads
SPIFFE_AUTH_MODE=disabled

# SPIRE Agent Workload API socket path
SPIFFE_ENDPOINT_SOCKET=unix:///run/spire/agent/api.sock

# SPIFFE trust domain for this environment
SPIFFE_TRUST_DOMAIN=rag-modulo.local

# Log warning when legacy JWT is used (for migration tracking)
SPIFFE_LEGACY_JWT_WARNING=false

# Default SVID TTL in seconds (default: 3600 = 1 hour)
SPIFFE_SVID_TTL_SECONDS=3600

# Allowed JWT-SVID audiences (comma-separated)
SPIFFE_JWT_AUDIENCES=rag-modulo,mcp-gateway