Configuration Files

Kaizo configuration files are YAML documents that describe how Python objects, functions, and plugins should be loaded, resolved, and executed.

Each key in the YAML file defines a configuration entry.

Note

Unlike traditional configuration systems, Kaizo configuration entries are executable. Accessing an entry may trigger dynamic imports, function calls, or plugin dispatch.

An entry may represent:

  • A literal value

  • A structured data object

  • A dynamically imported callable

  • A lazily executed function

  • A cached execution result

  • A plugin dispatch call

Kaizo converts every entry into an internal Entry object, which is resolved and executed through a unified interface.

Basic Entry Structure

The most common entry form is a module-based executable entry:

entry_name:
  module: module.path
  source: object_name
  args: {}

This form instructs Kaizo to:

  1. Import module.path

  2. Load object_name from that module

  3. Pass args to the object

  4. Optionally call or cache the result

Important

If an entry does not contain both module and source, Kaizo treats it as structured data and resolves it recursively instead of attempting execution.

Entry Properties

module

The module field specifies where Kaizo should load the object from.

It must be a valid Python import path or one of the special values below.

Standard module:

module: math

Special values:

  • local Loads an object from a Python file specified by the top-level local key.

  • plugin Dispatches a registered plugin.

Example:

task:
  module: local
  source: helper_function

Note

The module field is resolved before execution, allowing Kaizo to dynamically import Python code at runtime.

source

The source field specifies the attribute name inside the module.

Depending on context, this can be:

  • A function

  • A class

  • A method name (when used with call)

  • A plugin name (when module: plugin)

Example:

printer:
  module: builtins
  source: print

Important

If the specified source does not exist in the module, Kaizo raises an error during parsing.

args

The args field defines the arguments passed to the resolved callable.

It supports three forms:

  • A list → positional arguments

  • A dict → named argument mapping

  • A string reference → resolved dynamically into a list or dict

List Arguments

A list is resolved element-by-element and passed as positional arguments.

greet:
  module: builtins
  source: print
  args:
    - "Hello"
    - "World"

Each value in the list is fully resolvable and may reference other entries or runtime values.

Dictionary Arguments

A dictionary is resolved key-by-key into a DictEntry and passed as a mapping.

greet:
  module: builtins
  source: print
  args:
    sep: " - "

Each key-value pair is stored in local entry storage and can be referenced by other entries.

String Resolution

If args is a string, it is treated as a reference and resolved at runtime.

The resolved value must evaluate to a list or dictionary. Otherwise, an error is raised.

Example:

shared_args:
    - "Hello"
    - "Kaizo"

greet:
  module: builtins
  source: print
  args: .{shared_args}

At runtime, the string reference is resolved and executed. If the result is not a ListEntry or DictEntry, parsing fails.

Warning

When using string-based args:

  • The resolved value must be a ListEntry or DictEntry

  • Scalar values are not allowed

  • Resolution happens before execution

call

The call field controls how the loaded object is executed.

Supported values:

  • true (default) Call the object directly.

  • false Do not call the object. The raw object is returned instead.

  • "method_name" Call a specific method on the loaded object.

Examples:

Do not call the object:

cls:
  module: my.module
  source: MyClass
  call: false

Call a method:

runner:
  module: my.module
  source: MyClass
  call: run
  args:
    steps: 10

Warning

When call is set to a method name, the method must exist and must be callable, or parsing will fail.

lazy

If lazy is set to true, the entry is not executed immediately.

Instead, Kaizo returns a callable wrapper that can be executed later.

This is useful for:

  • Deferred execution

  • Passing functions as values

  • Composing pipelines

Example:

delayed:
  module: time
  source: sleep
  lazy: true
  args:
    - 5

Note

Accessing a lazy entry returns a callable object, not the execution result.

cache

The cache field controls whether execution results are cached.

  • true (default) Results are cached based on argument identity.

  • false The callable is executed every time the entry is accessed.

Example:

random_value:
  module: random
  source: random
  cache: false

Important

Caching is implemented internally using a per-entry bucket keyed by resolved argument signatures.

Top-Level Configuration Keys

local

The local key specifies a local Python file to load.

All objects inside this file become accessible using module: local.

local: ./helpers.py

Example usage:

compute:
  module: local
  source: add
  args:
    - 1
    - 2

Warning

The local file must exist and be a valid Python module, otherwise parsing will fail.

import

The import key allows importing other YAML configuration files.

Each imported file is parsed with its own ConfigParser instance, and its entries become accessible by module name.

import:
  shared: ./shared.yaml

Referencing imported entries:

task:
  args:
    value: shared.config.{param}

Note

Imported configuration files are resolved relative to the current configuration file.

plugins

The plugins key registers plugin dispatchers.

Plugins must be subclasses of Plugin and live under kaizo.plugins.

Basic plugin registration:

plugins:
  logger: LoggerPlugin

Advanced plugin configuration:

plugins:
  logger:
    source: LoggerPlugin
    args:
      level: INFO

Plugins are invoked using:

run:
  module: plugin
  source: logger

Important

Plugin execution is routed through the plugin’s dispatch method with resolved metadata.

Resolution Summary

Kaizo resolves configuration entries in the following order:

  1. Runtime keyword arguments

  2. Local storage

  3. Imported modules

  4. Plugin dispatch

  5. Python module imports

Note

Every resolved value is wrapped in an Entry object and evaluated through __call__ to ensure consistent execution semantics.