Skip to main content
Adjusts SDK-wide settings such as cache backend, session timeout, retry policy, and logging. configure() is synchronous and must be called before initialize(). Once the SDK is initialized, re-configuration is rejected to prevent inconsistent runtime state. In JavaScript, initialize() is optional; configure() is locked only after you call it yourself. Any options not supplied keep their existing values.

Parameters

str
Override the default cache storage path on disk. Python only. JavaScript accepts it and ignores it.
str | None
Cache backend selection. Pass "sqlite" to enable on-disk caching, or None to disable it. Anything other than "sqlite" or None raises InvalidInputError (Python 0.5.21 and later; earlier versions treated any value as "sqlite"). Python only. JavaScript accepts it and ignores it.
int
Session timeout in minutes. Accepted range is 5-1440. Python only. JavaScript accepts it and ignores it.
TimeoutConfig | dict
Per-operation timeout overrides. Pass either a TimeoutConfig instance or a plain dict with the fields you want to override.
RetryPolicy | dict | None
Retry policy for transient failures. Pass a RetryPolicy, a dict, or None to disable retries entirely.
str
Logging verbosity. One of "DEBUG", "INFO", "WARNING", "ERROR" or "CRITICAL", in any case. Anything else raises InvalidInputError (Python 0.5.21 and later; earlier versions used WARNING). Python only. JavaScript accepts it and ignores it.
logging.Logger
Custom logger instance to replace the SDK’s internal logger.
str
The model your agent runs on, for example "gpt-4o". Sent with every turn you record (record_message, send_message), and Synap uses its context window to decide when to compact; see record_message for when that happens. A name is enough for common models. Without it, Synap assumes a 128K window. The per-call model on record_message and send_message overrides it. Python 0.5.11 and later. JavaScript and TypeScript 0.5.9 and later.
int
Your agent model’s context window, in tokens. Only needed for a model Synap does not know by name. It takes precedence over the model name. The per-call context_window overrides it. Python 0.5.11 and later. JavaScript and TypeScript 0.5.9 and later.
str | None
default:"auto"
The local model the SDK uses to search earlier turns after a compaction, and to match a fetch to context it already holds, by meaning rather than only by words. "auto" (default) uses the SDK’s multilingual model (paraphrase-multilingual-MiniLM-L12-v2) when its runtime is installed (see Installation). It is downloaded once, about 135 MB, into ~/.synap/models, and loaded in the background. None (null in JavaScript) keeps keyword matching only; so does SYNAP_SDK_LOCAL_MODEL=off. Python 0.5.11 and later. JavaScript and TypeScript: on the constructor from 0.5.9, on configure() from 0.5.19.

Returns

Returns None.

Example

Raises

  • InvalidInputError: when configure() is called after initialize(), or when a value is not accepted (Python 0.5.21 and later; earlier Python raised pydantic’s ValidationError for an out-of-range value).
  • An unknown setting is logged as a warning and ignored (Python 0.5.21 and later).
See Error Codes for the full SDK exception hierarchy.

See also