# Yanex - Yet Another Experiment Tracker
A lightweight, Git-aware experiment tracking system for Python that makes reproducible research effortless.
## Why Yanex?
**Stop losing track of your experiments.** Yanex automatically tracks parameters, results, and code state so you can focus on what matters - your research.
```python
import yanex
# read parameters from config file or CLI arguments
lr = yanex.get_param('lr', default=0.001)
epochs = yanex.get_param('epochs', default=10)
# your experiment code
# ...
# log results, artifacts and figures
yanex.log_metrics({"step": epoch, "loss", loss, "accuracy": accuracy})
yanex.log_artifact("model.pth", model_path)
yanex.log_matplotlib_figure(fig, "loss_curve.png")
```
Run from the command line:
```bash
# Run with yanex CLI for automatic tracking
yanex run train.py --param lr=10e-3 --param epochs=10
```
That's it. Yanex creates a separate directory for each experiment, saves the logged results and files, stdout and stderr outptus, Python environment information, and even the Git state of your code repository. You can then compare results, search experiments, and reproduce them with ease.
## Key Features
- 🔒 **Reproducible**: Automatic Git state tracking ensures every experiment is reproducible
- 📊 **Interactive Comparison**: Compare experiments side-by-side with an interactive table
- ⚙️ **Flexible Parameters**: YAML configs with CLI overrides for easy experimentation and syntax for parameter sweeps
- 📈 **Rich Logging**: Track metrics, artifacts, and figures
- 🔍 **Powerful Search**: Find experiments by status, parameters, tags, or time ranges
- 📦 **Zero Dependencies**: No external services required - works offline
## Quick Start
### Install
```bash
pip install yanex
```
### 1. Run Your First Experiment
```python
# experiment.py
import yanex
params = yanex.get_params()
print(f"Learning rate: {params.get('learning_rate', 0.001)}")
# Simulate training
accuracy = 0.85 + (params.get('learning_rate', 0.001) * 10)
yanex.log_metrics({
"accuracy": accuracy,
"loss": 1 - accuracy
})
```
```bash
# Run with default parameters
yanex run experiment.py
# Override parameters
yanex run experiment.py --param learning_rate=0.01 --param epochs=50
# Add tags for organization
yanex run experiment.py --tag baseline --tag "quick-test"
```
### 2. Compare Results
```bash
# Interactive comparison table
yanex compare
# Compare specific experiments
yanex compare exp1 exp2 exp3
# Filter and compare
yanex compare --status completed --tag baseline
```
### 3. Track Everything
List, search, and manage your experiments:
```bash
# List recent experiments
yanex list
# Find experiments by criteria
yanex list --status completed --tag production
yanex list --started-after "1 week ago"
# Show detailed experiment info
yanex show exp_id
# Archive old experiments
yanex archive --started-before "1 month ago"
```
## Two Ways to Use Yanex
Yanex supports two usage patterns:
### 1. CLI-First (Recommended)
Write scripts that work both standalone and with yanex tracking:
```python
# train.py - Works both ways!
import yanex
params = yanex.get_params() # Gets parameters or defaults
lr = params.get('learning_rate', 0.001)
# Your training code
accuracy = train_model(lr=lr)
# Logging works in both contexts
yanex.log_metrics({"accuracy": accuracy})
```
```bash
# Run standalone (no tracking)
python train.py
# Run with yanex (full tracking)
yanex run train.py --param learning_rate=0.01
```
### 2. Explicit Experiment Creation (Advanced)
For Jupyter notebook usage, or when you need fine control:
```python
import yanex
from pathlib import Path
experiment = yanex.create_experiment(script_path=Path(__file__), name="my-exp", config={"lr": 0.01})
with experiment:
# Your code here
# ...
yanex.log_metrics({"accuracy": 0.95})
```
> **Note:** Don't mix both patterns! Use CLI-first for most cases, explicit creation for advanced scenarios.
## Configuration Files
Create `config.yaml` for default parameters:
```yaml
# config.yaml
model:
learning_rate: 0.001
batch_size: 32
epochs: 100
data:
dataset: "cifar10"
augmentation: true
training:
optimizer: "adam"
scheduler: "cosine"
```
## Documentation
📚 **[Complete Documentation](docs/README.md)** - Detailed guides and API reference
**Quick Links:**
- [CLI Commands](docs/cli-commands.md) - All yanex commands with examples
- [Python API](docs/python-api.md) - Complete Python API reference
- [Configuration](docs/configuration.md) - Parameter management and config files
- [Experiment Structure](docs/experiment-structure.md) - Directory layout and file organization
- [Comparison Tool](docs/compare.md) - Interactive experiment comparison
- [Best Practices](docs/best-practices.md) - Tips for effective experiment tracking
## Contributing
Yanex is open source and welcomes contributions! See our [contributing guidelines](CONTRIBUTING.md) for details.
**Built with assistance from [Claude](https://claude.ai).**
## License
MIT License - see [LICENSE](LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "yanex",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "experiment, tracking, machine-learning, research, reproducibility",
"author": "Thomas",
"author_email": "Thomas <from+gitgub@tomr.au>",
"download_url": "https://files.pythonhosted.org/packages/17/1b/004d86b69fabf69261e4f22d234be083b6c028981ab5dde88483fb46aa7d/yanex-0.4.0.tar.gz",
"platform": null,
"description": "# Yanex - Yet Another Experiment Tracker\n\nA lightweight, Git-aware experiment tracking system for Python that makes reproducible research effortless.\n\n## Why Yanex?\n\n**Stop losing track of your experiments.** Yanex automatically tracks parameters, results, and code state so you can focus on what matters - your research.\n\n```python\nimport yanex\n\n# read parameters from config file or CLI arguments\nlr = yanex.get_param('lr', default=0.001)\nepochs = yanex.get_param('epochs', default=10)\n\n# your experiment code\n# ...\n\n# log results, artifacts and figures\nyanex.log_metrics({\"step\": epoch, \"loss\", loss, \"accuracy\": accuracy})\nyanex.log_artifact(\"model.pth\", model_path)\nyanex.log_matplotlib_figure(fig, \"loss_curve.png\")\n```\n\nRun from the command line:\n\n```bash\n# Run with yanex CLI for automatic tracking\nyanex run train.py --param lr=10e-3 --param epochs=10\n```\n\nThat's it. Yanex creates a separate directory for each experiment, saves the logged results and files, stdout and stderr outptus, Python environment information, and even the Git state of your code repository. You can then compare results, search experiments, and reproduce them with ease.\n\n## Key Features\n\n- \ud83d\udd12 **Reproducible**: Automatic Git state tracking ensures every experiment is reproducible\n- \ud83d\udcca **Interactive Comparison**: Compare experiments side-by-side with an interactive table\n- \u2699\ufe0f **Flexible Parameters**: YAML configs with CLI overrides for easy experimentation and syntax for parameter sweeps\n- \ud83d\udcc8 **Rich Logging**: Track metrics, artifacts, and figures\n- \ud83d\udd0d **Powerful Search**: Find experiments by status, parameters, tags, or time ranges\n- \ud83d\udce6 **Zero Dependencies**: No external services required - works offline\n\n## Quick Start\n\n### Install\n```bash\npip install yanex\n```\n\n### 1. Run Your First Experiment\n\n```python\n# experiment.py\nimport yanex\n\nparams = yanex.get_params()\nprint(f\"Learning rate: {params.get('learning_rate', 0.001)}\")\n\n# Simulate training\naccuracy = 0.85 + (params.get('learning_rate', 0.001) * 10)\n\nyanex.log_metrics({\n \"accuracy\": accuracy,\n \"loss\": 1 - accuracy\n})\n```\n\n```bash\n# Run with default parameters\nyanex run experiment.py\n\n# Override parameters\nyanex run experiment.py --param learning_rate=0.01 --param epochs=50\n\n# Add tags for organization\nyanex run experiment.py --tag baseline --tag \"quick-test\"\n```\n\n### 2. Compare Results\n\n```bash\n# Interactive comparison table\nyanex compare\n\n# Compare specific experiments\nyanex compare exp1 exp2 exp3\n\n# Filter and compare\nyanex compare --status completed --tag baseline\n```\n\n### 3. Track Everything\n\nList, search, and manage your experiments:\n\n```bash\n# List recent experiments\nyanex list\n\n# Find experiments by criteria\nyanex list --status completed --tag production\nyanex list --started-after \"1 week ago\"\n\n# Show detailed experiment info\nyanex show exp_id\n\n# Archive old experiments\nyanex archive --started-before \"1 month ago\"\n```\n\n## Two Ways to Use Yanex\n\nYanex supports two usage patterns:\n\n### 1. CLI-First (Recommended)\nWrite scripts that work both standalone and with yanex tracking:\n\n```python\n# train.py - Works both ways!\nimport yanex\n\nparams = yanex.get_params() # Gets parameters or defaults\nlr = params.get('learning_rate', 0.001)\n\n# Your training code\naccuracy = train_model(lr=lr)\n\n# Logging works in both contexts\nyanex.log_metrics({\"accuracy\": accuracy})\n```\n\n```bash\n# Run standalone (no tracking)\npython train.py\n\n# Run with yanex (full tracking)\nyanex run train.py --param learning_rate=0.01\n```\n\n### 2. Explicit Experiment Creation (Advanced)\nFor Jupyter notebook usage, or when you need fine control:\n\n```python\nimport yanex\nfrom pathlib import Path\n\nexperiment = yanex.create_experiment(script_path=Path(__file__), name=\"my-exp\", config={\"lr\": 0.01})\n\nwith experiment:\n \n # Your code here\n # ...\n\n yanex.log_metrics({\"accuracy\": 0.95})\n```\n\n> **Note:** Don't mix both patterns! Use CLI-first for most cases, explicit creation for advanced scenarios.\n\n\n## Configuration Files\n\nCreate `config.yaml` for default parameters:\n\n```yaml\n# config.yaml\nmodel:\n learning_rate: 0.001\n batch_size: 32\n epochs: 100\n\ndata:\n dataset: \"cifar10\"\n augmentation: true\n\ntraining:\n optimizer: \"adam\"\n scheduler: \"cosine\"\n```\n\n\n## Documentation\n\n\ud83d\udcda **[Complete Documentation](docs/README.md)** - Detailed guides and API reference\n\n**Quick Links:**\n- [CLI Commands](docs/cli-commands.md) - All yanex commands with examples\n- [Python API](docs/python-api.md) - Complete Python API reference \n- [Configuration](docs/configuration.md) - Parameter management and config files\n- [Experiment Structure](docs/experiment-structure.md) - Directory layout and file organization\n- [Comparison Tool](docs/compare.md) - Interactive experiment comparison\n- [Best Practices](docs/best-practices.md) - Tips for effective experiment tracking\n\n\n## Contributing\n\nYanex is open source and welcomes contributions! See our [contributing guidelines](CONTRIBUTING.md) for details.\n\n**Built with assistance from [Claude](https://claude.ai).**\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Yet Another Experiment Tracker - A lightweight experiment tracking harness",
"version": "0.4.0",
"project_urls": {
"Documentation": "https://github.com/rueckstiess/yanex/blob/main/docs/README.md",
"Homepage": "https://github.com/rueckstiess/yanex",
"Issues": "https://github.com/rueckstiess/yanex/issues",
"Repository": "https://github.com/rueckstiess/yanex"
},
"split_keywords": [
"experiment",
" tracking",
" machine-learning",
" research",
" reproducibility"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "85d8382d4183a3a402b16b28e5917bdaad74df92f0f407cce471a0544b507189",
"md5": "aa94185889540b4516e999c37feb4ff5",
"sha256": "b47ca418093634e5031f190053e3a93b416d6cf52a1bc015aff0213678390a05"
},
"downloads": -1,
"filename": "yanex-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aa94185889540b4516e999c37feb4ff5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 86451,
"upload_time": "2025-07-18T02:15:35",
"upload_time_iso_8601": "2025-07-18T02:15:35.826554Z",
"url": "https://files.pythonhosted.org/packages/85/d8/382d4183a3a402b16b28e5917bdaad74df92f0f407cce471a0544b507189/yanex-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "171b004d86b69fabf69261e4f22d234be083b6c028981ab5dde88483fb46aa7d",
"md5": "6aad4ca83589f02379ad5595ba28de03",
"sha256": "33ea84fb568c10eec1af2922886a2b4207f94c0d6b341cc3607de92ba13217f3"
},
"downloads": -1,
"filename": "yanex-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "6aad4ca83589f02379ad5595ba28de03",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 94906,
"upload_time": "2025-07-18T02:15:37",
"upload_time_iso_8601": "2025-07-18T02:15:37.406565Z",
"url": "https://files.pythonhosted.org/packages/17/1b/004d86b69fabf69261e4f22d234be083b6c028981ab5dde88483fb46aa7d/yanex-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 02:15:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rueckstiess",
"github_project": "yanex",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"12.0.0"
]
]
},
{
"name": "gitpython",
"specs": [
[
">=",
"3.1.0"
]
]
},
{
"name": "dateparser",
"specs": [
[
">=",
"1.1.0"
]
]
},
{
"name": "textual",
"specs": [
[
">=",
"0.45.0"
]
]
}
],
"lcname": "yanex"
}
JSON
