Skip to content

Configuration reference

Configuration keys krites reads, with types, defaults, and the environment-variable mapping.

How configuration works

krites uses the go-tool-base config layer: a YAML config file (seeded by krites init, inspect the resolved values with krites config), overlaid by environment variables. Every key <section>.<key> maps to an environment variable KRITES_<SECTION>_<KEY> (uppercased, dots → underscores) — e.g. remove.enabled → KRITES_REMOVE_ENABLED. Config is hot-reloaded.

The heavy providers are local-first and off by default — enable them per capability (0001 §5). Their models and the ONNX Runtime library both download automatically on first use (checksum-verified and cached) — enabling a capability needs no manual downloads or paths (0013).

ONNX Runtime

Face/eye analysis and object removal run on ONNX Runtime. krites obtains the runtime library itself — bundled inside the macOS app, or auto-downloaded and checksum-verified for the current platform and cached — so you never install or locate libonnxruntime. The resolution order is: onnxruntime.library_path (if set) → a library bundled beside the executable → the auto-download cache.

Key Type Default Meaning
onnxruntime.library_path string (auto) Optional override — path to your own libonnxruntime. Leave unset to auto-provision. Shared by face + removal.

Global settings vs per-shoot overrides

Configuration is a two-layer cascade (spec 0012):

  • Global (~/.krites/config.yaml) is the base — set it from the studio's Settings panel (the gear on the shoots page) or with krites config.
  • Per-shoot (<shoot>/.krites/config.yaml) is a sparse override — only the keys that shoot deliberately deviates on; everything else inherits the global. Change a global key and every shoot that hasn't overridden it follows.

Only the cull-profile thresholds (cull.profile.*) are overridable per shoot. The install-level capabilities — the AI provider + key (review.*) and whether the ONNX models run (face.enabled, remove.enabled + their runtime paths) — are global-only: they have no per-shoot meaning. Saving from the studio applies without a restart (the config is hot-reloaded; the object-removal and review backends re-read it on the next request).

Core

Key Type Default Meaning
log.level string info Log verbosity (debug, info, warn, error).
update.policy string (compiled-in) Self-update posture: disabled, prompt, or enabled.
update.check_interval duration (24h) How often to check for updates (0 = every run).

Face / eye analysis

The face/eye provider (spec 0004) powers the eyes-closed / blink and facing/smile cull signals. Off by default; enabling it fetches and checksum-verifies the pinned ONNX models. Thresholds are starting points to tune.

Key Type Default Meaning
face.enabled bool false Turn face/eye analysis on.
face.execution_provider string cpu cpu or coreml (Apple Silicon; falls back to CPU).
face.library_path string (auto) Optional legacy override; prefer onnxruntime.library_path. Unset = auto-provisioned.
face.detector_model string (pinned) Override the face-detector ONNX path.
face.landmark_model string (pinned) Override the landmark ONNX path.
face.strategy string (provider default) Analysis strategy (see 0004).
face.ear.closed float 0.12 Eye-aspect-ratio at/below which eyes read fully closed.
face.ear.open float 0.26 Eye-aspect-ratio at/above which eyes read fully open.
face.smile.closed float 0.00 Mouth curvature at/below which the mouth reads unsmiling.
face.smile.open float 0.10 Mouth curvature at/above which the mouth reads a full smile.
face.facing.frontal float 0.10 Yaw asymmetry at/below which the face reads frontal.
face.facing.turned float 0.50 Yaw asymmetry at/above which the face reads turned away.

Object removal

The inpainting provider (spec 0008) backs krites remove and the studio's removal tool. Off by default; enabling it fetches and checksum-verifies the selected backend's pinned model.

Key Type Default Meaning
remove.enabled bool false Turn object removal on.
remove.backend string lama Inpaint backend: lama (reference-quality) or migan (fast/tiny).
remove.execution_provider string cpu cpu or coreml (Apple Silicon; falls back to CPU).
remove.library_path string (auto) Optional legacy override; prefer onnxruntime.library_path. Unset = auto-provisioned.
remove.model string (pinned) Override the model path (else the backend's pinned model is fetched).
remove.margin float 0.5 Context padding around the mask before the 512 crop (LaMa only).
remove.timeout duration 120s Per-inpaint deadline.

Licence note. Both inpaint backends are trained on Places2 (non-commercial / no-redistribution); see NOTICE.md and 0008 §4.1 before commercial distribution.

AI review

The AI critic (spec 0009) backs krites review — a chat-backed critic over go-tool-base's multimodal pkg/chat. Cloud-first and off by default: it egresses the image, so it stays inert until you choose a provider and enter its key.

Key Type Default Meaning
review.provider string (none) AI provider: gemini or claude. Empty = inert.
review.model string (provider default) Model id override.
review.timeout duration 180s Per-review deadline.

The provider API key is entered in the studio and stored in the OS keychain — never in the config file or an environment variable (0009 §3.1).

Cull profile

The judgement — per-signal thresholds, hard gates vs soft penalties, dedup aggressiveness — lives under cull.profile.*. These are the keys that cascade global → shoot: unset, they fall back to the built-in wedding-default seed; set globally, they become your default; set in a shoot, they override it there. Edit them from the studio (the global default in the Settings panel, per-shoot overrides in a shoot's Cull profile panel) rather than by hand.

Key Type Default Meaning
cull.profile.min_sharpness float 50 Hard focus gate: below it, reject.
cull.profile.soft_sharpness float 150 Soft focus floor: below it (≥ min), maybe.
cull.profile.max_clipped_highlights float 0.10 Hard blown-highlight gate (0–1); 0 disables.
cull.profile.max_clipped_shadows float 0.30 Hard crushed-shadow gate (0–1); 0 disables.
cull.profile.dedup_distance int 8 Max perceptual-hash distance for a burst; 0 disables dedup.
cull.profile.eye_open_soft float 0.50 Eye-open soft floor; below it, maybe. 0 disables the eye signal.
cull.profile.eye_open_hard float 0 Eye-open hard gate; below it, reject. 0 (default) = off.
cull.profile.min_face_box float 0.10 Ignore faces smaller than this fraction of the frame's shorter side.
cull.profile.smile_soft float 0 Smile soft floor; 0 = off (expression informs ranking only).
cull.profile.facing_soft float 0 Facing-camera soft floor; 0 = off.
cull.profile.aesthetic_floor float 0 Aesthetic maybe-floor; 0 = off.

A per-shoot override lives in <shoot>/.krites/config.yaml under the same cull.profile.* keys; unticking an override in the studio removes the key so the field re-inherits the global. Migrating from an older krites: a shoot's legacy .krites/profile.yaml is converted to sparse overrides on first open and backed up to profile.yaml.pre-cascade.bak.

The aesthetic (white balance + tone + grade/LUT) lives in a look catalog — config-driven, not flat keys here. See specs 0001 §6, 0006, 0007 and 0012.