.env.example

# ── Trus configuration ──────────────────────────────────────────────────────
# Copy to .env and fill in. Never commit .env.

# Session cookie signing secret. WARNING: with TRUS_ENV=prod the app REFUSES TO
# BOOT on this default value — it is public, so it makes every session forgeable
# (R-901). Generate a real one:
#   python -c "import secrets; print(secrets.token_urlsafe(48))"
SESSION_SECRET=dev-insecure-key-change-me

# ── Deployment posture (see deploy/README.md; prod image bakes these in) ──────
# TRUS_ENV=dev                # dev (default) | prod. prod enforces a real SESSION_SECRET.
# TRUS_COOKIE_SECURE=0        # 1 → session cookie is SameSite=None + Secure (both flip
#                             # together) — required for the hosted cross-origin
#                             # Vercel-frontend / Fly-backend split; needs HTTPS.
# TRUS_CORS_ORIGINS=http://localhost:3000   # comma-separated allowed browser origins
# TRUS_ALLOW_ANON=1           # 1 (default): anonymous sessions get workspaces (dev).
#                             # 0: only invite-claimed users — prod posture (R-901).
# TRUS_PUBLIC_URL=http://localhost:3000     # FRONTEND origin; invite links are
#                             # built as {TRUS_PUBLIC_URL}/claim?token=…
# TRUS_OPS_TOKEN=             # gates GET /api/ops/summary (unset → always 401)
# TRUS_DB_PATH=               # SQLite location override (prod: /data/trus.db on a volume)
# TRUS_LIVE_DATA=on           # on (default): GET /api/live/{provider} fetches real values
#                             # (weather via keyless Open-Meteo). off → a disabled marker;
#                             # components fall back to manual entry (R-701/R-704).
# TRUS_LIVE_CACHE_MAX=5000    # row cap for the shared live_cache table — the oldest
#                             # rows (by fetched_at) are pruned on write past the cap.
# TRUS_LOG_LEVEL=INFO         # Python logging level for the app logger.
# TRUS_ALLOW_URL_IMPORT=0     # Layout Studio's URL-based image import (SSRF guard,
#                             # Stage-1 review): only checked when TRUS_ENV=prod, where
#                             # it's disabled (422) unless set to 1. Always allowed in dev.

# ── Generate-route rate limit + per-owner cost ceiling (R-1202 completion) ────
# Applies to the 5 LLM-backed routes (generate/preview/generate_from_file/refine/
# workspace insights) — a SHARED per-owner budget (a preview and a generate count
# toward the same window).
# TRUS_GEN_RATE_MAX=30            # max generations per owner per window (default 30)
# TRUS_GEN_RATE_WINDOW=300        # window size in seconds (default 300 = 5 min)
# TRUS_DAILY_COST_CAP_USD=        # optional per-owner daily $ cap (UTC calendar day);
#                                 # unset (default) or 0 → never blocks
# TRUS_TOKEN_COST_IN=0            # $ per 1,000 INPUT tokens, for the cost estimate/cap
# TRUS_TOKEN_COST_OUT=0           # $ per 1,000 OUTPUT tokens (both default 0 → cost
#                                 # shown as $0 while token counts stay real)

# ── Backups (R-1106) — python -m src.backup; runbook: deploy/BACKUP.md ────────
# TRUS_BACKUP_DIR=/data/backups   # where timestamped snapshots land (default /data/backups)
# TRUS_BACKUP_KEEP=7              # retention: keep the newest N backups (default 7)

# ── Which LLM backend generates ModuleConfigs ────────────────────────────────
# TRUS_LLM_PROVIDER: gemini | openai | stub
#   - leave UNSET to auto-detect: a TRUS_LLM_BASE_URL below → openai;
#     a real GEMINI_API_KEY → gemini; otherwise the offline template "stub".
#   - "stub" needs no key and no network — it serves keyword templates only.
# TRUS_LLM_PROVIDER=

# ── Option A: free / local open-source model (recommended for cost) ──────────
# Any OpenAI-compatible server works. Examples:
#
#   Ollama (macOS/Windows/Linux, easiest — recommended default):
#     1) install from https://ollama.com
#     2) `ollama pull qwen3:4b-instruct-2507-q4_K_M`   (~2.5 GB, Apache-2.0,
#        runs on a 16 GB Mac; non-"thinking" so output is clean JSON)
#     3) it serves at http://localhost:11434/v1
#   TRUS_LLM_PROVIDER=openai
#   TRUS_LLM_BASE_URL=http://localhost:11434/v1
#   TRUS_LLM_MODEL=qwen3:4b-instruct-2507-q4_K_M
#     (alternatives: qwen2.5:7b-instruct, phi4-mini; bigger/better on 32GB+ or a
#      GPU box: qwen3:30b-a3b-instruct-2507-q4_K_M)
#
#   vLLM / llama.cpp server / LM Studio (self-host on an external GPU box):
#   TRUS_LLM_BASE_URL=http://YOUR_GPU_HOST:8000/v1
#   TRUS_LLM_MODEL=Qwen/Qwen3-30B-A3B-Instruct-2507
#
# JSON_MODE: object (default, widely supported) | schema (json-schema guided
# decoding on vLLM/llama.cpp/recent Ollama) | off. "object" + validate-and-retry
# is the robust default; "schema" can be slower on the 30-variant union.
# TRUS_LLM_JSON_MODE=object
# TRUS_LLM_TIMEOUT=60
# TRUS_LLM_MAX_RETRIES=1
# TRUS_LLM_CASCADE=on        # on (default): if the endpoint is down, fall back to
#                            # Gemini (if a key is set) then offline templates.

# ── Option B: cheap hosted open-model endpoint (also OpenAI-compatible) ───────
#   Together / Fireworks / DeepInfra / Groq / OpenRouter, e.g.:
#   TRUS_LLM_PROVIDER=openai
#   TRUS_LLM_BASE_URL=https://api.together.xyz/v1
#   TRUS_LLM_MODEL=Qwen/Qwen2.5-7B-Instruct-Turbo
#   TRUS_LLM_API_KEY=your_hosted_key_here

# ── Option C: Google Gemini (original cloud path) ────────────────────────────
GEMINI_API_KEY=your_key_here
# Pin a current CHEAP tier to cut cost ~5-20x (implicit prompt caching is automatic):
# GEMINI_MODEL=gemini-3.1-flash-lite       # NB: gemini-2.5-flash-lite is being retired
# TRUS_LLM_MAX_OUTPUT_TOKENS=              # optional cap (output is ~4x input price)

# ── Vision model (Layout Studio "screenshot → layout" importer) ───────────────
# The everyday text model can be text-only (e.g. Qwen3-4B), so vision is separate.
# Quickest: `make ollama-vision` (pulls qwen2.5vl:7b and sets this).
# TRUS_VISION_MODEL=qwen2.5vl:7b
# TRUS_VISION_BASE_URL=http://localhost:11434/v1   # defaults to TRUS_LLM_BASE_URL
# TRUS_VISION_API_KEY=                             # defaults to TRUS_LLM_API_KEY
# TRUS_VISION_TIMEOUT=180
#
# AMD RX 6800XT (Navi 21) on bare Windows: the vision projector (mmproj) is broken on
# the Vulkan backend and native-Windows ROCm for RDNA2 is unreliable — so LEAVE
# TRUS_VISION_MODEL UNSET and the capture engine uses Gemini Flash for the screenshot
# read (cheap), while text/transform/embeddings stay local. To try local vision, set
# TRUS_VISION_MODEL and run the smoke test first. WSL2/Linux unlocks fully-local vision.

# ── Voice transcription (voice rambling → text, R-201/R-204) ─────────────────
# POST /api/transcribe. Any OpenAI-compatible /audio/transcriptions server works
# (e.g. a local whisper.cpp/faster-whisper server, or a hosted Whisper-compatible
# endpoint) — no bundled speech model. BOTH vars below must be set to enable it;
# unset → the route honestly refuses (422) instead of silently failing.
# TRUS_STT_BASE_URL=http://localhost:8000/v1
# TRUS_STT_MODEL=whisper-1
# TRUS_STT_API_KEY=                                # optional; local servers ignore it
# TRUS_STT_TIMEOUT=120                             # seconds — audio can run long

# ── Screenshot capture engine (staged "screenshot → faithful Trus layout") ────
# POST /api/studio/use-cases/{key}/capture. Stages: capture IR → transform → score.
# All optional; sensible defaults below.
# TRUS_CAPTURE_OCR=off                # on → RapidOCR ground-truth text (needs rapidocr_onnxruntime)
# TRUS_CAPTURE_DETECTOR_URL=          # OmniParser sidecar /detect URL (Phase 3); empty = skip
# TRUS_CAPTURE_VERIFY=off             # on → render-and-verify loop (Phase 2; needs Playwright)
# TRUS_CAPTURE_VERIFY_MAX_ITERS=3
# TRUS_CAPTURE_RENDER_URL=http://localhost:3000/capture-render
# TRUS_CAPTURE_CONF_THRESHOLD=0.62    # below → Gemini escalation (Phase 2)
# TRUS_CAPTURE_AUTOPROMOTE=on         # high-confidence captures auto-seed generation

# ── Semantic cache (cuts cost + grows a real-time template library) ───────────
# Embeds each prompt; an (almost) identical prior prompt is reused with ZERO model
# tokens, and every generation is stored so the seed for the next request is the
# nearest past result. Default embedding is dependency-free (hashing); for deeper
# semantic matching point it at any OpenAI-compatible /embeddings endpoint.
# TRUS_CACHE=on                  # on (default) | off
# TRUS_CACHE_THRESHOLD=0.93      # similarity to REUSE a prior result for free
# TRUS_CACHE_SEED_THRESHOLD=0.6  # similarity to use a prior result as the seed
# TRUS_EMBED_BASE_URL=http://localhost:11434/v1   # optional (e.g. Ollama)
# TRUS_EMBED_MODEL=nomic-embed-text               # optional
# TRUS_EMBED_API_KEY=                             # optional (hosted embedders)