.env.sample

# Copy this file to .env and fill in the keys you have.
# .env is gitignored - never commit real keys, and never paste them into chats
# or issues. If a key is ever exposed, rotate it rather than hoping.

# ---------------------------------------------------------------------------
# Keys
# ---------------------------------------------------------------------------
#
# OPENAI_API_KEY is REQUIRED: it powers embeddings, which every question needs
# in order to search. The others are optional and affect only which model WRITES
# the answers.
#
# Every provider below speaks the OpenAI chat protocol, so all of them work
# through the one `openai` package - adding a provider needs no new dependency.

# Required. Embeddings + (by default) answer generation.
OPENAI_API_KEY=your_openai_api_key_here

# Optional. Answer generation only.
GEMINI_API_KEY=your_gemini_api_key_here

# Optional, and the best value per key: ONE key fronts hundreds of models across
# providers - including genuinely FREE ones, which makes this the practical
# fallback when paid credits run out. Measured working, at no cost:
#
#   nvidia/nemotron-3-super-120b-a12b:free   120B, 262k ctx, ~1.7s   <- best
#   poolside/laguna-s-2.1:free               fast, good at code
#   nvidia/nemotron-3-ultra-550b-a55b:free   550B, 1M ctx, ~6.8s
#
# Free tiers are rate-limited and can be withdrawn at any time, which is why the
# local options below are worth having as well - see `npm run list-models`.
OPENROUTER_API_KEY=

# Optional. Free tier, very fast, serves open-weight models. The useful contrast
# for latency and for how well a smaller model follows the grounding instruction.
# NOTE: Groq (this) is a different company from Grok (xAI, below).
GROQ_API_KEY=

# Optional. xAI's Grok.
XAI_API_KEY=

# ---------------------------------------------------------------------------
# Which model writes the answers
# ---------------------------------------------------------------------------

# openai (default), gemini, openrouter, groq, xai, or ollama.
# Safe to change at any time: retrieval, scores and citations are unaffected, so
# the same passages simply get a different writer. That also makes it a clean A/B
# comparison - see `npm run compare-providers`.
# If the chosen provider's key is missing, the server falls back to one that is
# set rather than refusing to start.
CHAT_PROVIDER=openai

# Model IDs are DEFAULTS, not guarantees - provider model naming changes often.
# Override per provider, or globally with CHAT_MODEL. If a name is rejected, the
# API error names the model, which is the quickest way to find the current one.
#
# Defaults:
#   openai     -> gpt-4o-mini
#   gemini     -> gemini-2.0-flash
#   openrouter -> meta-llama/llama-3.3-70b-instruct
#   groq       -> llama-3.3-70b-versatile
#   xai        -> grok-3-mini
#   ollama     -> llama3.2
#
# OPENAI_MODEL=
# GEMINI_MODEL=
# OPENROUTER_MODEL=
# GROQ_MODEL=
# XAI_MODEL=
# OLLAMA_MODEL=
# CHAT_MODEL=            # applies to whichever provider is active

# ---------------------------------------------------------------------------
# Local models - no key, no cost, no rate limits, works offline
# ---------------------------------------------------------------------------
#
# The complement to a free tier: slower and smaller, but nobody can withdraw it.
# Set ENABLE_LOCAL=true once a local server is running.
#
# LM Studio (recommended on AMD GPUs - its Vulkan backend avoids ROCm, which does
# not officially support gfx1031 cards such as the RX 6700 XT):
# ENABLE_LOCAL=true
# LMSTUDIO_BASE_URL=http://localhost:1234/v1
# LMSTUDIO_MODEL=qwen2.5-coder-14b-instruct
#
# Ollama (nicer CLI; AMD support on Windows goes through ROCm):
# ENABLE_LOCAL=true
# OLLAMA_BASE_URL=http://localhost:11434/v1
# OLLAMA_MODEL=qwen2.5-coder:7b

# ---------------------------------------------------------------------------
# Embeddings: NOT a runtime switch
# ---------------------------------------------------------------------------
#
# docs/angular/vectors.bin holds 1,136 passages in OpenAI's
# text-embedding-3-small space at 512 dimensions. A Gemini embedding of the same
# text lands in a different space entirely, and comparing across the two yields
# plausible-looking numbers that mean nothing.
#
# So changing the embedding provider is a rebuild, not a setting:
#   npm run build-embeddings   (rebuild the store)
#   npm run build-golden       (rebuild the test fixture to match)
#
# The server refuses to load a store whose model or dimensions disagree with what
# it expects, rather than silently returning nonsense.

# ---------------------------------------------------------------------------
# Backend port. Keep in sync with proxy.conf.json if you change it.
# ---------------------------------------------------------------------------
# PORT=3000

# --- Cost controls -----------------------------------------------------------
# Two independent limits. A rate limit bounds how FAST the balance can be spent;
# it is not a budget. The ceiling bounds the total.

# Token bucket on /api/chat, per caller. 0 disables.
RATE_LIMIT_PER_MINUTE=20
# How many requests may arrive at once before throttling starts.
RATE_LIMIT_BURST=5

# Daily ceiling in USD, checked before every call and persisted to data/spend.json
# so a restart cannot reset it. Unset or 0 disables. Cost is ESTIMATED from a
# static price table; the token counts underneath it are exact.
# DAILY_SPEND_USD=1.00

# --- Reranking ---------------------------------------------------------------
# A second pass that reorders retrieved passages by judging each against the
# question directly. Measured on the held-out set: hit@1 73 -> 87%, MRR 0.822 ->
# 0.922. Costs one extra model call per question (~$0.0002) and delays the first
# token of a streamed answer. Set RERANK=off to disable.
# RERANK=off
# How many passages to rerank. 10 by default: measured, recall is already 100% at
# 10 on this corpus and widening only adds noise.
# RERANK_CANDIDATES=10
# Pinned separately from CHAT_PROVIDER, because this changes RETRIEVAL.
# RERANK_PROVIDER=openai

# --- Answer style ------------------------------------------------------------
# How answers are WRITTEN. Presentation only: the grounding rules are identical
# across every style and a test enforces that.
#   tutor    starts from the problem the feature solves  (default)
#   lolcat   correct answers, terrible spelling
#   yoda     inverted syntax
#   concise  the measurement baseline, not offered in the UI
# The silly ones are not only a joke: they make it visible that the facts,
# citations and refusals are identical whatever the voice. See LEARN-RAG.md.
# ANSWER_STYLE=tutor