.env.example

# Set these per deployment. Do not commit real identity or secrets.
DIGITAL_TWIN_OWNER_NAME=
DIGITAL_TWIN_OWNER_ROLE=
# Auto-detected from the connected LLM when left empty.
DIGITAL_TWIN_MODEL_NAME=
DIGITAL_TWIN_LLM_BASE_URL=
# Use `responses` for sage-control-plane or another native Responses endpoint.
DIGITAL_TWIN_LLM_API_MODE=chat_completions
# Portable default: execute manifest tools through ordinary chat completions.
# Set to native only when the upstream server has native tool parsing enabled.
DIGITAL_TWIN_LLM_TOOL_CALLING_MODE=compat
DIGITAL_TWIN_SKILL_TOOL_PARALLELISM=4
DIGITAL_TWIN_SKILL_ANSWER_MAX_TOKENS=768
# Optional: point health/diagnostics at the real vLLM-HUST metrics endpoint
# when DIGITAL_TWIN_LLM_BASE_URL uses a local auth proxy that does not expose /metrics.
# DIGITAL_TWIN_VLLM_METRICS_URL=http://<metrics-host>:<metrics-port>/metrics
# Replace EMPTY with a real secret before running vLLM-HUST or the local
# OpenAI-compatible proxy. The engine and app/proxy keys must match.
DIGITAL_TWIN_API_KEY=EMPTY

# Network topology. These are machine-local deployment inputs consumed by the
# app, site proxy, verification, and Cloudflare scripts.
APP_HOST=127.0.0.1
APP_PORT=55601
APP_HEALTH_HOST=127.0.0.1
SITE_HOST=127.0.0.1
SITE_PORT=8088
SITE_HEALTH_HOST=127.0.0.1

# Future dev-hub owner integration. Keep disabled until the paired producer,
# cooperative fencing and explicit instance/action approvals are qualified.
# An enrolled instance never falls back to legacy control, even when disabled.
SAGE_MATE_INSTANCE_CONTROL_ENABLED=0
SAGE_MATE_INSTANCE_REGISTRATION=

# Local model runtime. On Sage Mate macOS Apple Silicon installs, the installer
# writes vllm_metal and points DIGITAL_TWIN_LLM_BASE_URL at 127.0.0.1:8000/v1
# unless the user explicitly configured a remote endpoint.
DIGITAL_TWIN_LOCAL_MODEL_BACKEND=none
SAGE_MATE_VLLM_METAL_DIR=./deps/vllm-metal-hust
VLLM_METAL_MODEL=mlx-community/gemma-3-1b-it-qat-4bit
VLLM_METAL_HOST=127.0.0.1
VLLM_METAL_PORT=8000
VLLM_METAL_SERVED_MODEL_NAME=

# Public branding and ingress (set only when this deployment has public URLs).
DIGITAL_TWIN_HOMEPAGE_PUBLIC_URL=
FACULTY_TWIN_PUBLIC_HOSTNAME=
FACULTY_TWIN_TUNNEL_NAME=
TUNNEL_ORIGIN_URL=
# Required when enabling the tunnel directly; the release installer writes it.
TUNNEL_ORIGIN_HEALTH_URL=http://127.0.0.1:8088/

# Runtime data repository
# Keep production KB, accounts, memories, logs, and mutable state outside this
# code repo. When unset, Sage Mate uses ../sage-mate-runtime-private relative
# to the checkout. Override with an absolute path when needed.
# DIGITAL_TWIN_RUNTIME_DIR=/path/to/sage-mate-runtime-private

# Slack /twin slash command.
# Slack app setup:
#   Command: /twin
#   Request URL: https://<public-host>/slack/commands/twin
#   Scopes: commands, chat:write, im:history, app_mentions:read
# Slack DM / App Home setup:
#   Request URL: https://<public-host>/slack/events
#   Subscribe to bot events: message.im, app_mention
SLACK_TWIN_REQUEST_URL=
SLACK_TWIN_SIGNING_SECRET=
SLACK_TWIN_ALLOWED_USER_IDS=
SLACK_TWIN_VISITOR_PROFILE=lab_member
# Optional; falls back to TWIN_MONITOR_SLACK_BOT_TOKEN when unset.
SLACK_TWIN_BOT_TOKEN=

# Optional inference monitor Slack alerts. Prefer a U... user id for direct
# messages; D... DM channel ids can become inaccessible to the bot.
TWIN_MONITOR_SLACK_BOT_TOKEN=
TWIN_MONITOR_SLACK_USER_ID=
# TWIN_MONITOR_SLACK_CHANNEL_ID=

# Local content and storage
# These default to paths under DIGITAL_TWIN_RUNTIME_DIR. Override only when
# splitting a specific store away from the runtime repo.
# DIGITAL_TWIN_HOMEPAGE_DIR=/path/to/homepage-export
# DIGITAL_TWIN_KNOWLEDGE_BASE_DIR=/path/to/runtime/data/knowledge_base
# Public Wiki has its own derived index; never point this into the private KB.
# Configure identically for the app and Wiki sync service. Required for Wiki ingestion.
# DIGITAL_TWIN_WIKI_INDEX_DIR=/path/to/public/wiki-index
DIGITAL_TWIN_KNOWLEDGE_NAMESPACE=private
# Knowledge retrieval backend: sagevdb (recommended) or neuromem
DIGITAL_TWIN_KNOWLEDGE_BACKEND=sagevdb
DIGITAL_TWIN_KNOWLEDGE_SEARCH_CACHE_TTL_SECONDS=300
DIGITAL_TWIN_KNOWLEDGE_SEARCH_CACHE_MAX_ENTRIES=256
# Experimental Wiki-Link retrieval. Keep disabled unless evaluating the
# authored-link expansion contract with pinned evidence and matched controls.
DIGITAL_TWIN_KNOWLEDGE_LINK_EXPANSION_ENABLED=false
DIGITAL_TWIN_KNOWLEDGE_LINK_EXPANSION_DECAY=0.6
DIGITAL_TWIN_KNOWLEDGE_LINK_EXPANSION_MAX_DOCUMENTS=8
# NeuroMem conversation indexes continue to use SageANNS.
DIGITAL_TWIN_SAGEVDB_BACKEND=sage-anns
DIGITAL_TWIN_SAGEVDB_ANNS_ALGORITHM=faiss_hnsw
# Prefer exact cosine knowledge retrieval for the current 646-document corpus.
# Qualify SageANNS recall before changing this independent knowledge setting.
DIGITAL_TWIN_KNOWLEDGE_SAGEVDB_BACKEND=cpp
# Remote Qwen embedding/reranker through the authenticated unified gateway.
# Both clients reuse DIGITAL_TWIN_API_KEY; never store a second key here.
DIGITAL_TWIN_SAGEVDB_EMBEDDING_BACKEND=openai
DIGITAL_TWIN_SAGEVDB_EMBEDDING_MODEL=Qwen/Qwen3-Embedding-8B
DIGITAL_TWIN_SAGEVDB_EMBEDDING_BASE_URL=https://codex.sage.org.ai/v1
DIGITAL_TWIN_SAGEVDB_DIMENSION=1024
DIGITAL_TWIN_SAGEVDB_EMBEDDING_BATCH_SIZE=32
DIGITAL_TWIN_SAGEVDB_RERANKER_ENABLED=true
DIGITAL_TWIN_SAGEVDB_RERANKER_MODEL=Qwen/Qwen3-Reranker-0.6B
DIGITAL_TWIN_SAGEVDB_RERANKER_BASE_URL=https://codex.sage.org.ai/v1
DIGITAL_TWIN_SAGEVDB_RERANKER_DOCUMENT_MAX_CHARS=1500
# Optional neuromem index setting (only effective when DIGITAL_TWIN_KNOWLEDGE_BACKEND=neuromem).
DIGITAL_TWIN_NEUROMEM_INDEX_TYPE=faiss
# DIGITAL_TWIN_CONVERSATION_MEMORY_DIR=/path/to/runtime/data/conversation_memory

# Scheduling and notifications
# DIGITAL_TWIN_AVAILABILITY_SCHEDULE_PATH=/path/to/runtime/data/availability/current_week.json
DIGITAL_TWIN_BOOKING_NOTIFICATION_EMAIL=faculty@example.edu
# Optional live owner calendar bridge. A remote bridge may be exposed with an
# SSH reverse tunnel configured for the target host.
DIGITAL_TWIN_CALENDAR_BRIDGE_ENABLED=false
DIGITAL_TWIN_CALENDAR_BRIDGE_URL=
DIGITAL_TWIN_CALENDAR_BRIDGE_TOKEN=
DIGITAL_TWIN_CALENDAR_BRIDGE_LOOKAHEAD_DAYS=14
DIGITAL_TWIN_CALENDAR_BRIDGE_MAX_EVENTS=40
DIGITAL_TWIN_CALENDAR_BRIDGE_INCLUDE_DESCRIPTION=false

# Admin access
DIGITAL_TWIN_ADMIN_USERNAME=admin
DIGITAL_TWIN_ADMIN_PASSWORD=change-me-admin-password
DIGITAL_TWIN_ADMIN_SESSION_SECRET=change-me-admin-session-secret

# Chat latency / streaming knobs (defaults match production)
# Enable per-token streaming over SSE. Requires the upstream LLM endpoint to
# emit Transfer-Encoding: chunked. Verify with: curl -N -i ... | head — the
# response MUST contain `Transfer-Encoding: chunked`. HTTP/1.0 routers (e.g.
# Python's http.server) silently disable chunked and break streaming.
DIGITAL_TWIN_STREAM_CHAT_ANSWER=false
DIGITAL_TWIN_CHAT_REQUEST_TIMEOUT_SECONDS=80
DIGITAL_TWIN_LONG_CHAT_REQUEST_TIMEOUT_SECONDS=240
DIGITAL_TWIN_CHAT_MAX_INFLIGHT_REQUESTS=1
DIGITAL_TWIN_CHAT_ADMISSION_TIMEOUT_SECONDS=1
DIGITAL_TWIN_POST_ANSWER_BACKGROUND=true
DIGITAL_TWIN_PROMPT_SOFT_CAP=24000
DIGITAL_TWIN_LLM_TIMEOUT_SECONDS=60
DIGITAL_TWIN_LLM_FAST_ANSWER_MAX_TOKENS=192
DIGITAL_TWIN_LLM_DEEP_ANSWER_MAX_TOKENS=16384
# Only effective when the serving engine supports thinking_token_budget.
DIGITAL_TWIN_THINKING_TOKEN_BUDGET=16384
# Verify the actual endpoint before enabling. A Chat Completions endpoint may
# enforce the budget while its Responses endpoint silently ignores the field.
DIGITAL_TWIN_LLM_THINKING_BUDGET_SUPPORTED=false
DIGITAL_TWIN_LLM_RESPONSES_THINKING_BUDGET_SUPPORTED=false
DIGITAL_TWIN_LLM_POLICY_OUTPUT_MAX_TOKENS_CAP=32768
DIGITAL_TWIN_FAST_ANSWER_CONCISE_GUIDANCE_ENABLED=true
DIGITAL_TWIN_WARM_SERVICE_ON_STARTUP=true
DIGITAL_TWIN_CHAT_SSE_KEEPALIVE_SECONDS=1
DIGITAL_TWIN_CHAT_PROMPT_SOFT_CAP_CHARS=12000
DIGITAL_TWIN_FAST_INTENT_CLASSIFIER_ENABLED=true
# Experimental comparison-only planner. It does not affect the executed DAG
# and adds an extra LLM request, so keep it off for interactive deployments.
DIGITAL_TWIN_SHADOW_PLANNER_ENABLED=false

# Optional vLLM-HUST fixed-prefix cache namespace.
# Uses vLLM's native cache_salt field; no vLLM-HUST changes are required.
DIGITAL_TWIN_KV_FIXED_PREFIX_MATERIALIZATION_ENABLED=true
DIGITAL_TWIN_KV_FIXED_PREFIX_ANCHOR_PREFIX=sage-faculty-twin-fixed-prefix
# Bump this when the fixed system/persona/installed-skill prompt changes.
DIGITAL_TWIN_KV_FIXED_PREFIX_ANCHOR_VERSION=skills-v1
DIGITAL_TWIN_KV_FIXED_PREFIX_WARMUP_ON_STARTUP=true
DIGITAL_TWIN_KV_FIXED_PREFIX_WARMUP_MAX_TOKENS=1
DIGITAL_TWIN_DYNAMIC_CONTEXT_MATERIALIZATION_ENABLED=true
# Optional segment-reuse control-plane hints. Keep disabled unless the
# vLLM-HUST runtime has a compatible VLLM_SEGMENT_REUSE=stitch path.
DIGITAL_TWIN_SEGMENT_REUSE_HINTS_ENABLED=false
DIGITAL_TWIN_SEGMENT_REUSE_NAMESPACE_PREFIX=sage-faculty-twin
DIGITAL_TWIN_SEGMENT_REUSE_BOUNDARY_CLASS=control-only
DIGITAL_TWIN_SEGMENT_REUSE_MAX_LEADING_TOKENS=4096
DIGITAL_TWIN_INSTALLED_SKILL_PROMPT_ENABLED=true
# Defaults under DIGITAL_TWIN_RUNTIME_DIR:
# DIGITAL_TWIN_INSTALLED_SKILL_PROMPT_PATH=/path/to/runtime/data/installed_skills/fixed_prompt_skills.md

# Optional web search (Tavily)
DIGITAL_TWIN_WEB_SEARCH_ENABLED=true
# Per-question auto/never/always decisions are owned by SAGE, not a global trigger.
DIGITAL_TWIN_WEB_SEARCH_MAX_RESULTS=3
DIGITAL_TWIN_WEB_SEARCH_TIMEOUT_SECONDS=8
# You can also set plain TAVILY_TOKEN in parent env files.
DIGITAL_TWIN_TAVILY_TOKEN=

# Optional systemd OpenAI proxy for vLLM.
# Proxy chain: app → OpenAI-compatible proxy → configured vLLM endpoint.
# VLLM_PROXY_UPSTREAM_BASE_URL must be set to the endpoint for this machine.
# VLLM_PROXY_UPSTREAM_API_KEY must match VLLM_HUST_API_KEY so auth_proxy accepts the request.
VLLM_PROXY_HOST=127.0.0.1
VLLM_PROXY_PORT=18001
VLLM_PROXY_CONNECT_HOST=127.0.0.1
VLLM_PROXY_PATH_PREFIX=/v1
VLLM_PROXY_UPSTREAM_BASE_URL=
VLLM_PROXY_UPSTREAM_API_KEY=
VLLM_PROXY_TRUST_ENV=false
# Engine-native bounded state and operator metadata for POST /v1/responses.
# The public proxy remains a thin authentication/rate-limit/audit boundary.
VLLM_ENABLE_RESPONSES_API_STORE=1
VLLM_RESPONSES_API_STORE_MAX_ENTRIES=256
VLLM_RESPONSES_API_STORE_TTL_SECONDS=3600
# Container path to a reviewed model catalog already present in a mounted
# runtime directory; do not point this at an arbitrary host file.
VLLM_OPENAI_MODELS_CATALOG_JSON=

# NVIDIA engine connection address (used only with the NVIDIA engine service).
VLLM_NVIDIA_CONNECT_HOST=127.0.0.1

# vLLM-HUST engine config (used by sage-mate-vllm-engine.service).
# The engine always runs inside a Docker container with NPU/GPU devices
# and CANN toolkit pre-installed.  Graph mode is ON (no --enforce-eager).
# Model selection can be automatic (recommended for machine-independent deployment):
# set VLLM_ENGINE_AUTO_RESOLVE_MODEL=true to auto-select a local model from the
# preferred families, optionally downloading if missing. When false, explicit
# VLLM_ENGINE_MODEL_PATH is required.
# The default family preference is GLM -> DeepSeek -> MiniMax -> Qwen.
# You may optionally override these env vars:
# - VLLM_ENGINE_MODEL_FAMILY_ORDER=glm,deepseek,minimax,qwen
# - VLLM_ENGINE_MODEL_ROOTS=/data/shared_models/modelscope_cache,/data/shared_models/huggingface_cache/hub
# - VLLM_ENGINE_AUTO_DOWNLOAD=true
# - VLLM_ENGINE_FAMILY_REMOTE_GLM_CANDIDATES=THUDM/glm-4-9b-chat
# - VLLM_ENGINE_FAMILY_REMOTE_DEEPSEEK_CANDIDATES=deepseek-ai/DeepSeek-V2.5,deepseek-ai/DeepSeek-V2
# - VLLM_ENGINE_FAMILY_REMOTE_MINIMAX_CANDIDATES=
# - VLLM_ENGINE_FAMILY_PATTERNS_GLM=glm
# - VLLM_ENGINE_FAMILY_PATTERNS_DEEPSEEK=deepseek
# - VLLM_ENGINE_FAMILY_PATTERNS_MINIMAX=minimax,minimaxi
# - VLLM_ENGINE_FAMILY_PATTERNS_QWEN=qwen
# - VLLM_ENGINE_FAMILY_REMOTE_QWEN_CANDIDATES=Qwen/Qwen3___5-35B-A3B,Qwen/Qwen3-32B
# Allow deployments to force model families while still keeping automatic discovery.
VLLM_ENGINE_REQUIRED_FAMILIES=
VLLM_ENGINE_ALLOW_QWEN_FALLBACK=0
VLLM_ENGINE_CONTAINER=
VLLM_ENGINE_AUTO_RESOLVE_MODEL=true
VLLM_ENGINE_AUTO_CREATE_CONTAINER=true
VLLM_ENGINE_CONTAINER_NON_INTERACTIVE=1
# Private engine logs are bounded and rotated before launch.
VLLM_ENGINE_LOG_MAX_BYTES=67108864
VLLM_ENGINE_LOG_BACKUP_COUNT=3
# Large TP/DP models may require substantially more process shared memory.
# Set this per deployment profile; for example, official DeepSeek-V4 A2 uses 512g.
VLLM_ENGINE_CONTAINER_SHM_SIZE=16g
# Optional allocator library path inside the container only.
VLLM_ENGINE_CONTAINER_LD_PRELOAD=
# Worker creation is deployment-specific. `spawn` avoids fork-related plugin
# subprocess failures in large tensor-parallel deployments.
VLLM_WORKER_MULTIPROC_METHOD=
# Increase HCCL rendezvous time for large TP jobs when source/plugin imports
# make worker creation slower than the runtime default.
HCCL_CONNECT_TIMEOUT=
HCCL_EXEC_TIMEOUT=
VLLM_HUST_AUTO_ENABLE_CONTAINER_SSH=0
HOST_WORKSPACE_ROOT=./deps
# Resolve both runtime packages from the repository submodules mounted at the
# container workspace. This keeps deployments reproducible from the pinned
# source tree instead of silently falling back to packages baked into an image.
VLLM_ENGINE_BASE_PYTHONPATH=/workspace/vllm-ascend-hust:/workspace/vllm-hust
# Optional fail-closed contract for a runtime package intentionally installed
# as a wheel instead of mounted from a declared source root. Each entry must
# name its distribution and exact version; the launcher and verifier also
# confirm that the imported module file is owned by that distribution.
# Example: {"vllm_ascend":{"distribution":"vllm-ascend-hust","version":"0.19.1"}}
VLLM_ENGINE_INSTALLED_MODULES_JSON={}
# Keep disabled so a plugin checkout baked into the image cannot override the
# pinned repository submodules. CANN-only inherited Python paths are preserved.
VLLM_ENGINE_INHERIT_PYTHONPATH=0
# Optional override. The launcher default enables the full Ascend plugin set,
# including model registration; setting only `ascend` is insufficient.
VLLM_PLUGINS=
VLLM_ENGINE_BIN=vllm-hust
VLLM_ENGINE_MODEL_PATH=
VLLM_ENGINE_CONNECT_HOST=127.0.0.1
VLLM_ENGINE_CONNECT_PORT=8000
VLLM_ENGINE_PORT=8000
VLLM_ENGINE_TP_SIZE=
VLLM_ENGINE_MAX_MODEL_LEN=32768
VLLM_ENGINE_GPU_MEM_UTIL=0.85
VLLM_ENGINE_MAX_NUM_SEQS=16
VLLM_ENGINE_DTYPE=bfloat16
# Production must fail closed instead of silently accepting a stale local
# override that disables reusable-prefix computation.
VLLM_ENGINE_ENABLE_PREFIX_CACHING=1
VLLM_ENGINE_REQUIRE_PREFIX_CACHING=1
# Optional; required as `fp8` by DeepSeek-V4's fp8_ds_mla cache layout.
VLLM_ENGINE_KV_CACHE_DTYPE=
# Optional deterministic KV-cache budget per device. This is useful when lazy
# graph allocations make automatic free-memory snapshots unreliable.
VLLM_ENGINE_KV_CACHE_MEMORY_BYTES=
# Set this to a container path whose .cache directory is bind-mounted to
# preserve torch/Ascend compilation artifacts across container recreation.
# VLLM_ENGINE_CONTAINER_HOME=/root
# Optional DeepSeek/Ascend memory controls. MLAPO favors throughput at the
# cost of NPU memory. The free-memory fraction is a safety cap used when the
# backend cannot profile graph memory before allocating KV cache.
VLLM_ASCEND_ENABLE_MLAPO=1
VLLM_ASCEND_KV_CACHE_FREE_MEMORY_FRACTION=0.8
# Ascend NPU device selection is machine-local. Set the allowed pool and the
# selected devices explicitly for each deployment; do not commit host IDs.
VLLM_ENGINE_ALLOWED_NPU_IDS=
VLLM_ENGINE_NPU_DEVICES=
ASCEND_RT_VISIBLE_DEVICES=