.env.example

# OKF Loremaster — copy to .env and fill in. Never put real values in this file.
# Every variable is read through okf_loremaster.config; nothing is read from os.environ directly.
#
# One `KEY=value` per line, no spaces around the `=`, and the value written bare.
# Quotes are stripped if you use them, so `medium` and `"medium"` are the same
# setting — but nothing here ever needs them. A line commented out is a setting
# you have not made; each block below says what happens when you leave it that way.

# ---------------------------------------------------------------------------
# LLM routing (required)
# ---------------------------------------------------------------------------
# Model strings are passed verbatim to LiteLLM, so any LiteLLM-supported
# provider works. Three roles; bind them to whatever tier you like.
#   FAST       cheapest and quickest; screening, one abstract at a time
#   BALANCED   mid-priced; query planning, curation, and extraction
#   REASONING  most capable and most expensive; the charter, and nothing else
#
# Extraction sits on BALANCED because it is the only node that makes a call per
# paper — two hundred of them against every other node's handful — so whatever it
# is bound to sets the price of a run. What guards the output there is code, not
# model tier: every number is checked against the source afterward and every quote
# is sliced out of it. Bind REASONING to something cheaper and you will barely
# notice; bind BALANCED to something expensive and you will.
#
# These three are a default, not a requirement. Replace them with any model
# string LiteLLM accepts:
#   Anthropic       claude-sonnet-5
#   OpenAI          gpt-5.2
#   Azure OpenAI    azure/<your-deployment-name>   + API_BASE below
#   Bedrock         bedrock/anthropic.claude-sonnet-4-5-v1:0
#   Ollama, local   ollama/llama3.3                + API_BASE below
#   vLLM, LM Studio openai/<model-name>            + API_BASE below
OKF_LOREMASTER_MODEL_FAST=claude-sonnet-5
OKF_LOREMASTER_MODEL_BALANCED=claude-sonnet-5
OKF_LOREMASTER_MODEL_REASONING=claude-opus-5

# The key for whichever provider you chose above. It is handed to LiteLLM
# directly, so it goes here whatever the provider is named — OPENAI_API_KEY and
# the rest are not read. A local model needs a value here too; nothing checks
# the string, but an empty one stops the run. `local` will do.
# ANTHROPIC_API_KEY is an accepted alias for this variable.
OKF_LOREMASTER_API_KEY=

# Azure, a gateway, or anything self-hosted. ANTHROPIC_BASE_URL is an alias.
#   Azure OpenAI       https://<resource>.openai.azure.com/
#   Azure AI Foundry   https://<resource>.services.ai.azure.com/anthropic/
#   Ollama             http://localhost:11434
#   vLLM, LM Studio    http://localhost:8000/v1
# Azure only: LiteLLM defaults to api-version 2025-02-01-preview. To pin another,
# export AZURE_API_VERSION in your shell — LiteLLM reads it from the process
# environment, and this file is not copied there.
OKF_LOREMASTER_API_BASE=

# How hard each tier may think before it answers. Commented out means nothing is
# sent and the model's own default applies, which on a current Anthropic model is
# `high`. One vocabulary across providers — LiteLLM translates it into a thinking
# budget for Anthropic and into the native parameter for OpenAI:
#
#   minimal  low  medium  high  xhigh  max  none
#
# Set one by deleting its `#` below and writing the word bare, so a medium
# BALANCED tier is exactly this and nothing more:
#
#   OKF_LOREMASTER_EFFORT_BALANCED=medium
#
# `none` is not the same as leaving this commented out. Commented out sends
# nothing; `none` asks explicitly for no reasoning, which is a real request to
# make of a model that would otherwise reason by default.
#
# Thinking is billed as output tokens, and the budget is spent per call. Two
# things follow. Effort on BALANCED is the expensive one: extraction lives there
# at one call per paper, so `high` on a 150-paper run buys about 600,000 output
# tokens of thinking before a single finding is written. Effort on FAST is worse
# value than it looks: screening is a yes-or-no on an abstract, and a thinking
# budget there multiplies the cost of the cheapest tier for a verdict that was
# not close. REASONING is where it is nearly free — one charter call per run.
#
# A tier with effort set stops sampling deterministically. Every call this tool
# makes asks at temperature 0, and no provider allows both: Anthropic refuses any
# temperature but 1 once thinking is on, OpenAI's reasoning models refuse the
# parameter outright. So setting this drops temperature for that tier and nothing
# else changes. The tiers you leave commented out still ask at 0.
#
# `--dry-run` counts this at full budget on every call, so check there first.
OKF_LOREMASTER_EFFORT_FAST=low
OKF_LOREMASTER_EFFORT_BALANCED=medium
OKF_LOREMASTER_EFFORT_REASONING=medium

# ---------------------------------------------------------------------------
# Cost accounting
# ---------------------------------------------------------------------------
# Set these and they are what the run bills against — nothing second-guesses them.
# Leave them unset and pricing falls back to LiteLLM's table, which is wrong in two
# different ways. It returns 0.0 for models it does not know, and a gateway or Azure
# deployment name is commonly one of those; 0.0 is indistinguishable from a free call,
# so an unpriceable call is reported as tokens with "cost unavailable", never $0.00.
# It is also a static file shipped inside the installed litellm wheel, so a published
# price that moves afterward leaves it quoting release day until the next upgrade.
#
# The variables are per tier, not per model, so they follow whatever you bound above:
# point BALANCED at an OpenAI or Gemini model and set BALANCED's two numbers to that
# model's list price. There is nowhere to look them up programmatically — providers
# return token counts, not dollars — so read them off the vendor's pricing page.
# `--dry-run` is the cheap way to confirm they are being picked up: it prints a figure
# instead of "unpriced (tokens only)" and makes zero model calls.
#
# Units: USD per 1M tokens. List price as of 2026-08-27, for reference:
#   Claude    sonnet-5  2 / 10      opus-5  5 / 25
# Both halves of a tier are required — an input price with no output price is ignored
# rather than half-applied, which would silently undercount every call.
# OKF_LOREMASTER_PRICE_FAST_IN=
# OKF_LOREMASTER_PRICE_FAST_OUT=
# OKF_LOREMASTER_PRICE_BALANCED_IN=
# OKF_LOREMASTER_PRICE_BALANCED_OUT=
# OKF_LOREMASTER_PRICE_REASONING_IN=
# OKF_LOREMASTER_PRICE_REASONING_OUT=

# Soft budget in USD. The run warns and pauses at this threshold; it does not abort.
# OKF_LOREMASTER_MAX_USD=5.00

# ---------------------------------------------------------------------------
# Model concurrency and retries
# ---------------------------------------------------------------------------
# How many calls per tier may be in flight at once. Screening submits every pooled
# paper at once and these are what meter it, so FAST is the one that matters. The
# binding limit is usually tokens per minute rather than requests: if a run reports
# screening calls failing with RateLimitError, lower FAST before anything else.
# OKF_LOREMASTER_CONCURRENCY_FAST=4
# BALANCED is what sets a run's wall-clock: extraction is one call per kept paper, so a
# 200-paper bundle makes 200 of them, each taking most of a minute. Measured at 6, that
# is a 5x speedup over running them one at a time — about 30 minutes for 200 papers
# against about 50 at 3. Rate limits are counted per model per minute, so this budget is
# not shared with FAST above. Lower it only if extraction starts reporting RateLimitError.
# OKF_LOREMASTER_CONCURRENCY_BALANCED=6
# OKF_LOREMASTER_CONCURRENCY_REASONING=3

# Attempts per call, not retries on top of the first — warnings count to one less.
# A rate limit clears on a 60-second window, so this has to be enough to outlast one.
# OKF_LOREMASTER_MAX_RETRIES=6

# Seconds before a single model call is abandoned. An extraction reads 6,000 tokens of
# source and writes several thousand back, which is minutes rather than seconds; set too
# low, the call times out on its own success and the paper is lost.
#
# This governs the whole call, including the wait before any output appears. Reasoning
# happens before the first token and does not stream, so a call on a thinking model is
# legitimately silent for tens of seconds before it says anything. Screening gets its own,
# much shorter, because a verdict on one abstract is seconds.
# OKF_LOREMASTER_REQUEST_TIMEOUT=300
# OKF_LOREMASTER_REQUEST_TIMEOUT_FAST=60

# Seconds of silence *between* chunks before a streaming call is abandoned and retried.
# Set to 0 to stop streaming and wait for each reply whole.
#
# Replies are streamed so that a call which stops responding can be caught by how long it
# has been quiet rather than by how long it has been running. A healthy call's gap between
# chunks is well under a second, so this fires only on a call that has died, and it fires
# far sooner than REQUEST_TIMEOUT would. It applies only after output has started; the
# silence before the first token is REQUEST_TIMEOUT's to judge.
#
# Tokens already streamed before a call is abandoned are billed by the provider, and are
# counted in the run's cost report alongside the retry that follows.
# OKF_LOREMASTER_STREAM_STALL_SECONDS=10

# ---------------------------------------------------------------------------
# NCBI E-utilities
# ---------------------------------------------------------------------------
# Optional but strongly recommended: raises the rate limit from 3 to 10 req/s.
# Free from https://account.ncbi.nlm.nih.gov/settings/
# We run at 2.5 or 8 req/s respectively — under the ceiling on purpose, because
# the limit is enforced per IP and a shared address may already be carrying
# traffic we cannot see. E-utilities, BioC and PubTator share one budget.
OKF_LOREMASTER_NCBI_API_KEY=
# Required. NCBI asks for a contact address on every request and throttles
# traffic that omits it. A build refuses to start without it.
OKF_LOREMASTER_NCBI_EMAIL=
OKF_LOREMASTER_NCBI_TOOL=okf-loremaster

# ---------------------------------------------------------------------------
# HTTP
# ---------------------------------------------------------------------------
# OKF_LOREMASTER_HTTP_TIMEOUT=30
# OKF_LOREMASTER_HTTP_MAX_RETRIES=4
# Responses are cached on disk, keyed by the request with credentials stripped,
# so rotating an API key does not orphan the cache. Bibliographic records are
# effectively immutable, hence the long default.
# OKF_LOREMASTER_HTTP_CACHE_ENABLED=true
# OKF_LOREMASTER_HTTP_CACHE_TTL_DAYS=30
#
# A CA bundle to verify TLS against, instead of the default trust store. Needed on
# a network whose proxy terminates TLS and presents its own certificate: the run
# then reports a certificate failure against a host that is perfectly healthy, and
# it can hit some hosts and not others depending on what the proxy allowlists.
# Ask your IT group for the organization's root CA in PEM form. There is
# deliberately no option to skip verification — the provenance a bundle claims
# rests on the bytes having come from who they say they came from.
# OKF_LOREMASTER_CA_BUNDLE=/path/to/corporate-ca.pem

# ---------------------------------------------------------------------------
# Embeddings (only used by the optional vector index)
# ---------------------------------------------------------------------------
# Must be a locally-runnable model: downstream consumers reject remote embedders
# on attach. Pinned by revision so a rebuild reproduces the same vectors.
# OKF_LOREMASTER_EMBED_MODEL=pritamdeka/S-PubMedBert-MS-MARCO
# OKF_LOREMASTER_EMBED_REVISION=

# Shared Hugging Face cache, so the embedding model downloads once per machine
# rather than once per environment. Commented out because the value has to be a
# real absolute path on your machine — a literal ~ is not expanded here, and an
# uncommented placeholder would send the download to a directory named after the
# placeholder. Leave it off and Hugging Face uses its own default.
# Keep it OUTSIDE any synced folder: the hub cache symlinks snapshots/ into blobs/,
# which sync clients mangle. OneDrive, Dropbox, Google Drive and iCloud Drive are
# checked by name at startup and refused.
# HF_HOME=/home/you/.cache/huggingface

# ---------------------------------------------------------------------------
# Review
# ---------------------------------------------------------------------------
# Who a `--review` sign-off is attributed to. Recorded in every document as
# verified: [{by: "human:<id>", ...}], which is what lifts the bundle above the
# unverified trust tier — so it has to name someone who can be asked about it.
# Unset falls back to the OS login name; set it when that is a service account
# or a shared box.
# OKF_LOREMASTER_REVIEWER_ID=

# ---------------------------------------------------------------------------
# Paths
# ---------------------------------------------------------------------------
# HTTP response cache and run checkpoints. Defaults to a platform cache dir.
# OKF_LOREMASTER_CACHE_DIR=
# Where runs are written. Defaults to ./bundles relative to the working dir.
# Every run lands here: `-o <name>` takes a name, not a path, and it is resolved
# against this. An absolute -o overrides it.
# OKF_LOREMASTER_OUTPUT_DIR=
#
# How many past runs keep their checkpoints. A build writes 100 to 350 MB of them
# — the whole state is saved once per node, and by the later ones it holds full
# texts and extractions — so without this the cache directory grows forever. Each
# build drops all but this many, newest first; 0 keeps everything. Only affects
# what `--resume` can still pick up. Bundles are never touched.
# OKF_LOREMASTER_CHECKPOINT_KEEP_RUNS=5
#
# Ceilings in MB on the three things that accumulate. Applied at both ends of a
# build, oldest entries first, so between builds each store is under its ceiling and
# only a run in flight is over. Nothing is reclaimed unless you build. 0 turns one
# off. `okf-loremaster runs` prints each size against its cap.
#
# Checkpoints are scratch, and the count above is meant to be what binds: five runs
# measure around 900 MB, so this is set clear of that rather than quietly cutting how
# many are resumable. The other two are not scratch — they are keyed by the request
# and shared by every bundle, which is what makes a rebuild fast and re-reading a
# paper free — so they sit where an ordinary year of use will not reach them. Raise
# the last one before the others if you rerun often.
# OKF_LOREMASTER_CHECKPOINT_MAX_MB=2048
# OKF_LOREMASTER_HTTP_CACHE_MAX_MB=1024
# OKF_LOREMASTER_EXTRACTION_CACHE_MAX_MB=512