Referencia: configuración

Para la tabla exhaustiva con todas las variables (backend + frontend + compose + bootstrap), ver Variables de entorno (entrega).

Esta página documenta todas las variables de entorno y settings del backend de Camarero IA. Es una referencia exhaustiva derivada de las fuentes:

• backend/app/core/config.py — clase Settings (pydantic-settings).
• backend/.env.example — plantilla del backend.
• .env.example — plantilla de la raíz (backend + frontend).

Cómo se cargan los valores

La configuración se resuelve con pydantic-settings. Las variables se leen, por orden, de los ficheros .env y .env.local (ver class Config en backend/app/core/config.py). El cotejo de nombres es case-insensitive (case_sensitive = False) y las variables desconocidas se ignoran (extra = "ignore"). El prefijo de entorno está vacío (env_prefix = ""), por lo que el nombre de la variable de entorno coincide con el del campo en mayúsculas (p. ej. el campo database_url se lee de DATABASE_URL).

Aplicación

Variable	Campo (Settings)	Uso	Por defecto
APP_NAME	app_name	Nombre de la aplicación.	Camarero IA
DEBUG	debug	Modo depuración.	false

Etiquetas de entorno admitidas en DEBUG

DEBUG acepta booleanos estrictos y etiquetas de entorno gracias al validador normalize_debug: release/prod/production → False; dev/development → True.

Base de datos

Variable	Campo	Uso	Por defecto
DATABASE_URL	database_url	URL de conexión a PostgreSQL (driver asyncpg).	postgresql+asyncpg://camarero_user:camarero_password@localhost:5432/camarero_db

Driver async obligatorio

El valor por defecto usa postgresql+asyncpg://. El backend trabaja con SQLAlchemy async, por lo que la URL debe usar el driver asyncpg. La plantilla de la raíz (.env.example) muestra un postgresql:// sin driver; úsalo solo como referencia y mantén +asyncpg para el backend.

Seguridad y JWT

Variable	Campo	Uso	Por defecto
SECRET_KEY	secret_key	Clave de firma. Obligatoria (mín. 32 caracteres).	"" (inválido)
ALGORITHM	algorithm	Algoritmo de firma JWT.	HS256
ACCESS_TOKEN_EXPIRE_MINUTES	access_token_expire_minutes	Expiración del access token, en minutos.	10080 (7 días)

SECRET_KEY se valida en arranque

El validador validate_secret_key rechaza una clave vacía o de menos de 32 caracteres en todos los entornos. Si no se cumple, la aplicación falla al instanciar Settings. Genera una con:

openssl rand -hex 32

Impuestos

Variable	Campo	Uso	Por defecto
DEFAULT_TAX_RATE	default_tax_rate	Tasa de IVA por defecto (porcentaje entero).	10

CORS

Variable	Campo	Uso	Por defecto
CORS_ORIGINS	cors_origins	Lista de orígenes permitidos.	["http://localhost:3000", "http://localhost:5173"]

Formato de CORS_ORIGINS

Es una lista. En .env se expresa como JSON, tal y como muestra el comentario de backend/.env.example:

CORS_ORIGINS=["https://camarero-demo.n0idea.app","http://localhost:3000"]

OAuth2 (Google y Apple)

Configuración de inicio de sesión por OAuth, separada por audiencia: cliente (customer) y administrador (admin).

Variable	Campo	Uso	Por defecto
GOOGLE_CUSTOMER_CLIENT_ID	google_customer_client_id	Client ID de Google (cliente).	""
GOOGLE_CUSTOMER_CLIENT_SECRET	google_customer_client_secret	Client secret de Google (cliente).	""
CUSTOMER_REDIRECT_URI	customer_redirect_uri	Redirect URI tras login de cliente.	http://localhost:3000/auth/callback
GOOGLE_ADMIN_CLIENT_ID	google_admin_client_id	Client ID de Google (admin).	""
GOOGLE_ADMIN_CLIENT_SECRET	google_admin_client_secret	Client secret de Google (admin).	""
ADMIN_REDIRECT_URI	admin_redirect_uri	Redirect URI tras login de admin.	http://localhost:3000/admin/auth/callback
APPLE_CUSTOMER_CLIENT_ID	apple_customer_client_id	Client ID de Apple (cliente).	""
APPLE_CUSTOMER_CLIENT_SECRET	apple_customer_client_secret	Client secret de Apple (cliente).	""
APPLE_ADMIN_CLIENT_ID	apple_admin_client_id	Client ID de Apple (admin).	""
APPLE_ADMIN_CLIENT_SECRET	apple_admin_client_secret	Client secret de Apple (admin).	""
OAUTH_REDIRECT_URI_ALLOWLIST	oauth_redirect_uri_allowlist	Allowlist de redirect URIs (separadas por coma).	""
APPLE_JWKS_TIMEOUT_SECONDS	apple_jwks_timeout_seconds	Timeout de descarga del JWKS de Apple (segundos).	5

Allowlist de redirect_uri (SEC03)

OAUTH_REDIRECT_URI_ALLOWLIST endurece la validación de redirect_uri (RFC 6749 §10.6 / RFC 7636). Cuando está vacía, el sistema usa como allowlist el conjunto {customer_redirect_uri, admin_redirect_uri} (propiedad oauth_redirect_uri_allowlist_set), de modo que los despliegues que ya fijan un redirect por audiencia siguen funcionando sin nuevas variables.

Timeout del JWKS de Apple (SEC-OAUTH01)

APPLE_JWKS_TIMEOUT_SECONDS acota tanto el timeout de socket de PyJWKClient como un techo de asyncio.wait_for, para que la petición nunca se cuelgue. El fallo es fail-closed (responde 500, no 401, porque el token aún no se había verificado).

IA (LLM vía NVIDIA NIM)

Variable	Campo	Uso	Por defecto
NVIDIA_API_KEY	nvidia_api_key	API key de NVIDIA NIM.	""
NVIDIA_MODEL	nvidia_model	Modelo de chat.	stepfun-ai/step-3.5-flash
NVIDIA_BASE_URL	nvidia_base_url	Base URL del proveedor.	https://integrate.api.nvidia.com/v1
AI_STREAM_TIMEOUT_SECONDS	ai_stream_timeout_seconds	Máximo de segundos a esperar el primer frame del proveedor (streaming).	60
MAX_AI_TOKENS_PER_SESSION	max_ai_tokens_per_session	Límite total de tokens IA (prompt + completion) por sesión de mesa. 0 desactiva el tope.	200000

Resiliencia del streaming (ERR02)

AI_STREAM_TIMEOUT_SECONDS se eligió por debajo del read timeout de httpx hacia NVIDIA (120 s), de forma que el timeout del use case dispare primero y el cliente reciba un frame de error estructurado en lugar de una caída abrupta de conexión. Se subió a 60 s para modelos de razonamiento lentos tras el proxy de NVIDIA.

Control de coste de IA (AI01)

MAX_AI_TOKENS_PER_SESSION es un tope duro de tokens por sesión de mesa. 0 desactiva el límite.

Alias heredados (compatibilidad)

Variable	Campo	Uso	Por defecto
STEPFUN_API_KEY	stepfun_api_key	Alias heredado de la API key.	""
STEPFUN_MODEL	stepfun_model	Alias heredado del modelo.	stepfun-ai/step-3.5-flash

Precedencia de la API key

La propiedad ai_api_key resuelve la clave efectiva: nvidia_api_key tiene prioridad y, si está vacía, se usa stepfun_api_key.

Embeddings y chat híbrido

El modelo de embeddings alimenta el clasificador de intenciones y el recomendador basado en contenido. Se carga de forma perezosa en el propio proceso.

Variable	Campo	Uso	Por defecto
EMBEDDINGS_ENABLED	embeddings_enabled	Activa el modelo de embeddings en proceso.	true
EMBEDDINGS_MODEL_NAME	embeddings_model_name	Modelo de embeddings.	sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
EMBEDDINGS_CACHE_DIR	embeddings_cache_dir	Directorio de caché del modelo (se exporta como HF_HOME antes de la primera carga).	""

Tests y CI

En CI/tests se fija EMBEDDINGS_ENABLED=false para que las suites nunca descarguen el modelo (~390 MB).

Clasificador de intenciones

Variable	Campo	Uso	Por defecto
INTENT_MIN_CONFIDENCE	intent_min_confidence	Umbral de similitud coseno por debajo del cual el mensaje va a la rama LLM de fallback.	0.65

Note

El min_confidence por árbol en el JSON sobrescribe este valor para el nodo classify.

Resolutor semántico de productos

Umbrales de coseno para la extracción de pedidos en el chat.

Variable	Campo	Uso	Por defecto
RESOLVER_ACCEPT_THRESHOLD	resolver_accept_threshold	El top-1 debe superarlo para ser candidato.	0.50
RESOLVER_AMBIGUOUS_FLOOR	resolver_ambiguous_floor	Candidatos por encima compiten en la desambiguación.	0.45
RESOLVER_MARGIN	resolver_margin	Si top1 - top2 está por debajo → ambiguo (se muestran opciones) en vez de adivinar.	0.06

Intérprete del árbol de decisiones

Variable	Campo	Uso	Por defecto
INTERPRETER_MAX_STEPS	interpreter_max_steps	Tope de nodos recorridos por mensaje (anti-bucle).	50
INTERPRETER_ACTION_TIMEOUT_SECONDS	interpreter_action_timeout_seconds	Timeout por acción.	5

POS (TPV)

Variable	Campo	Uso	Por defecto
POS_ADAPTER_TYPE	pos_adapter_type	Selector de adaptador de TPV.	local

Note

local cablea el LocalPOSAdapter interno (sin TPV externo). Un futuro valor hiopos seleccionará HioposPOSAdapter.

Rate limiting

Variable	Campo	Uso	Por defecto
REDIS_URL	redis_url	URL de Redis para el limiter.	""
VALKEY_URL	valkey_url	URL de Valkey (alternativa a Redis).	""

Selección del backend del limiter (RATE01)

Si hay una URL configurada, se usa el limiter respaldado por Redis; en caso contrario, degrada a un limiter respaldado por una tabla de Postgres. La propiedad rate_limiter_redis_url resuelve la URL efectiva: redis_url tiene prioridad y, si está vacía, se usa valkey_url.

Variables del frontend

Definidas en la plantilla de la raíz (.env.example); las consume el frontend, no la clase Settings del backend.

Variable	Uso	Por defecto
NEXT_PUBLIC_API_URL	URL base de la API que usa el frontend.	http://localhost:8000/api/v1
NEXT_PUBLIC_APP_URL	URL pública de la app.	http://localhost:3000

Bootstrap (uso puntual)

Presente en backend/.env.example para la creación inicial de un superadmin. No es un campo de Settings.

Variable	Uso
ADMIN_SUPER_EMAIL	Email del superadmin a crear una sola vez (eliminar tras el primer arranque).

Ejemplo mínimo de .env (backend)

DATABASE_URL=postgresql+asyncpg://camarero_user:camarero_password@localhost:5432/camarero_db
SECRET_KEY=  # generar con: openssl rand -hex 32
DEBUG=false
NVIDIA_API_KEY=nvapi----
# CORS_ORIGINS=["https://camarero-demo.n0idea.app","http://localhost:3000"]