.env.example

# penrose — example environment for local single-user v1.
# Copy to .env and fill in real values. .env is gitignored (never committed).
#
# Source your .env before `make run`:
#   set -a; source .env; set +a
# Or use a tool like direnv.

# --- LLM provider (F6-lite) ---------------------------------------------------
# penrose uses a single OpenAI-compatible adapter. Defaults route through
# Artificial Analysis to GLM 5x. Swap any of these to change provider.

# Your API key (required for real LLM calls in P2/P3/F10/chat).
# Get one from https://artificialanalysis.ai (or your provider of choice).
PENROSE_LLM_API_KEY=

# OpenAI-compatible base URL. Defaults work for:
#   Artificial Analysis: https://api.artificialanalysis.ai/v1   (default)
#   OpenAI:              https://api.openai.com/v1
#   z.ai GLM compat:     https://api.z.ai/api/v1
#   Ollama (local):      http://localhost:11434/v1
#   LiteLLM proxy:       http://localhost:4000/v1
PENROSE_LLM_BASE_URL=https://api.artificialanalysis.ai/v1

# Default model for every role. Per-role overrides live in src/penrose/config.py.
PENROSE_LLM_DEFAULT_MODEL=glm-5.2

# Clean, human-readable source titles for the UI (display-only). When enabled, each
# source ingest makes ONE extra LLM call to write a clean "author/publication/chapter"
# display title + one-line summary into the source's archive metadata AT CAPTURE.
# It is PURE PRESENTATION — never read by any gate, resolver, router, or binding, so
# verdicts are byte-identical whether it's on or off. Off by default keeps ingest
# deterministic + offline; set to 1 for a polished UI (recommended for operators).
PENROSE_SOURCE_TITLER=0

# Optional independent verifier for the adversarial fidelity judge. When URL/key
# are unset, fidelity_refuter falls back to the default provider path.
# PENROSE_LLM_VERIFIER_BASE_URL=https://api.openai.com/v1
# PENROSE_LLM_VERIFIER_API_KEY=
# PENROSE_LLM_VERIFIER_MODEL=claude-sonnet-4

# Hard daily spend cap (USD). Raises RuntimeError if a call would exceed it.
PENROSE_LLM_MAX_USD_DAY=40.0

# --- Throughput: parallel claim execution -------------------------------------
# Claims in a run can be evaluated concurrently. Verdicts are BYTE-IDENTICAL to a
# serial run (the multiple-testing denominator is pre-registered, not raced), so
# parallelism only changes speed, never the answer. Equivalent to `penrose run --workers`.
#
# Number of worker threads. Accepts an integer or "auto". Default when unset:
# min(4, auto) — 4 on capable hardware, auto-reduced on small machines so a laptop
# is never swamped. "auto" = the full hardware max (see the ceilings below).
# PENROSE_MAX_CLAIM_WORKERS=auto
#
# `auto`/default ceilings (workers = min of these):
# PENROSE_WORKER_HARD_CAP=8              # absolute max for auto (beyond this, use a real job queue)
# PENROSE_WORKER_RAM_PER_SANDBOX_GB=1.5  # RAM budgeted per worker (Docker auto-impl sandbox)
# PENROSE_WORKER_DEFAULT_CAP=4           # the cap applied to the unspecified default (min(cap, auto))
#
# Live concurrency also self-throttles: on provider 429s it halves and restores as they clear.
# Use PENROSE_MAX_CLAIM_WORKERS=1 (serial) for runs that depend on LIVE auto-fetch of shared series.

# --- Data vendors (BYO: bring your own key) -----------------------------------
# Generalizes the BYO Databento pattern. Each vendor is opt-in and fail-open:
# with no key the vendor is simply UNAVAILABLE — its series never enter the bundle
# and a run never crashes. Configure vendor series in your .env. Vendor-series config lives in
# src/penrose/data/vendors/__init__.py (DEFAULT_SERIES), not here.

# CERTIFIED adapters (free key, wired against the live API, key-gated integration test):
# FRED (St. Louis Fed) — macro series, e.g. the 10y treasury (DGS10). Free key:
#   https://fredaccount.stlouisfed.org/apikeys
FRED_API_KEY=
# Alpha Vantage — daily equities, e.g. SPY. Free key (email only):
#   https://www.alphavantage.co/support/#api-key   (free tier ~25 requests/day)
ALPHAVANTAGE_API_KEY=

# The following are framework TEMPLATES — plausible implementations of real endpoints,
# but NOT yet verified against a live key. Treat as a starting point and verify before use;
# each remains fail-open (simply unavailable) until you certify it.
# Polygon.io — add a key to enable (https://polygon.io)
# POLYGON_API_KEY=
# Tiingo — add a key to enable (https://www.tiingo.com)
# TIINGO_API_KEY=
# Alpaca — add BOTH a key and secret to enable (https://alpaca.markets)
# ALPACA_API_KEY=
# ALPACA_API_SECRET=

# --- optional: local data catalog (bring your own) ----------------------------
# For PRE-COLLECTED series that have no free live API (e.g. historical Kalshi macro
# signals). Point PENROSE_DATA_DIR at a directory exposing loader.py for the data
# contract (src/penrose/data/contract.py). When unset/absent, catalog-only series
# are UNAVAILABLE and dependent claims route to needs_data. Synthetic substitution is
# for calibration/dev only and must be explicitly enabled.
# PENROSE_DATA_DIR=/path/to/your/data-catalog
# PENROSE_ALLOW_SYNTHETIC=0

# --- optional: external embedding server (for vector retrieval) ---------------
# Vector retrieval uses in-process fastembed by default (pip install -e '.[embed]').
# To use an external OpenAI-compatible embedding server instead, point these at it:
# OPENAI_BASE_URL=http://localhost:8088/v1
# OPENAI_API_KEY=local