Settings

A setting is a value a caller chooses that changes how the tool reads, asks, answers, stores, or reports. Every flag in the command's help is one. The question text, the records, and help itself are not.

The typed value wins, then the environment, then the question file, then the configuration file, then the built-in default. A setting skips the tiers it has no home in.

Only a per-call value counts as typed. That is a command flag, or an argument on one library or SQL call, such as a question's threshold or a call's deadline. An engine-level library setting, such as EngineBuilder::throttle or Python's Engine(throttle=), sits in the environment tier. So does a SQL session setting, such as DuckDB's SET thinkthen_throttle or SQLite's thinkthen_configure(json). Each is set once for a process or a session, as a variable is.

The three SQL extensions offer thinkthen_try_details. It returns a row's detailed result, or a JSON failure for a row whose failure lets the query go on to later rows. Cancellation and deadlines still raise errors. SQLite's thinkthen_budget_ms(n) sets one time budget for the connection across ThinkThen calls: -1 clears it, 0 means it is spent, and a positive number of milliseconds bounds the calls that follow until it is reset. PostgreSQL bounds its query with its own statement_timeout and each call with thinkthen.deadline_ms. DuckDB's SET thinkthen_query_budget_ms bounds a whole query on Linux x86-64, Linux ARM64, Apple Silicon and Intel macOS.

The orders on record follow the rule:

• The address: --url, then THINKTHEN_BASE_URL, then the configuration file's url, then the built-in address.
• The backend and the address, together: typed --backend and --url, then EngineBuilder::backend and EngineBuilder::base_url, then THINKTHEN_BACKEND and THINKTHEN_BASE_URL, then the configuration file's backend and url. The first tier that names either decides. For these two settings the engine setting sits above the environment variables, so the environment tier splits in two. On the named path the backend supplies the key variables and, after --model, the question file's model, and the engine's model, the model.
• The model: --model, then the question file's model, then the engine's model, then the configuration file's model, then jev-1.13.0. For example, a saved file with "model":"saved-1" selects saved-1 over a configuration file with "model":"configured-1"; --model typed-1 selects typed-1 over both. The question-file page shows the complete example.
• The answer cache: --cache DIR selects that folder and --no-cache turns caching off for the command. Otherwise a nonblank THINKTHEN_CACHE names a folder and enables caching, even when the configuration file says "cache": false. Without a named folder, the configuration file's boolean cache turns the default answer cache folder on (true, omitted, or null) or off (false). The configuration file never names a cache folder.
• The batch: --batch, then THINKTHEN_BATCH, then the question file's batch, then max.
• A threshold-bearing question file names its tuned batch setting through batch, or 1 when it has no batch. The setting still resolves by the four tiers above; another running setting warns instead of changing it.
• The request size: --max-request-bytes, then THINKTHEN_MAX_REQUEST_BYTES, then 96,000 bytes.

--profile FILE loads a backend profile and has no environment or file tier. The question file's profile is calibration identity, a separate setting with its own row.

Cache forms differ by surface. EngineBuilder::from_env() reads the configuration and THINKTHEN_CACHE; explicit Rust cache_at(folder) and no_cache() override that choice, while a bare Engine::builder() does not read the configuration. Python accepts a folder, True for the default folder, or False for off; TypeScript and C accept a folder or false; Ruby accepts a folder or false (nil keeps the default); R accepts a folder or FALSE (NULL keeps the default). DuckDB's session setting names a folder. PostgreSQL accepts an absolute folder or off; RESET keeps THINKTHEN_CACHE, or no cache when it is unset. SQLite's thinkthen_configure takes "cache" as a folder, or false for off. These library and SQL settings do not change the configuration file's boolean type.

The configuration file is thinkthen.config/1 under the platform configuration home. The tool reads it and never writes it. The file names the address, the model, and the backends with the names of their key variables, so whoever can write it decides where the key and the evidence go. It may also set requests_per_minute on any backend, built-in or added, as the Requests a minute row says. On Unix, the command warns when another user owns the file or any user may write it. It still reads the file, and prints thinkthen: the configuration file is writable by another user; it decides where the key and evidence go on standard error before it runs. The libraries read the file the same way and print nothing. A file that draws this warning may not hold backends, and such a file is refused with exit 5. A file owned by the current user that only its group may write, as the usual 002 umask leaves it, gets no warning. Keep it writable by its owner alone. The cache folder and the configuration file follow XDG_CACHE_HOME, XDG_CONFIG_HOME and HOME. The usage totals follow XDG_STATE_HOME and HOME, as recording.md states. The cache folder never moves them.