RunConfig Reference: All Configuration Fields

Every YAML RunConfig field in OASIS-LLM: provider, model, image_set, sampling, and prompt settings, plus which changes invalidate a run’s canonical hash.

Every OASIS-LLM run is driven by a YAML configuration file. This page documents every field in that file — its type, its default value, and whether changing it after a run has started invalidates the run’s canonical hash (requiring a new name).

Example config

configs/runs/pilot10-gemma4-31b.yaml

name: pilot10-gemma4-31b
provider: openrouter
model: google/gemma-4-31b-it
modality: vision
dimensions: [valence, arousal]
image_set: pilot_10
samples_per_image: 5
max_concurrency: 4
request_timeout_s: 60
max_tokens: 256
capture_reasoning: true

Field reference

Field	Type	Default	Description
name	str	(required)	Run identifier and run_id primary key. Must be unique unless resuming. Excluded from canonical_hash.
provider	enum	(required)	One of openrouter, ollama, anthropic, google, openai. Selects auth method and default API base.
model	str	(required)	LiteLLM-style model ID, e.g. google/gemma-4-31b-it. The openrouter/ prefix is added at dispatch and should be omitted here.
modality	enum	"vision"	"vision" sends the image as a base64 data URL. "text" sends only the prompt, used for caption-based ablations.
dimensions	list	["valence", "arousal"]	Which rating dimensions to enqueue. Set to ["valence"] to halve the trial count.
image_set	str	"pilot_30"	Named subset (full_900, pilot_30, pilot_10, smoke_3) or a path to a newline-delimited image ID file. See Image sets.
samples_per_image	int	5	Ratings per (image, dimension) cell. Excluded from canonical_hash — you can increase this on an existing run without forking it.
max_concurrency	int	4	Async worker count. Excluded from canonical_hash.
request_timeout_s	int	60	Per-call LiteLLM timeout in seconds. Excluded from canonical_hash.
max_retries	int	3	Hard cap on retry attempts. Trials with status='failed' and attempts >= 3 are terminal. Excluded from canonical_hash.
temperature	float | null	null	If set, passed to the provider. If null, the provider default is used (which for many open-weights models is 0.0).
max_tokens	int	256	Generation cap. JSON-with-reasoning fits in under 100 tokens; 256 is comfortable headroom.
capture_reasoning	bool	true	If true, rewrites the prompt to request {"rating": ..., "reasoning": "..."} JSON and skips strict response_format. See Reasoning capture.
cache_buster	bool	true	Appends a per-(image, dim, sample_idx) salt to the end of the user prompt to force decoding variance. Placed after the image to preserve prefix cacheability. See Cache buster.
system_prompt_override	str | null	null	Full replacement for the paper-verbatim system prompt. Use sparingly — this invalidates direct comparison to the human norms.
format_hint_suffix	str | null	null	Appended to the user prompt. Useful to coerce JSON-only output on weaker models.
api_base	str | null	null	Override the API base URL. Required for Ollama or self-hosted vLLM/SGLang, e.g. http://localhost:11434.
extra_params	dict	{}	Passed verbatim to litellm.acompletion. Use for provider-specific knobs not covered by the fields above.

Canonical hash

RunConfig.canonical_hash() produces a 16-character SHA-256 digest of the config’s serialized fields. It excludes the following fields, which can change freely without forking the run:

• name — the identifier itself
• max_concurrency, request_timeout_s, max_retries — runtime knobs that don’t affect what the model sees
• samples_per_image — so progressive sampling is allowed without forking the run

Every other field is included in the hash. If you change model, dimensions, image_set, temperature, cache_buster, capture_reasoning, system_prompt_override, or anything else the model observes, you must give the run a new name. Attempting to reuse a name with a different config raises:

RuntimeError: Run 'pilot10-gemma4-31b' exists with different config hash
(stored=ab12cd34ef567890, new=ff00112233445566). Use a new --name or --new-run.

This guard is intentional. It enforces the distinction between “resume the same experiment” and “silently start a different one.”

Provider notes

OpenRouter

Set the OPENROUTER_API_KEY environment variable. Native cost reporting is enabled automatically — the runner sets extra_body.usage.include=true on every call so that cost_usd is populated from OpenRouter’s billed cost even when LiteLLM doesn’t have a price entry for the model.

The openrouter/ prefix on model IDs is added at dispatch and should be omitted from the model field in your YAML. If you accidentally include it, the config normalizer strips it so the canonical hash stays consistent.

Ollama

Set api_base: http://localhost:11434 (or the address of your Ollama instance). Cost will be NULL for all trials — latency and token counts are still captured. Because temperature defaults vary by model in Ollama, set it explicitly in your config if reproducibility matters.

Anthropic / Google / OpenAI

Standard environment variable auth applies: ANTHROPIC_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY. Cost is reported directly by LiteLLM from its built-in price table.