Managing complex configurations any other way would be highly illogical...

Quick Start · Documentation · Examples · Releases

About

spock is a framework that helps users easily define, manage, and use complex parameter configurations within Python applications. It lets you focus on the code you need to write instead of re-implementing boilerplate code such as creating ArgParsers, reading configuration files, handling dependencies, implementing type validation, maintaining traceability, etc.

spock configurations are normal python classes that are decorated with @spock. It supports inheritance, dynamic class dependencies, loading/saving configurations from/to multiple markdown formats, automatically generating CLI arguments, and hierarchical configuration by composition.

💥 Why You Should Use Spock 💥

• Simple organized parameter definitions (i.e. a single line)
• Type checked (static-eqsue) & frozen parameters (i.e. fail early during long ML training runs)
• Complex parameter dependencies made simple (i.e. @spock class with a parameter that is an Enum of other @spock classes)
• Fully serializable parameter state(s) (i.e. exactly reproduce prior runtime parameter configurations)
• Automatic type checked CLI generation w/o argparser boilerplate (i.e click and/or typer for free!)
• Easily maintain parity between CLIs and Python APIs (i.e. single line changes between CLI and Python API definitions)
• Unified hyper-parameter definitions and interface (i.e. don't write different definitions for Ax or Optuna)
• Resolver that supports value definitions from reference to other defined variables, environmental variables, dynamic template re-injection, and encryption of sensitive values

Key Features

• Simple Declaration: Type checked parameters are defined within a @spock decorated class. Supports required/optional and automatic defaults.
• Easily Managed Parameter Groups: Each class automatically generates its own object within a single namespace.
• Parameter Inheritance: Classes support inheritance (w/ lazy evaluation of inheritance/dependencies) allowing for complex configurations derived from a common base set of parameters.
• Complex Types: Nested Lists/Tuples, List/Tuples of Enum of @spock classes, List of repeated @spock classes
• Multiple Configuration File Types: Configurations are specified from YAML, TOML, or JSON files.
• Hierarchical Configuration: Compose from multiple configuration files via simple include statements.
• Command-Line Overrides: Quickly experiment by overriding a value with automatically generated command line arguments.
• Immutable: All classes are frozen preventing any misuse or accidental overwrites (to the extent they can be in Python).
• Tractability and Reproducibility: Save runtime parameter configuration to YAML, TOML, or JSON with a single chained command (with extra runtime info such as Git info, Python version, machine FQDN, etc). The saved markdown file can be used as the configuration input to reproduce prior runtime configurations.
• Hyper-Parameter Tuner Addon: Provides a unified interface for defining hyper-parameters (via @spockTuner decorator) that supports various tuning/algorithm backends (currently: Optuna, Ax)
• S3 Addon: Automatically detects s3:// URI(s) and handles loading and saving spock configuration files when an active boto3.Session is passed in (plus any additional S3Transfer configurations)

Quick Install

The basic install and [s3] extension require Python 3.7+ while the [tune] extension requires Python 3.8+

News/Releases

See Releases for more information.

Recent Changes

Original Implementation

spock was originally developed by the Artificial Intelligence Center of Excellence at Fidelity Investments by Nicholas Cilfone and Siddharth Narayanan