config | Kitaru

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_DEFAULT_MODEL_ENV

= _config_env.KITARU_DEFAULT_MODEL_ENV

attributeKITARU_CONFIG_PATH_ENV

= _config_env.KITARU_CONFIG_PATH_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

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

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

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

func_read_global_execution_config() -> KitaruConfig

Read execution defaults from global user config/runtime state.

Returns

kitaru.config.KitaruConfig

func_read_global_connection_config() -> KitaruConfig

Read connection defaults from global user config/runtime state.

Only reads server_url and auth_token from ZenML's persisted store configuration. Project is intentionally omitted here — it is only populated by explicit overrides (env var or runtime configure).

Returns

kitaru.config.KitaruConfig

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_connection_config(*, explicit=None, validate_for_use=False) -> ResolvedConnectionConfig

Resolve connection configuration with connection-specific precedence.

Precedence (lowest to highest):

Global ZenML-backed defaults (server_url, auth_token only)
Environment variable overrides (KITARU_SERVER_URL, etc.)
Runtime overrides from kitaru.configure(project=...)
Explicit argument passed by the caller

paramexplicitKitaruConfig | None

= None

paramvalidate_for_usebool

= False

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

func_kitaru_config_dir() -> Path

Return the Kitaru-owned global config directory.

Returns

pathlib.Path

func_kitaru_global_config_path() -> Path

Return the path to Kitaru's global config file.

Returns

pathlib.Path

func_parse_kitaru_config_file(config_path) -> _KitaruGlobalConfig | None

Parse a Kitaru global config file, returning None if absent.

paramconfig_pathPath

Returns

kitaru.config._KitaruGlobalConfig | None

func_read_kitaru_global_config() -> _KitaruGlobalConfig

Read Kitaru global config from disk.

Returns

kitaru.config._KitaruGlobalConfig

Parsed Kitaru global config.

func_write_kitaru_global_config(config) -> None

Write Kitaru global config to disk.

paramconfig_KitaruGlobalConfig

Returns

None

func_read_kitaru_global_config_for_update() -> _KitaruGlobalConfig

Read global config for mutation, recovering from malformed files.

Returns

kitaru.config._KitaruGlobalConfig

func_update_kitaru_global_config(mutator) -> _KitaruGlobalConfig

Apply an in-place mutation and persist the resulting global config.

parammutatorCallable[[_KitaruGlobalConfig], None]

Returns

kitaru.config._KitaruGlobalConfig

func_read_log_store_env_override() -> ResolvedLogStore | None

Parse an optional log-store override from environment variables.

Returns

kitaru.config.ResolvedLogStore | None

func_resolved_log_store_from_override(override, *, source) -> ResolvedLogStore

Convert a persisted/env override into a resolved log-store view.

paramoverrideLogStoreOverride

paramsourceLiteral['environment', 'global user config']

Returns

kitaru.config.ResolvedLogStore

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

func_read_model_registry_config() -> ModelRegistryConfig

Read the local model registry from global config.

Returns

kitaru.config.ModelRegistryConfig

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 LiteLLM model.

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

func_list_stack_entries() -> list[_StackListEntry]

List stacks with active + managed metadata for structured output.

Returns

list[kitaru.config._StackListEntry]

func_show_stack_operation(name_or_id) -> StackDetails

Inspect one stack and translate its component metadata for CLI display.

paramname_or_idstr

Returns

kitaru.config.StackDetails

func_create_kubernetes_stack_operation(name, *, spec, activate=True, labels=None, component_overrides=None) -> _StackCreateResult

Create a Kubernetes-backed stack via ZenML's one-shot stack API.

paramnamestr

paramspecKubernetesStackSpec

paramactivatebool

= True

paramlabelsdict[str, str] | None

= None

paramcomponent_overridesStackComponentConfigOverrides | None

= None

Returns

kitaru.config._StackCreateResult

func_create_vertex_stack_operation(name, *, spec, activate=True, labels=None, component_overrides=None) -> _StackCreateResult

Create a Vertex AI stack via ZenML's one-shot stack API.

paramnamestr

paramspecVertexStackSpec

paramactivatebool

= True

paramlabelsdict[str, str] | None

= None

paramcomponent_overridesStackComponentConfigOverrides | None

= None

Returns

kitaru.config._StackCreateResult

func_create_sagemaker_stack_operation(name, *, spec, activate=True, labels=None, component_overrides=None) -> _StackCreateResult

Create a SageMaker stack via ZenML's one-shot stack API.

paramnamestr

paramspecSagemakerStackSpec

paramactivatebool

= True

paramlabelsdict[str, str] | None

= None

paramcomponent_overridesStackComponentConfigOverrides | None

= None

Returns

kitaru.config._StackCreateResult

func_create_azureml_stack_operation(name, *, spec, activate=True, labels=None, component_overrides=None) -> _StackCreateResult

Create an AzureML stack via ZenML's one-shot stack API.

paramnamestr

paramspecAzureMLStackSpec

paramactivatebool

= True

paramlabelsdict[str, str] | None

= None

paramcomponent_overridesStackComponentConfigOverrides | None

= None

Returns

kitaru.config._StackCreateResult

func_create_stack_operation

(name, *, stack_type=StackType.LOCAL, activate=True, labels=None, remote_spec=None, component_overrides=None) -> _StackCreateResult

Create a stack by dispatching to the requested stack type flow.

paramnamestr

paramstack_typeStackType

= StackType.LOCAL

paramactivatebool

= True

paramlabelsdict[str, str] | None

= None

paramremote_specRemoteStackSpec | None

= None

paramcomponent_overridesStackComponentConfigOverrides | None

= None

Returns

kitaru.config._StackCreateResult

func_create_local_stack_operation(name, *, activate=True, labels=None, component_overrides=None) -> _StackCreateResult

Create a new local stack and return structured operation details.

paramnamestr

paramactivatebool

= True

paramlabelsdict[str, str] | None

= None

paramcomponent_overridesStackComponentConfigOverrides | None

= None

Returns

kitaru.config._StackCreateResult

func_delete_stack_operation(name_or_id, *, recursive=False, force=False) -> _StackDeleteResult

Delete a stack and return structured operation details.

paramname_or_idstr

paramrecursivebool

= False

paramforcebool

= False

Returns

kitaru.config._StackDeleteResult

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.

func_suppress_zenml_cli_messages() -> Iterator[None]

Silence ZenML success/progress chatter while Kitaru reuses its helpers.

This keeps the user-facing CLI output in Kitaru terms while still using ZenML's connection/authentication machinery underneath.

Returns

collections.abc.Iterator[None]

func_login_to_server_target(server, *, api_key=None, refresh=False, project=None, verify_ssl=True, 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.

paramverify_sslbool | str

= True

TLS verification mode or CA bundle path.

paramcloud_api_urlstr | None

= None

Optional managed-cloud API URL used for staging or custom control planes.

paramtimeoutint | None

= None

Optional connection timeout forwarded when supported by the underlying runtime.

Returns

None

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

Set process-local runtime defaults.

Execution-level fields (stack, image, cache, retries) 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.

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