.env.example

# =============================================================================
# RecordNote Environment Configuration (self-documented template)
# =============================================================================
# How to use:
# 1) Copy this file to `.env`
# 2) Fill required secrets and provider settings
# 3) Keep `.env` out of Git (never commit real secrets)
#
# Boolean values accepted by backend parser:
# - true/false, 1/0, yes/no, on/off
#
# Startup troubleshooting:
# - If app fails at startup with JWT error, set JWT_SECRET.
# - If Google login button fails, check GOOGLE_CLIENT_ID and VITE_GOOGLE_CLIENT_ID.
# - If transcription fails with local providers, verify local model paths below.


# =============================================================================
# APPLICATION SETTINGS (runtime mode, host/ports, paths)
# =============================================================================
# Runtime environment name. Optional.
# Used for environment-aware behavior and diagnostics.
# Common values: development | production | test
# Local recommendation: development
# Production recommendation: production
APP_ENV=development

# Alias for APP_ENV. Optional.
# If APP_ENV is set, it takes precedence.
ENVIRONMENT=development

# Backend bind host for CLI startup (`python main.py` path). Optional.
# Local: 0.0.0.0 or 127.0.0.1
# Production: usually 0.0.0.0 behind reverse proxy.
HOST=0.0.0.0

# Backend API port. Optional.
# Local default: 8000
# Production: use service/reverse proxy mapping as needed.
BACKEND_PORT=8000

# Frontend dev server port. Optional.
# Local default: 5173
FRONTEND_PORT=5173

# Base data directory for app outputs and user data. Optional.
# Performance: place on fast SSD for best throughput.
# Production: use persistent volume and backups.
BASE_DIR=Data

# Path to runtime JSON config store. Optional.
# Production: use persistent writable path.
CONFIG_STORE_PATH=config/runtime_config.json

# Root directory for local model registry/discovery. Optional.
# Used by startup model detection and capability checks.
MODEL_REGISTRY_ROOT=models


# =============================================================================
# AUTHENTICATION & SECURITY
# =============================================================================
# Google OAuth web client ID. Optional unless Google sign-in is enabled.
# Example: 123-abc.apps.googleusercontent.com
GOOGLE_CLIENT_ID=

# JWT signing secret. REQUIRED for backend startup.
# Sensitive: never commit real value.
# Generate with: python -c "import secrets; print(secrets.token_hex(32))"
# Production: use a long random value from secret manager.
JWT_SECRET=CHANGE_ME_IN_PRODUCTION_USE_A_LONG_RANDOM_STRING

# JWT algorithm. Optional.
# Keep HS256 unless backend code is changed.
JWT_ALGORITHM=HS256

# Access token validity (hours). Optional.
# Security: shorter is safer; longer is more convenient.
JWT_EXPIRES_HOURS=24

# Refresh token validity (days). Optional.
# Security: shorter limits token abuse window.
REFRESH_TOKEN_EXPIRES_DAYS=90

# Password reset token validity (minutes). Optional.
RESET_TOKEN_EXPIRES_MINUTES=60

# Cooldown before a user can change username again (days). Optional.
USERNAME_CHANGE_COOLDOWN_DAYS=30

# Login brute-force protection: max failed attempts before lockout. Optional.
AUTH_MAX_FAILED_LOGINS=5

# Account lockout duration in minutes after too many failed logins. Optional.
AUTH_LOCKOUT_MINUTES=15

# Token for runtime config admin endpoints (/api/v1/config). Sensitive.
# Required if you use config management APIs.
# Production: strong random value in secret manager.
CONFIG_ADMIN_TOKEN=CHANGE_ME_RUNTIME_CONFIG_TOKEN

# Secret used to sign public share URLs (HMAC). Sensitive.
# If empty, service falls back to JWT_SECRET then CONFIG_ADMIN_TOKEN.
# Production: set explicitly to isolate share-link secret scope.
SHARE_URL_SECRET=

# Default share-link expiry in hours. Optional.
# Set 0 to disable expiry.
SHARE_DEFAULT_EXPIRY_HOURS=72

# Optional HMAC secret for outbound webhook signatures. Sensitive.
# When set, webhooks include X-RecordNote-Signature header.
WEBHOOK_SECRET=

# Static API tokens for automation/integrations.
# Format: token:user_id,token2:user_id2 (user_id optional)
# Sensitive: treat as credentials and rotate regularly.
API_TOKENS=


# =============================================================================
# DATABASE
# =============================================================================
# SQLite path for auth accounts, sessions, and reset tokens.
# Local: auth.db is fine.
# Production: persistent volume + strict file permissions.
AUTH_DB_PATH=auth.db


# =============================================================================
# FRONTEND / URL SETTINGS
# =============================================================================
# Frontend base URL used for reset links and public URLs.
# Local: http://localhost:5173
# Production: your HTTPS public app URL.
APP_BASE_URL=http://localhost:5173

# Frontend build-time API base URL (Vite). Optional.
# If blank, frontend may use same-origin relative API.
# Production: set explicit public API URL if frontend/backend differ.
VITE_API_BASE_URL=

# Frontend build-time Google client ID. Optional.
# Usually should match GOOGLE_CLIENT_ID.
VITE_GOOGLE_CLIENT_ID=

# Frontend build-time site URL used in UI/link generation. Optional.
VITE_SITE_URL=http://localhost:5173


# =============================================================================
# CORS (cross-origin API access)
# =============================================================================
# Comma-separated allowed frontend origins.
# Local defaults include common dev ports.
# Production: restrict to your real frontend domain(s) only.
CORS_ALLOW_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://localhost:4173,http://127.0.0.1:4173,http://localhost:5173,http://127.0.0.1:5173

# Allow credentialed CORS requests (cookies/auth headers).
CORS_ALLOW_CREDENTIALS=true

# Comma-separated allowed CORS methods.
CORS_ALLOW_METHODS=GET,POST,PUT,PATCH,DELETE,OPTIONS

# Comma-separated allowed CORS request headers.
CORS_ALLOW_HEADERS=Authorization,Content-Type,Accept,Origin,X-Requested-With

# Comma-separated response headers exposed to browser JS.
CORS_EXPOSE_HEADERS=

# Browser CORS preflight cache duration (seconds).
CORS_MAX_AGE=600


# =============================================================================
# RATE LIMITING
# =============================================================================
# Enable/disable API rate limiter middleware.
# Production: keep true.
RATE_LIMIT_ENABLED=true

# Requests per minute limit.
# Tune by traffic profile and abuse risk.
RATE_LIMIT_REQUESTS_PER_MINUTE=120


# =============================================================================
# LOGGING / OBSERVABILITY
# =============================================================================
# Log verbosity: DEBUG | INFO | WARNING | ERROR | CRITICAL
# Local troubleshooting: DEBUG
# Production: INFO or WARNING
LOG_LEVEL=INFO

# Emit JSON logs for machine parsing. Production recommended: true
LOG_JSON=true

# Rotating log file path.
LOG_FILE_PATH=logs/recordnote.log

# Max bytes per log file before rotation.
LOG_MAX_BYTES=5242880

# Number of rotated backups to keep.
LOG_BACKUP_COUNT=5


# =============================================================================
# EMAIL / PASSWORD RESET DELIVERY
# =============================================================================
# SMTP host. Optional.
# If blank, reset links are printed to server console (dev-friendly).
SMTP_HOST=

# SMTP port (587 TLS-starttls commonly used).
SMTP_PORT=587

# SMTP username (sensitive in many setups).
SMTP_USER=

# SMTP password / token (sensitive).
SMTP_PASS=

# Sender address for outgoing reset emails.
SMTP_FROM=noreply@example.com


# =============================================================================
# GLOBAL LLM ROUTING (all LLM features)
# =============================================================================
# Forces a single backend for summarize/chat/flashcards/correction.
# Leave blank to let each request choose provider.
# Options: ollama | openai | chatgpt | claude | gemini | groq | llama_cpp | llamacpp
LLM_PROVIDER=

# Default model for selected global LLM provider.
LLM_MODEL=

# Optional global API key override for selected provider. Sensitive.
# If blank, provider-specific keys below are used.
LLM_API_KEY=

# Cloud provider API keys (sensitive). Optional unless using that provider.
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_API_KEY=
GROQ_API_KEY=


# =============================================================================
# OLLAMA (local LLM provider)
# =============================================================================
# Max concurrent Ollama tasks.
# Low-end: 1 | Mid: 1-2 | High server: 2-4
OLLAMA_MAX_CONCURRENCY=1

# Timeout for single Ollama task (seconds).
OLLAMA_TASK_TIMEOUT_SECONDS=600

# Reduce parallelism for low-end devices.
OLLAMA_LIGHTWEIGHT_MODE=false


# =============================================================================
# llama.cpp (local GGUF LLM provider)
# =============================================================================
# GGUF model path. Required when using llama_cpp provider.
# If invalid/missing, llama.cpp calls fail.
LLAMA_CPP_MODEL_PATH=/models/Qwen2.5-7B-Instruct-Q4_K_M.gguf

# Context tokens. Higher = more memory usage.
# Low-end: 2048-4096 | Mid: 4096-8192 | High: 8192+
LLAMA_CPP_N_CTX=4096

# Number of layers offloaded to GPU.
# 0=CPU only, larger values use more VRAM and can speed up inference.
LLAMA_CPP_N_GPU_LAYERS=0

# CPU threads for llama.cpp. 0=auto-detect.
LLAMA_CPP_N_THREADS=0

# Optional chat template override (auto-detect when blank).
# Examples: chatml, llama-2, gemma
LLAMA_CPP_CHAT_FORMAT=


# =============================================================================
# STT (speech-to-text) ORCHESTRATION
# =============================================================================
# Primary STT provider.
# Options: faster_whisper | whisper_cpp | local_transformer | openai | google
STT_ACTIVE_PROVIDER=faster_whisper

# Comma-separated fallback provider order.
STT_FALLBACK_PROVIDERS=whisper_cpp,local_transformer,openai,google

# Retry count for failed STT operations.
STT_RETRY_ATTEMPTS=1

# Backoff seconds between STT retries.
STT_RETRY_BACKOFF_SECONDS=0.2

# Per-request STT timeout (seconds).
STT_REQUEST_TIMEOUT_SECONDS=600


# =============================================================================
# STT PROVIDER: faster-whisper
# =============================================================================
# Enable faster-whisper provider.
STT_PROVIDER_FASTER_WHISPER_ENABLED=true

# Lower number = higher provider priority.
STT_PROVIDER_FASTER_WHISPER_PRIORITY=10

# Model size/name: tiny | base | small | medium | large-v3 (etc)
# Low-end: tiny/base | Mid: small/medium | High: large-v3
STT_PROVIDER_FASTER_WHISPER_MODEL=medium

# Optional directory for local faster-whisper model files.
# If invalid/missing, startup may report missing local model.
STT_PROVIDER_FASTER_WHISPER_MODEL_DIR=

# Timeout per faster-whisper task (seconds).
STT_PROVIDER_FASTER_WHISPER_TIMEOUT_SECONDS=600

# Concurrency for faster-whisper tasks.
# Low-end: 1 | Mid: 1-2 | High: 2-4
STT_PROVIDER_FASTER_WHISPER_CONCURRENCY_LIMIT=1


# =============================================================================
# STT PROVIDER: whisper.cpp
# =============================================================================
# Enable whisper.cpp provider.
STT_PROVIDER_WHISPER_CPP_ENABLED=false

# Lower number = higher provider priority.
STT_PROVIDER_WHISPER_CPP_PRIORITY=20

# Path to whisper.cpp model file (GGUF/bin per build).
STT_PROVIDER_WHISPER_CPP_MODEL=

# whisper.cpp executable path/name.
# If invalid, transcription fails with executable not found.
WHISPER_CPP_EXECUTABLE=whisper-cli

# Legacy fallback variable used by whisper.cpp provider code.
WHISPER_CPP_MODEL=

# Timeout per whisper.cpp task (seconds).
STT_PROVIDER_WHISPER_CPP_TIMEOUT_SECONDS=600

# Concurrency for whisper.cpp provider.
STT_PROVIDER_WHISPER_CPP_CONCURRENCY_LIMIT=1


# =============================================================================
# STT PROVIDER: local transformer
# =============================================================================
# Enable local Transformer STT provider.
STT_PROVIDER_LOCAL_TRANSFORMER_ENABLED=false

# Lower number = higher provider priority.
STT_PROVIDER_LOCAL_TRANSFORMER_PRIORITY=30

# HuggingFace/local model identifier.
STT_PROVIDER_LOCAL_TRANSFORMER_MODEL=openai/whisper-small

# Timeout per task (seconds).
STT_PROVIDER_LOCAL_TRANSFORMER_TIMEOUT_SECONDS=600

# Concurrency limit.
STT_PROVIDER_LOCAL_TRANSFORMER_CONCURRENCY_LIMIT=1


# =============================================================================
# STT PROVIDER: OpenAI API
# =============================================================================
# Enable OpenAI STT provider.
STT_PROVIDER_OPENAI_ENABLED=false

# Lower number = higher provider priority.
STT_PROVIDER_OPENAI_PRIORITY=40

# OpenAI STT model (example: gpt-4o-mini-transcribe).
STT_PROVIDER_OPENAI_MODEL=gpt-4o-mini-transcribe

# Optional custom endpoint for OpenAI-compatible API.
STT_PROVIDER_OPENAI_ENDPOINT=

# Explicit provider key (sensitive). Optional.
STT_PROVIDER_OPENAI_API_KEY=

# Env var name to read provider key from (advanced).
STT_PROVIDER_OPENAI_API_KEY_ENV=OPENAI_API_KEY

# Timeout per OpenAI STT request (seconds).
STT_PROVIDER_OPENAI_TIMEOUT_SECONDS=180

# Concurrency for OpenAI STT requests.
STT_PROVIDER_OPENAI_CONCURRENCY_LIMIT=4


# =============================================================================
# STT PROVIDER: Google Speech API
# =============================================================================
# Enable Google STT provider.
STT_PROVIDER_GOOGLE_ENABLED=false

# Lower number = higher provider priority.
STT_PROVIDER_GOOGLE_PRIORITY=50

# Google STT model/profile (example: latest_long).
STT_PROVIDER_GOOGLE_MODEL=latest_long

# Google Speech endpoint.
STT_PROVIDER_GOOGLE_ENDPOINT=https://speech.googleapis.com/v1/speech:recognize

# Explicit provider key (sensitive). Optional.
STT_PROVIDER_GOOGLE_API_KEY=

# Env var name to read provider key from (advanced).
STT_PROVIDER_GOOGLE_API_KEY_ENV=GOOGLE_SPEECH_API_KEY

# Fallback key used by health/capability checks for Google STT.
GOOGLE_SPEECH_API_KEY=

# Timeout per Google STT request (seconds).
STT_PROVIDER_GOOGLE_TIMEOUT_SECONDS=180

# Concurrency for Google STT requests.
STT_PROVIDER_GOOGLE_CONCURRENCY_LIMIT=4


# =============================================================================
# PIPELINE / QUEUE / PERFORMANCE TUNING
# =============================================================================
# Worker processes/threads handling heavy pipeline tasks.
# Low-end: 1 | Mid: 1-2 | High: 2-4+
PIPELINE_WORKER_COUNT=1

# Queue size for pending pipeline jobs.
# Low-end: 8-16 | Mid: 16-48 | High: 48-128
PIPELINE_QUEUE_MAXSIZE=32

# Max concurrent stage-level operations.
# Low-end: 1 | Mid: 2-3 | High: 4+
PIPELINE_STAGE_MAX_CONCURRENCY=2

# Timeout for a pipeline task (seconds).
PIPELINE_TASK_TIMEOUT_SECONDS=900

# Retry attempts for failed pipeline tasks.
PIPELINE_RETRY_ATTEMPTS=2

# Retry backoff (seconds).
PIPELINE_RETRY_BACKOFF_SECONDS=0.5

# Lightweight mode reduces resource usage at cost of throughput.
PIPELINE_LIGHTWEIGHT_MODE=false

# Upload chunk size in MB.
# Low-end: 1-2 | Mid: 2-4 | High: 4-8+
UPLOAD_CHUNK_SIZE_MB=2

# Processing profile label used by runtime tuning.
# Common values: fast | balanced_low | balanced | balanced_high | high
PROCESSING_QUALITY=balanced

# Device performance tier. Used by auto-tuning.
# Values: low | mid_low | mid | mid_high | high
PERFORMANCE_DEVICE_TIER=mid

# If true, runtime auto-detects and may downgrade tier based on CPU/RAM/VRAM.
PERFORMANCE_AUTO_TIER=true


# =============================================================================
# AUDIO PREPROCESSING TUNING
# =============================================================================
# Speech band-pass low cutoff in Hz.
SPEECH_BAND_LOW_HZ=80

# Speech band-pass high cutoff in Hz.
SPEECH_BAND_HIGH_HZ=7800

# Noise gate floor in dB.
NOISE_FLOOR_DB=-25


# =============================================================================
# ESTIMATED-TIME RATES (UI ETA calibration)
# =============================================================================
# These values affect ETA estimates shown to users, not core model quality.
ESTIMATE_TRANSCRIBE_RATE=90
ESTIMATE_TRANSCRIBE_MIN=10
ESTIMATE_DENOISE_RATE=3
ESTIMATE_SUMMARIZE_OLLAMA_RATE=30
ESTIMATE_SUMMARIZE_CLOUD_RATE=10
ESTIMATE_SUMMARIZE_MIN=5
ESTIMATE_VISUALIZE_FIXED=5
ESTIMATE_VISUALIZE_RATE=1
ESTIMATE_TRANSLATE_RATE=15
ESTIMATE_TRANSLATE_MIN=3


# =============================================================================
# PROMPT SAFETY / TEMPLATE OVERRIDES
# =============================================================================
# Default prompt version folder (blank = default prompt path).
PROMPT_DEFAULT_VERSION=

# Optional override directory for prompt templates.
# Useful for custom org/domain prompt packs.
PROMPT_OVERRIDE_DIR=

# Max prompt input chars accepted by safety service.
PROMPT_MAX_INPUT_CHARS=100000

# Redaction token inserted when prompt-injection patterns are detected.
PROMPT_REDACT_TOKEN=[filtered-instruction]

# Prompt budgeting for summarize pipeline (token estimates).
SUMMARY_CHUNK_PROMPT_TOKEN_BUDGET=2048
SUMMARY_FINAL_PROMPT_TOKEN_BUDGET=2048

# Max workers used by summarize utility.
# If OLLAMA_LIGHTWEIGHT_MODE=true or llama.cpp provider is used, app may force 1.
SUMMARY_MAX_WORKERS=2


# =============================================================================
# FIX_TRANSCRIBE UTILITY DEFAULTS (app/utils/fix_transcribe.py)
# =============================================================================
# Default provider used by fix_transcribe utility.
# Examples: ollama | openai | claude | gemini | groq | llama_cpp
FIX_TRANSCRIBE_PROVIDER=ollama

# Default model for fix_transcribe utility.
FIX_TRANSCRIBE_MODEL=llama3.1:8B


# =============================================================================
# LOCAL MODEL PATHS (translation / embeddings / local AI)
# =============================================================================
# Translator model directory (NLLB). Optional unless local translation used.
NLLB_MODEL_DIR=


# =============================================================================
# WEBHOOK / SHARING NOTES
# =============================================================================
# If WEBHOOK_SECRET is set, receivers should verify X-RecordNote-Signature.
# If SHARE_URL_SECRET is missing, backend uses JWT_SECRET/CONFIG_ADMIN_TOKEN fallback.


# =============================================================================
# PROVIDER DEPENDENCY QUICK GUIDE
# =============================================================================
# 1) Global routing:
#    - If LLM_PROVIDER is set, all LLM features use that provider.
#    - If LLM_API_KEY is set, it overrides provider-specific key variables.
#
# 2) STT provider toggles:
#    - Providers with *_ENABLED=false are skipped.
#    - STT_ACTIVE_PROVIDER must be enabled/healthy (or request fails).
#
# 3) Google auth vs Google APIs:
#    - GOOGLE_CLIENT_ID / VITE_GOOGLE_CLIENT_ID => Google Sign-In UI/auth
#    - GOOGLE_API_KEY / GOOGLE_SPEECH_API_KEY => Google LLM/STT APIs


# =============================================================================
# READY-TO-COPY EXAMPLES
# =============================================================================
# Local-only AI (Ollama + local STT):
# LLM_PROVIDER=ollama
# LLM_MODEL=qwen3:8b
# STT_ACTIVE_PROVIDER=faster_whisper
# STT_PROVIDER_FASTER_WHISPER_ENABLED=true
# STT_PROVIDER_OPENAI_ENABLED=false
# STT_PROVIDER_GOOGLE_ENABLED=false

# Cloud-only setup:
# LLM_PROVIDER=openai
# LLM_MODEL=gpt-4o-mini
# OPENAI_API_KEY=YOUR_KEY
# STT_ACTIVE_PROVIDER=openai
# STT_PROVIDER_OPENAI_ENABLED=true
# STT_PROVIDER_OPENAI_API_KEY=YOUR_KEY

# Hybrid setup:
# LLM_PROVIDER=ollama
# STT_ACTIVE_PROVIDER=faster_whisper
# STT_PROVIDER_OPENAI_ENABLED=true
# OPENAI_API_KEY=YOUR_KEY

# Low-end hardware:
# PERFORMANCE_DEVICE_TIER=low
# PERFORMANCE_AUTO_TIER=true
# PIPELINE_WORKER_COUNT=1
# PIPELINE_QUEUE_MAXSIZE=8
# OLLAMA_MAX_CONCURRENCY=1

# Production baseline:
# APP_ENV=production
# JWT_SECRET=<strong-random>
# CONFIG_ADMIN_TOKEN=<strong-random>
# SHARE_URL_SECRET=<strong-random>
# APP_BASE_URL=https://app.example.com
# CORS_ALLOW_ORIGINS=https://app.example.com
# LOG_LEVEL=INFO
# LOG_JSON=true
# RATE_LIMIT_ENABLED=true


# =============================================================================
# SYSTEM-DETECTED VARIABLES (usually do NOT set in .env manually)
# =============================================================================
# These are read mostly by helper scripts for terminal/CI detection:
# CI, GITHUB_ACTIONS, BUILD_ID, TF_BUILD, container,
# TERM, TERM_PROGRAM, WT_SESSION, ANSICON, WSL_DISTRO_NAME