config | Kitaru Reference

Configuration and connection management.

This module contains:

global config helpers for runtime log-store settings
stack-selection helpers
runtime configuration via kitaru.configure(...)
config precedence resolution for execution and connection settings

attributezenml_cli_utils

= importlib.import_module('zenml.cli.utils')

attributeKITARU_ANALYTICS_OPT_IN_ENV

= _kitaru_env.KITARU_ANALYTICS_OPT_IN_ENV

attributeKITARU_AUTH_TOKEN_ENV

= _kitaru_env.KITARU_AUTH_TOKEN_ENV

attributeKITARU_DEBUG_ENV

= _kitaru_env.KITARU_DEBUG_ENV

attributeKITARU_PROJECT_ENV

= _kitaru_env.KITARU_PROJECT_ENV

attributeKITARU_SERVER_URL_ENV

= _kitaru_env.KITARU_SERVER_URL_ENV

attributeKITARU_LOG_STORE_BACKEND_ENV

= _config_env.KITARU_LOG_STORE_BACKEND_ENV

attributeKITARU_LOG_STORE_ENDPOINT_ENV

= _config_env.KITARU_LOG_STORE_ENDPOINT_ENV

attributeKITARU_LOG_STORE_API_KEY_ENV

= _config_env.KITARU_LOG_STORE_API_KEY_ENV

attributeKITARU_STACK_ENV

= _config_env.KITARU_STACK_ENV

attributeKITARU_CACHE_ENV

= _config_env.KITARU_CACHE_ENV

attributeKITARU_RETRIES_ENV

= _config_env.KITARU_RETRIES_ENV

attributeKITARU_IMAGE_ENV

= _config_env.KITARU_IMAGE_ENV

attributeKITARU_LLM_ESTIMATED_COSTS_ENV

= _config_env.KITARU_LLM_ESTIMATED_COSTS_ENV

attributeKITARU_DEFAULT_MODEL_ENV

= _config_env.KITARU_DEFAULT_MODEL_ENV

attributeKITARU_CONFIG_PATH_ENV

= _config_env.KITARU_CONFIG_PATH_ENV

attributeKITARU_UI_URL_ENV

= _config_env.KITARU_UI_URL_ENV

attributeKITARU_MODEL_REGISTRY_ENV

= _kitaru_env.KITARU_MODEL_REGISTRY_ENV

attributeZENML_CONFIG_PATH_ENV

= _ZENML_CONFIG_PATH_ENV

attributeZENML_STORE_API_KEY_ENV

= _ZENML_STORE_API_KEY_ENV

attributeZENML_STORE_URL_ENV

= _ZENML_STORE_URL_ENV

attributeFROZEN_EXECUTION_SPEC_METADATA_KEY

= _config_execution_spec.FROZEN_EXECUTION_SPEC_METADATA_KEY

attributeImageSettings

= _config_images.ImageSettings

attributeImageInput

= _config_images.ImageInput

attributeKitaruConfig

= _config_core.KitaruConfig

attributeLLMEstimatedCostsPolicy

= _config_core.LLMEstimatedCostsPolicy

attributeResolvedExecutionConfig

= _config_core.ResolvedExecutionConfig

attributeResolvedConnectionConfig

= _config_core.ResolvedConnectionConfig

attributeActiveEnvironmentVariable

= _config_core.ActiveEnvironmentVariable

attributeFrozenExecutionSpec

= _config_execution_spec.FrozenExecutionSpec

attributeLogStoreOverride

= _config_log_store.LogStoreOverride

attributeResolvedLogStore

= _config_log_store.ResolvedLogStore

attributeActiveStackLogStore

= _config_log_store.ActiveStackLogStore

attributeModelAliasConfig

= _config_models.ModelAliasConfig

attributeModelRegistryConfig

= _config_models.ModelRegistryConfig

attributeModelAliasEntry

= _config_models.ModelAliasEntry

attributeResolvedModelSelection

= _config_models.ResolvedModelSelection

attributeProjectInfo

= _config_projects.ProjectInfo

attributeProjectCreateResult

= _config_projects.ProjectCreateResult

attributeProjectDeleteResult

= _config_projects.ProjectDeleteResult

attributeSandboxCommandResult

= _config_sandbox.SandboxCommandResult

attributeStackInfo

= _config_stacks.StackInfo

attributeStackType

= _config_stacks.StackType

attributeCloudProvider

= _config_stacks.CloudProvider

attributeKubernetesStackSpec

= _config_stacks.KubernetesStackSpec

attributeVertexStackSpec

= _config_stacks.VertexStackSpec

attributeSagemakerStackSpec

= _config_stacks.SagemakerStackSpec

attributeAzureMLStackSpec

= _config_stacks.AzureMLStackSpec

attributeModalStackSpec

= _config_stacks.ModalStackSpec

attributeRemoteStackSpec

= _config_stacks.RemoteStackSpec

attributeStackComponentConfigOverrides

= _config_stacks.StackComponentConfigOverrides

attributeStackComponentDetails

= _config_stacks.StackComponentDetails

attributeStackDetails

= _config_stacks.StackDetails

attributeimage_settings_to_docker_settings

= _config_images.image_settings_to_docker_settings

attributebuild_frozen_execution_spec

= _config_execution_spec.build_frozen_execution_spec

attributeDEFAULT_SANDBOX_COMMAND_MAX_CHARS

= _config_sandbox.DEFAULT_SANDBOX_COMMAND_MAX_CHARS

attributecurrent_project

= _config_projects.current_project

attributelist_projects

= _config_projects.list_projects

attributeget_project

= _config_projects.get_project

attributecreate_project

= _config_projects.create_project

attributedelete_project

= _config_projects.delete_project

attributeuse_project

= _config_projects.use_project

funcresolve_execution_config(*, decorator_overrides=None, invocation_overrides=None, start_dir=None) -> ResolvedExecutionConfig

Resolve execution configuration according to Phase 10 precedence.

paramdecorator_overridesKitaruConfig | None

= None

paraminvocation_overridesKitaruConfig | None

= None

paramstart_dirPath | None

= None

Returns

kitaru.config.ResolvedExecutionConfig

funcresolve_llm_estimated_cost_policy(*, start_dir=None) -> LLMEstimatedCostsPolicy

Resolve direct kitaru.llm() estimated-cost policy.

Direct LLM calls use the execution-config precedence chain entries that can exist at call time: project config, environment variables, then runtime kitaru.configure(...) overrides. The default is "auto".

paramstart_dirPath | None

= None

Returns

kitaru.config.LLMEstimatedCostsPolicy

funcresolve_connection_config(*, explicit=None, validate_for_use=False, require_project=True) -> ResolvedConnectionConfig

Resolve connection configuration with connection-specific precedence.

Precedence (lowest to highest):

Persisted ZenML-backed defaults (server_url, auth_token, active project)
Direct ZenML compatibility environment variables
Public Kitaru environment variables
Runtime overrides from kitaru.configure(project=...)
Explicit argument passed by the caller

paramexplicitKitaruConfig | None

= None

paramvalidate_for_usebool

= False

paramrequire_projectbool

= True

Returns

kitaru.config.ResolvedConnectionConfig

funcpersist_frozen_execution_spec(*, run_id, frozen_execution_spec) -> None

Persist a frozen execution spec as pipeline-run metadata.

paramrun_idUUID | str

paramfrozen_execution_specFrozenExecutionSpec

Returns

None

funcresolve_log_store() -> ResolvedLogStore

Resolve the effective runtime log-store backend.

Returns

kitaru.config.ResolvedLogStore

funcactive_stack_log_store() -> ActiveStackLogStore | None

Return the runtime log-store backend from the active stack.

Returns

kitaru.config.ActiveStackLogStore | None

funcset_global_log_store(backend, *, endpoint, api_key=None) -> ResolvedLogStore

Persist a global log-store override backend.

parambackendstr

paramendpointstr

paramapi_keystr | None

= None

Returns

kitaru.config.ResolvedLogStore

funcreset_global_log_store() -> ResolvedLogStore

Clear the persisted global log-store override.

Returns

kitaru.config.ResolvedLogStore

funcregister_model_alias(alias, *, model, secret=None) -> ModelAliasEntry

paramaliasstr

parammodelstr

paramsecretstr | None

= None

Returns

kitaru.config.ModelAliasEntry

funclist_model_aliases() -> list[ModelAliasEntry]

List model aliases visible in the current process environment.

Returns

list[kitaru.config.ModelAliasEntry]

funcresolve_model_selection(model) -> ResolvedModelSelection

Resolve an explicit/default model input to a concrete model string.

parammodelstr | None

Returns

kitaru.config.ResolvedModelSelection

funclist_active_kitaru_environment_variables() -> list[ActiveEnvironmentVariable]

Return the active public Kitaru environment variables in stable order.

Returns

list[kitaru.config.ActiveEnvironmentVariable]

funccurrent_stack() -> StackInfo

Return the currently active stack.

The active stack is managed by the underlying runtime and persisted in the runtime's global user configuration.

Returns

kitaru.config.StackInfo

funcclassify_stack_model_deployment_type(stack_model) -> _config_stacks._StackShowType

Classify an already-hydrated stack into Kitaru's deployment taxonomy.

paramstack_modelobject

Returns

kitaru._config._stacks.kitaru._config._stacks._StackShowType

funcclassify_stack_deployment_type(name_or_id=None) -> _config_stacks._StackShowType

Classify a stack into Kitaru's low-cardinality deployment taxonomy.

paramname_or_idstr | None

= None

Returns

kitaru._config._stacks.kitaru._config._stacks._StackShowType

funcrun_sandbox_command

(command, *, cwd=None, env=None, max_chars=DEFAULT_SANDBOX_COMMAND_MAX_CHARS, timeout_seconds=None, cleanup='destroy') -> SandboxCommandResult

Execute one command through the active stack's sandbox component.

paramcommandstr | Sequence[str]

Command to execute, as a provider-interpreted string or an argv-style command list. For exact argument splitting, pass a sequence.

paramcwdstr | None

= None

Optional working directory inside the sandbox.

paramenvMapping[str, str] | None

= None

Optional environment variables for the command. These values are passed to the sandbox provider but are not included in the result.

parammax_charsint

= DEFAULT_SANDBOX_COMMAND_MAX_CHARS

Maximum characters to collect from each output stream.

paramtimeout_secondsfloat | None

= None

Optional application-owned timeout for command execution. If the command does not finish in time, Kitaru asks the process to stop, cleans up the session on a best-effort basis, and returns a structured timeout result.

paramcleanupLiteral['destroy', 'close']

= 'destroy'

Whether to destroy or close the fresh sandbox session after the command completes.

Returns

kitaru.config.SandboxCommandResult

Structured command output and cleanup status.

funclist_stacks() -> list[StackInfo]

List stacks visible to the current user and mark the active one.

Returns

list[kitaru.config.StackInfo]

funccreate_stack(name, *, activate=True, labels=None) -> StackInfo

Create a new local stack and optionally activate it.

paramnamestr

paramactivatebool

= True

paramlabelsdict[str, str] | None

= None

Returns

kitaru.config.StackInfo

funcdelete_stack(name_or_id, *, recursive=False, force=False) -> None

Delete a stack and optionally its components.

paramname_or_idstr

paramrecursivebool

= False

paramforcebool

= False

Returns

None

funcuse_stack(name_or_id) -> StackInfo

Set the active stack and return the resulting active stack info.

paramname_or_idstr

Stack name or stack ID.

Returns

kitaru.config.StackInfo

Information about the newly active stack.

funcconfigure

(*, stack=_UNSET, image=_UNSET, cache=_UNSET, retries=_UNSET, llm_estimated_costs=_UNSET, project=_UNSET) -> KitaruConfig

Set process-local runtime defaults.

Execution-level fields (stack, image, cache, retries, llm_estimated_costs) update the execution precedence chain. The project field updates the connection precedence chain and is intended as an internal / testing escape hatch — it is not a normal user-facing setting.

paramstackstr | None | object

= _UNSET

Default stack name/ID override.

paramimageImageInput | None | object

= _UNSET

Default image settings override.

paramcachebool | None | object

= _UNSET

Default cache behavior override.

paramretriesint | None | object

= _UNSET

Default retry-count override.

paramllm_estimated_costsstr | None | object

= _UNSET

Estimated-cost policy for direct kitaru.llm() calls. Use "auto" to calculate estimates when possible, "off" to disable calculation, or None to clear the runtime override.

paramprojectstr | None | object

= _UNSET

Project override (internal/testing). Set to None to clear.

Returns

kitaru.config.KitaruConfig

The current runtime override layer after applying updates.

funcconnect

(server_url, *, api_key=None, refresh=False, project=None, no_verify_ssl=False, ssl_ca_cert=None, cloud_api_url=None, timeout=None) -> None

Connect to a Kitaru server.

Under the hood, this connects to a ZenML server and stores the resolved connection/auth state in ZenML's global user configuration.

paramserver_urlstr

URL of the Kitaru server.

paramapi_keystr | None

= None

API key used to authenticate with the server.

paramrefreshbool

= False

Force a fresh authentication flow.

paramprojectstr | None

= None

Project name or ID to activate after connecting.

paramno_verify_sslbool

= False

Disable TLS certificate verification.

paramssl_ca_certstr | None

= None

Path to a CA bundle used to verify the server.

paramcloud_api_urlstr | None

= None

Optional managed-cloud API URL used when the server URL points at a managed Kitaru deployment or staging environment.

paramtimeoutint | None

= None

Optional connection timeout forwarded when supported by the underlying runtime.

Returns

None

funclogin_to_server

(server, *, api_key=None, refresh=False, project=None, no_verify_ssl=False, ssl_ca_cert=None, cloud_api_url=None, timeout=None) -> None

Connect to a Kitaru server URL or managed workspace target.

paramserverstr

Kitaru server URL, workspace name, or workspace ID.

paramapi_keystr | None

= None

API key used to authenticate with the server.

paramrefreshbool

= False

Force a fresh authentication flow.

paramprojectstr | None

= None

Project name or ID to activate after connecting.

paramno_verify_sslbool

= False

Disable TLS certificate verification.

paramssl_ca_certstr | None

= None

Path to a CA bundle used to verify the server.

paramcloud_api_urlstr | None

= None

Optional managed-cloud API URL used when connecting to staging or another non-default control plane.

paramtimeoutint | None

= None

Optional connection timeout forwarded when supported by the underlying runtime.

Returns

None