env.example

# ============================================================================
# chatguru Agent - Environment Configuration Template
# ============================================================================
# Copy this file to .env and fill in your actual values.
# Usage: make env-setup (or manually: cp env.example .env)
#
# IMPORTANT: Never commit your .env file to version control!
# ============================================================================

# ============================================================================
# REQUIRED: LLM Configuration
# ============================================================================

# API key
# Used only when LLM_MODEL is set (a single-model / single-endpoint deployment):
# it is then forwarded to whatever backend that model routes to. In multi-provider
# picker mode (LLM_MODEL empty), leave this empty and give each provider its own
# standard env var instead (see LLM_LITELLM_MODELS_CONFIG below).
LLM_API_KEY=your-api-key-here

# Model id in LiteLLM form: <provider>/<model>. The provider prefix selects the
# backend, so switching providers is a config change, not a code change.
# REQUIRED. Examples: openai/gpt-4o-mini, azure/<deployment>,
# anthropic/claude-3-5-sonnet, gemini/gemini-2.5-flash, ollama/llama3.1:8b.
# See https://docs.litellm.ai/docs/providers
LLM_MODEL=openai/gpt-4o-mini

# Base URL for the chat/embeddings API (optional).
# Point at an OpenAI-compatible endpoint or a gateway (e.g. an Azure APIM proxy).
# Leave empty to use the provider's default endpoint — LiteLLM resolves it from the
# model id and each provider's standard credential env vars.
# Example: https://your-apim.azure-api.net/plc/openai/v1
LLM_API_BASE=

# API version (optional). Required by some gateways such as Azure.
# Example: 2024-02-15-preview
LLM_API_VERSION=

# Reasoning effort for models that support it (e.g. OpenAI o-series / gpt-5).
# Controls how many internal "thinking" tokens the model spends before answering.
# Values: minimal | low | medium | high (supported values vary by model)
# - Leave EMPTY to use the model default.
# - MUST be empty for models that don't support reasoning — they reject this parameter.
# LLM_REASONING_EFFORT=

# ============================================================================
# OPTIONAL: Embeddings Configuration
# ============================================================================

# Embeddings model id
# Default: text-embedding-ada-002
LLM_EMBEDDING_MODEL=text-embedding-ada-002

# Embedding vector dimensions
# Default: 1536 (ada-002 / text-embedding-3-small)
LLM_EMBEDDING_DIMENSIONS=1536

# Embeddings base URL override (optional)
# Set when embeddings use a different endpoint than LLM_API_BASE.
# Defaults to LLM_API_BASE when empty.
# LLM_EMBEDDINGS_API_BASE=https://other-endpoint/v1

# Embeddings API key override (optional)
# Defaults to LLM_API_KEY when empty.
# LLM_EMBEDDINGS_API_KEY=

# Selectable-models config (optional)
# Path to a JSON file listing the models offered in the frontend model picker.
# When set, GET /models serves it and the picker appears; when unset the picker
# is hidden and every request uses LLM_MODEL. See litellm_models.example.json.
# LLM_LITELLM_MODELS_CONFIG=/app/litellm_models.json
#
# Credentials for a multi-provider picker: LLM_API_KEY is forwarded only when
# LLM_MODEL is set, and then goes to whichever backend the chosen model routes
# to — so a shared key only fits a single endpoint/gateway. To offer models from
# several providers directly, LEAVE LLM_MODEL / LLM_API_KEY / LLM_API_BASE EMPTY
# and give each provider its own standard LiteLLM env var — LiteLLM picks the
# right one per model automatically:
#   OPENAI_API_KEY=sk-...
#   ANTHROPIC_API_KEY=sk-ant-...
#   GEMINI_API_KEY=...
# See https://docs.litellm.ai/docs/providers for each provider's variable.

# ============================================================================
# REQUIRED: Langfuse Configuration
# ============================================================================
# Langfuse provides observability, tracing, and monitoring for LLM applications.
# Sign up at https://langfuse.com/ to get your credentials.
# ============================================================================

# Langfuse Public Key
# REQUIRED: Your Langfuse public key (starts with pk-lf-)
# Example: pk-lf-abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
# Get this from: Langfuse Dashboard > Settings > API Keys
LANGFUSE_PUBLIC_KEY=your-langfuse-public-key

# Langfuse Secret Key
# REQUIRED: Your Langfuse secret key (starts with sk-lf-)
# Example: sk-lf-abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
# Get this from: Langfuse Dashboard > Settings > API Keys
# Security: Keep this secret! Never commit to version control.
LANGFUSE_SECRET_KEY=your-langfuse-secret-key

# Langfuse Host URL
# REQUIRED: Langfuse instance URL
# Default: https://cloud.langfuse.com (Langfuse Cloud)
# For self-hosted: https://your-langfuse-instance.com
LANGFUSE_HOST=https://cloud.langfuse.com

# Enable Langfuse Tracing
# Optional: Enable/disable Langfuse tracing
# Values: true, false
# Default: true
LANGFUSE_ENABLED=true

# ============================================================================
# OPTIONAL: FastAPI Configuration
# ============================================================================
# Configure the FastAPI server behavior.
# These have sensible defaults and usually don't need to be changed.
# ============================================================================

# FastAPI Host
# Optional: Host address to bind to
# Default: 0.0.0.0 (all interfaces)
# For local development only: 127.0.0.1
FASTAPI_HOST=0.0.0.0

# FastAPI Port
# Optional: Port number for the API server
# Default: 8000
# Change if port 8000 is already in use
FASTAPI_PORT=8000

# CORS Allowed Origins
# Optional: Allowed origins for CORS (JSON array format)
# Default: ["*"] (allow all origins)
# For production: ["https://yourdomain.com", "https://www.yourdomain.com"]
# Example: ["http://localhost:5173", "http://localhost:3000"]
FASTAPI_CORS_ORIGINS=["*"]

# ============================================================================
# OPTIONAL: Application Configuration
# ============================================================================
# General application settings.
# ============================================================================

# Application Name
# Optional: Name displayed in the UI and API responses
# Default: chatguru Agent
# Example: My Company Chatbot
APP_NAME=NG chatguru

# Debug Mode
# Optional: Enable debug mode (more verbose logging, stack traces)
# Values: true, false
# Default: false
# Warning: Set to false in production!
DEBUG=false

# Log Level
# Optional: Logging verbosity level
# Values: DEBUG, INFO, WARNING, ERROR, CRITICAL
# Default: INFO
# Recommended: INFO for production, DEBUG for development
LOG_LEVEL=INFO

# Emit tool_call/tool_result WS frames (default: true)
# Does not gate usage/model on the end frame — those are sent whenever known.
TOOL_FRAMES_ENABLED=true

# ============================================================================
# OPTIONAL: Chat history persistence (SQLAlchemy async + Alembic)
# ============================================================================
# Leave unset (commented out) to DISABLE persistence — no messages are stored, no DB required.
# Set to any async SQLAlchemy URL to ENABLE it; then run `make migrate` once to create tables.
# Format: <dialect>+<async_driver>://... (must use an async-capable driver).
# Keep persistence/sqlalchemy/tables.py aligned with alembic migrations when editing schema.
#
# Local dev with SQLite vector service: use ONE file for chat + product vectors, e.g.:
#   PERSISTENCE_DATABASE_URL=sqlite+aiosqlite:///data/chatguru.db
#   VECTOR_SQLITE_DB_PATH=data/chatguru.db   (vector microservice process; path must match)
# Docker (sqlite profile): both services mount the same volume at /data — see docker-compose.yml.
# Examples:
#   sqlite+aiosqlite:///data/chatguru.db
#   sqlite+aiosqlite:////absolute/path/to/chatguru.db
#   postgresql+asyncpg://user:pass@localhost:5432/chatguru
#   mysql+aiomysql://user:pass@localhost:3306/chatguru
# ============================================================================

# PERSISTENCE_DATABASE_URL=sqlite+aiosqlite:///data/chatguru.db

# ============================================================================
# OPTIONAL: Document RAG repository (MongoDB, retrieval-only)
# ============================================================================
# Disabled by default. When enabled, startup will fail fast if initialization or
# connectivity checks fail.
# This is separate from product RAG (VECTOR_DB_* settings).
# ============================================================================

# Enable document RAG repository bootstrap
# Values: true, false
# Default: false
DOCUMENT_RAG_ENABLED=false

# Backend selection for document RAG
# Values: mongodb (MongoDB Atlas / Atlas Local), cosmos (Azure Cosmos DB for MongoDB vCore)
# Default: mongodb
# Use 'cosmos' in Azure; local dev/tests use 'mongodb' (Atlas Local has no
# Cosmos-compatible local emulator with vector search).
DOCUMENT_RAG_BACKEND=mongodb

# MongoDB URI used by document RAG repository
# Default: mongodb://localhost:27017
DOCUMENT_RAG_MONGODB_URI=mongodb://localhost:27017

# MongoDB database and collection for document chunks
# Defaults: chatguru / documents
DOCUMENT_RAG_MONGODB_DATABASE=chatguru
DOCUMENT_RAG_MONGODB_COLLECTION=documents

# MongoDB vector search index name for document retrieval
# Default: document_vector_index
DOCUMENT_RAG_MONGODB_INDEX_NAME=document_vector_index

# Default result limit used by search_documents tool
# Default: 5
DOCUMENT_RAG_SEARCH_LIMIT_DEFAULT=5

# Embedding provider for document retrieval
# Values: openai, custom
# Default: openai
DOCUMENT_RAG_EMBEDDING_PROVIDER=openai

# Required only when DOCUMENT_RAG_EMBEDDING_PROVIDER=custom
# Format: module.path:ClassName
# Class must define: embed_query(query: str) -> list[float]
# DOCUMENT_RAG_EMBEDDING_CUSTOM_CLASS=your.module:YourProvider

# MongoDB connection timeout used during repository connect check
# Default: 5000 (milliseconds)
DOCUMENT_RAG_MONGODB_CONNECTION_TIMEOUT_MS=5000

# GridFS bucket for storing full source documents for /documents/{source_path}
# Default: document_sources
DOCUMENT_RAG_MONGODB_FILES_BUCKET=document_sources

# ----------------------------------------------------------------------------
# Cosmos DB for MongoDB vCore (DOCUMENT_RAG_BACKEND=cosmos only)
# ----------------------------------------------------------------------------
# When backend=cosmos, the DOCUMENT_RAG_MONGODB_* vars above are reused for the
# connection string, database, collection, index name and GridFS bucket — point
# DOCUMENT_RAG_MONGODB_URI at the Cosmos vCore connection string. Cosmos vCore
# builds the vector index via createIndexes + cosmosSearchOptions (no Atlas
# search-index API), tuned by the settings below.

# Vector index kind: vector-ivf or vector-hnsw
# Default: vector-ivf (good for small corpora; vector-hnsw needs M40+ tier)
DOCUMENT_RAG_COSMOS_VECTOR_INDEX_KIND=vector-ivf

# IVF list count (used when kind=vector-ivf)
# Default: 1
DOCUMENT_RAG_COSMOS_VECTOR_NUM_LISTS=1

# HNSW parameters (used when kind=vector-hnsw)
# Defaults: m=16, ef_construction=64
DOCUMENT_RAG_COSMOS_VECTOR_M=16
DOCUMENT_RAG_COSMOS_VECTOR_EF_CONSTRUCTION=64

# Vector similarity metric: COS, L2, or IP
# Default: COS
DOCUMENT_RAG_COSMOS_VECTOR_SIMILARITY=COS

# Force a full re-ingest on next container startup (ignores the
# /app/rag_ingest_state/.ingested sentinel, clears existing chunks + GridFS
# files, re-embeds everything in /app/rag_data). See docs/document-rag.md.
# Default: unset
# DOCUMENT_RAG_INGEST_FULL_REPLACE=1

# ============================================================================
# OPTIONAL: Conversation title generation provider
# ============================================================================
# Defaults to llm (uses the same LLM_* config as chat completions).
# Set to fallback for deterministic local-only title generation.
# Set to custom and provide TITLE_GENERATION_CUSTOM_CLASS to plug your own adapter.
# Values: llm, fallback, custom  (the legacy value "openai" is still accepted)
# Default: llm
TITLE_GENERATION_PROVIDER=llm

# Required only when TITLE_GENERATION_PROVIDER=custom.
# Format: module.path:ClassName
# The class must implement async methods: connect(), generate(first_message), close().
# Example: TITLE_GENERATION_CUSTOM_CLASS=my_project.titlegen:MyTitleGenerator
# TITLE_GENERATION_CUSTOM_CLASS=

# ============================================================================
# OPTIONAL: Product Database Configuration
# ============================================================================
# Configure the product database backend.
# Supports two backends: SQLite (sqlite-vec) and MongoDB (Atlas Vector Search)
# ============================================================================

# Database Type
# Optional: Which database backend to use
# Values: sqlite, mongodb
# Default: mongodb (fully local, runs in Docker)
VECTOR_DB_TYPE=mongodb

# SQLite Database Service URL
# Optional: Full URL of the SQLite database service
# Default: http://localhost:8001
# Docker: http://vector-db:8001 (Docker Compose service name)
VECTOR_DB_SQLITE_URL=http://localhost:8001

# SQLite file for the vector microservice (products + embeddings). For a single local DB
# alongside PERSISTENCE_DATABASE_URL, point both at the same path (vector service uses this path).
# Default in code: /data/chatguru.db (Docker) or set e.g. data/chatguru.db for local runs.
# VECTOR_SQLITE_DB_PATH=data/chatguru.db

# ============================================================================
# MongoDB Configuration (Local Docker)
# ============================================================================
# Used when VECTOR_DB_TYPE=mongodb
# Default setup uses local MongoDB running in Docker (no external service needed)
# ============================================================================

# MongoDB Connection URI
# Default: Uses local MongoDB container with docker-compose
# For local Docker: mongodb://admin:password@localhost:27017
# For Atlas (cloud): mongodb+srv://username:password@cluster.mongodb.net
VECTOR_DB_MONGODB_URI=mongodb://admin:password@localhost:27017

# MongoDB Vector Database API Service URL
# Optional: Full URL of the MongoDB vector database API service (HTTP endpoint)
# Default: http://localhost:8002
# Docker: http://mongo-vector-db:8002 (Docker Compose service name)
# Note: This is the HTTP API wrapper, not the MongoDB connection URI
VECTOR_DB_MONGODB_API_URL=http://localhost:8002

# MongoDB Database Name
# Optional: Name of the MongoDB database to use
# Default: products
VECTOR_DB_MONGODB_DATABASE=products

# MongoDB Collection Name
# Optional: Name of the MongoDB collection to use
# Default: products
VECTOR_DB_MONGODB_COLLECTION=products

# Database Request Timeout
# Optional: Request timeout in seconds
# Default: 30
VECTOR_DB_TIMEOUT=30

# ============================================================================
# Rate Limiting
# ============================================================================

# Enable Redis-backed rate limiting
# Optional: Set to true to enforce per-IP message quotas
# Default: false (disabled)
RATE_LIMIT_ENABLED=false

# Redis connection URL
# Required when RATE_LIMIT_ENABLED=true
# Default: redis://localhost:6379/0
RATE_LIMIT_REDIS_URL=redis://localhost:6379/0

# Maximum LLM messages allowed per IP per fixed window
# Optional: Increase for less restrictive limits
# Default: 10
RATE_LIMIT_MAX_MESSAGES=10

# Maximum file uploads (POST /process-document, GET /attachments) per IP per window
# Tracked separately from chat messages so uploads don't burn chat quota.
# Default: 10
RATE_LIMIT_MAX_UPLOADS=10

# Fixed window duration in seconds (shared by both chat and upload limits)
# Optional: 86400 = 24 hours
# Default: 86400
RATE_LIMIT_WINDOW_SECONDS=86400

# Trust X-Forwarded-For / X-Real-IP headers for IP extraction
# Optional: Enable only when behind a trusted reverse proxy (e.g. Nginx)
# WARNING: Do not enable in direct-to-internet deployments — headers can be spoofed
# Default: false
RATE_LIMIT_TRUST_PROXY=false

# ============================================================================
# Document Upload (Docling)
# ============================================================================

# Enable the POST /process-document endpoint for file-to-markdown conversion
# Default: true
DOCLING_ENABLED=true

# Maximum upload size in bytes (default: 20 MB)
DOCLING_MAX_FILE_SIZE_BYTES=20971520

# Enable VLM-based image/picture description for PDFs that contain images.
# Set to true only when your vision model supports images.
# NOTE: Unlike chat (which is provider-agnostic via LiteLLM), this feature POSTs
# an OpenAI-style chat/completions request DIRECTLY to the endpoint, so the
# target must be OpenAI-compatible (OpenAI, Azure, an APIM/LiteLLM proxy, or a
# local server with OpenAI compat). Native non-OpenAI APIs (Anthropic, Gemini,
# Bedrock) require an OpenAI-compatible proxy and an explicit URL below.
# Default: false
DOCLING_PICTURE_DESCRIPTION_ENABLED=false

# Chat completions URL for the vision model.
# OPTIONAL — when empty the URL is auto-derived from your main LLM settings:
#   • LLM_API_BASE + LLM_API_VERSION → <LLM_API_BASE>/openai/deployments/<model>/chat/completions?api-version=<LLM_API_VERSION>  (Azure)
#   • LLM_API_BASE only              → <LLM_API_BASE>/chat/completions
#   • no LLM_API_BASE + openai model → https://api.openai.com/v1/chat/completions
# Set explicitly when using a non-OpenAI provider, an OpenAI-compatible proxy,
# or a vision model different from the chat model:
#   Azure:  https://<resource>.openai.azure.com/openai/deployments/<vision-deployment>/chat/completions?api-version=2024-05-01-preview
#   OpenAI: https://api.openai.com/v1/chat/completions
DOCLING_PICTURE_DESCRIPTION_URL=

# API key for the vision endpoint. Defaults to LLM_API_KEY when empty.
DOCLING_PICTURE_DESCRIPTION_API_KEY=

# ============================================================================
# OPTIONAL: MCP Servers (Model Context Protocol)
# ============================================================================
# Expose tools from remote MCP servers to the agent. Server connections are
# parsed once at startup; the tools themselves are discovered per chat turn over
# a live session (so stateful servers keep state within a turn) and added
# alongside the built-in tools. Only remote transports (streamable_http, sse)
# are supported — local stdio/command servers are not.
#
# Failures degrade gracefully: an unreachable server, a missing config file,
# or an unset ${VAR} placeholder logs a warning and skips that server; the app
# keeps running with whatever loaded. Built-in tools always win name collisions.
#
# See docs/mcp.md and mcp.servers.example.json for the config file format.
# ============================================================================

# Enable loading tools from remote MCP servers.
# Default: false
MCP_ENABLED=false

# Path to the JSON file declaring MCP servers (required when MCP_ENABLED=true).
# Secrets referenced as ${VAR} inside the file are expanded from this environment.
# Example: ./mcp.servers.json
MCP_CONFIG_PATH=

# ============================================================================
# OPTIONAL: Attachment Storage
# ============================================================================
# Persists raw uploaded files (images, documents) so they remain accessible
# when replaying chat history. Enabled by default; set ATTACHMENT_STORAGE_ENABLED=false
# to turn the subsystem off entirely (upload endpoints still work but files are
# not saved and attachment_id will be null).
#
# Filesystem is the only supported backend today; cloud backends (Azure Blob,
# S3) can be added by implementing the AttachmentStorage interface.
#
# See docs/attachment-storage.md for full deployment guidance.
# ============================================================================

# Enable or disable attachment storage entirely.
# Default: true
ATTACHMENT_STORAGE_ENABLED=true

# Storage backend type.
# Values: filesystem
# Default: filesystem
ATTACHMENT_STORAGE_TYPE=filesystem

# Base directory for filesystem storage (created automatically if absent).
# Default: ./attachments
# ⚠ In Docker / container deployments this path MUST be inside a persistent
#   volume — files written here are lost on container restart otherwise.
#   Use an absolute path pointing at the volume mount, e.g. /data/attachments.
ATTACHMENT_STORAGE_BASE_PATH=./attachments

# ============================================================================
# Quick Reference
# ============================================================================
# REQUIRED Variables:
#   - LLM_API_KEY
#   - LLM_MODEL          (LiteLLM model id, e.g. openai/gpt-4o-mini)
#   - LANGFUSE_PUBLIC_KEY
#   - LANGFUSE_SECRET_KEY
#   - LANGFUSE_HOST
#
# OPTIONAL Variables (have defaults):
#   - LLM_API_BASE                (base URL / gateway; empty = provider default)
#   - LLM_API_VERSION             (required by some gateways, e.g. Azure)
#   - LLM_EMBEDDINGS_API_BASE     (overrides LLM_API_BASE for embeddings only)
#   - LLM_EMBEDDINGS_API_KEY      (overrides LLM_API_KEY for embeddings only)
#   - LLM_EMBEDDING_MODEL
#   - LLM_EMBEDDING_DIMENSIONS
#   - VECTOR_DB_* (database configuration)
#   - ATTACHMENT_STORAGE_ENABLED  (default: true — set to false to disable uploads)
#   - ATTACHMENT_STORAGE_TYPE     (default: filesystem)
#   - ATTACHMENT_STORAGE_BASE_PATH (default: ./attachments — use persistent volume path in Docker)
#   - All others can be left as-is for basic usage
#
# Security Notes:
#   - Never commit .env to version control
#   - Keep API keys secret
#   - Use environment-specific values for production
#
# Docker Compose:
#   - Set VECTOR_DB_SQLITE_URL=http://chatguru-sqlite-db:8001 when using docker-compose
#   - The SQLite database service runs on port 8001 by default
# ============================================================================