sparkwheel 0.0.5

A powerful YAML-based configuration system with references, expressions, and dynamic instantiation

⚙️ YAML configuration meets Python 🐍

Define Python objects in YAML. Reference, compose, and instantiate them effortlessly.

What is Sparkwheel?

Stop hardcoding parameters. Define complex Python objects in clean YAML files, compose them naturally, and instantiate with one line.

# config.yaml
model:
  _target_: torch.nn.Linear
  in_features: 784
  out_features: "%dataset::num_classes"  # Reference other values

dataset:
  num_classes: 10

from sparkwheel import Config

config = Config.load("config.yaml")
model = config.resolve("model")  # Actual torch.nn.Linear(784, 10) instance!

Key Features

• Declarative Object Creation - Instantiate any Python class from YAML with _target_
• Smart References - @ for resolved values, % for raw YAML
• Composition by Default - Configs merge naturally (dicts merge, lists extend)
• Explicit Operators - = to replace, ~ to delete when needed
• Python Expressions - Compute values dynamically with $ prefix
• Schema Validation - Type-check configs with Python dataclasses
• CLI Overrides - Override any value from command line

Installation

pip install sparkwheel

→ Get Started in 5 Minutes

Coming from Hydra/OmegaConf?

Sparkwheel builds on similar ideas but adds powerful features:

Feature	Hydra/OmegaConf	Sparkwheel
Config composition	Explicit (+, ++)	By default (dicts merge, lists extend)
Replace semantics	Default	Explicit with = operator
Delete keys	Not idempotent	Idempotent ~ operator
References	OmegaConf interpolation	@ (resolved) + % (raw YAML)
Python expressions	Limited	Full Python with $
Schema validation	Structured Configs	Python dataclasses
List extension	Lists replace	Lists extend by default

Composition by default means configs merge naturally without operators:

# base.yaml
model:
  hidden_size: 256
  dropout: 0.1

# experiment.yaml
model:
  hidden_size: 512  # Override
  # dropout inherited

Documentation

• Full Documentation
• Quick Start Guide
• Core Concepts
• Examples
• API Reference

Community

• Discord Server - Chat with the community
• YouTube Channel - Tutorials and demos
• GitHub Issues - Bug reports and feature requests

Contributing

We welcome contributions! See CONTRIBUTING.md for development setup and guidelines.

About

Sparkwheel is a hard fork of MONAI Bundle's configuration system, refined and expanded for general-purpose use. We're deeply grateful to the MONAI team for their excellent foundation.

Sparkwheel powers Lighter, our configuration-driven deep learning framework built on PyTorch Lightning.

License

Apache License 2.0 - See LICENSE for details.