deploy/huggingface/env.example

# Hugging Face Space environment reference.
#
# Split into two groups below: Space "Variables" (plaintext, fine to see in
# Space settings/logs) and Space "Secrets" (encrypted, never shown). See
# docs/getting-started/huggingface-space.md for the full explanation.
#
# Everything here already has a safe default baked into
# deploy/huggingface/Dockerfile — you only need to set values you want to
# change from the lightweight-demo defaults.

# ============================== Variables ==================================
# Safe to set as plain HF Space "Variables". Never put a key/token here.

AURALYNQ_HF_SPACE=true
AURALYNQ_DEMO_MODE=true
AURALYNQ_PUBLIC_DEMO=true

# false = Mode A (lightweight public demo, no upload persistence risk).
# true  = Mode B (full Docker Space); only flip this if you understand that a
#         public, unauthenticated Space would let anyone upload documents that
#         may persist (see the storage note below).
AURALYNQ_ALLOW_UPLOADS=false

# Where Auralynq stores its index/corpus/page-cache inside the container.
# If the Space has Persistent Storage attached and mounted at /data, this
# path survives restarts; otherwise it's wiped on every restart/redeploy.
AURALYNQ_DATA_DIR=/data/auralynq

# Offline-safe defaults — no GPU, no downloads, no paid keys required.
AURALYNQ_VECTOR__BACKEND=memory
AURALYNQ_EMBEDDING__PROVIDER=hash
AURALYNQ_LLM__PROVIDER=extractive
AURALYNQ_VISUAL__VISUAL_RETRIEVAL_ENABLED=true
AURALYNQ_MODELFIT__ENABLED=true

# --- Recommended for a hosted demo: PRO-backed generation on free hardware ---
# Route generation through HF Inference Providers instead of renting a GPU for
# the Space. A large instruct model answers in seconds on cpu-basic, because no
# inference happens in the container at all. Set the two Variables below and
# HUGGINGFACE_TOKEN as a *Secret* (see the Secrets section).
#
# Cost model: inference bills to the token owner's account. A public,
# unauthenticated Space means anyone on the internet can spend that budget, so
# pair it with a rate limit and keep the corpus small.
# AURALYNQ_LLM__PROVIDER=huggingface
# AURALYNQ_LLM__MODEL=meta-llama/Llama-3.3-70B-Instruct
#
# Guardrails for a public, PRO-backed Space. The default (120/min) is sized for
# a local stack, not for funding strangers' traffic.
# AURALYNQ_SERVE__RATE_LIMIT_PER_MIN=10
# AURALYNQ_LLM__MAX_TOKENS=512
# AURALYNQ_RETRIEVAL__FINAL_K=4
#
# If the hosted budget/quota runs out, the fallback chain keeps the Space up:
#   Hugging Face -> local vLLM -> local Ollama -> local GGUF -> extractive
# so a spent quota degrades answer quality instead of 500-ing the demo.

# Hosted VLM page-image Q&A via HF Inference Providers (needs HUGGINGFACE_TOKEN,
# PRO for the 72B default). Off by default; explicit opt-in.
# AURALYNQ_VISUAL__VLM_ENABLED=true
# AURALYNQ_VISUAL__VLM_MODEL=Qwen/Qwen2.5-VL-72B-Instruct

# The browser always calls same-origin /api — Next.js proxies internally.
NEXT_PUBLIC_API_BASE=/api

# ================================ Secrets ===================================
# Set these ONLY as HF Space "Secrets" (Settings -> Variables and secrets ->
# New secret). Never as Variables, never committed anywhere, never baked
# into the Dockerfile.

# Empty = API is open (fine for a same-origin-only Space where the API isn't
# reachable directly). Set a random value if you expose the API port
# separately from the web UI.
# AURALYNQ_SERVE__API_KEY=

# Only needed if you want real model quality instead of the offline
# extractive/hash fallback. Every one of these is optional; missing keys
# degrade gracefully (ADR-0003) rather than breaking the Space.
#
# --- Powerful models via Hugging Face Inference Providers (recommended) ------
# Route generation through HF's OpenAI-compatible router — no GPU, no download.
# Large models (Llama-3.3-70B, Qwen2.5-72B, DeepSeek-V3) need a PRO account and
# bill to the token owner. Set HUGGINGFACE_TOKEN as a *Secret*, the rest as
# Variables (see the PRO-backed block above). Requires the image to include the
# `llm` extra (openai SDK) — deploy/huggingface/Dockerfile installs
# `.[ingest,llm]`. Without it the provider silently degrades to extractive.
#
# Scope the token to inference only ("Make calls to Inference Providers") — a
# write-scoped token in a Space secret is far more damaging if it ever leaks.
# HUGGINGFACE_TOKEN=            # Secret only
#
# --- Or other commercial providers ------------------------------------------
# AURALYNQ_LLM__PROVIDER=openai
# OPENAI_API_KEY=
# ANTHROPIC_API_KEY=
# COHERE_API_KEY=