.env.example

# Live credentials for eval runs. The test suite needs none of this. It runs offline
# against recorded fixtures.
#
# Copy to .env and fill in the blanks (.env is gitignored, this file is not):
#   cp .env.example .env
#
# uv injects it with --env-file. The engine also seeds missing vars from a repo-root
# .env at import time, with real environment variables always winning.
#
# Scoring the eval cases needs a running app and GEMINI_API_KEY, SEARCH_GRAPH_BASE,
# GRAPH_RELEASE_URI and ORIGIN_CATALOGUE_URI in the environment:
#   just eval-app 8100
#   just eval-run http://127.0.0.1:8100
# The Langfuse keys below are for syncing cases to Langfuse datasets.

# --- Required ---

# Gemini key for the engine's LLM calls (extract/bind). Live calls only.
GEMINI_API_KEY=

# Langfuse Cloud EU. PUBLIC/SECRET keys are in Langfuse UI -> Settings -> API Keys.
# EU cloud is https://cloud.langfuse.com (US would be https://us.cloud.langfuse.com).
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=
LANGFUSE_BASE_URL=https://cloud.langfuse.com

# --- Optional (defaults shown, uncomment only to override) ---

# Graph target. Required: the search engine refuses to start without it. `just env`
# writes the dfo-dev graph here
# (https://dfo-dev-dc-datacommons-service-zms5lj4zhq-nn.a.run.app).
# SEARCH_GRAPH_BASE=

# Published graph release root (gs:// or file://), the directory holding its pointer.
# Every surface serves from the release the pointer names and fails at startup
# without it. dfo-dev publishes to gs://dfo-dev-graph-release-dev-fin-observatory/.
# GRAPH_RELEASE_URI=

# Published origin catalogue (gs:// or file://). Every surface that reads the graph
# loads it at startup and fails without it.
# ORIGIN_CATALOGUE_URI=

# LLM model. Default is the flash-lite alias.
# SEARCH_ENGINE_MODEL=gemini-3.5-flash-lite

# Sampler seed passed to every LLM call. Unset defaults to 1, which has measured
# as fully deterministic on the pinned model generation (identical response
# across repeated identical queries), though the pinned response re-rolls if the
# model, prompt, or graph state changes. google-genai documents seed as
# best-effort only ("the model makes a best effort to provide the same response
# for repeated requests").
# Set to an empty value to opt out and restore unseeded sampling.
# SEARCH_LLM_SEED=1

# Thinking-level override ("minimal", "low", "medium", or "high") for every LLM
# call, replacing the model-derived default. This also overrides the engine's
# per-stage defaults (search.engine.clients.llm._STAGE_THINKING_LEVELS). For
# example, setting this pins the bind stage away from its "minimal" default. Unset
# keeps the per-stage/model-derived defaults.
# SEARCH_LLM_THINKING_LEVEL=

# Most Gemini requests one event loop has open at once: the connection limit of
# each loop's Gemini HTTP pool (HTTP/1.1, one request per connection), per genai
# client. Production runs one loop, so this is the per-process cap. A request
# past the cap waits for a free connection, for at most SEARCH_LLM_TIMEOUT_S.
# Default is 32.
# SEARCH_LLM_MAX_CONCURRENCY=32

# Postgres persistence layer (dataset_store), optional, used only by `just migrate`
# and `just dataset-store-smoke` (see deploy/postgres.md). Point
# DATASET_STORE_HOST/_PORT at a local Postgres for a dry run (a local server
# authenticates the runtime role with DATASET_STORE_RUNTIME_DB_PASSWORD), or set
# DATASET_STORE_INSTANCE_CONNECTION_NAME to route through the Cloud SQL Connector
# instead.
# DATASET_STORE_INSTANCE_CONNECTION_NAME=
# DATASET_STORE_HOST=127.0.0.1
# DATASET_STORE_PORT=5432
# DATASET_STORE_DATABASE=datasets
# DATASET_STORE_RUNTIME_DB_USER=
# DATASET_STORE_RUNTIME_DB_PASSWORD=
# DATASET_STORE_POOL_SIZE=10
# DATASET_STORE_CONNECT_TIMEOUT=30
# DATASET_STORE_MIGRATOR_DB_USER=
# DATASET_STORE_MIGRATOR_DB_PASSWORD=

# Mounts the Datasets API's register, mint, definition, snapshot, and pin doors
# alongside Search on the deployed service (see deploy/postgres.md). "1" or "true"
# (case-insensitive). Default is off. Requires DATASET_STORE_RUNTIME_DB_USER and the
# mint/definition doors' own settings below to already be provisioned.
# DFO_DATASETS_SURFACE=

# Mint and definition door live dependencies (deploy/postgres.md). Required once
# DFO_DATASETS_SURFACE is on. Each door's own lifespan fails fast at startup if any
# is unset.
# DATASETS_GRAPH_BASE_URL=
# DATASETS_SDMX_BASE_URL=
# The UN System Data Commons API root, which serves undata/ dcids. Every surface
# and the origin catalogue job read this one variable. Defaults to
# https://unsd-datacommons.gcp.un-icc.cloud/core/api.
# UN_GRAPH_BASE_URL=
# DATASETS_ARTIFACT_BUCKET_WORKING=
# DATASETS_ARTIFACT_BUCKET_PINNED=

# Optional shared secret sent as the x-graph-token header to the mint and definition
# doors' graph and SDMX clients above, the same WAF rationale as SEARCH_GRAPH_TOKEN.
# Unset or empty sends no header.
# DATASETS_GRAPH_TOKEN=

# The pivot reshape's own output-cell cap (index values x output columns).
# Default is 5_000_000.
# DATASETS_PIVOT_MAX_OUTPUT_CELLS=5000000

# Sizes the frame refresh door's own executor and backpressure semaphore, apart from
# the definition door's, so refreshes take no thread from a public definition read.
# Memory-heavy rebuilds stay bounded by DATASETS_MATERIALISE_MAX_CONCURRENCY. Default 8.
# DATASETS_REFRESH_MAX_CONCURRENCY=8

# Sizes the definition retrieval door's own dedicated executor and backpressure
# semaphore, independent of the mint door's own concurrency. A retrieval re-runs the
# identical graph-read/SDMX-fetch/materialisation path a mint does. Default 4.
# DATASETS_DEFINITION_MAX_CONCURRENCY=4

# Bounds how long a definition retrieval request waits on the door's own
# executor hop before refusing, mirroring the mint door's own timeout.
# Default 120.
# DATASETS_DEFINITION_TIMEOUT_SECONDS=120

# Sizes the one materialise semaphore the mint door, the definition door's rebuild,
# the options rebuild, and every facet probe share. Sized for the 1 GiB service at a
# 266 MB rebuild peak. Default 2.
# DATASETS_MATERIALISE_MAX_CONCURRENCY=2

# Bounds how long a request waits for a materialise slot before refusing with a
# retryable 503. The request's own deadline caps the wait when it is nearer.
# Default 30.
# DATASETS_MATERIALISE_WAIT_SECONDS=30

# How long a confirmed head serves straight from the store, with no graph or SDMX
# call, before the next request re-probes the facet signal. Default 900.
# DATASETS_HEAD_RECHECK_SECONDS=900

# Age since the head's last materialisation past which a definition GET rebuilds
# regardless of the probe. Always greater than the recheck interval. Default 86400.
# DATASETS_HEAD_MAX_AGE_SECONDS=86400

# Snapshot/pin door executor sizes, a couple of bounded Postgres reads plus a
# signed-URL/IAM signBlob call per artifact, cheap relative to the mint door's own
# upstream I/O. Default is 4 each.
# DATASETS_SNAPSHOT_MAX_CONCURRENCY=4
# DATASETS_PIN_MAX_CONCURRENCY=4

# The header a calling service sends its principal value in. The pin, publish, recipe,
# and live-refresh routes compare it with the three values below. Each value is a shared
# secret the caller puts in the header itself: nothing in front of this service sets,
# replaces, or removes the header, so knowing a value is what admits a caller. Every
# one of those routes refuses a request bearing more than one occurrence of this
# header. Default is x-dfo-principal.
# DATASETS_PRINCIPAL_HEADER=x-dfo-principal

# The one principal value allowed to publish. Empty (the default) permits no
# principal at all. The publish door refuses everyone until this is set.
# DATASETS_FIRST_PARTY_PRINCIPAL=

# The one principal value allowed to pin, independent of
# DATASETS_FIRST_PARTY_PRINCIPAL above. Empty (the default) permits no principal
# at all. The pin door refuses everyone until this is set. Pinning has no unpin or
# delete route on this surface, so a principal trusted to publish must not
# automatically gain that irreversible capability too.
# DATASETS_PIN_FIRST_PARTY_PRINCIPAL=

# The one principal value allowed on the live-refresh routes: the Datasets frame
# refresh (POST /api/datasets/frames/refresh) and the two Presentation render routes
# (POST and GET under /api/presentation/components/{id}/revisions/{n}/render). It is
# read from the same header as the two principals above and carries no DATASETS_
# prefix, because the website and `ai` mount the same secret under this name.
# Empty (the default) refuses every caller. It opens no publish, recipe, or pin route.
# LIVE_REFRESH_PRINCIPAL=

# Mounts the Graph API's healthz, resolve, and node doors alongside Search (and
# Datasets, when enabled) on the deployed service. "1" or "true" (case-insensitive).
# Default is off. Requires GRAPH_DCP_BASE_URL below to already be provisioned.
# DFO_GRAPH_SURFACE=

# DCP base URL the Graph surface's own live GraphNodeReader reads through. Required
# once DFO_GRAPH_SURFACE is on. The surface's own lifespan fails fast at startup if
# unset.
# GRAPH_DCP_BASE_URL=

# Optional shared secret sent as the x-graph-token header to the Graph surface's own
# DCP reads, the same WAF rationale as DATASETS_GRAPH_TOKEN. Unset or empty sends no
# header.
# GRAPH_DCP_TOKEN=