# SpaX
**Declarative hyperparameter search spaces for Python**
Stop wrestling with HPO boilerplate. Define search spaces with type hints, validate automatically, and explore efficiently.
---
## 🚧 Coming Soon
SpaX is currently in active development. The core search space definition system is complete and tested, with experiment tracking and visualization features coming soon.
### What is SpaX?
A unified Python library for defining, exploring, and optimizing hyperparameter search spaces in machine learning. SpaX addresses the gap between parameter definition and systematic exploration that ML engineers and researchers face daily.
### Quick Preview
```python
import spax as sp
class ModelConfig(sp.Config):
learning_rate: float = sp.Float(1e-5, 1e-1, "log")
batch_size: int = sp.Int(8, 128, "log")
optimizer: str = sp.Categorical(["adam", "sgd"])
# Conditional parameter based on optimizer choice
momentum: float = sp.Conditional(
sp.FieldCondition("optimizer", sp.EqualsTo("sgd")),
true=sp.Float(0.8, 0.99),
false=0.0 # Adam doesn't use momentum
)
# Sample random configurations
config = ModelConfig.random()
# Or create with specific values (validated automatically)
config = ModelConfig(
learning_rate=0.001,
batch_size=32,
optimizer="adam",
momentum=0.0
)
```
### Features (Current & Planned)
#### ✅ Available Now
- **Declarative space definition** with type hints
- **Automatic validation** using Pydantic
- **Numeric spaces** (Float, Int) with uniform/log distributions
- **Categorical spaces** with optional weighting
- **Conditional spaces** with dependency tracking
- **Random sampling** from complex nested spaces
- **89% test coverage** with comprehensive edge case handling
#### 🚀 Coming Soon
- **Experiment tracking** with ask-and-tell interface
- **Visualization tools** (parameter importance, search history, correlation)
- **Random search algorithm** built-in
- **Space serialization** (JSON/YAML export/import)
- **Dynamic space manipulation** (pruning/expansion based on results)
- **Integration with Optuna, Hyperopt** and other HPO libraries
- **Parallel experiment execution**
### Why SpaX?
**The Problem:**
- Defining parameters is scattered across your codebase
- Manual validation is error-prone and repetitive
- Conditional parameters require custom logic
- Experiment tracking needs custom infrastructure
- Visualizing results means writing plotting code from scratch
**The Solution:**
- Define spaces once with type hints
- Validation happens automatically
- Conditionals are declarative and type-safe
- Experiments tracked with simple API
- Visualizations built-in
### Installation (Coming Soon)
```bash
pip install spax
```
Currently in pre-release. Star this repo to get notified when we launch!
### Development Status
SpaX is under active development. Core functionality is stable and well-tested. We're currently working on experiment tracking and visualization features.
**Current Version:** 0.1.0-alpha (not yet published to PyPI)
### Roadmap
- [x] Core space definition system
- [x] Conditional dependencies with cycle detection
- [x] Comprehensive test suite
- [ ] Experiment tracking system
- [ ] Basic visualization tools
- [ ] Space serialization (JSON/YAML)
- [ ] Random search optimizer
- [ ] Documentation site
- [ ] First stable release (0.1.0)
- [ ] Optuna/Hyperopt integration
- [ ] Advanced visualizations
- [ ] Parallel execution support
### Stay Updated
- ⭐ Star this repo to follow development
- 👀 Watch for release notifications
- 📖 Documentation site coming soon
### License
MIT License - see LICENSE file for details
---
**Built for ML engineers and researchers who want robust hyperparameter optimization without the pain.**
Raw data
{
"_id": null,
"home_page": null,
"name": "spax",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Keyhan Kamyar <keyhankamyar@gmail.com>",
"keywords": "hyperparameter-optimization, machine-learning, deep-learning, hyperparameter-tuning, experiment-tracking, search-space, automl, hpo, neural-architecture-search",
"author": null,
"author_email": "Keyhan Kamyar <keyhankamyar@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4a/1b/ccd53aed6c82256903b87efb37da08618a781d4d8cb6ad8f4102aee05dc0/spax-0.1.2a0.tar.gz",
"platform": null,
"description": "# SpaX\n\n**Declarative hyperparameter search spaces for Python**\n\nStop wrestling with HPO boilerplate. Define search spaces with type hints, validate automatically, and explore efficiently.\n\n---\n\n## \ud83d\udea7 Coming Soon\n\nSpaX is currently in active development. The core search space definition system is complete and tested, with experiment tracking and visualization features coming soon.\n\n### What is SpaX?\n\nA unified Python library for defining, exploring, and optimizing hyperparameter search spaces in machine learning. SpaX addresses the gap between parameter definition and systematic exploration that ML engineers and researchers face daily.\n\n### Quick Preview\n```python\nimport spax as sp\n\nclass ModelConfig(sp.Config):\n learning_rate: float = sp.Float(1e-5, 1e-1, \"log\")\n batch_size: int = sp.Int(8, 128, \"log\")\n optimizer: str = sp.Categorical([\"adam\", \"sgd\"])\n \n # Conditional parameter based on optimizer choice\n momentum: float = sp.Conditional(\n sp.FieldCondition(\"optimizer\", sp.EqualsTo(\"sgd\")),\n true=sp.Float(0.8, 0.99),\n false=0.0 # Adam doesn't use momentum\n )\n\n# Sample random configurations\nconfig = ModelConfig.random()\n\n# Or create with specific values (validated automatically)\nconfig = ModelConfig(\n learning_rate=0.001,\n batch_size=32,\n optimizer=\"adam\",\n momentum=0.0\n)\n```\n\n### Features (Current & Planned)\n\n#### \u2705 Available Now\n- **Declarative space definition** with type hints\n- **Automatic validation** using Pydantic\n- **Numeric spaces** (Float, Int) with uniform/log distributions\n- **Categorical spaces** with optional weighting\n- **Conditional spaces** with dependency tracking\n- **Random sampling** from complex nested spaces\n- **89% test coverage** with comprehensive edge case handling\n\n#### \ud83d\ude80 Coming Soon\n- **Experiment tracking** with ask-and-tell interface\n- **Visualization tools** (parameter importance, search history, correlation)\n- **Random search algorithm** built-in\n- **Space serialization** (JSON/YAML export/import)\n- **Dynamic space manipulation** (pruning/expansion based on results)\n- **Integration with Optuna, Hyperopt** and other HPO libraries\n- **Parallel experiment execution**\n\n### Why SpaX?\n\n**The Problem:**\n- Defining parameters is scattered across your codebase\n- Manual validation is error-prone and repetitive\n- Conditional parameters require custom logic\n- Experiment tracking needs custom infrastructure\n- Visualizing results means writing plotting code from scratch\n\n**The Solution:**\n- Define spaces once with type hints\n- Validation happens automatically\n- Conditionals are declarative and type-safe\n- Experiments tracked with simple API\n- Visualizations built-in\n\n### Installation (Coming Soon)\n```bash\npip install spax\n```\n\nCurrently in pre-release. Star this repo to get notified when we launch!\n\n### Development Status\n\nSpaX is under active development. Core functionality is stable and well-tested. We're currently working on experiment tracking and visualization features.\n\n**Current Version:** 0.1.0-alpha (not yet published to PyPI)\n\n### Roadmap\n\n- [x] Core space definition system\n- [x] Conditional dependencies with cycle detection\n- [x] Comprehensive test suite\n- [ ] Experiment tracking system\n- [ ] Basic visualization tools\n- [ ] Space serialization (JSON/YAML)\n- [ ] Random search optimizer\n- [ ] Documentation site\n- [ ] First stable release (0.1.0)\n- [ ] Optuna/Hyperopt integration\n- [ ] Advanced visualizations\n- [ ] Parallel execution support\n\n### Stay Updated\n\n- \u2b50 Star this repo to follow development\n- \ud83d\udc40 Watch for release notifications\n- \ud83d\udcd6 Documentation site coming soon\n\n### License\n\nMIT License - see LICENSE file for details\n\n---\n\n**Built for ML engineers and researchers who want robust hyperparameter optimization without the pain.**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Declarative search space definition library for ML hyperparameter optimization",
"version": "0.1.2a0",
"project_urls": {
"Bug Tracker": "https://github.com/keyhankamyar/SpaX/issues",
"Changelog": "https://github.com/keyhankamyar/SpaX/releases",
"Documentation": "https://github.com/keyhankamyar/SpaX#readme",
"Homepage": "https://github.com/keyhankamyar/SpaX",
"Repository": "https://github.com/keyhankamyar/SpaX"
},
"split_keywords": [
"hyperparameter-optimization",
" machine-learning",
" deep-learning",
" hyperparameter-tuning",
" experiment-tracking",
" search-space",
" automl",
" hpo",
" neural-architecture-search"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "56e6e0a2b653a178d75b6c22e2bd8745dc71740215682984d211980331fc2c65",
"md5": "aedfd6e97345e575efec905c260e5147",
"sha256": "a37c78837ffd01c688d52e49059b8781f534744b4dd7461e55d773ab0a0a1945"
},
"downloads": -1,
"filename": "spax-0.1.2a0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aedfd6e97345e575efec905c260e5147",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 26039,
"upload_time": "2025-10-19T14:46:30",
"upload_time_iso_8601": "2025-10-19T14:46:30.903880Z",
"url": "https://files.pythonhosted.org/packages/56/e6/e0a2b653a178d75b6c22e2bd8745dc71740215682984d211980331fc2c65/spax-0.1.2a0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4a1bccd53aed6c82256903b87efb37da08618a781d4d8cb6ad8f4102aee05dc0",
"md5": "3937719456bf7a067036ecd35ba97772",
"sha256": "22061744f1579db8e8aca6482bac1cb97aa5062367f2b871c920df4a678a1238"
},
"downloads": -1,
"filename": "spax-0.1.2a0.tar.gz",
"has_sig": false,
"md5_digest": "3937719456bf7a067036ecd35ba97772",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 41898,
"upload_time": "2025-10-19T14:46:32",
"upload_time_iso_8601": "2025-10-19T14:46:32.661232Z",
"url": "https://files.pythonhosted.org/packages/4a/1b/ccd53aed6c82256903b87efb37da08618a781d4d8cb6ad8f4102aee05dc0/spax-0.1.2a0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 14:46:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "keyhankamyar",
"github_project": "SpaX",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "pydantic",
"specs": []
}
],
"lcname": "spax"
}
JSON
