.env.example

# HelixAgent Environment Configuration
# COPY THIS FILE TO .env AND FILL IN YOUR ACTUAL VALUES
# NEVER COMMIT .env FILES WITH REAL API KEYS
# =============================================================================

# =============================================================================
# CRITICAL SECURITY WARNING
# =============================================================================
# This file contains placeholders ONLY. Create a .env file with real values.
# The .env file is gitignored and will NEVER be committed.
# API keys are sensitive - treat them like passwords!
# 
# To set up:
#   cp .env.example .env
#   # Edit .env and fill in your values
# =============================================================================

# =============================================================================
# HELIXMEMORY CONFIGURATION (Unified Cognee + Mem0 + Letta)
# =============================================================================

# Memory System Mode: "local" (containers) or "cloud" (API)
# - "local": Runs all services in Docker containers (default, recommended)
# - "cloud": Uses cloud API endpoints (requires API keys)
#
# IMPORTANT: Cognee requires a paid subscription for cloud access.
# If you don't have COGNEE_API_KEY, leave it empty and HelixMemory will
# automatically use the local Cognee container.
HELIX_MEMORY_MODE=local

# --- LOCAL MODE (Containers) - DEFAULT RECOMMENDED ---
# These endpoints are used when HELIX_MEMORY_MODE=local
# All services run in Docker containers via docker-compose.memory.yml
HELIX_MEMORY_COGNEE_ENDPOINT=http://localhost:8000
HELIX_MEMORY_MEM0_ENDPOINT=http://localhost:8001
HELIX_MEMORY_LETTA_ENDPOINT=http://localhost:8283
HELIX_MEMORY_GRAPHITI_ENDPOINT=http://localhost:8003

# --- CLOUD MODE (API) - Only if you have API keys ---
# Cognee: https://platform.cognee.ai - REQUIRES PAID SUBSCRIPTION
# Mem0: https://app.mem0.ai - Free tier available
# Letta: https://docs.letta.com - Free tier available
#
# IMPORTANT: If COGNEE_API_KEY is empty, local container will be used
# even if HELIX_MEMORY_MODE=cloud for other services

# Cloud API Keys (leave empty to use local containers)
HELIX_MEMORY_COGNEE_API_KEY=              # Cognee PAID - leave empty for local
HELIX_MEMORY_MEM0_API_KEY=your-mem0-key   # Mem0 - get from app.mem0.ai
HELIX_MEMORY_LETTA_API_KEY=your-letta-key # Letta - get from docs.letta.com

# Cloud Endpoints (only used when API keys are provided)
# These are the defaults - only change if using custom endpoints
HELIX_MEMORY_COGNEE_CLOUD_ENDPOINT=https://api.cognee.ai
HELIX_MEMORY_MEM0_CLOUD_ENDPOINT=https://api.mem0.ai
HELIX_MEMORY_LETTA_CLOUD_ENDPOINT=https://api.letta.com

# --- INFRASTRUCTURE (for local mode) ---
HELIX_MEMORY_QDRANT_ENDPOINT=http://localhost:6333
HELIX_MEMORY_NEO4J_ENDPOINT=bolt://localhost:7687
HELIX_MEMORY_NEO4J_USER=neo4j
HELIX_MEMORY_NEO4J_PASSWORD=helixmemory
HELIX_MEMORY_REDIS_ENDPOINT=localhost:6380
HELIX_MEMORY_REDIS_PASSWORD=

# --- FUSION ENGINE ---
HELIX_MEMORY_FUSION_DEDUP_THRESHOLD=0.92
HELIX_MEMORY_DEFAULT_TOP_K=10
HELIX_MEMORY_REQUEST_TIMEOUT=10s

# --- CONSOLIDATION (Sleep-Time Compute) ---
HELIX_MEMORY_CONSOLIDATION_ENABLED=true
HELIX_MEMORY_CONSOLIDATION_INTERVAL=30m

# --- CIRCUIT BREAKER ---
HELIX_MEMORY_CIRCUIT_BREAKER_THRESHOLD=5
HELIX_MEMORY_CIRCUIT_BREAKER_TIMEOUT=30s

# =============================================================================
# HELIXLLM CONFIGURATION (Submodule Integration)
# =============================================================================

# Enable/disable HelixLLM submodule integration
# When enabled, HelixAgent will automatically start and manage HelixLLM containers
# Local-first default (spec 002, HA-F2-002): ON unless set to an explicit
# false/0/no/off.
USE_HELIX_LLM=true

# -----------------------------------------------------------------------------
# CLOUD PROVIDER OPT-IN  (local-first default, spec 002 / HA-F2-002)
# -----------------------------------------------------------------------------
# Everything HelixAgent serves runs LOCALLY by default. Cloud providers stay in
# the code but are DISABLED unless you explicitly opt in here.
#
# This one switch gates every IMPLICIT cloud acquisition — every path where the
# process would decide on its own, from a credential in your environment (or
# from no credential at all), to build a cloud client or send a cloud request:
#
#   * provider auto-discovery in the registry
#   * providers enabled from an env API key (ANTHROPIC_API_KEY,
#     DEEPSEEK_API_KEY, GEMINI_API_KEY, QWEN_API_KEY, OPENROUTER_API_KEY)
#   * the credential-less anonymous zen endpoint
#   * boot-time verifier discovery + verification prompts
#   * OpenAI embeddings on POST /v1/protocols/execute (OPENAI_API_KEY);
#     without the opt-in the local embedding fallback is used
#   * OAuth session refresh driven by the mere PRESENCE of
#     ~/.claude/.credentials.json or ~/.qwen/oauth_creds.json
#
# Leaving an API key in this file (or in your shell) is therefore NOT by itself
# enough to reach a cloud provider. A provider you configure explicitly by hand
# is not gated — you already made that decision.
#
# Default: unset (= OFF). Opt in with true/1/yes/on.
# HELIX_CLOUD_PROVIDERS=true

# --- Connection Settings ---
HELIX_LLM_ENDPOINT=http://localhost:8443
HELIX_LLM_API_KEY=
HELIX_LLM_TLS_SKIP_VERIFY=true  # Set to false in production with valid certs

# --- HelixAgent -> HelixLLM CLIENT connection over LAN / VPN (env-parameterized) ---
# The helixllm.Provider reaches an OpenAI-compatible router (the coder fleet on
# :18434, or the :8443 gateway) using this precedence — first non-empty wins:
#   1. explicit provider baseURL
#   2. HELIX_LLM_LOCAL_OPENAI_ENDPOINT   (explicit base URL seam; RECOMMENDED for LAN)
#   3. HELIX_LLM_ENDPOINT                (line above; general override)
#   4. HELIX_LLM_HOST / HELIX_LLM_PORT   (composed http://HOST:PORT; see caveat)
#   5. the TLS :8443 gateway default
# To point HelixAgent at the coder over the LAN/VPN, set EITHER (recommended):
#   HELIX_LLM_LOCAL_OPENAI_ENDPOINT=http://10.6.100.221:18434   # base, NO /v1
# OR the HOST/PORT composition (client target — defaults localhost:18434):
#   (uncomment to use — but NOTE: HELIX_LLM_HOST/HELIX_LLM_PORT below in
#    "Server Settings" set the HelixLLM SERVER bind; the SAME names are reused as
#    the CLIENT target here. Because HELIX_LLM_ENDPOINT above is set, the HOST/PORT
#    composition is INERT by default — it only engages when both endpoint seams
#    are unset. A bind-all 0.0.0.0 is mapped to localhost for the client.)
#   HELIX_LLM_HOST=10.6.100.221
#   HELIX_LLM_PORT=18434
# The endpoint MUST be the BASE without /v1 (the provider appends
# /v1/chat/completions itself; a trailing /v1 -> /v1/v1 -> 404; normalizeBase
# strips a trailing /v1 defensively). If the router enforces auth, set
# HELIX_LLM_API_KEY (sent as "Authorization: Bearer <key>"). Export secrets via a
# gitignored api_keys.sh (see api_keys.sh.example) or this .env — never commit a
# real key (CONST-042 / §11.4.10). Full guide: helix_llm docs/OPERATOR_GUIDE.md §7.

# --- Mode Configuration ---
HELIX_LLM_MODE=full
# full | gateway | brain | knowledge | agents | control

# --- Server Settings ---
HELIX_LLM_PORT=8443
HELIX_LLM_HOST=0.0.0.0

# --- Database Configuration ---
HELIX_LLM_DB_HOST=helixllm-postgres
HELIX_LLM_DB_PORT=5432
HELIX_LLM_DB_NAME=helixllm
HELIX_LLM_DB_USER=helix
HELIX_LLM_DB_PASSWORD=helixllm

# --- Redis Configuration ---
HELIX_LLM_REDIS_HOST=helixllm-redis
HELIX_LLM_REDIS_PORT=6379
HELIX_LLM_REDIS_PASSWORD=helixllm123

# --- Vector Database ---
HELIX_LLM_VECTOR_DB=qdrant
HELIX_LLM_QDRANT_HTTP_PORT=6333
HELIX_LLM_QDRANT_GRPC_PORT=6334

# --- LLM Configuration ---
HELIX_LLM_LOCAL_MODEL=Llama-3.1-8B-Instruct-Q4_K_M
HELIX_LLM_DEFAULT_PROVIDER=local
HELIX_LLM_OPENAI_KEY=
HELIX_LLM_ANTHROPIC_KEY=

# --- Knowledge/RAG Configuration ---
HELIX_LLM_EMBEDDING_PROVIDER=local
HELIX_LLM_EMBEDDING_MODEL=all-mpnet-base-v2
HELIX_LLM_RAG_CHUNK_SIZE=1000
HELIX_LLM_RAG_CHUNK_OVERLAP=200
HELIX_LLM_RAG_TOP_K=5

# --- Feature Flags ---
HELIX_LLM_FEATURE_GRPC=true
HELIX_LLM_FEATURE_TOON=true
HELIX_LLM_FEATURE_SELFIMPROVE=false

# --- Messaging ---
HELIX_LLM_KAFKA_PORT=9093
HELIX_LLM_KAFKA_BROKERS=helixllm-kafka:9092

# --- Monitoring ---
HELIX_LLM_PROMETHEUS_PORT=9091
HELIX_LLM_LOG_LEVEL=info
HELIX_LLM_LOG_FORMAT=json
HELIX_LLM_OTEL_EXPORTER=otlp

# --- Integration with HelixAgent Services ---
# LLM Provider API Keys (for HelixLLM brain layer)
HELIX_LLM_OPENAI_KEY=
HELIX_LLM_ANTHROPIC_KEY=

HELIX_LLM_USE_HELIXAGENT_MCP=true
HELIX_LLM_USE_HELIXAGENT_LSP=true
HELIX_LLM_USE_HELIXAGENT_ACP=true
HELIX_LLM_USE_HELIXAGENT_EMBEDDINGS=true
HELIX_LLM_USE_HELIXAGENT_RAG=true
HELIX_LLM_USE_HELIXAGENT_MEMORY=true

# =============================================================================
# SETUP INSTRUCTIONS
# =============================================================================
#
# OPTION 1: Local Mode (Recommended - Free)
# ------------------------------------------
# 1. Check hardware: ./scripts/check_memory_hardware.sh
# 2. Start services: podman-compose -f docker-compose.memory.yml up -d
# 3. All services run locally, no API keys needed for Cognee
# 4. Optional: Add MEM0_API_KEY and LETTA_API_KEY if you want cloud backup
#
# OPTION 2: Cloud Mode (Paid for Cognee)
# --------------------------------------
# 1. Get API keys:
#    - Cognee: https://platform.cognee.ai (PAID subscription required)
#    - Mem0: https://app.mem0.ai (free tier available)
#    - Letta: https://docs.letta.com (free tier available)
# 2. Set HELIX_MEMORY_MODE=cloud
# 3. Fill in all HELIX_MEMORY_*_API_KEY values
# 4. Services will use cloud APIs instead of local containers
#
# OPTION 3: Hybrid Mode (Mixed)
# -----------------------------
# Set HELIX_MEMORY_MODE=local
# Provide API keys only for services you want in cloud
# Missing API keys will use local containers automatically
#
# =============================================================================

# =============================================================================
# LLM PROVIDER API KEYS
# =============================================================================
# At least one provider is required for HelixAgent to function

# OpenAI (Recommended)
OPENAI_API_KEY=sk-your-openai-key

# Anthropic Claude
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

# DeepSeek
DEEPSEEK_API_KEY=sk-your-deepseek-key

# Groq (Fast)
GROQ_API_KEY=gsk-your-groq-key

# Mistral
MISTRAL_API_KEY=your-mistral-key

# Cohere
COHERE_API_KEY=your-cohere-key

# Perplexity
PERPLEXITY_API_KEY=pplx-your-perplexity-key

# Google Gemini
GEMINI_API_KEY=your-gemini-key

# =============================================================================
# PORT REGISTRY — see docs/development/port-registry.md
# =============================================================================
# HelixAgent ports live in the 81xx band by default.
# Switch the whole system to 91xx with HELIXAGENT_PORT_PREFIX=9.
# Override any individual port by setting its HELIXAGENT_PORT_* var.
HELIXAGENT_PORT_PREFIX=8
HELIXAGENT_PORT_HTTP=8100
HELIXAGENT_PORT_POSTGRES=8101
HELIXAGENT_PORT_REDIS=8102
HELIXAGENT_PORT_MCP_BRIDGE=8103
HELIXAGENT_PORT_HELIXLLM=8105
HELIXAGENT_PORT_REDIS_MCP=8110
HELIXAGENT_PORT_GRPC=8112
HELIXAGENT_PORT_COGNEE=8120
HELIXAGENT_PORT_CHROMADB=8121
HELIXAGENT_PORT_QDRANT=8122
HELIXAGENT_PORT_NEO4J_HTTP=8123
HELIXAGENT_PORT_NEO4J_BOLT=8124
HELIXAGENT_PORT_PROMETHEUS=8310
HELIXAGENT_PORT_GRAFANA=8311
HELIXAGENT_PORT_JAEGER=8312

# =============================================================================
# INTEGRATION-TEST STRICTNESS
# =============================================================================
# HELIXAGENT_REQUIRED — declares that a real HelixAgent IS deployed at the
# address the integration tests probe (HELIXAGENT_URL, else
# HELIXAGENT_PORT_HTTP above).
#
# Unset (default): tests/integration guards SKIP when the /health endpoint is
# unreachable or answers without identifying as "helixagent". That fail-open
# default keeps an absent environment from being reported as a product defect.
#
# Set to exactly 1: those same guards FAIL instead of skipping.
#
# Why you want it where HelixAgent is genuinely deployed: three of the four
# non-identifying outcomes are HelixAgent REGRESSIONS — a dropped /health
# route (404), a panicking handler (500), a lost "service" identity field
# (200) — and the wire cannot tell the 404 case apart from a foreign service
# squatting on the port. Left on the default, a broken deployment produces a
# green run made entirely of skips.
#
# Scope note (measured, not assumed): no make target currently starts the
# HelixAgent server. `make test-integration-full` brings up PostgreSQL, Redis,
# Kafka, RabbitMQ, MinIO, Qdrant and the mock LLM — but not the agent itself,
# so enabling this flag there would manufacture failures. Enable it when you
# are running the server yourself (`make run` in another terminal) or against
# a deployed instance via HELIXAGENT_URL.
#
# Only the literal "1" enables it; "0"/"true"/"yes" do NOT (a loose
# truthiness test would read HELIXAGENT_REQUIRED=0 as "required").
# HELIXAGENT_REQUIRED=1

# =============================================================================
# DATABASE CONFIGURATION
# =============================================================================
DB_HOST=localhost
DB_PORT=8101
DB_USER=helixagent
DB_PASSWORD=helixagent123
DB_NAME=helixagent_db
DB_SSL_MODE=disable

# =============================================================================
# REDIS CONFIGURATION
# =============================================================================
REDIS_HOST=localhost
REDIS_PORT=8102
REDIS_PASSWORD=helixagent123
REDIS_DB=0

# =============================================================================
# SERVER CONFIGURATION
# =============================================================================
PORT=8100
GIN_MODE=release
JWT_SECRET=your-secret-key-here

# =============================================================================
# SEARCH PROVIDERS
# =============================================================================
TAVILY_API_KEY=tvly-your-tavily-key
PERPLEXITY_API_KEY=pplx-your-perplexity-key
EXA_API_KEY=your-exa-key

# =============================================================================
# MONITORING
# =============================================================================
PROMETHEUS_ENABLED=true
PROMETHEUS_PORT=8310
JAEGER_ENDPOINT=http://localhost:14268/api/traces

# =============================================================================
# SECURITY & RATE LIMITING
# =============================================================================
RATE_LIMIT_RPM=60
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8080

# =============================================================================
# DEVELOPMENT
# =============================================================================
DEBUG_ENABLED=false
LOG_LEVEL=info