.env.example

# Cortex — Jev (TypeSafe AI System One) configuration
#
# Copy to .env and fill in your key:    cp .env.example .env
# .env is gitignored. Never commit it.
#
# WHERE TO GET A KEY. There are two routes to the same model, and this file is
# set up for the one that is open to everyone:
#
#   1. Vercel AI Gateway  <- the default below, and what most people can use today
#      https://vercel.com/ai-gateway/models/jev  ->  "Get API key"  (key starts vck_)
#      Vercel serves TypeSafe's own request and response format verbatim, so
#      Cortex talks to it with no adapter: only JEV_BASE_URL and JEV_MODEL differ.
#      AI Gateway requires a credit card on file before it will route anything,
#      even while Jev itself is free — without one every call returns
#      403 customer_verification_required. Add one at https://vercel.com/account/ai
#
#   2. TypeSafe direct — https://console.typesafe.ai/keys
#      INVITE ONLY at the time of writing ("join the waitlist at typesafe.ai").
#      A waitlisted account's key is rejected with 401, exactly like a wrong one.
#      To use it, swap the two commented lines below.
#
# WHERE THIS FILE GOES. Cortex is one binary on PATH that operates on any repo,
# so the key is resolved in this order:
#   1. the environment, if JEV_API_KEY is already set
#   2. $CORTEX_HOME/.env      <- the normal case: one key, every repo
#   3. <the repo>/.env        <- per-repo override, if you need one
# The same order decides every setting below, and `.env` beats `.evolve/config.yaml`
# so a one-run override never means editing a committed file. `cortex config`
# prints the effective value and its source for every one of them.
#
# JEV_ENV_FILE moves step 2 somewhere else — for a key rendered by a password
# manager, or to take this file out of the chain entirely (the test suite sets
# JEV_ENV_FILE=/dev/null so no test can read your key).
# Option 2 keeps the key out of every project the tool touches. If you use
# option 3, `cortex init` adds .env to that repo's .gitignore.
#
# Never list .env in `environment.harness_files`: that copies files into both
# rollout sandboxes, which is the one place the key must never appear.
#
# Cortex works completely without this file. Jev is an accelerator for the
# PROPOSAL layer (which theme, which tier, which scope, is there anything to
# harvest). It never touches the verdict: `cortex score`, the gates and
# `check.sh` contain no model of any kind, by design. See docs/JEV.md.

# ---- required to enable Jev -------------------------------------------------

# Your key. From Vercel AI Gateway it starts `vck_`; from TypeSafe direct it is
# whatever console.typesafe.ai issues. Leave empty to keep Jev off.
JEV_API_KEY=

# ---- optional: endpoint and model ------------------------------------------

# The System One endpoint. These two lines are the ONLY difference between the
# two routes — the request and response bodies are identical, so nothing in
# bin/jev.py knows or cares which one it is talking to.
#
#   Vercel AI Gateway (default):
JEV_BASE_URL=https://ai-gateway.vercel.sh/typesafe/v1/systemone
#   TypeSafe direct:
#   JEV_BASE_URL=https://api.typesafe.ai/v1/systemone

# The model. On the gateway this is `typesafe-ai/jev` (its own curl example);
# `jev` also resolves, and is what GET /typesafe/v1/models advertises.
# On TypeSafe direct it is the alias `jev-latest`, or an exact version.
#
# Pin an exact version if you need the question library's J0 accuracy numbers
# (jev/RESULTS.md) to stay valid — a model change invalidates them. Whichever you
# send, the response reports the id that actually answered, and Cortex logs it.
JEV_MODEL=typesafe-ai/jev
#   TypeSafe direct:
#   JEV_MODEL=jev-latest

# ---- optional: behaviour ----------------------------------------------------

# Seconds before a Jev call is abandoned and Cortex falls back to its
# deterministic path. Keep this small: every call site must be optional.
JEV_TIMEOUT_S=10

# 429 and 529 are retried this many times, honouring Retry-After, then the call
# falls back. Everything else (401, 422) falls back on the first response.
JEV_RETRY_ATTEMPTS=3

# First backoff in seconds, doubled per attempt and capped by JEV_TIMEOUT_S.
# A `Retry-After` header wins over it when the response carries one.
JEV_RETRY_BACKOFF_S=1.0

# Ceiling for one /evolve cycle. A census that would exceed either one refuses
# to start rather than silently becoming a sample again. The R1 transcript
# census was ~6 MTok, so 12 leaves room without leaving the door open.
JEV_MAX_REQUESTS_PER_CYCLE=2000
JEV_MAX_INPUT_MTOK_PER_CYCLE=12

# Requests per second, kept an order of magnitude under the published ceiling
# while Jev is in early access and its limits are still moving. Through a gateway
# you are also subject to that gateway's own limits, which are lower.
JEV_MAX_RPS=15

# Master switch, independent of the key. Set to 0 to disable every Jev call
# while leaving the key in place (useful for A/B-ing Cortex with and without).
#
# The built-in default is OFF, and `cortex init` never writes a `jev:` block into
# a repo's config.yaml, so a repo that never turns Jev on never gains a `jev:`
# key. This line is what turns it on. A key alone does not: `cortex doctor` says
# so in as many words when it finds one with the switch off.
JEV_ENABLED=1

# ---- thresholds -------------------------------------------------------------
# These have config.yaml equivalents under `jev:`; the env vars win when set,
# so you can override for one run without editing the repo's config.

# cortex scope: warn when a candidate rule would be injected into tasks it is
# not about, below this relevance ratio. Advisory only — it never blocks a
# sweep and never kills a candidate.
JEV_RELEVANCE_FLOOR=0.35

# The session-end hook stays silent below this probability. Raise it if the
# nudge becomes noise; the hook's first duty is to never be annoying.
JEV_HARVEST_THRESHOLD=0.6

# Below this confidence, a Choice is escalated to Claude instead of being acted
# on. Applies to the tier decision in /evolve A4.
JEV_CONFIDENCE_FLOOR=0.7