Configuration

Settings

Bases: BaseModel

Typed, injected configuration for the Korchestrator SDK.

A plain, immutable configuration model. Bare construction performs no environment or file access — pass explicit values, or use :meth:from_env to layer .env, the environment, and explicit overrides on top of the declared defaults. Every other module receives a Settings instance by injection; nothing else reads the environment or a .env file.

With no environment and no arguments, the defaults describe a zero-config local run: the offline MockLM gateway, the in-process local runtime, and in-memory persistence.

Attributes:

Name	Type	Description
`mock_llm`	`bool`	Use the deterministic offline MockLM gateway. Defaults to `True`; under :meth:`from_env`, defaults to `False` when a gateway key is configured instead (spec 08 §1.3) — bare construction always defaults to `True`.
`korch_runtime`	`Literal['local', 'temporal']`	Which durable runtime drives the superstep loop — `"local"` in-process, or `"temporal"` for durable execution.
`persistence_backend`	`Literal['none', 'memory', 'kcg']`	Which context-graph backend to use; `"none"` runs fully standalone with no external store.
`kendra_ai_gateway_url`	`str \| None`	The model gateway's base URL. `LLM_GATEWAY_URL` is a recognised alias environment variable name for this same field.
`kendra_gateway_api_key`	`SecretStr \| None`	The model gateway's API key. Never logged or serialised in plain text (`SecretStr`).
`governance_trust_threshold`	`float`	The global fallback HITL intervention threshold (`GOVERNANCE_TRUST_THRESHOLD`, spec 08 §1.3), used when an agent has no per-agent `AgentConfig.hitl_threshold` of its own.
`routing_strategy`	`Literal['explicit', 'semantic', 'algorithmic', 'composite']`	How a model is chosen per agent — `"explicit"` (the default; works with no extra) plus its fallback, `"algorithmic"`, `"semantic"` (needs the `[routing]` extra), or `"composite"`.
`agent_model_map`	`dict[str, str]`	Explicit `agent_id → model` overrides for the explicit strategy.
`routing_weights`	`dict[str, float]`	Algorithmic ranking weights over `"quality"`, `"cost"`, `"latency"`.
`routing_priority_order`	`tuple[str, ...]`	The composite fallback chain, tried in order; `"fallback"` is the always-succeeds tail that keeps the default install resolvable.
`embedding_provider`	`str \| None`	The embedding backend name for the semantic strategy (`[routing]`).
`modelcard_source`	`Literal['builtin', 'file', 'url']`	Where candidate :class:`ModelCard`s come from — `"builtin"` (default), `"file"`, or `"url"`.
`modelcard_path`	`str \| None`	Path to a JSON model-card file when `modelcard_source="file"`.
`modelcard_url`	`str \| None`	URL of a model-card document when `modelcard_source="url"`.
`modelcard_cache_ttl_seconds`	`int`	How long the semantic strategy caches card embeddings.
`korch_max_supersteps`	`int`	The default hard halt bound for a run (1-100).
`korch_plugins_enabled`	`bool`	Whether entry-point plugin discovery (connectors, routers) runs.
`korch_log_level`	`str`	The level :func:`~korchestrator.logging.enable_logging` defaults to.
`korch_telemetry_enabled`	`bool`	Whether OTel instrumentation is active (`[otel]` extra).
`korch_engine_url`	`str \| None`	The remote Korchestrator engine's base URL (`[remote]` extra).
`korch_engine_api_key`	`SecretStr \| None`	The remote engine's API key (`SecretStr`).
`korch_engine_namespace`	`str`	The remote engine's namespace.
`korch_engine_task_queue`	`str`	The remote engine's task queue name.
`temporal_address`	`str`	The Temporal server address for the durable runtime.
`temporal_namespace`	`str`	The Temporal namespace.
`temporal_task_queue`	`str`	The Temporal task queue name.
`temporal_api_key`	`SecretStr \| None`	The Temporal Cloud API key; when set, the connection uses TLS (`SecretStr`).
`temporal_hitl_timeout_seconds`	`int`	How long a `governance_paused` run waits for a signal before transitioning to `timed_out` (spec 06 §7).

Example

from korchestrator.config import Settings Settings().korch_runtime 'local' Settings(korch_runtime="temporal").korch_runtime 'temporal' Settings().routing_strategy 'explicit'

from_env `classmethod`

from_env(
    *,
    dotenv_path: str | Path | None = None,
    **overrides: Any,
) -> Settings

Build Settings from the environment (and optionally .env) plus overrides.

Precedence, highest first: keyword argument, environment variable, .env file entry (only when dotenv_path is given), declared default. Only the recognised variables (the scalar, JSON, and CSV maps at module top) are read; any other variable is ignored. Scalar values are validated by pydantic, so an unrecognised runtime, backend, or strategy raises a pydantic.ValidationError at construction rather than at first use; malformed JSON raises an actionable :class:~korchestrator.exceptions.ConfigurationError.

.env loading is opt-in here (dotenv_path defaults to None) so this method stays side-effect-free by default for internal callers (Korch/Swarm resolve settings via a bare from_env() call per run) and for tests. :func:~korchestrator. config.configure — the process-wide, application-startup entry point — passes dotenv_path=".env" by default, matching spec 08 §1's precedence chain for the caller that is actually expected to load a project's .env file.

mock_llm, when not explicitly set by an override, .env, or the environment, defaults to False if a gateway key (KENDRA_GATEWAY_API_KEY) resolved, else True (spec 08 §1.3) — bare Settings() construction is unaffected and always defaults to True.

Parameters:

Name	Type	Description	Default
`dotenv_path`	`str \| Path \| None`	Path to a `.env` file to layer in. `None` (the default) skips `.env` entirely; a missing file at the given path is not an error.	`None`
`**overrides`	`Any`	Explicit field values that take precedence over everything else.	`{}`

Returns:

Type	Description
`Settings`	A validated, immutable :class:`Settings`.

Raises:

Type	Description
`ConfigurationError`	If a JSON-typed variable (`AGENT_MODEL_MAP`, `ROUTING_WEIGHTS`) holds invalid JSON.

Example

from korchestrator.config import Settings Settings().persistence_backend # bare construction reads no environment 'memory' Settings.from_env(korch_runtime="temporal").korch_runtime # explicit arg wins 'temporal'

configure

configure(
    *,
    dotenv_path: str | Path | None = ".env",
    **overrides: Any,
) -> Settings

Build, validate, and install a new process-wide :class:Settings (spec 08 §1.2).

Layers overrides over the environment, an optional .env file, and the declared defaults (:meth:Settings.from_env's precedence), validates the result immediately, and installs it as what :func:get_settings subsequently returns. Unlike a bare Settings.from_env() call, configure() reads .env from the current working directory by default — this is the application-startup entry point spec 08 §1's precedence chain has in mind; pass dotenv_path=None to skip it.

MUST NOT be called from inside a superstep — it mutates process-wide state, which would be a determinism violation in workflow scope (spec 06 §5). Tests use a settings fixture that resets the installed instance on teardown so no test leaks state into another.

Parameters:

Name	Type	Description	Default
`dotenv_path`	`str \| Path \| None`	Path to a `.env` file to layer in; `None` skips it. Defaults to `.env` in the current working directory; a missing file is not an error.	`'.env'`
`**overrides`	`Any`	Explicit field values; see :class:`Settings` for the full list.	`{}`

Returns:

Type	Description
`Settings`	The newly installed, validated :class:`Settings`.

Raises:

Type	Description
`ValidationError`	If an override or a resolved environment value fails structural validation (wraps the underlying `pydantic.ValidationError`; spec 08 §1.2).

Example

from korchestrator.config import configure, get_settings _ = configure(dotenv_path=None, korch_runtime="local", governance_trust_threshold=0.7) get_settings().governance_trust_threshold 0.7

enable_logging

enable_logging(
    level: str = "INFO", *, stream: TextIO | None = None
) -> None

Attach a single StreamHandler to the korchestrator logger (spec 08 §3).

Idempotent — calling this again replaces the previously attached handler and level rather than stacking a second one. Never touches the root logger and never calls logging.basicConfig(), so an embedding application's own logging configuration stays untouched.

Parameters:

Name	Type	Description	Default
`level`	`str`	The log level name, case-insensitive (`"DEBUG"`, `"INFO"`, `"WARNING"`, `"ERROR"`, `"CRITICAL"`, or `"NOTSET"`). Defaults to `"INFO"`.	`'INFO'`
`stream`	`TextIO \| None`	Where to write; defaults to `sys.stderr` (`logging.StreamHandler`'s own default when `stream` is `None`).	`None`

Raises:

Type	Description
`ValidationError`	If `level` is not a recognised level name.

Example

from korchestrator.logging import disable_logging, enable_logging enable_logging("DEBUG") disable_logging()

disable_logging

disable_logging() -> None

Remove the handler :func:enable_logging attached, if any. Idempotent.

Example

from korchestrator.logging import disable_logging, enable_logging enable_logging() disable_logging() disable_logging() # idempotent -- a second call is a no-op

Configuration

Settings

from_env classmethod

configure

enable_logging

disable_logging

from_env `classmethod`