.env.example

# QueryWeaver example environment file
# Copy this to `.env` and edit values before running the app or the Docker image:
#
#   cp .env.example .env
#   # edit .env
#
# Minimal required variables for a basic run (these are left uncommented below):
# - FASTAPI_SECRET_KEY  (REQUIRED)
# - FALKORDB_URL       (REQUIRED) — preferred single connection string for FalkorDB
#
# For a plain-HTTP local run you also need to uncomment APP_ENV=development
# below, otherwise the login cookie is Secure and your browser drops it.
#
# Optional (commented) variables are provided as examples; uncomment and set them
# only if you need the functionality (OAuth, AI keys, local host/port overrides, etc.).

# -----------------------------
# Application / Server settings
# -----------------------------
# REQUIRED: secret used by FastAPI session middleware — change this before running in production
# This also signs the browser-login session cookie: changing it logs everyone out.
FASTAPI_SECRET_KEY=your_super_secret_key_here

# Optional: enable debug/reload when running the app directly
# FASTAPI_DEBUG=False

# Application environment (development, staging, production)
# The browser-login session cookie is marked Secure (HTTPS-only) unless this
# reads as "development" once trimmed and lower-cased, so leaving it unset fails
# secure — which is what you want everywhere except a local plain-HTTP run.
#
# Uncomment the line below ONLY for local development over http://localhost.
# A development session cookie carries no Secure flag, so any plain-HTTP request
# can leak the login. Never ship it enabled.
# APP_ENV=development

# Optional: how long a browser login lasts, in hours. Default: 24
# BROWSER_SESSION_TTL_HOURS=24

# General prefix for graph names used for Demo Graphs
# GENERAL_PREFIX=your_general_prefix_here

# Optional: allow OAuth over HTTP in development (disable in production)
# OAUTHLIB_INSECURE_TRANSPORT=1

# -----------------------------
# FalkorDB connection (REQUIRED / preferred)
# -----------------------------
# Preferred: single connection URL. Edit to point at your FalkorDB/Redis instance.
# Example: redis://localhost:6379/0
FALKORDB_URL=redis://localhost:6379/0  # REQUIRED - change to your FalkorDB URL

# Optional: name of the central user-management graph (User/Identity/Token/UsageEvent).
# Defaults to "Organizations"; override to share or isolate that graph.
# ORGANIZATIONS_GRAPH=Organizations

# Optional: separate host/port settings for local testing (only used if FALKORDB_URL is not set)
# FALKORDB_HOST=localhost
# FALKORDB_PORT=6379

# -----------------------------
# API / secret tokens
# -----------------------------
# Optional: static bearer token for internal / programmatic API access.
# When set, this token is accepted as a "master" API key.
# When unset, only user-generated tokens are accepted.
# SECRET_TOKEN_ERP=your_erp_token

# -----------------------------
# AI / LLM configuration (optional)
# -----------------------------
# QueryWeaver supports multiple AI providers. Set ONE of the following API keys.
# Provider selection precedence (first match wins):
# OLLAMA_MODEL > OPENAI_API_KEY > GEMINI_API_KEY > ANTHROPIC_API_KEY > COHERE_API_KEY > Azure (fallback)
#
# Optional: Override the default models (both must be from the SAME provider):
# COMPLETION_MODEL=provider/model-name
# EMBEDDING_MODEL=provider/model-name
#
# IMPORTANT: The provider must match your API key. If you set gemini/* models,
# you must have GEMINI_API_KEY set. Mismatched overrides may cause runtime errors.
#
# Examples (using Gemini - requires GEMINI_API_KEY):
#   COMPLETION_MODEL=gemini/gemini-3-pro-preview
#   EMBEDDING_MODEL=gemini/gemini-embedding-001

# Examples (using OpenAI - requires OPENAI_API_KEY):
#   COMPLETION_MODEL=openai/gpt-4.1
#   EMBEDDING_MODEL=openai/text-embedding-ada-002

# Wall-clock budget for one LLM call end to end, in seconds (default 90).
# This is the total, not per attempt: the per-attempt timeout handed to the
# provider is this divided by LLM_MAX_RETRIES + 1, so retries cannot push the
# real ceiling past it. A hung provider surfaces as an error within the budget
# instead of stalling the response stream.
# LLM_TIMEOUT=90
#
# Calls slower than this are logged at WARNING (default 20).
# LLM_SLOW_CALL_THRESHOLD=20
#
# Retry budget per LLM call (default 1). LLM_TIMEOUT applies per attempt, so
# this is pinned rather than left to the provider SDK and litellm defaults,
# which each retry and together multiply the effective ceiling.
# LLM_MAX_RETRIES=1
#
# Bounds for executing a user query against the target database. Offloading
# execution to a thread keeps the event loop free, but only these bound how
# long the query itself may run (a thread blocked in a socket read cannot be
# cancelled from Python). Seconds.
# DB_CONNECT_TIMEOUT=10
# DB_STATEMENT_TIMEOUT=60
#
# Schema introspection gets a larger deadline (it is metadata work over a whole
# database) and a cap on how many may occupy worker threads at once, since that
# executor is shared with every other offloaded call.
# DB_SCHEMA_TIMEOUT=300
# DB_SCHEMA_CONCURRENCY=2

# OpenAI - uses openai/gpt-4.1 and openai/text-embedding-ada-002
# OPENAI_API_KEY=your_openai_api_key

# Google Gemini - uses gemini/gemini-3-pro-preview and gemini/gemini-embedding-001
# GEMINI_API_KEY=your_gemini_api_key

# Anthropic - uses anthropic/claude-sonnet-4-5-20250929
# Note: Anthropic has no native embeddings. You MUST also set one of:
#   VOYAGE_API_KEY or EMBEDDING_MODEL for embeddings (startup fails otherwise).
# ANTHROPIC_API_KEY=your_anthropic_api_key
# VOYAGE_API_KEY=your_voyage_api_key  # Optional: for Voyage AI embeddings with Anthropic

# Cohere - uses cohere/command-a-03-2025 and cohere/embed-v4.0
# COHERE_API_KEY=your_cohere_api_key
# COHERE_MODEL=command-a-03-2025
# COHERE_EMBEDDING_MODEL=embed-v4.0

# Local open-source model via Ollama (through LiteLLM)
# OLLAMA_MODEL=llama3.1
# OLLAMA_EMBEDDING_MODEL=nomic-embed-text
# OLLAMA_API_BASE=http://localhost:11434

# Azure OpenAI (default fallback) - uses azure/gpt-4.1 and azure/text-embedding-ada-002
# AZURE_API_KEY=your_azure_api_key
# AZURE_API_BASE=https://your-resource.openai.azure.com/
# Must be 2025-03-01-preview or later — Graphiti memory writes use the
# Azure Responses API, which rejects older api-versions with HTTP 400.
# AZURE_API_VERSION=2025-03-01-preview

# -----------------------------
# OAuth configuration (optional — uncomment to enable login flows)
# -----------------------------
# Google OAuth
# GOOGLE_CLIENT_ID=your_google_client_id
# GOOGLE_CLIENT_SECRET=your_google_client_secret

# GitHub OAuth
# GITHUB_CLIENT_ID=your_github_client_id
# GITHUB_CLIENT_SECRET=your_github_client_secret

# If your OAuth app uses a different base URL than the request base (e.g., using 127.0.0.1 vs localhost)
# you can override the base used for building callback URLs. Example:
# OAUTH_BASE_URL=http://localhost:5000

# -----------------------------
# Email Configuration
# -----------------------------
# Signup with email/password sends a six-digit confirmation code, and the
# account is only created when that code is typed back into the signup form.
# With APP_ENV=development and no MAIL_SERVER the message is written to the
# application log instead of being sent, which is enough for local development
# -- copy the code out of the log. Anywhere else an unconfigured process
# refuses the send rather than logging the code, so signup fails loudly instead
# of leaving users waiting for mail nobody sent.
#
# Any provider works: Mailgun, SendGrid, Resend, SES and Postmark all expose an
# SMTP endpoint.
# MAIL_SERVER=smtp.mailgun.org
# MAIL_PORT=587                      # 465 selects implicit TLS (SMTPS)
# MAIL_USE_TLS=True                  # STARTTLS on non-465 ports
# MAIL_USERNAME=your_mail_username   # omit to send unauthenticated
# MAIL_PASSWORD=your_mail_password
# MAIL_DEFAULT_SENDER=noreply@yourdomain.com
# MAIL_TIMEOUT_SECONDS=10

# Write messages to this directory as .eml files instead of sending them. Used
# by the Playwright suite to read the verification code back. Takes precedence
# over MAIL_SERVER, so a machine with a real relay configured can still run the
# tests without mailing anyone.
# MAIL_OUTBOX_DIR=e2e/.mail

# Email/password auth is on by default when no OAuth provider is configured.
# EMAIL_AUTH_ENABLED=false

# Confirmation code lifetime, wrong guesses allowed per code, and per-address
# send limits.
# EMAIL_VERIFICATION_TTL_MINUTES=15
# EMAIL_VERIFICATION_MAX_ATTEMPTS=5
# EMAIL_VERIFICATION_RESEND_SECONDS=60
# EMAIL_VERIFICATION_MAX_SENDS=5

# -----------------------------
# Frontend / analytics (optional)
# -----------------------------
# Google Tag Manager ID (optional)
# GOOGLE_TAG_MANAGER_ID=GTM-XXXXXXX

# -----------------------------
# Memory TTL (optional)
# -----------------------------
# Set a TTL (in seconds) on per-user memory graphs so they auto-expire.
# When unset, memory graphs persist indefinitely.
# Example: 604800 = 1 week
# MEMORY_TTL_SECONDS=604800

# -----------------------------
# Optional MCP (Model Context Protocol) settings
# -----------------------------
# Control QueryWeaver's built-in MCP endpoints (default: enabled)
# Set to "true" to disable mounting the MCP HTTP surface without editing code
# DISABLE_MCP=false

# Notes
# -----------------------------
# - Keep secrets out of source control. Use your local `.env` (ignored by git) or a secrets manager in production.
# - For Docker runs, pass `--env-file .env` to `docker run` or provide individual `-e` args.
# - See api/config.py for additional runtime configuration defaults and model overrides.