.env.template

# Hyperloom Environment Configuration
# Copy this file to .env and fill in the values:
#   cp .env.template .env

# LLM access. A provider side is configured by BOTH its base URL and its own
# key; Hyperloom never borrows one side's key or endpoint for the other. Exactly
# one of these four shapes is accepted:
#
#   1. OpenAI side only  -> Claude-side features are disabled
#        OPENAI_BASE_URL + OPENAI_API_KEY
#   2. Anthropic side only -> Codex / GEAK (OpenAI-protocol) features are disabled
#        ANTHROPIC_BASE_URL + ANTHROPIC_API_KEY
#   3. Both sides, each with its own base URL and key (this is what one gateway
#      serving both providers looks like: point both URLs at it and set both
#      keys, even when the key value is the same).
#   4. Claude Max/Pro subscription, no API credits -> CLAUDE_CODE_OAUTH_TOKEN
#      alone. It carries its own endpoint, so it needs no base URL.
#
# Anything else fails preflight instead of being silently repaired -- a base URL
# whose only key belongs to the other provider would ship that key to a foreign
# host.

# --- OpenAI side ------------------------------------------------------------
# Any OpenAI-compatible (LiteLLM-style) /v1 endpoint: an AMD Primus-Safe
# gateway, a self-hosted proxy, or api.openai.com (#340).
OPENAI_BASE_URL=https://<your-gateway-host>/api/v1/llm-proxy/v1
OPENAI_API_KEY=ak-your-api-key-here

# --- Anthropic side ---------------------------------------------------------
# Required for Claude-side features. Pointing at the same gateway as above is
# the "one gateway serves both" setup; api.anthropic.com is the native provider.
# Any Anthropic-protocol endpoint works here -- an enterprise LLM gateway is
# configured through these official variables, not through a Hyperloom-specific
# one (#1119).
# Uncomment BOTH lines together -- an API key without its base URL is rejected.
# (The subscription token below is the one Anthropic-side credential that needs
# no base URL, because it only ever validates against Anthropic itself.)
# ANTHROPIC_BASE_URL=https://<your-gateway-host>/api/v1/llm-proxy
# ANTHROPIC_API_KEY=ak-your-api-key-here
#
# Extra request headers, for gateways that authenticate on a header of their own
# (Azure API Management, corporate proxies) in addition to -- or instead of --
# the bearer key. AMD's llm-api.amd.com gateway needs the key repeated as an
# Ocp-Apim-Subscription-Key header. Newline-delimited "Name: value" as in the
# Anthropic SDK; a JSON object is accepted too. ${VAR} references are expanded
# from this file, so the secret stays in one place.
# Keep the double quotes: this file may be loaded with a shell "source", and an
# unquoted value containing a space and a colon fails with exit 127.
# ANTHROPIC_CUSTOM_HEADERS="Ocp-Apim-Subscription-Key: ${ANTHROPIC_API_KEY}"

# --- Anthropic side, Claude Max/Pro subscription (alternative to the above) ---
# Mint with `claude setup-token`. Spends your subscription instead of API
# credits, and implies https://api.anthropic.com, so set no ANTHROPIC_BASE_URL.
#
# Leave ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN unset when using it: the
# Claude CLI prefers either one and drops out of subscription mode, so the run
# silently bills API credits. Preflight warns about that combination but does
# not refuse it.
#
# Only the Claude CLI accepts this credential -- the Anthropic Messages API
# rejects it -- so the OpenAI-protocol call sites (Codex, GEAK, proposal
# scoring) stay disabled unless you also configure the OpenAI side above.
# CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-your-token-here

# --- Non-AMD-network deployment (#340) --------------------------------------
# To run on Vultr / TensorWave / a self-hosted gateway instead of the AMD
# network, set OPENAI_BASE_URL + OPENAI_API_KEY above to your endpoint, then pin
# model ids your gateway actually serves. Custom orchestration model ids are
# allowed by default and validated against the gateway's /models catalog, so no
# opt-in is needed here.
# CLAUDE_MODEL=your-gateway-orchestration-model
# CODEX_MODEL=your-gateway-kernel-model
#
# Uncomment to restore the strict AMD Claude allowlist
# (opus-5 / 4-8 / 4-7 / 4-6) and refuse to start when the catalog is unreachable.
# INFERENCE_OPTIMIZER_ALLOW_CUSTOM_ORCH_MODEL=0

# --- GEAK / kernel-agent model (GEAKv4 Claude Code workflow) ----------------
# GEAKv4 uses the Claude Code workflow. install.sh defaults from CLAUDE_MODEL;
# set explicitly only when GEAK should use a different Claude Code model.
# Unlike the orchestration model this is never checked against a /models
# catalog, and GEAK may reach a different endpoint (see GEAK_BASE_URL below),
# so a model the orchestration gateway serves can still 404 at run time. Pin an
# older id here if your GEAK endpoint lags behind.
# GEAK_CLAUDE_MODEL=claude-opus-5
#
# --- Forge-fusion model overrides --------------------------------------------
# Forge can run on Claude or Codex. Unset, it follows CLAUDE_MODEL / CODEX_MODEL
# for the selected backend. Set these only when Forge should use a different id
# than orchestration (same pattern as GEAK_CLAUDE_MODEL).
# FORGE_CLAUDE_MODEL=claude-opus-5
# FORGE_CODEX_MODEL=gpt-5.6-sol
#
# --- GEAK / generic LLM endpoint override (#521) ----------------------------
# GEAK runs in a separate network namespace and may not reach the gateway
# directly. By default GEAK_BASE_URL/LLM_API_BASE inherit OPENAI_BASE_URL; set
# them explicitly (e.g. a host-local reverse tunnel) to give the Kernel-agent a
# routable LLM endpoint. Preflight preserves these operator overrides.
# GEAK_BASE_URL=https://127.0.0.1:18444/api/v1/llm-proxy/v1
# LLM_API_BASE=https://127.0.0.1:18444/api/v1/llm-proxy/v1

# TraceLens public repo checkout. Leave empty to auto-clone under
# $HYPERLOOM_CACHE_DIR (default $REPO_ROOT/.cache), per revision as
# TraceLens@<sha>.
# TRACELENS_ROOT=
# OPTIONAL extension: backfills MAF/gap without an on-device benchmark.
# Leave empty to measure MAF on an idle GPU instead (same analysis, measured
# locally). Presence of this value is the sole switch — there is no separate
# toggle.
# TRACELENS_INTERNAL_ROOT=

# (Optional) Override framework source roots for PolicyGate + flag discovery.
# Colon-separated list; unioned with defaults (/sgl-workspace/{aiter,sglang,vllm}/).
# Populated automatically by src/hyperloom/inference_optimizer/assets/install.sh probe.
# INFERENCE_OPTIMIZER_FRAMEWORK_SOURCE_ROOTS=

# (Optional) Drop the optimize preflight gate that requires the selected serving
# framework to be importable and a ROCm build. Last resort: when the server runs
# elsewhere, set BENCHMARK_BASE_URL instead, which exempts the gate and configures
# the supported path. Already inert for xdit/custom, external multi-node, and any
# framework setup cannot install.
# HYPERLOOM_SKIP_FRAMEWORK_CHECK=1

# (Optional) When a first baseline boots but fails its accuracy eval, route it
# into enablement instead of halting the run. Default on (single-node only).
# INFERENCE_OPTIMIZER_ENABLEMENT_ON_EVAL_FAIL=1
# (Optional) Shared accuracy floor for the eval-failure trigger AND the
# enablement KEEP gate (finite, in [0,1]). Default 0.05.
# The default is a collapse guard, not a quality bar: it rejects a model that
# answers essentially nothing correctly (a real run once KEEPed a candidate at
# gsm8k 0.00076 under the old 0.0 default, i.e. 0.08% of a 0.906 baseline).
# Raise it if you want a genuine quality gate.
# Note: score=0.0 always fails regardless of floor (strictly positive required).
# score>=floor passes (score==floor is a pass). Single-node only.
# INFERENCE_OPTIMIZER_ENABLEMENT_ACCURACY_FLOOR=0.05

# (Optional) Accuracy-KEEP gates. Both default ON; set to 0 (or false/no/off) to
# fall back to a throughput-only KEEP for that lane. A candidate is graded only
# after it already cleared the throughput bar, and the score is read back from
# the run's own eval output, so neither gate costs an extra eval.
#   * KERNEL    — a kernel patch integrated by the kernel lane.
#   * FRAMEWORK — a framework source patch authored by a specialist.
# In both lanes a measured drop beyond the tolerance REVERTs; a missing verdict
# while a positive baseline accuracy is on record drops to NEEDS_REVIEW (eval
# should have worked and didn't); no baseline accuracy at all degrades to
# throughput-only rather than blocking every candidate.
# Disable only when the eval lane is known-broken: the gate is what stops a
# faster-but-wrong candidate from being kept.
# INFERENCE_OPTIMIZER_REQUIRE_KERNEL_ACCURACY=1
# INFERENCE_OPTIMIZER_REQUIRE_FRAMEWORK_ACCURACY=1
# The tolerance itself is NOT an env knob: ACCURACY_THRESHOLD in
# src/hyperloom/orchestrator/actions/executors/_accuracy_gate.py is a fixed 0.05
# (5 percentage points below the recorded baseline accuracy).

# Writable artifact root: hosts every session dir, optimizer_runs/, and the
# runtime/ tree generated by install.sh (GEAK e2e checkout,
# kernel-agent.env.sh, etc.). Left unset, Hyperloom uses /workspace/hyperloom when
# the image provides a writable /workspace, else <cwd>/session -- a bare-metal host
# off root has neither that directory nor permission to create it. Set it
# explicitly to put session output on a faster / bigger volume.
USER_DATA_PATH=/workspace/hyperloom

# (Optional) Live Langfuse trace push. Default OFF: the local
# reports/trace/*.jsonl ledger is always written; set this to 1 to ALSO mirror
# every LLM call into a Langfuse deployment in real time. When this flag is on,
# src/hyperloom/inference_optimizer/assets/install.sh auto-installs the `langfuse` SDK for you (it is skipped
# entirely when the flag is off, so non-Langfuse environments stay lean); you
# do NOT need a separate `pip install '...[trace]'`. Set the three LANGFUSE_*
# connection vars below too — any missing piece degrades to a safe no-op.
# HYPERLOOM_LANGFUSE_ENABLE=1
# LANGFUSE_HOST=https://langfuse.your-domain
# LANGFUSE_PUBLIC_KEY=pk-...
# LANGFUSE_SECRET_KEY=sk-...

# --- Forge GEMM tuning (optional) ------------------------------------------
# Selects the per-kernel `forge` backend for GEMM tuning. Tuning carries no
# knowledge base: every run tunes, and nothing is reused from a previous one.
# GEMM_TUNING_BACKEND=forge

# --- GPU identity ----------------------------------------------------------
# Two different things. GPU_TARGET is what kernels are compiled for; GPU_TYPE
# is the card they run on, and it is what a kernel's optimization experience is
# filed under. They are not interchangeable: mi300x, mi308x and mi325x all
# build for gfx942 while differing in bandwidth and cache, so the target cannot
# be reversed into a card. GPU_TARGET falls back to probing the host; GPU_TYPE
# does not, and is read only from here or from the candidate's own metadata.
# Where that metadata is absent, naming the card is the only way to get one:
# without it kernel optimization keeps working but reuses nothing and
# accumulates nothing.
# GPU_TYPE=mi355x
# GPU_TARGET=gfx950
# Recipe storage is explicitly local or remote; ambient credentials never
# select remote mode. Local is the network-isolated default.
KNOWLEDGE_STORE_MODE=local
# KNOWLEDGE_LOCAL_ROOT=/shared/knowledge
# Framework-agent KB root (lessons ledger for the FRAMEWORK phase). Defaults to
# $USER_DATA_PATH/framework-kb. The `fa` reader and the orchestrator's writeback
# both resolve through this one variable, so it moves the whole KB. The old
# reader-only FRAMEWORK_AGENT_KB_DIR is no longer read; it is ignored with a
# warning rather than failing the run, since it can no longer split the KB.
# INFERENCE_OPTIMIZER_FA_KB_PATH=/shared/framework-kb
# For remote Recipe mode, set KNOWLEDGE_STORE_MODE=remote and both KB Store
# values below. Remote mode replays the selected Recipe View and writes at CLOSE.
# KB_STORE_URL=https://<kb-store-host>
# KB_STORE_TOKEN=your-kb-store-token
# Internal cross-process handoff paths are created by Hyperloom in remote mode.
# Do not set these manually:
# KB_DRAFT_DIR=/path/to/session/runtime/kb_draft
# KB_WARM_START_DIR=/path/to/session/runtime/remote_recipe
# Optional non-Recipe GBrain KG / Framework PR capabilities:
# GBRAIN_BASE_URL=http://<gbrain-host>:80
# GBRAIN_TOKEN=gbrain_your-token-here

# --- Kernel optimization backend (optional) --------------------------------
# `geak` delegates the whole pipeline to GEAK e2e (bare-metal default).
# `forge` enables the per-kernel KernelForge backend; provide KernelForge
# yourself before selecting it.
# KERNEL_OPT_BACKEND_ORDER=geak
# When per-kernel Forge is enabled, allow eligible Triton candidates to switch
# from same-language `forge-loop` optimization to source-to-FlyDSL rewrite plus
# framework apply-back. Default (unset) = disabled; any candidate that fails the
# eligibility check silently stays on the generic forge-loop route.
# HYPERLOOM_FORGE_REWRITE_BY_FLYDSL=1
# Eligible single-node dense vLLM Forge runs capture runtime GEMM shapes when no
# explicit shape input exists. Disable the extra capture pass here; the timeout
# applies to dense TunableOp recording, while block-FP8 uses standard Roofline.
# HYPERLOOM_GEMM_SHAPE_CAPTURE=1
# HYPERLOOM_GEMM_SHAPE_CAPTURE_TIMEOUT_SEC=1800
# Force the per-optimization wall-clock budget in minutes (default 90). The env
# wins over the payload value, which is LLM-authored, so an operator raising the
# budget is not silently overridden. forge-loop reserves half the window for
# finalize, so this buys roughly half as much iteration as it reads.
# KERNEL_OPT_BACKEND_BUDGET_MIN=90

# --- Collective optimization lane (optional) -------------------------------
# The Coordinator drives this lane itself at KERNEL entry; it is never an agent
# request. It needs TP > 1, a TraceLens `Exposed Communication %` of at least 1%,
# and a source-resolved custom collective (all_reduce, reduce_scatter or
# all_gather) — vendor RCCL/NCCL never qualify.
# Skip the lane entirely.
# HYPERLOOM_SKIP_COLLECTIVE=1
# Run ONLY this lane at KERNEL entry (GEAK, fusion and per-kernel kernel_opt are
# all skipped), then hint skip_to_sweep. This is also how you reach the lane
# while KERNEL_OPT_BACKEND_ORDER selects `geak`, which otherwise owns the phase.
# HYPERLOOM_COLLECTIVE_ONLY=1
# E2E KEEP threshold in percent for the collective integrate (default 1.0);
# must be finite and non-negative.
# HYPERLOOM_COLLECTIVE_KEEP_PCT=1.0
# Allow a source-resolved collective to borrow shapes from the trace's only
# all-reduce workload family. Disabled by default because those shapes were not
# observed on that device symbol.
# HYPERLOOM_COLLECTIVE_ALLOW_INFERRED_SHAPES=1
# forge-collective wrapper timeout in seconds (default 14400 = 4h), and the
# per-agent timeout forwarded as --agent-timeout-sec.
# FORGE_COLLECTIVE_TIMEOUT=14400
# FORGE_COLLECTIVE_AGENT_TIMEOUT=3600

# --- Trace analysis route (optional) ---------------------------------------
# 'agent' (default): LLM-driven TraceLens analysis. 'deterministic': run the
# TraceLens Python toolchain directly (no LLM) for a faster, reproducible
# analysis that does not consume the orchestration model.
# HYPERLOOM_TRACE_ANALYSIS_ROUTE=deterministic

# --- Quantization master switch (optional) ---------------------------------
# Deterministic on/off gate for the quantization prelude. Quantization runs
# ONLY when this is truthy (1/true/yes/on). Even if --quantize/--quantize-scheme
# is present, it is SKIPPED unless this env is on (emits QUANTIZATION_SKIPPED:
# and continues on the un-quantized model). Lets a frontend/launcher control
# quantization via a sandbox env flag instead of relying on agent judgement.
# Default (unset) = disabled.
# HYPERLOOM_QUANTIZE_ENABLED=1